@usagetap/sdk 0.10.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UsageTap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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
@@ -110,21 +111,78 @@ const response = await openai.responses.create({
 });
 ```
 
-Prefer a zero-boilerplate integration? Keep scrolling—`wrapOpenAI` applies the same entitlement-aware defaults if you omit `model` from your request.
+Prefer a zero-boilerplate integration? Keep scrolling—`wrapOpenAI` applies the same entitlement-aware defaults if you omit `model` from your request.
 
 ```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" },
-	},
-});
-```
-
-> **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 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" }],
+});
+```
+
+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
 
@@ -414,16 +472,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.
-- `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/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.