entity

type ActionFlags interface {
	ClickyActionFlags()
}

type ActionInfo struct {
	Name     string
	Short    string
	Method   string
	DataFunc func(flags map[string]string, args []string) (any, error)
	// ContextDataFunc, when set, is preferred over DataFunc by both the CLI run
	// path (fed cmd.Context()) and the RPC executor (fed r.Context()), mirroring
	// the entity CRUD seam. Lets an action resolve request-scoped state instead
	// of process globals.
	ContextDataFunc ContextDataFunc
	// FlagsType, if non-nil, is the struct type whose `flag:"..."` tagged
	// fields are registered as cobra flags on the generated action command
	// and populated into the flag map passed to DataFunc.
	FlagsType    reflect.Type
	ResponseType reflect.Type
	// OptionalID, when true, makes the positional <id> argument optional on
	// the generated action command — the action is invokable with no
	// argument (and the `id` passed to the run func is empty). Use for
	// actions whose target is supplied entirely through flags.
	OptionalID bool
	// ToolGroup overrides the entity's tool group for this action only. Empty
	// means the action inherits the entity's group.
	ToolGroup string
	ToolHints MCPToolHints
}

type ActionSpec[R any] struct {
	// contains filtered or unexported fields
}

type BulkActionInfo struct {
	Name              string
	Short             string
	DataFunc          func(flags map[string]string, args []string) (any, error)
	FilterFunc        func(flags map[string]string, args []string) (any, error)
	LookupFunc        func(flags map[string]string, args []string) (any, error)
	ContextLookupFunc ContextLookupFunc
	ListType          reflect.Type
	BindCompletions   func(cmd *cobra.Command)
	ResponseType      reflect.Type
}

type BulkActionSpec[R any] struct {
	// contains filtered or unexported fields
}

type ClickyOperationMeta struct {
	SurfaceID          string        `json:"-"`
	Command            string        `json:"command,omitempty"`
	Surface            string        `json:"surface,omitempty"`
	Entity             string        `json:"-"`
	Parent             string        `json:"-"`
	Aliases            []string      `json:"-"`
	Admin              bool          `json:"-"`
	Icon               string        `json:"-"`
	Path               string        `json:"-"`
	Title              string        `json:"-"`
	Verb               string        `json:"verb,omitempty"`
	Scope              string        `json:"scope,omitempty"`
	ActionName         string        `json:"actionName,omitempty"`
	IDParam            string        `json:"idParam,omitempty"`
	SupportsLookup     bool          `json:"supportsLookup,omitempty"`
	SupportsFilterMode bool          `json:"supportsFilterMode,omitempty"`
	Group              string        `json:"group,omitempty"`
	ToolHints          MCPToolHints  `json:"-"`
	OpenAPIToolHints   *MCPToolHints `json:"toolHints,omitempty"`
	Export             *ExportMeta   `json:"export,omitempty"`
	Order              int           `json:"-"`
}

type ClickySpecMeta struct {
	Surfaces []ClickySurface `json:"surfaces,omitempty"`
}

type ClickySurface struct {
	Key         string `json:"key"`
	Entity      string `json:"entity"`
	Title       string `json:"title"`
	Parent      string `json:"parent,omitempty"`
	Admin       bool   `json:"admin,omitempty"`
	Description string `json:"description,omitempty"`
	// Icon is an opaque UI icon name (e.g. "database") the frontend resolves to
	// a glyph. Emitted verbatim from the entity's x-clicky-icon annotation.
	Icon string `json:"icon,omitempty"`
	// Path is this surface's position within its Parent group, always separated
	// by PathSeparator (e.g. "jms/incoming/disbursements"). Producers split
	// their own naming convention with SplitPath before emitting it, so the
	// frontend never guesses a delimiter. Empty — the default for every surface
	// that does not opt in — means the group renders as a flat list.
	Path  string `json:"path,omitempty"`
	Order int    `json:"-"`
}

type CommandOpenAPIMeta struct {
	Entity  string
	Parent  string
	Aliases []string
	Admin   bool
	// Icon is an opaque UI icon name (e.g. "database"); clicky never interprets
	// it — it is emitted verbatim on the surface for the frontend to resolve.
	Icon string
	// Path is the entity's hierarchy position within Parent, PathSeparator-joined.
	Path string
	// Title overrides the auto-generated surface title when non-empty.
	Title              string
	Verb               string
	Method             string
	Scope              string
	ActionName         string
	IDParam            string
	SupportsLookup     bool
	SupportsFilterMode bool
	// OptionalID is true when the operation's positional id is optional
	// (WithOptionalID). Such operations are invocable without an id, so the
	// generated REST path must NOT carry an {id} segment — otherwise the no-id
	// call collides with the entity's get-by-id route.
	OptionalID bool
	// ToolGroup names the group an operation belongs to. It is set on the entity
	// and inherited by every operation (a per-action override may replace it).
	// AI tool-preference layers use it to enable/disable a set of related tools
	// as one unit.
	ToolGroup string
	ToolHints MCPToolHints
}

type Config struct {
	// DefaultMethod is the default HTTP method for operations.
	DefaultMethod string
	// PathPrefix is the path prefix for REST APIs.
	PathPrefix string
	// AutoGeneratePaths controls whether REST paths are generated from the
	// command hierarchy.
	AutoGeneratePaths bool
	// DefaultTags are applied to all operations.
	DefaultTags []string
}

type ContextDataFunc = func(ctx context.Context, flags map[string]string, args []string) (any, error)

type ContextFilter[ListOpts any] interface {
	OptionsWithContext(ctx context.Context, opts ListOpts) map[string]api.Textable
}

type ContextLookupFunc = func(ctx context.Context, flags map[string]string, args []string) (any, error)

type ContextSearchableFilter[ListOpts any] interface {
	OptionsWithQueryAndContext(ctx context.Context, opts ListOpts, query string, limit int) (options map[string]api.Textable, total int)
}

type DataFunc func(flags map[string]string, args []string) (any, error)

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

type DynamicEntityFamily struct {
	// Name is the family's path segment: "profile" serves one route,
	// {prefix}/profile/{name}, for every profile that will ever exist.
	Name string

	// Parent groups the family's surfaces, as EntityInfo.Parent does.
	Parent string

	// Resolve returns the spec for one instance. It runs in front of every
	// request to the family, so it has to be cheap enough to sit there. A name
	// that does not exist is UnknownDynamicEntity rather than a zero spec: "no
	// such profile" and "a profile that does nothing" are different answers and a
	// caller has to be able to tell them apart.
	Resolve func(ctx context.Context, name string) (DynamicEntitySpec, error)

	// List enumerates the instances that exist right now, so the OpenAPI document
	// can describe them. It is called per request for the same reason Resolve is:
	// a document rendered once at startup would describe a set that has since
	// changed.
	List func(ctx context.Context) ([]DynamicEntitySpec, error)

	// Paged serves one page or one export of a resolved instance, putting a
	// family instance on the same export contract as RPCOperation.PagedFunc.
	//
	// It hangs off the family rather than off DynamicEntitySpec because the spec
	// says what the entity is and this says how the transport reads it, and
	// because one implementation serves every instance. Nil falls back to the
	// instance's List, served the way every other operation's data is.
	Paged func(ctx context.Context, spec DynamicEntitySpec, req PageRequest, flags map[string]string) (PageResponse, error)
}

type DynamicEntitySpec struct {
	Name    string
	Parent  string
	Aliases []string
	// Icon is an opaque UI icon name emitted on the surface (x-clicky.surfaces[].icon).
	Icon string
	// Path is the hierarchy position emitted on the surface (x-clicky.surfaces[].path).
	Path string
	// Title overrides the auto-generated surface title when non-empty.
	Title    string
	ListType reflect.Type // generated struct type: flag binding + OpenAPI params
	ItemType reflect.Type // generated item struct type for the response schema
	List     ContextDataFunc
	Get      ContextDataFunc
	Filters  []DynamicFilter
	// FilterRefs maps a filter key to the reusable named filter backing it, so
	// the OpenAPI layer can emit an x-clicky-lookup $ref (see EntityInfo.FilterRefs).
	FilterRefs map[string]string
}

type DynamicFilter struct {
	Key        string
	Label      string
	Type       string
	Multi      bool
	Searchable bool
	// Limit caps the option set this filter enumerates in one shot. Zero takes
	// MaxLookupOptions, which is also the ceiling.
	Limit int
	// Options returns the head set (query == "") or search matches, plus the true
	// total behind the head. Required.
	Options func(ctx context.Context, flags map[string]string, query string, limit int) (map[string]api.Textable, int, error)
	// Selected labels the currently-selected value(s) of this filter's key.
	// Optional; nil means "no selection rendering".
	Selected func(ctx context.Context, flags map[string]string) (map[string]api.Textable, error)
}

type DynamicGetFunc func(ctx context.Context, id string) (map[string]any, error)

type DynamicListFunc func(ctx context.Context, opts map[string]string) ([]map[string]any, error)

type Entity[T EntityItem, ListOpts any, R any] struct {
	Name string
	// Parent, when set, nests the entity's command under a parent cobra command
	// with that name. The parent command is created lazily by GenerateCLI if it
	// does not already exist.
	Parent string
	// Aliases applied to the generated entity cobra command.
	Aliases []string
	// Path is the entity's hierarchy position within Parent, PathSeparator-joined
	// (x-clicky.surfaces[].path). Build it with JoinPath/SplitPath so the
	// separator stays the wire convention. Empty declares no hierarchy.
	Path string
	List func(opts ListOpts) ([]T, error)
	Get  func(id string) (R, error)
	// ListWithContext / GetWithContext / GetWithFlagsAndContext are context-aware
	// variants of List / Get / GetWithFlags. When set they take precedence over
	// their non-context counterparts and receive the request-scoped
	// context.Context (r.Context() over HTTP, cmd.Context() on the CLI). Use them
	// to resolve per-request state (e.g. a database/config bundle) instead of
	// reaching for process globals.
	ListWithContext        func(ctx context.Context, opts ListOpts) ([]T, error)
	ListPaged              func(opts ListOpts) (PagedResult[T], error)
	ListPagedWithContext   func(ctx context.Context, opts ListOpts) (PagedResult[T], error)
	GetWithContext         func(ctx context.Context, id string) (R, error)
	GetWithFlagsAndContext func(ctx context.Context, id string, flags map[string]string) (R, error)
	// GetFlags, when non-nil, is a zero-value struct value implementing
	// ActionFlags whose `flag:"..."` tagged fields are registered as
	// CLI flags on the generated `get` subcommand. The parsed values are
	// passed into GetWithFlags.
	//
	// GetWithFlags is mutually exclusive with Get: when both are set,
	// GetWithFlags wins. Set GetFlags to declare the flag schema and
	// GetWithFlags to receive the typed values.
	GetFlags     ActionFlags
	GetWithFlags func(id string, flags map[string]string) (R, error)
	Create       func(body map[string]any) (R, error)
	Update       func(id string, body map[string]any) (R, error)
	Delete       func(id string) error
	// CreateWithContext / UpdateWithContext / DeleteWithContext are context-aware
	// variants of Create / Update / Delete, mirroring the read-side seam above.
	// When set they take precedence and receive the request-scoped context, so
	// writes target the request's environment rather than a process global.
	CreateWithContext func(ctx context.Context, body map[string]any) (R, error)
	UpdateWithContext func(ctx context.Context, id string, body map[string]any) (R, error)
	DeleteWithContext func(ctx context.Context, id string) error
	Filters           []Filter[ListOpts]

	PrimaryAction EntityAction
	Actions       []EntityAction
	BulkActions   []EntityBulkAction

	// Admin groups admin-only operations (inspect, configure, etc.)
	// that produce different views/columns from the main CRUD operations.
	// Generates subcommands under an "admin" subgroup and routes like /entity/admin/{verb}.
	Admin *Entity[T, ListOpts, R]

	// ValidArgs provides shell completion for the ID argument.
	ValidArgs func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

	// ToolGroup names the group all of this entity's operations belong to. It is
	// inherited by every generated operation; an action may override it via
	// WithToolGroup. AI tool-preference layers use it to toggle related tools
	// together.
	ToolGroup string
	ToolHints MCPToolHints
}

type EntityAction interface {
	// contains filtered or unexported methods
}

type EntityBuilder[T EntityItem, ListOpts any, R any] struct {
	// contains filtered or unexported fields
}

type EntityBulkAction interface {
	// contains filtered or unexported methods
}

type EntityInfo struct {
	Name    string
	Parent  string
	Aliases []string
	// Icon is an opaque UI icon name carried through to the OpenAPI surface
	// (x-clicky.surfaces[].icon). Empty for entities that declare no icon.
	Icon string
	// Path is the entity's hierarchy position within Parent, PathSeparator-joined
	// (x-clicky.surfaces[].path). Empty for entities that declare no hierarchy.
	Path string
	// Title overrides the auto-generated surface title when non-empty.
	Title         string
	Type          reflect.Type
	ListType      reflect.Type
	Operations    []EntityOperation
	PrimaryAction *ActionInfo
	Actions       []ActionInfo
	BulkActions   []BulkActionInfo
	ValidArgs     func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)
	IsAdmin       bool
	// FilterRefs maps a list filter's flag key to the name of the reusable named
	// filter backing it (when the filter was attached via the entity package's
	// Use/As helper). The OpenAPI layer uses it to emit an x-clicky-lookup $ref
	// to the shared filter definition. Nil when no filters reference a named one.
	FilterRefs map[string]string
	// ToolGroup names the group all of this entity's operations belong to. It is
	// inherited by every generated operation (an action may override it) and is
	// used by AI tool-preference layers to toggle related tools together.
	ToolGroup string
	ToolHints MCPToolHints
}

type EntityItem interface {
	GetID() string
	GetName() string
}

type EntityOperation struct {
	Verb     string // "list", "get", "create", "update", "delete"
	Method   string // Optional explicit HTTP method for generated RPC/OpenAPI routes.
	DataFunc func(flags map[string]string, args []string) (any, error)
	// ContextDataFunc, when set, is preferred over DataFunc by both the CLI run
	// path (fed cmd.Context()) and the RPC executor (fed r.Context()). Lets the
	// operation resolve request-scoped state instead of process globals.
	ContextDataFunc ContextDataFunc
	// FlagsType, when non-nil, binds typed flags from the given struct type
	// onto the generated cobra command and collects their values into the
	// flag map passed to DataFunc. Used by actions that implement
	// ActionFlags; ignored for the built-in CRUD verbs.
	FlagsType  reflect.Type
	LookupFunc func(flags map[string]string, args []string) (any, error)
	// ContextLookupFunc, when set, is the context-aware filter lookup closure.
	// The RPC converter wires it onto RPCOperation.ContextLookupFunc and the
	// executor prefers it over LookupFunc, feeding the request context.
	ContextLookupFunc ContextLookupFunc
	BindCompletions   func(cmd *cobra.Command)
	ResponseType      reflect.Type
	ResponseArray     bool
	ResponsePaged     bool
	ResponseEntityID  bool
}

type ExecutableCommand interface {
	// Execute runs the command with the given options, capturing everything
	// written to os.Stdout / os.Stderr (including direct writes, not just the
	// cobra writers). It is safe for concurrent callers: implementations that
	// swap process-global file descriptors serialize internally.
	Execute(ctx context.Context, opts ExecuteOptions) (stdout, stderr string, err error)

	// Path is the full space-joined command path ("user create").
	Path() string
	// Name is the leaf command name ("create").
	Name() string
	// RootName is the top-level application command name ("xero-cli"), used for
	// the MCP tool title.
	RootName() string

	// Runnable reports whether the command has a Run/RunE (not a pure group).
	Runnable() bool
	// Hidden reports whether the command is hidden from help/listing.
	Hidden() bool

	// IsBoolFlag reports whether the named flag is a boolean flag. Used by the
	// CLI-string reconstruction to render "--flag" vs "--flag=value".
	IsBoolFlag(name string) bool
}

type ExecuteOptions struct {
	// Args are the positional arguments.
	Args []string
	// Flags maps flag name -> string value. A flag absent on the command is
	// silently skipped (path params and other non-flag keys may appear here);
	// a present flag whose value fails to parse returns an error.
	Flags map[string]string
	// FormatOverrides are best-effort flag values applied before execution
	// (e.g. {"format":"markdown","no-color":"true"}). A flag absent on the
	// command is silently skipped. Used by the MCP server's format forcing.
	FormatOverrides map[string]string
}

type ExportHeaderDoc struct {
	Description string
	Type        string
}

type ExportMeta struct {
	Formats       []string       `json:"formats,omitempty"`
	Scopes        []string       `json:"scopes,omitempty"`
	AllRowsMode   string         `json:"allRowsMode,omitempty"`
	FormatMaxRows map[string]int `json:"formatMaxRows,omitempty"`
}

type Filter[ListOpts any] interface {
	Key() string
	Label() string
	Lookup(opts *ListOpts) (map[string]api.Textable, error)
	Options(opts ListOpts) map[string]api.Textable
}

type FilterContext struct {
	// Context is the request context (HTTP request or CLI command). It may be
	// nil when a source is invoked outside a request (e.g. shell completion).
	Context context.Context
	// Key is the bound flag/field name this filter resolves on the current
	// entity (e.g. "owner" when a "users" filter is attached via .As("owner")).
	Key string
	// Params holds the current values of every flag/filter on the entity, so a
	// source can narrow its options against sibling selections (cascading).
	Params map[string]string
}

type FilterSource interface {
	// Options returns the available options, optionally narrowed by query, and
	// the true total count behind the (possibly capped) returned set. An empty
	// query means "the head set". A non-positive limit means "no cap".
	Options(fc FilterContext, query string, limit int) (options map[string]api.Textable, total int, err error)
	// Resolve labels the currently-selected raw value(s) for display. A value
	// with no known label is echoed back as plain text.
	Resolve(fc FilterContext, values []string) (map[string]api.Textable, error)
}

type FilterSourceSpec struct {
	Kind string `json:"kind" yaml:"kind"`
	// Options is the value→label map for a static source.
	Options map[string]string `json:"options,omitempty" yaml:"options,omitempty"`
	// Entity is the source entity name for an entity source.
	Entity string `json:"entity,omitempty" yaml:"entity,omitempty"`
}

type FilterSpec struct {
	Name   string           `json:"name" yaml:"name"`
	Label  string           `json:"label,omitempty" yaml:"label,omitempty"`
	Type   string           `json:"type,omitempty" yaml:"type,omitempty"`
	Multi  bool             `json:"multi,omitempty" yaml:"multi,omitempty"`
	Source FilterSourceSpec `json:"source" yaml:"source"`
}

type Filterable[T any] interface {
	Filters() []Filter[T]
}

type Help interface {
	Help() api.Textable
}

type LimitedFilter interface {
	// LookupLimit returns the head/search cap, or zero to take the default.
	LookupLimit() int
}

type MCPToolHints struct {
	Title             string         `json:"title,omitempty"`
	ReadOnlyHint      *bool          `json:"readOnlyHint,omitempty"`
	DestructiveHint   *bool          `json:"destructiveHint,omitempty"`
	IdempotentHint    *bool          `json:"idempotentHint,omitempty"`
	OpenWorldHint     *bool          `json:"openWorldHint,omitempty"`
	Icon              string         `json:"icon,omitempty"`
	Group             string         `json:"group,omitempty"`
	Parent            string         `json:"parent,omitempty"`
	DefaultPermission ToolPermission `json:"defaultPermission,omitempty"`
	Strict            *bool          `json:"strict,omitempty"`
}

type MultiFilter []string

type Name interface {
	GetName() string
}

type NamedFilter struct {
	// Name is the unique registry key.
	Name string
	// Label is the human-facing control label. Defaults to Name when empty.
	Label string
	// Type is the UI control type: "select" (default), "multi-select", "date",
	// "from", or "to".
	Type string
	// Multi reports whether the control accepts multiple selections.
	Multi bool
	// Limit caps the option set this filter enumerates in one shot. Zero takes
	// MaxLookupOptions, which is also the ceiling. Declare a smaller one for a
	// field whose cardinality makes a full head set useless to pick from: what
	// is past it is reached by typing, not by scrolling.
	Limit int
	// Source resolves the filter's options.
	Source FilterSource
}

type PageInfo struct {
	Limit  int   `json:"limit"`
	Offset int   `json:"offset"`
	Total  int64 `json:"total"`
}

type PageLimits struct {
	DefaultPageSize int
	MaxPageSize     int
}

type PageRequest struct {
	// Scope is ScopePage or ScopeAll.
	Scope string
	// Format is the resolved export format, after ?format and Accept have been
	// reconciled — the operation never has to look at either again.
	Format string
	// Cursor is an opaque position handed back by a previous page.
	Cursor string
	// Filename overrides the download name. Empty means derive one.
	Filename string

	Limit  int
	Offset int

	// Download asks for a Content-Disposition even when no filename was named.
	Download bool

	// SkipTotal waives the exact total. A backend asked for the size of the whole
	// result has to produce the whole result first, which is the difference
	// between an export that streams and one that hangs until the last row is
	// found — so an all-rows export declines to ask.
	SkipTotal bool
}

type PageResponse struct {
	Rows formatters.RowIterator

	// Mode is ModePage, ModeBuffered or ModeStreaming.
	Mode string

	// Total is nil when the backend states no size for the whole result.
	Total   *Total
	HasMore bool
	// Next is the opaque position resuming after this page, when the provider
	// issued one.
	Next string

	// Ceiling stops an all-rows export. Zero means the rows are already bounded,
	// and therefore that nothing is left to discover by reading to the end.
	Ceiling int

	// MaxRows is the ceiling this export was bounded by, reported so a caller
	// sees the same number the server enforced.
	MaxRows int

	// Truncated reports a cut this response already knows about — the operation's
	// own size, or a cap the backend applied. A ceiling is not known to have
	// bitten until the rows have been read, so that case is reported as a trailer.
	Truncated bool

	// Pageable reports whether the operation can serve a position past its first
	// page. A response that cannot must not report one as available.
	Pageable bool
}

type Paged interface {
	PageMetadata() PageInfo
	PageRows() any
}

type PagedFunc func(ctx context.Context, req PageRequest, flags map[string]string) (PageResponse, error)

type PagedResult[T any] struct {
	Data []T      `json:"data"`
	Page PageInfo `json:"page"`
}

type Property struct {
	Type        string      `json:"type"`
	Description string      `json:"description"`
	Enum        []string    `json:"enum,omitempty"`
	Default     interface{} `json:"default,omitempty"`
}

type RPCOperation struct {
	Name              string               `json:"name"`
	Description       string               `json:"description"`
	Parameters        []RPCParameter       `json:"parameters"`
	Schema            Schema               `json:"schema"`
	Command           ExecutableCommand    `json:"-"`                // Transport-neutral handle to the original command
	Path              string               `json:"path,omitempty"`   // For REST APIs
	Method            string               `json:"method,omitempty"` // HTTP method
	Tags              []string             `json:"tags,omitempty"`   // OpenAPI tags (auto-derived from the parent command)
	Group             string               `json:"group,omitempty"`  // tool-group this operation belongs to (clicky/tool-group)
	ToolHints         MCPToolHints         `json:"-"`                // MCP annotations and Clicky-specific tool metadata
	DataFunc          DataFunc             `json:"-"`                // Direct data provider, bypasses stdout capture
	ContextDataFunc   ContextDataFunc      `json:"-"`                // Context-aware data provider; preferred over DataFunc when set
	PagedFunc         PagedFunc            `json:"-"`                // Paging/export data provider returning a PageResponse; preferred over ContextDataFunc when set. The operation supplies rows and the paging facts about them, and clicky owns the response: headers, content negotiation, streaming and the download name.
	LookupFunc        DataFunc             `json:"-"`                // Direct filter metadata provider
	ContextLookupFunc ContextLookupFunc    `json:"-"`                // Context-aware filter metadata provider; preferred over LookupFunc when set
	Clicky            *ClickyOperationMeta `json:"-"`                // Entity semantics used for OpenAPI extensions
	ResponseType      reflect.Type         `json:"-"`                // Static response type for OpenAPI generation
	ResponseArray     bool                 `json:"-"`                // Response body is an array of ResponseType
	ResponsePaged     bool                 `json:"-"`                // Response body is a paged envelope around ResponseType rows
	ResponseEntityID  bool                 `json:"-"`                // Array item schema should include Clicky _id metadata
}

type RPCParameter struct {
	Name        string      `json:"name"`
	Type        string      `json:"type"`
	Description string      `json:"description"`
	Required    bool        `json:"required"`
	Default     interface{} `json:"default,omitempty"`
	In          string      `json:"in,omitempty"` // "query", "path", "header" for REST
}

type RPCService struct {
	Name        string         `json:"name"`
	Version     string         `json:"version"`
	Description string         `json:"description"`
	Operations  []RPCOperation `json:"operations"`
}

type ResponseOpenAPIMeta struct {
	Type     reflect.Type
	Array    bool
	Paged    bool
	EntityID bool
}

type Schema struct {
	Type       string              `json:"type"`
	Properties map[string]Property `json:"properties"`
	Required   []string            `json:"required"`
}

type SearchableFilter[ListOpts any] interface {
	OptionsWithQuery(opts ListOpts, query string, limit int) (options map[string]api.Textable, total int)
}

type StatusError struct {
	// Status is the HTTP status this error is written with. It never appears in
	// the body: the status line already carries it, and repeating it invites the
	// two to disagree.
	Status int `json:"-"`

	Code    string `json:"code"`
	Message string `json:"message"`
}

type ToolPermission string

type Total struct {
	Value int64
	Exact bool
}

type TypedFilter[ListOpts any] interface {
	LookupType() string
}