@modelrelay/sdk 0.25.1 → 0.27.0

package/README.md

@@ -1,434 +1,115 @@
 # ModelRelay TypeScript SDK
 
-Typed client for Node.js that wraps the ModelRelay API for **consuming** LLM/usage endpoints. Use secret API keys or bearer tokens issued by your backend; publishable-key frontend token flows have been removed.
-
-## Installation
-
 ```bash
 bun add @modelrelay/sdk
-# or: npm install @modelrelay/sdk
 ```
 
-## Quick Start
+## Streaming Chat
 
 ```ts
 import { ModelRelay } from "@modelrelay/sdk";
 
-// Use a secret key or bearer token from your backend.
-const mr = new ModelRelay({
-  key: "mr_sk_..."
-});
-
-// Stream chat completions.
-const stream = await mr.chat.completions.create({
-  model: "grok-4-1-fast-reasoning",
-  messages: [{ role: "user", content: "Hello" }]
-});
-
-for await (const event of stream) {
-  if (event.type === "message_delta" && event.textDelta) {
-    console.log(event.textDelta);
-  }
-}
-```
-
-### Server-side usage
-
-Provide a secret API key or bearer token:
-
-```ts
 const mr = new ModelRelay({ key: "mr_sk_..." });
-const completion = await mr.chat.completions.create(
-  { model: "grok-4-1-fast-reasoning", messages: [{ role: "user", content: "Hi" }], stream: false }
-);
-console.log(completion.content.join(""));
-```
-
-## Scripts (run with Bun)
-
-- `bun run build` — bundle CJS + ESM outputs with type declarations.
-- `bun run test` — run unit tests.
-- `bun run lint` — typecheck the source without emitting files.
-
-## Configuration
-
-- **Environments**: `environment: "production" | "staging" | "sandbox"` or override `baseUrl`.
-- **Auth**: pass a secret/publishable `key` or a bearer `token`. Publishable keys mint frontend tokens automatically.
-- **Timeouts & retries**: `connectTimeoutMs` (default 5s per attempt) and `timeoutMs` (default 60s overall; set `0` to disable). Per-call overrides available on `chat.completions.create`. `retry` config (`{ maxAttempts, baseBackoffMs, maxBackoffMs, retryPost }` or `false`) controls exponential backoff with jitter.
-- **Headers & metadata**: `defaultHeaders` are sent with every request; `defaultMetadata` merges into every chat request and can be overridden per-call via `metadata`.
-- **Client header**: set `clientHeader` to override the telemetry header (defaults to `modelrelay-ts/<version>`).
-
-### Timeouts & retry examples
-
-```ts
-// Shorten connect + request timeouts globally
-const mr = new ModelRelay({
-  key: "mr_sk_...",
-  connectTimeoutMs: 3_000,
-  timeoutMs: 20_000,
-  retry: { maxAttempts: 4, baseBackoffMs: 200, maxBackoffMs: 2_000 }
-});
-
-// Per-call overrides (blocking)
-await mr.chat.completions.create(
-  { model: "grok-4-1-fast-reasoning", messages: [{ role: "user", content: "Hi" }], stream: false },
-  { timeoutMs: 5_000, retry: false }
-);
-
-// Streaming: keep connect timeout but disable request timeout
-const stream = await mr.chat.completions.create(
-  { model: "grok-4-1-fast-reasoning", messages: [{ role: "user", content: "Hi" }] },
-  { connectTimeoutMs: 2_000 } // request timeout is already disabled for streams by default
-);
-```
 
-### Typed models, stop reasons, and message roles
-
-- 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>" }`.
-- Message roles use a typed union (`MessageRole`) with constants available via `MessageRoles`.
-- Usage backfills `totalTokens` when the backend omits it, ensuring consistent accounting.
-
-```ts
-import { MessageRoles } from "@modelrelay/sdk";
-
-// Use typed role constants
-const messages = [
-  { role: MessageRoles.System, content: "You are helpful." },
-  { role: MessageRoles.User, content: "Hello!" },
-];
-
-// Available roles: User, Assistant, System, Tool
-```
-
-### Customer-attributed requests
-
-For customer-attributed requests, the customer's tier determines which model to use.
-Use `forCustomer()` instead of providing a model:
-
-```ts
-// Customer-attributed: tier determines model, no model parameter needed
-const stream = await mr.chat.forCustomer("customer-123").create({
-  messages: [{ role: "user", content: "Hello!" }]
+const stream = await mr.chat.completions.create({
+  model: "claude-sonnet-4-20250514",
+  messages: [{ role: "user", content: "Hello" }],
 });
 
 for await (const event of stream) {
   if (event.type === "message_delta" && event.textDelta) {
-    console.log(event.textDelta);
+    process.stdout.write(event.textDelta);
   }
 }
-
-// Non-streaming
-const completion = await mr.chat.forCustomer("customer-123").create(
-  { messages: [{ role: "user", content: "Hello!" }] },
-  { stream: false }
-);
-```
-
-This provides compile-time separation between:
-- **Direct/PAYGO requests** (`chat.completions.create({ model, ... })`) — model is required
-- **Customer-attributed requests** (`chat.forCustomer(id).create(...)`) — tier determines model
-
-### 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:
+## Structured Outputs with Zod
 
 ```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);
-```
-
-### Type-safe structured outputs with Zod schemas
-
-For automatic schema generation and validation, use `structured()` with Zod:
-
-```ts
-import { ModelRelay } from "@modelrelay/sdk";
 import { z } from "zod";
 
-const mr = new ModelRelay({ key: "mr_sk_..." });
-
-// Define your output type with Zod
-const PersonSchema = z.object({
+const Person = z.object({
   name: z.string(),
   age: z.number(),
 });
 
-// structured() auto-generates JSON schema and validates responses
-const result = await mr.chat.completions.structured(
-  PersonSchema,
-  {
-    model: "claude-sonnet-4-20250514",
-    messages: [{ role: "user", content: "Extract: John Doe is 30 years old" }],
-  },
-  { maxRetries: 2 } // Retry on validation failures
-);
+const result = await mr.chat.completions.structured(Person, {
+  model: "claude-sonnet-4-20250514",
+  messages: [{ role: "user", content: "Extract: John Doe is 30" }],
+});
 
-console.log(`Name: ${result.value.name}, Age: ${result.value.age}`);
-console.log(`Succeeded on attempt ${result.attempts}`);
+console.log(result.value); // { name: "John Doe", age: 30 }
 ```
 
-#### Schema features
+## Streaming Structured Outputs
 
-Zod schemas map to JSON Schema properties:
+Build progressive UIs that render fields as they complete:
 
 ```ts
-const StatusSchema = z.object({
-  // Required string field
-  code: z.string(),
-
-  // Optional field (not in "required" array)
-  notes: z.string().optional(),
-
-  // Description for documentation
-  email: z.string().email().describe("User's email address"),
-
-  // Enum constraint
-  priority: z.enum(["low", "medium", "high"]),
-
-  // Nested objects are fully supported
-  address: z.object({
-    city: z.string(),
-    country: z.string(),
-  }),
-
-  // Arrays
-  tags: z.array(z.string()),
+const Article = z.object({
+  title: z.string(),
+  summary: z.string(),
+  body: z.string(),
 });
-```
 
-#### Handling validation errors
-
-When validation fails after all retries:
-
-```ts
-import { StructuredExhaustedError } from "@modelrelay/sdk";
+const stream = await mr.chat.completions.streamStructured(Article, {
+  model: "claude-sonnet-4-20250514",
+  messages: [{ role: "user", content: "Write an article about TypeScript" }],
+});
 
-try {
-  const result = await mr.chat.completions.structured(
-    PersonSchema,
-    { model: "claude-sonnet-4-20250514", messages },
-    { maxRetries: 2 }
-  );
-} catch (err) {
-  if (err instanceof StructuredExhaustedError) {
-    console.log(`Failed after ${err.allAttempts.length} attempts`);
-    for (const attempt of err.allAttempts) {
-      console.log(`Attempt ${attempt.attempt}: ${attempt.rawJson}`);
-      if (attempt.error.kind === "validation" && attempt.error.issues) {
-        for (const issue of attempt.error.issues) {
-          console.log(`  - ${issue.path ?? "root"}: ${issue.message}`);
-        }
-      } else if (attempt.error.kind === "decode") {
-        console.log(`  Decode error: ${attempt.error.message}`);
-      }
-    }
+for await (const event of stream) {
+  // Render fields as soon as they're complete
+  if (event.completeFields.has("title")) {
+    renderTitle(event.payload.title);  // Safe to display
   }
-}
-```
-
-#### Custom retry handlers
-
-Customize retry behavior:
-
-```ts
-import type { RetryHandler } from "@modelrelay/sdk";
-
-const customHandler: RetryHandler = {
-  onValidationError(attempt, rawJson, error, messages) {
-    if (attempt >= 3) {
-      return null; // Stop retrying
-    }
-    return [
-      {
-        role: "user",
-        content: `Invalid response. Issues: ${JSON.stringify(error.issues)}. Try again.`,
-      },
-    ];
-  },
-};
-
-const result = await mr.chat.completions.structured(
-  PersonSchema,
-  { model: "claude-sonnet-4-20250514", messages },
-  { maxRetries: 3, retryHandler: customHandler }
-);
-```
-
-#### Streaming structured outputs
-
-For streaming with Zod schema (no retries):
-
-```ts
-const stream = await mr.chat.completions.streamStructured(
-  PersonSchema,
-  {
-    model: "claude-sonnet-4-20250514",
-    messages: [{ role: "user", content: "Extract: Jane, 25" }],
+  if (event.completeFields.has("summary")) {
+    renderSummary(event.payload.summary);
   }
-);
 
-for await (const evt of stream) {
-  if (evt.type === "completion") {
-    console.log("Final:", evt.payload);
+  // Show streaming preview of incomplete fields
+  if (!event.completeFields.has("body")) {
+    renderBodyPreview(event.payload.body + "▋");
   }
 }
 ```
 
-#### Customer-attributed structured outputs
-
-Works with customer-attributed requests too:
-
-```ts
-const result = await mr.chat.forCustomer("customer-123").structured(
-  PersonSchema,
-  { messages: [{ role: "user", content: "Extract: John, 30" }] },
-  { maxRetries: 2 }
-);
-```
-
-### Telemetry & metrics hooks
+## Customer-Attributed Requests
 
-Provide lightweight callbacks to observe latency and usage without extra deps:
+For metered billing, use `forCustomer()` — the customer's tier determines the model:
 
 ```ts
-const calls: string[] = [];
-const mr = new ModelRelay({
-  key: "mr_sk_...",
-  metrics: {
-    httpRequest: (m) => calls.push(`http ${m.context.path} ${m.status} ${m.latencyMs}ms`),
-    streamFirstToken: (m) => calls.push(`first-token ${m.latencyMs}ms`),
-    usage: (m) => calls.push(`usage ${m.usage.totalTokens}`)
-  },
-  trace: {
-    streamEvent: ({ event }) => calls.push(`event ${event.type}`),
-    requestFinish: ({ status, latencyMs }) => calls.push(`finished ${status} in ${latencyMs}`)
-  }
+const stream = await mr.chat.forCustomer("customer-123").create({
+  messages: [{ role: "user", content: "Hello" }],
 });
-
-// Per-call overrides
-await mr.chat.completions.create(
-  { model: "echo-1", messages: [{ role: "user", content: "hi" }] },
-  { metrics: { usage: console.log }, trace: { streamEvent: console.debug } }
-);
 ```
 
-### Error categories
-
-- **ConfigError**: missing key/token, invalid base URL, or request validation issues.
-- **TransportError**: network/connect/request/timeout failures (`kind` is one of `connect | timeout | request | other`), includes retry metadata when retries were attempted.
-- **APIError**: Non-2xx responses with `status`, `code`, `fields`, `requestId`, and optional `retries` metadata.
-
-## API surface
-
-- `chat.completions.create(params, options?)`
-  - Supports streaming (default) or blocking JSON (`stream: false`).
-  - Accepts per-call `requestId`, `headers`, `metadata`, `timeoutMs`, and `retry` overrides.
-- `apiKeys.list() | create() | delete(id)` — manage API keys when using secret keys or bearer tokens.
-- `customers` — manage customers with a secret key (see below).
-
-## Backend Customer Management
-
-Use a secret key (`mr_sk_*`) to manage customers from your backend:
+## Customer Management (Backend)
 
 ```ts
-import { ModelRelay } from "@modelrelay/sdk";
-
-const mr = new ModelRelay({ key: "mr_sk_..." });
-
-// Create or update a customer (upsert by external_id)
+// Create/update customer
 const customer = await mr.customers.upsert({
-  tier_id: "your-tier-uuid",
-  external_id: "github-user-12345",  // your app's user ID
+  tier_id: "tier-uuid",
+  external_id: "your-user-id",
   email: "user@example.com",
 });
 
-// List all customers
-const customers = await mr.customers.list();
-
-// Get a specific customer
-const customer = await mr.customers.get("customer-uuid");
-
-// Create a checkout session for subscription billing
-const session = await mr.customers.createCheckoutSession("customer-uuid", {
-  success_url: "https://myapp.com/billing/success",
-  cancel_url: "https://myapp.com/billing/cancel",
+// Create checkout session for subscription billing
+const session = await mr.customers.createCheckoutSession(customer.id, {
+  success_url: "https://myapp.com/success",
+  cancel_url: "https://myapp.com/cancel",
 });
-// Redirect user to session.url to complete payment
 
 // Check subscription status
-const status = await mr.customers.getSubscription("customer-uuid");
-if (status.active) {
-  // Grant access
-}
+const status = await mr.customers.getSubscription(customer.id);
+```
+
+## Configuration
 
-// Delete a customer
-await mr.customers.delete("customer-uuid");
+```ts
+const mr = new ModelRelay({
+  key: "mr_sk_...",
+  environment: "production", // or "staging", "sandbox"
+  timeoutMs: 30_000,
+  retry: { maxAttempts: 3 },
+});
 ```

package/dist/index.cjs

@@ -437,7 +437,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.25.1",
+  version: "0.27.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -2123,11 +2123,13 @@ var StructuredJSONStream = class {
     if (rawType === "completion") {
       this.sawTerminal = true;
     }
+    const completeFieldsArray = Array.isArray(obj.complete_fields) ? obj.complete_fields.filter((f) => typeof f === "string") : [];
     const event = {
       type: rawType,
       // biome-ignore lint/suspicious/noExplicitAny: payload is untyped json
       payload: obj.payload,
-      requestId: this.requestId
+      requestId: this.requestId,
+      completeFields: new Set(completeFieldsArray)
     };
     return event;
   }

package/dist/index.d.cts

@@ -560,10 +560,29 @@ interface ChatCompletionEvent<T = unknown> {
     raw: string;
 }
 type StructuredJSONRecordType = "start" | "update" | "completion" | "error";
+/**
+ * Recursively makes all properties optional.
+ * Useful for typing partial payloads during progressive streaming before
+ * all fields are complete.
+ *
+ * @example
+ * interface Article { title: string; body: string; }
+ * type PartialArticle = DeepPartial<Article>;
+ * // { title?: string; body?: string; }
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
 interface StructuredJSONEvent<T> {
     type: "update" | "completion";
     payload: T;
     requestId?: string;
+    /**
+     * Set of field paths that are complete (have their closing delimiter).
+     * Use dot notation for nested fields (e.g., "metadata.author").
+     * Check with completeFields.has("fieldName").
+     */
+    completeFields: Set<string>;
 }
 interface APIFrontendToken {
     token: string;
@@ -1884,4 +1903,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, type AttemptRecord, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, CustomerChatClient, type CustomerChatParams, type CustomerClaimRequest, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenAutoProvisionRequest, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownStopReason, type MessageDeltaData, type MessageRole, MessageRoles, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, type RequestContext, type ResponseFormat, type ResponseFormatType, ResponseFormatTypes, type ResponseJSONSchemaFormat, type RetryConfig, type RetryHandler, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, type StructuredJSONEvent, type StructuredJSONRecordType, StructuredJSONStream, type StructuredOptions, type StructuredResult, type SubscriptionStatus, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TiersClient, type TokenType, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type ValidationIssue, type WebSearchConfig, type WebToolMode, WebToolModes, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, defaultRetryHandler, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, responseFormatFromZod, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, validateWithZod, zodToJsonSchema };
+export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, type AttemptRecord, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, CustomerChatClient, type CustomerChatParams, type CustomerClaimRequest, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepPartial, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenAutoProvisionRequest, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownStopReason, type MessageDeltaData, type MessageRole, MessageRoles, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, type RequestContext, type ResponseFormat, type ResponseFormatType, ResponseFormatTypes, type ResponseJSONSchemaFormat, type RetryConfig, type RetryHandler, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, type StructuredJSONEvent, type StructuredJSONRecordType, StructuredJSONStream, type StructuredOptions, type StructuredResult, type SubscriptionStatus, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TiersClient, type TokenType, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type ValidationIssue, type WebSearchConfig, type WebToolMode, WebToolModes, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, defaultRetryHandler, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, responseFormatFromZod, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, validateWithZod, zodToJsonSchema };

package/dist/index.d.ts

@@ -560,10 +560,29 @@ interface ChatCompletionEvent<T = unknown> {
     raw: string;
 }
 type StructuredJSONRecordType = "start" | "update" | "completion" | "error";
+/**
+ * Recursively makes all properties optional.
+ * Useful for typing partial payloads during progressive streaming before
+ * all fields are complete.
+ *
+ * @example
+ * interface Article { title: string; body: string; }
+ * type PartialArticle = DeepPartial<Article>;
+ * // { title?: string; body?: string; }
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
 interface StructuredJSONEvent<T> {
     type: "update" | "completion";
     payload: T;
     requestId?: string;
+    /**
+     * Set of field paths that are complete (have their closing delimiter).
+     * Use dot notation for nested fields (e.g., "metadata.author").
+     * Check with completeFields.has("fieldName").
+     */
+    completeFields: Set<string>;
 }
 interface APIFrontendToken {
     token: string;
@@ -1884,4 +1903,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, type AttemptRecord, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, CustomerChatClient, type CustomerChatParams, type CustomerClaimRequest, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenAutoProvisionRequest, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownStopReason, type MessageDeltaData, type MessageRole, MessageRoles, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, type RequestContext, type ResponseFormat, type ResponseFormatType, ResponseFormatTypes, type ResponseJSONSchemaFormat, type RetryConfig, type RetryHandler, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, type StructuredJSONEvent, type StructuredJSONRecordType, StructuredJSONStream, type StructuredOptions, type StructuredResult, type SubscriptionStatus, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TiersClient, type TokenType, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type ValidationIssue, type WebSearchConfig, type WebToolMode, WebToolModes, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, defaultRetryHandler, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, responseFormatFromZod, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, validateWithZod, zodToJsonSchema };
+export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, type AttemptRecord, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, CustomerChatClient, type CustomerChatParams, type CustomerClaimRequest, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepPartial, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenAutoProvisionRequest, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownStopReason, type MessageDeltaData, type MessageRole, MessageRoles, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, type RequestContext, type ResponseFormat, type ResponseFormatType, ResponseFormatTypes, type ResponseJSONSchemaFormat, type RetryConfig, type RetryHandler, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, type StructuredJSONEvent, type StructuredJSONRecordType, StructuredJSONStream, type StructuredOptions, type StructuredResult, type SubscriptionStatus, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TiersClient, type TokenType, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type ValidationIssue, type WebSearchConfig, type WebToolMode, WebToolModes, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, defaultRetryHandler, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isEmailRequired, isNoFreeTier, isNoTiers, isProvisioningError, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, respondToToolCall, responseFormatFromZod, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, validateWithZod, zodToJsonSchema };

package/dist/index.js

@@ -340,7 +340,7 @@ function isTokenReusable(token) {
 // package.json
 var package_default = {
   name: "@modelrelay/sdk",
-  version: "0.25.1",
+  version: "0.27.0",
   description: "TypeScript SDK for the ModelRelay API",
   type: "module",
   main: "dist/index.cjs",
@@ -2026,11 +2026,13 @@ var StructuredJSONStream = class {
     if (rawType === "completion") {
       this.sawTerminal = true;
     }
+    const completeFieldsArray = Array.isArray(obj.complete_fields) ? obj.complete_fields.filter((f) => typeof f === "string") : [];
     const event = {
       type: rawType,
       // biome-ignore lint/suspicious/noExplicitAny: payload is untyped json
       payload: obj.payload,
-      requestId: this.requestId
+      requestId: this.requestId,
+      completeFields: new Set(completeFieldsArray)
     };
     return event;
   }

package/package.json

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