Go Payload CMS

Introduction

Go Payload is a GoLang client library for Payload CMS. It provides a simple and easy-to-use interface for interacting with the Payload CMS API by saving you the hassle of dealing with unmarshalling JSON responses into your Payload collections and globals.

Installation

go get -u github.com/ainsleyclark/go-payloadcms

Quick Start

import (
	"github.com/ainsleyclark/go-payloadcms"
)

type Entity struct {
	ID    int    `json:"id"`
	Email string `json:"email"`
	Name  string `json:"name"`
	// ... other fields
}

func main() {
	client, err := payloadcms.New(
		payloadcms.WithBaseURL("http://localhost:8080"),
		payloadcms.WithAPIKey("api-key"),
	)
	
	if err != nil {
		log.Fatalln(err)
	}
	
	var entities payloadcms.ListResponse[Entity]
	resp, err := client.Collections.List(context.Background(), "users", payloadcms.ListParams{}, &entities)
	if err != nil {
		log.Fatalln(err)
	}
	
	fmt.Printf("Received status: %d, with body: %s\n", resp.StatusCode, string(resp.Content))
}

Docs

Documentation can be found at the Go Docs, but we have included a kick-start guide below to get you started.

Services

The client provides the services as defined below. Each

• Collections
• Globals
• Media

Collections

The collections service provides methods to interact with the collections in Payload CMS. For more information please visit the docs here.

FindByID

var entity Entity // Any struct that conforms to your collection schema.
resp, err := client.Collections.FindByID(context.Background(), "collection", 1, &entity)
if err != nil {
	fmt.Println(err)
	return
}

List

var entities payloadcms.ListResponse[Entity] // Must use ListResponse with generic type.
resp, err := client.Collections.List(context.Background(), "collection", payloadcms.ListParams{
	Sort:  "-createdAt",
	Limit: 10,
	Page:  1,
}, entities)
if err != nil {
	fmt.Println(err)
	return
}

Create

var entity Entity // Any struct representing the entity to be created.
resp, err := client.Collections.Create(context.Background(), "collection", entity)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.

UpdateByID

var entity Entity // Any struct representing the updated entity.
resp, err := client.Collections.UpdateByID(context.Background(), "collection", 1, entity)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.

DeleteByID

resp, err := client.Collections.DeleteByID(context.Background(), "collection", 1)
if err != nil {
	fmt.Println(err)	
	return
}
// Use response data as needed

Globals

The globals service provides methods to interact with the globals in Payload CMS. For more information please visit the docs here.

Get

var global Global // Any struct representing a global type.
resp, err := client.Globals.Get(context.Background(), "global", &global)
if err != nil {
	fmt.Println(err)
	return
}

Update

var global Global // Any struct representing a global type.
resp, err := client.Globals.Update(context.Background(), "global", global)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.

Media

The media service provides methods to upload media types to Payload CMS. For more information please visit the docs here.

Upload

file, err := os.Open("path/to/file")
if err != nil {
	fmt.Println(err)
	return
}

media := &payloadcms.CreateResponse[Media]{}
_, err = m.payload.Media.UploadFromURL(ctx, file, Media{Alt: "alt"}, &media, payloadcms.MediaOptions{
	Collection:       "media",
})

if err != nil {
	fmt.Println(err)
	return
}

UploadFromURL

media := &payloadcms.CreateResponse[Media]{}
_, err = m.payload.Media.UploadFromURL(ctx, "https://payloadcms.com/picture-of-cat.jpg", Media{Alt: "alt"}, &media, payloadcms.MediaOptions{
	Collection:       "media",
})

if err != nil {
	fmt.Println(err)
	return
}

Queries

The Params allows you to add filters, sort order, pagination, and other query parameters. Here's an example:

import (
	"context"
	"fmt"
	"github.com/ainsleyclark/go-payloadcms"
)

func main() {
	client, err := payloadcms.New(
		payloadcms.WithBaseURL("http://localhost:8080"),
		payloadcms.WithAPIKey("api-key"),
	)
	if err != nil {
		log.Fatalln(err)
	}

	var entities payloadcms.ListResponse[Entity]
	
	params := payloadcms.ListParams{
		Sort: "-createdAt",          
		Limit: 10,                  
		Page: 1,                     
		Where: payloadcms.Query().Equals("status", "active").GreaterThan("age", "18"),
	}

	resp, err := client.Collections.List(context.Background(), "users", params, &entities)
	if err != nil {
		log.Fatalln(err)
	}

	fmt.Printf("Received status: %d, with body: %s\n", resp.StatusCode, string(resp.Content))
}

Mocks

Mock implementations can be found in payloadfakes package located in fakes directory.

They provide mock implementations of all the services provided by the client for convenience.

Example:

func TestPayload(t *testing.T) {
	// Create a new mock collection service
	mockCollectionService := payloadfakes.NewMockCollectionService()
	
	// Define the behavior of the FindByID method
	mockCollectionService.FindByIDFunc = func (ctx context.Context,
		collection payloadcms.Collection,
		id int,
		out any,
	) (payloadcms.Response, error) {
		// Custom logic for the mock implementation
		return payloadcms.Response{}, nil
	}
	
	// Use the mock collection service in your tests
	myFunctionUsingCollectionService(mockCollectionService)
}

Response and Error Types

The library defines custom response and error types to provide a more convenient way to interact with the API.

• Response: This struct wraps the standard http.Response returned by the API and provides additional fields for easier access to response data and potential errors.
  • Content: The response body bytes.
  • Message: A user-friendly message extracted from the response (if available).
  • Errors: A list of Error structs containing details about any API errors encountered.
• Error: This struct represents a single API error with a Message field containing the error description.

These types are used throughout the library to handle successful responses and API errors consistently.

Development

Setup

To get set up with Go Payload simply clone the repo and run the following:

make setup

This will install all dependencies and set up the project for development.

Payload Dev Env

Within the ./dev directory, you will find a local instance of Payload CMS that can be used for testing the client. To get setup with Payload, simply follow the steps below.

Copy the environment file and replace where necessary. The postgres-db adapater is currently being used for the database.

cp .env.example .env

Then run the Payload instance like you would any other installation.

pnpm run dev

TODOs

• Auth - https://payloadcms.com/docs/rest-api/overview#auth-operations
• Preferences: https://payloadcms.com/docs/rest-api/overview#preferences
• Finish E2E Tests under /tests directory using dockertest

Contributing

Contributions are welcome! If you find any bugs or have suggestions for improvement, please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Trademark

ainsley.dev and the ainsley.dev logo are either registered trademarks or trademarks of ainsley.dev LTD in the United Kingdom and/or other countries. All other trademarks are the property of their respective owners.