@usagetap/sdk 1.0.0 → 1.1.0

package/README.md

@@ -8,15 +8,16 @@ 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/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/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`) 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
@@ -115,12 +116,17 @@ Prefer a zero-boilerplate integration? Keep scrolling—`wrapOpenAI` applies the
 ```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" },
-	},
+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,
+	},
 });
 ```
 
@@ -129,6 +135,8 @@ const ai = wrapOpenAI(openai, usageTap, {
 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",
@@ -136,7 +144,7 @@ const begin = await usageTap.beginCall({
 
 const compressed = await usageTap.promptCompress({
 	callId: begin.data.callId,
-	input: "Please summarize this long prompt...",
+	input: `Please summarize this long prompt but keep ${protectPromptText("PLAN_ID_PRO_2026")} exact.`,
 });
 
 const response = await openai.responses.create({
@@ -147,6 +155,33 @@ const response = await openai.responses.create({
 
 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" }],
+});
+```
+
+When using The Token Company, configure `tokenCompanyApiKey` on `UsageTapClient` and set `provider: "thetokencompany"`. Optional `tokenCompanyModel`, `tokenCompanyAggressiveness`, 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
@@ -439,15 +474,17 @@ Key exports from `@usagetap/sdk`:
 - `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/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.