@absolutejs/billing 0.4.0 → 0.5.0

package/dist/ledger.d.ts

@@ -0,0 +1,56 @@
+/** One priced, metered event, ready to persist. */
+export type LedgerEntry = {
+    /** Charge in integer sub-units of the plan's denomination (see
+     *  `Plan.denomination`) — never a float. */
+    amount: number;
+    /** What the customer is billed in the product's own unit. */
+    credits: number;
+    /** Product-level grouping ("chat", "voice"), not the vendor's. */
+    feature?: string | null;
+    model?: string;
+    /** "llm" | "tts" | "embedding" | whatever the product meters. */
+    operation: string;
+    provider: string;
+    /** Idempotency handle for at-least-once callers. */
+    requestId?: string;
+    /** Null for system/background work with nobody to bill. */
+    tenant?: string | null;
+};
+export type LedgerCommit = {
+    /** Append the row AND debit `entry.credits` from the tenant's balance in a
+     *  single atomic unit. Called with tenant null for unattributed work, where
+     *  there is nothing to debit. */
+    commit: (entry: LedgerEntry) => Promise<void>;
+    /** Fold the entry into a derived daily aggregate. Best-effort by contract:
+     *  this module swallows its failures. */
+    rollup?: (entry: LedgerEntry) => Promise<void>;
+    /** Total sub-units charged since `since`, for the spend cap. */
+    spentSince?: (since: Date) => Promise<number>;
+};
+export type UsageLedgerOptions = {
+    /** Sub-units per credit. A peg of 1_000 with micros means 1 credit =
+     *  $0.001. Required for credit conversion; omit to bill in raw amounts. */
+    creditPegSubUnits?: number;
+    /** Reported when a rollup fails. The charge already succeeded. */
+    onRollupError?: (error: unknown, entry: LedgerEntry) => void;
+    store: LedgerCommit;
+};
+/**
+ * Credits for a charge. Ceiling, not rounding: a product that sells credits
+ * must never hand out a fraction it cannot deduct, and rounding down means
+ * the smallest calls are free — which is how a "cheap" endpoint becomes an
+ * unmetered one.
+ */
+export declare const creditsFor: (amount: number, pegSubUnits: number) => number;
+export type UsageLedger = {
+    /** Price-agnostic: hand it an amount already in sub-units. Returns what was
+     *  written, including the credits it derived. */
+    record: (entry: Omit<LedgerEntry, "credits"> & {
+        credits?: number;
+    }) => Promise<LedgerEntry>;
+    /** True once spend since `since` reaches `capSubUnits`. Fails OPEN — a
+     *  broken cap must not take down paid features, and the per-provider
+     *  budgets are still in front. */
+    overCap: (capSubUnits: number, since: Date) => Promise<boolean>;
+};
+export declare const createUsageLedger: (options: UsageLedgerOptions) => UsageLedger;

package/dist/ledger.js

@@ -0,0 +1,54 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/ledger.ts
+var creditsFor = (amount, pegSubUnits) => {
+  if (pegSubUnits <= 0)
+    return 0;
+  return Math.ceil(amount / pegSubUnits);
+};
+var createUsageLedger = (options) => {
+  const { creditPegSubUnits, onRollupError, store } = options;
+  return {
+    overCap: async (capSubUnits, since) => {
+      if (!store.spentSince)
+        return false;
+      try {
+        return await store.spentSince(since) >= capSubUnits;
+      } catch {
+        return false;
+      }
+    },
+    record: async (input) => {
+      const credits = input.credits ?? (creditPegSubUnits === undefined ? 0 : creditsFor(input.amount, creditPegSubUnits));
+      const entry = { ...input, credits };
+      await store.commit(entry);
+      if (store.rollup) {
+        await store.rollup(entry).catch((error) => {
+          onRollupError?.(error, entry);
+        });
+      }
+      return entry;
+    }
+  };
+};
+export {
+  creditsFor,
+  createUsageLedger
+};
+
+//# debugId=0E1FB04E107E92A964756E2164756E21
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/ledger.ts"],
+  "sourcesContent": [
+    "// The layer between a meter and an invoice: every metered event gets priced,\n// converted to the customer's credit unit, written to an append-only ledger,\n// debited against a balance, and folded into a daily rollup that a spend cap\n// can read. Every app billing a metered API rebuilds this, and each one\n// rediscovers the same three traps:\n//\n//   - Money in floats. Summing float ledger rows drifts; one real deployment\n//     lost 2 cents across 25,740 rows before anyone noticed. Amounts here are\n//     integer sub-units (see Plan.denomination) and are only ever added.\n//   - The debit and the ledger row diverging. If the row is written but the\n//     balance is not debited, a customer gets free usage; the reverse\n//     over-charges. They must land together, so the store commits them as one\n//     unit — this module never splits them.\n//   - The rollup being treated as truth. It is a derived index, rebuildable\n//     from the ledger, so a rollup failure must never fail the charge.\n//\n// Storage stays the host's business (Postgres, ClickHouse, anything). This\n// owns the policy and the arithmetic, which is the part that is identical\n// everywhere — and the part that is worth getting wrong only once.\n\n/** One priced, metered event, ready to persist. */\nexport type LedgerEntry = {\n  /** Charge in integer sub-units of the plan's denomination (see\n   *  `Plan.denomination`) — never a float. */\n  amount: number;\n  /** What the customer is billed in the product's own unit. */\n  credits: number;\n  /** Product-level grouping (\"chat\", \"voice\"), not the vendor's. */\n  feature?: string | null;\n  model?: string;\n  /** \"llm\" | \"tts\" | \"embedding\" | whatever the product meters. */\n  operation: string;\n  provider: string;\n  /** Idempotency handle for at-least-once callers. */\n  requestId?: string;\n  /** Null for system/background work with nobody to bill. */\n  tenant?: string | null;\n};\n\nexport type LedgerCommit = {\n  /** Append the row AND debit `entry.credits` from the tenant's balance in a\n   *  single atomic unit. Called with tenant null for unattributed work, where\n   *  there is nothing to debit. */\n  commit: (entry: LedgerEntry) => Promise<void>;\n  /** Fold the entry into a derived daily aggregate. Best-effort by contract:\n   *  this module swallows its failures. */\n  rollup?: (entry: LedgerEntry) => Promise<void>;\n  /** Total sub-units charged since `since`, for the spend cap. */\n  spentSince?: (since: Date) => Promise<number>;\n};\n\nexport type UsageLedgerOptions = {\n  /** Sub-units per credit. A peg of 1_000 with micros means 1 credit =\n   *  $0.001. Required for credit conversion; omit to bill in raw amounts. */\n  creditPegSubUnits?: number;\n  /** Reported when a rollup fails. The charge already succeeded. */\n  onRollupError?: (error: unknown, entry: LedgerEntry) => void;\n  store: LedgerCommit;\n};\n\n/**\n * Credits for a charge. Ceiling, not rounding: a product that sells credits\n * must never hand out a fraction it cannot deduct, and rounding down means\n * the smallest calls are free — which is how a \"cheap\" endpoint becomes an\n * unmetered one.\n */\nexport const creditsFor = (amount: number, pegSubUnits: number) => {\n  if (pegSubUnits <= 0) return 0;\n\n  return Math.ceil(amount / pegSubUnits);\n};\n\nexport type UsageLedger = {\n  /** Price-agnostic: hand it an amount already in sub-units. Returns what was\n   *  written, including the credits it derived. */\n  record: (\n    entry: Omit<LedgerEntry, \"credits\"> & { credits?: number },\n  ) => Promise<LedgerEntry>;\n  /** True once spend since `since` reaches `capSubUnits`. Fails OPEN — a\n   *  broken cap must not take down paid features, and the per-provider\n   *  budgets are still in front. */\n  overCap: (capSubUnits: number, since: Date) => Promise<boolean>;\n};\n\nexport const createUsageLedger = (options: UsageLedgerOptions): UsageLedger => {\n  const { creditPegSubUnits, onRollupError, store } = options;\n\n  return {\n    overCap: async (capSubUnits, since) => {\n      if (!store.spentSince) return false;\n      try {\n        return (await store.spentSince(since)) >= capSubUnits;\n      } catch {\n        return false;\n      }\n    },\n    record: async (input) => {\n      const credits =\n        input.credits ??\n        (creditPegSubUnits === undefined\n          ? 0\n          : creditsFor(input.amount, creditPegSubUnits));\n      const entry: LedgerEntry = { ...input, credits };\n      // The charge is the thing that must not be lost; it is awaited and its\n      // failure propagates to the caller.\n      await store.commit(entry);\n      // The rollup is a derived index — rebuildable from the ledger — so its\n      // failure is reported, never raised.\n      if (store.rollup) {\n        await store.rollup(entry).catch((error: unknown) => {\n          onRollupError?.(error, entry);\n        });\n      }\n\n      return entry;\n    },\n  };\n};\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAkEO,IAAM,aAAa,CAAC,QAAgB,gBAAwB;AAAA,EACjE,IAAI,eAAe;AAAA,IAAG,OAAO;AAAA,EAE7B,OAAO,KAAK,KAAK,SAAS,WAAW;AAAA;AAehC,IAAM,oBAAoB,CAAC,YAA6C;AAAA,EAC7E,QAAQ,mBAAmB,eAAe,UAAU;AAAA,EAEpD,OAAO;AAAA,IACL,SAAS,OAAO,aAAa,UAAU;AAAA,MACrC,IAAI,CAAC,MAAM;AAAA,QAAY,OAAO;AAAA,MAC9B,IAAI;AAAA,QACF,OAAQ,MAAM,MAAM,WAAW,KAAK,KAAM;AAAA,QAC1C,MAAM;AAAA,QACN,OAAO;AAAA;AAAA;AAAA,IAGX,QAAQ,OAAO,UAAU;AAAA,MACvB,MAAM,UACJ,MAAM,YACL,sBAAsB,YACnB,IACA,WAAW,MAAM,QAAQ,iBAAiB;AAAA,MAChD,MAAM,QAAqB,KAAK,OAAO,QAAQ;AAAA,MAG/C,MAAM,MAAM,OAAO,KAAK;AAAA,MAGxB,IAAI,MAAM,QAAQ;AAAA,QAChB,MAAM,MAAM,OAAO,KAAK,EAAE,MAAM,CAAC,UAAmB;AAAA,UAClD,gBAAgB,OAAO,KAAK;AAAA,SAC7B;AAAA,MACH;AAAA,MAEA,OAAO;AAAA;AAAA,EAEX;AAAA;",
+  "debugId": "0E1FB04E107E92A964756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/billing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cost-model substrate for the AbsoluteJS PaaS. createPlan declares a priced product (base fee + per-dimension unit prices + tiered / free-tier rules); computeInvoice turns a @absolutejs/metering Usage snapshot into Invoice line items in integer micros (no float drift). Pluggable invoice sinks (Stripe / etc.) live in @absolutejs/billing-adapters/*.",
   "repository": {
     "type": "git",
@@ -27,7 +27,12 @@
       "import": "./dist/manifest.js",
       "default": "./dist/manifest.js"
     },
-    "./manifest.json": "./dist/manifest.json"
+    "./manifest.json": "./dist/manifest.json",
+    "./ledger": {
+      "default": "./dist/ledger.js",
+      "import": "./dist/ledger.js",
+      "types": "./dist/ledger.d.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -37,7 +42,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts --root ./src --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json && absolute-manifest emit",
+    "build": "rm -rf dist && bun build src/index.ts src/ledger.ts src/manifest.ts --root ./src --outdir dist --sourcemap --target=bun && tsc --project tsconfig.build.json && absolute-manifest emit",
     "test": "bun test tests/",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",