@modelrelay/sdk 0.23.0 → 0.25.1

package/dist/index.cjs

@@ -25,17 +25,21 @@ __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,
   SDK_VERSION: () => SDK_VERSION,
   StopReasons: () => StopReasons,
+  StructuredDecodeError: () => StructuredDecodeError,
+  StructuredExhaustedError: () => StructuredExhaustedError,
   StructuredJSONStream: () => StructuredJSONStream,
   TiersClient: () => TiersClient,
   ToolArgsError: () => ToolArgsError,
@@ -58,6 +62,7 @@ __export(index_exports, {
   createUsage: () => createUsage,
   createUserMessage: () => createUserMessage,
   createWebTool: () => createWebTool,
+  defaultRetryHandler: () => defaultRetryHandler,
   executeWithRetry: () => executeWithRetry,
   firstToolCall: () => firstToolCall,
   formatToolErrorForModel: () => formatToolErrorForModel,
@@ -78,12 +83,14 @@ __export(index_exports, {
   parseToolArgs: () => parseToolArgs,
   parseToolArgsRaw: () => parseToolArgsRaw,
   respondToToolCall: () => respondToToolCall,
+  responseFormatFromZod: () => responseFormatFromZod,
   stopReasonToString: () => stopReasonToString,
   toolChoiceAuto: () => toolChoiceAuto,
   toolChoiceNone: () => toolChoiceNone,
   toolChoiceRequired: () => toolChoiceRequired,
   toolResultMessage: () => toolResultMessage,
   tryParseToolArgs: () => tryParseToolArgs,
+  validateWithZod: () => validateWithZod,
   zodToJsonSchema: () => zodToJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -430,7 +437,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.22.0",
+  version: "0.25.1",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -496,6 +503,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",
@@ -1184,10 +1197,68 @@ async function executeWithRetry(registry, toolCalls, options = {}) {
   return Array.from(successfulResults.values());
 }
 
+// src/structured.ts
+var StructuredDecodeError = class extends Error {
+  constructor(message, rawJson, attempt) {
+    super(`structured output decode error (attempt ${attempt}): ${message}`);
+    this.name = "StructuredDecodeError";
+    this.rawJson = rawJson;
+    this.attempt = attempt;
+  }
+};
+var StructuredExhaustedError = class extends Error {
+  constructor(lastRawJson, allAttempts, finalError) {
+    const errorMsg = finalError.kind === "decode" ? finalError.message : finalError.issues.map((i) => i.message).join("; ");
+    super(
+      `structured output failed after ${allAttempts.length} attempts: ${errorMsg}`
+    );
+    this.name = "StructuredExhaustedError";
+    this.lastRawJson = lastRawJson;
+    this.allAttempts = allAttempts;
+    this.finalError = finalError;
+  }
+};
+var defaultRetryHandler = {
+  onValidationError(_attempt, _rawJson, error, _originalMessages) {
+    const errorMsg = error.kind === "decode" ? error.message : error.issues.map((i) => `${i.path ?? ""}: ${i.message}`).join("; ");
+    return [
+      {
+        role: "user",
+        content: `The previous response did not match the expected schema. Error: ${errorMsg}. Please provide a response that matches the schema exactly.`
+      }
+    ];
+  }
+};
+function responseFormatFromZod(schema, name = "response") {
+  const jsonSchema = zodToJsonSchema(schema);
+  return {
+    type: "json_schema",
+    json_schema: {
+      name,
+      schema: jsonSchema,
+      strict: true
+    }
+  };
+}
+function validateWithZod(schema, data) {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errorMsg = result.error && typeof result.error === "object" && "message" in result.error ? String(result.error.message) : "validation failed";
+  return { success: false, error: errorMsg };
+}
+
 // 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 +1267,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 +1310,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 +1390,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)
@@ -1351,6 +1446,439 @@ var ChatCompletionsClient = class {
       trace
     );
   }
+  /**
+   * Send a structured output request with a Zod schema.
+   *
+   * Auto-generates JSON schema from the Zod schema, validates the response,
+   * and retries on validation failure if configured.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Chat completion parameters (excluding responseFormat)
+   * @param options - Request options including retry configuration
+   * @returns A typed result with the parsed value
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const PersonSchema = z.object({
+   *   name: z.string(),
+   *   age: z.number(),
+   * });
+   *
+   * const result = await client.chat.completions.structured(
+   *   PersonSchema,
+   *   { model: "claude-sonnet-4-20250514", messages: [...] },
+   *   { maxRetries: 2 }
+   * );
+   * ```
+   */
+  async structured(schema, params, options = {}) {
+    const {
+      maxRetries = 0,
+      retryHandler = defaultRetryHandler,
+      schemaName,
+      ...requestOptions
+    } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    const fullParams = {
+      ...params,
+      responseFormat,
+      stream: false
+    };
+    let messages = [...params.messages];
+    const attempts = [];
+    const maxAttempts = maxRetries + 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const response = await this.create(
+        { ...fullParams, messages },
+        { ...requestOptions, stream: false }
+      );
+      const rawJson = response.content.join("");
+      const requestId = response.requestId;
+      try {
+        const parsed = JSON.parse(rawJson);
+        const validated = validateWithZod(schema, parsed);
+        if (validated.success) {
+          return {
+            value: validated.data,
+            attempts: attempt,
+            requestId
+          };
+        }
+        const error = {
+          kind: "validation",
+          issues: [{ message: validated.error }]
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      } catch (e) {
+        if (e instanceof StructuredExhaustedError) {
+          throw e;
+        }
+        const error = {
+          kind: "decode",
+          message: e instanceof Error ? e.message : String(e)
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      }
+    }
+    throw new Error(
+      `Internal error: structured output loop exited unexpectedly after ${maxAttempts} attempts (this is a bug, please report it)`
+    );
+  }
+  /**
+   * Stream structured output with a Zod schema.
+   *
+   * Auto-generates JSON schema from the Zod schema. Note that streaming
+   * does not support retries - for retry behavior, use `structured()`.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Chat completion parameters (excluding responseFormat)
+   * @param options - Request options
+   * @returns A structured JSON stream
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const PersonSchema = z.object({
+   *   name: z.string(),
+   *   age: z.number(),
+   * });
+   *
+   * const stream = await client.chat.completions.streamStructured(
+   *   PersonSchema,
+   *   { model: "claude-sonnet-4-20250514", messages: [...] },
+   * );
+   *
+   * for await (const event of stream) {
+   *   console.log(event.type, event.payload);
+   * }
+   * ```
+   */
+  async streamStructured(schema, params, options = {}) {
+    const { schemaName, ...requestOptions } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    return this.streamJSON(
+      { ...params, responseFormat },
+      requestOptions
+    );
+  }
+};
+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
+    );
+  }
+  /**
+   * Send a structured output request with a Zod schema for customer-attributed calls.
+   *
+   * Auto-generates JSON schema from the Zod schema, validates the response,
+   * and retries on validation failure if configured.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Customer chat parameters (excluding responseFormat)
+   * @param options - Request options including retry configuration
+   * @returns A typed result with the parsed value
+   */
+  async structured(schema, params, options = {}) {
+    const {
+      maxRetries = 0,
+      retryHandler = defaultRetryHandler,
+      schemaName,
+      ...requestOptions
+    } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    const fullParams = {
+      ...params,
+      responseFormat,
+      stream: false
+    };
+    let messages = [...params.messages];
+    const attempts = [];
+    const maxAttempts = maxRetries + 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const response = await this.create(
+        { ...fullParams, messages },
+        { ...requestOptions, stream: false }
+      );
+      const rawJson = response.content.join("");
+      const requestId = response.requestId;
+      try {
+        const parsed = JSON.parse(rawJson);
+        const validated = validateWithZod(schema, parsed);
+        if (validated.success) {
+          return {
+            value: validated.data,
+            attempts: attempt,
+            requestId
+          };
+        }
+        const error = {
+          kind: "validation",
+          issues: [{ message: validated.error }]
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      } catch (e) {
+        if (e instanceof StructuredExhaustedError) {
+          throw e;
+        }
+        const error = {
+          kind: "decode",
+          message: e instanceof Error ? e.message : String(e)
+        };
+        attempts.push({ attempt, rawJson, error });
+        if (attempt >= maxAttempts) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        const retryMessages = retryHandler.onValidationError(
+          attempt,
+          rawJson,
+          error,
+          params.messages
+        );
+        if (!retryMessages) {
+          throw new StructuredExhaustedError(rawJson, attempts, error);
+        }
+        messages = [
+          ...params.messages,
+          { role: "assistant", content: rawJson },
+          ...retryMessages
+        ];
+      }
+    }
+    throw new Error(
+      `Internal error: structured output loop exited unexpectedly after ${maxAttempts} attempts (this is a bug, please report it)`
+    );
+  }
+  /**
+   * Stream structured output with a Zod schema for customer-attributed calls.
+   *
+   * Auto-generates JSON schema from the Zod schema. Note that streaming
+   * does not support retries - for retry behavior, use `structured()`.
+   *
+   * @param schema - A Zod schema defining the expected response structure
+   * @param params - Customer chat parameters (excluding responseFormat)
+   * @param options - Request options
+   * @returns A structured JSON stream
+   */
+  async streamStructured(schema, params, options = {}) {
+    const { schemaName, ...requestOptions } = options;
+    const responseFormat = responseFormatFromZod(schema, schemaName);
+    return this.streamJSON(
+      { ...params, responseFormat },
+      requestOptions
+    );
+  }
 };
 var ChatCompletionsStream = class {
   constructor(response, requestId, context, metrics, trace) {
@@ -1370,7 +1898,13 @@ var ChatCompletionsStream = class {
     this.closed = true;
     try {
       await this.response.body?.cancel(reason);
-    } catch {
+    } catch (err) {
+      if (this.trace?.streamError) {
+        this.trace.streamError({
+          context: this.context,
+          error: err instanceof Error ? err : new Error(String(err))
+        });
+      }
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1469,7 +2003,13 @@ var StructuredJSONStream = class {
     this.closed = true;
     try {
       await this.response.body?.cancel(reason);
-    } catch {
+    } catch (err) {
+      if (this.trace?.streamError) {
+        this.trace.streamError({
+          context: this.context,
+          error: err instanceof Error ? err : new Error(String(err))
+        });
+      }
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1670,7 +2210,7 @@ function mapChatEvent(raw, requestId) {
   if (raw.data) {
     try {
       parsed = JSON.parse(raw.data);
-    } catch {
+    } catch (err) {
       parsed = raw.data;
     }
   }
@@ -1842,10 +2382,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,17 +3110,21 @@ 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,
   SDK_VERSION,
   StopReasons,
+  StructuredDecodeError,
+  StructuredExhaustedError,
   StructuredJSONStream,
   TiersClient,
   ToolArgsError,
@@ -2588,6 +3147,7 @@ function resolveBaseUrl(override) {
   createUsage,
   createUserMessage,
   createWebTool,
+  defaultRetryHandler,
   executeWithRetry,
   firstToolCall,
   formatToolErrorForModel,
@@ -2608,11 +3168,13 @@ function resolveBaseUrl(override) {
   parseToolArgs,
   parseToolArgsRaw,
   respondToToolCall,
+  responseFormatFromZod,
   stopReasonToString,
   toolChoiceAuto,
   toolChoiceNone,
   toolChoiceRequired,
   toolResultMessage,
   tryParseToolArgs,
+  validateWithZod,
   zodToJsonSchema
 });