@modelrelay/sdk 0.23.0 → 0.24.0

package/README.md

@@ -82,12 +82,53 @@ const stream = await mr.chat.completions.create(
 );
 ```
 
-### Typed models and stop reasons
+### Typed models, stop reasons, and message roles
 
 - Models are plain strings (e.g., `"gpt-4o"`), so new models do not require SDK updates.
 - Stop reasons are parsed into the `StopReason` union (e.g., `StopReasons.EndTurn`); unknown values surface as `{ other: "<raw>" }`.
+- Message roles use a typed union (`MessageRole`) with constants available via `MessageRoles`.
 - Usage backfills `totalTokens` when the backend omits it, ensuring consistent accounting.
 
+```ts
+import { MessageRoles } from "@modelrelay/sdk";
+
+// Use typed role constants
+const messages = [
+  { role: MessageRoles.System, content: "You are helpful." },
+  { role: MessageRoles.User, content: "Hello!" },
+];
+
+// Available roles: User, Assistant, System, Tool
+```
+
+### Customer-attributed requests
+
+For customer-attributed requests, the customer's tier determines which model to use.
+Use `forCustomer()` instead of providing a model:
+
+```ts
+// Customer-attributed: tier determines model, no model parameter needed
+const stream = await mr.chat.forCustomer("customer-123").create({
+  messages: [{ role: "user", content: "Hello!" }]
+});
+
+for await (const event of stream) {
+  if (event.type === "message_delta" && event.textDelta) {
+    console.log(event.textDelta);
+  }
+}
+
+// Non-streaming
+const completion = await mr.chat.forCustomer("customer-123").create(
+  { messages: [{ role: "user", content: "Hello!" }] },
+  { stream: false }
+);
+```
+
+This provides compile-time separation between:
+- **Direct/PAYGO requests** (`chat.completions.create({ model, ... })`) — model is required
+- **Customer-attributed requests** (`chat.forCustomer(id).create(...)`) — tier determines model
+
 ### Structured outputs (`response_format`)
 
 Request structured JSON instead of free-form text when the backend supports it:

package/dist/index.cjs

@@ -25,12 +25,14 @@ __export(index_exports, {
   ChatClient: () => ChatClient,
   ChatCompletionsStream: () => ChatCompletionsStream,
   ConfigError: () => ConfigError,
+  CustomerChatClient: () => CustomerChatClient,
   CustomersClient: () => CustomersClient,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   DEFAULT_CLIENT_HEADER: () => DEFAULT_CLIENT_HEADER,
   DEFAULT_CONNECT_TIMEOUT_MS: () => DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS: () => DEFAULT_REQUEST_TIMEOUT_MS,
   ErrorCodes: () => ErrorCodes,
+  MessageRoles: () => MessageRoles,
   ModelRelay: () => ModelRelay,
   ModelRelayError: () => ModelRelayError,
   ResponseFormatTypes: () => ResponseFormatTypes,
@@ -430,7 +432,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.22.0",
+  version: "0.24.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -496,6 +498,12 @@ function createUsage(inputTokens, outputTokens, totalTokens) {
     totalTokens: totalTokens ?? inputTokens + outputTokens
   };
 }
+var MessageRoles = {
+  User: "user",
+  Assistant: "assistant",
+  System: "system",
+  Tool: "tool"
+};
 var ToolTypes = {
   Function: "function",
   Web: "web",
@@ -1185,9 +1193,15 @@ async function executeWithRetry(registry, toolCalls, options = {}) {
 }
 
 // src/chat.ts
+var CUSTOMER_ID_HEADER = "X-ModelRelay-Customer-Id";
 var REQUEST_ID_HEADER = "X-ModelRelay-Chat-Request-Id";
 var ChatClient = class {
   constructor(http, auth, cfg = {}) {
+    this.http = http;
+    this.auth = auth;
+    this.defaultMetadata = cfg.defaultMetadata;
+    this.metrics = cfg.metrics;
+    this.trace = cfg.trace;
     this.completions = new ChatCompletionsClient(
       http,
       auth,
@@ -1196,6 +1210,30 @@ var ChatClient = class {
       cfg.trace
     );
   }
+  /**
+   * Create a customer-attributed chat client for the given customer ID.
+   * The customer's tier determines the model - no model parameter is needed or allowed.
+   *
+   * @example
+   * ```typescript
+   * const stream = await client.chat.forCustomer("user-123").create({
+   *   messages: [{ role: "user", content: "Hello!" }],
+   * });
+   * ```
+   */
+  forCustomer(customerId) {
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    return new CustomerChatClient(
+      this.http,
+      this.auth,
+      customerId,
+      this.defaultMetadata,
+      this.metrics,
+      this.trace
+    );
+  }
 };
 var ChatCompletionsClient = class {
   constructor(http, auth, defaultMetadata, metrics, trace) {
@@ -1215,7 +1253,7 @@ var ChatCompletionsClient = class {
     if (!hasUserMessage(params.messages)) {
       throw new ConfigError("at least one user message is required");
     }
-    const authHeaders = await this.auth.authForChat(params.customerId);
+    const authHeaders = await this.auth.authForChat();
     const body = buildProxyBody(
       params,
       mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
@@ -1295,7 +1333,7 @@ var ChatCompletionsClient = class {
         "responseFormat with type=json_object or json_schema is required for structured streaming"
       );
     }
-    const authHeaders = await this.auth.authForChat(params.customerId);
+    const authHeaders = await this.auth.authForChat();
     const body = buildProxyBody(
       params,
       mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
@@ -1352,6 +1390,170 @@ var ChatCompletionsClient = class {
     );
   }
 };
+var CustomerChatClient = class {
+  constructor(http, auth, customerId, defaultMetadata, metrics, trace) {
+    this.http = http;
+    this.auth = auth;
+    this.customerId = customerId;
+    this.defaultMetadata = defaultMetadata;
+    this.metrics = metrics;
+    this.trace = trace;
+  }
+  async create(params, options = {}) {
+    const stream = options.stream ?? params.stream ?? true;
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    if (!params?.messages?.length) {
+      throw new ConfigError("at least one message is required");
+    }
+    if (!hasUserMessage(params.messages)) {
+      throw new ConfigError("at least one user message is required");
+    }
+    const authHeaders = await this.auth.authForChat(this.customerId);
+    const body = buildCustomerProxyBody(
+      params,
+      mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
+    );
+    const requestId = params.requestId || options.requestId;
+    const headers = {
+      ...options.headers || {},
+      [CUSTOMER_ID_HEADER]: this.customerId
+    };
+    if (requestId) {
+      headers[REQUEST_ID_HEADER] = requestId;
+    }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      model: void 0,
+      // Model is determined by tier
+      requestId
+    };
+    const response = await this.http.request("/llm/proxy", {
+      method: "POST",
+      body,
+      headers,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      accept: stream ? "text/event-stream" : "application/json",
+      raw: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? (stream ? 0 : void 0),
+      useDefaultTimeout: !stream,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
+    });
+    const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
+    if (!response.ok) {
+      throw await parseErrorResponse(response);
+    }
+    if (!stream) {
+      const payload = await response.json();
+      const result = normalizeChatResponse(payload, resolvedRequestId);
+      if (metrics?.usage) {
+        const ctx = {
+          ...baseContext,
+          requestId: resolvedRequestId ?? baseContext.requestId,
+          responseId: result.id
+        };
+        metrics.usage({ usage: result.usage, context: ctx });
+      }
+      return result;
+    }
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new ChatCompletionsStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
+  }
+  /**
+   * Stream structured JSON responses using the NDJSON contract.
+   * The request must include a structured responseFormat.
+   */
+  async streamJSON(params, options = {}) {
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    if (!params?.messages?.length) {
+      throw new ConfigError("at least one message is required");
+    }
+    if (!hasUserMessage(params.messages)) {
+      throw new ConfigError("at least one user message is required");
+    }
+    if (!params.responseFormat || params.responseFormat.type !== "json_object" && params.responseFormat.type !== "json_schema") {
+      throw new ConfigError(
+        "responseFormat with type=json_object or json_schema is required for structured streaming"
+      );
+    }
+    const authHeaders = await this.auth.authForChat(this.customerId);
+    const body = buildCustomerProxyBody(
+      params,
+      mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
+    );
+    const requestId = params.requestId || options.requestId;
+    const headers = {
+      ...options.headers || {},
+      [CUSTOMER_ID_HEADER]: this.customerId
+    };
+    if (requestId) {
+      headers[REQUEST_ID_HEADER] = requestId;
+    }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      model: void 0,
+      // Model is determined by tier
+      requestId
+    };
+    const response = await this.http.request("/llm/proxy", {
+      method: "POST",
+      body,
+      headers,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      accept: "application/x-ndjson",
+      raw: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? 0,
+      useDefaultTimeout: false,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
+    });
+    const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
+    if (!response.ok) {
+      throw await parseErrorResponse(response);
+    }
+    const contentType = response.headers.get("Content-Type") || "";
+    if (!/application\/(x-)?ndjson/i.test(contentType)) {
+      throw new TransportError(
+        `expected NDJSON structured stream, got Content-Type ${contentType || "missing"}`,
+        { kind: "request" }
+      );
+    }
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new StructuredJSONStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
+  }
+};
 var ChatCompletionsStream = class {
   constructor(response, requestId, context, metrics, trace) {
     this.firstTokenEmitted = false;
@@ -1842,10 +2044,25 @@ function buildProxyBody(params, metadata) {
   if (params.responseFormat) body.response_format = params.responseFormat;
   return body;
 }
+function buildCustomerProxyBody(params, metadata) {
+  const body = {
+    messages: normalizeMessages(params.messages)
+  };
+  if (typeof params.maxTokens === "number") body.max_tokens = params.maxTokens;
+  if (typeof params.temperature === "number")
+    body.temperature = params.temperature;
+  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
+  if (params.stop?.length) body.stop = params.stop;
+  if (params.stopSequences?.length) body.stop_sequences = params.stopSequences;
+  if (params.tools?.length) body.tools = normalizeTools(params.tools);
+  if (params.toolChoice) body.tool_choice = normalizeToolChoice(params.toolChoice);
+  if (params.responseFormat) body.response_format = params.responseFormat;
+  return body;
+}
 function normalizeMessages(messages) {
   return messages.map((msg) => {
     const normalized = {
-      role: msg.role || "user",
+      role: msg.role,
       content: msg.content
     };
     if (msg.toolCalls?.length) {
@@ -2555,12 +2772,14 @@ function resolveBaseUrl(override) {
   ChatClient,
   ChatCompletionsStream,
   ConfigError,
+  CustomerChatClient,
   CustomersClient,
   DEFAULT_BASE_URL,
   DEFAULT_CLIENT_HEADER,
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS,
   ErrorCodes,
+  MessageRoles,
   ModelRelay,
   ModelRelayError,
   ResponseFormatTypes,

package/dist/index.d.cts

@@ -271,8 +271,18 @@ interface Project {
     createdAt?: Date;
     updatedAt?: Date;
 }
+/**
+ * Valid roles for chat messages.
+ */
+declare const MessageRoles: {
+    readonly User: "user";
+    readonly Assistant: "assistant";
+    readonly System: "system";
+    readonly Tool: "tool";
+};
+type MessageRole = (typeof MessageRoles)[keyof typeof MessageRoles];
 interface ChatMessage {
-    role: string;
+    role: MessageRole;
     content: string;
     toolCalls?: ToolCall[];
     toolCallId?: string;
@@ -354,6 +364,10 @@ interface ResponseFormat {
     type: ResponseFormatType;
     json_schema?: ResponseJSONSchemaFormat;
 }
+/**
+ * Parameters for direct chat completions (owner PAYGO mode).
+ * Model is required - the developer specifies which model to use.
+ */
 interface ChatCompletionCreateParams {
     model: ModelId;
     messages: NonEmptyArray<ChatMessage>;
@@ -371,9 +385,38 @@ interface ChatCompletionCreateParams {
      */
     toolChoice?: ToolChoice;
     /**
-     * When using publishable keys, a customer id is required to mint a frontend token.
+     * 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.
+     */
+    stream?: boolean;
+    /**
+     * Optional request id to set on the call. If omitted, the server will generate one.
      */
-    customerId?: string;
+    requestId?: string;
+}
+/**
+ * Parameters for customer-attributed chat completions.
+ * Model is NOT included - the customer's tier determines the model.
+ */
+interface CustomerChatParams {
+    messages: NonEmptyArray<ChatMessage>;
+    maxTokens?: number;
+    temperature?: number;
+    metadata?: Record<string, string>;
+    stop?: string[];
+    stopSequences?: string[];
+    /**
+     * Tools available for the model to call.
+     */
+    tools?: Tool[];
+    /**
+     * Controls how the model responds to tool calls.
+     */
+    toolChoice?: ToolChoice;
     /**
      * Structured outputs configuration. When set with type `json_object` or
      * `json_schema`, the backend validates and returns structured JSON.
@@ -753,11 +796,28 @@ interface ChatRequestOptions {
 }
 declare class ChatClient {
     readonly completions: ChatCompletionsClient;
+    private readonly http;
+    private readonly auth;
+    private readonly defaultMetadata?;
+    private readonly metrics?;
+    private readonly trace?;
     constructor(http: HTTPClient, auth: AuthClient, cfg?: {
         defaultMetadata?: Record<string, string>;
         metrics?: MetricsCallbacks;
         trace?: TraceCallbacks;
     });
+    /**
+     * Create a customer-attributed chat client for the given customer ID.
+     * The customer's tier determines the model - no model parameter is needed or allowed.
+     *
+     * @example
+     * ```typescript
+     * const stream = await client.chat.forCustomer("user-123").create({
+     *   messages: [{ role: "user", content: "Hello!" }],
+     * });
+     * ```
+     */
+    forCustomer(customerId: string): CustomerChatClient;
 }
 declare class ChatCompletionsClient {
     private readonly http;
@@ -781,6 +841,33 @@ declare class ChatCompletionsClient {
         responseFormat: ResponseFormat;
     }, options?: ChatRequestOptions): Promise<StructuredJSONStream<T>>;
 }
+/**
+ * Client for customer-attributed chat completions.
+ * The customer's tier determines the model - no model parameter is needed or allowed.
+ */
+declare class CustomerChatClient {
+    private readonly http;
+    private readonly auth;
+    private readonly customerId;
+    private readonly defaultMetadata?;
+    private readonly metrics?;
+    private readonly trace?;
+    constructor(http: HTTPClient, auth: AuthClient, customerId: string, defaultMetadata?: Record<string, string>, metrics?: MetricsCallbacks, trace?: TraceCallbacks);
+    create(params: CustomerChatParams & {
+        stream: false;
+    }, options?: ChatRequestOptions): Promise<ChatCompletionResponse>;
+    create(params: CustomerChatParams, options: ChatRequestOptions & {
+        stream: false;
+    }): Promise<ChatCompletionResponse>;
+    create(params: CustomerChatParams, options?: ChatRequestOptions): Promise<ChatCompletionsStream>;
+    /**
+     * Stream structured JSON responses using the NDJSON contract.
+     * The request must include a structured responseFormat.
+     */
+    streamJSON<T>(params: CustomerChatParams & {
+        responseFormat: ResponseFormat;
+    }, options?: ChatRequestOptions): Promise<StructuredJSONStream<T>>;
+}
 declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent> {
     private readonly response;
     private readonly requestId?;
@@ -1558,4 +1645,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 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 TokenType, 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 };
+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, CustomerChatClient, type CustomerChatParams, 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 MessageRole, MessageRoles, 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 TokenType, 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

@@ -271,8 +271,18 @@ interface Project {
     createdAt?: Date;
     updatedAt?: Date;
 }
+/**
+ * Valid roles for chat messages.
+ */
+declare const MessageRoles: {
+    readonly User: "user";
+    readonly Assistant: "assistant";
+    readonly System: "system";
+    readonly Tool: "tool";
+};
+type MessageRole = (typeof MessageRoles)[keyof typeof MessageRoles];
 interface ChatMessage {
-    role: string;
+    role: MessageRole;
     content: string;
     toolCalls?: ToolCall[];
     toolCallId?: string;
@@ -354,6 +364,10 @@ interface ResponseFormat {
     type: ResponseFormatType;
     json_schema?: ResponseJSONSchemaFormat;
 }
+/**
+ * Parameters for direct chat completions (owner PAYGO mode).
+ * Model is required - the developer specifies which model to use.
+ */
 interface ChatCompletionCreateParams {
     model: ModelId;
     messages: NonEmptyArray<ChatMessage>;
@@ -371,9 +385,38 @@ interface ChatCompletionCreateParams {
      */
     toolChoice?: ToolChoice;
     /**
-     * When using publishable keys, a customer id is required to mint a frontend token.
+     * 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.
+     */
+    stream?: boolean;
+    /**
+     * Optional request id to set on the call. If omitted, the server will generate one.
      */
-    customerId?: string;
+    requestId?: string;
+}
+/**
+ * Parameters for customer-attributed chat completions.
+ * Model is NOT included - the customer's tier determines the model.
+ */
+interface CustomerChatParams {
+    messages: NonEmptyArray<ChatMessage>;
+    maxTokens?: number;
+    temperature?: number;
+    metadata?: Record<string, string>;
+    stop?: string[];
+    stopSequences?: string[];
+    /**
+     * Tools available for the model to call.
+     */
+    tools?: Tool[];
+    /**
+     * Controls how the model responds to tool calls.
+     */
+    toolChoice?: ToolChoice;
     /**
      * Structured outputs configuration. When set with type `json_object` or
      * `json_schema`, the backend validates and returns structured JSON.
@@ -753,11 +796,28 @@ interface ChatRequestOptions {
 }
 declare class ChatClient {
     readonly completions: ChatCompletionsClient;
+    private readonly http;
+    private readonly auth;
+    private readonly defaultMetadata?;
+    private readonly metrics?;
+    private readonly trace?;
     constructor(http: HTTPClient, auth: AuthClient, cfg?: {
         defaultMetadata?: Record<string, string>;
         metrics?: MetricsCallbacks;
         trace?: TraceCallbacks;
     });
+    /**
+     * Create a customer-attributed chat client for the given customer ID.
+     * The customer's tier determines the model - no model parameter is needed or allowed.
+     *
+     * @example
+     * ```typescript
+     * const stream = await client.chat.forCustomer("user-123").create({
+     *   messages: [{ role: "user", content: "Hello!" }],
+     * });
+     * ```
+     */
+    forCustomer(customerId: string): CustomerChatClient;
 }
 declare class ChatCompletionsClient {
     private readonly http;
@@ -781,6 +841,33 @@ declare class ChatCompletionsClient {
         responseFormat: ResponseFormat;
     }, options?: ChatRequestOptions): Promise<StructuredJSONStream<T>>;
 }
+/**
+ * Client for customer-attributed chat completions.
+ * The customer's tier determines the model - no model parameter is needed or allowed.
+ */
+declare class CustomerChatClient {
+    private readonly http;
+    private readonly auth;
+    private readonly customerId;
+    private readonly defaultMetadata?;
+    private readonly metrics?;
+    private readonly trace?;
+    constructor(http: HTTPClient, auth: AuthClient, customerId: string, defaultMetadata?: Record<string, string>, metrics?: MetricsCallbacks, trace?: TraceCallbacks);
+    create(params: CustomerChatParams & {
+        stream: false;
+    }, options?: ChatRequestOptions): Promise<ChatCompletionResponse>;
+    create(params: CustomerChatParams, options: ChatRequestOptions & {
+        stream: false;
+    }): Promise<ChatCompletionResponse>;
+    create(params: CustomerChatParams, options?: ChatRequestOptions): Promise<ChatCompletionsStream>;
+    /**
+     * Stream structured JSON responses using the NDJSON contract.
+     * The request must include a structured responseFormat.
+     */
+    streamJSON<T>(params: CustomerChatParams & {
+        responseFormat: ResponseFormat;
+    }, options?: ChatRequestOptions): Promise<StructuredJSONStream<T>>;
+}
 declare class ChatCompletionsStream implements AsyncIterable<ChatCompletionEvent> {
     private readonly response;
     private readonly requestId?;
@@ -1558,4 +1645,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 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 TokenType, 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 };
+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, CustomerChatClient, type CustomerChatParams, 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 MessageRole, MessageRoles, 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 TokenType, 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

@@ -340,7 +340,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.22.0",
+  version: "0.24.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -406,6 +406,12 @@ function createUsage(inputTokens, outputTokens, totalTokens) {
     totalTokens: totalTokens ?? inputTokens + outputTokens
   };
 }
+var MessageRoles = {
+  User: "user",
+  Assistant: "assistant",
+  System: "system",
+  Tool: "tool"
+};
 var ToolTypes = {
   Function: "function",
   Web: "web",
@@ -1095,9 +1101,15 @@ async function executeWithRetry(registry, toolCalls, options = {}) {
 }
 
 // src/chat.ts
+var CUSTOMER_ID_HEADER = "X-ModelRelay-Customer-Id";
 var REQUEST_ID_HEADER = "X-ModelRelay-Chat-Request-Id";
 var ChatClient = class {
   constructor(http, auth, cfg = {}) {
+    this.http = http;
+    this.auth = auth;
+    this.defaultMetadata = cfg.defaultMetadata;
+    this.metrics = cfg.metrics;
+    this.trace = cfg.trace;
     this.completions = new ChatCompletionsClient(
       http,
       auth,
@@ -1106,6 +1118,30 @@ var ChatClient = class {
       cfg.trace
     );
   }
+  /**
+   * Create a customer-attributed chat client for the given customer ID.
+   * The customer's tier determines the model - no model parameter is needed or allowed.
+   *
+   * @example
+   * ```typescript
+   * const stream = await client.chat.forCustomer("user-123").create({
+   *   messages: [{ role: "user", content: "Hello!" }],
+   * });
+   * ```
+   */
+  forCustomer(customerId) {
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    return new CustomerChatClient(
+      this.http,
+      this.auth,
+      customerId,
+      this.defaultMetadata,
+      this.metrics,
+      this.trace
+    );
+  }
 };
 var ChatCompletionsClient = class {
   constructor(http, auth, defaultMetadata, metrics, trace) {
@@ -1125,7 +1161,7 @@ var ChatCompletionsClient = class {
     if (!hasUserMessage(params.messages)) {
       throw new ConfigError("at least one user message is required");
     }
-    const authHeaders = await this.auth.authForChat(params.customerId);
+    const authHeaders = await this.auth.authForChat();
     const body = buildProxyBody(
       params,
       mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
@@ -1205,7 +1241,7 @@ var ChatCompletionsClient = class {
         "responseFormat with type=json_object or json_schema is required for structured streaming"
       );
     }
-    const authHeaders = await this.auth.authForChat(params.customerId);
+    const authHeaders = await this.auth.authForChat();
     const body = buildProxyBody(
       params,
       mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
@@ -1262,6 +1298,170 @@ var ChatCompletionsClient = class {
     );
   }
 };
+var CustomerChatClient = class {
+  constructor(http, auth, customerId, defaultMetadata, metrics, trace) {
+    this.http = http;
+    this.auth = auth;
+    this.customerId = customerId;
+    this.defaultMetadata = defaultMetadata;
+    this.metrics = metrics;
+    this.trace = trace;
+  }
+  async create(params, options = {}) {
+    const stream = options.stream ?? params.stream ?? true;
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    if (!params?.messages?.length) {
+      throw new ConfigError("at least one message is required");
+    }
+    if (!hasUserMessage(params.messages)) {
+      throw new ConfigError("at least one user message is required");
+    }
+    const authHeaders = await this.auth.authForChat(this.customerId);
+    const body = buildCustomerProxyBody(
+      params,
+      mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
+    );
+    const requestId = params.requestId || options.requestId;
+    const headers = {
+      ...options.headers || {},
+      [CUSTOMER_ID_HEADER]: this.customerId
+    };
+    if (requestId) {
+      headers[REQUEST_ID_HEADER] = requestId;
+    }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      model: void 0,
+      // Model is determined by tier
+      requestId
+    };
+    const response = await this.http.request("/llm/proxy", {
+      method: "POST",
+      body,
+      headers,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      accept: stream ? "text/event-stream" : "application/json",
+      raw: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? (stream ? 0 : void 0),
+      useDefaultTimeout: !stream,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
+    });
+    const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
+    if (!response.ok) {
+      throw await parseErrorResponse(response);
+    }
+    if (!stream) {
+      const payload = await response.json();
+      const result = normalizeChatResponse(payload, resolvedRequestId);
+      if (metrics?.usage) {
+        const ctx = {
+          ...baseContext,
+          requestId: resolvedRequestId ?? baseContext.requestId,
+          responseId: result.id
+        };
+        metrics.usage({ usage: result.usage, context: ctx });
+      }
+      return result;
+    }
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new ChatCompletionsStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
+  }
+  /**
+   * Stream structured JSON responses using the NDJSON contract.
+   * The request must include a structured responseFormat.
+   */
+  async streamJSON(params, options = {}) {
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    if (!params?.messages?.length) {
+      throw new ConfigError("at least one message is required");
+    }
+    if (!hasUserMessage(params.messages)) {
+      throw new ConfigError("at least one user message is required");
+    }
+    if (!params.responseFormat || params.responseFormat.type !== "json_object" && params.responseFormat.type !== "json_schema") {
+      throw new ConfigError(
+        "responseFormat with type=json_object or json_schema is required for structured streaming"
+      );
+    }
+    const authHeaders = await this.auth.authForChat(this.customerId);
+    const body = buildCustomerProxyBody(
+      params,
+      mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
+    );
+    const requestId = params.requestId || options.requestId;
+    const headers = {
+      ...options.headers || {},
+      [CUSTOMER_ID_HEADER]: this.customerId
+    };
+    if (requestId) {
+      headers[REQUEST_ID_HEADER] = requestId;
+    }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      model: void 0,
+      // Model is determined by tier
+      requestId
+    };
+    const response = await this.http.request("/llm/proxy", {
+      method: "POST",
+      body,
+      headers,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      accept: "application/x-ndjson",
+      raw: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? 0,
+      useDefaultTimeout: false,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
+    });
+    const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
+    if (!response.ok) {
+      throw await parseErrorResponse(response);
+    }
+    const contentType = response.headers.get("Content-Type") || "";
+    if (!/application\/(x-)?ndjson/i.test(contentType)) {
+      throw new TransportError(
+        `expected NDJSON structured stream, got Content-Type ${contentType || "missing"}`,
+        { kind: "request" }
+      );
+    }
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new StructuredJSONStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
+  }
+};
 var ChatCompletionsStream = class {
   constructor(response, requestId, context, metrics, trace) {
     this.firstTokenEmitted = false;
@@ -1752,10 +1952,25 @@ function buildProxyBody(params, metadata) {
   if (params.responseFormat) body.response_format = params.responseFormat;
   return body;
 }
+function buildCustomerProxyBody(params, metadata) {
+  const body = {
+    messages: normalizeMessages(params.messages)
+  };
+  if (typeof params.maxTokens === "number") body.max_tokens = params.maxTokens;
+  if (typeof params.temperature === "number")
+    body.temperature = params.temperature;
+  if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
+  if (params.stop?.length) body.stop = params.stop;
+  if (params.stopSequences?.length) body.stop_sequences = params.stopSequences;
+  if (params.tools?.length) body.tools = normalizeTools(params.tools);
+  if (params.toolChoice) body.tool_choice = normalizeToolChoice(params.toolChoice);
+  if (params.responseFormat) body.response_format = params.responseFormat;
+  return body;
+}
 function normalizeMessages(messages) {
   return messages.map((msg) => {
     const normalized = {
-      role: msg.role || "user",
+      role: msg.role,
       content: msg.content
     };
     if (msg.toolCalls?.length) {
@@ -2464,12 +2679,14 @@ export {
   ChatClient,
   ChatCompletionsStream,
   ConfigError,
+  CustomerChatClient,
   CustomersClient,
   DEFAULT_BASE_URL,
   DEFAULT_CLIENT_HEADER,
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS,
   ErrorCodes,
+  MessageRoles,
   ModelRelay,
   ModelRelayError,
   ResponseFormatTypes,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@modelrelay/sdk",
-	"version": "0.23.0",
+  "version": "0.24.0",
 	"description": "TypeScript SDK for the ModelRelay API",
 	"type": "module",
 	"main": "dist/index.cjs",
@@ -13,30 +13,28 @@
 			"require": "./dist/index.cjs"
 		}
 	},
-	"publishConfig": {
-	"access": "public"
-},
-"files": [
-	"dist"
-],
-"scripts": {
-	"build": "tsup src/index.ts --format esm,cjs --dts",
-	"dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-	"lint": "tsc --noEmit",
-	"test": "vitest run"
-},
-"keywords": [
-	"modelrelay",
-	"llm",
-	"sdk",
-	"typescript"
-],
-"author": "Shane Vitarana",
-"license": "Apache-2.0",
-"devDependencies": {
-	"tsup": "^8.2.4",
-	"typescript": "^5.6.3",
-	"vitest": "^2.1.4",
-	"zod": "^3.23.0"
-}
+	"publishConfig": { "access": "public" },
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup src/index.ts --format esm,cjs --dts",
+		"dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+		"lint": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"keywords": [
+		"modelrelay",
+		"llm",
+		"sdk",
+		"typescript"
+	],
+	"author": "Shane Vitarana",
+	"license": "Apache-2.0",
+	"devDependencies": {
+		"tsup": "^8.2.4",
+		"typescript": "^5.6.3",
+		"vitest": "^2.1.4",
+		"zod": "^3.23.0"
+	}
 }