gopcms

gopcms

A generic, dependency-free Go client for the PayloadCMS REST API. It's meant to be usable by any Go program — microservices, CLIs, batch jobs — that needs to query and manage PayloadCMS collections, including arbitrarily complex conditional filters.

No third-party dependencies: only the Go standard library.

Install

go get github.com/TaiBomb/gopcms

Quick start

package main

import (
	"context"
	"log"

	"github.com/TaiBomb/gopcms"
)

type Post struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Status string `json:"status"`
	Views  int    `json:"views"`
}

func main() {
	client, err := gopcms.New("https://cms.example.com")
	if err != nil {
		log.Fatal(err)
	}
	client.SetAuth(&gopcms.APIKeyAuth{Collection: "users", APIKey: "your-api-key"})

	posts := gopcms.NewCollection[Post](client, "posts")

	result, err := posts.Find(context.Background(), &gopcms.FindOptions{
		Where: gopcms.And(
			gopcms.Equals("status", "published"),
			gopcms.GreaterThan("views", 100),
		),
		Sort:  []string{"-createdAt"},
		Limit: 10,
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, p := range result.Docs {
		log.Println(p.Title)
	}
}

Filtering (conditional queries)

Every operator documented in Payload's query overview has a helper constructor:

gopcms.Equals("color", "mint")
gopcms.NotEquals("status", "draft")
gopcms.GreaterThan("views", 100)
gopcms.GreaterThanEqual("age", 18)
gopcms.LessThan("price", 50)
gopcms.LessThanEqual("stock", 0)
gopcms.Like("title", "hello world")
gopcms.Contains("description", "sale")
gopcms.In("status", "draft", "published")
gopcms.NotIn("category", "spam")
gopcms.All("tags", "go", "cms")     // MongoDB adapter only
gopcms.Exists("deletedAt", false)
gopcms.Near("location", -122.4, 37.7, 5000, 0)
gopcms.Within("location", geoJSON)
gopcms.Intersects("location", geoJSON)

Combine conditions with And / Or, nested as deeply as needed:

where := gopcms.Or(
	gopcms.Equals("color", "mint"),
	gopcms.And(
		gopcms.Equals("color", "white"),
		gopcms.Equals("featured", false),
	),
)

Nested/related properties use dot notation, exactly as in Payload:

gopcms.Exists("artists.featured", true)

Date values can be passed as a plain time.Time — it's automatically formatted as RFC3339 (in UTC), which is what PayloadCMS/MongoDB expect for date comparisons:

gopcms.GreaterThan("createdAt", time.Now().AddDate(0, 0, -7)) // last 7 days

Filters are serialized to Payload's REST bracket-notation query strings (e.g. where[or][0][color][equals]=mint) automatically — you never need to build query strings by hand.

FindOptions/DocOptions also expose Joins, for customizing Join fields (limit/sort/where per joined field, or false to disable all of them):

posts.Find(ctx, &gopcms.FindOptions{
	Joins: map[string]any{
		"relatedPosts": map[string]any{"limit": 5, "sort": "title"},
	},
})

CRUD

posts := gopcms.NewCollection[Post](client, "posts")

// Find (list) / FindByID / Count
result, err := posts.Find(ctx, &gopcms.FindOptions{Where: gopcms.Equals("status", "published")})
doc, err := posts.FindByID(ctx, "64f...", nil)
count, err := posts.Count(ctx, &gopcms.CountOptions{Where: gopcms.Equals("status", "draft")})

// Create / Update / Delete
created, err := posts.Create(ctx, map[string]any{"title": "Hello"}, nil)
updated, err := posts.Update(ctx, "64f...", map[string]any{"title": "Updated"}, nil)
deleted, err := posts.Delete(ctx, "64f...", nil)

// Bulk update / delete (require a non-empty Where)
bulkUpdated, err := posts.UpdateMany(ctx, gopcms.Equals("status", "draft"), map[string]any{"status": "archived"}, nil)
bulkDeleted, err := posts.DeleteMany(ctx, gopcms.LessThan("createdAt", "2020-01-01"), nil)

Iterating over every page

Collection.All transparently walks through every page of a query, using Go's range-over-func iterators (Go 1.23+):

for post, err := range posts.All(ctx, &gopcms.FindOptions{Where: gopcms.Equals("status", "published")}) {
	if err != nil {
		log.Fatal(err) // a Find call failed; iteration has already stopped
	}
	fmt.Println(post.Title)
}

Break out of the loop (or cancel ctx) at any point and no further requests are made.

Schema-agnostic usage

T can be a struct for type safety, or map[string]any / json.RawMessage for fully dynamic, schema-agnostic access — handy for a library that different services with different Payload schemas will reuse:

posts := gopcms.NewCollection[map[string]any](client, "posts")

Authentication

Two strategies are supported, both configurable per Client:

// API key (server-to-server, e.g. microservices)
client.SetAuth(&gopcms.APIKeyAuth{Collection: "users", APIKey: "..."})

// Email/password JWT
jwt := gopcms.NewJWTAuth("")
client.SetAuth(jwt)

users := gopcms.NewAuthCollection[User](client, "users", jwt)
login, err := users.Login(ctx, "dev@example.com", "secret")
// jwt's token is now set automatically; every subsequent Client call is authenticated.

me, err := users.Me(ctx)
refreshed, err := users.Refresh(ctx)
_, err = users.Logout(ctx, false)

AuthCollection also exposes Verify, Unlock, ForgotPassword and ResetPassword, matching Payload's auth operations.

Auto-refresh on 401: call EnableAutoRefresh once after login to have the underlying JWTAuth transparently call Refresh and retry a request that came back 401, instead of failing outright:

users := gopcms.NewAuthCollection[User](client, "users", jwt)
if _, err := users.Login(ctx, "dev@example.com", "secret"); err != nil {
	log.Fatal(err)
}
if err := users.EnableAutoRefresh(); err != nil {
	log.Fatal(err)
}
// Any later call that gets a 401 now triggers one automatic Refresh + retry
// before the error is returned to you.

Globals

type SiteSettings struct {
	SiteName string `json:"siteName"`
}

settings := gopcms.NewGlobal[SiteSettings](client, "site-settings")
doc, err := settings.Get(ctx, nil)
updated, err := settings.Update(ctx, map[string]any{"siteName": "New name"}, nil)

Uploads

For upload-enabled collections (e.g. a "media" collection), CreateWithFile / UpdateWithFile send a multipart/form-data request per Payload's upload docs: the file goes in a file part, and any other fields (like alt) are JSON-encoded into a _payload part.

type Media struct {
	ID  string `json:"id"`
	Alt string `json:"alt"`
}

media := gopcms.NewCollection[Media](client, "media")

f, err := os.Open("photo.jpg")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

created, err := media.CreateWithFile(ctx, gopcms.UploadFile{
	Reader:   f,
	Filename: "photo.jpg",
	// ContentType is optional; inferred from the extension if omitted.
}, map[string]any{"alt": "A photo"}, nil)

// Re-upload (replace) an existing document's file:
updated, err := media.UpdateWithFile(ctx, created.Doc.ID, gopcms.UploadFile{
	Reader:   anotherReader,
	Filename: "photo-v2.jpg",
}, map[string]any{"alt": "Updated photo"}, nil)

gopcms.NewUploadFileFromPath(path) is a shortcut that opens a local file and closes it automatically once the request completes:

file, err := gopcms.NewUploadFileFromPath("photo.jpg")
if err != nil {
	log.Fatal(err)
}
created, err := media.CreateWithFile(ctx, file, map[string]any{"alt": "A photo"}, nil)

Versions & drafts

For collections/globals with versions enabled, you can list a document's version history, fetch a single version, and restore a document to a prior version, per Payload's versions docs:

// List a document's version history (versions belonging to a specific parent):
versions, err := posts.FindVersions(ctx, &gopcms.FindOptions{
	Where: gopcms.Equals("parent", "64f..."),
	Sort:  []string{"-createdAt"},
})
for _, v := range versions.Docs {
	log.Println(v.ID, v.CreatedAt, v.Version.Title) // v.Version is a Post
}

// Fetch a single version by its own ID:
version, err := posts.FindVersionByID(ctx, "64a...", nil)

// Restore the parent document to that version's state:
restored, err := posts.RestoreVersion(ctx, "64a...", nil)
log.Println(restored.Doc.Title)

The same three methods (FindVersions, FindVersionByID, RestoreVersion) exist on Global[T], operating on /api/globals/{slug}/versions instead.

Preferences

Typed access to Payload's Preferences API, scoped to the currently authenticated user:

type RegionPref struct {
	Timezone string `json:"timezone"`
}

prefs := gopcms.NewPreferences[RegionPref](client)

pref, err := prefs.Get(ctx, "region")
set, err := prefs.Set(ctx, "region", RegionPref{Timezone: "Europe/Rome"})
_, err = prefs.Delete(ctx, "region")

T can just as well be a primitive (string, int, ...) or map[string]any for preference values without a fixed shape.

Access control

Typed-ish wrappers around Payload's Access API — pass any out (typically map[string]any or a custom struct matching your access-control shape):

var appAccess map[string]any
err := client.Access(ctx, &appAccess) // GET /api/access

var docAccess map[string]any
err = posts.Access(ctx, "64f...", &docAccess) // GET /api/posts/access/64f...

var globalAccess map[string]any
err = settings.Access(ctx, &globalAccess) // GET /api/globals/site-settings/access

Errors

Every non-2xx response is returned as *gopcms.APIError, carrying the HTTP status code and every error message Payload returned:

_, err := posts.FindByID(ctx, "missing-id", nil)
if gopcms.IsNotFound(err) {
	// ...
}
if apiErr, ok := gopcms.AsAPIError(err); ok {
	log.Println(apiErr.StatusCode, apiErr.Message())
}

Helpers: IsNotFound, IsUnauthorized, IsForbidden, IsValidationError.

Escape hatch: custom endpoints

Collection/Global/AuthCollection cover the standard CRUD, auth, versions, Preferences and Access operations, but PayloadCMS configs are highly customizable — custom endpoints declared in your own Payload config, for instance. Client.Do / Client.DoPublic expose the same request/response handling (auth, retries, error parsing, method-override) the rest of the library uses internally, for anything not wrapped yet:

var result MyCustomResponse
err := client.Do(ctx, http.MethodGet, "/posts/123/tracking", nil, nil, &result)

// DoPublic skips applying the configured Authenticator, for intentionally
// public custom endpoints.
err = client.DoPublic(ctx, http.MethodPost, "/some-public-endpoint", nil, requestBody, &result)

path is relative to the configured API prefix (default /api), same as every other method in the library. For file uploads to custom endpoints, Client.DoMultipart is the equivalent raw entry point used internally by CreateWithFile/UpdateWithFile.

Reliability

Long queries: GET requests whose URL would exceed a practical length (2000 characters by default) are transparently retried using Payload's method override (POST + X-Payload-HTTP-Method-Override: GET). This just works — no code changes needed — but the threshold is adjustable with WithMaxGETURLLength, or disabled with WithMaxGETURLLength(0).

Retries: disabled by default. Enable them with WithRetry for transient network errors or 429/502/503/504 responses on idempotent requests (GET, HEAD, DELETE) — Create (POST) is deliberately never auto-retried, since retrying it could create duplicate documents:

client, err := gopcms.New("https://cms.example.com",
	gopcms.WithRetry(gopcms.DefaultRetryPolicy()), // 3 retries, 200ms base delay, 2s cap, with jitter
)

If a 429/503 response includes a Retry-After header (either as seconds or an HTTP date, per RFC 9110), that value is honored instead of the exponential backoff delay — still clamped to the policy's MaxDelay so a server can't force an arbitrarily long wait.

Auto-refresh on 401 (JWT only): see Authentication — a 401 triggers one Refresher.Refresh attempt and request retry, independent of RetryPolicy, whenever the configured Authenticator supports it.

Observability: register an Observer to get notified of every physical HTTP request/response (including individual retry attempts) for logging or metrics, without needing a custom http.RoundTripper:

client, err := gopcms.New("https://cms.example.com",
	gopcms.WithObserver(gopcms.ObserverFunc{
		Response: func(ctx context.Context, method, url string, statusCode int, dur time.Duration, err error) {
			log.Printf("%s %s -> %d (%s) err=%v", method, url, statusCode, dur, err)
		},
	}),
)

Options

By default, New gives the Client its own *http.Client with a DefaultHTTPTimeout (30s) — never the bare http.DefaultClient, which has no timeout at all and would otherwise let a request hang indefinitely if you forget to pass a context with a deadline. Adjust it with WithTimeout, or replace the whole http.Client (e.g. for a custom Transport) with WithHTTPClient:

client, err := gopcms.New("https://cms.example.com",
	gopcms.WithHTTPClient(customHTTPClient),
	gopcms.WithTimeout(10 * time.Second), // adjust just the timeout; apply after WithHTTPClient to override its timeout too
	gopcms.WithAPIPrefix("custom-api"), // if routes.api isn't the default "/api"
	gopcms.WithAuth(&gopcms.APIKeyAuth{Collection: "users", APIKey: "..."}),
	gopcms.WithUserAgent("my-service/1.0"),
	gopcms.WithMaxGETURLLength(0), // disable the automatic GET-via-POST fallback
	gopcms.WithRetry(gopcms.DefaultRetryPolicy()),
	gopcms.WithObserver(myObserver),
)

Testing

go build ./... && go vet ./... && go test ./... -race

Tests use net/http/httptest and don't require a running PayloadCMS instance.

License

Apache License 2.0.