spec

type APIInfo struct {
	Title       string
	Summary     string
	Description string
	Version     string
}

type APISpec struct {
	// ContentType is the MIME type the spec was fetched with.
	ContentType string
	// Raw is the original spec bytes (JSON or YAML).
	Raw []byte
	// Document is the libopenapi parsed representation.
	Document libopenapi.Document
	// SourceURL/LocalPath capture where the spec came from so external refs can
	// be resolved consistently when the raw spec is cached and reparsed.
	SourceURL        string
	LocalPath        string
	AllowCrossOrigin bool
	// contains filtered or unexported fields
}

type CredentialAlternative []CredentialRequirement

type CredentialRequirement struct {
	ID       string   // stable local ID, usually the OpenAPI security scheme name
	Ref      string   // canonical source ref or URI
	Kind     string   // oauth2, api-key, http-basic, http-bearer, openid, mtls, unknown
	Needs    []string // scopes, roles, or other requirement values
	In       string   // api-key location, e.g. query, header, cookie
	Name     string   // api-key parameter/header/cookie name
	Source   string   // loader identity, e.g. openapi
	External bool     // true when the source used a URI-style reference
	// Undeclared is true when OpenAPI security references an ID that is absent
	// from components.securitySchemes.
	Undeclared bool
	// Deprecated is true when the source security scheme is marked deprecated.
	Deprecated bool
}

type DiscoverConfig struct {
	// APIName is the registered short name (used as the cache key).
	APIName string
	// BaseURL is the API's root URL.
	BaseURL string
	// SpecURL, if non-empty, is checked before probing other locations.
	// Ignored when SpecFiles is set.
	SpecURL string
	// SpecFiles, when non-empty, is an ordered list of local file paths or
	// URLs to load the spec from. Multiple files are deep-merged in order
	// (later entries win on conflict). Network discovery is skipped entirely.
	SpecFiles []string
	// CacheDir is the directory for CBOR spec cache files.
	CacheDir string
	// OperationBase overrides operation URL generation and is included in the
	// cached operation metadata key.
	OperationBase string
	// ServerVariables supplies explicit OpenAPI server variable values and is
	// included in cached operation metadata keys.
	ServerVariables map[string]string
	// Version is the running restish version; cache entries with a different
	// version are discarded.
	Version string
	// Transport is used for all HTTP fetches.  nil uses http.DefaultTransport.
	Transport http.RoundTripper
	// AllowCrossOrigin permits Link-header-discovered spec URLs on other hosts.
	// When false, only same-host discovered links are followed. Private/local
	// cross-origin targets are still rejected unless the base URL is already in
	// that trust class.
	AllowCrossOrigin bool
	// ForceRefresh bypasses any cached entry and rebuilds it from the source.
	ForceRefresh bool
	// Timeout is used when the caller context has no deadline. Zero selects a
	// default based on discovery mode.
	Timeout time.Duration
	// Trace receives verbose discovery progress messages.
	Trace func(format string, args ...any)
	// Warnf receives non-fatal operation extraction warnings.
	Warnf func(format string, args ...any)
}

type LoadError struct {
	Errors []string
}

type LoadOptions struct {
	Context          context.Context
	ContentType      string
	SourceURL        string
	LocalPath        string
	AllowCrossOrigin bool
	Transport        http.RoundTripper
	Trace            func(format string, args ...any)
}

type Loader interface {
	// Detect returns true if this loader recognises the content type and/or body.
	Detect(contentType string, body []byte) bool
	// LoadWithOptions parses body and returns a structured APISpec.
	LoadWithOptions(body []byte, opts LoadOptions) (*APISpec, error)
	// Priority determines loader selection order; higher priority wins.
	Priority() int
}

type MethodOp struct {
	Method string
	Op     *v3.Operation
}

type OpenAPILoader struct{}

type Operation struct {
	// ID is the operationId, or a kebab-case fallback when absent.
	ID     string
	Method string
	// Path is the full path template after applying any server base prefix.
	Path string
	// OperationServer is an absolute server URL from an operation/path-level
	// OpenAPI server whose origin differs from the configured API base URL.
	OperationServer string
	Summary         string
	Description     string
	Deprecated      bool
	Tags            []string
	Parameters      []Param
	// HasBody is true when the operation has a requestBody.
	HasBody bool
	// BodyRequired is true when requestBody.required is true.
	BodyRequired bool
	// NoAuth is true when the operation explicitly declares security: [].
	NoAuth bool
	// OptionalAuth is true when an operation allows anonymous calls alongside
	// one or more credential alternatives.
	OptionalAuth bool
	// CredentialAlternatives is the OR-list of AND credential requirements
	// derived from the effective OpenAPI security requirement.
	CredentialAlternatives []CredentialAlternative
	// MCPIgnore is true when x-mcp-ignore is set.
	MCPIgnore bool
	// RequestMediaType is the deterministic preferred content type from
	// requestBody.content, if the operation accepts a body.
	RequestMediaType string
	// ResponseMediaType is the deterministic preferred Accept value from
	// successful response content, if the operation declares one.
	ResponseMediaType string
	// ResponseMediaTypes are all declared successful response content types in
	// deterministic response-code and spec declaration order.
	ResponseMediaTypes []string
	// RequestMultipartContentTypes maps multipart/form-data property names to
	// per-part Content-Type values from the OpenAPI encoding object.
	RequestMultipartContentTypes map[string]string
	XCLI                         OperationXCLI
	Help                         OperationHelp
}

type OperationBodyHelp struct {
	MediaType         string
	Schema            string
	JSONSchema        map[string]any
	JSONSchemaDialect string
	Example           string
	RawBinary         bool
}

type OperationCacheStatus struct {
	FetchedAt time.Time
	ExpiresAt time.Time
	Stale     bool
}

type OperationHelp struct {
	Request   *OperationBodyHelp
	Requests  []OperationBodyHelp
	Responses []OperationResponseHelp
	Examples  []string
}

type OperationOptions struct {
	BaseURL         string
	OperationBase   string
	ServerVariables map[string]string
	Warnf           func(format string, args ...any)
}

type OperationResponseHelp struct {
	Codes       []string
	MediaType   string
	Headers     []string
	Schema      string
	Example     string
	NoBody      bool
	Description string
}

type OperationSet struct {
	Info           APIInfo
	Operations     []Operation
	Warnings       []string
	XCLIExtensions XCLIExtensionReport
}

type OperationXCLI struct {
	Ignore      bool
	Hidden      bool
	Name        string
	Description string
	Aliases     []string
}

type Param struct {
	Name              string
	In                string // "path", "query", "header", "cookie"
	Desc              string
	Schema            string
	JSONSchema        map[string]any
	JSONSchemaDialect string
	Required          bool
	Type              string
	ItemType          string
	Default           string
	DefaultValues     []string
	HasDefault        bool
	Style             string
	Explode           *bool
	AllowReserved     bool
	ContentMediaType  string
	Enum              []string
	ObjectProperties  []ParamObjectProperty
	XCLI              ParamXCLI
}

type ParamObjectProperty struct {
	Name string
	Type string
	Desc string
	Enum []string
}

type ParamXCLI struct {
	Ignore bool
	Hidden bool
	// Name overrides the kebab-case parameter name used for the flag.
	Name string
	// Description overrides the OpenAPI parameter description.
	Description string
}

type PluginLoader struct {
	PluginPath   string
	PluginName   string
	ContentTypes []string
}

type SecuritySchemeSummary struct {
	ID            string
	Kind          string
	Detail        string
	Supported     bool
	GlobalDefault bool
	Deprecated    bool
}

type XCLIAuth struct {
	// Type is the restish auth type (e.g. "bearer", "http-basic").
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
	// Params holds auth parameters; secret values should be empty strings.
	Params map[string]string `json:"params,omitempty" yaml:"params,omitempty"`
}

type XCLIConfig struct {
	// Profiles maps profile names to their pre-populated settings.
	Profiles map[string]*XCLIProfile `json:"profiles,omitempty" yaml:"profiles,omitempty"`

	// Legacy v1 shape. These fields are normalized into Profiles["default"]
	// during API configuration so specs already in the wild keep working.
	Security string                   `json:"security,omitempty" yaml:"security,omitempty"`
	Headers  map[string]string        `json:"headers,omitempty" yaml:"headers,omitempty"`
	Prompt   map[string]XCLIPromptVar `json:"prompt,omitempty" yaml:"prompt,omitempty"`
	Params   map[string]string        `json:"params,omitempty" yaml:"params,omitempty"`
}

type XCLICredential struct {
	Auth      *XCLIAuth                `json:"auth,omitempty" yaml:"auth,omitempty"`
	AuthRef   string                   `json:"auth_ref,omitempty" yaml:"auth_ref,omitempty"`
	Satisfies []string                 `json:"satisfies,omitempty" yaml:"satisfies,omitempty"`
	Prompt    map[string]XCLIPromptVar `json:"prompt,omitempty" yaml:"prompt,omitempty"`
	Params    map[string]string        `json:"params,omitempty" yaml:"params,omitempty"`

	PromptValues   map[string]string `json:"-" yaml:"-"`
	PromptedParams map[string]bool   `json:"-" yaml:"-"`
}

type XCLIExtensionDetail struct {
	Kind      string `json:"kind" cbor:"kind"`
	Extension string `json:"extension" cbor:"extension"`
	Location  string `json:"location" cbor:"location"`
	Name      string `json:"name,omitempty" cbor:"name,omitempty"`
	Value     string `json:"value,omitempty" cbor:"value,omitempty"`
	Effect    string `json:"effect" cbor:"effect"`
}

type XCLIExtensionReport struct {
	Details []XCLIExtensionDetail `json:"details,omitempty" cbor:"details,omitempty"`
}

type XCLIProfile struct {
	Headers     []string                   `json:"headers,omitempty" yaml:"headers,omitempty"`
	Query       []string                   `json:"query,omitempty" yaml:"query,omitempty"`
	Auth        *XCLIAuth                  `json:"auth,omitempty" yaml:"auth,omitempty"`
	Credentials map[string]*XCLICredential `json:"credentials,omitempty" yaml:"credentials,omitempty"`

	// Security, when non-empty, is the name of a security scheme in the spec's
	// components/securitySchemes. It is resolved to an Auth type and default
	// Params when applying the config; an explicit Auth field takes precedence.
	Security string `json:"security,omitempty" yaml:"security,omitempty"`

	// Params holds key→value pairs used for {var} template expansion in Headers.
	// Empty-string values indicate a placeholder that the operator should fill in.
	Params map[string]string `json:"params,omitempty" yaml:"params,omitempty"`

	// Prompt describes configuration-time questions. Prompted values are written
	// into Params before Resolve runs; prompts are never evaluated at request time.
	Prompt map[string]XCLIPromptVar `json:"prompt,omitempty" yaml:"prompt,omitempty"`

	// PromptValues holds configure-time prompt answers, including excluded
	// answers that are only available for template expansion.
	PromptValues map[string]string `json:"-" yaml:"-"`
	// PromptedParams marks Params entries that came directly from prompt input.
	// Prompt answers are literal values and are not expanded a second time.
	PromptedParams map[string]bool `json:"-" yaml:"-"`
}

type XCLIPromptVar struct {
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Example     string `json:"example,omitempty" yaml:"example,omitempty"`
	Default     any    `json:"default,omitempty" yaml:"default,omitempty"`
	Enum        []any  `json:"enum,omitempty" yaml:"enum,omitempty"`

	// Exclude keeps the prompted value out of auth params; it can still be used
	// for {var} template expansion in Params, Headers, or explicit Auth params.
	Exclude bool `json:"exclude,omitempty" yaml:"exclude,omitempty"`
}