client

type APIError struct {
	// Status is the HTTP status code.
	Status int
	// Errors is the decoded envelope. It is empty when the body was not one — a
	// proxy's HTML 502, say.
	Errors []api.ErrorInner
	// Body is the raw response, kept only when it could not be decoded, so that
	// the user is told *something* rather than "HTTP 502".
	Body string
}

type AllOption func(*allOptions)

type Client struct {
	// contains filtered or unexported fields
}

type Doer func(ctx context.Context) (*http.Response, error)

type FacilitySearchPayload = SearchPayload[api.FacilitySearchQuery, api.FacilitySort]

type GetFn[T any] func(ctx context.Context) (entity T, version int, err error)

type ListingSearchPayload = SearchPayload[api.ListingSearchQuery, api.ListingSort]

type Op[T any] struct {
	// Name names the operation in errors ("search the facilities").
	Name string

	// Items is the response field holding the entities: "facilities", "stocks",
	// "listings". It is the one part of the response shape that is not uniform.
	Items string

	// Do issues one page.
	Do func(ctx context.Context, raw api.ClientInterface, body []byte) (*http.Response, error)
}

type Option func(*options)

type Page[T any] struct {
	// Items are the entities on this page.
	Items []T

	// PageInfo carries the cursor to the next page, and whether there is one.
	PageInfo api.PageInfo

	// Total is the number of matches — *absent* unless the search asked for it with
	// options.withTotal. A pointer, because "the API did not count" and "the API
	// counted zero" are different answers and a command that renders `Total: 0` for
	// the first one is lying.
	Total *int
}

type PutFn[T any] func(ctx context.Context, entity T, version int) (T, error)

type QueryParam struct {
	// Name is the parameter's name as the API spells it.
	Name string

	// Values are the values to send. One for a scalar; any number for an array.
	Values []string

	// Explode chooses the encoding, and it must come from the *parameter's* own
	// `explode` in the spec — never from a policy applied to all of them.
	//
	//	true  repeats the name:     status=OPEN&status=CLOSED
	//	false joins with a comma:   status=OPEN%2CCLOSED
	//
	// The comma really does go over the wire percent-encoded: the values become one
	// string, and url.Values.Encode escapes the separator along with everything else.
	// It is what oapi-codegen's runtime already sends for the five tags it covers, and
	// it was confirmed against the live tenant on 2026-07-13 — getStockSummaries
	// filtered by facilityStatus=ONLINE%2COFFLINE answers 384,279 of 383,484 rows,
	// which is the union of the two statuses and emphatically not the zero an
	// unrecognised filter would have returned.
	//
	// The API does not reject the wrong *choice*, though, and that is the danger. It
	// answers 200 and filters on something else — a comma-joined value sent to an
	// exploded parameter is matched as the literal string "ONLINE,OFFLINE", which no
	// row has, and the user is told there are none. 17 of the spec's 77 array query
	// parameters want the joined form and 60 want the repeated one, which is why this
	// is a field and not a constant.
	Explode bool
}

type RawRequest struct {
	// Method is the HTTP method, upper-case.
	Method string

	// Path is the path template, placeholders and all: /api/pickjobs/{pickJobId}.
	// [RawRequest.URL] fills them from PathParams, so that the escaping happens in
	// one place instead of at every call site.
	Path string

	// PathParams fills the template's placeholders.
	PathParams map[string]string

	// Query is the query string, each parameter carrying its own encoding.
	Query []QueryParam

	// Header adds request headers. Content-Type, Accept and Authorization are set by
	// the client and should not be given here.
	Header map[string]string

	// Body is the request body, or nil for none.
	Body []byte
}

type Result struct {
	Status int
	Header http.Header
	Body   []byte
}

type Retry struct {
	// MaxAttempts is how many requests may be sent in total, the first included.
	MaxAttempts int

	// Base is the first backoff interval; it doubles from there.
	Base time.Duration

	// Max caps one backoff interval.
	Max time.Duration

	// MaxWait is the longest Retry-After fft will honour. A rate limit measured in
	// minutes is not something a CLI should sit and wait out — it is something the
	// user should be told about.
	MaxWait time.Duration

	// Sleep waits, or returns the context's error if the wait is cancelled. It is a
	// seam: nil means a real sleep, and specs replace it so that a spec exercising
	// a Retry-After of one second does not take one second.
	Sleep func(ctx context.Context, d time.Duration) error
}

type SearchPayload[Q, S any] struct {
	// Query is the entity's filter. Its zero value marshals to {}, which the API
	// accepts and reads as "everything" — confirmed against the live tenant.
	Query Q `json:"query"`

	// After is the cursor from the previous page's pageInfo.endCursor. [SearchAll]
	// drives it; a caller paging by hand sets it.
	After *string `json:"after,omitempty"`

	// Size is how many items to return: 1–250, 20 if absent.
	Size *int `json:"size,omitempty"`

	// Sort holds *exactly one* element, or is nil. The API's schema says
	// minItems: 1, maxItems: 1, and an empty array comes back as an opaque 400 —
	// so an empty (but non-nil) Sort is refused here, before the request is sent.
	Sort []S `json:"sort,omitempty"`

	// Options asks for the total. Without withTotal:true the response has no
	// `total` field at all — which is why [Page.Total] is a pointer.
	Options *api.SearchOptions `json:"options,omitempty"`
}

type StockSearchPayload = SearchPayload[api.StockSearchQuery, api.StockSort]

type TruncatedError struct {
	MaxItems int
	Op       string
}