@usebillow/sdk 0.5.0

package/dist/ingestion.d.ts

@@ -0,0 +1,182 @@
+import { Billow } from './index.js';
+import './billing-C4RIMgH_.js';
+import 'zod';
+import './billing-status-BZQN_gm7.js';
+import './status.js';
+import './credits-C3Fe3TO0.js';
+
+/**
+ * Auto-metering (PRD-16): ingestion strategies that call billow's `track()` for you,
+ * so you never hand-instrument usage.
+ *
+ * Two layers:
+ *   1. A generic primitive — {@link createUsageMeter} + {@link meterFunction} — a
+ *      non-blocking, buffered, idempotent dispatcher you can point at ANY usage
+ *      source (an S3 upload, a job run, a DB write).
+ *   2. LLM strategies built on it — {@link meterOpenAI} (OpenAI-compatible clients)
+ *      and {@link meterAIResult} (Vercel AI SDK) that auto-count prompt+completion
+ *      tokens from the provider's own response (never re-tokenizing).
+ *
+ * Posture (every strategy): SERVER-SIDE ONLY — a browser can't be trusted to
+ * self-report usage — and NON-BLOCKING: metering is a side effect that can never
+ * delay or break the wrapped call. A failed `track()` buffers and retries under an
+ * idempotency key; if it ultimately fails it is dropped (via `onError`), never thrown.
+ *
+ *   import { Billow } from "@usebillow/sdk";
+ *   import { createUsageMeter, meterOpenAI } from "@usebillow/sdk/ingestion";
+ *
+ *   const billow = new Billow(process.env.BILLOW_SECRET_KEY!);
+ *   const meter = createUsageMeter(billow);
+ *   const openai = meterOpenAI(new OpenAI(), {
+ *     meter,
+ *     feature: "tokens",
+ *     customer: (params) => String(params.user), // your billow customer id
+ *   });
+ *   // use `openai` exactly as before — every completion auto-meters its tokens.
+ */
+
+/** One usage event handed to `track()`. Mirrors {@link Billow.track}'s input. */
+interface UsageRecord {
+    customerId: string;
+    featureId: string;
+    /** Units to record (the engine defaults to 1). */
+    value?: number;
+    /** Event properties for meter filters / property-based aggregations. */
+    properties?: Record<string, string | number>;
+    /**
+     * Dedup key. Auto-generated per record when omitted, so a retried dispatch is a
+     * no-op — set it yourself to dedupe across process restarts.
+     */
+    idempotencyKey?: string;
+}
+/** The minimal client the meter needs — the real {@link Billow} satisfies it. */
+type TrackClient = Pick<Billow, "track">;
+interface MeterOptions {
+    /** Max dispatch attempts for one record before it's dropped (default 5). */
+    maxAttempts?: number;
+    /** Base retry backoff in ms; doubles each attempt (default 250). */
+    retryBaseMs?: number;
+    /** Called once when a record is permanently dropped after exhausting retries. */
+    onError?: (error: unknown, record: UsageRecord) => void;
+}
+/**
+ * A buffered, non-blocking dispatcher to `track()`. `record()` returns immediately
+ * and never throws; delivery (with retries under an idempotency key) happens in the
+ * background. Call {@link UsageMeter.flush} before a serverless handler returns so
+ * pending records aren't lost when the process freezes.
+ */
+interface UsageMeter {
+    /** Enqueue a usage event. Returns immediately, never throws. */
+    record(record: UsageRecord): void;
+    /**
+     * Enqueue a usage event whose record resolves LATER (e.g. a streamed response
+     * whose token totals arrive as a promise). Registers the pending work immediately
+     * so {@link UsageMeter.flush} awaits it — a `null` resolution or a rejected source
+     * is dropped. Returns immediately, never throws.
+     */
+    recordAsync(source: Promise<UsageRecord | null>): void;
+    /** Resolve once every buffered dispatch has settled (delivered or dropped). */
+    flush(): Promise<void>;
+    /** Records still in flight (queued or retrying). */
+    readonly pending: number;
+}
+/** Build a {@link UsageMeter} bound to a billow client (or any `{ track }`). */
+declare function createUsageMeter(client: TrackClient, options?: MeterOptions): UsageMeter;
+/**
+ * Derive a usage record from a completed call. Return `null` to skip metering it
+ * (e.g. a cache hit with no billable usage). Receives the resolved result and the
+ * original call arguments.
+ */
+type UsageExtractor<A extends unknown[], R> = (result: R, args: A) => UsageRecord | null;
+/**
+ * Wrap any async function so each successful call auto-records usage via `meter` —
+ * the generic ingestion primitive. Point it at any source by supplying an `extract`.
+ * Metering runs AFTER the call resolves and never blocks it; an extractor that
+ * throws is swallowed. If the wrapped call itself rejects, nothing is recorded and
+ * the error propagates unchanged.
+ */
+declare function meterFunction<A extends unknown[], R>(fn: (...args: A) => Promise<R>, meter: UsageMeter, extract: UsageExtractor<A, R>): (...args: A) => Promise<R>;
+/**
+ * Yield every value of `source` straight through to the consumer while calling
+ * `onValue` for each and `onDone` when iteration finishes (including an early
+ * `break`/`return` — it runs in a `finally`). Taps a stream WITHOUT consuming it:
+ * the caller still receives every chunk. Tap callbacks that throw are swallowed so
+ * they can't break the stream.
+ */
+declare function tapAsyncIterable<T>(source: AsyncIterable<T>, taps: {
+    onValue?: (value: T) => void;
+    onDone?: () => void;
+}): AsyncGenerator<T>;
+/** Normalized token counts, whatever the provider's field naming. */
+interface TokenCounts {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/** Which token count a meter records as its `value` (default `"total"`). */
+type TokenCount = "total" | "prompt" | "completion";
+/**
+ * Read token counts from a provider usage object, accepting OpenAI (`prompt_tokens`
+ * / `completion_tokens` / `total_tokens`), Vercel AI SDK v4 (`promptTokens` / …) and
+ * v5 (`inputTokens` / `outputTokens`) shapes. Returns `null` when no token fields
+ * are present. `totalTokens` is derived from prompt+completion when not supplied.
+ */
+declare function normalizeTokenUsage(usage: unknown): TokenCounts | null;
+/** A value supplied directly, or resolved from a call's params. */
+type Resolvable<T, P> = T | ((params: P) => T);
+interface MeterLLMOptions<P = unknown> {
+    /** The buffered meter that dispatches to `track()`. */
+    meter: UsageMeter;
+    /** The metered feature (token meter) id — static, or resolved per call. */
+    feature: Resolvable<string, P>;
+    /**
+     * The billow customer to bill. Static for single-tenant, or resolved per call
+     * (e.g. from the OpenAI `user` param) for multi-tenant. Returning `null`/`undefined`
+     * skips metering that call — there's no customer to attribute it to.
+     */
+    customer: Resolvable<string | null | undefined, P>;
+    /** Which token count to record as the meter value (default `"total"`). */
+    count?: TokenCount;
+    /** Extra event properties merged onto each record (`model` is added automatically). */
+    properties?: (params: P, tokens: TokenCounts) => Record<string, string | number>;
+}
+/**
+ * Wrap an OpenAI-compatible client so every `chat.completions.create` call
+ * auto-meters its token usage. Returns a proxy of the SAME type — use it exactly as
+ * before; every other property/method passes straight through untouched.
+ *
+ * Reads the token count from the provider's own response (no re-tokenizing), for
+ * both blocking and streaming calls. For a STREAMED call, pass
+ * `stream_options: { include_usage: true }` so the final chunk carries usage —
+ * otherwise a streamed call can't be metered (billow never mutates your request).
+ *
+ * A streamed response is metered when consumed the standard way: `await` the call,
+ * then `for await` the stream. The `Stream` helpers (`.tee()`, `.toReadableStream()`)
+ * and the un-awaited `APIPromise` helpers (`.withResponse()`, `.asResponse()`) are
+ * PRESERVED (they keep working), but consuming through them bypasses the iteration
+ * tap, so those calls are not token-metered.
+ *
+ * Works with any client exposing `chat.completions.create` returning a `.usage`
+ * shape: OpenAI, Azure OpenAI, Together, Groq, OpenRouter, and other compatibles.
+ *
+ *   const openai = meterOpenAI(new OpenAI(), { meter, feature: "tokens", customer });
+ *   const res = await openai.chat.completions.create({ model, messages }); // metered
+ */
+declare function meterOpenAI<T extends object>(client: T, options: MeterLLMOptions<Record<string, unknown>>): T;
+/**
+ * Meter a Vercel AI SDK result (the object `generateText`/`streamText` resolves to).
+ * Reads `result.usage` — an object (`generateText`) or a Promise (`streamText`) — and
+ * records the token count, non-blocking. Never touches `result.textStream`, so a
+ * streamed response is delivered to your consumer untouched. Accepts AI SDK v4
+ * (`promptTokens`/`completionTokens`) and v5 (`inputTokens`/`outputTokens`) shapes.
+ *
+ *   const result = streamText({ model, prompt });
+ *   meterAIResult(result, { meter, feature: "tokens", customer: customerId });
+ *   return result.toDataStreamResponse();
+ */
+declare function meterAIResult(result: {
+    usage?: unknown;
+    response?: unknown;
+}, options: MeterLLMOptions<void>): void;
+
+export { type MeterLLMOptions, type MeterOptions, type TokenCount, type TokenCounts, type TrackClient, type UsageExtractor, type UsageMeter, type UsageRecord, createUsageMeter, meterAIResult, meterFunction, meterOpenAI, normalizeTokenUsage, tapAsyncIterable };

package/dist/ingestion.js

@@ -0,0 +1,252 @@
+// src/ingestion.ts
+var DEFAULT_MAX_ATTEMPTS = 5;
+var DEFAULT_RETRY_BASE_MS = 250;
+function newIdempotencyKey() {
+  return crypto.randomUUID();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createUsageMeter(client, options = {}) {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+  const retryBaseMs = Math.max(0, options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS);
+  const inFlight = /* @__PURE__ */ new Set();
+  async function dispatch(record) {
+    const input = {
+      ...record,
+      idempotencyKey: record.idempotencyKey ?? newIdempotencyKey()
+    };
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await client.track(input);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) await sleep(retryBaseMs * 2 ** (attempt - 1));
+      }
+    }
+    try {
+      options.onError?.(lastError, input);
+    } catch {
+    }
+  }
+  function track(work) {
+    const p = work.finally(() => {
+      inFlight.delete(p);
+    });
+    inFlight.add(p);
+  }
+  return {
+    record(record) {
+      track(dispatch(record));
+    },
+    recordAsync(source) {
+      track(
+        source.then(
+          (record) => record ? dispatch(record) : void 0,
+          () => void 0
+        )
+      );
+    },
+    flush() {
+      return Promise.all([...inFlight]).then(() => void 0);
+    },
+    get pending() {
+      return inFlight.size;
+    }
+  };
+}
+function meterFunction(fn, meter, extract) {
+  return async (...args) => {
+    const result = await fn(...args);
+    try {
+      const record = extract(result, args);
+      if (record) meter.record(record);
+    } catch {
+    }
+    return result;
+  };
+}
+async function* tapAsyncIterable(source, taps) {
+  try {
+    for await (const value of source) {
+      try {
+        taps.onValue?.(value);
+      } catch {
+      }
+      yield value;
+    }
+  } finally {
+    try {
+      taps.onDone?.();
+    } catch {
+    }
+  }
+}
+function firstNumber(...values) {
+  for (const v of values) if (typeof v === "number" && Number.isFinite(v)) return v;
+  return null;
+}
+function normalizeTokenUsage(usage) {
+  if (typeof usage !== "object" || usage === null) return null;
+  const u = usage;
+  const prompt = firstNumber(u.prompt_tokens, u.promptTokens, u.inputTokens);
+  const completion = firstNumber(u.completion_tokens, u.completionTokens, u.outputTokens);
+  const total = firstNumber(u.total_tokens, u.totalTokens);
+  if (prompt === null && completion === null && total === null) return null;
+  const promptTokens = prompt ?? 0;
+  const completionTokens = completion ?? 0;
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens: total ?? promptTokens + completionTokens
+  };
+}
+function pickCount(counts, which) {
+  if (which === "prompt") return counts.promptTokens;
+  if (which === "completion") return counts.completionTokens;
+  return counts.totalTokens;
+}
+function resolveValue(r, params) {
+  return typeof r === "function" ? r(params) : r;
+}
+function buildTokenRecord(options, params, usage, model) {
+  const counts = normalizeTokenUsage(usage);
+  if (!counts) return null;
+  try {
+    const customerId = resolveValue(options.customer, params);
+    if (!customerId) return null;
+    const properties = {
+      tokens_prompt: counts.promptTokens,
+      tokens_completion: counts.completionTokens,
+      tokens_total: counts.totalTokens,
+      ...typeof model === "string" ? { model } : {},
+      ...options.properties?.(params, counts)
+    };
+    return {
+      customerId,
+      featureId: resolveValue(options.feature, params),
+      value: pickCount(counts, options.count ?? "total"),
+      properties
+    };
+  } catch {
+    return null;
+  }
+}
+function isPromiseLike(v) {
+  return (typeof v === "object" || typeof v === "function") && v !== null && typeof v.then === "function";
+}
+function wrapOpenAICreate(create, thisArg, options) {
+  return (params, ...rest) => {
+    const returned = Reflect.apply(create, thisArg, [params, ...rest]);
+    if (!isPromiseLike(returned)) return returned;
+    if (params.stream === true) {
+      return proxyResolved(
+        returned,
+        (stream) => typeof stream === "object" && stream !== null ? proxyAsyncIterable(
+          stream,
+          () => tapOpenAIStream(stream, params, options)
+        ) : stream
+      );
+    }
+    options.meter.recordAsync(returned.then((resp) => completionRecord(resp, params, options)));
+    return returned;
+  };
+}
+function completionRecord(resp, params, options) {
+  if (typeof resp !== "object" || resp === null) return null;
+  const r = resp;
+  return buildTokenRecord(options, params, r.usage, r.model);
+}
+function proxyResolved(source, map) {
+  const mappedThen = (onF, onR) => source.then((v) => onF ? onF(map(v)) : map(v), onR);
+  return new Proxy(source, {
+    get(target, prop) {
+      if (prop === "then") return mappedThen;
+      if (prop === "catch") return (onR) => mappedThen(void 0, onR);
+      if (prop === "finally") {
+        return (cb) => mappedThen(
+          (v) => {
+            cb?.();
+            return v;
+          },
+          (e) => {
+            cb?.();
+            throw e;
+          }
+        );
+      }
+      const value = Reflect.get(target, prop);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function proxyAsyncIterable(source, makeIterator) {
+  return new Proxy(source, {
+    get(target, prop) {
+      if (prop === Symbol.asyncIterator) return makeIterator;
+      const value = Reflect.get(target, prop);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function meterStream(stream, params, options, reduce) {
+  const acc = {};
+  return tapAsyncIterable(stream, {
+    onValue: (chunk) => reduce(chunk, acc),
+    onDone: () => {
+      const record = buildTokenRecord(options, params, acc.usage, acc.model);
+      if (record) options.meter.record(record);
+    }
+  });
+}
+function tapOpenAIStream(stream, params, options) {
+  return meterStream(stream, params, options, (chunk, acc) => {
+    if (typeof chunk !== "object" || chunk === null) return;
+    const c = chunk;
+    if (c.usage) acc.usage = c.usage;
+    if (c.model && acc.model === void 0) acc.model = c.model;
+  });
+}
+function meterOpenAI(client, options) {
+  const root = client;
+  const completions = root.chat?.completions;
+  const create = completions?.create;
+  if (typeof create !== "function" || !completions) {
+    throw new TypeError("meterOpenAI: expected client.chat.completions.create to be a function");
+  }
+  const wrapped = wrapOpenAICreate(create, completions, options);
+  return replaceCreate(client, wrapped);
+}
+function replaceCreate(client, wrapped) {
+  const root = client;
+  const completionsProxy = new Proxy(root.chat.completions, {
+    get: (t, p, r) => p === "create" ? wrapped : Reflect.get(t, p, r)
+  });
+  const chatProxy = new Proxy(root.chat, {
+    get: (t, p, r) => p === "completions" ? completionsProxy : Reflect.get(t, p, r)
+  });
+  return new Proxy(client, {
+    get: (t, p, r) => p === "chat" ? chatProxy : Reflect.get(t, p, r)
+  });
+}
+function meterAIResult(result, options) {
+  const model = extractAIModel(result.response);
+  const usage = result.usage;
+  if (isPromiseLike(usage)) {
+    options.meter.recordAsync(usage.then((u) => buildTokenRecord(options, void 0, u, model)));
+    return;
+  }
+  const record = buildTokenRecord(options, void 0, usage, model);
+  if (record) options.meter.record(record);
+}
+function extractAIModel(response) {
+  if (typeof response !== "object" || response === null) return void 0;
+  const m = response.modelId;
+  return typeof m === "string" ? m : void 0;
+}
+
+export { createUsageMeter, meterAIResult, meterFunction, meterOpenAI, normalizeTokenUsage, tapAsyncIterable };
+//# sourceMappingURL=ingestion.js.map
+//# sourceMappingURL=ingestion.js.map

package/dist/ingestion.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ingestion.ts"],"names":[],"mappings":"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","file":"ingestion.js","sourcesContent":["/**\n * Auto-metering (PRD-16): ingestion strategies that call billow's `track()` for you,\n * so you never hand-instrument usage.\n *\n * Two layers:\n *   1. A generic primitive — {@link createUsageMeter} + {@link meterFunction} — a\n *      non-blocking, buffered, idempotent dispatcher you can point at ANY usage\n *      source (an S3 upload, a job run, a DB write).\n *   2. LLM strategies built on it — {@link meterOpenAI} (OpenAI-compatible clients)\n *      and {@link meterAIResult} (Vercel AI SDK) that auto-count prompt+completion\n *      tokens from the provider's own response (never re-tokenizing).\n *\n * Posture (every strategy): SERVER-SIDE ONLY — a browser can't be trusted to\n * self-report usage — and NON-BLOCKING: metering is a side effect that can never\n * delay or break the wrapped call. A failed `track()` buffers and retries under an\n * idempotency key; if it ultimately fails it is dropped (via `onError`), never thrown.\n *\n *   import { Billow } from \"@usebillow/sdk\";\n *   import { createUsageMeter, meterOpenAI } from \"@usebillow/sdk/ingestion\";\n *\n *   const billow = new Billow(process.env.BILLOW_SECRET_KEY!);\n *   const meter = createUsageMeter(billow);\n *   const openai = meterOpenAI(new OpenAI(), {\n *     meter,\n *     feature: \"tokens\",\n *     customer: (params) => String(params.user), // your billow customer id\n *   });\n *   // use `openai` exactly as before — every completion auto-meters its tokens.\n */\n\nimport type { Billow } from \"./index\";\n\n/** One usage event handed to `track()`. Mirrors {@link Billow.track}'s input. */\nexport interface UsageRecord {\n  customerId: string;\n  featureId: string;\n  /** Units to record (the engine defaults to 1). */\n  value?: number;\n  /** Event properties for meter filters / property-based aggregations. */\n  properties?: Record<string, string | number>;\n  /**\n   * Dedup key. Auto-generated per record when omitted, so a retried dispatch is a\n   * no-op — set it yourself to dedupe across process restarts.\n   */\n  idempotencyKey?: string;\n}\n\n/** The minimal client the meter needs — the real {@link Billow} satisfies it. */\nexport type TrackClient = Pick<Billow, \"track\">;\n\nexport interface MeterOptions {\n  /** Max dispatch attempts for one record before it's dropped (default 5). */\n  maxAttempts?: number;\n  /** Base retry backoff in ms; doubles each attempt (default 250). */\n  retryBaseMs?: number;\n  /** Called once when a record is permanently dropped after exhausting retries. */\n  onError?: (error: unknown, record: UsageRecord) => void;\n}\n\n/**\n * A buffered, non-blocking dispatcher to `track()`. `record()` returns immediately\n * and never throws; delivery (with retries under an idempotency key) happens in the\n * background. Call {@link UsageMeter.flush} before a serverless handler returns so\n * pending records aren't lost when the process freezes.\n */\nexport interface UsageMeter {\n  /** Enqueue a usage event. Returns immediately, never throws. */\n  record(record: UsageRecord): void;\n  /**\n   * Enqueue a usage event whose record resolves LATER (e.g. a streamed response\n   * whose token totals arrive as a promise). Registers the pending work immediately\n   * so {@link UsageMeter.flush} awaits it — a `null` resolution or a rejected source\n   * is dropped. Returns immediately, never throws.\n   */\n  recordAsync(source: Promise<UsageRecord | null>): void;\n  /** Resolve once every buffered dispatch has settled (delivered or dropped). */\n  flush(): Promise<void>;\n  /** Records still in flight (queued or retrying). */\n  readonly pending: number;\n}\n\nconst DEFAULT_MAX_ATTEMPTS = 5;\nconst DEFAULT_RETRY_BASE_MS = 250;\n\nfunction newIdempotencyKey(): string {\n  return crypto.randomUUID();\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/** Build a {@link UsageMeter} bound to a billow client (or any `{ track }`). */\nexport function createUsageMeter(client: TrackClient, options: MeterOptions = {}): UsageMeter {\n  const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);\n  const retryBaseMs = Math.max(0, options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS);\n  const inFlight = new Set<Promise<void>>();\n\n  async function dispatch(record: UsageRecord): Promise<void> {\n    // Freeze one idempotency key for the record so every retry is the SAME call.\n    const input: UsageRecord = {\n      ...record,\n      idempotencyKey: record.idempotencyKey ?? newIdempotencyKey(),\n    };\n    let lastError: unknown;\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        await client.track(input);\n        return;\n      } catch (error) {\n        lastError = error;\n        if (attempt < maxAttempts) await sleep(retryBaseMs * 2 ** (attempt - 1));\n      }\n    }\n    try {\n      options.onError?.(lastError, input);\n    } catch {\n      // A throwing onError must not reject the tracked dispatch (which would make\n      // flush() reject) — the meter's contract is that it never throws.\n    }\n  }\n\n  /** Register a unit of metering work so `flush()`/`pending` account for it. */\n  function track(work: Promise<void>): void {\n    const p = work.finally(() => {\n      inFlight.delete(p);\n    });\n    inFlight.add(p);\n  }\n\n  return {\n    record(record) {\n      track(dispatch(record));\n    },\n    recordAsync(source) {\n      // Chain resolve-then-dispatch into ONE tracked unit so flush() covers work\n      // whose record isn't known yet. A null record or a rejected source is dropped.\n      track(\n        source.then(\n          (record) => (record ? dispatch(record) : undefined),\n          () => undefined,\n        ),\n      );\n    },\n    flush() {\n      return Promise.all([...inFlight]).then(() => undefined);\n    },\n    get pending() {\n      return inFlight.size;\n    },\n  };\n}\n\n/**\n * Derive a usage record from a completed call. Return `null` to skip metering it\n * (e.g. a cache hit with no billable usage). Receives the resolved result and the\n * original call arguments.\n */\nexport type UsageExtractor<A extends unknown[], R> = (result: R, args: A) => UsageRecord | null;\n\n/**\n * Wrap any async function so each successful call auto-records usage via `meter` —\n * the generic ingestion primitive. Point it at any source by supplying an `extract`.\n * Metering runs AFTER the call resolves and never blocks it; an extractor that\n * throws is swallowed. If the wrapped call itself rejects, nothing is recorded and\n * the error propagates unchanged.\n */\nexport function meterFunction<A extends unknown[], R>(\n  fn: (...args: A) => Promise<R>,\n  meter: UsageMeter,\n  extract: UsageExtractor<A, R>,\n): (...args: A) => Promise<R> {\n  return async (...args: A) => {\n    const result = await fn(...args);\n    try {\n      const record = extract(result, args);\n      if (record) meter.record(record);\n    } catch {\n      // Metering must never break the wrapped call — drop extractor errors.\n    }\n    return result;\n  };\n}\n\n/**\n * Yield every value of `source` straight through to the consumer while calling\n * `onValue` for each and `onDone` when iteration finishes (including an early\n * `break`/`return` — it runs in a `finally`). Taps a stream WITHOUT consuming it:\n * the caller still receives every chunk. Tap callbacks that throw are swallowed so\n * they can't break the stream.\n */\nexport async function* tapAsyncIterable<T>(\n  source: AsyncIterable<T>,\n  taps: { onValue?: (value: T) => void; onDone?: () => void },\n): AsyncGenerator<T> {\n  try {\n    for await (const value of source) {\n      try {\n        taps.onValue?.(value);\n      } catch {\n        // never let a tap break the passthrough\n      }\n      yield value;\n    }\n  } finally {\n    try {\n      taps.onDone?.();\n    } catch {\n      // never let a tap break the passthrough\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// LLM token metering\n// ---------------------------------------------------------------------------\n\n/** Normalized token counts, whatever the provider's field naming. */\nexport interface TokenCounts {\n  promptTokens: number;\n  completionTokens: number;\n  totalTokens: number;\n}\n\n/** Which token count a meter records as its `value` (default `\"total\"`). */\nexport type TokenCount = \"total\" | \"prompt\" | \"completion\";\n\nfunction firstNumber(...values: unknown[]): number | null {\n  for (const v of values) if (typeof v === \"number\" && Number.isFinite(v)) return v;\n  return null;\n}\n\n/**\n * Read token counts from a provider usage object, accepting OpenAI (`prompt_tokens`\n * / `completion_tokens` / `total_tokens`), Vercel AI SDK v4 (`promptTokens` / …) and\n * v5 (`inputTokens` / `outputTokens`) shapes. Returns `null` when no token fields\n * are present. `totalTokens` is derived from prompt+completion when not supplied.\n */\nexport function normalizeTokenUsage(usage: unknown): TokenCounts | null {\n  if (typeof usage !== \"object\" || usage === null) return null;\n  const u = usage as {\n    prompt_tokens?: unknown;\n    promptTokens?: unknown;\n    inputTokens?: unknown;\n    completion_tokens?: unknown;\n    completionTokens?: unknown;\n    outputTokens?: unknown;\n    total_tokens?: unknown;\n    totalTokens?: unknown;\n  };\n  const prompt = firstNumber(u.prompt_tokens, u.promptTokens, u.inputTokens);\n  const completion = firstNumber(u.completion_tokens, u.completionTokens, u.outputTokens);\n  const total = firstNumber(u.total_tokens, u.totalTokens);\n  if (prompt === null && completion === null && total === null) return null;\n  const promptTokens = prompt ?? 0;\n  const completionTokens = completion ?? 0;\n  return {\n    promptTokens,\n    completionTokens,\n    totalTokens: total ?? promptTokens + completionTokens,\n  };\n}\n\nfunction pickCount(counts: TokenCounts, which: TokenCount): number {\n  if (which === \"prompt\") return counts.promptTokens;\n  if (which === \"completion\") return counts.completionTokens;\n  return counts.totalTokens;\n}\n\n/** A value supplied directly, or resolved from a call's params. */\ntype Resolvable<T, P> = T | ((params: P) => T);\n\nfunction resolveValue<T, P>(r: Resolvable<T, P>, params: P): T {\n  return typeof r === \"function\" ? (r as (p: P) => T)(params) : r;\n}\n\nexport interface MeterLLMOptions<P = unknown> {\n  /** The buffered meter that dispatches to `track()`. */\n  meter: UsageMeter;\n  /** The metered feature (token meter) id — static, or resolved per call. */\n  feature: Resolvable<string, P>;\n  /**\n   * The billow customer to bill. Static for single-tenant, or resolved per call\n   * (e.g. from the OpenAI `user` param) for multi-tenant. Returning `null`/`undefined`\n   * skips metering that call — there's no customer to attribute it to.\n   */\n  customer: Resolvable<string | null | undefined, P>;\n  /** Which token count to record as the meter value (default `\"total\"`). */\n  count?: TokenCount;\n  /** Extra event properties merged onto each record (`model` is added automatically). */\n  properties?: (params: P, tokens: TokenCounts) => Record<string, string | number>;\n}\n\n/**\n * Build the usage record for one LLM call from its usage + model, or `null` to skip.\n * TOTAL by contract — a throwing `customer`/`feature`/`properties` resolver (e.g. an\n * unexpected params shape) drops the record rather than surfacing in the wrapped\n * call, so every caller (sync or async) inherits the non-blocking guarantee here.\n */\nfunction buildTokenRecord<P>(\n  options: MeterLLMOptions<P>,\n  params: P,\n  usage: unknown,\n  model: unknown,\n): UsageRecord | null {\n  const counts = normalizeTokenUsage(usage);\n  if (!counts) return null;\n  try {\n    const customerId = resolveValue(options.customer, params);\n    if (!customerId) return null;\n    const properties: Record<string, string | number> = {\n      tokens_prompt: counts.promptTokens,\n      tokens_completion: counts.completionTokens,\n      tokens_total: counts.totalTokens,\n      ...(typeof model === \"string\" ? { model } : {}),\n      ...options.properties?.(params, counts),\n    };\n    return {\n      customerId,\n      featureId: resolveValue(options.feature, params),\n      value: pickCount(counts, options.count ?? \"total\"),\n      properties,\n    };\n  } catch {\n    return null; // a resolver mistake must never break the wrapped call\n  }\n}\n\nfunction isPromiseLike(v: unknown): v is Promise<unknown> {\n  return (\n    (typeof v === \"object\" || typeof v === \"function\") &&\n    v !== null &&\n    typeof (v as { then?: unknown }).then === \"function\"\n  );\n}\n\n/** The two params slots an OpenAI-style `create(body, requestOptions?)` takes. */\ntype CreateArgs = [params: Record<string, unknown>, ...rest: unknown[]];\n\nfunction wrapOpenAICreate(\n  create: (...args: unknown[]) => unknown,\n  thisArg: unknown,\n  options: MeterLLMOptions<Record<string, unknown>>,\n): (...args: CreateArgs) => unknown {\n  return (params, ...rest) => {\n    const returned = Reflect.apply(create, thisArg, [params, ...rest]);\n    // openai-node returns a thenable (APIPromise) for BOTH streaming and not.\n    if (!isPromiseLike(returned)) return returned;\n\n    if ((params as { stream?: unknown }).stream === true) {\n      // Streaming: TAP iteration to read the usage the final chunk carries (present\n      // when the caller sets `stream_options.include_usage`) WITHOUT dropping the\n      // OpenAI return contract — the APIPromise keeps its helpers and the resolved\n      // Stream keeps its methods; we only override `Symbol.asyncIterator`.\n      return proxyResolved(returned, (stream) =>\n        typeof stream === \"object\" && stream !== null\n          ? proxyAsyncIterable(stream, () =>\n              tapOpenAIStream(stream as AsyncIterable<unknown>, params, options),\n            )\n          : stream,\n      );\n    }\n    // Non-streaming: record from the resolved completion's `.usage`, tracked by the\n    // meter so `flush()` awaits it. The caller receives the ORIGINAL promise\n    // untouched (APIPromise helpers intact); a failed call resolves to no record.\n    options.meter.recordAsync(returned.then((resp) => completionRecord(resp, params, options)));\n    return returned;\n  };\n}\n\nfunction completionRecord(\n  resp: unknown,\n  params: Record<string, unknown>,\n  options: MeterLLMOptions<Record<string, unknown>>,\n): UsageRecord | null {\n  if (typeof resp !== \"object\" || resp === null) return null;\n  const r = resp as { usage?: unknown; model?: unknown };\n  return buildTokenRecord(options, params, r.usage, r.model);\n}\n\n/**\n * Proxy a thenable so awaiting it yields `map(resolvedValue)`, while every other\n * property/method (an APIPromise's `.withResponse()`/`.asResponse()`, …) passes\n * straight through. Lets us tap the resolved value without dropping the return\n * contract.\n */\nfunction proxyResolved(\n  source: Promise<unknown>,\n  map: (value: unknown) => unknown,\n): Promise<unknown> {\n  const mappedThen = (onF?: (v: unknown) => unknown, onR?: (e: unknown) => unknown) =>\n    source.then((v) => (onF ? onF(map(v)) : map(v)), onR);\n  return new Proxy(source, {\n    get(target, prop) {\n      // Route `then`/`catch`/`finally` through the mapping so awaiting via ANY of\n      // them yields the tapped value — binding the native methods to `target` would\n      // resolve the raw (un-tapped) stream and silently skip metering.\n      if (prop === \"then\") return mappedThen;\n      if (prop === \"catch\") return (onR: (e: unknown) => unknown) => mappedThen(undefined, onR);\n      if (prop === \"finally\") {\n        return (cb?: () => void) =>\n          mappedThen(\n            (v) => {\n              cb?.();\n              return v;\n            },\n            (e) => {\n              cb?.();\n              throw e;\n            },\n          );\n      }\n      const value = Reflect.get(target, prop);\n      return typeof value === \"function\" ? value.bind(target) : value;\n    },\n  }) as Promise<unknown>;\n}\n\n/**\n * Proxy an async-iterable object so `for await` runs `makeIterator()` (our tap),\n * while every other property/method (a Stream's `.tee()`, `.toReadableStream()`, …)\n * passes straight through. Taps iteration WITHOUT replacing the object.\n */\nfunction proxyAsyncIterable(source: object, makeIterator: () => AsyncIterator<unknown>): object {\n  return new Proxy(source, {\n    get(target, prop) {\n      if (prop === Symbol.asyncIterator) return makeIterator;\n      const value = Reflect.get(target, prop);\n      return typeof value === \"function\" ? value.bind(target) : value;\n    },\n  });\n}\n\n/** Usage + model folded out of a streamed response, ready for {@link buildTokenRecord}. */\ninterface StreamUsage {\n  usage?: unknown;\n  model?: unknown;\n}\n\n/**\n * Meter a streamed response: tap the stream (yielding every chunk untouched), fold\n * each chunk into an accumulator via `reduce`, and record ONE usage event when\n * iteration finishes. This is the reusable middle between the generic\n * {@link tapAsyncIterable} and a specific provider's chunk shape — a new streaming\n * source (Anthropic SSE, etc.) plugs in by supplying only its `reduce`.\n */\nfunction meterStream<C, P>(\n  stream: AsyncIterable<C>,\n  params: P,\n  options: MeterLLMOptions<P>,\n  reduce: (chunk: C, acc: StreamUsage) => void,\n): AsyncGenerator<C> {\n  const acc: StreamUsage = {};\n  return tapAsyncIterable(stream, {\n    onValue: (chunk) => reduce(chunk, acc),\n    onDone: () => {\n      const record = buildTokenRecord(options, params, acc.usage, acc.model);\n      if (record) options.meter.record(record);\n    },\n  });\n}\n\nfunction tapOpenAIStream(\n  stream: AsyncIterable<unknown>,\n  params: Record<string, unknown>,\n  options: MeterLLMOptions<Record<string, unknown>>,\n): AsyncGenerator<unknown> {\n  return meterStream(stream, params, options, (chunk, acc) => {\n    if (typeof chunk !== \"object\" || chunk === null) return;\n    const c = chunk as { usage?: unknown; model?: unknown };\n    if (c.usage) acc.usage = c.usage; // the final chunk carries usage (include_usage)\n    if (c.model && acc.model === undefined) acc.model = c.model;\n  });\n}\n\n/**\n * Wrap an OpenAI-compatible client so every `chat.completions.create` call\n * auto-meters its token usage. Returns a proxy of the SAME type — use it exactly as\n * before; every other property/method passes straight through untouched.\n *\n * Reads the token count from the provider's own response (no re-tokenizing), for\n * both blocking and streaming calls. For a STREAMED call, pass\n * `stream_options: { include_usage: true }` so the final chunk carries usage —\n * otherwise a streamed call can't be metered (billow never mutates your request).\n *\n * A streamed response is metered when consumed the standard way: `await` the call,\n * then `for await` the stream. The `Stream` helpers (`.tee()`, `.toReadableStream()`)\n * and the un-awaited `APIPromise` helpers (`.withResponse()`, `.asResponse()`) are\n * PRESERVED (they keep working), but consuming through them bypasses the iteration\n * tap, so those calls are not token-metered.\n *\n * Works with any client exposing `chat.completions.create` returning a `.usage`\n * shape: OpenAI, Azure OpenAI, Together, Groq, OpenRouter, and other compatibles.\n *\n *   const openai = meterOpenAI(new OpenAI(), { meter, feature: \"tokens\", customer });\n *   const res = await openai.chat.completions.create({ model, messages }); // metered\n */\nexport function meterOpenAI<T extends object>(\n  client: T,\n  options: MeterLLMOptions<Record<string, unknown>>,\n): T {\n  const root = client as { chat?: { completions?: { create?: unknown } } };\n  const completions = root.chat?.completions;\n  const create = completions?.create;\n  if (typeof create !== \"function\" || !completions) {\n    throw new TypeError(\"meterOpenAI: expected client.chat.completions.create to be a function\");\n  }\n  const wrapped = wrapOpenAICreate(create as (...args: unknown[]) => unknown, completions, options);\n  return replaceCreate(client, wrapped);\n}\n\n/**\n * Return a non-mutating proxy of `client` that swaps ONLY `chat.completions.create`\n * for `wrapped`, passing every other access straight through. Untouched methods keep\n * their real receiver, so `this` stays correct.\n */\nfunction replaceCreate<T extends object>(client: T, wrapped: (...args: CreateArgs) => unknown): T {\n  const root = client as { chat: { completions: object } };\n  const completionsProxy = new Proxy(root.chat.completions, {\n    get: (t, p, r) => (p === \"create\" ? wrapped : Reflect.get(t, p, r)),\n  });\n  const chatProxy = new Proxy(root.chat, {\n    get: (t, p, r) => (p === \"completions\" ? completionsProxy : Reflect.get(t, p, r)),\n  });\n  return new Proxy(client, {\n    get: (t, p, r) => (p === \"chat\" ? chatProxy : Reflect.get(t, p, r)),\n  });\n}\n\n/**\n * Meter a Vercel AI SDK result (the object `generateText`/`streamText` resolves to).\n * Reads `result.usage` — an object (`generateText`) or a Promise (`streamText`) — and\n * records the token count, non-blocking. Never touches `result.textStream`, so a\n * streamed response is delivered to your consumer untouched. Accepts AI SDK v4\n * (`promptTokens`/`completionTokens`) and v5 (`inputTokens`/`outputTokens`) shapes.\n *\n *   const result = streamText({ model, prompt });\n *   meterAIResult(result, { meter, feature: \"tokens\", customer: customerId });\n *   return result.toDataStreamResponse();\n */\nexport function meterAIResult(\n  result: { usage?: unknown; response?: unknown },\n  options: MeterLLMOptions<void>,\n): void {\n  const model = extractAIModel(result.response);\n  const usage = result.usage;\n  if (isPromiseLike(usage)) {\n    // `streamText` resolves usage LATE — hand the meter the whole resolve→record\n    // chain so `flush()` (the README's serverless guidance) awaits it instead of\n    // snapshotting an empty in-flight set and dropping the usage.\n    options.meter.recordAsync(usage.then((u) => buildTokenRecord(options, undefined, u, model)));\n    return;\n  }\n  const record = buildTokenRecord(options, undefined, usage, model);\n  if (record) options.meter.record(record);\n}\n\n/** Best-effort model id from an AI SDK result's `response` (skipped if it's a promise). */\nfunction extractAIModel(response: unknown): unknown {\n  if (typeof response !== \"object\" || response === null) return undefined;\n  const m = (response as { modelId?: unknown }).modelId;\n  return typeof m === \"string\" ? m : undefined;\n}\n"]}