@absolutejs/billing 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `@absolutejs/billing`.
+
+This file is generated by `absolute-changelog` from the entries in
+`changelog/`. Edit an entry, not this file — and add new ones under
+`changelog/unreleased/`.
+
+## 0.7.0 — 2026-09-11
+
+### Added
+
+- **Add durable prepaid credit accounts, reservations, and capped idempotent work settlement**
+
+---
+
+## Earlier releases
+
+# @absolutejs/billing changelog
+
+## 0.1.0 — 2026-05-31
+
+Initial release. Closes G13 from the second-pass PaaS audit — the
+substrate now has a pure cost-model layer between
+`@absolutejs/metering` and any invoicing backend.
+
+### Added
+
+- **`createPlan({ name, basePriceMicros?, pricedDimensions,
+currency?, rounding?, minimumChargeMicros?, metadata? })`** —
+  declarative pricing config. Validates tiered dimensions at
+  construction: non-empty, final tier must be `upTo: Infinity`,
+  bounds must be monotonically non-decreasing.
+- **`computeInvoice({ plan, period, tenant, usage, currency? })`**
+  — pure function. Returns `{ tenant, plan, currency, period,
+lineItems, totalMicros, totalUnits, metadata? }`.
+- **Three pricing shapes** per dimension: flat `perUnitMicros`,
+  graduated `tiers`, or custom `price(quantity) => micros`.
+- **`freeTier`** per dimension subtracted before pricing.
+- **`unit`** divisor so `bytesEgress` priced as MB ↔ `unit:
+1024*1024`.
+- **Rounding modes**: `'truncate'` (default — sub-cent → $0.00 to
+  match operator intuition) and `'round-half-up'`.
+- **`minimumChargeMicros`** floor with an explicit
+  `'minimum-charge-adjustment'` line item that captures the gap
+  (transparent, not magical).
+- **`formatMicros(amount, currency, { minorUnits? })`** — pure
+  string formatter, honors zero-minor-unit currencies (JPY etc.).
+- **All money in integer micros** (1/1,000,000 of a unit) — same
+  denomination Stripe uses internally. Float drift structurally
+  impossible.
+
+### Design notes
+
+- Pure functions throughout — no IO, no SDK peers, no side effects.
+  The control plane can preview invoices, re-price past periods
+  under a proposed plan, and dry-run plan changes without touching
+  any external system.
+- Invoice push (Stripe, QuickBooks, mailed PDF) lives OUTSIDE this
+  package in `@absolutejs/billing-adapters/*`.
+- Substrate is intentionally policy-free: it doesn't pick the plan
+  for a tenant, doesn't fetch usage, doesn't store invoices. Those
+  are control-plane concerns.
+
+### Tests
+
+34 covering: tier validation; flat per-unit; zero / missing /
+negative / NaN usage; free tier (below / above / at boundary);
+unit divisor + truncation + round-half-up; tiered (single band /
+multi-band / unbounded final); tiered + free tier composition;
+custom price fn; chargedQuantity passed to custom fn; base fee
+emission + suppression-when-zero; minimum-charge top-up + no-op
+when above floor; currency defaults + override; metadata
+flow-through; realistic full-Usage shape; label override;
+formatMicros (whole / sub-cent / negative / zero-minor-unit).
+
+### License
+
+BSL-1.1 with named carveout against hosted SaaS-billing platforms
+(Metronome, Orb, Lago, Stripe Billing, m3ter, Chargebee). Change
+date: 2030-05-31 (Apache 2.0).

package/README.md

@@ -1,6 +1,6 @@
 # `@absolutejs/billing`
 
-> Cost-model substrate for the AbsoluteJS PaaS.
+> Provider-neutral pricing and invoice computation used by the hosted AbsoluteJS.ai platform.
 
 `@absolutejs/billing` is the pure-function layer between
 `@absolutejs/metering` (which collects usage events) and an
@@ -94,3 +94,7 @@ mailed-PDF generator) lives outside this package, in
 BSL-1.1 with named carveout against hosted SaaS billing platforms
 (Metronome, Orb, Lago, Stripe Billing, m3ter, Chargebee). See
 `LICENSE`. Change date: **2030-05-31** → Apache 2.0.
+
+## Prepaid service credits
+
+[Durable balances, reservations, capped work, and migration rules](docs/prepaid-credits.md) are available through the `prepaid`, `prepaid-postgres`, and `credit-work` subpaths.

package/changelog.json

@@ -0,0 +1,16 @@
+{
+	"contract": 1,
+	"name": "@absolutejs/billing",
+	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add durable prepaid credit accounts, reservations, and capped idempotent work settlement"
+				}
+			],
+			"date": "2026-09-11",
+			"version": "0.7.0"
+		}
+	]
+}

package/dist/creditWork.d.ts

@@ -0,0 +1,25 @@
+import { type CreditSqlClient } from "./prepaidPostgres";
+export type CreditWork = {
+    request: string;
+    budget: number;
+    charged: number;
+    absorbed: number;
+    status: "running" | "completed" | "failed";
+    result: string | null;
+};
+export declare const creditWorkPostgresSchemaSql: (schema?: string) => string;
+/** Durable execution claim + capped customer charge. A crash leaves work running
+ * and its credits held: never automatically rerun an uncertain external effect.
+ * Provider cost over the agreed budget is recorded as absorbed, not customer debt. */
+export declare const createPostgresCreditWork: (client: CreditSqlClient, schema?: string) => {
+    get: (accountId: string, workId: string) => Promise<CreditWork | null>;
+    begin: (accountId: string, workId: string, request: string, budget: number) => Promise<{
+        fresh: boolean;
+        work: CreditWork;
+    }>;
+    record: (accountId: string, workId: string, eventId: string, credits: number, reference: string) => Promise<{
+        charged: number;
+        fresh: boolean;
+    }>;
+    finish: (accountId: string, workId: string, result: string, failed?: boolean) => Promise<CreditWork>;
+};

package/dist/creditWork.js

@@ -0,0 +1,460 @@
+// @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/prepaid.ts
+var integer = (value) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error("Credits must be nonnegative safe integers");
+  return value;
+};
+var periodIdentity = (value) => {
+  if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value)
+    throw new Error("Credit period ID must be an ISO UTC start timestamp");
+  return value;
+};
+var identity = (value) => {
+  if (!value || value.length > 256)
+    throw new Error("Credit identity is invalid");
+  return value;
+};
+var validateCreditAccount = (account) => {
+  periodIdentity(account.periodId);
+  if (account.periodEnd !== null && periodIdentity(account.periodEnd) <= account.periodId)
+    throw new Error("Credit period end must follow its start");
+  for (const key of [
+    "periodAllowance",
+    "periodRemaining",
+    "purchasedRemaining",
+    "promotionalRemaining",
+    "debt",
+    "reserved",
+    "consumed"
+  ])
+    integer(account[key]);
+  integer(account.periodRemaining + account.purchasedRemaining + account.promotionalRemaining);
+  if (account.periodRemaining > account.periodAllowance)
+    throw new Error("Period balance exceeds its allowance");
+};
+var availableCredits = (account) => Math.max(0, account.periodRemaining + account.purchasedRemaining + account.promotionalRemaining - account.debt);
+var migrateLegacyCreditAccount = (input) => {
+  integer(input.periodAllowance);
+  integer(input.consumed);
+  if (!Number.isSafeInteger(input.bonusCredits))
+    throw new Error("Invalid legacy bonus credits");
+  const account = {
+    periodId: input.periodId,
+    periodEnd: input.periodEnd ?? null,
+    periodAllowance: input.periodAllowance,
+    periodRemaining: Math.max(0, input.periodAllowance - input.consumed),
+    purchasedRemaining: 0,
+    promotionalRemaining: Math.max(0, input.bonusCredits - Math.max(0, input.consumed - input.periodAllowance)),
+    debt: Math.max(0, -input.bonusCredits) + Math.max(0, input.consumed - input.periodAllowance - Math.max(0, input.bonusCredits)),
+    reserved: 0,
+    consumed: input.consumed
+  };
+  validateCreditAccount(account);
+  return account;
+};
+var allocationTotal = (value) => value.period + value.promotional + value.purchased;
+var take = (account, credits) => {
+  let owed = account.debt;
+  for (const key of [
+    "periodRemaining",
+    "promotionalRemaining",
+    "purchasedRemaining"
+  ]) {
+    const covered = Math.min(account[key], owed);
+    account[key] -= covered;
+    owed -= covered;
+  }
+  account.debt = owed;
+  const period = Math.min(account.periodRemaining, credits);
+  const promotional = Math.min(account.promotionalRemaining, credits - period);
+  const purchased = Math.min(account.purchasedRemaining, credits - period - promotional);
+  account.periodRemaining -= period;
+  account.promotionalRemaining -= promotional;
+  account.purchasedRemaining -= purchased;
+  return { period, promotional, purchased };
+};
+var grant = (account, key, credits) => {
+  const covered = Math.min(account.debt, credits);
+  account.debt -= covered;
+  account[key] = integer(account[key] + credits - covered);
+};
+var normalize = (command) => {
+  switch (command.kind) {
+    case "grant":
+    case "reverse":
+      if (command.bucket !== "purchased" && command.bucket !== "promotional")
+        throw new Error("Invalid credit bucket");
+      return {
+        kind: command.kind,
+        bucket: command.bucket,
+        credits: integer(command.credits)
+      };
+    case "period":
+      return {
+        kind: command.kind,
+        periodId: periodIdentity(command.periodId),
+        periodEnd: command.periodEnd === null ? null : periodIdentity(command.periodEnd),
+        allowance: integer(command.allowance)
+      };
+    case "reserve":
+    case "settle":
+      return {
+        kind: command.kind,
+        reservationId: identity(command.reservationId),
+        credits: integer(command.credits)
+      };
+    case "release":
+      return {
+        kind: command.kind,
+        reservationId: identity(command.reservationId)
+      };
+    case "debit":
+      return {
+        kind: command.kind,
+        credits: integer(command.credits),
+        allowDebt: command.allowDebt === true,
+        ...command.reference === undefined ? {} : { reference: identity(command.reference) }
+      };
+    default:
+      throw new Error("Invalid credit command");
+  }
+};
+var createCreditAccountLedger = (store) => ({
+  initialize: async (accountId, seed) => {
+    identity(accountId);
+    validateCreditAccount(seed);
+    await store.initialize(accountId, seed);
+  },
+  receipt: (accountId, operationId) => store.transaction(identity(accountId), (tx) => tx.receipt(identity(operationId))),
+  balance: (accountId) => store.read(identity(accountId)),
+  execute: async (accountId, operationId, input) => {
+    identity(accountId);
+    identity(operationId);
+    const command = normalize(input);
+    return store.transaction(accountId, async (tx) => {
+      const previous = await tx.receipt(operationId);
+      if (previous) {
+        if (JSON.stringify(normalize(previous.command)) !== JSON.stringify(command))
+          throw new Error("Credit operation ID reused with different input");
+        return previous;
+      }
+      const account = { ...tx.account };
+      validateCreditAccount(account);
+      let reservation;
+      switch (command.kind) {
+        case "grant":
+          grant(account, command.bucket === "purchased" ? "purchasedRemaining" : "promotionalRemaining", command.credits);
+          break;
+        case "reverse": {
+          const key = command.bucket === "purchased" ? "purchasedRemaining" : "promotionalRemaining";
+          const covered = Math.min(account[key], command.credits);
+          account[key] -= covered;
+          account.debt += command.credits - covered;
+          break;
+        }
+        case "period":
+          if (command.periodId < account.periodId)
+            throw new Error("Credit period cannot move backwards");
+          if (command.periodId === account.periodId) {
+            const increase = Math.max(0, command.allowance - account.periodAllowance);
+            if (account.periodEnd === null)
+              account.periodEnd = command.periodEnd;
+            account.periodAllowance += increase;
+            grant(account, "periodRemaining", increase);
+          } else {
+            account.periodId = command.periodId;
+            account.periodEnd = command.periodEnd;
+            account.periodAllowance = command.allowance;
+            account.periodRemaining = 0;
+            account.consumed = 0;
+            grant(account, "periodRemaining", command.allowance);
+          }
+          break;
+        case "debit": {
+          if (!command.allowDebt && availableCredits(account) < command.credits)
+            throw new Error("Insufficient credits");
+          const used = allocationTotal(take(account, command.credits));
+          account.debt += command.credits - used;
+          account.consumed += command.credits;
+          break;
+        }
+        case "reserve":
+          if (command.credits === 0)
+            throw new Error("Reservation must be positive");
+          if (await tx.reservation(command.reservationId))
+            throw new Error("Credit reservation already exists");
+          if (availableCredits(account) < command.credits)
+            throw new Error("Insufficient credits");
+          reservation = {
+            id: command.reservationId,
+            periodId: account.periodId,
+            allocation: take(account, command.credits),
+            status: "reserved",
+            charged: null
+          };
+          account.reserved += command.credits;
+          break;
+        case "settle":
+        case "release": {
+          const held = await tx.reservation(command.reservationId);
+          if (!held || held.status !== "reserved")
+            throw new Error("Credit reservation is not active");
+          const total = allocationTotal(held.allocation);
+          const charged = command.kind === "settle" ? command.credits : 0;
+          if (charged > total)
+            throw new Error("Charge exceeds reserved credits");
+          let refund = total - charged;
+          for (const [bucket, key] of [
+            ["purchased", "purchasedRemaining"],
+            ["promotional", "promotionalRemaining"],
+            ["period", "periodRemaining"]
+          ]) {
+            const restored = Math.min(held.allocation[bucket], refund);
+            refund -= restored;
+            if (bucket !== "period" || held.periodId === account.periodId)
+              grant(account, key, restored);
+          }
+          account.reserved -= total;
+          if (held.periodId === account.periodId)
+            account.consumed += charged;
+          reservation = {
+            ...held,
+            status: command.kind === "settle" ? "settled" : "released",
+            charged
+          };
+          break;
+        }
+      }
+      validateCreditAccount(account);
+      const receipt = {
+        command,
+        account,
+        ...reservation ? { reservation } : {}
+      };
+      await tx.save(operationId, receipt);
+      return receipt;
+    });
+  }
+});
+var creditEntitlements = (input) => {
+  const funded = input.prepaidEnabled && input.account !== null && input.account.purchasedRemaining + input.account.promotionalRemaining > 0 && availableCredits(input.account) > 0;
+  return {
+    portal: input.subscribed,
+    mcp: input.subscribed ? "member" : funded ? "prepaid" : "free"
+  };
+};
+
+// src/prepaidPostgres.ts
+var namespace = (value) => {
+  if (!/^[a-z][a-z0-9_]*$/.test(value))
+    throw new Error("Invalid credit schema name");
+  return value;
+};
+var creditAccountPostgresSchemaSql = (schema = "billing_credits") => {
+  const n = namespace(schema);
+  return `CREATE SCHEMA IF NOT EXISTS ${n};
+CREATE TABLE IF NOT EXISTS ${n}.accounts (
+  account_id text PRIMARY KEY, state jsonb NOT NULL, initial_state jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS ${n}.operations (
+  account_id text NOT NULL REFERENCES ${n}.accounts(account_id), operation_id text NOT NULL,
+  receipt jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (account_id, operation_id)
+);
+CREATE TABLE IF NOT EXISTS ${n}.reservations (
+  account_id text NOT NULL REFERENCES ${n}.accounts(account_id), reservation_id text NOT NULL,
+  state jsonb NOT NULL, updated_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (account_id, reservation_id)
+);`;
+};
+var createPostgresCreditAccountStore = (client, schema = "billing_credits") => {
+  const n = namespace(schema);
+  const read = async (sql, accountId, lock = false) => {
+    const { rows } = await sql.query(`SELECT state FROM ${n}.accounts WHERE account_id = $1${lock ? " FOR UPDATE" : ""}`, [accountId]);
+    if (!rows[0])
+      return null;
+    const state = rows[0].state;
+    validateCreditAccount(state);
+    return state;
+  };
+  return {
+    initialize: async (accountId, seed) => {
+      validateCreditAccount(seed);
+      await client.query(`INSERT INTO ${n}.accounts (account_id, state, initial_state) VALUES ($1, $2::jsonb, $2::jsonb) ON CONFLICT DO NOTHING`, [accountId, JSON.stringify(seed)]);
+    },
+    read: (accountId) => read(client, accountId),
+    transaction: (accountId, run) => client.transaction(async (sql) => {
+      const account = await read(sql, accountId, true);
+      if (!account)
+        throw new Error("Credit account is not initialized");
+      return run({
+        account,
+        receipt: async (operationId) => {
+          const { rows } = await sql.query(`SELECT receipt FROM ${n}.operations WHERE account_id = $1 AND operation_id = $2`, [accountId, operationId]);
+          return rows[0]?.receipt ?? null;
+        },
+        reservation: async (id) => {
+          const { rows } = await sql.query(`SELECT state FROM ${n}.reservations WHERE account_id = $1 AND reservation_id = $2`, [accountId, id]);
+          return rows[0]?.state ?? null;
+        },
+        save: async (operationId, receipt) => {
+          await sql.query(`UPDATE ${n}.accounts SET state = $2::jsonb, updated_at = now() WHERE account_id = $1`, [accountId, JSON.stringify(receipt.account)]);
+          if (receipt.reservation)
+            await sql.query(`INSERT INTO ${n}.reservations (account_id, reservation_id, state) VALUES ($1, $2, $3::jsonb) ON CONFLICT (account_id, reservation_id) DO UPDATE SET state = EXCLUDED.state, updated_at = now()`, [
+              accountId,
+              receipt.reservation.id,
+              JSON.stringify(receipt.reservation)
+            ]);
+          await sql.query(`INSERT INTO ${n}.operations (account_id, operation_id, receipt) VALUES ($1, $2, $3::jsonb)`, [accountId, operationId, JSON.stringify(receipt)]);
+        }
+      });
+    })
+  };
+};
+
+// src/creditWork.ts
+var namespace2 = (value) => {
+  if (!/^[a-z][a-z0-9_]*$/.test(value))
+    throw new Error("Invalid credit schema name");
+  return value;
+};
+var id = (value) => {
+  if (!value || value.length > 128)
+    throw new Error("Invalid credit work ID");
+};
+var integer2 = (value) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error("Invalid credit work amount");
+};
+var creditWorkPostgresSchemaSql = (schema = "billing_credits") => {
+  const n = namespace2(schema);
+  return `CREATE TABLE IF NOT EXISTS ${n}.work (
+    account_id text NOT NULL REFERENCES ${n}.accounts(account_id), work_id text NOT NULL,
+    state jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY(account_id, work_id)
+  );
+  CREATE TABLE IF NOT EXISTS ${n}.work_usage (
+    account_id text NOT NULL, work_id text NOT NULL, event_id text NOT NULL,
+    credits bigint NOT NULL CHECK (credits >= 0), charged bigint NOT NULL CHECK (charged >= 0 AND charged <= credits), reference text NOT NULL,
+    PRIMARY KEY(account_id, work_id, event_id), FOREIGN KEY(account_id, work_id) REFERENCES ${n}.work(account_id, work_id)
+  );`;
+};
+var createPostgresCreditWork = (client, schema = "billing_credits") => {
+  const n = namespace2(schema);
+  const read = async (sql, accountId, workId) => {
+    const { rows } = await sql.query(`SELECT state FROM ${n}.work WHERE account_id = $1 AND work_id = $2 FOR UPDATE`, [accountId, workId]);
+    return rows[0]?.state;
+  };
+  const save = (sql, accountId, workId, state) => sql.query(`UPDATE ${n}.work SET state = $3::jsonb, updated_at = now() WHERE account_id = $1 AND work_id = $2`, [accountId, workId, JSON.stringify(state)]);
+  const ledger = (sql) => createCreditAccountLedger(createPostgresCreditAccountStore({ ...sql, transaction: (run) => run(sql) }, schema));
+  return {
+    get: (accountId, workId) => {
+      id(accountId);
+      id(workId);
+      return client.transaction(async (sql) => await read(sql, accountId, workId) ?? null);
+    },
+    begin: (accountId, workId, request, budget) => {
+      id(accountId);
+      id(workId);
+      integer2(budget);
+      if (!budget || !request || request.length > 256)
+        throw new Error("Invalid credit work request");
+      return client.transaction(async (sql) => {
+        await sql.query(`SELECT account_id FROM ${n}.accounts WHERE account_id = $1 FOR UPDATE`, [accountId]);
+        const existing = await read(sql, accountId, workId);
+        if (existing) {
+          if (existing.request !== request || existing.budget !== budget)
+            throw new Error("Credit work ID reused with different input");
+          return { fresh: false, work: existing };
+        }
+        await ledger(sql).execute(accountId, `work-reserve:${workId}`, {
+          kind: "reserve",
+          reservationId: `work:${workId}`,
+          credits: budget
+        });
+        const work = {
+          request,
+          budget,
+          charged: 0,
+          absorbed: 0,
+          status: "running",
+          result: null
+        };
+        await sql.query(`INSERT INTO ${n}.work (account_id, work_id, state) VALUES ($1, $2, $3::jsonb)`, [accountId, workId, JSON.stringify(work)]);
+        return { fresh: true, work };
+      });
+    },
+    record: (accountId, workId, eventId, credits, reference) => {
+      id(accountId);
+      id(workId);
+      id(eventId);
+      integer2(credits);
+      id(reference);
+      return client.transaction(async (sql) => {
+        const work = await read(sql, accountId, workId);
+        if (!work)
+          throw new Error("Credit work does not exist");
+        const { rows } = await sql.query(`SELECT credits, charged, reference FROM ${n}.work_usage WHERE account_id = $1 AND work_id = $2 AND event_id = $3`, [accountId, workId, eventId]);
+        const previous = rows[0];
+        if (previous) {
+          if (Number(previous.credits) !== credits || previous.reference !== reference)
+            throw new Error("Credit work event reused with different input");
+          return { charged: Number(previous.charged), fresh: false };
+        }
+        if (work.status !== "running")
+          throw new Error("Credit work already finished");
+        const charged = Math.min(credits, work.budget - work.charged);
+        work.charged += charged;
+        work.absorbed += credits - charged;
+        integer2(work.charged);
+        integer2(work.absorbed);
+        await sql.query(`INSERT INTO ${n}.work_usage (account_id, work_id, event_id, credits, charged, reference) VALUES ($1, $2, $3, $4, $5, $6)`, [accountId, workId, eventId, credits, charged, reference]);
+        await save(sql, accountId, workId, work);
+        return { charged, fresh: true };
+      });
+    },
+    finish: (accountId, workId, result, failed = false) => {
+      id(accountId);
+      id(workId);
+      return client.transaction(async (sql) => {
+        await sql.query(`SELECT account_id FROM ${n}.accounts WHERE account_id = $1 FOR UPDATE`, [accountId]);
+        const work = await read(sql, accountId, workId);
+        if (!work)
+          throw new Error("Credit work does not exist");
+        if (work.status !== "running")
+          return work;
+        await ledger(sql).execute(accountId, `work-settle:${workId}`, {
+          kind: "settle",
+          reservationId: `work:${workId}`,
+          credits: work.charged
+        });
+        work.status = failed ? "failed" : "completed";
+        work.result = result;
+        await save(sql, accountId, workId, work);
+        return work;
+      });
+    }
+  };
+};
+export {
+  createPostgresCreditWork,
+  creditWorkPostgresSchemaSql
+};
+
+//# debugId=AA6CCB44B9F64D8964756E2164756E21
+//# sourceMappingURL=creditWork.js.map