@dainamite/billing 0.17.0 → 0.18.0

package/src/modules/billing/i18n/en.json

@@ -1,9 +1,11 @@
 {
   "billing.accounts.actions.open": "Open",
+  "billing.accounts.columns.credit_limit": "Credit limit",
   "billing.accounts.columns.currency": "Currency",
   "billing.accounts.columns.customer": "Customer",
   "billing.accounts.columns.cycle": "Cycle",
   "billing.accounts.columns.last_bill": "Last bill",
+  "billing.accounts.columns.mode": "Mode",
   "billing.accounts.columns.name": "Name",
   "billing.accounts.columns.next_bill": "Next bill",
   "billing.accounts.columns.status": "Status",
@@ -62,6 +64,8 @@
   "billing.accounts.form.error.next_bill_date_required": "Next bill date is required",
   "billing.accounts.form.invoice_email": "Invoice email",
   "billing.accounts.form.invoice_language": "Invoice language (ISO 639-1)",
+  "billing.accounts.form.mode.locked": "Immutable — frozen at account create time.",
+  "billing.accounts.form.mode.title": "Billing mode & credit",
   "billing.accounts.form.name": "Name",
   "billing.accounts.form.name.placeholder": "Auto-filled from customer — override e.g. \"Acme — production\"",
   "billing.accounts.form.next_bill_date": "Next bill date",
@@ -69,6 +73,7 @@
   "billing.accounts.form.saving": "Saving…",
   "billing.accounts.form.submit_hint": "to save,",
   "billing.accounts.form.tax_id": "Tax ID (NIP / VATIN, optional)",
+  "billing.accounts.form.threshold.hint": "Blank = tenant default",
   "billing.accounts.title": "Billing Accounts",
   "billing.common.active": "Active",
   "billing.common.cancel": "Cancel",
@@ -233,6 +238,37 @@
   "billing.items.type.one_time": "One-time",
   "billing.items.type.recurring": "Recurring",
   "billing.items.type.usage": "Usage",
+  "billing.mode.postpaid": "Postpaid",
+  "billing.mode.prepaid": "Prepaid",
+  "billing.prepaid.credit.near_limit": "Near limit",
+  "billing.prepaid.adjust.action": "Adjust",
+  "billing.prepaid.adjust.amount": "Amount (+credit / −debit)",
+  "billing.prepaid.adjust.confirm": "Apply adjustment",
+  "billing.prepaid.adjust.description": "Reason",
+  "billing.prepaid.adjust.error": "Adjustment failed",
+  "billing.prepaid.adjust.invalid_amount": "Enter a non-zero amount",
+  "billing.prepaid.adjust.invalid_description": "Enter a reason",
+  "billing.prepaid.adjust.submitting": "Applying…",
+  "billing.prepaid.adjust.success": "Balance adjusted",
+  "billing.prepaid.credit.over_limit": "Over limit",
+  "billing.prepaid.credit.within_limit": "Within limit",
+  "billing.prepaid.panel.balance": "Balance",
+  "billing.prepaid.panel.credit": "Credit",
+  "billing.prepaid.panel.last_movement": "Last movement",
+  "billing.prepaid.panel.no_transactions": "No balance movements yet.",
+  "billing.prepaid.panel.threshold": "Low threshold",
+  "billing.prepaid.panel.title": "Prepaid balance",
+  "billing.prepaid.panel.transactions": "Balance transactions",
+  "billing.prepaid.status.exhausted": "Exhausted",
+  "billing.prepaid.status.low": "Low",
+  "billing.prepaid.status.ok": "OK",
+  "billing.prepaid.topup.action": "Top up",
+  "billing.prepaid.topup.amount": "Amount",
+  "billing.prepaid.topup.confirm": "Start checkout",
+  "billing.prepaid.topup.created": "Top-up session created",
+  "billing.prepaid.topup.error": "Top-up failed",
+  "billing.prepaid.topup.invalid": "Enter a positive amount",
+  "billing.prepaid.topup.submitting": "Starting…",
   "billing.runs.actions.open": "Open",
   "billing.runs.columns.accounts": "Accounts",
   "billing.runs.columns.as_of_date": "As-of date",
@@ -256,6 +292,10 @@
   "billing.runs.detail.title": "Bill Run",
   "billing.runs.filters.status": "Status",
   "billing.runs.filters.triggered_by": "Trigger",
+  "billing.runs.mode.catch_up": "Catch-up",
+  "billing.runs.mode.dry_run": "Dry-run",
+  "billing.runs.mode.real": "Real",
+  "billing.runs.mode.test": "Test",
   "billing.runs.outcomes.columns.account": "Account",
   "billing.runs.outcomes.columns.error": "Error",
   "billing.runs.outcomes.columns.invoice": "Invoice",
@@ -277,10 +317,6 @@
   "billing.runs.summary.title": "Summary",
   "billing.runs.summary.usage": "Usage rated",
   "billing.runs.summary.warnings": "Warnings",
-  "billing.runs.mode.catch_up": "Catch-up",
-  "billing.runs.mode.dry_run": "Dry-run",
-  "billing.runs.mode.real": "Real",
-  "billing.runs.mode.test": "Test",
   "billing.runs.title": "Bill Runs",
   "billing.runs.trigger.action": "New run",
   "billing.runs.trigger.dialog.as_of_date": "As-of date",
@@ -299,6 +335,78 @@
   "billing.runs.trigger.manual": "Manual",
   "billing.runs.trigger.schedule": "Schedule",
   "billing.runs.trigger.success": "Bill Run triggered",
+  "billing.statements.breakdown.amount": "Amount",
+  "billing.statements.breakdown.item": "Item",
+  "billing.statements.breakdown.quantity": "Qty",
+  "billing.statements.breakdown.type": "Type",
+  "billing.statements.columns.adjustments": "Adjustments",
+  "billing.statements.columns.closing": "Closing",
+  "billing.statements.columns.opening": "Opening",
+  "billing.statements.columns.period": "Period",
+  "billing.statements.columns.recurring": "Recurring",
+  "billing.statements.columns.status": "Status",
+  "billing.statements.columns.account": "Account",
+  "billing.statements.columns.topups": "Top-ups",
+  "billing.statements.columns.usage": "Usage",
+  "billing.statements.detail.bill_run": "Bill Run",
+  "billing.statements.detail.breakdown": "Period-close charges",
+  "billing.statements.detail.load_error": "Failed to load statement",
+  "billing.statements.detail.loading": "Loading statement…",
+  "billing.statements.detail.no_charges": "No recurring charges this period.",
+  "billing.statements.detail.not_found": "Statement not found",
+  "billing.statements.detail.title": "Statement",
+  "billing.statements.detail.view_account": "View account",
+  "billing.statements.filters.status": "Status",
+  "billing.statements.status.generated": "Generated",
+  "billing.statements.status.sent": "Sent",
+  "billing.statements.title": "Statements",
+  "billing.topups.columns.account": "Account",
+  "billing.topups.columns.amount": "Amount",
+  "billing.topups.columns.created": "Created",
+  "billing.topups.columns.provider": "Provider",
+  "billing.topups.columns.status": "Status",
+  "billing.topups.detail.balance_txn": "Balance transaction",
+  "billing.topups.detail.gateway_txn": "Gateway transaction",
+  "billing.topups.detail.load_error": "Failed to load top-up",
+  "billing.topups.detail.loading": "Loading top-up…",
+  "billing.topups.detail.not_found": "Top-up not found",
+  "billing.topups.detail.payment_id": "Payment ID",
+  "billing.topups.detail.receipt": "VAT receipt",
+  "billing.topups.detail.title": "Top-up",
+  "billing.topups.detail.updated": "Updated",
+  "billing.topups.detail.view_account": "View account",
+  "billing.topups.filters.status": "Status",
+  "billing.topups.status.cancelled": "Cancelled",
+  "billing.topups.status.captured": "Captured",
+  "billing.topups.status.expired": "Expired",
+  "billing.topups.status.failed": "Failed",
+  "billing.topups.status.pending": "Pending",
+  "billing.topups.title": "Top-ups",
+  "billing.transactions.columns.amount": "Amount",
+  "billing.transactions.columns.balance_after": "Balance",
+  "billing.transactions.columns.description": "Description",
+  "billing.transactions.columns.type": "Type",
+  "billing.transactions.columns.when": "When",
+  "billing.transactions.type.adjustment": "Adjustment",
+  "billing.transactions.type.one_time": "One-time",
+  "billing.transactions.type.recurring": "Recurring",
+  "billing.transactions.type.reversal": "Reversal",
+  "billing.transactions.type.topup": "Top-up",
+  "billing.transactions.type.usage": "Usage",
+  "billing.transactions.columns.account": "Account",
+  "billing.transactions.detail.item": "Billing item",
+  "billing.transactions.detail.load_error": "Failed to load transaction",
+  "billing.transactions.detail.loading": "Loading transaction…",
+  "billing.transactions.detail.not_found": "Transaction not found",
+  "billing.transactions.detail.source_ref": "Source ref",
+  "billing.transactions.detail.statement": "Statement",
+  "billing.transactions.detail.title": "Transaction",
+  "billing.transactions.detail.topup": "Top-up",
+  "billing.transactions.detail.usage": "Usage record",
+  "billing.transactions.detail.user": "User",
+  "billing.transactions.detail.view_account": "View account",
+  "billing.transactions.filters.type": "Type",
+  "billing.transactions.title": "Transactions",
   "billing.usage.columns.description": "Description",
   "billing.usage.columns.period": "Period",
   "billing.usage.columns.quantity": "Quantity",

package/src/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/src/modules/billing/index.ts

@@ -15,7 +15,7 @@ export const metadata: ModuleInfo = {
     'Lightweight recurring-billing engine — 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,
 }
 

package/src/modules/billing/lib/accountStatus.ts

@@ -0,0 +1,155 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingAccount, BillingAccountBalance } from '../data/entities'
+import type { BalanceStatus, BillingMode } from '../data/validators'
+import {
+  computeBalanceStatus,
+  resolveLowBalanceThreshold,
+} from './balanceStatus'
+import {
+  computeCreditSnapshot,
+  detectCreditCrossing,
+  type CreditSnapshot,
+} from './creditStatus'
+import type { DomainEvent } from './balanceEvents'
+import { formatMoney, subMoney, toUnits } from './money'
+import {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault,
+} from './prepaidConfig'
+
+/**
+ * Read-model helpers for an account's prepaid balance + credit status
+ * (SPEC-002). Shared by `GET …/balance`, `GET …/credit-status`, and the
+ * admin Prepaid panel so the math lives in exactly one place.
+ */
+
+export type BalanceSnapshot = {
+  billAccountId: string
+  currencyCode: string
+  balance: string
+  balanceStatus: BalanceStatus
+  /** The resolved threshold (account row → tenant config default). */
+  lowBalanceThreshold: string
+  lastMovementAt: string | null
+}
+
+export async function getBalanceSnapshot(
+  em: EntityManager,
+  account: BillingAccount,
+): Promise<BalanceSnapshot> {
+  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,
+  }
+}
+
+/**
+ * Σ outstanding of POSTED (not-yet-paid) core/sales invoices the engine
+ * emitted for this account — the postpaid `credit_used` (v1; mid-period
+ * accrued usage is not counted, see SPEC-002 Open Question #5). Top-up
+ * receipts are `paid`, so they never count here.
+ */
+export async function getPostpaidOutstanding(
+  em: EntityManager,
+  account: BillingAccount,
+): Promise<string> {
+  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],
+  )) as unknown as Array<{ total: string }>
+  return formatMoney(rows?.[0]?.total ?? 0)
+}
+
+export type CreditSnapshotResult = CreditSnapshot & { currencyCode: string }
+
+export async function getCreditSnapshot(
+  em: EntityManager,
+  account: BillingAccount,
+): Promise<CreditSnapshotResult> {
+  const mode = (account.billingMode as BillingMode) ?? 'postpaid'
+  const nearLimitBuffer = await getNearLimitBufferDefault(em)
+
+  let balance: string | null = null
+  let outstanding: string | null = 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 }
+}
+
+/**
+ * Credit-crossing events for a postpaid account when a draft invoice is posted
+ * (SPEC-002 P6). `billing.credit.over_limit` fires once on the upward crossing
+ * of `credit_used` (Σ posted-unpaid outstanding) past `credit_limit`. The
+ * just-posted invoice's `outstanding` is already included in the current total,
+ * so the prior total is `current − justPostedOutstanding`.
+ */
+export async function buildPostpaidCreditCrossingEvents(
+  em: EntityManager,
+  account: BillingAccount,
+  justPostedOutstanding: string,
+): Promise<DomainEvent[]> {
+  if ((account.billingMode as 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: DomainEvent[] = []
+  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
+}

package/src/modules/billing/lib/balanceEvents.ts

@@ -0,0 +1,74 @@
+import { detectBalanceCrossing } from './balanceStatus'
+import { detectCreditCrossing, prepaidCreditUsed } from './creditStatus'
+
+/**
+ * Shared balance/credit threshold-crossing → domain-event builder (SPEC-002).
+ *
+ * Every balance movement that can change status — real-time usage debit, a
+ * manual adjustment, a period-close recurring charge — runs through this so
+ * the "fire only on the relevant downward/upward crossing" rule lives in
+ * exactly one place. The events are returned (not emitted) so callers fire
+ * them AFTER the DB commit.
+ */
+
+export type DomainEvent = { id: string; payload: Record<string, unknown> }
+
+export type BalanceEventScope = {
+  billAccountId: string
+  tenantId: string
+  organizationId: string
+  currencyCode: string
+}
+
+export function buildBalanceCrossingEvents(params: {
+  scope: BalanceEventScope
+  balanceBefore: string
+  balanceAfter: string
+  threshold: string
+  creditLimit: string
+  nearLimitBuffer: string
+}): DomainEvent[] {
+  const { scope, balanceBefore, balanceAfter, threshold, creditLimit, nearLimitBuffer } = params
+  const events: DomainEvent[] = []
+  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
+}