@modelrelay/sdk 0.5.0 → 0.14.1

package/dist/index.cjs

@@ -30,16 +30,39 @@ __export(index_exports, {
   DEFAULT_CLIENT_HEADER: () => DEFAULT_CLIENT_HEADER,
   DEFAULT_CONNECT_TIMEOUT_MS: () => DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS: () => DEFAULT_REQUEST_TIMEOUT_MS,
+  ErrorCodes: () => ErrorCodes,
   ModelRelay: () => ModelRelay,
   ModelRelayError: () => ModelRelayError,
   Models: () => Models,
   Providers: () => Providers,
-  SANDBOX_BASE_URL: () => SANDBOX_BASE_URL,
   SDK_VERSION: () => SDK_VERSION,
-  STAGING_BASE_URL: () => STAGING_BASE_URL,
   StopReasons: () => StopReasons,
   TiersClient: () => TiersClient,
+  ToolArgsError: () => ToolArgsError,
+  ToolCallAccumulator: () => ToolCallAccumulator,
+  ToolChoiceTypes: () => ToolChoiceTypes,
+  ToolRegistry: () => ToolRegistry,
+  ToolTypes: () => ToolTypes,
   TransportError: () => TransportError,
+  assistantMessageWithToolCalls: () => assistantMessageWithToolCalls,
+  createAccessTokenAuth: () => createAccessTokenAuth,
+  createApiKeyAuth: () => createApiKeyAuth,
+  createAssistantMessage: () => createAssistantMessage,
+  createFunctionCall: () => createFunctionCall,
+  createFunctionTool: () => createFunctionTool,
+  createFunctionToolFromSchema: () => createFunctionToolFromSchema,
+  createRetryMessages: () => createRetryMessages,
+  createSystemMessage: () => createSystemMessage,
+  createToolCall: () => createToolCall,
+  createUsage: () => createUsage,
+  createUserMessage: () => createUserMessage,
+  createWebTool: () => createWebTool,
+  executeWithRetry: () => executeWithRetry,
+  firstToolCall: () => firstToolCall,
+  formatToolErrorForModel: () => formatToolErrorForModel,
+  getRetryableErrors: () => getRetryableErrors,
+  hasRetryableErrors: () => hasRetryableErrors,
+  hasToolCalls: () => hasToolCalls,
   isPublishableKey: () => isPublishableKey,
   mergeMetrics: () => mergeMetrics,
   mergeTrace: () => mergeTrace,
@@ -48,12 +71,34 @@ __export(index_exports, {
   normalizeProvider: () => normalizeProvider,
   normalizeStopReason: () => normalizeStopReason,
   parseErrorResponse: () => parseErrorResponse,
+  parseToolArgs: () => parseToolArgs,
+  parseToolArgsRaw: () => parseToolArgsRaw,
   providerToString: () => providerToString,
-  stopReasonToString: () => stopReasonToString
+  respondToToolCall: () => respondToToolCall,
+  stopReasonToString: () => stopReasonToString,
+  toolChoiceAuto: () => toolChoiceAuto,
+  toolChoiceNone: () => toolChoiceNone,
+  toolChoiceRequired: () => toolChoiceRequired,
+  toolResultMessage: () => toolResultMessage,
+  tryParseToolArgs: () => tryParseToolArgs,
+  zodToJsonSchema: () => zodToJsonSchema
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
+var ErrorCodes = {
+  NOT_FOUND: "NOT_FOUND",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  RATE_LIMIT: "RATE_LIMIT",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  CONFLICT: "CONFLICT",
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  INVALID_INPUT: "INVALID_INPUT",
+  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
+  METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED"
+};
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
     super(message);
@@ -97,6 +142,30 @@ var APIError = class extends ModelRelayError {
       retries: opts.retries
     });
   }
+  /** Returns true if the error is a not found error. */
+  isNotFound() {
+    return this.code === ErrorCodes.NOT_FOUND;
+  }
+  /** Returns true if the error is a validation error. */
+  isValidation() {
+    return this.code === ErrorCodes.VALIDATION_ERROR || this.code === ErrorCodes.INVALID_INPUT;
+  }
+  /** Returns true if the error is a rate limit error. */
+  isRateLimit() {
+    return this.code === ErrorCodes.RATE_LIMIT;
+  }
+  /** Returns true if the error is an unauthorized error. */
+  isUnauthorized() {
+    return this.code === ErrorCodes.UNAUTHORIZED;
+  }
+  /** Returns true if the error is a forbidden error. */
+  isForbidden() {
+    return this.code === ErrorCodes.FORBIDDEN;
+  }
+  /** Returns true if the error is a service unavailable error. */
+  isUnavailable() {
+    return this.code === ErrorCodes.SERVICE_UNAVAILABLE;
+  }
 };
 async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
@@ -151,6 +220,12 @@ async function parseErrorResponse(response, retries) {
 }
 
 // src/auth.ts
+function createApiKeyAuth(apiKey) {
+  return { apiKey };
+}
+function createAccessTokenAuth(accessToken) {
+  return { accessToken };
+}
 var AuthClient = class {
   constructor(http, cfg) {
     this.cachedFrontend = /* @__PURE__ */ new Map();
@@ -210,7 +285,7 @@ var AuthClient = class {
    */
   async authForChat(customerId, overrides) {
     if (this.accessToken) {
-      return { accessToken: this.accessToken };
+      return createAccessTokenAuth(this.accessToken);
     }
     if (!this.apiKey) {
       throw new ConfigError("API key or token is required");
@@ -221,21 +296,21 @@ var AuthClient = class {
         deviceId: overrides?.deviceId,
         ttlSeconds: overrides?.ttlSeconds
       });
-      return { accessToken: token.token };
+      return createAccessTokenAuth(token.token);
     }
-    return { apiKey: this.apiKey };
+    return createApiKeyAuth(this.apiKey);
   }
   /**
    * Billing calls accept either bearer tokens or API keys (including publishable keys).
    */
   authForBilling() {
     if (this.accessToken) {
-      return { accessToken: this.accessToken };
+      return createAccessTokenAuth(this.accessToken);
     }
     if (!this.apiKey) {
       throw new ConfigError("API key or token is required");
     }
-    return { apiKey: this.apiKey };
+    return createApiKeyAuth(this.apiKey);
   }
 };
 function isPublishableKey(value) {
@@ -273,7 +348,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.5.0",
+  version: "0.14.1",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -307,15 +382,14 @@ var package_default = {
   devDependencies: {
     tsup: "^8.2.4",
     typescript: "^5.6.3",
-    vitest: "^2.1.4"
+    vitest: "^2.1.4",
+    zod: "^3.23.0"
   }
 };
 
 // src/types.ts
 var SDK_VERSION = package_default.version || "0.0.0";
 var DEFAULT_BASE_URL = "https://api.modelrelay.ai/api/v1";
-var STAGING_BASE_URL = "https://api-stg.modelrelay.ai/api/v1";
-var SANDBOX_BASE_URL = "https://api.sandbox.modelrelay.ai/api/v1";
 var DEFAULT_CLIENT_HEADER = `modelrelay-ts/${SDK_VERSION}`;
 var DEFAULT_CONNECT_TIMEOUT_MS = 5e3;
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
@@ -336,22 +410,45 @@ var StopReasons = {
 var Providers = {
   OpenAI: "openai",
   Anthropic: "anthropic",
-  Grok: "grok",
-  OpenRouter: "openrouter",
+  XAI: "xai",
+  GoogleAIStudio: "google-ai-studio",
   Echo: "echo"
 };
 var Models = {
-  OpenAIGpt4o: "openai/gpt-4o",
-  OpenAIGpt4oMini: "openai/gpt-4o-mini",
-  OpenAIGpt51: "openai/gpt-5.1",
-  AnthropicClaude35HaikuLatest: "anthropic/claude-3-5-haiku-latest",
-  AnthropicClaude35SonnetLatest: "anthropic/claude-3-5-sonnet-latest",
-  AnthropicClaudeOpus45: "anthropic/claude-opus-4-5-20251101",
-  OpenRouterClaude35Haiku: "anthropic/claude-3.5-haiku",
+  // OpenAI models (provider-agnostic identifiers)
+  Gpt4o: "gpt-4o",
+  Gpt4oMini: "gpt-4o-mini",
+  Gpt51: "gpt-5.1",
+  // Anthropic models (provider-agnostic identifiers)
+  Claude35HaikuLatest: "claude-3-5-haiku-latest",
+  Claude35SonnetLatest: "claude-3-5-sonnet-latest",
+  ClaudeOpus45: "claude-opus-4-5",
+  Claude35Haiku: "claude-3.5-haiku",
+  // xAI / Grok models
   Grok2: "grok-2",
-  Grok4Fast: "grok-4-fast",
+  Grok4_1FastNonReasoning: "grok-4-1-fast-non-reasoning",
+  Grok4_1FastReasoning: "grok-4-1-fast-reasoning",
+  // Internal echo model for testing.
   Echo1: "echo-1"
 };
+function createUsage(inputTokens, outputTokens, totalTokens) {
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: totalTokens ?? inputTokens + outputTokens
+  };
+}
+var ToolTypes = {
+  Function: "function",
+  Web: "web",
+  XSearch: "x_search",
+  CodeExecution: "code_execution"
+};
+var ToolChoiceTypes = {
+  Auto: "auto",
+  Required: "required",
+  None: "none"
+};
 function mergeMetrics(base, override) {
   if (!base && !override) return void 0;
   return {
@@ -415,6 +512,630 @@ function modelToString(value) {
   return value.other?.trim() || "";
 }
 
+// src/tools.ts
+function createUserMessage(content) {
+  return { role: "user", content };
+}
+function createAssistantMessage(content) {
+  return { role: "assistant", content };
+}
+function createSystemMessage(content) {
+  return { role: "system", content };
+}
+function createToolCall(id, name, args, type = ToolTypes.Function) {
+  return {
+    id,
+    type,
+    function: createFunctionCall(name, args)
+  };
+}
+function createFunctionCall(name, args) {
+  return { name, arguments: args };
+}
+function zodToJsonSchema(schema, options = {}) {
+  const result = convertZodType(schema);
+  if (options.includeSchema) {
+    const schemaVersion = options.target === "draft-04" ? "http://json-schema.org/draft-04/schema#" : options.target === "draft-2019-09" ? "https://json-schema.org/draft/2019-09/schema" : options.target === "draft-2020-12" ? "https://json-schema.org/draft/2020-12/schema" : "http://json-schema.org/draft-07/schema#";
+    return { $schema: schemaVersion, ...result };
+  }
+  return result;
+}
+function convertZodType(schema) {
+  const def = schema._def;
+  const typeName = def.typeName;
+  switch (typeName) {
+    case "ZodString":
+      return convertZodString(def);
+    case "ZodNumber":
+      return convertZodNumber(def);
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodNull":
+      return { type: "null" };
+    case "ZodArray":
+      return convertZodArray(def);
+    case "ZodObject":
+      return convertZodObject(def);
+    case "ZodEnum":
+      return convertZodEnum(def);
+    case "ZodNativeEnum":
+      return convertZodNativeEnum(def);
+    case "ZodLiteral":
+      return { const: def.value };
+    case "ZodUnion":
+      return convertZodUnion(def);
+    case "ZodOptional": {
+      const inner = convertZodType(def.innerType);
+      if (def.description && !inner.description) {
+        inner.description = def.description;
+      }
+      return inner;
+    }
+    case "ZodNullable":
+      return convertZodNullable(def);
+    case "ZodDefault":
+      return { ...convertZodType(def.innerType), default: def.defaultValue() };
+    case "ZodEffects":
+      return convertZodType(def.schema);
+    case "ZodRecord":
+      return convertZodRecord(def);
+    case "ZodTuple":
+      return convertZodTuple(def);
+    case "ZodAny":
+    case "ZodUnknown":
+      return {};
+    default:
+      return {};
+  }
+}
+function convertZodString(def) {
+  const result = { type: "string" };
+  const checks = def.checks;
+  if (checks) {
+    for (const check of checks) {
+      switch (check.kind) {
+        case "min":
+          result.minLength = check.value;
+          break;
+        case "max":
+          result.maxLength = check.value;
+          break;
+        case "length":
+          result.minLength = check.value;
+          result.maxLength = check.value;
+          break;
+        case "email":
+          result.format = "email";
+          break;
+        case "url":
+          result.format = "uri";
+          break;
+        case "uuid":
+          result.format = "uuid";
+          break;
+        case "datetime":
+          result.format = "date-time";
+          break;
+        case "regex":
+          result.pattern = check.value.source;
+          break;
+      }
+    }
+  }
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodNumber(def) {
+  const result = { type: "number" };
+  const checks = def.checks;
+  if (checks) {
+    for (const check of checks) {
+      switch (check.kind) {
+        case "int":
+          result.type = "integer";
+          break;
+        case "min":
+          if (check.inclusive === false) {
+            result.exclusiveMinimum = check.value;
+          } else {
+            result.minimum = check.value;
+          }
+          break;
+        case "max":
+          if (check.inclusive === false) {
+            result.exclusiveMaximum = check.value;
+          } else {
+            result.maximum = check.value;
+          }
+          break;
+        case "multipleOf":
+          result.multipleOf = check.value;
+          break;
+      }
+    }
+  }
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodArray(def) {
+  const result = {
+    type: "array",
+    items: convertZodType(def.type)
+  };
+  if (def.minLength !== void 0 && def.minLength !== null) {
+    result.minItems = def.minLength.value;
+  }
+  if (def.maxLength !== void 0 && def.maxLength !== null) {
+    result.maxItems = def.maxLength.value;
+  }
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodObject(def) {
+  const shape = def.shape;
+  const shapeObj = typeof shape === "function" ? shape() : shape;
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(shapeObj)) {
+    properties[key] = convertZodType(value);
+    const valueDef = value._def;
+    const isOptional = valueDef.typeName === "ZodOptional" || valueDef.typeName === "ZodDefault" || valueDef.typeName === "ZodNullable" && valueDef.innerType?._def?.typeName === "ZodDefault";
+    if (!isOptional) {
+      required.push(key);
+    }
+  }
+  const result = {
+    type: "object",
+    properties
+  };
+  if (required.length > 0) {
+    result.required = required;
+  }
+  if (def.description) {
+    result.description = def.description;
+  }
+  const unknownKeys = def.unknownKeys;
+  if (unknownKeys === "strict") {
+    result.additionalProperties = false;
+  }
+  return result;
+}
+function convertZodEnum(def) {
+  const result = {
+    type: "string",
+    enum: def.values
+  };
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodNativeEnum(def) {
+  const enumValues = def.values;
+  const values = Object.values(enumValues).filter(
+    (v) => typeof v === "string" || typeof v === "number"
+  );
+  const result = { enum: values };
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodUnion(def) {
+  const options = def.options;
+  const result = {
+    anyOf: options.map(convertZodType)
+  };
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodNullable(def) {
+  const inner = convertZodType(def.innerType);
+  return {
+    anyOf: [inner, { type: "null" }]
+  };
+}
+function convertZodRecord(def) {
+  const result = {
+    type: "object",
+    additionalProperties: convertZodType(def.valueType)
+  };
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function convertZodTuple(def) {
+  const items = def.items;
+  const result = {
+    type: "array",
+    items: items.map(convertZodType),
+    minItems: items.length,
+    maxItems: items.length
+  };
+  if (def.description) {
+    result.description = def.description;
+  }
+  return result;
+}
+function createFunctionToolFromSchema(name, description, schema, options) {
+  const jsonSchema = zodToJsonSchema(schema, options);
+  return createFunctionTool(name, description, jsonSchema);
+}
+function createFunctionTool(name, description, parameters) {
+  const fn = { name, description };
+  if (parameters) {
+    fn.parameters = parameters;
+  }
+  return {
+    type: ToolTypes.Function,
+    function: fn
+  };
+}
+function createWebTool(options) {
+  return {
+    type: ToolTypes.Web,
+    web: options ? {
+      mode: options.mode,
+      allowedDomains: options.allowedDomains,
+      excludedDomains: options.excludedDomains,
+      maxUses: options.maxUses
+    } : void 0
+  };
+}
+function toolChoiceAuto() {
+  return { type: ToolChoiceTypes.Auto };
+}
+function toolChoiceRequired() {
+  return { type: ToolChoiceTypes.Required };
+}
+function toolChoiceNone() {
+  return { type: ToolChoiceTypes.None };
+}
+function hasToolCalls(response) {
+  return (response.toolCalls?.length ?? 0) > 0;
+}
+function firstToolCall(response) {
+  return response.toolCalls?.[0];
+}
+function toolResultMessage(toolCallId, result) {
+  const content = typeof result === "string" ? result : JSON.stringify(result);
+  return {
+    role: "tool",
+    content,
+    toolCallId
+  };
+}
+function respondToToolCall(call, result) {
+  return toolResultMessage(call.id, result);
+}
+function assistantMessageWithToolCalls(content, toolCalls) {
+  return {
+    role: "assistant",
+    content,
+    toolCalls
+  };
+}
+var ToolCallAccumulator = class {
+  constructor() {
+    this.calls = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Processes a streaming tool call delta.
+   * Returns true if this started a new tool call.
+   */
+  processDelta(delta) {
+    const existing = this.calls.get(delta.index);
+    if (!existing) {
+      this.calls.set(delta.index, {
+        id: delta.id ?? "",
+        type: delta.type ?? ToolTypes.Function,
+        function: {
+          name: delta.function?.name ?? "",
+          arguments: delta.function?.arguments ?? ""
+        }
+      });
+      return true;
+    }
+    if (delta.function) {
+      if (delta.function.name) {
+        existing.function = existing.function ?? { name: "", arguments: "" };
+        existing.function.name = delta.function.name;
+      }
+      if (delta.function.arguments) {
+        existing.function = existing.function ?? { name: "", arguments: "" };
+        existing.function.arguments += delta.function.arguments;
+      }
+    }
+    return false;
+  }
+  /**
+   * Returns all accumulated tool calls in index order.
+   */
+  getToolCalls() {
+    if (this.calls.size === 0) {
+      return [];
+    }
+    const maxIdx = Math.max(...this.calls.keys());
+    const result = [];
+    for (let i = 0; i <= maxIdx; i++) {
+      const call = this.calls.get(i);
+      if (call) {
+        result.push(call);
+      }
+    }
+    return result;
+  }
+  /**
+   * Returns a specific tool call by index, or undefined if not found.
+   */
+  getToolCall(index) {
+    return this.calls.get(index);
+  }
+  /**
+   * Clears all accumulated tool calls.
+   */
+  reset() {
+    this.calls.clear();
+  }
+};
+var ToolArgsError = class extends Error {
+  constructor(message, toolCallId, toolName, rawArguments) {
+    super(message);
+    this.name = "ToolArgsError";
+    this.toolCallId = toolCallId;
+    this.toolName = toolName;
+    this.rawArguments = rawArguments;
+  }
+};
+function parseToolArgs(call, schema) {
+  const toolName = call.function?.name ?? "unknown";
+  const rawArgs = call.function?.arguments ?? "";
+  let parsed;
+  try {
+    parsed = rawArgs ? JSON.parse(rawArgs) : {};
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid JSON in arguments";
+    throw new ToolArgsError(
+      `Failed to parse arguments for tool '${toolName}': ${message}`,
+      call.id,
+      toolName,
+      rawArgs
+    );
+  }
+  try {
+    return schema.parse(parsed);
+  } catch (err) {
+    let message;
+    if (err instanceof Error) {
+      const zodErr = err;
+      if (zodErr.errors && Array.isArray(zodErr.errors)) {
+        const issues = zodErr.errors.map((e) => {
+          const path = e.path.length > 0 ? `${e.path.join(".")}: ` : "";
+          return `${path}${e.message}`;
+        }).join("; ");
+        message = issues;
+      } else {
+        message = err.message;
+      }
+    } else {
+      message = String(err);
+    }
+    throw new ToolArgsError(
+      `Invalid arguments for tool '${toolName}': ${message}`,
+      call.id,
+      toolName,
+      rawArgs
+    );
+  }
+}
+function tryParseToolArgs(call, schema) {
+  try {
+    const data = parseToolArgs(call, schema);
+    return { success: true, data };
+  } catch (err) {
+    if (err instanceof ToolArgsError) {
+      return { success: false, error: err };
+    }
+    const toolName = call.function?.name ?? "unknown";
+    const rawArgs = call.function?.arguments ?? "";
+    return {
+      success: false,
+      error: new ToolArgsError(
+        err instanceof Error ? err.message : String(err),
+        call.id,
+        toolName,
+        rawArgs
+      )
+    };
+  }
+}
+function parseToolArgsRaw(call) {
+  const toolName = call.function?.name ?? "unknown";
+  const rawArgs = call.function?.arguments ?? "";
+  try {
+    return rawArgs ? JSON.parse(rawArgs) : {};
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid JSON in arguments";
+    throw new ToolArgsError(
+      `Failed to parse arguments for tool '${toolName}': ${message}`,
+      call.id,
+      toolName,
+      rawArgs
+    );
+  }
+}
+var ToolRegistry = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Registers a handler function for a tool name.
+   * @param name - The tool name (must match the function name in the tool definition)
+   * @param handler - Function to execute when this tool is called
+   * @returns this for chaining
+   */
+  register(name, handler) {
+    this.handlers.set(name, handler);
+    return this;
+  }
+  /**
+   * Unregisters a tool handler.
+   * @param name - The tool name to unregister
+   * @returns true if the handler was removed, false if it didn't exist
+   */
+  unregister(name) {
+    return this.handlers.delete(name);
+  }
+  /**
+   * Checks if a handler is registered for the given tool name.
+   */
+  has(name) {
+    return this.handlers.has(name);
+  }
+  /**
+   * Returns the list of registered tool names.
+   */
+  getRegisteredTools() {
+    return Array.from(this.handlers.keys());
+  }
+  /**
+   * Executes a single tool call.
+   * @param call - The tool call to execute
+   * @returns The execution result
+   */
+  async execute(call) {
+    const toolName = call.function?.name ?? "";
+    const handler = this.handlers.get(toolName);
+    if (!handler) {
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: `Unknown tool: '${toolName}'. Available tools: ${this.getRegisteredTools().join(", ") || "none"}`
+      };
+    }
+    let args;
+    try {
+      args = call.function?.arguments ? JSON.parse(call.function.arguments) : {};
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: `Invalid JSON in arguments: ${errorMessage}`,
+        isRetryable: true
+      };
+    }
+    try {
+      const result = await handler(args, call);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result
+      };
+    } catch (err) {
+      const isRetryable = err instanceof ToolArgsError;
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        toolCallId: call.id,
+        toolName,
+        result: null,
+        error: errorMessage,
+        isRetryable
+      };
+    }
+  }
+  /**
+   * Executes multiple tool calls in parallel.
+   * @param calls - Array of tool calls to execute
+   * @returns Array of execution results in the same order as input
+   */
+  async executeAll(calls) {
+    return Promise.all(calls.map((call) => this.execute(call)));
+  }
+  /**
+   * Converts execution results to tool result messages.
+   * Useful for appending to the conversation history.
+   * @param results - Array of execution results
+   * @returns Array of ChatMessage objects with role "tool"
+   */
+  resultsToMessages(results) {
+    return results.map((r) => {
+      const content = r.error ? `Error: ${r.error}` : typeof r.result === "string" ? r.result : JSON.stringify(r.result);
+      return toolResultMessage(r.toolCallId, content);
+    });
+  }
+};
+function formatToolErrorForModel(result) {
+  const lines = [
+    `Tool call error for '${result.toolName}': ${result.error}`
+  ];
+  if (result.isRetryable) {
+    lines.push("");
+    lines.push("Please correct the arguments and try again.");
+  }
+  return lines.join("\n");
+}
+function hasRetryableErrors(results) {
+  return results.some((r) => r.error && r.isRetryable);
+}
+function getRetryableErrors(results) {
+  return results.filter((r) => r.error && r.isRetryable);
+}
+function createRetryMessages(results) {
+  return results.filter((r) => r.error && r.isRetryable).map((r) => toolResultMessage(r.toolCallId, formatToolErrorForModel(r)));
+}
+async function executeWithRetry(registry, toolCalls, options = {}) {
+  const maxRetries = options.maxRetries ?? 2;
+  let currentCalls = toolCalls;
+  let attempt = 0;
+  const successfulResults = /* @__PURE__ */ new Map();
+  while (attempt <= maxRetries) {
+    const results = await registry.executeAll(currentCalls);
+    for (const result of results) {
+      if (!result.error || !result.isRetryable) {
+        successfulResults.set(result.toolCallId, result);
+      }
+    }
+    const retryableResults = getRetryableErrors(results);
+    if (retryableResults.length === 0 || !options.onRetry) {
+      for (const result of results) {
+        if (result.error && result.isRetryable) {
+          successfulResults.set(result.toolCallId, result);
+        }
+      }
+      return Array.from(successfulResults.values());
+    }
+    attempt++;
+    if (attempt > maxRetries) {
+      for (const result of retryableResults) {
+        successfulResults.set(result.toolCallId, result);
+      }
+      return Array.from(successfulResults.values());
+    }
+    const errorMessages = createRetryMessages(retryableResults);
+    const newCalls = await options.onRetry(errorMessages, attempt);
+    if (newCalls.length === 0) {
+      for (const result of retryableResults) {
+        successfulResults.set(result.toolCallId, result);
+      }
+      return Array.from(successfulResults.values());
+    }
+    currentCalls = newCalls;
+  }
+  return Array.from(successfulResults.values());
+}
+
 // src/chat.ts
 var REQUEST_ID_HEADER = "X-ModelRelay-Chat-Request-Id";
 var ChatClient = class {
@@ -440,16 +1161,13 @@ var ChatCompletionsClient = class {
     const stream = options.stream ?? params.stream ?? true;
     const metrics = mergeMetrics(this.metrics, options.metrics);
     const trace = mergeTrace(this.trace, options.trace);
-    const modelValue = modelToString(params.model).trim();
-    if (!modelValue) {
-      throw new ConfigError("model is required");
-    }
     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");
     }
+    validateRequestModel(params.model);
     const authHeaders = await this.auth.authForChat(params.customerId);
     const body = buildProxyBody(
       params,
@@ -588,7 +1306,7 @@ var ChatCompletionsStream = class {
     const context = this.enrichContext(evt);
     this.context = context;
     this.trace?.streamEvent?.({ context, event: evt });
-    if (evt.type === "message_start" || evt.type === "message_delta" || evt.type === "message_stop") {
+    if (evt.type === "message_start" || evt.type === "message_delta" || evt.type === "message_stop" || evt.type === "tool_use_start" || evt.type === "tool_use_delta" || evt.type === "tool_use_stop") {
       this.recordFirstToken();
     }
     if (evt.type === "message_stop" && evt.usage && this.metrics?.usage) {
@@ -673,11 +1391,15 @@ function mapChatEvent(raw, requestId) {
   const model = normalizeModelId(p.model || p?.message?.model);
   const stopReason = normalizeStopReason(p.stop_reason);
   const textDelta = extractTextDelta(p);
+  const toolCallDelta = extractToolCallDelta(p, type);
+  const toolCalls = extractToolCalls(p, type);
   return {
     type,
     event: raw.event || type,
     data: p,
     textDelta,
+    toolCallDelta,
+    toolCalls,
     responseId,
     model,
     stopReason,
@@ -697,6 +1419,12 @@ function normalizeEventType(eventName, payload) {
       return "message_delta";
     case "message_stop":
       return "message_stop";
+    case "tool_use_start":
+      return "tool_use_start";
+    case "tool_use_delta":
+      return "tool_use_delta";
+    case "tool_use_stop":
+      return "tool_use_stop";
     case "ping":
       return "ping";
     default:
@@ -707,6 +1435,9 @@ function extractTextDelta(payload) {
   if (!payload || typeof payload !== "object") {
     return void 0;
   }
+  if (typeof payload.text_delta === "string" && payload.text_delta !== "") {
+    return payload.text_delta;
+  }
   if (typeof payload.delta === "string") {
     return payload.delta;
   }
@@ -720,9 +1451,56 @@ function extractTextDelta(payload) {
   }
   return void 0;
 }
+function extractToolCallDelta(payload, type) {
+  if (!payload || typeof payload !== "object") {
+    return void 0;
+  }
+  if (type !== "tool_use_start" && type !== "tool_use_delta") {
+    return void 0;
+  }
+  if (payload.tool_call_delta) {
+    const d = payload.tool_call_delta;
+    return {
+      index: d.index ?? 0,
+      id: d.id,
+      type: d.type,
+      function: d.function ? {
+        name: d.function.name,
+        arguments: d.function.arguments
+      } : void 0
+    };
+  }
+  if (typeof payload.index === "number" || payload.id || payload.name) {
+    return {
+      index: payload.index ?? 0,
+      id: payload.id,
+      type: payload.tool_type,
+      function: payload.name || payload.arguments ? {
+        name: payload.name,
+        arguments: payload.arguments
+      } : void 0
+    };
+  }
+  return void 0;
+}
+function extractToolCalls(payload, type) {
+  if (!payload || typeof payload !== "object") {
+    return void 0;
+  }
+  if (type !== "tool_use_stop" && type !== "message_stop") {
+    return void 0;
+  }
+  if (payload.tool_calls?.length) {
+    return normalizeToolCalls(payload.tool_calls);
+  }
+  if (payload.tool_call) {
+    return normalizeToolCalls([payload.tool_call]);
+  }
+  return void 0;
+}
 function normalizeChatResponse(payload, requestId) {
   const p = payload;
-  return {
+  const response = {
     id: p?.id,
     provider: normalizeProvider(p?.provider),
     content: Array.isArray(p?.content) ? p.content : p?.content ? [String(p.content)] : [],
@@ -731,26 +1509,51 @@ function normalizeChatResponse(payload, requestId) {
     usage: normalizeUsage(p?.usage),
     requestId
   };
+  if (p?.tool_calls?.length) {
+    response.toolCalls = normalizeToolCalls(p.tool_calls);
+  }
+  return response;
+}
+function normalizeToolCalls(toolCalls) {
+  return toolCalls.map(
+    (tc) => createToolCall(
+      tc.id,
+      tc.function?.name ?? "",
+      tc.function?.arguments ?? "",
+      tc.type || ToolTypes.Function
+    )
+  );
 }
 function normalizeUsage(payload) {
   if (!payload) {
-    return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    return createUsage(0, 0, 0);
   }
-  const usage = {
-    inputTokens: Number(payload.input_tokens ?? 0),
-    outputTokens: Number(payload.output_tokens ?? 0),
-    totalTokens: Number(payload.total_tokens ?? 0)
-  };
-  if (!usage.totalTokens) {
-    usage.totalTokens = usage.inputTokens + usage.outputTokens;
+  const inputTokens = Number(payload.input_tokens ?? 0);
+  const outputTokens = Number(payload.output_tokens ?? 0);
+  const totalTokens = Number(payload.total_tokens ?? 0);
+  return createUsage(inputTokens, outputTokens, totalTokens || void 0);
+}
+function validateRequestModel(model) {
+  if (model === void 0 || model === null) return;
+  const value = modelToString(model).trim();
+  if (!value) {
+    throw new ConfigError("model id must be a non-empty string when provided");
+  }
+  const knownModels = Object.values(Models);
+  if (!knownModels.includes(value)) {
+    throw new ConfigError(
+      `unsupported model id "${value}". Use one of the SDK Models.* constants or omit model to use the tier's default model.`
+    );
   }
-  return usage;
 }
 function buildProxyBody(params, metadata) {
+  const modelValue = params.model ? modelToString(params.model).trim() : "";
   const body = {
-    model: modelToString(params.model),
     messages: normalizeMessages(params.messages)
   };
+  if (modelValue) {
+    body.model = modelValue;
+  }
   if (typeof params.maxTokens === "number") body.max_tokens = params.maxTokens;
   if (params.provider) body.provider = providerToString(params.provider);
   if (typeof params.temperature === "number")
@@ -758,13 +1561,69 @@ function buildProxyBody(params, metadata) {
   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);
   return body;
 }
 function normalizeMessages(messages) {
-  return messages.map((msg) => ({
-    role: msg.role || "user",
-    content: msg.content
-  }));
+  return messages.map((msg) => {
+    const normalized = {
+      role: msg.role || "user",
+      content: msg.content
+    };
+    if (msg.toolCalls?.length) {
+      normalized.tool_calls = msg.toolCalls.map((tc) => ({
+        id: tc.id,
+        type: tc.type,
+        function: tc.function ? createFunctionCall(tc.function.name, tc.function.arguments) : void 0
+      }));
+    }
+    if (msg.toolCallId) {
+      normalized.tool_call_id = msg.toolCallId;
+    }
+    return normalized;
+  });
+}
+function normalizeTools(tools) {
+  return tools.map((tool) => {
+    const normalized = { type: tool.type };
+    if (tool.function) {
+      normalized.function = {
+        name: tool.function.name,
+        description: tool.function.description,
+        parameters: tool.function.parameters
+      };
+    }
+    if (tool.web) {
+      const web = {
+        allowed_domains: tool.web.allowedDomains,
+        excluded_domains: tool.web.excludedDomains,
+        max_uses: tool.web.maxUses
+      };
+      if (tool.web.mode) {
+        web.mode = tool.web.mode;
+      }
+      normalized.web = web;
+    }
+    if (tool.xSearch) {
+      normalized.x_search = {
+        allowed_handles: tool.xSearch.allowedHandles,
+        excluded_handles: tool.xSearch.excludedHandles,
+        from_date: tool.xSearch.fromDate,
+        to_date: tool.xSearch.toDate
+      };
+    }
+    if (tool.codeExecution) {
+      normalized.code_execution = {
+        language: tool.codeExecution.language,
+        timeout_ms: tool.codeExecution.timeoutMs
+      };
+    }
+    return normalized;
+  });
+}
+function normalizeToolChoice(tc) {
+  return { type: tc.type };
 }
 function requestIdFromHeaders(headers) {
   return headers.get(REQUEST_ID_HEADER) || headers.get("X-Request-Id") || void 0;
@@ -789,6 +1648,10 @@ function hasUserMessage(messages) {
 }
 
 // src/customers.ts
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidEmail(email) {
+  return EMAIL_REGEX.test(email);
+}
 var CustomersClient = class {
   constructor(http, cfg) {
     this.http = http;
@@ -823,6 +1686,12 @@ var CustomersClient = class {
     if (!request.external_id?.trim()) {
       throw new ConfigError("external_id is required");
     }
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required");
+    }
+    if (!isValidEmail(request.email)) {
+      throw new ConfigError("invalid email format");
+    }
     const response = await this.http.json("/customers", {
       method: "POST",
       body: request,
@@ -860,6 +1729,12 @@ var CustomersClient = class {
     if (!request.external_id?.trim()) {
       throw new ConfigError("external_id is required");
     }
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required");
+    }
+    if (!isValidEmail(request.email)) {
+      throw new ConfigError("invalid email format");
+    }
     const response = await this.http.json("/customers", {
       method: "PUT",
       body: request,
@@ -961,10 +1836,7 @@ var TiersClient = class {
 // src/http.ts
 var HTTPClient = class {
   constructor(cfg) {
-    const baseFromEnv = baseUrlForEnvironment(cfg.environment);
-    const resolvedBase = normalizeBaseUrl(
-      cfg.baseUrl || baseFromEnv || DEFAULT_BASE_URL
-    );
+    const resolvedBase = normalizeBaseUrl(cfg.baseUrl || DEFAULT_BASE_URL);
     if (!isValidHttpUrl(resolvedBase)) {
       throw new ConfigError(
         "baseUrl must start with http:// or https://"
@@ -1177,12 +2049,6 @@ function normalizeBaseUrl(value) {
 function isValidHttpUrl(value) {
   return /^https?:\/\//i.test(value);
 }
-function baseUrlForEnvironment(env) {
-  if (!env || env === "production") return void 0;
-  if (env === "staging") return STAGING_BASE_URL;
-  if (env === "sandbox") return SANDBOX_BASE_URL;
-  return void 0;
-}
 function normalizeRetryConfig(retry) {
   if (retry === false) return void 0;
   const cfg = retry || {};
@@ -1301,7 +2167,7 @@ var ModelRelay = class {
     if (!cfg.key && !cfg.token) {
       throw new ConfigError("Provide an API key or access token");
     }
-    this.baseUrl = resolveBaseUrl(cfg.environment, cfg.baseUrl);
+    this.baseUrl = resolveBaseUrl(cfg.baseUrl);
     const http = new HTTPClient({
       baseUrl: this.baseUrl,
       apiKey: cfg.key,
@@ -1312,7 +2178,6 @@ var ModelRelay = class {
       timeoutMs: cfg.timeoutMs,
       retry: cfg.retry,
       defaultHeaders: cfg.defaultHeaders,
-      environment: cfg.environment,
       metrics: cfg.metrics,
       trace: cfg.trace
     });
@@ -1335,8 +2200,8 @@ var ModelRelay = class {
     });
   }
 };
-function resolveBaseUrl(env, override) {
-  const base = override || (env === "staging" ? STAGING_BASE_URL : env === "sandbox" ? SANDBOX_BASE_URL : DEFAULT_BASE_URL);
+function resolveBaseUrl(override) {
+  const base = override || DEFAULT_BASE_URL;
   return base.replace(/\/+$/, "");
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1351,16 +2216,39 @@ function resolveBaseUrl(env, override) {
   DEFAULT_CLIENT_HEADER,
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS,
+  ErrorCodes,
   ModelRelay,
   ModelRelayError,
   Models,
   Providers,
-  SANDBOX_BASE_URL,
   SDK_VERSION,
-  STAGING_BASE_URL,
   StopReasons,
   TiersClient,
+  ToolArgsError,
+  ToolCallAccumulator,
+  ToolChoiceTypes,
+  ToolRegistry,
+  ToolTypes,
   TransportError,
+  assistantMessageWithToolCalls,
+  createAccessTokenAuth,
+  createApiKeyAuth,
+  createAssistantMessage,
+  createFunctionCall,
+  createFunctionTool,
+  createFunctionToolFromSchema,
+  createRetryMessages,
+  createSystemMessage,
+  createToolCall,
+  createUsage,
+  createUserMessage,
+  createWebTool,
+  executeWithRetry,
+  firstToolCall,
+  formatToolErrorForModel,
+  getRetryableErrors,
+  hasRetryableErrors,
+  hasToolCalls,
   isPublishableKey,
   mergeMetrics,
   mergeTrace,
@@ -1369,6 +2257,15 @@ function resolveBaseUrl(env, override) {
   normalizeProvider,
   normalizeStopReason,
   parseErrorResponse,
+  parseToolArgs,
+  parseToolArgsRaw,
   providerToString,
-  stopReasonToString
+  respondToToolCall,
+  stopReasonToString,
+  toolChoiceAuto,
+  toolChoiceNone,
+  toolChoiceRequired,
+  toolResultMessage,
+  tryParseToolArgs,
+  zodToJsonSchema
 });