@openrouter/ai-sdk-provider 1.2.8 → 1.3.0

package/README.md

@@ -167,9 +167,134 @@ await streamText({
   ],
 });
 ```
+## Anthropic Beta Features
+
+You can enable Anthropic beta features by passing custom headers through the OpenRouter SDK.
+
+### Fine-grained Tool Streaming
+
+[Fine-grained tool streaming](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/fine-grained-tool-streaming) allows streaming tool parameters without buffering, reducing latency for large schemas. This is particularly useful when working with large nested JSON structures.
+
+**Important:** This is a beta feature from Anthropic. Make sure to evaluate responses before using in production.
+
+#### Basic Usage
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { streamObject } from 'ai';
+
+const provider = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  headers: {
+    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
+  },
+});
+
+const model = provider.chat('anthropic/claude-sonnet-4');
+
+const result = await streamObject({
+  model,
+  schema: yourLargeSchema,
+  prompt: 'Generate a complex object...',
+});
+
+for await (const partialObject of result.partialObjectStream) {
+  console.log(partialObject);
+}
+```
+
+You can also pass the header at the request level:
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { generateText } from 'ai';
+
+const provider = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const model = provider.chat('anthropic/claude-sonnet-4');
+
+await generateText({
+  model,
+  prompt: 'Hello',
+  headers: {
+    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
+  },
+});
+```
+
+**Note:** Fine-grained tool streaming is specific to Anthropic models. When using models from other providers, the header will be ignored.
+
+#### Use Case: Large Component Generation
+
+This feature is particularly beneficial when streaming large, nested JSON structures like UI component trees:
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { streamObject } from 'ai';
+import { z } from 'zod';
+
+const componentSchema = z.object({
+  type: z.string(),
+  props: z.record(z.any()),
+  children: z.array(z.lazy(() => componentSchema)).optional(),
+});
+
+const provider = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+  headers: {
+    'anthropic-beta': 'fine-grained-tool-streaming-2025-05-14',
+  },
+});
+
+const model = provider.chat('anthropic/claude-sonnet-4');
+
+const result = await streamObject({
+  model,
+  schema: componentSchema,
+  prompt: 'Create a responsive dashboard layout',
+});
+
+for await (const partialComponent of result.partialObjectStream) {
+  console.log('Partial component:', partialComponent);
+}
+```
+
+
 
 ## Use Cases
 
+### Debugging API Requests
+
+The provider supports a debug mode that echoes back the request body sent to the upstream provider. This is useful for troubleshooting and understanding how your requests are being processed. Note that debug mode only works with streaming requests.
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { streamText } from 'ai';
+
+const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
+const model = openrouter('anthropic/claude-3.5-sonnet', {
+  debug: {
+    echo_upstream_body: true,
+  },
+});
+
+const result = await streamText({
+  model,
+  prompt: 'Hello, how are you?',
+});
+
+// The debug data is available in the stream's first chunk
+// and in the final response's providerMetadata
+for await (const chunk of result.fullStream) {
+  // Debug chunks have empty choices and contain debug.echo_upstream_body
+  console.log(chunk);
+}
+```
+
+The debug response will include the request body that was sent to the upstream provider, with sensitive data redacted (user IDs, base64 content, etc.). This helps you understand how OpenRouter transforms your request before sending it to the model provider.
+
 ### Usage Accounting
 
 The provider supports [OpenRouter usage accounting](https://openrouter.ai/docs/use-cases/usage-accounting), which allows you to track token usage details directly in your API responses, without making additional API calls.
@@ -197,3 +322,35 @@ if (result.providerMetadata?.openrouter?.usage) {
   );
 }
 ```
+
+It also supports BYOK (Bring Your Own Key) [usage accounting](https://openrouter.ai/docs/docs/guides/usage-accounting#cost-breakdown), which allows you to track passthrough costs when you are using a provider's own API key in your OpenRouter account.
+
+```typescript
+// Assuming you have set an OpenAI API key in https://openrouter.ai/settings/integrations
+
+// Enable usage accounting
+const model = openrouter('openai/gpt-3.5-turbo', {
+  usage: {
+    include: true,
+  },
+});
+
+// Access usage accounting data
+const result = await generateText({
+  model,
+  prompt: 'Hello, how are you today?',
+});
+
+// Provider-specific BYOK usage details (available in providerMetadata)
+if (result.providerMetadata?.openrouter?.usage) {
+  const costDetails = result.providerMetadata.openrouter.usage.costDetails;
+  if (costDetails) {
+    console.log('BYOK cost:', costDetails.upstreamInferenceCost);
+  }
+  console.log('OpenRouter credits cost:', result.providerMetadata.openrouter.usage.cost);
+  console.log(
+    'Total Tokens:',
+    result.providerMetadata.openrouter.usage.totalTokens,
+  );
+}
+```

package/dist/index.d.mts

@@ -71,6 +71,19 @@ type OpenRouterChatSettings = {
          */
         search_prompt?: string;
     };
+    /**
+     * Debug options for troubleshooting API requests.
+     * Only works with streaming requests.
+     * @see https://openrouter.ai/docs/api-reference/debugging
+     */
+    debug?: {
+        /**
+         * When true, echoes back the request body that was sent to the upstream provider.
+         * The debug data will be returned as the first chunk in the stream with a `debug.echo_upstream_body` field.
+         * Sensitive data like user IDs and base64 content will be redacted.
+         */
+        echo_upstream_body?: boolean;
+    };
     /**
      * Provider routing preferences to control request routing behavior
      */
@@ -106,7 +119,7 @@ type OpenRouterChatSettings = {
         /**
          * Sort providers by price, throughput, or latency
          */
-        sort?: models.Sort;
+        sort?: models.ProviderSort;
         /**
          * Maximum pricing you want to pay for this request
          */
@@ -173,7 +186,7 @@ type OpenRouterUsageAccounting = {
     };
     totalTokens: number;
     cost?: number;
-    costDetails: {
+    costDetails?: {
         upstreamInferenceCost: number;
     };
 };

package/dist/index.d.ts

@@ -71,6 +71,19 @@ type OpenRouterChatSettings = {
          */
         search_prompt?: string;
     };
+    /**
+     * Debug options for troubleshooting API requests.
+     * Only works with streaming requests.
+     * @see https://openrouter.ai/docs/api-reference/debugging
+     */
+    debug?: {
+        /**
+         * When true, echoes back the request body that was sent to the upstream provider.
+         * The debug data will be returned as the first chunk in the stream with a `debug.echo_upstream_body` field.
+         * Sensitive data like user IDs and base64 content will be redacted.
+         */
+        echo_upstream_body?: boolean;
+    };
     /**
      * Provider routing preferences to control request routing behavior
      */
@@ -106,7 +119,7 @@ type OpenRouterChatSettings = {
         /**
          * Sort providers by price, throughput, or latency
          */
-        sort?: models.Sort;
+        sort?: models.ProviderSort;
         /**
          * Maximum pricing you want to pay for this request
          */
@@ -173,7 +186,7 @@ type OpenRouterUsageAccounting = {
     };
     totalTokens: number;
     cost?: number;
-    costDetails: {
+    costDetails?: {
         upstreamInferenceCost: number;
     };
 };

package/dist/index.js

@@ -1030,7 +1030,7 @@ var OpenRouterProviderMetadataSchema = import_v43.z.object({
     cost: import_v43.z.number().optional(),
     costDetails: import_v43.z.object({
       upstreamInferenceCost: import_v43.z.number()
-    }).passthrough()
+    }).passthrough().optional()
   }).passthrough()
 }).passthrough();
 var OpenRouterProviderOptionsSchema = import_v43.z.object({
@@ -1149,9 +1149,8 @@ function getCacheControl(providerMetadata) {
   return (_c = (_b = (_a15 = openrouter2 == null ? void 0 : openrouter2.cacheControl) != null ? _a15 : openrouter2 == null ? void 0 : openrouter2.cache_control) != null ? _b : anthropic == null ? void 0 : anthropic.cacheControl) != null ? _c : anthropic == null ? void 0 : anthropic.cache_control;
 }
 function convertToOpenRouterChatMessages(prompt) {
-  var _a15, _b, _c, _d, _e, _f;
+  var _a15, _b, _c, _d, _e, _f, _g, _h;
   const messages = [];
-  const accumulatedReasoningDetails = [];
   for (const { role, content, providerOptions } of prompt) {
     switch (role) {
       case "system": {
@@ -1181,7 +1180,7 @@ function convertToOpenRouterChatMessages(prompt) {
         const messageCacheControl = getCacheControl(providerOptions);
         const contentParts = content.map(
           (part) => {
-            var _a16, _b2, _c2, _d2, _e2, _f2, _g;
+            var _a16, _b2, _c2, _d2, _e2, _f2, _g2;
             const cacheControl = (_a16 = getCacheControl(part.providerOptions)) != null ? _a16 : messageCacheControl;
             switch (part.type) {
               case "text":
@@ -1214,7 +1213,7 @@ function convertToOpenRouterChatMessages(prompt) {
                   };
                 }
                 const fileName = String(
-                  (_g = (_f2 = (_e2 = (_d2 = part.providerOptions) == null ? void 0 : _d2.openrouter) == null ? void 0 : _e2.filename) != null ? _f2 : part.filename) != null ? _g : ""
+                  (_g2 = (_f2 = (_e2 = (_d2 = part.providerOptions) == null ? void 0 : _d2.openrouter) == null ? void 0 : _e2.filename) != null ? _f2 : part.filename) != null ? _g2 : ""
                 );
                 const fileData = getFileUrl({
                   part,
@@ -1261,6 +1260,7 @@ function convertToOpenRouterChatMessages(prompt) {
         let text = "";
         let reasoning = "";
         const toolCalls = [];
+        const accumulatedReasoningDetails = [];
         for (const part of content) {
           switch (part.type) {
             case "text": {
@@ -1286,6 +1286,12 @@ function convertToOpenRouterChatMessages(prompt) {
             }
             case "reasoning": {
               reasoning += part.text;
+              const parsedPartProviderOptions = OpenRouterProviderOptionsSchema.safeParse(part.providerOptions);
+              if (parsedPartProviderOptions.success && ((_e = (_d = parsedPartProviderOptions.data) == null ? void 0 : _d.openrouter) == null ? void 0 : _e.reasoning_details)) {
+                accumulatedReasoningDetails.push(
+                  ...parsedPartProviderOptions.data.openrouter.reasoning_details
+                );
+              }
               break;
             }
             case "file":
@@ -1296,7 +1302,7 @@ function convertToOpenRouterChatMessages(prompt) {
           }
         }
         const parsedProviderOptions = OpenRouterProviderOptionsSchema.safeParse(providerOptions);
-        const messageReasoningDetails = parsedProviderOptions.success ? (_e = (_d = parsedProviderOptions.data) == null ? void 0 : _d.openrouter) == null ? void 0 : _e.reasoning_details : void 0;
+        const messageReasoningDetails = parsedProviderOptions.success ? (_g = (_f = parsedProviderOptions.data) == null ? void 0 : _f.openrouter) == null ? void 0 : _g.reasoning_details : void 0;
         const finalReasoningDetails = messageReasoningDetails && Array.isArray(messageReasoningDetails) && messageReasoningDetails.length > 0 ? messageReasoningDetails : accumulatedReasoningDetails.length > 0 ? accumulatedReasoningDetails : void 0;
         messages.push({
           role: "assistant",
@@ -1315,7 +1321,7 @@ function convertToOpenRouterChatMessages(prompt) {
             role: "tool",
             tool_call_id: toolResponse.toolCallId,
             content: content2,
-            cache_control: (_f = getCacheControl(providerOptions)) != null ? _f : getCacheControl(toolResponse.providerOptions)
+            cache_control: (_h = getCacheControl(providerOptions)) != null ? _h : getCacheControl(toolResponse.providerOptions)
           });
         }
         break;
@@ -1631,7 +1637,9 @@ var OpenRouterChatLanguageModel = class {
       plugins: this.settings.plugins,
       web_search_options: this.settings.web_search_options,
       // Provider routing settings:
-      provider: this.settings.provider
+      provider: this.settings.provider,
+      // Debug settings:
+      debug: this.settings.debug
     }, this.config.extraBody), this.settings.extraBody);
     if ((responseFormat == null ? void 0 : responseFormat.type) === "json" && responseFormat.schema != null) {
       return __spreadProps(__spreadValues({}, baseArgs), {
@@ -1666,7 +1674,7 @@ var OpenRouterChatLanguageModel = class {
     return baseArgs;
   }
   async doGenerate(options) {
-    var _a15, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
+    var _a15, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v;
     const providerOptions = options.providerOptions || {};
     const openrouterOptions = providerOptions.openrouter || {};
     const args = __spreadValues(__spreadValues({}, this.getArgs(options)), openrouterOptions);
@@ -1833,21 +1841,24 @@ var OpenRouterChatLanguageModel = class {
         openrouter: OpenRouterProviderMetadataSchema.parse({
           provider: (_k = response.provider) != null ? _k : "",
           reasoning_details: (_l = choice.message.reasoning_details) != null ? _l : [],
-          usage: {
+          usage: __spreadValues(__spreadValues(__spreadValues({
             promptTokens: (_m = usageInfo.inputTokens) != null ? _m : 0,
             completionTokens: (_n = usageInfo.outputTokens) != null ? _n : 0,
             totalTokens: (_o = usageInfo.totalTokens) != null ? _o : 0,
-            cost: (_p = response.usage) == null ? void 0 : _p.cost,
+            cost: (_p = response.usage) == null ? void 0 : _p.cost
+          }, ((_r = (_q = response.usage) == null ? void 0 : _q.prompt_tokens_details) == null ? void 0 : _r.cached_tokens) != null ? {
             promptTokensDetails: {
-              cachedTokens: (_s = (_r = (_q = response.usage) == null ? void 0 : _q.prompt_tokens_details) == null ? void 0 : _r.cached_tokens) != null ? _s : 0
-            },
+              cachedTokens: response.usage.prompt_tokens_details.cached_tokens
+            }
+          } : {}), ((_t = (_s = response.usage) == null ? void 0 : _s.completion_tokens_details) == null ? void 0 : _t.reasoning_tokens) != null ? {
             completionTokensDetails: {
-              reasoningTokens: (_v = (_u = (_t = response.usage) == null ? void 0 : _t.completion_tokens_details) == null ? void 0 : _u.reasoning_tokens) != null ? _v : 0
-            },
+              reasoningTokens: response.usage.completion_tokens_details.reasoning_tokens
+            }
+          } : {}), ((_v = (_u = response.usage) == null ? void 0 : _u.cost_details) == null ? void 0 : _v.upstream_inference_cost) != null ? {
             costDetails: {
-              upstreamInferenceCost: (_y = (_x = (_w = response.usage) == null ? void 0 : _w.cost_details) == null ? void 0 : _x.upstream_inference_cost) != null ? _y : 0
+              upstreamInferenceCost: response.usage.cost_details.upstream_inference_cost
             }
-          }
+          } : {})
         })
       },
       request: { body: args },
@@ -1904,7 +1915,7 @@ var OpenRouterChatLanguageModel = class {
       stream: response.pipeThrough(
         new TransformStream({
           transform(chunk, controller) {
-            var _a16, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
+            var _a16, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o;
             if (!chunk.success) {
               finishReason = "error";
               controller.enqueue({ type: "error", error: chunk.error });
@@ -1954,6 +1965,12 @@ var OpenRouterChatLanguageModel = class {
               }
               openrouterUsage.cost = value.usage.cost;
               openrouterUsage.totalTokens = value.usage.total_tokens;
+              const upstreamInferenceCost = (_c = value.usage.cost_details) == null ? void 0 : _c.upstream_inference_cost;
+              if (upstreamInferenceCost != null) {
+                openrouterUsage.costDetails = {
+                  upstreamInferenceCost
+                };
+              }
             }
             const choice = value.choices[0];
             if ((choice == null ? void 0 : choice.finish_reason) != null) {
@@ -1963,16 +1980,18 @@ var OpenRouterChatLanguageModel = class {
               return;
             }
             const delta = choice.delta;
-            const emitReasoningChunk = (chunkText) => {
+            const emitReasoningChunk = (chunkText, providerMetadata) => {
               if (!reasoningStarted) {
                 reasoningId = openrouterResponseId || generateId();
                 controller.enqueue({
+                  providerMetadata,
                   type: "reasoning-start",
                   id: reasoningId
                 });
                 reasoningStarted = true;
               }
               controller.enqueue({
+                providerMetadata,
                 type: "reasoning-delta",
                 delta: chunkText,
                 id: reasoningId || generateId()
@@ -1993,23 +2012,28 @@ var OpenRouterChatLanguageModel = class {
                   accumulatedReasoningDetails.push(detail);
                 }
               }
+              const reasoningMetadata = {
+                openrouter: {
+                  reasoning_details: delta.reasoning_details
+                }
+              };
               for (const detail of delta.reasoning_details) {
                 switch (detail.type) {
                   case "reasoning.text" /* Text */: {
                     if (detail.text) {
-                      emitReasoningChunk(detail.text);
+                      emitReasoningChunk(detail.text, reasoningMetadata);
                     }
                     break;
                   }
                   case "reasoning.encrypted" /* Encrypted */: {
                     if (detail.data) {
-                      emitReasoningChunk("[REDACTED]");
+                      emitReasoningChunk("[REDACTED]", reasoningMetadata);
                     }
                     break;
                   }
                   case "reasoning.summary" /* Summary */: {
                     if (detail.summary) {
-                      emitReasoningChunk(detail.summary);
+                      emitReasoningChunk(detail.summary, reasoningMetadata);
                     }
                     break;
                   }
@@ -2064,7 +2088,7 @@ var OpenRouterChatLanguageModel = class {
             }
             if (delta.tool_calls != null) {
               for (const toolCallDelta of delta.tool_calls) {
-                const index = (_c = toolCallDelta.index) != null ? _c : toolCalls.length - 1;
+                const index = (_d = toolCallDelta.index) != null ? _d : toolCalls.length - 1;
                 if (toolCalls[index] == null) {
                   if (toolCallDelta.type !== "function") {
                     throw new InvalidResponseDataError({
@@ -2078,7 +2102,7 @@ var OpenRouterChatLanguageModel = class {
                       message: `Expected 'id' to be a string.`
                     });
                   }
-                  if (((_d = toolCallDelta.function) == null ? void 0 : _d.name) == null) {
+                  if (((_e = toolCallDelta.function) == null ? void 0 : _e.name) == null) {
                     throw new InvalidResponseDataError({
                       data: toolCallDelta,
                       message: `Expected 'function.name' to be a string.`
@@ -2089,7 +2113,7 @@ var OpenRouterChatLanguageModel = class {
                     type: "function",
                     function: {
                       name: toolCallDelta.function.name,
-                      arguments: (_e = toolCallDelta.function.arguments) != null ? _e : ""
+                      arguments: (_f = toolCallDelta.function.arguments) != null ? _f : ""
                     },
                     inputStarted: false,
                     sent: false
@@ -2101,7 +2125,7 @@ var OpenRouterChatLanguageModel = class {
                       message: `Tool call at index ${index} is missing after creation.`
                     });
                   }
-                  if (((_f = toolCall2.function) == null ? void 0 : _f.name) != null && ((_g = toolCall2.function) == null ? void 0 : _g.arguments) != null && isParsableJson(toolCall2.function.arguments)) {
+                  if (((_g = toolCall2.function) == null ? void 0 : _g.name) != null && ((_h = toolCall2.function) == null ? void 0 : _h.arguments) != null && isParsableJson(toolCall2.function.arguments)) {
                     toolCall2.inputStarted = true;
                     controller.enqueue({
                       type: "tool-input-start",
@@ -2151,18 +2175,18 @@ var OpenRouterChatLanguageModel = class {
                     toolName: toolCall.function.name
                   });
                 }
-                if (((_h = toolCallDelta.function) == null ? void 0 : _h.arguments) != null) {
-                  toolCall.function.arguments += (_j = (_i = toolCallDelta.function) == null ? void 0 : _i.arguments) != null ? _j : "";
+                if (((_i = toolCallDelta.function) == null ? void 0 : _i.arguments) != null) {
+                  toolCall.function.arguments += (_k = (_j = toolCallDelta.function) == null ? void 0 : _j.arguments) != null ? _k : "";
                 }
                 controller.enqueue({
                   type: "tool-input-delta",
                   id: toolCall.id,
-                  delta: (_k = toolCallDelta.function.arguments) != null ? _k : ""
+                  delta: (_l = toolCallDelta.function.arguments) != null ? _l : ""
                 });
-                if (((_l = toolCall.function) == null ? void 0 : _l.name) != null && ((_m = toolCall.function) == null ? void 0 : _m.arguments) != null && isParsableJson(toolCall.function.arguments)) {
+                if (((_m = toolCall.function) == null ? void 0 : _m.name) != null && ((_n = toolCall.function) == null ? void 0 : _n.arguments) != null && isParsableJson(toolCall.function.arguments)) {
                   controller.enqueue({
                     type: "tool-call",
-                    toolCallId: (_n = toolCall.id) != null ? _n : generateId(),
+                    toolCallId: (_o = toolCall.id) != null ? _o : generateId(),
                     toolName: toolCall.function.name,
                     input: toolCall.function.arguments,
                     providerMetadata: {
@@ -2378,7 +2402,10 @@ var OpenRouterCompletionChunkSchema = import_v47.z.union([
         reasoning_tokens: import_v47.z.number()
       }).passthrough().nullish(),
       total_tokens: import_v47.z.number(),
-      cost: import_v47.z.number().optional()
+      cost: import_v47.z.number().optional(),
+      cost_details: import_v47.z.object({
+        upstream_inference_cost: import_v47.z.number().nullish()
+      }).passthrough().nullish()
     }).passthrough().nullish()
   }).passthrough(),
   OpenRouterErrorResponseSchema
@@ -2551,7 +2578,7 @@ var OpenRouterCompletionLanguageModel = class {
       stream: response.pipeThrough(
         new TransformStream({
           transform(chunk, controller) {
-            var _a15, _b;
+            var _a15, _b, _c;
             if (!chunk.success) {
               finishReason = "error";
               controller.enqueue({ type: "error", error: chunk.error });
@@ -2585,6 +2612,12 @@ var OpenRouterCompletionLanguageModel = class {
               }
               openrouterUsage.cost = value.usage.cost;
               openrouterUsage.totalTokens = value.usage.total_tokens;
+              const upstreamInferenceCost = (_c = value.usage.cost_details) == null ? void 0 : _c.upstream_inference_cost;
+              if (upstreamInferenceCost != null) {
+                openrouterUsage.costDetails = {
+                  upstreamInferenceCost
+                };
+              }
             }
             const choice = value.choices[0];
             if ((choice == null ? void 0 : choice.finish_reason) != null) {
@@ -2680,7 +2713,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = false ? "0.0.0-test" : "1.2.8";
+var VERSION = false ? "0.0.0-test" : "1.3.0";
 
 // src/provider.ts
 function createOpenRouter(options = {}) {