api

package
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 30, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PageOutlineTypePage       = "page"
	PageOutlineTypeCanvas     = "canvas"
	PageOutlineTypeRepeatable = "repeatable"
)

Outline entry types that are not editable types.

Variables

View Source 
var (
	ErrNotFound     = errors.New("not found")
	ErrUnauthorized = errors.New("unauthorized")
	ErrForbidden    = errors.New("forbidden")
	ErrRateLimit    = errors.New("rate limit exceeded")
)

Common error checks

Functions

func Count 

func Count(ctx context.Context, c *Client, path string, opts ...RequestOption) (int, error)

Count fetches the count from an endpoint.

func CreateCustomerCustomizations 

func CreateCustomerCustomizations(ctx context.Context, c *Client, fields any, opts ...RequestOption) error

CreateCustomerCustomizations creates the customer field schema.

func CreateProductCustomizations 

func CreateProductCustomizations(ctx context.Context, c *Client, fields any, opts ...RequestOption) error

CreateProductCustomizations creates the product field schema.

func DeleteChannel added in v0.2.3 

func DeleteChannel(ctx context.Context, c *Client, slug string, opts ...RequestOption) error

DeleteChannel deletes a channel by slug or ID.

func DocumentValues added in v0.3.0 

func DocumentValues[T any](documents []Document[T]) []T

DocumentValues returns the typed views used by table and plain renderers.

func DownloadPageAssets 

func DownloadPageAssets(ctx context.Context, c *Client, doc PageDocument, dir string) (int, []string, error)

DownloadPageAssets downloads remote file editables and rewrites them to local attachment_path refs. Returns the count of successful downloads, any per-asset warnings (non-fatal), and a fatal error.

func ExpandPageAttachmentPaths 

func ExpandPageAttachmentPaths(doc PageDocument) error

ExpandPageAttachmentPaths prepares file editables for an API write:

  • attachment_path: read the local file, base64-encode it, mark __type "File"
  • attachment_url: same-site CDN uploads become nimbu:// FileRefs; other URLs are downloaded and inlined

A file editable that ends up with neither an inline attachment nor a writable source is an error, since writing it would silently clear the asset.

func ExpandPageAttachmentPathsWithOptions added in v0.2.4 

func ExpandPageAttachmentPathsWithOptions(doc PageDocument, opts PageAttachmentExpansionOptions) error

ExpandPageAttachmentPathsWithOptions prepares file editables for an API write with explicit handling for dangerous empty-file payloads.

func FileRefCopyWarning added in v0.3.1 

func FileRefCopyWarning(rawURL string) string

FileRefCopyWarning is the stderr message body when a URL is downloaded and inlined.

func IsForbidden 

func IsForbidden(err error) bool

IsForbidden checks if any error in the chain is a 403.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound checks if any error in the chain is a 404.

func IsRateLimit 

func IsRateLimit(err error) bool

IsRateLimit checks if any error in the chain is a 429.

func IsUnauthorized 

func IsUnauthorized(err error) bool

IsUnauthorized checks if any error in the chain is a 401.

func List 

func List[T any](ctx context.Context, c *Client, path string, opts ...RequestOption) ([]T, error)

List fetches all items from a paginated endpoint. 

func MenuDocumentHandle(doc MenuDocument) string

MenuDocumentHandle returns the menu handle when present. 

func MenuDocumentHasItems(doc MenuDocument) bool

MenuDocumentHasItems returns whether the raw menu response explicitly includes a nested items tree. 

func MenuDocumentName(doc MenuDocument) string

MenuDocumentName returns the menu name when present. 

func MenuDocumentSlug(doc MenuDocument) string

MenuDocumentSlug returns the canonical slug when present. 

func MenuNestingLost(submitted, returned MenuDocumentStats) bool

MenuNestingLost reports whether a write response dropped nested depth relative to the submitted tree.

func NewUploadCreateFileRefPayload added in v0.2.5 

func NewUploadCreateFileRefPayload(sourceURI string) map[string]any

NewUploadCreateFileRefPayload builds the JSON upload body for copying an existing Nimbu file.

func NewUploadCreatePayload added in v0.1.13 

func NewUploadCreatePayload(filename string, content []byte, contentType string) map[string]any

NewUploadCreatePayload builds the JSON upload body expected by POST /uploads.

func NormalizeMenuDocumentForWrite 

func NormalizeMenuDocumentForWrite(doc MenuDocument)

NormalizeMenuDocumentForWrite strips write-unsafe fields and fills API field aliases (title→name, url→target_url) on a nested menu tree without deleting the aliases.

func NormalizePageDocumentForWrite added in v0.2.4 

func NormalizePageDocumentForWrite(doc PageDocument)

NormalizePageDocumentForWrite removes server-managed top-level keys so the document can be safely sent on create/update requests.

func NormalizePageFullpath 

func NormalizePageFullpath(fullpath string) string

NormalizePageFullpath strips leading slashes and whitespace from a page fullpath.

func PageCanvasRepeatableCounts added in v0.2.4 

func PageCanvasRepeatableCounts(doc PageDocument) map[string]int

PageCanvasRepeatableCounts returns, for each canvas editable path, the number of repeatables it contains. Nested paths use dot notation and aggregate repeatables across repeated instances of the same editable path.

func PageCanvasRepeatableInstanceCounts added in v0.2.4 

func PageCanvasRepeatableInstanceCounts(doc PageDocument) map[string]int

PageCanvasRepeatableInstanceCounts returns repeatable counts for each canvas instance. Nested paths include repeatable indexes, e.g. blocks[0].gallery.

func PageDocumentFullpath 

func PageDocumentFullpath(doc PageDocument) string

PageDocumentFullpath returns the canonical page fullpath when present.

func PageDocumentLocale 

func PageDocumentLocale(doc PageDocument) string

PageDocumentLocale returns the page locale when present.

func PageDocumentParentPath 

func PageDocumentParentPath(doc PageDocument) string

PageDocumentParentPath returns the parent path for a page when present.

func PageDocumentPublished 

func PageDocumentPublished(doc PageDocument) bool

PageDocumentPublished returns whether the page is published.

func PageDocumentTemplate 

func PageDocumentTemplate(doc PageDocument) string

PageDocumentTemplate returns the page template when present.

func PageDocumentTitle 

func PageDocumentTitle(doc PageDocument) string

PageDocumentTitle returns the page title when present.

func PageETag added in v0.3.1 

func PageETag(id, updatedAt string) (string, error)

PageETag is md5("<id>-<updated_at.to_f>") matching Ruby Time#to_f.to_s.

func PageEditableFile 

func PageEditableFile(editable map[string]any) map[string]any

PageEditableFile returns the file map from an editable, or nil if absent.

func PageOutlineContent added in v0.3.2 

func PageOutlineContent(editable map[string]any) any

PageOutlineContent returns the readable value of an editable: its content, else its file object, else its reference object, else nil.

func PageShape added in v0.2.4 

func PageShape(doc PageDocument) any

PageShape returns a skeleton of the page's editables: editable name -> type, and for canvases the list of repeatables with their slug and nested skeleton.

func PageShapeWithSchema added in v0.3.1 

func PageShapeWithSchema(doc PageDocument, schema *pagepath.Schema) any

PageShapeWithSchema is PageShape plus select options when a schema is available.

func ParseNimbuCDNSiteShortID added in v0.3.1 

func ParseNimbuCDNSiteShortID(rawURL string) (string, bool)

ParseNimbuCDNSiteShortID returns the /s/<id>/ segment of a cdn.nimbu.io URL.

func ParseRelationIDs added in v0.3.1 

func ParseRelationIDs(value any) []string

ParseRelationIDs extracts IDs from a plain []string, an array of strings and/or Reference objects, or a Relation wrapper object.

func ReconcileMenuDocument added in v0.3.0 

func ReconcileMenuDocument(current, desired MenuDocument)

ReconcileMenuDocument appends explicit tombstones for existing items omitted from a desired full-tree document. This provides replace semantics without the server's recursive replace=1 behavior, which can delete nested siblings.

func ReplaceCustomerCustomizations 

func ReplaceCustomerCustomizations(ctx context.Context, c *Client, fields any, opts ...RequestOption) error

ReplaceCustomerCustomizations replaces the customer field schema.

func ReplaceProductCustomizations 

func ReplaceProductCustomizations(ctx context.Context, c *Client, fields any, opts ...RequestOption) error

ReplaceProductCustomizations replaces the product field schema.

func ResolveSiteShortID added in v0.3.1 

func ResolveSiteShortID(ctx context.Context, client *Client) (string, error)

ResolveSiteShortID reads site_short_id from GET /themes or GET /themes/:id/info, falling back to the /s/<id>/ segment of cdn_root.

func WalkPageEditables 

func WalkPageEditables(doc PageDocument, fn func(name string, editable map[string]any) error) error

WalkPageEditables traverses all editables in a page document, including nested repeatables.

Types

type ActionStatus added in v0.1.4 

type ActionStatus struct {
	Status  string `json:"status,omitempty"`
	Message string `json:"message,omitempty"`
	State   string `json:"state,omitempty"`
	Paid    bool   `json:"paid,omitempty"`
	Primary bool   `json:"primary,omitempty"`
	Domain  string `json:"domain,omitempty"`
}

ActionStatus represents small state-changing action responses.

type Anchor added in v0.3.1 

type Anchor struct {
	Set bool
	ID  string
}

Anchor is a tri-state batch `after` value: omitted, JSON null, or an id.

func (Anchor) MarshalJSON added in v0.3.1 

func (a Anchor) MarshalJSON() ([]byte, error)

MarshalJSON encodes an explicit null or a repeatable id.

type App 

type App struct {
	Name          string        `json:"name"`
	URL           string        `json:"url,omitempty"`
	Key           string        `json:"key,omitempty"`
	Domain        string        `json:"domain,omitempty"`
	CallbackURL   string        `json:"callback_url,omitempty"`
	SDKVersion    string        `json:"sdk_version,omitempty"`
	Internal      bool          `json:"internal,omitempty"`
	InstallScopes []string      `json:"install_scopes,omitempty"`
	Functions     []AppFunction `json:"functions,omitempty"`
	Routes        []AppRoute    `json:"routes,omitempty"`
	Callbacks     []AppCallback `json:"callbacks,omitempty"`
	Jobs          []AppJob      `json:"jobs,omitempty"`
	Schedules     []AppSchedule `json:"schedules,omitempty"`
	CreatedAt     *time.Time    `json:"created_at,omitempty"`
	UpdatedAt     *time.Time    `json:"updated_at,omitempty"`
}

App represents an OAuth app.

type AppCallback 

type AppCallback struct {
	Event     string     `json:"event,omitempty"`
	Type      string     `json:"type,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
	URL       string     `json:"url,omitempty"`
	SHA       string     `json:"sha,omitempty"`
}

AppCallback represents a callback inside an app.

type AppCodeFile 

type AppCodeFile struct {
	Name      string     `json:"name"`
	URL       string     `json:"url,omitempty"`
	Code      string     `json:"code,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

AppCodeFile represents an app cloud code file.

type AppFunction 

type AppFunction struct {
	Name string `json:"name"`
	SHA  string `json:"sha,omitempty"`
}

AppFunction represents a cloud function inside an app.

type AppJob 

type AppJob struct {
	Name      string     `json:"name"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
	Every     string     `json:"every,omitempty"`
	SHA       string     `json:"sha,omitempty"`
}

AppJob represents a job inside an app.

type AppLog added in v0.2.5 

type AppLog struct {
	ID        string          `json:"id"`
	Time      float64         `json:"time"`
	Level     string          `json:"level"`
	Data      json.RawMessage `json:"data"`
	CreatedAt time.Time       `json:"created_at"`
	Context   json.RawMessage `json:"context,omitempty"`
}

AppLog represents one cloud-code log entry.

func ListAppLogs added in v0.2.5 

func ListAppLogs(ctx context.Context, client *Client, appKey string, opts AppLogOptions) ([]AppLog, error)

ListAppLogs fetches cloud-code logs for an app.

type AppLogOptions added in v0.2.5 

type AppLogOptions struct {
	Since  string
	Before string
	Level  string
	Query  string
	Job    string
	Limit  int
}

AppLogOptions filters app cloud-code log requests.

type AppRoute 

type AppRoute struct {
	Order       int            `json:"order,omitempty"`
	Verb        string         `json:"verb,omitempty"`
	Path        string         `json:"path,omitempty"`
	Constraints map[string]any `json:"constraints,omitempty"`
	UpdatedAt   *time.Time     `json:"updated_at,omitempty"`
	SHA         string         `json:"sha,omitempty"`
}

AppRoute represents a cloud route inside an app.

type AppSchedule 

type AppSchedule struct {
	Name      string         `json:"name"`
	Timing    string         `json:"timing,omitempty"`
	Data      map[string]any `json:"data,omitempty"`
	UpdatedAt *time.Time     `json:"updated_at,omitempty"`
	Cron      string         `json:"cron,omitempty"`
	SHA       string         `json:"sha,omitempty"`
}

AppSchedule represents a schedule inside an app.

func (*AppSchedule) UnmarshalJSON 

func (s *AppSchedule) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes app schedule timing for older CLI fields.

type AuthResponse 

type AuthResponse struct {
	Token string `json:"token"`
	User  User   `json:"user"`
}

AuthResponse is returned from login.

type BatchOpError added in v0.3.1 

type BatchOpError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

BatchOpError is a per-operation failure.

type BatchOpResult added in v0.3.1 

type BatchOpResult struct {
	Index   int           `json:"index"`
	Status  string        `json:"status"`
	Path    string        `json:"path"`
	ID      string        `json:"id,omitempty"`
	Error   *BatchOpError `json:"error,omitempty"`
	Warning string        `json:"warning,omitempty"`
}

BatchOpResult is one per-operation outcome.

type BatchOperation added in v0.3.1 

type BatchOperation struct {
	Op    string  `json:"op"`
	Path  string  `json:"path"`
	Value any     `json:"value,omitempty"`
	After *Anchor `json:"after,omitempty"`
}

BatchOperation is one POST /pages/{id}/batch operation.

type BatchOptions added in v0.3.1 

type BatchOptions struct {
	Atomic        bool
	IncludeResult bool
	ContentLocale string
	IfMatch       string
}

BatchOptions configure POST /pages/{id}/batch.

type BatchResult added in v0.3.1 

type BatchResult struct {
	Results   []BatchOpResult `json:"results"`
	ETag      string          `json:"etag"`
	UpdatedAt string          `json:"updated_at"`
	Page      json.RawMessage `json:"page,omitempty"`
}

BatchResult is the successful batch response.

type Blog 

type Blog struct {
	ID        string     `json:"id"`
	Name      string     `json:"name"`
	Handle    string     `json:"handle,omitempty"`
	Slug      string     `json:"slug,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Blog represents a blog.

func (*Blog) UnmarshalJSON 

func (b *Blog) UnmarshalJSON(data []byte) error

UnmarshalJSON maps blog slug to Handle fallback.

type BlogPost 

type BlogPost struct {
	ID          string     `json:"id"`
	Title       string     `json:"title"`
	Slug        string     `json:"slug,omitempty"`
	TextContent string     `json:"text_content,omitempty"`
	Status      string     `json:"status,omitempty"`
	Author      string     `json:"author,omitempty"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
}

BlogPost represents a blog post.

type Channel 

type Channel struct {
	ID          string     `json:"id"`
	Slug        string     `json:"slug"`
	Name        string     `json:"name"`
	Description string     `json:"description,omitempty"`
	EntryCount  *int       `json:"entry_count,omitempty"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
}

Channel represents a content channel summary.

func (*Channel) UnmarshalJSON 

func (c *Channel) UnmarshalJSON(data []byte) error

UnmarshalJSON trims channel names and keeps missing entry_count as nil.

type ChannelDependencyGraph 

type ChannelDependencyGraph struct {
	// contains filtered or unexported fields
}

ChannelDependencyGraph captures dependency and dependant relationships between channels.

func BuildChannelDependencyGraph 

func BuildChannelDependencyGraph(channels []ChannelDetail) ChannelDependencyGraph

BuildChannelDependencyGraph constructs dependency relationships from relational custom fields.

func (ChannelDependencyGraph) DirectDependants 

func (g ChannelDependencyGraph) DirectDependants(slug string) []string

DirectDependants returns the direct dependants for a channel.

func (ChannelDependencyGraph) DirectDependencies 

func (g ChannelDependencyGraph) DirectDependencies(slug string) []string

DirectDependencies returns the direct dependencies for a channel.

func (ChannelDependencyGraph) HasCircularDependencies 

func (g ChannelDependencyGraph) HasCircularDependencies(slug string) bool

HasCircularDependencies reports whether a channel participates in a cycle.

func (ChannelDependencyGraph) TransitiveDependants 

func (g ChannelDependencyGraph) TransitiveDependants(slug string) []string

TransitiveDependants returns all dependant descendants for a channel.

func (ChannelDependencyGraph) TransitiveDependencies 

func (g ChannelDependencyGraph) TransitiveDependencies(slug string) []string

TransitiveDependencies returns all dependency descendants for a channel.

type ChannelDetail 

type ChannelDetail struct {
	ID                  string         `json:"id"`
	Slug                string         `json:"slug"`
	Name                string         `json:"name"`
	Description         string         `json:"description,omitempty"`
	ACL                 map[string]any `json:"acl,omitempty"`
	Customizations      []CustomField  `json:"customizations,omitempty"`
	EntriesURL          string         `json:"entries_url,omitempty"`
	LabelField          string         `json:"label_field,omitempty"`
	TitleField          string         `json:"title_field,omitempty"`
	OrderBy             string         `json:"order_by,omitempty"`
	OrderDirection      string         `json:"order_direction,omitempty"`
	RSSEnabled          bool           `json:"rss_enabled,omitempty"`
	RSSTitle            string         `json:"rss_title,omitempty"`
	RSSDescription      string         `json:"rss_description,omitempty"`
	RSSTitleField       string         `json:"rss_title_field,omitempty"`
	RSSDescriptionField string         `json:"rss_description_field,omitempty"`
	Submittable         bool           `json:"submittable,omitempty"`
	SubmittableFieldIDs []string       `json:"submittable_field_ids,omitempty"`
	URL                 string         `json:"url,omitempty"`
}

ChannelDetail is the canonical rich channel contract.

func CreateChannel added in v0.2.3 

func CreateChannel(ctx context.Context, c *Client, payload any, opts ...RequestOption) (ChannelDetail, error)

CreateChannel creates a channel from a payload and returns the created detail. The payload may be a ChannelDetail or a raw map[string]any (e.g. from inline assignments or a --file body), and should carry name, slug, and optionally title_field/label_field/order_by/order_direction and a customizations array.

func GetChannelDetail 

func GetChannelDetail(ctx context.Context, c *Client, slug string, opts ...RequestOption) (ChannelDetail, error)

GetChannelDetail fetches the canonical channel detail contract.

func ListChannelDetails 

func ListChannelDetails(ctx context.Context, c *Client, opts ...RequestOption) ([]ChannelDetail, error)

ListChannelDetails fetches all channels with their richer schema fields.

func PatchChannelCustomizations added in v0.1.14 

func PatchChannelCustomizations(ctx context.Context, c *Client, slug string, fields any, replace bool, opts ...RequestOption) (ChannelDetail, error)

PatchChannelCustomizations applies channel custom field changes.

type ChannelSummary 

type ChannelSummary = Channel

ChannelSummary is the lightweight list/get projection for channels.

type Client 

type Client struct {
	BaseURL string
	// Token is a static bearer token; Tokens takes precedence when set.
	Token string
	// Tokens is shared by every copy of the client, so a refresh made through
	// one copy serves all of them.
	Tokens     TokenSource
	Site       string
	Version    string
	HTTPClient *http.Client
	Debug      bool
	Readonly   bool
}

Client is the Nimbu API client.

func New 

func New(baseURL, token string) *Client

New creates a new API client.

func (*Client) CreatePageDraftPreviewToken added in v0.3.1 

func (c *Client) CreatePageDraftPreviewToken(ctx context.Context, pageID string) (*PageDraftPreviewToken, error)

CreatePageDraftPreviewToken posts POST /pages/{pageID}/draft/preview_token.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, path string, result any, opts ...RequestOption) error

Delete performs a DELETE request.

func (*Client) DeletePageDraft added in v0.3.1 

func (c *Client) DeletePageDraft(ctx context.Context, pageID string) error

DeletePageDraft discards DELETE /pages/{pageID}/draft.

func (*Client) DownloadURL 

func (c *Client) DownloadURL(ctx context.Context, rawURL string) (*http.Response, string, error)

DownloadURL fetches a file from a URL (absolute or relative to BaseURL). It appends raw=true to bypass CDN image optimization, resolves relative URLs, and attaches auth headers when the URL targets the API host.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, result any, opts ...RequestOption) error

Get performs a GET request.

func (*Client) GetPageDraft added in v0.3.1 

func (c *Client) GetPageDraft(ctx context.Context, pageID string, opts DraftOptions) (*PageDraft, error)

GetPageDraft fetches GET /pages/{pageID}/draft.

func (*Client) GetPageItems added in v0.3.1 

func (c *Client) GetPageItems(ctx context.Context, pageID, rawPath string) (*PageSubtree, error)

GetPageItems fetches GET /pages/{pageID}/items/<raw path without /items/>.

func (*Client) GetPageSchema added in v0.3.1 

func (c *Client) GetPageSchema(ctx context.Context, pageID string) (*pagepath.Schema, error)

GetPageSchema fetches GET /pages/{pageID}/schema.

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, path string, body any, result any, opts ...RequestOption) error

Patch performs a PATCH request.

func (*Client) Post 

func (c *Client) Post(ctx context.Context, path string, body any, result any, opts ...RequestOption) error

Post performs a POST request.

func (*Client) PostPageBatch added in v0.3.1 

func (c *Client) PostPageBatch(ctx context.Context, pageID string, ops []BatchOperation, opts BatchOptions) (*BatchResult, error)

PostPageBatch sends operations to POST /pages/{pageID}/batch.

func (*Client) PostPageDraft added in v0.3.1 

func (c *Client) PostPageDraft(ctx context.Context, pageID string, body any, opts DraftOptions) (*PageDraft, error)

PostPageDraft saves POST /pages/{pageID}/draft with a page-like body.

func (*Client) PostPageDraftBatch added in v0.3.1 

func (c *Client) PostPageDraftBatch(ctx context.Context, pageID string, ops []BatchOperation, opts DraftBatchOptions) (*DraftBatchResult, error)

PostPageDraftBatch sends operations to POST /pages/{pageID}/draft/batch.

func (*Client) PublishPageDraft added in v0.3.1 

func (c *Client) PublishPageDraft(ctx context.Context, pageID string, confirm bool) (PageDocument, error)

PublishPageDraft posts POST /pages/{pageID}/draft/publish.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, path string, body any, result any, opts ...RequestOption) error

Put performs a PUT request.

func (*Client) RawRequest 

func (c *Client) RawRequest(ctx context.Context, method, path string, body any, opts ...RequestOption) (*http.Response, error)

RawRequest performs a request and returns the raw response.

func (*Client) Request 

func (c *Client) Request(ctx context.Context, method, path string, body any, result any, opts ...RequestOption) error

Request performs an HTTP request and decodes the JSON response.

func (*Client) SimulatorRender 

func (c *Client) SimulatorRender(ctx context.Context, payload SimulatorPayload) (*SimulatorResponse, error)

SimulatorRender calls the simulator rendering endpoint.

func (*Client) WithDebug 

func (c *Client) WithDebug(debug bool) *Client

WithDebug returns a copy of the client with debug logging enabled.

func (*Client) WithReadonly added in v0.2.1 

func (c *Client) WithReadonly(readonly bool) *Client

WithReadonly returns a copy of the client that blocks mutating requests.

func (*Client) WithSite 

func (c *Client) WithSite(site string) *Client

WithSite returns a copy of the client with the site set.

func (*Client) WithTimeout 

func (c *Client) WithTimeout(timeout time.Duration) *Client

WithTimeout returns a copy of the client with custom timeout.

func (*Client) WithTokenSource added in v0.4.0 

func (c *Client) WithTokenSource(ts TokenSource) *Client

WithTokenSource returns a copy of the client that authenticates with ts.

func (*Client) WithVersion added in v0.1.4 

func (c *Client) WithVersion(version string) *Client

WithVersion returns a copy of the client with the version set.

type Collection 

type Collection struct {
	ID             string                    `json:"id"`
	URL            string                    `json:"url,omitempty"`
	Name           string                    `json:"name"`
	Slug           string                    `json:"slug,omitempty"`
	Fullpath       string                    `json:"fullpath,omitempty"`
	Description    string                    `json:"description,omitempty"`
	ProductCount   int                       `json:"product_count,omitempty"`
	Status         string                    `json:"status,omitempty"`
	Type           string                    `json:"type,omitempty"`
	Priority       int                       `json:"priority,omitempty"`
	SEOTitle       string                    `json:"seo_title,omitempty"`
	SEODescription string                    `json:"seo_description,omitempty"`
	SEOKeywords    string                    `json:"seo_keywords,omitempty"`
	Images         []CollectionImage         `json:"images,omitempty"`
	FeaturedImage  *CollectionImage          `json:"featured_image,omitempty"`
	Translations   map[string]map[string]any `json:"translations,omitempty"`
	CreatedAt      *time.Time                `json:"created_at,omitempty"`
	UpdatedAt      *time.Time                `json:"updated_at,omitempty"`
}

Collection represents a product collection.

type CollectionImage 

type CollectionImage struct {
	ID          string `json:"id"`
	Position    int    `json:"position,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Width       int    `json:"width,omitempty"`
	Height      int    `json:"height,omitempty"`
	Size        int64  `json:"size,omitempty"`
	URL         string `json:"url,omitempty"`
}

CollectionImage represents an image attached to a collection.

type Coupon 

type Coupon struct {
	ID               string           `json:"id"`
	Name             string           `json:"name"`
	Description      string           `json:"description,omitempty"`
	Reason           string           `json:"reason,omitempty"`
	State            string           `json:"state,omitempty"`
	CouponType       string           `json:"coupon_type,omitempty"`
	CouponPercentage float64          `json:"coupon_percentage,omitempty"`
	CouponAmount     float64          `json:"coupon_amount,omitempty"`
	CustomerSpecific bool             `json:"customer_specific,omitempty"`
	Code             string           `json:"code,omitempty"`
	Lifespan         string           `json:"lifespan,omitempty"`
	LifespanAmount   int              `json:"lifespan_amount,omitempty"`
	LifespanTime     string           `json:"lifespan_time,omitempty"`
	Start            string           `json:"start,omitempty"`
	StartType        string           `json:"start_type,omitempty"`
	Constraints      string           `json:"constraints,omitempty"`
	Requirements     string           `json:"requirements,omitempty"`
	RequiredValue    float64          `json:"required_value,omitempty"`
	RequiredAmount   int              `json:"required_amount,omitempty"`
	CollectionIDs    []string         `json:"collection_ids,omitempty"`
	ProductTypeIDs   []string         `json:"product_type_ids,omitempty"`
	Customers        []map[string]any `json:"customers,omitempty"`
	Redemptions      []map[string]any `json:"redemptions,omitempty"`
	Referral         map[string]any   `json:"referral,omitempty"`
	Referrer         map[string]any   `json:"referrer,omitempty"`
	CreatedAt        *time.Time       `json:"created_at,omitempty"`
	UpdatedAt        *time.Time       `json:"updated_at,omitempty"`
}

Coupon represents a coupon.

type CustomField 

type CustomField struct {
	ID                   string         `json:"id,omitempty"`
	Name                 string         `json:"name,omitempty"`
	Label                string         `json:"label,omitempty"`
	Type                 string         `json:"type,omitempty"`
	Required             bool           `json:"required,omitempty"`
	RequiredExpression   string         `json:"required_expression,omitempty"`
	Unique               bool           `json:"unique,omitempty"`
	Localized            bool           `json:"localized,omitempty"`
	Encrypted            bool           `json:"encrypted,omitempty"`
	Hint                 string         `json:"hint,omitempty"`
	Reference            string         `json:"reference,omitempty"`
	SelectOptions        []SelectOption `json:"select_options,omitempty"`
	GeoType              string         `json:"geo_type,omitempty"`
	CalculatedExpression string         `json:"calculated_expression,omitempty"`
	CalculationType      string         `json:"calculation_type,omitempty"`
	PrivateStorage       bool           `json:"private_storage,omitempty"`
	Extra                map[string]any `json:"-"`
}

CustomField represents a channel customization field.

func GetChannelCustomizations added in v0.1.14 

func GetChannelCustomizations(ctx context.Context, c *Client, slug string, opts ...RequestOption) ([]CustomField, error)

GetChannelCustomizations fetches the custom field schema for one channel.

func GetCustomerCustomizations 

func GetCustomerCustomizations(ctx context.Context, c *Client, opts ...RequestOption) ([]CustomField, error)

GetCustomerCustomizations fetches the customer field schema.

func GetProductCustomizations 

func GetProductCustomizations(ctx context.Context, c *Client, opts ...RequestOption) ([]CustomField, error)

GetProductCustomizations fetches the product field schema.

func (CustomField) IsRelational 

func (f CustomField) IsRelational() bool

IsRelational reports whether the field references another channel.

func (CustomField) MarshalJSON 

func (f CustomField) MarshalJSON() ([]byte, error)

MarshalJSON emits known fields plus any Extra attributes preserved during unmarshal.

func (*CustomField) UnmarshalJSON 

func (f *CustomField) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves unknown field attributes while decoding the known customization fields.

type Customer 

type Customer struct {
	ID        string     `json:"id"`
	Email     string     `json:"email"`
	FirstName string     `json:"first_name,omitempty"`
	LastName  string     `json:"last_name,omitempty"`
	Phone     string     `json:"phone,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Customer represents a customer.

func (*Customer) UnmarshalJSON 

func (c *Customer) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts both modern and legacy customer field names.

type Document added in v0.3.0 

type Document[T any] struct {
	Value T
	// contains filtered or unexported fields
}

Document keeps the original API representation alongside a typed view. JSON output is therefore lossless while human-oriented commands can use Value.

func (Document[T]) MarshalJSON added in v0.3.0 

func (d Document[T]) MarshalJSON() ([]byte, error)

func (*Document[T]) UnmarshalJSON added in v0.3.0 

func (d *Document[T]) UnmarshalJSON(data []byte) error

type Domain added in v0.1.4 

type Domain struct {
	ID             string     `json:"id"`
	Domain         string     `json:"domain"`
	DNSCheck       bool       `json:"dns_check,omitempty"`
	Primary        bool       `json:"primary,omitempty"`
	SSLEnabled     bool       `json:"ssl_enabled,omitempty"`
	RedirectDomain string     `json:"redirect_domain,omitempty"`
	DefaultLocale  string     `json:"default_locale,omitempty"`
	DefaultCountry string     `json:"default_country,omitempty"`
	CreatedAt      *time.Time `json:"created_at,omitempty"`
	UpdatedAt      *time.Time `json:"updated_at,omitempty"`
}

Domain represents a custom site domain.

type DraftBatchOptions added in v0.3.1 

type DraftBatchOptions struct {
	ContentLocale string
}

DraftBatchOptions configure POST /pages/{id}/draft/batch.

type DraftBatchResult added in v0.3.1 

type DraftBatchResult struct {
	Results []BatchOpResult `json:"results"`
	Draft   json.RawMessage `json:"draft"`
}

DraftBatchResult is the successful draft batch response.

type DraftOptions added in v0.3.1 

type DraftOptions struct {
	ContentLocale string
}

DraftOptions configure draft GET/POST query params.

type Entry 

type Entry struct {
	ID        string         `json:"id"`
	Slug      string         `json:"slug,omitempty"`
	Title     string         `json:"title,omitempty"`
	Body      string         `json:"body,omitempty"`
	Position  int            `json:"position,omitempty"`
	Locale    string         `json:"locale,omitempty"`
	Published bool           `json:"published,omitempty"`
	Fields    map[string]any `json:"fields,omitempty"`
	CreatedAt *time.Time     `json:"created_at,omitempty"`
	UpdatedAt *time.Time     `json:"updated_at,omitempty"`
	Extra     map[string]any `json:"-"`
}

Entry represents a channel entry.

func (Entry) MarshalJSON added in v0.1.7 

func (e Entry) MarshalJSON() ([]byte, error)

MarshalJSON emits known entry fields plus custom top-level fields preserved from the channel entry payload.

func (*Entry) UnmarshalJSON added in v0.1.7 

func (e *Entry) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves custom top-level fields on channel entries.

type Error 

type Error struct {
	StatusCode int               `json:"status_code"`
	Code       string            `json:"code,omitempty"`
	Message    string            `json:"message"`
	Details    map[string]any    `json:"details,omitempty"`
	Errors     []ValidationError `json:"errors,omitempty"`
	Raw        map[string]any    `json:"-"`
	Err        error             `json:"-"`
}

Error represents an API error.

func (*Error) BatchResults added in v0.3.1 

func (e *Error) BatchResults() []BatchOpResult

BatchResults decodes results from a 422 atomic_failure body.

func (*Error) CurrentETag added in v0.3.1 

func (e *Error) CurrentETag() string

CurrentETag returns current_etag from a 412 body, if present.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) IsForbidden 

func (e *Error) IsForbidden() bool

IsForbidden returns true if this is a 403 error.

func (*Error) IsNotFound 

func (e *Error) IsNotFound() bool

IsNotFound returns true if this is a 404 error.

func (*Error) IsRateLimit 

func (e *Error) IsRateLimit() bool

IsRateLimit returns true if this is a 429 error.

func (*Error) IsUnauthorized 

func (e *Error) IsUnauthorized() bool

IsUnauthorized returns true if this is a 401 error.

func (*Error) IsValidation 

func (e *Error) IsValidation() bool

IsValidation returns true if this is a 422 validation error.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type FileRefNormalizer added in v0.3.1 

type FileRefNormalizer struct {
	Client      *Client
	SiteShortID string
	HTTPClient  *http.Client
}

FileRefNormalizer turns remote file URLs into write payloads. Same-site CDN URLs become nimbu:// upload references; every other http(s) URL is downloaded and inlined as {"__type":"File","attachment":...}.

func (*FileRefNormalizer) EnsureSiteShortID added in v0.3.1 

func (n *FileRefNormalizer) EnsureSiteShortID(ctx context.Context) (string, error)

EnsureSiteShortID returns the cached short id or resolves it from the API.

func (*FileRefNormalizer) NormalizeURL added in v0.3.1 

func (n *FileRefNormalizer) NormalizeURL(ctx context.Context, rawURL string) (map[string]any, string, error)

NormalizeURL rewrites a remote file URL into a FileRef write payload.

type JobRunResult 

type JobRunResult struct {
	JID string `json:"jid"`
}

JobRunResult represents a scheduled job response. 

type Links struct {
	First string
	Prev  string
	Next  string
	Last  string
}

Links holds pagination links from the Link header. 

func ParseLinks(header string) Links

ParseLinks parses the Link header.

func (Links) HasNext 

func (l Links) HasNext() bool

HasNext returns true if there's a next page.

type LoginRequest 

type LoginRequest struct {
	Description string `json:"description"`
	ExpiresIn   int    `json:"expires_in"`
}

LoginRequest is sent to /auth/login. 

type Menu struct {
	ID        string     `json:"id"`
	Name      string     `json:"name"`
	Handle    string     `json:"handle,omitempty"`
	Slug      string     `json:"slug,omitempty"`
	Items     []MenuItem `json:"items,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Menu represents a navigation menu summary. 

func (m *Menu) UnmarshalJSON(data []byte) error

UnmarshalJSON maps menu slug to Handle fallback. 

type MenuDocument map[string]any

MenuDocument is the canonical nested menu contract used for get/update flows.

func GetMenuDocument 

func GetMenuDocument(ctx context.Context, c *Client, identifier string, opts ...RequestOption) (MenuDocument, error)

GetMenuDocument fetches a menu document, falling back to the nested list contract when needed.

func PatchMenuDocument 

func PatchMenuDocument(ctx context.Context, c *Client, slug string, doc MenuDocument, opts ...RequestOption) (MenuDocument, error)

PatchMenuDocument updates a menu document. Pass WithReplace(true) for full-tree replace semantics.

func PostMenuDocument added in v0.2.4 

func PostMenuDocument(ctx context.Context, c *Client, doc MenuDocument, opts ...RequestOption) (MenuDocument, error)

PostMenuDocument creates a menu document, preserving the nested items tree.

func SelectMenuDocument 

func SelectMenuDocument(menus []MenuDocument, identifier string) (MenuDocument, bool)

SelectMenuDocument matches a menu by slug or handle from a nested menu result set. 

type MenuDocumentStats struct {
	HasItems  bool
	ItemCount int
	MaxDepth  int
	Shape     string
}

MenuDocumentStats summarizes a nested menu tree. 

func MenuStats(doc MenuDocument) MenuDocumentStats

MenuStats counts items and depth in a nested menu tree. 

type MenuItem struct {
	ID       string     `json:"id"`
	Title    string     `json:"title"`
	URL      string     `json:"url,omitempty"`
	Target   string     `json:"target,omitempty"`
	Position int        `json:"position,omitempty"`
	Children []MenuItem `json:"children,omitempty"`
}

MenuItem represents a menu item.

Read/write documents use MenuDocument (map[string]any). The API write shape prefers name/target_url; NormalizeMenuDocumentForWrite also accepts title/url aliases. This typed struct retains title/url for list/summary compatibility. 

type MenuSummary = Menu

MenuSummary is the lightweight list projection for menus.

type Notification 

type Notification struct {
	ID           string                    `json:"id"`
	URL          string                    `json:"url,omitempty"`
	Slug         string                    `json:"slug,omitempty"`
	Name         string                    `json:"name"`
	Description  string                    `json:"description,omitempty"`
	Subject      string                    `json:"subject,omitempty"`
	Text         string                    `json:"text,omitempty"`
	HTML         string                    `json:"html,omitempty"`
	HTMLEnabled  bool                      `json:"html_enabled,omitempty"`
	Translations map[string]map[string]any `json:"translations,omitempty"`
	CreatedAt    *time.Time                `json:"created_at,omitempty"`
	UpdatedAt    *time.Time                `json:"updated_at,omitempty"`
}

Notification represents a notification template.

type OperationClass 

type OperationClass string

OperationClass classifies request side-effect semantics. 

const (
	OperationRead        OperationClass = "read"
	OperationMutate      OperationClass = "mutate"
	OperationDestructive OperationClass = "destructive"
)

type Order 

type Order struct {
	ID         string     `json:"id"`
	Number     string     `json:"number,omitempty"`
	Status     string     `json:"status,omitempty"`
	Total      float64    `json:"total,omitempty"`
	Currency   string     `json:"currency,omitempty"`
	CustomerID string     `json:"customer_id,omitempty"`
	CreatedAt  *time.Time `json:"created_at,omitempty"`
	UpdatedAt  *time.Time `json:"updated_at,omitempty"`
}

Order represents an order.

func (*Order) UnmarshalJSON 

func (o *Order) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes order fields from API responses.

type Page 

type Page struct {
	ID         string         `json:"id"`
	Fullpath   string         `json:"fullpath,omitempty"`
	Parent     string         `json:"parent,omitempty"`
	ParentPath string         `json:"parent_path,omitempty"`
	Slug       string         `json:"slug,omitempty"`
	Title      string         `json:"title,omitempty"`
	Template   string         `json:"template,omitempty"`
	Published  bool           `json:"published,omitempty"`
	Locale     string         `json:"locale,omitempty"`
	Fields     map[string]any `json:"fields,omitempty"`
	CreatedAt  *time.Time     `json:"created_at,omitempty"`
	UpdatedAt  *time.Time     `json:"updated_at,omitempty"`
}

Page represents a page summary.

type PageAttachmentExpansionOptions added in v0.2.4 

type PageAttachmentExpansionOptions struct {
	AllowEmptyFile      bool
	DropEmptyFile       bool
	DropReadOnlyFileURL bool
	Context             context.Context
	FileRef             *FileRefNormalizer
	Warn                func(string)
}

PageAttachmentExpansionOptions configures file editable expansion for writes.

type PageDocument 

type PageDocument map[string]any

PageDocument is the canonical page contract used for get/update flows.

func GetPageDocument 

func GetPageDocument(ctx context.Context, c *Client, fullpath string, opts ...RequestOption) (PageDocument, error)

GetPageDocument fetches the full page document by fullpath.

func PageCompactDocument added in v0.3.2 

func PageCompactDocument(doc PageDocument) (PageDocument, error)

PageCompactDocument returns a display-only copy of the page document with per-editable bookkeeping removed: editable created_at/updated_at/slug/type, repeatable created_at/updated_at, translation entries that merely repeat the default-locale content, and file objects reduced to url/filename/width/height. Repeatable ids, positions and slugs are kept.

func PageProjectFields added in v0.3.2 

func PageProjectFields(doc PageDocument, fields []string) (PageDocument, error)

PageProjectFields keeps only the requested top-level keys of a page document. Unknown field names are reported as an error.

func PatchPageDocument 

func PatchPageDocument(ctx context.Context, c *Client, fullpath string, doc PageDocument, opts ...RequestOption) (PageDocument, error)

PatchPageDocument updates a page document. The caller controls merge vs. replace semantics via opts (see WithReplace); by default the API merges.

type PageDocumentStats 

type PageDocumentStats struct {
	AttachmentCount int
	EditableCount   int
}

PageDocumentStats summarizes nested editables inside a page document.

func PageStats 

func PageStats(doc PageDocument) PageDocumentStats

PageStats traverses the page document and counts editables and attachment-bearing file objects.

type PageDraft added in v0.3.1 

type PageDraft struct {
	ID               string          `json:"id"`
	PageID           string          `json:"page_id"`
	FuturePageID     string          `json:"future_page_id,omitempty"`
	ReservedFullpath string          `json:"reserved_fullpath,omitempty"`
	Content          json.RawMessage `json:"content"`
	UpdatedAt        string          `json:"updated_at"`
	// contains filtered or unexported fields
}

PageDraft is GET/POST /pages/{id}/draft with a lossless raw body.

func (PageDraft) ContentMap added in v0.3.1 

func (d PageDraft) ContentMap() map[string]any

ContentMap decodes draft.content as a generic object.

func (PageDraft) MarshalJSON added in v0.3.1 

func (d PageDraft) MarshalJSON() ([]byte, error)

func (*PageDraft) UnmarshalJSON added in v0.3.1 

func (d *PageDraft) UnmarshalJSON(data []byte) error

type PageDraftPreviewToken added in v0.3.1 

type PageDraftPreviewToken struct {
	Token      string `json:"token"`
	PreviewURL string `json:"preview_url"`
}

PageDraftPreviewToken is POST /pages/{id}/draft/preview_token.

type PageOutlineEntry added in v0.3.2 

type PageOutlineEntry struct {
	Path    string `json:"path"`
	RawPath string `json:"raw_path"`
	ID      string `json:"id,omitempty"`
	Slug    string `json:"slug,omitempty"`
	Type    string `json:"type"`
	Content any    `json:"content,omitempty"`

	// Label is the short display name for text output ("Blokken[0]"), Depth
	// the indent level, Repeatables the number of repeatables on a canvas
	// entry. None of them are serialized.
	Label       string `json:"-"`
	Depth       int    `json:"-"`
	Repeatables int    `json:"-"`
}

PageOutlineEntry is one row of a page outline: a page field, a canvas, a repeatable instance, or an editable inside one. Path is empty when no human path can address the entry; RawPath always can.

func PageOutline added in v0.3.2 

func PageOutline(doc PageDocument) []PageOutlineEntry

PageOutline flattens a page document into an ordered, readable listing: page-level fields first, then every editable in canvas/repeatable order. Paths are valid `pages set --path` inputs; RawPath is the API path.

type PageSubtree added in v0.3.1 

type PageSubtree struct {
	Path          string          `json:"path"`
	ParentPath    string          `json:"parent_path"`
	Position      int             `json:"position"`
	SiblingsCount int             `json:"siblings_count"`
	Type          string          `json:"type"`
	Data          json.RawMessage `json:"data"`
	// contains filtered or unexported fields
}

PageSubtree is GET /pages/{id}/items/... with a lossless raw body.

func (PageSubtree) MarshalJSON added in v0.3.1 

func (s PageSubtree) MarshalJSON() ([]byte, error)

func (*PageSubtree) UnmarshalJSON added in v0.3.1 

func (s *PageSubtree) UnmarshalJSON(data []byte) error

type PageSummary 

type PageSummary = Page

PageSummary is the lightweight list projection for pages.

type PagedResponse 

type PagedResponse[T any] struct {
	Data       []T
	Pagination Pagination
	Links      Links
}

PagedResponse wraps paginated API responses.

func ListPage 

func ListPage[T any](ctx context.Context, c *Client, path string, page, perPage int, opts ...RequestOption) (*PagedResponse[T], error)

ListPage fetches a single page from a paginated endpoint.

func (*PagedResponse[T]) HasMore added in v0.2.3 

func (p *PagedResponse[T]) HasMore(perPage, collected int) bool

HasMore reports whether another page should be fetched after this one. It prefers the Link header, falls back to X-Total-Count when the header is absent (degraded responses from rate limiters or CDNs may drop it), and as a last resort treats a full page without any Link header as "probably more" so truncation requires an explicit short page rather than a missing header.

type Pagination 

type Pagination struct {
	Page       int  `json:"page"`
	PerPage    int  `json:"per_page"`
	Total      int  `json:"total"`
	TotalPages int  `json:"total_pages"`
	TotalKnown bool `json:"-"`
}

Pagination holds pagination information.

type Product 

type Product struct {
	ID               string     `json:"id"`
	URL              string     `json:"url,omitempty"`
	Slug             string     `json:"slug,omitempty"`
	Name             string     `json:"name"`
	Description      string     `json:"description,omitempty"`
	Status           string     `json:"status,omitempty"`
	Price            float64    `json:"price,omitempty"`
	Currency         string     `json:"currency,omitempty"`
	SKU              string     `json:"sku,omitempty"`
	Inventory        int        `json:"inventory,omitempty"`
	Published        bool       `json:"published,omitempty"`
	CurrentStock     int        `json:"current_stock,omitempty"`
	Digital          bool       `json:"digital,omitempty"`
	RequiresShipping bool       `json:"requires_shipping,omitempty"`
	OnSale           bool       `json:"on_sale,omitempty"`
	OnSalePrice      float64    `json:"on_sale_price,omitempty"`
	VariantsEnabled  bool       `json:"variants_enabled,omitempty"`
	KeepStock        bool       `json:"keep_stock,omitempty"`
	CreatedAt        *time.Time `json:"created_at,omitempty"`
	UpdatedAt        *time.Time `json:"updated_at,omitempty"`
}

Product represents a product.

func (*Product) UnmarshalJSON 

func (p *Product) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes product fields from current and legacy API responses.

type ReadonlyError added in v0.2.1 

type ReadonlyError struct {
	Method string
	Path   string
}

ReadonlyError is returned before a mutating request is sent by a readonly client.

func (*ReadonlyError) Error added in v0.2.1 

func (e *ReadonlyError) Error() string

type RealtimeGrant added in v0.3.3 

type RealtimeGrant struct {
	Grant     string    `json:"grant"`
	ExpiresAt time.Time `json:"expires_at"`
}

RealtimeGrant is a single-use, short-lived credential for the realtime socket. The grant value is a secret: never log it or include it in error messages.

func MintRealtimeGrant added in v0.3.3 

func MintRealtimeGrant(ctx context.Context, c *Client) (*RealtimeGrant, error)

MintRealtimeGrant requests a fresh realtime grant for the client's site.

type Redirect 

type Redirect struct {
	ID        string     `json:"id"`
	URL       string     `json:"url,omitempty"`
	Source    string     `json:"source,omitempty"`
	Target    string     `json:"target,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Redirect represents a redirect rule.

type RelationIDs added in v0.3.1 

type RelationIDs []string

RelationIDs is a list of related object IDs.

The Nimbu API returns relation fields as a plain string array unless X-Nimbu-Client-Version is set, in which case it uses a Relation wrapper with Reference objects. UnmarshalJSON accepts both shapes. MarshalJSON always emits a plain []string.

func (RelationIDs) MarshalJSON added in v0.3.1 

func (r RelationIDs) MarshalJSON() ([]byte, error)

MarshalJSON emits a plain JSON string array.

func (*RelationIDs) UnmarshalJSON added in v0.3.1 

func (r *RelationIDs) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts []string, arrays of Reference objects, mixed arrays, and {"__type":"Relation","objects":[...]} wrappers.

type RequestBody 

type RequestBody struct {
	Reader        io.Reader
	GetBody       func() (io.ReadCloser, error)
	ContentType   string
	ContentLength int64
}

RequestBody supplies a custom request stream instead of JSON-marshaled data.

type RequestOption 

type RequestOption func(*requestOptions)

RequestOption configures a request.

func WithContentLocale added in v0.1.7 

func WithContentLocale(locale string) RequestOption

WithContentLocale sets the query locale for localized content fields.

func WithFields 

func WithFields(fields string) RequestOption

WithFields sets the fields to include.

func WithHeader 

func WithHeader(key, value string) RequestOption

WithHeader adds a request header.

func WithIdempotent 

func WithIdempotent(idempotent bool) RequestOption

WithIdempotent marks whether the request is safe to retry.

func WithInclude 

func WithInclude(include string) RequestOption

WithInclude sets related resources to include.

func WithLocale 

func WithLocale(locale string) RequestOption

WithLocale sets the locale for the request.

func WithOperationClass 

func WithOperationClass(class OperationClass) RequestOption

WithOperationClass overrides request operation class.

func WithPage 

func WithPage(page, perPage int) RequestOption

WithPage adds pagination parameters.

func WithParam 

func WithParam(key, value string) RequestOption

WithParam adds a single query parameter.

func WithQuery 

func WithQuery(params map[string]string) RequestOption

WithQuery adds query parameters.

func WithRedactedResponseLog added in v0.3.3 

func WithRedactedResponseLog() RequestOption

WithRedactedResponseLog replaces the response body in debug logs with a placeholder. Use it for responses carrying secrets, such as realtime grants.

func WithReplace added in v0.2.4 

func WithReplace(replace bool) RequestOption

WithReplace sets the replace query parameter for destructive rebuilds. It is a no-op when replace is false, leaving merge semantics in place.

func WithSite 

func WithSite(site string) RequestOption

WithSite sets the site for this request.

func WithTokenRejection added in v0.4.0 

func WithTokenRejection() RequestOption

WithTokenRejection marks an endpoint where a 401 can only mean the bearer token was rejected, such as GET /user. The client then renews the token and replays the request even when the token looks fresh, so a session revoked on the server is noticed at once.

type ResponseDecodeError added in v0.3.1 

type ResponseDecodeError struct {
	StatusCode int
	Body       []byte
	Err        error
}

ResponseDecodeError is returned when a 2xx response body cannot be decoded. The request itself succeeded; only the typed response mapping failed.

func (*ResponseDecodeError) Error added in v0.3.1 

func (e *ResponseDecodeError) Error() string

func (*ResponseDecodeError) Unwrap added in v0.3.1 

func (e *ResponseDecodeError) Unwrap() error

type RetryTransport 

type RetryTransport struct {
	Transport  http.RoundTripper
	MaxRetries int
	BaseDelay  time.Duration
}

RetryTransport wraps an http.RoundTripper with retry logic.

func NewRetryTransport 

func NewRetryTransport(transport http.RoundTripper) *RetryTransport

NewRetryTransport creates a new RetryTransport.

func (*RetryTransport) RoundTrip 

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper with retry logic.

type Role 

type Role struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Customers   RelationIDs    `json:"customers,omitempty"`
	Children    RelationIDs    `json:"children,omitempty"`
	Parents     RelationIDs    `json:"parents,omitempty"`
	ACL         map[string]any `json:"_acl,omitempty"`
	Owner       string         `json:"_owner,omitempty"`
	CreatedAt   *time.Time     `json:"created_at,omitempty"`
	UpdatedAt   *time.Time     `json:"updated_at,omitempty"`

	// Expanded is false when the API returned a Relation pointer without
	// an objects array, so the ID list is not known and must not be
	// treated as empty.
	CustomersExpanded bool `json:"-"`
	ChildrenExpanded  bool `json:"-"`
	ParentsExpanded   bool `json:"-"`
}

Role represents a customer role.

func (*Role) UnmarshalJSON added in v0.3.1 

func (r *Role) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a role and records whether each relation field was expanded. A Relation pointer without an objects key is not an empty list.

type SelectOption 

type SelectOption struct {
	ID       string `json:"id,omitempty"`
	Name     string `json:"name,omitempty"`
	Position int    `json:"position,omitempty"`
	Slug     string `json:"slug,omitempty"`
}

SelectOption represents a select or multi-select option in a channel customization.

type SenderDNSRecord added in v0.1.4 

type SenderDNSRecord struct {
	Type        string `json:"type,omitempty"`
	Name        string `json:"name,omitempty"`
	Value       string `json:"value,omitempty"`
	Host        string `json:"host,omitempty"`
	TTL         int    `json:"ttl,omitempty"`
	Priority    int    `json:"priority,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

SenderDNSRecord represents a DNS verification record for a sender domain.

type SenderDomain added in v0.1.4 

type SenderDomain struct {
	ID                  string            `json:"id"`
	Domain              string            `json:"domain"`
	Provider            string            `json:"provider,omitempty"`
	Status              string            `json:"status,omitempty"`
	OwnershipVerified   bool              `json:"ownership_verified,omitempty"`
	OwnershipVerifiedAt *time.Time        `json:"ownership_verified_at,omitempty"`
	VerifiedAt          *time.Time        `json:"verified_at,omitempty"`
	LastCheckAt         *time.Time        `json:"last_check_at,omitempty"`
	LastCheckError      string            `json:"last_check_error,omitempty"`
	ExpectedTXTRecord   string            `json:"expected_txt_record,omitempty"`
	DNSRecords          []SenderDNSRecord `json:"dns_records,omitempty"`
	CreatedAt           *time.Time        `json:"created_at,omitempty"`
	UpdatedAt           *time.Time        `json:"updated_at,omitempty"`
}

SenderDomain represents an email sender domain.

type ShippingRate added in v0.3.0 

type ShippingRate struct {
	ID         string `json:"id"`
	Name       string `json:"name,omitempty"`
	Criteria   any    `json:"criteria,omitempty"`
	Price      any    `json:"price,omitempty"`
	Default    bool   `json:"default,omitempty"`
	Pickup     bool   `json:"pickup,omitempty"`
	RegionID   string `json:"region_id,omitempty"`
	WeightMin  any    `json:"weight_min,omitempty"`
	WeightMax  any    `json:"weight_max,omitempty"`
	OrderMin   any    `json:"order_min,omitempty"`
	OrderMax   any    `json:"order_max,omitempty"`
	Restricted bool   `json:"restricted,omitempty"`
	Zipcodes   any    `json:"zipcodes,omitempty"`
}

ShippingRate represents the stable fields used by human-oriented output. Commands wrap it in Document so structured output retains unknown API fields.

type SimulatorPayload 

type SimulatorPayload struct {
	Simulator SimulatorRequest `json:"simulator"`
}

SimulatorPayload is sent to /simulator/render. Keep compatible with existing toolbelt format.

type SimulatorRequest 

type SimulatorRequest struct {
	Code    string                  `json:"code"`
	Method  string                  `json:"method"`
	Path    string                  `json:"path"`
	Request SimulatorRequestContext `json:"request"`
	Version string                  `json:"version"`
}

SimulatorRequest contains the full render request context.

type SimulatorRequestContext 

type SimulatorRequestContext struct {
	Body    *string        `json:"body,omitempty"`
	Headers string         `json:"headers"`
	Host    string         `json:"host"`
	Method  string         `json:"method"`
	Params  map[string]any `json:"params"`
	Port    int            `json:"port"`
	Query   string         `json:"query"`
	RawBody *string        `json:"rawBody,omitempty"`
}

SimulatorRequestContext mirrors the Ruby-compatible request envelope.

type SimulatorResponse 

type SimulatorResponse struct {
	Body       string            `json:"body"`
	Encoding   string            `json:"encoding,omitempty"`
	Headers    map[string]string `json:"headers"`
	Status     int               `json:"status"`
	StatusCode int               `json:"statusCode,omitempty"`
}

SimulatorResponse is the simulator API response payload.

func (*SimulatorResponse) EffectiveStatus 

func (r *SimulatorResponse) EffectiveStatus() int

EffectiveStatus resolves alternate status field names.

type Site 

type Site struct {
	ID          string     `json:"id"`
	Subdomain   string     `json:"subdomain"`
	Name        string     `json:"name"`
	Domain      string     `json:"domain,omitempty"`
	Description string     `json:"description,omitempty"`
	Locales     []string   `json:"locales,omitempty"`
	Timezone    string     `json:"timezone,omitempty"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
}

Site represents a Nimbu site.

type Theme 

type Theme struct {
	ID           string     `json:"id"`
	Name         string     `json:"name"`
	Short        string     `json:"short,omitempty"`
	CDNBasePath  string     `json:"cdn_base_path,omitempty"`
	CDNHost      string     `json:"cdn_host,omitempty"`
	CDNRoot      string     `json:"cdn_root,omitempty"`
	SiteID       string     `json:"site_id,omitempty"`
	SiteShortID  string     `json:"site_short_id,omitempty"`
	ThemeShortID string     `json:"theme_short_id,omitempty"`
	Active       bool       `json:"active,omitempty"`
	CreatedAt    *time.Time `json:"created_at,omitempty"`
	UpdatedAt    *time.Time `json:"updated_at,omitempty"`
}

Theme represents a theme.

type ThemeFile 

type ThemeFile struct {
	Path      string     `json:"path"`
	Type      string     `json:"type,omitempty"`
	Size      int64      `json:"size,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

ThemeFile represents a theme file.

type ThemeResource 

type ThemeResource struct {
	ID          string     `json:"id"`
	URL         string     `json:"url"`
	Permalink   string     `json:"permalink"`
	Name        string     `json:"name"`
	Path        string     `json:"path"`
	Folder      string     `json:"folder"`
	PublicURL   string     `json:"public_url"`
	Code        string     `json:"code"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
	ChangedLive bool       `json:"changed_live,omitempty"`
}

ThemeResource represents a theme layout/template/snippet/asset entry.

type Token 

type Token struct {
	ID        string     `json:"id"`
	Name      string     `json:"name,omitempty"`
	Token     string     `json:"token,omitempty"`
	Scopes    []string   `json:"scopes,omitempty"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
}

Token represents an API token.

type TokenSource added in v0.4.0 

type TokenSource interface {
	// Token returns a token to send, renewing it first when it is about to expire.
	Token(ctx context.Context) (string, error)
	// Renew replaces a token the API rejected with 401 and returns the new one.
	Renew(ctx context.Context, rejected string) (string, error)
	// MaybeExpired reports whether a 401 for token may mean it expired. Only
	// then is it renewed and the request replayed: other 401s (a customer
	// login's wrong password) must not be sent twice.
	MaybeExpired(token string) bool
}

TokenSource supplies bearer tokens that expire and can be renewed, such as an OAuth session. Implementations must be safe for concurrent use.

type Translation 

type Translation struct {
	Key    string            `json:"key"`
	Value  string            `json:"value,omitempty"`
	Locale string            `json:"locale,omitempty"`
	Values map[string]string `json:"values,omitempty"`
}

Translation represents a translation entry.

type Upload 

type Upload struct {
	ID        string     `json:"id"`
	Name      string     `json:"name"`
	URL       string     `json:"url,omitempty"`
	Size      int64      `json:"size,omitempty"`
	MimeType  string     `json:"mime_type,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Upload represents an uploaded file.

func (*Upload) UnmarshalJSON 

func (u *Upload) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes upload metadata from nested source payloads.

type User 

type User struct {
	ID        string     `json:"id"`
	Email     string     `json:"email"`
	Name      string     `json:"name"`
	Admin     bool       `json:"admin,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

User represents the current user.

type ValidationError 

type ValidationError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
	Code    string `json:"code,omitempty"`
}

ValidationError represents a field-level validation error.

type Webhook 

type Webhook struct {
	ID        string     `json:"id"`
	URL       string     `json:"url"`
	TargetURL string     `json:"target_url,omitempty"`
	Events    []string   `json:"events,omitempty"`
	Active    bool       `json:"active,omitempty"`
	Secret    string     `json:"secret,omitempty"`
	CreatedAt *time.Time `json:"created_at,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

Webhook represents a webhook.

func (*Webhook) UnmarshalJSON 

func (w *Webhook) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes webhook target_url to URL for CLI output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.