@usagetap/sdk 0.7.0 → 0.8.0

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-BzbMP-fp.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-BzbMP-fp.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-BzbMP-fp.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-BzbMP-fp.js';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/{client-nU5xk2pN.d.cts → client-BzbMP-fp.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,15 @@ interface BeginCallRequest {
     requested?: RequestedEntitlements;
     feature?: string;
     tags?: string[];
+    /**
+     * 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 +84,8 @@ interface BalanceSummary {
     tokensRemaining?: number;
     searchesRemaining?: number;
     audioSecondsRemaining?: number;
+    customMeter1Remaining?: number;
+    customMeter2Remaining?: number;
 }
 interface PlanSummary {
     id: string | null;
@@ -283,6 +294,27 @@ 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;
+}
 
 declare class UsageTapClient {
     private readonly apiKey;
@@ -302,6 +334,7 @@ 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;
@@ -314,4 +347,4 @@ declare class UsageTapClient {
     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 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-BzbMP-fp.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,15 @@ interface BeginCallRequest {
     requested?: RequestedEntitlements;
     feature?: string;
     tags?: string[];
+    /**
+     * 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 +84,8 @@ interface BalanceSummary {
     tokensRemaining?: number;
     searchesRemaining?: number;
     audioSecondsRemaining?: number;
+    customMeter1Remaining?: number;
+    customMeter2Remaining?: number;
 }
 interface PlanSummary {
     id: string | null;
@@ -283,6 +294,27 @@ 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;
+}
 
 declare class UsageTapClient {
     private readonly apiKey;
@@ -302,6 +334,7 @@ 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;
@@ -314,4 +347,4 @@ declare class UsageTapClient {
     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 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/express/index.d.cts

@@ -1,6 +1,6 @@
 import OpenAI from 'openai';
 import { Request, Response, NextFunction } from 'express';
-import { U as UsageTapClient } from '../client-nU5xk2pN.cjs';
+import { U as UsageTapClient } from '../client-BzbMP-fp.cjs';
 import { WrapOpenAIContext, WrapOpenAIOptions, wrapOpenAI, pipeToResponse } from '../adapters/openai.cjs';
 
 interface ExpressUsageTapContext {

package/dist/express/index.d.ts

@@ -1,6 +1,6 @@
 import OpenAI from 'openai';
 import { Request, Response, NextFunction } from 'express';
-import { U as UsageTapClient } from '../client-nU5xk2pN.js';
+import { U as UsageTapClient } from '../client-BzbMP-fp.js';
 import { WrapOpenAIContext, WrapOpenAIOptions, wrapOpenAI, pipeToResponse } from '../adapters/openai.js';
 
 interface ExpressUsageTapContext {

package/dist/index.cjs

@@ -121,6 +121,7 @@ var CALL_END_PATH = "call_end";
 var CHECK_USAGE_PATH = "customers/{customerId}/usage";
 var CREATE_CUSTOMER_PATH = "customers";
 var CHANGE_PLAN_PATH = "customers/{customerId}/change_plan";
+var INCREMENT_CUSTOM_METER_PATH = "custom_meter";
 var AUTH_HEADER = "authorization";
 var API_KEY_HEADER = "x-api-key";
 var CORRELATION_HEADER = "x-usage-correlation-id";
@@ -128,7 +129,7 @@ var IDEMPOTENCY_HEADER = "idempotency-key";
 var SDK_HEADER = "x-usage-sdk";
 var USER_AGENT = "UsageTapClient";
 var CANONICAL_MEDIA_TYPE = "application/vnd.usagetap.v1+json";
-var SDK_VERSION = "0.7.0" ;
+var SDK_VERSION = "0.8.0" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -188,13 +189,14 @@ var UsageTapClient = class {
     this.autoIdempotency = options.autoIdempotency ?? true;
   }
   async beginCall(request, options = {}) {
-    const idempotencyKey = request.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
+    const idempotencyKey = request.idempotencyKey ?? request.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
     const payload = {
       ...request,
       feature: request.feature ?? this.defaultFeature,
       tags: this.mergeTags(request.tags)
     };
     if (idempotencyKey) {
+      payload.idempotencyKey = idempotencyKey;
       payload.idempotency = idempotencyKey;
     }
     const response = await this.request(
@@ -289,9 +291,59 @@ var UsageTapClient = class {
     );
     return response;
   }
+  async incrementCustomMeter(request, options = {}) {
+    if (!request?.customerId) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "incrementCustomMeter requires customerId"
+      );
+    }
+    if (!request?.meterSlot) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "incrementCustomMeter requires meterSlot"
+      );
+    }
+    if (!["CUSTOM1", "CUSTOM2"].includes(request.meterSlot)) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "meterSlot must be CUSTOM1 or CUSTOM2"
+      );
+    }
+    if (typeof request.amount !== "number" || !Number.isFinite(request.amount) || request.amount <= 0) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "incrementCustomMeter requires a positive numeric amount"
+      );
+    }
+    const idempotencyKey = options.idempotencyKey ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
+    const payload = {
+      customerId: request.customerId,
+      meterSlot: request.meterSlot,
+      amount: request.amount
+    };
+    if (request.feature) {
+      payload.feature = request.feature;
+    }
+    if (request.tags && request.tags.length > 0) {
+      payload.tags = request.tags;
+    }
+    if (request.metadata) {
+      payload.metadata = request.metadata;
+    }
+    const response = await this.request(
+      INCREMENT_CUSTOM_METER_PATH,
+      payload,
+      {
+        ...options,
+        idempotencyKey
+      }
+    );
+    return response;
+  }
   async withUsage(beginRequest, handler, options = {}) {
-    const idempotencyKey = beginRequest.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
-    const beginPayload = idempotencyKey ? { ...beginRequest, idempotency: idempotencyKey } : { ...beginRequest };
+    const idempotencyKey = beginRequest.idempotencyKey ?? beginRequest.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
+    const beginPayload = idempotencyKey ? { ...beginRequest, idempotencyKey, idempotency: idempotencyKey } : { ...beginRequest };
     const beginResponse = await this.beginCall(beginPayload, options);
     let usage = {};
     const initialStripeCustomerId = typeof beginResponse.data.stripeCustomerId === "string" ? beginResponse.data.stripeCustomerId : typeof beginRequest.stripeCustomerId === "string" ? beginRequest.stripeCustomerId : void 0;