@usagetap/sdk 0.7.1 → 0.8.1

package/README.md

@@ -405,9 +405,10 @@ const { begin, end, vendor, endUsage } = envelope.data;
 
 Key exports from `@usagetap/sdk`:
 
-- `UsageTapClient` – minimal HTTP client for `createCustomer`, `changePlan`, `call_begin`, `call_end`, and `checkUsage`.
+- `UsageTapClient` – minimal HTTP client for `createCustomer`, `changePlan`, `incrementCustomMeter`, `call_begin`, `call_end`, and `checkUsage`.
 - `createCustomer` – idempotently ensure a customer subscription exists before starting a call.
 - `changePlan` – switch a customer to a different usage plan with configurable strategy (immediate reset, prorated, or scheduled).
+- `incrementCustomMeter` – track custom usage metrics beyond standard LLM counters (agent actions, documents, API calls, etc.).
 - `checkUsage` – lightweight method to query current usage status without creating a call session.
 - `wrapFetch` – wraps a fetch function to automatically instrument OpenAI API calls (minimal integration).
 - `createIdempotencyKey` – helper for generating UsageTap-compatible idempotency keys.
@@ -438,7 +439,7 @@ console.log("Plan:", snapshot.data.plan);
 console.log("Allowed entitlements:", snapshot.data.allowed);
 ```
 
-This returns the same rich subscription snapshot surfaces by `call_begin` and `checkUsage`, making it safe to cache the response for onboarding flows. Pass an `idempotencyKey` in `CreateCustomerOptions` when you need deterministic keys across services; otherwise the client auto-generates one by default.
+This returns the same rich subscription snapshot surfaces by `call_begin` and `checkUsage`, making it safe to cache the response for onboarding flows. Pass `idempotencyKey` in `CreateCustomerOptions` when you need deterministic keys across services; otherwise the client auto-generates one by default. Both `idempotencyKey` (preferred) and `idempotency` (deprecated) are supported.
 
 ### Change a customer's plan
 
@@ -477,6 +478,78 @@ console.log("Balances:", usageStatus.data.balances);
 
 This returns the same rich usage snapshot as `call_begin` (meters, entitlements, subscription details, plan info, balances) but without creating a call record. Use this for dashboard widgets, pre-flight checks, or displaying quota status to users.
 
+### Increment custom meters
+
+Custom meters allow you to track usage beyond standard LLM metrics—ideal for agent actions, document processing, API calls, or any custom usage you need to meter.
+
+```ts
+const result = await usageTap.incrementCustomMeter({
+	customerId: "cust_123",
+	meterSlot: "CUSTOM1",  // or "CUSTOM2"
+	amount: 5,
+	feature: "agent_actions",
+	tags: ["workflow_automation"],
+	metadata: {
+		workflowId: "wf_abc123",
+		actionType: "email_send",
+	},
+});
+
+console.log("Event recorded:", result.data.eventId);
+console.log("Remaining quota:", result.data.meter.remaining);
+console.log("Blocked:", result.data.blocked);
+```
+
+**Parameters:**
+
+- `customerId` (string, required): Customer identifier
+- `meterSlot` ("CUSTOM1" | "CUSTOM2", required): Which custom 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`.
+
+**Use cases:**
+
+```ts
+// Track agent tool invocations
+await usageTap.incrementCustomMeter({
+	customerId: "cust_123",
+	meterSlot: "CUSTOM1",
+	amount: 1,
+	feature: "agent.tool_call",
+	tags: ["web_search"],
+});
+
+// Track document processing (10 pages)
+await usageTap.incrementCustomMeter({
+	customerId: "cust_456",
+	meterSlot: "CUSTOM2",
+	amount: 10,
+	feature: "document.ocr",
+	metadata: { documentId: "doc_789", pages: 10 },
+});
+
+// Track external API calls
+await usageTap.incrementCustomMeter({
+	customerId: "cust_789",
+	meterSlot: "CUSTOM1",
+	amount: 1,
+	feature: "external_api.maps",
+	tags: ["geocoding"],
+});
+```
+
+**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
+
 ## Response envelope (canonical only)
 
 UsageTap responds exclusively with the canonical `{ result, data, correlationId }` envelope for every endpoint. The SDK automatically sends `Accept: application/vnd.usagetap.v1+json`, parses the envelope, and returns strongly typed data structures. Transitional `raw` payloads and the `normalize*` helpers have been removed—`response.data` already contains the canonical shape you should persist or render.

package/dist/adapters/openai.d.cts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { B as BeginCallRequest, U as UsageTapClient, W as WithUsageOptions, V as VendorHints, a as UsageTapSuccessResponse, b as BeginCallResponseBody, E as EndCallRequest } from '../client-nU5xk2pN.cjs';
+import { B as BeginCallRequest, U as UsageTapClient, W as WithUsageOptions, V as VendorHints, a as UsageTapSuccessResponse, b as BeginCallResponseBody, E as EndCallRequest } from '../client-DokYK2Gv.cjs';
 
 interface OpenAIAdapterInit {
     client: OpenAI;

package/dist/adapters/openai.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { B as BeginCallRequest, U as UsageTapClient, W as WithUsageOptions, V as VendorHints, a as UsageTapSuccessResponse, b as BeginCallResponseBody, E as EndCallRequest } from '../client-nU5xk2pN.js';
+import { B as BeginCallRequest, U as UsageTapClient, W as WithUsageOptions, V as VendorHints, a as UsageTapSuccessResponse, b as BeginCallResponseBody, E as EndCallRequest } from '../client-DokYK2Gv.js';
 
 interface OpenAIAdapterInit {
     client: OpenAI;

package/dist/adapters/openrouter.d.cts

@@ -1,6 +1,6 @@
 import { OpenAIAdapter } from './openai.cjs';
 import OpenAI from 'openai';
-import { U as UsageTapClient } from '../client-nU5xk2pN.cjs';
+import { U as UsageTapClient } from '../client-DokYK2Gv.cjs';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/adapters/openrouter.d.ts

@@ -1,6 +1,6 @@
 import { OpenAIAdapter } from './openai.js';
 import OpenAI from 'openai';
-import { U as UsageTapClient } from '../client-nU5xk2pN.js';
+import { U as UsageTapClient } from '../client-DokYK2Gv.js';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/{client-nU5xk2pN.d.cts → client-DokYK2Gv.d.cts}

@@ -26,6 +26,7 @@ interface MeterSummary {
     used: number | null;
     unlimited: boolean;
     ratio: number | null;
+    label?: string;
 }
 type MeterSnapshot = Record<string, MeterSummary>;
 type RemainingRatios = Record<string, number | null | undefined>;
@@ -64,7 +65,20 @@ interface BeginCallRequest {
     requested?: RequestedEntitlements;
     feature?: string;
     tags?: string[];
+    /**
+     * Optional PAYG hold hint (USD) to authorize upfront during call_begin.
+     * When provided, overrides the plan's default hold for this call only.
+     */
+    holdUsd?: number;
+    /**
+     * Idempotency key for safe retries. When omitted, UsageTap derives a key deterministically.
+     * @deprecated Use idempotencyKey instead
+     */
     idempotency?: string;
+    /**
+     * Idempotency key for safe retries. When omitted, UsageTap derives a key deterministically.
+     */
+    idempotencyKey?: string;
     customerName?: string;
     customerEmail?: string;
     stripeCustomerId?: string;
@@ -75,6 +89,8 @@ interface BalanceSummary {
     tokensRemaining?: number;
     searchesRemaining?: number;
     audioSecondsRemaining?: number;
+    customMeter1Remaining?: number;
+    customMeter2Remaining?: number;
 }
 interface PlanSummary {
     id: string | null;
@@ -103,6 +119,12 @@ interface BeginCallResponseBody {
 }
 interface EndCallRequest {
     callId: string;
+    /** Optional customer ID for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    customerId?: string;
+    /** Optional feature for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    feature?: string;
+    /** Optional tags for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    tags?: string[];
     modelUsed?: string;
     inputTokens?: number;
     responseTokens?: number;
@@ -200,6 +222,11 @@ interface UsageTapClientOptions {
      */
     autoIdempotency?: boolean;
     onLog?: (entry: UsageTapLogEntry) => void;
+    /**
+     * Callback invoked when usage metrics are recorded (call_end, custom_meter).
+     * Use this to export metrics to OpenTelemetry or other observability systems.
+     */
+    onUsageMetric?: (event: UsageMetricEvent) => void;
     /**
      * Override the default Authorization header with x-api-key when true.
      */
@@ -283,6 +310,63 @@ interface ChangePlanResponseBody {
     success: boolean;
     subscription: SubscriptionSnapshot;
 }
+type CustomMeterSlot = "CUSTOM1" | "CUSTOM2";
+interface IncrementCustomMeterRequest {
+    customerId: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    feature?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface IncrementCustomMeterOptions extends RequestOptions {
+    correlationId?: string;
+    idempotencyKey?: string;
+}
+interface IncrementCustomMeterResponseBody {
+    success: boolean;
+    eventId: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    meter: MeterSummary;
+    blocked: boolean;
+}
+/**
+ * Event emitted when usage metrics are recorded.
+ * Use with `onUsageMetric` callback to export to OpenTelemetry or other observability systems.
+ */
+interface UsageMetricEvent {
+    /** Type of metric event */
+    type: "call_end" | "custom_meter";
+    /** Timestamp in ISO 8601 format */
+    timestamp: string;
+    /** Customer identifier */
+    customerId: string;
+    /** Unique call identifier (for call_end events) */
+    callId?: string;
+    /** Feature tag */
+    feature?: string;
+    /** Additional tags */
+    tags?: string[];
+    /** Model used for the call */
+    modelUsed?: string;
+    /** Usage metrics */
+    metrics: {
+        inputTokens?: number;
+        responseTokens?: number;
+        cachedTokens?: number;
+        reasoningTokens?: number;
+        searches?: number;
+        audioSeconds?: number;
+        costUsd?: number;
+        /** Custom meter slot (for custom_meter events) */
+        customMeterSlot?: CustomMeterSlot;
+        /** Custom meter amount (for custom_meter events) */
+        customMeterAmount?: number;
+    };
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
 
 declare class UsageTapClient {
     private readonly apiKey;
@@ -294,6 +378,7 @@ declare class UsageTapClient {
     private readonly retryDefaults;
     private readonly idempotencyGenerator;
     private readonly logFn?;
+    private readonly metricFn?;
     private readonly authHeader;
     private readonly autoIdempotency;
     constructor(options: UsageTapClientOptions);
@@ -302,16 +387,18 @@ declare class UsageTapClient {
     checkUsage(request: CheckUsageRequest, options?: CheckUsageOptions): Promise<UsageTapSuccessResponse<CheckUsageResponseBody>>;
     createCustomer(request: CreateCustomerRequest, options?: CreateCustomerOptions): Promise<UsageTapSuccessResponse<CreateCustomerResponseBody>>;
     changePlan(request: ChangePlanRequest, options?: ChangePlanOptions): Promise<UsageTapSuccessResponse<ChangePlanResponseBody>>;
+    incrementCustomMeter(request: IncrementCustomMeterRequest, options?: IncrementCustomMeterOptions): Promise<UsageTapSuccessResponse<IncrementCustomMeterResponseBody>>;
     withUsage<T>(beginRequest: BeginCallRequest, handler: (context: WithUsageContext) => Promise<T>, options?: WithUsageOptions): Promise<T>;
     private request;
     private requestGet;
     private performFetch;
     private composeHeaders;
     private log;
+    private emitUsageMetric;
     private mergeTags;
     private shouldRetry;
     private toHttpError;
     private toApiError;
 }
 
-export { type AllowedEntitlements as A, type BeginCallRequest as B, type CreateCustomerOptions as C, type ModelHints as D, type EndCallRequest as E, type IdempotencyMetadata as I, type LimitType as L, type MeterSummary as M, type PlanSummary as P, type RemainingRatios as R, type SubscriptionSnapshot as S, UsageTapClient as U, type VendorHints as V, type WithUsageOptions as W, type UsageTapSuccessResponse as a, type BeginCallResponseBody as b, type BeginCallOptions as c, type CreateCustomerRequest as d, type CreateCustomerResponseBody as e, type CheckUsageOptions as f, type CheckUsageRequest as g, type CheckUsageResponseBody as h, type ChangePlanOptions as i, type ChangePlanRequest as j, type ChangePlanResponseBody as k, type ChangePlanStrategy as l, type EndCallOptions as m, type EndCallResponseBody as n, type BalanceSummary as o, type EntitlementHints as p, type MeterSnapshot as q, type MeteredUsage as r, type RequestedEntitlements as s, type RetryOptions as t, type UsageTapClientOptions as u, type UsageTapErrorResponse as v, type UsageTapResultEnvelope as w, type UsageTapResultStatus as x, type UsageTapLogEntry as y, type WithUsageContext as z };
+export { type AllowedEntitlements as A, type BeginCallRequest as B, type CreateCustomerOptions as C, type UsageTapResultStatus as D, type EndCallRequest as E, type UsageTapLogEntry as F, type WithUsageContext as G, type ModelHints as H, type IncrementCustomMeterOptions as I, type IdempotencyMetadata as J, type UsageMetricEvent as K, type LimitType as L, type MeterSummary as M, type PlanSummary as P, type RemainingRatios as R, type SubscriptionSnapshot as S, UsageTapClient as U, type VendorHints as V, type WithUsageOptions as W, type UsageTapSuccessResponse as a, type BeginCallResponseBody as b, type BeginCallOptions as c, type CreateCustomerRequest as d, type CreateCustomerResponseBody as e, type CheckUsageOptions as f, type CheckUsageRequest as g, type CheckUsageResponseBody as h, type ChangePlanOptions as i, type ChangePlanRequest as j, type ChangePlanResponseBody as k, type ChangePlanStrategy as l, type IncrementCustomMeterRequest as m, type IncrementCustomMeterResponseBody as n, type CustomMeterSlot as o, type EndCallOptions as p, type EndCallResponseBody as q, type BalanceSummary as r, type EntitlementHints as s, type MeterSnapshot as t, type MeteredUsage as u, type RequestedEntitlements as v, type RetryOptions as w, type UsageTapClientOptions as x, type UsageTapErrorResponse as y, type UsageTapResultEnvelope as z };

package/dist/{client-nU5xk2pN.d.ts → client-DokYK2Gv.d.ts}

@@ -26,6 +26,7 @@ interface MeterSummary {
     used: number | null;
     unlimited: boolean;
     ratio: number | null;
+    label?: string;
 }
 type MeterSnapshot = Record<string, MeterSummary>;
 type RemainingRatios = Record<string, number | null | undefined>;
@@ -64,7 +65,20 @@ interface BeginCallRequest {
     requested?: RequestedEntitlements;
     feature?: string;
     tags?: string[];
+    /**
+     * Optional PAYG hold hint (USD) to authorize upfront during call_begin.
+     * When provided, overrides the plan's default hold for this call only.
+     */
+    holdUsd?: number;
+    /**
+     * Idempotency key for safe retries. When omitted, UsageTap derives a key deterministically.
+     * @deprecated Use idempotencyKey instead
+     */
     idempotency?: string;
+    /**
+     * Idempotency key for safe retries. When omitted, UsageTap derives a key deterministically.
+     */
+    idempotencyKey?: string;
     customerName?: string;
     customerEmail?: string;
     stripeCustomerId?: string;
@@ -75,6 +89,8 @@ interface BalanceSummary {
     tokensRemaining?: number;
     searchesRemaining?: number;
     audioSecondsRemaining?: number;
+    customMeter1Remaining?: number;
+    customMeter2Remaining?: number;
 }
 interface PlanSummary {
     id: string | null;
@@ -103,6 +119,12 @@ interface BeginCallResponseBody {
 }
 interface EndCallRequest {
     callId: string;
+    /** Optional customer ID for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    customerId?: string;
+    /** Optional feature for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    feature?: string;
+    /** Optional tags for metric tracking. Not sent to API, used for onUsageMetric callback. */
+    tags?: string[];
     modelUsed?: string;
     inputTokens?: number;
     responseTokens?: number;
@@ -200,6 +222,11 @@ interface UsageTapClientOptions {
      */
     autoIdempotency?: boolean;
     onLog?: (entry: UsageTapLogEntry) => void;
+    /**
+     * Callback invoked when usage metrics are recorded (call_end, custom_meter).
+     * Use this to export metrics to OpenTelemetry or other observability systems.
+     */
+    onUsageMetric?: (event: UsageMetricEvent) => void;
     /**
      * Override the default Authorization header with x-api-key when true.
      */
@@ -283,6 +310,63 @@ interface ChangePlanResponseBody {
     success: boolean;
     subscription: SubscriptionSnapshot;
 }
+type CustomMeterSlot = "CUSTOM1" | "CUSTOM2";
+interface IncrementCustomMeterRequest {
+    customerId: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    feature?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface IncrementCustomMeterOptions extends RequestOptions {
+    correlationId?: string;
+    idempotencyKey?: string;
+}
+interface IncrementCustomMeterResponseBody {
+    success: boolean;
+    eventId: string;
+    meterSlot: CustomMeterSlot;
+    amount: number;
+    meter: MeterSummary;
+    blocked: boolean;
+}
+/**
+ * Event emitted when usage metrics are recorded.
+ * Use with `onUsageMetric` callback to export to OpenTelemetry or other observability systems.
+ */
+interface UsageMetricEvent {
+    /** Type of metric event */
+    type: "call_end" | "custom_meter";
+    /** Timestamp in ISO 8601 format */
+    timestamp: string;
+    /** Customer identifier */
+    customerId: string;
+    /** Unique call identifier (for call_end events) */
+    callId?: string;
+    /** Feature tag */
+    feature?: string;
+    /** Additional tags */
+    tags?: string[];
+    /** Model used for the call */
+    modelUsed?: string;
+    /** Usage metrics */
+    metrics: {
+        inputTokens?: number;
+        responseTokens?: number;
+        cachedTokens?: number;
+        reasoningTokens?: number;
+        searches?: number;
+        audioSeconds?: number;
+        costUsd?: number;
+        /** Custom meter slot (for custom_meter events) */
+        customMeterSlot?: CustomMeterSlot;
+        /** Custom meter amount (for custom_meter events) */
+        customMeterAmount?: number;
+    };
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
 
 declare class UsageTapClient {
     private readonly apiKey;
@@ -294,6 +378,7 @@ declare class UsageTapClient {
     private readonly retryDefaults;
     private readonly idempotencyGenerator;
     private readonly logFn?;
+    private readonly metricFn?;
     private readonly authHeader;
     private readonly autoIdempotency;
     constructor(options: UsageTapClientOptions);
@@ -302,16 +387,18 @@ declare class UsageTapClient {
     checkUsage(request: CheckUsageRequest, options?: CheckUsageOptions): Promise<UsageTapSuccessResponse<CheckUsageResponseBody>>;
     createCustomer(request: CreateCustomerRequest, options?: CreateCustomerOptions): Promise<UsageTapSuccessResponse<CreateCustomerResponseBody>>;
     changePlan(request: ChangePlanRequest, options?: ChangePlanOptions): Promise<UsageTapSuccessResponse<ChangePlanResponseBody>>;
+    incrementCustomMeter(request: IncrementCustomMeterRequest, options?: IncrementCustomMeterOptions): Promise<UsageTapSuccessResponse<IncrementCustomMeterResponseBody>>;
     withUsage<T>(beginRequest: BeginCallRequest, handler: (context: WithUsageContext) => Promise<T>, options?: WithUsageOptions): Promise<T>;
     private request;
     private requestGet;
     private performFetch;
     private composeHeaders;
     private log;
+    private emitUsageMetric;
     private mergeTags;
     private shouldRetry;
     private toHttpError;
     private toApiError;
 }
 
-export { type AllowedEntitlements as A, type BeginCallRequest as B, type CreateCustomerOptions as C, type ModelHints as D, type EndCallRequest as E, type IdempotencyMetadata as I, type LimitType as L, type MeterSummary as M, type PlanSummary as P, type RemainingRatios as R, type SubscriptionSnapshot as S, UsageTapClient as U, type VendorHints as V, type WithUsageOptions as W, type UsageTapSuccessResponse as a, type BeginCallResponseBody as b, type BeginCallOptions as c, type CreateCustomerRequest as d, type CreateCustomerResponseBody as e, type CheckUsageOptions as f, type CheckUsageRequest as g, type CheckUsageResponseBody as h, type ChangePlanOptions as i, type ChangePlanRequest as j, type ChangePlanResponseBody as k, type ChangePlanStrategy as l, type EndCallOptions as m, type EndCallResponseBody as n, type BalanceSummary as o, type EntitlementHints as p, type MeterSnapshot as q, type MeteredUsage as r, type RequestedEntitlements as s, type RetryOptions as t, type UsageTapClientOptions as u, type UsageTapErrorResponse as v, type UsageTapResultEnvelope as w, type UsageTapResultStatus as x, type UsageTapLogEntry as y, type WithUsageContext as z };
+export { type AllowedEntitlements as A, type BeginCallRequest as B, type CreateCustomerOptions as C, type UsageTapResultStatus as D, type EndCallRequest as E, type UsageTapLogEntry as F, type WithUsageContext as G, type ModelHints as H, type IncrementCustomMeterOptions as I, type IdempotencyMetadata as J, type UsageMetricEvent as K, type LimitType as L, type MeterSummary as M, type PlanSummary as P, type RemainingRatios as R, type SubscriptionSnapshot as S, UsageTapClient as U, type VendorHints as V, type WithUsageOptions as W, type UsageTapSuccessResponse as a, type BeginCallResponseBody as b, type BeginCallOptions as c, type CreateCustomerRequest as d, type CreateCustomerResponseBody as e, type CheckUsageOptions as f, type CheckUsageRequest as g, type CheckUsageResponseBody as h, type ChangePlanOptions as i, type ChangePlanRequest as j, type ChangePlanResponseBody as k, type ChangePlanStrategy as l, type IncrementCustomMeterRequest as m, type IncrementCustomMeterResponseBody as n, type CustomMeterSlot as o, type EndCallOptions as p, type EndCallResponseBody as q, type BalanceSummary as r, type EntitlementHints as s, type MeterSnapshot as t, type MeteredUsage as u, type RequestedEntitlements as v, type RetryOptions as w, type UsageTapClientOptions as x, type UsageTapErrorResponse as y, type UsageTapResultEnvelope as z };