@modelrelay/sdk 0.14.1 → 0.18.0

package/README.md

@@ -82,11 +82,87 @@ const stream = await mr.chat.completions.create(
 );
 ```
 
-### Typed models, providers, and stop reasons
+### Typed models and stop reasons
 
-- Models and providers use string literal unions with an `Other` escape hatch: pass `{ other: "my-provider" }` or `{ other: "custom/model-x" }` to preserve custom IDs while benefiting from autocomplete on known values (e.g., `Models.Gpt4o`, `Providers.Anthropic`).
+- Models are plain strings (e.g., `"gpt-4o"`), so new models do not require SDK updates.
 - Stop reasons are parsed into the `StopReason` union (e.g., `StopReasons.EndTurn`); unknown values surface as `{ other: "<raw>" }`.
-- Usage backfills `totalTokens` when providers omit it, ensuring consistent accounting.
+- Usage backfills `totalTokens` when the backend omits it, ensuring consistent accounting.
+
+### Structured outputs (`response_format`)
+
+Request structured JSON instead of free-form text when the backend supports it:
+
+```ts
+import { ModelRelay, type ResponseFormat } from "@modelrelay/sdk";
+
+const mr = new ModelRelay({ key: "mr_sk_..." });
+
+const format: ResponseFormat = {
+  type: "json_schema",
+  json_schema: {
+    name: "summary",
+    schema: {
+      type: "object",
+      properties: { headline: { type: "string" } },
+      additionalProperties: false,
+    },
+    strict: true,
+  },
+};
+
+const completion = await mr.chat.completions.create(
+  {
+    model: "gpt-4o-mini",
+    messages: [{ role: "user", content: "Summarize ModelRelay" }],
+    responseFormat: format,
+    stream: false,
+  },
+  { stream: false },
+);
+
+console.log(completion.content[0]); // JSON string matching your schema
+```
+
+### Structured streaming (NDJSON + response_format)
+
+Use the structured streaming contract for `/llm/proxy` to stream schema-valid
+JSON payloads over NDJSON:
+
+```ts
+type Item = { id: string; label: string };
+type RecommendationPayload = { items: Item[] };
+
+const format: ResponseFormat = {
+  type: "json_schema",
+  json_schema: {
+    name: "recommendations",
+    schema: {
+      type: "object",
+      properties: { items: { type: "array", items: { type: "object" } } },
+    },
+  },
+};
+
+const stream = await mr.chat.completions.streamJSON<RecommendationPayload>({
+  model: "grok-4-1-fast",
+  messages: [{ role: "user", content: "Recommend items for my user" }],
+  responseFormat: format,
+});
+
+for await (const evt of stream) {
+  if (evt.type === "update") {
+    // Progressive UI: evt.payload is a partial but schema-valid payload.
+    renderPartial(evt.payload.items);
+  }
+  if (evt.type === "completion") {
+    renderFinal(evt.payload.items);
+  }
+}
+
+// Prefer a single blocking result but still want structured validation?
+const final = await stream.collect();
+console.log(final.items.length);
+```
 
 ### Telemetry & metrics hooks
 

package/dist/index.cjs

@@ -33,10 +33,10 @@ __export(index_exports, {
   ErrorCodes: () => ErrorCodes,
   ModelRelay: () => ModelRelay,
   ModelRelayError: () => ModelRelayError,
-  Models: () => Models,
-  Providers: () => Providers,
+  ResponseFormatTypes: () => ResponseFormatTypes,
   SDK_VERSION: () => SDK_VERSION,
   StopReasons: () => StopReasons,
+  StructuredJSONStream: () => StructuredJSONStream,
   TiersClient: () => TiersClient,
   ToolArgsError: () => ToolArgsError,
   ToolCallAccumulator: () => ToolCallAccumulator,
@@ -44,6 +44,7 @@ __export(index_exports, {
   ToolRegistry: () => ToolRegistry,
   ToolTypes: () => ToolTypes,
   TransportError: () => TransportError,
+  WebToolModes: () => WebToolModes,
   assistantMessageWithToolCalls: () => assistantMessageWithToolCalls,
   createAccessTokenAuth: () => createAccessTokenAuth,
   createApiKeyAuth: () => createApiKeyAuth,
@@ -68,12 +69,10 @@ __export(index_exports, {
   mergeTrace: () => mergeTrace,
   modelToString: () => modelToString,
   normalizeModelId: () => normalizeModelId,
-  normalizeProvider: () => normalizeProvider,
   normalizeStopReason: () => normalizeStopReason,
   parseErrorResponse: () => parseErrorResponse,
   parseToolArgs: () => parseToolArgs,
   parseToolArgsRaw: () => parseToolArgsRaw,
-  providerToString: () => providerToString,
   respondToToolCall: () => respondToToolCall,
   stopReasonToString: () => stopReasonToString,
   toolChoiceAuto: () => toolChoiceAuto,
@@ -348,7 +347,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.14.1",
+  version: "0.18.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -407,30 +406,6 @@ var StopReasons = {
   Incomplete: "incomplete",
   Unknown: "unknown"
 };
-var Providers = {
-  OpenAI: "openai",
-  Anthropic: "anthropic",
-  XAI: "xai",
-  GoogleAIStudio: "google-ai-studio",
-  Echo: "echo"
-};
-var Models = {
-  // 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",
-  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,
@@ -441,14 +416,24 @@ function createUsage(inputTokens, outputTokens, totalTokens) {
 var ToolTypes = {
   Function: "function",
   Web: "web",
+  WebSearch: "web_search",
   XSearch: "x_search",
   CodeExecution: "code_execution"
 };
+var WebToolModes = {
+  Search: "search",
+  Browse: "browse"
+};
 var ToolChoiceTypes = {
   Auto: "auto",
   Required: "required",
   None: "none"
 };
+var ResponseFormatTypes = {
+  Text: "text",
+  JsonObject: "json_object",
+  JsonSchema: "json_schema"
+};
 function mergeMetrics(base, override) {
   if (!base && !override) return void 0;
   return {
@@ -482,34 +467,14 @@ function stopReasonToString(value) {
   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 };
+  return str;
 }
 function modelToString(value) {
-  if (typeof value === "string") return value;
-  return value.other?.trim() || "";
+  return String(value).trim();
 }
 
 // src/tools.ts
@@ -1167,7 +1132,6 @@ var ChatCompletionsClient = class {
     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,
@@ -1181,7 +1145,6 @@ var ChatCompletionsClient = class {
     const baseContext = {
       method: "POST",
       path: "/llm/proxy",
-      provider: params.provider,
       model: params.model,
       requestId
     };
@@ -1231,6 +1194,80 @@ var ChatCompletionsClient = class {
       trace
     );
   }
+  /**
+   * Stream structured JSON responses using the NDJSON contract defined for
+   * /llm/proxy. 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(params.customerId);
+    const body = buildProxyBody(
+      params,
+      mergeMetadata(this.defaultMetadata, params.metadata, options.metadata)
+    );
+    const requestId = params.requestId || options.requestId;
+    const headers = { ...options.headers || {} };
+    if (requestId) {
+      headers[REQUEST_ID_HEADER] = requestId;
+    }
+    const baseContext = {
+      method: "POST",
+      path: "/llm/proxy",
+      model: params.model,
+      requestId
+    };
+    const response = await this.http.request("/llm/proxy", {
+      method: "POST",
+      body,
+      headers,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      accept: "application/x-ndjson",
+      raw: true,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? 0,
+      useDefaultTimeout: false,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: baseContext
+    });
+    const resolvedRequestId = requestIdFromHeaders(response.headers) || requestId || void 0;
+    if (!response.ok) {
+      throw await parseErrorResponse(response);
+    }
+    const contentType = response.headers.get("Content-Type") || "";
+    if (!/application\/(x-)?ndjson/i.test(contentType)) {
+      throw new TransportError(
+        `expected NDJSON structured stream, got Content-Type ${contentType || "missing"}`,
+        { kind: "request" }
+      );
+    }
+    const streamContext = {
+      ...baseContext,
+      requestId: resolvedRequestId ?? baseContext.requestId
+    };
+    return new StructuredJSONStream(
+      response,
+      resolvedRequestId,
+      streamContext,
+      metrics,
+      trace
+    );
+  }
 };
 var ChatCompletionsStream = class {
   constructor(response, requestId, context, metrics, trace) {
@@ -1332,6 +1369,164 @@ var ChatCompletionsStream = class {
     });
   }
 };
+var StructuredJSONStream = class {
+  constructor(response, requestId, context, metrics, trace) {
+    this.closed = false;
+    this.sawTerminal = false;
+    if (!response.body) {
+      throw new ConfigError("streaming response is missing a body");
+    }
+    this.response = response;
+    this.requestId = requestId;
+    this.context = context;
+    this.metrics = metrics;
+    this.trace = trace;
+  }
+  async cancel(reason) {
+    this.closed = true;
+    try {
+      await this.response.body?.cancel(reason);
+    } catch {
+    }
+  }
+  async *[Symbol.asyncIterator]() {
+    if (this.closed) {
+      return;
+    }
+    const body = this.response.body;
+    if (!body) {
+      throw new ConfigError("streaming response is missing a body");
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        if (this.closed) {
+          await reader.cancel();
+          return;
+        }
+        const { value, done } = await reader.read();
+        if (done) {
+          const { records: records2 } = consumeNDJSONBuffer(buffer, true);
+          for (const line of records2) {
+            const evt = this.parseRecord(line);
+            if (evt) {
+              this.traceStructuredEvent(evt, line);
+              yield evt;
+            }
+          }
+          if (!this.sawTerminal) {
+            throw new TransportError(
+              "structured stream ended without completion or error",
+              { kind: "request" }
+            );
+          }
+          return;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const { records, remainder } = consumeNDJSONBuffer(buffer);
+        buffer = remainder;
+        for (const line of records) {
+          const evt = this.parseRecord(line);
+          if (evt) {
+            this.traceStructuredEvent(evt, line);
+            yield evt;
+          }
+        }
+      }
+    } catch (err) {
+      this.trace?.streamError?.({ context: this.context, error: err });
+      throw err;
+    } finally {
+      this.closed = true;
+      reader.releaseLock();
+    }
+  }
+  async collect() {
+    let last;
+    for await (const evt of this) {
+      last = evt;
+      if (evt.type === "completion") {
+        return evt.payload;
+      }
+    }
+    throw new TransportError(
+      "structured stream ended without completion or error",
+      { kind: "request" }
+    );
+  }
+  parseRecord(line) {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      throw new TransportError("invalid JSON in structured stream", {
+        kind: "request",
+        cause: err
+      });
+    }
+    if (!parsed || typeof parsed !== "object") {
+      throw new TransportError("structured stream record is not an object", {
+        kind: "request"
+      });
+    }
+    const obj = parsed;
+    const rawType = String(obj.type || "").trim().toLowerCase();
+    if (!rawType) return null;
+    if (rawType === "start") {
+      return null;
+    }
+    if (rawType === "error") {
+      this.sawTerminal = true;
+      const status = typeof obj.status === "number" && obj.status > 0 ? obj.status : 500;
+      const message = typeof obj.message === "string" && obj.message.trim() ? obj.message : "structured stream error";
+      const code = typeof obj.code === "string" && obj.code.trim() ? obj.code : void 0;
+      throw new APIError(message, {
+        status,
+        code,
+        requestId: this.requestId
+      });
+    }
+    if (rawType !== "update" && rawType !== "completion") {
+      return null;
+    }
+    if (obj.payload === void 0 || obj.payload === null) {
+      throw new TransportError(
+        "structured stream record missing payload",
+        { kind: "request" }
+      );
+    }
+    if (rawType === "completion") {
+      this.sawTerminal = true;
+    }
+    const event = {
+      type: rawType,
+      // biome-ignore lint/suspicious/noExplicitAny: payload is untyped json
+      payload: obj.payload,
+      requestId: this.requestId
+    };
+    return event;
+  }
+  traceStructuredEvent(evt, raw) {
+    if (!this.trace?.streamEvent) return;
+    const event = {
+      type: "custom",
+      event: "structured",
+      data: { type: evt.type, payload: evt.payload },
+      textDelta: void 0,
+      toolCallDelta: void 0,
+      toolCalls: void 0,
+      responseId: void 0,
+      model: void 0,
+      stopReason: void 0,
+      usage: void 0,
+      requestId: this.requestId,
+      raw
+    };
+    this.trace.streamEvent({ context: this.context, event });
+  }
+};
 function consumeSSEBuffer(buffer, flush = false) {
   const events = [];
   let eventName = "";
@@ -1374,6 +1569,19 @@ function consumeSSEBuffer(buffer, flush = false) {
   }
   return { events, remainder };
 }
+function consumeNDJSONBuffer(buffer, flush = false) {
+  const lines = buffer.split(/\r?\n/);
+  const records = [];
+  const lastIndex = lines.length - 1;
+  const limit = flush ? lines.length : Math.max(0, lastIndex);
+  for (let i = 0; i < limit; i++) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+    records.push(line);
+  }
+  const remainder = flush ? "" : lines[lastIndex] ?? "";
+  return { records, remainder };
+}
 function mapChatEvent(raw, requestId) {
   let parsed = raw.data;
   if (raw.data) {
@@ -1502,7 +1710,6 @@ function normalizeChatResponse(payload, requestId) {
   const p = payload;
   const response = {
     id: p?.id,
-    provider: normalizeProvider(p?.provider),
     content: Array.isArray(p?.content) ? p.content : p?.content ? [String(p.content)] : [],
     stopReason: normalizeStopReason(p?.stop_reason),
     model: normalizeModelId(p?.model),
@@ -1533,19 +1740,6 @@ function normalizeUsage(payload) {
   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.`
-    );
-  }
-}
 function buildProxyBody(params, metadata) {
   const modelValue = params.model ? modelToString(params.model).trim() : "";
   const body = {
@@ -1555,7 +1749,6 @@ function buildProxyBody(params, metadata) {
     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")
     body.temperature = params.temperature;
   if (metadata && Object.keys(metadata).length > 0) body.metadata = metadata;
@@ -1563,6 +1756,7 @@ function buildProxyBody(params, metadata) {
   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) {
@@ -1742,6 +1936,32 @@ var CustomersClient = class {
     });
     return response.customer;
   }
+  /**
+   * Claim a customer by email, setting their external_id.
+   * Used when a customer subscribes via Stripe Checkout (email only) and later
+   * authenticates to the app, needing to link their identity.
+   *
+   * @throws {APIError} with status 404 if customer not found by email
+   * @throws {APIError} with status 409 if customer already claimed or external_id in use
+   */
+  async claim(request) {
+    this.ensureSecretKey();
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required");
+    }
+    if (!isValidEmail(request.email)) {
+      throw new ConfigError("invalid email format");
+    }
+    if (!request.external_id?.trim()) {
+      throw new ConfigError("external_id is required");
+    }
+    const response = await this.http.json("/customers/claim", {
+      method: "POST",
+      body: request,
+      apiKey: this.apiKey
+    });
+    return response.customer;
+  }
   /**
    * Delete a customer by ID.
    */
@@ -1806,6 +2026,13 @@ var TiersClient = class {
       );
     }
   }
+  ensureSecretKey() {
+    if (!this.apiKey || !this.apiKey.startsWith("mr_sk_")) {
+      throw new ConfigError(
+        "Secret key (mr_sk_*) required for checkout operations"
+      );
+    }
+  }
   /**
    * List all tiers in the project.
    */
@@ -1831,6 +2058,42 @@ var TiersClient = class {
     });
     return response.tier;
   }
+  /**
+   * Create a Stripe checkout session for a tier (Stripe-first flow).
+   *
+   * This enables users to subscribe before authenticating. After checkout
+   * completes, a customer record is created with the provided email. The
+   * customer can later be linked to an identity via POST /customers/claim.
+   *
+   * Requires a secret key (mr_sk_*).
+   *
+   * @param tierId - The tier ID to create a checkout session for
+   * @param request - Checkout session request with email and redirect URLs
+   * @returns Checkout session with Stripe URL
+   */
+  async checkout(tierId, request) {
+    this.ensureSecretKey();
+    if (!tierId?.trim()) {
+      throw new ConfigError("tierId is required");
+    }
+    if (!request.email?.trim()) {
+      throw new ConfigError("email is required");
+    }
+    if (!request.success_url?.trim()) {
+      throw new ConfigError("success_url is required");
+    }
+    if (!request.cancel_url?.trim()) {
+      throw new ConfigError("cancel_url is required");
+    }
+    return await this.http.json(
+      `/tiers/${tierId}/checkout`,
+      {
+        method: "POST",
+        apiKey: this.apiKey,
+        body: request
+      }
+    );
+  }
 };
 
 // src/http.ts
@@ -2219,10 +2482,10 @@ function resolveBaseUrl(override) {
   ErrorCodes,
   ModelRelay,
   ModelRelayError,
-  Models,
-  Providers,
+  ResponseFormatTypes,
   SDK_VERSION,
   StopReasons,
+  StructuredJSONStream,
   TiersClient,
   ToolArgsError,
   ToolCallAccumulator,
@@ -2230,6 +2493,7 @@ function resolveBaseUrl(override) {
   ToolRegistry,
   ToolTypes,
   TransportError,
+  WebToolModes,
   assistantMessageWithToolCalls,
   createAccessTokenAuth,
   createApiKeyAuth,
@@ -2254,12 +2518,10 @@ function resolveBaseUrl(override) {
   mergeTrace,
   modelToString,
   normalizeModelId,
-  normalizeProvider,
   normalizeStopReason,
   parseErrorResponse,
   parseToolArgs,
   parseToolArgsRaw,
-  providerToString,
   respondToToolCall,
   stopReasonToString,
   toolChoiceAuto,