@dainamite/billing 0.17.0 → 0.19.0

package/src/modules/billing/commands/invoices.ts

@@ -8,8 +8,9 @@ import {
 } from '@open-mercato/shared/lib/commands/scope'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { SalesInvoice, SalesInvoiceLine } from '@open-mercato/core/modules/sales/data/entities'
-import { DraftInvoiceEdit } from '../data/entities'
-import { emitBillingEvent } from '../events'
+import { BillingAccount, DraftInvoiceEdit } from '../data/entities'
+import { emitBillingEvent, type BillingEventId } from '../events'
+import { buildPostpaidCreditCrossingEvents } from '../lib/accountStatus'
 import {
   billingInvoiceAddLineSchema,
   billingInvoiceEditLineSchema,
@@ -144,6 +145,29 @@ const postInvoiceCommand: CommandHandler<BillingInvoicePostInput, PostResult> =
       })
     }
 
+    // SPEC-002 P6: a newly-posted invoice raises the account's outstanding
+    // exposure — emit billing.credit.over_limit on the upward crossing. Billing
+    // never blocks; the consuming flow decides what to do.
+    const billAccountId = (meta as { bill_account_id?: string }).bill_account_id
+    if (billAccountId) {
+      const account = await em.findOne(BillingAccount, {
+        id: billAccountId,
+        tenantId: parsed.tenantId,
+        organizationId: parsed.organizationId,
+        deletedAt: null,
+      })
+      if (account) {
+        const creditEvents = await buildPostpaidCreditCrossingEvents(
+          em,
+          account,
+          invoice.outstandingAmount,
+        )
+        for (const ev of creditEvents) {
+          await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })
+        }
+      }
+    }
+
     return {
       invoiceId: invoice.id,
       invoiceNumber: invoice.invoiceNumber,

package/src/modules/billing/commands/statements.ts

@@ -0,0 +1,101 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+} from '@open-mercato/shared/lib/commands/scope'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { BillingAccount } from '../data/entities'
+import {
+  billingStatementGenerateSchema,
+  type BillingStatementGenerateInput,
+} from '../data/validators'
+import { runBillRun } from '../lib/billRunEngine'
+import { TenantLockBusyError } from '../lib/tenantLock'
+
+/**
+ * Manual statement generation (SPEC-002 P3).
+ *
+ * Reuses the Bill Run engine scoped to a single prepaid account — so the same
+ * recurring-charge + statement + anti-duplicate machinery runs, with the same
+ * tenant lock. If the account is due (`next_bill_date <= asOfDate`) it produces
+ * one statement (and advances the cycle); otherwise nothing is generated.
+ */
+
+function getEm(ctx: CommandRuntimeContext): EntityManager {
+  return (ctx.container.resolve('em') as EntityManager).fork()
+}
+
+function getContainer(ctx: CommandRuntimeContext): AwilixContainer {
+  return ctx.container as AwilixContainer
+}
+
+export type GenerateStatementResult = {
+  statementId: string | null
+  billRunId: string
+  status: string
+}
+
+const generateStatementCommand: CommandHandler<
+  BillingStatementGenerateInput,
+  GenerateStatementResult
+> = {
+  id: 'billing.statements.generate',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingStatementGenerateSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+
+    const em = getEm(ctx)
+    const account = await em.findOne(BillingAccount, {
+      id: parsed.billAccountId,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      throw new CrudHttpError(404, { error: 'Billing account not found' })
+    }
+    if (account.billingMode !== 'prepaid') {
+      throw new CrudHttpError(409, {
+        error: 'Statements are only generated for prepaid accounts',
+        code: 'billing.account.not_prepaid',
+      })
+    }
+
+    const asOfDate = parsed.asOfDate ?? new Date()
+    try {
+      const { billRun, outcomes } = await runBillRun(em, getContainer(ctx), {
+        tenantId: parsed.tenantId,
+        organizationId: parsed.organizationId,
+        asOfDate,
+        triggeredBy: 'manual',
+        mode: 'real',
+        scopedAccountIds: [account.id],
+      })
+      const outcome = outcomes.find((o) => o.billAccountId === account.id)
+      return {
+        statementId: outcome?.statementId ?? null,
+        billRunId: billRun.id,
+        status: outcome?.status ?? billRun.status,
+      }
+    } catch (err) {
+      if (err instanceof TenantLockBusyError) {
+        throw new CrudHttpError(409, {
+          error: 'Another Bill Run is already in progress for this tenant',
+          code: 'billing.run.lock_busy',
+          tenantId: err.tenantId,
+          lockName: err.lockName,
+        })
+      }
+      throw err
+    }
+  },
+}
+
+registerCommand(generateStatementCommand)
+
+export { generateStatementCommand }

package/src/modules/billing/commands/topups.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+} from '@open-mercato/shared/lib/commands/scope'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import type { PaymentGatewayService } from '@open-mercato/core/modules/payment_gateways/lib/gateway-service'
+import { BillingAccount, BillingTopup } from '../data/entities'
+import { billingEntityIds } from '../data/entityIds'
+import {
+  billingTopupCreateSchema,
+  type BillingTopupCreateInput,
+} from '../data/validators'
+import { formatMoney } from '../lib/money'
+import { getTopupProvider } from '../lib/prepaidConfig'
+
+/**
+ * Top-up initiation (SPEC-002 P2).
+ *
+ * Registers a first-class `BillingTopup` (status=pending), then opens a
+ * payment session via `core/payment_gateways`. The balance is NOT credited
+ * here — that happens on the `payment_gateways.payment.captured` event (see
+ * subscribers/prepaid-topup-captured.ts), so the money trail is always
+ * explainable: a top-up only credits the balance once the gateway confirms
+ * capture.
+ */
+
+const topupIndexer = { entityType: billingEntityIds.topup } as const
+const topupEvents = { module: 'billing', entity: 'topup', persistent: true } as const
+
+function getEm(ctx: CommandRuntimeContext): EntityManager {
+  return (ctx.container.resolve('em') as EntityManager).fork()
+}
+
+function getDataEngine(ctx: CommandRuntimeContext): DataEngine {
+  return ctx.container.resolve('dataEngine') as DataEngine
+}
+
+export type CreateTopupResult = {
+  topupId: string
+  paymentId: string
+  status: string
+  transactionId: string | null
+  redirectUrl: string | null
+  clientSecret: string | null
+}
+
+const createTopupCommand: CommandHandler<BillingTopupCreateInput, CreateTopupResult> = {
+  id: 'billing.topups.create',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingTopupCreateSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+
+    const em = getEm(ctx)
+    const account = await em.findOne(BillingAccount, {
+      id: parsed.billAccountId,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      throw new CrudHttpError(404, { error: 'Billing account not found' })
+    }
+    if (account.billingMode !== 'prepaid') {
+      throw new CrudHttpError(409, {
+        error: 'Top-ups are only available on prepaid accounts',
+        code: 'billing.account.not_prepaid',
+      })
+    }
+
+    // Idempotency on the initiating request: a retried POST with the same
+    // sourceRef returns the prior (still-pending) top-up + its session links
+    // rather than opening a second session.
+    if (parsed.sourceRef) {
+      const existing = await em.findOne(BillingTopup, {
+        tenantId: parsed.tenantId,
+        billAccountId: account.id,
+        sourceRef: parsed.sourceRef,
+        deletedAt: null,
+      })
+      if (existing) {
+        const meta = (existing.metadata as Record<string, unknown> | null) ?? {}
+        return {
+          topupId: existing.id,
+          paymentId: existing.paymentId,
+          status: existing.status,
+          transactionId: existing.gatewayTransactionId ?? null,
+          redirectUrl: (meta.redirect_url as string | null) ?? null,
+          clientSecret: (meta.client_secret as string | null) ?? null,
+        }
+      }
+    }
+
+    const providerKey = parsed.providerKey ?? (await getTopupProvider(em))
+    const paymentId = randomUUID()
+    const now = new Date()
+    const topup = em.create(BillingTopup, {
+      organizationId: parsed.organizationId,
+      tenantId: parsed.tenantId,
+      billAccountId: account.id,
+      status: 'pending',
+      amount: formatMoney(parsed.amount),
+      currencyCode: account.currencyCode,
+      providerKey,
+      paymentId,
+      sourceRef: parsed.sourceRef ?? null,
+      metadata: {
+        success_url: parsed.successUrl ?? null,
+        cancel_url: parsed.cancelUrl ?? null,
+      },
+      createdAt: now,
+      updatedAt: now,
+    })
+    em.persist(topup)
+    await em.flush()
+
+    // Open the gateway session. captureMethod 'automatic' so a successful
+    // checkout fires `payment.captured` directly (our capture subscriber
+    // credits the balance + issues the receipt).
+    const gateway = ctx.container.resolve('paymentGatewayService') as PaymentGatewayService
+    const { transaction, session } = await gateway.createPaymentSession({
+      providerKey,
+      paymentId,
+      amount: parsed.amount,
+      currencyCode: account.currencyCode,
+      captureMethod: 'automatic',
+      successUrl: parsed.successUrl,
+      cancelUrl: parsed.cancelUrl,
+      metadata: {
+        kind: 'prepaid_topup',
+        billAccountId: account.id,
+        topupId: topup.id,
+      },
+      organizationId: parsed.organizationId,
+      tenantId: parsed.tenantId,
+    })
+
+    topup.gatewayTransactionId = transaction.id
+    topup.metadata = {
+      ...(topup.metadata as Record<string, unknown>),
+      redirect_url: session.redirectUrl ?? null,
+      client_secret: session.clientSecret ?? null,
+      session_id: session.sessionId ?? null,
+    }
+    topup.updatedAt = new Date()
+    await em.flush()
+
+    await emitCrudSideEffects({
+      dataEngine: getDataEngine(ctx),
+      action: 'created',
+      entity: topup,
+      identifiers: {
+        id: topup.id,
+        tenantId: topup.tenantId,
+        organizationId: topup.organizationId,
+      },
+      indexer: topupIndexer,
+      events: topupEvents,
+    })
+
+    return {
+      topupId: topup.id,
+      paymentId,
+      status: topup.status,
+      transactionId: transaction.id,
+      redirectUrl: session.redirectUrl ?? null,
+      clientSecret: session.clientSecret ?? null,
+    }
+  },
+}
+
+registerCommand(createTopupCommand)
+
+export { createTopupCommand }

package/src/modules/billing/commands/transactions.ts

@@ -0,0 +1,152 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+} from '@open-mercato/shared/lib/commands/scope'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { BillingAccount, BillingAccountBalance } from '../data/entities'
+import { billingEntityIds } from '../data/entityIds'
+import {
+  billingTransactionAdjustSchema,
+  type BillingTransactionAdjustInput,
+  type BalanceStatus,
+} from '../data/validators'
+import { applyBalanceMovement } from '../lib/balanceLedger'
+import { buildBalanceCrossingEvents } from '../lib/balanceEvents'
+import { computeBalanceStatus, resolveLowBalanceThreshold } from '../lib/balanceStatus'
+import { formatMoney } from '../lib/money'
+import {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault,
+} from '../lib/prepaidConfig'
+import { emitBillingEvent, type BillingEventId } from '../events'
+
+/**
+ * Manual balance adjustment (SPEC-002 P5).
+ *
+ * Operator-driven credit/debit (`type='adjustment'`) audited via `user_id`.
+ * Non-fiscal by default — an adjustment moves already-taxed balance, so no
+ * receipt is issued (Open Question #3; can be revisited per jurisdiction).
+ * Goes through the same atomic ledger primitive as every other movement, so
+ * the reconciliation invariant still holds.
+ */
+
+const transactionIndexer = { entityType: billingEntityIds.transaction } as const
+const transactionEvents = { module: 'billing', entity: 'transaction', persistent: true } as const
+
+function getEm(ctx: CommandRuntimeContext): EntityManager {
+  return (ctx.container.resolve('em') as EntityManager).fork()
+}
+
+function getDataEngine(ctx: CommandRuntimeContext): DataEngine {
+  return ctx.container.resolve('dataEngine') as DataEngine
+}
+
+export type AdjustResult = {
+  transactionId: string
+  balance: string
+  balanceStatus: BalanceStatus
+  deduplicated: boolean
+}
+
+const adjustTransactionCommand: CommandHandler<BillingTransactionAdjustInput, AdjustResult> = {
+  id: 'billing.transactions.adjust',
+
+  async execute(rawInput, ctx) {
+    const parsed = billingTransactionAdjustSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+    ensureOrganizationScope(ctx, parsed.organizationId)
+
+    const em = getEm(ctx)
+    const account = await em.findOne(BillingAccount, {
+      id: parsed.billAccountId,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      throw new CrudHttpError(404, { error: 'Billing account not found' })
+    }
+    if (account.billingMode !== 'prepaid') {
+      throw new CrudHttpError(409, {
+        error: 'Balance adjustments are only available on prepaid accounts',
+        code: 'billing.account.not_prepaid',
+      })
+    }
+
+    const balanceRow = await em.findOne(BillingAccountBalance, {
+      tenantId: parsed.tenantId,
+      billAccountId: account.id,
+    })
+    const threshold = resolveLowBalanceThreshold(
+      balanceRow?.lowBalanceThreshold ?? null,
+      await getLowBalanceThresholdDefault(em),
+    )
+    const nearLimitBuffer = await getNearLimitBufferDefault(em)
+    const userId = (ctx.auth?.sub as string | undefined) ?? null
+
+    const outcome = await em.transactional(async (tem) =>
+      applyBalanceMovement(tem as EntityManager, {
+        organizationId: parsed.organizationId,
+        tenantId: parsed.tenantId,
+        billAccountId: account.id,
+        currencyCode: account.currencyCode,
+        type: 'adjustment',
+        amount: formatMoney(parsed.amount),
+        description: parsed.description,
+        sourceRef: parsed.sourceRef ?? null,
+        userId,
+        metadata: { manual: true },
+      }),
+    )
+
+    // Index the transaction + emit threshold-crossing events after commit.
+    const created = outcome.transaction
+    await emitCrudSideEffects({
+      dataEngine: getDataEngine(ctx),
+      action: 'created',
+      entity: created,
+      identifiers: {
+        id: created.id,
+        tenantId: created.tenantId,
+        organizationId: created.organizationId,
+      },
+      indexer: transactionIndexer,
+      events: transactionEvents,
+    })
+
+    if (!outcome.deduplicated) {
+      const events = buildBalanceCrossingEvents({
+        scope: {
+          billAccountId: account.id,
+          tenantId: parsed.tenantId,
+          organizationId: parsed.organizationId,
+          currencyCode: account.currencyCode,
+        },
+        balanceBefore: outcome.balanceBefore,
+        balanceAfter: outcome.balanceAfter,
+        threshold,
+        creditLimit: account.creditLimit ?? '0',
+        nearLimitBuffer,
+      })
+      for (const ev of events) {
+        await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })
+      }
+    }
+
+    return {
+      transactionId: created.id,
+      balance: outcome.balanceAfter,
+      balanceStatus: computeBalanceStatus(outcome.balanceAfter, threshold),
+      deduplicated: outcome.deduplicated,
+    }
+  },
+}
+
+registerCommand(adjustTransactionCommand)
+
+export { adjustTransactionCommand }

package/src/modules/billing/commands/usage.ts

@@ -1,4 +1,5 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
+import { UniqueConstraintViolationException } from '@mikro-orm/core'
 import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands/types'
 import { registerCommand } from '@open-mercato/shared/lib/commands'
 import {
@@ -15,6 +16,11 @@ import {
   billingUsageCreateSchema,
   type BillingUsageCreateInput,
 } from '../data/validators'
+import {
+  consumePrepaidUsage,
+  type PrepaidConsumeResult,
+} from '../lib/prepaidConsume'
+import { emitBillingEvent, type BillingEventId } from '../events'
 
 /**
  * Usage ingest — append-only.
@@ -41,10 +47,20 @@ function getDataEngine(ctx: CommandRuntimeContext): DataEngine {
   return ctx.container.resolve('dataEngine') as DataEngine
 }
 
-const createUsageCommand: CommandHandler<
-  BillingUsageCreateInput,
-  { id: string; deduplicated: boolean }
-> = {
+export type CreateUsageResult = {
+  id: string
+  deduplicated: boolean
+  // Prepaid-only extras (SPEC-002) — present only for prepaid accounts.
+  ratedAmount?: string
+  currencyCode?: string
+  balance?: string
+  balanceStatus?: PrepaidConsumeResult['balanceStatus']
+  creditStatus?: PrepaidConsumeResult['creditStatus']
+  tierBreakdown?: PrepaidConsumeResult['tierBreakdown']
+  warning?: string | null
+}
+
+const createUsageCommand: CommandHandler<BillingUsageCreateInput, CreateUsageResult> = {
   id: 'billing.usage.create',
 
   async execute(rawInput, ctx) {
@@ -63,6 +79,11 @@ const createUsageCommand: CommandHandler<
       throw new CrudHttpError(404, { error: 'Billing account not found' })
     }
 
+    // ─── Prepaid: rate + atomic debit + balance, all in one tx ────
+    if (account.billingMode === 'prepaid') {
+      return executePrepaidConsume(ctx, em, account, parsed)
+    }
+
     if (parsed.sourceRef) {
       const existing = await findBySourceRef(em, BillingAccountUsage, {
         tenantId: parsed.tenantId,
@@ -113,6 +134,95 @@ const createUsageCommand: CommandHandler<
   },
 }
 
+/**
+ * Prepaid consume: rate + atomic debit + balance + transaction in one DB
+ * transaction, then index + emit domain events AFTER the commit.
+ */
+async function executePrepaidConsume(
+  ctx: CommandRuntimeContext,
+  em: EntityManager,
+  account: BillingAccount,
+  parsed: BillingUsageCreateInput,
+): Promise<CreateUsageResult> {
+  const input = {
+    organizationId: parsed.organizationId,
+    tenantId: parsed.tenantId,
+    billAccountId: parsed.billAccountId,
+    uomCode: parsed.uomCode,
+    quantity: parsed.quantity,
+    periodStart: parsed.periodStart,
+    periodEnd: parsed.periodEnd,
+    lineDescription: parsed.lineDescription ?? null,
+    sourceRef: parsed.sourceRef ?? null,
+  }
+
+  let outcome
+  try {
+    outcome = await em.transactional(async (tem) =>
+      consumePrepaidUsage(tem as EntityManager, account, input),
+    )
+  } catch (err) {
+    // Concurrency: a simultaneous upload with the same sourceRef won the
+    // unique-constraint race and committed first, so our tx rolled back (no
+    // double-debit). Retry once on a fresh em — the dedup pre-check now finds
+    // the winner's record and returns its balance_after (idempotent 200).
+    if (parsed.sourceRef && err instanceof UniqueConstraintViolationException) {
+      outcome = await em.fork().transactional(async (tem) =>
+        consumePrepaidUsage(tem as EntityManager, account, input),
+      )
+    } else {
+      throw err
+    }
+  }
+
+  // Index the new usage record (parity with the postpaid path) — only when a
+  // fresh record was actually written (a dedup hit re-reads the prior one).
+  if (!outcome.result.deduplicated) {
+    const usage = await em.findOne(BillingAccountUsage, {
+      id: outcome.result.id,
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId,
+    })
+    if (usage) {
+      await emitCrudSideEffects({
+        dataEngine: getDataEngine(ctx),
+        action: 'created',
+        entity: usage,
+        identifiers: {
+          id: usage.id,
+          tenantId: usage.tenantId,
+          organizationId: usage.organizationId,
+        },
+        indexer: usageIndexer,
+        events: usageEvents,
+      })
+    }
+  }
+
+  // Domain events fire AFTER the DB commit (consistent with the post command).
+  // `billing.usage.rated` fires on EVERY upload — emit it ephemerally (a live
+  // signal, excluded from triggers) so the high-throughput consume path does
+  // not write a queue row per call. The meaningful crossing events
+  // (low/exhausted/credit) stay persistent so async consumers never miss them.
+  for (const ev of outcome.events) {
+    const persistent = ev.id !== 'billing.usage.rated'
+    await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent })
+  }
+
+  const r = outcome.result
+  return {
+    id: r.id,
+    deduplicated: r.deduplicated,
+    ratedAmount: r.ratedAmount,
+    currencyCode: r.currencyCode,
+    balance: r.balance,
+    balanceStatus: r.balanceStatus,
+    creditStatus: r.creditStatus,
+    tierBreakdown: r.tierBreakdown,
+    warning: r.warning,
+  }
+}
+
 registerCommand(createUsageCommand)
 
 export { createUsageCommand }