# UsageTap

## Recommended first integration

UsageTap Meter is the default onboarding product. Gateway and Compress are optional later products and must not be added unless the user explicitly requests them.

Canonical reference: https://usagetap.com/llmreference
Code integration and verification: https://usagetap.com/embed-api?features=meter
API reference: https://usagetap.com/docs/API_REFERENCE
SDK reference: https://usagetap.com/docs/SDK_REFERENCE

Implementation facts:
- Use a server-side utk- key with usage:write as USAGETAP_API_KEY.
- Keep the application's existing provider key and model.
- Every direct API request sends Accept: application/vnd.usagetap.v1+json.
- Direct call_begin requests use one unique idempotencyKey per logical call and reuse it only for retries.
- call_begin returns HTTP 200 for denied entitlements; inspect data.allowed before invoking the provider. A denied call is already finalized.
- Finalize successful calls with actual provider model and usage. Finalize provider failures with error: { code, message }.
- Do not send secrets, prompts, or raw provider response bodies in error metadata.

## Copyable coding-agent prompt

Implement UsageTap Meter in this repository.

Read https://usagetap.com/llmreference first and treat it as the canonical contract. The initial goal is Meter only. Do not add UsageTap Gateway, UsageTap Compress, prompt compression, provider migration, model changes, or Stripe synchronization unless I explicitly ask.

Work autonomously:
1. Inspect the repository to find every server-side AI/provider call, the framework/runtime, existing provider SDKs, streaming behavior, tests, environment-variable conventions, and the trusted authenticated customer or tenant ID.
2. Choose the smallest safe integration. Prefer @usagetap/sdk for supported server-side JavaScript/TypeScript provider clients. Use the explicit SDK lifecycle when BLOCK or DOWNGRADE must control provider invocation or model selection; provider wrappers do not invent a safe fallback model. Use direct HTTPS for other languages or when the SDK is not a safe fit. Preserve the existing provider, model, request/response shape, and error behavior.
3. Ask one concise clarification only if a stable server-trusted customerId cannot be inferred or there are multiple materially different integration targets. Otherwise proceed.
4. Implement the complete Meter lifecycle. Attribute every call to a stable customerId and feature; begin before provider work; inspect data.allowed before invoking the provider; do not end a denied call because call_begin already finalized it; finalize an allowed call exactly once on success, error, stream completion, cancellation, or abort; report the actual model and usage returned by the provider; sanitize error metadata; and use one unique idempotency key per logical call, reused only for its retries.
5. Keep all credentials server-side. Never read, print, log, or commit secret values. Add placeholders only to the project's example environment file. UsageTap Meter needs USAGETAP_API_KEY (create a utk-… key with usage:write at https://usagetap.com/configure#api-keys). Keep the app's existing provider key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY.
6. Add or update focused tests and run the relevant test, lint, and type/build checks. If credentials are unavailable, finish and verify the code without attempting a live provider request.

When done, report:
- what you changed and which calls are now metered;
- the exact environment-variable names the user must set, without values;
- any one remaining user decision or action;
- the command or request that produces the first metered call;
- how to verify it at https://usagetap.com/embed-api?features=meter;
- the next Meter step: define customer plans, allowances, and limits at https://usagetap.com/quickstart.

Do not stop at a plan or code sample. Make the changes when it is safe to do so.