@arnaudjnn/billing-tools 0.61.0 → 0.62.1

package/dist/usage.d.ts

@@ -0,0 +1,93 @@
+import { type AllowanceState, type LimitState } from "./allowance.js";
+import { type CycleWindow, type PlanCatalog } from "./plan-model.js";
+import { type UsageLedger } from "./usage-ledger.js";
+import type { BillingAdapter, ResolvedConfig } from "./types.js";
+/** One window with progress. `resetsAt` is null only for an open-ended cycle. */
+export interface UsageWindow extends LimitState {
+    /** 0-100, clamped, rounded. `size` 0 reads as 100 — nothing is allowed. */
+    percent: number;
+    resetsAt: number | null;
+}
+export interface UsageSummary {
+    plan: string | null;
+    /** The billing cycle the cap is measured over. */
+    cycle: CycleWindow;
+    /** Declared rate limits, tightest-first is NOT imposed: config order. */
+    windows: UsageWindow[];
+    /** The plan's included window, as its own progress row when there is one. */
+    pool: UsageWindow | null;
+    /** The caller's seat pack, when the plan caps per seat and a caller was given. */
+    pack: (UsageWindow & {
+        seatType: string;
+        extra: number;
+    }) | null;
+    /** Prepaid balance, in the configured currency. */
+    wallet: number;
+    /** Epoch ms this was read. What a "last updated" line shows. */
+    at: number;
+}
+export interface UsageSummaryInput {
+    orgId: string;
+    plans: PlanCatalog;
+    plan?: string | null;
+    /**
+     * Whose usage. Omit for the workspace as a whole — caller-scoped limits and the
+     * seat pack are then left out, because neither means anything without a caller.
+     * `seatType` is resolved from the adapter when not supplied.
+     */
+    caller?: {
+        kind: "user" | "api";
+        id?: string;
+        seatType?: string;
+    };
+    ledger?: UsageLedger;
+    now?: number;
+}
+/**
+ * Everything a usage screen shows for one subject (a workspace, or one member).
+ *
+ * One `resolveAllowance` underneath, so the numbers a screen shows and the numbers
+ * the meter enforces are the same numbers, read the same way. A screen that
+ * computed its own would eventually disagree with the gate — and the disagreement
+ * would be invisible until a customer was refused at 60%.
+ */
+export declare function usageSummary(adapter: BillingAdapter, config: ResolvedConfig, input: UsageSummaryInput): Promise<UsageSummary>;
+export interface MemberUsage {
+    /** WorkOS member id, or the API-key marker for the shared seat. */
+    id: string;
+    kind: "user" | "api";
+    seatType: string;
+    /** The member's pack, when the plan caps per seat. */
+    pack: (UsageWindow & {
+        extra: number;
+    }) | null;
+    /** Caller-scoped rate limits, measured for this member. */
+    windows: UsageWindow[];
+    /** Total counted usage in the billing cycle. */
+    usedInCycle: number;
+}
+/**
+ * Per-member usage for an admin view.
+ *
+ * One summary per member, run in parallel: the ledger has no group-by, and adding
+ * one to the seam would mean either a Stripe meter dimension per member (there is
+ * no such thing) or paging every transaction in the window and bucketing it here.
+ * A workspace is tens of members, not thousands, and this is a page, not the hot
+ * path — but it IS N round trips, so a caller that renders it on every request
+ * should cache it.
+ */
+export declare function memberUsage(adapter: BillingAdapter, config: ResolvedConfig, input: {
+    orgId: string;
+    plans: PlanCatalog;
+    plan?: string | null;
+    /** The members to report on, in the order they should appear. */
+    members: readonly {
+        id: string;
+        kind?: "user" | "api";
+    }[];
+    ledger?: UsageLedger;
+    now?: number;
+}): Promise<MemberUsage[]>;
+/** Re-exported so a consumer can type a state it passes around. */
+export type { AllowanceState, LimitState };
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAExF,OAAO,EAAa,KAAK,WAAW,EAAc,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAejE,iFAAiF;AACjF,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,WAAW,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,6EAA6E;IAC7E,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,IAAI,EAAE,CAAC,WAAW,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACjE,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;CACZ;AA+BD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,YAAY,CAAC,CAyCvB;AAED,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,IAAI,EAAE,CAAC,WAAW,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAC/C,2DAA2D;IAC3D,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,EAAE,CAAC;IAC1D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GACA,OAAO,CAAC,WAAW,EAAE,CAAC,CA8BxB;AAED,mEAAmE;AACnE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC"}

package/dist/usage.js

@@ -0,0 +1,110 @@
+import { getBillingCustomerId } from "./billing.js";
+import { resolveAllowance } from "./allowance.js";
+import { getSeatType } from "./seats.js";
+import { planModel } from "./plan-model.js";
+import { stripeBalanceUsageLedger } from "./usage-ledger.js";
+const pct = (used, size) => size <= 0 ? 100 : Math.min(100, Math.max(0, Math.round((used / size) * 100)));
+function toWindow(l) {
+    return { ...l, percent: pct(l.used, l.size), resetsAt: l.window.end };
+}
+/** The cap's own window, so a screen can render pool/pack with the same row as a
+ *  rate limit rather than special-casing three shapes. */
+function capWindow(every, label, size, used, cycle) {
+    return {
+        every,
+        scope: "org",
+        label,
+        size,
+        used,
+        remaining: Math.max(0, size - used),
+        window: cycle,
+        percent: pct(used, size),
+        resetsAt: cycle.end,
+    };
+}
+/**
+ * Everything a usage screen shows for one subject (a workspace, or one member).
+ *
+ * One `resolveAllowance` underneath, so the numbers a screen shows and the numbers
+ * the meter enforces are the same numbers, read the same way. A screen that
+ * computed its own would eventually disagree with the gate — and the disagreement
+ * would be invisible until a customer was refused at 60%.
+ */
+export async function usageSummary(adapter, config, input) {
+    const model = planModel(input.plans, input.plan ?? null);
+    const at = input.now ?? Date.now();
+    // A member's seat decides which pack and which seat-scoped limits apply, so
+    // resolve it here rather than making every page do it.
+    let caller = input.caller;
+    if (caller && !caller.seatType) {
+        const seatType = caller.kind === "api"
+            ? "api"
+            : ((caller.id && (await getSeatType(adapter, input.orgId, caller.id))) || "standard");
+        caller = { ...caller, seatType };
+    }
+    const state = await resolveAllowance(adapter, config, {
+        orgId: input.orgId,
+        plans: input.plans,
+        plan: input.plan,
+        caller,
+        ledger: input.ledger ?? stripeBalanceUsageLedger(),
+        now: at,
+    });
+    return {
+        plan: state.plan,
+        cycle: state.cycle,
+        windows: state.limits.map(toWindow),
+        pool: state.pool
+            ? capWindow("cycle", model?.display?.pooled?.title ?? null, state.pool.size, state.pool.used, state.cycle)
+            : null,
+        pack: state.pack
+            ? {
+                ...capWindow("cycle", null, state.pack.size + state.pack.extra, state.pack.used, state.cycle),
+                seatType: state.pack.seatType,
+                extra: state.pack.extra,
+            }
+            : null,
+        wallet: state.wallet,
+        at,
+    };
+}
+/**
+ * Per-member usage for an admin view.
+ *
+ * One summary per member, run in parallel: the ledger has no group-by, and adding
+ * one to the seam would mean either a Stripe meter dimension per member (there is
+ * no such thing) or paging every transaction in the window and bucketing it here.
+ * A workspace is tens of members, not thousands, and this is a page, not the hot
+ * path — but it IS N round trips, so a caller that renders it on every request
+ * should cache it.
+ */
+export async function memberUsage(adapter, config, input) {
+    const at = input.now ?? Date.now();
+    const customerId = await getBillingCustomerId(adapter, input.orgId);
+    if (!customerId)
+        return [];
+    return Promise.all(input.members.map(async (m) => {
+        const kind = m.kind ?? "user";
+        const summary = await usageSummary(adapter, config, {
+            orgId: input.orgId,
+            plans: input.plans,
+            plan: input.plan,
+            caller: { kind, id: m.id },
+            ledger: input.ledger,
+            now: at,
+        });
+        // The pack is the per-member figure when the plan has one; without a pack
+        // (a pool or a pure wallet) fall back to the caller-scoped window, and
+        // failing that to zero, which is honest: a pooled plan does not attribute.
+        const usedInCycle = summary.pack?.used ?? summary.windows.find((w) => w.scope === "caller")?.used ?? 0;
+        return {
+            id: m.id,
+            kind,
+            seatType: summary.pack?.seatType ?? (kind === "api" ? "api" : "standard"),
+            pack: summary.pack ? { ...summary.pack, extra: summary.pack.extra } : null,
+            windows: summary.windows.filter((w) => w.scope === "caller"),
+            usedInCycle,
+        };
+    }));
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnaudjnn/billing-tools",
-  "version": "0.61.0",
+  "version": "0.62.1",
   "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",