@dainamite/billing 0.17.0 → 0.18.0

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

@@ -0,0 +1,153 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  SalesInvoice,
+  SalesInvoiceLine,
+} from '@open-mercato/core/modules/sales/data/entities'
+import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
+import type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'
+import { resolveInvoiceStatusEntryId } from './invoiceStatus'
+
+/**
+ * Creates the fiscal VAT receipt for a captured prepaid top-up (SPEC-002 P2).
+ *
+ * Deliberate divergence from the postpaid draft→post gate: a captured top-up
+ * is a completed, already-paid transaction with nothing to review, so the
+ * receipt is created **posted + paid** in one shot (the gate exists for
+ * outbound bills, not money already received — mirrors the xd-249 "deviations"
+ * convention).
+ *
+ * **VAT at top-up.** The top-up `amount` is the GROSS the customer paid (= the
+ * balance credited). The core tax service splits it into net + VAT at the
+ * configured rate. Gap-free numbering reuses `salesDocumentNumberGenerator`.
+ */
+
+export type TopupReceiptParams = {
+  account: {
+    id: string
+    organizationId: string
+    tenantId: string
+    currencyCode: string
+  }
+  topupId: string
+  paymentId: string
+  /** Gross amount paid (numeric(18,4) string). */
+  amount: string
+  /** VAT percent (e.g. 23). 0 = no VAT. */
+  taxRate: number
+}
+
+export type TopupReceiptDeps = {
+  numberGenerator: Pick<SalesDocumentNumberGenerator, 'generate'>
+  taxService: TaxCalculationService
+}
+
+export type TopupReceipt = {
+  invoiceId: string
+  invoiceNumber: string
+  netAmount: string
+  taxAmount: string
+  grossAmount: string
+  taxRate: number
+}
+
+function fmt4(value: number): string {
+  return (Number.isFinite(value) ? value : 0).toFixed(4)
+}
+
+export async function createTopupReceipt(
+  em: EntityManager,
+  deps: TopupReceiptDeps,
+  params: TopupReceiptParams,
+): Promise<TopupReceipt> {
+  const { account } = params
+
+  // VAT split — the top-up amount is GROSS (what was paid = balance credited).
+  const tax = await deps.taxService.calculateUnitAmounts({
+    amount: Number.parseFloat(params.amount),
+    mode: 'gross',
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+    taxRate: params.taxRate,
+  })
+  const net = fmt4(tax.netAmount)
+  const gross = fmt4(tax.grossAmount)
+  const taxAmount = fmt4(tax.taxAmount)
+  const effectiveRate = tax.taxRate ?? 0
+
+  const generated = await deps.numberGenerator.generate({
+    kind: 'invoice',
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+  })
+
+  // Posted+paid in one shot — resolve the `paid` status entry directly.
+  const paidStatusEntryId = await resolveInvoiceStatusEntryId(
+    em,
+    account.tenantId,
+    account.organizationId,
+    'paid',
+  )
+
+  const now = new Date()
+  const invoice = em.create(SalesInvoice, {
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+    invoiceNumber: generated.number,
+    statusEntryId: paidStatusEntryId,
+    status: 'paid',
+    issueDate: now,
+    currencyCode: account.currencyCode,
+    subtotalNetAmount: net,
+    subtotalGrossAmount: gross,
+    discountTotalAmount: '0',
+    taxTotalAmount: taxAmount,
+    grandTotalNetAmount: net,
+    grandTotalGrossAmount: gross,
+    paidTotalAmount: gross,
+    outstandingAmount: '0',
+    metadata: {
+      kind: 'prepaid_topup',
+      bill_account_id: account.id,
+      topup_id: params.topupId,
+      payment_id: params.paymentId,
+    },
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(invoice)
+
+  const line = em.create(SalesInvoiceLine, {
+    invoice,
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+    lineNumber: 1,
+    kind: 'service',
+    description: 'Account top-up',
+    quantity: '1',
+    normalizedQuantity: '1',
+    currencyCode: account.currencyCode,
+    unitPriceNet: net,
+    unitPriceGross: gross,
+    discountAmount: '0',
+    discountPercent: '0',
+    taxRate: fmt4(effectiveRate),
+    taxAmount,
+    totalNetAmount: net,
+    totalGrossAmount: gross,
+    metadata: {
+      kind: 'prepaid_topup',
+      topup_id: params.topupId,
+    },
+  })
+  em.persist(line)
+  await em.flush()
+
+  return {
+    invoiceId: invoice.id,
+    invoiceNumber: generated.number,
+    netAmount: net,
+    taxAmount,
+    grossAmount: gross,
+    taxRate: effectiveRate,
+  }
+}

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

@@ -0,0 +1,31 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingTopup } from '../data/entities'
+import type { TopupStatus } from '../data/validators'
+
+/**
+ * Transition a registered top-up to a terminal non-captured status
+ * (failed / cancelled / expired) in response to the sibling gateway events.
+ *
+ * Finding a BillingTopup by `payment_id` IS the guard: a non-top-up payment
+ * (e.g. a postpaid invoice, whose paymentId is the invoice id) matches no
+ * BillingTopup, so this is a silent no-op for everyone else. A captured
+ * top-up is never downgraded.
+ */
+export async function transitionTopupByPaymentId(
+  em: EntityManager,
+  scope: { paymentId: string; tenantId: string; organizationId: string },
+  toStatus: Extract<TopupStatus, 'failed' | 'cancelled' | 'expired'>,
+): Promise<BillingTopup | null> {
+  const topup = await em.findOne(BillingTopup, {
+    paymentId: scope.paymentId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+  if (!topup) return null
+  if (topup.status === 'captured' || topup.status === toStatus) return topup
+  topup.status = toStatus
+  topup.updatedAt = new Date()
+  await em.flush()
+  return topup
+}

package/src/modules/billing/migrations/Migration20260619000000_billing_prepaid.ts

@@ -0,0 +1,131 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Prepaid balance billing schema (SPEC-002).
+ *
+ * Additive only — extends `billing_accounts` + `billing_run_outcomes` and
+ * adds the four new prepaid tables. Postpaid accounts are unaffected
+ * (`billing_mode` defaults to 'postpaid', `credit_limit` to 0).
+ *
+ * Hand-written to match `data/entities.ts` 1:1 (index/constraint names mirror
+ * the decorator names so a later `yarn mercato db generate` diffs clean). The
+ * statements here are pure `create table` / `alter table … add column` —
+ * never destructive to existing billing data.
+ */
+export class Migration20260619000000_billing_prepaid extends Migration {
+  async up(): Promise<void> {
+    // ─── billing_accounts: billing_mode + credit_limit ───────
+    this.addSql(
+      `alter table "billing_accounts" add column "billing_mode" text not null default 'postpaid';`,
+    )
+    this.addSql(
+      `alter table "billing_accounts" add column "credit_limit" numeric(18, 4) not null default 0;`,
+    )
+
+    // ─── billing_run_outcomes: statement_id (prepaid analogue) ─
+    this.addSql(`alter table "billing_run_outcomes" add column "statement_id" uuid null;`)
+
+    // ─── billing_account_balances ────────────────────────────
+    this.addSql(`create table "billing_account_balances" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "currency_code" text not null,
+      "balance" numeric(18, 4) not null default 0,
+      "low_balance_threshold" numeric(18, 4) null,
+      "last_movement_at" timestamptz null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      constraint "billing_account_balances_pkey" primary key ("id")
+    );`)
+    this.addSql(`alter table "billing_account_balances" add constraint "billing_account_balances_account_unique" unique ("tenant_id", "bill_account_id");`)
+    this.addSql(`create index "billing_account_balances_balance_idx" on "billing_account_balances" ("organization_id", "tenant_id", "balance");`)
+
+    // ─── billing_account_transactions ────────────────────────
+    this.addSql(`create table "billing_account_transactions" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "type" text not null,
+      "amount" numeric(18, 4) not null,
+      "currency_code" text not null,
+      "balance_after" numeric(18, 4) not null,
+      "usage_id" uuid null,
+      "billing_item_id" uuid null,
+      "topup_id" uuid null,
+      "statement_id" uuid null,
+      "description" text not null,
+      "source_ref" text null,
+      "metadata" jsonb null,
+      "user_id" uuid null,
+      "created_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_account_transactions_pkey" primary key ("id")
+    );`)
+    this.addSql(`alter table "billing_account_transactions" add constraint "billing_account_transactions_source_ref_unique" unique ("tenant_id", "bill_account_id", "source_ref");`)
+    this.addSql(`create index "billing_account_transactions_history_idx" on "billing_account_transactions" ("organization_id", "tenant_id", "bill_account_id", "created_at");`)
+    this.addSql(`create index "billing_account_transactions_account_type_idx" on "billing_account_transactions" ("bill_account_id", "type", "created_at");`)
+
+    // ─── billing_topups ──────────────────────────────────────
+    this.addSql(`create table "billing_topups" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "status" text not null,
+      "amount" numeric(18, 4) not null,
+      "currency_code" text not null,
+      "provider_key" text not null,
+      "payment_id" uuid not null,
+      "gateway_transaction_id" uuid null,
+      "transaction_id" uuid null,
+      "receipt_invoice_id" uuid null,
+      "source_ref" text null,
+      "metadata" jsonb null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_topups_pkey" primary key ("id")
+    );`)
+    this.addSql(`alter table "billing_topups" add constraint "billing_topups_payment_id_unique" unique ("tenant_id", "payment_id");`)
+    this.addSql(`create index "billing_topups_account_history_idx" on "billing_topups" ("organization_id", "tenant_id", "bill_account_id", "created_at");`)
+    this.addSql(`create index "billing_topups_status_idx" on "billing_topups" ("tenant_id", "status");`)
+
+    // ─── billing_statements ──────────────────────────────────
+    this.addSql(`create table "billing_statements" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "bill_run_id" uuid null,
+      "period_start" date not null,
+      "period_end" date not null,
+      "currency_code" text not null,
+      "opening_balance" numeric(18, 4) not null,
+      "total_topups" numeric(18, 4) not null,
+      "total_usage" numeric(18, 4) not null,
+      "total_recurring" numeric(18, 4) not null,
+      "total_adjustments" numeric(18, 4) not null default 0,
+      "closing_balance" numeric(18, 4) not null,
+      "debit_breakdown" jsonb not null,
+      "status" text not null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      constraint "billing_statements_pkey" primary key ("id")
+    );`)
+    this.addSql(`alter table "billing_statements" add constraint "billing_statements_period_unique" unique ("tenant_id", "bill_account_id", "period_start", "period_end");`)
+    this.addSql(`create index "billing_statements_account_period_idx" on "billing_statements" ("organization_id", "tenant_id", "bill_account_id", "period_end");`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop table if exists "billing_statements" cascade;`)
+    this.addSql(`drop table if exists "billing_topups" cascade;`)
+    this.addSql(`drop table if exists "billing_account_transactions" cascade;`)
+    this.addSql(`drop table if exists "billing_account_balances" cascade;`)
+    this.addSql(`alter table "billing_run_outcomes" drop column if exists "statement_id";`)
+    this.addSql(`alter table "billing_accounts" drop column if exists "credit_limit";`)
+    this.addSql(`alter table "billing_accounts" drop column if exists "billing_mode";`)
+  }
+}

package/src/modules/billing/setup.ts

@@ -200,6 +200,45 @@ async function seedBillingConfigs(em: EntityManager): Promise<void> {
     name: 'invoice_number.reset_cycle',
     value: 'yearly',
   })
+
+  // ─── Prepaid balance billing (SPEC-002) ──────────────────────
+  // Fallback low-balance threshold when a prepaid account leaves its own
+  // `low_balance_threshold` null. 0 = off (status never flips to `low`
+  // until an operator sets a per-account threshold).
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'prepaid.low_balance_threshold_default',
+    value: 0,
+  })
+  // Default gateway provider key for top-up sessions.
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'prepaid.topup_provider',
+    value: 'stripe',
+  })
+  // Master switch for period statements.
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'prepaid.statement_enabled',
+    value: true,
+  })
+  // VAT rate (percent) applied to top-up receipts. The top-up `amount` is
+  // treated as GROSS (what the customer pays = what the balance is credited);
+  // the core tax service computes net + VAT from this rate. 0 = no VAT until
+  // an operator sets the jurisdiction's rate. (Deviation from xd-249, which
+  // never resolves a rate — see CHANGELOG.)
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'prepaid.topup_tax_rate',
+    value: 0,
+  })
+  // Fallback buffer for the `near_limit` credit status. 0 = warn only at the
+  // limit itself.
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'credit.near_limit_buffer_default',
+    value: 0,
+  })
 }
 
 // Derived from `acl.ts` so a new feature added there automatically lands
@@ -224,6 +263,12 @@ export const setup: ModuleSetupConfig = {
       'billing.run.view',
       'billing.run.dry_run',
       'billing.invoice.view',
+      // Prepaid read-only (SPEC-002): balances, transactions, top-ups,
+      // statements, credit status — no adjust / no top-up initiation.
+      'billing.balance.view',
+      'billing.credit.view',
+      'billing.topup.view',
+      'billing.statement.view',
     ],
 
     // Narrow scope for external usage-ingestion API keys.

package/src/modules/billing/subscribers/prepaid-topup-cancelled.ts

@@ -0,0 +1,31 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { transitionTopupByPaymentId } from '../lib/topupTransition'
+
+/**
+ * Subscriber: `payment_gateways.payment.cancelled` → BillingTopup → cancelled.
+ * No-op for any non-top-up payment. No balance movement.
+ */
+
+export const metadata = {
+  event: 'payment_gateways.payment.cancelled',
+  persistent: true,
+  id: 'billing-prepaid-topup-cancelled',
+}
+
+type Payload = { paymentId?: string; tenantId?: string; organizationId?: string }
+
+export default async function handle(payload: Payload): Promise<void> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) return
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await transitionTopupByPaymentId(
+    em,
+    {
+      paymentId: payload.paymentId,
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    },
+    'cancelled',
+  )
+}

package/src/modules/billing/subscribers/prepaid-topup-captured.ts

@@ -0,0 +1,120 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
+import type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'
+import { BillingAccount, BillingTopup } from '../data/entities'
+import { emitBillingEvent } from '../events'
+import { captureTopup } from '../lib/topupCapture'
+import { getTopupTaxRate } from '../lib/prepaidConfig'
+
+/**
+ * Subscriber: `payment_gateways.payment.captured` → prepaid top-up captured.
+ *
+ * Coexists with `payment-captured-to-paid.ts`: that subscriber matches
+ * `paymentId == invoiceId` (postpaid), while a top-up's `paymentId` is a
+ * minted UUID that only ever matches a `BillingTopup`. Finding the
+ * BillingTopup IS the guard — for any non-top-up payment this is a silent
+ * no-op.
+ *
+ * Idempotent: a re-fired capture on an already-captured top-up is a no-op
+ * (the gateway delivers webhooks at-least-once).
+ */
+
+export const metadata = {
+  event: 'payment_gateways.payment.captured',
+  persistent: true,
+  id: 'billing-prepaid-topup-captured',
+}
+
+type CapturedPayload = {
+  paymentId?: string
+  transactionId?: string
+  organizationId?: string
+  tenantId?: string
+  providerKey?: string
+}
+
+export default async function handle(payload: CapturedPayload): Promise<void> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) {
+    return
+  }
+
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+
+  const topup = await em.findOne(BillingTopup, {
+    paymentId: payload.paymentId,
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+    deletedAt: null,
+  })
+  if (!topup) {
+    // Not a prepaid top-up — other subscribers own this captured payment.
+    return
+  }
+  if (topup.status === 'captured') {
+    return // idempotent re-fire
+  }
+
+  const account = await em.findOne(BillingAccount, {
+    id: topup.billAccountId,
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+    deletedAt: null,
+  })
+  if (!account) {
+    return
+  }
+
+  const taxRate = await getTopupTaxRate(em)
+  const numberGenerator = container.resolve(
+    'salesDocumentNumberGenerator',
+  ) as SalesDocumentNumberGenerator
+  const taxService = container.resolve('taxCalculationService') as TaxCalculationService
+
+  const result = await captureTopup(
+    em,
+    { numberGenerator, taxService },
+    {
+      topup,
+      account: {
+        id: account.id,
+        organizationId: account.organizationId,
+        tenantId: account.tenantId,
+        currencyCode: account.currencyCode,
+      },
+      taxRate,
+      gatewayTransactionId: payload.transactionId ?? null,
+    },
+  )
+
+  if (result.status !== 'captured') return
+
+  // Side effects fire AFTER the capture transaction commits.
+  await emitBillingEvent('billing.balance.topped_up', {
+    billAccountId: account.id,
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+    topupId: topup.id,
+    amount: topup.amount,
+    currencyCode: account.currencyCode,
+    balance: result.balanceAfter ?? null,
+    transactionId: result.transactionId ?? null,
+    receiptInvoiceId: result.receiptInvoiceId ?? null,
+  })
+
+  // Reuse the postpaid receipt path so the existing mailer / accounting bridge
+  // sends the top-up VAT receipt.
+  if (result.receiptInvoiceId) {
+    await emitBillingEvent('billing.invoice.posted', {
+      invoiceId: result.receiptInvoiceId,
+      invoiceNumber: result.invoiceNumber ?? null,
+      tenantId: account.tenantId,
+      organizationId: account.organizationId,
+      grandTotalGross: result.grossAmount ?? null,
+      currencyCode: account.currencyCode,
+      billAccountId: account.id,
+      kind: 'prepaid_topup',
+    })
+  }
+}

package/src/modules/billing/subscribers/prepaid-topup-expired.ts

@@ -0,0 +1,31 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { transitionTopupByPaymentId } from '../lib/topupTransition'
+
+/**
+ * Subscriber: `payment_gateways.session.expired` → BillingTopup → expired.
+ * No-op for any non-top-up session. No balance movement.
+ */
+
+export const metadata = {
+  event: 'payment_gateways.session.expired',
+  persistent: true,
+  id: 'billing-prepaid-topup-expired',
+}
+
+type Payload = { paymentId?: string; tenantId?: string; organizationId?: string }
+
+export default async function handle(payload: Payload): Promise<void> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) return
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await transitionTopupByPaymentId(
+    em,
+    {
+      paymentId: payload.paymentId,
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    },
+    'expired',
+  )
+}

package/src/modules/billing/subscribers/prepaid-topup-failed.ts

@@ -0,0 +1,32 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { transitionTopupByPaymentId } from '../lib/topupTransition'
+
+/**
+ * Subscriber: `payment_gateways.payment.failed` → BillingTopup → failed.
+ * No-op for any non-top-up payment (no matching BillingTopup). No balance
+ * movement.
+ */
+
+export const metadata = {
+  event: 'payment_gateways.payment.failed',
+  persistent: true,
+  id: 'billing-prepaid-topup-failed',
+}
+
+type Payload = { paymentId?: string; tenantId?: string; organizationId?: string }
+
+export default async function handle(payload: Payload): Promise<void> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) return
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await transitionTopupByPaymentId(
+    em,
+    {
+      paymentId: payload.paymentId,
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    },
+    'failed',
+  )
+}

package/src/modules/billing/workers/reconcile-prepaid-balances.ts

@@ -0,0 +1,68 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingAccountBalance } from '../data/entities'
+import { reconcileAccountBalance } from '../lib/balanceLedger'
+
+export const metadata: WorkerMeta = {
+  queue: 'billing-reconcile-prepaid-balances',
+  id: 'billing:reconcile-prepaid-balances',
+  concurrency: 1,
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+/**
+ * Reconciliation guard (SPEC-002 P5, optional).
+ *
+ * Periodically asserts the ledger invariant per prepaid account:
+ *   `cachedBalance == SUM(transactions.amount) == latest.balance_after`.
+ *
+ * The atomic `UPDATE … RETURNING` + paired transaction insert keeps this true
+ * by construction, so a healthy system always reconciles. This worker is a
+ * cheap backstop against any future non-atomic write slipping in — it logs a
+ * warning per drifted account (the operator-facing alert) and never mutates
+ * the balance (a fix is a deliberate operator action, not an automatic one).
+ */
+const SCAN_LIMIT = 10_000
+
+export default async function handle(_job: QueuedJob, ctx: HandlerContext): Promise<void> {
+  const em = ctx.resolve<EntityManager>('em')
+  const rows = await em.find(
+    BillingAccountBalance,
+    {} as never,
+    { limit: SCAN_LIMIT, orderBy: { updatedAt: 'DESC' } },
+  )
+
+  let checked = 0
+  let drifted = 0
+  for (const row of rows) {
+    const result = await reconcileAccountBalance(em.fork(), {
+      tenantId: row.tenantId,
+      organizationId: row.organizationId,
+      billAccountId: row.billAccountId,
+    })
+    checked += 1
+    if (!result.reconciled) {
+      drifted += 1
+      console.warn('[billing/reconcile] balance drift detected', {
+        billAccountId: row.billAccountId,
+        tenantId: row.tenantId,
+        organizationId: row.organizationId,
+        cachedBalance: result.cachedBalance,
+        sumOfAmounts: result.sumOfAmounts,
+        latestBalanceAfter: result.latestBalanceAfter,
+      })
+    }
+  }
+
+  if (rows.length === SCAN_LIMIT) {
+    console.warn(
+      `[billing/reconcile] scan hit the ${SCAN_LIMIT}-row cap — some accounts were not checked this run`,
+    )
+  }
+  if (drifted > 0) {
+    console.warn(`[billing/reconcile] ${drifted}/${checked} prepaid accounts drifted`)
+  }
+}