@usagetap/sdk 0.1.0 → 0.2.1

package/README.md

@@ -385,7 +385,8 @@ const { begin, end, vendor, endUsage } = envelope.data;
 
 Key exports from `@usagetap/sdk`:
 
-- `UsageTapClient` – minimal HTTP client for `call_begin` and `call_end`.
+- `UsageTapClient` – minimal HTTP client for `call_begin`, `call_end`, and `checkUsage`.
+- `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).
 - `withUsage` / `withUsageMiddleware` – Express middleware for server-side usage tracking (requires `express` peer dependency).
@@ -396,6 +397,21 @@ Key exports from `@usagetap/sdk`:
 
 All helpers are designed for server runtimes. Use `UsageTapClient` with `allowBrowser: true` only for sandbox/test scenarios.
 
+### 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()`:
+
+```ts
+const usageStatus = await usageTap.checkUsage({ customerId: "cust_123" });
+
+console.log("Meters:", usageStatus.data.meters);
+console.log("Allowed:", usageStatus.data.allowed);
+console.log("Plan:", usageStatus.data.plan);
+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.
+
 ## 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.
@@ -516,6 +532,29 @@ UsageTap responds exclusively with the canonical `{ result, data, correlationId
 
 `metered` is derived from the raw Dynamo deltas. Additional meters (audio seconds, reasoning tokens, balances) will populate in later phases without breaking the contract.
 
+### Premium detection and override
+
+UsageTap automatically determines whether a call is premium based on the model's output token pricing:
+- If the output token price exceeds **$4.00 per million tokens**, the call is classified as premium
+- Otherwise, it's classified as standard
+
+You can explicitly override this detection by passing `isPremium` in your `call_end` request:
+
+```ts
+await usageTap.endCall({
+  callId: begin.data.callId,
+  modelUsed: "custom-model-v2",
+  inputTokens: 100,
+  responseTokens: 200,
+  isPremium: true,  // Explicitly mark this as a premium call
+});
+```
+
+This is useful when:
+- You're using custom models that aren't in UsageTap's pricing database
+- You want to enforce specific billing tiers regardless of pricing
+- You're implementing your own tier classification logic
+
 ### Raw fetch integrations
 
 Prefer `UsageTapClient` whenever possible—it handles retries, headers, and idempotency for you. If you still need to work with `fetch` directly, remember to request the canonical media type and consume the envelope shape directly:

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, Y as OpenAIRequestContext, Z as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, _ 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-CKyw08rB.cjs';
+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';

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, Y as OpenAIRequestContext, Z as OpenAIStreamCallResult, f as OpenAIStreamParams, g as OpenAIStreamResult, S as StreamMode, l as StreamOpenAIRouteOptions, h as StreamToResponseOptions, _ 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-CKyw08rB.js';
+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';

package/dist/adapters/openrouter.d.cts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-CKyw08rB.cjs';
+import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-CeptbEGH.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-CKyw08rB.js';
+import { U as UsageTapClient, O as OpenAIAdapter } from '../openai-CeptbEGH.js';
 
 interface OpenRouterAdapterInit {
     client: OpenAI;

package/dist/index.cjs

@@ -118,6 +118,7 @@ async function runWithRetry(operation, options, shouldRetry, onSchedule, signal)
 // src/client.ts
 var CALL_BEGIN_PATH = "call_begin";
 var CALL_END_PATH = "call_end";
+var CHECK_USAGE_PATH = "customers/{customerId}/usage";
 var AUTH_HEADER = "authorization";
 var API_KEY_HEADER = "x-api-key";
 var CORRELATION_HEADER = "x-usage-correlation-id";
@@ -125,7 +126,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.1.0" ;
+var SDK_VERSION = "0.2.1" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
   apiKey;
@@ -219,6 +220,23 @@ var UsageTapClient = class {
     );
     return response;
   }
+  async checkUsage(request, options = {}) {
+    if (!request?.customerId) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "checkUsage requires customerId"
+      );
+    }
+    const path = CHECK_USAGE_PATH.replace(
+      "{customerId}",
+      encodeURIComponent(request.customerId)
+    );
+    const response = await this.requestGet(
+      path,
+      options
+    );
+    return response;
+  }
   async withUsage(beginRequest, handler, options = {}) {
     const idempotencyKey = beginRequest.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
     const beginPayload = idempotencyKey ? { ...beginRequest, idempotency: idempotencyKey } : { ...beginRequest };
@@ -338,6 +356,62 @@ var UsageTapClient = class {
       throw error;
     });
   }
+  async requestGet(path, options) {
+    const url = new URL(path, this.baseUrl).toString();
+    const headers = this.composeHeaders(void 0, options);
+    const resolvedRetry = resolveRetryOptions(
+      this.retryDefaults,
+      options.retries
+    );
+    const startTime = () => typeof performance !== "undefined" ? performance.now() : Date.now();
+    return runWithRetry(
+      async (attempt) => {
+        const startedAt = startTime();
+        this.log({
+          event: "request:start",
+          path,
+          attempt,
+          correlationId: options.correlationId
+        });
+        const response = await this.performFetch({
+          url,
+          method: "GET",
+          headers,
+          signal: options.signal
+        });
+        this.log({
+          event: "request:success",
+          path,
+          attempt,
+          correlationId: response.correlationId,
+          elapsedMs: startTime() - startedAt
+        });
+        return response;
+      },
+      resolvedRetry,
+      (error) => this.shouldRetry(error),
+      (attempt, delayMs, error) => {
+        this.log({
+          event: "retry:scheduled",
+          path,
+          attempt,
+          correlationId: options.correlationId,
+          error,
+          elapsedMs: delayMs
+        });
+      },
+      options.signal
+    ).catch((error) => {
+      this.log({
+        event: "retry:exhausted",
+        path,
+        attempt: resolvedRetry.maxAttempts,
+        correlationId: options.correlationId,
+        error
+      });
+      throw error;
+    });
+  }
   async performFetch(init) {
     let response;
     try {