UsageTap

View saved version →

---
name: integrate-usagetap
description: Add or repair UsageTap Meter in an existing server-side JavaScript or TypeScript application that calls OpenAI, Anthropic, or OpenRouter. Use when the user asks to instrument, wrap, meter, attribute, or verify LLM calls; do not use for ordinary usage analysis, pricing-plan design, Gateway adoption, or prompt compression.
---

# Integrate UsageTap

Implement the smallest safe UsageTap Meter change in the user's existing application. Preserve its provider, model selection, request and response shapes, streaming behavior, and error semantics.

Do not stop at a plan or generic sample when the user asked for implementation and the repository is writable. Inspect, edit, and validate the actual integration.

## Establish the contract

Before editing:

1. Read `https://usagetap.com/llmreference` and treat it as the canonical current contract.
2. Use `https://usagetap.com/embed-api?features=meter` for maintained stack-specific examples when needed.
3. If the public reference is unavailable, read [references/integration-contract.md](references/integration-contract.md).
4. Inspect the installed `@usagetap/sdk` version, exports, lockfile, and any local UsageTap documentation. Prefer the installed version's real API over a stale example, and report a material conflict rather than guessing.

## Inspect the application

Find the server runtime, package manager, provider SDKs, every relevant LLM call site, streaming paths, error handling, environment-file convention, tests, and the server-trusted customer or tenant identity.

Preserve unrelated user changes. Do not instrument browser code with a UsageTap credential. Do not instrument test fixtures, examples, or dead code unless the user explicitly put them in scope.

If a stable server-trusted `customerId` cannot be identified, ask one concise question before choosing one. Do not substitute an email address, display name, request ID, session ID, or a newly generated value. Prefer the application's durable account or tenant identifier; add a stable non-PII end-user ID only when useful and already available.

## Choose the integration

Read [references/integration-contract.md](references/integration-contract.md) for the selection rules and invariants.

- Prefer `withMetering` for supported OpenAI, Anthropic, and OpenRouter clients when UsageTap can wrap the existing provider call without changing application decisions.
- Preserve the Anthropic call shape already in use. `@usagetap/sdk` 1.6.0 and newer retain `messages.create()` response helpers such as `.withResponse()` and `.asResponse()`, and support both `messages.create({ stream: true })` and synchronous `messages.stream()`, including event handlers, async iteration, cancellation, and final-message helpers. Do not rewrite one form into the other unless the installed UsageTap SDK predates that support.
- Use `UsageTapClient.withUsage`, `beginCall`/`endCall`, or the documented HTTPS lifecycle when the application must inspect entitlements before selecting a model or tool, implement BLOCK or DOWNGRADE behavior, or coordinate an unsupported call shape.
- Detect existing instrumentation before adding anything. Repair or extend it instead of double-wrapping or double-reporting a call.
- Keep the wrapper near the authenticated request boundary when customer identity varies per request. Never bind all tenants to a sample or constant customer ID.

## Implement safely

- Add only the dependency and imports required by the chosen path.
- Keep UsageTap and provider credentials in the server runtime. Never read, print, log, transmit, or commit secret values. Add variable names with placeholder values only to the project's example environment file; do not modify `.env`, `.env.local`, secret stores, or deployment configuration unless the user explicitly asks.
- Reuse the application's existing provider client and model. Do not migrate providers or change models as part of metering.
- Use a meaningful low-cardinality feature name derived from the product operation.
- Preserve retries and use one idempotency key per logical UsageTap call, reusing it only for retries of that same call.
- Ensure allowed calls finalize on success, provider error, stream completion, cancellation, and abort. A call denied by `call_begin` is already finalized and must not invoke the provider or call `call_end`.
- Report provider-returned model and usage fields when available. Sanitize error metadata; never include prompts, responses, credentials, headers, or raw provider bodies.

Do not add UsageTap Gateway, prompt compression, sampling or payload capture, provider migration, model changes, Stripe synchronization, plan mutation, browser embed sessions, or admin automation unless the user asks for that separate capability.

## Validate and hand off

Run focused tests plus the relevant type, lint, and build checks available in the repository. Add tests for the changed boundary when the project has a compatible test setup. Do not make a paid or externally visible live provider request unless the user explicitly authorizes it.

When a connected UsageTap MCP server and an already-produced test call are available, use `find_customers` if identity resolution is needed, then `list_calls` with the exact customer ID and a bounded explicit time range. Verify customer attribution, feature, status, provider/model, and token fields. Do not claim live verification from code inspection alone.

Finish with:

- the call sites instrumented and the integration path chosen;
- validation that ran and anything not run;
- environment-variable names still required, without values;
- the exact command or request that produces the first metered call;
- any unresolved customer-identity or deployment action;
- links to UsageTap [Live View](https://usagetap.com/live) and [Code Integration](https://usagetap.com/embed-api?features=meter).

For skill evaluation rather than an actual integration, use [references/staging-evals.md](references/staging-evals.md).

Referenced files: 3 — file references are metadata, not package contents.