@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,91 @@
+import {
+  DEFAULT_NUMBER_MASKS,
+  claimDocumentNumber,
+  draftNumber,
+  maskFor,
+  parseMask,
+  renderNumber,
+  sequenceScopeKey,
+  testNumber,
+  validateMask,
+} from '../../lib/numbering'
+
+const nov = new Date('2026-11-14T00:00:00Z')
+const dec = new Date('2026-12-01T00:00:00Z')
+const jan = new Date('2027-01-05T00:00:00Z')
+
+describe('validateMask', () => {
+  it('accepts the defaults and simple masks', () => {
+    for (const mask of Object.values(DEFAULT_NUMBER_MASKS)) expect(validateMask(mask)).toEqual([])
+    expect(validateMask('INV-{SEQUENCE_NUM}')).toEqual([])
+    expect(validateMask('FV/{SEQUENCE_NUM_YEAR:5}/{YY}')).toEqual([])
+  })
+
+  it('rejects masks without or with several sequences', () => {
+    expect(validateMask('INV/{YYYY}')).toContain('mask_missing_sequence')
+    expect(validateMask('{SEQUENCE_NUM}/{SEQUENCE_NUM_YEAR}/{YYYY}')).toContain('mask_multiple_sequences')
+    expect(validateMask('  ')).toEqual(['mask_empty'])
+  })
+
+  it('requires the date parts a scoped counter resets on', () => {
+    expect(validateMask('INV/{SEQUENCE_NUM_YEAR}')).toContain('mask_year_scope_needs_year')
+    expect(validateMask('INV/{YYYY}/{SEQUENCE_NUM_MONTH}')).toContain('mask_month_scope_needs_year_and_month')
+    expect(validateMask('INV/{MM}/{SEQUENCE_NUM_MONTH}')).toContain('mask_month_scope_needs_year_and_month')
+  })
+
+  it('rejects unknown tokens, stray braces and overlong masks', () => {
+    expect(validateMask('INV/{YEAR}/{SEQUENCE_NUM}')).toContain('mask_unknown_token')
+    expect(validateMask('INV/{SEQUENCE_NUM}}')).toContain('mask_unknown_token')
+    expect(validateMask(`${'X'.repeat(70)}{SEQUENCE_NUM}`)).toContain('mask_too_long')
+  })
+})
+
+describe('scope keys and rendering', () => {
+  it('derives the counter scope from the mask and the issue date', () => {
+    expect(sequenceScopeKey('INV-{SEQUENCE_NUM}', nov)).toBe('')
+    expect(sequenceScopeKey('INV/{YYYY}/{SEQUENCE_NUM_YEAR}', nov)).toBe('2026')
+    expect(sequenceScopeKey('INV/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH}', nov)).toBe('2026-11')
+    expect(sequenceScopeKey('INV/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH}', dec)).toBe('2026-12')
+    expect(sequenceScopeKey('INV/{YYYY}/{SEQUENCE_NUM_YEAR}', jan)).toBe('2027')
+  })
+
+  it('renders every token with optional padding', () => {
+    expect(renderNumber(DEFAULT_NUMBER_MASKS.invoice, { seq: 1, issueDate: nov })).toBe('INV/2026/11/0001')
+    expect(renderNumber('FV/{YY}{MM}{DD}-{SEQUENCE_NUM}', { seq: 42, issueDate: nov })).toBe('FV/261114-42')
+    expect(renderNumber('X{SEQUENCE_NUM_YEAR:2}', { seq: 123, issueDate: nov })).toBe('X123')
+  })
+
+  it('parses scope and padding', () => {
+    expect(parseMask(DEFAULT_NUMBER_MASKS.receipt)).toEqual({ scope: 'month', pad: 4, hasYear: true, hasMonth: true })
+  })
+
+  it('falls back to the default mask when the configured one is invalid', () => {
+    expect(maskFor({ invoice: 'BAD' }, 'invoice')).toBe(DEFAULT_NUMBER_MASKS.invoice)
+    expect(maskFor({ invoice: 'A-{SEQUENCE_NUM}' }, 'invoice')).toBe('A-{SEQUENCE_NUM}')
+    expect(maskFor(null, 'credit_memo')).toBe(DEFAULT_NUMBER_MASKS.credit_memo)
+  })
+
+  it('builds temporary numbers that can never look like a posted one', () => {
+    expect(draftNumber()).toMatch(/^DRAFT-[0-9A-F]{8}$/)
+    expect(testNumber()).toMatch(/^TEST-/)
+  })
+})
+
+describe('claimDocumentNumber', () => {
+  it('upserts the scoped counter and renders the claimed value', async () => {
+    const execute = jest.fn(async () => [{ seq: '7' }])
+    const em = { execute } as never
+    const res = await claimDocumentNumber(em, { tenantId: 't', organizationId: 'o' }, 'invoice', DEFAULT_NUMBER_MASKS.invoice, nov)
+    expect(res).toEqual({ number: 'INV/2026/11/0007', seq: 7, scopeKey: '2026-11' })
+    const [sql, params] = execute.mock.calls[0] as unknown as [string, unknown[]]
+    expect(sql).toMatch(/ON CONFLICT \(tenant_id, organization_id, series, scope_key\)/)
+    expect(params.slice(0, 4)).toEqual(['t', 'o', 'invoice', '2026-11'])
+  })
+
+  it('fails loudly when the database returns no sequence', async () => {
+    const em = { execute: jest.fn(async () => []) } as never
+    await expect(
+      claimDocumentNumber(em, { tenantId: 't', organizationId: 'o' }, 'receipt', DEFAULT_NUMBER_MASKS.receipt, nov),
+    ).rejects.toThrow('Failed to claim a receipt number')
+  })
+})

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

@@ -0,0 +1,36 @@
+import { daysOverdue, daysOverdueSql, isOverdue, overdueSql } from '../../lib/overdue'
+
+const today = new Date('2026-11-14T15:00:00Z')
+const base = { status: 'posted', documentType: 'invoice', dueDate: '2026-11-10', outstanding: '100.0000' }
+
+describe('overdue predicate (B-D6)', () => {
+  it('posted / partially paid receivables past due with outstanding > 0 are overdue', () => {
+    expect(daysOverdue(base, today)).toBe(4)
+    expect(isOverdue({ ...base, status: 'partially_paid' }, today)).toBe(true)
+    expect(isOverdue({ ...base, documentType: 'debit_memo' }, today)).toBe(true)
+  })
+
+  it('the due date itself is not overdue (strictly before today)', () => {
+    expect(isOverdue({ ...base, dueDate: '2026-11-14' }, today)).toBe(false)
+    expect(daysOverdue({ ...base, dueDate: new Date('2026-11-13T00:00:00Z') }, today)).toBe(1)
+  })
+
+  it('drafts, paid, credited, receipts, credit memos and settled documents are never overdue', () => {
+    for (const status of ['draft', 'paid', 'credited']) expect(isOverdue({ ...base, status }, today)).toBe(false)
+    expect(isOverdue({ ...base, documentType: 'receipt' }, today)).toBe(false)
+    expect(isOverdue({ ...base, documentType: 'credit_memo' }, today)).toBe(false)
+    expect(isOverdue({ ...base, outstanding: '0' }, today)).toBe(false)
+    expect(isOverdue({ ...base, outstanding: -5 }, today)).toBe(false)
+    expect(isOverdue({ ...base, dueDate: null }, today)).toBe(false)
+  })
+
+  it('SQL mirrors the predicate with one / two bound dates', () => {
+    const sql = overdueSql('i')
+    expect(sql).toContain("i.status IN ('posted', 'partially_paid')")
+    expect(sql).toContain("i.document_type IN ('invoice', 'debit_memo')")
+    expect(sql).toContain('i.due_date < ?::date')
+    expect(sql).toContain('i.outstanding > 0')
+    expect((sql.match(/\?/g) ?? []).length).toBe(1)
+    expect((daysOverdueSql('i').match(/\?/g) ?? []).length).toBe(2)
+  })
+})

package/src/modules/billing/__tests__/lib/paymentCsv.test.ts

@@ -0,0 +1,148 @@
+import { parsePaymentCsv, paymentSourceRef, sourceRefsForRows, splitCsv } from '../../lib/paymentCsv'
+import { extractInvoiceTokens, matchPayment, type MatchableDocument } from '../../lib/paymentMatcher'
+
+const HEADER = 'date,amount,currency,reference,payer_name,payer_account'
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+
+describe('splitCsv', () => {
+  it('handles quotes, escaped quotes, commas and newlines inside quotes, CRLF', () => {
+    const records = splitCsv('a,"b, c","d ""q"""\r\n1,"multi\nline",3\n')
+    expect(records).toEqual([
+      { line: 1, fields: ['a', 'b, c', 'd "q"'] },
+      { line: 2, fields: ['1', 'multi\nline', '3'] },
+    ])
+  })
+})
+
+describe('parsePaymentCsv', () => {
+  it('parses valid rows (BOM, case-insensitive header, normalised amount / currency / IBAN)', () => {
+    const result = parsePaymentCsv(
+      `Date,Amount,Currency,Reference,Payer_Name,Payer_Account\n2026-11-20,123,pln,"Payment for INV/2026/11/0003",ACME,pl61 1090 1014\n`,
+    )
+    expect(result.fatal).toBeNull()
+    expect(result.rows).toEqual([
+      {
+        line: 2,
+        receivedAt: '2026-11-20',
+        amount: '123.0000',
+        currency: 'PLN',
+        reference: 'Payment for INV/2026/11/0003',
+        payerName: 'ACME',
+        payerAccount: 'PL6110901014',
+      },
+    ])
+  })
+
+  it('reports invalid rows with line numbers and keeps the valid ones', () => {
+    const result = parsePaymentCsv(
+      [HEADER, '2026-11-20,0,PLN,x,,', '20.11.2026,10,PLN,x,,', '2026-11-20,10,PLN,x', '2026-11-20,1,000.50,PLN,x,,', '2026-11-21,10.5,EUR,,,'].join('\n'),
+    )
+    expect(result.rows.map((r) => r.line)).toEqual([6])
+    expect(result.errors.map((e) => e.row)).toEqual([2, 3, 4, 5])
+    expect(result.errors[0].message).toContain('greater than 0')
+  })
+
+  it('rejects a wrong header or an empty file as fatal', () => {
+    expect(parsePaymentCsv('').fatal).toBeTruthy()
+    expect(parsePaymentCsv('date;amount\n').fatal).toContain('header')
+  })
+
+  it('caps the file at 5,000 rows', () => {
+    const rows = Array.from({ length: 5001 }, () => '2026-11-20,1,PLN,x,,')
+    expect(parsePaymentCsv([HEADER, ...rows].join('\n')).fatal).toContain('5000')
+  })
+})
+
+describe('source refs (duplicate guard)', () => {
+  const row = { receivedAt: '2026-11-20', amount: '10.0000', currency: 'PLN', reference: 'x', payerAccount: null }
+
+  it('is stable for the same line and differs per occurrence within a file', () => {
+    expect(paymentSourceRef(scope, row, 1)).toBe(paymentSourceRef(scope, row, 1))
+    expect(paymentSourceRef(scope, row, 1)).not.toBe(paymentSourceRef(scope, row, 2))
+    const rows = [row, row, { ...row, amount: '11.0000' }].map((r, i) => ({ ...r, line: i + 2, payerName: null }))
+    const refs = sourceRefsForRows(scope, rows)
+    expect(new Set(refs).size).toBe(3)
+    expect(refs[0]).toBe(paymentSourceRef(scope, row, 1))
+    expect(refs[1]).toBe(paymentSourceRef(scope, row, 2))
+  })
+
+  it('is scoped per organization', () => {
+    expect(paymentSourceRef(scope, row, 1)).not.toBe(paymentSourceRef({ ...scope, organizationId: 'o-2' }, row, 1))
+  })
+})
+
+describe('extractInvoiceTokens', () => {
+  it('extracts number-like tokens, upper-cased, without trailing punctuation', () => {
+    expect(extractInvoiceTokens('Payment for inv/2026/11/0003, INV/2026/11/0004.')).toEqual(['INV/2026/11/0003', 'INV/2026/11/0004'])
+    expect(extractInvoiceTokens('thanks for the service')).toEqual([])
+    expect(extractInvoiceTokens(null)).toEqual([])
+  })
+})
+
+describe('matchPayment', () => {
+  const doc = (overrides: Partial<MatchableDocument>): MatchableDocument => ({
+    invoiceId: 'i-1',
+    number: 'INV/2026/11/0001',
+    billAccountId: 'acc-1',
+    billingMode: 'postpaid',
+    currencyCode: 'PLN',
+    documentType: 'invoice',
+    status: 'posted',
+    outstanding: '123.0000',
+    ...overrides,
+  })
+  const lookup = (...docs: MatchableDocument[]) => new Map(docs.map((d) => [d.number.toUpperCase(), d]))
+
+  it('allocates to referenced open invoices of one account', () => {
+    const a = doc({})
+    const b = doc({ invoiceId: 'i-2', number: 'INV/2026/11/0002' })
+    expect(matchPayment({ reference: 'INV/2026/11/0001 + INV/2026/11/0002', currency: 'pln' }, lookup(a, b))).toEqual({
+      outcome: 'allocate',
+      billAccountId: 'acc-1',
+      invoiceIds: ['i-1', 'i-2'],
+    })
+  })
+
+  it('no reference / unknown number → unmatched(no_reference)', () => {
+    expect(matchPayment({ reference: 'gift', currency: 'PLN' }, lookup(doc({})))).toMatchObject({ outcome: 'unmatched', reason: 'no_reference' })
+    expect(matchPayment({ reference: 'INV/9', currency: 'PLN' }, lookup(doc({})))).toMatchObject({ reason: 'no_reference' })
+  })
+
+  it('references to two different accounts are ambiguous → unmatched', () => {
+    const other = doc({ invoiceId: 'i-9', number: 'INV/9/1', billAccountId: 'acc-2' })
+    expect(matchPayment({ reference: 'INV/2026/11/0001 INV/9/1', currency: 'PLN' }, lookup(doc({}), other))).toMatchObject({
+      outcome: 'unmatched',
+      reason: 'no_reference',
+      billAccountId: null,
+    })
+  })
+
+  it('prepaid accounts and top-up receipts → unmatched(prepaid_account) with the account kept', () => {
+    expect(matchPayment({ reference: 'INV/2026/11/0001', currency: 'PLN' }, lookup(doc({ billingMode: 'prepaid' })))).toEqual({
+      outcome: 'unmatched',
+      billAccountId: 'acc-1',
+      reason: 'prepaid_account',
+    })
+    expect(matchPayment({ reference: 'RC/2026/11/0001', currency: 'PLN' }, lookup(doc({ number: 'RC/2026/11/0001', documentType: 'receipt', status: 'paid' })))).toMatchObject({
+      reason: 'prepaid_account',
+    })
+  })
+
+  it('currency mismatch → unmatched(currency_mismatch)', () => {
+    expect(matchPayment({ reference: 'INV/2026/11/0001', currency: 'EUR' }, lookup(doc({})))).toMatchObject({ reason: 'currency_mismatch' })
+  })
+
+  it('already paid invoice → account credit', () => {
+    expect(matchPayment({ reference: 'INV/2026/11/0001', currency: 'PLN' }, lookup(doc({ status: 'paid', outstanding: '0' })))).toEqual({
+      outcome: 'credit',
+      billAccountId: 'acc-1',
+      reason: 'invoice_already_paid',
+    })
+  })
+
+  it('debit memos are matchable receivables', () => {
+    expect(matchPayment({ reference: 'INV/2026/11/0009', currency: 'PLN' }, lookup(doc({ number: 'INV/2026/11/0009', documentType: 'debit_memo' })))).toMatchObject({
+      outcome: 'allocate',
+    })
+  })
+})

package/src/modules/billing/__tests__/lib/paymentImport.test.ts

@@ -0,0 +1,113 @@
+jest.mock('../../lib/accountLock', () => ({
+  withAccountLock: jest.fn(async (em: unknown, _scope: unknown, fn: (tem: unknown) => Promise<unknown>) => fn(em)),
+}))
+jest.mock('../../lib/allocation', () => {
+  const actual = jest.requireActual('../../lib/allocation')
+  return {
+    ...actual,
+    allocate: jest.fn(async () => actual.emptyEffects()),
+    applyAccountCredit: jest.fn(async () => actual.emptyEffects()),
+    loadOpenReceivables: jest.fn(async (_tem: unknown, _scope: unknown, _account: unknown, ids: string[]) =>
+      ids.map((id: string) => ({ id, outstandingCents: 10000, dueDate: null, issueDate: null, number: id })),
+    ),
+  }
+})
+
+import { BillingPayment, BillingPaymentImport } from '../../data/entities'
+import { allocate, applyAccountCredit } from '../../lib/allocation'
+import { withAccountLock } from '../../lib/accountLock'
+import { importPayments } from '../../lib/paymentImport'
+import { paymentSourceRef } from '../../lib/paymentCsv'
+
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+const HEADER = 'date,amount,currency,reference,payer_name,payer_account'
+
+function makeEm(opts: { existingRefs?: string[]; statusCounts?: Array<{ status: string; n: number }> } = {}) {
+  const created: Array<{ entity: string; data: Record<string, unknown> }> = []
+  let seq = 0
+  const em = {
+    execute: jest.fn(async (sql: string) => {
+      if (sql.includes('SELECT source_ref')) return (opts.existingRefs ?? []).map((source_ref) => ({ source_ref }))
+      if (sql.includes('upper(i.number)')) {
+        return [
+          { id: 'inv-1', number: 'INV/2026/11/0001', bill_account_id: 'acc-1', billing_mode: 'postpaid', currency_code: 'PLN', document_type: 'invoice', status: 'posted', outstanding: '100.0000' },
+          { id: 'inv-2', number: 'INV/2026/11/0002', bill_account_id: 'acc-2', billing_mode: 'postpaid', currency_code: 'PLN', document_type: 'invoice', status: 'paid', outstanding: '0' },
+        ]
+      }
+      if (sql.includes('GROUP BY status')) return opts.statusCounts ?? []
+      return []
+    }),
+    create: jest.fn((entity: { name: string }, data: Record<string, unknown>) => {
+      const row = { id: `${entity.name}-${++seq}`, ...data }
+      created.push({ entity: entity.name, data: row })
+      return row
+    }),
+    persist: jest.fn(),
+    flush: jest.fn(async () => undefined),
+    nativeUpdate: jest.fn(async () => 1),
+  }
+  return { em, created }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('importPayments', () => {
+  const csv = [
+    HEADER,
+    '2026-11-20,100.00,PLN,Payment INV/2026/11/0001,ACME,',
+    '2026-11-21,40.00,PLN,INV/2026/11/0002 again,Globex,',
+    '2026-11-22,15.00,PLN,thanks,Unknown,',
+    '2026-11-23,10.00,EUR,INV/2026/11/0001,ACME,',
+    '2026-11-24,-5,PLN,bad,,',
+  ].join('\n')
+
+  it('creates one payment per new row with the matcher outcome and settles per account', async () => {
+    const { em, created } = makeEm({
+      statusCounts: [
+        { status: 'allocated', n: 1 },
+        { status: 'matched', n: 1 },
+        { status: 'unmatched', n: 2 },
+      ],
+    })
+    const { summary } = await importPayments(em as never, { scope, fileName: 'bank.csv', content: csv, userId: 'u-1' })
+
+    const payments = created.filter((c) => c.entity === BillingPayment.name).map((c) => c.data)
+    expect(payments.map((p) => [p.status, p.billAccountId, p.matchReason])).toEqual([
+      ['matched', 'acc-1', null],
+      ['matched', 'acc-2', 'invoice_already_paid'],
+      ['unmatched', null, 'no_reference'],
+      ['unmatched', 'acc-1', 'currency_mismatch'],
+    ])
+    expect(created.find((c) => c.entity === BillingPaymentImport.name)!.data).toMatchObject({ fileName: 'bank.csv', rowCount: 5, userId: 'u-1' })
+
+    // One lock per matched account; referenced invoice allocated, then credit for the remainder.
+    expect((withAccountLock as jest.Mock).mock.calls.map((c) => c[1].billAccountId)).toEqual(['acc-1', 'acc-2'])
+    expect(allocate).toHaveBeenCalledTimes(1)
+    expect((allocate as jest.Mock).mock.calls[0][2]).toMatchObject({ invoiceId: 'inv-1', amountCents: 10000, by: 'auto' })
+    expect(applyAccountCredit).toHaveBeenCalledTimes(2)
+
+    expect(summary.counts).toEqual({ allocated: 1, partially_allocated: 0, matched: 1, unmatched: 2, duplicate: 0, rejected: 1 })
+    expect(summary.errors).toEqual([expect.objectContaining({ row: 6 })])
+  })
+
+  it('counts already imported lines as duplicates and does not store them again', async () => {
+    const line = { receivedAt: '2026-11-20', amount: '100.0000', currency: 'PLN', reference: 'Payment INV/2026/11/0001', payerAccount: null }
+    const { em, created } = makeEm({ existingRefs: [paymentSourceRef(scope, line, 1)] })
+    const { summary } = await importPayments(em as never, {
+      scope,
+      fileName: 'bank.csv',
+      content: [HEADER, '2026-11-20,100.00,PLN,Payment INV/2026/11/0001,ACME,'].join('\n'),
+    })
+    expect(created.filter((c) => c.entity === BillingPayment.name)).toHaveLength(0)
+    expect(summary.counts.duplicate).toBe(1)
+    expect(withAccountLock).not.toHaveBeenCalled()
+  })
+
+  it('rejects an invalid file with 400', async () => {
+    const { em } = makeEm()
+    await expect(importPayments(em as never, { scope, fileName: 'x.csv', content: 'nope' })).rejects.toMatchObject({
+      status: 400,
+      body: expect.objectContaining({ code: 'billing.payment_import.invalid_file' }),
+    })
+  })
+})

package/src/modules/billing/__tests__/lib/paymentsSample.test.ts

@@ -0,0 +1,73 @@
+import { buildPaymentsSampleCsv } from '../../lib/seeds/paymentsSample'
+import { parsePaymentCsv } from '../../lib/paymentCsv'
+import { matchPayment, type MatchableDocument } from '../../lib/paymentMatcher'
+
+const invoices = [1, 2, 3, 4, 5, 6].map((n) => ({
+  number: `INV/2026/11/000${n}`,
+  totalGross: `${n * 100}.0000`,
+  currencyCode: 'PLN',
+  accountName: n % 2 ? 'Northwind, Ltd' : 'Globex',
+}))
+const receipt = { number: 'RC/2026/11/0001', currencyCode: 'PLN', accountName: 'Prepaid Co' }
+
+describe('buildPaymentsSampleCsv', () => {
+  it('produces a parseable CSV covering every outcome', () => {
+    const sample = buildPaymentsSampleCsv({ invoices, receipt, date: '2026-11-20' })
+    expect(sample.missing).toEqual([])
+    const parsed = parsePaymentCsv(sample.csv)
+    expect(parsed.fatal).toBeNull()
+    expect(parsed.errors).toEqual([])
+    expect(parsed.rows).toHaveLength(10)
+    expect(parsed.rows.map((r) => r.amount)).toEqual(
+      expect.arrayContaining(['100.0000', '100.0000', '350.0000', '1000.0000', '25.0000', '12.3400']),
+    )
+    // Payer names with commas are quoted.
+    expect(sample.csv).toContain('"Northwind, Ltd"')
+
+    const lookup = new Map<string, MatchableDocument>(
+      [
+        ...invoices.map((inv, i) => ({
+          invoiceId: `i${i}`,
+          number: inv.number,
+          billAccountId: inv.accountName,
+          billingMode: 'postpaid',
+          currencyCode: 'PLN',
+          documentType: 'invoice',
+          status: 'posted',
+          outstanding: inv.totalGross,
+        })),
+        { invoiceId: 'r', number: receipt.number, billAccountId: 'prepaid', billingMode: 'prepaid', currencyCode: 'PLN', documentType: 'receipt', status: 'paid', outstanding: '0' },
+      ].map((doc) => [doc.number.toUpperCase(), doc]),
+    )
+    const outcomes = parsed.rows.map((row) => {
+      const decision = matchPayment({ reference: row.reference, currency: row.currency }, lookup)
+      return decision.outcome === 'allocate' ? 'allocate' : decision.reason
+    })
+    expect(outcomes).toEqual([
+      'allocate',
+      'allocate',
+      'allocate',
+      'allocate', // two invoices of one account (4 and 6)
+      'no_reference',
+      'prepaid_account',
+      'no_reference',
+      'currency_mismatch',
+      'no_reference',
+      'no_reference',
+    ])
+  })
+
+  it('reports what it could not build with few invoices', () => {
+    const sample = buildPaymentsSampleCsv({ invoices: invoices.slice(0, 1), receipt: null, date: '2026-11-20' })
+    expect(sample.missing.length).toBeGreaterThanOrEqual(3)
+    expect(parsePaymentCsv(sample.csv).errors).toEqual([])
+  })
+
+  it('adds a row paying a posted debit memo by its number (Spec D)', () => {
+    const debitMemo = { number: 'INV/2026/11/0099', totalGross: '12.3000', currencyCode: 'PLN', accountName: 'Globex' }
+    const sample = buildPaymentsSampleCsv({ invoices, receipt, debitMemo, date: '2026-11-20' })
+    const parsed = parsePaymentCsv(sample.csv)
+    expect(parsed.rows.some((r) => r.reference === 'Note INV/2026/11/0099' && r.amount === '12.3000')).toBe(true)
+  })
+})
+

package/src/modules/billing/__tests__/lib/pdf/invoicePdf.test.ts

@@ -0,0 +1,199 @@
+import { PDFDocument } from 'pdf-lib'
+import {
+  buildInvoiceDocumentModel,
+  type DocumentTranslate,
+  type PdfInvoice,
+  type PdfLine,
+} from '../../../lib/pdf/invoiceModel'
+import { renderInvoicePdf, sanitizeForFont } from '../../../lib/pdf/invoiceTemplate'
+import en from '../../../i18n/en.json'
+import pl from '../../../i18n/pl.json'
+
+const translator = (dict: Record<string, string>): DocumentTranslate => (key, fallback) => dict[key] ?? fallback
+
+const invoice: PdfInvoice = {
+  number: 'INV/2026/11/0007',
+  documentType: 'invoice',
+  status: 'posted',
+  testRun: false,
+  issueDate: '2026-11-14',
+  dueDate: '2026-11-28',
+  billDate: '2026-11-01',
+  periodStart: '2026-11-01',
+  periodEnd: '2026-11-30',
+  currencyCode: 'PLN',
+  subtotalNet: '148.3300',
+  taxTotal: '25.6700',
+  totalGross: '174.0000',
+}
+
+const line = (overrides: Partial<PdfLine> = {}): PdfLine => ({
+  description: 'Internet 300 Mb/s',
+  quantity: '1.0000',
+  unitPriceNet: '100.0000',
+  taxRate: '23',
+  netAmount: '100.0000',
+  taxAmount: '23.0000',
+  grossAmount: '123.0000',
+  servicePeriodStart: '2026-11-01',
+  servicePeriodEnd: '2026-11-30',
+  ...overrides,
+})
+
+const lines = [
+  line(),
+  line({ description: 'Wsparcie priorytetowe', unitPriceNet: '33.3300', taxRate: '8', netAmount: '33.3300', taxAmount: '2.6700', grossAmount: '36.0000' }),
+  line({ description: 'Kopie zapasowe', unitPriceNet: '15.0000', taxRate: '0', netAmount: '15.0000', taxAmount: '0.0000', grossAmount: '15.0000', servicePeriodStart: null, servicePeriodEnd: null }),
+]
+
+const seller = {
+  legalName: 'Żółta Łódź sp. z o.o.',
+  address: { line1: 'ul. Świętokrzyska 1', city: 'Kraków', postal_code: '30-001', country: 'PL' },
+  taxId: 'PL1234563218',
+  bankName: 'Bank Śląski',
+  iban: 'PL61109010140000071219812874',
+  bic: 'WBKPPLPP',
+  footer: 'KRS 0000000000\nKapitał zakładowy 5 000 zł',
+}
+
+const buyer = { name: 'Jan Kowalski', address: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' }, taxId: null }
+
+function model(language: 'en' | 'pl', overrides: Partial<PdfInvoice> = {}, docLines: PdfLine[] = lines) {
+  return buildInvoiceDocumentModel({
+    invoice: { ...invoice, ...overrides },
+    lines: docLines,
+    seller,
+    buyer,
+    language,
+    translate: translator(language === 'pl' ? (pl as Record<string, string>) : (en as Record<string, string>)),
+  })
+}
+
+describe('buildInvoiceDocumentModel', () => {
+  it('builds English labels, en-GB dates and the payment title with the invoice number', () => {
+    const m = model('en')
+    expect(m.title).toBe('VAT invoice')
+    expect(m.meta).toEqual(
+      expect.arrayContaining([
+        ['Number', 'INV/2026/11/0007'],
+        ['Issue date', '14/11/2026'],
+        ['Due date', '28/11/2026'],
+      ]),
+    )
+    expect(m.payment?.lines).toEqual(
+      expect.arrayContaining(['IBAN: PL61 1090 1014 0000 0712 1981 2874', 'Transfer title: INV/2026/11/0007']),
+    )
+    expect(m.watermark).toBeNull()
+    expect(m.pageLabel(1, 3)).toBe('Page 1 of 3')
+  })
+
+  it('builds Polish labels and pl-PL money / dates', () => {
+    const m = model('pl')
+    expect(m.title).toBe('Faktura VAT')
+    expect(m.meta).toEqual(expect.arrayContaining([['Data wystawienia', '14.11.2026'], ['Termin płatności', '28.11.2026']]))
+    expect(m.totals[2]).toEqual(['Do zapłaty', '174,00 zł'])
+    expect(m.payment?.lines).toContain('Tytuł przelewu: INV/2026/11/0007')
+    expect(m.seller.heading).toBe('Sprzedawca')
+  })
+
+  it('groups the VAT summary by rate (highest first) and it adds up to the totals', () => {
+    const m = model('en')
+    expect(m.vatSummary.rows.map((r) => r[0])).toEqual(['23 %', '8 %', '0 %'])
+    const parse = (s: string) => Number.parseFloat(s.replace(/[^0-9.-]/g, ''))
+    const vat = m.vatSummary.rows.reduce((sum, r) => sum + parse(r[2]), 0)
+    expect(vat.toFixed(2)).toBe('25.67')
+  })
+
+  it('prints the service period on lines that carry one, once', () => {
+    const m = model('en')
+    expect(m.table.rows[0][1]).toBe('Internet 300 Mb/s (01/11/2026 – 30/11/2026)')
+    expect(m.table.rows[2][1]).toBe('Kopie zapasowe')
+    const dated = model('en', {}, [line({ description: 'Plan · 2026-11-15 – 2026-11-30' })])
+    expect(dated.table.rows[0][1]).toBe('Plan · 2026-11-15 – 2026-11-30')
+  })
+
+  it('watermarks drafts (no issue / due date yet) and test documents', () => {
+    const draft = model('en', { status: 'draft', number: 'DRAFT-1A2B3C4D', issueDate: null, dueDate: null })
+    expect(draft.watermark).toBe('DRAFT')
+    expect(draft.meta).toEqual(expect.arrayContaining([['Issue date', '—']]))
+    expect(model('pl', { status: 'draft', testRun: true }).watermark).toBe('TEST')
+  })
+
+  it('has no payment block without an IBAN or for receipts; credit memos show their settlement', () => {
+    expect(
+      buildInvoiceDocumentModel({ invoice, lines, seller: { ...seller, iban: null }, buyer, language: 'en', translate: translator({}) }).payment,
+    ).toBeNull()
+    expect(model('en', { documentType: 'receipt' }).payment).toBeNull()
+    const memo = model('en', {
+      documentType: 'credit_memo',
+      correctsNumber: 'INV/2026/10/0003',
+      correctsIssueDate: '2026-10-05',
+      correctionReason: 'Wrong price',
+    })
+    expect(memo.title).toBe('Credit memo')
+    // Spec D: a credit memo shows how it settles instead of payment instructions.
+    expect(memo.payment?.heading).toBe('Settlement')
+    expect(memo.payment?.lines.join(' ')).toContain('Settled against invoice INV/2026/10/0003')
+    expect(memo.payment?.lines.join(' ')).not.toContain('IBAN')
+    expect(memo.totals[2][0]).toBe('Total credited')
+    expect(memo.meta).toEqual(
+      expect.arrayContaining([
+        ['Corrects', 'INV/2026/10/0003 of 05/10/2026'],
+        ['Reason', 'Wrong price'],
+      ]),
+    )
+    const debit = model('pl', { documentType: 'debit_memo', correctsNumber: 'INV/2026/10/0003' })
+    expect(debit.title).toBe('Nota obciążeniowa')
+    expect(debit.payment?.lines).toContain('Tytuł przelewu: INV/2026/11/0007')
+  })
+
+  it('splits the footer into lines and falls back to English for unknown languages', () => {
+    expect(model('en').footer).toEqual(['KRS 0000000000', 'Kapitał zakładowy 5 000 zł'])
+    const de = buildInvoiceDocumentModel({ invoice, lines, seller, buyer, language: 'de', translate: translator({}) })
+    expect(de.meta[1]).toEqual(['Issue date', '14/11/2026'])
+  })
+})
+
+describe('renderInvoicePdf', () => {
+  it('renders a one-page A4 document with Polish text and the embedded font', async () => {
+    const bytes = await renderInvoicePdf(model('pl'))
+    const doc = await PDFDocument.load(bytes)
+    expect(doc.getPageCount()).toBe(1)
+    const [page] = doc.getPages()
+    expect(Math.round(page.getWidth())).toBe(595)
+    expect(doc.getTitle()).toBe('Faktura VAT INV/2026/11/0007')
+  }, 30_000)
+
+  it('paginates long invoices, repeating the table on every page', async () => {
+    const rows = (n: number) =>
+      Array.from({ length: n }, (_, i) =>
+        line({ description: `Usługa nr ${i + 1}`, servicePeriodStart: null, servicePeriodEnd: null }),
+      )
+    const pages = async (n: number) =>
+      (await PDFDocument.load(await renderInvoicePdf(model('pl', { status: 'draft' }, rows(n))))).getPageCount()
+    // ~31 single-line rows fit under the header on page 1, ~44 on later pages;
+    // the VAT summary, totals and payment block follow the last row.
+    expect(await pages(10)).toBe(1)
+    expect(await pages(40)).toBe(2)
+    expect(await pages(80)).toBe(3)
+  }, 30_000)
+
+  it('wraps long descriptions instead of overflowing the column', async () => {
+    const long = line({ description: 'Bardzo długi opis usługi '.repeat(12) })
+    const bytes = await renderInvoicePdf(model('en', {}, [long]))
+    expect((await PDFDocument.load(bytes)).getPageCount()).toBe(1)
+  }, 30_000)
+
+  it('never throws on characters outside the font (they become "?")', async () => {
+    const exotic = buildInvoiceDocumentModel({
+      invoice,
+      lines: [line({ description: 'Тест 中文 🚀' })],
+      seller,
+      buyer: { ...buyer, name: 'Ελληνικά' },
+      language: 'en',
+      translate: translator({}),
+    })
+    await expect(renderInvoicePdf(exotic)).resolves.toBeInstanceOf(Uint8Array)
+    expect(sanitizeForFont('Zażółć 🚀', new Set([...'Zażółć '].map((c) => c.codePointAt(0)!)))).toBe('Zażółć ?')
+  }, 30_000)
+})