FEATURE: Added usagetap support for billing, metering, etc.

Author: PredictabilityAtScale

README.md

@@ -182,6 +182,71 @@ import { geminiAdapter } from 'promptopskit/gemini';
 import { openrouterAdapter } from 'promptopskit/openrouter';
 ```
 
+## Optional UsageTap Tracking
+
+PromptOpsKit can also help you track provider calls with UsageTap.com while keeping the core render API body-only.
+
+```typescript
+import { createPromptOpsKit } from 'promptopskit';
+import { createUsageTapClient, runOpenAIWithUsageTap } from 'promptopskit/usagetap';
+
+const kit = createPromptOpsKit({ sourceDir: './prompts' });
+const usageTap = createUsageTapClient({ apiKey: process.env.USAGETAP_API_KEY! });
+
+const { request } = await kit.renderPrompt({
+  path: 'support/reply',
+  provider: 'openai',
+  variables: {
+    user_message: 'How do I reset my password?',
+    app_context: 'Account settings page',
+  },
+});
+
+const tracked = await runOpenAIWithUsageTap(usageTap, {
+  begin: {
+    customerId: 'user_123',
+    feature: 'chat.send',
+    requested: { standard: true, premium: true, search: true },
+    idempotencyKey: 'chat-send-user-123-req-456',
+  },
+  request,
+  entitlementMode: 'apply',
+  modelTiers: {
+    standard: 'gpt-5.4-mini',
+    premium: 'gpt-5.4',
+  },
+  toolEntitlements: {
+    image_tool: 'image',
+    web_lookup: 'search',
+  },
+  invoke: async (requestUsed) => {
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify(requestUsed.body),
+    });
+
+    return response.json();
+  },
+});
+
+// tracked.response      -> vendor JSON response
+// tracked.begin         -> UsageTap call_begin payload
+// tracked.end           -> UsageTap call_end payload
+// tracked.requestUsed   -> effective request after optional entitlement changes
+// tracked.effectiveUsage -> usage sent to UsageTap
+```
+
+Notes:
+- `entitlementMode` defaults to `'off'`. Set it to `'apply'` only when you want UsageTap allowances to mutate a cloned provider request.
+- `runOpenRouterWithUsageTap`, `runAnthropicWithUsageTap`, and `runGeminiWithUsageTap` follow the same pattern.
+- `extractOpenAIUsage`, `extractAnthropicUsage`, and `extractGeminiUsage` are public if you want to manage UsageTap lifecycle yourself.
+
+For explicit lifecycle control, use `beginUsageTapCall`, `endUsageTapCall`, or `withUsageTapCall` from `promptopskit/usagetap`. Full documentation: [docs/usagetap.md](./docs/usagetap.md).
+
 ## Overrides
 
 Define environment and tier overrides in front matter. Precedence: **base → environment → tier → runtime**. Scalars and arrays are replaced, not merged.

docs/index.md

@@ -9,6 +9,7 @@ Open-source developer toolkit for managing prompts, system instructions, tools,
 - [Composition](./composition.md) — Share system instructions across prompts with `includes`
 - [Overrides](./overrides.md) — Environment and tier-based overrides for dev/prod/free/pro
 - [Providers](./providers.md) — Provider adapters for OpenAI, Anthropic, Gemini, and OpenRouter
+- [UsageTap](./usagetap.md) — Optional begin/end call tracking and entitlement-aware provider helpers for UsageTap.com
 - [Inline Source](./inline-source.md) — Render prompts from strings without files
 
 ## Reference

docs/providers.md

@@ -50,6 +50,17 @@ interface ProviderAdapter {
 }
 ```
 
+## Optional UsageTap tracking
+
+If you want UsageTap begin/end tracking around a provider call, use the optional `promptopskit/usagetap` helper layer.
+
+- The core adapters still only produce request bodies.
+- Provider-specific runners are available for OpenAI, OpenRouter, Anthropic, and Gemini.
+- Manual lifecycle control is available through `withUsageTapCall`.
+- Entitlement-aware request mutation is opt-in and runs on a cloned request.
+
+See [UsageTap](./usagetap.md) for setup, lifecycle helpers, entitlement behavior, tool gating, standalone usage extractors, and provider examples.
+
 ## OpenAI
 
 Body shape: [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)

docs/usagetap.md

@@ -0,0 +1,205 @@
+# UsageTap
+
+PromptOpsKit includes an optional `promptopskit/usagetap` helper layer for UsageTap.com call tracking. It wraps your own provider call with `call_begin` and `call_end` requests while keeping the core prompt rendering API body-only.
+
+## Install surface
+
+UsageTap helpers ship inside the main package under a separate subpath:
+
+```typescript
+import {
+  createUsageTapClient,
+  runOpenAIWithUsageTap,
+  runOpenRouterWithUsageTap,
+  runAnthropicWithUsageTap,
+  runGeminiWithUsageTap,
+  withUsageTapCall,
+  extractOpenAIUsage,
+  extractAnthropicUsage,
+  extractGeminiUsage,
+} from 'promptopskit/usagetap';
+```
+
+The helper layer does not add an SDK dependency. It uses `fetch` directly against `https://api.usagetap.com` and sends:
+
+- `Authorization: Bearer ...`
+- `Accept: application/vnd.usagetap.v1+json`
+- `Content-Type: application/json`
+
+## Create a client
+
+```typescript
+import { createUsageTapClient } from 'promptopskit/usagetap';
+
+const usageTap = createUsageTapClient({
+  apiKey: process.env.USAGETAP_API_KEY!,
+});
+```
+
+You can also override `baseUrl` or `fetch` for tests and custom runtimes.
+
+## Track a provider call
+
+```typescript
+import { createPromptOpsKit } from 'promptopskit';
+import { createUsageTapClient, runOpenAIWithUsageTap } from 'promptopskit/usagetap';
+
+const kit = createPromptOpsKit({ sourceDir: './prompts' });
+const usageTap = createUsageTapClient({ apiKey: process.env.USAGETAP_API_KEY! });
+
+const { request } = await kit.renderPrompt({
+  path: 'support/reply',
+  provider: 'openai',
+  variables: {
+    user_message: 'How do I reset my password?',
+    app_context: 'Account settings page',
+  },
+});
+
+const tracked = await runOpenAIWithUsageTap(usageTap, {
+  begin: {
+    customerId: 'user_123',
+    feature: 'chat.send',
+    requested: { standard: true, premium: true, search: true },
+    idempotencyKey: 'chat-send-user-123-req-456',
+  },
+  request,
+  entitlementMode: 'apply',
+  modelTiers: {
+    standard: 'gpt-5.4-mini',
+    premium: 'gpt-5.4',
+  },
+  toolEntitlements: {
+    image_tool: 'image',
+    web_lookup: 'search',
+  },
+  invoke: async (requestUsed) => {
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify(requestUsed.body),
+    });
+
+    return response.json();
+  },
+});
+
+tracked.response;
+tracked.begin;
+tracked.end;
+tracked.requestUsed;
+tracked.effectiveUsage;
+tracked.allowed;
+```
+
+`runOpenRouterWithUsageTap`, `runAnthropicWithUsageTap`, and `runGeminiWithUsageTap` follow the same pattern.
+
+## Entitlement mode
+
+`entitlementMode` defaults to `'off'`.
+
+- `'off'`: track the call, but do not change the provider request.
+- `'apply'`: clone the provider request and apply UsageTap allowances before invoking the vendor.
+
+When `entitlementMode: 'apply'` is enabled, helpers can:
+
+- Swap to `modelTiers.standard` or `modelTiers.premium`.
+- Cap OpenAI or OpenRouter `reasoning_effort`.
+- Cap Gemini `thinkingConfig.thinkingBudget`. If no Gemini thinking budget was present, the helper now sets one from the allowed reasoning level.
+- Remove built-in OpenAI `web_search` when `allowed.search === false`.
+- Remove named tools according to `toolEntitlements` for OpenAI, Anthropic, and Gemini function declarations.
+
+Notes:
+
+- Mutations happen on a cloned request. The original `request` object is left unchanged.
+- Built-in tool gating is intentionally narrow today. Only OpenAI `web_search` is handled automatically; other built-ins must be mapped through your own tool policy.
+- Applying Gemini reasoning limits can introduce a `thinkingConfig` block even when the original request omitted one.
+
+## Manual lifecycle control
+
+Use `withUsageTapCall` when you want begin/invoke/end tracking without a provider-specific helper.
+
+```typescript
+import { createUsageTapClient, withUsageTapCall } from 'promptopskit/usagetap';
+
+const usageTap = createUsageTapClient({ apiKey: process.env.USAGETAP_API_KEY! });
+
+const tracked = await withUsageTapCall(usageTap, {
+  begin: {
+    customerId: 'user_123',
+    feature: 'embeddings.index',
+  },
+  invoke: async ({ setUsage, signal }) => {
+    const response = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      signal,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify({
+        model: 'text-embedding-3-large',
+        input: 'PromptOpsKit',
+      }),
+    }).then((result) => result.json());
+
+    setUsage({
+      modelUsed: 'text-embedding-3-large',
+      inputTokens: 6,
+    });
+
+    return response;
+  },
+});
+```
+
+`withUsageTapCall` also accepts an invoke result shaped like `{ result, usage }` if you prefer to return the usage payload directly.
+
+If the vendor call throws and UsageTap `call_end` also fails, the original vendor error is rethrown and the UsageTap failure is attached as `error.cause` when possible.
+
+## Standalone usage extractors
+
+The provider runners use public extractor helpers that you can call yourself:
+
+- `extractOpenAIUsage(response, meta)`
+- `extractAnthropicUsage(response, meta)`
+- `extractGeminiUsage(response, meta)`
+
+They map common token fields into the UsageTap `call_end` payload shape:
+
+- OpenAI and OpenRouter: `usage.prompt_tokens`, `completion_tokens`, cached prompt tokens, reasoning tokens
+- Anthropic: `usage.input_tokens`, `output_tokens`, `cache_read_input_tokens`
+- Gemini: `usageMetadata.promptTokenCount`, `candidatesTokenCount`, `cachedContentTokenCount`, `thoughtsTokenCount`
+
+## API surface
+
+Main exports:
+
+- `createUsageTapClient`
+- `beginUsageTapCall`
+- `endUsageTapCall`
+- `withUsageTapCall`
+- `applyUsageTapEntitlements`
+- `runOpenAIWithUsageTap`
+- `runOpenRouterWithUsageTap`
+- `runAnthropicWithUsageTap`
+- `runGeminiWithUsageTap`
+- `extractOpenAIUsage`
+- `extractAnthropicUsage`
+- `extractGeminiUsage`
+- `defaultUsageTapErrorMapper`
+
+Relevant types:
+
+- `UsageTapBeginRequest`
+- `UsageTapBeginResponse`
+- `UsageTapEndUsage`
+- `UsageTapCallOptions`
+- `UsageTapProviderRunOptions`
+- `UsageTapEntitlementOptions`
+- `UsageTapAllowed`
+
+For the rest of the PromptOpsKit provider model, see [Providers](./providers.md).

package.json

@@ -30,6 +30,16 @@
         "default": "./dist/testing.cjs"
       }
     },
+    "./usagetap": {
+      "import": {
+        "types": "./dist/usagetap/index.d.ts",
+        "default": "./dist/usagetap/index.js"
+      },
+      "require": {
+        "types": "./dist/usagetap/index.d.cts",
+        "default": "./dist/usagetap/index.cjs"
+      }
+    },
     "./openai": {
       "import": {
         "types": "./dist/providers/openai.d.ts",

src/index.ts

@@ -21,6 +21,27 @@ export type { PromptValidationResult, ValidationError } from './validation/index
 export type { RenderedSections, RenderOptions } from './renderer/index.js';
 export type { ParseResult } from './parser/index.js';
 export type { OverrideOptions } from './overrides/index.js';
+export type {
+  UsageTapAllowed,
+  UsageTapAllowedCapability,
+  UsageTapBeginRequest,
+  UsageTapBeginResponse,
+  UsageTapCallOptions,
+  UsageTapCallResult,
+  UsageTapClient,
+  UsageTapClientConfig,
+  UsageTapEndRequest,
+  UsageTapEndResponse,
+  UsageTapEndUsage,
+  UsageTapEntitlementMode,
+  UsageTapEntitlementOptions,
+  UsageTapErrorPayload,
+  UsageTapInvokeContext,
+  UsageTapInvokeResult,
+  UsageTapProviderRunOptions,
+  UsageTapProviderRunResult,
+  UsageTapReasoningLevel,
+} from './usagetap/index.js';
 
 export { parsePrompt, loadPromptFile, extractSections } from './parser/index.js';
 export { interpolate, extractVariables } from './renderer/index.js';
@@ -32,6 +53,21 @@ export { anthropicAdapter } from './providers/anthropic.js';
 export { geminiAdapter } from './providers/gemini.js';
 export { openrouterAdapter } from './providers/openrouter.js';
 export { PromptAssetSchema, PromptAssetOverridesSchema } from './schema/index.js';
+export {
+  applyUsageTapEntitlements,
+  beginUsageTapCall,
+  createUsageTapClient,
+  defaultUsageTapErrorMapper,
+  endUsageTapCall,
+  extractAnthropicUsage,
+  extractGeminiUsage,
+  extractOpenAIUsage,
+  runAnthropicWithUsageTap,
+  runGeminiWithUsageTap,
+  runOpenAIWithUsageTap,
+  runOpenRouterWithUsageTap,
+  withUsageTapCall,
+} from './usagetap/index.js';
 
 // --- Config ---