@arnaudjnn/billing-tools 0.61.0 → 0.62.0

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":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAwC,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,SAAS,EAAkD,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAoB,MAAM,mBAAmB,CAAC;AAuC/E,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,IAAY,EAAU,EAAE,CACjD,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAEhF,SAAS,QAAQ,CAAC,CAAa;IAC7B,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;AACxE,CAAC;AAED;0DAC0D;AAC1D,SAAS,SAAS,CAChB,KAAY,EACZ,KAAoB,EACpB,IAAY,EACZ,IAAY,EACZ,KAAkB;IAElB,OAAO;QACL,KAAK;QACL,KAAK,EAAE,KAAK;QACZ,KAAK;QACL,IAAI;QACJ,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;QACnC,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC;QACxB,QAAQ,EAAE,KAAK,CAAC,GAAG;KACpB,CAAC;AACJ,CAAC;AAgBD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAuB,EACvB,MAAsB,EACtB,KAAwB;IAExB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACzD,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAEnC,4EAA4E;IAC5E,uDAAuD;IACvD,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GACZ,MAAM,CAAC,IAAI,KAAK,KAAK;YACnB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC;QAC1F,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE;QACpD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM;QACN,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,wBAAwB,EAAE;QAClD,GAAG,EAAE,EAAE;KACR,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnC,IAAI,EAAE,KAAK,CAAC,IAAI;YACd,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC;YAC1G,CAAC,CAAC,IAAI;QACR,IAAI,EAAE,KAAK,CAAC,IAAI;YACd,CAAC,CAAC;gBACE,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC;gBAC7F,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;gBAC7B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;aACxB;YACH,CAAC,CAAC,IAAI;QACR,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,EAAE;KACH,CAAC;AACJ,CAAC;AAeD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAuB,EACvB,MAAsB,EACtB,KAQC;IAED,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACpE,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAE3B,OAAO,OAAO,CAAC,GAAG,CAChB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE;YAClD,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE;YAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,EAAE,EAAE;SACR,CAAC,CAAC;QACH,0EAA0E;QAC1E,uEAAuE;QACvE,2EAA2E;QAC3E,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;QACvG,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI;YACJ,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;YACzE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI;YAC1E,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC;YAC5D,WAAW;SACZ,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

package/package.json

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