@modelrelay/sdk 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -64,6 +64,10 @@ __export(index_exports, {
   getRetryableErrors: () => getRetryableErrors,
   hasRetryableErrors: () => hasRetryableErrors,
   hasToolCalls: () => hasToolCalls,
+  isEmailRequired: () => isEmailRequired,
+  isNoFreeTier: () => isNoFreeTier,
+  isNoTiers: () => isNoTiers,
+  isProvisioningError: () => isProvisioningError,
   isPublishableKey: () => isPublishableKey,
   mergeMetrics: () => mergeMetrics,
   mergeTrace: () => mergeTrace,
@@ -100,7 +104,9 @@ var ErrorCodes = {
   /** No tiers configured for the project - create a tier first. */
   NO_TIERS: "NO_TIERS",
   /** No free tier available for auto-provisioning - create a free tier or use checkout flow. */
-  NO_FREE_TIER: "NO_FREE_TIER"
+  NO_FREE_TIER: "NO_FREE_TIER",
+  /** Email required for auto-provisioning a new customer. */
+  EMAIL_REQUIRED: "EMAIL_REQUIRED"
 };
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
@@ -185,14 +191,33 @@ var APIError = class extends ModelRelayError {
     return this.code === ErrorCodes.NO_FREE_TIER;
   }
   /**
-   * Returns true if this is a customer provisioning error (NO_TIERS or NO_FREE_TIER).
+   * Returns true if email is required for auto-provisioning a new customer.
+   * To resolve: provide the 'email' field in FrontendTokenRequest.
+   */
+  isEmailRequired() {
+    return this.code === ErrorCodes.EMAIL_REQUIRED;
+  }
+  /**
+   * Returns true if this is a customer provisioning error (NO_TIERS, NO_FREE_TIER, or EMAIL_REQUIRED).
    * These errors occur when calling frontendToken() with a customer that doesn't exist
    * and automatic provisioning cannot complete.
    */
   isProvisioningError() {
-    return this.isNoTiers() || this.isNoFreeTier();
+    return this.isNoTiers() || this.isNoFreeTier() || this.isEmailRequired();
   }
 };
+function isEmailRequired(err) {
+  return err instanceof APIError && err.isEmailRequired();
+}
+function isNoFreeTier(err) {
+  return err instanceof APIError && err.isNoFreeTier();
+}
+function isNoTiers(err) {
+  return err instanceof APIError && err.isNoTiers();
+}
+function isProvisioningError(err) {
+  return err instanceof APIError && err.isProvisioningError();
+}
 async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
   const fallbackMessage = response.statusText || "Request failed";
@@ -208,8 +233,8 @@ async function parseErrorResponse(response, retries) {
   try {
     const parsed = JSON.parse(bodyText);
     const parsedObj = typeof parsed === "object" && parsed !== null ? parsed : null;
-    if (parsedObj?.error) {
-      const errPayload = typeof parsedObj.error === "object" && parsedObj.error !== null ? parsedObj.error : null;
+    if (parsedObj?.error && typeof parsedObj.error === "object") {
+      const errPayload = parsedObj.error;
       const message = errPayload?.message || fallbackMessage;
       const code = errPayload?.code || void 0;
       const fields = Array.isArray(errPayload?.fields) ? errPayload?.fields : void 0;
@@ -261,20 +286,47 @@ var AuthClient = class {
     this.customer = cfg.customer;
   }
   /**
-   * Exchange a publishable key for a short-lived frontend token.
+   * Exchange a publishable key for a short-lived frontend token for an existing customer.
    * Tokens are cached until they are close to expiry.
+   *
+   * Use this method when the customer already exists in the system.
+   * For auto-provisioning new customers, use frontendTokenAutoProvision instead.
    */
   async frontendToken(request) {
-    const publishableKey = request?.publishableKey || (isPublishableKey(this.apiKey) ? this.apiKey : void 0);
-    if (!publishableKey) {
-      throw new ConfigError("publishable key required to issue frontend tokens");
+    if (!request.publishableKey?.trim()) {
+      throw new ConfigError("publishableKey is required");
+    }
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    return this.sendFrontendTokenRequest(request);
+  }
+  /**
+   * Exchange a publishable key for a frontend token, creating the customer if needed.
+   * The customer will be auto-provisioned on the project's free tier.
+   * Tokens are cached until they are close to expiry.
+   *
+   * Use this method when the customer may not exist and should be created automatically.
+   * The email is required for auto-provisioning.
+   */
+  async frontendTokenAutoProvision(request) {
+    if (!request.publishableKey?.trim()) {
+      throw new ConfigError("publishableKey is required");
+    }
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
     }
-    const customerId = request?.customerId || this.customer?.id;
-    if (!customerId) {
-      throw new ConfigError("customerId is required to mint a frontend token");
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required for auto-provisioning");
     }
-    const deviceId = request?.deviceId || this.customer?.deviceId;
-    const ttlSeconds = request?.ttlSeconds ?? this.customer?.ttlSeconds;
+    return this.sendFrontendTokenRequest(request);
+  }
+  /**
+   * Internal method to send frontend token requests.
+   */
+  async sendFrontendTokenRequest(request) {
+    const { publishableKey, customerId, deviceId, ttlSeconds } = request;
+    const email = "email" in request ? request.email : void 0;
     const cacheKey = `${publishableKey}:${customerId}:${deviceId || ""}`;
     const cached = this.cachedFrontend.get(cacheKey);
     if (cached && isTokenReusable(cached)) {
@@ -290,6 +342,9 @@ var AuthClient = class {
     if (typeof ttlSeconds === "number" && ttlSeconds > 0) {
       payload.ttl_seconds = ttlSeconds;
     }
+    if (email) {
+      payload.email = email;
+    }
     const response = await this.http.json(
       "/auth/frontend-token",
       {
@@ -317,10 +372,15 @@ var AuthClient = class {
       throw new ConfigError("API key or token is required");
     }
     if (isPublishableKey(this.apiKey)) {
+      const resolvedCustomerId = customerId || overrides?.id || this.customer?.id;
+      if (!resolvedCustomerId) {
+        throw new ConfigError("customerId is required to mint a frontend token");
+      }
       const token = await this.frontendToken({
-        customerId: customerId || overrides?.id,
-        deviceId: overrides?.deviceId,
-        ttlSeconds: overrides?.ttlSeconds
+        publishableKey: this.apiKey,
+        customerId: resolvedCustomerId,
+        deviceId: overrides?.deviceId || this.customer?.deviceId,
+        ttlSeconds: overrides?.ttlSeconds ?? this.customer?.ttlSeconds
       });
       return createAccessTokenAuth(token.token);
     }
@@ -374,7 +434,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.20.0",
+  version: "0.22.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -2538,6 +2598,10 @@ function resolveBaseUrl(override) {
   getRetryableErrors,
   hasRetryableErrors,
   hasToolCalls,
+  isEmailRequired,
+  isNoFreeTier,
+  isNoTiers,
+  isProvisioningError,
   isPublishableKey,
   mergeMetrics,
   mergeTrace,

package/dist/index.d.cts

@@ -180,10 +180,35 @@ interface FrontendCustomer {
     deviceId?: string;
     ttlSeconds?: number;
 }
+/**
+ * Request for fetching a frontend token for an existing customer.
+ * Use this when the customer already exists in the system.
+ */
 interface FrontendTokenRequest {
-    publishableKey?: string;
+    /** Publishable key (mr_pk_*) - required for authentication. */
+    publishableKey: string;
+    /** Customer identifier - required to issue a token for this customer. */
+    customerId: string;
+    /** Optional device identifier for tracking/rate limiting. */
+    deviceId?: string;
+    /** Optional TTL in seconds for the issued token. */
+    ttlSeconds?: number;
+}
+/**
+ * Request for fetching a frontend token with auto-provisioning.
+ * Use this when the customer may not exist and should be created on the free tier.
+ * The email is required for auto-provisioning.
+ */
+interface FrontendTokenAutoProvisionRequest {
+    /** Publishable key (mr_pk_*) - required for authentication. */
+    publishableKey: string;
+    /** Customer identifier - required to issue a token for this customer. */
     customerId: string;
+    /** Email address - required for auto-provisioning a new customer. */
+    email: string;
+    /** Optional device identifier for tracking/rate limiting. */
     deviceId?: string;
+    /** Optional TTL in seconds for the issued token. */
     ttlSeconds?: number;
 }
 interface FrontendToken {
@@ -640,10 +665,26 @@ declare class AuthClient {
     private cachedFrontend;
     constructor(http: HTTPClient, cfg: AuthConfig);
     /**
-     * Exchange a publishable key for a short-lived frontend token.
+     * Exchange a publishable key for a short-lived frontend token for an existing customer.
      * Tokens are cached until they are close to expiry.
+     *
+     * Use this method when the customer already exists in the system.
+     * For auto-provisioning new customers, use frontendTokenAutoProvision instead.
      */
-    frontendToken(request?: Partial<FrontendTokenRequest>): Promise<FrontendToken>;
+    frontendToken(request: FrontendTokenRequest): Promise<FrontendToken>;
+    /**
+     * Exchange a publishable key for a frontend token, creating the customer if needed.
+     * The customer will be auto-provisioned on the project's free tier.
+     * Tokens are cached until they are close to expiry.
+     *
+     * Use this method when the customer may not exist and should be created automatically.
+     * The email is required for auto-provisioning.
+     */
+    frontendTokenAutoProvision(request: FrontendTokenAutoProvisionRequest): Promise<FrontendToken>;
+    /**
+     * Internal method to send frontend token requests.
+     */
+    private sendFrontendTokenRequest;
     /**
      * Determine the correct auth headers for chat completions.
      * Publishable keys are automatically exchanged for frontend tokens.
@@ -981,6 +1022,8 @@ declare const ErrorCodes: {
     readonly NO_TIERS: "NO_TIERS";
     /** No free tier available for auto-provisioning - create a free tier or use checkout flow. */
     readonly NO_FREE_TIER: "NO_FREE_TIER";
+    /** Email required for auto-provisioning a new customer. */
+    readonly EMAIL_REQUIRED: "EMAIL_REQUIRED";
 };
 type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type ErrorCategory = "config" | "transport" | "api";
@@ -1048,12 +1091,33 @@ declare class APIError extends ModelRelayError {
      */
     isNoFreeTier(): boolean;
     /**
-     * Returns true if this is a customer provisioning error (NO_TIERS or NO_FREE_TIER).
+     * Returns true if email is required for auto-provisioning a new customer.
+     * To resolve: provide the 'email' field in FrontendTokenRequest.
+     */
+    isEmailRequired(): boolean;
+    /**
+     * Returns true if this is a customer provisioning error (NO_TIERS, NO_FREE_TIER, or EMAIL_REQUIRED).
      * These errors occur when calling frontendToken() with a customer that doesn't exist
      * and automatic provisioning cannot complete.
      */
     isProvisioningError(): boolean;
 }
+/**
+ * Returns true if the error indicates email is required for auto-provisioning.
+ */
+declare function isEmailRequired(err: unknown): boolean;
+/**
+ * Returns true if the error indicates no free tier is available.
+ */
+declare function isNoFreeTier(err: unknown): boolean;
+/**
+ * Returns true if the error indicates no tiers are configured.
+ */
+declare function isNoTiers(err: unknown): boolean;
+/**
+ * Returns true if the error is a customer provisioning error.
+ */
+declare function isProvisioningError(err: unknown): boolean;
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
 /**
@@ -1482,4 +1546,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 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 };
+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 FrontendTokenAutoProvisionRequest, 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, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };

package/dist/index.d.ts

@@ -180,10 +180,35 @@ interface FrontendCustomer {
     deviceId?: string;
     ttlSeconds?: number;
 }
+/**
+ * Request for fetching a frontend token for an existing customer.
+ * Use this when the customer already exists in the system.
+ */
 interface FrontendTokenRequest {
-    publishableKey?: string;
+    /** Publishable key (mr_pk_*) - required for authentication. */
+    publishableKey: string;
+    /** Customer identifier - required to issue a token for this customer. */
+    customerId: string;
+    /** Optional device identifier for tracking/rate limiting. */
+    deviceId?: string;
+    /** Optional TTL in seconds for the issued token. */
+    ttlSeconds?: number;
+}
+/**
+ * Request for fetching a frontend token with auto-provisioning.
+ * Use this when the customer may not exist and should be created on the free tier.
+ * The email is required for auto-provisioning.
+ */
+interface FrontendTokenAutoProvisionRequest {
+    /** Publishable key (mr_pk_*) - required for authentication. */
+    publishableKey: string;
+    /** Customer identifier - required to issue a token for this customer. */
     customerId: string;
+    /** Email address - required for auto-provisioning a new customer. */
+    email: string;
+    /** Optional device identifier for tracking/rate limiting. */
     deviceId?: string;
+    /** Optional TTL in seconds for the issued token. */
     ttlSeconds?: number;
 }
 interface FrontendToken {
@@ -640,10 +665,26 @@ declare class AuthClient {
     private cachedFrontend;
     constructor(http: HTTPClient, cfg: AuthConfig);
     /**
-     * Exchange a publishable key for a short-lived frontend token.
+     * Exchange a publishable key for a short-lived frontend token for an existing customer.
      * Tokens are cached until they are close to expiry.
+     *
+     * Use this method when the customer already exists in the system.
+     * For auto-provisioning new customers, use frontendTokenAutoProvision instead.
      */
-    frontendToken(request?: Partial<FrontendTokenRequest>): Promise<FrontendToken>;
+    frontendToken(request: FrontendTokenRequest): Promise<FrontendToken>;
+    /**
+     * Exchange a publishable key for a frontend token, creating the customer if needed.
+     * The customer will be auto-provisioned on the project's free tier.
+     * Tokens are cached until they are close to expiry.
+     *
+     * Use this method when the customer may not exist and should be created automatically.
+     * The email is required for auto-provisioning.
+     */
+    frontendTokenAutoProvision(request: FrontendTokenAutoProvisionRequest): Promise<FrontendToken>;
+    /**
+     * Internal method to send frontend token requests.
+     */
+    private sendFrontendTokenRequest;
     /**
      * Determine the correct auth headers for chat completions.
      * Publishable keys are automatically exchanged for frontend tokens.
@@ -981,6 +1022,8 @@ declare const ErrorCodes: {
     readonly NO_TIERS: "NO_TIERS";
     /** No free tier available for auto-provisioning - create a free tier or use checkout flow. */
     readonly NO_FREE_TIER: "NO_FREE_TIER";
+    /** Email required for auto-provisioning a new customer. */
+    readonly EMAIL_REQUIRED: "EMAIL_REQUIRED";
 };
 type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type ErrorCategory = "config" | "transport" | "api";
@@ -1048,12 +1091,33 @@ declare class APIError extends ModelRelayError {
      */
     isNoFreeTier(): boolean;
     /**
-     * Returns true if this is a customer provisioning error (NO_TIERS or NO_FREE_TIER).
+     * Returns true if email is required for auto-provisioning a new customer.
+     * To resolve: provide the 'email' field in FrontendTokenRequest.
+     */
+    isEmailRequired(): boolean;
+    /**
+     * Returns true if this is a customer provisioning error (NO_TIERS, NO_FREE_TIER, or EMAIL_REQUIRED).
      * These errors occur when calling frontendToken() with a customer that doesn't exist
      * and automatic provisioning cannot complete.
      */
     isProvisioningError(): boolean;
 }
+/**
+ * Returns true if the error indicates email is required for auto-provisioning.
+ */
+declare function isEmailRequired(err: unknown): boolean;
+/**
+ * Returns true if the error indicates no free tier is available.
+ */
+declare function isNoFreeTier(err: unknown): boolean;
+/**
+ * Returns true if the error indicates no tiers are configured.
+ */
+declare function isNoTiers(err: unknown): boolean;
+/**
+ * Returns true if the error is a customer provisioning error.
+ */
+declare function isProvisioningError(err: unknown): boolean;
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
 /**
@@ -1482,4 +1546,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 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 };
+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 FrontendTokenAutoProvisionRequest, 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, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };

package/dist/index.js

@@ -14,7 +14,9 @@ var ErrorCodes = {
   /** No tiers configured for the project - create a tier first. */
   NO_TIERS: "NO_TIERS",
   /** No free tier available for auto-provisioning - create a free tier or use checkout flow. */
-  NO_FREE_TIER: "NO_FREE_TIER"
+  NO_FREE_TIER: "NO_FREE_TIER",
+  /** Email required for auto-provisioning a new customer. */
+  EMAIL_REQUIRED: "EMAIL_REQUIRED"
 };
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
@@ -99,14 +101,33 @@ var APIError = class extends ModelRelayError {
     return this.code === ErrorCodes.NO_FREE_TIER;
   }
   /**
-   * Returns true if this is a customer provisioning error (NO_TIERS or NO_FREE_TIER).
+   * Returns true if email is required for auto-provisioning a new customer.
+   * To resolve: provide the 'email' field in FrontendTokenRequest.
+   */
+  isEmailRequired() {
+    return this.code === ErrorCodes.EMAIL_REQUIRED;
+  }
+  /**
+   * Returns true if this is a customer provisioning error (NO_TIERS, NO_FREE_TIER, or EMAIL_REQUIRED).
    * These errors occur when calling frontendToken() with a customer that doesn't exist
    * and automatic provisioning cannot complete.
    */
   isProvisioningError() {
-    return this.isNoTiers() || this.isNoFreeTier();
+    return this.isNoTiers() || this.isNoFreeTier() || this.isEmailRequired();
   }
 };
+function isEmailRequired(err) {
+  return err instanceof APIError && err.isEmailRequired();
+}
+function isNoFreeTier(err) {
+  return err instanceof APIError && err.isNoFreeTier();
+}
+function isNoTiers(err) {
+  return err instanceof APIError && err.isNoTiers();
+}
+function isProvisioningError(err) {
+  return err instanceof APIError && err.isProvisioningError();
+}
 async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
   const fallbackMessage = response.statusText || "Request failed";
@@ -122,8 +143,8 @@ async function parseErrorResponse(response, retries) {
   try {
     const parsed = JSON.parse(bodyText);
     const parsedObj = typeof parsed === "object" && parsed !== null ? parsed : null;
-    if (parsedObj?.error) {
-      const errPayload = typeof parsedObj.error === "object" && parsedObj.error !== null ? parsedObj.error : null;
+    if (parsedObj?.error && typeof parsedObj.error === "object") {
+      const errPayload = parsedObj.error;
       const message = errPayload?.message || fallbackMessage;
       const code = errPayload?.code || void 0;
       const fields = Array.isArray(errPayload?.fields) ? errPayload?.fields : void 0;
@@ -175,20 +196,47 @@ var AuthClient = class {
     this.customer = cfg.customer;
   }
   /**
-   * Exchange a publishable key for a short-lived frontend token.
+   * Exchange a publishable key for a short-lived frontend token for an existing customer.
    * Tokens are cached until they are close to expiry.
+   *
+   * Use this method when the customer already exists in the system.
+   * For auto-provisioning new customers, use frontendTokenAutoProvision instead.
    */
   async frontendToken(request) {
-    const publishableKey = request?.publishableKey || (isPublishableKey(this.apiKey) ? this.apiKey : void 0);
-    if (!publishableKey) {
-      throw new ConfigError("publishable key required to issue frontend tokens");
+    if (!request.publishableKey?.trim()) {
+      throw new ConfigError("publishableKey is required");
+    }
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    return this.sendFrontendTokenRequest(request);
+  }
+  /**
+   * Exchange a publishable key for a frontend token, creating the customer if needed.
+   * The customer will be auto-provisioned on the project's free tier.
+   * Tokens are cached until they are close to expiry.
+   *
+   * Use this method when the customer may not exist and should be created automatically.
+   * The email is required for auto-provisioning.
+   */
+  async frontendTokenAutoProvision(request) {
+    if (!request.publishableKey?.trim()) {
+      throw new ConfigError("publishableKey is required");
+    }
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
     }
-    const customerId = request?.customerId || this.customer?.id;
-    if (!customerId) {
-      throw new ConfigError("customerId is required to mint a frontend token");
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required for auto-provisioning");
     }
-    const deviceId = request?.deviceId || this.customer?.deviceId;
-    const ttlSeconds = request?.ttlSeconds ?? this.customer?.ttlSeconds;
+    return this.sendFrontendTokenRequest(request);
+  }
+  /**
+   * Internal method to send frontend token requests.
+   */
+  async sendFrontendTokenRequest(request) {
+    const { publishableKey, customerId, deviceId, ttlSeconds } = request;
+    const email = "email" in request ? request.email : void 0;
     const cacheKey = `${publishableKey}:${customerId}:${deviceId || ""}`;
     const cached = this.cachedFrontend.get(cacheKey);
     if (cached && isTokenReusable(cached)) {
@@ -204,6 +252,9 @@ var AuthClient = class {
     if (typeof ttlSeconds === "number" && ttlSeconds > 0) {
       payload.ttl_seconds = ttlSeconds;
     }
+    if (email) {
+      payload.email = email;
+    }
     const response = await this.http.json(
       "/auth/frontend-token",
       {
@@ -231,10 +282,15 @@ var AuthClient = class {
       throw new ConfigError("API key or token is required");
     }
     if (isPublishableKey(this.apiKey)) {
+      const resolvedCustomerId = customerId || overrides?.id || this.customer?.id;
+      if (!resolvedCustomerId) {
+        throw new ConfigError("customerId is required to mint a frontend token");
+      }
       const token = await this.frontendToken({
-        customerId: customerId || overrides?.id,
-        deviceId: overrides?.deviceId,
-        ttlSeconds: overrides?.ttlSeconds
+        publishableKey: this.apiKey,
+        customerId: resolvedCustomerId,
+        deviceId: overrides?.deviceId || this.customer?.deviceId,
+        ttlSeconds: overrides?.ttlSeconds ?? this.customer?.ttlSeconds
       });
       return createAccessTokenAuth(token.token);
     }
@@ -288,7 +344,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.20.0",
+  version: "0.22.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -2451,6 +2507,10 @@ export {
   getRetryableErrors,
   hasRetryableErrors,
   hasToolCalls,
+  isEmailRequired,
+  isNoFreeTier,
+  isNoTiers,
+  isProvisioningError,
   isPublishableKey,
   mergeMetrics,
   mergeTrace,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@modelrelay/sdk",
-  "version": "0.20.0",
+  "version": "0.22.0",
 	"description": "TypeScript SDK for the ModelRelay API",
 	"type": "module",
 	"main": "dist/index.cjs",