@usagetap/sdk 1.3.1 → 1.3.2

package/README.md

@@ -1,67 +1,67 @@
-# @usagetap/sdk
-
-Server-only JavaScript/TypeScript client for UsageTap. The SDK helps you instrument `call_begin → vendor call → call_end` flows with built-in retries, idempotency helpers, and vendor adapters.
-
-## Module formats
-
-`@usagetap/sdk` ships real dual ESM (`.mjs`) and CommonJS (`.cjs`) entrypoints. In ESM projects use `import { UsageTapClient } from "@usagetap/sdk";`. For CommonJS runtimes (including VS Code extensions) rely on `const { UsageTapClient } = require("@usagetap/sdk");`.
-
-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/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.
-
-```bash
-npm install @usagetap/sdk openai
-```
-
-Wrap the provider client you already use. `USAGETAP_API_KEY` and the production
-UsageTap URL are read automatically:
-
-```ts
-import OpenAI from "openai";
-import { withMetering } from "@usagetap/sdk/openai";
-
-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",
-});
-
-console.log(completion.output_text);
-```
-
-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";
-
+# @usagetap/sdk
+
+Server-only JavaScript/TypeScript client for UsageTap. The SDK helps you instrument `call_begin → vendor call → call_end` flows with built-in retries, idempotency helpers, and vendor adapters.
+
+## Module formats
+
+`@usagetap/sdk` ships real dual ESM (`.mjs`) and CommonJS (`.cjs`) entrypoints. In ESM projects use `import { UsageTapClient } from "@usagetap/sdk";`. For CommonJS runtimes (including VS Code extensions) rely on `const { UsageTapClient } = require("@usagetap/sdk");`.
+
+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/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.
+
+```bash
+npm install @usagetap/sdk openai
+```
+
+Wrap the provider client you already use. `USAGETAP_API_KEY` and the production
+UsageTap URL are read automatically:
+
+```ts
+import OpenAI from "openai";
+import { withMetering } from "@usagetap/sdk/openai";
+
+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",
+});
+
+console.log(completion.output_text);
+```
+
+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,
-});
-```
-
+const completion = await openai.responses.create({
+	model: "gpt-5.5-mini",
+	input: longPrompt,
+});
+```
+
 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.
@@ -71,798 +71,798 @@ 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.
-
-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" },
-	},
-	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.
-
-### Streaming helpers
-
-`wrapOpenAI` automatically instruments streaming responses. You can feed the wrapped stream directly into Next.js or an Express response using the exported helpers:
-
-```ts
-import { toNextResponse } from "@usagetap/sdk/openai";
-
-export async function POST() {
-	const stream = await ai.chat.completions.create(
-		{
-			messages: [{ role: "user", content: "Stream it" }],
-			stream: true,
-		},
-		{
-			usageTap: {
-				requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
-			},
-		},
-	);
-
-	return toNextResponse(stream, { mode: "text" });
-}
-```
-
-`wrapOpenAI` inspects `begin.data.vendorHints.preferredModel`: premium entitlements resolve to `gpt5`, otherwise the wrapper falls back to `gpt5-mini`. Use the manual pattern shown earlier when you need to toggle reasoning effort or attach search tools based on the returned allowances.
-
-### Overriding usage context per request
-
-You can override the UsageTap begin payload on a per-call basis via the `usageTap` option:
-
-```ts
-await ai.chat.completions.create(
-	{ messages },
-	{
-		usageTap: {
-			customerId: currentUser.id,
-			feature: "chat.assist",
-			tags: ["beta"],
-			requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
-		},
-	},
-);
-```
-
-The begin response for that call will promote premium plans to `gpt5`, fall back to `gpt5-mini` otherwise, and cap reasoning to the granted tier.
-
-For streaming calls created with `{ stream: true }`, UsageTap automatically calculates usage from the final OpenAI response (or falls back to estimates when available). The wrapped stream retains OpenAI-specific helpers like `finalChatCompletion()`.
-
-### responses.create support
-
-The wrapper also instruments `openai.responses.create`, applying vendor hints (preferred models, token limits) and collecting usage data the same way as chat completions.
-
-### OpenRouter support
-
-`wrapOpenAI` works seamlessly with OpenRouter since it uses an OpenAI-compatible API. Just point the base URL to OpenRouter:
-
-```ts
-import OpenAI from "openai";
-import { UsageTapClient } from "@usagetap/sdk";
-import { wrapOpenAI } from "@usagetap/sdk/openai";
-
-const usageTap = new UsageTapClient({
-	apiKey: process.env.USAGETAP_API_KEY!,
-	baseUrl: process.env.USAGETAP_BASE_URL!,
-});
-
-const openrouter = new OpenAI({
-	baseURL: "https://openrouter.ai/api/v1",
-	apiKey: process.env.OPENROUTER_API_KEY!,
-});
-
-const ai = wrapOpenAI(openrouter, usageTap, {
-	defaultContext: {
-		customerId: "cust_123",
-		feature: "chat.send",
-		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
-	},
-});
-
-const completion = await ai.chat.completions.create(
-	{
-		messages: [{ role: "user", content: "Hello from OpenRouter!" }],
-	},
-	{
-		usageTap: {
-			requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
-		},
-	},
-);
-```
-
-`begin.data.models` will surface the OpenRouter-specific identifiers the customer can use (for example, `standard` ⇒ `gpt5-mini`, `premium` ⇒ `gpt5`). Since `wrapOpenAI` honors those hints, you can omit `model` and let UsageTap keep the request aligned with the active entitlement.
-
-### Express middleware
-
-For Express applications, use the `withUsage` middleware to attach UsageTap context to requests:
-
-```ts
-import express from "express";
-import OpenAI from "openai";
-import { UsageTapClient } from "@usagetap/sdk";
-import { withUsage } from "@usagetap/sdk/express";
-
-const app = express();
-const usageTap = new UsageTapClient({
-	apiKey: process.env.USAGETAP_API_KEY!,
-	baseUrl: process.env.USAGETAP_BASE_URL!,
-});
-
-// Extract customer ID from your auth system
-app.use(withUsage(usageTap, (req) => req.user.id));
-
-app.post("/api/chat", async (req, res) => {
-	const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
-	const ai = req.usageTap!.openai(openai, {
-		feature: "chat.assistant",
-		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
-	});
-	
-	const stream = await ai.chat.completions.create(
-		{
-			messages: req.body.messages,
-			stream: true,
-		},
-		{
-			usageTap: {
-				requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
-			},
-		},
-	);
-	
-	// Pipes stream to response and finalizes usage
-	req.usageTap!.pipeToResponse(stream, res);
-});
-```
-
-With that context in place, premium calls receive `gpt5` and everyone else falls back to `gpt5-mini`. To respect `allowed.reasoningLevel` or `allowed.search`, read the begin payload inside route handlers (see the manual `withUsage` example above) and shape the OpenAI request accordingly.
-
-### React hook for chat UIs
-
-Build chat interfaces with automatic UsageTap tracking:
-
-```tsx
-import { useChatWithUsage } from "@usagetap/sdk/react";
-
-function ChatComponent({ userId }) {
-	const { messages, input, setInput, handleSubmit, isLoading } = useChatWithUsage({
-		api: "/api/chat",
-		customerId: userId,
-		feature: "chat.assistant",
-	});
-	
-	return (
-		<div>
-			{messages.map((m) => (
-				<div key={m.id}>
-					<strong>{m.role}:</strong> {m.content}
-				</div>
-			))}
-			<form onSubmit={handleSubmit}>
-				<input
-					value={input}
-					onChange={(e) => setInput(e.target.value)}
-					disabled={isLoading}
-				/>
-				<button type="submit" disabled={isLoading}>
-					Send
-				</button>
-			</form>
-		</div>
-	);
-}
-```
-
-The hook works with server routes that use UsageTap SDK (see `streamOpenAIRoute` above).
-
-### wrapFetch: minimal integration
-
-For the smallest possible integration, use `wrapFetch` to wrap the `fetch` function passed to the OpenAI SDK. This requires zero changes to your OpenAI code:
-
-```ts
-import OpenAI from "openai";
-import { UsageTapClient, wrapFetch } from "@usagetap/sdk";
-
-const usageTap = new UsageTapClient({
-	apiKey: process.env.USAGETAP_API_KEY!,
-	baseUrl: process.env.USAGETAP_BASE_URL!,
-});
-
-const wrappedFetch = wrapFetch(usageTap, {
-	defaultContext: {
-		customerId: "cust_123",
-		feature: "chat",
-		requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
-	},
-});
-
-const openai = new OpenAI({
-	apiKey: process.env.OPENAI_API_KEY!,
-	fetch: wrappedFetch,
-});
-
-// Reuse the selectCapabilities helper shown above to map entitlements to models
-// Pull the entitlements you cached after call_begin and pick the right tier
-const { model } = selectCapabilities(session.entitlements.allowed);
-
-const completion = await openai.chat.completions.create({
-	model,
-	messages: [{ role: "user", content: "Hello!" }],
-});
-```
-
-`wrapFetch` detects OpenAI API endpoints, handles streaming and non-streaming responses, and automatically extracts usage data. Persist the `begin.data.allowed` blob wherever you store session context so every downstream `openai` call can resolve to `gpt5` (premium) or `gpt5-mini` (standard). You can override context per-request using special headers:
-
-```ts
-await openai.chat.completions.create(
-	{ messages: [{ role: "user", content: "Hello!" }] },
-	{
-		headers: {
-			"x-usagetap-customer-id": currentUser.id,
-			"x-usagetap-feature": "chat.premium",
-		},
-	},
-);
-```
-
-### Unified `/call` endpoint (API-only)
-
-Need a single round-trip without the SDK? The public REST API exposes `POST /call`, which wraps `call_begin`, an optional vendor invocation, and `call_end` into one atomic request. Supply your usual begin payload plus an optional `vendor` block containing the URL, headers, and body to execute. UsageTap merges usage metrics from the vendor response with any explicit overrides before finalizing the call.
-
-```ts
-async function getEntitlementsFor(customerId: string) {
-	// Call begin upfront or reuse a cached begin payload for this customer + feature
-	return sessionStore.read(customerId); // pseudo-code: use your own persistence layer
-}
-
-const entitlements = await getEntitlementsFor("cust_123"); // stash begin.data.allowed somewhere durable
-const { model } = selectCapabilities(entitlements.allowed);
-
-const response = await fetch(`${baseUrl}/call`, {
-	method: "POST",
-	headers: {
-		Authorization: `Bearer ${process.env.USAGETAP_API_KEY}`,
-		Accept: "application/vnd.usagetap.v1+json",
-		"Content-Type": "application/json",
-	},
-	body: JSON.stringify({
-		customerId: "cust_123",
-		requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
-		feature: "chat.completions",
-		idempotency: crypto.randomUUID(),
-		vendor: {
-			url: "https://api.openai.com/v1/chat/completions",
-			method: "POST",
-			headers: {
-				Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
-				"Content-Type": "application/json",
-			},
-			body: {
-				model,
-				messages: [{ role: "user", content: "Hello" }],
-			},
-			responseType: "json",
-		},
-		usage: { modelUsed: model },
-	}),
-});
-
-const envelope = await response.json();
-if (!response.ok || envelope.result.status !== "ACCEPTED") {
-	throw new Error(`UsageTap /call failed: ${envelope.result.code}`);
-}
-
-const { begin, end, vendor, endUsage } = envelope.data;
-```
-
-- When the `vendor` block is omitted, `/call` simply runs begin → end using the provided `usage` overrides.
-- Non-2xx vendor responses still trigger `call_end`; the envelope returns `CALL_VENDOR_WARNING` alongside vendor error metadata.
-- The canonical media type `application/vnd.usagetap.v1+json` is required; the SDK already sends this header automatically when you rely on `UsageTapClient`.
-
-## Exports
-
-Key exports from `@usagetap/sdk`:
-
-- `UsageTapClient` – minimal HTTP client for `createCustomer`, `changePlan`, `incrementCustomMeter`, `call_begin`, `call_end`, and `checkUsage`.
-- `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).
-- `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.
-
-All helpers are designed for server runtimes. Use `UsageTapClient` with `allowBrowser: true` only for sandbox/test scenarios.
-
-### Ensure a customer subscription exists
-
-Run `createCustomer` before you invoke `call_begin` (or higher-level helpers) to guarantee the customer has an active subscription. The endpoint is fully idempotent—repeat calls return the existing snapshot and set `newCustomer: false`:
-
-```ts
-const snapshot = await usageTap.createCustomer({
-	customerId: "cust_123",
-	customerFriendlyName: "Acme AI",
-	customerEmail: "billing@acme.ai",
-	stripeCustomerId: "cus_123",
-});
-
-console.log("New customer?", snapshot.data.newCustomer);
-console.log("Plan:", snapshot.data.plan);
-console.log("Allowed entitlements:", snapshot.data.allowed);
-```
-
-`customerFriendlyName` (aka `customerName`) and `customerEmail` are **HIGHLY IMPORTANT BUT OPTIONAL**: they populate the customer profile on first creation and are safe to omit if you truly do not have them yet.
-
-This returns the same rich subscription snapshot surfaces by `call_begin` and `checkUsage`, making it safe to cache the response for onboarding flows. Pass `idempotencyKey` in `CreateCustomerOptions` when you need deterministic keys across services; otherwise the client auto-generates one by default. Both `idempotencyKey` (preferred) and `idempotency` (deprecated) are supported.
-
-### Change a customer's plan
-
-Use `changePlan` to switch a customer to a different usage plan. You can control how the change is applied with the `strategy` option:
-
-```ts
-const result = await usageTap.changePlan({
-	customerId: "cust_123",
-	planId: "plan_premium_v2",
-	strategy: "IMMEDIATE_RESET", // or "IMMEDIATE_PRORATED" or "AT_NEXT_REPLENISH"
-});
-
-console.log("Plan changed:", result.data.success);
-console.log("New subscription:", result.data.subscription);
-```
-
-**Strategy options:**
-- `IMMEDIATE_RESET`: Switch plan immediately and reset all usage counters to zero
-- `IMMEDIATE_PRORATED`: Switch plan immediately and prorate existing usage against new limits
-- `AT_NEXT_REPLENISH`: Schedule the plan change for the next replenishment cycle (default)
-
-The response includes the updated subscription details, including the new plan version, limits, and next replenishment timestamp. If `strategy: "AT_NEXT_REPLENISH"` is used, the `subscription.pending` field will indicate the scheduled plan change.
-
-### Check usage without creating a call
-
-When you need to display current quota status, plan details, or remaining balances without tracking a vendor call, use `checkUsage()`:
-
-```ts
-const usageStatus = await usageTap.checkUsage({ customerId: "cust_123" });
-
-console.log("Meters:", usageStatus.data.meters);
-console.log("Allowed:", usageStatus.data.allowed);
-console.log("Plan:", usageStatus.data.plan);
-console.log("Balances:", usageStatus.data.balances);
-```
-
-This returns the same rich usage snapshot as `call_begin` (meters, entitlements, subscription details, plan info, balances) but without creating a call record. Use this for dashboard widgets, pre-flight checks, or displaying quota status to users.
-
-### Increment custom meters
-
-Custom meters allow you to track usage beyond standard LLM metrics—ideal for agent actions, document processing, API calls, or any custom usage you need to meter.
-
-```ts
-const result = await usageTap.incrementCustomMeter({
-	customerId: "cust_123",
-	meterSlot: "CUSTOM1",  // or "CUSTOM2"
-	amount: 5,
-	feature: "agent_actions",
-	tags: ["workflow_automation"],
-	metadata: {
-		workflowId: "wf_abc123",
-		actionType: "email_send",
-	},
-});
-
-console.log("Event recorded:", result.data.eventId);
-console.log("Remaining quota:", result.data.meter.remaining);
-console.log("Blocked:", result.data.blocked);
-```
-
-**Parameters:**
-
-- `customerId` (string, required): Customer identifier
-- `meterSlot` ("CUSTOM1" | "CUSTOM2", required): Which custom meter to increment
-- `amount` (number, required): Positive number to decrement from quota
-- `feature` (string, optional): Feature identifier for tracking
-- `tags` (string[], optional): Tags for categorization  
-- `metadata` (object, optional): Additional metadata
-
-The method returns the updated meter snapshot showing remaining quota, limits, and usage. If the customer's plan has `limitType: "BLOCK"` and quota is exceeded, a `UsageTapError` is thrown with code `USAGETAP_AUTH_ERROR`.
-
-**Use cases:**
-
-```ts
-// Track agent tool invocations
-await usageTap.incrementCustomMeter({
-	customerId: "cust_123",
-	meterSlot: "CUSTOM1",
-	amount: 1,
-	feature: "agent.tool_call",
-	tags: ["web_search"],
-});
-
-// Track document processing (10 pages)
-await usageTap.incrementCustomMeter({
-	customerId: "cust_456",
-	meterSlot: "CUSTOM2",
-	amount: 10,
-	feature: "document.ocr",
-	metadata: { documentId: "doc_789", pages: 10 },
-});
-
-// Track external API calls
-await usageTap.incrementCustomMeter({
-	customerId: "cust_789",
-	meterSlot: "CUSTOM1",
-	amount: 1,
-	feature: "external_api.maps",
-	tags: ["geocoding"],
-});
-```
-
-**Important notes:**
-
-1. Custom meters must be enabled in the customer's usage plan
-2. The `amount` decrements the remaining quota (like token usage)
-3. With `BLOCK` policy, exceeding quota throws an error
-4. With `DOWNGRADE` policy, usage continues but quota can go negative
-5. Unlimited meters don't track usage but still record events for analytics
-
-## Response envelope (canonical only)
-
-UsageTap responds exclusively with the canonical `{ result, data, correlationId }` envelope for every endpoint. The SDK automatically sends `Accept: application/vnd.usagetap.v1+json`, parses the envelope, and returns strongly typed data structures. Transitional `raw` payloads and the `normalize*` helpers have been removed—`response.data` already contains the canonical shape you should persist or render.
-
-### Example `call_begin` success
-
-```json
-{
-  "result": {
-    "status": "ACCEPTED",
-    "code": "CALL_BEGIN_SUCCESS",
-    "timestamp": "2025-10-04T18:21:37.482Z"
-  },
-  "data": {
-    "callId": "call_123",
-    "startTime": "2025-10-04T18:21:37.482Z",
-		"policy": "DOWNGRADE",
-    "newCustomer": false,
-    "canceled": false,
-    "allowed": {
-      "standard": true,
-      "premium": true,
-      "audio": false,
-      "image": false,
-      "search": true,
-			"reasoningLevel": "MEDIUM"
-		},
-		"entitlementHints": {
-			"suggestedModelTier": "standard",
-			"reasoningLevel": "MEDIUM",
-			"policy": "DOWNGRADE",
-			"downgrade": {
-				"reason": "PREMIUM_QUOTA_EXHAUSTED",
-				"fallbackTier": "standard"
-			}
-		},
-		"meters": {
-			"standardCalls": {
-				"remaining": 12,
-				"limit": 20,
-				"used": 8,
-				"unlimited": false,
-				"ratio": 0.6
-			},
-			"premiumCalls": {
-				"remaining": 0,
-				"limit": null,
-				"used": 0,
-				"unlimited": true,
-				"ratio": null
-			},
-			"standardTokens": {
-				"remaining": 800,
-				"limit": 1000,
-				"used": 200,
-				"unlimited": false,
-				"ratio": 0.8
-			}
-		},
-		"remainingRatios": {
-			"standardCalls": 0.6,
-			"standardTokens": 0.8
-		},
-		"subscription": {
-			"id": "sub_123",
-			"usagePlanVersionId": "plan_2025_01",
-			"planName": "Pro",
-			"planVersion": "2025-01",
-			"limitType": "DOWNGRADE",
-			"reasoningLevel": "MEDIUM",
-			"lastReplenishedAt": "2025-10-04T00:00:00.000Z",
-			"nextReplenishAt": "2025-11-04T00:00:00.000Z",
-			"subscriptionVersion": 14
-		},
-		"models": {
-			"standard": ["gpt5-mini"],
-			"premium": ["gpt5"]
-		},
-		"idempotency": {
-			"key": "call_123",
-			"source": "derived"
-		}
-  },
-  "correlationId": "corr_abc123"
-}
-```
-
-`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.
-- `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.
-- `plan` and `balances` remain available alongside the core begin payload for backwards compatibility with earlier SDK versions.
-
-### Example `call_end` success
-
-```json
-{
-  "result": {
-    "status": "ACCEPTED",
-    "code": "CALL_END_SUCCESS",
-    "timestamp": "2025-10-04T18:21:52.103Z"
-  },
-  "data": {
-    "callId": "call_123",
-    "costUSD": 0,
-    "usage": {
-      "inputTokens": 600,
-      "cachedInputTokens": 120,
-      "billableInputTokens": 480,
-      "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"
-}
-```
-
-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
-
-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
-- Otherwise, it's classified as standard
-
-You can explicitly override this detection by passing `isPremium` in your `call_end` request:
-
-```ts
-await usageTap.endCall({
-  callId: begin.data.callId,
-  modelUsed: "custom-model-v2",
-  inputTokens: 100,
-  responseTokens: 200,
-  isPremium: true,  // Explicitly mark this as a premium call
-});
-```
-
-This is useful when:
-- You're using custom models that aren't in UsageTap's pricing database
-- You want to enforce specific billing tiers regardless of pricing
-- You're implementing your own tier classification logic
-
-### Batch pricing
-
-Batch mode applies a **50% discount** to standard pricing rates. Set `batch: true` or `pricingMode: "batch"` on either `call_begin` or `call_end`.
-
-When set on `call_begin`, the pricing mode carries through to `call_end` automatically. Setting it on `call_end` overrides the `call_begin` value.
-
-```ts
-// Option 1: Set on call_begin (carries through)
-const begin = await usageTap.beginCall({
-  customerId: "cust_123",
-  batch: true,
-  pricingMode: "batch",
-});
-
-// Option 2: Set on call_end (overrides call_begin)
-await usageTap.endCall({
-  callId: begin.data.callId,
-  modelUsed: "gpt-4o",
-  inputTokens: 100,
-  responseTokens: 200,
-  batch: true,
-  pricingMode: "batch",
-});
-```
-
-Both `batch` and `pricingMode` are echoed in the responses from `call_begin` and `call_end`.
-
-### Raw fetch integrations
-
-Prefer `UsageTapClient` whenever possible—it handles retries, headers, and idempotency for you. If you still need to work with `fetch` directly, remember to request the canonical media type and consume the envelope shape directly:
-
-```ts
-import type { BeginCallResponseBody, EndCallResponseBody } from "@usagetap/sdk";
-
-const beginResponse = await fetch(`${baseUrl}/call_begin`, {
-	method: "POST",
-	headers: {
-		Authorization: `Bearer ${apiKey}`,
-		Accept: "application/vnd.usagetap.v1+json",
-		"Content-Type": "application/json",
-	},
-	body: JSON.stringify(payload),
-}).then((r) => r.json());
-
-if (beginResponse.result.status !== "ACCEPTED") {
-	throw new Error(`call_begin failed: ${beginResponse.result.code}`);
-}
-
-const begin = beginResponse.data as BeginCallResponseBody;
-
-// ...later, when closing the call
-
-const endResponse = await fetch(`${baseUrl}/call_end`, {
-	method: "POST",
-	headers: {
-		Authorization: `Bearer ${apiKey}`,
-		Accept: "application/vnd.usagetap.v1+json",
-		"Content-Type": "application/json",
-	},
-	body: JSON.stringify({ callId: begin.callId }),
-}).then((r) => r.json());
-
-if (endResponse.result.status !== "ACCEPTED") {
-	throw new Error(`call_end failed: ${endResponse.result.code}`);
-}
-
-const end = endResponse.data as EndCallResponseBody;
-```
-
-The canonical payloads (`BeginCallResponseBody`, `EndCallResponseBody`, etc.) now match the envelope exactly, keeping SDK and raw integrations aligned without extra helper utilities.
+
+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" },
+	},
+	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.
+
+### Streaming helpers
+
+`wrapOpenAI` automatically instruments streaming responses. You can feed the wrapped stream directly into Next.js or an Express response using the exported helpers:
+
+```ts
+import { toNextResponse } from "@usagetap/sdk/openai";
+
+export async function POST() {
+	const stream = await ai.chat.completions.create(
+		{
+			messages: [{ role: "user", content: "Stream it" }],
+			stream: true,
+		},
+		{
+			usageTap: {
+				requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
+			},
+		},
+	);
+
+	return toNextResponse(stream, { mode: "text" });
+}
+```
+
+`wrapOpenAI` inspects `begin.data.vendorHints.preferredModel`: premium entitlements resolve to `gpt5`, otherwise the wrapper falls back to `gpt5-mini`. Use the manual pattern shown earlier when you need to toggle reasoning effort or attach search tools based on the returned allowances.
+
+### Overriding usage context per request
+
+You can override the UsageTap begin payload on a per-call basis via the `usageTap` option:
+
+```ts
+await ai.chat.completions.create(
+	{ messages },
+	{
+		usageTap: {
+			customerId: currentUser.id,
+			feature: "chat.assist",
+			tags: ["beta"],
+			requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
+		},
+	},
+);
+```
+
+The begin response for that call will promote premium plans to `gpt5`, fall back to `gpt5-mini` otherwise, and cap reasoning to the granted tier.
+
+For streaming calls created with `{ stream: true }`, UsageTap automatically calculates usage from the final OpenAI response (or falls back to estimates when available). The wrapped stream retains OpenAI-specific helpers like `finalChatCompletion()`.
+
+### responses.create support
+
+The wrapper also instruments `openai.responses.create`, applying vendor hints (preferred models, token limits) and collecting usage data the same way as chat completions.
+
+### OpenRouter support
+
+`wrapOpenAI` works seamlessly with OpenRouter since it uses an OpenAI-compatible API. Just point the base URL to OpenRouter:
+
+```ts
+import OpenAI from "openai";
+import { UsageTapClient } from "@usagetap/sdk";
+import { wrapOpenAI } from "@usagetap/sdk/openai";
+
+const usageTap = new UsageTapClient({
+	apiKey: process.env.USAGETAP_API_KEY!,
+	baseUrl: process.env.USAGETAP_BASE_URL!,
+});
+
+const openrouter = new OpenAI({
+	baseURL: "https://openrouter.ai/api/v1",
+	apiKey: process.env.OPENROUTER_API_KEY!,
+});
+
+const ai = wrapOpenAI(openrouter, usageTap, {
+	defaultContext: {
+		customerId: "cust_123",
+		feature: "chat.send",
+		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
+	},
+});
+
+const completion = await ai.chat.completions.create(
+	{
+		messages: [{ role: "user", content: "Hello from OpenRouter!" }],
+	},
+	{
+		usageTap: {
+			requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
+		},
+	},
+);
+```
+
+`begin.data.models` will surface the OpenRouter-specific identifiers the customer can use (for example, `standard` ⇒ `gpt5-mini`, `premium` ⇒ `gpt5`). Since `wrapOpenAI` honors those hints, you can omit `model` and let UsageTap keep the request aligned with the active entitlement.
+
+### Express middleware
+
+For Express applications, use the `withUsage` middleware to attach UsageTap context to requests:
+
+```ts
+import express from "express";
+import OpenAI from "openai";
+import { UsageTapClient } from "@usagetap/sdk";
+import { withUsage } from "@usagetap/sdk/express";
+
+const app = express();
+const usageTap = new UsageTapClient({
+	apiKey: process.env.USAGETAP_API_KEY!,
+	baseUrl: process.env.USAGETAP_BASE_URL!,
+});
+
+// Extract customer ID from your auth system
+app.use(withUsage(usageTap, (req) => req.user.id));
+
+app.post("/api/chat", async (req, res) => {
+	const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
+	const ai = req.usageTap!.openai(openai, {
+		feature: "chat.assistant",
+		requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
+	});
+	
+	const stream = await ai.chat.completions.create(
+		{
+			messages: req.body.messages,
+			stream: true,
+		},
+		{
+			usageTap: {
+				requested: { standard: true, premium: true, search: true, reasoningLevel: "HIGH" },
+			},
+		},
+	);
+	
+	// Pipes stream to response and finalizes usage
+	req.usageTap!.pipeToResponse(stream, res);
+});
+```
+
+With that context in place, premium calls receive `gpt5` and everyone else falls back to `gpt5-mini`. To respect `allowed.reasoningLevel` or `allowed.search`, read the begin payload inside route handlers (see the manual `withUsage` example above) and shape the OpenAI request accordingly.
+
+### React hook for chat UIs
+
+Build chat interfaces with automatic UsageTap tracking:
+
+```tsx
+import { useChatWithUsage } from "@usagetap/sdk/react";
+
+function ChatComponent({ userId }) {
+	const { messages, input, setInput, handleSubmit, isLoading } = useChatWithUsage({
+		api: "/api/chat",
+		customerId: userId,
+		feature: "chat.assistant",
+	});
+	
+	return (
+		<div>
+			{messages.map((m) => (
+				<div key={m.id}>
+					<strong>{m.role}:</strong> {m.content}
+				</div>
+			))}
+			<form onSubmit={handleSubmit}>
+				<input
+					value={input}
+					onChange={(e) => setInput(e.target.value)}
+					disabled={isLoading}
+				/>
+				<button type="submit" disabled={isLoading}>
+					Send
+				</button>
+			</form>
+		</div>
+	);
+}
+```
+
+The hook works with server routes that use UsageTap SDK (see `streamOpenAIRoute` above).
+
+### wrapFetch: minimal integration
+
+For the smallest possible integration, use `wrapFetch` to wrap the `fetch` function passed to the OpenAI SDK. This requires zero changes to your OpenAI code:
+
+```ts
+import OpenAI from "openai";
+import { UsageTapClient, wrapFetch } from "@usagetap/sdk";
+
+const usageTap = new UsageTapClient({
+	apiKey: process.env.USAGETAP_API_KEY!,
+	baseUrl: process.env.USAGETAP_BASE_URL!,
+});
+
+const wrappedFetch = wrapFetch(usageTap, {
+	defaultContext: {
+		customerId: "cust_123",
+		feature: "chat",
+		requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
+	},
+});
+
+const openai = new OpenAI({
+	apiKey: process.env.OPENAI_API_KEY!,
+	fetch: wrappedFetch,
+});
+
+// Reuse the selectCapabilities helper shown above to map entitlements to models
+// Pull the entitlements you cached after call_begin and pick the right tier
+const { model } = selectCapabilities(session.entitlements.allowed);
+
+const completion = await openai.chat.completions.create({
+	model,
+	messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+`wrapFetch` detects OpenAI API endpoints, handles streaming and non-streaming responses, and automatically extracts usage data. Persist the `begin.data.allowed` blob wherever you store session context so every downstream `openai` call can resolve to `gpt5` (premium) or `gpt5-mini` (standard). You can override context per-request using special headers:
+
+```ts
+await openai.chat.completions.create(
+	{ messages: [{ role: "user", content: "Hello!" }] },
+	{
+		headers: {
+			"x-usagetap-customer-id": currentUser.id,
+			"x-usagetap-feature": "chat.premium",
+		},
+	},
+);
+```
+
+### Unified `/call` endpoint (API-only)
+
+Need a single round-trip without the SDK? The public REST API exposes `POST /call`, which wraps `call_begin`, an optional vendor invocation, and `call_end` into one atomic request. Supply your usual begin payload plus an optional `vendor` block containing the URL, headers, and body to execute. UsageTap merges usage metrics from the vendor response with any explicit overrides before finalizing the call.
+
+```ts
+async function getEntitlementsFor(customerId: string) {
+	// Call begin upfront or reuse a cached begin payload for this customer + feature
+	return sessionStore.read(customerId); // pseudo-code: use your own persistence layer
+}
+
+const entitlements = await getEntitlementsFor("cust_123"); // stash begin.data.allowed somewhere durable
+const { model } = selectCapabilities(entitlements.allowed);
+
+const response = await fetch(`${baseUrl}/call`, {
+	method: "POST",
+	headers: {
+		Authorization: `Bearer ${process.env.USAGETAP_API_KEY}`,
+		Accept: "application/vnd.usagetap.v1+json",
+		"Content-Type": "application/json",
+	},
+	body: JSON.stringify({
+		customerId: "cust_123",
+		requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
+		feature: "chat.completions",
+		idempotency: crypto.randomUUID(),
+		vendor: {
+			url: "https://api.openai.com/v1/chat/completions",
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+				"Content-Type": "application/json",
+			},
+			body: {
+				model,
+				messages: [{ role: "user", content: "Hello" }],
+			},
+			responseType: "json",
+		},
+		usage: { modelUsed: model },
+	}),
+});
+
+const envelope = await response.json();
+if (!response.ok || envelope.result.status !== "ACCEPTED") {
+	throw new Error(`UsageTap /call failed: ${envelope.result.code}`);
+}
+
+const { begin, end, vendor, endUsage } = envelope.data;
+```
+
+- When the `vendor` block is omitted, `/call` simply runs begin → end using the provided `usage` overrides.
+- Non-2xx vendor responses still trigger `call_end`; the envelope returns `CALL_VENDOR_WARNING` alongside vendor error metadata.
+- The canonical media type `application/vnd.usagetap.v1+json` is required; the SDK already sends this header automatically when you rely on `UsageTapClient`.
+
+## Exports
+
+Key exports from `@usagetap/sdk`:
+
+- `UsageTapClient` – minimal HTTP client for `createCustomer`, `changePlan`, `incrementCustomMeter`, `call_begin`, `call_end`, and `checkUsage`.
+- `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).
+- `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.
+
+All helpers are designed for server runtimes. Use `UsageTapClient` with `allowBrowser: true` only for sandbox/test scenarios.
+
+### Ensure a customer subscription exists
+
+Run `createCustomer` before you invoke `call_begin` (or higher-level helpers) to guarantee the customer has an active subscription. The endpoint is fully idempotent—repeat calls return the existing snapshot and set `newCustomer: false`:
+
+```ts
+const snapshot = await usageTap.createCustomer({
+	customerId: "cust_123",
+	customerFriendlyName: "Acme AI",
+	customerEmail: "billing@acme.ai",
+	stripeCustomerId: "cus_123",
+});
+
+console.log("New customer?", snapshot.data.newCustomer);
+console.log("Plan:", snapshot.data.plan);
+console.log("Allowed entitlements:", snapshot.data.allowed);
+```
+
+`customerFriendlyName` (aka `customerName`) and `customerEmail` are **HIGHLY IMPORTANT BUT OPTIONAL**: they populate the customer profile on first creation and are safe to omit if you truly do not have them yet.
+
+This returns the same rich subscription snapshot surfaces by `call_begin` and `checkUsage`, making it safe to cache the response for onboarding flows. Pass `idempotencyKey` in `CreateCustomerOptions` when you need deterministic keys across services; otherwise the client auto-generates one by default. Both `idempotencyKey` (preferred) and `idempotency` (deprecated) are supported.
+
+### Change a customer's plan
+
+Use `changePlan` to switch a customer to a different usage plan. You can control how the change is applied with the `strategy` option:
+
+```ts
+const result = await usageTap.changePlan({
+	customerId: "cust_123",
+	planId: "plan_premium_v2",
+	strategy: "IMMEDIATE_RESET", // or "IMMEDIATE_PRORATED" or "AT_NEXT_REPLENISH"
+});
+
+console.log("Plan changed:", result.data.success);
+console.log("New subscription:", result.data.subscription);
+```
+
+**Strategy options:**
+- `IMMEDIATE_RESET`: Switch plan immediately and reset all usage counters to zero
+- `IMMEDIATE_PRORATED`: Switch plan immediately and prorate existing usage against new limits
+- `AT_NEXT_REPLENISH`: Schedule the plan change for the next replenishment cycle (default)
+
+The response includes the updated subscription details, including the new plan version, limits, and next replenishment timestamp. If `strategy: "AT_NEXT_REPLENISH"` is used, the `subscription.pending` field will indicate the scheduled plan change.
+
+### Check usage without creating a call
+
+When you need to display current quota status, plan details, or remaining balances without tracking a vendor call, use `checkUsage()`:
+
+```ts
+const usageStatus = await usageTap.checkUsage({ customerId: "cust_123" });
+
+console.log("Meters:", usageStatus.data.meters);
+console.log("Allowed:", usageStatus.data.allowed);
+console.log("Plan:", usageStatus.data.plan);
+console.log("Balances:", usageStatus.data.balances);
+```
+
+This returns the same rich usage snapshot as `call_begin` (meters, entitlements, subscription details, plan info, balances) but without creating a call record. Use this for dashboard widgets, pre-flight checks, or displaying quota status to users.
+
+### Increment custom meters
+
+Custom meters allow you to track usage beyond standard LLM metrics—ideal for agent actions, document processing, API calls, or any custom usage you need to meter.
+
+```ts
+const result = await usageTap.incrementCustomMeter({
+	customerId: "cust_123",
+	meterSlot: "CUSTOM1",  // or "CUSTOM2"
+	amount: 5,
+	feature: "agent_actions",
+	tags: ["workflow_automation"],
+	metadata: {
+		workflowId: "wf_abc123",
+		actionType: "email_send",
+	},
+});
+
+console.log("Event recorded:", result.data.eventId);
+console.log("Remaining quota:", result.data.meter.remaining);
+console.log("Blocked:", result.data.blocked);
+```
+
+**Parameters:**
+
+- `customerId` (string, required): Customer identifier
+- `meterSlot` ("CUSTOM1" | "CUSTOM2", required): Which custom meter to increment
+- `amount` (number, required): Positive number to decrement from quota
+- `feature` (string, optional): Feature identifier for tracking
+- `tags` (string[], optional): Tags for categorization  
+- `metadata` (object, optional): Additional metadata
+
+The method returns the updated meter snapshot showing remaining quota, limits, and usage. If the customer's plan has `limitType: "BLOCK"` and quota is exceeded, a `UsageTapError` is thrown with code `USAGETAP_AUTH_ERROR`.
+
+**Use cases:**
+
+```ts
+// Track agent tool invocations
+await usageTap.incrementCustomMeter({
+	customerId: "cust_123",
+	meterSlot: "CUSTOM1",
+	amount: 1,
+	feature: "agent.tool_call",
+	tags: ["web_search"],
+});
+
+// Track document processing (10 pages)
+await usageTap.incrementCustomMeter({
+	customerId: "cust_456",
+	meterSlot: "CUSTOM2",
+	amount: 10,
+	feature: "document.ocr",
+	metadata: { documentId: "doc_789", pages: 10 },
+});
+
+// Track external API calls
+await usageTap.incrementCustomMeter({
+	customerId: "cust_789",
+	meterSlot: "CUSTOM1",
+	amount: 1,
+	feature: "external_api.maps",
+	tags: ["geocoding"],
+});
+```
+
+**Important notes:**
+
+1. Custom meters must be enabled in the customer's usage plan
+2. The `amount` decrements the remaining quota (like token usage)
+3. With `BLOCK` policy, exceeding quota throws an error
+4. With `DOWNGRADE` policy, usage continues but quota can go negative
+5. Unlimited meters don't track usage but still record events for analytics
+
+## Response envelope (canonical only)
+
+UsageTap responds exclusively with the canonical `{ result, data, correlationId }` envelope for every endpoint. The SDK automatically sends `Accept: application/vnd.usagetap.v1+json`, parses the envelope, and returns strongly typed data structures. Transitional `raw` payloads and the `normalize*` helpers have been removed—`response.data` already contains the canonical shape you should persist or render.
+
+### Example `call_begin` success
+
+```json
+{
+  "result": {
+    "status": "ACCEPTED",
+    "code": "CALL_BEGIN_SUCCESS",
+    "timestamp": "2025-10-04T18:21:37.482Z"
+  },
+  "data": {
+    "callId": "call_123",
+    "startTime": "2025-10-04T18:21:37.482Z",
+		"policy": "DOWNGRADE",
+    "newCustomer": false,
+    "canceled": false,
+    "allowed": {
+      "standard": true,
+      "premium": true,
+      "audio": false,
+      "image": false,
+      "search": true,
+			"reasoningLevel": "MEDIUM"
+		},
+		"entitlementHints": {
+			"suggestedModelTier": "standard",
+			"reasoningLevel": "MEDIUM",
+			"policy": "DOWNGRADE",
+			"downgrade": {
+				"reason": "PREMIUM_QUOTA_EXHAUSTED",
+				"fallbackTier": "standard"
+			}
+		},
+		"meters": {
+			"standardCalls": {
+				"remaining": 12,
+				"limit": 20,
+				"used": 8,
+				"unlimited": false,
+				"ratio": 0.6
+			},
+			"premiumCalls": {
+				"remaining": 0,
+				"limit": null,
+				"used": 0,
+				"unlimited": true,
+				"ratio": null
+			},
+			"standardTokens": {
+				"remaining": 800,
+				"limit": 1000,
+				"used": 200,
+				"unlimited": false,
+				"ratio": 0.8
+			}
+		},
+		"remainingRatios": {
+			"standardCalls": 0.6,
+			"standardTokens": 0.8
+		},
+		"subscription": {
+			"id": "sub_123",
+			"usagePlanVersionId": "plan_2025_01",
+			"planName": "Pro",
+			"planVersion": "2025-01",
+			"limitType": "DOWNGRADE",
+			"reasoningLevel": "MEDIUM",
+			"lastReplenishedAt": "2025-10-04T00:00:00.000Z",
+			"nextReplenishAt": "2025-11-04T00:00:00.000Z",
+			"subscriptionVersion": 14
+		},
+		"models": {
+			"standard": ["gpt5-mini"],
+			"premium": ["gpt5"]
+		},
+		"idempotency": {
+			"key": "call_123",
+			"source": "derived"
+		}
+  },
+  "correlationId": "corr_abc123"
+}
+```
+
+`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.
+- `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.
+- `plan` and `balances` remain available alongside the core begin payload for backwards compatibility with earlier SDK versions.
+
+### Example `call_end` success
+
+```json
+{
+  "result": {
+    "status": "ACCEPTED",
+    "code": "CALL_END_SUCCESS",
+    "timestamp": "2025-10-04T18:21:52.103Z"
+  },
+  "data": {
+    "callId": "call_123",
+    "costUSD": 0,
+    "usage": {
+      "inputTokens": 600,
+      "cachedInputTokens": 120,
+      "billableInputTokens": 480,
+      "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"
+}
+```
+
+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
+
+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
+- Otherwise, it's classified as standard
+
+You can explicitly override this detection by passing `isPremium` in your `call_end` request:
+
+```ts
+await usageTap.endCall({
+  callId: begin.data.callId,
+  modelUsed: "custom-model-v2",
+  inputTokens: 100,
+  responseTokens: 200,
+  isPremium: true,  // Explicitly mark this as a premium call
+});
+```
+
+This is useful when:
+- You're using custom models that aren't in UsageTap's pricing database
+- You want to enforce specific billing tiers regardless of pricing
+- You're implementing your own tier classification logic
+
+### Batch pricing
+
+Batch mode applies a **50% discount** to standard pricing rates. Set `batch: true` or `pricingMode: "batch"` on either `call_begin` or `call_end`.
+
+When set on `call_begin`, the pricing mode carries through to `call_end` automatically. Setting it on `call_end` overrides the `call_begin` value.
+
+```ts
+// Option 1: Set on call_begin (carries through)
+const begin = await usageTap.beginCall({
+  customerId: "cust_123",
+  batch: true,
+  pricingMode: "batch",
+});
+
+// Option 2: Set on call_end (overrides call_begin)
+await usageTap.endCall({
+  callId: begin.data.callId,
+  modelUsed: "gpt-4o",
+  inputTokens: 100,
+  responseTokens: 200,
+  batch: true,
+  pricingMode: "batch",
+});
+```
+
+Both `batch` and `pricingMode` are echoed in the responses from `call_begin` and `call_end`.
+
+### Raw fetch integrations
+
+Prefer `UsageTapClient` whenever possible—it handles retries, headers, and idempotency for you. If you still need to work with `fetch` directly, remember to request the canonical media type and consume the envelope shape directly:
+
+```ts
+import type { BeginCallResponseBody, EndCallResponseBody } from "@usagetap/sdk";
+
+const beginResponse = await fetch(`${baseUrl}/call_begin`, {
+	method: "POST",
+	headers: {
+		Authorization: `Bearer ${apiKey}`,
+		Accept: "application/vnd.usagetap.v1+json",
+		"Content-Type": "application/json",
+	},
+	body: JSON.stringify(payload),
+}).then((r) => r.json());
+
+if (beginResponse.result.status !== "ACCEPTED") {
+	throw new Error(`call_begin failed: ${beginResponse.result.code}`);
+}
+
+const begin = beginResponse.data as BeginCallResponseBody;
+
+// ...later, when closing the call
+
+const endResponse = await fetch(`${baseUrl}/call_end`, {
+	method: "POST",
+	headers: {
+		Authorization: `Bearer ${apiKey}`,
+		Accept: "application/vnd.usagetap.v1+json",
+		"Content-Type": "application/json",
+	},
+	body: JSON.stringify({ callId: begin.callId }),
+}).then((r) => r.json());
+
+if (endResponse.result.status !== "ACCEPTED") {
+	throw new Error(`call_end failed: ${endResponse.result.code}`);
+}
+
+const end = endResponse.data as EndCallResponseBody;
+```
+
+The canonical payloads (`BeginCallResponseBody`, `EndCallResponseBody`, etc.) now match the envelope exactly, keeping SDK and raw integrations aligned without extra helper utilities.