apierr

type Cause struct {
	Cause      string `json:"cause"`
	Confidence string `json:"confidence"`
	Detail     string `json:"detail,omitempty"`
	Fix        string `json:"fix,omitempty"`
}

type Code string

type Confidence string

type Error struct {
	Code         Code            `json:"code"`
	Exit         int             `json:"exit"`
	Message      string          `json:"message"`
	Hint         string          `json:"hint,omitempty"`
	Retriable    bool            `json:"retriable"`
	Confidence   Confidence      `json:"confidence"`
	Fields       []Field         `json:"fields"`
	Failures     []Failure       `json:"failures,omitempty"`
	LikelyCauses []Cause         `json:"likely_causes,omitempty"`
	DidYouMean   []string        `json:"did_you_mean"`
	Docs         string          `json:"docs,omitempty"`
	HTTP         *HTTP           `json:"http,omitempty"`
	Raw          json.RawMessage `json:"raw,omitempty"`

	// RawRedactedPaths is non-empty when redaction modified Raw. The CLI turns
	// it into the warnings[] entry {"code":"raw_redacted","paths":[…]} so the
	// agent knows the bytes differ from the wire (§11.1).
	RawRedactedPaths []string `json:"-"`
	// contains filtered or unexported fields
}

type Failure struct {
	ID      any     `json:"id"`
	Code    Code    `json:"code"`
	Message string  `json:"message"`
	Fields  []Field `json:"fields"`
}

type Field struct {
	Path    string `json:"path"`
	Label   string `json:"label,omitempty"`
	Message string `json:"message"`
	// Sent is true iff Path is a leaf of the request body PayCLI actually sent.
	// It exists because Payload validates the WHOLE document on PATCH and
	// therefore reports fields the caller never touched.
	Sent bool `json:"sent"`
}

type HTTP struct {
	Status int    `json:"status"`
	Method string `json:"method"`
	URL    string `json:"url"`
	// PayloadErrorName is errors[0].name verbatim — the signal the normaliser
	// classified on, exposed so an agent can audit the decision.
	PayloadErrorName string `json:"payload_error_name,omitempty"`
	Attempts         int    `json:"attempts"`
	RetryAfter       string `json:"retry_after,omitempty"`
	// BodyExcerpt is at most excerptLimit characters of a non-JSON body.
	BodyExcerpt string `json:"body_excerpt,omitempty"`
}

type Relationship struct {
	Path       string // request-body leaf path, e.g. "heroImage"
	Collection string // the relationTo target slug
	ID         any    // the id that was sent
}

type Response struct {
	Status      int
	Method      string
	URL         string
	ContentType string
	Body        []byte
	Attempts    int
	RetryAfter  string

	// AuthMode and IdentityVerified drive the 403 split. The server cannot make
	// this call for us: a 403 body is byte-identical whether the caller is
	// unauthenticated or merely unpermitted (verified), and its message is
	// translated on top of that.
	AuthMode         string
	IdentityVerified bool

	// UploadCollection is the target collection's flags.upload. A 400 against an
	// upload collection with no errors[0].name is file_missing — a structural,
	// language-independent signal (the English "No files were uploaded." is
	// only a confirming signal that raises confidence).
	UploadCollection bool

	// Collection is the target slug, used in messages only.
	Collection string

	// SentPaths is the leaf-path set of the request body PayCLI actually sent,
	// which decides Field.Sent and therefore which validation hint is used.
	SentPaths map[string]bool

	// IncludeRaw is false for --no-raw; NoRedact is true for --no-redact.
	IncludeRaw bool
	NoRedact   bool
}