@modelrelay/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -3,7 +3,54 @@ declare const DEFAULT_BASE_URL = "https://api.modelrelay.ai/api/v1";
 declare const STAGING_BASE_URL = "https://api-stg.modelrelay.ai/api/v1";
 declare const SANDBOX_BASE_URL = "https://api.sandbox.modelrelay.ai/api/v1";
 declare const DEFAULT_CLIENT_HEADER: string;
+declare const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+type NonEmptyArray<T> = [T, ...T[]];
+declare const StopReasons: {
+    readonly Completed: "completed";
+    readonly Stop: "stop";
+    readonly StopSequence: "stop_sequence";
+    readonly EndTurn: "end_turn";
+    readonly MaxTokens: "max_tokens";
+    readonly MaxLength: "max_len";
+    readonly MaxContext: "max_context";
+    readonly ToolCalls: "tool_calls";
+    readonly TimeLimit: "time_limit";
+    readonly ContentFilter: "content_filter";
+    readonly Incomplete: "incomplete";
+    readonly Unknown: "unknown";
+};
+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 OpenRouter: "openrouter";
+    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 OpenRouterClaude35Haiku: "anthropic/claude-3.5-haiku";
+    readonly Grok2: "grok-2";
+    readonly Grok4Fast: "grok-4-fast";
+    readonly Echo1: "echo-1";
+};
+type KnownModel = (typeof Models)[keyof typeof Models];
+type ModelId = KnownModel | {
+    other: string;
+} | string;
 interface ModelRelayOptions {
     /**
      * API key (secret or publishable). Publishable keys are required for frontend token exchange.
@@ -20,13 +67,17 @@ interface ModelRelayOptions {
     baseUrl?: string;
     fetch?: typeof fetch;
     /**
-     * Default end-user metadata used when exchanging publishable keys for frontend tokens.
+     * Default customer metadata used when exchanging publishable keys for frontend tokens.
      */
-    endUser?: FrontendIdentity;
+    customer?: FrontendCustomer;
     /**
      * Optional client header override for telemetry.
      */
     clientHeader?: string;
+    /**
+     * Default connect timeout in milliseconds (applies to each attempt).
+     */
+    connectTimeoutMs?: number;
     /**
      * Default request timeout in milliseconds (non-streaming). Set to 0 to disable.
      */
@@ -43,16 +94,24 @@ interface ModelRelayOptions {
      * Default metadata merged into every chat completion request.
      */
     defaultMetadata?: Record<string, string>;
+    /**
+     * Optional metrics callbacks for latency/usage.
+     */
+    metrics?: MetricsCallbacks;
+    /**
+     * Optional trace/log hooks for request + stream lifecycle.
+     */
+    trace?: TraceCallbacks;
 }
 type Environment = "production" | "staging" | "sandbox";
-interface FrontendIdentity {
+interface FrontendCustomer {
     id: string;
     deviceId?: string;
     ttlSeconds?: number;
 }
 interface FrontendTokenRequest {
     publishableKey?: string;
-    userId: string;
+    customerId: string;
     deviceId?: string;
     ttlSeconds?: number;
 }
@@ -66,9 +125,9 @@ interface FrontendToken {
     tokenScope?: string[];
     tokenSource?: string;
     /**
-     * The end-user identifier used when issuing the token. Added client-side for caching.
+     * The customer identifier used when issuing the token. Added client-side for caching.
      */
-    endUserId?: string;
+    customerId?: string;
     /**
      * Publishable key used for issuance. Added client-side for caching.
      */
@@ -78,53 +137,47 @@ interface FrontendToken {
      */
     deviceId?: string;
 }
-interface CheckoutRequest {
-    endUserId: string;
-    deviceId?: string;
-    planId?: string;
-    plan?: string;
-    successUrl: string;
-    cancelUrl: string;
-}
-interface CheckoutSession {
-    id: string;
-    plan: string;
-    status: string;
-    url: string;
-    expiresAt?: Date;
-    completedAt?: Date;
-}
-interface EndUserRef {
-    id: string;
-    externalId: string;
-    ownerId: string;
-}
-interface CheckoutResponse {
-    endUser: EndUserRef;
-    session: CheckoutSession;
-}
 interface Usage {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
 }
+interface UsageSummary {
+    plan: string;
+    planType?: string;
+    windowStart?: Date | string;
+    windowEnd?: Date | string;
+    limit?: number;
+    used?: number;
+    actionsLimit?: number;
+    actionsUsed?: number;
+    remaining?: number;
+    state?: string;
+}
+interface Project {
+    id: string;
+    name: string;
+    description?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
 interface ChatMessage {
     role: string;
     content: string;
 }
 interface ChatCompletionCreateParams {
-    model: string;
-    messages: ChatMessage[];
-    provider?: string;
+    model: ModelId;
+    messages: NonEmptyArray<ChatMessage>;
+    provider?: ProviderId;
     maxTokens?: number;
     temperature?: number;
     metadata?: Record<string, string>;
     stop?: string[];
     stopSequences?: string[];
     /**
-     * When using publishable keys, an end-user id is required to mint a frontend token.
+     * When using publishable keys, a customer id is required to mint a frontend token.
      */
-    endUserId?: string;
+    customerId?: string;
     /**
      * Opt out of SSE streaming and request a blocking JSON response.
      */
@@ -136,10 +189,10 @@ interface ChatCompletionCreateParams {
 }
 interface ChatCompletionResponse {
     id: string;
-    provider: string;
+    provider?: ProviderId;
     content: string[];
-    stopReason?: string;
-    model: string;
+    stopReason?: StopReason;
+    model?: ModelId;
     usage: Usage;
     requestId?: string;
 }
@@ -153,6 +206,67 @@ interface RetryConfig {
     maxBackoffMs?: number;
     retryPost?: boolean;
 }
+interface RetryMetadata {
+    attempts: number;
+    lastStatus?: number;
+    lastError?: string;
+}
+type TransportErrorKind = "timeout" | "connect" | "request" | "other";
+interface RequestContext {
+    method: string;
+    path: string;
+    provider?: ProviderId;
+    model?: ModelId;
+    requestId?: string;
+    responseId?: string;
+}
+interface HttpRequestMetrics {
+    latencyMs: number;
+    status?: number;
+    error?: string;
+    retries?: RetryMetadata;
+    context: RequestContext;
+}
+interface StreamFirstTokenMetrics {
+    latencyMs: number;
+    error?: string;
+    context: RequestContext;
+}
+interface TokenUsageMetrics {
+    usage: Usage;
+    context: RequestContext;
+}
+interface MetricsCallbacks {
+    httpRequest?: (metrics: HttpRequestMetrics) => void;
+    streamFirstToken?: (metrics: StreamFirstTokenMetrics) => void;
+    usage?: (metrics: TokenUsageMetrics) => void;
+}
+interface TraceCallbacks {
+    requestStart?: (context: RequestContext) => void;
+    requestFinish?: (info: {
+        context: RequestContext;
+        status?: number;
+        error?: unknown;
+        retries?: RetryMetadata;
+        latencyMs: number;
+    }) => void;
+    streamEvent?: (info: {
+        context: RequestContext;
+        event: ChatCompletionEvent;
+    }) => void;
+    streamError?: (info: {
+        context: RequestContext;
+        error: unknown;
+    }) => void;
+}
+declare function mergeMetrics(base?: MetricsCallbacks, override?: MetricsCallbacks): MetricsCallbacks | undefined;
+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" | "ping" | "custom";
 interface MessageStartData {
     responseId?: string;
@@ -170,10 +284,10 @@ interface MessageDeltaData {
     [key: string]: unknown;
 }
 interface MessageStopData {
-    stopReason?: string;
+    stopReason?: StopReason;
     usage?: Usage;
     responseId?: string;
-    model?: string;
+    model?: ModelId;
     [key: string]: unknown;
 }
 interface ChatCompletionEvent<T = unknown> {
@@ -182,8 +296,8 @@ interface ChatCompletionEvent<T = unknown> {
     data?: T;
     textDelta?: string;
     responseId?: string;
-    model?: string;
-    stopReason?: string;
+    model?: ModelId;
+    stopReason?: StopReason;
     usage?: Usage;
     requestId?: string;
     raw: string;
@@ -191,21 +305,14 @@ interface ChatCompletionEvent<T = unknown> {
 interface APIFrontendToken {
     token: string;
     expires_at?: string;
-    expiresAt?: string;
     expires_in?: number;
-    expiresIn?: number;
     token_type?: string;
-    tokenType?: string;
     key_id?: string;
-    keyId?: string;
     session_id?: string;
-    sessionId?: string;
     token_scope?: string[];
-    tokenScope?: string[];
     token_source?: string;
-    tokenSource?: string;
 }
-interface APIEndUserRef {
+interface APICustomerRef {
     id: string;
     external_id: string;
     owner_id: string;
@@ -218,28 +325,19 @@ interface APICheckoutSession {
     expires_at?: string;
     completed_at?: string;
 }
-interface APICheckoutResponse {
-    end_user?: APIEndUserRef;
-    session?: APICheckoutSession;
-}
 interface APIChatUsage {
     input_tokens?: number;
     output_tokens?: number;
     total_tokens?: number;
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
 }
 interface APIChatResponse {
     id?: string;
     provider?: string;
     content?: string | string[];
     stop_reason?: string;
-    stopReason?: string;
     model?: string;
     usage?: APIChatUsage;
     response_id?: string;
-    responseId?: string;
     message?: {
         id?: string;
         model?: string;
@@ -261,11 +359,6 @@ interface APIKey {
     redactedKey: string;
     secretKey?: string;
 }
-interface APIKeyCreateRequest {
-    label: string;
-    expiresAt?: Date;
-    kind?: string;
-}
 
 interface RequestOptions {
     method?: string;
@@ -288,6 +381,26 @@ interface RequestOptions {
      * When false, skip the default client timeout (useful for streaming).
      */
     useDefaultTimeout?: boolean;
+    /**
+     * Override the per-request connect timeout in milliseconds (set to 0 to disable).
+     */
+    connectTimeoutMs?: number;
+    /**
+     * When false, skip the default connect timeout for this request.
+     */
+    useDefaultConnectTimeout?: boolean;
+    /**
+     * Per-request metrics callbacks merged over client defaults.
+     */
+    metrics?: MetricsCallbacks;
+    /**
+     * Per-request trace/log hooks merged over client defaults.
+     */
+    trace?: TraceCallbacks;
+    /**
+     * Optional request context metadata to propagate to telemetry.
+     */
+    context?: Partial<RequestContext>;
 }
 declare class HTTPClient {
     private readonly baseUrl;
@@ -296,18 +409,24 @@ declare class HTTPClient {
     private readonly fetchImpl?;
     private readonly clientHeader?;
     private readonly defaultTimeoutMs;
+    private readonly defaultConnectTimeoutMs;
     private readonly retry?;
     private readonly defaultHeaders;
+    private readonly metrics?;
+    private readonly trace?;
     constructor(cfg: {
         baseUrl?: string;
         apiKey?: string;
         accessToken?: string;
         fetchImpl?: typeof fetch;
         clientHeader?: string;
+        connectTimeoutMs?: number;
         timeoutMs?: number;
         retry?: RetryConfig | false;
         defaultHeaders?: Record<string, string>;
         environment?: Environment;
+        metrics?: MetricsCallbacks;
+        trace?: TraceCallbacks;
     });
     request(path: string, options?: RequestOptions): Promise<Response>;
     json<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -316,7 +435,7 @@ declare class HTTPClient {
 interface AuthConfig {
     apiKey?: string;
     accessToken?: string;
-    endUser?: FrontendIdentity;
+    customer?: FrontendCustomer;
 }
 interface AuthHeaders {
     apiKey?: string;
@@ -326,7 +445,7 @@ declare class AuthClient {
     private readonly http;
     private readonly apiKey?;
     private readonly accessToken?;
-    private readonly endUser?;
+    private readonly customer?;
     private cachedFrontend;
     constructor(http: HTTPClient, cfg: AuthConfig);
     /**
@@ -338,7 +457,7 @@ declare class AuthClient {
      * Determine the correct auth headers for chat completions.
      * Publishable keys are automatically exchanged for frontend tokens.
      */
-    authForChat(endUserId?: string, overrides?: Partial<FrontendIdentity>): Promise<AuthHeaders>;
+    authForChat(customerId?: string, overrides?: Partial<FrontendCustomer>): Promise<AuthHeaders>;
     /**
      * Billing calls accept either bearer tokens or API keys (including publishable keys).
      */
@@ -346,24 +465,6 @@ declare class AuthClient {
 }
 declare function isPublishableKey(value?: string | null): boolean;
 
-declare class ApiKeysClient {
-    private readonly http;
-    constructor(http: HTTPClient);
-    list(): Promise<APIKey[]>;
-    create(req: APIKeyCreateRequest): Promise<APIKey>;
-    delete(id: string): Promise<void>;
-}
-
-declare class BillingClient {
-    private readonly http;
-    private readonly auth;
-    constructor(http: HTTPClient, auth: AuthClient);
-    /**
-     * Initiate a Stripe Checkout session for an end user.
-     */
-    checkout(params: CheckoutRequest): Promise<CheckoutResponse>;
-}
-
 interface ChatRequestOptions {
     /**
      * Abort the HTTP request and stream consumption.
@@ -389,22 +490,38 @@ interface ChatRequestOptions {
      * Override the per-request timeout in milliseconds (set to 0 to disable).
      */
     timeoutMs?: number;
+    /**
+     * Override the connect timeout in milliseconds (set to 0 to disable).
+     */
+    connectTimeoutMs?: number;
     /**
      * Override retry behavior for this call. Set to `false` to disable retries.
      */
     retry?: RetryConfig | false;
+    /**
+     * Per-call metrics callbacks (merged over client defaults).
+     */
+    metrics?: MetricsCallbacks;
+    /**
+     * Per-call trace/log hooks (merged over client defaults).
+     */
+    trace?: TraceCallbacks;
 }
 declare class ChatClient {
     readonly completions: ChatCompletionsClient;
     constructor(http: HTTPClient, auth: AuthClient, cfg?: {
         defaultMetadata?: Record<string, string>;
+        metrics?: MetricsCallbacks;
+        trace?: TraceCallbacks;
     });
 }
 declare class ChatCompletionsClient {
     private readonly http;
     private readonly auth;
     private readonly defaultMetadata?;
-    constructor(http: HTTPClient, auth: AuthClient, defaultMetadata?: Record<string, string>);
+    private readonly metrics?;
+    private readonly trace?;
+    constructor(http: HTTPClient, auth: AuthClient, defaultMetadata?: Record<string, string>, metrics?: MetricsCallbacks, trace?: TraceCallbacks);
     create(params: ChatCompletionCreateParams & {
         stream: false;
     }, options?: ChatRequestOptions): Promise<ChatCompletionResponse>;
@@ -416,34 +533,179 @@ declare class ChatCompletionsClient {
 declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent> {
     private readonly response;
     private readonly requestId?;
+    private context;
+    private readonly metrics?;
+    private readonly trace?;
+    private readonly startedAt;
+    private firstTokenEmitted;
     private closed;
-    constructor(response: Response, requestId?: string);
+    constructor(response: Response, requestId: string | undefined, context: RequestContext, metrics?: MetricsCallbacks, trace?: TraceCallbacks);
     cancel(reason?: unknown): Promise<void>;
     [Symbol.asyncIterator](): AsyncIterator<ChatCompletionEvent>;
+    private handleStreamEvent;
+    private enrichContext;
+    private recordFirstToken;
+}
+
+/**
+ * Customer metadata as an arbitrary key-value object.
+ */
+type CustomerMetadata = Record<string, unknown>;
+/**
+ * Customer represents a customer in a ModelRelay project.
+ */
+interface Customer {
+    id: string;
+    project_id: string;
+    tier_id: string;
+    tier_code?: string;
+    external_id: string;
+    email?: string;
+    metadata?: CustomerMetadata;
+    stripe_customer_id?: string;
+    stripe_subscription_id?: string;
+    subscription_status?: string;
+    current_period_start?: string;
+    current_period_end?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Request to create a customer.
+ */
+interface CustomerCreateRequest {
+    tier_id: string;
+    external_id: string;
+    email?: string;
+    metadata?: CustomerMetadata;
+}
+/**
+ * Request to upsert a customer by external_id.
+ */
+interface CustomerUpsertRequest {
+    tier_id: string;
+    external_id: string;
+    email?: string;
+    metadata?: CustomerMetadata;
+}
+/**
+ * Request to create a checkout session.
+ */
+interface CheckoutSessionRequest {
+    success_url: string;
+    cancel_url: string;
+}
+/**
+ * Checkout session response.
+ */
+interface CheckoutSession {
+    session_id: string;
+    url: string;
+}
+/**
+ * Subscription status response.
+ */
+interface SubscriptionStatus {
+    active: boolean;
+    subscription_id?: string;
+    status?: string;
+    current_period_start?: string;
+    current_period_end?: string;
+}
+interface CustomersClientConfig {
+    apiKey?: string;
+}
+/**
+ * CustomersClient provides methods to manage customers in a project.
+ * Requires a secret key (mr_sk_*) for authentication.
+ */
+declare class CustomersClient {
+    private readonly http;
+    private readonly apiKey?;
+    constructor(http: HTTPClient, cfg: CustomersClientConfig);
+    private ensureSecretKey;
+    /**
+     * List all customers in the project.
+     */
+    list(): Promise<Customer[]>;
+    /**
+     * Create a new customer in the project.
+     */
+    create(request: CustomerCreateRequest): Promise<Customer>;
+    /**
+     * Get a customer by ID.
+     */
+    get(customerId: string): Promise<Customer>;
+    /**
+     * Upsert a customer by external_id.
+     * If a customer with the given external_id exists, it is updated.
+     * Otherwise, a new customer is created.
+     */
+    upsert(request: CustomerUpsertRequest): Promise<Customer>;
+    /**
+     * Delete a customer by ID.
+     */
+    delete(customerId: string): Promise<void>;
+    /**
+     * Create a Stripe checkout session for a customer.
+     */
+    createCheckoutSession(customerId: string, request: CheckoutSessionRequest): Promise<CheckoutSession>;
+    /**
+     * Get the subscription status for a customer.
+     */
+    getSubscription(customerId: string): Promise<SubscriptionStatus>;
 }
 
+type ErrorCategory = "config" | "transport" | "api";
 declare class ModelRelayError extends Error {
-    status: number;
+    category: ErrorCategory;
+    status?: number;
     code?: string;
     requestId?: string;
     fields?: FieldError[];
     data?: unknown;
+    retries?: RetryMetadata;
+    cause?: unknown;
+    constructor(message: string, opts: {
+        category: ErrorCategory;
+        status?: number;
+        code?: string;
+        requestId?: string;
+        fields?: FieldError[];
+        data?: unknown;
+        retries?: RetryMetadata;
+        cause?: unknown;
+    });
+}
+declare class ConfigError extends ModelRelayError {
+    constructor(message: string, data?: unknown);
+}
+declare class TransportError extends ModelRelayError {
+    kind: TransportErrorKind;
+    constructor(message: string, opts: {
+        kind: TransportErrorKind;
+        retries?: RetryMetadata;
+        cause?: unknown;
+    });
+}
+declare class APIError extends ModelRelayError {
     constructor(message: string, opts: {
         status: number;
         code?: string;
         requestId?: string;
         fields?: FieldError[];
         data?: unknown;
+        retries?: RetryMetadata;
     });
 }
+declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
 declare class ModelRelay {
-    readonly billing: BillingClient;
     readonly chat: ChatClient;
     readonly auth: AuthClient;
-    readonly apiKeys: ApiKeysClient;
+    readonly customers: CustomersClient;
     readonly baseUrl: string;
     constructor(options: ModelRelayOptions);
 }
 
-export { type APIChatResponse, type APIChatUsage, type APICheckoutResponse, type APICheckoutSession, type APIEndUserRef, type APIFrontendToken, type APIKey, type APIKeyCreateRequest, ApiKeysClient, AuthClient, BillingClient, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutRequest, type CheckoutResponse, type CheckoutSession, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_REQUEST_TIMEOUT_MS, type EndUserRef, type Environment, type FieldError, type FrontendIdentity, type FrontendToken, type FrontendTokenRequest, type MessageDeltaData, type MessageStartData, type MessageStopData, ModelRelay, ModelRelayError, type ModelRelayOptions, type RetryConfig, SANDBOX_BASE_URL, SDK_VERSION, STAGING_BASE_URL, type Usage, isPublishableKey };
+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, 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 Environment, type ErrorCategory, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenRequest, type HttpRequestMetrics, type KnownModel, type KnownProvider, type KnownStopReason, type MessageDeltaData, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, ModelRelayError, type ModelRelayOptions, Models, type NonEmptyArray, type Project, type ProviderId, Providers, type RequestContext, type RetryConfig, type RetryMetadata, SANDBOX_BASE_URL, SDK_VERSION, STAGING_BASE_URL, type StopReason, StopReasons, type StreamFirstTokenMetrics, type SubscriptionStatus, type TokenUsageMetrics, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeProvider, normalizeStopReason, parseErrorResponse, providerToString, stopReasonToString };