/** A JSON Schema object. */ export type JsonSchema = Record; /** Any valid JSON value. */ export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue; }; /** Configuration for the Opper SDK client. */ export interface ClientConfig { /** API key for authentication. Falls back to OPPER_API_KEY env var. */ readonly apiKey?: string; /** Base URL for the API. Falls back to OPPER_BASE_URL env var, then https://api.opper.ai */ readonly baseUrl?: string; /** Additional headers to include in requests. */ readonly headers?: Record; } /** Options for HTTP requests. */ export interface RequestOptions { /** Additional headers for this request. */ readonly headers?: Record; /** AbortSignal for request cancellation. */ readonly signal?: AbortSignal; /** Timeout in milliseconds, overrides client default. */ readonly timeout?: number; } /** Error detail returned by the API. */ export interface ErrorDetail { readonly code: string; readonly message: string; readonly details?: unknown; } /** Error response wrapper from the API. */ export interface ErrorResponse { readonly error: ErrorDetail; } /** API error with status code and structured error info. */ export declare class ApiError extends Error { readonly status: number; readonly statusText: string; readonly body: unknown; constructor(status: number, statusText: string, body: unknown); /** Parsed error detail from the response body, if available. */ get error(): ErrorDetail | undefined; /** @internal */ static parseDetail(body: unknown): ErrorDetail | undefined; } /** 400 Bad Request — invalid input or malformed request. */ export declare class BadRequestError extends ApiError { constructor(statusText: string, body: unknown); } /** 401 Unauthorized — missing or invalid API key. */ export declare class AuthenticationError extends ApiError { constructor(statusText: string, body: unknown); } /** 404 Not Found — the requested resource does not exist. */ export declare class NotFoundError extends ApiError { constructor(statusText: string, body: unknown); } /** 429 Too Many Requests — rate limit exceeded. */ export declare class RateLimitError extends ApiError { constructor(statusText: string, body: unknown); } /** 500 Internal Server Error — something went wrong on the server. */ export declare class InternalServerError extends ApiError { constructor(statusText: string, body: unknown); } /** A JSON Schema or a Standard Schema (Zod, Valibot, ArkType, etc.). */ export type SchemaLike = JsonSchema | import("./schema.js").StandardSchemaV1; /** * Extended model configuration with provider-specific options. * * @example * ```typescript * { name: "anthropic/claude-sonnet-4-6", options: { max_tokens: 1000 } } * ``` */ export interface ModelConfig { /** Model identifier (e.g. `"openai/gpt-4o"`). */ readonly name: string; /** Provider-specific parameters (temperature, max_tokens, reasoning_effort, etc.). */ readonly options?: Record; /** Extra HTTP headers to send with requests to this model. */ readonly extra_headers?: Record; } /** * Model specification: a model identifier string, a {@link ModelConfig} object * with provider-specific options, or an array of either for fallback chains. * * @example * ```typescript * // Simple string * model: "anthropic/claude-sonnet-4-6" * * // With options * model: { name: "anthropic/claude-sonnet-4-6", options: { max_tokens: 500 } } * * // Fallback chain — models tried in order on retriable errors * model: ["anthropic/claude-sonnet-4-6", { name: "openai/gpt-4o", options: { temperature: 0.7 } }] * ``` */ export type Model = string | ModelConfig | (string | ModelConfig)[]; /** Tool definition for function execution. */ export interface Tool { readonly name: string; readonly description?: string; readonly parameters?: SchemaLike; readonly type?: string; } /** Token usage information. */ export interface UsageInfo { readonly input_tokens: number; readonly output_tokens: number; readonly reasoning_tokens?: number; readonly cache_read_tokens?: number; readonly cache_creation_tokens?: number; readonly cache_creation_1h_tokens?: number; readonly input_audio_tokens?: number; readonly output_audio_tokens?: number; } /** An async operation that is still in progress. */ export interface PendingOperation { readonly id: string; readonly status_url: string; readonly type: string; } /** Status of an async artifact generation. */ export interface ArtifactStatus { readonly id: string; readonly status: "processing" | "completed" | "failed"; readonly url?: string; readonly mime_type?: string; readonly error?: string; } /** Response metadata from function execution. */ export interface ResponseMeta { readonly function_name: string; readonly script_cached: boolean; readonly execution_ms: number; readonly llm_calls: number; readonly tts_calls: number; readonly image_gen_calls: number; readonly generation_ms?: number; readonly cost?: number; readonly usage?: UsageInfo; readonly models_used?: string[]; readonly model_warnings?: string[]; readonly guards?: unknown[]; readonly tool_calls?: unknown[]; readonly message?: string; readonly status?: string; readonly pending_operations?: PendingOperation[]; } /** Request to run a function. */ export interface RunRequest { /** JSON Schema or Standard Schema describing the input shape. Defaults to text when omitted. */ readonly input_schema?: SchemaLike; /** JSON Schema or Standard Schema describing the expected output shape. Defaults to text when omitted. */ readonly output_schema?: SchemaLike; /** The input data to send to the function. */ readonly input: JsonValue; /** Model to use — a string, a {@link ModelConfig} with provider-specific options, or a fallback chain. */ readonly model?: Model; /** Sampling temperature (0–2). Lower = more deterministic. */ readonly temperature?: number; /** Maximum tokens in the response. */ readonly max_tokens?: number; /** Reasoning effort hint for reasoning-capable models. */ readonly reasoning_effort?: "low" | "medium" | "high"; /** Opt into thought summary streaming, e.g. `"auto"`. */ readonly reasoning_summary?: string; /** Instructions for the function. */ readonly instructions?: string; /** Parent span ID for tracing/observability. */ readonly parent_span_id?: string; /** Tool definitions available to the function. */ readonly tools?: Tool[]; } /** Request to run a function with a Standard Schema for output type inference. */ export interface SchemaRunRequest { /** Standard Schema (Zod, Valibot, ArkType, etc.) or raw JSON Schema defining the expected output shape. */ readonly output_schema: import("./schema.js").StandardSchemaV1 | JsonSchema; /** The input data to send to the function. */ readonly input: JsonValue; /** JSON Schema or Standard Schema describing the input shape. Defaults to text when omitted. */ readonly input_schema?: SchemaLike; /** Model to use — a string, a {@link ModelConfig} with provider-specific options, or a fallback chain. */ readonly model?: Model; /** Sampling temperature (0–2). Lower = more deterministic. */ readonly temperature?: number; /** Maximum tokens in the response. */ readonly max_tokens?: number; /** Reasoning effort hint for reasoning-capable models. */ readonly reasoning_effort?: "low" | "medium" | "high"; /** Opt into thought summary streaming, e.g. `"auto"`. */ readonly reasoning_summary?: string; /** Instructions for the function. */ readonly instructions?: string; /** Parent span ID for tracing/observability. */ readonly parent_span_id?: string; /** Tool definitions available to the function. */ readonly tools?: Tool[]; } /** Response from running a function. */ export interface RunResponse { readonly data: T; readonly meta?: ResponseMeta; } /** SSE stream chunk: content text delta. */ export interface ContentChunk { readonly type: "content"; readonly delta: string; readonly tool_call_index?: number; } /** SSE stream chunk: start of a tool call. */ export interface ToolCallStartChunk { readonly type: "tool_call_start"; readonly tool_call_index: number; readonly tool_call_id: string; readonly tool_call_name: string; } /** SSE stream chunk: incremental tool call arguments. */ export interface ToolCallDeltaChunk { readonly type: "tool_call_delta"; readonly tool_call_index: number; readonly tool_call_args: string; readonly tool_call_thought_sig?: string; } /** SSE stream chunk: stream completed. */ export interface DoneChunk { readonly type: "done"; readonly usage?: UsageInfo; readonly tool_call_index?: number; } /** SSE stream chunk: error occurred. */ export interface ErrorChunk { readonly type: "error"; readonly error: string; } /** SSE stream chunk: final parsed result from `event: complete`. */ export interface CompleteChunk { readonly type: "complete"; readonly data: T; readonly meta?: ResponseMeta; } /** SSE stream chunk from /stream endpoint. */ export type StreamChunk = ContentChunk | ToolCallStartChunk | ToolCallDeltaChunk | DoneChunk | ErrorChunk | CompleteChunk; /** Request to update a function. */ export interface UpdateFunctionRequest { readonly source: string; } /** Detailed function information including schemas. */ export interface FunctionDetails { readonly name: string; readonly schema_hash: string; readonly generated_at: string; readonly hit_count: number; readonly source: string; readonly input_schema: JsonSchema; readonly output_schema: JsonSchema; } /** Summary function information. */ export interface FunctionInfo { readonly name: string; readonly schema_hash: string; readonly generated_at: string; readonly hit_count: number; readonly has_script: boolean; } /** Function revision with schema details. */ export interface FunctionRevision { readonly revision_id: number; readonly source: string; readonly schema_hash: string; readonly created_at: string; readonly input_schema: JsonSchema; readonly output_schema: JsonSchema; } /** Revision info summary. */ export interface RevisionInfo { readonly revision_id: number; readonly created_at: string; readonly schema_hash: string; readonly is_current: boolean; } /** Server-side turn detection (VAD) configuration. */ export interface RealtimeTurnDetection { /** Detection strategy, e.g. `"server_vad"`. */ readonly type: string; /** Voice activation threshold, 0..1. */ readonly threshold?: number; /** Audio prepended to the start of detected speech, in ms. */ readonly prefix_padding_ms?: number; /** Silence required to end a turn, in ms. */ readonly silence_duration_ms?: number; } /** A tool definition exposed to the realtime model. */ export interface RealtimeTool { readonly name: string; readonly description?: string; readonly parameters?: Record; } /** * Session configuration bound at ticket-mint time or sent inline on * `session.start` for server-side connections. */ export interface RealtimeSessionConfig { /** Opper model id, e.g. `"openai/gpt-realtime-2"`. */ readonly model?: string; /** System instructions for the session. */ readonly instructions?: string; /** Voice id (model-specific). */ readonly voice?: string; /** Active modalities, e.g. `["audio", "text"]`. */ readonly modalities?: ReadonlyArray; /** Sampling temperature. */ readonly temperature?: number; /** Reasoning effort for reasoning-capable models. */ readonly reasoning_effort?: string; /** PCM audio format for inbound audio, e.g. `"pcm16"`. */ readonly input_audio_format?: string; /** PCM audio format for outbound audio. */ readonly output_audio_format?: string; /** Enable transcription of user audio. */ readonly input_transcription?: boolean; /** Provider-specific transcription model. */ readonly input_transcription_model?: string; /** Enable transcription of model audio. */ readonly output_transcription?: boolean; /** Server-side turn detection (VAD) settings. */ readonly turn_detection?: RealtimeTurnDetection; /** Tools the model may call during the session. */ readonly tools?: ReadonlyArray; } /** Body for `POST /v3/realtime-sessions`. */ export interface CreateRealtimeSessionRequest { /** Fields locked to the ticket; the browser cannot override them at session.start. */ readonly config?: RealtimeSessionConfig; /** * Field names whose zero value must stay zero (e.g. force `output_transcription` off). * Fields not listed remain open for the browser to fill in. */ readonly locked_fields?: ReadonlyArray; /** Ticket lifetime in seconds. */ readonly ttl_seconds?: number; } /** Response from `POST /v3/realtime-sessions`. */ export interface RealtimeSession { /** Single-use ticket secret. */ readonly client_secret: string; /** Expiry timestamp (ISO 8601). */ readonly expires_at: string; /** Optional fully-qualified WS URL. */ readonly ws_url?: string; } /** Request to create a span. */ export interface CreateSpanRequest { readonly name: string; readonly trace_id?: string; readonly parent_id?: string; readonly type?: string; readonly input?: string; readonly output?: string; readonly error?: string; readonly start_time?: string | Date; readonly end_time?: string | Date; readonly meta?: Record; readonly metadata?: Record; readonly tags?: Record; } /** Response from creating a span. */ export interface CreateSpanResponse { readonly id: string; readonly trace_id: string; readonly name: string; readonly parent_id?: string; readonly type?: string; } /** Request to update a span. */ export interface UpdateSpanRequest { readonly output?: string; readonly error?: string; readonly end_time?: string | Date; readonly meta?: Record; readonly metadata?: Record; readonly tags?: Record; } /** Options for the `traced()` method. */ export interface TracedOptions { /** Name for the trace span. Defaults to `"traced"`. */ readonly name?: string; /** Input to record on the span. */ readonly input?: string; /** Custom metadata for the span. */ readonly meta?: Record; /** Tags for filtering. */ readonly tags?: Record; } /** Handle to the current span inside a `traced()` callback. */ export interface SpanHandle { /** The span ID. */ readonly id: string; /** The trace ID. */ readonly traceId: string; } /** A single embedding data item. */ export interface EmbeddingsDataItem { readonly object: string; readonly index: number; readonly embedding: number[]; } /** Token usage for embeddings requests. */ export interface EmbeddingsUsageInfo { readonly prompt_tokens: number; readonly total_tokens: number; } /** Embeddings request. */ export interface EmbeddingsRequest { readonly input: string | string[]; readonly model: string; readonly dimensions?: number; readonly encoding_format?: string; readonly user?: string; } /** Embeddings response. */ export interface EmbeddingsResponse { readonly object: string; readonly data: EmbeddingsDataItem[]; readonly model: string; readonly usage: EmbeddingsUsageInfo; } /** Information about an available model. */ export interface ModelInfo { readonly id: string; readonly name: string; readonly provider: string; readonly aliases?: string[]; readonly capabilities?: Record; readonly pricing?: Record; readonly parameters?: Record; /** Model family/series (e.g. "gpt-4", "claude-sonnet-4"). */ readonly family?: string; /** Maximum output tokens supported by the model. */ readonly max_output_tokens?: number; /** Whether the model supports reasoning/thinking. */ readonly thinking?: boolean; /** Date when this model will be or was retired. */ readonly retired_at?: string; } /** Response containing list of models. */ export interface ModelsResponse { readonly models: ModelInfo[]; } /** Query parameters for listing generations. */ export interface ListGenerationsParams { readonly query?: string; readonly page?: number; readonly page_size?: number; } /** Request to fetch a URL. */ export interface WebFetchRequest { readonly url: string; } /** Response from fetching a URL. */ export interface WebFetchResponse { readonly content: string; } /** Request to search the web. */ export interface WebSearchRequest { readonly query: string; } /** A single web search result. */ export interface WebSearchResult { readonly title: string; readonly url: string; readonly snippet: string; } /** Response from a web search. */ export interface WebSearchResponse { readonly results: WebSearchResult[]; } /** Paginated response wrapper. */ export interface PaginatedResponse { readonly data: T[]; readonly meta: { readonly total_count: number; }; } /** Request to create a knowledge base. */ export interface CreateKnowledgeBaseRequest { readonly name: string; readonly embedding_model?: string; } /** Response from creating a knowledge base. */ export interface CreateKnowledgeBaseResponse { readonly id: string; readonly name: string; readonly created_at: string; readonly embedding_model: string; } /** Knowledge base summary in list responses. */ export interface KnowledgeBaseInfo { readonly id: string; readonly name: string; readonly created_at: string; readonly embedding_model: string; } /** Detailed knowledge base response including document count. */ export interface GetKnowledgeBaseResponse { readonly id: string; readonly name: string; readonly created_at: string; readonly embedding_model: string; readonly count: number; } /** Text processing configuration for chunking. */ export interface TextProcessingConfiguration { readonly chunk_size?: number; readonly chunk_overlap?: number; } /** Request to add a document to a knowledge base. */ export interface AddDocumentRequest { readonly content: string; readonly key?: string; readonly metadata?: Record; readonly configuration?: TextProcessingConfiguration; } /** Response from adding a document. */ export interface AddDocumentResponse { readonly id: string; readonly key: string; readonly metadata?: Record; } /** Filter operation for knowledge base queries. */ export type FilterOp = "=" | "!=" | ">" | "<" | "in"; /** A filter condition for knowledge base queries. */ export interface KnowledgeBaseFilter { readonly field: string; readonly operation: FilterOp; readonly value: string | number | (string | number)[]; } /** Request to query a knowledge base. */ export interface QueryKnowledgeBaseRequest { readonly query: string; readonly prefilter_limit?: number; readonly top_k?: number; readonly filters?: KnowledgeBaseFilter[]; readonly rerank?: boolean; readonly parent_span_id?: string; } /** A single query result from a knowledge base. */ export interface QueryKnowledgeBaseResponse { readonly id: string; readonly key: string; readonly content: string; readonly metadata: Record; readonly score: number; } /** A document segment. */ export interface DocumentSegment { readonly id: string; readonly content: string; } /** Response from getting a document by key. */ export interface GetDocumentResponse { readonly id: string; readonly key: string; readonly segments: DocumentSegment[]; readonly metadata?: Record; } /** Request to delete documents from a knowledge base. */ export interface DeleteDocumentsRequest { readonly filters?: KnowledgeBaseFilter[]; } /** Response from deleting documents. */ export interface DeleteDocumentsResponse { readonly deleted_count: number; } /** Response from getting a presigned upload URL. */ export interface GetUploadUrlResponse { readonly url: string; readonly fields: Record; readonly id: string; } /** Request to register a file after S3 upload. */ export interface RegisterFileUploadRequest { readonly filename: string; readonly file_id: string; readonly content_type: string; readonly configuration?: TextProcessingConfiguration; readonly metadata?: Record; } /** Response from registering a file upload. */ export interface RegisterFileUploadResponse { readonly id: string; readonly key: string; readonly original_filename: string; readonly document_id: number; readonly metadata?: Record; } /** Response from direct file upload. */ export interface UploadFileResponse { readonly id: string; readonly key: string; readonly original_filename: string; readonly document_id: number; readonly metadata?: Record; } /** File information in list responses. */ export interface ListFilesResponse { readonly id: string; readonly original_filename: string; readonly size: number; readonly status: string; readonly document_id: number; readonly metadata: Record; } /** Query parameters for listing traces. */ export interface ListTracesParams { /** Max items to return (default 100, max 100). */ readonly limit?: number; /** Number of items to skip (default 0). */ readonly offset?: number; /** Filter by trace name (case-insensitive substring match). */ readonly name?: string; } /** A trace item in list responses. */ export interface ListTracesItem { readonly id: string; readonly name?: string; readonly span_count: number; readonly start_time?: string; readonly end_time?: string; readonly duration_ms?: number; readonly status?: string; } /** Response from listing traces. */ export interface ListTracesResponse { readonly data: ListTracesItem[]; readonly meta: { readonly total_count: number; }; } /** Span details within a trace. */ export interface TraceSpan { readonly id: string; readonly trace_id: string; readonly name: string; readonly parent_id?: string; readonly type?: string; readonly input?: unknown; readonly output?: unknown; readonly error?: string; readonly start_time?: string; readonly end_time?: string; readonly created_at?: string; readonly status?: string; readonly meta?: Record; readonly metadata?: Record; readonly tags?: Record; } /** Response from getting a single trace with all its spans. */ export interface GetTraceResponse { readonly id: string; readonly name?: string; readonly span_count: number; readonly spans: TraceSpan[]; readonly start_time?: string; readonly end_time?: string; readonly duration_ms?: number; readonly status?: string; } /** Response from getting a single span. */ export interface GetSpanResponse { readonly id: string; readonly trace_id: string; readonly name: string; readonly parent_id?: string; readonly type?: string; readonly input?: unknown; readonly output?: unknown; readonly error?: string; readonly start_time?: string; readonly end_time?: string; readonly status?: string; readonly meta?: Record; readonly metadata?: Record; readonly tags?: Record; }