@usagetap/sdk 1.4.0 → 1.7.0

package/README.md

@@ -2,6 +2,17 @@
 
 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.
 
+For API requests and MCP tool calls, use the dedicated call meter without model or token fields:
+
+```ts
+await client.incrementCustomMeter(
+  { customerId, meterSlot: "AGENTIC_API", amount: 1, feature: "mcp.tools.call" },
+  { idempotencyKey: `mcp:${requestId}` },
+);
+```
+
+Configure its included allocation and single-rate or graduated overage pricing in **More > Agentic & API** on the usage plan. It uses the same reporting, credit funding, and asynchronous PAYG settlement as custom meters. This does not reserve credit or impose a rolling rate limit. See [Agentic/API integration and limits](../../docs/agentic-api-meter.md).
+
 ## 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");`.
@@ -9,7 +20,7 @@ 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/anthropic` – Anthropic helpers (`withMetering`, `wrapAnthropic`)
 - `@usagetap/sdk/openrouter` – discoverable OpenRouter aliases for the OpenAI-compatible wrappers
 - `@usagetap/sdk/express` – Express middleware
 - `@usagetap/sdk/react` – React chat hook
@@ -123,6 +134,41 @@ const completion = await usageTap.gateway.chat.completions.create({
 console.log(completion.choices[0].message?.content);
 ```
 
+The typed Responses resource supports portable built-in web search, structured
+output, verbosity, prompt caching, and Gateway compression. It is buffered in
+this release, so omit `stream` or set it to `false`:
+
+```ts
+const response = await usageTap.gateway.responses.create({
+	model: "usagetap/standard",
+	customerId: "cust_123",
+	feature: "answer.with.sources",
+	instructions: stablePolicy,
+	input: "Find the current answer and return it as JSON.",
+	tools: [{ type: "web_search" }],
+	text: {
+		verbosity: "low",
+		format: {
+			type: "json_schema",
+			name: "sourced_answer",
+			strict: true,
+			schema: {
+				type: "object",
+				properties: { answer: { type: "string" } },
+				required: ["answer"],
+				additionalProperties: false,
+			},
+		},
+	},
+	prompt_cache_key: "answer-policy-v1",
+	prompt_cache_options: { mode: "implicit" },
+	compress: true,
+});
+
+console.log(response.output_text);
+console.log(response.usage?.input_tokens_details?.cached_tokens);
+```
+
 The same resource exposes `models.list()` and the complete native batch
 lifecycle. Batch creation generates the required idempotency key unless one is
 provided:
@@ -368,6 +414,31 @@ export async function POST() {
 
 `wrapOpenAI` preserves the model already supplied by the application. It does not invent a model mapping or fallback. Use the manual `withUsage` pattern when BLOCK or DOWNGRADE must control provider invocation, model selection, reasoning effort, or search tools.
 
+Starting in `@usagetap/sdk` 1.6.0, the Anthropic adapter preserves both
+streaming forms. Use
+`messages.create({ stream: true })` for the lower-level async iterable, or use
+the synchronous `messages.stream()` helper when the application relies on
+events and final-message accumulation:
+
+```ts
+const stream = anthropic.messages
+	.stream({
+		model: "claude-sonnet-4-5",
+		max_tokens: 512,
+		messages: [{ role: "user", content: "Stream it" }],
+	})
+	.on("text", (text) => process.stdout.write(text));
+
+const message = await stream.finalMessage();
+```
+
+`messages.stream()` still returns Anthropic's `MessageStream` immediately and
+retains `.on()`, async iteration, `.abort()`, `.done()`, `.finalText()`, and
+`.finalMessage()`. UsageTap begins metering before the provider request and
+finalizes once when the underlying stream completes, fails, or is aborted.
+Wrapped `messages.create()` results also retain Anthropic's `.withResponse()`
+and `.asResponse()` helpers.
+
 ### Overriding usage context per request
 
 You can override the UsageTap begin payload on a per-call basis via the `usageTap` option:
@@ -393,7 +464,12 @@ For streaming calls created with `{ stream: true }`, UsageTap automatically calc
 
 ### responses.create support
 
-The wrapper also instruments `openai.responses.create`, preserves the supplied model and request, and collects usage data the same way as chat completions.
+The wrapper also instruments `openai.responses.create`, preserves text controls,
+tools, prompt-cache controls and breakpoints through compression, and records
+cache reads, cache writes, reasoning tokens, and completed web-search calls.
+Install OpenAI SDK 7.5 or newer when you want its native TypeScript definitions
+for the latest Responses fields; the UsageTap Gateway resource has its own types
+and does not require the OpenAI package.
 
 ### OpenRouter support
 
@@ -540,6 +616,11 @@ const wrappedFetch = wrapFetch(usageTap, {
 		feature: "chat",
 		requested: { standard: true, premium: true, search: true, reasoningLevel: "MEDIUM" },
 	},
+	onMeteringError: ({ stage, callId, error }) => {
+		console.error("UsageTap metering failed", { stage, callId, error });
+	},
+	// Set true when an unmetered vendor response must fail the application call.
+	strictMetering: false,
 });
 
 const openai = new OpenAI({
@@ -557,7 +638,7 @@ const completion = await openai.chat.completions.create({
 });
 ```
 
-`wrapFetch` detects OpenAI API endpoints, handles streaming and non-streaming responses, and automatically extracts usage data. It preserves the application's model. If limits must control provider selection, use an explicit begin decision before this layer. You can override metering context per request using special headers:
+`wrapFetch` detects OpenAI API endpoints, handles streaming and non-streaming responses, requests final usage for chat streams, and automatically extracts usage data. It preserves the application's model. If limits must control provider selection, use an explicit begin decision before this layer. Use `onMeteringError` to export request parsing, begin, or end failures after SDK retries are exhausted. Set `strictMetering` when those failures should reject the application call. You can override metering context per request using special headers; the wrapper consumes these headers and removes them before calling the provider:
 
 ```ts
 await openai.chat.completions.create(
@@ -625,6 +706,48 @@ const { begin, end, vendor, endUsage } = envelope.data;
 - 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`.
 
+### Retrieve finalized call pricing (API-only)
+
+An external server can retrieve the stored result later with `GET
+/calls/{callId}`. Use a server API key containing `usage:read`; do not expose
+the key in browser code.
+
+```ts
+const response = await fetch(
+	`${baseUrl}/calls/${encodeURIComponent(callId)}`,
+	{
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${process.env.USAGETAP_API_KEY}`,
+			Accept: "application/vnd.usagetap.v1+json",
+		},
+	},
+);
+
+const envelope = await response.json();
+if (!response.ok || envelope.result.status !== "ACCEPTED") {
+	throw new Error(`UsageTap call lookup failed: ${envelope.result.code}`);
+}
+if (envelope.data.pricingStatus !== "FINAL") {
+	throw new Error(`Call pricing is ${envelope.data.pricingStatus}`);
+}
+
+const providerCostUsd = envelope.data.costUSD;
+const customerChargeUsd = envelope.data.payg.chargedUsd;
+const customerId = envelope.data.customerId;
+const customerUserId = envelope.data.customerUserId; // string or null
+```
+
+`pricingStatus` is `PENDING` while the call is open and `UNAVAILABLE` when a
+completed call could not resolve model pricing. Only treat `costUSD` as final
+when the status is `FINAL`.
+
+The response includes only the stable customer identifiers recorded on the
+call: `customerId` and nullable `customerUserId`. Use opaque, non-PII values
+for both. Customer and end-user names or emails, billing-provider identifiers,
+`organizationId`, and the internal `orgIdCustomerId` composite key are not
+returned.
+
 ## Exports
 
 Key exports from `@usagetap/sdk`:
@@ -686,9 +809,9 @@ 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)
+- `IMMEDIATE_RESET`: Switch immediately, grant the target plan's full allowances, and start a new replenishment cycle (default when the SDK option is omitted)
+- `IMMEDIATE_PRORATED`: Switch immediately, preserve usage already consumed, adjust remaining allowances to the target limits, and keep the current replenishment date
+- `AT_NEXT_REPLENISH`: Keep the current plan until its existing scheduled replenishment, then switch
 
 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.
 
@@ -715,7 +838,7 @@ Custom meters allow you to track usage beyond standard LLM metrics—ideal for a
 const result = await usageTap.incrementCustomMeter({
 	customerId: "cust_123",
 	customerUserId: currentUser.id,
-	meterSlot: "CUSTOM1",  // or "CUSTOM2"
+	meterSlot: "CUSTOM1",  // or "CUSTOM2" or "AGENTIC_API"
 	amount: 5,
 	feature: "agent_actions",
 	tags: ["workflow_automation"],
@@ -735,13 +858,13 @@ console.log("Blocked:", result.data.blocked);
 - `customerId` (string, required): Customer identifier
 - `customerUserId` (string, optional): Stable identifier for the end user responsible for the event
 - `customerUserName` and `customerUserEmail` (string, optional): Display fields for live activity
-- `meterSlot` ("CUSTOM1" | "CUSTOM2", required): Which custom meter to increment
+- `meterSlot` ("CUSTOM1" | "CUSTOM2" | "AGENTIC_API", required): Which 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`.
+The method returns the updated meter snapshot showing remaining quota, limits, and usage. If usage exceeds the allocation and eligible overage funding, it returns `data.blocked: true`. The SDK does not throw for this accepted usage report; your application must enforce the flag.
 
 **Use cases:**
 
@@ -749,10 +872,11 @@ The method returns the updated meter snapshot showing remaining quota, limits, a
 // Track agent tool invocations
 await usageTap.incrementCustomMeter({
 	customerId: "cust_123",
-	meterSlot: "CUSTOM1",
+	meterSlot: "AGENTIC_API",
 	amount: 1,
 	feature: "agent.tool_call",
 	tags: ["web_search"],
+	metadata: { kind: "mcp", serverName: "search", toolName: "web_search" },
 });
 
 // Track document processing (10 pages)
@@ -767,20 +891,26 @@ await usageTap.incrementCustomMeter({
 // Track external API calls
 await usageTap.incrementCustomMeter({
 	customerId: "cust_789",
-	meterSlot: "CUSTOM1",
+	meterSlot: "AGENTIC_API",
 	amount: 1,
 	feature: "external_api.maps",
 	tags: ["geocoding"],
+	metadata: { kind: "api", method: "GET", endpoint: "/v1/geocode" },
 });
 ```
 
+For Agentic & API Calls, use `metadata.toolName` (and optionally
+`metadata.serverName`) for MCP operations, or `metadata.endpoint` and
+`metadata.method` for HTTP APIs. Live View displays these values and removes URL
+query strings from endpoint labels.
+
 **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
+2. Report a positive safe integer quantity. Usage consumes allocation, then eligible purchased meter credits and/or PAYG funding. The last included unit is allowed.
+3. Unfunded usage is recorded with `blocked: true`; the application must enforce that flag. LLM `BLOCK`/`DOWNGRADE` policies do not apply to meter reports.
+4. PAYG overages require enabled PAYG and a configured single or graduated price. Settlement is asynchronous and does not reserve dollar credit or impose a rolling rate limit.
+5. Unlimited meters still record events for analytics but do not consume allocation or charge overages.
 
 ## Response envelope (canonical only)
 
@@ -875,7 +1005,7 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
 - `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). The SDK generates a unique key by default. With SDK auto-generation disabled, the backend derives a deterministic hash from organization, customer, feature, requested entitlements, call type, PAYG hold, and pricing mode; identical inputs can replay an earlier call.
+- `idempotency` reveals the actual key that was persisted (`callId` mirrors this value). The SDK generates a unique key by default. With SDK auto-generation disabled, the backend derives a deterministic hash from organization, customer, feature, requested entitlements, call type, and pricing mode; identical inputs can replay an earlier call.
 - `plan` and `balances` remain available alongside the core begin payload for backwards compatibility with earlier SDK versions.
 
 ### Example `call_end` success
@@ -898,7 +1028,7 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
       "reasoningTokens": 0
     },
     "metered": {
-      "tokens": 768,
+      "tokens": 288,
       "calls": 1,
       "searches": 1
     },
@@ -939,7 +1069,15 @@ includes cache reads. Anthropic reports ordinary input, cache reads, and cache
 writes separately, so the Anthropic wrapper adds the three counters for
 `inputTokens` while retaining both cache subsets.
 
-`metered` is derived from the raw Dynamo deltas. Additional meters (audio seconds, reasoning tokens, balances) will populate in later phases without breaking the contract.
+`metered.tokens` is the provider-reported output-token count. Input tokens,
+including cache reads and cache writes, remain recorded and part of provider
+cost but do not consume the plan's Standard Output Tokens or Premium Output
+Tokens allowance and are not sent to the corresponding Stripe token meters.
+Reasoning tokens are a breakdown of provider output and are not added again.
+
+The persisted meter keys remain `standardTokens` and `premiumTokens` for API
+compatibility; they represent standard and premium output tokens in both plan
+limits and Stripe usage metering.
 
 `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.