@dainamite/billing 0.17.0 → 0.19.0

package/dist/modules/billing/lib/billRunEngine.js

@@ -15,14 +15,20 @@ import {
 } from "./invoiceWriter.js";
 import { withTenantLock } from "./tenantLock.js";
 import { processUsageForAccount } from "./usageRunner.js";
+import { processPrepaidAccount } from "./prepaidPeriodClose.js";
+import { emitBillingEvent } from "../events.js";
 const SCHEDULED_CYCLE_LIMIT = 1;
 const CATCH_UP_HARD_CAP = 60;
 async function runBillRun(em, container, params) {
-  return withTenantLock(
+  const output = await withTenantLock(
     em,
     { tenantId: params.tenantId, lockName: "billing-run" },
     async (tem) => executeRunWithinLock(tem, container, params)
   );
+  for (const ev of output.pendingEvents) {
+    await emitBillingEvent(ev.id, ev.payload, { persistent: true });
+  }
+  return { billRun: output.billRun, outcomes: output.outcomes };
 }
 async function executeRunWithinLock(em, container, params) {
   const now = /* @__PURE__ */ new Date();
@@ -47,6 +53,7 @@ async function executeRunWithinLock(em, container, params) {
   await em.flush();
   const accounts = await selectTargetAccounts(em, params);
   const outcomes = [];
+  const pendingEvents = [];
   let totalUsageRecordsRated = 0;
   for (const account of accounts) {
     const processResult = await processAccountSafely(em, container, billRun, account, params);
@@ -62,6 +69,7 @@ async function executeRunWithinLock(em, container, params) {
       errorMessage: processResult.status === "failed" ? processResult.errorMessage : null,
       warnings: processResult.status === "failed" ? null : processResult.warnings,
       draftInvoiceId: processResult.status === "failed" ? null : processResult.draftInvoiceId,
+      statementId: processResult.status === "failed" ? null : processResult.statementId ?? null,
       isActive: true,
       createdAt: /* @__PURE__ */ new Date(),
       updatedAt: /* @__PURE__ */ new Date()
@@ -69,13 +77,16 @@ async function executeRunWithinLock(em, container, params) {
     em.persist(outcome);
     await em.flush();
     outcomes.push(outcome);
+    if (processResult.status !== "failed" && processResult.statementEvents) {
+      pendingEvents.push(...processResult.statementEvents);
+    }
   }
   billRun.status = computeFinalRunStatus(outcomes);
   billRun.finishedAt = /* @__PURE__ */ new Date();
   billRun.updatedAt = billRun.finishedAt;
   billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated);
   await em.flush();
-  return { billRun, outcomes };
+  return { billRun, outcomes, pendingEvents };
 }
 async function selectTargetAccounts(em, params) {
   const where = {
@@ -102,6 +113,26 @@ async function processAccountSafely(em, container, billRun, account, params) {
   }
 }
 async function processAccount(em, container, billRun, account, params) {
+  if (account.billingMode === "prepaid") {
+    const result = await processPrepaidAccount(em, account, billRun, {
+      asOfDate: params.asOfDate,
+      mode: params.mode,
+      triggeredBy: params.triggeredBy,
+      catchUp: params.catchUp
+    });
+    if (result.status === "failed") {
+      return { status: "failed", errorMessage: result.errorMessage };
+    }
+    return {
+      status: result.status,
+      warnings: result.warnings,
+      draftInvoiceId: null,
+      statementId: result.statementId,
+      statementEvents: result.statementEvents,
+      cyclesEmitted: result.cyclesEmitted,
+      usageRecordsRated: 0
+    };
+  }
   const maxCycles = params.triggeredBy === "schedule" || !params.catchUp ? SCHEDULED_CYCLE_LIMIT : CATCH_UP_HARD_CAP;
   let cyclesEmitted = 0;
   let lastDraftInvoiceId = null;
@@ -245,6 +276,13 @@ function buildRunSummary(outcomes, totalAccounts, usageRecordsRated) {
       (o) => o.draftInvoiceId !== null && o.status !== "skipped_existing_draft"
     ).length,
     drafts_skipped_existing: outcomes.filter((o) => o.status === "skipped_existing_draft").length,
+    // SPEC-002 prepaid period close.
+    statements_created: outcomes.filter(
+      (o) => o.statementId !== null && o.status !== "skipped_existing_statement"
+    ).length,
+    statements_skipped_existing: outcomes.filter(
+      (o) => o.status === "skipped_existing_statement"
+    ).length,
     accounts_failed: outcomes.filter((o) => o.status === "failed").length,
     accounts_with_warnings: outcomes.filter((o) => o.status === "success_with_warnings").length,
     usage_records_rated: usageRecordsRated

package/dist/modules/billing/lib/billRunEngine.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/billRunEngine.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport {\n  BillingAccount,\n  BillingAccountUsage,\n  BillingItem,\n  BillRun,\n  BillRunOutcome,\n} from '../data/entities'\nimport { advanceNextBillDate, deriveBillPeriod, isCycleDue } from './billPeriod'\nimport {\n  selectItemsForPeriod,\n  type SelectableItem,\n} from './itemSelector'\nimport {\n  buildInvoiceLinesFromItems,\n  writeDraftInvoice,\n  type InvoiceLineDescriptor,\n  type WriteMode,\n} from './invoiceWriter'\nimport { withTenantLock } from './tenantLock'\nimport { processUsageForAccount } from './usageRunner'\nimport type { BillCycle } from '../data/validators'\n\n/**\n * Bill Run engine \u2014 orchestrates one execution of the billing cycle for\n * a single tenant.\n *\n * Concurrency / locking:\n *   - The whole run is wrapped in `withTenantLock(...)`, which holds a\n *     transaction-scoped Postgres advisory lock keyed by\n *     `hash(tenant_id || ':billing-run')`. A second trigger fired while a\n *     run is in flight short-circuits with `TenantLockBusyError` (the\n *     command layer maps that to HTTP 409).\n *   - Within the outer transaction, every account is processed inside a\n *     nested `em.transactional(...)` (PG SAVEPOINT). A per-account failure\n *     rolls back only that account's work, leaving siblings unaffected.\n *\n * Run modes:\n *   - `real` (default) \u2014 persist drafts, advance `next_bill_date`, mark\n *     items `billed_to_date`. Production path.\n *   - `test` \u2014 persist drafts flagged with `metadata.test_run=true`, but\n *     do NOT advance state. Repeatable.\n *   - `dry`  \u2014 compute everything; persist nothing. Preview only.\n *\n * Catch-up:\n *   - Manual triggers may set `catchUp=true`. The engine then loops cycles\n *     per account until `next_bill_date > as_of_date`, emitting one draft\n *     per missed cycle (never combined).\n *   - Scheduled triggers always process exactly ONE cycle per account per\n *     run, regardless of how far behind the account is.\n *\n * Anti-duplicate guards (both run in every mode except `dry`):\n *   1. Open-draft check on `core/sales` invoice (per period boundary).\n *   2. `billed_to_date` per BillingItem.\n */\n\nexport type RunMode = WriteMode\n\nexport type RunBillRunParams = {\n  tenantId: string\n  organizationId: string\n  asOfDate: Date\n  triggeredBy: 'schedule' | 'manual'\n  mode: RunMode\n  scopedAccountIds?: string[]\n  parentRunId?: string | null\n  catchUp?: boolean\n}\n\nexport type RunBillRunResult = {\n  billRun: BillRun\n  outcomes: BillRunOutcome[]\n}\n\ntype AccountWarnings = {\n  currency_mismatch_items?: string[]\n  unmatched_usage_uoms?: string[]\n}\n\ntype AccountProcessSuccess = {\n  status: 'success' | 'success_with_warnings' | 'skipped_existing_draft'\n  warnings: AccountWarnings | null\n  draftInvoiceId: string | null\n  cyclesEmitted: number\n  usageRecordsRated: number\n}\n\ntype AccountProcessFailed = {\n  status: 'failed'\n  errorMessage: string\n}\n\ntype AccountProcessResult = AccountProcessSuccess | AccountProcessFailed\n\nconst SCHEDULED_CYCLE_LIMIT = 1\nconst CATCH_UP_HARD_CAP = 60 // safety net so a misconfigured account can't loop forever\n\nexport async function runBillRun(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunBillRunResult> {\n  return withTenantLock(\n    em,\n    { tenantId: params.tenantId, lockName: 'billing-run' },\n    async (tem) => executeRunWithinLock(tem, container, params),\n  )\n}\n\nasync function executeRunWithinLock(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunBillRunResult> {\n  const now = new Date()\n  const billRun = em.create(BillRun, {\n    organizationId: params.organizationId,\n    tenantId: params.tenantId,\n    triggeredBy: params.triggeredBy,\n    parentRunId: params.parentRunId ?? null,\n    dryRun: params.mode === 'dry',\n    testMode: params.mode === 'test',\n    catchUp: Boolean(params.catchUp),\n    scopedAccountIds: params.scopedAccountIds ?? null,\n    asOfDate: params.asOfDate,\n    startedAt: now,\n    status: 'running',\n    summary: null,\n    isActive: true,\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(billRun)\n  await em.flush()\n\n  const accounts = await selectTargetAccounts(em, params)\n  const outcomes: BillRunOutcome[] = []\n  let totalUsageRecordsRated = 0\n\n  for (const account of accounts) {\n    const processResult = await processAccountSafely(em, container, billRun, account, params)\n    if (processResult.status !== 'failed') {\n      totalUsageRecordsRated += processResult.usageRecordsRated\n    }\n    const outcome = em.create(BillRunOutcome, {\n      organizationId: params.organizationId,\n      tenantId: params.tenantId,\n      billRunId: billRun.id,\n      billAccountId: account.id,\n      status: processResult.status,\n      errorMessage: processResult.status === 'failed' ? processResult.errorMessage : null,\n      warnings:\n        processResult.status === 'failed'\n          ? null\n          : (processResult.warnings as Record<string, unknown> | null),\n      draftInvoiceId: processResult.status === 'failed' ? null : processResult.draftInvoiceId,\n      isActive: true,\n      createdAt: new Date(),\n      updatedAt: new Date(),\n    })\n    em.persist(outcome)\n    await em.flush()\n    outcomes.push(outcome)\n  }\n\n  billRun.status = computeFinalRunStatus(outcomes)\n  billRun.finishedAt = new Date()\n  billRun.updatedAt = billRun.finishedAt\n  billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated)\n  await em.flush()\n\n  return { billRun, outcomes }\n}\n\nasync function selectTargetAccounts(\n  em: EntityManager,\n  params: RunBillRunParams,\n): Promise<BillingAccount[]> {\n  const where: Record<string, unknown> = {\n    tenantId: params.tenantId,\n    organizationId: params.organizationId,\n    deletedAt: null,\n    nextBillDate: { $lte: params.asOfDate },\n  }\n  if (params.scopedAccountIds && params.scopedAccountIds.length > 0) {\n    where.id = { $in: params.scopedAccountIds }\n  }\n  return em.find(BillingAccount, where as never)\n}\n\nasync function processAccountSafely(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  try {\n    return await em.transactional(async (subEm) => {\n      return processAccount(subEm, container, billRun, account, params)\n    })\n  } catch (err) {\n    return {\n      status: 'failed',\n      errorMessage: err instanceof Error ? err.message : String(err),\n    }\n  }\n}\n\nasync function processAccount(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  const maxCycles =\n    params.triggeredBy === 'schedule' || !params.catchUp\n      ? SCHEDULED_CYCLE_LIMIT\n      : CATCH_UP_HARD_CAP\n\n  let cyclesEmitted = 0\n  let lastDraftInvoiceId: string | null = null\n  let totalUsageRatedThisAccount = 0\n  const aggregatedWarnings: AccountWarnings = {}\n\n  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {\n    const period = deriveBillPeriod(account.nextBillDate, account.billCycle as BillCycle)\n\n    // Open-draft anti-duplicate \u2014 only applies when we'd actually persist.\n    if (params.mode !== 'dry') {\n      const existing = await findExistingDraftForPeriod(em, account, period)\n      if (existing) {\n        return {\n          status: 'skipped_existing_draft',\n          warnings: null,\n          draftInvoiceId: existing,\n          cyclesEmitted,\n          usageRecordsRated: totalUsageRatedThisAccount,\n        }\n      }\n    }\n\n    const items = await em.find(BillingItem, {\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      billAccountId: account.id,\n      deletedAt: null,\n    } as never)\n\n    const usageItems = (items as BillingItem[]).filter((it) => it.type === 'usage')\n\n    // Non-usage path: one_time + recurring filtered by the selector.\n    const { included } = selectItemsForPeriod(items as SelectableItem[], period)\n    const billableItems = included as unknown as BillingItem[]\n\n    const currencyMismatchIds = billableItems\n      .filter((it) => it.currencyMismatch)\n      .map((it) => it.id)\n    if (currencyMismatchIds.length > 0) {\n      aggregatedWarnings.currency_mismatch_items = [\n        ...(aggregatedWarnings.currency_mismatch_items ?? []),\n        ...currencyMismatchIds,\n      ]\n    }\n    const itemLines = buildInvoiceLinesFromItems(billableItems)\n\n    // Usage path: aggregate matching usage records per uom_code, rate,\n    // emit one line per matched usage item, warn about unmatched UoMs.\n    const usageResult = await processUsageForAccount(em, account, period, usageItems)\n    if (usageResult.unmatchedUoms.length > 0) {\n      aggregatedWarnings.unmatched_usage_uoms = [\n        ...(aggregatedWarnings.unmatched_usage_uoms ?? []),\n        ...usageResult.unmatchedUoms,\n      ]\n    }\n\n    const allLines: InvoiceLineDescriptor[] = [...itemLines, ...usageResult.lines]\n    if (allLines.length === 0) {\n      // Nothing to bill this cycle \u2014 still advance so the account moves\n      // forward in real mode. In test / dry, no advance, so we'd loop\n      // forever; break out.\n      if (params.mode !== 'real') break\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = new Date()\n      cyclesEmitted += 1\n      continue\n    }\n\n    const written = await writeDraftInvoice(em, container, {\n      mode: params.mode,\n      account,\n      period,\n      billRunId: billRun.id,\n      lines: allLines,\n    })\n    lastDraftInvoiceId = written.invoiceId\n\n    if (params.mode === 'real') {\n      const now = new Date()\n      for (const item of billableItems) {\n        item.billedToDate = period.periodEnd\n        item.updatedAt = now\n      }\n      // Mark consumed usage records \u2014 single bulk update so we don't\n      // round-trip per record on accounts with thousands of usage rows.\n      if (usageResult.matchedUoms.length > 0) {\n        // Predicate-based bulk update: marks every still-unrated record\n        // for the matched uoms in the account's period with a single\n        // SQL UPDATE \u2014 no id list ever leaves Postgres. Stays\n        // memory-bounded even for telco accounts with millions of\n        // usage records per cycle (spec Performance Considerations\n        // \"Shape B\").\n        await em.nativeUpdate(\n          BillingAccountUsage,\n          {\n            tenantId: account.tenantId,\n            organizationId: account.organizationId,\n            billAccountId: account.id,\n            uomCode: { $in: usageResult.matchedUoms },\n            ratedInBillRunId: null,\n            periodEnd: { $lte: period.periodEnd },\n            deletedAt: null,\n          } as never,\n          { ratedInBillRunId: billRun.id, updatedAt: now } as never,\n        )\n      }\n      totalUsageRatedThisAccount += usageResult.ratedCount\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = now\n      await em.flush()\n    } else {\n      // Test / dry: do not advance state. One iteration only.\n      break\n    }\n\n    cyclesEmitted += 1\n  }\n\n  const hasCurrencyWarnings =\n    (aggregatedWarnings.currency_mismatch_items ?? []).length > 0\n  const hasUnmatchedUsage =\n    (aggregatedWarnings.unmatched_usage_uoms ?? []).length > 0\n  const hasWarnings = hasCurrencyWarnings || hasUnmatchedUsage\n  return {\n    status: hasWarnings ? 'success_with_warnings' : 'success',\n    warnings: hasWarnings ? aggregatedWarnings : null,\n    draftInvoiceId: lastDraftInvoiceId,\n    cyclesEmitted,\n    usageRecordsRated: totalUsageRatedThisAccount,\n  }\n}\n\nasync function findExistingDraftForPeriod(\n  em: EntityManager,\n  account: BillingAccount,\n  period: { periodStart: Date; periodEnd: Date },\n): Promise<string | null> {\n  const periodStartISO = period.periodStart.toISOString().slice(0, 10)\n  const periodEndISO = period.periodEnd.toISOString().slice(0, 10)\n  const rows = (await em.execute(\n    `SELECT id FROM sales_invoices\n     WHERE tenant_id = ?\n       AND organization_id = ?\n       AND deleted_at IS NULL\n       AND status = 'draft'\n       AND metadata->>'bill_account_id' = ?\n       AND metadata->>'bill_period_start' = ?\n       AND metadata->>'bill_period_end' = ?\n     LIMIT 1`,\n    [account.tenantId, account.organizationId, account.id, periodStartISO, periodEndISO],\n  )) as unknown as Array<{ id: string }> | undefined\n  if (!rows || rows.length === 0) return null\n  return rows[0].id ?? null\n}\n\nfunction computeFinalRunStatus(\n  outcomes: readonly BillRunOutcome[],\n): BillRun['status'] {\n  if (outcomes.length === 0) return 'completed'\n  const anyFailed = outcomes.some((o) => o.status === 'failed')\n  const anySuccess = outcomes.some(\n    (o) => o.status === 'success' || o.status === 'success_with_warnings',\n  )\n  if (anyFailed && anySuccess) return 'partial_failure'\n  if (anyFailed) return 'partial_failure'\n  return 'completed'\n}\n\nfunction buildRunSummary(\n  outcomes: readonly BillRunOutcome[],\n  totalAccounts: number,\n  usageRecordsRated: number,\n): Record<string, unknown> {\n  return {\n    accounts_processed: totalAccounts,\n    drafts_created: outcomes.filter(\n      (o) => o.draftInvoiceId !== null && o.status !== 'skipped_existing_draft',\n    ).length,\n    drafts_skipped_existing: outcomes.filter((o) => o.status === 'skipped_existing_draft')\n      .length,\n    accounts_failed: outcomes.filter((o) => o.status === 'failed').length,\n    accounts_with_warnings: outcomes.filter((o) => o.status === 'success_with_warnings')\n      .length,\n    usage_records_rated: usageRecordsRated,\n  }\n}\n"],
-  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,qBAAqB,kBAAkB,kBAAkB;AAClE;AAAA,EACE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP,SAAS,sBAAsB;AAC/B,SAAS,8BAA8B;AA0EvC,MAAM,wBAAwB;AAC9B,MAAM,oBAAoB;AAE1B,eAAsB,WACpB,IACA,WACA,QAC2B;AAC3B,SAAO;AAAA,IACL;AAAA,IACA,EAAE,UAAU,OAAO,UAAU,UAAU,cAAc;AAAA,IACrD,OAAO,QAAQ,qBAAqB,KAAK,WAAW,MAAM;AAAA,EAC5D;AACF;AAEA,eAAe,qBACb,IACA,WACA,QAC2B;AAC3B,QAAM,MAAM,oBAAI,KAAK;AACrB,QAAM,UAAU,GAAG,OAAO,SAAS;AAAA,IACjC,gBAAgB,OAAO;AAAA,IACvB,UAAU,OAAO;AAAA,IACjB,aAAa,OAAO;AAAA,IACpB,aAAa,OAAO,eAAe;AAAA,IACnC,QAAQ,OAAO,SAAS;AAAA,IACxB,UAAU,OAAO,SAAS;AAAA,IAC1B,SAAS,QAAQ,OAAO,OAAO;AAAA,IAC/B,kBAAkB,OAAO,oBAAoB;AAAA,IAC7C,UAAU,OAAO;AAAA,IACjB,WAAW;AAAA,IACX,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,IACV,WAAW;AAAA,IACX,WAAW;AAAA,EACb,CAAC;AACD,KAAG,QAAQ,OAAO;AAClB,QAAM,GAAG,MAAM;AAEf,QAAM,WAAW,MAAM,qBAAqB,IAAI,MAAM;AACtD,QAAM,WAA6B,CAAC;AACpC,MAAI,yBAAyB;AAE7B,aAAW,WAAW,UAAU;AAC9B,UAAM,gBAAgB,MAAM,qBAAqB,IAAI,WAAW,SAAS,SAAS,MAAM;AACxF,QAAI,cAAc,WAAW,UAAU;AACrC,gCAA0B,cAAc;AAAA,IAC1C;AACA,UAAM,UAAU,GAAG,OAAO,gBAAgB;AAAA,MACxC,gBAAgB,OAAO;AAAA,MACvB,UAAU,OAAO;AAAA,MACjB,WAAW,QAAQ;AAAA,MACnB,eAAe,QAAQ;AAAA,MACvB,QAAQ,cAAc;AAAA,MACtB,cAAc,cAAc,WAAW,WAAW,cAAc,eAAe;AAAA,MAC/E,UACE,cAAc,WAAW,WACrB,OACC,cAAc;AAAA,MACrB,gBAAgB,cAAc,WAAW,WAAW,OAAO,cAAc;AAAA,MACzE,UAAU;AAAA,MACV,WAAW,oBAAI,KAAK;AAAA,MACpB,WAAW,oBAAI,KAAK;AAAA,IACtB,CAAC;AACD,OAAG,QAAQ,OAAO;AAClB,UAAM,GAAG,MAAM;AACf,aAAS,KAAK,OAAO;AAAA,EACvB;AAEA,UAAQ,SAAS,sBAAsB,QAAQ;AAC/C,UAAQ,aAAa,oBAAI,KAAK;AAC9B,UAAQ,YAAY,QAAQ;AAC5B,UAAQ,UAAU,gBAAgB,UAAU,SAAS,QAAQ,sBAAsB;AACnF,QAAM,GAAG,MAAM;AAEf,SAAO,EAAE,SAAS,SAAS;AAC7B;AAEA,eAAe,qBACb,IACA,QAC2B;AAC3B,QAAM,QAAiC;AAAA,IACrC,UAAU,OAAO;AAAA,IACjB,gBAAgB,OAAO;AAAA,IACvB,WAAW;AAAA,IACX,cAAc,EAAE,MAAM,OAAO,SAAS;AAAA,EACxC;AACA,MAAI,OAAO,oBAAoB,OAAO,iBAAiB,SAAS,GAAG;AACjE,UAAM,KAAK,EAAE,KAAK,OAAO,iBAAiB;AAAA,EAC5C;AACA,SAAO,GAAG,KAAK,gBAAgB,KAAc;AAC/C;AAEA,eAAe,qBACb,IACA,WACA,SACA,SACA,QAC+B;AAC/B,MAAI;AACF,WAAO,MAAM,GAAG,cAAc,OAAO,UAAU;AAC7C,aAAO,eAAe,OAAO,WAAW,SAAS,SAAS,MAAM;AAAA,IAClE,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IAC/D;AAAA,EACF;AACF;AAEA,eAAe,eACb,IACA,WACA,SACA,SACA,QAC+B;AAC/B,QAAM,YACJ,OAAO,gBAAgB,cAAc,CAAC,OAAO,UACzC,wBACA;AAEN,MAAI,gBAAgB;AACpB,MAAI,qBAAoC;AACxC,MAAI,6BAA6B;AACjC,QAAM,qBAAsC,CAAC;AAE7C,SAAO,gBAAgB,aAAa,WAAW,QAAQ,cAAc,OAAO,QAAQ,GAAG;AACrF,UAAM,SAAS,iBAAiB,QAAQ,cAAc,QAAQ,SAAsB;AAGpF,QAAI,OAAO,SAAS,OAAO;AACzB,YAAM,WAAW,MAAM,2BAA2B,IAAI,SAAS,MAAM;AACrE,UAAI,UAAU;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,UAAU;AAAA,UACV,gBAAgB;AAAA,UAChB;AAAA,UACA,mBAAmB;AAAA,QACrB;AAAA,MACF;AAAA,IACF;AAEA,UAAM,QAAQ,MAAM,GAAG,KAAK,aAAa;AAAA,MACvC,UAAU,QAAQ;AAAA,MAClB,gBAAgB,QAAQ;AAAA,MACxB,eAAe,QAAQ;AAAA,MACvB,WAAW;AAAA,IACb,CAAU;AAEV,UAAM,aAAc,MAAwB,OAAO,CAAC,OAAO,GAAG,SAAS,OAAO;AAG9E,UAAM,EAAE,SAAS,IAAI,qBAAqB,OAA2B,MAAM;AAC3E,UAAM,gBAAgB;AAEtB,UAAM,sBAAsB,cACzB,OAAO,CAAC,OAAO,GAAG,gBAAgB,EAClC,IAAI,CAAC,OAAO,GAAG,EAAE;AACpB,QAAI,oBAAoB,SAAS,GAAG;AAClC,yBAAmB,0BAA0B;AAAA,QAC3C,GAAI,mBAAmB,2BAA2B,CAAC;AAAA,QACnD,GAAG;AAAA,MACL;AAAA,IACF;AACA,UAAM,YAAY,2BAA2B,aAAa;AAI1D,UAAM,cAAc,MAAM,uBAAuB,IAAI,SAAS,QAAQ,UAAU;AAChF,QAAI,YAAY,cAAc,SAAS,GAAG;AACxC,yBAAmB,uBAAuB;AAAA,QACxC,GAAI,mBAAmB,wBAAwB,CAAC;AAAA,QAChD,GAAG,YAAY;AAAA,MACjB;AAAA,IACF;AAEA,UAAM,WAAoC,CAAC,GAAG,WAAW,GAAG,YAAY,KAAK;AAC7E,QAAI,SAAS,WAAW,GAAG;AAIzB,UAAI,OAAO,SAAS,OAAQ;AAC5B,cAAQ,eAAe;AAAA,QACrB,QAAQ;AAAA,QACR,QAAQ;AAAA,MACV;AACA,cAAQ,eAAe,OAAO;AAC9B,cAAQ,YAAY,oBAAI,KAAK;AAC7B,uBAAiB;AACjB;AAAA,IACF;AAEA,UAAM,UAAU,MAAM,kBAAkB,IAAI,WAAW;AAAA,MACrD,MAAM,OAAO;AAAA,MACb;AAAA,MACA;AAAA,MACA,WAAW,QAAQ;AAAA,MACnB,OAAO;AAAA,IACT,CAAC;AACD,yBAAqB,QAAQ;AAE7B,QAAI,OAAO,SAAS,QAAQ;AAC1B,YAAM,MAAM,oBAAI,KAAK;AACrB,iBAAW,QAAQ,eAAe;AAChC,aAAK,eAAe,OAAO;AAC3B,aAAK,YAAY;AAAA,MACnB;AAGA,UAAI,YAAY,YAAY,SAAS,GAAG;AAOtC,cAAM,GAAG;AAAA,UACP;AAAA,UACA;AAAA,YACE,UAAU,QAAQ;AAAA,YAClB,gBAAgB,QAAQ;AAAA,YACxB,eAAe,QAAQ;AAAA,YACvB,SAAS,EAAE,KAAK,YAAY,YAAY;AAAA,YACxC,kBAAkB;AAAA,YAClB,WAAW,EAAE,MAAM,OAAO,UAAU;AAAA,YACpC,WAAW;AAAA,UACb;AAAA,UACA,EAAE,kBAAkB,QAAQ,IAAI,WAAW,IAAI;AAAA,QACjD;AAAA,MACF;AACA,oCAA8B,YAAY;AAC1C,cAAQ,eAAe;AAAA,QACrB,QAAQ;AAAA,QACR,QAAQ;AAAA,MACV;AACA,cAAQ,eAAe,OAAO;AAC9B,cAAQ,YAAY;AACpB,YAAM,GAAG,MAAM;AAAA,IACjB,OAAO;AAEL;AAAA,IACF;AAEA,qBAAiB;AAAA,EACnB;AAEA,QAAM,uBACH,mBAAmB,2BAA2B,CAAC,GAAG,SAAS;AAC9D,QAAM,qBACH,mBAAmB,wBAAwB,CAAC,GAAG,SAAS;AAC3D,QAAM,cAAc,uBAAuB;AAC3C,SAAO;AAAA,IACL,QAAQ,cAAc,0BAA0B;AAAA,IAChD,UAAU,cAAc,qBAAqB;AAAA,IAC7C,gBAAgB;AAAA,IAChB;AAAA,IACA,mBAAmB;AAAA,EACrB;AACF;AAEA,eAAe,2BACb,IACA,SACA,QACwB;AACxB,QAAM,iBAAiB,OAAO,YAAY,YAAY,EAAE,MAAM,GAAG,EAAE;AACnE,QAAM,eAAe,OAAO,UAAU,YAAY,EAAE,MAAM,GAAG,EAAE;AAC/D,QAAM,OAAQ,MAAM,GAAG;AAAA,IACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,CAAC,QAAQ,UAAU,QAAQ,gBAAgB,QAAQ,IAAI,gBAAgB,YAAY;AAAA,EACrF;AACA,MAAI,CAAC,QAAQ,KAAK,WAAW,EAAG,QAAO;AACvC,SAAO,KAAK,CAAC,EAAE,MAAM;AACvB;AAEA,SAAS,sBACP,UACmB;AACnB,MAAI,SAAS,WAAW,EAAG,QAAO;AAClC,QAAM,YAAY,SAAS,KAAK,CAAC,MAAM,EAAE,WAAW,QAAQ;AAC5D,QAAM,aAAa,SAAS;AAAA,IAC1B,CAAC,MAAM,EAAE,WAAW,aAAa,EAAE,WAAW;AAAA,EAChD;AACA,MAAI,aAAa,WAAY,QAAO;AACpC,MAAI,UAAW,QAAO;AACtB,SAAO;AACT;AAEA,SAAS,gBACP,UACA,eACA,mBACyB;AACzB,SAAO;AAAA,IACL,oBAAoB;AAAA,IACpB,gBAAgB,SAAS;AAAA,MACvB,CAAC,MAAM,EAAE,mBAAmB,QAAQ,EAAE,WAAW;AAAA,IACnD,EAAE;AAAA,IACF,yBAAyB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,wBAAwB,EAClF;AAAA,IACH,iBAAiB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,QAAQ,EAAE;AAAA,IAC/D,wBAAwB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,uBAAuB,EAChF;AAAA,IACH,qBAAqB;AAAA,EACvB;AACF;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport {\n  BillingAccount,\n  BillingAccountUsage,\n  BillingItem,\n  BillRun,\n  BillRunOutcome,\n} from '../data/entities'\nimport { advanceNextBillDate, deriveBillPeriod, isCycleDue } from './billPeriod'\nimport {\n  selectItemsForPeriod,\n  type SelectableItem,\n} from './itemSelector'\nimport {\n  buildInvoiceLinesFromItems,\n  writeDraftInvoice,\n  type InvoiceLineDescriptor,\n  type WriteMode,\n} from './invoiceWriter'\nimport { withTenantLock } from './tenantLock'\nimport { processUsageForAccount } from './usageRunner'\nimport { processPrepaidAccount } from './prepaidPeriodClose'\nimport type { DomainEvent } from './balanceEvents'\nimport { emitBillingEvent, type BillingEventId } from '../events'\nimport type { BillCycle } from '../data/validators'\n\n/**\n * Bill Run engine \u2014 orchestrates one execution of the billing cycle for\n * a single tenant.\n *\n * Concurrency / locking:\n *   - The whole run is wrapped in `withTenantLock(...)`, which holds a\n *     transaction-scoped Postgres advisory lock keyed by\n *     `hash(tenant_id || ':billing-run')`. A second trigger fired while a\n *     run is in flight short-circuits with `TenantLockBusyError` (the\n *     command layer maps that to HTTP 409).\n *   - Within the outer transaction, every account is processed inside a\n *     nested `em.transactional(...)` (PG SAVEPOINT). A per-account failure\n *     rolls back only that account's work, leaving siblings unaffected.\n *\n * Run modes:\n *   - `real` (default) \u2014 persist drafts, advance `next_bill_date`, mark\n *     items `billed_to_date`. Production path.\n *   - `test` \u2014 persist drafts flagged with `metadata.test_run=true`, but\n *     do NOT advance state. Repeatable.\n *   - `dry`  \u2014 compute everything; persist nothing. Preview only.\n *\n * Catch-up:\n *   - Manual triggers may set `catchUp=true`. The engine then loops cycles\n *     per account until `next_bill_date > as_of_date`, emitting one draft\n *     per missed cycle (never combined).\n *   - Scheduled triggers always process exactly ONE cycle per account per\n *     run, regardless of how far behind the account is.\n *\n * Anti-duplicate guards (both run in every mode except `dry`):\n *   1. Open-draft check on `core/sales` invoice (per period boundary).\n *   2. `billed_to_date` per BillingItem.\n */\n\nexport type RunMode = WriteMode\n\nexport type RunBillRunParams = {\n  tenantId: string\n  organizationId: string\n  asOfDate: Date\n  triggeredBy: 'schedule' | 'manual'\n  mode: RunMode\n  scopedAccountIds?: string[]\n  parentRunId?: string | null\n  catchUp?: boolean\n}\n\nexport type RunBillRunResult = {\n  billRun: BillRun\n  outcomes: BillRunOutcome[]\n}\n\ntype RunOutput = RunBillRunResult & {\n  /** Prepaid statement / crossing events to emit AFTER the outer tx commits. */\n  pendingEvents: DomainEvent[]\n}\n\ntype AccountWarnings = {\n  currency_mismatch_items?: string[]\n  unmatched_usage_uoms?: string[]\n}\n\ntype AccountProcessSuccess = {\n  status:\n    | 'success'\n    | 'success_with_warnings'\n    | 'skipped_existing_draft'\n    | 'skipped_existing_statement'\n  warnings: AccountWarnings | Record<string, unknown> | null\n  draftInvoiceId: string | null\n  // SPEC-002: prepaid accounts produce a statement instead of a draft invoice.\n  statementId?: string | null\n  statementEvents?: DomainEvent[]\n  cyclesEmitted: number\n  usageRecordsRated: number\n}\n\ntype AccountProcessFailed = {\n  status: 'failed'\n  errorMessage: string\n}\n\ntype AccountProcessResult = AccountProcessSuccess | AccountProcessFailed\n\nconst SCHEDULED_CYCLE_LIMIT = 1\nconst CATCH_UP_HARD_CAP = 60 // safety net so a misconfigured account can't loop forever\n\nexport async function runBillRun(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunBillRunResult> {\n  const output = await withTenantLock(\n    em,\n    { tenantId: params.tenantId, lockName: 'billing-run' },\n    async (tem) => executeRunWithinLock(tem, container, params),\n  )\n  // Emit prepaid statement / crossing events ONLY after the outer transaction\n  // (held by withTenantLock) has committed \u2014 emitting inside the lock would let\n  // a consumer observe an uncommitted statement or a phantom event on rollback.\n  for (const ev of output.pendingEvents) {\n    await emitBillingEvent(ev.id as BillingEventId, ev.payload, { persistent: true })\n  }\n  return { billRun: output.billRun, outcomes: output.outcomes }\n}\n\nasync function executeRunWithinLock(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: RunBillRunParams,\n): Promise<RunOutput> {\n  const now = new Date()\n  const billRun = em.create(BillRun, {\n    organizationId: params.organizationId,\n    tenantId: params.tenantId,\n    triggeredBy: params.triggeredBy,\n    parentRunId: params.parentRunId ?? null,\n    dryRun: params.mode === 'dry',\n    testMode: params.mode === 'test',\n    catchUp: Boolean(params.catchUp),\n    scopedAccountIds: params.scopedAccountIds ?? null,\n    asOfDate: params.asOfDate,\n    startedAt: now,\n    status: 'running',\n    summary: null,\n    isActive: true,\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(billRun)\n  await em.flush()\n\n  const accounts = await selectTargetAccounts(em, params)\n  const outcomes: BillRunOutcome[] = []\n  const pendingEvents: DomainEvent[] = []\n  let totalUsageRecordsRated = 0\n\n  for (const account of accounts) {\n    const processResult = await processAccountSafely(em, container, billRun, account, params)\n    if (processResult.status !== 'failed') {\n      totalUsageRecordsRated += processResult.usageRecordsRated\n    }\n    const outcome = em.create(BillRunOutcome, {\n      organizationId: params.organizationId,\n      tenantId: params.tenantId,\n      billRunId: billRun.id,\n      billAccountId: account.id,\n      status: processResult.status,\n      errorMessage: processResult.status === 'failed' ? processResult.errorMessage : null,\n      warnings:\n        processResult.status === 'failed'\n          ? null\n          : (processResult.warnings as Record<string, unknown> | null),\n      draftInvoiceId: processResult.status === 'failed' ? null : processResult.draftInvoiceId,\n      statementId: processResult.status === 'failed' ? null : (processResult.statementId ?? null),\n      isActive: true,\n      createdAt: new Date(),\n      updatedAt: new Date(),\n    })\n    em.persist(outcome)\n    await em.flush()\n    outcomes.push(outcome)\n\n    // Collect statement / crossing events \u2014 runBillRun emits them AFTER the\n    // outer tx commits (see runBillRun), never from inside the lock.\n    if (processResult.status !== 'failed' && processResult.statementEvents) {\n      pendingEvents.push(...processResult.statementEvents)\n    }\n  }\n\n  billRun.status = computeFinalRunStatus(outcomes)\n  billRun.finishedAt = new Date()\n  billRun.updatedAt = billRun.finishedAt\n  billRun.summary = buildRunSummary(outcomes, accounts.length, totalUsageRecordsRated)\n  await em.flush()\n\n  return { billRun, outcomes, pendingEvents }\n}\n\nasync function selectTargetAccounts(\n  em: EntityManager,\n  params: RunBillRunParams,\n): Promise<BillingAccount[]> {\n  const where: Record<string, unknown> = {\n    tenantId: params.tenantId,\n    organizationId: params.organizationId,\n    deletedAt: null,\n    nextBillDate: { $lte: params.asOfDate },\n  }\n  if (params.scopedAccountIds && params.scopedAccountIds.length > 0) {\n    where.id = { $in: params.scopedAccountIds }\n  }\n  return em.find(BillingAccount, where as never)\n}\n\nasync function processAccountSafely(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  try {\n    return await em.transactional(async (subEm) => {\n      return processAccount(subEm, container, billRun, account, params)\n    })\n  } catch (err) {\n    return {\n      status: 'failed',\n      errorMessage: err instanceof Error ? err.message : String(err),\n    }\n  }\n}\n\nasync function processAccount(\n  em: EntityManager,\n  container: AwilixContainer,\n  billRun: BillRun,\n  account: BillingAccount,\n  params: RunBillRunParams,\n): Promise<AccountProcessResult> {\n  // SPEC-002: a prepaid account never gets a payable draft invoice. It still\n  // runs in the Bill Run, but charges recurring / one_time items to the\n  // balance and produces a non-fiscal consumption statement.\n  if (account.billingMode === 'prepaid') {\n    const result = await processPrepaidAccount(em, account, billRun, {\n      asOfDate: params.asOfDate,\n      mode: params.mode,\n      triggeredBy: params.triggeredBy,\n      catchUp: params.catchUp,\n    })\n    if (result.status === 'failed') {\n      return { status: 'failed', errorMessage: result.errorMessage }\n    }\n    return {\n      status: result.status,\n      warnings: result.warnings,\n      draftInvoiceId: null,\n      statementId: result.statementId,\n      statementEvents: result.statementEvents,\n      cyclesEmitted: result.cyclesEmitted,\n      usageRecordsRated: 0,\n    }\n  }\n\n  const maxCycles =\n    params.triggeredBy === 'schedule' || !params.catchUp\n      ? SCHEDULED_CYCLE_LIMIT\n      : CATCH_UP_HARD_CAP\n\n  let cyclesEmitted = 0\n  let lastDraftInvoiceId: string | null = null\n  let totalUsageRatedThisAccount = 0\n  const aggregatedWarnings: AccountWarnings = {}\n\n  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {\n    const period = deriveBillPeriod(account.nextBillDate, account.billCycle as BillCycle)\n\n    // Open-draft anti-duplicate \u2014 only applies when we'd actually persist.\n    if (params.mode !== 'dry') {\n      const existing = await findExistingDraftForPeriod(em, account, period)\n      if (existing) {\n        return {\n          status: 'skipped_existing_draft',\n          warnings: null,\n          draftInvoiceId: existing,\n          cyclesEmitted,\n          usageRecordsRated: totalUsageRatedThisAccount,\n        }\n      }\n    }\n\n    const items = await em.find(BillingItem, {\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      billAccountId: account.id,\n      deletedAt: null,\n    } as never)\n\n    const usageItems = (items as BillingItem[]).filter((it) => it.type === 'usage')\n\n    // Non-usage path: one_time + recurring filtered by the selector.\n    const { included } = selectItemsForPeriod(items as SelectableItem[], period)\n    const billableItems = included as unknown as BillingItem[]\n\n    const currencyMismatchIds = billableItems\n      .filter((it) => it.currencyMismatch)\n      .map((it) => it.id)\n    if (currencyMismatchIds.length > 0) {\n      aggregatedWarnings.currency_mismatch_items = [\n        ...(aggregatedWarnings.currency_mismatch_items ?? []),\n        ...currencyMismatchIds,\n      ]\n    }\n    const itemLines = buildInvoiceLinesFromItems(billableItems)\n\n    // Usage path: aggregate matching usage records per uom_code, rate,\n    // emit one line per matched usage item, warn about unmatched UoMs.\n    const usageResult = await processUsageForAccount(em, account, period, usageItems)\n    if (usageResult.unmatchedUoms.length > 0) {\n      aggregatedWarnings.unmatched_usage_uoms = [\n        ...(aggregatedWarnings.unmatched_usage_uoms ?? []),\n        ...usageResult.unmatchedUoms,\n      ]\n    }\n\n    const allLines: InvoiceLineDescriptor[] = [...itemLines, ...usageResult.lines]\n    if (allLines.length === 0) {\n      // Nothing to bill this cycle \u2014 still advance so the account moves\n      // forward in real mode. In test / dry, no advance, so we'd loop\n      // forever; break out.\n      if (params.mode !== 'real') break\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = new Date()\n      cyclesEmitted += 1\n      continue\n    }\n\n    const written = await writeDraftInvoice(em, container, {\n      mode: params.mode,\n      account,\n      period,\n      billRunId: billRun.id,\n      lines: allLines,\n    })\n    lastDraftInvoiceId = written.invoiceId\n\n    if (params.mode === 'real') {\n      const now = new Date()\n      for (const item of billableItems) {\n        item.billedToDate = period.periodEnd\n        item.updatedAt = now\n      }\n      // Mark consumed usage records \u2014 single bulk update so we don't\n      // round-trip per record on accounts with thousands of usage rows.\n      if (usageResult.matchedUoms.length > 0) {\n        // Predicate-based bulk update: marks every still-unrated record\n        // for the matched uoms in the account's period with a single\n        // SQL UPDATE \u2014 no id list ever leaves Postgres. Stays\n        // memory-bounded even for telco accounts with millions of\n        // usage records per cycle (spec Performance Considerations\n        // \"Shape B\").\n        await em.nativeUpdate(\n          BillingAccountUsage,\n          {\n            tenantId: account.tenantId,\n            organizationId: account.organizationId,\n            billAccountId: account.id,\n            uomCode: { $in: usageResult.matchedUoms },\n            ratedInBillRunId: null,\n            periodEnd: { $lte: period.periodEnd },\n            deletedAt: null,\n          } as never,\n          { ratedInBillRunId: billRun.id, updatedAt: now } as never,\n        )\n      }\n      totalUsageRatedThisAccount += usageResult.ratedCount\n      account.nextBillDate = advanceNextBillDate(\n        account.nextBillDate,\n        account.billCycle as BillCycle,\n      )\n      account.lastBillDate = period.periodEnd\n      account.updatedAt = now\n      await em.flush()\n    } else {\n      // Test / dry: do not advance state. One iteration only.\n      break\n    }\n\n    cyclesEmitted += 1\n  }\n\n  const hasCurrencyWarnings =\n    (aggregatedWarnings.currency_mismatch_items ?? []).length > 0\n  const hasUnmatchedUsage =\n    (aggregatedWarnings.unmatched_usage_uoms ?? []).length > 0\n  const hasWarnings = hasCurrencyWarnings || hasUnmatchedUsage\n  return {\n    status: hasWarnings ? 'success_with_warnings' : 'success',\n    warnings: hasWarnings ? aggregatedWarnings : null,\n    draftInvoiceId: lastDraftInvoiceId,\n    cyclesEmitted,\n    usageRecordsRated: totalUsageRatedThisAccount,\n  }\n}\n\nasync function findExistingDraftForPeriod(\n  em: EntityManager,\n  account: BillingAccount,\n  period: { periodStart: Date; periodEnd: Date },\n): Promise<string | null> {\n  const periodStartISO = period.periodStart.toISOString().slice(0, 10)\n  const periodEndISO = period.periodEnd.toISOString().slice(0, 10)\n  const rows = (await em.execute(\n    `SELECT id FROM sales_invoices\n     WHERE tenant_id = ?\n       AND organization_id = ?\n       AND deleted_at IS NULL\n       AND status = 'draft'\n       AND metadata->>'bill_account_id' = ?\n       AND metadata->>'bill_period_start' = ?\n       AND metadata->>'bill_period_end' = ?\n     LIMIT 1`,\n    [account.tenantId, account.organizationId, account.id, periodStartISO, periodEndISO],\n  )) as unknown as Array<{ id: string }> | undefined\n  if (!rows || rows.length === 0) return null\n  return rows[0].id ?? null\n}\n\nfunction computeFinalRunStatus(\n  outcomes: readonly BillRunOutcome[],\n): BillRun['status'] {\n  if (outcomes.length === 0) return 'completed'\n  const anyFailed = outcomes.some((o) => o.status === 'failed')\n  const anySuccess = outcomes.some(\n    (o) => o.status === 'success' || o.status === 'success_with_warnings',\n  )\n  if (anyFailed && anySuccess) return 'partial_failure'\n  if (anyFailed) return 'partial_failure'\n  return 'completed'\n}\n\nfunction buildRunSummary(\n  outcomes: readonly BillRunOutcome[],\n  totalAccounts: number,\n  usageRecordsRated: number,\n): Record<string, unknown> {\n  return {\n    accounts_processed: totalAccounts,\n    drafts_created: outcomes.filter(\n      (o) => o.draftInvoiceId !== null && o.status !== 'skipped_existing_draft',\n    ).length,\n    drafts_skipped_existing: outcomes.filter((o) => o.status === 'skipped_existing_draft')\n      .length,\n    // SPEC-002 prepaid period close.\n    statements_created: outcomes.filter(\n      (o) => o.statementId !== null && o.status !== 'skipped_existing_statement',\n    ).length,\n    statements_skipped_existing: outcomes.filter(\n      (o) => o.status === 'skipped_existing_statement',\n    ).length,\n    accounts_failed: outcomes.filter((o) => o.status === 'failed').length,\n    accounts_with_warnings: outcomes.filter((o) => o.status === 'success_with_warnings')\n      .length,\n    usage_records_rated: usageRecordsRated,\n  }\n}\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,qBAAqB,kBAAkB,kBAAkB;AAClE;AAAA,EACE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP,SAAS,sBAAsB;AAC/B,SAAS,8BAA8B;AACvC,SAAS,6BAA6B;AAEtC,SAAS,wBAA6C;AAsFtD,MAAM,wBAAwB;AAC9B,MAAM,oBAAoB;AAE1B,eAAsB,WACpB,IACA,WACA,QAC2B;AAC3B,QAAM,SAAS,MAAM;AAAA,IACnB;AAAA,IACA,EAAE,UAAU,OAAO,UAAU,UAAU,cAAc;AAAA,IACrD,OAAO,QAAQ,qBAAqB,KAAK,WAAW,MAAM;AAAA,EAC5D;AAIA,aAAW,MAAM,OAAO,eAAe;AACrC,UAAM,iBAAiB,GAAG,IAAsB,GAAG,SAAS,EAAE,YAAY,KAAK,CAAC;AAAA,EAClF;AACA,SAAO,EAAE,SAAS,OAAO,SAAS,UAAU,OAAO,SAAS;AAC9D;AAEA,eAAe,qBACb,IACA,WACA,QACoB;AACpB,QAAM,MAAM,oBAAI,KAAK;AACrB,QAAM,UAAU,GAAG,OAAO,SAAS;AAAA,IACjC,gBAAgB,OAAO;AAAA,IACvB,UAAU,OAAO;AAAA,IACjB,aAAa,OAAO;AAAA,IACpB,aAAa,OAAO,eAAe;AAAA,IACnC,QAAQ,OAAO,SAAS;AAAA,IACxB,UAAU,OAAO,SAAS;AAAA,IAC1B,SAAS,QAAQ,OAAO,OAAO;AAAA,IAC/B,kBAAkB,OAAO,oBAAoB;AAAA,IAC7C,UAAU,OAAO;AAAA,IACjB,WAAW;AAAA,IACX,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,IACV,WAAW;AAAA,IACX,WAAW;AAAA,EACb,CAAC;AACD,KAAG,QAAQ,OAAO;AAClB,QAAM,GAAG,MAAM;AAEf,QAAM,WAAW,MAAM,qBAAqB,IAAI,MAAM;AACtD,QAAM,WAA6B,CAAC;AACpC,QAAM,gBAA+B,CAAC;AACtC,MAAI,yBAAyB;AAE7B,aAAW,WAAW,UAAU;AAC9B,UAAM,gBAAgB,MAAM,qBAAqB,IAAI,WAAW,SAAS,SAAS,MAAM;AACxF,QAAI,cAAc,WAAW,UAAU;AACrC,gCAA0B,cAAc;AAAA,IAC1C;AACA,UAAM,UAAU,GAAG,OAAO,gBAAgB;AAAA,MACxC,gBAAgB,OAAO;AAAA,MACvB,UAAU,OAAO;AAAA,MACjB,WAAW,QAAQ;AAAA,MACnB,eAAe,QAAQ;AAAA,MACvB,QAAQ,cAAc;AAAA,MACtB,cAAc,cAAc,WAAW,WAAW,cAAc,eAAe;AAAA,MAC/E,UACE,cAAc,WAAW,WACrB,OACC,cAAc;AAAA,MACrB,gBAAgB,cAAc,WAAW,WAAW,OAAO,cAAc;AAAA,MACzE,aAAa,cAAc,WAAW,WAAW,OAAQ,cAAc,eAAe;AAAA,MACtF,UAAU;AAAA,MACV,WAAW,oBAAI,KAAK;AAAA,MACpB,WAAW,oBAAI,KAAK;AAAA,IACtB,CAAC;AACD,OAAG,QAAQ,OAAO;AAClB,UAAM,GAAG,MAAM;AACf,aAAS,KAAK,OAAO;AAIrB,QAAI,cAAc,WAAW,YAAY,cAAc,iBAAiB;AACtE,oBAAc,KAAK,GAAG,cAAc,eAAe;AAAA,IACrD;AAAA,EACF;AAEA,UAAQ,SAAS,sBAAsB,QAAQ;AAC/C,UAAQ,aAAa,oBAAI,KAAK;AAC9B,UAAQ,YAAY,QAAQ;AAC5B,UAAQ,UAAU,gBAAgB,UAAU,SAAS,QAAQ,sBAAsB;AACnF,QAAM,GAAG,MAAM;AAEf,SAAO,EAAE,SAAS,UAAU,cAAc;AAC5C;AAEA,eAAe,qBACb,IACA,QAC2B;AAC3B,QAAM,QAAiC;AAAA,IACrC,UAAU,OAAO;AAAA,IACjB,gBAAgB,OAAO;AAAA,IACvB,WAAW;AAAA,IACX,cAAc,EAAE,MAAM,OAAO,SAAS;AAAA,EACxC;AACA,MAAI,OAAO,oBAAoB,OAAO,iBAAiB,SAAS,GAAG;AACjE,UAAM,KAAK,EAAE,KAAK,OAAO,iBAAiB;AAAA,EAC5C;AACA,SAAO,GAAG,KAAK,gBAAgB,KAAc;AAC/C;AAEA,eAAe,qBACb,IACA,WACA,SACA,SACA,QAC+B;AAC/B,MAAI;AACF,WAAO,MAAM,GAAG,cAAc,OAAO,UAAU;AAC7C,aAAO,eAAe,OAAO,WAAW,SAAS,SAAS,MAAM;AAAA,IAClE,CAAC;AAAA,EACH,SAAS,KAAK;AACZ,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IAC/D;AAAA,EACF;AACF;AAEA,eAAe,eACb,IACA,WACA,SACA,SACA,QAC+B;AAI/B,MAAI,QAAQ,gBAAgB,WAAW;AACrC,UAAM,SAAS,MAAM,sBAAsB,IAAI,SAAS,SAAS;AAAA,MAC/D,UAAU,OAAO;AAAA,MACjB,MAAM,OAAO;AAAA,MACb,aAAa,OAAO;AAAA,MACpB,SAAS,OAAO;AAAA,IAClB,CAAC;AACD,QAAI,OAAO,WAAW,UAAU;AAC9B,aAAO,EAAE,QAAQ,UAAU,cAAc,OAAO,aAAa;AAAA,IAC/D;AACA,WAAO;AAAA,MACL,QAAQ,OAAO;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,gBAAgB;AAAA,MAChB,aAAa,OAAO;AAAA,MACpB,iBAAiB,OAAO;AAAA,MACxB,eAAe,OAAO;AAAA,MACtB,mBAAmB;AAAA,IACrB;AAAA,EACF;AAEA,QAAM,YACJ,OAAO,gBAAgB,cAAc,CAAC,OAAO,UACzC,wBACA;AAEN,MAAI,gBAAgB;AACpB,MAAI,qBAAoC;AACxC,MAAI,6BAA6B;AACjC,QAAM,qBAAsC,CAAC;AAE7C,SAAO,gBAAgB,aAAa,WAAW,QAAQ,cAAc,OAAO,QAAQ,GAAG;AACrF,UAAM,SAAS,iBAAiB,QAAQ,cAAc,QAAQ,SAAsB;AAGpF,QAAI,OAAO,SAAS,OAAO;AACzB,YAAM,WAAW,MAAM,2BAA2B,IAAI,SAAS,MAAM;AACrE,UAAI,UAAU;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR,UAAU;AAAA,UACV,gBAAgB;AAAA,UAChB;AAAA,UACA,mBAAmB;AAAA,QACrB;AAAA,MACF;AAAA,IACF;AAEA,UAAM,QAAQ,MAAM,GAAG,KAAK,aAAa;AAAA,MACvC,UAAU,QAAQ;AAAA,MAClB,gBAAgB,QAAQ;AAAA,MACxB,eAAe,QAAQ;AAAA,MACvB,WAAW;AAAA,IACb,CAAU;AAEV,UAAM,aAAc,MAAwB,OAAO,CAAC,OAAO,GAAG,SAAS,OAAO;AAG9E,UAAM,EAAE,SAAS,IAAI,qBAAqB,OAA2B,MAAM;AAC3E,UAAM,gBAAgB;AAEtB,UAAM,sBAAsB,cACzB,OAAO,CAAC,OAAO,GAAG,gBAAgB,EAClC,IAAI,CAAC,OAAO,GAAG,EAAE;AACpB,QAAI,oBAAoB,SAAS,GAAG;AAClC,yBAAmB,0BAA0B;AAAA,QAC3C,GAAI,mBAAmB,2BAA2B,CAAC;AAAA,QACnD,GAAG;AAAA,MACL;AAAA,IACF;AACA,UAAM,YAAY,2BAA2B,aAAa;AAI1D,UAAM,cAAc,MAAM,uBAAuB,IAAI,SAAS,QAAQ,UAAU;AAChF,QAAI,YAAY,cAAc,SAAS,GAAG;AACxC,yBAAmB,uBAAuB;AAAA,QACxC,GAAI,mBAAmB,wBAAwB,CAAC;AAAA,QAChD,GAAG,YAAY;AAAA,MACjB;AAAA,IACF;AAEA,UAAM,WAAoC,CAAC,GAAG,WAAW,GAAG,YAAY,KAAK;AAC7E,QAAI,SAAS,WAAW,GAAG;AAIzB,UAAI,OAAO,SAAS,OAAQ;AAC5B,cAAQ,eAAe;AAAA,QACrB,QAAQ;AAAA,QACR,QAAQ;AAAA,MACV;AACA,cAAQ,eAAe,OAAO;AAC9B,cAAQ,YAAY,oBAAI,KAAK;AAC7B,uBAAiB;AACjB;AAAA,IACF;AAEA,UAAM,UAAU,MAAM,kBAAkB,IAAI,WAAW;AAAA,MACrD,MAAM,OAAO;AAAA,MACb;AAAA,MACA;AAAA,MACA,WAAW,QAAQ;AAAA,MACnB,OAAO;AAAA,IACT,CAAC;AACD,yBAAqB,QAAQ;AAE7B,QAAI,OAAO,SAAS,QAAQ;AAC1B,YAAM,MAAM,oBAAI,KAAK;AACrB,iBAAW,QAAQ,eAAe;AAChC,aAAK,eAAe,OAAO;AAC3B,aAAK,YAAY;AAAA,MACnB;AAGA,UAAI,YAAY,YAAY,SAAS,GAAG;AAOtC,cAAM,GAAG;AAAA,UACP;AAAA,UACA;AAAA,YACE,UAAU,QAAQ;AAAA,YAClB,gBAAgB,QAAQ;AAAA,YACxB,eAAe,QAAQ;AAAA,YACvB,SAAS,EAAE,KAAK,YAAY,YAAY;AAAA,YACxC,kBAAkB;AAAA,YAClB,WAAW,EAAE,MAAM,OAAO,UAAU;AAAA,YACpC,WAAW;AAAA,UACb;AAAA,UACA,EAAE,kBAAkB,QAAQ,IAAI,WAAW,IAAI;AAAA,QACjD;AAAA,MACF;AACA,oCAA8B,YAAY;AAC1C,cAAQ,eAAe;AAAA,QACrB,QAAQ;AAAA,QACR,QAAQ;AAAA,MACV;AACA,cAAQ,eAAe,OAAO;AAC9B,cAAQ,YAAY;AACpB,YAAM,GAAG,MAAM;AAAA,IACjB,OAAO;AAEL;AAAA,IACF;AAEA,qBAAiB;AAAA,EACnB;AAEA,QAAM,uBACH,mBAAmB,2BAA2B,CAAC,GAAG,SAAS;AAC9D,QAAM,qBACH,mBAAmB,wBAAwB,CAAC,GAAG,SAAS;AAC3D,QAAM,cAAc,uBAAuB;AAC3C,SAAO;AAAA,IACL,QAAQ,cAAc,0BAA0B;AAAA,IAChD,UAAU,cAAc,qBAAqB;AAAA,IAC7C,gBAAgB;AAAA,IAChB;AAAA,IACA,mBAAmB;AAAA,EACrB;AACF;AAEA,eAAe,2BACb,IACA,SACA,QACwB;AACxB,QAAM,iBAAiB,OAAO,YAAY,YAAY,EAAE,MAAM,GAAG,EAAE;AACnE,QAAM,eAAe,OAAO,UAAU,YAAY,EAAE,MAAM,GAAG,EAAE;AAC/D,QAAM,OAAQ,MAAM,GAAG;AAAA,IACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,CAAC,QAAQ,UAAU,QAAQ,gBAAgB,QAAQ,IAAI,gBAAgB,YAAY;AAAA,EACrF;AACA,MAAI,CAAC,QAAQ,KAAK,WAAW,EAAG,QAAO;AACvC,SAAO,KAAK,CAAC,EAAE,MAAM;AACvB;AAEA,SAAS,sBACP,UACmB;AACnB,MAAI,SAAS,WAAW,EAAG,QAAO;AAClC,QAAM,YAAY,SAAS,KAAK,CAAC,MAAM,EAAE,WAAW,QAAQ;AAC5D,QAAM,aAAa,SAAS;AAAA,IAC1B,CAAC,MAAM,EAAE,WAAW,aAAa,EAAE,WAAW;AAAA,EAChD;AACA,MAAI,aAAa,WAAY,QAAO;AACpC,MAAI,UAAW,QAAO;AACtB,SAAO;AACT;AAEA,SAAS,gBACP,UACA,eACA,mBACyB;AACzB,SAAO;AAAA,IACL,oBAAoB;AAAA,IACpB,gBAAgB,SAAS;AAAA,MACvB,CAAC,MAAM,EAAE,mBAAmB,QAAQ,EAAE,WAAW;AAAA,IACnD,EAAE;AAAA,IACF,yBAAyB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,wBAAwB,EAClF;AAAA;AAAA,IAEH,oBAAoB,SAAS;AAAA,MAC3B,CAAC,MAAM,EAAE,gBAAgB,QAAQ,EAAE,WAAW;AAAA,IAChD,EAAE;AAAA,IACF,6BAA6B,SAAS;AAAA,MACpC,CAAC,MAAM,EAAE,WAAW;AAAA,IACtB,EAAE;AAAA,IACF,iBAAiB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,QAAQ,EAAE;AAAA,IAC/D,wBAAwB,SAAS,OAAO,CAAC,MAAM,EAAE,WAAW,uBAAuB,EAChF;AAAA,IACH,qBAAqB;AAAA,EACvB;AACF;",
   "names": []
 }

package/dist/modules/billing/lib/creditStatus.js

@@ -0,0 +1,65 @@
+import { compareMoney, fromUnits, subMoney, toUnits } from "./money.js";
+function prepaidCreditUsed(balance) {
+  if (compareMoney(balance, 0) >= 0) return "0.0000";
+  return fromUnits(-toUnits(balance));
+}
+function computeCreditUsed(mode, opts) {
+  if (mode === "prepaid") {
+    return prepaidCreditUsed(opts.balance ?? "0");
+  }
+  return fromUnits(toUnits(opts.outstanding ?? "0"));
+}
+function computeAvailableCredit(creditLimit, creditUsed) {
+  return subMoney(creditLimit, creditUsed);
+}
+function computeCreditStatus(availableCredit, nearLimitBuffer, creditUsed) {
+  const hasDraw = creditUsed === void 0 ? true : compareMoney(creditUsed, 0) > 0;
+  if (compareMoney(availableCredit, 0) <= 0) {
+    return hasDraw ? "over_limit" : "within_limit";
+  }
+  if (compareMoney(availableCredit, nearLimitBuffer) <= 0) return "near_limit";
+  return "within_limit";
+}
+function resolveNearLimitBuffer(configDefault) {
+  if (configDefault !== null && configDefault !== void 0) return String(configDefault);
+  return "0";
+}
+function computeCreditSnapshot(params) {
+  const creditLimit = fromUnits(toUnits(params.creditLimit));
+  const creditUsed = computeCreditUsed(params.mode, {
+    balance: params.balance,
+    outstanding: params.outstanding
+  });
+  const availableCredit = computeAvailableCredit(creditLimit, creditUsed);
+  return {
+    mode: params.mode,
+    creditLimit,
+    creditUsed,
+    availableCredit,
+    creditStatus: computeCreditStatus(availableCredit, params.nearLimitBuffer, creditUsed)
+  };
+}
+function detectCreditCrossing(params) {
+  const limitUnits = toUnits(params.creditLimit);
+  if (limitUnits <= 0) {
+    return { overLimitCrossedUp: false, nearLimitCrossedUp: false };
+  }
+  const usedBefore = toUnits(params.usedBefore);
+  const usedAfter = toUnits(params.usedAfter);
+  const bufferUnits = toUnits(params.nearLimitBuffer);
+  const overLimitCrossedUp = usedBefore < limitUnits && usedAfter >= limitUnits;
+  const availBefore = limitUnits - usedBefore;
+  const availAfter = limitUnits - usedAfter;
+  const nearLimitCrossedUp = bufferUnits > 0 && availBefore > bufferUnits && availAfter <= bufferUnits && availAfter > 0;
+  return { overLimitCrossedUp, nearLimitCrossedUp };
+}
+export {
+  computeAvailableCredit,
+  computeCreditSnapshot,
+  computeCreditStatus,
+  computeCreditUsed,
+  detectCreditCrossing,
+  prepaidCreditUsed,
+  resolveNearLimitBuffer
+};
+//# sourceMappingURL=creditStatus.js.map

package/dist/modules/billing/lib/creditStatus.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/creditStatus.ts"],
+  "sourcesContent": ["import type { BillingMode, CreditStatus } from '../data/validators'\nimport { compareMoney, fromUnits, subMoney, toUnits } from './money'\n\n/**\n * Credit-line status (both modes, SPEC-002). Billing **computes and reports**\n * where an account stands against its `credit_limit` \u2014 it NEVER blocks\n * (assumption #11). A consumer (CPQ order conversion, a dunning job, an\n * operator) decides what to do with an over-limit signal.\n *\n * `credit_used` per mode:\n *   - prepaid:  max(0, \u2212balance) \u2014 the portion of the balance gone negative\n *     (drawing on the credit line).\n *   - postpaid: \u03A3 outstanding (posted, not-yet-paid) invoice `outstanding`\n *     amounts from core/sales.\n *\n * `available_credit = credit_limit \u2212 credit_used` (unified across both modes;\n * for prepaid this equals `balance + credit_limit` when balance < 0, else\n * `credit_limit`).\n */\n\n/** Prepaid credit drawn = max(0, \u2212balance). */\nexport function prepaidCreditUsed(balance: string | number): string {\n  if (compareMoney(balance, 0) >= 0) return '0.0000'\n  return fromUnits(-toUnits(balance))\n}\n\nexport function computeCreditUsed(\n  mode: BillingMode,\n  opts: { balance?: string | number | null; outstanding?: string | number | null },\n): string {\n  if (mode === 'prepaid') {\n    return prepaidCreditUsed(opts.balance ?? '0')\n  }\n  // postpaid\n  return fromUnits(toUnits(opts.outstanding ?? '0'))\n}\n\nexport function computeAvailableCredit(\n  creditLimit: string | number,\n  creditUsed: string | number,\n): string {\n  return subMoney(creditLimit, creditUsed)\n}\n\n/**\n * | status        | condition                                  |\n * |---------------|--------------------------------------------|\n * | within_limit  | available_credit > near_limit_buffer       |\n * | near_limit    | 0 < available_credit <= near_limit_buffer  |\n * | over_limit    | available_credit <= 0 (and credit is drawn)|\n *\n * `creditUsed` disambiguates the default \"no credit line\" case: with\n * `credit_limit = 0` and nothing drawn (`credit_used = 0`) the available\n * credit is exactly 0 \u2014 that is NOT over-limit (the account simply has no\n * credit line), so it reports `within_limit`. Once any credit is actually\n * drawn (prepaid balance negative, or postpaid outstanding > 0) the formula\n * applies. When `creditUsed` is omitted, a draw is assumed (pure spec\n * formula) \u2014 callers that have the figure should pass it.\n */\nexport function computeCreditStatus(\n  availableCredit: string | number,\n  nearLimitBuffer: string | number,\n  creditUsed?: string | number,\n): CreditStatus {\n  const hasDraw = creditUsed === undefined ? true : compareMoney(creditUsed, 0) > 0\n  if (compareMoney(availableCredit, 0) <= 0) {\n    return hasDraw ? 'over_limit' : 'within_limit'\n  }\n  if (compareMoney(availableCredit, nearLimitBuffer) <= 0) return 'near_limit'\n  return 'within_limit'\n}\n\nexport function resolveNearLimitBuffer(\n  configDefault: string | number | null | undefined,\n): string {\n  if (configDefault !== null && configDefault !== undefined) return String(configDefault)\n  return '0'\n}\n\nexport type CreditSnapshot = {\n  mode: BillingMode\n  creditLimit: string\n  creditUsed: string\n  availableCredit: string\n  creditStatus: CreditStatus\n}\n\n/** Assemble the full credit snapshot reported on consume responses + the API. */\nexport function computeCreditSnapshot(params: {\n  mode: BillingMode\n  creditLimit: string | number\n  nearLimitBuffer: string | number\n  balance?: string | number | null\n  outstanding?: string | number | null\n}): CreditSnapshot {\n  const creditLimit = fromUnits(toUnits(params.creditLimit))\n  const creditUsed = computeCreditUsed(params.mode, {\n    balance: params.balance,\n    outstanding: params.outstanding,\n  })\n  const availableCredit = computeAvailableCredit(creditLimit, creditUsed)\n  return {\n    mode: params.mode,\n    creditLimit,\n    creditUsed,\n    availableCredit,\n    creditStatus: computeCreditStatus(availableCredit, params.nearLimitBuffer, creditUsed),\n  }\n}\n\nexport type CreditCrossing = {\n  /** credit_used crossed upward past credit_limit (available \u2264 0). */\n  overLimitCrossedUp: boolean\n  /** available_credit crossed downward into (0, buffer] (optional event). */\n  nearLimitCrossedUp: boolean\n}\n\n/**\n * Detect upward crossings of `credit_used` (i.e. downward crossings of\n * `available_credit`) for the `billing.credit.over_limit` /\n * `billing.credit.near_limit` events. `over_limit` fires once when usage /\n * recurring pushes credit_used from below the limit to at/above it.\n *\n * `credit_limit == 0` (no credit) means available is never > 0 once any\n * credit is \"used\"; to avoid firing on every prepaid debit while at 0 balance\n * with no credit line, the crossing requires a real limit (> 0).\n */\nexport function detectCreditCrossing(params: {\n  creditLimit: string | number\n  nearLimitBuffer: string | number\n  usedBefore: string | number\n  usedAfter: string | number\n}): CreditCrossing {\n  const limitUnits = toUnits(params.creditLimit)\n  if (limitUnits <= 0) {\n    return { overLimitCrossedUp: false, nearLimitCrossedUp: false }\n  }\n  const usedBefore = toUnits(params.usedBefore)\n  const usedAfter = toUnits(params.usedAfter)\n  const bufferUnits = toUnits(params.nearLimitBuffer)\n\n  const overLimitCrossedUp = usedBefore < limitUnits && usedAfter >= limitUnits\n\n  const availBefore = limitUnits - usedBefore\n  const availAfter = limitUnits - usedAfter\n  const nearLimitCrossedUp =\n    bufferUnits > 0 &&\n    availBefore > bufferUnits &&\n    availAfter <= bufferUnits &&\n    availAfter > 0\n\n  return { overLimitCrossedUp, nearLimitCrossedUp }\n}\n"],
+  "mappings": "AACA,SAAS,cAAc,WAAW,UAAU,eAAe;AAoBpD,SAAS,kBAAkB,SAAkC;AAClE,MAAI,aAAa,SAAS,CAAC,KAAK,EAAG,QAAO;AAC1C,SAAO,UAAU,CAAC,QAAQ,OAAO,CAAC;AACpC;AAEO,SAAS,kBACd,MACA,MACQ;AACR,MAAI,SAAS,WAAW;AACtB,WAAO,kBAAkB,KAAK,WAAW,GAAG;AAAA,EAC9C;AAEA,SAAO,UAAU,QAAQ,KAAK,eAAe,GAAG,CAAC;AACnD;AAEO,SAAS,uBACd,aACA,YACQ;AACR,SAAO,SAAS,aAAa,UAAU;AACzC;AAiBO,SAAS,oBACd,iBACA,iBACA,YACc;AACd,QAAM,UAAU,eAAe,SAAY,OAAO,aAAa,YAAY,CAAC,IAAI;AAChF,MAAI,aAAa,iBAAiB,CAAC,KAAK,GAAG;AACzC,WAAO,UAAU,eAAe;AAAA,EAClC;AACA,MAAI,aAAa,iBAAiB,eAAe,KAAK,EAAG,QAAO;AAChE,SAAO;AACT;AAEO,SAAS,uBACd,eACQ;AACR,MAAI,kBAAkB,QAAQ,kBAAkB,OAAW,QAAO,OAAO,aAAa;AACtF,SAAO;AACT;AAWO,SAAS,sBAAsB,QAMnB;AACjB,QAAM,cAAc,UAAU,QAAQ,OAAO,WAAW,CAAC;AACzD,QAAM,aAAa,kBAAkB,OAAO,MAAM;AAAA,IAChD,SAAS,OAAO;AAAA,IAChB,aAAa,OAAO;AAAA,EACtB,CAAC;AACD,QAAM,kBAAkB,uBAAuB,aAAa,UAAU;AACtE,SAAO;AAAA,IACL,MAAM,OAAO;AAAA,IACb;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc,oBAAoB,iBAAiB,OAAO,iBAAiB,UAAU;AAAA,EACvF;AACF;AAmBO,SAAS,qBAAqB,QAKlB;AACjB,QAAM,aAAa,QAAQ,OAAO,WAAW;AAC7C,MAAI,cAAc,GAAG;AACnB,WAAO,EAAE,oBAAoB,OAAO,oBAAoB,MAAM;AAAA,EAChE;AACA,QAAM,aAAa,QAAQ,OAAO,UAAU;AAC5C,QAAM,YAAY,QAAQ,OAAO,SAAS;AAC1C,QAAM,cAAc,QAAQ,OAAO,eAAe;AAElD,QAAM,qBAAqB,aAAa,cAAc,aAAa;AAEnE,QAAM,cAAc,aAAa;AACjC,QAAM,aAAa,aAAa;AAChC,QAAM,qBACJ,cAAc,KACd,cAAc,eACd,cAAc,eACd,aAAa;AAEf,SAAO,EAAE,oBAAoB,mBAAmB;AAClD;",
+  "names": []
+}

package/dist/modules/billing/lib/money.js

@@ -0,0 +1,47 @@
+const SCALE = 1e4;
+function toUnits(value) {
+  if (value === null || value === void 0) return 0;
+  const n = typeof value === "number" ? value : Number.parseFloat(value);
+  if (!Number.isFinite(n)) return 0;
+  return Math.round((n + Number.EPSILON * Math.sign(n)) * SCALE);
+}
+function fromUnits(units) {
+  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")}`;
+}
+function addMoney(a, b) {
+  return fromUnits(toUnits(a) + toUnits(b));
+}
+function subMoney(a, b) {
+  return fromUnits(toUnits(a) - toUnits(b));
+}
+function negateMoney(a) {
+  return fromUnits(-toUnits(a));
+}
+function absMoney(a) {
+  return fromUnits(Math.abs(toUnits(a)));
+}
+function compareMoney(a, b) {
+  const ua = toUnits(a);
+  const ub = toUnits(b);
+  if (ua < ub) return -1;
+  if (ua > ub) return 1;
+  return 0;
+}
+function formatMoney(value) {
+  return fromUnits(toUnits(value));
+}
+export {
+  absMoney,
+  addMoney,
+  compareMoney,
+  formatMoney,
+  fromUnits,
+  negateMoney,
+  subMoney,
+  toUnits
+};
+//# sourceMappingURL=money.js.map

package/dist/modules/billing/lib/money.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/money.ts"],
+  "sourcesContent": ["/**\n * Exact decimal arithmetic for the prepaid balance ledger (SPEC-002).\n *\n * All billing money columns are `numeric(18,4)` \u2014 four decimal places. Doing\n * the running-balance / reconciliation math in JS `number` would accumulate\n * binary floating-point error (`0.1 + 0.2 !== 0.3`), and the reconciliation\n * invariant `balance == SUM(amount) == latest.balance_after` would drift.\n *\n * So we work in **integer ten-thousandths** (\"units\"): the smallest\n * representable step of a `numeric(18,4)` column. `12.3400` \u21C4 `123400` units.\n * Addition/subtraction of integers is exact; we only ever format back to a\n * 4dp string at the persistence boundary.\n *\n * `numeric(18,4)` holds values up to ~10^14, i.e. ~10^18 units \u2014 well within\n * JS `Number.MAX_SAFE_INTEGER` (~9.007\u00D710^15) for any realistic balance\n * (max safe ~\u00B1900,000,000,000 currency units). Magnitudes beyond that would\n * already overflow the column itself; we guard the parse defensively.\n */\n\nconst SCALE = 10_000\n\n/** Parse a numeric(18,4) string (or number) into integer ten-thousandths. */\nexport function toUnits(value: string | number | null | undefined): number {\n  if (value === null || value === undefined) return 0\n  const n = typeof value === 'number' ? value : Number.parseFloat(value)\n  if (!Number.isFinite(n)) return 0\n  // Round to the nearest ten-thousandth \u2014 half-up, EPSILON-nudged to survive\n  // representations like 12.33999999998.\n  return Math.round((n + Number.EPSILON * Math.sign(n)) * SCALE)\n}\n\n/** Format integer ten-thousandths back to a numeric(18,4) string. */\nexport function fromUnits(units: number): string {\n  const sign = units < 0 ? '-' : ''\n  const abs = Math.abs(Math.trunc(units))\n  const whole = Math.trunc(abs / SCALE)\n  const frac = abs % SCALE\n  return `${sign}${whole}.${frac.toString().padStart(4, '0')}`\n}\n\n/** Add two numeric(18,4) values exactly, returning a 4dp string. */\nexport function addMoney(a: string | number, b: string | number): string {\n  return fromUnits(toUnits(a) + toUnits(b))\n}\n\n/** Subtract `b` from `a` exactly, returning a 4dp string. */\nexport function subMoney(a: string | number, b: string | number): string {\n  return fromUnits(toUnits(a) - toUnits(b))\n}\n\n/** Negate a numeric(18,4) value, returning a 4dp string. */\nexport function negateMoney(a: string | number): string {\n  return fromUnits(-toUnits(a))\n}\n\n/** Absolute value of a numeric(18,4), returning a 4dp string. */\nexport function absMoney(a: string | number): string {\n  return fromUnits(Math.abs(toUnits(a)))\n}\n\n/** Compare two numeric(18,4) values. Returns -1 / 0 / 1. */\nexport function compareMoney(a: string | number, b: string | number): -1 | 0 | 1 {\n  const ua = toUnits(a)\n  const ub = toUnits(b)\n  if (ua < ub) return -1\n  if (ua > ub) return 1\n  return 0\n}\n\n/** Normalize any numeric(18,4) input to a canonical 4dp string. */\nexport function formatMoney(value: string | number): string {\n  return fromUnits(toUnits(value))\n}\n"],
+  "mappings": "AAmBA,MAAM,QAAQ;AAGP,SAAS,QAAQ,OAAmD;AACzE,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,QAAM,IAAI,OAAO,UAAU,WAAW,QAAQ,OAAO,WAAW,KAAK;AACrE,MAAI,CAAC,OAAO,SAAS,CAAC,EAAG,QAAO;AAGhC,SAAO,KAAK,OAAO,IAAI,OAAO,UAAU,KAAK,KAAK,CAAC,KAAK,KAAK;AAC/D;AAGO,SAAS,UAAU,OAAuB;AAC/C,QAAM,OAAO,QAAQ,IAAI,MAAM;AAC/B,QAAM,MAAM,KAAK,IAAI,KAAK,MAAM,KAAK,CAAC;AACtC,QAAM,QAAQ,KAAK,MAAM,MAAM,KAAK;AACpC,QAAM,OAAO,MAAM;AACnB,SAAO,GAAG,IAAI,GAAG,KAAK,IAAI,KAAK,SAAS,EAAE,SAAS,GAAG,GAAG,CAAC;AAC5D;AAGO,SAAS,SAAS,GAAoB,GAA4B;AACvE,SAAO,UAAU,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC;AAC1C;AAGO,SAAS,SAAS,GAAoB,GAA4B;AACvE,SAAO,UAAU,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC;AAC1C;AAGO,SAAS,YAAY,GAA4B;AACtD,SAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B;AAGO,SAAS,SAAS,GAA4B;AACnD,SAAO,UAAU,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC;AACvC;AAGO,SAAS,aAAa,GAAoB,GAAgC;AAC/E,QAAM,KAAK,QAAQ,CAAC;AACpB,QAAM,KAAK,QAAQ,CAAC;AACpB,MAAI,KAAK,GAAI,QAAO;AACpB,MAAI,KAAK,GAAI,QAAO;AACpB,SAAO;AACT;AAGO,SAAS,YAAY,OAAgC;AAC1D,SAAO,UAAU,QAAQ,KAAK,CAAC;AACjC;",
+  "names": []
+}

package/dist/modules/billing/lib/prepaidConfig.js

@@ -0,0 +1,45 @@
+import { ModuleConfig } from "@open-mercato/core/modules/configs/data/entities";
+async function readConfig(em, name) {
+  const row = await em.findOne(ModuleConfig, { moduleId: "billing", name });
+  if (!row) return void 0;
+  return row.valueJson;
+}
+function asNumberString(value, fallback) {
+  if (value === null || value === void 0) 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;
+}
+async function getLowBalanceThresholdDefault(em) {
+  return asNumberString(await readConfig(em, "prepaid.low_balance_threshold_default"), "0");
+}
+async function getNearLimitBufferDefault(em) {
+  return asNumberString(await readConfig(em, "credit.near_limit_buffer_default"), "0");
+}
+async function getTopupProvider(em) {
+  const value = await readConfig(em, "prepaid.topup_provider");
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : "stripe";
+}
+async function getStatementEnabled(em) {
+  const value = await readConfig(em, "prepaid.statement_enabled");
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value.trim().toLowerCase() !== "false";
+  return Boolean(value);
+}
+async function getTopupTaxRate(em) {
+  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;
+}
+export {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault,
+  getStatementEnabled,
+  getTopupProvider,
+  getTopupTaxRate
+};
+//# sourceMappingURL=prepaidConfig.js.map

package/dist/modules/billing/lib/prepaidConfig.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/prepaidConfig.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'\n\n/**\n * Typed readers for the prepaid billing module configs (SPEC-002), seeded by\n * `setup.ts \u2192 seedBillingConfigs`. Stored as raw JSON scalars in\n * `ModuleConfig.valueJson`. Each reader falls back to the same default the\n * seed uses, so a missing row (older tenant) behaves identically.\n */\n\nasync function readConfig(em: EntityManager, name: string): Promise<unknown> {\n  const row = await em.findOne(ModuleConfig, { moduleId: 'billing', name })\n  if (!row) return undefined\n  return row.valueJson as unknown\n}\n\nfunction asNumberString(value: unknown, fallback: string): string {\n  if (value === null || value === undefined) return fallback\n  if (typeof value === 'number' && Number.isFinite(value)) return String(value)\n  if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {\n    return value.trim()\n  }\n  return fallback\n}\n\n/** `prepaid.low_balance_threshold_default` \u2014 numeric string (default '0'). */\nexport async function getLowBalanceThresholdDefault(em: EntityManager): Promise<string> {\n  return asNumberString(await readConfig(em, 'prepaid.low_balance_threshold_default'), '0')\n}\n\n/** `credit.near_limit_buffer_default` \u2014 numeric string (default '0'). */\nexport async function getNearLimitBufferDefault(em: EntityManager): Promise<string> {\n  return asNumberString(await readConfig(em, 'credit.near_limit_buffer_default'), '0')\n}\n\n/** `prepaid.topup_provider` \u2014 gateway provider key (default 'stripe'). */\nexport async function getTopupProvider(em: EntityManager): Promise<string> {\n  const value = await readConfig(em, 'prepaid.topup_provider')\n  return typeof value === 'string' && value.trim() !== '' ? value.trim() : 'stripe'\n}\n\n/** `prepaid.statement_enabled` \u2014 master switch (default true). */\nexport async function getStatementEnabled(em: EntityManager): Promise<boolean> {\n  const value = await readConfig(em, 'prepaid.statement_enabled')\n  if (value === undefined || value === null) return true\n  if (typeof value === 'boolean') return value\n  // A stored string \"false\" must read as false (Boolean(\"false\") === true).\n  if (typeof value === 'string') return value.trim().toLowerCase() !== 'false'\n  return Boolean(value)\n}\n\n/** `prepaid.topup_tax_rate` \u2014 VAT percent on top-up receipts (default 0). */\nexport async function getTopupTaxRate(em: EntityManager): Promise<number> {\n  const value = await readConfig(em, 'prepaid.topup_tax_rate')\n  if (typeof value === 'number' && Number.isFinite(value)) return value\n  if (typeof value === 'string' && Number.isFinite(Number(value))) return Number(value)\n  return 0\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAS7B,eAAe,WAAW,IAAmB,MAAgC;AAC3E,QAAM,MAAM,MAAM,GAAG,QAAQ,cAAc,EAAE,UAAU,WAAW,KAAK,CAAC;AACxE,MAAI,CAAC,IAAK,QAAO;AACjB,SAAO,IAAI;AACb;AAEA,SAAS,eAAe,OAAgB,UAA0B;AAChE,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO,OAAO,KAAK;AAC5E,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,MAAM,OAAO,SAAS,OAAO,KAAK,CAAC,GAAG;AACtF,WAAO,MAAM,KAAK;AAAA,EACpB;AACA,SAAO;AACT;AAGA,eAAsB,8BAA8B,IAAoC;AACtF,SAAO,eAAe,MAAM,WAAW,IAAI,uCAAuC,GAAG,GAAG;AAC1F;AAGA,eAAsB,0BAA0B,IAAoC;AAClF,SAAO,eAAe,MAAM,WAAW,IAAI,kCAAkC,GAAG,GAAG;AACrF;AAGA,eAAsB,iBAAiB,IAAoC;AACzE,QAAM,QAAQ,MAAM,WAAW,IAAI,wBAAwB;AAC3D,SAAO,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,IAAI;AAC3E;AAGA,eAAsB,oBAAoB,IAAqC;AAC7E,QAAM,QAAQ,MAAM,WAAW,IAAI,2BAA2B;AAC9D,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,MAAI,OAAO,UAAU,UAAW,QAAO;AAEvC,MAAI,OAAO,UAAU,SAAU,QAAO,MAAM,KAAK,EAAE,YAAY,MAAM;AACrE,SAAO,QAAQ,KAAK;AACtB;AAGA,eAAsB,gBAAgB,IAAoC;AACxE,QAAM,QAAQ,MAAM,WAAW,IAAI,wBAAwB;AAC3D,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,EAAG,QAAO;AAChE,MAAI,OAAO,UAAU,YAAY,OAAO,SAAS,OAAO,KAAK,CAAC,EAAG,QAAO,OAAO,KAAK;AACpF,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/billing/lib/prepaidConsume.js

@@ -0,0 +1,214 @@
+import {
+  BillingAccountBalance,
+  BillingAccountTransaction,
+  BillingAccountUsage,
+  BillingItem
+} from "../data/entities.js";
+import {
+  applyBalanceMovement,
+  PREPAID_USAGE_SENTINEL_RUN_ID
+} from "./balanceLedger.js";
+import {
+  computeBalanceStatus,
+  resolveLowBalanceThreshold
+} from "./balanceStatus.js";
+import {
+  computeCreditStatus,
+  computeAvailableCredit,
+  prepaidCreditUsed
+} from "./creditStatus.js";
+import { buildBalanceCrossingEvents } from "./balanceEvents.js";
+import { absMoney, negateMoney } from "./money.js";
+import {
+  getLowBalanceThresholdDefault,
+  getNearLimitBufferDefault
+} from "./prepaidConfig.js";
+import { rateUsageForItem } from "./usageRater.js";
+function breakdownFromMetadata(meta) {
+  const b = meta?.usage_tier_breakdown;
+  return Array.isArray(b) ? b : [];
+}
+async function findUsageItem(em, input) {
+  return em.findOne(
+    BillingItem,
+    {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      billAccountId: input.billAccountId,
+      type: "usage",
+      uomCode: input.uomCode,
+      isActive: true,
+      deletedAt: null
+    },
+    { orderBy: { createdAt: "DESC" } }
+  );
+}
+async function consumePrepaidUsage(em, account, input) {
+  const currencyCode = account.currencyCode;
+  const threshold = resolveLowBalanceThreshold(
+    await readAccountThreshold(em, input),
+    await getLowBalanceThresholdDefault(em)
+  );
+  const nearLimitBuffer = await getNearLimitBufferDefault(em);
+  const creditLimit = account.creditLimit ?? "0";
+  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 ratedAmount2 = txn ? absMoney(txn.amount) : "0.0000";
+      const warning2 = txn?.metadata?.warning ?? null;
+      return {
+        result: {
+          id: existing.id,
+          deduplicated: true,
+          ratedAmount: ratedAmount2,
+          currencyCode,
+          balance,
+          balanceStatus: computeBalanceStatus(balance, threshold),
+          creditStatus: computeCreditStatus(
+            computeAvailableCredit(creditLimit, prepaidCreditUsed(balance)),
+            nearLimitBuffer,
+            prepaidCreditUsed(balance)
+          ),
+          tierBreakdown: breakdownFromMetadata(txn?.metadata),
+          warning: warning2
+        },
+        events: []
+      };
+    }
+  }
+  const now = /* @__PURE__ */ 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();
+  const item = await findUsageItem(em, input);
+  let ratedAmount = "0.0000";
+  let breakdown = [];
+  let warning = 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;
+    }
+  }
+  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;
+  const balanceStatus = computeBalanceStatus(balanceAfter, threshold);
+  const scope = {
+    billAccountId: input.billAccountId,
+    tenantId: input.tenantId,
+    organizationId: input.organizationId,
+    currencyCode
+  };
+  const events = buildBalanceCrossingEvents({
+    scope,
+    balanceBefore,
+    balanceAfter,
+    threshold,
+    creditLimit,
+    nearLimitBuffer
+  });
+  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, input, warning) {
+  if (input.lineDescription) return input.lineDescription;
+  const qty = input.quantity.toLocaleString("en-US");
+  if (!item) return `Usage \u2014 ${qty} ${input.uomCode} (no matching item)`;
+  if (warning === "unratable") return `Usage \u2014 ${qty} ${input.uomCode} (unratable)`;
+  return `${item.description} \u2014 ${qty} ${input.uomCode}`;
+}
+async function readAccountThreshold(em, input) {
+  const row = await em.findOne(BillingAccountBalance, {
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId
+  });
+  return row?.lowBalanceThreshold ?? null;
+}
+async function readCurrentBalance(em, input) {
+  const row = await em.findOne(BillingAccountBalance, {
+    tenantId: input.tenantId,
+    billAccountId: input.billAccountId
+  });
+  return row?.balance ?? "0.0000";
+}
+export {
+  consumePrepaidUsage
+};
+//# sourceMappingURL=prepaidConsume.js.map