api

type Envelope[R any] struct {
	Data  []R    `json:"data"`
	Meta  *Meta  `json:"meta,omitempty"`
	Links *Links `json:"links,omitempty"`
}

type IdempotencyOptions struct {
	// Methods guarded (default POST and PATCH).
	Methods []string
	// Required answers 400 when the header is missing.
	Required bool
	// TTL keeps completed responses (default 24h).
	TTL time.Duration
	// LockTTL bounds an in-flight request (default 1 minute).
	LockTTL time.Duration
	// MaxBody bounds the request body that is fingerprinted (default 1 MiB).
	MaxBody int64
	// Scope separates callers so one cannot replay another's response.
	// Default: the authenticated principal (auth.Principal: guard and user
	// id) when an auth middleware ran before Idempotency, else a SHA-256 of
	// the Authorization header. Place Idempotency after auth.Required so
	// a revoked token is refused before any replay. A request with a key
	// whose scope is empty is refused with 400; return a constant to share
	// keys on purpose.
	Scope func(r *http.Request) string
}

type Links struct {
	Self string  `json:"self"`
	Next *string `json:"next"`
	Prev *string `json:"prev"`
}

type Meta struct {
	Page       int    `json:"page,omitempty"`
	PerPage    int    `json:"per_page"`
	Total      *int64 `json:"total,omitempty"`
	LastPage   int    `json:"last_page,omitempty"`
	NextCursor string `json:"next_cursor,omitempty"`
}

type Op struct {
	// Name is the route name (and the OpenAPI operationId).
	Name        string
	Summary     string
	Description string
	Tags        []string
	// Status is the success status; default 201 for POST, 204 when the
	// output type is struct{}, 200 otherwise.
	Status     int
	Deprecated bool
	// Security lists the security schemes the OpenAPI document declares
	// (e.g. "bearer"). It is documentation only and does not authenticate
	// the route: add auth.Required (and auth.Ability) to the route or group.
	Security []string
	// ValidateResponse checks the output against its `validate` tags
	// (z.For[Out]) before writing it, when web.Services.CheckResponses is
	// on: the app sets it whenever APP_ENV is not production, so a staging
	// deployment with APP_ENV=development or test runs the check too. A
	// mismatch is a server bug: it is logged and answered with a generic 500
	// instead of sending data that breaks the documented contract. Out must
	// be a struct; Register panics otherwise.
	ValidateResponse bool
}

type Operation struct {
	Op
	Method string
	Path   string
	Params []string
	In     reflect.Type
	Out    reflect.Type
}

type Option func(*spec)

type Registrar interface {
	Match(methods []string, path string, h web.HandlerFunc) []*router.Route
}

type Request[T any] struct {
	Query    orm.Query[T]
	Page     int
	PerPage  int
	Cursor   string
	Includes []string
}