@modelrelay/sdk 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -96,7 +96,13 @@ var ErrorCodes = {
   SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
   INVALID_INPUT: "INVALID_INPUT",
   PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
-  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED"
+  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED",
+  /** 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",
+  /** Email required for auto-provisioning a new customer. */
+  EMAIL_REQUIRED: "EMAIL_REQUIRED"
 };
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
@@ -165,6 +171,36 @@ var APIError = class extends ModelRelayError {
   isUnavailable() {
     return this.code === ErrorCodes.SERVICE_UNAVAILABLE;
   }
+  /**
+   * Returns true if the error indicates no tiers are configured.
+   * To resolve: create at least one tier in your project dashboard.
+   */
+  isNoTiers() {
+    return this.code === ErrorCodes.NO_TIERS;
+  }
+  /**
+   * Returns true if the error indicates no free tier is available for auto-provisioning.
+   * To resolve: either create a free tier for automatic customer creation,
+   * or use the checkout flow to create paying customers first.
+   */
+  isNoFreeTier() {
+    return this.code === ErrorCodes.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() || this.isEmailRequired();
+  }
 };
 async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
@@ -234,20 +270,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");
     }
-    const customerId = request?.customerId || this.customer?.id;
-    if (!customerId) {
-      throw new ConfigError("customerId is required to mint a frontend token");
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
     }
-    const deviceId = request?.deviceId || this.customer?.deviceId;
-    const ttlSeconds = request?.ttlSeconds ?? this.customer?.ttlSeconds;
+    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");
+    }
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required for auto-provisioning");
+    }
+    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)) {
@@ -263,6 +326,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",
       {
@@ -290,10 +356,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);
     }
@@ -347,7 +418,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.19.0",
+  version: "0.21.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",

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.
@@ -977,6 +1018,12 @@ declare const ErrorCodes: {
     readonly INVALID_INPUT: "INVALID_INPUT";
     readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
     readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+    /** No tiers configured for the project - create a tier first. */
+    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";
@@ -1032,6 +1079,28 @@ declare class APIError extends ModelRelayError {
     isForbidden(): boolean;
     /** Returns true if the error is a service unavailable error. */
     isUnavailable(): boolean;
+    /**
+     * Returns true if the error indicates no tiers are configured.
+     * To resolve: create at least one tier in your project dashboard.
+     */
+    isNoTiers(): boolean;
+    /**
+     * Returns true if the error indicates no free tier is available for auto-provisioning.
+     * To resolve: either create a free tier for automatic customer creation,
+     * or use the checkout flow to create paying customers first.
+     */
+    isNoFreeTier(): boolean;
+    /**
+     * 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;
 }
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
@@ -1461,4 +1530,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, 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.
@@ -977,6 +1018,12 @@ declare const ErrorCodes: {
     readonly INVALID_INPUT: "INVALID_INPUT";
     readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
     readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+    /** No tiers configured for the project - create a tier first. */
+    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";
@@ -1032,6 +1079,28 @@ declare class APIError extends ModelRelayError {
     isForbidden(): boolean;
     /** Returns true if the error is a service unavailable error. */
     isUnavailable(): boolean;
+    /**
+     * Returns true if the error indicates no tiers are configured.
+     * To resolve: create at least one tier in your project dashboard.
+     */
+    isNoTiers(): boolean;
+    /**
+     * Returns true if the error indicates no free tier is available for auto-provisioning.
+     * To resolve: either create a free tier for automatic customer creation,
+     * or use the checkout flow to create paying customers first.
+     */
+    isNoFreeTier(): boolean;
+    /**
+     * 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;
 }
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
@@ -1461,4 +1530,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, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };

package/dist/index.js

@@ -10,7 +10,13 @@ var ErrorCodes = {
   SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
   INVALID_INPUT: "INVALID_INPUT",
   PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
-  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED"
+  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED",
+  /** 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",
+  /** Email required for auto-provisioning a new customer. */
+  EMAIL_REQUIRED: "EMAIL_REQUIRED"
 };
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
@@ -79,6 +85,36 @@ var APIError = class extends ModelRelayError {
   isUnavailable() {
     return this.code === ErrorCodes.SERVICE_UNAVAILABLE;
   }
+  /**
+   * Returns true if the error indicates no tiers are configured.
+   * To resolve: create at least one tier in your project dashboard.
+   */
+  isNoTiers() {
+    return this.code === ErrorCodes.NO_TIERS;
+  }
+  /**
+   * Returns true if the error indicates no free tier is available for auto-provisioning.
+   * To resolve: either create a free tier for automatic customer creation,
+   * or use the checkout flow to create paying customers first.
+   */
+  isNoFreeTier() {
+    return this.code === ErrorCodes.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() || this.isEmailRequired();
+  }
 };
 async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
@@ -148,20 +184,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");
     }
-    const customerId = request?.customerId || this.customer?.id;
-    if (!customerId) {
-      throw new ConfigError("customerId is required to mint a frontend token");
+    if (!request.customerId?.trim()) {
+      throw new ConfigError("customerId is required");
     }
-    const deviceId = request?.deviceId || this.customer?.deviceId;
-    const ttlSeconds = request?.ttlSeconds ?? this.customer?.ttlSeconds;
+    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");
+    }
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required for auto-provisioning");
+    }
+    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)) {
@@ -177,6 +240,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",
       {
@@ -204,10 +270,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);
     }
@@ -261,7 +332,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.19.0",
+  version: "0.21.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",

package/package.json

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