UsageTap Meter implementation contract

1. Required agent behavior

1. Find every server-side provider call, including streaming, background jobs, retries, tool loops, and alternate routes.
2. Identify a stable, server-trusted customer or tenant ID. Never trust a browser-supplied customer ID without checking it against the authenticated session.
3. Prefer the provider wrapper for the smallest JavaScript or TypeScript change. Use the explicit SDK lifecycle when the app must enforce BLOCK or DOWNGRADE itself. Use direct HTTPS outside the supported server-side JavaScript runtime.
4. Begin before provider work and finalize once after success, provider error, stream completion, cancellation, or abort. Report the model and usage returned by the provider.
5. Preserve the original provider error if UsageTap finalization also fails. Make the finalization failure observable without replacing the primary error.
6. Add focused tests and run the repository's relevant test, lint, type, and build checks.

2. Credentials and transport

• Never expose either key to browser code, logs, commits, or agent output.
• API authentication accepts Authorization: Bearer $USAGETAP_API_KEY or x-api-key.
• Every API request must send Accept: application/vnd.usagetap.v1+json. Missing or incompatible Accept headers return HTTP 406.
• JSON POST requests should send Content-Type: application/json. Responses use the versioned UsageTap media type and a standard result envelope.

3. Choose the integration path

4. JavaScript and TypeScript SDK

Install @usagetap/sdk plus the provider package already used by the application. Import OpenAI helpers from @usagetap/sdk/openai, OpenRouter helpers from @usagetap/sdk/openrouter, and Anthropic helpers from @usagetap/sdk/anthropic.

import OpenAI from "openai";
import { withMetering } from "@usagetap/sdk/openai";

const provider = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export function meteredOpenAI(customerId: string) {
  return withMetering(provider, {
    apiKey: process.env.USAGETAP_API_KEY,
    customerId,
    feature: "chat.reply",
  });
}

// The OpenAI client shape is preserved.
const response = await meteredOpenAI(currentCustomer.id).responses.create({
  model: existingModel,
  input,
});

The wrapper preserves chat.completions.create() and responses.create(), generates unique idempotency keys, retries eligible UsageTap requests, extracts provider usage, and finalizes consumed or cancelled streams. It does not know the application's safe model fallback. Use the explicit path when BLOCK or DOWNGRADE must control provider selection.

import OpenAI from "openai";
import { UsageTapClient } from "@usagetap/sdk";

const usageTap = new UsageTapClient();
const openai = new OpenAI();

const response = await usageTap.withUsage(
  {
    customerId: currentCustomer.id,
    feature: "chat.reply",
    requested: { premium: true },
  },
  async ({ begin, setUsage }) => {
    // A blocked call is already finalized by call_begin.
    // If DOWNGRADE is configured, select a known safe fallback here.
    if (!begin.data.allowed.premium) {
      throw new Error("Premium usage is not allowed for this customer");
    }

    const result = await openai.responses.create({
      model: existingModel,
      input,
    });

    setUsage({
      modelUsed: result.model ?? existingModel,
      inputTokens: result.usage?.input_tokens ?? 0,
      responseTokens: result.usage?.output_tokens ?? 0,
      cachedInputTokens:
        result.usage?.input_tokens_details?.cached_tokens ?? 0,
    });

    return result;
  },
);

5. Direct HTTPS lifecycle

const apiKey = process.env.USAGETAP_API_KEY;
const apiBase = process.env.USAGETAP_BASE_URL ?? "https://api.usagetap.com";

async function usageTapPost(path, body) {
  const response = await fetch(`${apiBase}/${path}`, {
    method: "POST",
    headers: {
      Accept: "application/vnd.usagetap.v1+json",
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });
  const envelope = await response.json();
  if (!response.ok || envelope.result?.status !== "ACCEPTED") {
    throw new Error(
      `UsageTap ${path} failed: ${envelope.result?.code ?? response.status}`,
    );
  }
  return envelope;
}

const idempotencyKey = crypto.randomUUID();
const begin = await usageTapPost("call_begin", {
  customerId: currentCustomer.id,
  feature: "chat.reply",
  requested: { premium: true },
  idempotencyKey,
});

// call_begin returns HTTP 200 for entitlement denials and has already
// finalized the denied call. Do not invoke the provider or call call_end.
if (!begin.data.allowed.premium) {
  throw new Error("Premium usage is not allowed for this customer");
}

let providerResponse;
try {
  providerResponse = await openai.responses.create({
    model: existingModel,
    input,
  });
} catch (providerError) {
  try {
    await usageTapPost("call_end", {
      callId: begin.data.callId,
      error: {
        code: "PROVIDER_ERROR",
        message: "Provider request failed",
      },
    });
  } catch {
    // Preserve the original provider error. Report finalization separately.
  }
  throw providerError;
}

await usageTapPost("call_end", {
  callId: begin.data.callId,
  modelUsed: providerResponse.model ?? existingModel,
  inputTokens: providerResponse.usage?.input_tokens ?? 0,
  responseTokens: providerResponse.usage?.output_tokens ?? 0,
  cachedInputTokens:
    providerResponse.usage?.input_tokens_details?.cached_tokens ?? 0,
});

6. POST /call_begin

{
  "customerId": "tenant_123",
  "feature": "chat.reply",
  "tags": ["production"],
  "requested": {
    "standard": true,
    "premium": false,
    "audio": false,
    "image": false,
    "search": false,
    "reasoningLevel": "NONE"
  },
  "idempotencyKey": "one-key-per-logical-call"
}

{
  "result": {
    "status": "ACCEPTED",
    "code": "CALL_BEGIN_SUCCESS",
    "timestamp": "ISO-8601"
  },
  "correlationId": "request-correlation-id",
  "data": {
    "callId": "call-id",
    "startTime": "ISO-8601",
    "newCustomer": false,
    "canceled": false,
    "policy": "NONE | BLOCK | DOWNGRADE",
    "allowed": {
      "standard": true,
      "premium": false,
      "audio": false,
      "image": false,
      "search": false,
      "reasoningLevel": "NONE | LOW | MEDIUM | HIGH"
    },
    "entitlementHints": { "...": "advisory details" },
    "rateLimits": { "...": "optional rolling-call state" },
    "meters": { "...": "remaining, used, limit, unlimited, ratio" },
    "remainingRatios": { "...": "0 through 1, or null" },
    "subscription": { "...": "current subscription snapshot" },
    "plan": { "id": null, "name": null, "version": null },
    "balances": { "...": "optional remaining balances" },
    "idempotency": {
      "key": "one-key-per-logical-call",
      "source": "explicit | derived"
    }
  }
}

• A blocked entitlement still returns an accepted HTTP 200 envelope with allowed set accordingly. The denied call record is already finalized; do not invoke the provider and do not call /call_end.
• For DOWNGRADE, choose only a fallback model already approved by the application or user. Never invent a provider or model mapping.
• Treat entitlementHints, models, and rate-limit snapshots as guidance. The allowed fields are the decision inputs.

7. POST /call_end

{
  "callId": "call-id",
  "modelUsed": "provider-returned-model",
  "inputTokens": 1200,
  "cachedInputTokens": 400,
  "cacheWriteInputTokens": 0,
  "responseTokens": 180,
  "reasoningTokens": 0,
  "searches": 0,
  "audioSeconds": 0
}

{
  "callId": "call-id",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "Provider request failed"
  }
}

{
  "result": {
    "status": "ACCEPTED",
    "code": "CALL_END_SUCCESS",
    "timestamp": "ISO-8601"
  },
  "correlationId": "request-correlation-id",
  "data": {
    "callId": "call-id",
    "status": "COMPLETED | FAILED",
    "error": { "code": "optional", "message": "optional" },
    "costUSD": 0.00123,
    "standardCostUSD": 0.00123,
    "pricingMultiplier": 1,
    "usage": {
      "inputTokens": 1200,
      "cachedInputTokens": 400,
      "cacheWriteInputTokens": 0,
      "billableInputTokens": 800,
      "responseTokens": 180,
      "reasoningTokens": 0
    },
    "metered": { "...": "usage applied to configured meters" },
    "spendVelocity": { "...": "optional hour and day snapshots" },
    "meters": { "...": "updated meter snapshot" },
    "balances": { "...": "updated balances" }
  }
}

/call_end is idempotent. A repeated finalization does not decrement meters twice. The SDK error object is a first-class API contract: an accepted provider-error finalization returns data.status = "FAILED" while preserving the normalized error metadata.

8. Streaming, retries, and failure policy

• Finalize after the stream is consumed, not when headers arrive. Include final usage events from the provider when its streaming option must be enabled explicitly.
• Finalize on consumer cancellation and abort. Do not discard a wrapped stream without consuming or cancelling it.
• Retry a UsageTap request only with the same idempotency key and call ID for the same logical call. Never generate a new key inside a retry loop.
• The SDK defaults to three total attempts with bounded backoff and jitter for retryable UsageTap failures. Provider retries remain controlled by the existing provider integration.
• Decide and document fail-open versus fail-closed behavior for a UsageTap outage. Access enforcement generally fails closed; observability-only metering may fail open if the product owner accepts missing usage.

9. Customer and Meter setup after code

1. Set USAGETAP_API_KEY and the existing provider key in the application's server runtime.
2. Run the exact local command or request identified by the coding agent to produce one provider call.
3. Confirm the connection and customer attribution on Code Integration.
4. Configure customer plans, call and token allowances, limits, replenishment, and optional custom meters in Meter setup.
5. Exercise one allowed call and one limit path before production.

POST /customers and usageTap.createCustomer() are idempotent and can provision a customer before their first model call. GET /customers/{customerId}/usage and usageTap.checkUsage() return the current entitlement and meter snapshot. Plan changes require an admin key and should not be embedded in the initial application integration.

10. Explicitly outside first onboarding

11. Agent completion contract