@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,356 @@
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { BillingAllocation } from "../data/entities.js";
+function toCents(value) {
+  const n = typeof value === "number" ? value : Number.parseFloat(value ?? "0");
+  return Number.isFinite(n) ? Math.round(n * 100) : 0;
+}
+function fromCents(cents) {
+  return (cents / 100).toFixed(4);
+}
+function sortOpenReceivables(rows) {
+  return [...rows].sort((a, b) => {
+    if (a.dueDate !== b.dueDate) {
+      if (!a.dueDate) return 1;
+      if (!b.dueDate) return -1;
+      return a.dueDate < b.dueDate ? -1 : 1;
+    }
+    if (a.issueDate !== b.issueDate) {
+      if (!a.issueDate) return 1;
+      if (!b.issueDate) return -1;
+      return a.issueDate < b.issueDate ? -1 : 1;
+    }
+    return a.number.localeCompare(b.number);
+  });
+}
+function planAllocation(amountCents, receivables) {
+  let remaining = Math.max(0, amountCents);
+  const allocations = [];
+  for (const receivable of receivables) {
+    if (remaining <= 0) break;
+    const take = Math.min(remaining, Math.max(0, receivable.outstandingCents));
+    if (take <= 0) continue;
+    allocations.push({ invoiceId: receivable.id, amountCents: take });
+    remaining -= take;
+  }
+  return { allocations, remainderCents: remaining };
+}
+function recomputeReceivable(state) {
+  const { totalGrossCents: gross, paidCents: paid, creditedCents: credited } = state;
+  const outstandingCents = Math.max(0, gross - paid - credited);
+  if (state.status === "draft") return { paidCents: paid, creditedCents: credited, outstandingCents, status: "draft" };
+  let status;
+  if (gross > 0 && outstandingCents === 0) status = credited >= gross ? "credited" : "paid";
+  else if (paid + credited > 0) status = "partially_paid";
+  else status = "posted";
+  return { paidCents: paid, creditedCents: credited, outstandingCents, status };
+}
+function paymentStatusFor(payment) {
+  if (payment.status === "ignored" || payment.status === "converted_to_topup") return payment.status;
+  if (!payment.billAccountId) return "unmatched";
+  if (payment.unallocatedCents <= 0) return "allocated";
+  if (payment.unallocatedCents < payment.amountCents) return "partially_allocated";
+  return "matched";
+}
+function emptyEffects() {
+  return { created: [], removed: [], invoiceStatusChanges: [] };
+}
+function mergeEffects(target, extra) {
+  target.created.push(...extra.created);
+  target.removed.push(...extra.removed);
+  target.invoiceStatusChanges.push(...extra.invoiceStatusChanges);
+  return target;
+}
+const RECEIVABLE_TYPES = ["invoice", "debit_memo"];
+const OPEN_STATUSES = ["posted", "partially_paid"];
+function isoDay(value) {
+  if (!value) return null;
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  return String(value).slice(0, 10);
+}
+async function loadReceivable(tem, scope, invoiceId) {
+  const rows = await tem.execute(
+    `SELECT id, bill_account_id, currency_code, status, document_type, test_run, total_gross, outstanding,
+            due_date, issue_date, number
+       FROM billing_invoices
+      WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`,
+    [invoiceId, scope.tenantId, scope.organizationId]
+  );
+  return rows?.[0] ?? null;
+}
+async function loadSource(tem, scope, source) {
+  const sql = source.type === "payment" ? `SELECT id, bill_account_id, currency_code, unallocated_amount AS unallocated, status
+           FROM billing_payments
+          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL` : `SELECT id, bill_account_id, currency_code, outstanding AS unallocated, status
+           FROM billing_invoices
+          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL
+            AND document_type = 'credit_memo'`;
+  const rows = await tem.execute(sql, [source.id, scope.tenantId, scope.organizationId]);
+  return rows?.[0] ?? null;
+}
+async function adjustSourceUnallocated(tem, scope, source, deltaCents) {
+  const amount = fromCents(Math.abs(deltaCents));
+  if (source.type === "payment") {
+    const rows2 = await tem.execute(
+      deltaCents >= 0 ? `UPDATE billing_payments
+              SET unallocated_amount = unallocated_amount - ?::numeric, updated_at = now()
+            WHERE id = ? AND tenant_id = ? AND organization_id = ? AND unallocated_amount >= ?::numeric
+          RETURNING id` : `UPDATE billing_payments
+              SET unallocated_amount = LEAST(amount, unallocated_amount + ?::numeric), updated_at = now()
+            WHERE id = ? AND tenant_id = ? AND organization_id = ?
+          RETURNING id`,
+      deltaCents >= 0 ? [amount, source.id, scope.tenantId, scope.organizationId, amount] : [amount, source.id, scope.tenantId, scope.organizationId]
+    );
+    if (!rows2?.length) return false;
+    await tem.execute(
+      `UPDATE billing_payments
+          SET status = CASE
+                WHEN unallocated_amount <= 0 THEN 'allocated'
+                WHEN unallocated_amount < amount THEN 'partially_allocated'
+                ELSE 'matched' END
+        WHERE id = ? AND status IN ('matched', 'partially_allocated', 'allocated')`,
+      [source.id]
+    );
+    return true;
+  }
+  const rows = await tem.execute(
+    deltaCents >= 0 ? `UPDATE billing_invoices
+            SET outstanding = outstanding - ?::numeric,
+                status = CASE WHEN outstanding - ?::numeric <= 0 THEN 'paid' ELSE 'posted' END,
+                updated_at = now()
+          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND document_type = 'credit_memo'
+            AND outstanding >= ?::numeric
+        RETURNING id` : `UPDATE billing_invoices
+            SET outstanding = LEAST(total_gross, outstanding + ?::numeric), status = 'posted', updated_at = now()
+          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND document_type = 'credit_memo'
+        RETURNING id`,
+    deltaCents >= 0 ? [amount, amount, source.id, scope.tenantId, scope.organizationId, amount] : [amount, source.id, scope.tenantId, scope.organizationId]
+  );
+  return Boolean(rows?.length);
+}
+async function recomputeInvoice(tem, scope, invoiceId) {
+  const invoice = await loadReceivable(tem, scope, invoiceId);
+  if (!invoice || !RECEIVABLE_TYPES.includes(invoice.document_type)) return null;
+  const sums = await tem.execute(
+    `SELECT COALESCE(SUM(amount) FILTER (WHERE source_type = 'payment'), 0) AS paid,
+            COALESCE(SUM(amount) FILTER (WHERE source_type = 'credit_memo'), 0) AS credited
+       FROM billing_allocations
+      WHERE invoice_id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`,
+    [invoiceId, scope.tenantId, scope.organizationId]
+  );
+  const next = recomputeReceivable({
+    status: invoice.status,
+    totalGrossCents: toCents(invoice.total_gross),
+    paidCents: toCents(sums?.[0]?.paid),
+    creditedCents: toCents(sums?.[0]?.credited)
+  });
+  await tem.execute(
+    `UPDATE billing_invoices
+        SET paid_total = ?::numeric, credited_total = ?::numeric, outstanding = ?::numeric, status = ?, updated_at = now()
+      WHERE id = ? AND tenant_id = ? AND organization_id = ?`,
+    [
+      fromCents(next.paidCents),
+      fromCents(next.creditedCents),
+      fromCents(next.outstandingCents),
+      next.status,
+      invoiceId,
+      scope.tenantId,
+      scope.organizationId
+    ]
+  );
+  return next.status !== invoice.status ? { invoiceId, from: invoice.status, to: next.status } : null;
+}
+async function allocate(tem, scope, params) {
+  const effects = emptyEffects();
+  if (params.amountCents <= 0) {
+    throw new CrudHttpError(400, { error: "Allocation amount must be positive", code: "billing.allocation.invalid_amount" });
+  }
+  const [source, invoice] = await Promise.all([
+    loadSource(tem, scope, params.source),
+    loadReceivable(tem, scope, params.invoiceId)
+  ]);
+  if (!source) throw new CrudHttpError(404, { error: "Payment source not found", code: "billing.allocation.source_missing" });
+  if (!invoice) throw new CrudHttpError(404, { error: "Invoice not found", code: "billing.allocation.invoice_missing" });
+  if (!source.bill_account_id || source.bill_account_id !== invoice.bill_account_id) {
+    throw new CrudHttpError(409, {
+      error: "Payment and invoice belong to different accounts",
+      code: "billing.allocation.account_mismatch"
+    });
+  }
+  if (source.currency_code !== invoice.currency_code) {
+    throw new CrudHttpError(409, { error: "Currencies differ", code: "billing.allocation.currency_mismatch" });
+  }
+  if (invoice.test_run || !RECEIVABLE_TYPES.includes(invoice.document_type) || !OPEN_STATUSES.includes(invoice.status)) {
+    throw new CrudHttpError(409, { error: "Invoice is not open for payment", code: "billing.allocation.invoice_not_open" });
+  }
+  if (params.amountCents > toCents(invoice.outstanding)) {
+    throw new CrudHttpError(409, {
+      error: "Allocation exceeds the invoice outstanding amount",
+      code: "billing.allocation.exceeds_outstanding"
+    });
+  }
+  const decremented = await adjustSourceUnallocated(tem, scope, params.source, params.amountCents);
+  if (!decremented) {
+    throw new CrudHttpError(409, {
+      error: "Not enough unallocated amount",
+      code: "billing.allocation.insufficient_unallocated"
+    });
+  }
+  const now = /* @__PURE__ */ new Date();
+  const row = tem.create(BillingAllocation, {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    sourceType: params.source.type,
+    sourceId: params.source.id,
+    invoiceId: params.invoiceId,
+    billAccountId: invoice.bill_account_id,
+    amount: fromCents(params.amountCents),
+    currencyCode: invoice.currency_code,
+    allocatedBy: params.by,
+    userId: params.userId ?? null,
+    createdAt: now,
+    updatedAt: now
+  });
+  tem.persist(row);
+  await tem.flush();
+  effects.created.push({
+    allocationId: row.id,
+    sourceType: params.source.type,
+    sourceId: params.source.id,
+    invoiceId: params.invoiceId,
+    amount: row.amount
+  });
+  const change = await recomputeInvoice(tem, scope, params.invoiceId);
+  if (change) effects.invoiceStatusChanges.push(change);
+  return effects;
+}
+async function unallocate(tem, scope, params) {
+  const effects = emptyEffects();
+  const rows = await tem.execute(
+    `UPDATE billing_allocations
+        SET deleted_at = now(), updated_at = now(), deallocated_by_user_id = ?
+      WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL
+    RETURNING id, source_type, source_id, invoice_id, amount`,
+    [params.userId ?? null, params.allocationId, scope.tenantId, scope.organizationId]
+  );
+  const removed = rows?.[0];
+  if (!removed) throw new CrudHttpError(404, { error: "Allocation not found", code: "billing.allocation.not_found" });
+  await adjustSourceUnallocated(tem, scope, { type: removed.source_type, id: removed.source_id }, -toCents(removed.amount));
+  effects.removed.push({
+    allocationId: removed.id,
+    sourceType: removed.source_type,
+    sourceId: removed.source_id,
+    invoiceId: removed.invoice_id,
+    amount: removed.amount
+  });
+  const change = await recomputeInvoice(tem, scope, removed.invoice_id);
+  if (change) effects.invoiceStatusChanges.push(change);
+  return effects;
+}
+async function loadOpenReceivables(tem, scope, account, onlyIds) {
+  const params = [scope.tenantId, scope.organizationId, account.id, account.currencyCode];
+  let idFilter = "";
+  if (onlyIds && onlyIds.length > 0) {
+    idFilter = ` AND id = ANY(?::uuid[])`;
+    params.push(`{${onlyIds.join(",")}}`);
+  }
+  const rows = await tem.execute(
+    `SELECT id, outstanding, due_date, issue_date, number
+       FROM billing_invoices
+      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?
+        AND deleted_at IS NULL AND test_run = false
+        AND document_type IN ('invoice', 'debit_memo')
+        AND status IN ('posted', 'partially_paid')
+        AND outstanding > 0${idFilter}`,
+    params
+  );
+  return sortOpenReceivables(
+    (rows ?? []).map((row) => ({
+      id: row.id,
+      outstandingCents: toCents(row.outstanding),
+      dueDate: isoDay(row.due_date),
+      issueDate: isoDay(row.issue_date),
+      number: row.number
+    }))
+  );
+}
+async function loadCreditSources(tem, scope, account) {
+  const rows = await tem.execute(
+    `SELECT 'payment' AS source_type, id, unallocated_amount AS available, received_at AS at, created_at
+       FROM billing_payments
+      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?
+        AND deleted_at IS NULL AND status IN ('matched', 'partially_allocated') AND unallocated_amount > 0
+     UNION ALL
+     SELECT 'credit_memo' AS source_type, id, outstanding AS available, issue_date AS at, created_at
+       FROM billing_invoices
+      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?
+        AND deleted_at IS NULL AND test_run = false AND document_type = 'credit_memo'
+        AND status = 'posted' AND outstanding > 0
+     ORDER BY at ASC, created_at ASC`,
+    [
+      scope.tenantId,
+      scope.organizationId,
+      account.id,
+      account.currencyCode,
+      scope.tenantId,
+      scope.organizationId,
+      account.id,
+      account.currencyCode
+    ]
+  );
+  return (rows ?? []).map((row) => ({
+    source: { type: row.source_type, id: row.id },
+    availableCents: toCents(row.available)
+  }));
+}
+async function applyAccountCredit(tem, scope, account, opts = {}) {
+  const effects = emptyEffects();
+  let sources = await loadCreditSources(tem, scope, account);
+  if (opts.onlySources) {
+    const wanted = new Set(opts.onlySources.map((s) => `${s.type}:${s.id}`));
+    sources = sources.filter((s) => wanted.has(`${s.source.type}:${s.source.id}`));
+  }
+  if (sources.length === 0) return effects;
+  const receivables = await loadOpenReceivables(tem, scope, account);
+  for (const credit of sources) {
+    let available = credit.availableCents;
+    for (const receivable of receivables) {
+      if (available <= 0) break;
+      const take = Math.min(available, receivable.outstandingCents);
+      if (take <= 0) continue;
+      mergeEffects(
+        effects,
+        await allocate(tem, scope, {
+          source: credit.source,
+          invoiceId: receivable.id,
+          amountCents: take,
+          by: opts.by ?? "credit"
+        })
+      );
+      receivable.outstandingCents -= take;
+      available -= take;
+    }
+  }
+  return effects;
+}
+async function getAccountCredit(em, scope, account) {
+  const sources = await loadCreditSources(em, scope, account);
+  return fromCents(sources.reduce((sum, s) => sum + s.availableCents, 0));
+}
+export {
+  allocate,
+  applyAccountCredit,
+  emptyEffects,
+  fromCents,
+  getAccountCredit,
+  loadCreditSources,
+  loadOpenReceivables,
+  mergeEffects,
+  paymentStatusFor,
+  planAllocation,
+  recomputeInvoice,
+  recomputeReceivable,
+  sortOpenReceivables,
+  toCents,
+  unallocate
+};
+//# sourceMappingURL=allocation.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/allocation.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'\nimport { BillingAllocation } from '../data/entities'\nimport type { AllocatedBy, AllocationSourceType } from '../data/validators'\n\n/**\n * Allocation service (Spec C; generalised for Spec D credit memos).\n *\n * An allocation moves money from a SOURCE (`payment` \u2192 `billing_payments`, or\n * `credit_memo` \u2192 a posted credit memo in `billing_invoices`) to a receivable\n * (`invoice` / `debit_memo`). Rules:\n *\n *   - Receivable amounts are RECOMPUTED from \u03A3 active allocations, never\n *     incremented: `paid_total` (payment sources), `credited_total` (credit\n *     memo sources), `outstanding = gross \u2212 paid \u2212 credited`, status\n *     `posted | partially_paid | paid | credited` (P-D2, Spec D P-D3).\n *   - A source's unallocated amount (payment `unallocated_amount`, credit memo\n *     `outstanding`) is decremented with a guarded UPDATE, so it can never go\n *     negative even if a caller forgets the account lock.\n *   - Callers hold `withAccountLock` (P-D3); every function here takes the\n *     transactional EntityManager of that lock.\n *   - Unallocated money of an account is ACCOUNT CREDIT; `applyAccountCredit`\n *     spends it on open receivables, oldest due date first (D12, P-D5).\n *\n * Money is handled in integer cents internally (2 dp documents).\n */\n\n// \u2500\u2500\u2500 Pure helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function toCents(value: string | number | null | undefined): number {\n  const n = typeof value === 'number' ? value : Number.parseFloat(value ?? '0')\n  return Number.isFinite(n) ? Math.round(n * 100) : 0\n}\n\nexport function fromCents(cents: number): string {\n  return (cents / 100).toFixed(4)\n}\n\nexport type OpenReceivable = {\n  id: string\n  outstandingCents: number\n  dueDate: string | null\n  issueDate: string | null\n  number: string\n}\n\n/** Oldest due date first (nulls last), then issue date, then number. */\nexport function sortOpenReceivables<T extends Omit<OpenReceivable, 'outstandingCents'>>(rows: T[]): T[] {\n  return [...rows].sort((a, b) => {\n    if (a.dueDate !== b.dueDate) {\n      if (!a.dueDate) return 1\n      if (!b.dueDate) return -1\n      return a.dueDate < b.dueDate ? -1 : 1\n    }\n    if (a.issueDate !== b.issueDate) {\n      if (!a.issueDate) return 1\n      if (!b.issueDate) return -1\n      return a.issueDate < b.issueDate ? -1 : 1\n    }\n    return a.number.localeCompare(b.number)\n  })\n}\n\n/** Spreads `amountCents` over receivables in the given order, never above outstanding. */\nexport function planAllocation(\n  amountCents: number,\n  receivables: ReadonlyArray<Pick<OpenReceivable, 'id' | 'outstandingCents'>>,\n): { allocations: Array<{ invoiceId: string; amountCents: number }>; remainderCents: number } {\n  let remaining = Math.max(0, amountCents)\n  const allocations: Array<{ invoiceId: string; amountCents: number }> = []\n  for (const receivable of receivables) {\n    if (remaining <= 0) break\n    const take = Math.min(remaining, Math.max(0, receivable.outstandingCents))\n    if (take <= 0) continue\n    allocations.push({ invoiceId: receivable.id, amountCents: take })\n    remaining -= take\n  }\n  return { allocations, remainderCents: remaining }\n}\n\nexport type ReceivableState = {\n  status: string\n  totalGrossCents: number\n  paidCents: number\n  creditedCents: number\n}\n\n/** Paid / credited / outstanding / status of a receivable from its allocation sums. */\nexport function recomputeReceivable(state: ReceivableState): {\n  paidCents: number\n  creditedCents: number\n  outstandingCents: number\n  status: string\n} {\n  const { totalGrossCents: gross, paidCents: paid, creditedCents: credited } = state\n  const outstandingCents = Math.max(0, gross - paid - credited)\n  if (state.status === 'draft') return { paidCents: paid, creditedCents: credited, outstandingCents, status: 'draft' }\n  let status: string\n  if (gross > 0 && outstandingCents === 0) status = credited >= gross ? 'credited' : 'paid'\n  else if (paid + credited > 0) status = 'partially_paid'\n  else status = 'posted'\n  return { paidCents: paid, creditedCents: credited, outstandingCents, status }\n}\n\n/** Payment status from its allocation state (terminal / unmatched states are kept). */\nexport function paymentStatusFor(payment: {\n  status: string\n  billAccountId: string | null | undefined\n  amountCents: number\n  unallocatedCents: number\n}): string {\n  if (payment.status === 'ignored' || payment.status === 'converted_to_topup') return payment.status\n  if (!payment.billAccountId) return 'unmatched'\n  if (payment.unallocatedCents <= 0) return 'allocated'\n  if (payment.unallocatedCents < payment.amountCents) return 'partially_allocated'\n  return 'matched'\n}\n\n// \u2500\u2500\u2500 Effects (emitted by callers after commit) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport type InvoiceStatusChange = { invoiceId: string; from: string; to: string }\n\nexport type AllocationEffects = {\n  created: Array<{ allocationId: string; sourceType: AllocationSourceType; sourceId: string; invoiceId: string; amount: string }>\n  removed: Array<{ allocationId: string; sourceType: AllocationSourceType; sourceId: string; invoiceId: string; amount: string }>\n  invoiceStatusChanges: InvoiceStatusChange[]\n}\n\nexport function emptyEffects(): AllocationEffects {\n  return { created: [], removed: [], invoiceStatusChanges: [] }\n}\n\nexport function mergeEffects(target: AllocationEffects, extra: AllocationEffects): AllocationEffects {\n  target.created.push(...extra.created)\n  target.removed.push(...extra.removed)\n  target.invoiceStatusChanges.push(...extra.invoiceStatusChanges)\n  return target\n}\n\n// \u2500\u2500\u2500 DB service (inside withAccountLock) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport type ArScope = { tenantId: string; organizationId: string }\n\nexport type AllocationSource = { type: AllocationSourceType; id: string }\n\ntype ReceivableRow = {\n  id: string\n  bill_account_id: string\n  currency_code: string\n  status: string\n  document_type: string\n  test_run: boolean\n  total_gross: string\n  outstanding: string\n  due_date: string | null\n  issue_date: string | null\n  number: string\n}\n\ntype SourceRow = {\n  id: string\n  bill_account_id: string | null\n  currency_code: string\n  unallocated: string\n  status: string\n}\n\nconst RECEIVABLE_TYPES = ['invoice', 'debit_memo']\nconst OPEN_STATUSES = ['posted', 'partially_paid']\n\nfunction isoDay(value: unknown): string | null {\n  if (!value) return null\n  if (value instanceof Date) return value.toISOString().slice(0, 10)\n  return String(value).slice(0, 10)\n}\n\nasync function loadReceivable(tem: EntityManager, scope: ArScope, invoiceId: string): Promise<ReceivableRow | null> {\n  const rows = (await tem.execute(\n    `SELECT id, bill_account_id, currency_code, status, document_type, test_run, total_gross, outstanding,\n            due_date, issue_date, number\n       FROM billing_invoices\n      WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`,\n    [invoiceId, scope.tenantId, scope.organizationId],\n  )) as unknown as ReceivableRow[]\n  return rows?.[0] ?? null\n}\n\nasync function loadSource(tem: EntityManager, scope: ArScope, source: AllocationSource): Promise<SourceRow | null> {\n  const sql =\n    source.type === 'payment'\n      ? `SELECT id, bill_account_id, currency_code, unallocated_amount AS unallocated, status\n           FROM billing_payments\n          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`\n      : `SELECT id, bill_account_id, currency_code, outstanding AS unallocated, status\n           FROM billing_invoices\n          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL\n            AND document_type = 'credit_memo'`\n  const rows = (await tem.execute(sql, [source.id, scope.tenantId, scope.organizationId])) as unknown as SourceRow[]\n  return rows?.[0] ?? null\n}\n\n/** Guarded decrement (negative `deltaCents` restores). 0 rows \u2192 insufficient. */\nasync function adjustSourceUnallocated(\n  tem: EntityManager,\n  scope: ArScope,\n  source: AllocationSource,\n  deltaCents: number,\n): Promise<boolean> {\n  const amount = fromCents(Math.abs(deltaCents))\n  if (source.type === 'payment') {\n    const rows = (await tem.execute(\n      deltaCents >= 0\n        ? `UPDATE billing_payments\n              SET unallocated_amount = unallocated_amount - ?::numeric, updated_at = now()\n            WHERE id = ? AND tenant_id = ? AND organization_id = ? AND unallocated_amount >= ?::numeric\n          RETURNING id`\n        : `UPDATE billing_payments\n              SET unallocated_amount = LEAST(amount, unallocated_amount + ?::numeric), updated_at = now()\n            WHERE id = ? AND tenant_id = ? AND organization_id = ?\n          RETURNING id`,\n      deltaCents >= 0\n        ? [amount, source.id, scope.tenantId, scope.organizationId, amount]\n        : [amount, source.id, scope.tenantId, scope.organizationId],\n    )) as unknown as Array<{ id: string }>\n    if (!rows?.length) return false\n    await tem.execute(\n      `UPDATE billing_payments\n          SET status = CASE\n                WHEN unallocated_amount <= 0 THEN 'allocated'\n                WHEN unallocated_amount < amount THEN 'partially_allocated'\n                ELSE 'matched' END\n        WHERE id = ? AND status IN ('matched', 'partially_allocated', 'allocated')`,\n      [source.id],\n    )\n    return true\n  }\n  // Credit memo: its `outstanding` is the unallocated credit (Spec D, P-D5).\n  const rows = (await tem.execute(\n    deltaCents >= 0\n      ? `UPDATE billing_invoices\n            SET outstanding = outstanding - ?::numeric,\n                status = CASE WHEN outstanding - ?::numeric <= 0 THEN 'paid' ELSE 'posted' END,\n                updated_at = now()\n          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND document_type = 'credit_memo'\n            AND outstanding >= ?::numeric\n        RETURNING id`\n      : `UPDATE billing_invoices\n            SET outstanding = LEAST(total_gross, outstanding + ?::numeric), status = 'posted', updated_at = now()\n          WHERE id = ? AND tenant_id = ? AND organization_id = ? AND document_type = 'credit_memo'\n        RETURNING id`,\n    deltaCents >= 0\n      ? [amount, amount, source.id, scope.tenantId, scope.organizationId, amount]\n      : [amount, source.id, scope.tenantId, scope.organizationId],\n  )) as unknown as Array<{ id: string }>\n  return Boolean(rows?.length)\n}\n\n/** Recomputes paid / credited / outstanding / status of a receivable from its active allocations. */\nexport async function recomputeInvoice(\n  tem: EntityManager,\n  scope: ArScope,\n  invoiceId: string,\n): Promise<InvoiceStatusChange | null> {\n  const invoice = await loadReceivable(tem, scope, invoiceId)\n  if (!invoice || !RECEIVABLE_TYPES.includes(invoice.document_type)) return null\n  const sums = (await tem.execute(\n    `SELECT COALESCE(SUM(amount) FILTER (WHERE source_type = 'payment'), 0) AS paid,\n            COALESCE(SUM(amount) FILTER (WHERE source_type = 'credit_memo'), 0) AS credited\n       FROM billing_allocations\n      WHERE invoice_id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL`,\n    [invoiceId, scope.tenantId, scope.organizationId],\n  )) as unknown as Array<{ paid: string; credited: string }>\n  const next = recomputeReceivable({\n    status: invoice.status,\n    totalGrossCents: toCents(invoice.total_gross),\n    paidCents: toCents(sums?.[0]?.paid),\n    creditedCents: toCents(sums?.[0]?.credited),\n  })\n  await tem.execute(\n    `UPDATE billing_invoices\n        SET paid_total = ?::numeric, credited_total = ?::numeric, outstanding = ?::numeric, status = ?, updated_at = now()\n      WHERE id = ? AND tenant_id = ? AND organization_id = ?`,\n    [\n      fromCents(next.paidCents),\n      fromCents(next.creditedCents),\n      fromCents(next.outstandingCents),\n      next.status,\n      invoiceId,\n      scope.tenantId,\n      scope.organizationId,\n    ],\n  )\n  return next.status !== invoice.status ? { invoiceId, from: invoice.status, to: next.status } : null\n}\n\nexport async function allocate(\n  tem: EntityManager,\n  scope: ArScope,\n  params: { source: AllocationSource; invoiceId: string; amountCents: number; by: AllocatedBy; userId?: string | null },\n): Promise<AllocationEffects> {\n  const effects = emptyEffects()\n  if (params.amountCents <= 0) {\n    throw new CrudHttpError(400, { error: 'Allocation amount must be positive', code: 'billing.allocation.invalid_amount' })\n  }\n  const [source, invoice] = await Promise.all([\n    loadSource(tem, scope, params.source),\n    loadReceivable(tem, scope, params.invoiceId),\n  ])\n  if (!source) throw new CrudHttpError(404, { error: 'Payment source not found', code: 'billing.allocation.source_missing' })\n  if (!invoice) throw new CrudHttpError(404, { error: 'Invoice not found', code: 'billing.allocation.invoice_missing' })\n  if (!source.bill_account_id || source.bill_account_id !== invoice.bill_account_id) {\n    throw new CrudHttpError(409, {\n      error: 'Payment and invoice belong to different accounts',\n      code: 'billing.allocation.account_mismatch',\n    })\n  }\n  if (source.currency_code !== invoice.currency_code) {\n    throw new CrudHttpError(409, { error: 'Currencies differ', code: 'billing.allocation.currency_mismatch' })\n  }\n  if (\n    invoice.test_run ||\n    !RECEIVABLE_TYPES.includes(invoice.document_type) ||\n    !OPEN_STATUSES.includes(invoice.status)\n  ) {\n    throw new CrudHttpError(409, { error: 'Invoice is not open for payment', code: 'billing.allocation.invoice_not_open' })\n  }\n  if (params.amountCents > toCents(invoice.outstanding)) {\n    throw new CrudHttpError(409, {\n      error: 'Allocation exceeds the invoice outstanding amount',\n      code: 'billing.allocation.exceeds_outstanding',\n    })\n  }\n  const decremented = await adjustSourceUnallocated(tem, scope, params.source, params.amountCents)\n  if (!decremented) {\n    throw new CrudHttpError(409, {\n      error: 'Not enough unallocated amount',\n      code: 'billing.allocation.insufficient_unallocated',\n    })\n  }\n  const now = new Date()\n  const row = tem.create(BillingAllocation, {\n    organizationId: scope.organizationId,\n    tenantId: scope.tenantId,\n    sourceType: params.source.type,\n    sourceId: params.source.id,\n    invoiceId: params.invoiceId,\n    billAccountId: invoice.bill_account_id,\n    amount: fromCents(params.amountCents),\n    currencyCode: invoice.currency_code,\n    allocatedBy: params.by,\n    userId: params.userId ?? null,\n    createdAt: now,\n    updatedAt: now,\n  })\n  tem.persist(row)\n  await tem.flush()\n  effects.created.push({\n    allocationId: row.id,\n    sourceType: params.source.type,\n    sourceId: params.source.id,\n    invoiceId: params.invoiceId,\n    amount: row.amount,\n  })\n  const change = await recomputeInvoice(tem, scope, params.invoiceId)\n  if (change) effects.invoiceStatusChanges.push(change)\n  return effects\n}\n\nexport async function unallocate(\n  tem: EntityManager,\n  scope: ArScope,\n  params: { allocationId: string; userId?: string | null },\n): Promise<AllocationEffects> {\n  const effects = emptyEffects()\n  const rows = (await tem.execute(\n    `UPDATE billing_allocations\n        SET deleted_at = now(), updated_at = now(), deallocated_by_user_id = ?\n      WHERE id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL\n    RETURNING id, source_type, source_id, invoice_id, amount`,\n    [params.userId ?? null, params.allocationId, scope.tenantId, scope.organizationId],\n  )) as unknown as Array<{ id: string; source_type: AllocationSourceType; source_id: string; invoice_id: string; amount: string }>\n  const removed = rows?.[0]\n  if (!removed) throw new CrudHttpError(404, { error: 'Allocation not found', code: 'billing.allocation.not_found' })\n  await adjustSourceUnallocated(tem, scope, { type: removed.source_type, id: removed.source_id }, -toCents(removed.amount))\n  effects.removed.push({\n    allocationId: removed.id,\n    sourceType: removed.source_type,\n    sourceId: removed.source_id,\n    invoiceId: removed.invoice_id,\n    amount: removed.amount,\n  })\n  const change = await recomputeInvoice(tem, scope, removed.invoice_id)\n  if (change) effects.invoiceStatusChanges.push(change)\n  return effects\n}\n\n/** Open receivables of an account in auto-apply order. */\nexport async function loadOpenReceivables(\n  tem: EntityManager,\n  scope: ArScope,\n  account: { id: string; currencyCode: string },\n  onlyIds?: string[],\n): Promise<OpenReceivable[]> {\n  const params: unknown[] = [scope.tenantId, scope.organizationId, account.id, account.currencyCode]\n  let idFilter = ''\n  if (onlyIds && onlyIds.length > 0) {\n    idFilter = ` AND id = ANY(?::uuid[])`\n    params.push(`{${onlyIds.join(',')}}`)\n  }\n  const rows = (await tem.execute(\n    `SELECT id, outstanding, due_date, issue_date, number\n       FROM billing_invoices\n      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?\n        AND deleted_at IS NULL AND test_run = false\n        AND document_type IN ('invoice', 'debit_memo')\n        AND status IN ('posted', 'partially_paid')\n        AND outstanding > 0${idFilter}`,\n    params,\n  )) as unknown as Array<{ id: string; outstanding: string; due_date: unknown; issue_date: unknown; number: string }>\n  return sortOpenReceivables(\n    (rows ?? []).map((row) => ({\n      id: row.id,\n      outstandingCents: toCents(row.outstanding),\n      dueDate: isoDay(row.due_date),\n      issueDate: isoDay(row.issue_date),\n      number: row.number,\n    })),\n  )\n}\n\n/** Credit sources of an account (unallocated payments + open credit memos), oldest first. */\nexport async function loadCreditSources(\n  tem: EntityManager,\n  scope: ArScope,\n  account: { id: string; currencyCode: string },\n): Promise<Array<{ source: AllocationSource; availableCents: number }>> {\n  const rows = (await tem.execute(\n    `SELECT 'payment' AS source_type, id, unallocated_amount AS available, received_at AS at, created_at\n       FROM billing_payments\n      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?\n        AND deleted_at IS NULL AND status IN ('matched', 'partially_allocated') AND unallocated_amount > 0\n     UNION ALL\n     SELECT 'credit_memo' AS source_type, id, outstanding AS available, issue_date AS at, created_at\n       FROM billing_invoices\n      WHERE tenant_id = ? AND organization_id = ? AND bill_account_id = ? AND currency_code = ?\n        AND deleted_at IS NULL AND test_run = false AND document_type = 'credit_memo'\n        AND status = 'posted' AND outstanding > 0\n     ORDER BY at ASC, created_at ASC`,\n    [\n      scope.tenantId,\n      scope.organizationId,\n      account.id,\n      account.currencyCode,\n      scope.tenantId,\n      scope.organizationId,\n      account.id,\n      account.currencyCode,\n    ],\n  )) as unknown as Array<{ source_type: AllocationSourceType; id: string; available: string }>\n  return (rows ?? []).map((row) => ({\n    source: { type: row.source_type, id: row.id },\n    availableCents: toCents(row.available),\n  }))\n}\n\n/**\n * Spends the account's credit on its open receivables (D12): sources oldest\n * first, receivables oldest due first. `onlySources` restricts the spend\n * (e.g. the payment just imported); default = all credit of the account.\n */\nexport async function applyAccountCredit(\n  tem: EntityManager,\n  scope: ArScope,\n  account: { id: string; currencyCode: string },\n  opts: { onlySources?: AllocationSource[]; by?: AllocatedBy } = {},\n): Promise<AllocationEffects> {\n  const effects = emptyEffects()\n  let sources = await loadCreditSources(tem, scope, account)\n  if (opts.onlySources) {\n    const wanted = new Set(opts.onlySources.map((s) => `${s.type}:${s.id}`))\n    sources = sources.filter((s) => wanted.has(`${s.source.type}:${s.source.id}`))\n  }\n  if (sources.length === 0) return effects\n  const receivables = await loadOpenReceivables(tem, scope, account)\n  for (const credit of sources) {\n    let available = credit.availableCents\n    for (const receivable of receivables) {\n      if (available <= 0) break\n      const take = Math.min(available, receivable.outstandingCents)\n      if (take <= 0) continue\n      mergeEffects(\n        effects,\n        await allocate(tem, scope, {\n          source: credit.source,\n          invoiceId: receivable.id,\n          amountCents: take,\n          by: opts.by ?? 'credit',\n        }),\n      )\n      receivable.outstandingCents -= take\n      available -= take\n    }\n  }\n  return effects\n}\n\n/** Unapplied credit of an account (\u03A3 unallocated payments + open credit memos). */\nexport async function getAccountCredit(\n  em: EntityManager,\n  scope: ArScope,\n  account: { id: string; currencyCode: string },\n): Promise<string> {\n  const sources = await loadCreditSources(em, scope, account)\n  return fromCents(sources.reduce((sum, s) => sum + s.availableCents, 0))\n}\n"],
+  "mappings": "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",
+  "names": ["rows"]
+}

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

@@ -0,0 +1,22 @@
+import { emitBillingEvent } from "../events.js";
+async function emitAllocationEffects(scope, effects) {
+  for (const row of effects.created) {
+    if (row.sourceType !== "payment") continue;
+    await emitBillingEvent("billing.payment.allocated", { ...scope, paymentId: row.sourceId, invoiceId: row.invoiceId, allocationId: row.allocationId, amount: row.amount });
+  }
+  for (const row of effects.removed) {
+    if (row.sourceType !== "payment") continue;
+    await emitBillingEvent("billing.payment.unallocated", { ...scope, paymentId: row.sourceId, invoiceId: row.invoiceId, allocationId: row.allocationId, amount: row.amount });
+  }
+  const finalStatus = /* @__PURE__ */ new Map();
+  for (const change of effects.invoiceStatusChanges) finalStatus.set(change.invoiceId, change.to);
+  for (const [invoiceId, status] of finalStatus) {
+    if (status === "paid") await emitBillingEvent("billing.invoice.paid", { ...scope, invoiceId });
+    else if (status === "partially_paid") await emitBillingEvent("billing.invoice.partially_paid", { ...scope, invoiceId });
+    else if (status === "credited") await emitBillingEvent("billing.invoice.credited", { ...scope, invoiceId });
+  }
+}
+export {
+  emitAllocationEffects
+};
+//# sourceMappingURL=allocationEvents.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/billing/lib/allocationEvents.ts"],
+  "sourcesContent": ["import { emitBillingEvent } from '../events'\nimport type { AllocationEffects, ArScope } from './allocation'\n\n/**\n * Emits the events of an allocation change AFTER the transaction committed\n * (Spec C): one `billing.payment.allocated` / `unallocated` per payment\n * allocation row, and `billing.invoice.paid` / `partially_paid` / `credited` (Spec D) per receivable whose status changed.\n */\nexport async function emitAllocationEffects(scope: ArScope, effects: AllocationEffects): Promise<void> {\n  for (const row of effects.created) {\n    if (row.sourceType !== 'payment') continue\n    await emitBillingEvent('billing.payment.allocated', { ...scope, paymentId: row.sourceId, invoiceId: row.invoiceId, allocationId: row.allocationId, amount: row.amount })\n  }\n  for (const row of effects.removed) {\n    if (row.sourceType !== 'payment') continue\n    await emitBillingEvent('billing.payment.unallocated', { ...scope, paymentId: row.sourceId, invoiceId: row.invoiceId, allocationId: row.allocationId, amount: row.amount })\n  }\n  // Last transition per invoice wins (several allocations can touch one invoice).\n  const finalStatus = new Map<string, string>()\n  for (const change of effects.invoiceStatusChanges) finalStatus.set(change.invoiceId, change.to)\n  for (const [invoiceId, status] of finalStatus) {\n    if (status === 'paid') await emitBillingEvent('billing.invoice.paid', { ...scope, invoiceId })\n    else if (status === 'partially_paid') await emitBillingEvent('billing.invoice.partially_paid', { ...scope, invoiceId })\n    else if (status === 'credited') await emitBillingEvent('billing.invoice.credited', { ...scope, invoiceId })\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,wBAAwB;AAQjC,eAAsB,sBAAsB,OAAgB,SAA2C;AACrG,aAAW,OAAO,QAAQ,SAAS;AACjC,QAAI,IAAI,eAAe,UAAW;AAClC,UAAM,iBAAiB,6BAA6B,EAAE,GAAG,OAAO,WAAW,IAAI,UAAU,WAAW,IAAI,WAAW,cAAc,IAAI,cAAc,QAAQ,IAAI,OAAO,CAAC;AAAA,EACzK;AACA,aAAW,OAAO,QAAQ,SAAS;AACjC,QAAI,IAAI,eAAe,UAAW;AAClC,UAAM,iBAAiB,+BAA+B,EAAE,GAAG,OAAO,WAAW,IAAI,UAAU,WAAW,IAAI,WAAW,cAAc,IAAI,cAAc,QAAQ,IAAI,OAAO,CAAC;AAAA,EAC3K;AAEA,QAAM,cAAc,oBAAI,IAAoB;AAC5C,aAAW,UAAU,QAAQ,qBAAsB,aAAY,IAAI,OAAO,WAAW,OAAO,EAAE;AAC9F,aAAW,CAAC,WAAW,MAAM,KAAK,aAAa;AAC7C,QAAI,WAAW,OAAQ,OAAM,iBAAiB,wBAAwB,EAAE,GAAG,OAAO,UAAU,CAAC;AAAA,aACpF,WAAW,iBAAkB,OAAM,iBAAiB,kCAAkC,EAAE,GAAG,OAAO,UAAU,CAAC;AAAA,aAC7G,WAAW,WAAY,OAAM,iBAAiB,4BAA4B,EAAE,GAAG,OAAO,UAAU,CAAC;AAAA,EAC5G;AACF;",
+  "names": []
+}

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

@@ -90,12 +90,26 @@ function isCycleDue(nextBillDate, asOfDate) {
   const b = cloneAtMidnight(asOfDate).getTime();
   return a <= b;
 }
+function shiftCycles(anchor, cycle, k) {
+  const base = cloneAtMidnight(anchor);
+  switch (cycle) {
+    case "weekly":
+      return addDays(base, 7 * k);
+    case "monthly":
+      return shiftMonths(base, k);
+    case "quarterly":
+      return shiftMonths(base, 3 * k);
+    case "annually":
+      return shiftYears(base, k);
+  }
+}
 export {
   addDays,
   advanceNextBillDate,
   cloneAtMidnight,
   cycleContaining,
   deriveBillPeriod,
-  isCycleDue
+  isCycleDue,
+  shiftCycles
 };
 //# sourceMappingURL=billPeriod.js.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/lib/billPeriod.ts"],
-  "sourcesContent": ["import type { BillCycle } from '../data/validators'\n\n/**\n * Calendar-aware bill-period arithmetic.\n *\n * The spec mandates calendar units (Postgres `interval`-equivalent),\n * NOT raw day counts \u2014 months and quarters have variable length, so a\n * 30-day subtraction would skew the period boundary every February.\n *\n * All helpers here treat input dates as midnight in the host timezone\n * (the way MikroORM's `date`-column round-trip lands them). Date math\n * via `Date.setMonth` / `setDate` is the right primitive: Postgres'\n * `+ interval '1 month'` and JS's `setMonth(+1)` agree on the\n * \"clamp to month end\" behaviour (e.g. Jan 31 + 1 month \u2192 Feb 28/29).\n *\n * Examples (all from the spec's reference table):\n *\n *   monthly  next=2026-06-01 \u2192 period=2026-05-01..2026-05-31\n *   monthly  next=2026-03-01 \u2192 period=2026-02-01..2026-02-28\n *   monthly  next=2024-03-01 \u2192 period=2024-02-01..2024-02-29 (leap)\n *   quarterly next=2026-07-01 \u2192 period=2026-04-01..2026-06-30\n *   weekly   next=2026-05-04 (Mon) \u2192 period=2026-04-27..2026-05-03\n */\n\nexport type BillPeriod = {\n  /** Inclusive \u2014 first day of the cycle being billed. */\n  periodStart: Date\n  /** Inclusive \u2014 last day of the cycle (`nextBillDate - 1 day`). */\n  periodEnd: Date\n}\n\nfunction cloneAtMidnight(date: Date | string | number): Date {\n  // MikroORM hands `date`-typed columns back as 'YYYY-MM-DD' strings,\n  // not Date objects \u2014 coerce so every helper here is input-tolerant\n  // whether called from the engine (DB rows) or unit tests (plain\n  // `new Date('2026-06-01')` values).\n  const result = new Date(date instanceof Date ? date.getTime() : date)\n  result.setUTCHours(0, 0, 0, 0)\n  return result\n}\n\nfunction subtractDays(date: Date, days: number): Date {\n  const result = cloneAtMidnight(date)\n  result.setUTCDate(result.getUTCDate() - days)\n  return result\n}\n\nfunction addDays(date: Date, days: number): Date {\n  const result = cloneAtMidnight(date)\n  result.setUTCDate(result.getUTCDate() + days)\n  return result\n}\n\nfunction lastDayOfMonthUTC(year: number, monthZeroIndexed: number): number {\n  // Date(Date.UTC(y, m+1, 0)) returns the last day of month m. The\n  // zero-day-of-next-month trick is the canonical JS idiom.\n  return new Date(Date.UTC(year, monthZeroIndexed + 1, 0)).getUTCDate()\n}\n\nfunction shiftMonths(date: Date, deltaMonths: number): Date {\n  // JS `setUTCMonth` does NOT clamp when the target month is shorter\n  // than the source day \u2014 it overflows (Jan 31 + 1 month \u2192 Mar 3\n  // because Feb 31 spills over). Postgres `+ interval '1 month'` and\n  // the spec both clamp, so we replicate that: shift the month while\n  // pinned to day 1, then restore the original day clamped to the new\n  // month's last day.\n  const result = cloneAtMidnight(date)\n  const day = result.getUTCDate()\n  result.setUTCDate(1)\n  result.setUTCMonth(result.getUTCMonth() + deltaMonths)\n  const lastDay = lastDayOfMonthUTC(result.getUTCFullYear(), result.getUTCMonth())\n  result.setUTCDate(Math.min(day, lastDay))\n  return result\n}\n\nfunction shiftYears(date: Date, deltaYears: number): Date {\n  // Same clamp story for Feb 29 in non-leap years.\n  const result = cloneAtMidnight(date)\n  const day = result.getUTCDate()\n  result.setUTCDate(1)\n  result.setUTCFullYear(result.getUTCFullYear() + deltaYears)\n  const lastDay = lastDayOfMonthUTC(result.getUTCFullYear(), result.getUTCMonth())\n  result.setUTCDate(Math.min(day, lastDay))\n  return result\n}\n\nfunction subtractCycle(date: Date, cycle: BillCycle): Date {\n  switch (cycle) {\n    case 'weekly': {\n      const result = cloneAtMidnight(date)\n      result.setUTCDate(result.getUTCDate() - 7)\n      return result\n    }\n    case 'monthly':\n      return shiftMonths(date, -1)\n    case 'quarterly':\n      return shiftMonths(date, -3)\n    case 'annually':\n      return shiftYears(date, -1)\n  }\n}\n\nfunction addCycle(date: Date, cycle: BillCycle): Date {\n  switch (cycle) {\n    case 'weekly': {\n      const result = cloneAtMidnight(date)\n      result.setUTCDate(result.getUTCDate() + 7)\n      return result\n    }\n    case 'monthly':\n      return shiftMonths(date, 1)\n    case 'quarterly':\n      return shiftMonths(date, 3)\n    case 'annually':\n      return shiftYears(date, 1)\n  }\n}\n\n/**\n * Compute the bill period for the cycle that `nextBillDate` marks the\n * START of the *next* one. So `periodEnd = nextBillDate - 1 day` and\n * `periodStart = nextBillDate - cycle`.\n */\nexport function deriveBillPeriod(nextBillDate: Date, cycle: BillCycle): BillPeriod {\n  const periodEnd = subtractDays(nextBillDate, 1)\n  const periodStart = subtractCycle(nextBillDate, cycle)\n  return { periodStart, periodEnd }\n}\n\n/**\n * Advance `nextBillDate` by one cycle. Used by the engine after a\n * successful real-mode account run.\n */\nexport function advanceNextBillDate(currentNextBillDate: Date, cycle: BillCycle): Date {\n  return addCycle(currentNextBillDate, cycle)\n}\n\n/**\n * The bill cycle that `target` falls into, given any known cycle\n * boundary `anchor` (e.g. an account's `nextBillDate`). Returned\n * `periodStart` is inclusive, `periodEnd` is the last day of the cycle.\n *\n * Used by the cpq-billing-connector to prorate a mid-cycle amendment \u2014\n * the connector owns the billing-cycle knowledge, CPQ does not.\n */\nexport function cycleContaining(\n  anchor: Date | string | number,\n  cycle: BillCycle,\n  target: Date | string | number,\n): BillPeriod {\n  const targetMs = cloneAtMidnight(target).getTime()\n  let start = cloneAtMidnight(anchor)\n  let guard = 0\n  // Walk forward while the cycle starting at `start` ends before target.\n  while (addCycle(start, cycle).getTime() <= targetMs && guard++ < 600) {\n    start = addCycle(start, cycle)\n  }\n  guard = 0\n  // Walk backward while `start` itself is after target.\n  while (start.getTime() > targetMs && guard++ < 600) {\n    start = subtractCycle(start, cycle)\n  }\n  return { periodStart: start, periodEnd: subtractDays(addCycle(start, cycle), 1) }\n}\n\n/**\n * True when the account still has cycles to bill on or before\n * `asOfDate`. The engine uses this to drive the catch-up loop.\n */\nexport function isCycleDue(nextBillDate: Date, asOfDate: Date): boolean {\n  const a = cloneAtMidnight(nextBillDate).getTime()\n  const b = cloneAtMidnight(asOfDate).getTime()\n  return a <= b\n}\n\n/**\n * Test seam: re-export the day-add helper so the engine can compute\n * `bill_period_end + 1 day` consistently with this module's calendar\n * semantics (avoids drift between engine code and period-math tests).\n */\nexport { addDays, cloneAtMidnight }\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { BillCycle } from '../data/validators'\n\n/**\n * Calendar-aware bill-period arithmetic.\n *\n * The spec mandates calendar units (Postgres `interval`-equivalent),\n * NOT raw day counts \u2014 months and quarters have variable length, so a\n * 30-day subtraction would skew the period boundary every February.\n *\n * All helpers here treat input dates as midnight in the host timezone\n * (the way MikroORM's `date`-column round-trip lands them). Date math\n * via `Date.setMonth` / `setDate` is the right primitive: Postgres'\n * `+ interval '1 month'` and JS's `setMonth(+1)` agree on the\n * \"clamp to month end\" behaviour (e.g. Jan 31 + 1 month \u2192 Feb 28/29).\n *\n * Examples (all from the spec's reference table):\n *\n *   monthly  next=2026-06-01 \u2192 period=2026-05-01..2026-05-31\n *   monthly  next=2026-03-01 \u2192 period=2026-02-01..2026-02-28\n *   monthly  next=2024-03-01 \u2192 period=2024-02-01..2024-02-29 (leap)\n *   quarterly next=2026-07-01 \u2192 period=2026-04-01..2026-06-30\n *   weekly   next=2026-05-04 (Mon) \u2192 period=2026-04-27..2026-05-03\n */\n\nexport type BillPeriod = {\n  /** Inclusive \u2014 first day of the cycle being billed. */\n  periodStart: Date\n  /** Inclusive \u2014 last day of the cycle (`nextBillDate - 1 day`). */\n  periodEnd: Date\n}\n\nfunction cloneAtMidnight(date: Date | string | number): Date {\n  // MikroORM hands `date`-typed columns back as 'YYYY-MM-DD' strings,\n  // not Date objects \u2014 coerce so every helper here is input-tolerant\n  // whether called from the engine (DB rows) or unit tests (plain\n  // `new Date('2026-06-01')` values).\n  const result = new Date(date instanceof Date ? date.getTime() : date)\n  result.setUTCHours(0, 0, 0, 0)\n  return result\n}\n\nfunction subtractDays(date: Date, days: number): Date {\n  const result = cloneAtMidnight(date)\n  result.setUTCDate(result.getUTCDate() - days)\n  return result\n}\n\nfunction addDays(date: Date, days: number): Date {\n  const result = cloneAtMidnight(date)\n  result.setUTCDate(result.getUTCDate() + days)\n  return result\n}\n\nfunction lastDayOfMonthUTC(year: number, monthZeroIndexed: number): number {\n  // Date(Date.UTC(y, m+1, 0)) returns the last day of month m. The\n  // zero-day-of-next-month trick is the canonical JS idiom.\n  return new Date(Date.UTC(year, monthZeroIndexed + 1, 0)).getUTCDate()\n}\n\nfunction shiftMonths(date: Date, deltaMonths: number): Date {\n  // JS `setUTCMonth` does NOT clamp when the target month is shorter\n  // than the source day \u2014 it overflows (Jan 31 + 1 month \u2192 Mar 3\n  // because Feb 31 spills over). Postgres `+ interval '1 month'` and\n  // the spec both clamp, so we replicate that: shift the month while\n  // pinned to day 1, then restore the original day clamped to the new\n  // month's last day.\n  const result = cloneAtMidnight(date)\n  const day = result.getUTCDate()\n  result.setUTCDate(1)\n  result.setUTCMonth(result.getUTCMonth() + deltaMonths)\n  const lastDay = lastDayOfMonthUTC(result.getUTCFullYear(), result.getUTCMonth())\n  result.setUTCDate(Math.min(day, lastDay))\n  return result\n}\n\nfunction shiftYears(date: Date, deltaYears: number): Date {\n  // Same clamp story for Feb 29 in non-leap years.\n  const result = cloneAtMidnight(date)\n  const day = result.getUTCDate()\n  result.setUTCDate(1)\n  result.setUTCFullYear(result.getUTCFullYear() + deltaYears)\n  const lastDay = lastDayOfMonthUTC(result.getUTCFullYear(), result.getUTCMonth())\n  result.setUTCDate(Math.min(day, lastDay))\n  return result\n}\n\nfunction subtractCycle(date: Date, cycle: BillCycle): Date {\n  switch (cycle) {\n    case 'weekly': {\n      const result = cloneAtMidnight(date)\n      result.setUTCDate(result.getUTCDate() - 7)\n      return result\n    }\n    case 'monthly':\n      return shiftMonths(date, -1)\n    case 'quarterly':\n      return shiftMonths(date, -3)\n    case 'annually':\n      return shiftYears(date, -1)\n  }\n}\n\nfunction addCycle(date: Date, cycle: BillCycle): Date {\n  switch (cycle) {\n    case 'weekly': {\n      const result = cloneAtMidnight(date)\n      result.setUTCDate(result.getUTCDate() + 7)\n      return result\n    }\n    case 'monthly':\n      return shiftMonths(date, 1)\n    case 'quarterly':\n      return shiftMonths(date, 3)\n    case 'annually':\n      return shiftYears(date, 1)\n  }\n}\n\n/**\n * Compute the bill period for the cycle that `nextBillDate` marks the\n * START of the *next* one. So `periodEnd = nextBillDate - 1 day` and\n * `periodStart = nextBillDate - cycle`.\n */\nexport function deriveBillPeriod(nextBillDate: Date, cycle: BillCycle): BillPeriod {\n  const periodEnd = subtractDays(nextBillDate, 1)\n  const periodStart = subtractCycle(nextBillDate, cycle)\n  return { periodStart, periodEnd }\n}\n\n/**\n * Advance `nextBillDate` by one cycle. Used by the engine after a\n * successful real-mode account run.\n */\nexport function advanceNextBillDate(currentNextBillDate: Date, cycle: BillCycle): Date {\n  return addCycle(currentNextBillDate, cycle)\n}\n\n/**\n * The bill cycle that `target` falls into, given any known cycle\n * boundary `anchor` (e.g. an account's `nextBillDate`). Returned\n * `periodStart` is inclusive, `periodEnd` is the last day of the cycle.\n *\n * Used by the cpq-billing-connector to prorate a mid-cycle amendment \u2014\n * the connector owns the billing-cycle knowledge, CPQ does not.\n */\nexport function cycleContaining(\n  anchor: Date | string | number,\n  cycle: BillCycle,\n  target: Date | string | number,\n): BillPeriod {\n  const targetMs = cloneAtMidnight(target).getTime()\n  let start = cloneAtMidnight(anchor)\n  let guard = 0\n  // Walk forward while the cycle starting at `start` ends before target.\n  while (addCycle(start, cycle).getTime() <= targetMs && guard++ < 600) {\n    start = addCycle(start, cycle)\n  }\n  guard = 0\n  // Walk backward while `start` itself is after target.\n  while (start.getTime() > targetMs && guard++ < 600) {\n    start = subtractCycle(start, cycle)\n  }\n  return { periodStart: start, periodEnd: subtractDays(addCycle(start, cycle), 1) }\n}\n\n/**\n * True when the account still has cycles to bill on or before\n * `asOfDate`. The engine uses this to drive the catch-up loop.\n */\nexport function isCycleDue(nextBillDate: Date, asOfDate: Date): boolean {\n  const a = cloneAtMidnight(nextBillDate).getTime()\n  const b = cloneAtMidnight(asOfDate).getTime()\n  return a <= b\n}\n\n/**\n * The cycle boundary `k` cycles away from `anchor` (k may be negative),\n * computed directly from the anchor \u2014 never by chaining single steps \u2014 so\n * month-end clamping does not drift (Jan 31 \u2192 Feb 28 \u2192 Mar 31, not Mar 28).\n */\nexport function shiftCycles(anchor: Date | string | number, cycle: BillCycle, k: number): Date {\n  const base = cloneAtMidnight(anchor)\n  switch (cycle) {\n    case 'weekly':\n      return addDays(base, 7 * k)\n    case 'monthly':\n      return shiftMonths(base, k)\n    case 'quarterly':\n      return shiftMonths(base, 3 * k)\n    case 'annually':\n      return shiftYears(base, k)\n  }\n}\n\n/**\n * Test seam: re-export the day-add helper so the engine can compute\n * `bill_period_end + 1 day` consistently with this module's calendar\n * semantics (avoids drift between engine code and period-math tests).\n */\nexport { addDays, cloneAtMidnight }\n"],
+  "mappings": "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",
   "names": []
 }