@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,67 @@
+/**
+ * Where an item stands against today (account Items tab): has it been billed,
+ * and through which date? Pure — computed from the item row and today's date.
+ *
+ *   inactive      the item is switched off
+ *   metered       usage item (billed from usage records, no watermark)
+ *   scheduled     starts after today, nothing billed yet
+ *   awaiting_run  started, but no Bill Run has charged it yet
+ *   billed        one-time item already charged
+ *   current       recurring, charged through today or later (paid ahead)
+ *   due           recurring, charged only through a past date — the next
+ *                 Bill Run will charge the rest
+ *   fully_billed  recurring with an end date, charged through that end
+ */
+
+export type ItemBillingStatus =
+  | 'inactive'
+  | 'metered'
+  | 'scheduled'
+  | 'awaiting_run'
+  | 'billed'
+  | 'current'
+  | 'due'
+  | 'fully_billed'
+
+export type ItemBillingInput = {
+  type: 'one_time' | 'recurring' | 'usage'
+  is_active: boolean
+  bill_start_date: string
+  bill_end_date?: string | null
+  billed_to_date?: string | null
+}
+
+export type ItemBillingState = {
+  status: ItemBillingStatus
+  /** The relevant date for the label: start, billed-through or due-since day (YYYY-MM-DD). */
+  date: string | null
+}
+
+function day(value: string | null | undefined): string | null {
+  return value ? value.slice(0, 10) : null
+}
+
+function nextDay(iso: string): string {
+  const date = new Date(`${iso}T00:00:00Z`)
+  date.setUTCDate(date.getUTCDate() + 1)
+  return date.toISOString().slice(0, 10)
+}
+
+/** `today` is a YYYY-MM-DD string (the viewer's calendar day). */
+export function itemBillingState(item: ItemBillingInput, today: string): ItemBillingState {
+  if (!item.is_active) return { status: 'inactive', date: null }
+  if (item.type === 'usage') return { status: 'metered', date: null }
+  const start = day(item.bill_start_date) ?? today
+  const billedTo = day(item.billed_to_date)
+  const end = day(item.bill_end_date)
+
+  if (item.type === 'one_time') {
+    if (billedTo) return { status: 'billed', date: null }
+    return start > today ? { status: 'scheduled', date: start } : { status: 'awaiting_run', date: null }
+  }
+
+  if (!billedTo) return start > today ? { status: 'scheduled', date: start } : { status: 'awaiting_run', date: null }
+  if (end && billedTo >= end) return { status: 'fully_billed', date: billedTo }
+  if (billedTo >= today) return { status: 'current', date: billedTo }
+  return { status: 'due', date: nextDay(billedTo) }
+}

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

@@ -0,0 +1,56 @@
+import { toIsoDate, toUtcMidnight } from './dateOnly'
+
+/**
+ * Change the price of a recurring item from a date on (Spec F follow-up):
+ * the current item ends the day before `effectiveDate`, and a copy with the
+ * new price starts on `effectiveDate` and keeps the original end date.
+ *
+ * Nothing is billed twice: if the old item was already billed past the
+ * change (in advance), the engine credits the unused days (prorate on) and
+ * the new item charges them at the new price; with prorate off the old item
+ * keeps them and the new item starts charging at its next full period.
+ *
+ * Pure — validates and computes the dates; the command does the writes.
+ */
+
+export type PriceChangeItem = {
+  type: string
+  isActive: boolean
+  deletedAt?: Date | string | null
+  billStartDate: Date | string
+  billEndDate?: Date | string | null
+}
+
+export type PriceChangePlan = {
+  /** New end date of the current item: the day before the change. */
+  oldItemEndDate: Date
+  /** Start of the new item: the effective date. */
+  newItemStartDate: Date
+  /** The new item keeps the original end date (null = open-ended). */
+  newItemEndDate: Date | null
+}
+
+export type PriceChangeError =
+  | 'billing.item.price_change_recurring_only'
+  | 'billing.item.price_change_inactive'
+  | 'billing.item.price_change_before_start'
+  | 'billing.item.price_change_after_end'
+
+export function planPriceChange(
+  item: PriceChangeItem,
+  effectiveDate: Date | string,
+): { ok: true; plan: PriceChangePlan } | { ok: false; error: PriceChangeError } {
+  if (item.type !== 'recurring') return { ok: false, error: 'billing.item.price_change_recurring_only' }
+  if (!item.isActive || item.deletedAt) return { ok: false, error: 'billing.item.price_change_inactive' }
+  const effective = toUtcMidnight(effectiveDate)
+  const start = toUtcMidnight(item.billStartDate)
+  // The current item must keep at least one day.
+  if (effective.getTime() <= start.getTime()) return { ok: false, error: 'billing.item.price_change_before_start' }
+  const end = item.billEndDate ? toUtcMidnight(item.billEndDate) : null
+  if (end && effective.getTime() > end.getTime()) return { ok: false, error: 'billing.item.price_change_after_end' }
+  const oldItemEndDate = new Date(effective)
+  oldItemEndDate.setUTCDate(oldItemEndDate.getUTCDate() - 1)
+  return { ok: true, plan: { oldItemEndDate, newItemStartDate: effective, newItemEndDate: end } }
+}
+
+export { toIsoDate }

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

@@ -20,7 +20,10 @@ import type { BillPeriod } from './billPeriod'
  *      `billed_to_date IS NULL` AND the item's `[bill_start_date,
  *      bill_end_date]` window overlaps the bill period.
  *
- *   `recurring` — one line per full cycle. Eligible only when:
+ *   `recurring` — used by PREPAID period close only (Spec A, A-D1). The
+ *      postpaid engine prices recurring items with `servicePeriods`
+ *      (in advance / in arrears, proration, credits). Here: one line per
+ *      full cycle. Eligible only when:
  *      - `bill_start_date <= bill_period_start`
  *      - AND (`bill_end_date IS NULL` OR `bill_end_date >= bill_period_end`)
  *      - AND (`billed_to_date IS NULL` OR `billed_to_date < bill_period_end`)

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

@@ -0,0 +1,61 @@
+import { lineAmountsFromGross, lineAmountsFromNet, type VatAmounts } from './vat'
+
+/**
+ * Basis-aware line VAT — the single entry point for every billing line
+ * (Spec F, P-D3): invoice drafts, dry / test previews and prepaid debits.
+ *
+ * An item price is stored as typed, on its `price_basis`:
+ *   - `net`:   tax = round2(net × rate), gross = net + tax
+ *   - `gross`: net = round2(gross / (1 + rate)), tax = gross − net
+ * so a gross the operator typed is exactly the gross on the document.
+ * Rounding happens once per line, on the extended amount
+ * (unit × quantity × proration), never per unit.
+ */
+
+export type PriceBasis = 'net' | 'gross'
+
+export type LineVatInput = {
+  /** Extended line amount on `priceBasis` (unit × quantity × proration). */
+  amount: number | string
+  priceBasis: PriceBasis
+  /** VAT rate in percent. */
+  taxRate: number | string
+}
+
+function toNumber(value: number | string): number {
+  const n = typeof value === 'number' ? value : Number.parseFloat(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+export function lineVat(input: LineVatInput): VatAmounts {
+  const amount = toNumber(input.amount)
+  const rate = toNumber(input.taxRate)
+  return input.priceBasis === 'gross' ? lineAmountsFromGross(amount, rate) : lineAmountsFromNet(amount, rate)
+}
+
+/** Resolve a stored basis value (anything but `gross` reads as `net`). */
+export function priceBasisOf(value: unknown): PriceBasis {
+  return value === 'gross' ? 'gross' : 'net'
+}
+
+/**
+ * Net unit price for `billing_invoice_lines.unit_price_net` (display only,
+ * 4 dp). Net basis keeps the typed unit price; gross basis derives it.
+ */
+export function unitPriceNetOf(unitPrice: number | string, priceBasis: PriceBasis, taxRate: number | string): string {
+  const unit = toNumber(unitPrice)
+  if (priceBasis !== 'gross') return unit.toFixed(4)
+  const rate = toNumber(taxRate)
+  const net = rate > 0 ? unit / (1 + rate / 100) : unit
+  const sign = net < 0 ? -1 : 1
+  return ((sign * Math.round((Math.abs(net) + Number.EPSILON) * 10000)) / 10000).toFixed(4)
+}
+
+/**
+ * The counterpart of a typed unit price, for the ItemForm preview: the gross
+ * of a net price or the net of a gross price (2 dp, same rule as the lines).
+ */
+export function counterpartAmount(amount: number | string, priceBasis: PriceBasis, taxRate: number | string): number {
+  const vat = lineVat({ amount, priceBasis, taxRate })
+  return priceBasis === 'gross' ? vat.net : vat.gross
+}

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

@@ -0,0 +1,41 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { toCents } from './allocation'
+
+/**
+ * Credit memo guard (Spec D, P-D4). Pure core + one aggregate query.
+ *
+ *   Σ gross of posted credit memos on the original (incl. the new one)
+ *     ≤ original gross + Σ gross of posted debit memos on it
+ *
+ * Evaluated inside the per-account lock at post (authoritative) and,
+ * without the lock, when a draft memo is created (early feedback).
+ */
+
+export type CorrectionTotals = { creditCents: number; debitCents: number }
+
+export function creditHeadroomCents(originalGrossCents: number, totals: CorrectionTotals): number {
+  return originalGrossCents + totals.debitCents - totals.creditCents
+}
+
+export function creditFits(originalGrossCents: number, totals: CorrectionTotals, newCreditCents: number): boolean {
+  return newCreditCents <= creditHeadroomCents(originalGrossCents, totals)
+}
+
+/** Σ gross of POSTED (non-draft) memos correcting an invoice, per type. */
+export async function loadCorrectionTotals(
+  em: EntityManager,
+  scope: { tenantId: string; organizationId: string },
+  originalId: string,
+  opts: { excludeId?: string } = {},
+): Promise<CorrectionTotals> {
+  const rows = (await em.execute(
+    `SELECT document_type, COALESCE(SUM(total_gross), 0) AS gross
+       FROM billing_invoices
+      WHERE corrects_invoice_id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL
+        AND status <> 'draft' AND test_run = false AND id <> ?
+      GROUP BY document_type`,
+    [originalId, scope.tenantId, scope.organizationId, opts.excludeId ?? '00000000-0000-0000-0000-000000000000'],
+  )) as unknown as Array<{ document_type: string; gross: string }>
+  const of = (type: string) => toCents(rows?.find((r) => r.document_type === type)?.gross ?? '0')
+  return { creditCents: of('credit_memo'), debitCents: of('debit_memo') }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Where an item page returns to (Spec E, D23).
+ *
+ * Billing items always belong to an account, so the account is the natural
+ * parent: back / after-save / after-delete land there. The only exception is
+ * an item opened from the global Items list (`?from=items`), which returns
+ * to that list so the operator keeps their place.
+ */
+
+export const ITEMS_LIST_HREF = '/backend/billing/items'
+
+/** Query value the global Items list appends when opening an item. */
+export const FROM_ITEMS_LIST = 'items'
+
+/** Tabs of the Billing Account workspace (Spec E / Spec F, F8), deep-linkable via `?tab=`. */
+export const ACCOUNT_TABS = ['overview', 'items', 'usage', 'invoices', 'payments', 'balance', 'statements', 'runs'] as const
+export type AccountTab = (typeof ACCOUNT_TABS)[number]
+
+export function isAccountTab(value: unknown): value is AccountTab {
+  return typeof value === 'string' && (ACCOUNT_TABS as readonly string[]).includes(value)
+}
+
+/** The account workspace, optionally on one tab (`overview` is the default and is left out). */
+export function accountHref(billAccountId: string, tab?: AccountTab): string {
+  const base = `/backend/billing/accounts/${encodeURIComponent(billAccountId)}`
+  return tab && tab !== 'overview' ? `${base}?tab=${tab}` : base
+}
+
+export function resolveItemReturnTarget(params: {
+  from?: string | null
+  billAccountId?: string | null
+}): string {
+  if (params.from === FROM_ITEMS_LIST) return ITEMS_LIST_HREF
+  const accountId = (params.billAccountId ?? '').trim()
+  return accountId ? accountHref(accountId, 'items') : ITEMS_LIST_HREF
+}
+
+export function itemDetailHref(itemId: string, opts: { fromItemsList?: boolean } = {}): string {
+  const base = `${ITEMS_LIST_HREF}/${encodeURIComponent(itemId)}`
+  return opts.fromItemsList ? `${base}?from=${FROM_ITEMS_LIST}` : base
+}
+
+/**
+ * Where an invoice detail page returns to (Spec B): the account it was
+ * opened from (`?from=account`), otherwise the global Invoices list.
+ */
+export const INVOICES_LIST_HREF = '/backend/billing/invoices'
+export const FROM_ACCOUNT = 'account'
+
+export function invoiceDetailHref(invoiceId: string, opts: { fromAccountId?: string | null } = {}): string {
+  const base = `${INVOICES_LIST_HREF}/${encodeURIComponent(invoiceId)}`
+  const accountId = (opts.fromAccountId ?? '').trim()
+  return accountId ? `${base}?from=${FROM_ACCOUNT}&accountId=${encodeURIComponent(accountId)}` : base
+}
+
+export function resolveInvoiceReturnTarget(params: { from?: string | null; accountId?: string | null }): string {
+  const accountId = (params.accountId ?? '').trim()
+  return params.from === FROM_ACCOUNT && accountId ? accountHref(accountId, 'invoices') : INVOICES_LIST_HREF
+}
+
+/** PDF of a billing document — frozen when posted, a watermarked preview otherwise. */
+export function invoicePdfHref(invoiceId: string): string {
+  return `/api/billing/invoices/${encodeURIComponent(invoiceId)}/pdf`
+}

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

@@ -0,0 +1,174 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Document numbering (Spec 0, decision E-D6 / P-D3).
+ *
+ * Each series has a mask, e.g. `INV/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}`:
+ *   {YYYY} {YY} {MM} {DD}     — parts of the issue date
+ *   {SEQUENCE_NUM}            — counter never resets
+ *   {SEQUENCE_NUM_YEAR}       — counter resets every year
+ *   {SEQUENCE_NUM_MONTH}      — counter resets every month
+ *   …:N                       — optional zero-pad to N digits
+ *
+ * The counter row is `(tenant, org, series, scope_key)` where scope_key is
+ * '' / 'YYYY' / 'YYYY-MM'. A number is claimed only at post, by one upsert
+ * inside the caller's transaction — a rollback releases it (gap-free) and
+ * concurrent posts serialize on the row.
+ */
+
+export const DOCUMENT_SERIES = ['invoice', 'credit_memo', 'receipt'] as const
+export type DocumentSeries = (typeof DOCUMENT_SERIES)[number]
+
+export const DEFAULT_NUMBER_MASKS: Record<DocumentSeries, string> = {
+  invoice: 'INV/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}',
+  credit_memo: 'CN/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}',
+  receipt: 'RC/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}',
+}
+
+export type SequenceScope = 'none' | 'year' | 'month'
+
+export type ParsedMask = {
+  scope: SequenceScope
+  pad: number
+  hasYear: boolean
+  hasMonth: boolean
+}
+
+export type MaskError =
+  | 'mask_empty'
+  | 'mask_too_long'
+  | 'mask_unknown_token'
+  | 'mask_missing_sequence'
+  | 'mask_multiple_sequences'
+  | 'mask_year_scope_needs_year'
+  | 'mask_month_scope_needs_year_and_month'
+
+export const MAX_MASK_LENGTH = 64
+
+const TOKEN_RE = /\{([A-Z_]+)(?::(\d{1,2}))?\}/g
+const DATE_TOKENS = new Set(['YYYY', 'YY', 'MM', 'DD'])
+const SEQUENCE_TOKENS: Record<string, SequenceScope> = {
+  SEQUENCE_NUM: 'none',
+  SEQUENCE_NUM_YEAR: 'year',
+  SEQUENCE_NUM_MONTH: 'month',
+}
+
+function tokensOf(mask: string): Array<{ name: string; pad: number }> {
+  return Array.from(mask.matchAll(TOKEN_RE), (m) => ({ name: m[1], pad: m[2] ? Number(m[2]) : 0 }))
+}
+
+/** Validation errors for a mask; empty array = valid. */
+export function validateMask(mask: string): MaskError[] {
+  const trimmed = (mask ?? '').trim()
+  if (!trimmed) return ['mask_empty']
+  const errors: MaskError[] = []
+  if (trimmed.length > MAX_MASK_LENGTH) errors.push('mask_too_long')
+  const tokens = tokensOf(trimmed)
+  // Any brace not consumed by a known-shaped token is an unknown token.
+  const stripped = trimmed.replace(TOKEN_RE, '')
+  if (/[{}]/.test(stripped) || tokens.some((t) => !DATE_TOKENS.has(t.name) && !(t.name in SEQUENCE_TOKENS))) {
+    errors.push('mask_unknown_token')
+  }
+  const sequences = tokens.filter((t) => t.name in SEQUENCE_TOKENS)
+  if (sequences.length === 0) errors.push('mask_missing_sequence')
+  if (sequences.length > 1) errors.push('mask_multiple_sequences')
+  const hasYear = tokens.some((t) => t.name === 'YYYY' || t.name === 'YY')
+  const hasMonth = tokens.some((t) => t.name === 'MM')
+  const scope = sequences[0] ? SEQUENCE_TOKENS[sequences[0].name] : 'none'
+  if (scope === 'year' && !hasYear) errors.push('mask_year_scope_needs_year')
+  if (scope === 'month' && (!hasYear || !hasMonth)) errors.push('mask_month_scope_needs_year_and_month')
+  return errors
+}
+
+export function parseMask(mask: string): ParsedMask {
+  const tokens = tokensOf(mask)
+  const sequence = tokens.find((t) => t.name in SEQUENCE_TOKENS)
+  return {
+    scope: sequence ? SEQUENCE_TOKENS[sequence.name] : 'none',
+    pad: sequence?.pad ?? 0,
+    hasYear: tokens.some((t) => t.name === 'YYYY' || t.name === 'YY'),
+    hasMonth: tokens.some((t) => t.name === 'MM'),
+  }
+}
+
+function datePart(date: Date, part: 'YYYY' | 'YY' | 'MM' | 'DD'): string {
+  const d = new Date(date)
+  switch (part) {
+    case 'YYYY':
+      return String(d.getUTCFullYear())
+    case 'YY':
+      return String(d.getUTCFullYear()).slice(-2)
+    case 'MM':
+      return String(d.getUTCMonth() + 1).padStart(2, '0')
+    case 'DD':
+      return String(d.getUTCDate()).padStart(2, '0')
+  }
+}
+
+/** Counter scope for a mask on a given issue date: '', 'YYYY' or 'YYYY-MM'. */
+export function sequenceScopeKey(mask: string, issueDate: Date): string {
+  const { scope } = parseMask(mask)
+  if (scope === 'year') return datePart(issueDate, 'YYYY')
+  if (scope === 'month') return `${datePart(issueDate, 'YYYY')}-${datePart(issueDate, 'MM')}`
+  return ''
+}
+
+export function renderNumber(mask: string, params: { seq: number; issueDate: Date }): string {
+  return mask.replace(TOKEN_RE, (_match, name: string, pad?: string) => {
+    if (name in SEQUENCE_TOKENS) return String(params.seq).padStart(pad ? Number(pad) : 0, '0')
+    if (DATE_TOKENS.has(name)) return datePart(params.issueDate, name as 'YYYY' | 'YY' | 'MM' | 'DD')
+    return _match
+  })
+}
+
+export function maskFor(masks: Partial<Record<string, string>> | null | undefined, series: DocumentSeries): string {
+  const candidate = masks?.[series]
+  return candidate && validateMask(candidate).length === 0 ? candidate : DEFAULT_NUMBER_MASKS[series]
+}
+
+function randomHex(length: number): string {
+  let out = ''
+  while (out.length < length) out += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, '0')
+  return out.slice(0, length)
+}
+
+/** Temporary number for an unposted real draft (no sequence consumed). */
+export function draftNumber(): string {
+  return `DRAFT-${randomHex(8).toUpperCase()}`
+}
+
+/** Number for test-run drafts — never posted, never numbered. */
+export function testNumber(): string {
+  return `TEST-${Date.now().toString(16)}-${randomHex(8)}`
+}
+
+export type NumberScope = { tenantId: string; organizationId: string }
+
+/**
+ * Claims the next number of a series. MUST run inside the caller's
+ * transaction (post command / receipt capture) so a rollback releases it.
+ */
+export async function claimDocumentNumber(
+  em: EntityManager,
+  scope: NumberScope,
+  series: DocumentSeries,
+  mask: string,
+  issueDate: Date,
+): Promise<{ number: string; seq: number; scopeKey: string }> {
+  const scopeKey = sequenceScopeKey(mask, issueDate)
+  const now = new Date()
+  const rows = (await em.execute(
+    `INSERT INTO billing_document_sequences
+       (tenant_id, organization_id, series, scope_key, next_value, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 2, ?, ?)
+     ON CONFLICT (tenant_id, organization_id, series, scope_key)
+     DO UPDATE SET next_value = billing_document_sequences.next_value + 1, updated_at = EXCLUDED.updated_at
+     RETURNING next_value - 1 AS seq`,
+    [scope.tenantId, scope.organizationId, series, scopeKey, now, now],
+  )) as unknown as Array<{ seq: number | string }> | undefined
+  const seq = Number(rows?.[0]?.seq)
+  if (!Number.isFinite(seq) || seq < 1) {
+    throw new Error(`Failed to claim a ${series} number`)
+  }
+  return { number: renderNumber(mask, { seq, issueDate }), seq, scopeKey }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Overdue is computed, never stored (Spec B, B-D6):
+ *
+ *   status ∈ {posted, partially_paid} AND due_date < today AND outstanding > 0
+ *
+ * Receivable documents only (invoices and debit memos). One definition shared
+ * by the in-memory predicate (UI / tests) and the SQL fragment (invoice list,
+ * account summary), so the two can never disagree. No worker until dunning.
+ */
+
+export const OPEN_STATUSES = ['posted', 'partially_paid'] as const
+export const RECEIVABLE_DOCUMENT_TYPES = ['invoice', 'debit_memo'] as const
+
+export type OverdueCandidate = {
+  status: string
+  documentType?: string | null
+  dueDate: Date | string | null | undefined
+  outstanding: string | number | null | undefined
+}
+
+function dayNumber(value: Date | string): number {
+  const date = typeof value === 'string' ? new Date(`${value.slice(0, 10)}T00:00:00Z`) : value
+  return Math.floor(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()) / 86_400_000)
+}
+
+export function isOverdue(doc: OverdueCandidate, today: Date): boolean {
+  return daysOverdue(doc, today) > 0
+}
+
+/** Whole days past the due date; 0 when not overdue. */
+export function daysOverdue(doc: OverdueCandidate, today: Date): number {
+  if (!(OPEN_STATUSES as readonly string[]).includes(doc.status)) return 0
+  if (doc.documentType && !(RECEIVABLE_DOCUMENT_TYPES as readonly string[]).includes(doc.documentType)) return 0
+  if (!doc.dueDate) return 0
+  const outstanding = typeof doc.outstanding === 'number' ? doc.outstanding : Number.parseFloat(doc.outstanding ?? '0')
+  if (!(outstanding > 0)) return 0
+  return Math.max(0, dayNumber(today) - dayNumber(doc.dueDate))
+}
+
+/** `YYYY-MM-DD` of a date in UTC — the `today` parameter for SQL. */
+export function isoDay(date: Date): string {
+  return date.toISOString().slice(0, 10)
+}
+
+/**
+ * SQL predicate for overdue documents on alias `alias`. Bind one parameter:
+ * today as `YYYY-MM-DD`.
+ */
+export function overdueSql(alias: string): string {
+  return (
+    `(${alias}.status IN ('posted', 'partially_paid')` +
+    ` AND ${alias}.document_type IN ('invoice', 'debit_memo')` +
+    ` AND ${alias}.due_date < ?::date AND ${alias}.outstanding > 0)`
+  )
+}
+
+/** SQL expression for days overdue (0 when not overdue). Bind today twice. */
+export function daysOverdueSql(alias: string): string {
+  return `(CASE WHEN ${overdueSql(alias)} THEN (?::date - ${alias}.due_date) ELSE 0 END)`
+}