@modelrelay/sdk 0.14.1 → 0.18.0

package/dist/index.js

@@ -261,7 +261,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",
@@ -320,30 +320,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,
@@ -354,14 +330,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 {
@@ -395,34 +381,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
@@ -1080,7 +1046,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,
@@ -1094,7 +1059,6 @@ var ChatCompletionsClient = class {
     const baseContext = {
       method: "POST",
       path: "/llm/proxy",
-      provider: params.provider,
       model: params.model,
       requestId
     };
@@ -1144,6 +1108,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) {
@@ -1245,6 +1283,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 = "";
@@ -1287,6 +1483,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) {
@@ -1415,7 +1624,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),
@@ -1446,19 +1654,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 = {
@@ -1468,7 +1663,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;
@@ -1476,6 +1670,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) {
@@ -1655,6 +1850,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.
    */
@@ -1719,6 +1940,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.
    */
@@ -1744,6 +1972,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
@@ -2131,10 +2395,10 @@ export {
   ErrorCodes,
   ModelRelay,
   ModelRelayError,
-  Models,
-  Providers,
+  ResponseFormatTypes,
   SDK_VERSION,
   StopReasons,
+  StructuredJSONStream,
   TiersClient,
   ToolArgsError,
   ToolCallAccumulator,
@@ -2142,6 +2406,7 @@ export {
   ToolRegistry,
   ToolTypes,
   TransportError,
+  WebToolModes,
   assistantMessageWithToolCalls,
   createAccessTokenAuth,
   createApiKeyAuth,
@@ -2166,12 +2431,10 @@ export {
   mergeTrace,
   modelToString,
   normalizeModelId,
-  normalizeProvider,
   normalizeStopReason,
   parseErrorResponse,
   parseToolArgs,
   parseToolArgsRaw,
-  providerToString,
   respondToToolCall,
   stopReasonToString,
   toolChoiceAuto,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@modelrelay/sdk",
-  "version": "0.14.1",
+  "version": "0.18.0",
 	"description": "TypeScript SDK for the ModelRelay API",
 	"type": "module",
 	"main": "dist/index.cjs",