vaultapi

type AlreadyExistsError struct {
	// Code is the API's error code for the conflict. In practice that is always
	// task_exists: an ambiguous_name envelope becomes ErrAmbiguous before this
	// type is constructed.
	Code string
	// TaskIdentifier is the occupant's identifier, empty when it has none.
	TaskIdentifier string
	// Status is the occupant's normalised status, empty when unreadable.
	Status string
	// What is the operation that produced the conflict, so a create and a
	// re-address do not read identically in a log.
	What string
}

type Client interface {
	// ReadTask returns the task with the given identifier, or ErrNotFound.
	ReadTask(ctx context.Context, id string) (*Task, error)
	// CreateTask creates a task and returns it with the identifier the API
	// minted. ErrAlreadyExists when one is already present — as *AlreadyExistsError,
	// which names the occupant so the caller can decide what to do about it.
	CreateTask(ctx context.Context, task Task, opts CreateOptions) (*Task, error)
	// PatchTask replaces the named frontmatter fields and returns the task as it
	// now stands. It is the atomic mutation: the API serialises per task.
	PatchTask(ctx context.Context, id string, fields map[string]any) (*Task, error)
	// PutBody replaces the task's body. It does not touch frontmatter.
	PutBody(ctx context.Context, id string, body string) error
	// ListTasks returns the tasks matching filter. It refuses rather than returns
	// when the API reports a total the response does not carry, so a caller never
	// mistakes a partial set for the whole population.
	ListTasks(ctx context.Context, filter Filter) ([]Task, error)
	// ReaddressTask moves the task to a new identifier without moving its file.
	// ErrAlreadyExists when the target identifier is already taken — the refusal
	// is mandatory, because silently merging two tasks into one address is the
	// worst outcome available.
	ReaddressTask(ctx context.Context, id string, next string) (*Task, error)
}

type CreateOptions struct {
	// ReopenTerminal asks the API to REPLACE an occupant whose status is
	// terminal. A live occupant is still a conflict — reopening one would let
	// two attempts share an identity.
	ReopenTerminal bool
}

type Filter struct {
	Assignee  string
	Status    string
	Phase     string
	Goal      string
	Cluster   string
	TaskTypes []string
}

type Task struct {
	ID          string         `json:"id"`
	Title       string         `json:"title"`
	Frontmatter map[string]any `json:"frontmatter,omitempty"`
	Body        string         `json:"body,omitempty"`
}