pocketclient

README

PocketClient (Go SDK) - v1.0.7

A minimal, typed Go SDK for PocketBase.

Install

go get github.com/chrisbrocklesby/pocketclient

Usage

Create a client

client := pocketclient.New("https://your-pocketbase.example.com")

Auth

// Authenticate against any collection
var user User
err := client.AuthPassword("users", "user@example.com", "password", &user)

// Authenticate as superuser
err := client.AuthPassword("_superusers", "admin@example.com", "password", nil)

The token is stored on the client automatically and sent with every subsequent request. If the token expires and a 401 is returned, the client will automatically re-authenticate and retry once. Disable this with:

client.DisableAutoReauth()

Use a pre-existing token:

client := pocketclient.New("https://your-pocketbase.example.com").WithToken("your-token")

CRUD

// Create
var record Post
err := client.Create("posts", PostInput{Title: "Hello"}, &record)

// View
var record Post
err := client.View("posts", "RECORD_ID", &record)

// Update
var record Post
err := client.Update("posts", "RECORD_ID", map[string]any{"title": "Updated"}, &record)

// List
var result pocketclient.Response[Post]
err := client.List("posts", &result, pocketclient.Query{
    "page":    1,
    "perPage": 50,
    "sort":    "-created",
    "filter":  `status = "published"`,
})

// Delete
err := client.Delete("posts", "RECORD_ID", nil)

File uploads

Use pocketclient.File in your input struct when writing. File fields return as string or []string when reading.

type PostInput struct {
    Title string            `json:"title"`
    Cover pocketclient.File `json:"cover,omitempty"`
}

type Post struct {
    ID    string `json:"id"`
    Title string `json:"title"`
    Cover []string `json:"cover"` // filenames returned by PocketBase
}

err := client.Create("posts", PostInput{
    Title: "Hello",
    Cover: pocketclient.File{Name: "cover.png", Data: imgBytes},
}, &created)

Multiple files:

type PostInput struct {
    Images []pocketclient.File `json:"images,omitempty"`
}

Error handling

err := client.View("posts", id, &post)
if err != nil {
    // Check for any API error
    if e, ok := pocketclient.IsError(err); ok {
        fmt.Println(e.Status, e.Body)
    }

    // Check for a specific status
    if _, ok := pocketclient.IsError(err, 404); ok {
        fmt.Println("not found")
    }

    // Check for multiple statuses
    if e, ok := pocketclient.IsError(err, 401, 403); ok {
        fmt.Println("auth error:", e.Status)
    }
}

Raw requests

// Simple
var health map[string]any
err := client.Raw("GET", "/api/health", nil, &health)

// With context
err := client.RawCtx(ctx, "GET", "/api/health", nil, &health)

// With custom headers
err := client.RawWithHeaders(ctx, "POST", "/api/custom", body, &out, pocketclient.Headers{
    "X-Custom-Header": "value",
})

Response type

pocketclient.Response[T] maps PocketBase's paginated list response:

type Response[T any] struct {
    Page       int
    PerPage    int
    TotalItems int
    TotalPages int
    Items      []T
}

License

MIT

Documentation

Index

• type Client
  • func New(baseURL string) *Client
  • func (c *Client) AuthPassword(collection, identity, password string, output any) error
  • func (c *Client) Create(collection string, body any, output any, query ...Query) error
  • func (c *Client) DELETE(path string, output any, query ...Query) error
  • func (c *Client) Delete(collection, id string, output any, query ...Query) error
  • func (c *Client) DisableAutoReauth() *Client
  • func (c *Client) GET(path string, output any, query ...Query) error
  • func (c *Client) List(collection string, output any, query ...Query) error
  • func (c *Client) PATCH(path string, body any, output any, query ...Query) error
  • func (c *Client) POST(path string, body any, output any, query ...Query) error
  • func (c *Client) Raw(method, path string, body any, output any, query ...Query) error
  • func (c *Client) RawCtx(ctx context.Context, method, path string, body any, output any, query ...Query) error
  • func (c *Client) RawWithHeaders(ctx context.Context, method, path string, body any, output any, ...) error
  • func (c *Client) Update(collection, id string, body any, output any, query ...Query) error
  • func (c *Client) View(collection, id string, output any, query ...Query) error
  • func (c *Client) WithToken(token string) *Client
• type Error
  • func IsError(err error, status ...int) (Error, bool)
  • func (e Error) Error() string
• type File
• type Headers
• type Query
• type Response

Types

type Client

type Client struct {
	BaseURL string
	HTTP    *http.Client

	Token string
	// contains filtered or unexported fields
}

func New

func New(baseURL string) *Client

func (*Client) AuthPassword

func (c *Client) AuthPassword(collection, identity, password string, output any) error

func (*Client) Create

func (c *Client) Create(collection string, body any, output any, query ...Query) error

func (*Client) DELETE

func (c *Client) DELETE(path string, output any, query ...Query) error

func (*Client) Delete

func (c *Client) Delete(collection, id string, output any, query ...Query) error

func (*Client) DisableAutoReauth

func (c *Client) DisableAutoReauth() *Client

func (*Client) GET

func (c *Client) GET(path string, output any, query ...Query) error

func (*Client) List

func (c *Client) List(collection string, output any, query ...Query) error

func (*Client) PATCH

func (c *Client) PATCH(path string, body any, output any, query ...Query) error

func (*Client) POST

func (c *Client) POST(path string, body any, output any, query ...Query) error

func (*Client) Raw

func (c *Client) Raw(method, path string, body any, output any, query ...Query) error

func (*Client) RawCtx

func (c *Client) RawCtx(ctx context.Context, method, path string, body any, output any, query ...Query) error

func (*Client) RawWithHeaders

func (c *Client) RawWithHeaders(ctx context.Context, method, path string, body any, output any, headers Headers, query ...Query) error

func (*Client) Update

func (c *Client) Update(collection, id string, body any, output any, query ...Query) error

func (*Client) View

func (c *Client) View(collection, id string, output any, query ...Query) error

func (*Client) WithToken

func (c *Client) WithToken(token string) *Client

type Error

type Error struct {
	Status int
	Method string
	Path   string
	Body   string
}

func IsError

func IsError(err error, status ...int) (Error, bool)

func (Error) Error

func (e Error) Error() string

type File

type File struct {
	Name string
	Data []byte
}

type Headers

type Headers map[string]string

type Query

type Query map[string]any

type Response

type Response[T any] struct {
	Page       int `json:"page"`
	PerPage    int `json:"perPage"`
	TotalItems int `json:"totalItems"`
	TotalPages int `json:"totalPages"`
	Items      []T `json:"items"`
}