api

type API struct {
	Router        *chi.Mux
	Config        *APIConfig
	VersionRouter *VersionRouter
	RateLimiter   RateLimiter
	// contains filtered or unexported fields
}

type APIConfig struct {
	Version         string
	RateLimitPerMin int
	EnableCORS      bool
	AllowedOrigins  []string
	EnableMetrics   bool
	Debug           bool
}

type Components struct {
	Schemas map[string]*Schema `json:"schemas,omitempty"`
}

type DocInfo struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

type Document struct {
	OpenAPI string   `json:"openapi"`
	Info    DocInfo  `json:"info"`
	Servers []Server `json:"servers,omitempty"`

	// Paths maps a path template to its operations. A map, so encoding/json
	// sorts the keys and the document is byte-identical between runs -- which
	// is what makes it reviewable in a diff.
	Paths map[string]map[string]*Operation `json:"paths"`

	Components Components `json:"components,omitempty"`
}

type Envelope[T any] struct {
	Success   bool       `json:"success"`
	Data      T          `json:"data,omitempty"`
	Error     *ErrorInfo `json:"error,omitempty"`
	Meta      *Meta      `json:"meta,omitempty"`
	Timestamp int64      `json:"timestamp"`
}

type ErrorInfo struct {
	Code    string                 `json:"code" xml:"code"`
	Message string                 `json:"message" xml:"message"`
	Details map[string]interface{} `json:"details,omitempty" xml:"details,omitempty"`
}

type ErrorResponse struct {
	Success   bool       `json:"success"`
	Error     *ErrorInfo `json:"error,omitempty"`
	Meta      *Meta      `json:"meta,omitempty"`
	Timestamp int64      `json:"timestamp"`
}

type Info struct {
	Title       string
	Version     string
	Description string

	// Servers are the base URLs the paths are relative to.
	Servers []string
}

type MediaType struct {
	Schema *Schema `json:"schema,omitempty"`
}

type Meta struct {
	Page       int    `json:"page,omitempty" xml:"page,omitempty"`
	PerPage    int    `json:"per_page,omitempty" xml:"per_page,omitempty"`
	Total      int    `json:"total,omitempty" xml:"total,omitempty"`
	TotalPages int    `json:"total_pages,omitempty" xml:"total_pages,omitempty"`
	Version    string `json:"version,omitempty" xml:"version,omitempty"`
	RequestID  string `json:"request_id,omitempty" xml:"request_id,omitempty"`
}

type Op struct {
	Summary     string
	Description string
	Tags        []string

	// OperationID is what client generators name the method. Left empty it is
	// derived from the method and pattern, which is stable as long as the route
	// is -- set it explicitly if a generated client's method names matter more
	// than the URL structure.
	OperationID string

	// Request is a zero value of the type the request body decodes into, or
	// nil for an operation with no body.
	Request any

	// Response is a zero value of what is written on success -- what is
	// actually on the wire, not the payload inside it.
	//
	// Handlers that answer through JSON get the standard envelope, so this is
	// usually Envelope[T] rather than T:
	//
	//	Response: api.Envelope[Invoice]{}       // api.JSON(w, 200, invoice)
	//	Response: api.Envelope[[]Invoice]{}     // a list
	//	Response: Invoice{}                     // api.RawJSON(w, 200, invoice)
	//
	// Declaring T where the handler writes Envelope[T] describes a body nobody
	// sends, so CheckResponse fails on it.
	Response any

	// Status is the success status code. Zero means 200, or 204 when there is
	// no response body.
	Status int

	// Params are the query and header parameters. Path parameters are read off
	// the route pattern, because the spec requires every path template
	// variable to be declared and declaring them by hand only creates the
	// chance to disagree with the URL.
	Params []Parameter

	// Errors are the other status codes this operation returns. They are
	// described with the error envelope this package writes.
	Errors []int

	Deprecated bool
}

type Operation struct {
	OperationID string   `json:"operationId"`
	Summary     string   `json:"summary,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Deprecated  bool     `json:"deprecated,omitempty"`

	Parameters  []Parameter           `json:"parameters,omitempty"`
	RequestBody *RequestBody          `json:"requestBody,omitempty"`
	Responses   map[string]*Response3 `json:"responses"`
}

type Parameter struct {
	Name string `json:"name"`

	// In is "query" or "header". Empty means "query"; path parameters are
	// derived from the route pattern rather than declared.
	In string `json:"in"`

	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`

	// Type is a zero value whose type gives the schema. Nil means string.
	// Not serialised: Schema is what the document carries.
	Type any `json:"-"`

	Schema  *Schema `json:"schema,omitempty"`
	Example any     `json:"example,omitempty"`
}

type RateLimitInfo struct {
	Limit      int
	Remaining  int
	Reset      time.Time
	RetryAfter int // seconds
}

type RateLimiter interface {
	Allow(key string) (bool, *RateLimitInfo)
	Reset(key string)
}

type RequestBody struct {
	Required bool                 `json:"required,omitempty"`
	Content  map[string]MediaType `json:"content"`
}

type ResourceController interface {
	List(w http.ResponseWriter, r *http.Request)
	Create(w http.ResponseWriter, r *http.Request)
	Get(w http.ResponseWriter, r *http.Request)
	Update(w http.ResponseWriter, r *http.Request)
	Delete(w http.ResponseWriter, r *http.Request)
}

type Response struct {
	Success   bool        `json:"success" xml:"success"`
	Data      interface{} `json:"data,omitempty" xml:"data,omitempty"`
	Error     *ErrorInfo  `json:"error,omitempty" xml:"error,omitempty"`
	Meta      *Meta       `json:"meta,omitempty" xml:"meta,omitempty"`
	Timestamp int64       `json:"timestamp" xml:"timestamp"`
}

type Response3 struct {
	Description string               `json:"description"`
	Content     map[string]MediaType `json:"content,omitempty"`
}

type ResponseOption func(*Response)

type Route struct {
	Method  string
	Pattern string
}

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

type Schema struct {
	Ref string `json:"$ref,omitempty"`

	// Type is a string, or a two-element array for a nullable type.
	Type any `json:"type,omitempty"`

	Format string `json:"format,omitempty"`

	// ContentEncoding is how 3.1 says "these bytes are base64", replacing
	// 3.0's `format: byte`.
	ContentEncoding string `json:"contentEncoding,omitempty"`

	Description string `json:"description,omitempty"`

	Items      *Schema            `json:"items,omitempty"`
	Properties map[string]*Schema `json:"properties,omitempty"`
	Required   []string           `json:"required,omitempty"`

	AdditionalProperties *Schema `json:"additionalProperties,omitempty"`

	Enum    []any `json:"enum,omitempty"`
	Example any   `json:"example,omitempty"`
}

type Server struct {
	URL string `json:"url"`
}

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

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

type ValidationError struct {
	Field   string `json:"field" xml:"field"`
	Message string `json:"message" xml:"message"`
	Value   string `json:"value,omitempty" xml:"value,omitempty"`
}

type VersionConfig struct {
	DefaultVersion    string
	SupportedVersions []string
	VersionHeader     string
	VersionInPath     bool
	VersionInQuery    bool
	Deprecated        map[string]string // Maps deprecated versions to sunset dates
}

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

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