@dainamite/billing 0.17.0

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

@@ -0,0 +1,256 @@
+import {
+  BillingAccount,
+  BillingAccountUsage,
+  BillingItem,
+  BillRun,
+  BillRunOutcome
+} from "../data/entities.js";
+import { advanceNextBillDate, deriveBillPeriod, isCycleDue } from "./billPeriod.js";
+import {
+  selectItemsForPeriod
+} from "./itemSelector.js";
+import {
+  buildInvoiceLinesFromItems,
+  writeDraftInvoice
+} from "./invoiceWriter.js";
+import { withTenantLock } from "./tenantLock.js";
+import { processUsageForAccount } from "./usageRunner.js";
+const SCHEDULED_CYCLE_LIMIT = 1;
+const CATCH_UP_HARD_CAP = 60;
+async function runBillRun(em, container, params) {
+  return withTenantLock(
+    em,
+    { tenantId: params.tenantId, lockName: "billing-run" },
+    async (tem) => executeRunWithinLock(tem, container, params)
+  );
+}
+async function executeRunWithinLock(em, container, params) {
+  const now = /* @__PURE__ */ new Date();
+  const billRun = em.create(BillRun, {
+    organizationId: params.organizationId,
+    tenantId: params.tenantId,
+    triggeredBy: params.triggeredBy,
+    parentRunId: params.parentRunId ?? null,
+    dryRun: params.mode === "dry",
+    testMode: params.mode === "test",
+    catchUp: Boolean(params.catchUp),
+    scopedAccountIds: params.scopedAccountIds ?? null,
+    asOfDate: params.asOfDate,
+    startedAt: now,
+    status: "running",
+    summary: null,
+    isActive: true,
+    createdAt: now,
+    updatedAt: now
+  });
+  em.persist(billRun);
+  await em.flush();
+  const accounts = await selectTargetAccounts(em, params);
+  const outcomes = [];
+  let totalUsageRecordsRated = 0;
+  for (const account of accounts) {
+    const processResult = await processAccountSafely(em, container, billRun, account, params);
+    if (processResult.status !== "failed") {
+      totalUsageRecordsRated += processResult.usageRecordsRated;
+    }
+    const outcome = em.create(BillRunOutcome, {
+      organizationId: params.organizationId,
+      tenantId: params.tenantId,
+      billRunId: billRun.id,
+      billAccountId: account.id,
+      status: processResult.status,
+      errorMessage: processResult.status === "failed" ? processResult.errorMessage : null,
+      warnings: processResult.status === "failed" ? null : processResult.warnings,
+      draftInvoiceId: processResult.status === "failed" ? null : processResult.draftInvoiceId,
+      isActive: true,
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    em.persist(outcome);
+    await em.flush();
+    outcomes.push(outcome);
+  }
+  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 };
+}
+async function selectTargetAccounts(em, params) {
+  const where = {
+    tenantId: params.tenantId,
+    organizationId: params.organizationId,
+    deletedAt: null,
+    nextBillDate: { $lte: params.asOfDate }
+  };
+  if (params.scopedAccountIds && params.scopedAccountIds.length > 0) {
+    where.id = { $in: params.scopedAccountIds };
+  }
+  return em.find(BillingAccount, where);
+}
+async function processAccountSafely(em, container, billRun, account, params) {
+  try {
+    return await em.transactional(async (subEm) => {
+      return processAccount(subEm, container, billRun, account, params);
+    });
+  } catch (err) {
+    return {
+      status: "failed",
+      errorMessage: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function processAccount(em, container, billRun, account, params) {
+  const maxCycles = params.triggeredBy === "schedule" || !params.catchUp ? SCHEDULED_CYCLE_LIMIT : CATCH_UP_HARD_CAP;
+  let cyclesEmitted = 0;
+  let lastDraftInvoiceId = null;
+  let totalUsageRatedThisAccount = 0;
+  const aggregatedWarnings = {};
+  while (cyclesEmitted < maxCycles && isCycleDue(account.nextBillDate, params.asOfDate)) {
+    const period = deriveBillPeriod(account.nextBillDate, account.billCycle);
+    if (params.mode !== "dry") {
+      const existing = await findExistingDraftForPeriod(em, account, period);
+      if (existing) {
+        return {
+          status: "skipped_existing_draft",
+          warnings: null,
+          draftInvoiceId: existing,
+          cyclesEmitted,
+          usageRecordsRated: totalUsageRatedThisAccount
+        };
+      }
+    }
+    const items = await em.find(BillingItem, {
+      tenantId: account.tenantId,
+      organizationId: account.organizationId,
+      billAccountId: account.id,
+      deletedAt: null
+    });
+    const usageItems = items.filter((it) => it.type === "usage");
+    const { included } = selectItemsForPeriod(items, period);
+    const billableItems = included;
+    const currencyMismatchIds = billableItems.filter((it) => it.currencyMismatch).map((it) => it.id);
+    if (currencyMismatchIds.length > 0) {
+      aggregatedWarnings.currency_mismatch_items = [
+        ...aggregatedWarnings.currency_mismatch_items ?? [],
+        ...currencyMismatchIds
+      ];
+    }
+    const itemLines = buildInvoiceLinesFromItems(billableItems);
+    const usageResult = await processUsageForAccount(em, account, period, usageItems);
+    if (usageResult.unmatchedUoms.length > 0) {
+      aggregatedWarnings.unmatched_usage_uoms = [
+        ...aggregatedWarnings.unmatched_usage_uoms ?? [],
+        ...usageResult.unmatchedUoms
+      ];
+    }
+    const allLines = [...itemLines, ...usageResult.lines];
+    if (allLines.length === 0) {
+      if (params.mode !== "real") break;
+      account.nextBillDate = advanceNextBillDate(
+        account.nextBillDate,
+        account.billCycle
+      );
+      account.lastBillDate = period.periodEnd;
+      account.updatedAt = /* @__PURE__ */ new Date();
+      cyclesEmitted += 1;
+      continue;
+    }
+    const written = await writeDraftInvoice(em, container, {
+      mode: params.mode,
+      account,
+      period,
+      billRunId: billRun.id,
+      lines: allLines
+    });
+    lastDraftInvoiceId = written.invoiceId;
+    if (params.mode === "real") {
+      const now = /* @__PURE__ */ new Date();
+      for (const item of billableItems) {
+        item.billedToDate = period.periodEnd;
+        item.updatedAt = now;
+      }
+      if (usageResult.matchedUoms.length > 0) {
+        await em.nativeUpdate(
+          BillingAccountUsage,
+          {
+            tenantId: account.tenantId,
+            organizationId: account.organizationId,
+            billAccountId: account.id,
+            uomCode: { $in: usageResult.matchedUoms },
+            ratedInBillRunId: null,
+            periodEnd: { $lte: period.periodEnd },
+            deletedAt: null
+          },
+          { ratedInBillRunId: billRun.id, updatedAt: now }
+        );
+      }
+      totalUsageRatedThisAccount += usageResult.ratedCount;
+      account.nextBillDate = advanceNextBillDate(
+        account.nextBillDate,
+        account.billCycle
+      );
+      account.lastBillDate = period.periodEnd;
+      account.updatedAt = now;
+      await em.flush();
+    } else {
+      break;
+    }
+    cyclesEmitted += 1;
+  }
+  const hasCurrencyWarnings = (aggregatedWarnings.currency_mismatch_items ?? []).length > 0;
+  const hasUnmatchedUsage = (aggregatedWarnings.unmatched_usage_uoms ?? []).length > 0;
+  const hasWarnings = hasCurrencyWarnings || hasUnmatchedUsage;
+  return {
+    status: hasWarnings ? "success_with_warnings" : "success",
+    warnings: hasWarnings ? aggregatedWarnings : null,
+    draftInvoiceId: lastDraftInvoiceId,
+    cyclesEmitted,
+    usageRecordsRated: totalUsageRatedThisAccount
+  };
+}
+async function findExistingDraftForPeriod(em, account, period) {
+  const periodStartISO = period.periodStart.toISOString().slice(0, 10);
+  const periodEndISO = period.periodEnd.toISOString().slice(0, 10);
+  const rows = await em.execute(
+    `SELECT id FROM sales_invoices
+     WHERE tenant_id = ?
+       AND organization_id = ?
+       AND deleted_at IS NULL
+       AND status = 'draft'
+       AND metadata->>'bill_account_id' = ?
+       AND metadata->>'bill_period_start' = ?
+       AND metadata->>'bill_period_end' = ?
+     LIMIT 1`,
+    [account.tenantId, account.organizationId, account.id, periodStartISO, periodEndISO]
+  );
+  if (!rows || rows.length === 0) return null;
+  return rows[0].id ?? null;
+}
+function computeFinalRunStatus(outcomes) {
+  if (outcomes.length === 0) return "completed";
+  const anyFailed = outcomes.some((o) => o.status === "failed");
+  const anySuccess = outcomes.some(
+    (o) => o.status === "success" || o.status === "success_with_warnings"
+  );
+  if (anyFailed && anySuccess) return "partial_failure";
+  if (anyFailed) return "partial_failure";
+  return "completed";
+}
+function buildRunSummary(outcomes, totalAccounts, usageRecordsRated) {
+  return {
+    accounts_processed: totalAccounts,
+    drafts_created: outcomes.filter(
+      (o) => o.draftInvoiceId !== null && o.status !== "skipped_existing_draft"
+    ).length,
+    drafts_skipped_existing: outcomes.filter((o) => o.status === "skipped_existing_draft").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
+  };
+}
+export {
+  runBillRun
+};
+//# sourceMappingURL=billRunEngine.js.map

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

@@ -0,0 +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": "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",
+  "names": []
+}

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

@@ -0,0 +1,8 @@
+function billRunName(asOfDate) {
+  const date = typeof asOfDate === "string" && asOfDate.length >= 10 ? asOfDate.slice(0, 10) : "unknown";
+  return `BILL_RUN_${date}`;
+}
+export {
+  billRunName
+};
+//# sourceMappingURL=billRunLabel.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/billRunLabel.ts"],
+  "sourcesContent": ["/**\n * Human-readable label for a Bill Run.\n *\n * The BillRun entity has no `name` column \u2014 the engine keys runs by id.\n * The admin UI derives a stable, scannable label from the run's as-of\n * date so operators see `BILL_RUN_2026-05-20` instead of a raw UUID.\n */\nexport function billRunName(asOfDate: string | null | undefined): string {\n  const date =\n    typeof asOfDate === 'string' && asOfDate.length >= 10\n      ? asOfDate.slice(0, 10)\n      : 'unknown'\n  return `BILL_RUN_${date}`\n}\n"],
+  "mappings": "AAOO,SAAS,YAAY,UAA6C;AACvE,QAAM,OACJ,OAAO,aAAa,YAAY,SAAS,UAAU,KAC/C,SAAS,MAAM,GAAG,EAAE,IACpB;AACN,SAAO,YAAY,IAAI;AACzB;",
+  "names": []
+}

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

@@ -0,0 +1,13 @@
+async function findBySourceRef(em, entity, scope) {
+  const where = {
+    tenantId: scope.tenantId,
+    billAccountId: scope.billAccountId,
+    sourceRef: scope.sourceRef,
+    deletedAt: null
+  };
+  return em.findOne(entity, where);
+}
+export {
+  findBySourceRef
+};
+//# sourceMappingURL=idempotency.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/idempotency.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\n\n/**\n * `source_ref` idempotency helper.\n *\n * The unique index on `(tenant_id, bill_account_id, source_ref)` does the\n * heavy lifting at the database level \u2014 Postgres treats NULLs as distinct,\n * so multiple NULL `source_ref` values coexist for the same account. This\n * helper checks for an existing row *before* the insert so we can return\n * it (HTTP 200 with `deduplicated: true`) instead of taking the round-trip\n * to the DB and unwinding a unique-violation.\n *\n * Why not rely solely on the unique constraint and catch the conflict?\n * Two reasons:\n *   1. Catching the conflict requires a SAVEPOINT or a separate tx \u2014\n *      complicates error handling and rolls back the surrounding work.\n *   2. Idempotency is also a read-side guarantee: if a connector POSTs\n *      twice, the *second* call should observe what the first one\n *      persisted, not just \"duplicate, sorry.\"\n *\n * The constraint stays in place as the *correctness* gate \u2014 if a race\n * sneaks past this check, the DB still refuses the duplicate.\n */\n\ntype SourceRefScope = {\n  tenantId: string\n  billAccountId: string\n  sourceRef: string\n  deletedAt?: null\n}\n\ntype EntityCtor<T> = new (...args: never[]) => T\n\nexport async function findBySourceRef<T extends { sourceRef?: string | null }>(\n  em: EntityManager,\n  entity: EntityCtor<T>,\n  scope: { tenantId: string; billAccountId: string; sourceRef: string },\n): Promise<T | null> {\n  const where: SourceRefScope = {\n    tenantId: scope.tenantId,\n    billAccountId: scope.billAccountId,\n    sourceRef: scope.sourceRef,\n    deletedAt: null,\n  }\n  return em.findOne(entity, where as never)\n}\n"],
+  "mappings": "AAiCA,eAAsB,gBACpB,IACA,QACA,OACmB;AACnB,QAAM,QAAwB;AAAA,IAC5B,UAAU,MAAM;AAAA,IAChB,eAAe,MAAM;AAAA,IACrB,WAAW,MAAM;AAAA,IACjB,WAAW;AAAA,EACb;AACA,SAAO,GAAG,QAAQ,QAAQ,KAAc;AAC1C;",
+  "names": []
+}

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

@@ -0,0 +1,38 @@
+import {
+  Dictionary,
+  DictionaryEntry
+} from "@open-mercato/core/modules/dictionaries/data/entities";
+const SALES_INVOICE_STATUS_DICTIONARY_KEY = "sales.invoice_status";
+const cache = /* @__PURE__ */ new Map();
+function key(tenantId, organizationId, status) {
+  return `${tenantId}:${organizationId}:${status}`;
+}
+async function resolveInvoiceStatusEntryId(em, tenantId, organizationId, status) {
+  const cacheKey = key(tenantId, organizationId, status);
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+  const dictionary = await em.findOne(Dictionary, {
+    tenantId,
+    organizationId,
+    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,
+    deletedAt: null
+  });
+  if (!dictionary) return null;
+  const entry = await em.findOne(DictionaryEntry, {
+    dictionary,
+    tenantId,
+    organizationId,
+    value: status
+  });
+  if (!entry) return null;
+  cache.set(cacheKey, entry.id);
+  return entry.id;
+}
+function __resetInvoiceStatusCacheForTests() {
+  cache.clear();
+}
+export {
+  __resetInvoiceStatusCacheForTests,
+  resolveInvoiceStatusEntryId
+};
+//# sourceMappingURL=invoiceStatus.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/invoiceStatus.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport {\n  Dictionary,\n  DictionaryEntry,\n} from '@open-mercato/core/modules/dictionaries/data/entities'\nimport type { InvoiceStatus } from '../data/validators'\n\n/**\n * Resolve the `sales.invoice_status` dictionary entry id for a given\n * status value, scoped per `(tenantId, organizationId)`.\n *\n * Used by:\n *   - `invoiceWriter` to set `statusEntryId` on the draft at create time.\n *   - The \"post\" command to flip draft \u2192 posted.\n *   - The payment-captured subscriber to flip posted \u2192 paid.\n *\n * Cached because the lookup is hot (every Bill Run draft hits it\n * once, every posted invoice hits it twice, every paid invoice once)\n * and the dictionary entry id never changes for the lifetime of a\n * tenant. Exposed `__resetInvoiceStatusCacheForTests` to keep tests\n * deterministic across runs.\n */\n\nconst SALES_INVOICE_STATUS_DICTIONARY_KEY = 'sales.invoice_status'\n\nconst cache = new Map<string, string>()\n\nfunction key(tenantId: string, organizationId: string, status: InvoiceStatus): string {\n  return `${tenantId}:${organizationId}:${status}`\n}\n\nexport async function resolveInvoiceStatusEntryId(\n  em: EntityManager,\n  tenantId: string,\n  organizationId: string,\n  status: InvoiceStatus,\n): Promise<string | null> {\n  const cacheKey = key(tenantId, organizationId, status)\n  const cached = cache.get(cacheKey)\n  if (cached) return cached\n  const dictionary = await em.findOne(Dictionary, {\n    tenantId,\n    organizationId,\n    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,\n    deletedAt: null,\n  })\n  if (!dictionary) return null\n  const entry = await em.findOne(DictionaryEntry, {\n    dictionary,\n    tenantId,\n    organizationId,\n    value: status,\n  })\n  if (!entry) return null\n  cache.set(cacheKey, entry.id)\n  return entry.id\n}\n\nexport function __resetInvoiceStatusCacheForTests(): void {\n  cache.clear()\n}\n"],
+  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAmBP,MAAM,sCAAsC;AAE5C,MAAM,QAAQ,oBAAI,IAAoB;AAEtC,SAAS,IAAI,UAAkB,gBAAwB,QAA+B;AACpF,SAAO,GAAG,QAAQ,IAAI,cAAc,IAAI,MAAM;AAChD;AAEA,eAAsB,4BACpB,IACA,UACA,gBACA,QACwB;AACxB,QAAM,WAAW,IAAI,UAAU,gBAAgB,MAAM;AACrD,QAAM,SAAS,MAAM,IAAI,QAAQ;AACjC,MAAI,OAAQ,QAAO;AACnB,QAAM,aAAa,MAAM,GAAG,QAAQ,YAAY;AAAA,IAC9C;AAAA,IACA;AAAA,IACA,KAAK;AAAA,IACL,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,QAAQ,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC9C;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO;AAAA,EACT,CAAC;AACD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,IAAI,UAAU,MAAM,EAAE;AAC5B,SAAO,MAAM;AACf;AAEO,SAAS,oCAA0C;AACxD,QAAM,MAAM;AACd;",
+  "names": []
+}

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

@@ -0,0 +1,153 @@
+import {
+  SalesInvoice,
+  SalesInvoiceLine
+} from "@open-mercato/core/modules/sales/data/entities";
+import {
+  __resetInvoiceStatusCacheForTests,
+  resolveInvoiceStatusEntryId
+} from "./invoiceStatus.js";
+const DRAFT_INVOICE_STATUS_VALUE = "draft";
+function __resetInvoiceWriterCacheForTests() {
+  __resetInvoiceStatusCacheForTests();
+}
+function generateTestInvoiceNumber() {
+  const random = Math.floor(Math.random() * 1e9).toString(16).padStart(8, "0");
+  return `TEST-${Date.now().toString(16)}-${random}`;
+}
+function roundHalfUp2dp(value) {
+  return Math.round((value + Number.EPSILON) * 100) / 100;
+}
+function format4dp(value) {
+  return roundHalfUp2dp(value).toFixed(4);
+}
+function sumNetTotal(lines) {
+  let total = 0;
+  for (const line of lines) {
+    total += Number.parseFloat(line.totalNetAmount);
+  }
+  return format4dp(total);
+}
+async function writeDraftInvoice(em, container, params) {
+  const totalNet = sumNetTotal(params.lines);
+  if (params.mode === "dry") {
+    return { invoiceId: null, invoiceNumber: null, totalNet };
+  }
+  const { account, period, billRunId, lines, mode } = params;
+  let invoiceNumber;
+  if (mode === "test") {
+    invoiceNumber = generateTestInvoiceNumber();
+  } else {
+    const numberGenerator = container.resolve(
+      "salesDocumentNumberGenerator"
+    );
+    const generated = await numberGenerator.generate({
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      kind: "invoice"
+    });
+    invoiceNumber = generated.number;
+  }
+  const statusEntryId = await resolveInvoiceStatusEntryId(
+    em,
+    account.tenantId,
+    account.organizationId,
+    "draft"
+  );
+  const now = /* @__PURE__ */ new Date();
+  const invoice = em.create(SalesInvoice, {
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+    invoiceNumber,
+    statusEntryId,
+    status: DRAFT_INVOICE_STATUS_VALUE,
+    issueDate: now,
+    currencyCode: account.currencyCode,
+    subtotalNetAmount: totalNet,
+    subtotalGrossAmount: totalNet,
+    // gross == net for drafts (tax computed on post)
+    discountTotalAmount: "0",
+    taxTotalAmount: "0",
+    grandTotalNetAmount: totalNet,
+    grandTotalGrossAmount: totalNet,
+    paidTotalAmount: "0",
+    outstandingAmount: totalNet,
+    metadata: {
+      bill_run_id: billRunId,
+      bill_account_id: account.id,
+      bill_period_start: period.periodStart.toISOString().slice(0, 10),
+      bill_period_end: period.periodEnd.toISOString().slice(0, 10),
+      test_run: mode === "test" ? true : void 0
+    },
+    createdAt: now,
+    updatedAt: now
+  });
+  em.persist(invoice);
+  let lineNumber = 1;
+  for (const line of lines) {
+    const invoiceLine = em.create(SalesInvoiceLine, {
+      invoice,
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      lineNumber: lineNumber++,
+      kind: "product",
+      description: line.description,
+      quantity: line.quantity,
+      normalizedQuantity: line.quantity,
+      currencyCode: account.currencyCode,
+      unitPriceNet: line.unitPriceNet,
+      unitPriceGross: line.unitPriceNet,
+      // gross == net until tax computed on post
+      discountAmount: "0",
+      discountPercent: "0",
+      taxRate: "0",
+      taxAmount: "0",
+      totalNetAmount: line.totalNetAmount,
+      totalGrossAmount: line.totalNetAmount,
+      metadata: {
+        billing_item_id: line.billingItemId,
+        billing_type: line.billingType,
+        ...line.metadataExtra ?? {}
+      }
+    });
+    em.persist(invoiceLine);
+  }
+  await em.flush();
+  return { invoiceId: invoice.id, invoiceNumber, totalNet };
+}
+function buildInvoiceLinesFromItems(items) {
+  const lines = [];
+  for (const item of items) {
+    if (item.type === "one_time") {
+      const rate = item.rateJson;
+      if (!rate || typeof rate.amount !== "number") continue;
+      const amount = format4dp(rate.amount);
+      lines.push({
+        billingItemId: item.id,
+        billingType: "one_time",
+        description: item.description,
+        unitPriceNet: amount,
+        quantity: "1",
+        totalNetAmount: amount
+      });
+    } else if (item.type === "recurring") {
+      const rate = item.rateJson;
+      if (!rate || typeof rate.unit_price !== "number") continue;
+      const unitPrice = format4dp(rate.unit_price);
+      lines.push({
+        billingItemId: item.id,
+        billingType: "recurring",
+        description: item.description,
+        unitPriceNet: unitPrice,
+        quantity: "1",
+        totalNetAmount: unitPrice
+      });
+    }
+  }
+  return lines;
+}
+export {
+  __resetInvoiceWriterCacheForTests,
+  buildInvoiceLinesFromItems,
+  writeDraftInvoice
+};
+//# sourceMappingURL=invoiceWriter.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/invoiceWriter.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { AwilixContainer } from 'awilix'\nimport {\n  SalesInvoice,\n  SalesInvoiceLine,\n} from '@open-mercato/core/modules/sales/data/entities'\nimport type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'\nimport type { BillingAccount, BillingItem } from '../data/entities'\nimport type { BillPeriod } from './billPeriod'\nimport {\n  __resetInvoiceStatusCacheForTests,\n  resolveInvoiceStatusEntryId,\n} from './invoiceStatus'\n\n/**\n * Writes a `core/sales` draft invoice for a billing account's bill period.\n *\n * Two notable deviations from the spec, documented in CHANGELOG / spec:\n *\n *   1. `SalesInvoice.invoice_number` is `NOT NULL` in the upstream\n *      schema, but the spec says \"sequence number assigned at Post.\"\n *      Real-mode invoices get a real number via\n *      `salesDocumentNumberGenerator.generate({ kind: 'invoice' })` at\n *      *draft create time* \u2014 the spec's intent (gap-free numbering via\n *      atomic SQL upsert) is preserved; the timing differs because the\n *      upstream column is `NOT NULL`. \"Post\" then just transitions\n *      status `draft \u2192 posted`.\n *\n *   2. Test-mode invoices use a `TEST-<uuid>` placeholder number (not\n *      the real sequence) so test runs do not burn production numbers\n *      and can be repeated idempotently.\n *\n * VAT is NOT computed here \u2014 `core/sales`'s tax service owns the\n * per-line `tax_rate` / `tax_amount` calculation, and runs on POST.\n * Drafts therefore carry zeroes in the tax columns; the totals reflect\n * net amounts only.\n */\n\nexport type WriteMode = 'real' | 'test' | 'dry'\n\nexport type InvoiceLineDescriptor = {\n  /** Maps to billing_item_id on the resulting SalesInvoiceLine.metadata. */\n  billingItemId: string\n  /** From the spec's `metadata.billing_type` for traceability. */\n  billingType: 'one_time' | 'recurring' | 'usage'\n  description: string\n  /** Net unit price (numeric string for SalesInvoiceLine.unit_price_net). */\n  unitPriceNet: string\n  /** Quantity (string for the numeric(18,4) column). */\n  quantity: string\n  /** Total net (string). */\n  totalNetAmount: string\n  /** Optional per-line metadata extension \u2014 e.g. usage tier breakdown. */\n  metadataExtra?: Record<string, unknown>\n}\n\nexport type WriteInvoiceParams = {\n  mode: WriteMode\n  account: BillingAccount\n  period: BillPeriod\n  billRunId: string\n  lines: InvoiceLineDescriptor[]\n}\n\nexport type WrittenInvoice = {\n  invoiceId: string | null\n  invoiceNumber: string | null\n  totalNet: string\n}\n\nconst DRAFT_INVOICE_STATUS_VALUE = 'draft'\n\n/**\n * Test hook \u2014 clears the shared resolver's status cache so the engine\n * test suite stays deterministic across mocked-EM environments.\n */\nexport function __resetInvoiceWriterCacheForTests(): void {\n  __resetInvoiceStatusCacheForTests()\n}\n\nfunction generateTestInvoiceNumber(): string {\n  // Match the pattern operators search by: `TEST-` prefix + random\n  // suffix so the test wipe-out endpoint can filter via `LIKE 'TEST-%'`\n  // (defensive \u2014 primary filter is `metadata.test_run=true`).\n  const random = Math.floor(Math.random() * 1e9)\n    .toString(16)\n    .padStart(8, '0')\n  return `TEST-${Date.now().toString(16)}-${random}`\n}\n\n/**\n * 2dp half-up rounding that survives binary floating-point edge cases\n * (e.g. `1.005 * 100 === 100.49999...` would otherwise round DOWN to\n * `1.00` under naive `Math.round`). The `+ EPSILON` nudge pushes\n * representations like 100.4999...8 up to the true half-up boundary.\n * Matches the spec's \"2 decimal places, half-up\" rounding policy.\n */\nfunction roundHalfUp2dp(value: number): number {\n  return Math.round((value + Number.EPSILON) * 100) / 100\n}\n\nfunction format4dp(value: number): string {\n  return roundHalfUp2dp(value).toFixed(4)\n}\n\nfunction sumNetTotal(lines: InvoiceLineDescriptor[]): string {\n  let total = 0\n  for (const line of lines) {\n    total += Number.parseFloat(line.totalNetAmount)\n  }\n  return format4dp(total)\n}\n\nexport async function writeDraftInvoice(\n  em: EntityManager,\n  container: AwilixContainer,\n  params: WriteInvoiceParams,\n): Promise<WrittenInvoice> {\n  const totalNet = sumNetTotal(params.lines)\n\n  if (params.mode === 'dry') {\n    // Compute totals; persist nothing.\n    return { invoiceId: null, invoiceNumber: null, totalNet }\n  }\n\n  const { account, period, billRunId, lines, mode } = params\n\n  let invoiceNumber: string\n  if (mode === 'test') {\n    invoiceNumber = generateTestInvoiceNumber()\n  } else {\n    const numberGenerator = container.resolve(\n      'salesDocumentNumberGenerator',\n    ) as SalesDocumentNumberGenerator\n    const generated = await numberGenerator.generate({\n      organizationId: account.organizationId,\n      tenantId: account.tenantId,\n      kind: 'invoice',\n    })\n    invoiceNumber = generated.number\n  }\n\n  const statusEntryId = await resolveInvoiceStatusEntryId(\n    em,\n    account.tenantId,\n    account.organizationId,\n    'draft',\n  )\n\n  const now = new Date()\n  const invoice = em.create(SalesInvoice, {\n    organizationId: account.organizationId,\n    tenantId: account.tenantId,\n    invoiceNumber,\n    statusEntryId,\n    status: DRAFT_INVOICE_STATUS_VALUE,\n    issueDate: now,\n    currencyCode: account.currencyCode,\n    subtotalNetAmount: totalNet,\n    subtotalGrossAmount: totalNet, // gross == net for drafts (tax computed on post)\n    discountTotalAmount: '0',\n    taxTotalAmount: '0',\n    grandTotalNetAmount: totalNet,\n    grandTotalGrossAmount: totalNet,\n    paidTotalAmount: '0',\n    outstandingAmount: totalNet,\n    metadata: {\n      bill_run_id: billRunId,\n      bill_account_id: account.id,\n      bill_period_start: period.periodStart.toISOString().slice(0, 10),\n      bill_period_end: period.periodEnd.toISOString().slice(0, 10),\n      test_run: mode === 'test' ? true : undefined,\n    },\n    createdAt: now,\n    updatedAt: now,\n  })\n  em.persist(invoice)\n\n  let lineNumber = 1\n  for (const line of lines) {\n    const invoiceLine = em.create(SalesInvoiceLine, {\n      invoice,\n      organizationId: account.organizationId,\n      tenantId: account.tenantId,\n      lineNumber: lineNumber++,\n      kind: 'product',\n      description: line.description,\n      quantity: line.quantity,\n      normalizedQuantity: line.quantity,\n      currencyCode: account.currencyCode,\n      unitPriceNet: line.unitPriceNet,\n      unitPriceGross: line.unitPriceNet, // gross == net until tax computed on post\n      discountAmount: '0',\n      discountPercent: '0',\n      taxRate: '0',\n      taxAmount: '0',\n      totalNetAmount: line.totalNetAmount,\n      totalGrossAmount: line.totalNetAmount,\n      metadata: {\n        billing_item_id: line.billingItemId,\n        billing_type: line.billingType,\n        ...(line.metadataExtra ?? {}),\n      },\n    })\n    em.persist(invoiceLine)\n  }\n\n  await em.flush()\n\n  return { invoiceId: invoice.id, invoiceNumber, totalNet }\n}\n\n/**\n * Build the InvoiceLineDescriptor list for a single account's eligible\n * items (the result of `itemSelector.selectItemsForPeriod`). One line\n * per item; `usage` items are excluded earlier by the selector.\n *\n * Per-type pricing per the spec's `BillingItem \u2192 InvoiceLine mapping`:\n *   - `one_time`: unit_price = amount, quantity = 1\n *   - `recurring`: unit_price = unit_price, quantity = 1\n *     (one full cycle per bill period; catch-up emits separate drafts\n *     per missed cycle, never combined)\n */\nexport function buildInvoiceLinesFromItems(\n  items: readonly BillingItem[],\n): InvoiceLineDescriptor[] {\n  const lines: InvoiceLineDescriptor[] = []\n  for (const item of items) {\n    if (item.type === 'one_time') {\n      const rate = item.rateJson as { amount?: number } | null\n      if (!rate || typeof rate.amount !== 'number') continue\n      // For one_time the per-unit price IS the total \u2014 quantity is 1.\n      // Both fields therefore carry the same value, with the 2dp\n      // half-up policy applied (unit price + line total are the same\n      // numeric column at numeric(18,4)).\n      const amount = format4dp(rate.amount)\n      lines.push({\n        billingItemId: item.id,\n        billingType: 'one_time',\n        description: item.description,\n        unitPriceNet: amount,\n        quantity: '1',\n        totalNetAmount: amount,\n      })\n    } else if (item.type === 'recurring') {\n      const rate = item.rateJson as { unit_price?: number } | null\n      if (!rate || typeof rate.unit_price !== 'number') continue\n      const unitPrice = format4dp(rate.unit_price)\n      lines.push({\n        billingItemId: item.id,\n        billingType: 'recurring',\n        description: item.description,\n        unitPriceNet: unitPrice,\n        quantity: '1',\n        totalNetAmount: unitPrice,\n      })\n    }\n  }\n  return lines\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -0,0 +1,77 @@
+function asTime(date) {
+  if (!date) return null;
+  return new Date(date).getTime();
+}
+function isWithin(windowStart, windowEnd, point) {
+  const pointTime = asTime(point);
+  const startTime = asTime(windowStart);
+  if (pointTime < startTime) return false;
+  const endTime = asTime(windowEnd);
+  if (endTime === null) return true;
+  return pointTime <= endTime;
+}
+function overlapsPeriod(itemStart, itemEnd, period) {
+  const itemStartTime = asTime(itemStart);
+  const itemEndTime = asTime(itemEnd);
+  const periodStartTime = asTime(period.periodStart);
+  const periodEndTime = asTime(period.periodEnd);
+  if (itemStartTime > periodEndTime) return false;
+  if (itemEndTime !== null && itemEndTime < periodStartTime) return false;
+  return true;
+}
+function shouldIncludeItem(item, period) {
+  if (!item.isActive) return { include: false, reason: "item-inactive" };
+  if (item.deletedAt) return { include: false, reason: "item-soft-deleted" };
+  switch (item.type) {
+    case "one_time": {
+      if (item.billedToDate) {
+        return { include: false, reason: "one_time-already-billed" };
+      }
+      if (!overlapsPeriod(item.billStartDate, item.billEndDate, period)) {
+        return { include: false, reason: "one_time-window-outside-period" };
+      }
+      return { include: true };
+    }
+    case "recurring": {
+      const billedToTime = asTime(item.billedToDate);
+      const periodEndTime = asTime(period.periodEnd);
+      if (billedToTime !== null && billedToTime >= periodEndTime) {
+        return { include: false, reason: "recurring-already-billed-through-period" };
+      }
+      const periodStartTime = asTime(period.periodStart);
+      const itemStartTime = asTime(item.billStartDate);
+      if (itemStartTime > periodStartTime) {
+        return { include: false, reason: "recurring-starts-mid-cycle" };
+      }
+      const itemEndTime = asTime(item.billEndDate);
+      if (itemEndTime !== null && itemEndTime < periodEndTime) {
+        return { include: false, reason: "recurring-ends-mid-cycle" };
+      }
+      return { include: true };
+    }
+    case "usage":
+      return { include: false, reason: "usage-handled-by-rater" };
+    default:
+      return { include: false, reason: `unknown-type:${item.type}` };
+  }
+}
+function selectItemsForPeriod(items, period) {
+  const included = [];
+  const skipped = [];
+  for (const item of items) {
+    const decision = shouldIncludeItem(item, period);
+    if (decision.include) {
+      included.push(item);
+    } else {
+      skipped.push({ item, reason: decision.reason });
+    }
+  }
+  return { included, skipped };
+}
+export {
+  isWithin,
+  overlapsPeriod,
+  selectItemsForPeriod,
+  shouldIncludeItem
+};
+//# sourceMappingURL=itemSelector.js.map