@dainamite/billing 0.19.0 → 0.21.0

package/dist/modules/billing/lib/servicePeriods.js

@@ -0,0 +1,121 @@
+import { addDays, cloneAtMidnight, shiftCycles } from "./billPeriod.js";
+const MAX_PERIODS_PER_ITEM = 120;
+const DAY_MS = 864e5;
+function toDate(value) {
+  return cloneAtMidnight(value);
+}
+function optDate(value) {
+  return value === null || value === void 0 || value === "" ? null : toDate(value);
+}
+function minDate(a, b) {
+  return a.getTime() <= b.getTime() ? a : b;
+}
+function maxDate(a, b) {
+  return a.getTime() >= b.getTime() ? a : b;
+}
+function inclusiveDays(from, to) {
+  return Math.round((to.getTime() - from.getTime()) / DAY_MS) + 1;
+}
+function roundHalfUp2dp(value) {
+  const sign = value < 0 ? -1 : 1;
+  return sign * Math.round((Math.abs(value) + Number.EPSILON) * 100) / 100;
+}
+function gridPeriod(anchor, cycle, index) {
+  const start = shiftCycles(anchor, cycle, index);
+  const end = addDays(shiftCycles(anchor, cycle, index + 1), -1);
+  return { index, start, end };
+}
+function gridPeriodContaining(anchor, cycle, date) {
+  const target = date.getTime();
+  const approxDays = { weekly: 7, monthly: 30.44, quarterly: 91.31, annually: 365.25 };
+  let index = Math.floor((target - anchor.getTime()) / DAY_MS / approxDays[cycle]);
+  let period = gridPeriod(anchor, cycle, index);
+  let guard = 0;
+  while (period.start.getTime() > target && guard++ < 1e3) period = gridPeriod(anchor, cycle, --index);
+  while (period.end.getTime() < target && guard++ < 2e3) period = gridPeriod(anchor, cycle, ++index);
+  return period;
+}
+function slice(item, anchor, cycle, from, to, kind) {
+  const lines = [];
+  const skipped = [];
+  let lastCovered = null;
+  let period = gridPeriodContaining(anchor, cycle, from);
+  let count = 0;
+  while (period.start.getTime() <= to.getTime()) {
+    if (count++ >= MAX_PERIODS_PER_ITEM) {
+      skipped.push({ billingItemId: item.id, reason: "period-cap-reached", servicePeriodStart: period.start, servicePeriodEnd: null });
+      break;
+    }
+    const activeStart = maxDate(period.start, from);
+    const activeEnd = minDate(period.end, to);
+    const periodDays = inclusiveDays(period.start, period.end);
+    const activeDays = inclusiveDays(activeStart, activeEnd);
+    const partial = activeDays < periodDays;
+    if (partial && !item.prorate) {
+      skipped.push({
+        billingItemId: item.id,
+        reason: "partial-period-not-prorated",
+        servicePeriodStart: activeStart,
+        servicePeriodEnd: activeEnd
+      });
+    } else {
+      const gross = partial ? item.unitPrice * activeDays / periodDays : item.unitPrice;
+      const amount = roundHalfUp2dp(gross);
+      lines.push({
+        billingItemId: item.id,
+        kind,
+        servicePeriodStart: activeStart,
+        servicePeriodEnd: activeEnd,
+        amount: kind === "credit" ? -amount : amount,
+        proration: partial ? { activeDays, periodDays } : null
+      });
+    }
+    lastCovered = activeEnd;
+    period = gridPeriod(anchor, cycle, period.index + 1);
+  }
+  return { lines, skipped, lastCovered };
+}
+function computeRecurringLines(item, params) {
+  const billedTo = optDate(item.billedToDate);
+  if (item.deletedAt) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: "item-soft-deleted", servicePeriodStart: null, servicePeriodEnd: null }] };
+  }
+  if (!item.isActive) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: "item-inactive", servicePeriodStart: null, servicePeriodEnd: null }] };
+  }
+  const anchor = toDate(params.billDate);
+  const { cycle } = params;
+  const start = toDate(item.billStartDate);
+  const end = optDate(item.billEndDate);
+  if (end && billedTo && end.getTime() < billedTo.getTime()) {
+    if (!item.prorate) {
+      return {
+        lines: [],
+        newBilledToDate: billedTo,
+        skipped: [{ billingItemId: item.id, reason: "ended-after-billing-no-credit", servicePeriodStart: addDays(end, 1), servicePeriodEnd: billedTo }]
+      };
+    }
+    const credit = slice(item, anchor, cycle, maxDate(addDays(end, 1), start), billedTo, "credit");
+    return { lines: credit.lines, newBilledToDate: end, skipped: credit.skipped };
+  }
+  const horizon = item.chargeTiming === "in_arrears" ? addDays(anchor, -1) : addDays(shiftCycles(anchor, cycle, 1), -1);
+  const cursor = billedTo ? maxDate(addDays(billedTo, 1), start) : start;
+  const windowEnd = end ? minDate(horizon, end) : horizon;
+  if (cursor.getTime() > windowEnd.getTime()) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [] };
+  }
+  const charge = slice(item, anchor, cycle, cursor, windowEnd, "charge");
+  return {
+    lines: charge.lines,
+    newBilledToDate: charge.lastCovered ?? billedTo,
+    skipped: charge.skipped
+  };
+}
+export {
+  MAX_PERIODS_PER_ITEM,
+  computeRecurringLines,
+  gridPeriodContaining,
+  inclusiveDays,
+  roundHalfUp2dp
+};
+//# sourceMappingURL=servicePeriods.js.map

package/dist/modules/billing/lib/servicePeriods.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/servicePeriods.ts"],
+  "sourcesContent": ["import type { BillCycle, ChargeTiming } from '../data/validators'\nimport { addDays, cloneAtMidnight, shiftCycles } from './billPeriod'\n\n/**\n * Recurring-charge computation for one bill date (Spec A).\n *\n * Pure and storage-agnostic: given an item's state and the account's bill\n * date, decide which service periods to charge (or credit) and where the\n * item's `billed_to_date` watermark moves. The engine calls it once per item\n * per simulated bill date and owns persistence.\n *\n * Model:\n *   - The account's cycle grid is anchored at the bill date `D`:\n *     \u2026, D \u2212 cycle, D, D + cycle, \u2026  (each period `[g_k, g_{k+1} \u2212 1]`).\n *   - Horizon \u2014 how far the item is billed on `D`:\n *       in_advance \u2192 D + cycle \u2212 1     in_arrears \u2192 D \u2212 1\n *   - Cursor \u2014 first unbilled day: `billed_to_date + 1`, else `bill_start_date`.\n *   - The unbilled window `[cursor, min(horizon, bill_end_date)]` is cut along\n *     the grid; each grid period becomes one line (full \u2192 unit price,\n *     partial \u2192 prorated by calendar days, or skipped when `prorate=false`).\n *   - Credit (A-D2): an item ended (`bill_end_date`) before what was already\n *     billed (`billed_to_date`) gets negative lines for the unused days when\n *     `prorate=true`, and the watermark is pulled back to `bill_end_date`.\n *\n * The watermark is the single source of truth against double billing: every\n * computation starts at `billed_to_date + 1`, so switching timing, re-running\n * a bill date, or catching up can never charge a day twice.\n */\n\nexport type RecurringItemState = {\n  id: string\n  chargeTiming: ChargeTiming\n  prorate: boolean\n  billStartDate: Date | string\n  billEndDate?: Date | string | null\n  billedToDate?: Date | string | null\n  unitPrice: number\n  isActive: boolean\n  deletedAt?: Date | string | null\n}\n\nexport type ProrationInfo = { activeDays: number; periodDays: number }\n\nexport type RecurringLine = {\n  billingItemId: string\n  kind: 'charge' | 'credit'\n  /** Inclusive service period the line covers. */\n  servicePeriodStart: Date\n  servicePeriodEnd: Date\n  /** 2dp half-up; negative for credits. */\n  amount: number\n  /** Null when the line covers a full grid period. */\n  proration: ProrationInfo | null\n}\n\nexport type RecurringSkipReason =\n  | 'item-inactive'\n  | 'item-soft-deleted'\n  | 'partial-period-not-prorated'\n  | 'ended-after-billing-no-credit'\n  | 'period-cap-reached'\n\nexport type RecurringSkip = {\n  billingItemId: string\n  reason: RecurringSkipReason\n  servicePeriodStart: Date | null\n  servicePeriodEnd: Date | null\n}\n\nexport type RecurringComputation = {\n  lines: RecurringLine[]\n  /** Watermark after these lines; unchanged when nothing was billed. */\n  newBilledToDate: Date | null\n  skipped: RecurringSkip[]\n}\n\n/** Upper bound of grid periods processed per item per call (runaway guard). */\nexport const MAX_PERIODS_PER_ITEM = 120\n\nconst DAY_MS = 86_400_000\n\nfunction toDate(value: Date | string | number): Date {\n  return cloneAtMidnight(value)\n}\n\nfunction optDate(value: Date | string | null | undefined): Date | null {\n  return value === null || value === undefined || value === '' ? null : toDate(value)\n}\n\nfunction minDate(a: Date, b: Date): Date {\n  return a.getTime() <= b.getTime() ? a : b\n}\n\nfunction maxDate(a: Date, b: Date): Date {\n  return a.getTime() >= b.getTime() ? a : b\n}\n\n/** Inclusive day count of `[from, to]`. */\nexport function inclusiveDays(from: Date, to: Date): number {\n  return Math.round((to.getTime() - from.getTime()) / DAY_MS) + 1\n}\n\n/** Half-up 2dp rounding that survives binary floating point (1.005 \u2192 1.01). */\nexport function roundHalfUp2dp(value: number): number {\n  const sign = value < 0 ? -1 : 1\n  return (sign * Math.round((Math.abs(value) + Number.EPSILON) * 100)) / 100\n}\n\ntype GridPeriod = { index: number; start: Date; end: Date }\n\nfunction gridPeriod(anchor: Date, cycle: BillCycle, index: number): GridPeriod {\n  const start = shiftCycles(anchor, cycle, index)\n  const end = addDays(shiftCycles(anchor, cycle, index + 1), -1)\n  return { index, start, end }\n}\n\n/** Grid period (anchored at `anchor`) containing `date`. */\nexport function gridPeriodContaining(anchor: Date, cycle: BillCycle, date: Date): GridPeriod {\n  const target = date.getTime()\n  // Coarse estimate first so long gaps don't walk one cycle at a time.\n  const approxDays: Record<BillCycle, number> = { weekly: 7, monthly: 30.44, quarterly: 91.31, annually: 365.25 }\n  let index = Math.floor((target - anchor.getTime()) / DAY_MS / approxDays[cycle])\n  let period = gridPeriod(anchor, cycle, index)\n  let guard = 0\n  while (period.start.getTime() > target && guard++ < 1000) period = gridPeriod(anchor, cycle, --index)\n  while (period.end.getTime() < target && guard++ < 2000) period = gridPeriod(anchor, cycle, ++index)\n  return period\n}\n\n/**\n * Slices `[from, to]` along the grid and prices each slice. Shared by the\n * charge and credit paths so both prorate identically.\n */\nfunction slice(\n  item: RecurringItemState,\n  anchor: Date,\n  cycle: BillCycle,\n  from: Date,\n  to: Date,\n  kind: RecurringLine['kind'],\n): { lines: RecurringLine[]; skipped: RecurringSkip[]; lastCovered: Date | null } {\n  const lines: RecurringLine[] = []\n  const skipped: RecurringSkip[] = []\n  let lastCovered: Date | null = null\n  let period = gridPeriodContaining(anchor, cycle, from)\n  let count = 0\n  while (period.start.getTime() <= to.getTime()) {\n    if (count++ >= MAX_PERIODS_PER_ITEM) {\n      skipped.push({ billingItemId: item.id, reason: 'period-cap-reached', servicePeriodStart: period.start, servicePeriodEnd: null })\n      break\n    }\n    const activeStart = maxDate(period.start, from)\n    const activeEnd = minDate(period.end, to)\n    const periodDays = inclusiveDays(period.start, period.end)\n    const activeDays = inclusiveDays(activeStart, activeEnd)\n    const partial = activeDays < periodDays\n    if (partial && !item.prorate) {\n      skipped.push({\n        billingItemId: item.id,\n        reason: 'partial-period-not-prorated',\n        servicePeriodStart: activeStart,\n        servicePeriodEnd: activeEnd,\n      })\n    } else {\n      const gross = partial ? (item.unitPrice * activeDays) / periodDays : item.unitPrice\n      const amount = roundHalfUp2dp(gross)\n      lines.push({\n        billingItemId: item.id,\n        kind,\n        servicePeriodStart: activeStart,\n        servicePeriodEnd: activeEnd,\n        amount: kind === 'credit' ? -amount : amount,\n        proration: partial ? { activeDays, periodDays } : null,\n      })\n    }\n    lastCovered = activeEnd\n    period = gridPeriod(anchor, cycle, period.index + 1)\n  }\n  return { lines, skipped, lastCovered }\n}\n\nexport function computeRecurringLines(\n  item: RecurringItemState,\n  params: { billDate: Date | string; cycle: BillCycle },\n): RecurringComputation {\n  const billedTo = optDate(item.billedToDate)\n  if (item.deletedAt) {\n    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: 'item-soft-deleted', servicePeriodStart: null, servicePeriodEnd: null }] }\n  }\n  if (!item.isActive) {\n    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: 'item-inactive', servicePeriodStart: null, servicePeriodEnd: null }] }\n  }\n\n  const anchor = toDate(params.billDate)\n  const { cycle } = params\n  const start = toDate(item.billStartDate)\n  const end = optDate(item.billEndDate)\n\n  // \u2500\u2500 Credit: the item ended inside what was already billed (A-D2). \u2500\u2500\n  if (end && billedTo && end.getTime() < billedTo.getTime()) {\n    if (!item.prorate) {\n      return {\n        lines: [],\n        newBilledToDate: billedTo,\n        skipped: [{ billingItemId: item.id, reason: 'ended-after-billing-no-credit', servicePeriodStart: addDays(end, 1), servicePeriodEnd: billedTo }],\n      }\n    }\n    const credit = slice(item, anchor, cycle, maxDate(addDays(end, 1), start), billedTo, 'credit')\n    return { lines: credit.lines, newBilledToDate: end, skipped: credit.skipped }\n  }\n\n  // \u2500\u2500 Charge: bill the unbilled window up to the horizon. \u2500\u2500\n  const horizon =\n    item.chargeTiming === 'in_arrears' ? addDays(anchor, -1) : addDays(shiftCycles(anchor, cycle, 1), -1)\n  const cursor = billedTo ? maxDate(addDays(billedTo, 1), start) : start\n  const windowEnd = end ? minDate(horizon, end) : horizon\n  if (cursor.getTime() > windowEnd.getTime()) {\n    return { lines: [], newBilledToDate: billedTo, skipped: [] }\n  }\n  const charge = slice(item, anchor, cycle, cursor, windowEnd, 'charge')\n  return {\n    lines: charge.lines,\n    newBilledToDate: charge.lastCovered ?? billedTo,\n    skipped: charge.skipped,\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/billing/lib/tenantLock.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/tenantLock.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\n\n/**\n * Per-tenant Postgres transaction-scoped advisory lock primitive.\n *\n * The Bill Run engine (Phase 2) uses this to guarantee at most one\n * concurrently-running run per tenant \u2014 the spec requires this so two\n * cron triggers or a \"schedule\" + \"manual\" overlap cannot produce\n * duplicate drafts.\n *\n * Why advisory locks (not row locks):\n *   - `pg_try_advisory_xact_lock` is non-blocking \u2014 we get a clean \"busy\"\n *     signal instead of waiting on a row.\n *   - It's released automatically when the transaction ends (commit,\n *     rollback, or process death) \u2014 so there is no lock-leak path even\n *     on `kill -9`. The `BillRun` row's `status='running'` may be left\n *     hanging, but the lock itself vanishes; the reaper worker\n *     (workers/reap-stale-bill-runs.ts) handles the orphaned row.\n *   - It works without a sentinel table \u2014 we hash a string key into the\n *     bigint key space the advisory-lock API requires.\n *\n * Usage:\n *\n * ```ts\n * import { withTenantLock, TenantLockBusyError } from '../lib/tenantLock'\n *\n * try {\n *   await withTenantLock(em, { tenantId, lockName: 'billing-run' }, async (tem) => {\n *     // tem is the transactional EntityManager; lock is held here.\n *     // Returns to caller after function resolves and tx commits.\n *   })\n * } catch (err) {\n *   if (err instanceof TenantLockBusyError) {\n *     // HTTP 409 \u2014 another run is in progress.\n *   }\n *   throw err\n * }\n * ```\n *\n * Keep work inside the callback short. The advisory lock is released only\n * when the transaction ends; long-running work blocks other triggers for\n * the whole tenant.\n */\n\nexport class TenantLockBusyError extends Error {\n  readonly tenantId: string\n  readonly lockName: string\n\n  constructor(tenantId: string, lockName: string) {\n    super(`Tenant ${tenantId} already holds the billing lock \"${lockName}\"`)\n    this.name = 'TenantLockBusyError'\n    this.tenantId = tenantId\n    this.lockName = lockName\n  }\n}\n\nconst LOCK_KEY_PREFIX = 'dainamite-billing'\n\n/**\n * Build the deterministic string key fed into `hashtext()`. Exposed for\n * tests so they can assert lock-key independence across tenants /\n * lockNames without scraping SQL strings.\n */\nexport function buildLockKey(tenantId: string, lockName: string): string {\n  return `${LOCK_KEY_PREFIX}:${tenantId}:${lockName}`\n}\n\ntype AdvisoryLockRow = { acquired: boolean }\n\nexport async function withTenantLock<T>(\n  em: EntityManager,\n  params: { tenantId: string; lockName: string },\n  fn: (tem: EntityManager) => Promise<T>,\n): Promise<T> {\n  return em.transactional(async (tem) => {\n    const key = buildLockKey(params.tenantId, params.lockName)\n    const rows = (await tem.execute(\n      'SELECT pg_try_advisory_xact_lock(hashtext(?)::bigint) AS acquired',\n      [key],\n    )) as unknown as AdvisoryLockRow[] | AdvisoryLockRow | undefined\n    const first: AdvisoryLockRow | undefined = Array.isArray(rows) ? rows[0] : rows\n    if (!first?.acquired) {\n      throw new TenantLockBusyError(params.tenantId, params.lockName)\n    }\n    return fn(tem)\n  })\n}\n"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\n\n/**\n * Per-tenant Postgres transaction-scoped advisory lock primitive.\n *\n * The Bill Run engine (Phase 2) uses this to guarantee at most one\n * concurrently-running run per tenant \u2014 the spec requires this so two\n * cron triggers or a \"schedule\" + \"manual\" overlap cannot produce\n * duplicate drafts.\n *\n * Why advisory locks (not row locks):\n *   - `pg_try_advisory_xact_lock` is non-blocking \u2014 we get a clean \"busy\"\n *     signal instead of waiting on a row.\n *   - It's released automatically when the transaction ends (commit,\n *     rollback, or process death) \u2014 so there is no lock-leak path even\n *     on `kill -9`. The `BillingRun` row's `status='running'` may be left\n *     hanging, but the lock itself vanishes; the reaper worker\n *     (workers/reap-stale-bill-runs.ts) handles the orphaned row.\n *   - It works without a sentinel table \u2014 we hash a string key into the\n *     bigint key space the advisory-lock API requires.\n *\n * Usage:\n *\n * ```ts\n * import { withTenantLock, TenantLockBusyError } from '../lib/tenantLock'\n *\n * try {\n *   await withTenantLock(em, { tenantId, lockName: 'billing-run' }, async (tem) => {\n *     // tem is the transactional EntityManager; lock is held here.\n *     // Returns to caller after function resolves and tx commits.\n *   })\n * } catch (err) {\n *   if (err instanceof TenantLockBusyError) {\n *     // HTTP 409 \u2014 another run is in progress.\n *   }\n *   throw err\n * }\n * ```\n *\n * Keep work inside the callback short. The advisory lock is released only\n * when the transaction ends; long-running work blocks other triggers for\n * the whole tenant.\n */\n\nexport class TenantLockBusyError extends Error {\n  readonly tenantId: string\n  readonly lockName: string\n\n  constructor(tenantId: string, lockName: string) {\n    super(`Tenant ${tenantId} already holds the billing lock \"${lockName}\"`)\n    this.name = 'TenantLockBusyError'\n    this.tenantId = tenantId\n    this.lockName = lockName\n  }\n}\n\nconst LOCK_KEY_PREFIX = 'dainamite-billing'\n\n/**\n * Build the deterministic string key fed into `hashtext()`. Exposed for\n * tests so they can assert lock-key independence across tenants /\n * lockNames without scraping SQL strings.\n */\nexport function buildLockKey(tenantId: string, lockName: string): string {\n  return `${LOCK_KEY_PREFIX}:${tenantId}:${lockName}`\n}\n\ntype AdvisoryLockRow = { acquired: boolean }\n\nexport async function withTenantLock<T>(\n  em: EntityManager,\n  params: { tenantId: string; lockName: string },\n  fn: (tem: EntityManager) => Promise<T>,\n): Promise<T> {\n  return em.transactional(async (tem) => {\n    const key = buildLockKey(params.tenantId, params.lockName)\n    const rows = (await tem.execute(\n      'SELECT pg_try_advisory_xact_lock(hashtext(?)::bigint) AS acquired',\n      [key],\n    )) as unknown as AdvisoryLockRow[] | AdvisoryLockRow | undefined\n    const first: AdvisoryLockRow | undefined = Array.isArray(rows) ? rows[0] : rows\n    if (!first?.acquired) {\n      throw new TenantLockBusyError(params.tenantId, params.lockName)\n    }\n    return fn(tem)\n  })\n}\n"],
   "mappings": "AA4CO,MAAM,4BAA4B,MAAM;AAAA,EAI7C,YAAY,UAAkB,UAAkB;AAC9C,UAAM,UAAU,QAAQ,oCAAoC,QAAQ,GAAG;AACvE,SAAK,OAAO;AACZ,SAAK,WAAW;AAChB,SAAK,WAAW;AAAA,EAClB;AACF;AAEA,MAAM,kBAAkB;AAOjB,SAAS,aAAa,UAAkB,UAA0B;AACvE,SAAO,GAAG,eAAe,IAAI,QAAQ,IAAI,QAAQ;AACnD;AAIA,eAAsB,eACpB,IACA,QACA,IACY;AACZ,SAAO,GAAG,cAAc,OAAO,QAAQ;AACrC,UAAM,MAAM,aAAa,OAAO,UAAU,OAAO,QAAQ;AACzD,UAAM,OAAQ,MAAM,IAAI;AAAA,MACtB;AAAA,MACA,CAAC,GAAG;AAAA,IACN;AACA,UAAM,QAAqC,MAAM,QAAQ,IAAI,IAAI,KAAK,CAAC,IAAI;AAC3E,QAAI,CAAC,OAAO,UAAU;AACpB,YAAM,IAAI,oBAAoB,OAAO,UAAU,OAAO,QAAQ;AAAA,IAChE;AACA,WAAO,GAAG,GAAG;AAAA,EACf,CAAC;AACH;",
   "names": []
 }

package/dist/modules/billing/lib/testRunCleanup.js

@@ -0,0 +1,24 @@
+async function deleteTestRunArtifacts(em, scope) {
+  const params = [scope.tenantId, scope.organizationId];
+  let billRunClause = "";
+  if (scope.billRunId) {
+    billRunClause = " AND bill_run_id = ?";
+    params.push(scope.billRunId);
+  }
+  const rows = await em.execute(
+    `SELECT id FROM billing_invoices
+     WHERE tenant_id = ? AND organization_id = ? AND test_run = true AND document_type = 'invoice'${billRunClause}`,
+    params
+  );
+  const ids = (rows ?? []).map((row) => row.id);
+  if (ids.length === 0) return 0;
+  const placeholders = ids.map(() => "?").join(",");
+  await em.execute(`DELETE FROM billing_draft_invoice_edits WHERE invoice_id IN (${placeholders})`, ids);
+  await em.execute(`DELETE FROM billing_invoice_lines WHERE invoice_id IN (${placeholders})`, ids);
+  await em.execute(`DELETE FROM billing_invoices WHERE id IN (${placeholders})`, ids);
+  return ids.length;
+}
+export {
+  deleteTestRunArtifacts
+};
+//# sourceMappingURL=testRunCleanup.js.map

package/dist/modules/billing/lib/testRunCleanup.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/testRunCleanup.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\n\n/**\n * Test-run cleanup shared by the \"wipe test invoices\" and \"delete run\"\n * commands (Spec F, P-D1).\n *\n * Hard-deletes test drafts (`test_run = true`, `document_type = 'invoice'`)\n * together with their lines and their draft-edit audit rows. Scoped by\n * tenant + organization, and optionally by one Bill Run. Must run inside the\n * caller's transaction.\n */\n\nexport type TestRunCleanupScope = {\n  tenantId: string\n  organizationId: string\n  /** When set, only test invoices written by this Bill Run are removed. */\n  billRunId?: string | null\n}\n\nexport async function deleteTestRunArtifacts(\n  em: EntityManager,\n  scope: TestRunCleanupScope,\n): Promise<number> {\n  const params: unknown[] = [scope.tenantId, scope.organizationId]\n  let billRunClause = ''\n  if (scope.billRunId) {\n    billRunClause = ' AND bill_run_id = ?'\n    params.push(scope.billRunId)\n  }\n  const rows = (await em.execute(\n    `SELECT id FROM billing_invoices\n     WHERE tenant_id = ? AND organization_id = ? AND test_run = true AND document_type = 'invoice'${billRunClause}`,\n    params,\n  )) as unknown as Array<{ id: string }> | undefined\n  const ids = (rows ?? []).map((row) => row.id)\n  if (ids.length === 0) return 0\n  const placeholders = ids.map(() => '?').join(',')\n  await em.execute(`DELETE FROM billing_draft_invoice_edits WHERE invoice_id IN (${placeholders})`, ids)\n  await em.execute(`DELETE FROM billing_invoice_lines WHERE invoice_id IN (${placeholders})`, ids)\n  await em.execute(`DELETE FROM billing_invoices WHERE id IN (${placeholders})`, ids)\n  return ids.length\n}\n"],
+  "mappings": "AAmBA,eAAsB,uBACpB,IACA,OACiB;AACjB,QAAM,SAAoB,CAAC,MAAM,UAAU,MAAM,cAAc;AAC/D,MAAI,gBAAgB;AACpB,MAAI,MAAM,WAAW;AACnB,oBAAgB;AAChB,WAAO,KAAK,MAAM,SAAS;AAAA,EAC7B;AACA,QAAM,OAAQ,MAAM,GAAG;AAAA,IACrB;AAAA,oGACgG,aAAa;AAAA,IAC7G;AAAA,EACF;AACA,QAAM,OAAO,QAAQ,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE;AAC5C,MAAI,IAAI,WAAW,EAAG,QAAO;AAC7B,QAAM,eAAe,IAAI,IAAI,MAAM,GAAG,EAAE,KAAK,GAAG;AAChD,QAAM,GAAG,QAAQ,gEAAgE,YAAY,KAAK,GAAG;AACrG,QAAM,GAAG,QAAQ,0DAA0D,YAAY,KAAK,GAAG;AAC/F,QAAM,GAAG,QAAQ,6CAA6C,YAAY,KAAK,GAAG;AAClF,SAAO,IAAI;AACb;",
+  "names": []
+}

package/dist/modules/billing/lib/topupCapture.js

@@ -1,7 +1,7 @@
 import { BillingTopup } from "../data/entities.js";
 import { applyBalanceMovement } from "./balanceLedger.js";
 import { createTopupReceipt } from "./topupReceipt.js";
-async function captureTopup(em, deps, params) {
+async function captureTopup(em, params) {
   const { topup, account } = params;
   if (topup.status === "captured") {
     return { status: "already_captured" };
@@ -32,7 +32,7 @@ async function captureTopup(em, deps, params) {
         receiptInvoiceId: prior?.receiptInvoiceId ?? void 0
       };
     }
-    const receipt = await createTopupReceipt(tem, deps, {
+    const receipt = await createTopupReceipt(tem, {
       account,
       topupId: topup.id,
       paymentId: topup.paymentId,

package/dist/modules/billing/lib/topupCapture.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/topupCapture.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { BillingTopup } from '../data/entities'\nimport { applyBalanceMovement } from './balanceLedger'\nimport { createTopupReceipt, type TopupReceiptDeps } from './topupReceipt'\n\n/**\n * Idempotent top-up capture (SPEC-002 P2).\n *\n * On `payment_gateways.payment.captured` for a top-up, in ONE DB transaction:\n *   - credit the balance (atomic) + append a `type='topup'` transaction with a\n *     deterministic `source_ref = topup-{paymentId}` (so a re-fired capture can\n *     never double-credit),\n *   - create the posted+paid VAT receipt in core/sales,\n *   - transition the BillingTopup \u2192 captured, backfilling `transaction_id` +\n *     `receipt_invoice_id`.\n *\n * Re-firing on an already-captured top-up is a no-op (the gateway delivers\n * webhooks at-least-once).\n */\n\nexport type CaptureTopupAccount = {\n  id: string\n  organizationId: string\n  tenantId: string\n  currencyCode: string\n}\n\nexport type CaptureTopupParams = {\n  topup: BillingTopup\n  account: CaptureTopupAccount\n  /** VAT percent applied to the receipt. */\n  taxRate: number\n  /** Provider transaction id for the transaction metadata, if known. */\n  gatewayTransactionId?: string | null\n}\n\nexport type CaptureTopupResult = {\n  status: 'captured' | 'already_captured'\n  balanceAfter?: string\n  transactionId?: string\n  receiptInvoiceId?: string\n  invoiceNumber?: string\n  grossAmount?: string\n}\n\nexport async function captureTopup(\n  em: EntityManager,\n  deps: TopupReceiptDeps,\n  params: CaptureTopupParams,\n): Promise<CaptureTopupResult> {\n  const { topup, account } = params\n\n  if (topup.status === 'captured') {\n    return { status: 'already_captured' }\n  }\n\n  return em.transactional(async (tem) => {\n    // 1. Atomic credit + paired transaction (idempotent on source_ref).\n    const movement = await applyBalanceMovement(tem as EntityManager, {\n      organizationId: account.organizationId,\n      tenantId: account.tenantId,\n      billAccountId: account.id,\n      currencyCode: account.currencyCode,\n      type: 'topup',\n      amount: topup.amount,\n      description: `Top-up \u2014 ${topup.providerKey}`,\n      topupId: topup.id,\n      sourceRef: `topup-${topup.paymentId}`,\n      metadata: {\n        provider_key: topup.providerKey,\n        payment_id: topup.paymentId,\n        gateway_transaction_id: params.gatewayTransactionId ?? topup.gatewayTransactionId ?? null,\n      },\n    })\n\n    // A deduplicated credit means a PRIOR capture already committed (the\n    // gateway delivers `payment.captured` at-least-once, and the stale\n    // `status` check above can race a concurrent capture). Do NOT issue a\n    // second fiscal receipt \u2014 return the existing capture's links.\n    if (movement.deduplicated) {\n      const prior = await tem.findOne(BillingTopup, { id: topup.id })\n      return {\n        status: 'already_captured' as const,\n        balanceAfter: movement.balanceAfter,\n        transactionId: prior?.transactionId ?? movement.transaction.id,\n        receiptInvoiceId: prior?.receiptInvoiceId ?? undefined,\n      }\n    }\n\n    // 2. Fiscal VAT receipt (posted+paid).\n    const receipt = await createTopupReceipt(tem as EntityManager, deps, {\n      account,\n      topupId: topup.id,\n      paymentId: topup.paymentId,\n      amount: topup.amount,\n      taxRate: params.taxRate,\n    })\n\n    // 3. Transition the top-up.\n    const managed = await tem.findOne(BillingTopup, { id: topup.id })\n    const target = managed ?? topup\n    target.status = 'captured'\n    target.transactionId = movement.transaction.id\n    target.receiptInvoiceId = receipt.invoiceId\n    target.updatedAt = new Date()\n    await tem.flush()\n\n    return {\n      status: 'captured' as const,\n      balanceAfter: movement.balanceAfter,\n      transactionId: movement.transaction.id,\n      receiptInvoiceId: receipt.invoiceId,\n      invoiceNumber: receipt.invoiceNumber,\n      grossAmount: receipt.grossAmount,\n    }\n  })\n}\n"],
-  "mappings": "AACA,SAAS,oBAAoB;AAC7B,SAAS,4BAA4B;AACrC,SAAS,0BAAiD;AA0C1D,eAAsB,aACpB,IACA,MACA,QAC6B;AAC7B,QAAM,EAAE,OAAO,QAAQ,IAAI;AAE3B,MAAI,MAAM,WAAW,YAAY;AAC/B,WAAO,EAAE,QAAQ,mBAAmB;AAAA,EACtC;AAEA,SAAO,GAAG,cAAc,OAAO,QAAQ;AAErC,UAAM,WAAW,MAAM,qBAAqB,KAAsB;AAAA,MAChE,gBAAgB,QAAQ;AAAA,MACxB,UAAU,QAAQ;AAAA,MAClB,eAAe,QAAQ;AAAA,MACvB,cAAc,QAAQ;AAAA,MACtB,MAAM;AAAA,MACN,QAAQ,MAAM;AAAA,MACd,aAAa,iBAAY,MAAM,WAAW;AAAA,MAC1C,SAAS,MAAM;AAAA,MACf,WAAW,SAAS,MAAM,SAAS;AAAA,MACnC,UAAU;AAAA,QACR,cAAc,MAAM;AAAA,QACpB,YAAY,MAAM;AAAA,QAClB,wBAAwB,OAAO,wBAAwB,MAAM,wBAAwB;AAAA,MACvF;AAAA,IACF,CAAC;AAMD,QAAI,SAAS,cAAc;AACzB,YAAM,QAAQ,MAAM,IAAI,QAAQ,cAAc,EAAE,IAAI,MAAM,GAAG,CAAC;AAC9D,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,cAAc,SAAS;AAAA,QACvB,eAAe,OAAO,iBAAiB,SAAS,YAAY;AAAA,QAC5D,kBAAkB,OAAO,oBAAoB;AAAA,MAC/C;AAAA,IACF;AAGA,UAAM,UAAU,MAAM,mBAAmB,KAAsB,MAAM;AAAA,MACnE;AAAA,MACA,SAAS,MAAM;AAAA,MACf,WAAW,MAAM;AAAA,MACjB,QAAQ,MAAM;AAAA,MACd,SAAS,OAAO;AAAA,IAClB,CAAC;AAGD,UAAM,UAAU,MAAM,IAAI,QAAQ,cAAc,EAAE,IAAI,MAAM,GAAG,CAAC;AAChE,UAAM,SAAS,WAAW;AAC1B,WAAO,SAAS;AAChB,WAAO,gBAAgB,SAAS,YAAY;AAC5C,WAAO,mBAAmB,QAAQ;AAClC,WAAO,YAAY,oBAAI,KAAK;AAC5B,UAAM,IAAI,MAAM;AAEhB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,SAAS;AAAA,MACvB,eAAe,SAAS,YAAY;AAAA,MACpC,kBAAkB,QAAQ;AAAA,MAC1B,eAAe,QAAQ;AAAA,MACvB,aAAa,QAAQ;AAAA,IACvB;AAAA,EACF,CAAC;AACH;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { BillingTopup } from '../data/entities'\nimport { applyBalanceMovement } from './balanceLedger'\nimport { createTopupReceipt } from './topupReceipt'\n\n/**\n * Idempotent top-up capture (SPEC-002 P2).\n *\n * On `payment_gateways.payment.captured` for a top-up, in ONE DB transaction:\n *   - credit the balance (atomic) + append a `type='topup'` transaction with a\n *     deterministic `source_ref = topup-{paymentId}` (so a re-fired capture can\n *     never double-credit),\n *   - create the paid VAT receipt as a billing document (`document_type = 'receipt'`),\n *   - transition the BillingTopup \u2192 captured, backfilling `transaction_id` +\n *     `receipt_invoice_id`.\n *\n * Re-firing on an already-captured top-up is a no-op (the gateway delivers\n * webhooks at-least-once).\n */\n\nexport type CaptureTopupAccount = {\n  id: string\n  organizationId: string\n  tenantId: string\n  currencyCode: string\n}\n\nexport type CaptureTopupParams = {\n  topup: BillingTopup\n  account: CaptureTopupAccount\n  /** VAT percent applied to the receipt. */\n  taxRate: number\n  /** Provider transaction id for the transaction metadata, if known. */\n  gatewayTransactionId?: string | null\n}\n\nexport type CaptureTopupResult = {\n  status: 'captured' | 'already_captured'\n  balanceAfter?: string\n  transactionId?: string\n  receiptInvoiceId?: string\n  invoiceNumber?: string\n  grossAmount?: string\n}\n\nexport async function captureTopup(\n  em: EntityManager,\n  params: CaptureTopupParams,\n): Promise<CaptureTopupResult> {\n  const { topup, account } = params\n\n  if (topup.status === 'captured') {\n    return { status: 'already_captured' }\n  }\n\n  return em.transactional(async (tem) => {\n    // 1. Atomic credit + paired transaction (idempotent on source_ref).\n    const movement = await applyBalanceMovement(tem as EntityManager, {\n      organizationId: account.organizationId,\n      tenantId: account.tenantId,\n      billAccountId: account.id,\n      currencyCode: account.currencyCode,\n      type: 'topup',\n      amount: topup.amount,\n      description: `Top-up \u2014 ${topup.providerKey}`,\n      topupId: topup.id,\n      sourceRef: `topup-${topup.paymentId}`,\n      metadata: {\n        provider_key: topup.providerKey,\n        payment_id: topup.paymentId,\n        gateway_transaction_id: params.gatewayTransactionId ?? topup.gatewayTransactionId ?? null,\n      },\n    })\n\n    // A deduplicated credit means a PRIOR capture already committed (the\n    // gateway delivers `payment.captured` at-least-once, and the stale\n    // `status` check above can race a concurrent capture). Do NOT issue a\n    // second fiscal receipt \u2014 return the existing capture's links.\n    if (movement.deduplicated) {\n      const prior = await tem.findOne(BillingTopup, { id: topup.id })\n      return {\n        status: 'already_captured' as const,\n        balanceAfter: movement.balanceAfter,\n        transactionId: prior?.transactionId ?? movement.transaction.id,\n        receiptInvoiceId: prior?.receiptInvoiceId ?? undefined,\n      }\n    }\n\n    // 2. Fiscal VAT receipt (posted+paid).\n    const receipt = await createTopupReceipt(tem as EntityManager, {\n      account,\n      topupId: topup.id,\n      paymentId: topup.paymentId,\n      amount: topup.amount,\n      taxRate: params.taxRate,\n    })\n\n    // 3. Transition the top-up.\n    const managed = await tem.findOne(BillingTopup, { id: topup.id })\n    const target = managed ?? topup\n    target.status = 'captured'\n    target.transactionId = movement.transaction.id\n    target.receiptInvoiceId = receipt.invoiceId\n    target.updatedAt = new Date()\n    await tem.flush()\n\n    return {\n      status: 'captured' as const,\n      balanceAfter: movement.balanceAfter,\n      transactionId: movement.transaction.id,\n      receiptInvoiceId: receipt.invoiceId,\n      invoiceNumber: receipt.invoiceNumber,\n      grossAmount: receipt.grossAmount,\n    }\n  })\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAC7B,SAAS,4BAA4B;AACrC,SAAS,0BAA0B;AA0CnC,eAAsB,aACpB,IACA,QAC6B;AAC7B,QAAM,EAAE,OAAO,QAAQ,IAAI;AAE3B,MAAI,MAAM,WAAW,YAAY;AAC/B,WAAO,EAAE,QAAQ,mBAAmB;AAAA,EACtC;AAEA,SAAO,GAAG,cAAc,OAAO,QAAQ;AAErC,UAAM,WAAW,MAAM,qBAAqB,KAAsB;AAAA,MAChE,gBAAgB,QAAQ;AAAA,MACxB,UAAU,QAAQ;AAAA,MAClB,eAAe,QAAQ;AAAA,MACvB,cAAc,QAAQ;AAAA,MACtB,MAAM;AAAA,MACN,QAAQ,MAAM;AAAA,MACd,aAAa,iBAAY,MAAM,WAAW;AAAA,MAC1C,SAAS,MAAM;AAAA,MACf,WAAW,SAAS,MAAM,SAAS;AAAA,MACnC,UAAU;AAAA,QACR,cAAc,MAAM;AAAA,QACpB,YAAY,MAAM;AAAA,QAClB,wBAAwB,OAAO,wBAAwB,MAAM,wBAAwB;AAAA,MACvF;AAAA,IACF,CAAC;AAMD,QAAI,SAAS,cAAc;AACzB,YAAM,QAAQ,MAAM,IAAI,QAAQ,cAAc,EAAE,IAAI,MAAM,GAAG,CAAC;AAC9D,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,cAAc,SAAS;AAAA,QACvB,eAAe,OAAO,iBAAiB,SAAS,YAAY;AAAA,QAC5D,kBAAkB,OAAO,oBAAoB;AAAA,MAC/C;AAAA,IACF;AAGA,UAAM,UAAU,MAAM,mBAAmB,KAAsB;AAAA,MAC7D;AAAA,MACA,SAAS,MAAM;AAAA,MACf,WAAW,MAAM;AAAA,MACjB,QAAQ,MAAM;AAAA,MACd,SAAS,OAAO;AAAA,IAClB,CAAC;AAGD,UAAM,UAAU,MAAM,IAAI,QAAQ,cAAc,EAAE,IAAI,MAAM,GAAG,CAAC;AAChE,UAAM,SAAS,WAAW;AAC1B,WAAO,SAAS;AAChB,WAAO,gBAAgB,SAAS,YAAY;AAC5C,WAAO,mBAAmB,QAAQ;AAClC,WAAO,YAAY,oBAAI,KAAK;AAC5B,UAAM,IAAI,MAAM;AAEhB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,SAAS;AAAA,MACvB,eAAe,SAAS,YAAY;AAAA,MACpC,kBAAkB,QAAQ;AAAA,MAC1B,eAAe,QAAQ;AAAA,MACvB,aAAa,QAAQ;AAAA,IACvB;AAAA,EACF,CAAC;AACH;",
   "names": []
 }

package/dist/modules/billing/lib/topupReceipt.js

@@ -1,94 +1,73 @@
-import {
-  SalesInvoice,
-  SalesInvoiceLine
-} from "@open-mercato/core/modules/sales/data/entities";
-import { resolveInvoiceStatusEntryId } from "./invoiceStatus.js";
-function fmt4(value) {
-  return (Number.isFinite(value) ? value : 0).toFixed(4);
+import { BillingInvoice, BillingInvoiceLine } from "../data/entities.js";
+import { getBillingSettings, numberMaskFor } from "./billingSettings.js";
+import { claimDocumentNumber } from "./numbering.js";
+import { lineAmountsFromGross, money4 } from "./vat.js";
+function todayUtc() {
+  const now = /* @__PURE__ */ new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
 }
-async function createTopupReceipt(em, deps, params) {
+async function createTopupReceipt(em, params) {
   const { account } = params;
-  const tax = await deps.taxService.calculateUnitAmounts({
-    amount: Number.parseFloat(params.amount),
-    mode: "gross",
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    taxRate: params.taxRate
-  });
-  const net = fmt4(tax.netAmount);
-  const gross = fmt4(tax.grossAmount);
-  const taxAmount = fmt4(tax.taxAmount);
-  const effectiveRate = tax.taxRate ?? 0;
-  const generated = await deps.numberGenerator.generate({
-    kind: "invoice",
-    organizationId: account.organizationId,
-    tenantId: account.tenantId
-  });
-  const paidStatusEntryId = await resolveInvoiceStatusEntryId(
-    em,
-    account.tenantId,
-    account.organizationId,
-    "paid"
-  );
+  const scope = { tenantId: account.tenantId, organizationId: account.organizationId };
+  const taxRate = Number.isFinite(params.taxRate) && params.taxRate > 0 ? params.taxRate : 0;
+  const amounts = lineAmountsFromGross(Number.parseFloat(params.amount), taxRate);
+  const net = money4(amounts.net);
+  const tax = money4(amounts.tax);
+  const gross = money4(amounts.gross);
+  const settings = await getBillingSettings(em, scope);
+  const issueDate = todayUtc();
+  const claimed = await claimDocumentNumber(em, scope, "receipt", numberMaskFor(settings, "receipt"), issueDate);
   const now = /* @__PURE__ */ new Date();
-  const invoice = em.create(SalesInvoice, {
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    invoiceNumber: generated.number,
-    statusEntryId: paidStatusEntryId,
+  const receipt = em.create(BillingInvoice, {
+    ...scope,
+    billAccountId: account.id,
+    documentType: "receipt",
+    number: claimed.number,
+    series: "receipt",
     status: "paid",
-    issueDate: now,
+    testRun: false,
+    issueDate,
+    postedAt: now,
     currencyCode: account.currencyCode,
-    subtotalNetAmount: net,
-    subtotalGrossAmount: gross,
-    discountTotalAmount: "0",
-    taxTotalAmount: taxAmount,
-    grandTotalNetAmount: net,
-    grandTotalGrossAmount: gross,
-    paidTotalAmount: gross,
-    outstandingAmount: "0",
-    metadata: {
-      kind: "prepaid_topup",
-      bill_account_id: account.id,
-      topup_id: params.topupId,
-      payment_id: params.paymentId
-    },
+    subtotalNet: net,
+    taxTotal: tax,
+    totalGross: gross,
+    paidTotal: gross,
+    creditedTotal: "0",
+    outstanding: "0",
+    topupId: params.topupId,
+    metadata: { kind: "prepaid_topup", payment_id: params.paymentId },
     createdAt: now,
     updatedAt: now
   });
-  em.persist(invoice);
-  const line = em.create(SalesInvoiceLine, {
-    invoice,
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    lineNumber: 1,
-    kind: "service",
-    description: "Account top-up",
-    quantity: "1",
-    normalizedQuantity: "1",
-    currencyCode: account.currencyCode,
-    unitPriceNet: net,
-    unitPriceGross: gross,
-    discountAmount: "0",
-    discountPercent: "0",
-    taxRate: fmt4(effectiveRate),
-    taxAmount,
-    totalNetAmount: net,
-    totalGrossAmount: gross,
-    metadata: {
-      kind: "prepaid_topup",
-      topup_id: params.topupId
-    }
-  });
-  em.persist(line);
+  em.persist(receipt);
+  await em.flush();
+  em.persist(
+    em.create(BillingInvoiceLine, {
+      ...scope,
+      invoiceId: receipt.id,
+      lineNumber: 1,
+      billingType: "receipt",
+      description: "Account top-up",
+      quantity: "1.0000",
+      unitPriceNet: net,
+      taxRate: taxRate.toFixed(4),
+      netAmount: net,
+      taxAmount: tax,
+      grossAmount: gross,
+      metadata: { kind: "prepaid_topup", topup_id: params.topupId },
+      createdAt: now,
+      updatedAt: now
+    })
+  );
   await em.flush();
   return {
-    invoiceId: invoice.id,
-    invoiceNumber: generated.number,
+    invoiceId: receipt.id,
+    invoiceNumber: claimed.number,
     netAmount: net,
-    taxAmount,
+    taxAmount: tax,
     grossAmount: gross,
-    taxRate: effectiveRate
+    taxRate
   };
 }
 export {

package/dist/modules/billing/lib/topupReceipt.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/topupReceipt.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport {\n  SalesInvoice,\n  SalesInvoiceLine,\n} from '@open-mercato/core/modules/sales/data/entities'\nimport type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'\nimport type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'\nimport { resolveInvoiceStatusEntryId } from './invoiceStatus'\n\n/**\n * Creates the fiscal VAT receipt for a captured prepaid top-up (SPEC-002 P2).\n *\n * Deliberate divergence from the postpaid draft\u2192post gate: a captured top-up\n * is a completed, already-paid transaction with nothing to review, so the\n * receipt is created **posted + paid** in one shot (the gate exists for\n * outbound bills, not money already received \u2014 mirrors the xd-249 \"deviations\"\n * convention).\n *\n * **VAT at top-up.** The top-up `amount` is the GROSS the customer paid (= the\n * balance credited). The core tax service splits it into net + VAT at the\n * configured rate. Gap-free numbering reuses `salesDocumentNumberGenerator`.\n */\n\nexport type TopupReceiptParams = {\n  account: {\n    id: string\n    organizationId: string\n    tenantId: string\n    currencyCode: string\n  }\n  topupId: string\n  paymentId: string\n  /** Gross amount paid (numeric(18,4) string). */\n  amount: string\n  /** VAT percent (e.g. 23). 0 = no VAT. */\n  taxRate: number\n}\n\nexport type TopupReceiptDeps = {\n  numberGenerator: Pick<SalesDocumentNumberGenerator, 'generate'>\n  taxService: TaxCalculationService\n}\n\nexport type TopupReceipt = {\n  invoiceId: string\n  invoiceNumber: string\n  netAmount: string\n  taxAmount: string\n  grossAmount: string\n  taxRate: number\n}\n\nfunction fmt4(value: number): string {\n  return (Number.isFinite(value) ? value : 0).toFixed(4)\n}\n\nexport async function createTopupReceipt(\n  em: EntityManager,\n  deps: TopupReceiptDeps,\n  params: TopupReceiptParams,\n): Promise<TopupReceipt> {\n  const { account } = params\n\n  // VAT split \u2014 the top-up amount is GROSS (what was paid = balance credited).\n  const tax = await deps.taxService.calculateUnitAmounts({\n    amount: Number.parseFloat(params.amount),\n    mode: 'gross',\n    organizationId: account.organizationId,\n    tenantId: account.tenantId,\n    taxRate: params.taxRate,\n  })\n  const net = fmt4(tax.netAmount)\n  const gross = fmt4(tax.grossAmount)\n  const taxAmount = fmt4(tax.taxAmount)\n  const effectiveRate = tax.taxRate ?? 0\n\n  const generated = await deps.numberGenerator.generate({\n    kind: 'invoice',\n    organizationId: account.organizationId,\n    tenantId: account.tenantId,\n  })\n\n  // Posted+paid in one shot \u2014 resolve the `paid` status entry directly.\n  const paidStatusEntryId = await resolveInvoiceStatusEntryId(\n    em,\n    account.tenantId,\n    account.organizationId,\n    'paid',\n  )\n\n  const now = new Date()\n  const invoice = em.create(SalesInvoice, {\n    organizationId: account.organizationId,\n    tenantId: account.tenantId,\n    invoiceNumber: generated.number,\n    statusEntryId: paidStatusEntryId,\n    status: 'paid',\n    issueDate: now,\n    currencyCode: account.currencyCode,\n    subtotalNetAmount: net,\n    subtotalGrossAmount: gross,\n    discountTotalAmount: '0',\n    taxTotalAmount: taxAmount,\n    grandTotalNetAmount: net,\n    grandTotalGrossAmount: gross,\n    paidTotalAmount: gross,\n    outstandingAmount: '0',\n    metadata: {\n      kind: 'prepaid_topup',\n      bill_account_id: account.id,\n      topup_id: params.topupId,\n      payment_id: params.paymentId,\n    },\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(invoice)\n\n  const line = em.create(SalesInvoiceLine, {\n    invoice,\n    organizationId: account.organizationId,\n    tenantId: account.tenantId,\n    lineNumber: 1,\n    kind: 'service',\n    description: 'Account top-up',\n    quantity: '1',\n    normalizedQuantity: '1',\n    currencyCode: account.currencyCode,\n    unitPriceNet: net,\n    unitPriceGross: gross,\n    discountAmount: '0',\n    discountPercent: '0',\n    taxRate: fmt4(effectiveRate),\n    taxAmount,\n    totalNetAmount: net,\n    totalGrossAmount: gross,\n    metadata: {\n      kind: 'prepaid_topup',\n      topup_id: params.topupId,\n    },\n  })\n  em.persist(line)\n  await em.flush()\n\n  return {\n    invoiceId: invoice.id,\n    invoiceNumber: generated.number,\n    netAmount: net,\n    taxAmount,\n    grossAmount: gross,\n    taxRate: effectiveRate,\n  }\n}\n"],
-  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAGP,SAAS,mCAAmC;AA6C5C,SAAS,KAAK,OAAuB;AACnC,UAAQ,OAAO,SAAS,KAAK,IAAI,QAAQ,GAAG,QAAQ,CAAC;AACvD;AAEA,eAAsB,mBACpB,IACA,MACA,QACuB;AACvB,QAAM,EAAE,QAAQ,IAAI;AAGpB,QAAM,MAAM,MAAM,KAAK,WAAW,qBAAqB;AAAA,IACrD,QAAQ,OAAO,WAAW,OAAO,MAAM;AAAA,IACvC,MAAM;AAAA,IACN,gBAAgB,QAAQ;AAAA,IACxB,UAAU,QAAQ;AAAA,IAClB,SAAS,OAAO;AAAA,EAClB,CAAC;AACD,QAAM,MAAM,KAAK,IAAI,SAAS;AAC9B,QAAM,QAAQ,KAAK,IAAI,WAAW;AAClC,QAAM,YAAY,KAAK,IAAI,SAAS;AACpC,QAAM,gBAAgB,IAAI,WAAW;AAErC,QAAM,YAAY,MAAM,KAAK,gBAAgB,SAAS;AAAA,IACpD,MAAM;AAAA,IACN,gBAAgB,QAAQ;AAAA,IACxB,UAAU,QAAQ;AAAA,EACpB,CAAC;AAGD,QAAM,oBAAoB,MAAM;AAAA,IAC9B;AAAA,IACA,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR;AAAA,EACF;AAEA,QAAM,MAAM,oBAAI,KAAK;AACrB,QAAM,UAAU,GAAG,OAAO,cAAc;AAAA,IACtC,gBAAgB,QAAQ;AAAA,IACxB,UAAU,QAAQ;AAAA,IAClB,eAAe,UAAU;AAAA,IACzB,eAAe;AAAA,IACf,QAAQ;AAAA,IACR,WAAW;AAAA,IACX,cAAc,QAAQ;AAAA,IACtB,mBAAmB;AAAA,IACnB,qBAAqB;AAAA,IACrB,qBAAqB;AAAA,IACrB,gBAAgB;AAAA,IAChB,qBAAqB;AAAA,IACrB,uBAAuB;AAAA,IACvB,iBAAiB;AAAA,IACjB,mBAAmB;AAAA,IACnB,UAAU;AAAA,MACR,MAAM;AAAA,MACN,iBAAiB,QAAQ;AAAA,MACzB,UAAU,OAAO;AAAA,MACjB,YAAY,OAAO;AAAA,IACrB;AAAA,IACA,WAAW;AAAA,IACX,WAAW;AAAA,EACb,CAAC;AACD,KAAG,QAAQ,OAAO;AAElB,QAAM,OAAO,GAAG,OAAO,kBAAkB;AAAA,IACvC;AAAA,IACA,gBAAgB,QAAQ;AAAA,IACxB,UAAU,QAAQ;AAAA,IAClB,YAAY;AAAA,IACZ,MAAM;AAAA,IACN,aAAa;AAAA,IACb,UAAU;AAAA,IACV,oBAAoB;AAAA,IACpB,cAAc,QAAQ;AAAA,IACtB,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,IACjB,SAAS,KAAK,aAAa;AAAA,IAC3B;AAAA,IACA,gBAAgB;AAAA,IAChB,kBAAkB;AAAA,IAClB,UAAU;AAAA,MACR,MAAM;AAAA,MACN,UAAU,OAAO;AAAA,IACnB;AAAA,EACF,CAAC;AACD,KAAG,QAAQ,IAAI;AACf,QAAM,GAAG,MAAM;AAEf,SAAO;AAAA,IACL,WAAW,QAAQ;AAAA,IACnB,eAAe,UAAU;AAAA,IACzB,WAAW;AAAA,IACX;AAAA,IACA,aAAa;AAAA,IACb,SAAS;AAAA,EACX;AACF;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { BillingInvoice, BillingInvoiceLine } from '../data/entities'\nimport { getBillingSettings, numberMaskFor } from './billingSettings'\nimport { claimDocumentNumber } from './numbering'\nimport { lineAmountsFromGross, money4 } from './vat'\n\n/**\n * Creates the fiscal VAT receipt for a captured prepaid top-up (SPEC-002 P2,\n * Spec 0 E-D3).\n *\n * The receipt is a billing-owned document (`billing_invoices` with\n * `document_type = 'receipt'`, `status = 'paid'`), numbered from the\n * `receipt` series (default mask `RC/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}`).\n * Nothing is written to core `sales`.\n *\n * VAT at top-up: the top-up `amount` is the GROSS the customer paid (= the\n * balance credited); `vat.lineAmountsFromGross` splits it into net + tax with\n * `net + tax = gross` exactly.\n *\n * MUST run inside the capture transaction (`captureTopup`) so the receipt\n * number, the balance credit and the top-up transition commit together.\n */\n\nexport type TopupReceiptParams = {\n  account: {\n    id: string\n    organizationId: string\n    tenantId: string\n    currencyCode: string\n  }\n  topupId: string\n  paymentId: string\n  /** Gross amount paid (numeric(18,4) string). */\n  amount: string\n  /** VAT percent (e.g. 23). 0 = no VAT. */\n  taxRate: number\n}\n\nexport type TopupReceipt = {\n  invoiceId: string\n  invoiceNumber: string\n  netAmount: string\n  taxAmount: string\n  grossAmount: string\n  taxRate: number\n}\n\nfunction todayUtc(): Date {\n  const now = new Date()\n  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()))\n}\n\nexport async function createTopupReceipt(em: EntityManager, params: TopupReceiptParams): Promise<TopupReceipt> {\n  const { account } = params\n  const scope = { tenantId: account.tenantId, organizationId: account.organizationId }\n  const taxRate = Number.isFinite(params.taxRate) && params.taxRate > 0 ? params.taxRate : 0\n  const amounts = lineAmountsFromGross(Number.parseFloat(params.amount), taxRate)\n  const net = money4(amounts.net)\n  const tax = money4(amounts.tax)\n  const gross = money4(amounts.gross)\n\n  const settings = await getBillingSettings(em, scope)\n  const issueDate = todayUtc()\n  const claimed = await claimDocumentNumber(em, scope, 'receipt', numberMaskFor(settings, 'receipt'), issueDate)\n\n  const now = new Date()\n  const receipt = em.create(BillingInvoice, {\n    ...scope,\n    billAccountId: account.id,\n    documentType: 'receipt',\n    number: claimed.number,\n    series: 'receipt',\n    status: 'paid',\n    testRun: false,\n    issueDate,\n    postedAt: now,\n    currencyCode: account.currencyCode,\n    subtotalNet: net,\n    taxTotal: tax,\n    totalGross: gross,\n    paidTotal: gross,\n    creditedTotal: '0',\n    outstanding: '0',\n    topupId: params.topupId,\n    metadata: { kind: 'prepaid_topup', payment_id: params.paymentId },\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(receipt)\n  await em.flush() // need the receipt id for the line\n\n  em.persist(\n    em.create(BillingInvoiceLine, {\n      ...scope,\n      invoiceId: receipt.id,\n      lineNumber: 1,\n      billingType: 'receipt',\n      description: 'Account top-up',\n      quantity: '1.0000',\n      unitPriceNet: net,\n      taxRate: taxRate.toFixed(4),\n      netAmount: net,\n      taxAmount: tax,\n      grossAmount: gross,\n      metadata: { kind: 'prepaid_topup', topup_id: params.topupId },\n      createdAt: now,\n      updatedAt: now,\n    }),\n  )\n  await em.flush()\n\n  return {\n    invoiceId: receipt.id,\n    invoiceNumber: claimed.number,\n    netAmount: net,\n    taxAmount: tax,\n    grossAmount: gross,\n    taxRate,\n  }\n}\n"],
+  "mappings": "AACA,SAAS,gBAAgB,0BAA0B;AACnD,SAAS,oBAAoB,qBAAqB;AAClD,SAAS,2BAA2B;AACpC,SAAS,sBAAsB,cAAc;AA2C7C,SAAS,WAAiB;AACxB,QAAM,MAAM,oBAAI,KAAK;AACrB,SAAO,IAAI,KAAK,KAAK,IAAI,IAAI,eAAe,GAAG,IAAI,YAAY,GAAG,IAAI,WAAW,CAAC,CAAC;AACrF;AAEA,eAAsB,mBAAmB,IAAmB,QAAmD;AAC7G,QAAM,EAAE,QAAQ,IAAI;AACpB,QAAM,QAAQ,EAAE,UAAU,QAAQ,UAAU,gBAAgB,QAAQ,eAAe;AACnF,QAAM,UAAU,OAAO,SAAS,OAAO,OAAO,KAAK,OAAO,UAAU,IAAI,OAAO,UAAU;AACzF,QAAM,UAAU,qBAAqB,OAAO,WAAW,OAAO,MAAM,GAAG,OAAO;AAC9E,QAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAM,QAAQ,OAAO,QAAQ,KAAK;AAElC,QAAM,WAAW,MAAM,mBAAmB,IAAI,KAAK;AACnD,QAAM,YAAY,SAAS;AAC3B,QAAM,UAAU,MAAM,oBAAoB,IAAI,OAAO,WAAW,cAAc,UAAU,SAAS,GAAG,SAAS;AAE7G,QAAM,MAAM,oBAAI,KAAK;AACrB,QAAM,UAAU,GAAG,OAAO,gBAAgB;AAAA,IACxC,GAAG;AAAA,IACH,eAAe,QAAQ;AAAA,IACvB,cAAc;AAAA,IACd,QAAQ,QAAQ;AAAA,IAChB,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,SAAS;AAAA,IACT;AAAA,IACA,UAAU;AAAA,IACV,cAAc,QAAQ;AAAA,IACtB,aAAa;AAAA,IACb,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,WAAW;AAAA,IACX,eAAe;AAAA,IACf,aAAa;AAAA,IACb,SAAS,OAAO;AAAA,IAChB,UAAU,EAAE,MAAM,iBAAiB,YAAY,OAAO,UAAU;AAAA,IAChE,WAAW;AAAA,IACX,WAAW;AAAA,EACb,CAAC;AACD,KAAG,QAAQ,OAAO;AAClB,QAAM,GAAG,MAAM;AAEf,KAAG;AAAA,IACD,GAAG,OAAO,oBAAoB;AAAA,MAC5B,GAAG;AAAA,MACH,WAAW,QAAQ;AAAA,MACnB,YAAY;AAAA,MACZ,aAAa;AAAA,MACb,aAAa;AAAA,MACb,UAAU;AAAA,MACV,cAAc;AAAA,MACd,SAAS,QAAQ,QAAQ,CAAC;AAAA,MAC1B,WAAW;AAAA,MACX,WAAW;AAAA,MACX,aAAa;AAAA,MACb,UAAU,EAAE,MAAM,iBAAiB,UAAU,OAAO,QAAQ;AAAA,MAC5D,WAAW;AAAA,MACX,WAAW;AAAA,IACb,CAAC;AAAA,EACH;AACA,QAAM,GAAG,MAAM;AAEf,SAAO;AAAA,IACL,WAAW,QAAQ;AAAA,IACnB,eAAe,QAAQ;AAAA,IACvB,WAAW;AAAA,IACX,WAAW;AAAA,IACX,aAAa;AAAA,IACb;AAAA,EACF;AACF;",
   "names": []
 }

package/dist/modules/billing/lib/usageRater.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/usageRater.ts"],
-  "sourcesContent": ["/**\n * Pure functions to rate usage quantity against a `rate_json` payload.\n *\n * Three tier models per the spec (`volume` / `graduated` / `flat`) plus\n * the \"simple\" flat-rate shape (`{ unit_price }` without a `model`).\n * The validator at `data/validators.ts` ensures the payload structure\n * before it reaches this rater \u2014 this module trusts the shape but\n * defends against numeric edge cases (NaN, negative quantity).\n *\n * Output:\n *   - `amount` \u2014 numeric string, rounded 2dp half-up, formatted to 4\n *     decimals to match the `core/sales` numeric(18,4) column shape.\n *   - `breakdown` \u2014 per-tier rated quantity / amount, persisted into\n *     `SalesInvoiceLine.metadata.usage_tier_breakdown` so operators\n *     can see how the line was built without re-running the math.\n */\n\nimport type { BillingItem } from '../data/entities'\n\nexport type SimpleFlatRate = { unit_price: number }\nexport type VolumeTier = { up_to: number | null; unit_price: number }\nexport type GraduatedTier = { up_to: number | null; unit_price: number }\nexport type FlatTier = { up_to: number | null; flat_amount: number }\n\nexport type VolumeRate = { model: 'volume'; tiers: VolumeTier[] }\nexport type GraduatedRate = { model: 'graduated'; tiers: GraduatedTier[] }\nexport type FlatRate = { model: 'flat'; tiers: FlatTier[] }\nexport type TieredRate = VolumeRate | GraduatedRate | FlatRate\nexport type UsageRate = SimpleFlatRate | TieredRate\n\nexport type TierBreakdownEntry = {\n  tierIndex: number\n  upTo: number | null\n  /** Quantity rated at this tier \u2014 0 for tiers above the consumed range. */\n  rangeQuantity: number\n  /** `unit_price` for volume/graduated; `flat_amount` for flat. */\n  rate: number\n  /** Per-tier amount contribution, rounded 4dp. */\n  amount: string\n}\n\nexport type UsageRateResult = {\n  /** Total rated amount, numeric(18,4) string. */\n  amount: string\n  /** Per-tier or single-rate breakdown for invoice-line metadata. */\n  breakdown: TierBreakdownEntry[]\n}\n\n/**\n * Half-up rounding to 2dp survives the JS floating-point edge case\n * (`1.005 \u2192 1.01`, `100 \u00D7 0.001 + 100 \u00D7 0.001 + \u2026 \u2192 exactly N\u00D70.001`).\n * Match `invoiceWriter`'s rounding policy so totals are consistent\n * across line types.\n */\nfunction roundHalfUp2dp(value: number): number {\n  return Math.round((value + Number.EPSILON) * 100) / 100\n}\n\nfunction format4dp(value: number): string {\n  return roundHalfUp2dp(value).toFixed(4)\n}\n\n/**\n * Format a unit price to 4dp WITHOUT 2dp rounding \u2014 sub-cent rates\n * like `0.001` (per-API-request pricing) are legitimate. The spec's\n * 2dp half-up rule applies only to line *amounts*, not per-unit\n * rates.\n */\nfunction formatUnitPrice(value: number): string {\n  if (!Number.isFinite(value)) return '0.0000'\n  return value.toFixed(4)\n}\n\nfunction isTieredRate(rate: UsageRate): rate is TieredRate {\n  return typeof (rate as { model?: unknown }).model === 'string'\n}\n\nfunction safeQuantity(quantity: number): number {\n  if (!Number.isFinite(quantity) || quantity < 0) return 0\n  return quantity\n}\n\n// \u2500\u2500\u2500 Simple flat-rate \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction rateSimpleFlat(quantity: number, rate: SimpleFlatRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const total = q * rate.unit_price\n  return {\n    amount: format4dp(total),\n    breakdown: [\n      {\n        tierIndex: 0,\n        upTo: null,\n        rangeQuantity: q,\n        rate: rate.unit_price,\n        amount: format4dp(total),\n      },\n    ],\n  }\n}\n\n// \u2500\u2500\u2500 Volume tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"Entire quantity priced at the unit_price of the tier its total falls\n// into.\" So we walk tiers in order, find the first tier whose `up_to`\n// is `null` (open-ended) or `>= quantity`, and charge `quantity \u00D7\n// that tier's unit_price`. The unconsumed tiers report 0.\n\nfunction rateVolume(quantity: number, rate: VolumeRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const breakdown: TierBreakdownEntry[] = rate.tiers.map((tier, idx) => ({\n    tierIndex: idx,\n    upTo: tier.up_to,\n    rangeQuantity: 0,\n    rate: tier.unit_price,\n    amount: format4dp(0),\n  }))\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    if (tier.up_to === null || q <= tier.up_to) {\n      const total = q * tier.unit_price\n      breakdown[i] = {\n        tierIndex: i,\n        upTo: tier.up_to,\n        rangeQuantity: q,\n        rate: tier.unit_price,\n        amount: format4dp(total),\n      }\n      return { amount: format4dp(total), breakdown }\n    }\n  }\n  // Should be unreachable: validator enforces an open-ended top tier.\n  return { amount: format4dp(0), breakdown }\n}\n\n// \u2500\u2500\u2500 Graduated tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"Each unit priced at its tier.\" Walk tiers in order, charging\n// `min(q_remaining, tier_capacity) \u00D7 unit_price` for each tier the\n// quantity touches.\n\nfunction rateGraduated(quantity: number, rate: GraduatedRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  let remaining = q\n  let previousUpTo = 0\n  let total = 0\n  const breakdown: TierBreakdownEntry[] = []\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    const tierCapacity =\n      tier.up_to === null ? Infinity : Math.max(0, tier.up_to - previousUpTo)\n    const consumed = Math.min(remaining, tierCapacity)\n    const tierAmount = consumed * tier.unit_price\n    total += tierAmount\n    breakdown.push({\n      tierIndex: i,\n      upTo: tier.up_to,\n      rangeQuantity: consumed,\n      rate: tier.unit_price,\n      amount: format4dp(tierAmount),\n    })\n    remaining -= consumed\n    previousUpTo = tier.up_to ?? previousUpTo\n    if (remaining <= 0) {\n      // Pad remaining tiers with zeros for breakdown completeness.\n      for (let j = i + 1; j < rate.tiers.length; j++) {\n        breakdown.push({\n          tierIndex: j,\n          upTo: rate.tiers[j].up_to,\n          rangeQuantity: 0,\n          rate: rate.tiers[j].unit_price,\n          amount: format4dp(0),\n        })\n      }\n      break\n    }\n  }\n  return { amount: format4dp(total), breakdown }\n}\n\n// \u2500\u2500\u2500 Flat tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"One flat fee for the highest tier reached.\" Find the first tier\n// whose `up_to` is `null` or `>= quantity`. Charge that tier's\n// `flat_amount`. Other tiers report 0.\n\nfunction rateFlat(quantity: number, rate: FlatRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const breakdown: TierBreakdownEntry[] = rate.tiers.map((tier, idx) => ({\n    tierIndex: idx,\n    upTo: tier.up_to,\n    rangeQuantity: 0,\n    rate: tier.flat_amount,\n    amount: format4dp(0),\n  }))\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    if (tier.up_to === null || q <= tier.up_to) {\n      breakdown[i] = {\n        tierIndex: i,\n        upTo: tier.up_to,\n        rangeQuantity: q,\n        rate: tier.flat_amount,\n        amount: format4dp(tier.flat_amount),\n      }\n      return { amount: format4dp(tier.flat_amount), breakdown }\n    }\n  }\n  return { amount: format4dp(0), breakdown }\n}\n\n// \u2500\u2500\u2500 Public dispatcher \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function rateUsageQuantity(rate: UsageRate, totalQuantity: number): UsageRateResult {\n  if (!isTieredRate(rate)) {\n    return rateSimpleFlat(totalQuantity, rate)\n  }\n  switch (rate.model) {\n    case 'volume':\n      return rateVolume(totalQuantity, rate)\n    case 'graduated':\n      return rateGraduated(totalQuantity, rate)\n    case 'flat':\n      return rateFlat(totalQuantity, rate)\n  }\n}\n\n/**\n * Convenience wrapper: takes a BillingItem's `rate_json` (typed as\n * `unknown` from JSONB) and the total quantity, returns the rated\n * amount + breakdown. Returns `null` when the rate shape is invalid \u2014\n * caller falls back to \"no charge\" + warns instead of crashing the\n * whole account.\n */\nexport function rateUsageForItem(\n  item: Pick<BillingItem, 'rateJson' | 'type'>,\n  totalQuantity: number,\n): UsageRateResult | null {\n  if (item.type !== 'usage') return null\n  const rate = item.rateJson as UsageRate | null | undefined\n  if (!rate || typeof rate !== 'object') return null\n  if (isTieredRate(rate)) {\n    if (!Array.isArray(rate.tiers) || rate.tiers.length === 0) return null\n  } else if (typeof (rate as SimpleFlatRate).unit_price !== 'number') {\n    return null\n  }\n  return rateUsageQuantity(rate, totalQuantity)\n}\n\nexport { roundHalfUp2dp, format4dp, formatUnitPrice }\n"],
+  "sourcesContent": ["/**\n * Pure functions to rate usage quantity against a `rate_json` payload.\n *\n * Three tier models per the spec (`volume` / `graduated` / `flat`) plus\n * the \"simple\" flat-rate shape (`{ unit_price }` without a `model`).\n * The validator at `data/validators.ts` ensures the payload structure\n * before it reaches this rater \u2014 this module trusts the shape but\n * defends against numeric edge cases (NaN, negative quantity).\n *\n * Output:\n *   - `amount` \u2014 numeric string, rounded 2dp half-up, formatted to 4\n *     decimals to match the `core/sales` numeric(18,4) column shape.\n *   - `breakdown` \u2014 per-tier rated quantity / amount, persisted into\n *     `billing_invoice_lines.metadata.usage_tier_breakdown` so operators\n *     can see how the line was built without re-running the math.\n */\n\nimport type { BillingItem } from '../data/entities'\n\nexport type SimpleFlatRate = { unit_price: number }\nexport type VolumeTier = { up_to: number | null; unit_price: number }\nexport type GraduatedTier = { up_to: number | null; unit_price: number }\nexport type FlatTier = { up_to: number | null; flat_amount: number }\n\nexport type VolumeRate = { model: 'volume'; tiers: VolumeTier[] }\nexport type GraduatedRate = { model: 'graduated'; tiers: GraduatedTier[] }\nexport type FlatRate = { model: 'flat'; tiers: FlatTier[] }\nexport type TieredRate = VolumeRate | GraduatedRate | FlatRate\nexport type UsageRate = SimpleFlatRate | TieredRate\n\nexport type TierBreakdownEntry = {\n  tierIndex: number\n  upTo: number | null\n  /** Quantity rated at this tier \u2014 0 for tiers above the consumed range. */\n  rangeQuantity: number\n  /** `unit_price` for volume/graduated; `flat_amount` for flat. */\n  rate: number\n  /** Per-tier amount contribution, rounded 4dp. */\n  amount: string\n}\n\nexport type UsageRateResult = {\n  /** Total rated amount, numeric(18,4) string. */\n  amount: string\n  /** Per-tier or single-rate breakdown for invoice-line metadata. */\n  breakdown: TierBreakdownEntry[]\n}\n\n/**\n * Half-up rounding to 2dp survives the JS floating-point edge case\n * (`1.005 \u2192 1.01`, `100 \u00D7 0.001 + 100 \u00D7 0.001 + \u2026 \u2192 exactly N\u00D70.001`).\n * Match `invoiceWriter`'s rounding policy so totals are consistent\n * across line types.\n */\nfunction roundHalfUp2dp(value: number): number {\n  return Math.round((value + Number.EPSILON) * 100) / 100\n}\n\nfunction format4dp(value: number): string {\n  return roundHalfUp2dp(value).toFixed(4)\n}\n\n/**\n * Format a unit price to 4dp WITHOUT 2dp rounding \u2014 sub-cent rates\n * like `0.001` (per-API-request pricing) are legitimate. The spec's\n * 2dp half-up rule applies only to line *amounts*, not per-unit\n * rates.\n */\nfunction formatUnitPrice(value: number): string {\n  if (!Number.isFinite(value)) return '0.0000'\n  return value.toFixed(4)\n}\n\nfunction isTieredRate(rate: UsageRate): rate is TieredRate {\n  return typeof (rate as { model?: unknown }).model === 'string'\n}\n\nfunction safeQuantity(quantity: number): number {\n  if (!Number.isFinite(quantity) || quantity < 0) return 0\n  return quantity\n}\n\n// \u2500\u2500\u2500 Simple flat-rate \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction rateSimpleFlat(quantity: number, rate: SimpleFlatRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const total = q * rate.unit_price\n  return {\n    amount: format4dp(total),\n    breakdown: [\n      {\n        tierIndex: 0,\n        upTo: null,\n        rangeQuantity: q,\n        rate: rate.unit_price,\n        amount: format4dp(total),\n      },\n    ],\n  }\n}\n\n// \u2500\u2500\u2500 Volume tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"Entire quantity priced at the unit_price of the tier its total falls\n// into.\" So we walk tiers in order, find the first tier whose `up_to`\n// is `null` (open-ended) or `>= quantity`, and charge `quantity \u00D7\n// that tier's unit_price`. The unconsumed tiers report 0.\n\nfunction rateVolume(quantity: number, rate: VolumeRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const breakdown: TierBreakdownEntry[] = rate.tiers.map((tier, idx) => ({\n    tierIndex: idx,\n    upTo: tier.up_to,\n    rangeQuantity: 0,\n    rate: tier.unit_price,\n    amount: format4dp(0),\n  }))\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    if (tier.up_to === null || q <= tier.up_to) {\n      const total = q * tier.unit_price\n      breakdown[i] = {\n        tierIndex: i,\n        upTo: tier.up_to,\n        rangeQuantity: q,\n        rate: tier.unit_price,\n        amount: format4dp(total),\n      }\n      return { amount: format4dp(total), breakdown }\n    }\n  }\n  // Should be unreachable: validator enforces an open-ended top tier.\n  return { amount: format4dp(0), breakdown }\n}\n\n// \u2500\u2500\u2500 Graduated tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"Each unit priced at its tier.\" Walk tiers in order, charging\n// `min(q_remaining, tier_capacity) \u00D7 unit_price` for each tier the\n// quantity touches.\n\nfunction rateGraduated(quantity: number, rate: GraduatedRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  let remaining = q\n  let previousUpTo = 0\n  let total = 0\n  const breakdown: TierBreakdownEntry[] = []\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    const tierCapacity =\n      tier.up_to === null ? Infinity : Math.max(0, tier.up_to - previousUpTo)\n    const consumed = Math.min(remaining, tierCapacity)\n    const tierAmount = consumed * tier.unit_price\n    total += tierAmount\n    breakdown.push({\n      tierIndex: i,\n      upTo: tier.up_to,\n      rangeQuantity: consumed,\n      rate: tier.unit_price,\n      amount: format4dp(tierAmount),\n    })\n    remaining -= consumed\n    previousUpTo = tier.up_to ?? previousUpTo\n    if (remaining <= 0) {\n      // Pad remaining tiers with zeros for breakdown completeness.\n      for (let j = i + 1; j < rate.tiers.length; j++) {\n        breakdown.push({\n          tierIndex: j,\n          upTo: rate.tiers[j].up_to,\n          rangeQuantity: 0,\n          rate: rate.tiers[j].unit_price,\n          amount: format4dp(0),\n        })\n      }\n      break\n    }\n  }\n  return { amount: format4dp(total), breakdown }\n}\n\n// \u2500\u2500\u2500 Flat tier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// \"One flat fee for the highest tier reached.\" Find the first tier\n// whose `up_to` is `null` or `>= quantity`. Charge that tier's\n// `flat_amount`. Other tiers report 0.\n\nfunction rateFlat(quantity: number, rate: FlatRate): UsageRateResult {\n  const q = safeQuantity(quantity)\n  const breakdown: TierBreakdownEntry[] = rate.tiers.map((tier, idx) => ({\n    tierIndex: idx,\n    upTo: tier.up_to,\n    rangeQuantity: 0,\n    rate: tier.flat_amount,\n    amount: format4dp(0),\n  }))\n  for (let i = 0; i < rate.tiers.length; i++) {\n    const tier = rate.tiers[i]\n    if (tier.up_to === null || q <= tier.up_to) {\n      breakdown[i] = {\n        tierIndex: i,\n        upTo: tier.up_to,\n        rangeQuantity: q,\n        rate: tier.flat_amount,\n        amount: format4dp(tier.flat_amount),\n      }\n      return { amount: format4dp(tier.flat_amount), breakdown }\n    }\n  }\n  return { amount: format4dp(0), breakdown }\n}\n\n// \u2500\u2500\u2500 Public dispatcher \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function rateUsageQuantity(rate: UsageRate, totalQuantity: number): UsageRateResult {\n  if (!isTieredRate(rate)) {\n    return rateSimpleFlat(totalQuantity, rate)\n  }\n  switch (rate.model) {\n    case 'volume':\n      return rateVolume(totalQuantity, rate)\n    case 'graduated':\n      return rateGraduated(totalQuantity, rate)\n    case 'flat':\n      return rateFlat(totalQuantity, rate)\n  }\n}\n\n/**\n * Convenience wrapper: takes a BillingItem's `rate_json` (typed as\n * `unknown` from JSONB) and the total quantity, returns the rated\n * amount + breakdown. Returns `null` when the rate shape is invalid \u2014\n * caller falls back to \"no charge\" + warns instead of crashing the\n * whole account.\n */\nexport function rateUsageForItem(\n  item: Pick<BillingItem, 'rateJson' | 'type'>,\n  totalQuantity: number,\n): UsageRateResult | null {\n  if (item.type !== 'usage') return null\n  const rate = item.rateJson as UsageRate | null | undefined\n  if (!rate || typeof rate !== 'object') return null\n  if (isTieredRate(rate)) {\n    if (!Array.isArray(rate.tiers) || rate.tiers.length === 0) return null\n  } else if (typeof (rate as SimpleFlatRate).unit_price !== 'number') {\n    return null\n  }\n  return rateUsageQuantity(rate, totalQuantity)\n}\n\nexport { roundHalfUp2dp, format4dp, formatUnitPrice }\n"],
   "mappings": "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",
   "names": []
 }

package/dist/modules/billing/lib/usageRunner.js

@@ -1,4 +1,6 @@
+import { itemTaxRate } from "./invoiceWriter.js";
 import { format4dp, formatUnitPrice, rateUsageForItem } from "./usageRater.js";
+import { priceBasisOf } from "./lineAmounts.js";
 const EMPTY_RESULT = {
   lines: [],
   matchedUoms: [],
@@ -15,7 +17,9 @@ function nonNullUomItems(items) {
   }
   return out;
 }
-async function fetchUsageAggregate(em, account, period) {
+async function fetchUsageAggregate(em, account, period, after) {
+  const params = [account.tenantId, account.organizationId, account.id, period.periodEnd];
+  if (after) params.push(after);
   const rows = await em.execute(
     `SELECT uom_code,
             SUM(quantity)::text AS total_quantity,
@@ -27,13 +31,14 @@ async function fetchUsageAggregate(em, account, period) {
        AND deleted_at IS NULL
        AND rated_in_bill_run_id IS NULL
        AND period_end <= ?
+       ${after ? "AND period_end > ?" : ""}
      GROUP BY uom_code`,
-    [account.tenantId, account.organizationId, account.id, period.periodEnd]
+    params
   );
   return rows ?? [];
 }
-async function processUsageForAccount(em, account, period, usageItems) {
-  const aggregateRows = await fetchUsageAggregate(em, account, period);
+async function processUsageForAccount(em, account, period, usageItems, options = {}) {
+  const aggregateRows = await fetchUsageAggregate(em, account, period, options.after ?? null);
   if (aggregateRows.length === 0) return EMPTY_RESULT;
   const itemByUom = nonNullUomItems(usageItems);
   const lines = [];
@@ -61,9 +66,12 @@ async function processUsageForAccount(em, account, period, usageItems) {
       billingItemId: item.id,
       billingType: "usage",
       description: item.description,
-      unitPriceNet,
+      unitPrice: unitPriceNet,
       quantity: format4dp(totalQuantity),
-      totalNetAmount: rated.amount,
+      lineAmount: rated.amount,
+      // Tiered rates are always net (P-D4); a simple rate keeps the item basis.
+      priceBasis: isSimpleFlat ? priceBasisOf(item.priceBasis) : "net",
+      taxRate: itemTaxRate(item),
       metadataExtra: {
         uom_code: uom,
         usage_record_count: recordCount,