apiendpoint

type APIEndpoint[TReq, TResp any] struct {
	Title  string `json:"title" yaml:"title"`
	Method string `json:"method" yaml:"method"`
	Route  string `json:"route" yaml:"route"`
	// SDKMethodKey overrides the generated Stainless method key for this endpoint. When empty, codegen derives the key from the route + method.
	SDKMethodKey      string `json:"sdk_method_key,omitempty" yaml:"sdk_method_key,omitempty"`
	ContentType       string `json:"content_type" yaml:"content_type"`
	SuccessStatusCode int    `json:"success_status_code" yaml:"success_status_code"`
	Public            bool   `json:"-" yaml:"-"`
	Preview           bool   `json:"-" yaml:"-"`
	// AgentTool, when true, marks this endpoint for inclusion in the generated agent-tool catalog so agents can invoke it. Defaults to false; flagging an endpoint is the opt-in to expose it as an agent capability.
	AgentTool bool `json:"-" yaml:"-"`
	// ReadOnly declares that this endpoint computes an answer without changing anything, even though its method is not GET. Quotes, previews, validations and analytics all take a request body too large or too structured for a query string, so they are POST or PUT while writing nothing.
	//
	// Only set this where it is true of the whole request path, including anything downstream: an endpoint that emails a customer or calls a carrier's API has taken an externally-visible action even if it stores nothing. The default is the safe one — anything other than a GET is assumed to change state — so leaving this unset on a read-only endpoint only over-reports, while setting it wrongly would present a writing endpoint as safe to run unsupervised.
	//
	// Read by the agent-tool catalog, which surfaces it as the tool's `mutating` flag: that is what a merchant reads when deciding which tools an agent may run without review, so a quote that reports itself as mutating gets gated for no reason and dilutes the signal on the tools that genuinely need it.
	ReadOnly bool `json:"-" yaml:"-"`
	// RequiredPermissions declares the any-of permission set this endpoint requires, using typed domain/action constants (e.g. {types.PermissionDomainCustomers, types.ActionRead}) so typos are caught by the compiler. The gateway gate rejects callers who hold none of the listed permissions; holding one is enough to reach the handler. Agent tools and OpenAPI docs surface the same declaration.
	RequiredPermissions types.AnyOfPermissions `json:"-" yaml:"-"`
	// RequiredRoleType, when set, declares that the endpoint requires the caller to have a specific role type (e.g. constants.RoleTypeAdmin) rather than (or in addition to) a permission. The zero value means no role-type requirement.
	RequiredRoleType constants.RoleType                        `json:"-" yaml:"-"`
	ServiceHandler   func(svc any) ServiceHandler[TReq, TResp] `json:"-" yaml:"-"`
	Extras           APIEndpointExtras                         `json:"-" yaml:"-"`
	MinVersion       *version.APIVersion                       `json:"-" yaml:"-"`
	// ObjectType identifies the API resource type this endpoint operates on. Used for version transformations. Only endpoints with an ObjectType get transformations applied.
	ObjectType constants.ObjectType `json:"-" yaml:"-"`
	// Returns the Location header value: the resource created on 201, or on 202 the job
	// that tracks the accepted work and that the caller polls for its outcome.
	LocationFunc func(TResp) string `json:"-" yaml:"-"`
	// IncludeConfig declares which sub-objects can be expanded via the include query parameter. When nil, no include support is provided (zero overhead).
	IncludeConfig *IncludeConfig `json:"-" yaml:"-"`
	// (optional) Sets the response's Cache-Control header, for a body carrying something
	// short-lived such as a signed URL.
	CacheControl string `json:"-" yaml:"-"`

	// EndpointType is the reflect.Type of the concrete *XxxEndpoint struct that produced this APIEndpoint. It is used by the OpenAPI generator to resolve the operation description from the Go doc comment on that struct.
	EndpointType reflect.Type
	// contains filtered or unexported fields
}

type APIEndpointExtras struct {
	SkipRequestBodyParsing bool `json:"skip_request_body_parsing" yaml:"skip_request_body_parsing"`
	SkipRequestLogging     bool `json:"skip_request_logging" yaml:"skip_request_logging"`
	// HideFromRequestLog persists the request log but omits it from the default request-log listing. Use for high-frequency polling endpoints that would otherwise flood the log (e.g. notification unread-count). Unlike SkipRequestLogging the row is still saved.
	HideFromRequestLog bool `json:"hide_from_request_log" yaml:"hide_from_request_log"`
}

type APIEndpointGroup struct {
	Title       string `json:"title" yaml:"title"`
	Description string `json:"description" yaml:"description"`
	// SDKResourcePath overrides the generated Stainless resource path for
	// endpoints in this group when route inference is insufficient.
	SDKResourcePath []string                 `json:"sdk_resource_path,omitempty" yaml:"sdk_resource_path,omitempty"`
	ResourceType    contracts.DocumentedType `json:"-" yaml:"-"`
	Endpoints       []APIEndpointer          `json:"endpoints" yaml:"endpoints"`
}

type APIEndpointer interface {
	GetMethod() string
	GetRoute() string
	IsPublic() bool
	IsAgentTool() bool
	GetHandler() http.HandlerFunc
	IsServiceBound() bool
	GetRequestType() reflect.Type
	GetResponseType() reflect.Type
}

type IncludeConfig struct {
	Fields []IncludeField
	// ExtractRoots overrides the default root extraction for non-standard
	// response shapes (e.g. map-typed responses). When nil, the reflective
	// default handles *Resource and *List[Resource] shapes.
	ExtractRoots func(any) []any
}

type IncludeField struct {
	// Key is the client-facing include value (e.g. "role", "actor.role").
	Key string
	// ObjectType is the object type used in the collapsed reference.
	ObjectType constants.ObjectType
	// JSONPaths are the dot-separated paths where this sub-object appears in the
	// serialized response (e.g. "role", "api_key_info.role").
	JSONPaths []string
}

type IncludeFieldDef struct {
	// Key is the client-facing key, matches JSON field name (e.g., "role").
	Key string
	// ObjectType is the type of the expanded sub-object.
	ObjectType constants.ObjectType
	// JSONPath overrides the JSON path if different from Key.
	JSONPath string
	// Children defines nested expandable fields inline, bypassing registry lookup.
	// Use when the nested type doesn't have its own ObjectType (e.g., RequestLogActor).
	// When nil, the system resolves children from the registry using ObjectType.
	Children []IncludeFieldDef
}

type IncludesParams struct {
	// ObjectType is the root resource type returned by this endpoint.
	ObjectType constants.ObjectType
	// Fields is the explicit whitelist of include keys to expose.
	// Supports dot-notation (e.g., "actor.role") for nested includes.
	// REQUIRED — the function panics if empty.
	Fields []string
	// PathPrefix prepends a JSON path prefix for wrapper types
	// (e.g., "api_key_info" when the APIKey is nested inside CreatedAPIKey).
	PathPrefix string
}

type ObjectIncludes struct {
	ObjectType constants.ObjectType
	Fields     []IncludeFieldDef
}

type ServiceHandler[TReq, TResp any] = func(ctx context.Context, req TReq) (TResp, *apierror.APIError)