Documentation
¶
Overview ¶
Package client is a thin JSON:API client for catalog-api, typed against catalog-objects.go value objects. It covers list/get/create/patch/delete for every entity type plus the /search endpoints used for name resolution.
Index ¶
- Constants
- Variables
- func ContentTypeForFilename(name string) (string, error)
- func Create[T any](ctx context.Context, c *Client, plural string, entity *T) (*T, error)
- func CreateVolume(ctx context.Context, c *Client, fields VolumeCreateFields) (*vo.VolumeVO, error)
- func Delete(ctx context.Context, c *Client, plural, id string) error
- func Get[T any](ctx context.Context, c *Client, plural, id string) (*T, error)
- func IsAuthError(err error) bool
- func IsNotFound(err error) bool
- func List[T any](ctx context.Context, c *Client, plural string, opts ListOptions) ([]*T, error)
- func Search[T any](ctx context.Context, c *Client, plural, q string) ([]*T, error)
- type APIError
- type AssetsClient
- type Client
- type EntityType
- type Filter
- type ListOptions
- type TokenSource
- type VolumeCreateFields
- type WriteDisposition
- func Patch[T any](ctx context.Context, c *Client, plural, id string, fields map[string]any) (*T, WriteDisposition, error)
- func SetVolumeCover(ctx context.Context, c *Client, assets *AssetsClient, volumeID string, ...) (*vo.VolumeVO, WriteDisposition, error)
- func SetVolumeSamples(ctx context.Context, c *Client, assets *AssetsClient, volumeID string, ...) (*vo.VolumeVO, WriteDisposition, error)
Constants ¶
const ( AssetKindCover = "cover" AssetKindSample = "sample" )
Asset kinds the CLI writes. These are the live kinds: catalog-api's finalize-session flow promotes staged assets to cover/<volumeID> and sample/<volumeID>-<n>, so uploading straight to the live kind plus a PATCH produces the same end state without an edit session (sessions have no REST API - they are written directly to Redis by catalog-api/catalog-web).
const MediaType = "application/vnd.api+json"
MediaType is the JSON:API content type catalog-api serves.
Variables ¶
var Entities = map[string]EntityType{ "volume": {Name: "volume", Plural: "volumes", Searchable: false}, "publisher": {Name: "publisher", Plural: "publishers", Searchable: true}, "studio": {Name: "studio", Plural: "studios", Searchable: true}, "person": {Name: "person", Plural: "persons", Searchable: true}, "system": {Name: "system", Plural: "systems", Searchable: true}, "license": {Name: "license", Plural: "licenses", Searchable: true}, "review": {Name: "review", Plural: "reviews", Searchable: false}, "contribution": {Name: "contribution", Plural: "contributions", Searchable: false}, }
Entities is the full registry of entity types the CLI can address.
Functions ¶
func ContentTypeForFilename ¶
ContentTypeForFilename maps an image file extension to the MIME type assets-web accepts, or an error naming the supported types.
func Create ¶
Create posts the entity as plain JSON (catalog-api binds VOs directly, not as JSON:API requests) and returns the created record from the JSON:API response document.
func CreateVolume ¶ added in v0.2.0
CreateVolume posts fields to POST /volumes and returns the created, live volume record.
func Get ¶
Get fetches one entity by ID into out (a *vo.X). A 404 yields an *APIError with StatusCode 404 (see IsNotFound).
func IsAuthError ¶
IsAuthError reports whether err indicates missing/insufficient credentials.
func IsNotFound ¶
IsNotFound reports whether err is a 404 from the server.
Types ¶
type APIError ¶
APIError carries a non-2xx response's status and parsed body. Body shapes vary by handler ({error,message}, {message}, or {error}); anything unparseable keeps the raw text in Message so operators see what the server said.
type AssetsClient ¶
type AssetsClient struct {
BaseURL *url.URL
HTTP *http.Client
Tokens TokenSource
}
AssetsClient talks to one assets-web deployment.
func NewAssetsClient ¶
func NewAssetsClient(baseURL string, tokens TokenSource) (*AssetsClient, error)
NewAssetsClient parses baseURL (must be absolute http(s)) and returns an AssetsClient using the default HTTP transport.
func (*AssetsClient) Upload ¶
func (c *AssetsClient) Upload(ctx context.Context, kind, id string, data []byte, contentType string) error
Upload stores data at assets-web's /asset/<kind>/<id>. The wire format is a multipart form with one "file" part carrying the image bytes; the server requires a non-empty filename and an image/png, image/jpeg, or image/webp content type. Success is 201 Created.
type Client ¶
type Client struct {
BaseURL *url.URL
HTTP *http.Client
Tokens TokenSource
}
Client talks to one catalog-api deployment.
type EntityType ¶
EntityType describes one catalog entity's URL shape. Searchable marks types that expose the /search?q= endpoint backing name resolution.
func Lookup ¶
func Lookup(name string) (EntityType, error)
Lookup returns the entity type for a CLI name, erroring on unknown types so typos fail before any network call.
type Filter ¶
Filter is one equality filter: filter[field]=v1,v2 on the wire. catalog-api maps these to Mongo $eq/$in queries.
type ListOptions ¶
ListOptions narrows a list request.
type TokenSource ¶
TokenSource supplies the bearer token per request. Returning an empty string sends no Authorization header.
type VolumeCreateFields ¶ added in v0.2.0
type VolumeCreateFields struct {
Title string `json:"title"`
Description string `json:"description,omitempty"`
Notes string `json:"notes,omitempty"`
Format string `json:"format,omitempty"`
Tags []string `json:"tags,omitempty"`
Properties []modelcore.PropertyVO `json:"properties,omitempty"`
PublisherIDs []string `json:"publisherIds,omitempty"`
}
VolumeCreateFields is the POST /volumes wire body. It is deliberately not vo.VolumeVO: catalog-api's create endpoint (matching PATCH /volumes/:id) takes tags as plain names ([]string), not the {name,value} TagVO shape GET/list responses return - posting a VolumeVO's Tags field as-is 400s with "cannot unmarshal object into ... of type string".
type WriteDisposition ¶
WriteDisposition reports how the server treated a patch: applied live, or recorded as a proposed change awaiting review.
func Patch ¶
func Patch[T any](ctx context.Context, c *Client, plural, id string, fields map[string]any) (*T, WriteDisposition, error)
Patch sends flat field updates ({name: "...", tags: [...]}) and returns the live record plus how the server disposed of the change. When disposition. Submitted is true the live record is nil and Version/State/Message describe the proposed change.
func SetVolumeCover ¶
func SetVolumeCover(ctx context.Context, c *Client, assets *AssetsClient, volumeID string, image []byte, contentType string) (*vo.VolumeVO, WriteDisposition, error)
SetVolumeCover uploads image as the volume's live cover asset (cover/<volumeID> on assets-web) and links it via PATCH. Admins/editors get a live write back; submitters get a submitted change (the server rejects coverAssetId from submitter roles, surfacing that as an *APIError).
func SetVolumeSamples ¶
func SetVolumeSamples(ctx context.Context, c *Client, assets *AssetsClient, volumeID string, samples [][]byte, contentType string) (*vo.VolumeVO, WriteDisposition, error)
SetVolumeSamples uploads each image as sample/<volumeID>-<i> (order preserved) and replaces the volume's sample list in one PATCH. An empty slice clears all samples.
Source Files