@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,109 @@
+import {
+  BILLING_SETTINGS_DEFAULTS,
+  buildSellerSnapshot,
+  getBillingSettings,
+  missingSellerFields,
+  numberMaskFor,
+  serializeBillingSettings,
+  taxRateColumn,
+} from '../../lib/billingSettings'
+import { DEFAULT_NUMBER_MASKS } from '../../lib/numbering'
+import type { BillingSettings } from '../../data/entities'
+
+const scope = { tenantId: 't', organizationId: 'o' }
+
+function settingsRow(overrides: Partial<BillingSettings> = {}): BillingSettings {
+  return {
+    id: 's-1',
+    tenantId: 't',
+    organizationId: 'o',
+    lowBalanceThresholdDefault: '5.0000',
+    nearLimitBufferDefault: '0',
+    statementEnabled: true,
+    topupTaxRate: '23.0000',
+    topupProvider: 'stripe',
+    numberMasks: null,
+    ...overrides,
+  } as BillingSettings
+}
+
+describe('billingSettings', () => {
+  it('returns the existing row without inserting', async () => {
+    const row = settingsRow()
+    const em = { findOne: jest.fn(async () => row), execute: jest.fn() }
+    expect(await getBillingSettings(em as never, scope)).toBe(row)
+    expect(em.execute).not.toHaveBeenCalled()
+  })
+
+  it('lazily creates the row with defaults (race-safe upsert) and re-reads it', async () => {
+    const row = settingsRow()
+    const findOne = jest.fn().mockResolvedValueOnce(null).mockResolvedValueOnce(row)
+    const execute = jest.fn(async () => [])
+    expect(await getBillingSettings({ findOne, execute } as never, scope)).toBe(row)
+    const [sql, params] = execute.mock.calls[0] as unknown as [string, unknown[]]
+    expect(sql).toMatch(/ON CONFLICT \(tenant_id, organization_id\) WHERE deleted_at IS NULL DO NOTHING/)
+    expect(params[7]).toBe(JSON.stringify(BILLING_SETTINGS_DEFAULTS.numberMasks))
+  })
+
+  it('falls back to default masks and serializes numbers', () => {
+    const row = settingsRow({ numberMasks: { invoice: 'FV/{SEQUENCE_NUM}', receipt: 'broken' } })
+    expect(numberMaskFor(row, 'invoice')).toBe('FV/{SEQUENCE_NUM}')
+    expect(serializeBillingSettings(row)).toMatchObject({
+      lowBalanceThresholdDefault: 5,
+      topupTaxRate: 23,
+      numberMasks: {
+        invoice: 'FV/{SEQUENCE_NUM}',
+        credit_memo: DEFAULT_NUMBER_MASKS.credit_memo,
+        receipt: DEFAULT_NUMBER_MASKS.receipt,
+      },
+    })
+  })
+})
+
+describe('billingSettings — Spec B seller fields', () => {
+  const complete = settingsRow({
+    legalName: 'Seller',
+    sellerAddress: { line1: 'ul. A 1', city: 'Kraków', postal_code: '30-001', country: 'PL' },
+    taxId: 'PL1',
+    iban: 'PL61109010140000071219812874',
+  })
+
+  it('reports no missing fields when the printable minimum is filled', () => {
+    expect(missingSellerFields(complete)).toEqual([])
+  })
+
+  it('reports empty, blank and missing fields in a stable order', () => {
+    expect(missingSellerFields(settingsRow())).toEqual(['legalName', 'sellerAddress', 'taxId', 'iban'])
+    expect(missingSellerFields({ ...complete, taxId: '  ', sellerAddress: {} } as BillingSettings)).toEqual([
+      'sellerAddress',
+      'taxId',
+    ])
+  })
+
+  it('freezes the seller block for the invoice snapshot', () => {
+    expect(buildSellerSnapshot(complete)).toMatchObject({
+      organization_id: 'o',
+      legal_name: 'Seller',
+      tax_id: 'PL1',
+      iban: 'PL61109010140000071219812874',
+      bic: null,
+      logo_attachment_id: null,
+    })
+  })
+
+  it('formats VAT rates for the numeric(7,4) column', () => {
+    expect(taxRateColumn(23)).toBe('23')
+    expect(taxRateColumn(5.5)).toBe('5.5')
+    expect(taxRateColumn(8.123456)).toBe('8.1235')
+  })
+
+  it('serializes seller fields with defaults for the settings page', () => {
+    expect(serializeBillingSettings(complete)).toMatchObject({
+      legalName: 'Seller',
+      bic: '',
+      defaultPaymentTermsDays: 14,
+      defaultTaxRate: 23,
+    })
+  })
+})
+

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

@@ -0,0 +1,156 @@
+import {
+  CUSTOMER_LOOKUP_CHUNK,
+  applyCustomerPrefill,
+  customerDetailHref,
+  customerEndpoint,
+  extractItems,
+  mapPrimaryAddress,
+  planCustomerLookups,
+  toCustomerSummary,
+  type PrefillTarget,
+} from '../../lib/customerLookup'
+
+const blankForm: PrefillTarget = {
+  name: '',
+  invoiceEmail: '',
+  invoiceAddress: { line1: '', line2: '', city: '', postal_code: '', country: 'PL' },
+}
+
+describe('customerEndpoint / customerDetailHref', () => {
+  it('routes companies and people to their own collections', () => {
+    expect(customerEndpoint('company')).toBe('/api/customers/companies')
+    expect(customerEndpoint('person')).toBe('/api/customers/people')
+    expect(customerDetailHref('person', 'p-1')).toBe('/backend/customers/people/p-1')
+    expect(customerDetailHref('company', 'c 1')).toBe('/backend/customers/companies/c%201')
+  })
+})
+
+describe('extractItems / toCustomerSummary', () => {
+  it('reads `{ items }` and bare arrays, ignoring junk', () => {
+    expect(extractItems({ items: [{ id: 'a' }, null, 3] })).toEqual([{ id: 'a' }])
+    expect(extractItems([{ id: 'b' }])).toEqual([{ id: 'b' }])
+    expect(extractItems(null)).toEqual([])
+  })
+
+  it('maps snake_case and camelCase rows', () => {
+    expect(toCustomerSummary({ id: 'c1', display_name: 'Acme', primary_email: 'ar@acme.test' })).toEqual({
+      id: 'c1',
+      name: 'Acme',
+      email: 'ar@acme.test',
+    })
+    expect(toCustomerSummary({ id: 'p1', displayName: 'Jan Kowalski' })).toEqual({
+      id: 'p1',
+      name: 'Jan Kowalski',
+      email: null,
+    })
+  })
+
+  it('falls back to the id as name and rejects rows without id', () => {
+    expect(toCustomerSummary({ id: 'x' })?.name).toBe('x')
+    expect(toCustomerSummary({ display_name: 'No id' })).toBeNull()
+  })
+})
+
+describe('mapPrimaryAddress', () => {
+  const secondary = {
+    is_primary: false,
+    address_line1: 'Boczna',
+    building_number: '2',
+    city: 'Kraków',
+    postal_code: '30-001',
+    country: 'pl',
+  }
+  const primary = {
+    is_primary: true,
+    address_line1: 'Marszałkowska',
+    building_number: '10',
+    flat_number: '5',
+    address_line2: 'II piętro',
+    city: 'Warszawa',
+    postal_code: '00-001',
+    country: 'pl',
+  }
+
+  it('prefers the primary address and composes building/flat into line 1', () => {
+    expect(mapPrimaryAddress([secondary, primary])).toEqual({
+      line1: 'Marszałkowska 10/5',
+      line2: 'II piętro',
+      city: 'Warszawa',
+      postal_code: '00-001',
+      country: 'PL',
+    })
+  })
+
+  it('falls back to the first complete address when the primary is incomplete', () => {
+    expect(mapPrimaryAddress([{ ...primary, city: '' }, secondary])?.line1).toBe('Boczna 2')
+  })
+
+  it('ignores a flat number without a building number', () => {
+    expect(mapPrimaryAddress([{ ...secondary, building_number: '', flat_number: '7' }])?.line1).toBe('Boczna')
+  })
+
+  it('returns null when nothing is usable', () => {
+    expect(mapPrimaryAddress([])).toBeNull()
+    expect(mapPrimaryAddress([{ address_line1: 'X', city: 'Y', postal_code: 'Z', country: '' }])).toBeNull()
+  })
+})
+
+describe('applyCustomerPrefill', () => {
+  const customer = { id: 'p1', name: 'Jan Kowalski', email: 'jan@example.test' }
+  const address = { line1: 'Marszałkowska 10', line2: '', city: 'Warszawa', postal_code: '00-001', country: 'PL' }
+
+  it('fills name, email and address into a blank form', () => {
+    expect(applyCustomerPrefill(blankForm, customer, address)).toEqual({
+      name: 'Jan Kowalski',
+      invoiceEmail: 'jan@example.test',
+      invoiceAddress: address,
+    })
+  })
+
+  it('never overwrites what the operator typed', () => {
+    const typed: PrefillTarget = {
+      name: 'Jan — home',
+      invoiceEmail: 'billing@jan.test',
+      invoiceAddress: { ...blankForm.invoiceAddress, city: 'Gdańsk' },
+    }
+    expect(applyCustomerPrefill(typed, customer, address)).toEqual(typed)
+  })
+
+  it('treats the default country alone as an empty address', () => {
+    expect(applyCustomerPrefill(blankForm, null, address).invoiceAddress).toEqual(address)
+  })
+
+  it('is a no-op without data', () => {
+    expect(applyCustomerPrefill(blankForm, null, null)).toBe(blankForm)
+  })
+
+  it('preserves extra fields on the target', () => {
+    const form = { ...blankForm, currencyCode: 'PLN' }
+    expect(applyCustomerPrefill(form, customer, null).currencyCode).toBe('PLN')
+  })
+})
+
+describe('planCustomerLookups', () => {
+  it('groups by kind, de-duplicates and skips empty ids', () => {
+    const plan = planCustomerLookups([
+      { customerId: 'c1', customerKind: 'company' },
+      { customerId: 'p1', customerKind: 'person' },
+      { customerId: 'c1', customerKind: 'company' },
+      { customerId: '', customerKind: 'person' },
+      { customerId: 'c2', customerKind: null },
+    ])
+    expect(plan).toEqual([
+      { kind: 'company', ids: ['c1', 'c2'] },
+      { kind: 'person', ids: ['p1'] },
+    ])
+  })
+
+  it('chunks to the API page-size cap', () => {
+    const rows = Array.from({ length: CUSTOMER_LOOKUP_CHUNK + 5 }, (_, i) => ({
+      customerId: `c${i}`,
+      customerKind: 'company' as const,
+    }))
+    const plan = planCustomerLookups(rows)
+    expect(plan.map((p) => p.ids.length)).toEqual([CUSTOMER_LOOKUP_CHUNK, 5])
+  })
+})

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

@@ -0,0 +1,35 @@
+import { computeDueDate, resolvePaymentTermsDays } from '../../lib/dueDate'
+
+const d = (iso: string) => new Date(`${iso}T00:00:00Z`)
+const iso = (date: Date) => date.toISOString().slice(0, 10)
+
+describe('resolvePaymentTermsDays', () => {
+  it('prefers the account terms, including 0 (due on issue)', () => {
+    expect(resolvePaymentTermsDays(7, 14)).toBe(7)
+    expect(resolvePaymentTermsDays(0, 14)).toBe(0)
+  })
+
+  it('falls back to the organization default, then 14', () => {
+    expect(resolvePaymentTermsDays(null, 30)).toBe(30)
+    expect(resolvePaymentTermsDays(undefined, undefined)).toBe(14)
+    expect(resolvePaymentTermsDays(-1, -5)).toBe(14)
+    expect(resolvePaymentTermsDays(2.5, 21)).toBe(21)
+  })
+})
+
+describe('computeDueDate', () => {
+  it('adds calendar days across month and year ends', () => {
+    expect(iso(computeDueDate(d('2026-11-14'), 14))).toBe('2026-11-28')
+    expect(iso(computeDueDate(d('2026-12-25'), 14))).toBe('2027-01-08')
+    expect(iso(computeDueDate(d('2027-01-31'), 30))).toBe('2027-03-02')
+  })
+
+  it('handles leap years', () => {
+    expect(iso(computeDueDate(d('2028-02-15'), 14))).toBe('2028-02-29')
+  })
+
+  it('returns the issue date itself for 0 days, at UTC midnight', () => {
+    const due = computeDueDate(new Date('2026-11-14T22:30:00Z'), 0)
+    expect(due.toISOString()).toBe('2026-11-14T00:00:00.000Z')
+  })
+})

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

@@ -0,0 +1,38 @@
+import { formatIban, isValidBic, isValidIban, normalizeIban } from '../../lib/iban'
+
+describe('IBAN', () => {
+  it('normalizes spaces and case', () => {
+    expect(normalizeIban(' pl61 1090 1014 0000 0712 1981 2874 ')).toBe('PL61109010140000071219812874')
+  })
+
+  it('accepts valid IBANs (mod-97)', () => {
+    expect(isValidIban('PL61 1090 1014 0000 0712 1981 2874')).toBe(true)
+    expect(isValidIban('DE89370400440532013000')).toBe(true)
+    expect(isValidIban('GB29NWBK60161331926819')).toBe(true)
+  })
+
+  it('rejects typos and malformed values', () => {
+    expect(isValidIban('PL61109010140000071219812875')).toBe(false)
+    expect(isValidIban('DE89370400440532013001')).toBe(false)
+    expect(isValidIban('PL6110901014')).toBe(false)
+    expect(isValidIban('1234567890123456')).toBe(false)
+    expect(isValidIban('')).toBe(false)
+  })
+
+  it('formats in groups of four', () => {
+    expect(formatIban('PL61109010140000071219812874')).toBe('PL61 1090 1014 0000 0712 1981 2874')
+  })
+})
+
+describe('BIC', () => {
+  it('accepts 8 and 11 character codes', () => {
+    expect(isValidBic('WBKPPLPP')).toBe(true)
+    expect(isValidBic('deutdeffxxx')).toBe(true)
+  })
+
+  it('rejects other lengths and shapes', () => {
+    expect(isValidBic('WBKPPL')).toBe(false)
+    expect(isValidBic('WBKPPLPPX')).toBe(false)
+    expect(isValidBic('1BKPPLPP')).toBe(false)
+  })
+})

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

@@ -0,0 +1,206 @@
+jest.mock('../../lib/pdf/invoicePdf', () => ({
+  getInvoicePdf: jest.fn(async () => ({ bytes: new Uint8Array([37, 80, 68, 70]), fileName: 'INV-2026-11-0001.pdf', frozen: true })),
+  loadDocumentTranslator: jest.fn(),
+}))
+jest.mock('../../events', () => ({ emitBillingEvent: jest.fn(async () => undefined) }))
+
+import { emitBillingEvent } from '../../events'
+import { BillingAccount, BillingInvoice } from '../../data/entities'
+import {
+  buildInvoiceEmail,
+  hasSuccessfulDelivery,
+  isDeliverableEmail,
+  sendInvoice,
+} from '../../lib/invoiceDelivery'
+import { autoSendInvoice } from '../../subscribers/invoice-auto-send'
+
+const scope = { tenantId: 't-1', organizationId: 'o-1' }
+const loadTranslator = async () => (_key: string, fallback: string) => fallback
+const now = () => new Date('2026-11-14T12:00:00Z')
+
+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,
+    totalGross: '123.0000',
+    currencyCode: 'PLN',
+    dueDate: new Date('2026-11-28T00:00:00Z'),
+    metadata: null,
+    buyerSnapshot: { name: 'Jan Kowalski', invoice_language: 'en', invoice_email: 'old@example.com' },
+    sellerSnapshot: { legal_name: 'Seller sp. z o.o.', iban: 'PL61109010140000071219812874' },
+    ...overrides,
+  } as unknown as BillingInvoice
+}
+
+function makeEm(invoice: BillingInvoice | null, account: Record<string, unknown> | null = {}) {
+  const executed: Array<{ sql: string; params: unknown[] }> = []
+  const em = {
+    findOne: jest.fn(async (entity: unknown) => {
+      if (entity === BillingInvoice) return invoice
+      if (entity === BillingAccount)
+        return account === null
+          ? null
+          : { id: 'acc-1', name: 'Jan', invoiceEmail: 'jan@example.com', invoiceLanguage: 'en', autoSendInvoice: true, ...account }
+      return null
+    }),
+    execute: jest.fn(async (sql: string, params: unknown[]) => {
+      executed.push({ sql, params })
+      return []
+    }),
+  }
+  return { em, executed }
+}
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('sendInvoice', () => {
+  it('emails the frozen PDF to the live invoice address and logs a sent delivery', async () => {
+    const invoice = invoiceRow()
+    const { em, executed } = makeEm(invoice)
+    const sendEmail = jest.fn(async () => undefined)
+    const result = await sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail, loadTranslator, now })
+
+    expect(result).toEqual({ invoiceId: 'inv-1', to: 'jan@example.com', status: 'sent', error: null })
+    expect(sendEmail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: 'jan@example.com',
+        subject: 'Invoice INV/2026/11/0001',
+        attachments: [{ filename: 'INV-2026-11-0001.pdf', content: 'JVBERg==', contentType: 'application/pdf' }],
+        tenantId: 't-1',
+        organizationId: 'o-1',
+      }),
+    )
+    const append = executed.find((e) => e.sql.includes('jsonb_set'))
+    expect(JSON.parse(append!.params[0] as string)).toEqual([
+      { at: '2026-11-14T12:00:00.000Z', to: 'jan@example.com', status: 'sent', error: null, trigger: 'manual' },
+    ])
+    expect(append!.params.slice(1)).toEqual(['inv-1', 't-1', 'o-1'])
+    expect(emitBillingEvent).toHaveBeenCalledWith('billing.invoice.sent', expect.objectContaining({ invoiceId: 'inv-1', trigger: 'manual' }))
+    expect(hasSuccessfulDelivery(invoice)).toBe(true)
+  })
+
+  it('records a failed delivery (no throw) when the transport fails', async () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const { em, executed } = makeEm(invoiceRow())
+    const sendEmail = jest.fn(async () => {
+      throw new Error('EMAIL_TRANSPORT_NOT_CONFIGURED')
+    })
+    const result = await sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail, loadTranslator, now })
+    expect(result).toMatchObject({ status: 'failed', error: 'EMAIL_TRANSPORT_NOT_CONFIGURED' })
+    expect(JSON.parse(executed[0].params[0] as string)[0]).toMatchObject({ status: 'failed', error: 'EMAIL_TRANSPORT_NOT_CONFIGURED' })
+    expect(emitBillingEvent).toHaveBeenCalledWith('billing.invoice.send_failed', expect.anything())
+    spy.mockRestore()
+  })
+
+  it('loads the translator for the resolved document language (snapshot first, then account, else default)', async () => {
+    const spyLoader = jest.fn(async (_language: string) => (_key: string, fallback: string) => fallback)
+    const sendEmail = jest.fn(async () => undefined)
+    const run = async (snapshotLanguage: unknown, accountLanguage: string) => {
+      spyLoader.mockClear()
+      const { em } = makeEm(
+        invoiceRow({ buyerSnapshot: { name: 'Jan', invoice_language: snapshotLanguage } }),
+        { invoiceLanguage: accountLanguage },
+      )
+      await sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail, loadTranslator: spyLoader, now })
+      return spyLoader.mock.calls[0]?.[0]
+    }
+    expect(await run(' PL ', 'en')).toBe('pl')
+    expect(await run(undefined, 'pl')).toBe('pl')
+    expect(await run('xx', 'pl')).toBe('en')
+  })
+
+  it('refuses drafts and test documents with 409 not_posted', async () => {
+    for (const overrides of [{ status: 'draft' }, { testRun: true }]) {
+      const { em } = makeEm(invoiceRow(overrides))
+      await expect(
+        sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail: jest.fn(), loadTranslator }),
+      ).rejects.toMatchObject({ status: 409, body: expect.objectContaining({ code: 'billing.invoice.not_posted' }) })
+    }
+  })
+
+  it('refuses placeholder and malformed addresses with 422 and sends nothing', async () => {
+    const sendEmail = jest.fn()
+    for (const invoiceEmail of ['shell-123@invalid.local', 'not-an-email']) {
+      const { em, executed } = makeEm(invoiceRow(), { invoiceEmail })
+      await expect(
+        sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail, loadTranslator }),
+      ).rejects.toMatchObject({ status: 422, body: expect.objectContaining({ code: 'billing.invoice.email_invalid' }) })
+      expect(executed).toHaveLength(0)
+    }
+    expect(sendEmail).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the frozen buyer email when the account is gone; 404 for unknown invoices', async () => {
+    const { em } = makeEm(invoiceRow(), null)
+    const result = await sendInvoice(em as never, { invoiceId: 'inv-1', ...scope, trigger: 'manual' }, { sendEmail: jest.fn(async () => undefined), loadTranslator })
+    expect(result.to).toBe('old@example.com')
+    const missing = makeEm(null)
+    await expect(sendInvoice(missing.em as never, { invoiceId: 'x', ...scope, trigger: 'manual' })).rejects.toMatchObject({ status: 404 })
+  })
+})
+
+describe('buildInvoiceEmail', () => {
+  it('fills subject and body in the document language and escapes HTML', () => {
+    const pl: Record<string, string> = {
+      'billing.email.invoice.subject': 'Faktura {number}',
+      'billing.email.invoice.greeting': 'Dzień dobry {name},',
+    }
+    const email = buildInvoiceEmail({
+      invoice: { number: 'INV/1', totalGross: '123.0000', currencyCode: 'PLN', dueDate: new Date('2026-11-28T00:00:00Z') },
+      buyerName: 'Jan <b>Kowalski</b>',
+      sellerName: 'Seller',
+      iban: 'PL61109010140000071219812874',
+      language: 'pl',
+      translate: (key, fallback) => pl[key] ?? fallback,
+    })
+    expect(email.subject).toBe('Faktura INV/1')
+    expect(email.text).toContain('Dzień dobry Jan <b>Kowalski</b>,')
+    expect(email.text).toContain('123,00 zł')
+    expect(email.text).toContain('28.11.2026')
+    expect(email.text).toContain('PL61 1090 1014 0000 0712 1981 2874')
+    expect(email.html).toContain('Jan &lt;b&gt;Kowalski&lt;/b&gt;')
+  })
+})
+
+describe('isDeliverableEmail', () => {
+  it('accepts real addresses only', () => {
+    expect(isDeliverableEmail('a@b.co')).toBe(true)
+    expect(isDeliverableEmail('X@INVALID.LOCAL')).toBe(false)
+    expect(isDeliverableEmail('')).toBe(false)
+    expect(isDeliverableEmail(null)).toBe(false)
+  })
+})
+
+describe('autoSendInvoice (subscriber)', () => {
+  const payload = { invoiceId: 'inv-1', ...scope }
+
+  it('sends once when the account opted in', async () => {
+    const { em } = makeEm(invoiceRow())
+    const sendEmail = jest.fn(async () => undefined)
+    expect(await autoSendInvoice(em as never, payload, { sendEmail, loadTranslator, now })).toBe('sent')
+    expect(sendEmail).toHaveBeenCalledTimes(1)
+  })
+
+  it('is idempotent on redelivery (an auto delivery already succeeded)', async () => {
+    const invoice = invoiceRow({ metadata: { deliveries: [{ at: 'x', to: 'a@b.co', status: 'sent', trigger: 'auto' }] } })
+    const sendEmail = jest.fn()
+    expect(await autoSendInvoice(makeEm(invoice).em as never, payload, { sendEmail, loadTranslator })).toBe('skipped')
+    expect(sendEmail).not.toHaveBeenCalled()
+  })
+
+  it('skips when the flag is off, the email is a placeholder, or the document is a receipt / test', async () => {
+    const sendEmail = jest.fn()
+    const deps = { sendEmail, loadTranslator }
+    expect(await autoSendInvoice(makeEm(invoiceRow(), { autoSendInvoice: false }).em as never, payload, deps)).toBe('skipped')
+    expect(await autoSendInvoice(makeEm(invoiceRow(), { invoiceEmail: 'x@invalid.local' }).em as never, payload, deps)).toBe('skipped')
+    expect(await autoSendInvoice(makeEm(invoiceRow({ documentType: 'receipt' })).em as never, payload, deps)).toBe('skipped')
+    expect(await autoSendInvoice(makeEm(invoiceRow({ testRun: true })).em as never, payload, deps)).toBe('skipped')
+    expect(await autoSendInvoice(makeEm(invoiceRow()).em as never, { invoiceId: 'inv-1' }, deps)).toBe('skipped')
+    expect(sendEmail).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,49 @@
+import {
+  DEFAULT_INVOICE_LANGUAGE,
+  INVOICE_LANGUAGE_CODES,
+  SUPPORTED_INVOICE_LANGUAGES,
+  invoiceIntlLocale,
+  isSupportedInvoiceLanguage,
+  resolveInvoiceLanguage,
+} from '../../lib/invoiceLanguages'
+import { documentLocale } from '../../lib/pdf/invoiceModel'
+
+describe('invoice language registry', () => {
+  it('lists the default first and derives the code list from the registry', () => {
+    expect(SUPPORTED_INVOICE_LANGUAGES[0].code).toBe(DEFAULT_INVOICE_LANGUAGE)
+    expect(INVOICE_LANGUAGE_CODES).toEqual(SUPPORTED_INVOICE_LANGUAGES.map((l) => l.code))
+    expect(new Set(INVOICE_LANGUAGE_CODES).size).toBe(INVOICE_LANGUAGE_CODES.length)
+  })
+
+  it('gives every language an endonym label and a valid Intl locale', () => {
+    for (const language of SUPPORTED_INVOICE_LANGUAGES) {
+      expect(language.label.trim()).not.toBe('')
+      expect(Intl.DateTimeFormat.supportedLocalesOf([language.intlLocale])).toEqual([language.intlLocale])
+      expect(language.intlLocale.toLowerCase().startsWith(`${language.code}-`)).toBe(true)
+    }
+  })
+
+  it('resolves stored values: normalizes case / whitespace, falls back to the default', () => {
+    expect(resolveInvoiceLanguage(' PL ')).toBe('pl')
+    expect(resolveInvoiceLanguage('en')).toBe('en')
+    expect(resolveInvoiceLanguage('xx')).toBe(DEFAULT_INVOICE_LANGUAGE)
+    expect(resolveInvoiceLanguage('')).toBe(DEFAULT_INVOICE_LANGUAGE)
+    expect(resolveInvoiceLanguage(null)).toBe(DEFAULT_INVOICE_LANGUAGE)
+    expect(resolveInvoiceLanguage(undefined)).toBe(DEFAULT_INVOICE_LANGUAGE)
+  })
+
+  it('checks support strictly (no normalization)', () => {
+    expect(isSupportedInvoiceLanguage('pl')).toBe(true)
+    expect(isSupportedInvoiceLanguage('PL')).toBe(false)
+    expect(isSupportedInvoiceLanguage('xx')).toBe(false)
+  })
+
+  it('maps languages to their Intl locale; documentLocale delegates to the registry', () => {
+    for (const language of SUPPORTED_INVOICE_LANGUAGES) {
+      expect(invoiceIntlLocale(language.code)).toBe(language.intlLocale)
+      expect(documentLocale(language.code)).toBe(language.intlLocale)
+    }
+    expect(invoiceIntlLocale('xx')).toBe('en-GB')
+    expect(documentLocale('xx')).toBe('en-GB')
+  })
+})