feat: add usage accounting support to OpenRouter (#64)

* feat: add usage accounting support to OpenRouter

- Updated README.md to include usage accounting use cases and examples.
- Enhanced OpenRouterChatLanguageModel to support usage accounting settings and metadata extraction.
- Implemented detailed usage information tracking in responses.
- Added tests for usage accounting functionality, ensuring correct metadata inclusion based on settings.

Tested:
- Verified that usage accounting data is included in responses when enabled.
- Confirmed that provider-specific metadata is omitted when usage accounting is disabled.

* fix: update OpenRouterSharedSettings type definition

- Moved `OpenRouterSharedSettings` type definition to the correct location in `src/types.ts`.
- Added `extraBody` property to `OpenRouterSharedSettings`.
- Marked `includeReasoning` as deprecated, suggesting to use `reasoning` instead.

Tested:
- No functional changes, but type definitions are now correctly structured.

* chore: release version 0.5.0 with usage accounting support

- Added support for OpenRouter usage accounting feature, enabling tracking of token usage details in API responses.
- Updated schema to accommodate the new usage accounting response format.
- Documented changes in CHANGELOG.md.

Tested:
- Verified that usage accounting data is correctly included in both streaming and non-streaming API responses.

* feat: refactor usage accounting schema in OpenRouter

- Introduced `openRouterUsageAccountingSchema` to centralize usage accounting details.
- Updated `OpenRouterChatCompletionBaseResponseSchema` to utilize the new schema for cleaner code.
- Added TypeScript type inference for `OpenRouterUsageAccounting` in `src/types.ts`.

Tested:
- Ensured that the new schema correctly captures token usage details in API responses.

* chore: update version to 0.5.0-canary.1 and adjust CHANGELOG.md

- Changed package version from 0.5.0 to 0.5.0-canary.1 to indicate a pre-release.
- Updated CHANGELOG.md to reflect the version as [Unreleased] for upcoming changes.

No functional changes; this prepares the package for the next development phase.

* chore: update version to 0.5.0-canary.2 and refactor usage accounting schema

- Bumped package version to 0.5.0-canary.2.
- Refactored `OpenRouterChatCompletionBaseResponseSchema` to directly define the usage accounting schema inline, improving clarity and maintainability.
- Updated `OpenRouterUsageAccounting` type definition to match the new schema structure.

No functional changes; this prepares the package for further development.

* chore: update pnpm and tsconfig

* chore: add e2e test

* chore: add example env.e2e

* use kebab case for key

* chore: bump deps

---------

Co-authored-by: lab <[email protected]>

Author: ImBIOS

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 dist
 ./internal
+
+.env.e2e*

CHANGELOG.md

@@ -37,7 +37,7 @@ const { text } = await generateText({
 
 ## Supported models
 
-This list is not a definitive list of models supported by OpenRouter, as it constantly changes as we add new models (and deprecate old ones) to our system.  
+This list is not a definitive list of models supported by OpenRouter, as it constantly changes as we add new models (and deprecate old ones) to our system.
 You can find the latest list of models supported by OpenRouter [here](https://openrouter.ai/models).
 
 You can find the latest list of tool-supported models supported by OpenRouter [here](https://openrouter.ai/models?order=newest&supported_parameters=tools). (Note: This list may contain models that are not compatible with the AI SDK.)
@@ -154,3 +154,30 @@ await streamText({
   ],
 });
 ```
+
+## Use Cases
+
+### 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.
+
+```typescript
+// 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 usage details (available in providerMetadata)
+if (result.providerMetadata?.openrouter?.usage) {
+  console.log('Cost:', result.providerMetadata.openrouter.usage.cost);
+  console.log('Total Tokens:', result.providerMetadata.openrouter.usage.totalTokens);
+}
+```

README.md

@@ -0,0 +1,50 @@
+import { createOpenRouter } from '@/src';
+import { streamText } from 'ai';
+import { it } from 'vitest';
+
+it('receive usage accounting', async () => {
+  const openrouter = createOpenRouter({
+    apiKey: process.env.OPENROUTER_API_KEY,
+    baseUrl: `${process.env.OPENROUTER_API_BASE}/api/v1`,
+  });
+  const model = openrouter('anthropic/claude-3.7-sonnet:thinking', {
+    usage: {
+      include: true,
+    },
+  });
+  const response = streamText({
+    model,
+    messages: [
+      {
+        role: 'user',
+        content: 'What is the capital of France?',
+      },
+    ],
+    onFinish(e) {
+      expect(e.providerMetadata?.openrouter).toMatchObject({
+        usage: expect.objectContaining({
+          promptTokens: expect.any(Number),
+          completionTokens: expect.any(Number),
+          promptTokensDetails: expect.any(Object),
+          completionTokensDetails: expect.any(Object),
+          totalTokens: expect.any(Number),
+          cost: expect.any(Number),
+        }),
+      });
+    },
+  });
+
+  await response.consumeStream();
+  const providerMetadata = await response.providerMetadata;
+  // You can use expect.any(Type) or expect.objectContaining for schema-like matching
+  expect(providerMetadata?.openrouter).toMatchObject({
+    usage: expect.objectContaining({
+      promptTokens: expect.any(Number),
+      completionTokens: expect.any(Number),
+      promptTokensDetails: expect.any(Object),
+      completionTokensDetails: expect.any(Object),
+      totalTokens: expect.any(Number),
+      cost: expect.any(Number),
+    }),
+  });
+});

e2e/usage-accounting.test.ts

@@ -0,0 +1,3 @@
+# Rename to .env.e2e
+OPENROUTER_API_BASE=https://openrouter.ai
+OPENROUTER_API_KEY=you-api-key-here

example.env.e2e

@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/ai-sdk-provider",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -20,7 +20,8 @@
     "prepublish": "pnpm run build",
     "test": "pnpm test:node && pnpm test:edge",
     "test:edge": "vitest --config vitest.edge.config.ts --run",
-    "test:node": "vitest --config vitest.node.config.ts --run"
+    "test:node": "vitest --config vitest.node.config.ts --run",
+    "test:e2e": "vitest --config vitest.e2e.config.ts --run"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -41,6 +42,7 @@
     "@ai-sdk/provider-utils": "2.1.10"
   },
   "devDependencies": {
+    "@biomejs/biome": "1.9.4",
     "@ianvs/prettier-plugin-sort-imports": "4.4.1",
     "@edge-runtime/vm": "5.0.0",
     "@types/jest": "29.5.14",
@@ -50,6 +52,8 @@
     "prettier": "3.5.2",
     "typescript": "5.7.3",
     "vitest": "3.0.7",
+    "vite-tsconfig-paths": "5.1.4",
+    "dotenv": "16.5.0",
     "zod": "3.24.2"
   },
   "peerDependencies": {
@@ -72,5 +76,5 @@
   "keywords": [
     "ai"
   ],
-  "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
+  "packageManager": "pnpm@10.11.0"
 }

package.json

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - '@biomejs/biome'