@dainamite/billing 0.19.0 → 0.21.0

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

@@ -1,11 +1,12 @@
 import { runBillRun, type RunBillRunParams } from '../../lib/billRunEngine'
 import { __resetInvoiceWriterCacheForTests } from '../../lib/invoiceWriter'
 import {
-  BillRun,
-  BillRunOutcome,
+  BillingRun,
+  BillingRunOutcome,
   BillingAccount,
   BillingAccountUsage,
   BillingItem,
+  BillingInvoice,
 } from '../../data/entities'
 
 /**
@@ -76,8 +77,15 @@ function createEnvironment(
       // test fixture records by uom for the runner.
       if (sql.includes('billing_account_usage') && sql.includes('GROUP BY uom_code')) {
         const accountId = (params?.[2] ?? '') as string
+        // Mirror the SQL bounds by calendar day: period_end <= ? [AND period_end > ?]
+        const day = (v: unknown) => new Date(v as Date).toISOString().slice(0, 10)
+        const upTo = params?.[3] ? day(params[3]) : null
+        const after = params?.[4] ? day(params[4]) : null
         const recs = (options.usageByAccount?.get(accountId) ?? []).filter(
-          (r) => r.ratedInBillRunId === null,
+          (r) =>
+            r.ratedInBillRunId === null &&
+            (!upTo || day(r.periodEnd) <= upTo) &&
+            (!after || day(r.periodEnd) > after),
         )
         const grouped = new Map<string, { sum: number; count: number }>()
         for (const r of recs) {
@@ -128,7 +136,15 @@ function createEnvironment(
       }
       return []
     }),
-    findOne: jest.fn(async (_entity: unknown, _where: unknown) => null),
+    // Dedupe check: an existing billing invoice for (account, bill date).
+    findOne: jest.fn(async (entity: unknown, where: unknown) => {
+      if (entity === BillingInvoice) {
+        const accountId = (where as { billAccountId?: string }).billAccountId
+        const existing = accountId ? options.openDraftIds?.get(accountId) : undefined
+        return existing ? { id: existing } : null
+      }
+      return null
+    }),
     nativeUpdate: jest.fn(async (entity: unknown, where: unknown, data: unknown) => {
       if (entity === BillingAccountUsage) {
         // Predicate-based bulk update (post-Phase-4f refactor): the
@@ -214,14 +230,21 @@ function makeAccount(overrides: Partial<BillingAccount>): BillingAccount {
   } as BillingAccount
 }
 
-function makeRecurringItem(billAccountId: string, id = 'item-mrc'): BillingItem {
+function makeRecurringItem(
+  billAccountId: string,
+  id = 'item-mrc',
+  overrides: Partial<BillingItem> = {},
+): BillingItem {
   return {
     id,
     organizationId: 'org-1',
     tenantId: 'tenant-1',
     billAccountId,
     type: 'recurring',
-    billStartDate: new Date('2026-01-01T00:00:00Z'),
+    // Starts on the account's bill date (Spec A default: billed in advance).
+    billStartDate: new Date('2026-06-01T00:00:00Z'),
+    chargeTiming: 'in_advance',
+    prorate: true,
     billEndDate: null,
     description: 'MRC',
     rateJson: { unit_price: 49.99 },
@@ -235,6 +258,7 @@ function makeRecurringItem(billAccountId: string, id = 'item-mrc'): BillingItem
     createdAt: new Date(),
     updatedAt: new Date(),
     deletedAt: null,
+    ...overrides,
   } as BillingItem
 }
 
@@ -268,8 +292,9 @@ describe('runBillRun — orchestration', () => {
     expect(outcomes[0].draftInvoiceId).toMatch(/^gen-/)
     // Real-mode advances next_bill_date
     expect(account.nextBillDate.toISOString().slice(0, 10)).toBe('2026-07-01')
-    expect(item.billedToDate?.toISOString().slice(0, 10)).toBe('2026-05-31')
-    // Persisted entities: BillRun + SalesInvoice + 1 line + BillingAccountUsage advance + BillRunOutcome
+    // In advance: the June bill date bills June (Spec A).
+    expect(item.billedToDate?.toISOString().slice(0, 10)).toBe('2026-06-30')
+    // Persisted entities: BillingRun + SalesInvoice + 1 line + BillingAccountUsage advance + BillingRunOutcome
     expect(captured.persisted.length).toBeGreaterThan(0)
   })
 
@@ -445,11 +470,10 @@ describe('runBillRun — orchestration', () => {
     expect(outcomes[0].status).toBe('success')
     // Persisted SalesInvoiceLine for the usage item with the right total
     const usageLine = captured.persisted.find((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'usage'
+      return (p as { billingType?: string }).billingType === 'usage'
     })
     expect(usageLine).toBeDefined()
-    expect((usageLine as { totalNetAmount?: string }).totalNetAmount).toBe('15.0000')
+    expect((usageLine as { netAmount?: string }).netAmount).toBe('15.0000')
 
     // Real-mode marks records as rated
     expect(u1.ratedInBillRunId).toBe(billRun.id)
@@ -488,12 +512,11 @@ describe('runBillRun — orchestration', () => {
     await runBillRun(em as never, container as never, params({}))
 
     const usageLine = captured.persisted.find((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'usage'
-    }) as { unitPriceNet?: string; totalNetAmount?: string; quantity?: string } | undefined
+      return (p as { billingType?: string }).billingType === 'usage'
+    }) as { unitPriceNet?: string; netAmount?: string; quantity?: string } | undefined
     expect(usageLine?.unitPriceNet).toBe('0.0010')
     expect(usageLine?.quantity).toBe('12000.0000')
-    expect(usageLine?.totalNetAmount).toBe('12.0000')
+    expect(usageLine?.netAmount).toBe('12.0000')
   })
 
   it('test mode: rates usage on draft but does NOT mark records as rated', async () => {
@@ -525,15 +548,15 @@ describe('runBillRun — orchestration', () => {
     await runBillRun(em as never, container as never, params({}))
 
     const lines = captured.persisted.filter((p) => {
-      const m = (p as { metadata?: { billing_type?: string } }).metadata
-      return m?.billing_type === 'recurring' || m?.billing_type === 'usage'
+      const type = (p as { billingType?: string }).billingType
+      return type === 'recurring' || type === 'usage'
     })
     expect(lines).toHaveLength(2)
     // Invoice header totalNet should be 49.99 (MRC) + 12.00 (usage) = 61.99
     const invoice = captured.persisted.find(
-      (p) => (p as { invoiceNumber?: string }).invoiceNumber,
-    ) as { grandTotalNetAmount?: string } | undefined
-    expect(invoice?.grandTotalNetAmount).toBe('61.9900')
+      (p) => (p as { documentType?: string }).documentType === 'invoice',
+    ) as { subtotalNet?: string } | undefined
+    expect(invoice?.subtotalNet).toBe('61.9900')
   })
 
   it('summary aggregates drafts_created / accounts_failed / accounts_with_warnings', async () => {
@@ -559,3 +582,191 @@ describe('runBillRun — orchestration', () => {
     })
   })
 })
+
+// ─── Spec A — cycle semantics ────────────────────────────────────
+
+describe('runBillRun — Spec A cycles', () => {
+  const day = (d: Date | null | undefined) => (d ? new Date(d).toISOString().slice(0, 10) : null)
+  type Cycle = { bill_date: string; status: string; period_start: string | null; period_end: string | null; invoice_id: string | null }
+  const cyclesOf = (outcome: { cycles?: unknown }) => (outcome.cycles ?? []) as Cycle[]
+  const invoicesOf = (persisted: unknown[]) =>
+    persisted.filter((p) => (p as { documentType?: string }).documentType === 'invoice') as Array<{
+      number: string
+      billDate: Date
+      testRun: boolean
+      metadata: Record<string, unknown>
+    }>
+
+  function operatorScenario() {
+    const account = makeAccount({ nextBillDate: new Date('2026-11-14T00:00:00Z') })
+    const item = makeRecurringItem(account.id, 'internet', {
+      billStartDate: new Date('2026-11-14T00:00:00Z'),
+      rateJson: { unit_price: 100 },
+    })
+    return { account, item }
+  }
+  const asOf = new Date('2027-02-01T00:00:00Z')
+
+  it("real: the operator's test bills 3 cycles and advances the account", async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { billRun, outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => [c.bill_date, c.period_start, c.period_end, c.status])).toEqual([
+      ['2026-11-14', '2026-11-14', '2026-12-13', 'invoiced'],
+      ['2026-12-14', '2026-12-14', '2027-01-13', 'invoiced'],
+      ['2027-01-14', '2027-01-14', '2027-02-13', 'invoiced'],
+    ])
+    expect(invoicesOf(env.captured.persisted).map((i) => day(i.billDate))).toEqual([
+      '2026-11-14',
+      '2026-12-14',
+      '2027-01-14',
+    ])
+    expect(day(account.nextBillDate)).toBe('2027-02-14')
+    expect(day(item.billedToDate)).toBe('2027-02-13')
+    expect(billRun.summary).toMatchObject({ drafts_created: 3, cycles_processed: 3 })
+  })
+
+  it('a scheduled run catches up exactly like a manual one', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: asOf, triggeredBy: 'schedule' }),
+    )
+    expect(cyclesOf(outcomes[0])).toHaveLength(3)
+  })
+
+  it('test: writes a TEST draft per cycle and leaves the account untouched', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'test' }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['invoiced', 'invoiced', 'invoiced'])
+    const invoices = invoicesOf(env.captured.persisted)
+    expect(invoices).toHaveLength(3)
+    expect(invoices.every((i) => i.number.startsWith('TEST-') && i.testRun === true)).toBe(true)
+    expect(day(account.nextBillDate)).toBe('2026-11-14')
+    expect(item.billedToDate).toBeNull()
+    expect(env.numberGenerator.generate).not.toHaveBeenCalled()
+  })
+
+  it('dry: previews every cycle and persists no invoice', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'dry' }))
+
+    expect(cyclesOf(outcomes[0]).map((c) => [c.status, c.invoice_id])).toEqual([
+      ['previewed', null],
+      ['previewed', null],
+      ['previewed', null],
+    ])
+    expect(invoicesOf(env.captured.persisted)).toHaveLength(0)
+    expect(day(account.nextBillDate)).toBe('2026-11-14')
+    expect(item.billedToDate).toBeNull()
+  })
+
+  it('test re-run: existing test drafts are skipped per cycle, simulation continues', async () => {
+    const { account, item } = operatorScenario()
+    const env = createEnvironment({
+      accounts: [account],
+      itemsByAccount: new Map([[account.id, [item]]]),
+      openDraftIds: new Map([[account.id, 'test-draft']]),
+    })
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ asOfDate: asOf, mode: 'test' }))
+    expect(outcomes[0].status).toBe('success')
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['skipped_existing', 'skipped_existing', 'skipped_existing'])
+    expect(invoicesOf(env.captured.persisted)).toHaveLength(0)
+  })
+
+  it('test mode never bills the same usage twice across simulated cycles', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2026-06-01T00:00:00Z') })
+    const usageItem = {
+      ...makeRecurringItem(account.id, 'usage-api'),
+      type: 'usage',
+      uomCode: 'api_request',
+      rateJson: { unit_price: 0.01 },
+    } as BillingItem
+    const record = {
+      id: 'u1',
+      organizationId: 'org-1',
+      tenantId: 'tenant-1',
+      billAccountId: account.id,
+      uomCode: 'api_request',
+      quantity: '100.0000',
+      periodStart: new Date('2026-05-01T00:00:00Z'),
+      periodEnd: new Date('2026-05-31T00:00:00Z'),
+      ratedInBillRunId: null,
+      deletedAt: null,
+    } as BillingAccountUsage
+    const env = createEnvironment({
+      accounts: [account],
+      itemsByAccount: new Map([[account.id, [usageItem]]]),
+      usageByAccount: new Map([[account.id, [record]]]),
+    })
+
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: new Date('2026-08-01T00:00:00Z'), mode: 'test' }),
+    )
+
+    expect(cyclesOf(outcomes[0]).map((c) => c.status)).toEqual(['invoiced', 'empty', 'empty'])
+    expect(record.ratedInBillRunId).toBeNull()
+  })
+
+  it('in advance and in arrears items share one invoice with their own service periods', async () => {
+    const account = makeAccount({})
+    const advance = makeRecurringItem(account.id, 'adv')
+    const arrears = makeRecurringItem(account.id, 'arr', {
+      chargeTiming: 'in_arrears',
+      billStartDate: new Date('2026-05-01T00:00:00Z'),
+    })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [advance, arrears]]]) })
+
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({}))
+
+    const lines = env.captured.persisted.filter((p) => (p as { billingType?: string }).billingType === 'recurring') as Array<{ billingItemId: string; servicePeriodStart: Date; servicePeriodEnd: Date }>
+    expect(lines.map((l) => [l.billingItemId, day(l.servicePeriodStart), day(l.servicePeriodEnd)])).toEqual([
+      ['adv', '2026-06-01', '2026-06-30'],
+      ['arr', '2026-05-01', '2026-05-31'],
+    ])
+    expect(cyclesOf(outcomes[0])[0]).toMatchObject({ period_start: '2026-05-01', period_end: '2026-06-30' })
+  })
+
+  it('an item ended after advance billing gets a credit line (negative total warning)', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2026-07-01T00:00:00Z') })
+    const item = makeRecurringItem(account.id, 'cancelled', {
+      billedToDate: new Date('2026-06-30T00:00:00Z'),
+      billEndDate: new Date('2026-06-15T00:00:00Z'),
+      rateJson: { unit_price: 30 },
+    })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, [item]]]) })
+
+    const { outcomes } = await runBillRun(
+      env.em as never,
+      env.container as never,
+      params({ asOfDate: new Date('2026-07-01T00:00:00Z') }),
+    )
+
+    const line = env.captured.persisted.find((p) => (p as { metadata?: { credit_for?: string } | null }).metadata?.credit_for) as { netAmount: string; description: string }
+    expect(line.netAmount).toBe('-15.0000')
+    expect(line.description).toBe('MRC · 2026-06-16 – 2026-06-30')
+    expect(day(item.billedToDate)).toBe('2026-06-15')
+    expect(outcomes[0].status).toBe('success_with_warnings')
+    expect((outcomes[0].warnings as { negative_total_bill_dates?: string[] }).negative_total_bill_dates).toEqual(['2026-07-01'])
+  })
+
+  it('stops at the hard cap and warns', async () => {
+    const account = makeAccount({ nextBillDate: new Date('2020-01-01T00:00:00Z') })
+    const env = createEnvironment({ accounts: [account], itemsByAccount: new Map([[account.id, []]]) })
+    const { outcomes } = await runBillRun(env.em as never, env.container as never, params({ mode: 'dry' }))
+    expect(cyclesOf(outcomes[0])).toHaveLength(60)
+    expect((outcomes[0].warnings as { catch_up_cap_reached?: boolean }).catch_up_cap_reached).toBe(true)
+    expect(outcomes[0].status).toBe('success_with_warnings')
+  })
+})

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