@usagetap/sdk 1.2.0 → 1.3.1

package/README.md

@@ -8,205 +8,180 @@ Server-only JavaScript/TypeScript client for UsageTap. The SDK helps you instrum
 
 Optional adapters live behind subpath exports so their peer dependencies stay out of the core bundle:
 
-- `@usagetap/sdk/openai` – OpenAI/OpenRouter helpers (`wrapOpenAI`, `streamOpenAIRoute`, etc.)
-- `@usagetap/sdk/anthropic` – Anthropic helper (`wrapAnthropic`)
-- `@usagetap/sdk/express` – Express middleware
-- `@usagetap/sdk/react` – React chat hook
+- `@usagetap/sdk/openai` – OpenAI/OpenRouter helpers (`wrapOpenAI`, `streamOpenAIRoute`, etc.)
+- `@usagetap/sdk/anthropic` – Anthropic helper (`wrapAnthropic`)
+- `@usagetap/sdk/openrouter` – discoverable OpenRouter aliases for the OpenAI-compatible wrappers
+- `@usagetap/sdk/express` – Express middleware
+- `@usagetap/sdk/react` – React chat hook
 
 Install only the peer dependencies for the adapters you actually use.
 
 ## Quick start
 
-Install the peer dependency for your vendor (e.g. `openai` or `@anthropic-ai/sdk`) and the UsageTap SDK in your server runtime.
+Install the peer dependency for your vendor (e.g. `openai` or `@anthropic-ai/sdk`) and the UsageTap SDK in your server runtime.
 
 ```bash
 npm install @usagetap/sdk openai
 ```
 
-Create a UsageTap client, request entitlements, and choose the right model every time:
+Wrap the provider client you already use. `USAGETAP_API_KEY` and the production
+UsageTap URL are read automatically:
 
 ```ts
 import OpenAI from "openai";
-import { UsageTapClient } from "@usagetap/sdk";
+import { withMetering } from "@usagetap/sdk/openai";
 
-const usageTap = new UsageTapClient({
-	apiKey: process.env.USAGETAP_API_KEY!,
-	baseUrl: process.env.USAGETAP_BASE_URL!,
+const openai = withMetering(new OpenAI(), "cust_123");
+const completion = await openai.responses.create({
+	model: "gpt-5.5-mini",
+	input: "Draft a welcome email for our Pro plan",
 });
 
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
+console.log(completion.output_text);
+```
 
-await usageTap.createCustomer({
-	customerId: "cust_123",
-	customerFriendlyName: "Acme AI",
-	customerEmail: "billing@acme.ai",
+Only the customer ID is required for metering. Pass an object instead of the
+string when you want optional feature, tag, entitlement, or prompt-compression
+settings. Existing `wrapOpenAI`, `wrapAnthropic`, and manual `withUsage` flows
+remain supported for advanced control.
+
+For standalone compression, wrap the client without changing any downstream
+calls:
+
+```ts
+import OpenAI from "openai";
+import { withCompression } from "@usagetap/sdk/openai";
+
+const openai = withCompression(new OpenAI(), {
+	// Defaults to 1,000. Use 0 to always attempt compression.
+	minContextTokens: 2_000,
+});
+const completion = await openai.responses.create({
+	model: "gpt-5.5-mini",
+	input: longPrompt,
 });
+```
 
-function selectCapabilities(allowed: {
-	standard?: boolean;
-	premium?: boolean;
-	reasoningLevel?: "LOW" | "MEDIUM" | "HIGH" | null;
-	search?: boolean;
-}) {
-	const tier = allowed.premium ? "premium" : "standard";
-	const model = tier === "premium" ? "gpt5" : "gpt5-mini";
-	const reasoningEffort = allowed.reasoningLevel === "HIGH"
-		? "high"
-		: allowed.reasoningLevel === "MEDIUM"
-			? "medium"
-			: allowed.reasoningLevel === "LOW"
-				? "low"
-				: undefined;
-
-	return {
-		model,
-		reasoning: reasoningEffort ? { effort: reasoningEffort } : undefined,
-		tools: allowed.search ? [{ type: "web_search" as const }] : undefined,
-	};
-}
+The same `withMetering` and `withCompression` APIs are exported from
+`@usagetap/sdk/anthropic` and `@usagetap/sdk/openrouter`. Remove the wrapper or
+call `.unwrap()` to recover the original provider client.
+
+`withCompression` uses a fast token estimate over the combined request context
+and skips the compression step below 1,000 estimated tokens by default. This
+avoids an extra network round trip when likely savings are small. Override the
+cutoff with `minContextTokens`; set it to `0` to always attempt compression.
+The separate `minTokens` option remains a per-text-segment cutoff.
 
-const completion = await usageTap.withUsage(
-	{
+Wrappers compose. Put metering outside compression so the metered operation
+includes compression and the provider call:
+
+```ts
+const openai = withMetering(
+	withCompression(new OpenAI()),
+	"cust_123",
+);
+```
+
+Each `.unwrap()` removes one layer. Do not also set `promptCompression: true` on
+`withMetering` when using a separate `withCompression` layer.
+
+For advanced entitlement control, `wrapOpenAI` exposes the full UsageTap context
+and applies entitlement-aware defaults when you omit `model`.
+
+```ts
+import { wrapOpenAI } from "@usagetap/sdk/openai";
+
+const ai = wrapOpenAI(openai, usageTap, {
+	defaultContext: {
 		customerId: "cust_123",
 		feature: "chat.send",
 		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
 	},
-	async ({ begin, setUsage }) => {
-		const { model, reasoning, tools } = selectCapabilities(begin.data.allowed);
-
-		const response = await openai.responses.create({
-			model,
-			input: "Draft a welcome email for our Pro plan",
-			reasoning,
-			tools,
-		});
-
-		setUsage({
-			modelUsed: model,
-			inputTokens: response.usage?.input_tokens ?? response.usage?.prompt_tokens ?? 0,
-			cachedInputTokens:
-				response.usage?.prompt_tokens_details?.cached_tokens ??
-				response.usage?.cache_read_input_tokens ??
-				response.usage?.cached_tokens ??
-				0,
-			responseTokens: response.usage?.output_tokens ?? response.usage?.completion_tokens ?? 0,
-			reasoningTokens: reasoning ? response.usage?.reasoning_tokens ?? 0 : 0,
-			searches: tools?.length ? response.usage?.web_search_queries ?? 0 : 0,
-		});
-
-		return response;
+	promptCompression: {
+		provider: "heuristic",
+		roles: { user: true, tool: true },
+		minTokens: 500,
 	},
-);
-
-console.log(completion.output_text);
+});
 ```
 
-If you only need to toggle web search, keep the selected model and conditionally add the tool when UsageTap says it’s allowed:
+### Prompt compression
+
+Prompt compression is an explicit step after `call_begin`. `beginCall` only starts the call and returns the `callId`; `promptCompress` compresses locally, records savings metadata against that call, and returns the compressed prompt for your vendor request. Raw prompt content is not sent to UsageTap.
 
 ```ts
+import { protectPromptText } from "@usagetap/sdk";
+
+const begin = await usageTap.beginCall({
+	customerId: "cust_123",
+	feature: "chat.send",
+});
+
+const compressed = await usageTap.promptCompress({
+	callId: begin.data.callId,
+	input: `Please summarize this long prompt but keep ${protectPromptText("PLAN_ID_PRO_2026")} exact.`,
+});
+
 const response = await openai.responses.create({
-	model: "gpt5",
-	tools: begin.data.allowed.search ? [{ type: "web_search" }] : undefined,
-	input: "What was a positive news story from today?",
+	model: "gpt5-mini",
+	input: compressed.compressedInput as string,
 });
 ```
 
-Prefer a zero-boilerplate integration? Keep scrolling—`wrapOpenAI` applies the same entitlement-aware defaults if you omit `model` from your request.
+The default heuristic is conservative: it normalizes whitespace, preserves fenced code indentation, minifies valid embedded JSON, and converts eligible JSON data blocks to TOON when that is smaller. Pass `provider: "toon"` to force local TOON-style encoding for structured data. Savings include both character counts and approximate token counts using lightweight regex tokenization (`[\p{L}\p{N}]+|[^\s]`), not a model-specific BPE tokenizer. If compression or savings reporting fails, the SDK returns the original input with zero savings so the vendor call can continue.
+
+`wrapOpenAI()` and `wrapAnthropic()` can also compress prompts automatically after `call_begin` and before the vendor request. This is opt-in via `promptCompression`; assistant messages are skipped by default so historical assistant turns are not rewritten. Compression telemetry is aggregated once per UsageTap call, and stats are available on `ai.promptCompression.totalTokensSaved`.
 
 ```ts
-import { wrapOpenAI } from "@usagetap/sdk/openai";
+import Anthropic from "@anthropic-ai/sdk";
+import { wrapAnthropic } from "@usagetap/sdk/anthropic";
 
-const ai = wrapOpenAI(openai, usageTap, {
-	defaultContext: {
-		customerId: "cust_123",
-		feature: "chat.send",
-		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
-	},
-	promptCompression: {
-		provider: "heuristic",
-		roles: { user: true, tool: true },
-		minTokens: 500,
-	},
-});
-```
-
-### Prompt compression
-
-Prompt compression is an explicit step after `call_begin`. `beginCall` only starts the call and returns the `callId`; `promptCompress` compresses locally, records savings metadata against that call, and returns the compressed prompt for your vendor request. Raw prompt content is not sent to UsageTap.
-
-```ts
-import { protectPromptText } from "@usagetap/sdk";
-
-const begin = await usageTap.beginCall({
-	customerId: "cust_123",
-	feature: "chat.send",
-});
-
-const compressed = await usageTap.promptCompress({
-	callId: begin.data.callId,
-	input: `Please summarize this long prompt but keep ${protectPromptText("PLAN_ID_PRO_2026")} exact.`,
-});
-
-const response = await openai.responses.create({
-	model: "gpt5-mini",
-	input: compressed.compressedInput as string,
-});
-```
-
-The default heuristic is conservative: it normalizes whitespace, preserves fenced code indentation, minifies valid embedded JSON, and converts eligible JSON data blocks to TOON when that is smaller. Pass `provider: "toon"` to force local TOON-style encoding for structured data. Savings include both character counts and approximate token counts using lightweight regex tokenization (`[\p{L}\p{N}]+|[^\s]`), not a model-specific BPE tokenizer. If compression or savings reporting fails, the SDK returns the original input with zero savings so the vendor call can continue.
-
-`wrapOpenAI()` and `wrapAnthropic()` can also compress prompts automatically after `call_begin` and before the vendor request. This is opt-in via `promptCompression`; assistant messages are skipped by default so historical assistant turns are not rewritten. Compression telemetry is aggregated once per UsageTap call, and stats are available on `ai.promptCompression.totalTokensSaved`.
-
-```ts
-import Anthropic from "@anthropic-ai/sdk";
-import { wrapAnthropic } from "@usagetap/sdk/anthropic";
-
-const anthropic = wrapAnthropic(
-	new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
-	usageTap,
-	{
-		defaultContext: { customerId: "cust_123", feature: "chat.send" },
-		promptCompression: { roles: { system: true, user: true, tool: true } },
-	},
-);
-
-await anthropic.messages.create({
-	model: "claude-3-5-haiku-latest",
-	max_tokens: 512,
-	system: "Long system prompt",
-	messages: [{ role: "user", content: "Long user prompt" }],
-});
-```
-
-Use `provider: "usagetap"` to compress with UsageTap's hosted endpoints. Manual `promptCompress()` and `compressPromptInput()` use the single-text The Token Company-compatible endpoint at `https://compress.usagetap.com/v1/compress`, where `aggressiveness` is a single number from `0.0` to `1.0`. `wrapOpenAI()` and `wrapAnthropic()` use the message/request endpoint at `https://compress.usagetap.com/v1/messages/compress`, where `aggressiveness` may be a per-role object:
-
-```ts
-const result = await usageTap.promptCompress({
-	callId: begin.data.callId,
-	text: "Your text here",
-	provider: "usagetap",
-	model: "bear-2",
-	aggressiveness: 0.5,
-});
-```
-
-```ts
-const ai = wrapOpenAI(openai, usageTap, {
-		defaultContext: { customerId: "cust_123", feature: "chat.send" },
-		promptCompression: {
-			provider: "usagetap",
-			aggressiveness: { user: 0.5, system: 0.5, tool: 0.5 },
-		},
-	});
-```
-
-`UsageTapClient` sends your UsageTap API key by default. Override `usageTapCompressionEndpoint` for single-text compression or `usageTapCompressionMessagesEndpoint` for wrapper message compression.
-
-When using The Token Company, configure `tokenCompanyApiKey` on `UsageTapClient` and set `provider: "thetokencompany"`. Optional `tokenCompanyModel`, `aggressiveness`, and `tokenCompanyAppId` are supported at the client, manual `promptCompress`, and wrapper levels. Use `protectPromptText()` for text that must be passed through unchanged by compression-compatible providers.
-
-For advanced custom flows, `compressPromptInput(input, options?)` returns compression results without recording telemetry, and `recordPromptCompression({ callId, promptCompression })` records precomputed savings metadata against a call.
-
-> **Heads up:** `UsageTapClient` always negotiates the canonical UsageTap media type by sending `Accept: application/vnd.usagetap.v1+json`. Every response now uses the `{ result, data, correlationId }` envelope exclusively and the begin payload includes `data.idempotency.key` (always matching `callId`), per-meter snapshots, and subscription metadata. Set `autoIdempotency: false` (or pass your own `idempotency`) to skip the SDK's auto-generated key and rely on the server's deterministic fallback when retriable semantics are acceptable.
+const anthropic = wrapAnthropic(
+	new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+	usageTap,
+	{
+		defaultContext: { customerId: "cust_123", feature: "chat.send" },
+		promptCompression: { roles: { system: true, user: true, tool: true } },
+	},
+);
+
+await anthropic.messages.create({
+	model: "claude-3-5-haiku-latest",
+	max_tokens: 512,
+	system: "Long system prompt",
+	messages: [{ role: "user", content: "Long user prompt" }],
+});
+```
+
+Use `provider: "usagetap"` to compress with UsageTap's hosted endpoints. Manual `promptCompress()` and `compressPromptInput()` use the single-text The Token Company-compatible endpoint at `https://compress.usagetap.com/v1/compress`, where `aggressiveness` is a single number from `0.0` to `1.0`. `wrapOpenAI()` and `wrapAnthropic()` use the message/request endpoint at `https://compress.usagetap.com/v1/messages/compress`, where `aggressiveness` may be a per-role object:
+
+```ts
+const result = await usageTap.promptCompress({
+	callId: begin.data.callId,
+	text: "Your text here",
+	provider: "usagetap",
+	model: "bear-2",
+	aggressiveness: 0.5,
+});
+```
+
+```ts
+const ai = wrapOpenAI(openai, usageTap, {
+		defaultContext: { customerId: "cust_123", feature: "chat.send" },
+		promptCompression: {
+			provider: "usagetap",
+			aggressiveness: { user: 0.5, system: 0.5, tool: 0.5 },
+		},
+	});
+```
+
+`UsageTapClient` sends your UsageTap API key by default. Override `usageTapCompressionEndpoint` for single-text compression or `usageTapCompressionMessagesEndpoint` for wrapper message compression.
+
+When using The Token Company, configure `tokenCompanyApiKey` on `UsageTapClient` and set `provider: "thetokencompany"`. Optional `tokenCompanyModel`, `aggressiveness`, and `tokenCompanyAppId` are supported at the client, manual `promptCompress`, and wrapper levels. Use `protectPromptText()` for text that must be passed through unchanged by compression-compatible providers.
+
+For advanced custom flows, `compressPromptInput(input, options?)` returns compression results without recording telemetry, and `recordPromptCompression({ callId, promptCompression })` records precomputed savings metadata against a call.
+
+> **Heads up:** `UsageTapClient` always negotiates the canonical UsageTap media type by sending `Accept: application/vnd.usagetap.v1+json`. Every response now uses the `{ result, data, correlationId }` envelope exclusively and the begin payload includes `data.idempotency.key` (always matching `callId`), per-meter snapshots, and subscription metadata. Set `autoIdempotency: false` (or pass your own `idempotency`) to skip the SDK's auto-generated key and rely on the server's deterministic fallback when retriable semantics are acceptable.
 
 ### Streaming helpers
 
@@ -496,19 +471,19 @@ Key exports from `@usagetap/sdk`:
 - `createCustomer` – idempotently ensure a customer subscription exists before starting a call.
 - `changePlan` – switch a customer to a different usage plan with configurable strategy (immediate reset, prorated, or scheduled).
 - `incrementCustomMeter` – track custom usage metrics beyond standard LLM counters (agent actions, documents, API calls, etc.).
-- `checkUsage` – lightweight method to query current usage status without creating a call session.
-- `promptCompress` / `compressPromptToon` – compress prompt input after `call_begin`, return the compressed payload, and record savings metadata for the call.
-- `protectPromptText` / `protect` – mark exact text spans that compatible compressors should not rewrite.
-- `wrapFetch` – wraps a fetch function to automatically instrument OpenAI API calls (minimal integration).
+- `checkUsage` – lightweight method to query current usage status without creating a call session.
+- `promptCompress` / `compressPromptToon` – compress prompt input after `call_begin`, return the compressed payload, and record savings metadata for the call.
+- `protectPromptText` / `protect` – mark exact text spans that compatible compressors should not rewrite.
+- `wrapFetch` – wraps a fetch function to automatically instrument OpenAI API calls (minimal integration).
 - `createIdempotencyKey` – helper for generating UsageTap-compatible idempotency keys.
 - Type definitions for canonical UsageTap request/response payloads.
 
-Optional subpaths:
-
-- `@usagetap/sdk/openai` – `wrapOpenAI`, `createOpenAIAdapter`, `streamOpenAIRoute`, `toNextResponse`, `pipeToResponse`, and related types.
-- `@usagetap/sdk/anthropic` – `wrapAnthropic` and related prompt compression types.
-- `@usagetap/sdk/express` – `withUsage`, `withUsageMiddleware`, and corresponding Express request types.
-- `@usagetap/sdk/react` – `useChatWithUsage` and supporting types for building chat interfaces.
+Optional subpaths:
+
+- `@usagetap/sdk/openai` – `wrapOpenAI`, `createOpenAIAdapter`, `streamOpenAIRoute`, `toNextResponse`, `pipeToResponse`, and related types.
+- `@usagetap/sdk/anthropic` – `wrapAnthropic` and related prompt compression types.
+- `@usagetap/sdk/express` – `withUsage`, `withUsageMiddleware`, and corresponding Express request types.
+- `@usagetap/sdk/react` – `useChatWithUsage` and supporting types for building chat interfaces.
 
 All helpers are designed for server runtimes. Use `UsageTapClient` with `allowBrowser: true` only for sandbox/test scenarios.
 
@@ -669,18 +644,18 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
       "search": true,
 			"reasoningLevel": "MEDIUM"
 		},
-		"entitlementHints": {
-			"suggestedModelTier": "standard",
-			"reasoningLevel": "MEDIUM",
-			"policy": "DOWNGRADE",
-			"downgrade": {
-				"reason": "PREMIUM_QUOTA_EXHAUSTED",
-				"fallbackTier": "standard"
-			}
-		},
-		"meters": {
-			"standardCalls": {
-				"remaining": 12,
+		"entitlementHints": {
+			"suggestedModelTier": "standard",
+			"reasoningLevel": "MEDIUM",
+			"policy": "DOWNGRADE",
+			"downgrade": {
+				"reason": "PREMIUM_QUOTA_EXHAUSTED",
+				"fallbackTier": "standard"
+			}
+		},
+		"meters": {
+			"standardCalls": {
+				"remaining": 12,
 				"limit": 20,
 				"used": 8,
 				"unlimited": false,
@@ -731,8 +706,8 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
 
 `UsageTapClient` exposes the normalized structure via `UsageTapSuccessResponse<BeginCallResponseBody>`. In addition to the flattened `allowed` map, the begin response now ships richer metadata:
 
-- `entitlementHints` summarises the recommended model tier and downgrade rationale based on the active policy.
-- `meters` is a per-counter snapshot including remaining quotas, total limits, usage to date, and convenience ratios. `remainingRatios` mirrors the same information in a compact map for quick lookups.
+- `entitlementHints` summarises the recommended model tier and downgrade rationale based on the active policy.
+- `meters` is a per-counter snapshot including remaining quotas, total limits, usage to date, and convenience ratios. `remainingRatios` mirrors the same information in a compact map for quick lookups.
 - `subscription` contains the active plan identity, versioning, and upcoming replenishment timestamps so you can render customer-facing UI without querying Dynamo yourself.
 - `models` surfaces per-organization vendor hints (e.g. standard vs. premium model shortlists).
 - `idempotency` reveals the actual key that was persisted (`callId` mirrors this value). When you omit `idempotency` in the request, the backend derives a deterministic hash from organization, customer, feature, and requested entitlements.
@@ -757,48 +732,48 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
       "responseTokens": 288,
       "reasoningTokens": 0
     },
-    "metered": {
-      "tokens": 768,
-      "calls": 1,
-      "searches": 1
-    },
-    "spendVelocity": {
-      "currency": "USD",
-      "source": "usage_aggregate",
-      "generatedAt": "2025-10-04T18:21:52.103Z",
-      "customerId": "cust_123",
-      "currentCallCostUsd": 0,
-      "windows": {
-        "hour": {
-          "bucket": "2025-10-04T18",
-          "windowMinutes": 60,
-          "startedAt": "2025-10-04T18:00:00.000Z",
-          "endedAt": "2025-10-04T18:21:52.103Z",
-          "completedCostUsd": 8.75,
-          "completedCalls": 24
-        },
-        "day": {
-          "bucket": "2025-10-04",
-          "windowMinutes": 1440,
-          "startedAt": "2025-10-04T00:00:00.000Z",
-          "endedAt": "2025-10-04T18:21:52.103Z",
-          "completedCostUsd": 42.1,
-          "completedCalls": 140
-        }
-      }
-    }
-  },
-  "correlationId": "corr_abc123"
-}
+    "metered": {
+      "tokens": 768,
+      "calls": 1,
+      "searches": 1
+    },
+    "spendVelocity": {
+      "currency": "USD",
+      "source": "usage_aggregate",
+      "generatedAt": "2025-10-04T18:21:52.103Z",
+      "customerId": "cust_123",
+      "currentCallCostUsd": 0,
+      "windows": {
+        "hour": {
+          "bucket": "2025-10-04T18",
+          "windowMinutes": 60,
+          "startedAt": "2025-10-04T18:00:00.000Z",
+          "endedAt": "2025-10-04T18:21:52.103Z",
+          "completedCostUsd": 8.75,
+          "completedCalls": 24
+        },
+        "day": {
+          "bucket": "2025-10-04",
+          "windowMinutes": 1440,
+          "startedAt": "2025-10-04T00:00:00.000Z",
+          "endedAt": "2025-10-04T18:21:52.103Z",
+          "completedCostUsd": 42.1,
+          "completedCalls": 140
+        }
+      }
+    }
+  },
+  "correlationId": "corr_abc123"
+}
 ```
 
 Send `cachedInputTokens` when available so UsageTap can apply provider cache-read pricing correctly.
 
-`metered` is derived from the raw Dynamo deltas. Additional meters (audio seconds, reasoning tokens, balances) will populate in later phases without breaking the contract.
-
-`spendVelocity` is aggregate-backed current UTC hour/day telemetry. UsageTap does not enforce limits from this section; `currentCallCostUsd` is included separately because aggregate updates are asynchronous.
-
-### Premium detection and override
+`metered` is derived from the raw Dynamo deltas. Additional meters (audio seconds, reasoning tokens, balances) will populate in later phases without breaking the contract.
+
+`spendVelocity` is aggregate-backed current UTC hour/day telemetry. UsageTap does not enforce limits from this section; `currentCallCostUsd` is included separately because aggregate updates are asynchronous.
+
+### Premium detection and override
 
 UsageTap automatically determines whether a call is premium based on the model's output token pricing:
 - If the output token price exceeds **$4.00 per million tokens**, the call is classified as premium