{"id":16383662,"url":"https://github.com/ainsleyclark/go-payloadcms","last_synced_at":"2025-10-07T15:27:35.654Z","repository":{"id":241343161,"uuid":"806646462","full_name":"ainsleyclark/go-payloadcms","owner":"ainsleyclark","description":"GoLang client library \u0026 SDK for Payload CMS","archived":false,"fork":false,"pushed_at":"2025-02-21T16:28:22.000Z","size":270,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-15T22:56:09.791Z","etag":null,"topics":["cms","content-management","go","golang","library","open-source","payload","payloadcms","sdk"],"latest_commit_sha":null,"homepage":"https://ainsley.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ainsleyclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-27T15:47:01.000Z","updated_at":"2025-02-10T13:22:53.000Z","dependencies_parsed_at":"2024-05-29T09:40:33.604Z","dependency_job_id":"eb4c9191-1c7a-451d-b2bb-083d7fdf2aa7","html_url":"https://github.com/ainsleyclark/go-payloadcms","commit_stats":null,"previous_names":["ainsleydev/go-payloadcms","ainsleyclark/go-payloadcms"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-payloadcms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-payloadcms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-payloadcms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-payloadcms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ainsleyclark","download_url":"https://codeload.github.com/ainsleyclark/go-payloadcms/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052645,"owners_count":20553162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cms","content-management","go","golang","library","open-source","payload","payloadcms","sdk"],"created_at":"2024-10-11T04:09:22.079Z","updated_at":"2025-10-07T15:27:30.607Z","avatar_url":"https://github.com/ainsleyclark.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./res/payload-logo.jpg\" height=\"86\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://ainsley.dev\"\u003e\n        \u003ch2 align=\"center\"\u003eGo Payload CMS\u003c/h2\u003e\n\t\t\u003cp align=\"center\"\u003eGoLang client library \u0026 SDK for Payload CMS\u003c/p\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/ainsleyclark/go-payloadcms)](https://goreportcard.com/report/github.com/ainsleyclark/go-payloadcms)\n[![Maintainability](https://api.codeclimate.com/v1/badges/9cb93230fcfd6643dfa5/maintainability)](https://codeclimate.com/github/ainsleyclark/go-payloadcms/maintainability)\n[![GoDoc](https://godoc.org/github.com/ainsleyclark/go-payloadcms?status.svg)](https://godoc.org/github.com/ainsleyclark/go-payloadcms)\n[![Test](https://github.com/ainsleyclark/go-payloadcms/actions/workflows/test.yaml/badge.svg?query=new)](https://github.com/ainsleyclark/go-payloadcms/actions/workflows/test.yaml)\n[![Lint](https://github.com/ainsleyclark/go-payloadcms/actions/workflows/lint.yaml/badge.svg?query=new)](https://github.com/ainsleyclark/go-payloadcms/actions/workflows/lint.yaml)\n\u003cbr /\u003e\n[![codecov](https://codecov.io/gh/ainsleyclark/go-payloadcms/graph/badge.svg?token=hhaaiJW6Vq)](https://codecov.io/gh/ainsleyclark/go-payloadcms)\n[![ainsley.dev](https://img.shields.io/badge/-ainsley.dev-black?style=flat\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QA/wD/AP+gvaeTAAAAB3RJTUUH5wEYDzUGL1b35AAABA1JREFUWMPtlttvFVUUxn977ZnZu+W0tLalqRovBAUvQag0xNQbpSIosSSIJC198YknJfHJxDf9A/DBJ0x8MbFACjVqvCASq6FYFLFBvJAaAomkFCmhHGpLO+PDzOmZzpn2nKP4pCs5ycmevb7vW99as/fA//FfD1XO5p1nzuA3NWJHx5T8cVkRBPHHQfRjd0tzyZhOOQIy27bAxET9zCuvvhY0r2kC/OiRABeAN4BL/4oDr9+3lGszPs7UVNfUE23v3Nj5koszR/8N4EXg3XJckFIFuCLUuU7GWNNtTg25cu4syJx0F+gGMuU4UJKAt1Yux1UKV6TVat1qs+OYwQESMwDQCjwKsOv4iZsnwGihwbiuEek2WjJGhMrvv0UujYKa08VFkQvuTXNgz6oVeCIo1CqrZYMRwTiaytERKn44kRQAsAFYDbBrsLgLRQU0GI919TXKiHQaUQ1GBCuCCQKqjg/MqInrM4lZrgc6A1CljHhRAZ4Ip65m77FaOmbJdehC5vzZr1RAf/T6x6NDwb3/uAVfP74GnwCjZasRuXuWXASj9XQme+3t6erqPcB0IvUuYCsUH8YFBRhRNBqvyYpsn0MeOnG6wvc/9x33MPBjSvp24Na/7cDP7Y/gKIURecZoeTBObkSwWg7UNjaOeFfGLgK9KRAPAM8Wc2FeAUaEWtddbEV2WBFtREXkCqvlghE5yOQkvucBHAR+T0BooAtYXLYDI5sewxWFJ/Kk1bI2UTlW5DMFp03+JPwJ+DQFai2wbiEXUgVUas0trmuslm4jUmGi/tuwDVmrpafBuNPVrs7N/wzQA2QTUJbwYLIlOxB0tOGJ4IhqsSJts+T54Rv0lBz1RFh9ZJA385fOAHAshaMNaAF4OcWFQgeUwhMlrlJdnqjaOLkR8Y2WvbWec9VIQeo4sJf8FZ2LmmgWJO1cmm8I7wc2a6XwosGL+v+rFfnYUYplh47Obo5dvZ8Av6TgbSZ8KxYWEGxZn/u7Dbg9t8HNnwF9S2qqzqVUn4vzQF/K+m3AC1A4jGlId0QC8l0BXKVGrahe//okNR99WZAUc6EXuJiC+zxw57wOxKp/DliRAvCFKDUkxS+YIeBwyvryCHuOC0kH6oBOCj/V/gTeA6aK0oefZj3ARGJdRdh1BQ7Eqm8HHk4B/Q7oB1B9acWFEWtDf5STjGbgqbgLcQcqCQ8NL5EUAPuBsRKqz8UVYB+F97QXcSyatSXoWJ8zvB04AFQlkoaBp4HhhaqPR1TdUsLjeVni8TjhVX0odCAkd4AdKeQAHxIwXEb1Odt+Az5IeVQVcTmhgDBWAhtTNl8G9qGAwKfU2N3SnJvi/RFGMjYCD8UFdACNKRsHgZMA6v0j5ZpAlPtNyvqSiJO/AKik60y0ALlUAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDIzLTAxLTI0VDE1OjUzOjA2KzAwOjAwm5vntAAAACV0RVh0ZGF0ZTptb2RpZnkAMjAyMy0wMS0yNFQxNTo1MzowNiswMDowMOrGXwgAAABXelRYdFJhdyBwcm9maWxlIHR5cGUgaXB0YwAAeJzj8gwIcVYoKMpPy8xJ5VIAAyMLLmMLEyMTS5MUAxMgRIA0w2QDI7NUIMvY1MjEzMQcxAfLgEigSi4A6hcRdPJCNZUAAAAASUVORK5CYII=)](https://ainsley.dev)\n[![Twitter Handle](https://img.shields.io/twitter/follow/ainsleydev)](https://twitter.com/ainsleydev)\n\n\u003c/div\u003e\n\n## Introduction\n\nGo Payload is a GoLang client library for Payload CMS. It provides a simple and easy-to-use\ninterface for interacting with the Payload CMS API by saving you the hassle of dealing with\nunmarshalling JSON responses into your Payload collections and globals.\n\n## Installation\n\n```bash\ngo get -u github.com/ainsleyclark/go-payloadcms\n```\n\n## Quick Start\n\n```go\nimport (\n\t\"github.com/ainsleyclark/go-payloadcms\"\n)\n\ntype Entity struct {\n\tID    int    `json:\"id\"`\n\tEmail string `json:\"email\"`\n\tName  string `json:\"name\"`\n\t// ... other fields\n}\n\nfunc main() {\n\tclient, err := payloadcms.New(\n\t\tpayloadcms.WithBaseURL(\"http://localhost:8080\"),\n\t\tpayloadcms.WithAPIKey(\"api-key\"),\n\t)\n\t\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\t\n\tvar entities payloadcms.ListResponse[Entity]\n\tresp, err := client.Collections.List(context.Background(), \"users\", payloadcms.ListParams{}, \u0026entities)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\t\n\tfmt.Printf(\"Received status: %d, with body: %s\\n\", resp.StatusCode, string(resp.Content))\n}\n```\n\n## Docs\n\nDocumentation can be found at\nthe [Go Docs](https://pkg.go.dev/github.com/ainsleyclark/go-payloadcms), but we have included a\nkick-start guide below to get you started.\n\n## Services\n\nThe client provides the services as defined below. Each\n\n- `Collections`\n- `Globals`\n- `Media`\n\n### Collections\n\nThe collections service provides methods to interact with the collections in Payload CMS.\nFor more information please visit the docs [here](https://payloadcms.com/docs/api/collections).\n\n#### FindByID\n\n```go\nvar entity Entity // Any struct that conforms to your collection schema.\nresp, err := client.Collections.FindByID(context.Background(), \"collection\", 1, \u0026entity)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n```\n\n#### List\n\n```go\nvar entities payloadcms.ListResponse[Entity] // Must use ListResponse with generic type.\nresp, err := client.Collections.List(context.Background(), \"collection\", payloadcms.ListParams{\n\tSort:  \"-createdAt\",\n\tLimit: 10,\n\tPage:  1,\n}, entities)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n```\n\n#### Create\n\n```go\nvar entity Entity // Any struct representing the entity to be created.\nresp, err := client.Collections.Create(context.Background(), \"collection\", entity)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\nfmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.\n```\n\n#### UpdateByID\n\n```go\nvar entity Entity // Any struct representing the updated entity.\nresp, err := client.Collections.UpdateByID(context.Background(), \"collection\", 1, entity)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\nfmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.\n```\n\n#### DeleteByID\n\n```go\nresp, err := client.Collections.DeleteByID(context.Background(), \"collection\", 1)\nif err != nil {\n\tfmt.Println(err)\t\n\treturn\n}\n// Use response data as needed\n```\n\n### Globals\n\nThe globals service provides methods to interact with the globals in Payload CMS.\nFor more information please visit the docs [here](https://payloadcms.com/docs/api/globals).\n\n#### Get\n\n```go\nvar global Global // Any struct representing a global type.\nresp, err := client.Globals.Get(context.Background(), \"global\", \u0026global)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n```\n\n#### Update\n\n```go\nvar global Global // Any struct representing a global type.\nresp, err := client.Globals.Update(context.Background(), \"global\", global)\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\nfmt.Println(string(resp.Content)) // Can unmarshal into response struct if needed.\n```\n\n### Media\n\nThe media service provides methods to upload media types to Payload CMS.\nFor more information please visit the docs [here](https://payloadcms.com/docs/upload/overview).\n\n#### Upload\n\n```go\nfile, err := os.Open(\"path/to/file\")\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n\nmedia := \u0026payloadcms.CreateResponse[Media]{}\n_, err = m.payload.Media.UploadFromURL(ctx, file, Media{Alt: \"alt\"}, \u0026media, payloadcms.MediaOptions{\n\tCollection:       \"media\",\n})\n\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n```\n\n#### UploadFromURL\n\n```go\nmedia := \u0026payloadcms.CreateResponse[Media]{}\n_, err = m.payload.Media.UploadFromURL(ctx, \"https://payloadcms.com/picture-of-cat.jpg\", Media{Alt: \"alt\"}, \u0026media, payloadcms.MediaOptions{\n\tCollection:       \"media\",\n})\n\nif err != nil {\n\tfmt.Println(err)\n\treturn\n}\n```\n\n#### Queries\n\nThe `Params` allows you to add filters, sort order, pagination, and other query parameters. Here's an example:\n\n```go\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"github.com/ainsleyclark/go-payloadcms\"\n)\n\nfunc main() {\n\tclient, err := payloadcms.New(\n\t\tpayloadcms.WithBaseURL(\"http://localhost:8080\"),\n\t\tpayloadcms.WithAPIKey(\"api-key\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tvar entities payloadcms.ListResponse[Entity]\n\t\n\tparams := payloadcms.ListParams{\n\t\tSort: \"-createdAt\",          \n\t\tLimit: 10,                  \n\t\tPage: 1,                     \n\t\tWhere: payloadcms.Query().Equals(\"status\", \"active\").GreaterThan(\"age\", \"18\"),\n\t}\n\n\tresp, err := client.Collections.List(context.Background(), \"users\", params, \u0026entities)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tfmt.Printf(\"Received status: %d, with body: %s\\n\", resp.StatusCode, string(resp.Content))\n}\n```\n\n### Options\n\nThe `RequestOption` type is a functional option used to configure HTTP requests sent to the Payload \nCMS API.\n\n### WithDepth\n\n`WithDepth` specifies the depth level for API responses, determining how much nested data is included.\nSee the [Payload Website](https://payloadcms.com/docs/queries/depth) for more details.\n\n**Usage:**\n```go\nclient.Do(ctx, http.MethodGet, \"/api/posts\", nil, \u0026out,\n    WithDepth(10),\n)\n```\nThis will append `?depth=10` to the request URL.\n\n### WithQueryParam\n\n`WithQueryParam` adds a key, value query parameters to the API request.\n\n**Usage:**\n```go\nclient.Do(ctx, http.MethodGet, \"/api/posts\", nil, \u0026out,\n    WithQueryParam(\"category\", \"tech\"),\n)\n```\n\nThis will append `?category=tech` to the request URL.\n\n## Mocks\n\nMock implementations can be found in `payloadfakes` package located\nin [fakes](https://github.com/ainsleyclark/go-payloadcms/tree/main/fakes) directory.\n\nThey provide mock implementations of all the services provided by the client for convenience.\n\n**Example:**\n\n```go\nfunc TestPayload(t *testing.T) {\n\t// Create a new mock collection service\n\tmockCollectionService := payloadfakes.NewMockCollectionService()\n\t\n\t// Define the behavior of the FindByID method\n\tmockCollectionService.FindByIDFunc = func (ctx context.Context,\n\t\tcollection payloadcms.Collection,\n\t\tid int,\n\t\tout any,\n\t) (payloadcms.Response, error) {\n\t\t// Custom logic for the mock implementation\n\t\treturn payloadcms.Response{}, nil\n\t}\n\t\n\t// Use the mock collection service in your tests\n\tmyFunctionUsingCollectionService(mockCollectionService)\n}\n```\n\n## Response and Error Types\n\nThe library defines custom response and error types to provide a more convenient way to interact with\nthe API.\n\n* **Response:** This struct wraps the standard `http.Response` returned by the API and provides\n  additional fields for easier access to response data and potential errors.\n\t* `Content`: The response body bytes.\n\t* `Message`: A user-friendly message extracted from the response (if available).\n\t* `Errors`: A list of `Error` structs containing details about any API errors encountered.\n* **Error:** This struct represents a single API error with a `Message` field containing the error\n  description.\n\nThese types are used throughout the library to handle successful responses and API errors\nconsistently.\n\n## Development\n\n### Setup\n\nTo get set up with Go Payload simply clone the repo and run the following:\n\n```bash\nmake setup\n```\n\nThis will install all dependencies and set up the project for development.\n\n### Payload Dev Env\n\nWithin the `./dev` directory, you will find a local instance of Payload CMS that can be used for\ntesting the client.\nTo get setup with Payload, simply follow the steps below.\n\nCopy the environment file and replace where necessary. The `postgres-db` adapater is currently being\nused for the database.\n\n```bash\ncp .env.example .env\n```\n\nThen run the Payload instance like you would any other installation.\n\n```bash\npnpm run dev\n```\n\n## TODOs\n\n- Auth - https://payloadcms.com/docs/rest-api/overview#auth-operations\n- Preferences:    https://payloadcms.com/docs/rest-api/overview#preferences\n- Finish E2E Tests under `/tests` directory using `dockertest`\n\n## Contributing\n\nContributions are welcome! If you find any bugs or have suggestions for improvement, please open an\nissue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Trademark\n\nainsley.dev and the ainsley.dev logo are either registered trademarks or trademarks of ainsley.dev\nLTD in the United Kingdom and/or other countries. All other trademarks are the property of their\nrespective owners.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Fgo-payloadcms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fainsleyclark%2Fgo-payloadcms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Fgo-payloadcms/lists"}