@arnaudjnn/billing-tools 0.55.0 → 0.57.0

package/dist/usage-ledger.d.ts

@@ -0,0 +1,87 @@
+/** Which allowance paid for a call. */
+export type FundingSource = 
+/** The org-wide included window. */
+"pool"
+/** The caller's seat pack. */
+ | "pack"
+/** Prepaid balance — the only one that moves money. */
+ | "wallet";
+export interface UsageEvent {
+    orgId: string;
+    customerId: string;
+    action: string;
+    cost: number;
+    funded: FundingSource;
+    caller?: {
+        kind: string;
+        id?: string;
+    };
+    /** Epoch ms. Defaults to now. */
+    at?: number;
+    /** Makes a retry a no-op where the backing store supports it. */
+    idempotencyKey?: string;
+}
+export interface UsageQuery {
+    orgId: string;
+    customerId: string;
+    /** Epoch ms, inclusive. */
+    start: number;
+    /** Epoch ms, exclusive. Omit for "up to now". */
+    end?: number;
+    filter?: {
+        callerKind?: string;
+        callerId?: string;
+    };
+}
+export interface UsageLedger {
+    record(event: UsageEvent): Promise<void>;
+    /** Summed cost in [start, end). */
+    total(query: UsageQuery): Promise<number>;
+}
+/**
+ * The ledger this library has always had: the debits themselves.
+ *
+ * `record` is a no-op — `deductTokens` already wrote the row — and `total` is
+ * `usageSince`. Correct and free for any plan where every call is wallet-funded,
+ * which is every plan that existed before included windows, so it stays the
+ * default. It cannot see pool- or pack-funded usage, because that usage moves no
+ * money and therefore writes no transaction: a plan with an included window
+ * needs the meter ledger below.
+ */
+export declare function stripeBalanceUsageLedger(): UsageLedger;
+/** Default name of the Stripe Billing Meter events are reported to. */
+export declare const USAGE_METER_EVENT = "billing_tools_usage";
+/**
+ * Stripe Billing Meters: purpose-built usage counting, aggregated server-side.
+ *
+ * Chosen over reading balance transactions for two reasons beyond the money/usage
+ * split. It is idempotent by construction (`identifier`), and a summary is ONE
+ * call for any window — `usageSince` walks pages newest-first until it passes the
+ * start, so an annual window would page through a year of transactions on the hot
+ * path of every metered execution.
+ *
+ * The trade: summaries lag aggregation by a few seconds, so a hard cap can
+ * overshoot slightly. Irrelevant against a pool of a million tokens; it is why
+ * seat packs, which are small, can keep using the exact balance path.
+ *
+ * `ensureMeters` provisions the meter, in the same spirit as `ensurePlans`.
+ */
+export declare function stripeMeterUsageLedger(opts?: {
+    eventName?: string;
+}): UsageLedger;
+/**
+ * Create the usage meter if it doesn't exist. Idempotent, like `ensurePlans`.
+ *
+ * Only needed by a config with an included window; a wallet-only product never
+ * calls it. Aggregates `sum` over the reported `value`, which is the token cost.
+ */
+export declare function ensureMeters(opts?: {
+    eventName?: string;
+    displayName?: string;
+}): Promise<{
+    meterId: string;
+    created: boolean;
+}>;
+/** Forget resolved meter ids — for a test, or after archiving one. */
+export declare function invalidateMeters(): void;
+//# sourceMappingURL=usage-ledger.d.ts.map

package/dist/usage-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.d.ts","sourceRoot":"","sources":["../src/usage-ledger.ts"],"names":[],"mappings":"AAmBA,uCAAuC;AACvC,MAAM,MAAM,aAAa;AACvB,oCAAoC;AAClC,MAAM;AACR,8BAA8B;GAC5B,MAAM;AACR,uDAAuD;GACrD,QAAQ,CAAC;AAEb,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,mCAAmC;IACnC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,IAAI,WAAW,CAQtD;AAED,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,WAAW,CAoCb;AAmBD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACtD,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAahD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/usage-ledger.js

@@ -0,0 +1,117 @@
+import { getStripe, usageSince } from "./billing.js";
+/**
+ * The ledger this library has always had: the debits themselves.
+ *
+ * `record` is a no-op — `deductTokens` already wrote the row — and `total` is
+ * `usageSince`. Correct and free for any plan where every call is wallet-funded,
+ * which is every plan that existed before included windows, so it stays the
+ * default. It cannot see pool- or pack-funded usage, because that usage moves no
+ * money and therefore writes no transaction: a plan with an included window
+ * needs the meter ledger below.
+ */
+export function stripeBalanceUsageLedger() {
+    return {
+        async record() {
+            /* the balance transaction IS the record */
+        },
+        // `start` is epoch ms throughout this seam; Stripe's `created` is seconds.
+        total: (q) => usageSince(q.customerId, Math.floor(q.start / 1000), q.filter),
+    };
+}
+/** Default name of the Stripe Billing Meter events are reported to. */
+export const USAGE_METER_EVENT = "billing_tools_usage";
+/**
+ * Stripe Billing Meters: purpose-built usage counting, aggregated server-side.
+ *
+ * Chosen over reading balance transactions for two reasons beyond the money/usage
+ * split. It is idempotent by construction (`identifier`), and a summary is ONE
+ * call for any window — `usageSince` walks pages newest-first until it passes the
+ * start, so an annual window would page through a year of transactions on the hot
+ * path of every metered execution.
+ *
+ * The trade: summaries lag aggregation by a few seconds, so a hard cap can
+ * overshoot slightly. Irrelevant against a pool of a million tokens; it is why
+ * seat packs, which are small, can keep using the exact balance path.
+ *
+ * `ensureMeters` provisions the meter, in the same spirit as `ensurePlans`.
+ */
+export function stripeMeterUsageLedger(opts = {}) {
+    const eventName = opts.eventName ?? USAGE_METER_EVENT;
+    return {
+        async record(e) {
+            await getStripe().billing.meterEvents.create({
+                event_name: eventName,
+                payload: {
+                    // Stripe requires the customer on the payload; everything else is ours.
+                    stripe_customer_id: e.customerId,
+                    value: String(e.cost),
+                    action: e.action,
+                    funded: e.funded,
+                    ...(e.caller?.kind ? { caller_kind: e.caller.kind } : {}),
+                    ...(e.caller?.id ? { caller_id: e.caller.id } : {}),
+                },
+                ...(e.idempotencyKey ? { identifier: e.idempotencyKey } : {}),
+                ...(e.at ? { timestamp: Math.floor(e.at / 1000) } : {}),
+            });
+        },
+        async total(q) {
+            const meter = await meterIdFor(eventName);
+            if (!meter)
+                return 0;
+            // Seconds, and Stripe requires the window to sit on minute boundaries.
+            const floorMinute = (ms) => Math.floor(ms / 60_000) * 60;
+            const summaries = await getStripe().billing.meters.listEventSummaries(meter, {
+                customer: q.customerId,
+                start_time: floorMinute(q.start),
+                end_time: floorMinute(q.end ?? Date.now()),
+                limit: 100,
+            });
+            // A meter aggregates one dimension, so a per-caller filter can't be pushed
+            // down. Callers that need it use the balance ledger (seat packs), which is
+            // exact anyway — see the note above.
+            return summaries.data.reduce((sum, s) => sum + s.aggregated_value, 0);
+        },
+    };
+}
+// Meter ids are stable per event name; resolving one is a list call, so memoise
+// it per process the way plan prices are.
+const meterIds = new Map();
+async function meterIdFor(eventName) {
+    const hit = meterIds.get(eventName);
+    if (hit !== undefined)
+        return hit;
+    for await (const m of getStripe().billing.meters.list({ status: "active", limit: 100 })) {
+        if (m.event_name === eventName) {
+            meterIds.set(eventName, m.id);
+            return m.id;
+        }
+    }
+    meterIds.set(eventName, null);
+    return null;
+}
+/**
+ * Create the usage meter if it doesn't exist. Idempotent, like `ensurePlans`.
+ *
+ * Only needed by a config with an included window; a wallet-only product never
+ * calls it. Aggregates `sum` over the reported `value`, which is the token cost.
+ */
+export async function ensureMeters(opts = {}) {
+    const eventName = opts.eventName ?? USAGE_METER_EVENT;
+    const existing = await meterIdFor(eventName);
+    if (existing)
+        return { meterId: existing, created: false };
+    const meter = await getStripe().billing.meters.create({
+        display_name: opts.displayName ?? "billing-tools usage",
+        event_name: eventName,
+        default_aggregation: { formula: "sum" },
+        customer_mapping: { type: "by_id", event_payload_key: "stripe_customer_id" },
+        value_settings: { event_payload_key: "value" },
+    });
+    meterIds.set(eventName, meter.id);
+    return { meterId: meter.id, created: true };
+}
+/** Forget resolved meter ids — for a test, or after archiving one. */
+export function invalidateMeters() {
+    meterIds.clear();
+}
+//# sourceMappingURL=usage-ledger.js.map

package/dist/usage-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.js","sourceRoot":"","sources":["../src/usage-ledger.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnaudjnn/billing-tools",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "The get-paid engine for Stripe + WorkOS apps, for humans and AI agents. Drop-in API-key auth, token/credit + subscription billing, auth.md agent registration, and MPP machine payments, as MCP tools, a REST API, and a CLI. Framework-agnostic, storage-pluggable.",
   "license": "MIT",
   "author": "Arnaud Jeannin",
@@ -59,6 +59,11 @@
       "types": "./dist/dev/stripe-cli.d.ts",
       "import": "./dist/dev/stripe-cli.js",
       "default": "./dist/dev/stripe-cli.js"
+    },
+    "./pricing": {
+      "types": "./dist/pricing.d.ts",
+      "import": "./dist/pricing.js",
+      "default": "./dist/pricing.js"
     }
   },
   "files": [