@modelrelay/sdk 0.2.0 → 0.5.0

package/dist/index.cjs

@@ -20,20 +20,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  ApiKeysClient: () => ApiKeysClient,
+  APIError: () => APIError,
   AuthClient: () => AuthClient,
-  BillingClient: () => BillingClient,
   ChatClient: () => ChatClient,
   ChatCompletionsStream: () => ChatCompletionsStream,
+  ConfigError: () => ConfigError,
+  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,
   ModelRelay: () => ModelRelay,
   ModelRelayError: () => ModelRelayError,
+  Models: () => Models,
+  Providers: () => Providers,
   SANDBOX_BASE_URL: () => SANDBOX_BASE_URL,
   SDK_VERSION: () => SDK_VERSION,
   STAGING_BASE_URL: () => STAGING_BASE_URL,
-  isPublishableKey: () => isPublishableKey
+  StopReasons: () => StopReasons,
+  TiersClient: () => TiersClient,
+  TransportError: () => TransportError,
+  isPublishableKey: () => isPublishableKey,
+  mergeMetrics: () => mergeMetrics,
+  mergeTrace: () => mergeTrace,
+  modelToString: () => modelToString,
+  normalizeModelId: () => normalizeModelId,
+  normalizeProvider: () => normalizeProvider,
+  normalizeStopReason: () => normalizeStopReason,
+  parseErrorResponse: () => parseErrorResponse,
+  providerToString: () => providerToString,
+  stopReasonToString: () => stopReasonToString
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -41,15 +57,48 @@ module.exports = __toCommonJS(index_exports);
 var ModelRelayError = class extends Error {
   constructor(message, opts) {
     super(message);
-    this.name = "ModelRelayError";
+    this.name = this.constructor.name;
+    this.category = opts.category;
     this.status = opts.status;
     this.code = opts.code;
     this.requestId = opts.requestId;
     this.fields = opts.fields;
     this.data = opts.data;
+    this.retries = opts.retries;
+    this.cause = opts.cause;
   }
 };
-async function parseErrorResponse(response) {
+var ConfigError = class extends ModelRelayError {
+  constructor(message, data) {
+    super(message, { category: "config", status: 400, data });
+  }
+};
+var TransportError = class extends ModelRelayError {
+  constructor(message, opts) {
+    super(message, {
+      category: "transport",
+      status: opts.kind === "timeout" ? 408 : 0,
+      retries: opts.retries,
+      cause: opts.cause,
+      data: opts.cause
+    });
+    this.kind = opts.kind;
+  }
+};
+var APIError = class extends ModelRelayError {
+  constructor(message, opts) {
+    super(message, {
+      category: "api",
+      status: opts.status,
+      code: opts.code,
+      requestId: opts.requestId,
+      fields: opts.fields,
+      data: opts.data,
+      retries: opts.retries
+    });
+  }
+};
+async function parseErrorResponse(response, retries) {
   const requestId = response.headers.get("X-ModelRelay-Chat-Request-Id") || response.headers.get("X-Request-Id") || void 0;
   const fallbackMessage = response.statusText || "Request failed";
   const status = response.status || 500;
@@ -59,7 +108,7 @@ async function parseErrorResponse(response) {
   } catch {
   }
   if (!bodyText) {
-    return new ModelRelayError(fallbackMessage, { status, requestId });
+    return new APIError(fallbackMessage, { status, requestId, retries });
   }
   try {
     const parsed = JSON.parse(bodyText);
@@ -70,31 +119,34 @@ async function parseErrorResponse(response) {
       const code = errPayload?.code || void 0;
       const fields = Array.isArray(errPayload?.fields) ? errPayload?.fields : void 0;
       const parsedStatus = typeof errPayload?.status === "number" ? errPayload.status : status;
-      return new ModelRelayError(message, {
+      return new APIError(message, {
         status: parsedStatus,
         code,
         fields,
         requestId: parsedObj?.request_id || parsedObj?.requestId || requestId,
-        data: parsed
+        data: parsed,
+        retries
       });
     }
     if (parsedObj?.message || parsedObj?.code) {
       const message = parsedObj.message || fallbackMessage;
-      return new ModelRelayError(message, {
+      return new APIError(message, {
         status,
         code: parsedObj.code,
         fields: parsedObj.fields,
         requestId: parsedObj?.request_id || parsedObj?.requestId || requestId,
-        data: parsed
+        data: parsed,
+        retries
       });
     }
-    return new ModelRelayError(fallbackMessage, {
+    return new APIError(fallbackMessage, {
       status,
       requestId,
-      data: parsed
+      data: parsed,
+      retries
     });
   } catch {
-    return new ModelRelayError(bodyText, { status, requestId });
+    return new APIError(bodyText, { status, requestId, retries });
   }
 }
 
@@ -105,7 +157,7 @@ var AuthClient = class {
     this.http = http;
     this.apiKey = cfg.apiKey;
     this.accessToken = cfg.accessToken;
-    this.endUser = cfg.endUser;
+    this.customer = cfg.customer;
   }
   /**
    * Exchange a publishable key for a short-lived frontend token.
@@ -114,28 +166,22 @@ var AuthClient = class {
   async frontendToken(request) {
     const publishableKey = request?.publishableKey || (isPublishableKey(this.apiKey) ? this.apiKey : void 0);
     if (!publishableKey) {
-      throw new ModelRelayError(
-        "publishable key required to issue frontend tokens",
-        { status: 400 }
-      );
+      throw new ConfigError("publishable key required to issue frontend tokens");
     }
-    const userId = request?.userId || this.endUser?.id;
-    if (!userId) {
-      throw new ModelRelayError(
-        "endUserId is required to mint a frontend token",
-        { status: 400 }
-      );
+    const customerId = request?.customerId || this.customer?.id;
+    if (!customerId) {
+      throw new ConfigError("customerId is required to mint a frontend token");
     }
-    const deviceId = request?.deviceId || this.endUser?.deviceId;
-    const ttlSeconds = request?.ttlSeconds ?? this.endUser?.ttlSeconds;
-    const cacheKey = `${publishableKey}:${userId}:${deviceId || ""}`;
+    const deviceId = request?.deviceId || this.customer?.deviceId;
+    const ttlSeconds = request?.ttlSeconds ?? this.customer?.ttlSeconds;
+    const cacheKey = `${publishableKey}:${customerId}:${deviceId || ""}`;
     const cached = this.cachedFrontend.get(cacheKey);
     if (cached && isTokenReusable(cached)) {
       return cached;
     }
     const payload = {
       publishable_key: publishableKey,
-      user_id: userId
+      customer_id: customerId
     };
     if (deviceId) {
       payload.device_id = deviceId;
@@ -152,7 +198,7 @@ var AuthClient = class {
     );
     const token = normalizeFrontendToken(response, {
       publishableKey,
-      userId,
+      customerId,
       deviceId
     });
     this.cachedFrontend.set(cacheKey, token);
@@ -162,18 +208,16 @@ var AuthClient = class {
    * Determine the correct auth headers for chat completions.
    * Publishable keys are automatically exchanged for frontend tokens.
    */
-  async authForChat(endUserId, overrides) {
+  async authForChat(customerId, overrides) {
     if (this.accessToken) {
       return { accessToken: this.accessToken };
     }
     if (!this.apiKey) {
-      throw new ModelRelayError("API key or token is required", {
-        status: 401
-      });
+      throw new ConfigError("API key or token is required");
     }
     if (isPublishableKey(this.apiKey)) {
       const token = await this.frontendToken({
-        userId: endUserId || overrides?.id,
+        customerId: customerId || overrides?.id,
         deviceId: overrides?.deviceId,
         ttlSeconds: overrides?.ttlSeconds
       });
@@ -189,9 +233,7 @@ var AuthClient = class {
       return { accessToken: this.accessToken };
     }
     if (!this.apiKey) {
-      throw new ModelRelayError("API key or token is required", {
-        status: 401
-      });
+      throw new ConfigError("API key or token is required");
     }
     return { apiKey: this.apiKey };
   }
@@ -203,17 +245,17 @@ function isPublishableKey(value) {
   return value.trim().toLowerCase().startsWith("mr_pk_");
 }
 function normalizeFrontendToken(payload, meta) {
-  const expiresAt = payload.expires_at || payload.expiresAt;
+  const expiresAt = payload.expires_at;
   return {
     token: payload.token,
     expiresAt: expiresAt ? new Date(expiresAt) : void 0,
-    expiresIn: payload.expires_in ?? payload.expiresIn,
-    tokenType: payload.token_type ?? payload.tokenType,
-    keyId: payload.key_id ?? payload.keyId,
-    sessionId: payload.session_id ?? payload.sessionId,
-    tokenScope: payload.token_scope ?? payload.tokenScope,
-    tokenSource: payload.token_source ?? payload.tokenSource,
-    endUserId: meta.userId,
+    expiresIn: payload.expires_in,
+    tokenType: payload.token_type,
+    keyId: payload.key_id,
+    sessionId: payload.session_id,
+    tokenScope: payload.token_scope,
+    tokenSource: payload.token_source,
+    customerId: meta.customerId,
     publishableKey: meta.publishableKey,
     deviceId: meta.deviceId
   };
@@ -228,120 +270,149 @@ function isTokenReusable(token) {
   return token.expiresAt.getTime() - Date.now() > 6e4;
 }
 
-// src/api-keys.ts
-var ApiKeysClient = class {
-  constructor(http) {
-    this.http = http;
-  }
-  async list() {
-    const payload = await this.http.json("/api-keys", {
-      method: "GET"
-    });
-    const items = payload.api_keys || payload.apiKeys || [];
-    return items.map(normalizeApiKey).filter(Boolean);
-  }
-  async create(req) {
-    if (!req?.label?.trim()) {
-      throw new ModelRelayError("label is required", { status: 400 });
-    }
-    const body = {
-      label: req.label
-    };
-    if (req.kind) body.kind = req.kind;
-    if (req.expiresAt instanceof Date) {
-      body.expires_at = req.expiresAt.toISOString();
-    }
-    const payload = await this.http.json("/api-keys", {
-      method: "POST",
-      body
-    });
-    const record = payload.api_key || payload.apiKey;
-    if (!record) {
-      throw new ModelRelayError("missing api_key in response", {
-        status: 500
-      });
-    }
-    return normalizeApiKey(record);
-  }
-  async delete(id) {
-    if (!id?.trim()) {
-      throw new ModelRelayError("id is required", { status: 400 });
+// package.json
+var package_default = {
+  name: "@modelrelay/sdk",
+  version: "0.5.0",
+  description: "TypeScript SDK for the ModelRelay API",
+  type: "module",
+  main: "dist/index.cjs",
+  module: "dist/index.js",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
     }
-    await this.http.request(`/api-keys/${encodeURIComponent(id)}`, {
-      method: "DELETE"
-    });
+  },
+  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"
   }
 };
-function normalizeApiKey(record) {
-  const created = record?.created_at || record?.createdAt || "";
-  const expires = record?.expires_at ?? record?.expiresAt ?? void 0;
-  const lastUsed = record?.last_used_at ?? record?.lastUsedAt ?? void 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;
+var StopReasons = {
+  Completed: "completed",
+  Stop: "stop",
+  StopSequence: "stop_sequence",
+  EndTurn: "end_turn",
+  MaxTokens: "max_tokens",
+  MaxLength: "max_len",
+  MaxContext: "max_context",
+  ToolCalls: "tool_calls",
+  TimeLimit: "time_limit",
+  ContentFilter: "content_filter",
+  Incomplete: "incomplete",
+  Unknown: "unknown"
+};
+var Providers = {
+  OpenAI: "openai",
+  Anthropic: "anthropic",
+  Grok: "grok",
+  OpenRouter: "openrouter",
+  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",
+  Grok2: "grok-2",
+  Grok4Fast: "grok-4-fast",
+  Echo1: "echo-1"
+};
+function mergeMetrics(base, override) {
+  if (!base && !override) return void 0;
   return {
-    id: record?.id || "",
-    label: record?.label || "",
-    kind: record?.kind || "",
-    createdAt: created ? new Date(created) : /* @__PURE__ */ new Date(),
-    expiresAt: expires ? new Date(expires) : void 0,
-    lastUsedAt: lastUsed ? new Date(lastUsed) : void 0,
-    redactedKey: record?.redacted_key || record?.redactedKey || "",
-    secretKey: record?.secret_key ?? record?.secretKey ?? void 0
+    ...base || {},
+    ...override || {}
   };
 }
-
-// src/billing.ts
-var BillingClient = class {
-  constructor(http, auth) {
-    this.http = http;
-    this.auth = auth;
+function mergeTrace(base, override) {
+  if (!base && !override) return void 0;
+  return {
+    ...base || {},
+    ...override || {}
+  };
+}
+function normalizeStopReason(value) {
+  if (value === void 0 || value === null) return void 0;
+  const str = String(value).trim();
+  const lower = str.toLowerCase();
+  for (const reason of Object.values(StopReasons)) {
+    if (lower === reason) return reason;
   }
-  /**
-   * Initiate a Stripe Checkout session for an end user.
-   */
-  async checkout(params) {
-    if (!params?.endUserId?.trim()) {
-      throw new ModelRelayError("endUserId is required", { status: 400 });
-    }
-    if (!params.successUrl?.trim() || !params.cancelUrl?.trim()) {
-      throw new ModelRelayError("successUrl and cancelUrl are required", {
-        status: 400
-      });
-    }
-    const authHeaders = this.auth.authForBilling();
-    const body = {
-      end_user_id: params.endUserId,
-      success_url: params.successUrl,
-      cancel_url: params.cancelUrl
-    };
-    if (params.deviceId) body.device_id = params.deviceId;
-    if (params.planId) body.plan_id = params.planId;
-    if (params.plan) body.plan = params.plan;
-    const response = await this.http.json(
-      "/end-users/checkout",
-      {
-        method: "POST",
-        body,
-        apiKey: authHeaders.apiKey,
-        accessToken: authHeaders.accessToken
-      }
-    );
-    return normalizeCheckoutResponse(response);
+  switch (lower) {
+    case "length":
+      return StopReasons.MaxLength;
+    default:
+      return { other: str };
   }
-};
-function normalizeCheckoutResponse(payload) {
-  const endUser = {
-    id: payload.end_user?.id || "",
-    externalId: payload.end_user?.external_id || "",
-    ownerId: payload.end_user?.owner_id || ""
-  };
-  const session = {
-    id: payload.session?.id || "",
-    plan: payload.session?.plan || "",
-    status: payload.session?.status || "",
-    url: payload.session?.url || "",
-    expiresAt: payload.session?.expires_at ? new Date(payload.session.expires_at) : void 0,
-    completedAt: payload.session?.completed_at ? new Date(payload.session.completed_at) : void 0
-  };
-  return { endUser, session };
+}
+function stopReasonToString(value) {
+  if (!value) return void 0;
+  if (typeof value === "string") return value;
+  return value.other?.trim() || void 0;
+}
+function normalizeProvider(value) {
+  if (value === void 0 || value === null) return void 0;
+  const str = String(value).trim();
+  if (!str) return void 0;
+  const lower = str.toLowerCase();
+  for (const p of Object.values(Providers)) {
+    if (lower === p) return p;
+  }
+  return { other: str };
+}
+function providerToString(value) {
+  if (!value) return void 0;
+  if (typeof value === "string") return value;
+  return value.other?.trim() || void 0;
+}
+function normalizeModelId(value) {
+  if (value === void 0 || value === null) return void 0;
+  const str = String(value).trim();
+  if (!str) return void 0;
+  const lower = str.toLowerCase();
+  for (const m of Object.values(Models)) {
+    if (lower === m) return m;
+  }
+  return { other: str };
+}
+function modelToString(value) {
+  if (typeof value === "string") return value;
+  return value.other?.trim() || "";
 }
 
 // src/chat.ts
@@ -351,33 +422,35 @@ var ChatClient = class {
     this.completions = new ChatCompletionsClient(
       http,
       auth,
-      cfg.defaultMetadata
+      cfg.defaultMetadata,
+      cfg.metrics,
+      cfg.trace
     );
   }
 };
 var ChatCompletionsClient = class {
-  constructor(http, auth, defaultMetadata) {
+  constructor(http, auth, defaultMetadata, metrics, trace) {
     this.http = http;
     this.auth = auth;
     this.defaultMetadata = defaultMetadata;
+    this.metrics = metrics;
+    this.trace = trace;
   }
   async create(params, options = {}) {
     const stream = options.stream ?? params.stream ?? true;
-    if (!params?.model?.trim()) {
-      throw new ModelRelayError("model is required", { status: 400 });
+    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 ModelRelayError("at least one message is required", {
-        status: 400
-      });
+      throw new ConfigError("at least one message is required");
     }
     if (!hasUserMessage(params.messages)) {
-      throw new ModelRelayError(
-        "at least one user message is required",
-        { status: 400 }
-      );
+      throw new ConfigError("at least one user message is required");
     }
-    const authHeaders = await this.auth.authForChat(params.endUserId);
+    const authHeaders = await this.auth.authForChat(params.customerId);
     const body = buildProxyBody(
       params,
       mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
@@ -387,6 +460,13 @@ var ChatCompletionsClient = class {
     if (requestId) {
       headers[REQUEST_ID_HEADER] = requestId;
     }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      provider: params.provider,
+      model: params.model,
+      requestId
+    };
     const response = await this.http.request("/llm/proxy", {
       method: "POST",
       body,
@@ -398,7 +478,11 @@ var ChatCompletionsClient = class {
       signal: options.signal,
       timeoutMs: options.timeoutMs ?? (stream ? 0 : void 0),
       useDefaultTimeout: !stream,
-      retry: options.retry
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
     });
     const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
     if (!response.ok) {
@@ -406,21 +490,43 @@ var ChatCompletionsClient = class {
     }
     if (!stream) {
       const payload = await response.json();
-      return normalizeChatResponse(payload, resolvedRequestId);
+      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;
     }
-    return new ChatCompletionsStream(response, resolvedRequestId);
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new ChatCompletionsStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
   }
 };
 var ChatCompletionsStream = class {
-  constructor(response, requestId) {
+  constructor(response, requestId, context, metrics, trace) {
+    this.firstTokenEmitted = false;
     this.closed = false;
     if (!response.body) {
-      throw new ModelRelayError("streaming response is missing a body", {
-        status: 500
-      });
+      throw new ConfigError("streaming response is missing a body");
     }
     this.response = response;
     this.requestId = requestId;
+    this.context = context;
+    this.metrics = metrics;
+    this.trace = trace;
+    this.startedAt = this.metrics?.streamFirstToken || this.trace?.streamEvent || this.trace?.streamError ? Date.now() : 0;
   }
   async cancel(reason) {
     this.closed = true;
@@ -435,9 +541,7 @@ var ChatCompletionsStream = class {
     }
     const body = this.response.body;
     if (!body) {
-      throw new ModelRelayError("streaming response is missing a body", {
-        status: 500
-      });
+      throw new ConfigError("streaming response is missing a body");
     }
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -454,6 +558,7 @@ var ChatCompletionsStream = class {
           for (const evt of events2) {
             const parsed = mapChatEvent(evt, this.requestId);
             if (parsed) {
+              this.handleStreamEvent(parsed);
               yield parsed;
             }
           }
@@ -465,15 +570,49 @@ var ChatCompletionsStream = class {
         for (const evt of events) {
           const parsed = mapChatEvent(evt, this.requestId);
           if (parsed) {
+            this.handleStreamEvent(parsed);
             yield parsed;
           }
         }
       }
+    } catch (err) {
+      this.recordFirstToken(err);
+      this.trace?.streamError?.({ context: this.context, error: err });
+      throw err;
     } finally {
       this.closed = true;
       reader.releaseLock();
     }
   }
+  handleStreamEvent(evt) {
+    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") {
+      this.recordFirstToken();
+    }
+    if (evt.type === "message_stop" && evt.usage && this.metrics?.usage) {
+      this.metrics.usage({ usage: evt.usage, context });
+    }
+  }
+  enrichContext(evt) {
+    return {
+      ...this.context,
+      responseId: evt.responseId || this.context.responseId,
+      requestId: evt.requestId || this.context.requestId,
+      model: evt.model || this.context.model
+    };
+  }
+  recordFirstToken(error) {
+    if (!this.metrics?.streamFirstToken || this.firstTokenEmitted) return;
+    this.firstTokenEmitted = true;
+    const latencyMs = this.startedAt ? Date.now() - this.startedAt : 0;
+    this.metrics.streamFirstToken({
+      latencyMs,
+      error: error ? String(error) : void 0,
+      context: this.context
+    });
+  }
 };
 function consumeSSEBuffer(buffer, flush = false) {
   const events = [];
@@ -530,9 +669,9 @@ function mapChatEvent(raw, requestId) {
   const p = payload;
   const type = normalizeEventType(raw.event, p);
   const usage = normalizeUsage(p.usage);
-  const responseId = p.response_id || p.responseId || p.id || p?.message?.id;
-  const model = p.model || p?.message?.model;
-  const stopReason = p.stop_reason || p.stopReason;
+  const responseId = p.response_id || p.id || p?.message?.id;
+  const model = normalizeModelId(p.model || p?.message?.model);
+  const stopReason = normalizeStopReason(p.stop_reason);
   const textDelta = extractTextDelta(p);
   return {
     type,
@@ -585,10 +724,10 @@ function normalizeChatResponse(payload, requestId) {
   const p = payload;
   return {
     id: p?.id,
-    provider: p?.provider,
+    provider: normalizeProvider(p?.provider),
     content: Array.isArray(p?.content) ? p.content : p?.content ? [String(p.content)] : [],
-    stopReason: p?.stop_reason ?? p?.stopReason,
-    model: p?.model,
+    stopReason: normalizeStopReason(p?.stop_reason),
+    model: normalizeModelId(p?.model),
     usage: normalizeUsage(p?.usage),
     requestId
   };
@@ -597,19 +736,23 @@ function normalizeUsage(payload) {
   if (!payload) {
     return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
   }
-  return {
-    inputTokens: Number(payload.input_tokens ?? payload.inputTokens ?? 0),
-    outputTokens: Number(payload.output_tokens ?? payload.outputTokens ?? 0),
-    totalTokens: Number(payload.total_tokens ?? payload.totalTokens ?? 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;
+  }
+  return usage;
 }
 function buildProxyBody(params, metadata) {
   const body = {
-    model: params.model,
+    model: modelToString(params.model),
     messages: normalizeMessages(params.messages)
   };
   if (typeof params.maxTokens === "number") body.max_tokens = params.maxTokens;
-  if (params.provider) body.provider = params.provider;
+  if (params.provider) body.provider = providerToString(params.provider);
   if (typeof params.temperature === "number")
     body.temperature = params.temperature;
   if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
@@ -645,78 +788,218 @@ function hasUserMessage(messages) {
   );
 }
 
-// package.json
-var package_default = {
-  name: "@modelrelay/sdk",
-  version: "0.2.0",
-  description: "TypeScript SDK for the ModelRelay API",
-  type: "module",
-  main: "dist/index.cjs",
-  module: "dist/index.js",
-  types: "dist/index.d.ts",
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.js",
-      require: "./dist/index.cjs"
+// src/customers.ts
+var CustomersClient = class {
+  constructor(http, cfg) {
+    this.http = http;
+    this.apiKey = cfg.apiKey;
+  }
+  ensureSecretKey() {
+    if (!this.apiKey || !this.apiKey.startsWith("mr_sk_")) {
+      throw new ConfigError(
+        "Secret key (mr_sk_*) required for customer operations"
+      );
     }
-  },
-  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"
+  }
+  /**
+   * List all customers in the project.
+   */
+  async list() {
+    this.ensureSecretKey();
+    const response = await this.http.json("/customers", {
+      method: "GET",
+      apiKey: this.apiKey
+    });
+    return response.customers;
+  }
+  /**
+   * Create a new customer in the project.
+   */
+  async create(request) {
+    this.ensureSecretKey();
+    if (!request.tier_id?.trim()) {
+      throw new ConfigError("tier_id is required");
+    }
+    if (!request.external_id?.trim()) {
+      throw new ConfigError("external_id is required");
+    }
+    const response = await this.http.json("/customers", {
+      method: "POST",
+      body: request,
+      apiKey: this.apiKey
+    });
+    return response.customer;
+  }
+  /**
+   * Get a customer by ID.
+   */
+  async get(customerId) {
+    this.ensureSecretKey();
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    const response = await this.http.json(
+      `/customers/${customerId}`,
+      {
+        method: "GET",
+        apiKey: this.apiKey
+      }
+    );
+    return response.customer;
+  }
+  /**
+   * Upsert a customer by external_id.
+   * If a customer with the given external_id exists, it is updated.
+   * Otherwise, a new customer is created.
+   */
+  async upsert(request) {
+    this.ensureSecretKey();
+    if (!request.tier_id?.trim()) {
+      throw new ConfigError("tier_id is required");
+    }
+    if (!request.external_id?.trim()) {
+      throw new ConfigError("external_id is required");
+    }
+    const response = await this.http.json("/customers", {
+      method: "PUT",
+      body: request,
+      apiKey: this.apiKey
+    });
+    return response.customer;
+  }
+  /**
+   * Delete a customer by ID.
+   */
+  async delete(customerId) {
+    this.ensureSecretKey();
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    await this.http.request(`/customers/${customerId}`, {
+      method: "DELETE",
+      apiKey: this.apiKey
+    });
+  }
+  /**
+   * Create a Stripe checkout session for a customer.
+   */
+  async createCheckoutSession(customerId, request) {
+    this.ensureSecretKey();
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    if (!request.success_url?.trim() || !request.cancel_url?.trim()) {
+      throw new ConfigError("success_url and cancel_url are required");
+    }
+    return await this.http.json(
+      `/customers/${customerId}/checkout`,
+      {
+        method: "POST",
+        body: request,
+        apiKey: this.apiKey
+      }
+    );
+  }
+  /**
+   * Get the subscription status for a customer.
+   */
+  async getSubscription(customerId) {
+    this.ensureSecretKey();
+    if (!customerId?.trim()) {
+      throw new ConfigError("customerId is required");
+    }
+    return await this.http.json(
+      `/customers/${customerId}/subscription`,
+      {
+        method: "GET",
+        apiKey: this.apiKey
+      }
+    );
   }
 };
 
-// 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_REQUEST_TIMEOUT_MS = 6e4;
+// src/tiers.ts
+var TiersClient = class {
+  constructor(http, cfg) {
+    this.http = http;
+    this.apiKey = cfg.apiKey;
+  }
+  ensureApiKey() {
+    if (!this.apiKey || !this.apiKey.startsWith("mr_pk_") && !this.apiKey.startsWith("mr_sk_")) {
+      throw new ConfigError(
+        "API key (mr_pk_* or mr_sk_*) required for tier operations"
+      );
+    }
+  }
+  /**
+   * List all tiers in the project.
+   */
+  async list() {
+    this.ensureApiKey();
+    const response = await this.http.json("/tiers", {
+      method: "GET",
+      apiKey: this.apiKey
+    });
+    return response.tiers;
+  }
+  /**
+   * Get a tier by ID.
+   */
+  async get(tierId) {
+    this.ensureApiKey();
+    if (!tierId?.trim()) {
+      throw new ConfigError("tierId is required");
+    }
+    const response = await this.http.json(`/tiers/${tierId}`, {
+      method: "GET",
+      apiKey: this.apiKey
+    });
+    return response.tier;
+  }
+};
 
 // src/http.ts
 var HTTPClient = class {
   constructor(cfg) {
     const baseFromEnv = baseUrlForEnvironment(cfg.environment);
-    this.baseUrl = normalizeBaseUrl(cfg.baseUrl || baseFromEnv || DEFAULT_BASE_URL);
+    const resolvedBase = normalizeBaseUrl(
+      cfg.baseUrl || baseFromEnv || DEFAULT_BASE_URL
+    );
+    if (!isValidHttpUrl(resolvedBase)) {
+      throw new ConfigError(
+        "baseUrl must start with http:// or https://"
+      );
+    }
+    this.baseUrl = resolvedBase;
     this.apiKey = cfg.apiKey?.trim();
     this.accessToken = cfg.accessToken?.trim();
     this.fetchImpl = cfg.fetchImpl;
     this.clientHeader = cfg.clientHeader?.trim() || DEFAULT_CLIENT_HEADER;
+    this.defaultConnectTimeoutMs = cfg.connectTimeoutMs === void 0 ? DEFAULT_CONNECT_TIMEOUT_MS : Math.max(0, cfg.connectTimeoutMs);
     this.defaultTimeoutMs = cfg.timeoutMs === void 0 ? DEFAULT_REQUEST_TIMEOUT_MS : Math.max(0, cfg.timeoutMs);
     this.retry = normalizeRetryConfig(cfg.retry);
     this.defaultHeaders = normalizeHeaders(cfg.defaultHeaders);
+    this.metrics = cfg.metrics;
+    this.trace = cfg.trace;
   }
   async request(path, options = {}) {
     const fetchFn = this.fetchImpl ?? globalThis.fetch;
     if (!fetchFn) {
-      throw new ModelRelayError(
-        "fetch is not available; provide a fetch implementation",
-        { status: 500 }
+      throw new ConfigError(
+        "fetch is not available; provide a fetch implementation"
       );
     }
     const method = options.method || "GET";
     const url = buildUrl(this.baseUrl, path);
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    const context = {
+      method,
+      path,
+      ...options.context || {}
+    };
+    trace?.requestStart?.(context);
+    const start = metrics?.httpRequest || trace?.requestFinish ? Date.now() : 0;
     const headers = new Headers({
       ...this.defaultHeaders,
       ...options.headers || {}
@@ -744,15 +1027,35 @@ var HTTPClient = class {
       headers.set("X-ModelRelay-Client", this.clientHeader);
     }
     const timeoutMs = options.useDefaultTimeout === false ? options.timeoutMs : options.timeoutMs ?? this.defaultTimeoutMs;
+    const connectTimeoutMs = options.useDefaultConnectTimeout === false ? options.connectTimeoutMs : options.connectTimeoutMs ?? this.defaultConnectTimeoutMs;
     const retryCfg = normalizeRetryConfig(
       options.retry === void 0 ? this.retry : options.retry
     );
     const attempts = retryCfg ? Math.max(1, retryCfg.maxAttempts) : 1;
     let lastError;
+    let lastStatus;
     for (let attempt = 1; attempt <= attempts; attempt++) {
-      const controller = timeoutMs && timeoutMs > 0 ? new AbortController() : void 0;
-      const signal = mergeSignals(options.signal, controller?.signal);
-      const timer = controller && setTimeout(() => controller.abort(new DOMException("timeout", "AbortError")), timeoutMs);
+      let connectTimedOut = false;
+      let requestTimedOut = false;
+      const connectController = connectTimeoutMs && connectTimeoutMs > 0 ? new AbortController() : void 0;
+      const requestController = timeoutMs && timeoutMs > 0 ? new AbortController() : void 0;
+      const signal = mergeSignals(
+        options.signal,
+        connectController?.signal,
+        requestController?.signal
+      );
+      const connectTimer = connectController && setTimeout(() => {
+        connectTimedOut = true;
+        connectController.abort(
+          new DOMException("connect timeout", "AbortError")
+        );
+      }, connectTimeoutMs);
+      const requestTimer = requestController && setTimeout(() => {
+        requestTimedOut = true;
+        requestController.abort(
+          new DOMException("timeout", "AbortError")
+        );
+      }, timeoutMs);
       try {
         const response = await fetchFn(url, {
           method,
@@ -760,6 +1063,9 @@ var HTTPClient = class {
           body: payload,
           signal
         });
+        if (connectTimer) {
+          clearTimeout(connectTimer);
+        }
         if (!response.ok) {
           const shouldRetry = retryCfg && shouldRetryStatus(
             response.status,
@@ -767,31 +1073,68 @@ var HTTPClient = class {
             retryCfg.retryPost
           ) && attempt < attempts;
           if (shouldRetry) {
+            lastStatus = response.status;
             await backoff(attempt, retryCfg);
             continue;
           }
-          if (!options.raw) {
-            throw await parseErrorResponse(response);
-          }
+          const retries = buildRetryMetadata(attempt, response.status, lastError);
+          const finishedCtx2 = withRequestId(context, response.headers);
+          recordHttpMetrics(metrics, trace, start, retries, {
+            status: response.status,
+            context: finishedCtx2
+          });
+          throw options.raw ? await parseErrorResponse(response, retries) : await parseErrorResponse(response, retries);
         }
+        const finishedCtx = withRequestId(context, response.headers);
+        recordHttpMetrics(metrics, trace, start, void 0, {
+          status: response.status,
+          context: finishedCtx
+        });
         return response;
       } catch (err) {
         if (options.signal?.aborted) {
           throw err;
         }
-        const shouldRetry = retryCfg && isRetryableError(err) && (method !== "POST" || retryCfg.retryPost) && attempt < attempts;
-        if (!shouldRetry) {
+        if (err instanceof ModelRelayError) {
+          recordHttpMetrics(metrics, trace, start, void 0, {
+            error: err,
+            context
+          });
           throw err;
         }
+        const transportKind = classifyTransportErrorKind(
+          err,
+          connectTimedOut,
+          requestTimedOut
+        );
+        const shouldRetry = retryCfg && isRetryableError(err, transportKind) && (method !== "POST" || retryCfg.retryPost) && attempt < attempts;
+        if (!shouldRetry) {
+          const retries = buildRetryMetadata(
+            attempt,
+            lastStatus,
+            err instanceof Error ? err.message : String(err)
+          );
+          recordHttpMetrics(metrics, trace, start, retries, {
+            error: err,
+            context
+          });
+          throw toTransportError(err, transportKind, retries);
+        }
         lastError = err;
         await backoff(attempt, retryCfg);
       } finally {
-        if (timer) {
-          clearTimeout(timer);
+        if (connectTimer) {
+          clearTimeout(connectTimer);
+        }
+        if (requestTimer) {
+          clearTimeout(requestTimer);
         }
       }
     }
-    throw lastError instanceof Error ? lastError : new ModelRelayError("request failed", { status: 500 });
+    throw lastError instanceof Error ? lastError : new TransportError("request failed", {
+      kind: "other",
+      retries: buildRetryMetadata(attempts, lastStatus)
+    });
   }
   async json(path, options = {}) {
     const response = await this.request(path, {
@@ -808,7 +1151,7 @@ var HTTPClient = class {
     try {
       return await response.json();
     } catch (err) {
-      throw new ModelRelayError("failed to parse response JSON", {
+      throw new APIError("failed to parse response JSON", {
         status: response.status,
         data: err
       });
@@ -831,6 +1174,9 @@ function normalizeBaseUrl(value) {
   }
   return trimmed;
 }
+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;
@@ -856,9 +1202,10 @@ function shouldRetryStatus(status, method, retryPost) {
   }
   return false;
 }
-function isRetryableError(err) {
+function isRetryableError(err, kind) {
   if (!err) return false;
-  return err instanceof DOMException && err.name === "AbortError" || err instanceof TypeError;
+  if (kind === "timeout" || kind === "connect") return true;
+  return err instanceof DOMException || err instanceof TypeError;
 }
 function backoff(attempt, cfg) {
   const exp = Math.max(0, attempt - 1);
@@ -869,24 +1216,22 @@ function backoff(attempt, cfg) {
   if (delay <= 0) return Promise.resolve();
   return new Promise((resolve) => setTimeout(resolve, delay));
 }
-function mergeSignals(user, timeoutSignal) {
-  if (!user && !timeoutSignal) return void 0;
-  if (user && !timeoutSignal) return user;
-  if (!user && timeoutSignal) return timeoutSignal;
+function mergeSignals(...signals) {
+  const active = signals.filter(Boolean);
+  if (active.length === 0) return void 0;
+  if (active.length === 1) return active[0];
   const controller = new AbortController();
-  const propagate = (source) => {
-    if (source.aborted) {
-      controller.abort(source.reason);
-    } else {
-      source.addEventListener(
-        "abort",
-        () => controller.abort(source.reason),
-        { once: true }
-      );
+  for (const src of active) {
+    if (src.aborted) {
+      controller.abort(src.reason);
+      break;
     }
-  };
-  if (user) propagate(user);
-  if (timeoutSignal) propagate(timeoutSignal);
+    src.addEventListener(
+      "abort",
+      () => controller.abort(src.reason),
+      { once: true }
+    );
+  }
   return controller.signal;
 }
 function normalizeHeaders(headers) {
@@ -902,15 +1247,59 @@ function normalizeHeaders(headers) {
   }
   return normalized;
 }
+function buildRetryMetadata(attempt, lastStatus, lastError) {
+  if (!attempt || attempt <= 1) return void 0;
+  return {
+    attempts: attempt,
+    lastStatus,
+    lastError: typeof lastError === "string" ? lastError : lastError instanceof Error ? lastError.message : lastError ? String(lastError) : void 0
+  };
+}
+function classifyTransportErrorKind(err, connectTimedOut, requestTimedOut) {
+  if (connectTimedOut) return "connect";
+  if (requestTimedOut) return "timeout";
+  if (err instanceof DOMException && err.name === "AbortError") {
+    return requestTimedOut ? "timeout" : "request";
+  }
+  if (err instanceof TypeError) return "request";
+  return "other";
+}
+function toTransportError(err, kind, retries) {
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "request failed";
+  return new TransportError(message, { kind, retries, cause: err });
+}
+function recordHttpMetrics(metrics, trace, start, retries, info) {
+  if (!metrics?.httpRequest && !trace?.requestFinish) return;
+  const latencyMs = start ? Date.now() - start : 0;
+  if (metrics?.httpRequest) {
+    metrics.httpRequest({
+      latencyMs,
+      status: info.status,
+      error: info.error ? String(info.error) : void 0,
+      retries,
+      context: info.context
+    });
+  }
+  trace?.requestFinish?.({
+    context: info.context,
+    status: info.status,
+    error: info.error,
+    retries,
+    latencyMs
+  });
+}
+function withRequestId(context, headers) {
+  const requestId = headers.get("X-ModelRelay-Chat-Request-Id") || headers.get("X-Request-Id") || context.requestId;
+  if (!requestId) return context;
+  return { ...context, requestId };
+}
 
 // src/index.ts
 var ModelRelay = class {
   constructor(options) {
     const cfg = options || {};
     if (!cfg.key && !cfg.token) {
-      throw new ModelRelayError("Provide an API key or access token", {
-        status: 400
-      });
+      throw new ConfigError("Provide an API key or access token");
     }
     this.baseUrl = resolveBaseUrl(cfg.environment, cfg.baseUrl);
     const http = new HTTPClient({
@@ -919,22 +1308,31 @@ var ModelRelay = class {
       accessToken: cfg.token,
       fetchImpl: cfg.fetch,
       clientHeader: cfg.clientHeader || DEFAULT_CLIENT_HEADER,
+      connectTimeoutMs: cfg.connectTimeoutMs,
       timeoutMs: cfg.timeoutMs,
       retry: cfg.retry,
       defaultHeaders: cfg.defaultHeaders,
-      environment: cfg.environment
+      environment: cfg.environment,
+      metrics: cfg.metrics,
+      trace: cfg.trace
     });
     const auth = new AuthClient(http, {
       apiKey: cfg.key,
       accessToken: cfg.token,
-      endUser: cfg.endUser
+      customer: cfg.customer
     });
     this.auth = auth;
-    this.billing = new BillingClient(http, auth);
     this.chat = new ChatClient(http, auth, {
-      defaultMetadata: cfg.defaultMetadata
+      defaultMetadata: cfg.defaultMetadata,
+      metrics: cfg.metrics,
+      trace: cfg.trace
+    });
+    this.customers = new CustomersClient(http, {
+      apiKey: cfg.key
+    });
+    this.tiers = new TiersClient(http, {
+      apiKey: cfg.key
     });
-    this.apiKeys = new ApiKeysClient(http);
   }
 };
 function resolveBaseUrl(env, override) {
@@ -943,18 +1341,34 @@ function resolveBaseUrl(env, override) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ApiKeysClient,
+  APIError,
   AuthClient,
-  BillingClient,
   ChatClient,
   ChatCompletionsStream,
+  ConfigError,
+  CustomersClient,
   DEFAULT_BASE_URL,
   DEFAULT_CLIENT_HEADER,
+  DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS,
   ModelRelay,
   ModelRelayError,
+  Models,
+  Providers,
   SANDBOX_BASE_URL,
   SDK_VERSION,
   STAGING_BASE_URL,
-  isPublishableKey
+  StopReasons,
+  TiersClient,
+  TransportError,
+  isPublishableKey,
+  mergeMetrics,
+  mergeTrace,
+  modelToString,
+  normalizeModelId,
+  normalizeProvider,
+  normalizeStopReason,
+  parseErrorResponse,
+  providerToString,
+  stopReasonToString
 });