Documentation
¶
Overview ¶
Package items provides API operations for Truestamp items.
Index ¶
Constants ¶
const DefaultLimit = 25
DefaultLimit matches the server's own default for the paginated read.
Variables ¶
var Visibilities = []string{"private", "team", "public"}
Visibilities is the closed set the server accepts for an item's visibility. It is declared once so `items create` and `items update` validate and describe the same three values.
Functions ¶
func NormalizeTags ¶ added in v0.14.0
NormalizeTags trims whitespace and drops empty entries, so "a, b,," from a flag becomes ["a" "b"] whichever command received it.
func ValidateVisibility ¶ added in v0.14.0
ValidateVisibility rejects a value outside Visibilities. The empty string is accepted: it means "not supplied".
Types ¶
type CreateItemResponse ¶
type CreateItemResponse struct {
ID string
State string
ClaimsHash string
ItemHash string
Visibility string
Tags []string
TeamID string
Name string
Hash string
HashType string
}
CreateItemResponse holds the parsed JSON:API response for a created item.
func CreateItem ¶
func CreateItem(apiURL, team string, claims map[string]any, visibility string, tags []string) (*CreateItemResponse, error)
CreateItem calls CreateItemCtx with context.Background.
func CreateItemCtx ¶ added in v0.3.0
func CreateItemCtx(ctx context.Context, apiURL, team string, claims map[string]any, visibility string, tags []string) (*CreateItemResponse, error)
CreateItemCtx sends a JSON:API POST request to create a new item. claims is the nested claims map (hash, hash_type, name, etc.); visibility and tags are top-level item attributes. ctx cancels the in-flight request. The credential is applied by the process-wide [auth.Authorizer].
type Item ¶ added in v0.14.0
type Item struct {
ID string `json:"id"`
State string `json:"state"`
Claims map[string]any `json:"claims,omitempty"`
ClaimsHash string `json:"claims_hash,omitempty"`
ItemHash string `json:"item_hash,omitempty"`
Visibility string `json:"visibility,omitempty"`
Tags []string `json:"tags,omitempty"`
TeamID string `json:"team_id,omitempty"`
DisplayName string `json:"display_name,omitempty"`
InsertedAt string `json:"inserted_at,omitempty"`
UpdatedAt string `json:"updated_at,omitempty"`
ExpiresAt string `json:"expires_at,omitempty"`
}
Item is the subset of an item's attributes the CLI reads back.
Three of these fields — InsertedAt, UpdatedAt, ExpiresAt — are NOT in the resource's json_api default_fields, so every request that wants them must ask for them explicitly via fields[item]. See requestFields.
type ListOptions ¶ added in v0.14.0
type ListOptions struct {
Limit int
// After is a keyset cursor from a previous Page.NextCursor; Before is
// one from Page.PrevCursor. At most one is set.
After string
Before string
// OldestFirst walks from the beginning instead of the newest item.
OldestFirst bool
// Count asks the server for the total, reported as Page.Total.
Count bool
// Committed and Pending filter on commitment state. Both false means
// no filter; both true is rejected by the caller.
Committed bool
Pending bool
}
ListOptions configures a list request.
type Page ¶ added in v0.14.0
type Page struct {
Items []Item
// NextCursor is empty when there are no more pages; PrevCursor is
// empty on the first.
NextCursor string
PrevCursor string
// Total is the server's count of matching items, only when asked for.
Total int
// Limit is the page size the server actually used (it clamps to its
// max_page_size rather than refusing).
Limit int
}
Page is one page of a list response plus the cursor for the next.
type UpdateOptions ¶ added in v0.14.0
UpdateOptions carries the mutable attributes.
The server's :update action is `accept [:team_id, :visibility, :tags]`, described there as "considered mutable and not included in the item's hash". name and description live inside claims and are immutable, so there is deliberately no way to reach a signed field from here.
func (UpdateOptions) Empty ¶ added in v0.14.0
func (o UpdateOptions) Empty() bool
Empty reports whether the caller asked for no change at all.