@usagetap/sdk 0.2.1 → 0.3.0

package/README.md

@@ -23,6 +23,12 @@ const usageTap = new UsageTapClient({
 
 const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
 
+await usageTap.createCustomer({
+	customerId: "cust_123",
+	customerFriendlyName: "Acme AI",
+	customerEmail: "billing@acme.ai",
+});
+
 function selectCapabilities(allowed: {
 	standard?: boolean;
 	premium?: boolean;
@@ -385,7 +391,8 @@ const { begin, end, vendor, endUsage } = envelope.data;
 
 Key exports from `@usagetap/sdk`:
 
-- `UsageTapClient` – minimal HTTP client for `call_begin`, `call_end`, and `checkUsage`.
+- `UsageTapClient` – minimal HTTP client for `createCustomer`, `call_begin`, `call_end`, and `checkUsage`.
+- `createCustomer` – idempotently ensure a customer subscription exists before starting a call.
 - `checkUsage` – lightweight method to query current usage status without creating a call session.
 - `wrapOpenAI` – wraps an OpenAI client instance with automatic begin/end handling.
 - `wrapFetch` – wraps a fetch function to automatically instrument OpenAI API calls (minimal integration).
@@ -397,6 +404,25 @@ Key exports from `@usagetap/sdk`:
 
 All helpers are designed for server runtimes. Use `UsageTapClient` with `allowBrowser: true` only for sandbox/test scenarios.
 
+### Ensure a customer subscription exists
+
+Run `createCustomer` before you invoke `call_begin` (or higher-level helpers) to guarantee the customer has an active subscription. The endpoint is fully idempotent—repeat calls return the existing snapshot and set `newCustomer: false`:
+
+```ts
+const snapshot = await usageTap.createCustomer({
+	customerId: "cust_123",
+	customerFriendlyName: "Acme AI",
+	customerEmail: "billing@acme.ai",
+	stripeCustomerId: "cus_123",
+});
+
+console.log("New customer?", snapshot.data.newCustomer);
+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.
+
 ### Check usage without creating a call
 
 When you need to display current quota status, plan details, or remaining balances without tracking a vendor call, use `checkUsage()`:

package/dist/adapters/openai.d.cts

@@ -1,2 +1,2 @@
 import 'openai';
-export { N as NodeResponseLike, O as OpenAIAdapter, b as OpenAIAdapterInit, d as OpenAIInvokeParams, e as OpenAIInvokeResult, $ as OpenAIRequestContext, a0 as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, a1 as UsageTapStream, i as WrapOpenAICallOptions, W as WrapOpenAIContext, a as WrapOpenAIOptions, j as WrapOpenAIResponseCallOptions, k as WrappedOpenAI, c as createOpenAIAdapter, p as pipeToResponse, s as streamOpenAIRoute, t as toNextResponse, w as wrapOpenAI } from '../openai-CeptbEGH.cjs';
+export { N as NodeResponseLike, O as OpenAIAdapter, b as OpenAIAdapterInit, d as OpenAIInvokeParams, e as OpenAIInvokeResult, a2 as OpenAIRequestContext, a3 as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, a4 as UsageTapStream, i as WrapOpenAICallOptions, W as WrapOpenAIContext, a as WrapOpenAIOptions, j as WrapOpenAIResponseCallOptions, k as WrappedOpenAI, c as createOpenAIAdapter, p as pipeToResponse, s as streamOpenAIRoute, t as toNextResponse, w as wrapOpenAI } from '../openai-Ch7hN2vD.cjs';

package/dist/adapters/openai.d.ts

@@ -1,2 +1,2 @@
 import 'openai';
-export { N as NodeResponseLike, O as OpenAIAdapter, b as OpenAIAdapterInit, d as OpenAIInvokeParams, e as OpenAIInvokeResult, $ as OpenAIRequestContext, a0 as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, a1 as UsageTapStream, i as WrapOpenAICallOptions, W as WrapOpenAIContext, a as WrapOpenAIOptions, j as WrapOpenAIResponseCallOptions, k as WrappedOpenAI, c as createOpenAIAdapter, p as pipeToResponse, s as streamOpenAIRoute, t as toNextResponse, w as wrapOpenAI } from '../openai-CeptbEGH.js';
+export { N as NodeResponseLike, O as OpenAIAdapter, b as OpenAIAdapterInit, d as OpenAIInvokeParams, e as OpenAIInvokeResult, a2 as OpenAIRequestContext, a3 as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, a4 as UsageTapStream, i as WrapOpenAICallOptions, W as WrapOpenAIContext, a as WrapOpenAIOptions, j as WrapOpenAIResponseCallOptions, k as WrappedOpenAI, c as createOpenAIAdapter, p as pipeToResponse, s as streamOpenAIRoute, t as toNextResponse, w as wrapOpenAI } from '../openai-Ch7hN2vD.js';

package/dist/adapters/openrouter.d.cts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-CeptbEGH.cjs';
+import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-Ch7hN2vD.cjs';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/adapters/openrouter.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-CeptbEGH.js';
+import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-Ch7hN2vD.js';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/index.cjs

@@ -119,6 +119,7 @@ async function runWithRetry(operation, options, shouldRetry, onSchedule, signal)
 var CALL_BEGIN_PATH = "call_begin";
 var CALL_END_PATH = "call_end";
 var CHECK_USAGE_PATH = "customers/{customerId}/usage";
+var CREATE_CUSTOMER_PATH = "customers";
 var AUTH_HEADER = "authorization";
 var API_KEY_HEADER = "x-api-key";
 var CORRELATION_HEADER = "x-usage-correlation-id";
@@ -126,7 +127,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.2.1" ;
+var SDK_VERSION = "0.3.0" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -237,6 +238,24 @@ var UsageTapClient = class {
     );
     return response;
   }
+  async createCustomer(request, options = {}) {
+    if (!request?.customerId) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "createCustomer requires customerId"
+      );
+    }
+    const idempotencyKey = options.idempotencyKey ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
+    const response = await this.request(
+      CREATE_CUSTOMER_PATH,
+      { ...request },
+      {
+        ...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 };