@dainamite/billing 0.17.0 → 0.18.0

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

@@ -0,0 +1,73 @@
+/**
+ * Exact decimal arithmetic for the prepaid balance ledger (SPEC-002).
+ *
+ * All billing money columns are `numeric(18,4)` — four decimal places. Doing
+ * the running-balance / reconciliation math in JS `number` would accumulate
+ * binary floating-point error (`0.1 + 0.2 !== 0.3`), and the reconciliation
+ * invariant `balance == SUM(amount) == latest.balance_after` would drift.
+ *
+ * So we work in **integer ten-thousandths** ("units"): the smallest
+ * representable step of a `numeric(18,4)` column. `12.3400` ⇄ `123400` units.
+ * Addition/subtraction of integers is exact; we only ever format back to a
+ * 4dp string at the persistence boundary.
+ *
+ * `numeric(18,4)` holds values up to ~10^14, i.e. ~10^18 units — well within
+ * JS `Number.MAX_SAFE_INTEGER` (~9.007×10^15) for any realistic balance
+ * (max safe ~±900,000,000,000 currency units). Magnitudes beyond that would
+ * already overflow the column itself; we guard the parse defensively.
+ */
+
+const SCALE = 10_000
+
+/** Parse a numeric(18,4) string (or number) into integer ten-thousandths. */
+export function toUnits(value: string | number | null | undefined): number {
+  if (value === null || value === undefined) return 0
+  const n = typeof value === 'number' ? value : Number.parseFloat(value)
+  if (!Number.isFinite(n)) return 0
+  // Round to the nearest ten-thousandth — half-up, EPSILON-nudged to survive
+  // representations like 12.33999999998.
+  return Math.round((n + Number.EPSILON * Math.sign(n)) * SCALE)
+}
+
+/** Format integer ten-thousandths back to a numeric(18,4) string. */
+export function fromUnits(units: number): string {
+  const sign = units < 0 ? '-' : ''
+  const abs = Math.abs(Math.trunc(units))
+  const whole = Math.trunc(abs / SCALE)
+  const frac = abs % SCALE
+  return `${sign}${whole}.${frac.toString().padStart(4, '0')}`
+}
+
+/** Add two numeric(18,4) values exactly, returning a 4dp string. */
+export function addMoney(a: string | number, b: string | number): string {
+  return fromUnits(toUnits(a) + toUnits(b))
+}
+
+/** Subtract `b` from `a` exactly, returning a 4dp string. */
+export function subMoney(a: string | number, b: string | number): string {
+  return fromUnits(toUnits(a) - toUnits(b))
+}
+
+/** Negate a numeric(18,4) value, returning a 4dp string. */
+export function negateMoney(a: string | number): string {
+  return fromUnits(-toUnits(a))
+}
+
+/** Absolute value of a numeric(18,4), returning a 4dp string. */
+export function absMoney(a: string | number): string {
+  return fromUnits(Math.abs(toUnits(a)))
+}
+
+/** Compare two numeric(18,4) values. Returns -1 / 0 / 1. */
+export function compareMoney(a: string | number, b: string | number): -1 | 0 | 1 {
+  const ua = toUnits(a)
+  const ub = toUnits(b)
+  if (ua < ub) return -1
+  if (ua > ub) return 1
+  return 0
+}
+
+/** Normalize any numeric(18,4) input to a canonical 4dp string. */
+export function formatMoney(value: string | number): string {
+  return fromUnits(toUnits(value))
+}

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

@@ -0,0 +1,58 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'
+
+/**
+ * Typed readers for the prepaid billing module configs (SPEC-002), seeded by
+ * `setup.ts → seedBillingConfigs`. Stored as raw JSON scalars in
+ * `ModuleConfig.valueJson`. Each reader falls back to the same default the
+ * seed uses, so a missing row (older tenant) behaves identically.
+ */
+
+async function readConfig(em: EntityManager, name: string): Promise<unknown> {
+  const row = await em.findOne(ModuleConfig, { moduleId: 'billing', name })
+  if (!row) return undefined
+  return row.valueJson as unknown
+}
+
+function asNumberString(value: unknown, fallback: string): string {
+  if (value === null || value === undefined) return fallback
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value)
+  if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+    return value.trim()
+  }
+  return fallback
+}
+
+/** `prepaid.low_balance_threshold_default` — numeric string (default '0'). */
+export async function getLowBalanceThresholdDefault(em: EntityManager): Promise<string> {
+  return asNumberString(await readConfig(em, 'prepaid.low_balance_threshold_default'), '0')
+}
+
+/** `credit.near_limit_buffer_default` — numeric string (default '0'). */
+export async function getNearLimitBufferDefault(em: EntityManager): Promise<string> {
+  return asNumberString(await readConfig(em, 'credit.near_limit_buffer_default'), '0')
+}
+
+/** `prepaid.topup_provider` — gateway provider key (default 'stripe'). */
+export async function getTopupProvider(em: EntityManager): Promise<string> {
+  const value = await readConfig(em, 'prepaid.topup_provider')
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : 'stripe'
+}
+
+/** `prepaid.statement_enabled` — master switch (default true). */
+export async function getStatementEnabled(em: EntityManager): Promise<boolean> {
+  const value = await readConfig(em, 'prepaid.statement_enabled')
+  if (value === undefined || value === null) return true
+  if (typeof value === 'boolean') return value
+  // A stored string "false" must read as false (Boolean("false") === true).
+  if (typeof value === 'string') return value.trim().toLowerCase() !== 'false'
+  return Boolean(value)
+}
+
+/** `prepaid.topup_tax_rate` — VAT percent on top-up receipts (default 0). */
+export async function getTopupTaxRate(em: EntityManager): Promise<number> {
+  const value = await readConfig(em, 'prepaid.topup_tax_rate')
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && Number.isFinite(Number(value))) return Number(value)
+  return 0
+}

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

@@ -0,0 +1,299 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  BillingAccount,
+  BillingAccountBalance,
+  BillingAccountTransaction,
+  BillingAccountUsage,
+  BillingItem,
+} from '../data/entities'
+import type { BalanceStatus, CreditStatus } from '../data/validators'
+import {
+  applyBalanceMovement,
+  PREPAID_USAGE_SENTINEL_RUN_ID,
+} from './balanceLedger'
+import {
+  computeBalanceStatus,
+  resolveLowBalanceThreshold,
+} from './balanceStatus'
+import {
+  computeCreditStatus,
+  computeAvailableCredit,
+  prepaidCreditUsed,
+} from './creditStatus'
+import { buildBalanceCrossingEvents, type DomainEvent } from './balanceEvents'
+import { absMoney, negateMoney } from './money'
+import {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault,
+} from './prepaidConfig'
+import { rateUsageForItem, type TierBreakdownEntry } from './usageRater'
+
+/**
+ * Real-time prepaid consume (SPEC-002 P1).
+ *
+ * For a prepaid account, a usage upload is rated in real time, debited from
+ * the balance, and the remaining balance is returned — *"I uploaded usage and
+ * got my remaining balance back."* Usage is NEVER rejected: a missing price or
+ * an exhausted balance still records the usage; we report status and let the
+ * client throttle itself.
+ *
+ * The caller MUST run this inside an `em.transactional(...)` so the usage
+ * insert, the atomic balance debit, and the transaction insert commit (or roll
+ * back) together. Domain events are returned (not emitted) so the caller can
+ * fire them AFTER the DB commit.
+ */
+
+export type PrepaidConsumeInput = {
+  organizationId: string
+  tenantId: string
+  billAccountId: string
+  uomCode: string
+  quantity: number
+  periodStart: Date
+  periodEnd: Date
+  lineDescription?: string | null
+  sourceRef?: string | null
+}
+
+export type PrepaidConsumeResult = {
+  id: string
+  deduplicated: boolean
+  ratedAmount: string
+  currencyCode: string
+  balance: string
+  balanceStatus: BalanceStatus
+  creditStatus: CreditStatus
+  tierBreakdown: TierBreakdownEntry[]
+  warning: string | null
+}
+
+export type PrepaidConsumeOutcome = {
+  result: PrepaidConsumeResult
+  events: DomainEvent[]
+}
+
+function breakdownFromMetadata(meta: Record<string, unknown> | null | undefined): TierBreakdownEntry[] {
+  const b = meta?.usage_tier_breakdown
+  return Array.isArray(b) ? (b as TierBreakdownEntry[]) : []
+}
+
+/**
+ * Resolve the active `type=usage` Billing Item priced for a uom (exact match,
+ * no conversion — same rule as the postpaid runner). Latest active item wins.
+ */
+async function findUsageItem(
+  em: EntityManager,
+  input: PrepaidConsumeInput,
+): Promise<BillingItem | null> {
+  return em.findOne(
+    BillingItem,
+    {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      billAccountId: input.billAccountId,
+      type: 'usage',
+      uomCode: input.uomCode,
+      isActive: true,
+      deletedAt: null,
+    } as never,
+    { orderBy: { createdAt: 'DESC' } },
+  )
+}
+
+export async function consumePrepaidUsage(
+  em: EntityManager,
+  account: BillingAccount,
+  input: PrepaidConsumeInput,
+): Promise<PrepaidConsumeOutcome> {
+  const currencyCode = account.currencyCode
+  const threshold = resolveLowBalanceThreshold(
+    await readAccountThreshold(em, input),
+    await getLowBalanceThresholdDefault(em),
+  )
+  const nearLimitBuffer = await getNearLimitBufferDefault(em)
+  const creditLimit = account.creditLimit ?? '0'
+
+  // ─── Idempotency: a duplicate sourceRef never double-debits ────
+  if (input.sourceRef) {
+    const existing = await em.findOne(BillingAccountUsage, {
+      tenantId: input.tenantId,
+      billAccountId: input.billAccountId,
+      sourceRef: input.sourceRef,
+      deletedAt: null,
+    })
+    if (existing) {
+      const txn = await em.findOne(BillingAccountTransaction, {
+        tenantId: input.tenantId,
+        billAccountId: input.billAccountId,
+        usageId: existing.id,
+        deletedAt: null,
+      })
+      const balance = txn?.balanceAfter ?? (await readCurrentBalance(em, input))
+      const ratedAmount = txn ? absMoney(txn.amount) : '0.0000'
+      const warning = (txn?.metadata?.warning as string | undefined) ?? null
+      return {
+        result: {
+          id: existing.id,
+          deduplicated: true,
+          ratedAmount,
+          currencyCode,
+          balance,
+          balanceStatus: computeBalanceStatus(balance, threshold),
+          creditStatus: computeCreditStatus(
+            computeAvailableCredit(creditLimit, prepaidCreditUsed(balance)),
+            nearLimitBuffer,
+            prepaidCreditUsed(balance),
+          ),
+          tierBreakdown: breakdownFromMetadata(txn?.metadata),
+          warning,
+        },
+        events: [],
+      }
+    }
+  }
+
+  // ─── 3. Persist the usage record (rated at ingest = sentinel) ──
+  const now = new Date()
+  const usage = em.create(BillingAccountUsage, {
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId,
+    uomCode: input.uomCode,
+    quantity: input.quantity.toFixed(4),
+    periodStart: input.periodStart,
+    periodEnd: input.periodEnd,
+    lineDescription: input.lineDescription ?? null,
+    sourceRef: input.sourceRef ?? null,
+    // Stamped immediately so a postpaid-style run never re-rates it.
+    ratedInBillRunId: PREPAID_USAGE_SENTINEL_RUN_ID,
+    isActive: true,
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(usage)
+  await em.flush()
+
+  // ─── 4. Rate against the matching usage item ───────────────────
+  const item = await findUsageItem(em, input)
+  let ratedAmount = '0.0000'
+  let breakdown: TierBreakdownEntry[] = []
+  let warning: string | null = null
+  if (!item) {
+    warning = 'no_matching_item'
+  } else {
+    const rated = rateUsageForItem(item, input.quantity)
+    if (!rated) {
+      warning = 'unratable'
+    } else {
+      ratedAmount = rated.amount
+      breakdown = rated.breakdown
+    }
+  }
+
+  // ─── 5–7. Atomic debit + paired transaction (signed amount) ────
+  const movement = await applyBalanceMovement(em, {
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId,
+    currencyCode,
+    type: 'usage',
+    amount: negateMoney(ratedAmount),
+    description: buildDescription(item, input, warning),
+    usageId: usage.id,
+    billingItemId: item?.id ?? null,
+    sourceRef: input.sourceRef ?? null,
+    metadata: {
+      uom_code: input.uomCode,
+      usage_tier_breakdown: breakdown,
+      ...(warning ? { warning } : {}),
+    },
+  })
+
+  const { balanceBefore, balanceAfter } = movement
+
+  // ─── 8. Status + crossing events ──────────────────────────────
+  const balanceStatus = computeBalanceStatus(balanceAfter, threshold)
+  const scope = {
+    billAccountId: input.billAccountId,
+    tenantId: input.tenantId,
+    organizationId: input.organizationId,
+    currencyCode,
+  }
+  const events: DomainEvent[] = buildBalanceCrossingEvents({
+    scope,
+    balanceBefore,
+    balanceAfter,
+    threshold,
+    creditLimit,
+    nearLimitBuffer,
+  })
+
+  // Optional per-debit signal (excluded from workflow triggers).
+  events.push({
+    id: 'billing.usage.rated',
+    payload: {
+      ...scope,
+      balance: balanceAfter,
+      usageId: usage.id,
+      transactionId: movement.transaction.id,
+      ratedAmount,
+      balanceStatus,
+    },
+  })
+
+  const usedAfter = prepaidCreditUsed(balanceAfter)
+  const creditStatus = computeCreditStatus(
+    computeAvailableCredit(creditLimit, usedAfter),
+    nearLimitBuffer,
+    usedAfter,
+  )
+
+  return {
+    result: {
+      id: usage.id,
+      deduplicated: false,
+      ratedAmount,
+      currencyCode,
+      balance: balanceAfter,
+      balanceStatus,
+      creditStatus,
+      tierBreakdown: breakdown,
+      warning,
+    },
+    events,
+  }
+}
+
+function buildDescription(
+  item: BillingItem | null,
+  input: PrepaidConsumeInput,
+  warning: string | null,
+): string {
+  if (input.lineDescription) return input.lineDescription
+  const qty = input.quantity.toLocaleString('en-US')
+  if (!item) return `Usage — ${qty} ${input.uomCode} (no matching item)`
+  if (warning === 'unratable') return `Usage — ${qty} ${input.uomCode} (unratable)`
+  return `${item.description} — ${qty} ${input.uomCode}`
+}
+
+async function readAccountThreshold(
+  em: EntityManager,
+  input: PrepaidConsumeInput,
+): Promise<string | null> {
+  const row = await em.findOne(BillingAccountBalance, {
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId,
+  })
+  return row?.lowBalanceThreshold ?? null
+}
+
+async function readCurrentBalance(
+  em: EntityManager,
+  input: PrepaidConsumeInput,
+): Promise<string> {
+  const row = await em.findOne(BillingAccountBalance, {
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId,
+  })
+  return row?.balance ?? '0.0000'
+}