@dainamite/billing 0.19.0 → 0.21.0

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

@@ -0,0 +1,86 @@
+import { counterpartAmount, lineVat, priceBasisOf, unitPriceNetOf } from '../../lib/lineAmounts'
+import { billingItemCreateSchema, isTieredRate } from '../../data/validators'
+
+describe('lineVat (Spec F, F-D2)', () => {
+  it('net basis: tax on top of the net', () => {
+    expect(lineVat({ amount: 49, priceBasis: 'net', taxRate: 23 })).toEqual({ net: 49, tax: 11.27, gross: 60.27 })
+  })
+
+  it('gross basis: the typed gross is reproduced exactly, for every cent', () => {
+    // Net-only storage cannot reach ~1 in 5 gross values at 23 %; the basis can.
+    for (let cents = 4900; cents <= 5100; cents += 1) {
+      const gross = cents / 100
+      const vat = lineVat({ amount: gross, priceBasis: 'gross', taxRate: 23 })
+      expect(vat.gross).toBe(gross)
+      expect(Math.round((vat.net + vat.tax) * 100)).toBe(cents)
+    }
+  })
+
+  it('gross basis: rounds once on the extended amount (quantity / proration)', () => {
+    // 3 × 12.30 gross = 36.90 → net 30.00, tax 6.90 (not 3 × rounded unit nets).
+    expect(lineVat({ amount: 36.9, priceBasis: 'gross', taxRate: 23 })).toEqual({ net: 30, tax: 6.9, gross: 36.9 })
+    // Prorated 16/30 of 49.99 gross = 26.66 (2 dp) → split on that amount.
+    const prorated = lineVat({ amount: 26.66, priceBasis: 'gross', taxRate: 23 })
+    expect(prorated.gross).toBe(26.66)
+    expect(prorated.net).toBe(21.67)
+  })
+
+  it('0 % VAT: net = gross on both bases; negative amounts keep their sign', () => {
+    expect(lineVat({ amount: 20, priceBasis: 'gross', taxRate: 0 })).toEqual({ net: 20, tax: 0, gross: 20 })
+    expect(lineVat({ amount: '-12.30', priceBasis: 'gross', taxRate: '23' })).toEqual({ net: -10, tax: -2.3, gross: -12.3 })
+  })
+})
+
+describe('price basis helpers', () => {
+  it('priceBasisOf treats anything but gross as net', () => {
+    expect(priceBasisOf('gross')).toBe('gross')
+    expect(priceBasisOf('net')).toBe('net')
+    expect(priceBasisOf(undefined)).toBe('net')
+  })
+
+  it('unitPriceNetOf keeps the net price and derives it from a gross one (4 dp)', () => {
+    expect(unitPriceNetOf(49, 'net', 23)).toBe('49.0000')
+    expect(unitPriceNetOf(60.27, 'gross', 23)).toBe('49.0000')
+    expect(unitPriceNetOf(10, 'gross', 0)).toBe('10.0000')
+  })
+
+  it('counterpartAmount shows the other side for the form preview', () => {
+    expect(counterpartAmount(49, 'net', 23)).toBe(60.27)
+    expect(counterpartAmount(60.27, 'gross', 23)).toBe(49)
+  })
+})
+
+describe('item validators — price basis', () => {
+  const base = {
+    tenantId: '11111111-1111-4111-8111-111111111111',
+    organizationId: '22222222-2222-4222-8222-222222222222',
+    billAccountId: '33333333-3333-4333-8333-333333333333',
+    billStartDate: '2026-11-14',
+    description: 'Plan',
+  }
+
+  it('accepts a gross basis on recurring and simple usage rates', () => {
+    expect(billingItemCreateSchema.safeParse({ ...base, type: 'recurring', rateJson: { unit_price: 60 }, priceBasis: 'gross' }).success).toBe(true)
+    expect(
+      billingItemCreateSchema.safeParse({ ...base, type: 'usage', uomCode: 'gb', rateJson: { unit_price: 0.5 }, priceBasis: 'gross' }).success,
+    ).toBe(true)
+  })
+
+  it('rejects a gross basis on a tiered usage rate', () => {
+    const result = billingItemCreateSchema.safeParse({
+      ...base,
+      type: 'usage',
+      uomCode: 'gb',
+      priceBasis: 'gross',
+      rateJson: { model: 'volume', tiers: [{ up_to: null, unit_price: 1 }] },
+    })
+    expect(result.success).toBe(false)
+    if (!result.success) expect(result.error.issues.map((i) => i.message)).toContain('billing.item.gross_tiered_unsupported')
+  })
+
+  it('isTieredRate recognises the tiered shape only', () => {
+    expect(isTieredRate({ model: 'graduated', tiers: [] })).toBe(true)
+    expect(isTieredRate({ unit_price: 1 })).toBe(false)
+    expect(isTieredRate(null)).toBe(false)
+  })
+})

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

@@ -0,0 +1,71 @@
+import {
+  ITEMS_LIST_HREF,
+  accountHref,
+  itemDetailHref,
+  resolveItemReturnTarget,
+  INVOICES_LIST_HREF,
+  invoiceDetailHref,
+  invoicePdfHref,
+  resolveInvoiceReturnTarget,
+  isAccountTab,
+} from '../../lib/navigation'
+
+describe('resolveItemReturnTarget', () => {
+  it('returns to the owning account by default', () => {
+    expect(resolveItemReturnTarget({ billAccountId: 'acc-1' })).toBe('/backend/billing/accounts/acc-1?tab=items')
+  })
+
+  it('returns to the items list when opened from it', () => {
+    expect(resolveItemReturnTarget({ from: 'items', billAccountId: 'acc-1' })).toBe(ITEMS_LIST_HREF)
+  })
+
+  it('ignores unknown `from` values', () => {
+    expect(resolveItemReturnTarget({ from: 'elsewhere', billAccountId: 'acc-1' })).toBe(accountHref('acc-1', 'items'))
+  })
+
+  it('falls back to the items list without an account', () => {
+    expect(resolveItemReturnTarget({})).toBe(ITEMS_LIST_HREF)
+    expect(resolveItemReturnTarget({ billAccountId: '  ' })).toBe(ITEMS_LIST_HREF)
+    expect(resolveItemReturnTarget({ from: null, billAccountId: null })).toBe(ITEMS_LIST_HREF)
+  })
+})
+
+describe('itemDetailHref', () => {
+  it('tags links from the items list', () => {
+    expect(itemDetailHref('it-1')).toBe('/backend/billing/items/it-1')
+    expect(itemDetailHref('it-1', { fromItemsList: true })).toBe('/backend/billing/items/it-1?from=items')
+  })
+})
+
+describe('invoice navigation (Spec B)', () => {
+  it('links to the invoice with a return-to-account marker when opened from an account', () => {
+    expect(invoiceDetailHref('inv-1')).toBe('/backend/billing/invoices/inv-1')
+    expect(invoiceDetailHref('inv-1', { fromAccountId: 'acc 1' })).toBe(
+      '/backend/billing/invoices/inv-1?from=account&accountId=acc%201',
+    )
+  })
+
+  it('returns to the account only when opened from it', () => {
+    expect(resolveInvoiceReturnTarget({ from: 'account', accountId: 'acc-1' })).toBe(accountHref('acc-1', 'invoices'))
+    expect(resolveInvoiceReturnTarget({ from: 'account', accountId: ' ' })).toBe(INVOICES_LIST_HREF)
+    expect(resolveInvoiceReturnTarget({ from: null, accountId: 'acc-1' })).toBe(INVOICES_LIST_HREF)
+  })
+
+  it('builds the PDF endpoint', () => {
+    expect(invoicePdfHref('inv-1')).toBe('/api/billing/invoices/inv-1/pdf')
+  })
+})
+
+describe('account workspace tabs (Spec F, F8)', () => {
+  it('deep-links a tab and leaves the default overview out of the URL', () => {
+    expect(accountHref('acc-1')).toBe('/backend/billing/accounts/acc-1')
+    expect(accountHref('acc-1', 'overview')).toBe('/backend/billing/accounts/acc-1')
+    expect(accountHref('acc-1', 'runs')).toBe('/backend/billing/accounts/acc-1?tab=runs')
+  })
+
+  it('recognises valid tab ids only', () => {
+    expect(isAccountTab('invoices')).toBe(true)
+    expect(isAccountTab('nope')).toBe(false)
+    expect(isAccountTab(null)).toBe(false)
+  })
+})

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)
+  })
+})
+