output

type Alternative struct {
	Why string `json:"why"`
	Cmd string `json:"cmd"`
}

type CacheMeta struct {
	Discovery   string `json:"discovery"`
	AgeS        *int64 `json:"age_s"`
	TTLS        *int64 `json:"ttl_s"`
	Fingerprint string `json:"fingerprint,omitempty"`
	Revalidated bool   `json:"revalidated"`
}

type Changed struct {
	Created int   `json:"created"`
	Updated int   `json:"updated"`
	Deleted int   `json:"deleted"`
	Trashed int   `json:"trashed"`
	IDs     []any `json:"ids"`
}

type DataKind string

type EditOp struct {
	// Command is the Cmd* constant of the stage that produced it.
	Command string `json:"command"`
	// Field is the document field it edited.
	Field string `json:"field"`
	// Detail is one human-readable sentence: "moved id:a1 (cta) from 0 to 2".
	Detail string `json:"detail"`
	// Matched are the source indices the selector resolved to, recorded
	// because the indices shift under the next stage and this is the only
	// record of what the caller actually addressed.
	Matched []int `json:"matched,omitempty"`
	// Rows is the row count after the op, so a listing is not needed to see
	// that a remove removed something.
	Rows int `json:"rows"`
}

type Edits struct {
	// Fields are the document's top-level field paths the pipeline changed, in
	// first-touched order and deduplicated. `apply` builds its PATCH body from
	// exactly these.
	Fields []string `json:"fields"`
	// Ops is every transform applied, oldest first, so the envelope explains
	// itself after four stages of a pipe.
	Ops []EditOp `json:"ops"`
}

type Envelope struct {
	OK       bool          `json:"ok"`
	V        int           `json:"v"`
	Command  string        `json:"command"`
	DataKind DataKind      `json:"data_kind"`
	Partial  bool          `json:"partial,omitempty"`
	Target   *Target       `json:"target,omitempty"`
	Data     any           `json:"data,omitempty"`
	Changed  *Changed      `json:"changed,omitempty"`
	Edits    *Edits        `json:"edits,omitempty"`
	Page     *Page         `json:"page,omitempty"`
	Error    *apierr.Error `json:"error,omitempty"`
	Next     *Next         `json:"next,omitempty"`
	Meta     Meta          `json:"meta"`
	Warnings []Warning     `json:"warnings"`

	// RawBody is the server's response body for `--output raw`. It never
	// appears in the JSON envelope; the writer emits it instead of the
	// envelope. It is stored already redacted, with RawRedacted recording
	// whether redaction changed the bytes so the writer can print the
	// "--no-redact" notice on stderr (§10.3).
	RawBody     []byte `json:"-"`
	RawRedacted bool   `json:"-"`
	// contains filtered or unexported fields
}

type ErrorsTo string

type Format string

type Locale struct {
	Requested *string `json:"requested"`
	Fallback  *string `json:"fallback"`
}

type Meta struct {
	RequestID            string  `json:"request_id"`
	CLIVersion           string  `json:"cli_version"`
	Profile              string  `json:"profile"`
	BaseURL              string  `json:"base_url"`
	APIPath              string  `json:"api_path"`
	AuthMode             string  `json:"auth_mode"`
	PayloadVersion       *string `json:"payload_version"`
	PayloadVersionSource string  `json:"payload_version_source"`
	Locale               Locale  `json:"locale"`
	DateField            *string `json:"date_field"`
	// SearchedFields is §9.4's mandatory report for --q: the text fields the
	// OR of `contains` was actually built over. Absent on a command that did
	// not search.
	SearchedFields    []string   `json:"searched_fields,omitempty"`
	Since             *string    `json:"since"`
	Until             *string    `json:"until"`
	DurationMS        int64      `json:"duration_ms"`
	HTTPRequests      int        `json:"http_requests"`
	Retries           int        `json:"retries"`
	Bytes             int64      `json:"bytes"`
	Cache             *CacheMeta `json:"cache,omitempty"`
	DiscoveryRevision string     `json:"discovery_revision,omitempty"`
	DryRun            bool       `json:"dry_run"`
	// Backups lists the §12.8 backup files this invocation wrote before it
	// changed or removed a document. Absent when nothing was backed up —
	// backups are off, or the command changed no existing document.
	Backups []string `json:"backups,omitempty"`
	// RichText records that --richtext md|text rendered the rich text of the
	// data for reading. Absent when rich text is the stored Lexical JSON (the
	// default). Its presence is what `pay apply` and `--data @-` refuse: a
	// rendered document must never be written back.
	RichText *RichTextMeta `json:"richtext,omitempty"`
	// ResetNested reports a --reset-nested write (§10.2.1): the carrier
	// phases sent before the requested body, the block tables they cleared
	// and whether the stored row read back clean. Absent on every other
	// command.
	ResetNested any `json:"reset_nested,omitempty"`
	// Upsert is what `pay upsert` decided (F6): absent on every other command.
	Upsert *UpsertMeta `json:"upsert,omitempty"`
	// RestoredFrom is the backup file `pay backups restore` wrote back
	// (§12.8.8); absent on every other command.
	RestoredFrom string `json:"restored_from,omitempty"`
}

type Next struct {
	Reason       string         `json:"reason"`
	Cmd          string         `json:"cmd"`
	Args         map[string]any `json:"args,omitempty"`
	Alternatives []Alternative  `json:"alternatives,omitempty"`
}

type Page struct {
	Limit       int  `json:"limit"`
	Page        int  `json:"page"`
	TotalPages  int  `json:"total_pages"`
	TotalDocs   int  `json:"total_docs"`
	Returned    int  `json:"returned"`
	HasNextPage bool `json:"has_next_page"`
	HasPrevPage bool `json:"has_prev_page"`
	NextPage    *int `json:"next_page"`
	PrevPage    *int `json:"prev_page"`
	Truncated   bool `json:"truncated"`
}

type Renderer interface {
	Render(env *Envelope) (exitCode int, err error)
}

type RichTextMeta struct {
	// Format is what every editor state was replaced by: "md" or "text".
	Format string `json:"format"`
	// Rendered counts the editor states replaced.
	Rendered int `json:"rendered"`
	// Paths are the replaced values' paths (`content`, `layout[2].richText`,
	// `[0].content` in a list), at most MaxRichTextPaths of them.
	Paths []string `json:"paths"`
	// PathsTruncated reports that Paths was capped.
	PathsTruncated bool `json:"paths_truncated,omitempty"`
}

type Target struct {
	Kind     string `json:"kind"` // "collection" | "global"
	Slug     string `json:"slug"`
	Singular string `json:"singular,omitempty"`
	IDType   string `json:"id_type,omitempty"`
	ID       any    `json:"id,omitempty"`
}

type UpsertMeta struct {
	// Action is created | updated | unchanged after a real run, and the
	// plan vocabulary create | update | unchanged under --dry-run (nothing
	// happened yet).
	Action string `json:"action"`
	// MatchedBy is the --match fields and the values taken from the body.
	MatchedBy map[string]any `json:"matched_by"`
	// ID is the matched (or created) document's id; null for a dry-run create.
	ID any `json:"id"`
	// Forced is true when --force wrote a body that changed nothing.
	Forced bool `json:"forced,omitempty"`
}

type Warning struct {
	Code         string         `json:"code"`
	Message      string         `json:"message"`
	Paths        []string       `json:"paths,omitempty"`
	Sent         map[string]any `json:"sent,omitempty"`
	Returned     map[string]any `json:"returned,omitempty"`
	StillMissing []string       `json:"still_missing,omitempty"`
	Hint         string         `json:"hint,omitempty"`
}

type Writer struct {
	Stdout io.Writer
	Stderr io.Writer

	// Format is --output. Zero value renders as json.
	Format Format
	// ErrorsTo is --errors-to.
	ErrorsTo ErrorsTo
	// Columns overrides the default column selection for csv and table.
	Columns []string
	// Width is the terminal width for table output; 0 uses DefaultWidth.
	Width int
	// Human adds the one-line stderr summary on an error (§11.1). It is on by
	// default; --quiet turns it off.
	Quiet bool
	// NoRedact is --no-redact. The zero value redacts, so a Writer built
	// anywhere (including in a test) can never be the thing that spills a
	// credential (§5.3).
	NoRedact bool
	// StdoutIsData says the command has already written raw bytes to Stdout
	// and owns that stream (today: `pay download -o -`). The envelope is then
	// rendered to Stderr, because appending JSON after a PNG produces a file
	// that is neither: a 463-byte image came out as a 1570-byte hybrid. It is
	// deliberately a writer-level flag rather than a per-command dance, so
	// every future byte-streaming command gets the same protection.
	StdoutIsData bool
}