@modelrelay/sdk 0.7.0 → 0.17.0

package/dist/index.d.ts

@@ -22,33 +22,8 @@ type KnownStopReason = (typeof StopReasons)[keyof typeof StopReasons];
 type StopReason = KnownStopReason | {
     other: string;
 };
-declare const Providers: {
-    readonly OpenAI: "openai";
-    readonly Anthropic: "anthropic";
-    readonly Grok: "grok";
-    readonly Echo: "echo";
-};
-type KnownProvider = (typeof Providers)[keyof typeof Providers];
-type ProviderId = KnownProvider | {
-    other: string;
-};
-declare const Models: {
-    readonly OpenAIGpt4o: "openai/gpt-4o";
-    readonly OpenAIGpt4oMini: "openai/gpt-4o-mini";
-    readonly OpenAIGpt51: "openai/gpt-5.1";
-    readonly AnthropicClaude35HaikuLatest: "anthropic/claude-3-5-haiku-latest";
-    readonly AnthropicClaude35SonnetLatest: "anthropic/claude-3-5-sonnet-latest";
-    readonly AnthropicClaudeOpus45: "anthropic/claude-opus-4-5-20251101";
-    readonly AnthropicClaude35Haiku: "anthropic/claude-3.5-haiku";
-    readonly Grok2: "grok-2";
-    readonly Grok4_1FastNonReasoning: "grok-4-1-fast-non-reasoning";
-    readonly Grok4_1FastReasoning: "grok-4-1-fast-reasoning";
-    readonly Echo1: "echo-1";
-};
-type KnownModel = (typeof Models)[keyof typeof Models];
-type ModelId = KnownModel | {
-    other: string;
-} | string;
+type ProviderId = string;
+type ModelId = string;
 /**
  * Common configuration options for the ModelRelay client.
  */
@@ -238,6 +213,10 @@ interface Usage {
     outputTokens: number;
     totalTokens: number;
 }
+/**
+ * Creates a Usage object with automatic totalTokens calculation if not provided.
+ */
+declare function createUsage(inputTokens: number, outputTokens: number, totalTokens?: number): Usage;
 interface UsageSummary {
     plan: string;
     planType?: string;
@@ -265,11 +244,17 @@ interface ChatMessage {
 }
 declare const ToolTypes: {
     readonly Function: "function";
+    readonly Web: "web";
     readonly WebSearch: "web_search";
     readonly XSearch: "x_search";
     readonly CodeExecution: "code_execution";
 };
 type ToolType = (typeof ToolTypes)[keyof typeof ToolTypes];
+declare const WebToolModes: {
+    readonly Search: "search";
+    readonly Browse: "browse";
+};
+type WebToolMode = (typeof WebToolModes)[keyof typeof WebToolModes];
 interface FunctionTool {
     name: string;
     description?: string;
@@ -279,6 +264,7 @@ interface WebSearchConfig {
     allowedDomains?: string[];
     excludedDomains?: string[];
     maxUses?: number;
+    mode?: string;
 }
 interface XSearchConfig {
     allowedHandles?: string[];
@@ -294,6 +280,8 @@ interface Tool {
     type: ToolType;
     function?: FunctionTool;
     webSearch?: WebSearchConfig;
+    /** Alias for webSearch - used in API normalization */
+    web?: WebSearchConfig;
     xSearch?: XSearchConfig;
     codeExecution?: CodeExecConfig;
 }
@@ -315,10 +303,25 @@ interface ToolCall {
     type: ToolType;
     function?: FunctionCall;
 }
+declare const ResponseFormatTypes: {
+    readonly Text: "text";
+    readonly JsonObject: "json_object";
+    readonly JsonSchema: "json_schema";
+};
+type ResponseFormatType = (typeof ResponseFormatTypes)[keyof typeof ResponseFormatTypes];
+interface ResponseJSONSchemaFormat {
+    name: string;
+    description?: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+}
+interface ResponseFormat {
+    type: ResponseFormatType;
+    json_schema?: ResponseJSONSchemaFormat;
+}
 interface ChatCompletionCreateParams {
     model: ModelId;
     messages: NonEmptyArray<ChatMessage>;
-    provider?: ProviderId;
     maxTokens?: number;
     temperature?: number;
     metadata?: Record<string, string>;
@@ -336,6 +339,11 @@ interface ChatCompletionCreateParams {
      * When using publishable keys, a customer id is required to mint a frontend token.
      */
     customerId?: string;
+    /**
+     * Structured outputs configuration. When set with type `json_object` or
+     * `json_schema`, the backend validates and returns structured JSON.
+     */
+    responseFormat?: ResponseFormat;
     /**
      * Opt out of SSE streaming and request a blocking JSON response.
      */
@@ -347,7 +355,6 @@ interface ChatCompletionCreateParams {
 }
 interface ChatCompletionResponse {
     id: string;
-    provider?: ProviderId;
     content: string[];
     stopReason?: StopReason;
     model?: ModelId;
@@ -374,7 +381,6 @@ type TransportErrorKind = "timeout" | "connect" | "request" | "other";
 interface RequestContext {
     method: string;
     path: string;
-    provider?: ProviderId;
     model?: ModelId;
     requestId?: string;
     responseId?: string;
@@ -422,8 +428,6 @@ declare function mergeMetrics(base?: MetricsCallbacks, override?: MetricsCallbac
 declare function mergeTrace(base?: TraceCallbacks, override?: TraceCallbacks): TraceCallbacks | undefined;
 declare function normalizeStopReason(value?: unknown): StopReason | undefined;
 declare function stopReasonToString(value?: StopReason): string | undefined;
-declare function normalizeProvider(value?: unknown): ProviderId | undefined;
-declare function providerToString(value?: ProviderId): string | undefined;
 declare function normalizeModelId(value: unknown): ModelId | undefined;
 declare function modelToString(value: ModelId): string;
 type ChatEventType = "message_start" | "message_delta" | "message_stop" | "tool_use_start" | "tool_use_delta" | "tool_use_stop" | "ping" | "custom";
@@ -477,6 +481,12 @@ interface ChatCompletionEvent<T = unknown> {
     requestId?: string;
     raw: string;
 }
+type StructuredJSONRecordType = "start" | "update" | "completion" | "error";
+interface StructuredJSONEvent<T> {
+    type: "update" | "completion";
+    payload: T;
+    requestId?: string;
+}
 interface APIFrontendToken {
     token: string;
     expires_at?: string;
@@ -507,7 +517,6 @@ interface APIChatUsage {
 }
 interface APIChatResponse {
     id?: string;
-    provider?: string;
     content?: string | string[];
     stop_reason?: string;
     model?: string;
@@ -615,6 +624,14 @@ interface AuthHeaders {
     apiKey?: string;
     accessToken?: string;
 }
+/**
+ * Creates AuthHeaders with an API key.
+ */
+declare function createApiKeyAuth(apiKey: string): AuthHeaders;
+/**
+ * Creates AuthHeaders with an access token.
+ */
+declare function createAccessTokenAuth(accessToken: string): AuthHeaders;
 declare class AuthClient {
     private readonly http;
     private readonly apiKey?;
@@ -703,6 +720,13 @@ declare class ChatCompletionsClient {
         stream: false;
     }): Promise<ChatCompletionResponse>;
     create(params: ChatCompletionCreateParams, options?: ChatRequestOptions): Promise<ChatCompletionsStream>;
+    /**
+     * Stream structured JSON responses using the NDJSON contract defined for
+     * /llm/proxy. The request must include a structured responseFormat.
+     */
+    streamJSON<T>(params: ChatCompletionCreateParams & {
+        responseFormat: ResponseFormat;
+    }, options?: ChatRequestOptions): Promise<StructuredJSONStream<T>>;
 }
 declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent> {
     private readonly response;
@@ -720,6 +744,21 @@ declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent
     private enrichContext;
     private recordFirstToken;
 }
+declare class StructuredJSONStream<T> implements AsyncIterable<StructuredJSONEvent<T>> {
+    private readonly response;
+    private readonly requestId?;
+    private context;
+    private readonly metrics?;
+    private readonly trace?;
+    private closed;
+    private sawTerminal;
+    constructor(response: Response, requestId: string | undefined, context: RequestContext, metrics?: MetricsCallbacks, trace?: TraceCallbacks);
+    cancel(reason?: unknown): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<StructuredJSONEvent<T>>;
+    collect(): Promise<T>;
+    private parseRecord;
+    private traceStructuredEvent;
+}
 
 /**
  * Customer metadata as an arbitrary key-value object.
@@ -734,7 +773,7 @@ interface Customer {
     tier_id: string;
     tier_code?: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
     stripe_customer_id?: string;
     stripe_subscription_id?: string;
@@ -750,7 +789,7 @@ interface Customer {
 interface CustomerCreateRequest {
     tier_id: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
 }
 /**
@@ -759,9 +798,18 @@ interface CustomerCreateRequest {
 interface CustomerUpsertRequest {
     tier_id: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
 }
+/**
+ * Request to claim a customer by email, setting their external_id.
+ * Used when a customer subscribes via Stripe Checkout (email only) and later
+ * authenticates to the app, needing to link their identity.
+ */
+interface CustomerClaimRequest {
+    email: string;
+    external_id: string;
+}
 /**
  * Request to create a checkout session.
  */
@@ -816,6 +864,15 @@ declare class CustomersClient {
      * Otherwise, a new customer is created.
      */
     upsert(request: CustomerUpsertRequest): Promise<Customer>;
+    /**
+     * Claim a customer by email, setting their external_id.
+     * Used when a customer subscribes via Stripe Checkout (email only) and later
+     * authenticates to the app, needing to link their identity.
+     *
+     * @throws {APIError} with status 404 if customer not found by email
+     * @throws {APIError} with status 409 if customer already claimed or external_id in use
+     */
+    claim(request: CustomerClaimRequest): Promise<Customer>;
     /**
      * Delete a customer by ID.
      */
@@ -873,6 +930,24 @@ declare class TiersClient {
     get(tierId: string): Promise<Tier>;
 }
 
+/**
+ * API error codes returned by the server.
+ * These constants can be used for programmatic error handling.
+ */
+declare const ErrorCodes: {
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly CONFLICT: "CONFLICT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type ErrorCategory = "config" | "transport" | "api";
 declare class ModelRelayError extends Error {
     category: ErrorCategory;
@@ -914,9 +989,41 @@ declare class APIError extends ModelRelayError {
         data?: unknown;
         retries?: RetryMetadata;
     });
+    /** Returns true if the error is a not found error. */
+    isNotFound(): boolean;
+    /** Returns true if the error is a validation error. */
+    isValidation(): boolean;
+    /** Returns true if the error is a rate limit error. */
+    isRateLimit(): boolean;
+    /** Returns true if the error is an unauthorized error. */
+    isUnauthorized(): boolean;
+    /** Returns true if the error is a forbidden error. */
+    isForbidden(): boolean;
+    /** Returns true if the error is a service unavailable error. */
+    isUnavailable(): boolean;
 }
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
+/**
+ * Creates a user message.
+ */
+declare function createUserMessage(content: string): ChatMessage;
+/**
+ * Creates an assistant message.
+ */
+declare function createAssistantMessage(content: string): ChatMessage;
+/**
+ * Creates a system message.
+ */
+declare function createSystemMessage(content: string): ChatMessage;
+/**
+ * Creates a tool call object.
+ */
+declare function createToolCall(id: string, name: string, args: string, type?: ToolType): ToolCall;
+/**
+ * Creates a function call object.
+ */
+declare function createFunctionCall(name: string, args: string): FunctionCall;
 /**
  * Interface for Zod-like schema types.
  * Compatible with Zod's ZodType and similar libraries.
@@ -988,9 +1095,10 @@ declare function createFunctionToolFromSchema(name: string, description: string,
  */
 declare function createFunctionTool(name: string, description: string, parameters?: Record<string, unknown>): Tool;
 /**
- * Creates a web search tool with optional domain filters.
+ * Creates a web tool with optional domain filters and mode.
  */
-declare function createWebSearchTool(options?: {
+declare function createWebTool(options?: {
+    mode?: WebToolMode;
     allowedDomains?: string[];
     excludedDomains?: string[];
     maxUses?: number;
@@ -1322,4 +1430,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, AuthClient, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type ErrorCategory, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownModel, type KnownProvider, type KnownStopReason, type MessageDeltaData, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, Models, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, Providers, type RequestContext, type RetryConfig, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, type SubscriptionStatus, type Tier, TiersClient, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type WebSearchConfig, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createWebSearchTool, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeProvider, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, providerToString, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };
+export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, type CustomerClaimRequest, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownStopReason, type MessageDeltaData, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, type RequestContext, type ResponseFormat, type ResponseFormatType, ResponseFormatTypes, type ResponseJSONSchemaFormat, type RetryConfig, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, type StructuredJSONEvent, type StructuredJSONRecordType, StructuredJSONStream, type SubscriptionStatus, type Tier, TiersClient, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type WebSearchConfig, type WebToolMode, WebToolModes, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };