Types

interface GatelitClientConfig {
  gatewayUrl: string
  getToken: () => Promise<{
    token: string
    scheme: TokenScheme
  }>
}

type TokenScheme = "Bearer" | "GatelitSigned" | "GatelitKey"

interface ChatOptions {
  model: string                    // "provider/model-id"
  messages: ChatMessage[]          // At least one message
  maxTokens?: number               // Max output tokens
  temperature?: number             // 0–2
  signal?: AbortSignal             // For cancellation
  outputSchema?: {                 // Structured output config
    mode: "json_object" | "json_schema"
    [key: string]: unknown
  } | null
  promptId?: string                // Link to a saved prompt (UUID)
  endUserId?: string               // End-user ID for log filtering (header only)
  user?: string                    // End-user ID forwarded to the provider (OpenAI-standard `user` field)
  metadata?: Record<string, string | number | boolean>  // Arbitrary tags — stored on the log, filterable in the dashboard
  requestSource?: "api" | "dashboard" | "eval"
  cache?: boolean | { ttl: number }  // Opt-in exact-match response cache (deterministic requests only)
}

type ChatMessageContent =
  | string
  | ChatMessageContentPart[]

interface ChatMessage {
  role: "system" | "user" | "assistant"
  content: ChatMessageContent
}

type ChatMessageContentPart =
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: { url: string } }
  | { type: "file"; file: {
      mime_type?: string
      file_data?: string
      file_id?: string
      url?: string
    } }

interface ChatResponse {
  content: string
  model: string
  usage: Usage | null
  finishReason: string | null
  meta: GatelitMeta
}

interface StreamChunk {
  delta: string
  model: string | undefined
  finishReason: string | null
  usage: Usage | null
  usedFallback?: boolean    // true when a fallback model handled the request
  fallbackReason?: string   // provider_error | rate_limit | timeout | refusal_detected | cache
  fallbackModel?: string    // the fallback model that responded
  clampedParams?: Record<string, string>  // present when the gateway clamped a param
}

interface Usage {
  inputTokens: number
  outputTokens: number
  totalTokens: number
}

interface GatelitMeta {
  requestId: string
  model: string
  usedFallback?: boolean    // true when a fallback model handled the request
  fallbackReason?: string   // provider_error | rate_limit | timeout | refusal_detected | cache
  fallbackModel?: string    // the fallback model that responded
  clampedParams?: Record<string, string>  // e.g. { max_tokens: "10000->4096" } when the gateway clamped a param
  cacheHit?: boolean        // true when the response was served from the gateway cache
}

class GatelitError extends Error {
  code: string      // "unauthorized" | "gateway_error" | "provider_error" | "invalid_json"
  message: string
  status: number    // HTTP status
}

interface ConversationOptions {
  model: string
  systemPrompt?: string
  maxTokens?: number
  temperature?: number
  tools?: Tool[]
  toolChoice?: ToolChoice
  endUserId?: string
  metadata?: RequestMetadata
  user?: string
  cache?: boolean | { ttl: number }  // Opt-in exact-match response cache
}