interfaces

type AnalyticsData struct {
	LLMID                  uint      `json:"llm_id"`
	ModelName              string    `json:"model_name"` // e.g., "gpt-4", "claude-3-sonnet"
	Vendor                 string    `json:"vendor"`     // e.g., "openai", "anthropic"
	PromptTokens           int       `json:"prompt_tokens"`
	ResponseTokens         int       `json:"response_tokens"`
	CacheWritePromptTokens int       `json:"cache_write_prompt_tokens"` // Anthropic cache writes
	CacheReadPromptTokens  int       `json:"cache_read_prompt_tokens"`  // Anthropic cache reads
	TotalTokens            int       `json:"total_tokens"`
	Cost                   float64   `json:"cost"`     // Cost in USD
	Currency               string    `json:"currency"` // Usually "USD"
	AppID                  uint      `json:"app_id"`
	UserID                 uint      `json:"user_id"`
	Timestamp              time.Time `json:"timestamp"`
	ToolCalls              int       `json:"tool_calls"`    // Number of tool calls in request
	Choices                int       `json:"choices"`       // Number of response choices
	TotalTimeMS            int       `json:"total_time_ms"` // Request latency in milliseconds
	RequestID              string    `json:"request_id"`    // Unique request identifier
	StatusCode             int       `json:"status_code"`   // HTTP status code (e.g., 200, 403 for budget exceeded)

	// Request/response data (optional - for pulse transmission)
	RequestBody  string `json:"request_body,omitempty"`  // Request body (optional)
	ResponseBody string `json:"response_body,omitempty"` // Response body (optional)

	// Failover marker: the primary LLM this attempt was failing over from and
	// the 1-based rung index. nil / 0 for a primary attempt. Carried so the
	// pulse can report the marker to the hub's ProxyLog.
	FailoverFromLLMID *uint `json:"failover_from_llm_id,omitempty"`
	FailoverAttempt   int   `json:"failover_attempt,omitempty"`

	// Routing decision, when the request was addressed to a router: its kind
	// and slug, the pool or route chosen, and why.
	RouterKind          string  `json:"router_kind,omitempty"`
	RouterSlug          string  `json:"router_slug,omitempty"`
	RouterPool          string  `json:"router_pool,omitempty"`
	Route               string  `json:"route,omitempty"`
	RouteReason         string  `json:"route_reason,omitempty"`
	RouterSourceModel   string  `json:"router_source_model,omitempty"`
	RouterTargetModel   string  `json:"router_target_model,omitempty"`
	RouterSelectionAlgo string  `json:"router_selection_algo,omitempty"`
	RouteScore          float64 `json:"route_score,omitempty"`  // Semantic Router: similarity that decided an embedding match
	ShadowRoute         string  `json:"shadow_route,omitempty"` // Semantic Router shadow mode: the route the classifier picked
	OnBehalfOf          string  `json:"on_behalf_of,omitempty"` // who the call was for, when an auth plugin said (audit only)
	ActingAgent         string  `json:"acting_agent,omitempty"` // the agent that made it, when an auth plugin said (audit only)
}

type AuthPlugin interface {
	BasePlugin

	// Authenticate performs authentication based on the provided request
	Authenticate(ctx context.Context, req *AuthRequest, pluginCtx *PluginContext) (*AuthResponse, error)

	// ValidateToken validates a specific token (if the plugin supports token-based auth)
	ValidateToken(ctx context.Context, token string, pluginCtx *PluginContext) (*AuthResponse, error)
}

type AuthRequest struct {
	Credential string         `json:"credential"`
	AuthType   string         `json:"auth_type"` // "token", "bearer", "api-key", etc.
	Request    *PluginRequest `json:"request"`
}

type AuthResponse struct {
	Authenticated bool              `json:"authenticated"`
	UserID        string            `json:"user_id,omitempty"`
	AppID         string            `json:"app_id,omitempty"`
	Claims        map[string]string `json:"claims,omitempty"`
	ErrorMessage  string            `json:"error_message,omitempty"`
}

type BasePlugin interface {
	// Initialize initializes the plugin with configuration
	Initialize(config map[string]interface{}) error

	// GetHookType returns the hook type this plugin implements
	GetHookType() HookType

	// GetName returns the plugin name
	GetName() string

	// GetVersion returns the plugin version
	GetVersion() string

	// Shutdown performs cleanup when plugin is unloaded
	Shutdown() error
}

type BudgetUsageData struct {
	AppID            uint      `json:"app_id"`
	LLMID            uint      `json:"llm_id"`
	TokensUsed       int64     `json:"tokens_used"`       // Total tokens consumed
	Cost             float64   `json:"cost"`              // Cost in USD
	RequestsCount    int       `json:"requests_count"`    // Number of requests
	PromptTokens     int64     `json:"prompt_tokens"`     // Input tokens
	CompletionTokens int64     `json:"completion_tokens"` // Output tokens
	PeriodStart      time.Time `json:"period_start"`      // Budget period start
	PeriodEnd        time.Time `json:"period_end"`        // Budget period end
	Timestamp        time.Time `json:"timestamp"`         // When this usage occurred
	RequestID        string    `json:"request_id"`        // Unique request identifier
}

type ConfigSchemaProvider interface {
	// GetConfigSchema returns the JSON Schema for this plugin's configuration
	// The schema should follow the JSON Schema specification (jsonschema.org)
	GetConfigSchema() ([]byte, error)
}

type DataCollectionHookType string

type DataCollectionPlugin interface {
	BasePlugin

	// HandleProxyLog processes proxy request/response logs
	// This is called for every LLM request/response that goes through the gateway
	HandleProxyLog(ctx context.Context, req *ProxyLogData, pluginCtx *PluginContext) (*DataCollectionResponse, error)

	// HandleAnalytics processes token usage and cost data
	// This is called when recording LLM usage for billing and analytics
	HandleAnalytics(ctx context.Context, req *AnalyticsData, pluginCtx *PluginContext) (*DataCollectionResponse, error)

	// HandleBudgetUsage processes budget usage tracking data
	// This is called when updating budget usage for apps and LLMs
	HandleBudgetUsage(ctx context.Context, req *BudgetUsageData, pluginCtx *PluginContext) (*DataCollectionResponse, error)
}

type DataCollectionResponse struct {
	// Success indicates if the plugin processed the data successfully
	Success bool `json:"success"`

	// Handled indicates if the plugin processed the data
	// If true and ReplaceDatabase is configured, database storage may be skipped
	Handled bool `json:"handled"`

	// ErrorMessage provides details if Success is false
	ErrorMessage string `json:"error_message"`

	// Metadata can contain plugin-specific response data
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type EnrichedRequest struct {
	*PluginRequest
	UserID        string            `json:"user_id,omitempty"`
	AppID         string            `json:"app_id,omitempty"`
	AuthClaims    map[string]string `json:"auth_claims,omitempty"`
	Authenticated bool              `json:"authenticated"`
}

type HeadersRequest struct {
	Headers map[string]string `json:"headers"`
	Context *PluginContext    `json:"context"`
}

type HeadersResponse struct {
	Modified bool              `json:"modified"`
	Headers  map[string]string `json:"headers"`
}

type HookType string

type PluginContext struct {
	RequestID    string                 `json:"request_id"`
	LLMID        uint                   `json:"llm_id"`
	LLMSlug      string                 `json:"llm_slug"`
	Vendor       string                 `json:"vendor"`
	AppID        uint                   `json:"app_id"`
	UserID       uint                   `json:"user_id,omitempty"`
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
	TraceContext map[string]string      `json:"trace_context,omitempty"`
}

type PluginRequest struct {
	Method     string            `json:"method"`
	Path       string            `json:"path"`
	Headers    map[string]string `json:"headers"`
	Body       []byte            `json:"body"`
	RemoteAddr string            `json:"remote_addr"`
	Context    *PluginContext    `json:"context"`
}

type PluginResponse struct {
	Modified       bool              `json:"modified"`
	StatusCode     int               `json:"status_code"`
	Headers        map[string]string `json:"headers,omitempty"`
	Body           []byte            `json:"body,omitempty"`
	Block          bool              `json:"block"` // Stop processing if true
	ErrorMessage   string            `json:"error_message,omitempty"`
	ContextUpdates map[string]string `json:"context_updates,omitempty"` // Updates to request context (e.g., upstream_override)
}

type PostAuthPlugin interface {
	BasePlugin

	// ProcessRequest processes the request after successful authentication
	ProcessRequest(ctx context.Context, req *EnrichedRequest, pluginCtx *PluginContext) (*PluginResponse, error)
}

type PreAuthPlugin interface {
	BasePlugin

	// ProcessRequest processes the incoming request before authentication
	ProcessRequest(ctx context.Context, req *PluginRequest, pluginCtx *PluginContext) (*PluginResponse, error)
}

type ProxyLogData struct {
	AppID        uint      `json:"app_id"`
	UserID       uint      `json:"user_id"`
	Vendor       string    `json:"vendor"`        // e.g., "openai", "anthropic"
	RequestBody  []byte    `json:"request_body"`  // Full request JSON
	ResponseBody []byte    `json:"response_body"` // Full response JSON
	ResponseCode int       `json:"response_code"` // HTTP status code
	Timestamp    time.Time `json:"timestamp"`
	RequestID    string    `json:"request_id"` // Unique request identifier
}

type ResponseData struct {
	RequestID  string            `json:"request_id"`
	StatusCode int               `json:"status_code"`
	Headers    map[string]string `json:"headers"`
	Body       []byte            `json:"body"`
	Context    *PluginContext    `json:"context"`
	LatencyMs  int64             `json:"latency_ms"`
}

type ResponsePlugin interface {
	BasePlugin

	// OnBeforeWriteHeaders is called before response headers are written (fast path)
	// Use this for header-only modifications without processing the body
	OnBeforeWriteHeaders(ctx context.Context, req *HeadersRequest, pluginCtx *PluginContext) (*HeadersResponse, error)

	// OnBeforeWrite is called before response body is written (full path)
	// Use this for body modifications or combined header+body modifications
	// isStreamChunk indicates if this is a streaming chunk (true) or complete response (false)
	OnBeforeWrite(ctx context.Context, req *ResponseWriteRequest, pluginCtx *PluginContext) (*ResponseWriteResponse, error)
}

type ResponseWriteRequest struct {
	Body          []byte            `json:"body"`
	Headers       map[string]string `json:"headers"`
	IsStreamChunk bool              `json:"is_stream_chunk"`
	Context       *PluginContext    `json:"context"`
}

type ResponseWriteResponse struct {
	Modified bool              `json:"modified"`
	Body     []byte            `json:"body"`
	Headers  map[string]string `json:"headers"`
}