@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,76 @@
+import { lineVat, type PriceBasis } from './lineAmounts'
+import { round2 } from './vat'
+
+/**
+ * Prepaid tax point (Spec F, F-D3 / P-D10) — how much a prepaid charge takes
+ * from the balance. Shared by the Bill Run period close and real-time usage
+ * consumption so the two paths can never drift apart.
+ *
+ *   - `topup` (default): VAT was charged on the top-up receipt, so the
+ *     balance holds VAT-inclusive money and the item amount is debited as
+ *     entered (`debit = net = amount`, `tax = 0`). The item's VAT rate and
+ *     price basis do not apply.
+ *   - `consumption`: the receipt carried no VAT; each debit is the line's
+ *     gross at the item's rate and basis (`lineVat`).
+ */
+
+export type PrepaidTaxPoint = 'topup' | 'consumption'
+
+export type PrepaidDebitInput = {
+  /** Extended line amount on `priceBasis` (negative for credits). */
+  lineAmount: number | string
+  priceBasis: PriceBasis
+  /** Item VAT rate in percent. */
+  taxRate: number | string
+  taxPoint: PrepaidTaxPoint
+}
+
+export type PrepaidDebit = {
+  /** What leaves the balance (positive charge, negative credit back). */
+  debit: number
+  net: number
+  tax: number
+  /** VAT rate applied (0 in `topup` mode). */
+  taxRate: number
+}
+
+function toNumber(value: number | string): number {
+  const n = typeof value === 'number' ? value : Number.parseFloat(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+export function resolvePrepaidDebit(input: PrepaidDebitInput): PrepaidDebit {
+  if (input.taxPoint === 'topup') {
+    const amount = round2(toNumber(input.lineAmount))
+    return { debit: amount, net: amount, tax: 0, taxRate: 0 }
+  }
+  const rate = Math.max(0, toNumber(input.taxRate))
+  const vat = lineVat({ amount: input.lineAmount, priceBasis: input.priceBasis, taxRate: rate })
+  return { debit: vat.gross, net: vat.net, tax: vat.tax, taxRate: rate }
+}
+
+export type VatSummaryRow = { rate: string; net: string; tax: string; gross: string }
+
+/**
+ * Per-rate VAT summary of a set of prepaid debits (statement `vat_summary`).
+ * Empty when no debit carried VAT information (`topup` mode).
+ */
+export function buildVatSummary(debits: ReadonlyArray<PrepaidDebit>, taxPoint: PrepaidTaxPoint): VatSummaryRow[] {
+  if (taxPoint === 'topup') return []
+  const byRate = new Map<number, { net: number; tax: number; gross: number }>()
+  for (const debit of debits) {
+    const row = byRate.get(debit.taxRate) ?? { net: 0, tax: 0, gross: 0 }
+    row.net = round2(row.net + debit.net)
+    row.tax = round2(row.tax + debit.tax)
+    row.gross = round2(row.gross + debit.debit)
+    byRate.set(debit.taxRate, row)
+  }
+  return Array.from(byRate.entries())
+    .sort(([a], [b]) => b - a)
+    .map(([rate, row]) => ({
+      rate: String(rate),
+      net: row.net.toFixed(4),
+      tax: row.tax.toFixed(4),
+      gross: row.gross.toFixed(4),
+    }))
+}

package/src/modules/billing/lib/seeds/demo.ts

@@ -1,5 +1,8 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { BillingAccount, BillingItem, BillingAccountUsage } from '../../data/entities'
+import type { CustomerKind } from '../../data/validators'
+import type { InvoiceLanguageCode } from '../invoiceLanguages'
+import { DEFAULT_DEMO_SELLER, applySellerDefaults } from './sellerSettings'
 
 /**
  * Self-contained billing test-data seed.
@@ -10,9 +13,13 @@ import { BillingAccount, BillingItem, BillingAccountUsage } from '../../data/ent
  * so re-running is a no-op rather than a duplicate.
  *
  * The accounts are dated so they are immediately billable: `next_bill_date`
- * is the 1st of the current month, which makes a Bill Run with the default
- * (today's) as-of date produce an invoice for the previous month — the usage
- * record is seeded into exactly that period.
+ * is the 1st of the current month. A Bill Run with the default (today's)
+ * as-of date then shows every Spec A behaviour on one invoice per account:
+ *   - recurring items billed IN ADVANCE for this month (the default);
+ *   - Globex's in-arrears item billed for last month;
+ *   - Northwind's mid-cycle add-on: a prorated stub for the second half of
+ *     last month plus this month;
+ *   - usage (always in arrears) for last month.
  *
  * Drives `mercato billing seed`. Kept free of any customer-specific data so
  * it ships with `@dainamite/billing`.
@@ -32,8 +39,10 @@ const ACCOUNT_NAME_PREFIX = 'Demo — '
 type DemoAccountSpec = {
   name: string
   customerId: string
+  // Spec E: 'person' = a B2C account. Omitted → 'company'.
+  customerKind?: CustomerKind
   currencyCode: string
-  invoiceLanguage: string
+  invoiceLanguage: InvoiceLanguageCode
 }
 
 type DemoItemSpec = {
@@ -42,6 +51,18 @@ type DemoItemSpec = {
   description: string
   unitPrice: number
   uomCode?: string
+  // Spec B: VAT %. Default 23 (PL standard rate).
+  taxRate?: string
+  // Spec A. Default 'in_advance'.
+  chargeTiming?: 'in_advance' | 'in_arrears'
+  // Spec F. Default 'net'. Consumer (B2C) prices are quoted gross.
+  priceBasis?: 'net' | 'gross'
+  // When the item starts, relative to the seeded bill date:
+  //   'billDate' (default) — 1st of this month, billed in advance from day one;
+  //   'prevMonth'          — 1st of last month (in-arrears items bill it now);
+  //   'prevMonthMid'       — 15th of last month: an add-on bought mid-cycle,
+  //                          so the first run shows a prorated stub line.
+  start?: 'billDate' | 'prevMonth' | 'prevMonthMid'
 }
 
 type DemoUsageSpec = {
@@ -65,7 +86,15 @@ const ACCOUNTS: Array<{
     },
     items: [
       { ref: `${SRC}-nw-rec`, type: 'recurring', description: 'Platform subscription (monthly)', unitPrice: 199 },
-      { ref: `${SRC}-nw-usg`, type: 'usage', description: 'Data transfer (per GB)', unitPrice: 0.5, uomCode: 'gb' },
+      {
+        ref: `${SRC}-nw-addon`,
+        type: 'recurring',
+        description: 'Priority support add-on (monthly)',
+        unitPrice: 60,
+        taxRate: '8',
+        start: 'prevMonthMid',
+      },
+      { ref: `${SRC}-nw-usg`, type: 'usage', description: 'Data transfer (per GB)', unitPrice: 0.5, uomCode: 'gb', start: 'prevMonth' },
     ],
     usage: [
       { ref: `${SRC}-nw-usage`, uomCode: 'gb', quantity: 120, lineDescription: 'Data transfer (prev. month)' },
@@ -80,11 +109,43 @@ const ACCOUNTS: Array<{
     },
     items: [
       { ref: `${SRC}-gx-rec`, type: 'recurring', description: 'Cloud plan (monthly)', unitPrice: 49 },
+      {
+        ref: `${SRC}-gx-arr`,
+        type: 'recurring',
+        description: 'Managed backups (billed in arrears)',
+        unitPrice: 15,
+        // 0 % — shows a mixed-rate VAT summary on the document.
+        taxRate: '0',
+        chargeTiming: 'in_arrears',
+        start: 'prevMonth',
+      },
+    ],
+    usage: [],
+  },
+  {
+    // B2C: a private person on a flat monthly internet plan, invoiced in Polish.
+    account: {
+      name: `${ACCOUNT_NAME_PREFIX}Jan Kowalski`,
+      customerId: 'demo-cust-jan-kowalski',
+      customerKind: 'person',
+      currencyCode: 'PLN',
+      invoiceLanguage: 'pl',
+    },
+    items: [
+      // B2C price quoted gross (79.00 PLN incl. 23 % VAT) — Spec F, F-D2.
+      {
+        ref: `${SRC}-jk-rec`,
+        type: 'recurring',
+        description: 'Internet 300 Mb/s (miesięcznie)',
+        unitPrice: 79,
+        priceBasis: 'gross',
+      },
     ],
     usage: [],
   },
 ]
 
+
 /** Delete every row this seed owns within the scope (reset before re-seed). */
 export async function resetBillingDemo(em: EntityManager, scope: BillingDemoScope): Promise<void> {
   await em.nativeDelete(BillingAccountUsage, {
@@ -116,9 +177,16 @@ export async function seedBillingDemo(
   const nextBillDate = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1))
   const prevMonthStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1))
   const prevMonthEnd = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 0))
+  const prevMonthMid = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 15))
+  const startFor = (item: DemoItemSpec): Date =>
+    item.start === 'prevMonth' ? prevMonthStart : item.start === 'prevMonthMid' ? prevMonthMid : nextBillDate
 
   const result: BillingDemoResult = { accountsCreated: 0, itemsCreated: 0, usageCreated: 0 }
 
+  // ── Seller settings (Spec B: posting needs them). Only empty fields are
+  // filled, so an operator's real details are never overwritten. ──
+  await applySellerDefaults(em, scope, DEFAULT_DEMO_SELLER)
+
   for (const spec of ACCOUNTS) {
     // ── Account (idempotent by name within scope) ──
     let account = await em.findOne(BillingAccount, {
@@ -130,6 +198,7 @@ export async function seedBillingDemo(
       account = em.create(BillingAccount, {
         ...scope,
         customerId: spec.account.customerId,
+        customerKind: spec.account.customerKind ?? 'company',
         name: spec.account.name,
         currencyCode: spec.account.currencyCode,
         billCycle: 'monthly',
@@ -156,8 +225,12 @@ export async function seedBillingDemo(
           ...scope,
           billAccountId: account.id,
           type: item.type,
-          billStartDate: prevMonthStart,
+          billStartDate: startFor(item),
           billEndDate: null,
+          chargeTiming: item.chargeTiming ?? 'in_advance',
+          prorate: true,
+          taxRate: item.taxRate ?? '23',
+          priceBasis: item.priceBasis ?? 'net',
           description: item.description,
           rateJson: { unit_price: item.unitPrice },
           uomCode: item.uomCode ?? null,

package/src/modules/billing/lib/seeds/paymentsSample.ts

@@ -0,0 +1,136 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { PAYMENT_CSV_HEADER } from '../paymentCsv'
+
+/**
+ * Demo bank statement (Spec C): a `payments-sample.csv` built from the
+ * organization's real posted invoices, so numbers and amounts line up and
+ * every matcher outcome shows up after one upload:
+ *
+ *   exact amount + number            → allocated, invoice paid
+ *   half the amount                  → invoice partially paid
+ *   amount + 50                      → paid, 50 credit applied to the next open invoice
+ *   two numbers, sum of both         → both paid
+ *   no reference, known payer        → unmatched → assign to account
+ *   a top-up receipt number          → unmatched (prepaid) → convert to top-up
+ *   junk title                       → unmatched (no reference)
+ *   other currency                   → unmatched (currency mismatch)
+ *   the same line twice              → both stored (occurrence index); re-upload = duplicates
+ *
+ * Pure builder + a loader for the CLI (`mercato billing payments-sample`).
+ */
+
+export type SampleInvoice = {
+  number: string
+  totalGross: string
+  currencyCode: string
+  accountName: string
+}
+
+export type SampleReceipt = { number: string; currencyCode: string; accountName: string }
+
+function csvField(value: string): string {
+  return /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value
+}
+
+function money(value: number): string {
+  return value.toFixed(2)
+}
+
+export function buildPaymentsSampleCsv(params: {
+  invoices: SampleInvoice[]
+  receipt?: SampleReceipt | null
+  /** Spec D: a posted debit memo — paid by its own number like an invoice. */
+  debitMemo?: SampleInvoice | null
+  date: string
+}): { csv: string; rows: number; missing: string[] } {
+  const { invoices, receipt, date, debitMemo } = params
+  const rows: string[][] = []
+  const missing: string[] = []
+  const gross = (inv: SampleInvoice) => Number.parseFloat(inv.totalGross)
+  const [a, b, c] = invoices
+  // Two invoices of the SAME account (references to two customers are ambiguous).
+  const rest = invoices.slice(3)
+  let d: SampleInvoice | undefined
+  let e: SampleInvoice | undefined
+  for (let i = 0; i < rest.length && !d; i += 1) {
+    const match = rest.slice(i + 1).find((other) => other.accountName === rest[i].accountName && other.currencyCode === rest[i].currencyCode)
+    if (match) {
+      d = rest[i]
+      e = match
+    }
+  }
+
+  if (a) rows.push([date, money(gross(a)), a.currencyCode, `Payment for ${a.number}`, a.accountName, ''])
+  else missing.push('exact payment (needs 1 posted invoice)')
+  if (b) rows.push([date, money(gross(b) / 2), b.currencyCode, `${b.number} part 1`, b.accountName, ''])
+  else missing.push('partial payment (needs 2 posted invoices)')
+  if (c) rows.push([date, money(gross(c) + 50), c.currencyCode, `Invoice ${c.number} + advance`, c.accountName, ''])
+  else missing.push('overpayment (needs 3 posted invoices)')
+  if (d && e) rows.push([date, money(gross(d) + gross(e)), d.currencyCode, `${d.number}, ${e.number}`, d.accountName, ''])
+  else missing.push('two invoices in one title (needs two more posted invoices of one account)')
+  if (a) rows.push([date, '25.00', a.currencyCode, 'Thank you', a.accountName, 'PL61109010140000071219812874'])
+  if (receipt) rows.push([date, '100.00', receipt.currencyCode, `Top-up ${receipt.number}`, receipt.accountName, ''])
+  else missing.push('prepaid top-up (needs a prepaid top-up receipt)')
+  if (debitMemo) {
+    rows.push([date, money(gross(debitMemo)), debitMemo.currencyCode, `Note ${debitMemo.number}`, debitMemo.accountName, ''])
+  }
+  rows.push([date, '12.34', 'PLN', 'misc transfer', 'Unknown payer', ''])
+  if (a) {
+    const other = a.currencyCode === 'EUR' ? 'PLN' : 'EUR'
+    rows.push([date, money(gross(a)), other, a.number, a.accountName, ''])
+    const dup = [date, '10.00', a.currencyCode, 'Duplicate line', a.accountName, '']
+    rows.push(dup, [...dup])
+  }
+  const csv = [PAYMENT_CSV_HEADER.join(','), ...rows.map((row) => row.map(csvField).join(','))].join('\n') + '\n'
+  return { csv, rows: rows.length, missing }
+}
+
+/** Posted, unpaid invoices of the org (oldest first) and one top-up receipt. */
+export async function loadSampleSources(
+  em: EntityManager,
+  scope: { tenantId: string; organizationId: string },
+): Promise<{ invoices: SampleInvoice[]; receipt: SampleReceipt | null; debitMemo: SampleInvoice | null }> {
+  const invoices = (await em.execute(
+    `SELECT i.number, i.total_gross, i.currency_code, a.name AS account_name
+       FROM billing_invoices i
+       JOIN billing_accounts a ON a.id = i.bill_account_id
+      WHERE i.tenant_id = ? AND i.organization_id = ? AND i.deleted_at IS NULL AND i.test_run = false
+        AND i.document_type = 'invoice' AND i.status = 'posted' AND a.billing_mode = 'postpaid'
+      ORDER BY i.issue_date ASC, i.number ASC
+      LIMIT 20`,
+    [scope.tenantId, scope.organizationId],
+  )) as unknown as Array<{ number: string; total_gross: string; currency_code: string; account_name: string }>
+  const receipts = (await em.execute(
+    `SELECT i.number, i.currency_code, a.name AS account_name
+       FROM billing_invoices i
+       JOIN billing_accounts a ON a.id = i.bill_account_id
+      WHERE i.tenant_id = ? AND i.organization_id = ? AND i.deleted_at IS NULL AND i.document_type = 'receipt'
+      ORDER BY i.created_at DESC
+      LIMIT 1`,
+    [scope.tenantId, scope.organizationId],
+  )) as unknown as Array<{ number: string; currency_code: string; account_name: string }>
+  const debits = (await em.execute(
+    `SELECT i.number, i.total_gross, i.currency_code, a.name AS account_name
+       FROM billing_invoices i
+       JOIN billing_accounts a ON a.id = i.bill_account_id
+      WHERE i.tenant_id = ? AND i.organization_id = ? AND i.deleted_at IS NULL AND i.test_run = false
+        AND i.document_type = 'debit_memo' AND i.status = 'posted'
+      ORDER BY i.issue_date ASC
+      LIMIT 1`,
+    [scope.tenantId, scope.organizationId],
+  )) as unknown as Array<{ number: string; total_gross: string; currency_code: string; account_name: string }>
+  return {
+    debitMemo: debits?.[0]
+      ? { number: debits[0].number, totalGross: debits[0].total_gross, currencyCode: debits[0].currency_code, accountName: debits[0].account_name }
+      : null,
+    invoices: (invoices ?? []).map((row) => ({
+      number: row.number,
+      totalGross: row.total_gross,
+      currencyCode: row.currency_code,
+      accountName: row.account_name,
+    })),
+    receipt: receipts?.[0]
+      ? { number: receipts[0].number, currencyCode: receipts[0].currency_code, accountName: receipts[0].account_name }
+      : null,
+  }
+}

package/src/modules/billing/lib/seeds/sellerSettings.ts

@@ -0,0 +1,78 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { BillingSettings } from '../../data/entities'
+import { getBillingSettings, type SettingsScope } from '../billingSettings'
+
+/**
+ * Seller details for demo / seed tenants (Spec B: posting an invoice needs
+ * legal name, address, tax ID and IBAN). Public seed API — demo use cases
+ * (`demo_gix`, `demo_puffin`, …) call `applySellerDefaults` from their own
+ * `seedDefaults` with a profile of their own.
+ *
+ * Only EMPTY fields are filled, so an operator's real details are never
+ * overwritten and re-running a seed is a no-op. Values must pass the settings
+ * validators (checksum-valid IBAN, 8/11-char BIC) so the settings page can be
+ * saved without touching them.
+ */
+
+export type SellerProfile = {
+  legalName: string
+  sellerAddress: { line1: string; line2?: string; city: string; postal_code: string; country: string }
+  taxId: string
+  bankName: string
+  iban: string
+  bic: string
+  invoiceFooter?: string
+}
+
+const SELLER_FIELDS = ['legalName', 'sellerAddress', 'taxId', 'bankName', 'iban', 'bic', 'invoiceFooter'] as const
+type SellerField = (typeof SELLER_FIELDS)[number]
+
+/** The generic seller of the billing demo seed (primary tenant). */
+export const DEFAULT_DEMO_SELLER: SellerProfile = {
+  legalName: 'Dainamite Demo sp. z o.o.',
+  sellerAddress: { line1: 'ul. Przykładowa 10', city: 'Kraków', postal_code: '30-001', country: 'PL' },
+  taxId: 'PL1234563218',
+  bankName: 'Demo Bank S.A.',
+  iban: 'PL61109010140000071219812874',
+  bic: 'WBKPPLPP',
+  invoiceFooter: 'Sąd Rejonowy dla Krakowa-Śródmieścia, KRS 0000000000. Kapitał zakładowy 5 000 zł.',
+}
+
+function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'string') return value.trim() === ''
+  if (typeof value === 'object') return Object.keys(value as object).length === 0
+  return false
+}
+
+/** Pure: which profile values would fill which empty settings fields. */
+export function sellerFieldsToFill(
+  settings: Pick<BillingSettings, SellerField>,
+  profile: SellerProfile,
+): Partial<Record<SellerField, unknown>> {
+  const out: Partial<Record<SellerField, unknown>> = {}
+  for (const field of SELLER_FIELDS) {
+    const value = profile[field]
+    if (value === undefined) continue
+    if (isEmpty(settings[field])) out[field] = value
+  }
+  return out
+}
+
+/**
+ * Fill the organization's empty seller fields from `profile` and flush.
+ * Returns the names of the fields that were filled (empty when nothing changed).
+ */
+export async function applySellerDefaults(
+  em: EntityManager,
+  scope: SettingsScope,
+  profile: SellerProfile,
+): Promise<string[]> {
+  const settings = await getBillingSettings(em, scope)
+  const fill = sellerFieldsToFill(settings, profile)
+  const fields = Object.keys(fill)
+  if (fields.length === 0) return []
+  Object.assign(settings, fill, { updatedAt: new Date() })
+  await em.flush()
+  return fields
+}

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

@@ -0,0 +1,226 @@
+import type { BillCycle, ChargeTiming } from '../data/validators'
+import { addDays, cloneAtMidnight, shiftCycles } from './billPeriod'
+
+/**
+ * Recurring-charge computation for one bill date (Spec A).
+ *
+ * Pure and storage-agnostic: given an item's state and the account's bill
+ * date, decide which service periods to charge (or credit) and where the
+ * item's `billed_to_date` watermark moves. The engine calls it once per item
+ * per simulated bill date and owns persistence.
+ *
+ * Model:
+ *   - The account's cycle grid is anchored at the bill date `D`:
+ *     …, D − cycle, D, D + cycle, …  (each period `[g_k, g_{k+1} − 1]`).
+ *   - Horizon — how far the item is billed on `D`:
+ *       in_advance → D + cycle − 1     in_arrears → D − 1
+ *   - Cursor — first unbilled day: `billed_to_date + 1`, else `bill_start_date`.
+ *   - The unbilled window `[cursor, min(horizon, bill_end_date)]` is cut along
+ *     the grid; each grid period becomes one line (full → unit price,
+ *     partial → prorated by calendar days, or skipped when `prorate=false`).
+ *   - Credit (A-D2): an item ended (`bill_end_date`) before what was already
+ *     billed (`billed_to_date`) gets negative lines for the unused days when
+ *     `prorate=true`, and the watermark is pulled back to `bill_end_date`.
+ *
+ * The watermark is the single source of truth against double billing: every
+ * computation starts at `billed_to_date + 1`, so switching timing, re-running
+ * a bill date, or catching up can never charge a day twice.
+ */
+
+export type RecurringItemState = {
+  id: string
+  chargeTiming: ChargeTiming
+  prorate: boolean
+  billStartDate: Date | string
+  billEndDate?: Date | string | null
+  billedToDate?: Date | string | null
+  unitPrice: number
+  isActive: boolean
+  deletedAt?: Date | string | null
+}
+
+export type ProrationInfo = { activeDays: number; periodDays: number }
+
+export type RecurringLine = {
+  billingItemId: string
+  kind: 'charge' | 'credit'
+  /** Inclusive service period the line covers. */
+  servicePeriodStart: Date
+  servicePeriodEnd: Date
+  /** 2dp half-up; negative for credits. */
+  amount: number
+  /** Null when the line covers a full grid period. */
+  proration: ProrationInfo | null
+}
+
+export type RecurringSkipReason =
+  | 'item-inactive'
+  | 'item-soft-deleted'
+  | 'partial-period-not-prorated'
+  | 'ended-after-billing-no-credit'
+  | 'period-cap-reached'
+
+export type RecurringSkip = {
+  billingItemId: string
+  reason: RecurringSkipReason
+  servicePeriodStart: Date | null
+  servicePeriodEnd: Date | null
+}
+
+export type RecurringComputation = {
+  lines: RecurringLine[]
+  /** Watermark after these lines; unchanged when nothing was billed. */
+  newBilledToDate: Date | null
+  skipped: RecurringSkip[]
+}
+
+/** Upper bound of grid periods processed per item per call (runaway guard). */
+export const MAX_PERIODS_PER_ITEM = 120
+
+const DAY_MS = 86_400_000
+
+function toDate(value: Date | string | number): Date {
+  return cloneAtMidnight(value)
+}
+
+function optDate(value: Date | string | null | undefined): Date | null {
+  return value === null || value === undefined || value === '' ? null : toDate(value)
+}
+
+function minDate(a: Date, b: Date): Date {
+  return a.getTime() <= b.getTime() ? a : b
+}
+
+function maxDate(a: Date, b: Date): Date {
+  return a.getTime() >= b.getTime() ? a : b
+}
+
+/** Inclusive day count of `[from, to]`. */
+export function inclusiveDays(from: Date, to: Date): number {
+  return Math.round((to.getTime() - from.getTime()) / DAY_MS) + 1
+}
+
+/** Half-up 2dp rounding that survives binary floating point (1.005 → 1.01). */
+export function roundHalfUp2dp(value: number): number {
+  const sign = value < 0 ? -1 : 1
+  return (sign * Math.round((Math.abs(value) + Number.EPSILON) * 100)) / 100
+}
+
+type GridPeriod = { index: number; start: Date; end: Date }
+
+function gridPeriod(anchor: Date, cycle: BillCycle, index: number): GridPeriod {
+  const start = shiftCycles(anchor, cycle, index)
+  const end = addDays(shiftCycles(anchor, cycle, index + 1), -1)
+  return { index, start, end }
+}
+
+/** Grid period (anchored at `anchor`) containing `date`. */
+export function gridPeriodContaining(anchor: Date, cycle: BillCycle, date: Date): GridPeriod {
+  const target = date.getTime()
+  // Coarse estimate first so long gaps don't walk one cycle at a time.
+  const approxDays: Record<BillCycle, number> = { weekly: 7, monthly: 30.44, quarterly: 91.31, annually: 365.25 }
+  let index = Math.floor((target - anchor.getTime()) / DAY_MS / approxDays[cycle])
+  let period = gridPeriod(anchor, cycle, index)
+  let guard = 0
+  while (period.start.getTime() > target && guard++ < 1000) period = gridPeriod(anchor, cycle, --index)
+  while (period.end.getTime() < target && guard++ < 2000) period = gridPeriod(anchor, cycle, ++index)
+  return period
+}
+
+/**
+ * Slices `[from, to]` along the grid and prices each slice. Shared by the
+ * charge and credit paths so both prorate identically.
+ */
+function slice(
+  item: RecurringItemState,
+  anchor: Date,
+  cycle: BillCycle,
+  from: Date,
+  to: Date,
+  kind: RecurringLine['kind'],
+): { lines: RecurringLine[]; skipped: RecurringSkip[]; lastCovered: Date | null } {
+  const lines: RecurringLine[] = []
+  const skipped: RecurringSkip[] = []
+  let lastCovered: Date | null = null
+  let period = gridPeriodContaining(anchor, cycle, from)
+  let count = 0
+  while (period.start.getTime() <= to.getTime()) {
+    if (count++ >= MAX_PERIODS_PER_ITEM) {
+      skipped.push({ billingItemId: item.id, reason: 'period-cap-reached', servicePeriodStart: period.start, servicePeriodEnd: null })
+      break
+    }
+    const activeStart = maxDate(period.start, from)
+    const activeEnd = minDate(period.end, to)
+    const periodDays = inclusiveDays(period.start, period.end)
+    const activeDays = inclusiveDays(activeStart, activeEnd)
+    const partial = activeDays < periodDays
+    if (partial && !item.prorate) {
+      skipped.push({
+        billingItemId: item.id,
+        reason: 'partial-period-not-prorated',
+        servicePeriodStart: activeStart,
+        servicePeriodEnd: activeEnd,
+      })
+    } else {
+      const gross = partial ? (item.unitPrice * activeDays) / periodDays : item.unitPrice
+      const amount = roundHalfUp2dp(gross)
+      lines.push({
+        billingItemId: item.id,
+        kind,
+        servicePeriodStart: activeStart,
+        servicePeriodEnd: activeEnd,
+        amount: kind === 'credit' ? -amount : amount,
+        proration: partial ? { activeDays, periodDays } : null,
+      })
+    }
+    lastCovered = activeEnd
+    period = gridPeriod(anchor, cycle, period.index + 1)
+  }
+  return { lines, skipped, lastCovered }
+}
+
+export function computeRecurringLines(
+  item: RecurringItemState,
+  params: { billDate: Date | string; cycle: BillCycle },
+): RecurringComputation {
+  const billedTo = optDate(item.billedToDate)
+  if (item.deletedAt) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: 'item-soft-deleted', servicePeriodStart: null, servicePeriodEnd: null }] }
+  }
+  if (!item.isActive) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [{ billingItemId: item.id, reason: 'item-inactive', servicePeriodStart: null, servicePeriodEnd: null }] }
+  }
+
+  const anchor = toDate(params.billDate)
+  const { cycle } = params
+  const start = toDate(item.billStartDate)
+  const end = optDate(item.billEndDate)
+
+  // ── Credit: the item ended inside what was already billed (A-D2). ──
+  if (end && billedTo && end.getTime() < billedTo.getTime()) {
+    if (!item.prorate) {
+      return {
+        lines: [],
+        newBilledToDate: billedTo,
+        skipped: [{ billingItemId: item.id, reason: 'ended-after-billing-no-credit', servicePeriodStart: addDays(end, 1), servicePeriodEnd: billedTo }],
+      }
+    }
+    const credit = slice(item, anchor, cycle, maxDate(addDays(end, 1), start), billedTo, 'credit')
+    return { lines: credit.lines, newBilledToDate: end, skipped: credit.skipped }
+  }
+
+  // ── Charge: bill the unbilled window up to the horizon. ──
+  const horizon =
+    item.chargeTiming === 'in_arrears' ? addDays(anchor, -1) : addDays(shiftCycles(anchor, cycle, 1), -1)
+  const cursor = billedTo ? maxDate(addDays(billedTo, 1), start) : start
+  const windowEnd = end ? minDate(horizon, end) : horizon
+  if (cursor.getTime() > windowEnd.getTime()) {
+    return { lines: [], newBilledToDate: billedTo, skipped: [] }
+  }
+  const charge = slice(item, anchor, cycle, cursor, windowEnd, 'charge')
+  return {
+    lines: charge.lines,
+    newBilledToDate: charge.lastCovered ?? billedTo,
+    skipped: charge.skipped,
+  }
+}