@modelrelay/sdk 0.14.1 → 0.18.0

package/dist/index.d.cts

@@ -22,34 +22,8 @@ type KnownStopReason = (typeof StopReasons)[keyof typeof StopReasons];
 type StopReason = KnownStopReason | {
     other: string;
 };
-declare const Providers: {
-    readonly OpenAI: "openai";
-    readonly Anthropic: "anthropic";
-    readonly XAI: "xai";
-    readonly GoogleAIStudio: "google-ai-studio";
-    readonly Echo: "echo";
-};
-type KnownProvider = (typeof Providers)[keyof typeof Providers];
-type ProviderId = KnownProvider | {
-    other: string;
-};
-declare const Models: {
-    readonly Gpt4o: "gpt-4o";
-    readonly Gpt4oMini: "gpt-4o-mini";
-    readonly Gpt51: "gpt-5.1";
-    readonly Claude35HaikuLatest: "claude-3-5-haiku-latest";
-    readonly Claude35SonnetLatest: "claude-3-5-sonnet-latest";
-    readonly ClaudeOpus45: "claude-opus-4-5";
-    readonly Claude35Haiku: "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;
-};
+type ProviderId = string;
+type ModelId = string;
 /**
  * Common configuration options for the ModelRelay client.
  */
@@ -271,21 +245,26 @@ 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;
     parameters?: Record<string, unknown>;
 }
-type WebToolMode = "auto" | "search_only" | "fetch_only" | "search_and_fetch";
-interface WebToolConfig {
+interface WebSearchConfig {
     allowedDomains?: string[];
     excludedDomains?: string[];
     maxUses?: number;
-    mode?: WebToolMode;
+    mode?: string;
 }
 interface XSearchConfig {
     allowedHandles?: string[];
@@ -300,7 +279,9 @@ interface CodeExecConfig {
 interface Tool {
     type: ToolType;
     function?: FunctionTool;
-    web?: WebToolConfig;
+    webSearch?: WebSearchConfig;
+    /** Alias for webSearch - used in API normalization */
+    web?: WebSearchConfig;
     xSearch?: XSearchConfig;
     codeExecution?: CodeExecConfig;
 }
@@ -322,13 +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 to use for the request. Optional - if omitted, the tier's default model is used.
-     */
-    model?: KnownModel;
+    model: ModelId;
     messages: NonEmptyArray<ChatMessage>;
-    provider?: ProviderId;
     maxTokens?: number;
     temperature?: number;
     metadata?: Record<string, string>;
@@ -346,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.
      */
@@ -357,7 +355,6 @@ interface ChatCompletionCreateParams {
 }
 interface ChatCompletionResponse {
     id: string;
-    provider?: ProviderId;
     content: string[];
     stopReason?: StopReason;
     model?: ModelId;
@@ -384,7 +381,6 @@ type TransportErrorKind = "timeout" | "connect" | "request" | "other";
 interface RequestContext {
     method: string;
     path: string;
-    provider?: ProviderId;
     model?: ModelId;
     requestId?: string;
     responseId?: string;
@@ -432,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";
@@ -487,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;
@@ -517,7 +517,6 @@ interface APIChatUsage {
 }
 interface APIChatResponse {
     id?: string;
-    provider?: string;
     content?: string | string[];
     stop_reason?: string;
     model?: string;
@@ -721,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;
@@ -738,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.
@@ -780,6 +801,15 @@ interface CustomerUpsertRequest {
     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.
  */
@@ -834,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.
      */
@@ -869,6 +908,21 @@ interface Tier {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Request to create a tier checkout session (Stripe-first flow).
+ */
+interface TierCheckoutRequest {
+    email: string;
+    success_url: string;
+    cancel_url: string;
+}
+/**
+ * Tier checkout session response.
+ */
+interface TierCheckoutSession {
+    session_id: string;
+    url: string;
+}
 interface TiersClientConfig {
     apiKey?: string;
 }
@@ -881,6 +935,7 @@ declare class TiersClient {
     private readonly apiKey?;
     constructor(http: HTTPClient, cfg: TiersClientConfig);
     private ensureApiKey;
+    private ensureSecretKey;
     /**
      * List all tiers in the project.
      */
@@ -889,6 +944,20 @@ declare class TiersClient {
      * Get a tier by ID.
      */
     get(tierId: string): Promise<Tier>;
+    /**
+     * Create a Stripe checkout session for a tier (Stripe-first flow).
+     *
+     * This enables users to subscribe before authenticating. After checkout
+     * completes, a customer record is created with the provided email. The
+     * customer can later be linked to an identity via POST /customers/claim.
+     *
+     * Requires a secret key (mr_sk_*).
+     *
+     * @param tierId - The tier ID to create a checkout session for
+     * @param request - Checkout session request with email and redirect URLs
+     * @returns Checkout session with Stripe URL
+     */
+    checkout(tierId: string, request: TierCheckoutRequest): Promise<TierCheckoutSession>;
 }
 
 /**
@@ -1391,4 +1460,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-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 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 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 WebToolConfig, type WebToolMode, 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, 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, type TierCheckoutRequest, type TierCheckoutSession, 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 };

package/dist/index.d.ts

@@ -22,34 +22,8 @@ type KnownStopReason = (typeof StopReasons)[keyof typeof StopReasons];
 type StopReason = KnownStopReason | {
     other: string;
 };
-declare const Providers: {
-    readonly OpenAI: "openai";
-    readonly Anthropic: "anthropic";
-    readonly XAI: "xai";
-    readonly GoogleAIStudio: "google-ai-studio";
-    readonly Echo: "echo";
-};
-type KnownProvider = (typeof Providers)[keyof typeof Providers];
-type ProviderId = KnownProvider | {
-    other: string;
-};
-declare const Models: {
-    readonly Gpt4o: "gpt-4o";
-    readonly Gpt4oMini: "gpt-4o-mini";
-    readonly Gpt51: "gpt-5.1";
-    readonly Claude35HaikuLatest: "claude-3-5-haiku-latest";
-    readonly Claude35SonnetLatest: "claude-3-5-sonnet-latest";
-    readonly ClaudeOpus45: "claude-opus-4-5";
-    readonly Claude35Haiku: "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;
-};
+type ProviderId = string;
+type ModelId = string;
 /**
  * Common configuration options for the ModelRelay client.
  */
@@ -271,21 +245,26 @@ 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;
     parameters?: Record<string, unknown>;
 }
-type WebToolMode = "auto" | "search_only" | "fetch_only" | "search_and_fetch";
-interface WebToolConfig {
+interface WebSearchConfig {
     allowedDomains?: string[];
     excludedDomains?: string[];
     maxUses?: number;
-    mode?: WebToolMode;
+    mode?: string;
 }
 interface XSearchConfig {
     allowedHandles?: string[];
@@ -300,7 +279,9 @@ interface CodeExecConfig {
 interface Tool {
     type: ToolType;
     function?: FunctionTool;
-    web?: WebToolConfig;
+    webSearch?: WebSearchConfig;
+    /** Alias for webSearch - used in API normalization */
+    web?: WebSearchConfig;
     xSearch?: XSearchConfig;
     codeExecution?: CodeExecConfig;
 }
@@ -322,13 +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 to use for the request. Optional - if omitted, the tier's default model is used.
-     */
-    model?: KnownModel;
+    model: ModelId;
     messages: NonEmptyArray<ChatMessage>;
-    provider?: ProviderId;
     maxTokens?: number;
     temperature?: number;
     metadata?: Record<string, string>;
@@ -346,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.
      */
@@ -357,7 +355,6 @@ interface ChatCompletionCreateParams {
 }
 interface ChatCompletionResponse {
     id: string;
-    provider?: ProviderId;
     content: string[];
     stopReason?: StopReason;
     model?: ModelId;
@@ -384,7 +381,6 @@ type TransportErrorKind = "timeout" | "connect" | "request" | "other";
 interface RequestContext {
     method: string;
     path: string;
-    provider?: ProviderId;
     model?: ModelId;
     requestId?: string;
     responseId?: string;
@@ -432,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";
@@ -487,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;
@@ -517,7 +517,6 @@ interface APIChatUsage {
 }
 interface APIChatResponse {
     id?: string;
-    provider?: string;
     content?: string | string[];
     stop_reason?: string;
     model?: string;
@@ -721,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;
@@ -738,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.
@@ -780,6 +801,15 @@ interface CustomerUpsertRequest {
     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.
  */
@@ -834,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.
      */
@@ -869,6 +908,21 @@ interface Tier {
     created_at: string;
     updated_at: string;
 }
+/**
+ * Request to create a tier checkout session (Stripe-first flow).
+ */
+interface TierCheckoutRequest {
+    email: string;
+    success_url: string;
+    cancel_url: string;
+}
+/**
+ * Tier checkout session response.
+ */
+interface TierCheckoutSession {
+    session_id: string;
+    url: string;
+}
 interface TiersClientConfig {
     apiKey?: string;
 }
@@ -881,6 +935,7 @@ declare class TiersClient {
     private readonly apiKey?;
     constructor(http: HTTPClient, cfg: TiersClientConfig);
     private ensureApiKey;
+    private ensureSecretKey;
     /**
      * List all tiers in the project.
      */
@@ -889,6 +944,20 @@ declare class TiersClient {
      * Get a tier by ID.
      */
     get(tierId: string): Promise<Tier>;
+    /**
+     * Create a Stripe checkout session for a tier (Stripe-first flow).
+     *
+     * This enables users to subscribe before authenticating. After checkout
+     * completes, a customer record is created with the provided email. The
+     * customer can later be linked to an identity via POST /customers/claim.
+     *
+     * Requires a secret key (mr_sk_*).
+     *
+     * @param tierId - The tier ID to create a checkout session for
+     * @param request - Checkout session request with email and redirect URLs
+     * @returns Checkout session with Stripe URL
+     */
+    checkout(tierId: string, request: TierCheckoutRequest): Promise<TierCheckoutSession>;
 }
 
 /**
@@ -1391,4 +1460,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-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 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 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 WebToolConfig, type WebToolMode, 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, 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, type TierCheckoutRequest, type TierCheckoutSession, 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 };