@dainamite/billing 0.17.0 → 0.19.0

package/dist/modules/billing/i18n/pl.json

@@ -1,9 +1,11 @@
 {
   "billing.accounts.actions.open": "Otwórz",
+  "billing.accounts.columns.credit_limit": "Limit kredytowy",
   "billing.accounts.columns.currency": "Waluta",
   "billing.accounts.columns.customer": "Klient",
   "billing.accounts.columns.cycle": "Cykl",
   "billing.accounts.columns.last_bill": "Ostatnie rozliczenie",
+  "billing.accounts.columns.mode": "Tryb",
   "billing.accounts.columns.name": "Nazwa",
   "billing.accounts.columns.next_bill": "Następne rozliczenie",
   "billing.accounts.columns.status": "Status",
@@ -62,6 +64,8 @@
   "billing.accounts.form.error.next_bill_date_required": "Data następnego rozliczenia jest wymagana",
   "billing.accounts.form.invoice_email": "E-mail do faktur",
   "billing.accounts.form.invoice_language": "Język faktury (ISO 639-1)",
+  "billing.accounts.form.mode.locked": "Niezmienne — ustalane przy tworzeniu konta.",
+  "billing.accounts.form.mode.title": "Tryb rozliczeń i kredyt",
   "billing.accounts.form.name": "Nazwa",
   "billing.accounts.form.name.placeholder": "Uzupełnione z klienta — nadpisz np. „Acme — produkcja”",
   "billing.accounts.form.next_bill_date": "Data następnego rozliczenia",
@@ -69,6 +73,7 @@
   "billing.accounts.form.saving": "Zapisywanie…",
   "billing.accounts.form.submit_hint": "aby zapisać,",
   "billing.accounts.form.tax_id": "NIP / VATIN (opcjonalnie)",
+  "billing.accounts.form.threshold.hint": "Puste = domyślne dla najemcy",
   "billing.accounts.title": "Konta rozliczeniowe",
   "billing.common.active": "Aktywne",
   "billing.common.cancel": "Anuluj",
@@ -233,6 +238,37 @@
   "billing.items.type.one_time": "Jednorazowa",
   "billing.items.type.recurring": "Cykliczna",
   "billing.items.type.usage": "Wg zużycia",
+  "billing.mode.postpaid": "Postpłata",
+  "billing.mode.prepaid": "Przedpłata",
+  "billing.prepaid.credit.near_limit": "Blisko limitu",
+  "billing.prepaid.adjust.action": "Korekta",
+  "billing.prepaid.adjust.amount": "Kwota (+uznanie / −obciążenie)",
+  "billing.prepaid.adjust.confirm": "Zastosuj korektę",
+  "billing.prepaid.adjust.description": "Powód",
+  "billing.prepaid.adjust.error": "Korekta nie powiodła się",
+  "billing.prepaid.adjust.invalid_amount": "Podaj kwotę różną od zera",
+  "billing.prepaid.adjust.invalid_description": "Podaj powód",
+  "billing.prepaid.adjust.submitting": "Stosowanie…",
+  "billing.prepaid.adjust.success": "Saldo skorygowane",
+  "billing.prepaid.credit.over_limit": "Powyżej limitu",
+  "billing.prepaid.credit.within_limit": "W limicie",
+  "billing.prepaid.panel.balance": "Saldo",
+  "billing.prepaid.panel.credit": "Kredyt",
+  "billing.prepaid.panel.last_movement": "Ostatnia zmiana",
+  "billing.prepaid.panel.no_transactions": "Brak zmian salda.",
+  "billing.prepaid.panel.threshold": "Próg niskiego salda",
+  "billing.prepaid.panel.title": "Saldo przedpłacone",
+  "billing.prepaid.panel.transactions": "Transakcje salda",
+  "billing.prepaid.status.exhausted": "Wyczerpane",
+  "billing.prepaid.status.low": "Niskie",
+  "billing.prepaid.status.ok": "OK",
+  "billing.prepaid.topup.action": "Doładuj",
+  "billing.prepaid.topup.amount": "Kwota",
+  "billing.prepaid.topup.confirm": "Rozpocznij płatność",
+  "billing.prepaid.topup.created": "Utworzono sesję doładowania",
+  "billing.prepaid.topup.error": "Doładowanie nie powiodło się",
+  "billing.prepaid.topup.invalid": "Podaj dodatnią kwotę",
+  "billing.prepaid.topup.submitting": "Rozpoczynanie…",
   "billing.runs.actions.open": "Otwórz",
   "billing.runs.columns.accounts": "Konta",
   "billing.runs.columns.as_of_date": "Data rozliczenia",
@@ -256,6 +292,10 @@
   "billing.runs.detail.title": "Przebieg rozliczeniowy",
   "billing.runs.filters.status": "Status",
   "billing.runs.filters.triggered_by": "Wyzwalacz",
+  "billing.runs.mode.catch_up": "Nadrabianie",
+  "billing.runs.mode.dry_run": "Dry-run",
+  "billing.runs.mode.real": "Realny",
+  "billing.runs.mode.test": "Testowy",
   "billing.runs.outcomes.columns.account": "Konto",
   "billing.runs.outcomes.columns.error": "Błąd",
   "billing.runs.outcomes.columns.invoice": "Faktura",
@@ -277,10 +317,6 @@
   "billing.runs.summary.title": "Podsumowanie",
   "billing.runs.summary.usage": "Rozliczone zużycie",
   "billing.runs.summary.warnings": "Ostrzeżenia",
-  "billing.runs.mode.catch_up": "Nadrabianie",
-  "billing.runs.mode.dry_run": "Dry-run",
-  "billing.runs.mode.real": "Realny",
-  "billing.runs.mode.test": "Testowy",
   "billing.runs.title": "Przebiegi rozliczeniowe",
   "billing.runs.trigger.action": "Nowy przebieg",
   "billing.runs.trigger.dialog.as_of_date": "Data odniesienia",
@@ -299,6 +335,78 @@
   "billing.runs.trigger.manual": "Ręcznie",
   "billing.runs.trigger.schedule": "Harmonogram",
   "billing.runs.trigger.success": "Przebieg rozliczeniowy uruchomiony",
+  "billing.statements.breakdown.amount": "Kwota",
+  "billing.statements.breakdown.item": "Pozycja",
+  "billing.statements.breakdown.quantity": "Ilość",
+  "billing.statements.breakdown.type": "Typ",
+  "billing.statements.columns.adjustments": "Korekty",
+  "billing.statements.columns.closing": "Zamknięcie",
+  "billing.statements.columns.opening": "Otwarcie",
+  "billing.statements.columns.period": "Okres",
+  "billing.statements.columns.recurring": "Cykliczne",
+  "billing.statements.columns.status": "Status",
+  "billing.statements.columns.account": "Konto",
+  "billing.statements.columns.topups": "Doładowania",
+  "billing.statements.columns.usage": "Zużycie",
+  "billing.statements.detail.bill_run": "Przebieg rozliczeń",
+  "billing.statements.detail.breakdown": "Opłaty na koniec okresu",
+  "billing.statements.detail.load_error": "Nie udało się wczytać zestawienia",
+  "billing.statements.detail.loading": "Wczytywanie zestawienia…",
+  "billing.statements.detail.no_charges": "Brak opłat cyklicznych w tym okresie.",
+  "billing.statements.detail.not_found": "Nie znaleziono zestawienia",
+  "billing.statements.detail.title": "Zestawienie",
+  "billing.statements.detail.view_account": "Zobacz konto",
+  "billing.statements.filters.status": "Status",
+  "billing.statements.status.generated": "Wygenerowane",
+  "billing.statements.status.sent": "Wysłane",
+  "billing.statements.title": "Zestawienia",
+  "billing.topups.columns.account": "Konto",
+  "billing.topups.columns.amount": "Kwota",
+  "billing.topups.columns.created": "Utworzono",
+  "billing.topups.columns.provider": "Dostawca",
+  "billing.topups.columns.status": "Status",
+  "billing.topups.detail.balance_txn": "Transakcja salda",
+  "billing.topups.detail.gateway_txn": "Transakcja bramki",
+  "billing.topups.detail.load_error": "Nie udało się wczytać doładowania",
+  "billing.topups.detail.loading": "Wczytywanie doładowania…",
+  "billing.topups.detail.not_found": "Nie znaleziono doładowania",
+  "billing.topups.detail.payment_id": "Identyfikator płatności",
+  "billing.topups.detail.receipt": "Faktura VAT",
+  "billing.topups.detail.title": "Doładowanie",
+  "billing.topups.detail.updated": "Zaktualizowano",
+  "billing.topups.detail.view_account": "Zobacz konto",
+  "billing.topups.filters.status": "Status",
+  "billing.topups.status.cancelled": "Anulowane",
+  "billing.topups.status.captured": "Zaksięgowane",
+  "billing.topups.status.expired": "Wygasłe",
+  "billing.topups.status.failed": "Nieudane",
+  "billing.topups.status.pending": "Oczekujące",
+  "billing.topups.title": "Doładowania",
+  "billing.transactions.columns.amount": "Kwota",
+  "billing.transactions.columns.balance_after": "Saldo",
+  "billing.transactions.columns.description": "Opis",
+  "billing.transactions.columns.type": "Typ",
+  "billing.transactions.columns.when": "Kiedy",
+  "billing.transactions.type.adjustment": "Korekta",
+  "billing.transactions.type.one_time": "Jednorazowe",
+  "billing.transactions.type.recurring": "Cykliczne",
+  "billing.transactions.type.reversal": "Storno",
+  "billing.transactions.type.topup": "Doładowanie",
+  "billing.transactions.type.usage": "Zużycie",
+  "billing.transactions.columns.account": "Konto",
+  "billing.transactions.detail.item": "Pozycja rozliczeniowa",
+  "billing.transactions.detail.load_error": "Nie udało się wczytać transakcji",
+  "billing.transactions.detail.loading": "Wczytywanie transakcji…",
+  "billing.transactions.detail.not_found": "Nie znaleziono transakcji",
+  "billing.transactions.detail.source_ref": "Referencja źródłowa",
+  "billing.transactions.detail.statement": "Zestawienie",
+  "billing.transactions.detail.title": "Transakcja",
+  "billing.transactions.detail.topup": "Doładowanie",
+  "billing.transactions.detail.usage": "Rekord zużycia",
+  "billing.transactions.detail.user": "Użytkownik",
+  "billing.transactions.detail.view_account": "Zobacz konto",
+  "billing.transactions.filters.type": "Typ",
+  "billing.transactions.title": "Transakcje",
   "billing.usage.columns.description": "Opis",
   "billing.usage.columns.period": "Okres",
   "billing.usage.columns.quantity": "Ilość",

package/dist/modules/billing/index.js

@@ -6,7 +6,7 @@ const metadata = {
   description: "Lightweight recurring-billing engine \u2014 collects one-time / recurring / usage items, runs Bill Runs, produces draft invoices in core/sales.",
   author: "Dainamite",
   license: "MIT",
-  requires: ["auth", "directory", "dictionaries", "configs", "sales"],
+  requires: ["auth", "directory", "dictionaries", "configs", "sales", "payment_gateways"],
   ejectable: false
 };
 import { features } from "./acl.js";

package/dist/modules/billing/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/modules/billing/index.ts"],
-  "sourcesContent": ["import type { ModuleInfo } from '@open-mercato/shared/modules/registry'\n\n// Side-effect import \u2014 registers every CRUD command in the global\n// command bus at module load time. The makeCrudRoute factory looks up\n// `actions.<verb>.commandId` against this registry at request time, so\n// without this import every billing write returns \"command not found\".\n// Pattern mirrors `@open-mercato/core/src/modules/customers/index.ts`.\nimport './commands'\n\nexport const metadata: ModuleInfo = {\n  name: 'billing',\n  title: 'Billing',\n  version: '0.1.0',\n  description:\n    'Lightweight recurring-billing engine \u2014 collects one-time / recurring / usage items, runs Bill Runs, produces draft invoices in core/sales.',\n  author: 'Dainamite',\n  license: 'MIT',\n  requires: ['auth', 'directory', 'dictionaries', 'configs', 'sales'],\n  ejectable: false,\n}\n\nexport { features } from './acl'\n"],
-  "mappings": "AAOA,OAAO;AAEA,MAAM,WAAuB;AAAA,EAClC,MAAM;AAAA,EACN,OAAO;AAAA,EACP,SAAS;AAAA,EACT,aACE;AAAA,EACF,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,UAAU,CAAC,QAAQ,aAAa,gBAAgB,WAAW,OAAO;AAAA,EAClE,WAAW;AACb;AAEA,SAAS,gBAAgB;",
+  "sourcesContent": ["import type { ModuleInfo } from '@open-mercato/shared/modules/registry'\n\n// Side-effect import \u2014 registers every CRUD command in the global\n// command bus at module load time. The makeCrudRoute factory looks up\n// `actions.<verb>.commandId` against this registry at request time, so\n// without this import every billing write returns \"command not found\".\n// Pattern mirrors `@open-mercato/core/src/modules/customers/index.ts`.\nimport './commands'\n\nexport const metadata: ModuleInfo = {\n  name: 'billing',\n  title: 'Billing',\n  version: '0.1.0',\n  description:\n    'Lightweight recurring-billing engine \u2014 collects one-time / recurring / usage items, runs Bill Runs, produces draft invoices in core/sales.',\n  author: 'Dainamite',\n  license: 'MIT',\n  requires: ['auth', 'directory', 'dictionaries', 'configs', 'sales', 'payment_gateways'],\n  ejectable: false,\n}\n\nexport { features } from './acl'\n"],
+  "mappings": "AAOA,OAAO;AAEA,MAAM,WAAuB;AAAA,EAClC,MAAM;AAAA,EACN,OAAO;AAAA,EACP,SAAS;AAAA,EACT,aACE;AAAA,EACF,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,UAAU,CAAC,QAAQ,aAAa,gBAAgB,WAAW,SAAS,kBAAkB;AAAA,EACtF,WAAW;AACb;AAEA,SAAS,gBAAgB;",
   "names": []
 }

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

@@ -0,0 +1,106 @@
+import { BillingAccountBalance } from "../data/entities.js";
+import {
+  computeBalanceStatus,
+  resolveLowBalanceThreshold
+} from "./balanceStatus.js";
+import {
+  computeCreditSnapshot,
+  detectCreditCrossing
+} from "./creditStatus.js";
+import { formatMoney, subMoney, toUnits } from "./money.js";
+import {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault
+} from "./prepaidConfig.js";
+async function getBalanceSnapshot(em, account) {
+  const row = await em.findOne(BillingAccountBalance, {
+    tenantId: account.tenantId,
+    billAccountId: account.id
+  });
+  const balance = row?.balance ?? "0.0000";
+  const threshold = resolveLowBalanceThreshold(
+    row?.lowBalanceThreshold ?? null,
+    await getLowBalanceThresholdDefault(em)
+  );
+  return {
+    billAccountId: account.id,
+    currencyCode: account.currencyCode,
+    balance: formatMoney(balance),
+    balanceStatus: computeBalanceStatus(balance, threshold),
+    lowBalanceThreshold: formatMoney(threshold),
+    lastMovementAt: row?.lastMovementAt ? row.lastMovementAt.toISOString() : null
+  };
+}
+async function getPostpaidOutstanding(em, account) {
+  const rows = await em.execute(
+    `SELECT COALESCE(SUM(outstanding_amount), 0) AS total
+       FROM sales_invoices
+      WHERE tenant_id = ?
+        AND organization_id = ?
+        AND deleted_at IS NULL
+        AND status = 'posted'
+        AND metadata->>'bill_account_id' = ?`,
+    [account.tenantId, account.organizationId, account.id]
+  );
+  return formatMoney(rows?.[0]?.total ?? 0);
+}
+async function getCreditSnapshot(em, account) {
+  const mode = account.billingMode ?? "postpaid";
+  const nearLimitBuffer = await getNearLimitBufferDefault(em);
+  let balance = null;
+  let outstanding = null;
+  if (mode === "prepaid") {
+    const row = await em.findOne(BillingAccountBalance, {
+      tenantId: account.tenantId,
+      billAccountId: account.id
+    });
+    balance = row?.balance ?? "0.0000";
+  } else {
+    outstanding = await getPostpaidOutstanding(em, account);
+  }
+  const snapshot = computeCreditSnapshot({
+    mode,
+    creditLimit: account.creditLimit ?? "0",
+    nearLimitBuffer,
+    balance,
+    outstanding
+  });
+  return { ...snapshot, currencyCode: account.currencyCode };
+}
+async function buildPostpaidCreditCrossingEvents(em, account, justPostedOutstanding) {
+  if (account.billingMode !== "postpaid") return [];
+  const creditLimit = account.creditLimit ?? "0";
+  if (toUnits(creditLimit) <= 0) return [];
+  const nearLimitBuffer = await getNearLimitBufferDefault(em);
+  const usedAfter = await getPostpaidOutstanding(em, account);
+  const usedBefore = subMoney(usedAfter, justPostedOutstanding);
+  const crossing = detectCreditCrossing({
+    creditLimit,
+    nearLimitBuffer,
+    usedBefore,
+    usedAfter
+  });
+  const events = [];
+  const base = {
+    billAccountId: account.id,
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+    currencyCode: account.currencyCode,
+    creditLimit,
+    creditUsed: usedAfter
+  };
+  if (crossing.overLimitCrossedUp) {
+    events.push({ id: "billing.credit.over_limit", payload: { ...base } });
+  }
+  if (crossing.nearLimitCrossedUp) {
+    events.push({ id: "billing.credit.near_limit", payload: { ...base } });
+  }
+  return events;
+}
+export {
+  buildPostpaidCreditCrossingEvents,
+  getBalanceSnapshot,
+  getCreditSnapshot,
+  getPostpaidOutstanding
+};
+//# sourceMappingURL=accountStatus.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/accountStatus.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { BillingAccount, BillingAccountBalance } from '../data/entities'\nimport type { BalanceStatus, BillingMode } from '../data/validators'\nimport {\n  computeBalanceStatus,\n  resolveLowBalanceThreshold,\n} from './balanceStatus'\nimport {\n  computeCreditSnapshot,\n  detectCreditCrossing,\n  type CreditSnapshot,\n} from './creditStatus'\nimport type { DomainEvent } from './balanceEvents'\nimport { formatMoney, subMoney, toUnits } from './money'\nimport {\n  getLowBalanceThresholdDefault,\n  getNearLimitBufferDefault,\n} from './prepaidConfig'\n\n/**\n * Read-model helpers for an account's prepaid balance + credit status\n * (SPEC-002). Shared by `GET \u2026/balance`, `GET \u2026/credit-status`, and the\n * admin Prepaid panel so the math lives in exactly one place.\n */\n\nexport type BalanceSnapshot = {\n  billAccountId: string\n  currencyCode: string\n  balance: string\n  balanceStatus: BalanceStatus\n  /** The resolved threshold (account row \u2192 tenant config default). */\n  lowBalanceThreshold: string\n  lastMovementAt: string | null\n}\n\nexport async function getBalanceSnapshot(\n  em: EntityManager,\n  account: BillingAccount,\n): Promise<BalanceSnapshot> {\n  const row = await em.findOne(BillingAccountBalance, {\n    tenantId: account.tenantId,\n    billAccountId: account.id,\n  })\n  const balance = row?.balance ?? '0.0000'\n  const threshold = resolveLowBalanceThreshold(\n    row?.lowBalanceThreshold ?? null,\n    await getLowBalanceThresholdDefault(em),\n  )\n  return {\n    billAccountId: account.id,\n    currencyCode: account.currencyCode,\n    balance: formatMoney(balance),\n    balanceStatus: computeBalanceStatus(balance, threshold),\n    lowBalanceThreshold: formatMoney(threshold),\n    lastMovementAt: row?.lastMovementAt ? row.lastMovementAt.toISOString() : null,\n  }\n}\n\n/**\n * \u03A3 outstanding of POSTED (not-yet-paid) core/sales invoices the engine\n * emitted for this account \u2014 the postpaid `credit_used` (v1; mid-period\n * accrued usage is not counted, see SPEC-002 Open Question #5). Top-up\n * receipts are `paid`, so they never count here.\n */\nexport async function getPostpaidOutstanding(\n  em: EntityManager,\n  account: BillingAccount,\n): Promise<string> {\n  const rows = (await em.execute(\n    `SELECT COALESCE(SUM(outstanding_amount), 0) AS total\n       FROM sales_invoices\n      WHERE tenant_id = ?\n        AND organization_id = ?\n        AND deleted_at IS NULL\n        AND status = 'posted'\n        AND metadata->>'bill_account_id' = ?`,\n    [account.tenantId, account.organizationId, account.id],\n  )) as unknown as Array<{ total: string }>\n  return formatMoney(rows?.[0]?.total ?? 0)\n}\n\nexport type CreditSnapshotResult = CreditSnapshot & { currencyCode: string }\n\nexport async function getCreditSnapshot(\n  em: EntityManager,\n  account: BillingAccount,\n): Promise<CreditSnapshotResult> {\n  const mode = (account.billingMode as BillingMode) ?? 'postpaid'\n  const nearLimitBuffer = await getNearLimitBufferDefault(em)\n\n  let balance: string | null = null\n  let outstanding: string | null = null\n  if (mode === 'prepaid') {\n    const row = await em.findOne(BillingAccountBalance, {\n      tenantId: account.tenantId,\n      billAccountId: account.id,\n    })\n    balance = row?.balance ?? '0.0000'\n  } else {\n    outstanding = await getPostpaidOutstanding(em, account)\n  }\n\n  const snapshot = computeCreditSnapshot({\n    mode,\n    creditLimit: account.creditLimit ?? '0',\n    nearLimitBuffer,\n    balance,\n    outstanding,\n  })\n  return { ...snapshot, currencyCode: account.currencyCode }\n}\n\n/**\n * Credit-crossing events for a postpaid account when a draft invoice is posted\n * (SPEC-002 P6). `billing.credit.over_limit` fires once on the upward crossing\n * of `credit_used` (\u03A3 posted-unpaid outstanding) past `credit_limit`. The\n * just-posted invoice's `outstanding` is already included in the current total,\n * so the prior total is `current \u2212 justPostedOutstanding`.\n */\nexport async function buildPostpaidCreditCrossingEvents(\n  em: EntityManager,\n  account: BillingAccount,\n  justPostedOutstanding: string,\n): Promise<DomainEvent[]> {\n  if ((account.billingMode as BillingMode) !== 'postpaid') return []\n  const creditLimit = account.creditLimit ?? '0'\n  if (toUnits(creditLimit) <= 0) return []\n\n  const nearLimitBuffer = await getNearLimitBufferDefault(em)\n  const usedAfter = await getPostpaidOutstanding(em, account)\n  const usedBefore = subMoney(usedAfter, justPostedOutstanding)\n  const crossing = detectCreditCrossing({\n    creditLimit,\n    nearLimitBuffer,\n    usedBefore,\n    usedAfter,\n  })\n\n  const events: DomainEvent[] = []\n  const base = {\n    billAccountId: account.id,\n    tenantId: account.tenantId,\n    organizationId: account.organizationId,\n    currencyCode: account.currencyCode,\n    creditLimit,\n    creditUsed: usedAfter,\n  }\n  if (crossing.overLimitCrossedUp) {\n    events.push({ id: 'billing.credit.over_limit', payload: { ...base } })\n  }\n  if (crossing.nearLimitCrossedUp) {\n    events.push({ id: 'billing.credit.near_limit', payload: { ...base } })\n  }\n  return events\n}\n"],
+  "mappings": "AACA,SAAyB,6BAA6B;AAEtD;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AAEP,SAAS,aAAa,UAAU,eAAe;AAC/C;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAkBP,eAAsB,mBACpB,IACA,SAC0B;AAC1B,QAAM,MAAM,MAAM,GAAG,QAAQ,uBAAuB;AAAA,IAClD,UAAU,QAAQ;AAAA,IAClB,eAAe,QAAQ;AAAA,EACzB,CAAC;AACD,QAAM,UAAU,KAAK,WAAW;AAChC,QAAM,YAAY;AAAA,IAChB,KAAK,uBAAuB;AAAA,IAC5B,MAAM,8BAA8B,EAAE;AAAA,EACxC;AACA,SAAO;AAAA,IACL,eAAe,QAAQ;AAAA,IACvB,cAAc,QAAQ;AAAA,IACtB,SAAS,YAAY,OAAO;AAAA,IAC5B,eAAe,qBAAqB,SAAS,SAAS;AAAA,IACtD,qBAAqB,YAAY,SAAS;AAAA,IAC1C,gBAAgB,KAAK,iBAAiB,IAAI,eAAe,YAAY,IAAI;AAAA,EAC3E;AACF;AAQA,eAAsB,uBACpB,IACA,SACiB;AACjB,QAAM,OAAQ,MAAM,GAAG;AAAA,IACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,CAAC,QAAQ,UAAU,QAAQ,gBAAgB,QAAQ,EAAE;AAAA,EACvD;AACA,SAAO,YAAY,OAAO,CAAC,GAAG,SAAS,CAAC;AAC1C;AAIA,eAAsB,kBACpB,IACA,SAC+B;AAC/B,QAAM,OAAQ,QAAQ,eAA+B;AACrD,QAAM,kBAAkB,MAAM,0BAA0B,EAAE;AAE1D,MAAI,UAAyB;AAC7B,MAAI,cAA6B;AACjC,MAAI,SAAS,WAAW;AACtB,UAAM,MAAM,MAAM,GAAG,QAAQ,uBAAuB;AAAA,MAClD,UAAU,QAAQ;AAAA,MAClB,eAAe,QAAQ;AAAA,IACzB,CAAC;AACD,cAAU,KAAK,WAAW;AAAA,EAC5B,OAAO;AACL,kBAAc,MAAM,uBAAuB,IAAI,OAAO;AAAA,EACxD;AAEA,QAAM,WAAW,sBAAsB;AAAA,IACrC;AAAA,IACA,aAAa,QAAQ,eAAe;AAAA,IACpC;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACD,SAAO,EAAE,GAAG,UAAU,cAAc,QAAQ,aAAa;AAC3D;AASA,eAAsB,kCACpB,IACA,SACA,uBACwB;AACxB,MAAK,QAAQ,gBAAgC,WAAY,QAAO,CAAC;AACjE,QAAM,cAAc,QAAQ,eAAe;AAC3C,MAAI,QAAQ,WAAW,KAAK,EAAG,QAAO,CAAC;AAEvC,QAAM,kBAAkB,MAAM,0BAA0B,EAAE;AAC1D,QAAM,YAAY,MAAM,uBAAuB,IAAI,OAAO;AAC1D,QAAM,aAAa,SAAS,WAAW,qBAAqB;AAC5D,QAAM,WAAW,qBAAqB;AAAA,IACpC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,SAAwB,CAAC;AAC/B,QAAM,OAAO;AAAA,IACX,eAAe,QAAQ;AAAA,IACvB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,cAAc,QAAQ;AAAA,IACtB;AAAA,IACA,YAAY;AAAA,EACd;AACA,MAAI,SAAS,oBAAoB;AAC/B,WAAO,KAAK,EAAE,IAAI,6BAA6B,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC;AAAA,EACvE;AACA,MAAI,SAAS,oBAAoB;AAC/B,WAAO,KAAK,EAAE,IAAI,6BAA6B,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC;AAAA,EACvE;AACA,SAAO;AACT;",
+  "names": []
+}

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

@@ -0,0 +1,48 @@
+import { detectBalanceCrossing } from "./balanceStatus.js";
+import { detectCreditCrossing, prepaidCreditUsed } from "./creditStatus.js";
+function buildBalanceCrossingEvents(params) {
+  const { scope, balanceBefore, balanceAfter, threshold, creditLimit, nearLimitBuffer } = params;
+  const events = [];
+  const base = {
+    billAccountId: scope.billAccountId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    currencyCode: scope.currencyCode,
+    balance: balanceAfter
+  };
+  const balanceCrossing = detectBalanceCrossing(balanceBefore, balanceAfter, threshold);
+  if (balanceCrossing.exhaustedCrossedDown) {
+    events.push({ id: "billing.balance.exhausted", payload: { ...base } });
+  }
+  if (balanceCrossing.lowCrossedDown) {
+    events.push({
+      id: "billing.balance.low",
+      payload: { ...base, lowBalanceThreshold: threshold }
+    });
+  }
+  const usedBefore = prepaidCreditUsed(balanceBefore);
+  const usedAfter = prepaidCreditUsed(balanceAfter);
+  const creditCrossing = detectCreditCrossing({
+    creditLimit,
+    nearLimitBuffer,
+    usedBefore,
+    usedAfter
+  });
+  if (creditCrossing.overLimitCrossedUp) {
+    events.push({
+      id: "billing.credit.over_limit",
+      payload: { ...base, creditLimit, creditUsed: usedAfter }
+    });
+  }
+  if (creditCrossing.nearLimitCrossedUp) {
+    events.push({
+      id: "billing.credit.near_limit",
+      payload: { ...base, creditLimit, creditUsed: usedAfter }
+    });
+  }
+  return events;
+}
+export {
+  buildBalanceCrossingEvents
+};
+//# sourceMappingURL=balanceEvents.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/balanceEvents.ts"],
+  "sourcesContent": ["import { detectBalanceCrossing } from './balanceStatus'\nimport { detectCreditCrossing, prepaidCreditUsed } from './creditStatus'\n\n/**\n * Shared balance/credit threshold-crossing \u2192 domain-event builder (SPEC-002).\n *\n * Every balance movement that can change status \u2014 real-time usage debit, a\n * manual adjustment, a period-close recurring charge \u2014 runs through this so\n * the \"fire only on the relevant downward/upward crossing\" rule lives in\n * exactly one place. The events are returned (not emitted) so callers fire\n * them AFTER the DB commit.\n */\n\nexport type DomainEvent = { id: string; payload: Record<string, unknown> }\n\nexport type BalanceEventScope = {\n  billAccountId: string\n  tenantId: string\n  organizationId: string\n  currencyCode: string\n}\n\nexport function buildBalanceCrossingEvents(params: {\n  scope: BalanceEventScope\n  balanceBefore: string\n  balanceAfter: string\n  threshold: string\n  creditLimit: string\n  nearLimitBuffer: string\n}): DomainEvent[] {\n  const { scope, balanceBefore, balanceAfter, threshold, creditLimit, nearLimitBuffer } = params\n  const events: DomainEvent[] = []\n  const base = {\n    billAccountId: scope.billAccountId,\n    tenantId: scope.tenantId,\n    organizationId: scope.organizationId,\n    currencyCode: scope.currencyCode,\n    balance: balanceAfter,\n  }\n\n  const balanceCrossing = detectBalanceCrossing(balanceBefore, balanceAfter, threshold)\n  if (balanceCrossing.exhaustedCrossedDown) {\n    events.push({ id: 'billing.balance.exhausted', payload: { ...base } })\n  }\n  if (balanceCrossing.lowCrossedDown) {\n    events.push({\n      id: 'billing.balance.low',\n      payload: { ...base, lowBalanceThreshold: threshold },\n    })\n  }\n\n  const usedBefore = prepaidCreditUsed(balanceBefore)\n  const usedAfter = prepaidCreditUsed(balanceAfter)\n  const creditCrossing = detectCreditCrossing({\n    creditLimit,\n    nearLimitBuffer,\n    usedBefore,\n    usedAfter,\n  })\n  if (creditCrossing.overLimitCrossedUp) {\n    events.push({\n      id: 'billing.credit.over_limit',\n      payload: { ...base, creditLimit, creditUsed: usedAfter },\n    })\n  }\n  if (creditCrossing.nearLimitCrossedUp) {\n    events.push({\n      id: 'billing.credit.near_limit',\n      payload: { ...base, creditLimit, creditUsed: usedAfter },\n    })\n  }\n\n  return events\n}\n"],
+  "mappings": "AAAA,SAAS,6BAA6B;AACtC,SAAS,sBAAsB,yBAAyB;AAqBjD,SAAS,2BAA2B,QAOzB;AAChB,QAAM,EAAE,OAAO,eAAe,cAAc,WAAW,aAAa,gBAAgB,IAAI;AACxF,QAAM,SAAwB,CAAC;AAC/B,QAAM,OAAO;AAAA,IACX,eAAe,MAAM;AAAA,IACrB,UAAU,MAAM;AAAA,IAChB,gBAAgB,MAAM;AAAA,IACtB,cAAc,MAAM;AAAA,IACpB,SAAS;AAAA,EACX;AAEA,QAAM,kBAAkB,sBAAsB,eAAe,cAAc,SAAS;AACpF,MAAI,gBAAgB,sBAAsB;AACxC,WAAO,KAAK,EAAE,IAAI,6BAA6B,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC;AAAA,EACvE;AACA,MAAI,gBAAgB,gBAAgB;AAClC,WAAO,KAAK;AAAA,MACV,IAAI;AAAA,MACJ,SAAS,EAAE,GAAG,MAAM,qBAAqB,UAAU;AAAA,IACrD,CAAC;AAAA,EACH;AAEA,QAAM,aAAa,kBAAkB,aAAa;AAClD,QAAM,YAAY,kBAAkB,YAAY;AAChD,QAAM,iBAAiB,qBAAqB;AAAA,IAC1C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACD,MAAI,eAAe,oBAAoB;AACrC,WAAO,KAAK;AAAA,MACV,IAAI;AAAA,MACJ,SAAS,EAAE,GAAG,MAAM,aAAa,YAAY,UAAU;AAAA,IACzD,CAAC;AAAA,EACH;AACA,MAAI,eAAe,oBAAoB;AACrC,WAAO,KAAK;AAAA,MACV,IAAI;AAAA,MACJ,SAAS,EAAE,GAAG,MAAM,aAAa,YAAY,UAAU;AAAA,IACzD,CAAC;AAAA,EACH;AAEA,SAAO;AACT;",
+  "names": []
+}

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

@@ -0,0 +1,136 @@
+import {
+  BillingAccountBalance,
+  BillingAccountTransaction
+} from "../data/entities.js";
+import { fromUnits, subMoney, toUnits } from "./money.js";
+const PREPAID_USAGE_SENTINEL_RUN_ID = "dddddddd-dddd-4ddd-8ddd-dddddddddddd";
+async function ensureBalanceRow(em, init) {
+  const existing = await em.findOne(BillingAccountBalance, {
+    tenantId: init.tenantId,
+    billAccountId: init.billAccountId
+  });
+  if (existing) {
+    if (init.lowBalanceThreshold !== void 0 && init.lowBalanceThreshold !== null && (existing.lowBalanceThreshold === null || existing.lowBalanceThreshold === void 0)) {
+      existing.lowBalanceThreshold = init.lowBalanceThreshold;
+      existing.updatedAt = /* @__PURE__ */ new Date();
+    }
+    return existing;
+  }
+  const now = /* @__PURE__ */ new Date();
+  const row = em.create(BillingAccountBalance, {
+    organizationId: init.organizationId,
+    tenantId: init.tenantId,
+    billAccountId: init.billAccountId,
+    currencyCode: init.currencyCode,
+    balance: "0",
+    lowBalanceThreshold: init.lowBalanceThreshold ?? null,
+    lastMovementAt: null,
+    createdAt: now,
+    updatedAt: now
+  });
+  em.persist(row);
+  await em.flush();
+  return row;
+}
+async function applyBalanceMovement(em, params) {
+  if (params.sourceRef) {
+    const existing = await em.findOne(BillingAccountTransaction, {
+      tenantId: params.tenantId,
+      billAccountId: params.billAccountId,
+      sourceRef: params.sourceRef,
+      deletedAt: null
+    });
+    if (existing) {
+      return {
+        balanceBefore: subMoney(existing.balanceAfter, existing.amount),
+        balanceAfter: existing.balanceAfter,
+        transaction: existing,
+        deduplicated: true
+      };
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  await em.execute(
+    `INSERT INTO billing_account_balances
+       (id, organization_id, tenant_id, bill_account_id, currency_code, balance, created_at, updated_at)
+     VALUES (gen_random_uuid(), ?, ?, ?, ?, 0, ?, ?)
+     ON CONFLICT (tenant_id, bill_account_id) DO NOTHING`,
+    [
+      params.organizationId,
+      params.tenantId,
+      params.billAccountId,
+      params.currencyCode,
+      now,
+      now
+    ]
+  );
+  const rows = await em.execute(
+    `UPDATE billing_account_balances
+        SET balance = balance + ?, last_movement_at = ?, updated_at = ?
+      WHERE tenant_id = ? AND bill_account_id = ?
+      RETURNING balance`,
+    [params.amount, now, now, params.tenantId, params.billAccountId]
+  );
+  if (!rows || rows.length === 0) {
+    throw new Error(
+      `balanceLedger: balance row missing for account ${params.billAccountId} after upsert`
+    );
+  }
+  const balanceAfter = fromUnits(toUnits(rows[0].balance));
+  const balanceBefore = subMoney(balanceAfter, params.amount);
+  const transaction = em.create(BillingAccountTransaction, {
+    organizationId: params.organizationId,
+    tenantId: params.tenantId,
+    billAccountId: params.billAccountId,
+    type: params.type,
+    amount: params.amount,
+    currencyCode: params.currencyCode,
+    balanceAfter,
+    usageId: params.usageId ?? null,
+    billingItemId: params.billingItemId ?? null,
+    topupId: params.topupId ?? null,
+    statementId: params.statementId ?? null,
+    description: params.description,
+    sourceRef: params.sourceRef ?? null,
+    metadata: params.metadata ?? null,
+    userId: params.userId ?? null,
+    createdAt: now
+  });
+  em.persist(transaction);
+  await em.flush();
+  return { balanceBefore, balanceAfter, transaction, deduplicated: false };
+}
+async function reconcileAccountBalance(em, scope) {
+  const balanceRow = await em.findOne(BillingAccountBalance, {
+    tenantId: scope.tenantId,
+    billAccountId: scope.billAccountId
+  });
+  const cachedBalance = balanceRow ? fromUnits(toUnits(balanceRow.balance)) : "0.0000";
+  const sumRows = await em.execute(
+    `SELECT COALESCE(SUM(amount), 0) AS sum_amount
+       FROM billing_account_transactions
+      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND deleted_at IS NULL`,
+    [scope.tenantId, scope.organizationId, scope.billAccountId]
+  );
+  const sumOfAmounts = fromUnits(toUnits(sumRows?.[0]?.sum_amount ?? 0));
+  const latest = await em.findOne(
+    BillingAccountTransaction,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      billAccountId: scope.billAccountId,
+      deletedAt: null
+    },
+    { orderBy: { createdAt: "DESC" } }
+  );
+  const latestBalanceAfter = latest ? fromUnits(toUnits(latest.balanceAfter)) : "0.0000";
+  const reconciled = toUnits(cachedBalance) === toUnits(sumOfAmounts) && (latest === null || toUnits(cachedBalance) === toUnits(latestBalanceAfter));
+  return { cachedBalance, sumOfAmounts, latestBalanceAfter, reconciled };
+}
+export {
+  PREPAID_USAGE_SENTINEL_RUN_ID,
+  applyBalanceMovement,
+  ensureBalanceRow,
+  reconcileAccountBalance
+};
+//# sourceMappingURL=balanceLedger.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/balanceLedger.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport {\n  BillingAccountBalance,\n  BillingAccountTransaction,\n} from '../data/entities'\nimport type { TransactionType } from '../data/validators'\nimport { fromUnits, subMoney, toUnits } from './money'\n\n/**\n * Prepaid balance ledger (SPEC-002).\n *\n * Two append-only primitives back every balance change:\n *   - `BillingAccountBalance` \u2014 the O(1) running-balance cache, one row per\n *     prepaid account; the row the atomic `UPDATE \u2026 RETURNING` locks.\n *   - `BillingAccountTransaction` \u2014 the source of truth; `balance == SUM(amount)`.\n *\n * Concurrency correctness: the single-statement `UPDATE \u2026 RETURNING`\n * serializes via the Postgres row lock on the balance row, so N concurrent\n * uploads apply N debits with no lost update and each gets a distinct\n * `balance_after`. The transaction insert in the SAME DB transaction carries\n * that exact snapshot.\n *\n * **All functions here MUST be called inside an `em.transactional(...)`** so\n * the balance move and the transaction insert commit (or roll back) together.\n */\n\n// Sentinel `rated_in_bill_run_id` stamped on a usage record the moment it is\n// rated in real time, so a postpaid-style Bill Run never re-rates it. It is a\n// fixed, recognizable UUID (not a real run id) \u2014 its presence simply means\n// \"already rated at ingest, paired with a BillingAccountTransaction\".\nexport const PREPAID_USAGE_SENTINEL_RUN_ID = 'dddddddd-dddd-4ddd-8ddd-dddddddddddd'\n\nexport type BalanceRowInit = {\n  organizationId: string\n  tenantId: string\n  billAccountId: string\n  currencyCode: string\n  lowBalanceThreshold?: string | null\n}\n\n/**\n * Find-or-create the 1:1 balance row for an account. Idempotent \u2014 safe to\n * call on every prepaid account create. Uses the ORM (this runs at account\n * create, not on the hot consume path).\n */\nexport async function ensureBalanceRow(\n  em: EntityManager,\n  init: BalanceRowInit,\n): Promise<BillingAccountBalance> {\n  const existing = await em.findOne(BillingAccountBalance, {\n    tenantId: init.tenantId,\n    billAccountId: init.billAccountId,\n  })\n  if (existing) {\n    // Allow create-time threshold to land even if a prior (defensive) row\n    // already exists with no threshold set.\n    if (\n      init.lowBalanceThreshold !== undefined &&\n      init.lowBalanceThreshold !== null &&\n      (existing.lowBalanceThreshold === null || existing.lowBalanceThreshold === undefined)\n    ) {\n      existing.lowBalanceThreshold = init.lowBalanceThreshold\n      existing.updatedAt = new Date()\n    }\n    return existing\n  }\n  const now = new Date()\n  const row = em.create(BillingAccountBalance, {\n    organizationId: init.organizationId,\n    tenantId: init.tenantId,\n    billAccountId: init.billAccountId,\n    currencyCode: init.currencyCode,\n    balance: '0',\n    lowBalanceThreshold: init.lowBalanceThreshold ?? null,\n    lastMovementAt: null,\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(row)\n  await em.flush()\n  return row\n}\n\nexport type ApplyMovementParams = {\n  organizationId: string\n  tenantId: string\n  billAccountId: string\n  currencyCode: string\n  /** Transaction type. */\n  type: TransactionType\n  /** SIGNED amount: > 0 credit, < 0 debit. */\n  amount: string\n  description: string\n  usageId?: string | null\n  billingItemId?: string | null\n  topupId?: string | null\n  statementId?: string | null\n  /** Idempotency key \u2014 when set, a duplicate is a no-op (returns the prior row). */\n  sourceRef?: string | null\n  metadata?: Record<string, unknown> | null\n  userId?: string | null\n}\n\nexport type ApplyMovementResult = {\n  /** Running balance BEFORE this movement (4dp string). */\n  balanceBefore: string\n  /** Running balance AFTER this movement \u2014 authoritative (4dp string). */\n  balanceAfter: string\n  transaction: BillingAccountTransaction\n  /** True when `sourceRef` already existed \u2014 no balance was moved. */\n  deduplicated: boolean\n}\n\n/**\n * Atomically move the balance and append the paired transaction.\n *\n * Idempotent on `sourceRef`: if a transaction with the same\n * `(tenant_id, bill_account_id, source_ref)` already exists, NO balance move\n * happens and the existing row is returned (`deduplicated: true`). The unique\n * constraint is the correctness backstop if a race slips past the pre-check \u2014\n * the duplicate insert fails and rolls back the whole (caller's) transaction,\n * so the balance move is undone too. Never double-moves.\n */\nexport async function applyBalanceMovement(\n  em: EntityManager,\n  params: ApplyMovementParams,\n): Promise<ApplyMovementResult> {\n  if (params.sourceRef) {\n    const existing = await em.findOne(BillingAccountTransaction, {\n      tenantId: params.tenantId,\n      billAccountId: params.billAccountId,\n      sourceRef: params.sourceRef,\n      deletedAt: null,\n    })\n    if (existing) {\n      return {\n        balanceBefore: subMoney(existing.balanceAfter, existing.amount),\n        balanceAfter: existing.balanceAfter,\n        transaction: existing,\n        deduplicated: true,\n      }\n    }\n  }\n\n  const now = new Date()\n  // Self-healing: ensure the balance row exists (race-safe via the unique\n  // constraint), then the atomic single-statement move. `amount` is signed\n  // so one statement covers both credit and debit.\n  await em.execute(\n    `INSERT INTO billing_account_balances\n       (id, organization_id, tenant_id, bill_account_id, currency_code, balance, created_at, updated_at)\n     VALUES (gen_random_uuid(), ?, ?, ?, ?, 0, ?, ?)\n     ON CONFLICT (tenant_id, bill_account_id) DO NOTHING`,\n    [\n      params.organizationId,\n      params.tenantId,\n      params.billAccountId,\n      params.currencyCode,\n      now,\n      now,\n    ],\n  )\n  const rows = (await em.execute(\n    `UPDATE billing_account_balances\n        SET balance = balance + ?, last_movement_at = ?, updated_at = ?\n      WHERE tenant_id = ? AND bill_account_id = ?\n      RETURNING balance`,\n    [params.amount, now, now, params.tenantId, params.billAccountId],\n  )) as unknown as Array<{ balance: string }>\n\n  if (!rows || rows.length === 0) {\n    // Should be unreachable \u2014 the upsert above guarantees a row exists.\n    throw new Error(\n      `balanceLedger: balance row missing for account ${params.billAccountId} after upsert`,\n    )\n  }\n  // Normalize whatever the driver hands back (string or number) to 4dp.\n  const balanceAfter = fromUnits(toUnits(rows[0].balance))\n  const balanceBefore = subMoney(balanceAfter, params.amount)\n\n  const transaction = em.create(BillingAccountTransaction, {\n    organizationId: params.organizationId,\n    tenantId: params.tenantId,\n    billAccountId: params.billAccountId,\n    type: params.type,\n    amount: params.amount,\n    currencyCode: params.currencyCode,\n    balanceAfter,\n    usageId: params.usageId ?? null,\n    billingItemId: params.billingItemId ?? null,\n    topupId: params.topupId ?? null,\n    statementId: params.statementId ?? null,\n    description: params.description,\n    sourceRef: params.sourceRef ?? null,\n    metadata: params.metadata ?? null,\n    userId: params.userId ?? null,\n    createdAt: now,\n  })\n  em.persist(transaction)\n  await em.flush()\n\n  return { balanceBefore, balanceAfter, transaction, deduplicated: false }\n}\n\nexport type ReconcileResult = {\n  /** The denormalized running balance (cache). */\n  cachedBalance: string\n  /** SUM(amount) over all (non-deleted) transactions. */\n  sumOfAmounts: string\n  /** The most recent transaction's balance_after, or '0.0000' if none. */\n  latestBalanceAfter: string\n  /** True when all three agree. */\n  reconciled: boolean\n}\n\n/**\n * Assert the ledger invariant for one account:\n * `cachedBalance == SUM(amount) == latest.balance_after`.\n *\n * The optional reconciliation worker (P5) runs this per account and alerts on\n * drift \u2014 a cheap guard against any future non-atomic write slipping in.\n */\nexport async function reconcileAccountBalance(\n  em: EntityManager,\n  scope: { tenantId: string; organizationId: string; billAccountId: string },\n): Promise<ReconcileResult> {\n  const balanceRow = await em.findOne(BillingAccountBalance, {\n    tenantId: scope.tenantId,\n    billAccountId: scope.billAccountId,\n  })\n  const cachedBalance = balanceRow ? fromUnits(toUnits(balanceRow.balance)) : '0.0000'\n\n  const sumRows = (await em.execute(\n    `SELECT COALESCE(SUM(amount), 0) AS sum_amount\n       FROM billing_account_transactions\n      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND deleted_at IS NULL`,\n    [scope.tenantId, scope.organizationId, scope.billAccountId],\n  )) as unknown as Array<{ sum_amount: string }>\n  const sumOfAmounts = fromUnits(toUnits(sumRows?.[0]?.sum_amount ?? 0))\n\n  const latest = await em.findOne(\n    BillingAccountTransaction,\n    {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId,\n      billAccountId: scope.billAccountId,\n      deletedAt: null,\n    },\n    { orderBy: { createdAt: 'DESC' } },\n  )\n  const latestBalanceAfter = latest ? fromUnits(toUnits(latest.balanceAfter)) : '0.0000'\n\n  const reconciled =\n    toUnits(cachedBalance) === toUnits(sumOfAmounts) &&\n    (latest === null || toUnits(cachedBalance) === toUnits(latestBalanceAfter))\n\n  return { cachedBalance, sumOfAmounts, latestBalanceAfter, reconciled }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -0,0 +1,29 @@
+import { compareMoney, toUnits } from "./money.js";
+function resolveLowBalanceThreshold(accountThreshold, configDefault) {
+  if (accountThreshold !== null && accountThreshold !== void 0) {
+    return accountThreshold;
+  }
+  if (configDefault !== null && configDefault !== void 0) {
+    return String(configDefault);
+  }
+  return "0";
+}
+function computeBalanceStatus(balance, threshold) {
+  if (compareMoney(balance, 0) <= 0) return "exhausted";
+  if (compareMoney(balance, threshold) <= 0) return "low";
+  return "ok";
+}
+function detectBalanceCrossing(balanceBefore, balanceAfter, threshold) {
+  const beforeUnits = toUnits(balanceBefore);
+  const afterUnits = toUnits(balanceAfter);
+  const thresholdUnits = toUnits(threshold);
+  const exhaustedCrossedDown = beforeUnits > 0 && afterUnits <= 0;
+  const lowCrossedDown = thresholdUnits > 0 && beforeUnits > thresholdUnits && afterUnits <= thresholdUnits && afterUnits > 0;
+  return { lowCrossedDown, exhaustedCrossedDown };
+}
+export {
+  computeBalanceStatus,
+  detectBalanceCrossing,
+  resolveLowBalanceThreshold
+};
+//# sourceMappingURL=balanceStatus.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/balanceStatus.ts"],
+  "sourcesContent": ["import type { BalanceStatus } from '../data/validators'\nimport { compareMoney, toUnits } from './money'\n\n/**\n * Prepaid funds status & threshold-crossing detection (SPEC-002).\n *\n * Usage is NEVER rejected \u2014 we only classify and report. Events fire ONLY on\n * a downward crossing (compare `balance_before` vs `balance_after`), so a\n * client sitting at `exhausted` and still pushing usage is not spammed.\n */\n\n/**\n * Resolve the effective low-balance threshold:\n *   account row's own threshold \u2192 tenant config default \u2192 0 (off).\n */\nexport function resolveLowBalanceThreshold(\n  accountThreshold: string | null | undefined,\n  configDefault: string | number | null | undefined,\n): string {\n  if (accountThreshold !== null && accountThreshold !== undefined) {\n    return accountThreshold\n  }\n  if (configDefault !== null && configDefault !== undefined) {\n    return String(configDefault)\n  }\n  return '0'\n}\n\n/**\n * | status     | condition                          |\n * |------------|------------------------------------|\n * | exhausted  | balance <= 0 (incl. negative)      |\n * | low        | 0 < balance <= threshold           |\n * | ok         | balance > threshold                |\n */\nexport function computeBalanceStatus(\n  balance: string | number,\n  threshold: string | number,\n): BalanceStatus {\n  if (compareMoney(balance, 0) <= 0) return 'exhausted'\n  if (compareMoney(balance, threshold) <= 0) return 'low'\n  return 'ok'\n}\n\nexport type BalanceCrossing = {\n  /** Crossed downward from > threshold into the (0, threshold] low band. */\n  lowCrossedDown: boolean\n  /** Crossed downward from > 0 to <= 0. */\n  exhaustedCrossedDown: boolean\n}\n\n/**\n * Detect downward threshold crossings between two balances.\n *\n * A single large debit that jumps straight past the low band into exhausted\n * fires ONLY `exhausted` (the customer is already negative \u2014 \"you're low\" is\n * moot). `low` fires only when the balance lands in the (0, threshold] band.\n * When `threshold <= 0` the low band is empty, so `low` never fires (the\n * config default 0 = \"off\"); `exhausted` still works.\n */\nexport function detectBalanceCrossing(\n  balanceBefore: string | number,\n  balanceAfter: string | number,\n  threshold: string | number,\n): BalanceCrossing {\n  const beforeUnits = toUnits(balanceBefore)\n  const afterUnits = toUnits(balanceAfter)\n  const thresholdUnits = toUnits(threshold)\n\n  const exhaustedCrossedDown = beforeUnits > 0 && afterUnits <= 0\n  const lowCrossedDown =\n    thresholdUnits > 0 &&\n    beforeUnits > thresholdUnits &&\n    afterUnits <= thresholdUnits &&\n    afterUnits > 0\n\n  return { lowCrossedDown, exhaustedCrossedDown }\n}\n"],
+  "mappings": "AACA,SAAS,cAAc,eAAe;AAc/B,SAAS,2BACd,kBACA,eACQ;AACR,MAAI,qBAAqB,QAAQ,qBAAqB,QAAW;AAC/D,WAAO;AAAA,EACT;AACA,MAAI,kBAAkB,QAAQ,kBAAkB,QAAW;AACzD,WAAO,OAAO,aAAa;AAAA,EAC7B;AACA,SAAO;AACT;AASO,SAAS,qBACd,SACA,WACe;AACf,MAAI,aAAa,SAAS,CAAC,KAAK,EAAG,QAAO;AAC1C,MAAI,aAAa,SAAS,SAAS,KAAK,EAAG,QAAO;AAClD,SAAO;AACT;AAkBO,SAAS,sBACd,eACA,cACA,WACiB;AACjB,QAAM,cAAc,QAAQ,aAAa;AACzC,QAAM,aAAa,QAAQ,YAAY;AACvC,QAAM,iBAAiB,QAAQ,SAAS;AAExC,QAAM,uBAAuB,cAAc,KAAK,cAAc;AAC9D,QAAM,iBACJ,iBAAiB,KACjB,cAAc,kBACd,cAAc,kBACd,aAAa;AAEf,SAAO,EAAE,gBAAgB,qBAAqB;AAChD;",
+  "names": []
+}