client

type APIInfo struct {
	Title       string
	Version     string
	Description string
	Contact     *Contact
	License     *License
}

type APISpec struct {
	Info          APIInfo
	Servers       []Server
	Endpoints     []Endpoint
	WebSockets    []WebSocketEndpoint
	SSEs          []SSEEndpoint
	WebTransports []WebTransportEndpoint
	Schemas       map[string]*Schema
	Entities      map[string]*EntityRef
	Security      []SecurityScheme
	Tags          []Tag

	// RoutingTypes holds the named types that are NOT entities but sit on a
	// path to one: a paginated envelope (`PageOrder{items: []Order}`), or an
	// intermediate hop (`Order -> Shipment -> Carrier`, where Shipment carries
	// no identity of its own).
	//
	// They are kept out of Entities rather than merged into it because
	// `spec.Entities[name]` is read at several call sites as the question "is
	// this type an entity" -- registerStreamBindingEntities skips a binding
	// whose type is already there, and endpoint resolution writes it. An entry
	// with no identity answering yes to that question is a defect waiting for
	// whoever writes the next reader, and the ordering that makes it safe today
	// is invisible from those call sites.
	//
	// The row shape is the same as an entity's, minus identity, so EntityRef is
	// reused with IDField always empty. The two maps are disjoint by
	// construction: resolveEntityFields builds this one as the useful types
	// MINUS the entities, and it is the only writer.
	//
	// Both maps are emitted into the one `entities` table the browser runtime
	// reads, where a row with no idField means "walk me, never store me".
	RoutingTypes map[string]*EntityRef

	// Warnings collected while building this specification: things that did
	// not stop the parse but that silently reduce what the generated client
	// can do (an entity whose declared id field does not exist in its response
	// schema; a stream binding naming an entity type no schema describes).
	//
	// A language generator is expected to surface these alongside its own
	// warnings. Silent degradation is the failure mode this whole path exists
	// to avoid: a cache key that never matches looks exactly like a cache that
	// simply is not very effective.
	Warnings []string

	// Streaming extension features
	Streaming *StreamingSpec

	// Kind records which document family this spec was parsed from. MergeSpecs
	// orders sources by this rather than by argument order, so that
	// `--from-spec a.json --from-spec b.json` and the reverse produce identical
	// output. A spec built by Introspector carries SourceIntrospection and
	// ranks with OpenAPI, because it is authoritative for REST the same way.
	Kind SourceKind
}

type APIStats struct {
	TotalEndpoints   int
	RESTEndpoints    int
	WebSocketCount   int
	SSECount         int
	SecuredEndpoints int
	Tags             []string
	UpdatedAt        time.Time

	// Streaming features
	HasRooms    bool
	HasPresence bool
	HasTyping   bool
	HasChannels bool
	HasHistory  bool
}

type AuthCodeGenerator struct{}

type AuthRequirement struct {
	SchemeName string
	Required   bool
	Scopes     []string
}

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

type Change struct {
	Kind     ChangeKind `json:"kind"`
	Category string     `json:"category"`
	Subject  string     `json:"subject"`
	Detail   string     `json:"detail"`
	Old      string     `json:"old,omitempty"`
	New      string     `json:"new,omitempty"`
}

type ChangeKind string

type ChannelClientConfig struct {
	// MaxChannelsPerUser is the default max channels a user can subscribe to
	MaxChannelsPerUser int

	// SupportPatterns enables wildcard/pattern subscriptions
	SupportPatterns bool
}

type ChannelFeatureConfig struct {
	// Maximum channels a user can subscribe to
	MaxChannelsPerUser int

	// Whether to support channel patterns/wildcards
	SupportPatterns bool
}

type ChannelOperations struct {
	// Path for the channel WebSocket endpoint
	Path string

	// Parameters for the path (e.g., channelId)
	Parameters []Parameter

	// Subscribe schema
	SubscribeSchema *Schema

	// Unsubscribe schema
	UnsubscribeSchema *Schema

	// Publish schema
	PublishSchema *Schema

	// Message received schema
	MessageSchema *Schema
}

type ConnectionState string

type Contact struct {
	Name  string
	URL   string
	Email string
}

type DetectedAuthScheme struct {
	Name          string
	Type          string
	In            string
	Scheme        string
	BearerFormat  string
	RequiresScope bool
}

type DiffReport struct {
	Changes []Change    `json:"changes"`
	Summary DiffSummary `json:"summary"`
}

type DiffSummary struct {
	Compatible    int `json:"compatible"`
	BreakingAPI   int `json:"breaking_api"`
	BreakingCache int `json:"breaking_cache"`
	Unknown       int `json:"unknown"`
	Total         int `json:"total"`
}

type Discriminator struct {
	PropertyName string
	Mapping      map[string]string // value -> schema reference
}

type Endpoint struct {
	ID          string
	Method      string
	Path        string
	Summary     string
	Description string
	Tags        []string
	OperationID string
	Deprecated  bool

	// Parameters
	PathParams   []Parameter
	QueryParams  []Parameter
	HeaderParams []Parameter

	// Request/Response
	RequestBody  *RequestBody
	Responses    map[int]*Response
	DefaultError *Response

	// Security
	Security []SecurityRequirement

	// Metadata
	Metadata map[string]any

	// Cache metadata
	Entity    *EntityRef
	CacheTags TagSet

	// RootType is the typename of this endpoint's success response -- or of its
	// ELEMENTS, when that response is a bare array, since a typename propagates
	// through an array unchanged. Empty when the response has no named type.
	//
	// It is not the same thing as Entity.Type and must not be conflated with
	// it. For `GET /orders` returning `PageOrder{items: []Order, total: int}`,
	// Entity.Type is "Order" -- the thing being cached and tagged -- while
	// RootType is "PageOrder", the type the response document actually IS. The
	// runtime looks the root up in the entities table to learn which of its
	// properties to descend, so handing it "Order" there would have it read
	// Order's field edges against an envelope's properties and find nothing.
	//
	// Populated for every endpoint with a named response type, entity or not:
	// it describes the document, and describing it costs nothing when there is
	// no entity beneath.
	RootType string
}

type EndpointType string

type EntityRef struct {
	Type    string // typename, e.g. "Order"
	IDField string // JSON property name, e.g. "id"

	// Fields maps a JSON property of this type to the typename of what that
	// property contains -- the ELEMENT typename for an array, so a
	// `[]LineItem` records "LineItem" rather than any array marker.
	//
	// It is the only way the browser runtime can recognise a nested entity of
	// a different type: a JSON response carries no typename, and the runtime
	// refuses to derive one from shape for the same reason InferEntity does --
	// a guess made wrong on a type carrying both an id and a tenant id keys
	// two tenants' records to one entry. So `Order.customer` normalizes into
	// `Customer:c-3` only because this map says so.
	//
	// Populated by resolveEntityFields after every entity in a spec is known,
	// because resolving a property's $ref needs the whole spec.Schemas table
	// and InferEntity sees one schema at a time. Nil when the type has no
	// entity-typed property.
	Fields map[string]string
}

type Example struct {
	Summary     string
	Description string
	Value       any
}

type Features struct {
	// Reconnection enables automatic reconnection for streaming endpoints
	Reconnection bool

	// Heartbeat enables heartbeat/ping for maintaining connections
	Heartbeat bool

	// StateManagement enables connection state tracking
	StateManagement bool

	// TypedErrors generates typed error responses
	TypedErrors bool

	// RequestRetry enables automatic request retry with exponential backoff
	RequestRetry bool

	// Timeout enables request timeout configuration
	Timeout bool

	// Middleware enables request/response middleware/interceptors
	Middleware bool

	// Logging enables built-in logging support
	Logging bool
}

type FilterResult struct {
	// KeptEndpoints and DroppedEndpoints count operations, not paths: one path
	// with a GET and a DELETE is two endpoints and they filter together.
	KeptEndpoints    int
	DroppedEndpoints int

	// KeptSchemas and DroppedSchemas count component schemas after pruning.
	KeptSchemas    int
	DroppedSchemas int

	// DroppedPaths lists the distinct paths removed, sorted, for reporting.
	DroppedPaths []string
}

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

type GeneratorConfig struct {
	// Language specifies the target language (go, typescript, rust)
	Language string

	// OutputDir is the directory where generated files will be written
	OutputDir string

	// PackageName is the name of the generated package/module
	PackageName string

	// APIName is the name of the main client struct/class
	APIName string

	// BaseURL is the default base URL for the API
	BaseURL string

	// IncludeAuth determines if auth configuration should be generated
	IncludeAuth bool

	// IncludeStreaming determines if WebSocket/SSE clients should be generated
	IncludeStreaming bool

	// Features contains feature flags for generation
	Features Features

	// Streaming contains streaming-specific configuration
	Streaming StreamingConfig

	// Hooks emits the operation manifest (src/ops.ts) and typed hook facades
	// (src/hooks.ts) delegating to @forge-go/client-core.
	//
	// A layer rather than a second client: the hooks bind directly to the
	// operations the manifest describes. Off by default — it adds a
	// dependency on @forge-go/client-core, which a consumer with no need for
	// cached hooks should not inherit.
	//
	// Read this through HooksEnabled, never directly, so the deprecated
	// ReactQuery alias is honoured too.
	Hooks bool

	// ReactQuery is the former name of Hooks, kept so existing callers still
	// compile. Go has no field aliases, so both fields exist and HooksEnabled
	// ORs them; setting either one enables the layer.
	//
	// Deprecated: use Hooks. The generated code has not been TanStack Query
	// since the hook facades replaced it (see facades.go), and this name
	// describes a library the output no longer uses.
	ReactQuery bool

	// PathFilter selects which endpoints the generated client covers.
	//
	// Honoured by GenerateFromFile, which owns the spec it parses. Callers of
	// Generate hold their own *APISpec and should apply the filter themselves
	// with spec.Apply — silently mutating an argument would be a surprise.
	PathFilter PathFilter

	// Module is the Go module path (for Go only)
	Module string

	// Version is the version of the generated client
	Version string

	// Enhanced features
	UseFetch        bool // Use fetch instead of axios (TypeScript)
	DualPackage     bool // Generate ESM + CJS (TypeScript)
	GenerateTests   bool // Generate test setup
	GenerateLinting bool // Generate linting setup
	GenerateCI      bool // Generate CI config
	ErrorTaxonomy   bool // Generate typed error classes
	Interceptors    bool // Generate interceptor support
	Pagination      bool // Generate pagination helpers

	// Output control
	ClientOnly bool // Generate only client source files (no package.json, tsconfig, etc.)

	// FieldNaming selects the client-side identifier style for schema properties.
	// The wire name always comes from the spec. Only the TypeScript generator reads
	// this field in this change; other language generators ignore it and are
	// unaffected. Defaults to NamingCamel when Language is "typescript", and to
	// NamingPreserve otherwise, so no existing generator changes behaviour.
	FieldNaming NamingStrategy

	// FieldOverrides maps a wire name to an explicit client-side name. A key of
	// "Schema.wire_name" applies to that schema only; a bare "wire_name" applies
	// globally. A schema-scoped entry wins over a global one for the same wire
	// name. Overrides bypass FieldNaming entirely and are used verbatim.
	FieldOverrides map[string]string
}

type GeneratorInfo struct {
	Name              string
	SupportedFeatures []string
}

type GeneratorOption func(*GeneratorConfig)

type HeartbeatConfig struct {
	Enabled  bool
	Interval time.Duration
	Timeout  time.Duration
}

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

type License struct {
	Name string
	URL  string
}

type MediaType struct {
	Schema   *Schema
	Example  any
	Examples map[string]*Example
}

type NamingStrategy string

type OAuthFlow struct {
	AuthorizationURL string
	TokenURL         string
	RefreshURL       string
	Scopes           map[string]string
}

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow
	AuthorizationCode *OAuthFlow
}

type OutputManager struct{}

type Parameter struct {
	Name        string
	In          string // "path", "query", "header"
	Description string
	Required    bool
	Deprecated  bool
	Schema      *Schema
	Example     any
}

type PathFilter struct {
	// Include keeps only the endpoints matching at least one pattern. Empty
	// means every endpoint is a candidate.
	Include []string

	// Exclude drops endpoints matching any pattern, and is applied after
	// Include so that a narrow exclusion can carve a hole in a broad include.
	Exclude []string
}

type PresenceClientConfig struct {
	// Statuses are the available presence statuses
	Statuses []string

	// HeartbeatIntervalMs is the default heartbeat interval
	HeartbeatIntervalMs int

	// IdleTimeoutMs is the default idle timeout before auto-away
	IdleTimeoutMs int

	// IncludeCustomStatus enables custom status message support
	IncludeCustomStatus bool
}

type PresenceFeatureConfig struct {
	// Heartbeat interval in milliseconds
	HeartbeatIntervalMs int

	// Idle timeout before marking as away (in milliseconds)
	IdleTimeoutMs int
}

type PresenceOperations struct {
	// Path for the presence WebSocket endpoint
	Path string

	// Status update schema (client -> server)
	UpdateSchema *Schema

	// Presence event schema (server -> client)
	EventSchema *Schema

	// Available statuses
	Statuses []string // e.g., ["online", "away", "busy", "offline"]
}

type ReconnectionConfig struct {
	Strategy      ReconnectionStrategy
	InitialDelay  time.Duration
	MaxDelay      time.Duration
	MaxAttempts   int
	BackoffFactor float64 // For exponential strategy
	JitterEnabled bool    // Add random jitter to delays
}

type ReconnectionStrategy string

type RequestBody struct {
	Description string
	Required    bool
	Content     map[string]*MediaType // content-type -> media type
}

type Response struct {
	Description string
	Content     map[string]*MediaType // content-type -> media type
	Headers     map[string]*Parameter
}

type RoomClientConfig struct {
	// MaxRoomsPerUser is the default max rooms a user can join (for docs/validation)
	MaxRoomsPerUser int

	// IncludeMemberEvents generates handlers for member join/leave events
	IncludeMemberEvents bool

	// IncludeRoomMetadata generates room metadata support
	IncludeRoomMetadata bool
}

type RoomFeatureConfig struct {
	// Maximum rooms a user can join
	MaxRoomsPerUser int

	// Maximum members per room
	MaxMembersPerRoom int

	// Whether to broadcast member events
	BroadcastMemberEvents bool
}

type RoomOperations struct {
	// Path for the room WebSocket endpoint
	Path string

	// Parameters for the path (e.g., roomId)
	Parameters []Parameter

	// Message schemas
	JoinSchema    *Schema // Client request to join room
	LeaveSchema   *Schema // Client request to leave room
	SendSchema    *Schema // Client message to room
	ReceiveSchema *Schema // Server message from room

	// Member event schemas
	MemberJoinSchema  *Schema // Member joined notification
	MemberLeaveSchema *Schema // Member left notification

	// History configuration
	HistoryEnabled bool
	HistorySchema  *Schema // History query/response schema
}

type SSEClientTemplate struct {
	EndpointID      string
	Path            string
	EventSchemas    map[string]*Schema
	Features        StreamingFeatures
	ReconnectConfig ReconnectionConfig
}

type SSEEndpoint struct {
	ID          string
	Path        string
	Summary     string
	Description string
	Tags        []string

	// Event schemas (event name -> schema)
	EventSchemas map[string]*Schema

	// Security
	Security []SecurityRequirement

	// Metadata
	Metadata map[string]any

	// Cache metadata
	StreamBindings []StreamBinding
}

type Schema struct {
	Type        string // "object", "array", "string", "number", "integer", "boolean", "null"
	Format      string // "date-time", "email", "uuid", etc.
	Description string
	Required    []string // For object types
	Properties  map[string]*Schema
	Items       *Schema // For array types
	Enum        []any   // For enum types
	Default     any
	Example     any
	Nullable    bool
	ReadOnly    bool
	WriteOnly   bool
	Deprecated  bool
	MinLength   *int
	MaxLength   *int
	Minimum     *float64
	Maximum     *float64
	Pattern     string
	Ref         string // Reference to another schema (e.g., "#/components/schemas/User")

	// Polymorphism
	OneOf         []*Schema
	AnyOf         []*Schema
	AllOf         []*Schema
	Discriminator *Discriminator

	// Additional properties
	AdditionalProperties any // bool or *Schema

	// Extensions
	Extensions map[string]any
}

type SecurityRequirement struct {
	SchemeName string
	Scopes     []string
}

type SecurityScheme struct {
	Type             string // "apiKey", "http", "oauth2", "openIdConnect"
	Name             string // Scheme name
	Description      string
	In               string            // "query", "header", "cookie" (for apiKey)
	Scheme           string            // "bearer", "basic" (for http)
	BearerFormat     string            // "JWT" (for http bearer)
	Flows            *OAuthFlows       // For oauth2
	OpenIDConnectURL string            // For openIdConnect
	CustomHeaders    map[string]string // Custom headers
}

type Server struct {
	URL         string
	Description string
	Variables   map[string]ServerVariable
}

type ServerVariable struct {
	Default     string
	Description string
	Enum        []string
}

type SourceKind int

type SpecParser struct{}

type StreamBinding struct {
	Message     string
	EntityType  string
	Intent      StreamIntent
	Invalidates []string
}

type StreamIntent string

type StreamSchema struct {
	SendSchema    *Schema // Client -> Server
	ReceiveSchema *Schema // Server -> Client
}

type StreamingCodeHelper struct{}

type StreamingConfig struct {
	// EnableRooms generates room management client (join/leave/broadcast)
	EnableRooms bool

	// EnableChannels generates pub/sub channel client
	EnableChannels bool

	// EnablePresence generates presence tracking client
	EnablePresence bool

	// EnableTyping generates typing indicator client
	EnableTyping bool

	// EnableHistory generates message history support
	EnableHistory bool

	// RoomConfig contains room-specific configuration
	RoomConfig RoomClientConfig

	// PresenceConfig contains presence-specific configuration
	PresenceConfig PresenceClientConfig

	// TypingConfig contains typing indicator configuration
	TypingConfig TypingClientConfig

	// ChannelConfig contains channel-specific configuration
	ChannelConfig ChannelClientConfig

	// GenerateUnifiedClient generates a unified StreamingClient that composes all features
	GenerateUnifiedClient bool

	// GenerateModularClients generates separate clients for each feature
	GenerateModularClients bool
}

type StreamingFeatures struct {
	Reconnection    bool
	Heartbeat       bool
	StateManagement bool
}

type StreamingSpec struct {
	// Feature flags indicating what's available
	EnableRooms    bool
	EnableChannels bool
	EnablePresence bool
	EnableTyping   bool
	EnableHistory  bool

	// Room operations and schemas
	Rooms *RoomOperations

	// Presence tracking
	Presence *PresenceOperations

	// Typing indicators
	Typing *TypingOperations

	// Pub/sub channels
	Channels *ChannelOperations
}

type Tag struct {
	Name        string
	Description string
}

type TagSet struct {
	Provides    []string
	Invalidates []string
}

type TypingClientConfig struct {
	// TimeoutMs is the auto-stop timeout in milliseconds
	TimeoutMs int

	// DebounceMs is the debounce interval for typing events
	DebounceMs int
}

type TypingFeatureConfig struct {
	// Auto-stop timeout in milliseconds
	TimeoutMs int

	// Debounce interval in milliseconds
	DebounceMs int
}

type TypingOperations struct {
	// Path for the typing WebSocket endpoint
	Path string

	// Parameters for the path (e.g., roomId)
	Parameters []Parameter

	// Typing start schema
	StartSchema *Schema

	// Typing stop schema
	StopSchema *Schema

	// Timeout duration for auto-stop (in milliseconds)
	TimeoutMs int
}

type ValidationError struct {
	Type    string
	Path    string
	Message string
	Index   int
}

type ValidationOptions struct {
	RequireOperationIDs bool
	RequireDescriptions bool
	RequireExamples     bool
	RequireSecurity     bool
}

type WebSocketClientTemplate struct {
	EndpointID      string
	Path            string
	SendSchema      *Schema
	ReceiveSchema   *Schema
	Features        StreamingFeatures
	ReconnectConfig ReconnectionConfig
	HeartbeatConfig HeartbeatConfig
}

type WebSocketEndpoint struct {
	ID          string
	Path        string
	Summary     string
	Description string
	Tags        []string

	// Path parameters (e.g., roomId, channelId)
	Parameters []Parameter

	// Message schemas
	SendSchema    *Schema // Client -> Server
	ReceiveSchema *Schema // Server -> Client

	// Additional message types for multiplexed connections
	MessageTypes map[string]*Schema // message type -> schema

	// Security
	Security []SecurityRequirement

	// Metadata
	Metadata map[string]any

	// Cache metadata
	StreamBindings []StreamBinding

	// Streaming extension features (if this endpoint supports them)
	StreamingFeatures *WebSocketStreamingFeatures
}

type WebSocketStreamingFeatures struct {
	// Feature flags
	SupportsRooms    bool
	SupportsPresence bool
	SupportsTyping   bool
	SupportsChannels bool
	SupportsHistory  bool

	// Feature-specific configurations
	RoomConfig     *RoomFeatureConfig
	PresenceConfig *PresenceFeatureConfig
	TypingConfig   *TypingFeatureConfig
	ChannelConfig  *ChannelFeatureConfig
}

type WebTransportEndpoint struct {
	ID          string
	Path        string
	Summary     string
	Description string
	Tags        []string

	// Stream schemas
	UniStreamSchema *StreamSchema // Unidirectional streams
	BiStreamSchema  *StreamSchema // Bidirectional streams
	DatagramSchema  *Schema       // Unreliable datagrams

	// Security
	Security []SecurityRequirement

	// Metadata
	Metadata map[string]any
}