@dainamite/billing 0.20.0 → 0.22.0

package/src/modules/billing/index.ts

@@ -12,10 +12,14 @@ export const metadata: ModuleInfo = {
   title: 'Billing',
   version: '0.1.0',
   description:
-    'Lightweight recurring-billing engine — collects one-time / recurring / usage items, runs Bill Runs, produces draft invoices in core/sales.',
+    'Lightweight recurring-billing engine — collects one-time / recurring / usage items, runs Bill Runs and issues its own invoices, memos and top-up receipts (no core sales dependency).',
   author: 'Dainamite',
   license: 'MIT',
-  requires: ['auth', 'directory', 'dictionaries', 'configs', 'sales', 'payment_gateways'],
+  // Spec 0: billing owns its documents. `payment_gateways` is optional
+  // (online top-ups only, resolved at runtime); no sales / configs /
+  // dictionaries dependency. Spec B: `attachments` (platform module) stores
+  // frozen invoice PDFs and the document logo.
+  requires: ['auth', 'directory', 'attachments'],
   ejectable: false,
 }
 

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

@@ -0,0 +1,84 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { isoDay, overdueSql } from './overdue'
+
+/**
+ * Account-list financials (Spec E §4 / Spec F, F8, P-D15).
+ *
+ * One aggregate over `billing_invoices` per list page — `GROUP BY
+ * bill_account_id` for the page's account ids, never a per-row fetch:
+ *   - balance_due     Σ outstanding of posted / partially paid receivables
+ *   - overdue_amount  Σ outstanding of the overdue subset
+ * Test-run documents never count. Same overdue rule as the invoice list and
+ * the account summary (`overdueSql`).
+ */
+
+export type AccountFinancials = { balance_due: string; overdue_amount: string }
+
+export type FinancialsScope = { tenantId: string; organizationId: string }
+
+export const ACCOUNT_FINANCIALS_SQL = `SELECT
+    i.bill_account_id,
+    COALESCE(SUM(i.outstanding), 0) AS balance_due,
+    COALESCE(SUM(i.outstanding) FILTER (WHERE ${overdueSql('i')}), 0) AS overdue_amount
+  FROM billing_invoices i
+  WHERE i.tenant_id = ? AND i.organization_id = ? AND i.bill_account_id = ANY(?::uuid[])
+    AND i.deleted_at IS NULL AND i.test_run = false
+    AND i.status IN ('posted', 'partially_paid')
+    AND i.document_type IN ('invoice', 'debit_memo')
+  GROUP BY i.bill_account_id`
+
+export const OVERDUE_ACCOUNT_IDS_SQL = `SELECT DISTINCT i.bill_account_id
+  FROM billing_invoices i
+  WHERE i.tenant_id = ? AND i.organization_id = ANY(?::uuid[])
+    AND i.deleted_at IS NULL AND i.test_run = false
+    AND ${overdueSql('i')}`
+
+const ZERO = '0.0000'
+
+function money(value: string | number | null | undefined): string {
+  const n = typeof value === 'number' ? value : Number.parseFloat(value ?? '0')
+  return (Number.isFinite(n) ? n : 0).toFixed(4)
+}
+
+function uuidArray(ids: readonly string[]): string {
+  return `{${ids.join(',')}}`
+}
+
+export async function fetchAccountFinancials(
+  em: EntityManager,
+  scope: FinancialsScope,
+  accountIds: readonly string[],
+  today: Date = new Date(),
+): Promise<Map<string, AccountFinancials>> {
+  const out = new Map<string, AccountFinancials>()
+  if (accountIds.length === 0) return out
+  const rows = (await em.execute(ACCOUNT_FINANCIALS_SQL, [
+    isoDay(today),
+    scope.tenantId,
+    scope.organizationId,
+    uuidArray(accountIds),
+  ])) as unknown as Array<{ bill_account_id: string; balance_due: string; overdue_amount: string }>
+  for (const row of rows ?? []) {
+    out.set(String(row.bill_account_id), { balance_due: money(row.balance_due), overdue_amount: money(row.overdue_amount) })
+  }
+  return out
+}
+
+/** Ids of accounts with at least one overdue receivable (the `hasOverdue` filter). */
+export async function fetchOverdueAccountIds(
+  em: EntityManager,
+  scope: { tenantId: string; organizationIds: readonly string[] },
+  today: Date = new Date(),
+): Promise<string[]> {
+  if (scope.organizationIds.length === 0) return []
+  const rows = (await em.execute(OVERDUE_ACCOUNT_IDS_SQL, [
+    scope.tenantId,
+    uuidArray(scope.organizationIds),
+    isoDay(today),
+  ])) as unknown as Array<{ bill_account_id: string }>
+  return (rows ?? []).map((row) => String(row.bill_account_id))
+}
+
+export function financialsOrZero(map: Map<string, AccountFinancials>, accountId: string): AccountFinancials {
+  return map.get(accountId) ?? { balance_due: ZERO, overdue_amount: ZERO }
+}

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

@@ -0,0 +1,32 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Per-billing-account transaction-scoped advisory lock (Spec C, P-D3).
+ *
+ * Every change to an account's receivables — CSV import allocations, manual
+ * allocate / un-allocate, credit auto-apply on post, gateway captures and
+ * (Spec D) credit memo posts — runs inside this lock, so two of them can
+ * never spend the same credit or over-allocate the same invoice.
+ *
+ * Unlike `tenantLock` (a non-blocking try-lock for bill runs), this one
+ * BLOCKS: operations on one account simply queue up. The lock is released
+ * when the transaction ends (commit, rollback or process death). Keep the
+ * callback short — it holds a database transaction.
+ */
+
+export type AccountLockScope = { tenantId: string; billAccountId: string }
+
+export function accountLockKey(scope: AccountLockScope): string {
+  return `billing-ar:${scope.tenantId}:${scope.billAccountId}`
+}
+
+export async function withAccountLock<T>(
+  em: EntityManager,
+  scope: AccountLockScope,
+  fn: (tem: EntityManager) => Promise<T>,
+): Promise<T> {
+  return em.transactional(async (tem) => {
+    await (tem as EntityManager).execute('SELECT pg_advisory_xact_lock(hashtextextended(?, 0))', [accountLockKey(scope)])
+    return fn(tem as EntityManager)
+  })
+}

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

@@ -44,7 +44,7 @@ export async function getBalanceSnapshot(
   const balance = row?.balance ?? '0.0000'
   const threshold = resolveLowBalanceThreshold(
     row?.lowBalanceThreshold ?? null,
-    await getLowBalanceThresholdDefault(em),
+    await getLowBalanceThresholdDefault(em, { tenantId: account.tenantId, organizationId: account.organizationId }),
   )
   return {
     billAccountId: account.id,
@@ -57,8 +57,8 @@ export async function getBalanceSnapshot(
 }
 
 /**
- * Σ outstanding of POSTED (not-yet-paid) core/sales invoices the engine
- * emitted for this account — the postpaid `credit_used` (v1; mid-period
+ * Σ outstanding of posted / partially paid billing invoices and debit memos
+ * of this account (Spec 0: billing-owned `billing_invoices`) — 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.
  */
@@ -67,13 +67,15 @@ export async function getPostpaidOutstanding(
   account: BillingAccount,
 ): Promise<string> {
   const rows = (await em.execute(
-    `SELECT COALESCE(SUM(outstanding_amount), 0) AS total
-       FROM sales_invoices
+    `SELECT COALESCE(SUM(outstanding), 0) AS total
+       FROM billing_invoices
       WHERE tenant_id = ?
         AND organization_id = ?
         AND deleted_at IS NULL
-        AND status = 'posted'
-        AND metadata->>'bill_account_id' = ?`,
+        AND test_run = false
+        AND status IN ('posted', 'partially_paid')
+        AND document_type IN ('invoice', 'debit_memo')
+        AND bill_account_id = ?`,
     [account.tenantId, account.organizationId, account.id],
   )) as unknown as Array<{ total: string }>
   return formatMoney(rows?.[0]?.total ?? 0)
@@ -86,7 +88,7 @@ export async function getCreditSnapshot(
   account: BillingAccount,
 ): Promise<CreditSnapshotResult> {
   const mode = (account.billingMode as BillingMode) ?? 'postpaid'
-  const nearLimitBuffer = await getNearLimitBufferDefault(em)
+  const nearLimitBuffer = await getNearLimitBufferDefault(em, { tenantId: account.tenantId, organizationId: account.organizationId })
 
   let balance: string | null = null
   let outstanding: string | null = null
@@ -126,7 +128,7 @@ export async function buildPostpaidCreditCrossingEvents(
   const creditLimit = account.creditLimit ?? '0'
   if (toUnits(creditLimit) <= 0) return []
 
-  const nearLimitBuffer = await getNearLimitBufferDefault(em)
+  const nearLimitBuffer = await getNearLimitBufferDefault(em, { tenantId: account.tenantId, organizationId: account.organizationId })
   const usedAfter = await getPostpaidOutstanding(em, account)
   const usedBefore = subMoney(usedAfter, justPostedOutstanding)
   const crossing = detectCreditCrossing({

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

@@ -0,0 +1,172 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { BillingAccount } from '../data/entities'
+import { isoDay, overdueSql } from './overdue'
+import { getAccountCredit } from './allocation'
+import { computeBalanceStatus, resolveLowBalanceThreshold } from './balanceStatus'
+import { getLowBalanceThresholdDefault } from './prepaidConfig'
+import { toIsoDate } from './dateOnly'
+
+/**
+ * Accounts-receivable summary of one billing account (Spec B; the endpoint
+ * is Spec E's `GET /api/billing/accounts/{id}/summary`, which later adds the
+ * prepaid balance and next bill date to the same response).
+ *
+ * One aggregate query over `billing_invoices` (indexed on
+ * `bill_account_id, status, due_date`), no ORM hydration:
+ *   - open_amount    Σ outstanding of posted / partially paid receivables
+ *   - overdue_amount Σ outstanding of the overdue subset (B-D6)
+ *   - overdue_count  number of overdue documents
+ *   - credit_amount  unapplied credit (Spec C): unallocated payments + open
+ *                    credit memos of the account
+ * Test-run documents never count.
+ */
+
+export type AccountArSummary = {
+  bill_account_id: string
+  currency_code: string
+  open_amount: string
+  overdue_amount: string
+  overdue_count: number
+  credit_amount: string
+}
+
+type SummaryRow = { open_amount: string | null; overdue_amount: string | null; overdue_count: number | string | null }
+
+export const ACCOUNT_SUMMARY_SQL = `SELECT
+    COALESCE(SUM(i.outstanding), 0) AS open_amount,
+    COALESCE(SUM(i.outstanding) FILTER (WHERE ${overdueSql('i')}), 0) AS overdue_amount,
+    COUNT(*) FILTER (WHERE ${overdueSql('i')})::int AS overdue_count
+  FROM billing_invoices i
+  WHERE i.tenant_id = ? AND i.organization_id = ? AND i.bill_account_id = ?
+    AND i.deleted_at IS NULL AND i.test_run = false
+    AND i.status IN ('posted', 'partially_paid')
+    AND i.document_type IN ('invoice', 'debit_memo')`
+
+function money(value: string | number | null | undefined): string {
+  const n = typeof value === 'number' ? value : Number.parseFloat(value ?? '0')
+  return (Number.isFinite(n) ? n : 0).toFixed(4)
+}
+
+export async function getAccountArSummary(
+  em: EntityManager,
+  account: Pick<BillingAccount, 'id' | 'tenantId' | 'organizationId' | 'currencyCode'>,
+  today: Date = new Date(),
+): Promise<AccountArSummary> {
+  const day = isoDay(today)
+  const rows = (await em.execute(ACCOUNT_SUMMARY_SQL, [
+    day,
+    day,
+    account.tenantId,
+    account.organizationId,
+    account.id,
+  ])) as unknown as SummaryRow[]
+  const row = rows?.[0]
+  return {
+    bill_account_id: account.id,
+    currency_code: account.currencyCode,
+    open_amount: money(row?.open_amount),
+    overdue_amount: money(row?.overdue_amount),
+    overdue_count: Number(row?.overdue_count ?? 0) || 0,
+    credit_amount: await getAccountCredit(
+      em,
+      { tenantId: account.tenantId, organizationId: account.organizationId },
+      { id: account.id, currencyCode: account.currencyCode },
+    ),
+  }
+}
+
+// ─── Spec E / Spec F (F8): the account workspace header ──────────
+
+export type AccountWorkspaceSummary = AccountArSummary & {
+  billing_mode: 'postpaid' | 'prepaid'
+  bill_cycle: string
+  next_bill_date: string | null
+  last_invoice: { id: string; number: string; issue_date: string | null; total_gross: string } | null
+  prepaid: {
+    balance: string
+    balance_status: 'ok' | 'low' | 'exhausted'
+    credit_limit: string
+    last_statement: { id: string; period_start: string; period_end: string; closing_balance: string } | null
+  } | null
+}
+
+type LastInvoiceRow = { id: string; number: string; issue_date: string | Date | null; total_gross: string }
+type BalanceRow = { balance: string | null; low_balance_threshold: string | null }
+type StatementRow = { id: string; period_start: string | Date; period_end: string | Date; closing_balance: string }
+
+export const LAST_INVOICE_SQL = `SELECT id, number, issue_date, total_gross
+  FROM billing_invoices
+  WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ?
+    AND deleted_at IS NULL AND test_run = false
+    AND document_type IN ('invoice', 'debit_memo')
+    AND status NOT IN ('draft')
+  ORDER BY issue_date DESC NULLS LAST, created_at DESC
+  LIMIT 1`
+
+export const BALANCE_SQL = `SELECT balance, low_balance_threshold
+  FROM billing_account_balances
+  WHERE tenant_id = ? AND bill_account_id = ?
+  LIMIT 1`
+
+export const LAST_STATEMENT_SQL = `SELECT id, period_start, period_end, closing_balance
+  FROM billing_statements
+  WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ?
+  ORDER BY period_end DESC
+  LIMIT 1`
+
+/**
+ * Everything the account header shows, in a fixed number of small indexed
+ * queries (no ORM hydration, no per-document fetch): the AR summary, cycle
+ * state, the last posted invoice and — for prepaid accounts — the balance
+ * with its status, the credit limit and the last statement.
+ */
+export async function getAccountWorkspaceSummary(
+  em: EntityManager,
+  account: Pick<
+    BillingAccount,
+    'id' | 'tenantId' | 'organizationId' | 'currencyCode' | 'billingMode' | 'billCycle' | 'nextBillDate' | 'creditLimit'
+  >,
+  today: Date = new Date(),
+): Promise<AccountWorkspaceSummary> {
+  const ar = await getAccountArSummary(em, account, today)
+  const scopeParams = [account.tenantId, account.organizationId, account.id]
+  const lastInvoice = ((await em.execute(LAST_INVOICE_SQL, scopeParams)) as unknown as LastInvoiceRow[])?.[0]
+  let prepaid: AccountWorkspaceSummary['prepaid'] = null
+  if (account.billingMode === 'prepaid') {
+    const balanceRow = ((await em.execute(BALANCE_SQL, [account.tenantId, account.id])) as unknown as BalanceRow[])?.[0]
+    const statement = ((await em.execute(LAST_STATEMENT_SQL, scopeParams)) as unknown as StatementRow[])?.[0]
+    const balance = money(balanceRow?.balance)
+    const threshold = resolveLowBalanceThreshold(
+      balanceRow?.low_balance_threshold ?? null,
+      await getLowBalanceThresholdDefault(em, { tenantId: account.tenantId, organizationId: account.organizationId }),
+    )
+    prepaid = {
+      balance,
+      balance_status: computeBalanceStatus(balance, threshold),
+      credit_limit: money(account.creditLimit),
+      last_statement: statement
+        ? {
+            id: statement.id,
+            period_start: toIsoDate(statement.period_start),
+            period_end: toIsoDate(statement.period_end),
+            closing_balance: money(statement.closing_balance),
+          }
+        : null,
+    }
+  }
+  return {
+    ...ar,
+    billing_mode: account.billingMode === 'prepaid' ? 'prepaid' : 'postpaid',
+    bill_cycle: account.billCycle,
+    next_bill_date: account.nextBillDate ? toIsoDate(account.nextBillDate) : null,
+    last_invoice: lastInvoice
+      ? {
+          id: lastInvoice.id,
+          number: lastInvoice.number,
+          issue_date: lastInvoice.issue_date ? toIsoDate(lastInvoice.issue_date) : null,
+          total_gross: money(lastInvoice.total_gross),
+        }
+      : null,
+    prepaid,
+  }
+}