api

type ArrayTypeHandler struct{}

type BasicTypeHandler struct{}

type BasicTypeMapper interface {
	MapType(reflect.Kind) *Schema
}

type BodyValidationError struct {
	Errors []string `json:"errors"`
}

type Components struct {
	Schemas         map[string]*Schema         `json:"schemas,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
	Responses       map[string]*Response       `json:"responses,omitempty"`
}

type ContextValidator interface {
	Validate(ctx context.Context) error
}

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

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

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

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

type CookiesValidationError struct {
	Errors []string `json:"errors"`
}

type DefaultParameterAdapter struct{}

type Discriminator struct {
	PropertyName string            `json:"propertyName"`
	Mapping      map[string]string `json:"mapping,omitempty"`
}

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

type DocsConfig struct {
	// Title shown in the browser tab / UI header.
	Title string
	// OpenAPIPath under which the generated OpenAPI document is served. Must start with "/".
	// Defaults to "/openapi.json".
	OpenAPIPath string
	// SpecFile points to a pre-generated OpenAPI 3.1 JSON (or YAML) file on
	// disk. When set, DocsRoute will load the specification from this file
	// once during server start-up and serve it at runtime instead of
	// generating a fresh spec on every request. This allows enrichment from
	// build-time tooling (e.g. doc comments).
	//
	// If the file cannot be read or parsed the router falls back to runtime
	// generation so that documentation is still available albeit without the
	// additional metadata.
	SpecFile string
	// UITemplate holds the HTML page used to render the documentation UI. The
	// template must contain the placeholders {{.Title}}, {{.OpenAPIPath}} and
	// {{.BasePath}} which are replaced at runtime. Predefined templates are
	// provided – StoplightUITemplate (default), SwaggerUITemplate and
	// RedocUITemplate – but callers can supply any custom template string.
	UITemplate UITemplate
}

type Documentation struct {
	Description string
	Fields      map[string]FieldDoc
	Deprecated  bool
	Example     string
	Since       string
}

type EmbeddedStructProcessor interface {
	ProcessEmbedded(field reflect.StructField, schema *Schema, registry map[string]*Schema) error
}

type ErrorResponse struct {
	Error   string                 `json:"error"`
	Details map[string]interface{} `json:"details,omitempty"`
}

type EventHandlerFunc interface{}

type ExistingTypeHandler struct{}

type ExitFunc func(int)

type ExportConfig struct {
	Output    io.Writer
	ExitFunc  ExitFunc
	LogFatalf LogFatalfFunc
}

type ExportableRouteInfo struct {
	Method       string `json:"method"`
	Path         string `json:"path"`
	HandlerName  string `json:"handlerName"`
	RequestType  string `json:"requestType,omitempty"`
	ResponseType string `json:"responseType,omitempty"`
}

type FieldDoc struct {
	Description string
	Example     string
	Deprecated  bool
}

type FieldProcessor interface {
	ProcessField(field reflect.StructField, schema *Schema, registry map[string]*Schema) error
}

type FieldValidator interface {
	Var(field interface{}, tag string) error
	Struct(s interface{}) error
}

type FileReader interface {
	ReadFile(filename string) ([]byte, error)
}

type FuncForPCProvider func(uintptr) *runtime.Func

type FunctionNameExtractor func(interface{}) string

type GenericParameterAdapter[T any] interface {
	Path(ctx T, key string) (string, bool)
	Query(ctx T, key string) (string, bool)
	Header(ctx T, key string) (string, bool)
	Cookie(ctx T, key string) (string, bool)
}

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

type GorkTagInfo struct {
	Name          string
	Discriminator string
}

type HTTPParameterAdapter struct{}

type HandlerOption struct {
	Tags     []string
	Security []SecurityRequirement
}

type Header struct {
	Description string  `json:"description,omitempty"`
	Required    bool    `json:"required,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

type HeadersValidationError struct {
	Errors []string `json:"errors"`
}

type Info struct {
	Title   string `json:"title,omitempty"`
	Version string `json:"version,omitempty"`
}

type JSONEncoder interface {
	Encode(v interface{}) error
}

type JSONEncoderFactory interface {
	NewEncoder(w io.Writer) JSONEncoder
}

type JSONMarshaler func(v any) ([]byte, error)

type LogFatalfFunc func(string, ...interface{})

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

type OpenAPIOption func(*OpenAPISpec)

type OpenAPISpec struct {
	OpenAPI    string               `json:"openapi"`
	Info       Info                 `json:"info"`
	Paths      map[string]*PathItem `json:"paths"`
	Components *Components          `json:"components,omitempty"`
	// contains filtered or unexported fields
}

type Operation struct {
	OperationID string                 `json:"operationId,omitempty"`
	Summary     string                 `json:"summary,omitempty"`
	Description string                 `json:"description,omitempty"`
	Tags        []string               `json:"tags,omitempty"`
	Security    []map[string][]string  `json:"security,omitempty"`
	Parameters  []Parameter            `json:"parameters,omitempty"`
	RequestBody *RequestBody           `json:"requestBody,omitempty"`
	Responses   map[string]*Response   `json:"responses,omitempty"`
	Deprecated  bool                   `json:"deprecated,omitempty"`
	Extensions  map[string]interface{} `json:"-"` // Custom extensions like x-webhook-provider
	// Explicit vendor extension fields to ensure emission
	XWebhookProvider map[string]string        `json:"x-webhook-provider,omitempty"`
	XWebhookEvents   []map[string]interface{} `json:"x-webhook-events,omitempty"`
}

type Option func(*HandlerOption)

type Parameter struct {
	Name        string  `json:"name"`
	In          string  `json:"in"` // "query", "header", "path", "cookie"
	Required    bool    `json:"required"`
	Description string  `json:"description,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

type PathItem struct {
	Get    *Operation `json:"get,omitempty"`
	Post   *Operation `json:"post,omitempty"`
	Put    *Operation `json:"put,omitempty"`
	Patch  *Operation `json:"patch,omitempty"`
	Delete *Operation `json:"delete,omitempty"`
}

type PathValidationError struct {
	Errors []string `json:"errors"`
}

type PointerTypeHandler struct{}

type QueryValidationError struct {
	Errors []string `json:"errors"`
}

type RegisteredEventHandler struct {
	EventType           string
	HandlerFunc         EventHandlerFunc
	HandlerName         string
	ProviderPayloadType reflect.Type
	UserMetadataType    reflect.Type
}

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

type RequestValidationError struct {
	Errors []string `json:"errors"`
}

type Response struct {
	Ref         string                `json:"$ref,omitempty"`
	Description string                `json:"description,omitempty"`
	Content     map[string]*MediaType `json:"content,omitempty"`
	Headers     map[string]*Header    `json:"headers,omitempty"`
}

type RouteInfo struct {
	Method       string         // HTTP method (GET, POST, ...)
	Path         string         // Absolute route path, including any prefix
	Handler      interface{}    // The original typed handler function
	HandlerName  string         // getFunctionName(handler)
	RequestType  reflect.Type   // The concrete request struct type (non-pointer)
	ResponseType reflect.Type   // The concrete response struct type (non-pointer)
	Options      *HandlerOption // Collected handler options (tags, security, etc.)
	// WebhookHandler stores the original webhook handler instance for OpenAPI reflection.
	// This field is only set for webhook routes created with WebhookHandlerFunc.
	WebhookHandler interface{} // Original webhook handler with SuccessResponse() and ErrorResponse() methods
	// WebhookProviderInfo contains optional provider metadata exposed by the handler implementation.
	WebhookProviderInfo *WebhookProviderInfo
	// WebhookHandledEvents lists only the events that have user-registered handlers via WithEventHandler.
	WebhookHandledEvents []string
	// WebhookHandlersMeta contains detailed metadata about each registered handler for documentation.
	WebhookHandlersMeta []RegisteredEventHandler
	// Middleware can hold router specific middleware descriptors. For now we
	// simply keep them as raw Option values so that future work can refine the
	// representation without breaking the API.
	Middleware []Option
}

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

type Schema struct {
	// Title provides a human-readable name for the schema. Some documentation UIs
	// (e.g. ReDoc, Swagger UI) display this value in type signatures. We set it
	// automatically from the Go type name where available so that arrays like
	// []UserResponse are shown as array[UserResponse] instead of array[object].
	Title         string             `json:"title,omitempty"`
	Ref           string             `json:"$ref,omitempty"`
	Type          string             `json:"-"`
	Types         []string           `json:"-"`
	Properties    map[string]*Schema `json:"properties,omitempty"`
	Required      []string           `json:"required,omitempty"`
	OneOf         []*Schema          `json:"oneOf,omitempty"`
	AnyOf         []*Schema          `json:"anyOf,omitempty"`
	Discriminator *Discriminator     `json:"discriminator,omitempty"`
	Description   string             `json:"description,omitempty"`
	Minimum       *float64           `json:"minimum,omitempty"`
	Maximum       *float64           `json:"maximum,omitempty"`
	MinLength     *int               `json:"minLength,omitempty"`
	MaxLength     *int               `json:"maxLength,omitempty"`
	Pattern       string             `json:"pattern,omitempty"`
	Enum          []string           `json:"enum,omitempty"`
	Items         *Schema            `json:"items,omitempty"`
	Format        string             `json:"format,omitempty"`
}

type SchemaFieldSuffix string

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

type SecurityRequirement struct {
	Type   string   // "basic", "bearer", "apiKey"
	Scopes []string // For OAuth2
}

type SecurityScheme struct {
	Type   string `json:"type"`
	In     string `json:"in,omitempty"`
	Name   string `json:"name,omitempty"`
	Scheme string `json:"scheme,omitempty"`
}

type SpecParser interface {
	ParseJSON(data []byte) (*OpenAPISpec, error)
	ParseYAML(data []byte) (*OpenAPISpec, error)
}

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

type StructTypeHandler struct{}

type TypeDocExtractor interface {
	GetAllTypeNames() []string
	ExtractTypeDoc(typeName string) Documentation
}

type TypeParserFunc func(context.Context, string) (interface{}, error)

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

type TypeRegistrar interface {
	RegisterType(t reflect.Type, schema *Schema, registry map[string]*Schema) *Schema
}

type TypeSchemaHandler interface {
	CanHandle(t reflect.Type) bool
	GenerateSchema(t reflect.Type, registry map[string]*Schema, makePointerNullable bool) *Schema
}

type TypedRouter[T any] struct {
	// contains filtered or unexported fields
}

type UITemplate string

type UnionTypeHandler struct{}

type ValidationError interface {
	error
	GetErrors() []string
}

type ValidationErrorResponse struct {
	Message string              `json:"error"`
	Details map[string][]string `json:"details,omitempty"`
}

type Validator interface {
	Validate() error
}

type ValidatorConfig struct {
	TagNameFunc func(reflect.StructField) string
}

type WebhookEvent struct {
	Type           string
	ProviderObject interface{}
	UserMetaJSON   json.RawMessage
}

type WebhookHandler[T WebhookRequest] interface {
	// ParseRequest verifies the webhook signature and extracts event data using conventional struct
	ParseRequest(req T) (WebhookEvent, error)

	// SuccessResponse returns the appropriate success response for the provider
	SuccessResponse() interface{}

	// ErrorResponse returns the appropriate error response for the provider
	ErrorResponse(err error) interface{}

	// GetValidEventTypes returns a list of valid event types for validation and OpenAPI.
	GetValidEventTypes() []string

	// ProviderInfo exposes provider name and documentation metadata.
	ProviderInfo() WebhookProviderInfo
}

type WebhookHandlerOption struct {
	EventHandlers map[string]EventHandlerFunc
	// When true: user metadata validation/unmarshal errors produce 400 with ErrorResponse.
	// When false (default): handlers receive a nil user metadata pointer on validation errors.
	StrictUserValidation bool
}

type WebhookOption func(*WebhookHandlerOption)

type WebhookProviderInfo struct {
	Name    string
	Website string
	DocsURL string
}

type WebhookRequest interface {
	// WebhookRequest marker method to identify webhook request types
	WebhookRequest()
}