items

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Sep 17, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package items provides API operations for Truestamp items.

Index

Constants

View Source
const DefaultLimit = 25

DefaultLimit matches the server's own default for the paginated read.

Variables

View Source
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

func NormalizeTags(in []string) []string

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

func ValidateVisibility(v string) error

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.

func Get added in v0.14.0

func Get(ctx context.Context, apiURL, team, id string) (*Item, error)

Get fetches one item by ULID.

func Update added in v0.14.0

func Update(ctx context.Context, apiURL, team, id string, opts UpdateOptions) (*Item, error)

Update patches an item's mutable attributes.

func (Item) Committed added in v0.14.0

func (i Item) Committed() bool

Committed reports whether a proof can be generated for this item. Proof generation hard-requires the committed state server-side, so this is the difference between `proofs get <id>` working and being refused with no_external_commitments.

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.

func List added in v0.14.0

func List(ctx context.Context, apiURL, team string, opts ListOptions) (*Page, error)

List fetches one page of items, newest first.

type UpdateOptions added in v0.14.0

type UpdateOptions struct {
	Visibility *string
	Tags       *[]string
	TeamID     *string
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL