@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,269 @@
+import { PDFDocument } from 'pdf-lib'
+import {
+  buildInvoiceDocumentModel,
+  type DocumentTranslate,
+  type PdfInvoice,
+  type PdfLine,
+} from '../../../lib/pdf/invoiceModel'
+import fontkit from '@pdf-lib/fontkit'
+import { TABLE_COLUMNS, renderInvoicePdf, sanitizeForFont, wrap } from '../../../lib/pdf/invoiceTemplate'
+import { NOTO_SANS_BOLD_BASE64 } from '../../../lib/pdf/fonts/embeddedFonts'
+import en from '../../../i18n/en.json'
+import pl from '../../../i18n/pl.json'
+import es from '../../../i18n/es.json'
+import de from '../../../i18n/de.json'
+import type { InvoiceLanguageCode } from '../../../lib/invoiceLanguages'
+
+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 }
+
+const DICTIONARIES: Record<InvoiceLanguageCode, Record<string, string>> = { en, pl, es, de }
+
+function model(language: InvoiceLanguageCode, overrides: Partial<PdfInvoice> = {}, docLines: PdfLine[] = lines) {
+  return buildInvoiceDocumentModel({
+    invoice: { ...invoice, ...overrides },
+    lines: docLines,
+    seller,
+    buyer,
+    language,
+    translate: translator(DICTIONARIES[language]),
+  })
+}
+
+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('builds Spanish labels and es-ES money / dates (invoice and credit memo)', () => {
+    const m = model('es', { currencyCode: 'EUR', totalGross: '1234.5600' })
+    expect(m.title).toBe('Factura')
+    expect(m.meta).toEqual(expect.arrayContaining([['Fecha de emisión', '14/11/2026']]))
+    expect(m.table.headers).toEqual(expect.arrayContaining(['Cant.', 'Precio unit.', '% IVA', 'IVA']))
+    expect(m.totals[0][0]).toBe('Base imponible')
+    expect(m.totals[2]).toEqual(['Total a pagar', '1234,56 €'])
+    // The payment matcher looks for the invoice number in the transfer title.
+    expect(m.payment?.lines).toContain('Concepto: INV/2026/11/0007')
+    expect(m.seller.heading).toBe('Emisor')
+    expect(m.buyer.heading).toBe('Cliente')
+    expect(m.vatSummary.heading).toBe('Resumen de IVA')
+    expect(m.pageLabel(1, 2)).not.toContain('{')
+    const memo = model('es', { documentType: 'credit_memo', correctsNumber: 'INV/2026/10/0003', correctsIssueDate: '2026-10-05' })
+    expect(memo.title).toBe('Factura rectificativa')
+    expect(memo.meta).toEqual(expect.arrayContaining([['Rectifica', 'INV/2026/10/0003 de 05/10/2026']]))
+    expect(memo.totals[2][0]).toBe('Total abonado')
+    expect(memo.payment?.lines.join(' ')).toContain('INV/2026/10/0003')
+    expect(model('es', { status: 'draft' }).watermark).toBe('BORRADOR')
+  })
+
+  it('builds German labels and de-DE money / dates (invoice and credit memo)', () => {
+    const m = model('de', { currencyCode: 'EUR', totalGross: '1234.5600' })
+    expect(m.title).toBe('Rechnung')
+    expect(m.meta).toEqual(expect.arrayContaining([['Leistungszeitraum', '01.11.2026 – 30.11.2026']]))
+    expect(m.table.headers).toEqual(expect.arrayContaining(['Anz.', 'Einzelpreis netto', 'USt. %', 'USt.']))
+    expect(m.totals[2]).toEqual(['Zahlbetrag', '1.234,56 €'])
+    expect(m.payment?.lines).toContain('Verwendungszweck: INV/2026/11/0007')
+    expect(m.seller.heading).toBe('Rechnungssteller')
+    expect(m.buyer.heading).toBe('Rechnungsempfänger')
+    const memo = model('de', { documentType: 'credit_memo', correctsNumber: 'INV/2026/10/0003', correctsIssueDate: '2026-10-05' })
+    expect(memo.title).toBe('Rechnungskorrektur')
+    expect(memo.meta).toEqual(expect.arrayContaining([['Korrigiert', 'INV/2026/10/0003 vom 05.10.2026']]))
+    expect(memo.totals[2][0]).toBe('Gutgeschriebener Betrag')
+    expect(model('de', { status: 'draft' }).watermark).toBe('ENTWURF')
+  })
+
+  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 unknown = buildInvoiceDocumentModel({ invoice, lines, seller, buyer, language: 'xx', translate: translator({}) })
+    expect(unknown.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.each(['es', 'de'] as const)('renders a one-page %s document with its own title and diacritics', async (language) => {
+    const m = model(language, { currencyCode: 'EUR' })
+    const doc = await PDFDocument.load(await renderInvoicePdf(m))
+    expect(doc.getPageCount()).toBe(1)
+    expect(doc.getTitle()).toBe(`${m.title} INV/2026/11/0007`)
+  }, 30_000)
+
+  it.each(['en', 'es', 'de', 'pl'] as const)(
+    'fits %s column headers in their columns with the real font (no mid-word split, at most 3 lines)',
+    async (language) => {
+      const doc = await PDFDocument.create()
+      doc.registerFontkit(fontkit)
+      const bold = await doc.embedFont(Buffer.from(NOTO_SANS_BOLD_BASE64, 'base64'), { subset: true })
+      // Same size / padding the template uses for table headers (SMALL_SIZE = 8, 3pt each side).
+      model(language).table.headers.forEach((header, i) => {
+        const width = TABLE_COLUMNS[i] - 6
+        const lines = wrap(header, bold, 8, width)
+        expect({ header, lines: lines.length }).toEqual({ header, lines: expect.any(Number) })
+        expect(lines.length).toBeLessThanOrEqual(3)
+        // Every wrapped line is a whole word (or words): no word was cut by characters.
+        const words = new Set(header.split(/\s+/))
+        for (const part of lines) for (const w of part.split(' ')) expect({ header, word: w, whole: words.has(w) }).toEqual({ header, word: w, whole: true })
+      })
+    },
+  )
+
+  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)
+})

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

@@ -0,0 +1,147 @@
+jest.mock('../../../lib/pdf/invoiceTemplate', () => ({
+  renderInvoicePdf: jest.fn(async () => new Uint8Array([37, 80, 68, 70])),
+}))
+jest.mock('../../../lib/pdf/attachmentStore', () => ({
+  storeAttachment: jest.fn(async () => 'att-new'),
+  readAttachment: jest.fn(async () => null),
+  attachmentIdFromUrl: jest.requireActual('../../../lib/pdf/attachmentStore').attachmentIdFromUrl,
+}))
+
+import { renderInvoicePdf } from '../../../lib/pdf/invoiceTemplate'
+import { readAttachment, storeAttachment } from '../../../lib/pdf/attachmentStore'
+import { freezeInvoicePdf, getInvoicePdf, pdfFileName } from '../../../lib/pdf/invoicePdf'
+import { BillingAccount, BillingInvoice, BillingInvoiceLine, BillingSettings } from '../../../data/entities'
+import type { InvoiceDocumentModel } from '../../../lib/pdf/invoiceModel'
+
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+const loadTranslator = async () => (_key: string, fallback: string) => fallback
+
+function invoiceRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'inv-1',
+    ...scope,
+    billAccountId: 'acc-1',
+    number: 'INV/2026/11/0001',
+    documentType: 'invoice',
+    status: 'posted',
+    testRun: false,
+    issueDate: new Date('2026-11-14T00:00:00Z'),
+    dueDate: new Date('2026-11-28T00:00:00Z'),
+    currencyCode: 'PLN',
+    subtotalNet: '100.0000',
+    taxTotal: '23.0000',
+    totalGross: '123.0000',
+    pdfAttachmentId: null,
+    sellerSnapshot: { legal_name: 'Frozen Seller', tax_id: 'PL-FROZEN', iban: 'PL61109010140000071219812874', logo_attachment_id: null },
+    buyerSnapshot: { name: 'Frozen Buyer', invoice_language: 'pl' },
+    ...overrides,
+  } as unknown as BillingInvoice
+}
+
+function makeEm() {
+  return {
+    find: jest.fn(async (entity: unknown) =>
+      entity === BillingInvoiceLine
+        ? [
+            {
+              description: 'Plan',
+              quantity: '1',
+              unitPriceNet: '100',
+              taxRate: '23',
+              netAmount: '100',
+              taxAmount: '23',
+              grossAmount: '123',
+            },
+          ]
+        : [],
+    ),
+    findOne: jest.fn(async (entity: unknown) => {
+      if (entity === BillingSettings) return { organizationId: 'o-1', legalName: 'Live Seller', taxId: 'PL-LIVE' }
+      if (entity === BillingAccount) return { id: 'acc-1', name: 'Live Buyer', invoiceLanguage: 'en', invoiceEmail: 'x@y.z' }
+      return null
+    }),
+    execute: jest.fn(async (): Promise<Array<{ logo_url: string | null }>> => [{ logo_url: null }]),
+    nativeUpdate: jest.fn(async () => 1),
+  }
+}
+
+const lastModel = () => (renderInvoicePdf as jest.Mock).mock.calls.at(-1)?.[0] as InvoiceDocumentModel
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('invoice PDF service', () => {
+  it('renders drafts live with live parties and never stores them', async () => {
+    const em = makeEm()
+    const draft = invoiceRow({ status: 'draft', number: 'DRAFT-1A2B3C4D', sellerSnapshot: null, buyerSnapshot: null })
+    const pdf = await getInvoicePdf(em as never, draft, { loadTranslator })
+    expect(pdf).toMatchObject({ fileName: 'DRAFT-1A2B3C4D.pdf', frozen: false })
+    expect(lastModel().seller.lines[0]).toBe('Live Seller')
+    expect(lastModel().buyer.lines[0]).toBe('Live Buyer')
+    expect(lastModel().watermark).toBe('DRAFT')
+    expect(storeAttachment).not.toHaveBeenCalled()
+  })
+
+  it('serves the frozen attachment of a posted document without re-rendering', async () => {
+    ;(readAttachment as jest.Mock).mockResolvedValueOnce({ bytes: new Uint8Array([1, 2]), mimeType: 'application/pdf', fileName: 'x.pdf' })
+    const pdf = await getInvoicePdf(makeEm() as never, invoiceRow({ pdfAttachmentId: 'att-1' }), { loadTranslator })
+    expect(pdf).toMatchObject({ frozen: true, fileName: 'INV-2026-11-0001.pdf' })
+    expect(Array.from(pdf.bytes)).toEqual([1, 2])
+    expect(renderInvoicePdf).not.toHaveBeenCalled()
+  })
+
+  it('freezes a posted document lazily on first request, from the frozen snapshots', async () => {
+    const em = makeEm()
+    const invoice = invoiceRow()
+    const pdf = await getInvoicePdf(em as never, invoice, { loadTranslator })
+    expect(pdf.frozen).toBe(true)
+    expect(storeAttachment).toHaveBeenCalledWith(em, scope, expect.objectContaining({
+      entityId: 'billing:billing_invoice',
+      recordId: 'inv-1',
+      mimeType: 'application/pdf',
+      fileName: 'INV-2026-11-0001.pdf',
+    }))
+    // Conditional claim: only sets the column when still empty.
+    expect(em.nativeUpdate).toHaveBeenCalledWith(
+      BillingInvoice,
+      expect.objectContaining({ id: 'inv-1', pdfAttachmentId: null }),
+      { pdfAttachmentId: 'att-new' },
+    )
+    expect(invoice.pdfAttachmentId).toBe('att-new')
+    expect(lastModel().seller.lines[0]).toBe('Frozen Seller')
+    expect(lastModel().buyer.lines[0]).toBe('Frozen Buyer')
+    expect(lastModel().watermark).toBeNull()
+  })
+
+  it('is idempotent and refuses to freeze drafts or test documents', async () => {
+    await expect(freezeInvoicePdf(makeEm() as never, invoiceRow({ pdfAttachmentId: 'att-1' }))).resolves.toEqual({
+      attachmentId: 'att-1',
+      bytes: null,
+    })
+    expect(storeAttachment).not.toHaveBeenCalled()
+    await expect(freezeInvoicePdf(makeEm() as never, invoiceRow({ status: 'draft' }))).rejects.toThrow()
+    await expect(freezeInvoicePdf(makeEm() as never, invoiceRow({ testRun: true }))).rejects.toThrow()
+  })
+
+  it('falls back to a fresh render when the stored file is unreadable', async () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const pdf = await getInvoicePdf(makeEm() as never, invoiceRow({ pdfAttachmentId: 'att-lost' }), { loadTranslator })
+    expect(pdf.frozen).toBe(true)
+    expect(renderInvoicePdf).toHaveBeenCalledTimes(1)
+    expect(storeAttachment).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
+
+  it('uses the organization logo only when it is one of our attachments', async () => {
+    const em = makeEm()
+    em.execute.mockResolvedValueOnce([{ logo_url: '/api/attachments/file/12345678-1234-4234-8234-123456789012' }])
+    ;(readAttachment as jest.Mock).mockResolvedValueOnce({ bytes: new Uint8Array([9]), mimeType: 'image/png', fileName: 'l.png' })
+    await getInvoicePdf(em as never, invoiceRow({ status: 'draft' }), { loadTranslator })
+    expect(readAttachment).toHaveBeenCalledWith(em, scope, '12345678-1234-4234-8234-123456789012')
+    expect((renderInvoicePdf as jest.Mock).mock.calls[0][1]).toEqual({ logo: { bytes: new Uint8Array([9]), mimeType: 'image/png' } })
+  })
+
+  it('builds safe file names from document numbers', () => {
+    expect(pdfFileName({ number: 'INV/2026/11/0001' })).toBe('INV-2026-11-0001.pdf')
+    expect(pdfFileName({ number: 'FV 1/"x"' })).toBe('FV-1-x-.pdf')
+  })
+})