@dainamite/billing 0.19.0 → 0.21.0

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

@@ -0,0 +1,118 @@
+import { buildVatSummary, resolvePrepaidDebit } from '../../lib/prepaidTaxPoint'
+import { receiptTaxRate } from '../../lib/billingSettings'
+import { consumePrepaidUsage } from '../../lib/prepaidConsume'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+describe('resolvePrepaidDebit (Spec F, F-D3)', () => {
+  it('topup: debits the amount as entered — rate and basis ignored', () => {
+    expect(resolvePrepaidDebit({ lineAmount: 49, priceBasis: 'net', taxRate: 23, taxPoint: 'topup' })).toEqual({
+      debit: 49,
+      net: 49,
+      tax: 0,
+      taxRate: 0,
+    })
+    expect(resolvePrepaidDebit({ lineAmount: '12.30', priceBasis: 'gross', taxRate: 23, taxPoint: 'topup' }).debit).toBe(12.3)
+  })
+
+  it('consumption: debits the gross — 20 @ 0 % → 20, 10 net @ 23 % → 12.30', () => {
+    expect(resolvePrepaidDebit({ lineAmount: 20, priceBasis: 'net', taxRate: 0, taxPoint: 'consumption' }).debit).toBe(20)
+    expect(resolvePrepaidDebit({ lineAmount: 10, priceBasis: 'net', taxRate: 23, taxPoint: 'consumption' })).toEqual({
+      debit: 12.3,
+      net: 10,
+      tax: 2.3,
+      taxRate: 23,
+    })
+  })
+
+  it('consumption: a gross price is debited as typed; credits keep their sign', () => {
+    expect(resolvePrepaidDebit({ lineAmount: 12.3, priceBasis: 'gross', taxRate: 23, taxPoint: 'consumption' }).debit).toBe(12.3)
+    expect(resolvePrepaidDebit({ lineAmount: -10, priceBasis: 'net', taxRate: 23, taxPoint: 'consumption' }).debit).toBe(-12.3)
+  })
+})
+
+describe('buildVatSummary', () => {
+  it('groups consumption debits by rate (highest first) and is empty in topup mode', () => {
+    const debits = [
+      resolvePrepaidDebit({ lineAmount: 10, priceBasis: 'net', taxRate: 23, taxPoint: 'consumption' }),
+      resolvePrepaidDebit({ lineAmount: 5, priceBasis: 'net', taxRate: 23, taxPoint: 'consumption' }),
+      resolvePrepaidDebit({ lineAmount: 20, priceBasis: 'net', taxRate: 0, taxPoint: 'consumption' }),
+    ]
+    expect(buildVatSummary(debits, 'consumption')).toEqual([
+      { rate: '23', net: '15.0000', tax: '3.4500', gross: '18.4500' },
+      { rate: '0', net: '20.0000', tax: '0.0000', gross: '20.0000' },
+    ])
+    expect(buildVatSummary(debits, 'topup')).toEqual([])
+  })
+})
+
+describe('receiptTaxRate (Spec F, P-D11)', () => {
+  it('uses the top-up rate only when tax is charged at top-up — never twice', () => {
+    expect(receiptTaxRate({ topupTaxRate: '23', prepaidTaxPoint: 'topup' })).toBe(23)
+    expect(receiptTaxRate({ topupTaxRate: '23', prepaidTaxPoint: 'consumption' })).toBe(0)
+    expect(receiptTaxRate({ topupTaxRate: 'x', prepaidTaxPoint: 'topup' })).toBe(0)
+  })
+})
+
+describe('consumePrepaidUsage — tax point', () => {
+  const TENANT = 'ten-1'
+  const ORG = 'org-1'
+  const ACCT = 'acct-1'
+  const account = { id: ACCT, tenantId: TENANT, organizationId: ORG, currencyCode: 'EUR', billingMode: 'prepaid', creditLimit: '0' }
+  const usageItem = (overrides: Record<string, unknown> = {}) => ({
+    id: 'item-usage',
+    type: 'usage',
+    uomCode: 'gb',
+    isActive: true,
+    deletedAt: null,
+    taxRate: '23',
+    priceBasis: 'net',
+    rateJson: { unit_price: 1 },
+    description: 'Data',
+    ...overrides,
+  })
+  const input = {
+    organizationId: ORG,
+    tenantId: TENANT,
+    billAccountId: ACCT,
+    uomCode: 'gb',
+    quantity: 10,
+    periodStart: new Date('2026-11-01'),
+    periodEnd: new Date('2026-11-30'),
+  }
+
+  it('topup mode: debits the rated amount', async () => {
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '100.0000' },
+      usageItem: usageItem(),
+    })
+    const { result } = await consumePrepaidUsage(em as never, account as never, input)
+    expect(result.ratedAmount).toBe('10.0000')
+    expect(result.balance).toBe('90.0000')
+  })
+
+  it('consumption mode: debits the gross (10 × 1.00 net @ 23 % → 12.30) and records the split', async () => {
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '100.0000' },
+      usageItem: usageItem(),
+      configs: { 'prepaid.tax_point': 'consumption' },
+    })
+    const { result } = await consumePrepaidUsage(em as never, account as never, input)
+    expect(result.ratedAmount).toBe('12.3000')
+    expect(result.balance).toBe('87.7000')
+    const txn = em.transactions.find((t) => t.type === 'usage')!
+    expect(txn.metadata).toMatchObject({ rated_amount: '10.0000', net: '10.0000', tax: '2.3000', tax_rate: '23', tax_point: 'consumption' })
+  })
+
+  it('consumption mode at 0 %: net = gross', async () => {
+    const em = createPrepaidMockEm({
+      account,
+      balance: { tenantId: TENANT, billAccountId: ACCT, balance: '100.0000' },
+      usageItem: usageItem({ taxRate: '0' }),
+      configs: { 'prepaid.tax_point': 'consumption' },
+    })
+    const { result } = await consumePrepaidUsage(em as never, account as never, input)
+    expect(result.ratedAmount).toBe('10.0000')
+  })
+})

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

@@ -9,11 +9,15 @@ function makeMockEm() {
   const store: Array<Record<string, unknown>> = []
   let idSeq = 0
   const nativeDeleteCalls: unknown[] = []
+  // Spec B: the seed fills empty seller fields on the org's BillingSettings.
+  const settings: Record<string, unknown> = { defaultTaxRate: '23', legalName: null }
 
   const em = {
     store,
     nativeDeleteCalls,
-    findOne: jest.fn(async (_entity: unknown, where: Record<string, unknown>) => {
+    settings,
+    findOne: jest.fn(async (entity: unknown, where: Record<string, unknown>) => {
+      if ((entity as { name?: string }).name === 'BillingSettings') return settings
       return (
         store.find((row) => {
           if (typeof where.name === 'string') return row.name === where.name
@@ -38,6 +42,7 @@ function makeMockEm() {
   return em as never as Parameters<typeof seedBillingDemo>[0] & {
     store: Array<Record<string, unknown>>
     nativeDeleteCalls: unknown[]
+    settings: Record<string, unknown>
   }
 }
 
@@ -49,7 +54,34 @@ describe('seedBillingDemo', () => {
     const em = makeMockEm()
     const res = await seedBillingDemo(em, SCOPE, { now: NOW })
 
-    expect(res).toEqual({ accountsCreated: 2, itemsCreated: 3, usageCreated: 1 })
+    expect(res).toEqual({ accountsCreated: 3, itemsCreated: 6, usageCreated: 1 })
+  })
+
+  it('dates items to demo in-advance, in-arrears and mid-cycle proration (Spec A)', async () => {
+    const em = makeMockEm()
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+    const byRef = (ref: string) =>
+      em.store.find((r) => r.sourceRef === ref) as { billStartDate: Date; chargeTiming: string } | undefined
+    const day = (d?: Date) => d?.toISOString().slice(0, 10)
+    expect(day(byRef('demo-billing-nw-rec')?.billStartDate)).toBe('2026-06-01')
+    expect(byRef('demo-billing-nw-rec')?.chargeTiming).toBe('in_advance')
+    expect(day(byRef('demo-billing-nw-addon')?.billStartDate)).toBe('2026-05-15')
+    expect(byRef('demo-billing-gx-arr')).toMatchObject({ chargeTiming: 'in_arrears' })
+    expect(day(byRef('demo-billing-gx-arr')?.billStartDate)).toBe('2026-05-01')
+  })
+
+  it('seeds a B2C person account invoiced in Polish next to the company accounts', async () => {
+    const em = makeMockEm()
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+
+    const person = em.store.find((r) => r.name === 'Demo — Jan Kowalski') as
+      | { customerKind: string; invoiceLanguage: string }
+      | undefined
+    const company = em.store.find((r) => r.name === 'Demo — Northwind Telecom') as
+      | { customerKind: string }
+      | undefined
+    expect(person).toMatchObject({ customerKind: 'person', invoiceLanguage: 'pl' })
+    expect(company?.customerKind).toBe('company')
   })
 
   it('is idempotent — a second run creates nothing', async () => {
@@ -83,4 +115,23 @@ describe('seedBillingDemo', () => {
     await resetBillingDemo(em, SCOPE)
     expect(em.nativeDelete).toHaveBeenCalledTimes(3)
   })
+
+  it('seeds VAT rates on items, including a 0 % item (Spec B)', async () => {
+    const em = makeMockEm()
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+    const rates = em.store.filter((r) => typeof r.sourceRef === 'string' && 'taxRate' in r).map((r) => r.taxRate)
+    expect(rates).toContain('23')
+    expect(rates).toContain('8')
+    expect(rates).toContain('0')
+  })
+
+  it('fills empty seller settings so demo invoices can be posted, never overwriting real values', async () => {
+    const em = makeMockEm()
+    em.settings.taxId = 'PL-REAL'
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+    expect(em.settings.legalName).toBe('Dainamite Demo sp. z o.o.')
+    expect(em.settings.iban).toBe('PL61109010140000071219812874')
+    expect(em.settings.sellerAddress).toMatchObject({ city: 'Kraków' })
+    expect(em.settings.taxId).toBe('PL-REAL')
+  })
 })

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

@@ -0,0 +1,28 @@
+import { DEFAULT_DEMO_SELLER, applySellerDefaults, sellerFieldsToFill } from '../../lib/seeds/sellerSettings'
+import { billingSettingsUpdateSchema } from '../../data/validators'
+import { missingSellerFields } from '../../lib/billingSettings'
+
+const scope = { tenantId: '11111111-1111-4111-8111-111111111111', organizationId: '22222222-2222-4222-8222-222222222222' }
+
+describe('seller defaults for seed tenants', () => {
+  it('fills only empty fields — real details are never overwritten', () => {
+    const fill = sellerFieldsToFill(
+      { legalName: 'Real Co', sellerAddress: null, taxId: '', bankName: null, iban: 'PL61109010140000071219812874', bic: null, invoiceFooter: null } as never,
+      DEFAULT_DEMO_SELLER,
+    )
+    expect(Object.keys(fill).sort()).toEqual(['bankName', 'bic', 'invoiceFooter', 'sellerAddress', 'taxId'])
+  })
+
+  it('applies and flushes once; a re-run is a no-op', async () => {
+    const settings: Record<string, unknown> = { legalName: null, sellerAddress: null, taxId: null, bankName: null, iban: null, bic: null, invoiceFooter: null }
+    const em = { findOne: jest.fn(async () => settings), flush: jest.fn(async () => undefined), execute: jest.fn() }
+    expect(await applySellerDefaults(em as never, scope, DEFAULT_DEMO_SELLER)).toHaveLength(7)
+    expect(missingSellerFields(settings as never)).toEqual([])
+    expect(await applySellerDefaults(em as never, scope, DEFAULT_DEMO_SELLER)).toEqual([])
+    expect(em.flush).toHaveBeenCalledTimes(1)
+  })
+
+  it('the default profile passes the settings validators (the page can save it unchanged)', () => {
+    expect(billingSettingsUpdateSchema.safeParse({ ...scope, ...DEFAULT_DEMO_SELLER }).success).toBe(true)
+  })
+})

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

@@ -0,0 +1,190 @@
+import {
+  MAX_PERIODS_PER_ITEM,
+  computeRecurringLines,
+  gridPeriodContaining,
+  inclusiveDays,
+  roundHalfUp2dp,
+  type RecurringItemState,
+} from '../../lib/servicePeriods'
+import type { BillCycle } from '../../data/validators'
+
+const d = (iso: string) => new Date(`${iso}T00:00:00.000Z`)
+const iso = (date: Date | null) => (date ? date.toISOString().slice(0, 10) : null)
+
+function item(overrides: Partial<RecurringItemState> = {}): RecurringItemState {
+  return {
+    id: 'item-1',
+    chargeTiming: 'in_advance',
+    prorate: true,
+    billStartDate: d('2026-11-14'),
+    billEndDate: null,
+    billedToDate: null,
+    unitPrice: 100,
+    isActive: true,
+    deletedAt: null,
+    ...overrides,
+  }
+}
+
+function run(state: RecurringItemState, billDate: string, cycle: BillCycle = 'monthly') {
+  const res = computeRecurringLines(state, { billDate: d(billDate), cycle })
+  return {
+    ...res,
+    periods: res.lines.map((l) => [iso(l.servicePeriodStart), iso(l.servicePeriodEnd), l.amount]),
+    watermark: iso(res.newBilledToDate),
+  }
+}
+
+describe('helpers', () => {
+  it('counts inclusive days and rounds half-up symmetrically', () => {
+    expect(inclusiveDays(d('2026-11-14'), d('2026-11-30'))).toBe(17)
+    expect(roundHalfUp2dp(1.005)).toBe(1.01)
+    expect(roundHalfUp2dp(-1.005)).toBe(-1.01)
+  })
+
+  it('finds the grid period containing a date, without month-end drift', () => {
+    const p = gridPeriodContaining(d('2026-01-31'), 'monthly', d('2026-03-31'))
+    expect([iso(p.start), iso(p.end)]).toEqual(['2026-03-31', '2026-04-29'])
+    const back = gridPeriodContaining(d('2026-12-01'), 'monthly', d('2026-11-14'))
+    expect([iso(back.start), iso(back.end)]).toEqual(['2026-11-01', '2026-11-30'])
+  })
+})
+
+describe('computeRecurringLines — spec worked examples', () => {
+  it("operator's test: in advance from Nov 14 bills Nov 14–Dec 13 on Nov 14", () => {
+    const r = run(item(), '2026-11-14')
+    expect(r.periods).toEqual([['2026-11-14', '2026-12-13', 100]])
+    expect(r.watermark).toBe('2026-12-13')
+    expect(r.lines[0].proration).toBeNull()
+  })
+
+  it('catch-up chain: Dec 14 and Jan 14 continue from the watermark', () => {
+    const dec = run(item({ billedToDate: d('2026-12-13') }), '2026-12-14')
+    expect(dec.periods).toEqual([['2026-12-14', '2027-01-13', 100]])
+    const jan = run(item({ billedToDate: d('2027-01-13') }), '2027-01-14')
+    expect(jan.periods).toEqual([['2027-01-14', '2027-02-13', 100]])
+  })
+
+  it('mid-cycle add: prorated stub + full next period', () => {
+    const r = run(item(), '2026-12-01')
+    expect(r.periods).toEqual([
+      ['2026-11-14', '2026-11-30', 56.67],
+      ['2026-12-01', '2026-12-31', 100],
+    ])
+    expect(r.lines[0].proration).toEqual({ activeDays: 17, periodDays: 30 })
+    expect(r.watermark).toBe('2026-12-31')
+  })
+
+  it('in arrears bills the period just ended', () => {
+    const r = run(item({ chargeTiming: 'in_arrears', billStartDate: d('2026-11-01') }), '2026-12-01')
+    expect(r.periods).toEqual([['2026-11-01', '2026-11-30', 100]])
+  })
+
+  it('cancel after prepay: credit for unused days, watermark pulled back', () => {
+    const r = run(item({ billStartDate: d('2026-01-01'), billedToDate: d('2026-12-31'), billEndDate: d('2026-12-15') }), '2027-01-01')
+    expect(r.periods).toEqual([['2026-12-16', '2026-12-31', -51.61]])
+    expect(r.lines[0].kind).toBe('credit')
+    expect(r.watermark).toBe('2026-12-15')
+  })
+})
+
+describe('computeRecurringLines — edge cases', () => {
+  it('nothing to bill before the item starts (in arrears, start in the future)', () => {
+    const r = run(item({ chargeTiming: 'in_arrears', billStartDate: d('2026-12-05') }), '2026-12-01')
+    expect(r.lines).toHaveLength(0)
+    expect(r.watermark).toBeNull()
+  })
+
+  it('backdated item spanning 3 grid periods lands on one bill date', () => {
+    const r = run(item({ chargeTiming: 'in_arrears', billStartDate: d('2026-09-01') }), '2026-12-01')
+    expect(r.periods).toEqual([
+      ['2026-09-01', '2026-09-30', 100],
+      ['2026-10-01', '2026-10-31', 100],
+      ['2026-11-01', '2026-11-30', 100],
+    ])
+  })
+
+  it('prorates a mid-period end (in arrears)', () => {
+    const r = run(
+      item({ chargeTiming: 'in_arrears', billStartDate: d('2026-11-01'), billEndDate: d('2026-11-10') }),
+      '2026-12-01',
+    )
+    expect(r.periods).toEqual([['2026-11-01', '2026-11-10', 33.33]])
+    expect(r.watermark).toBe('2026-11-10')
+  })
+
+  it('an end exactly on a grid boundary is a full period (no proration)', () => {
+    const r = run(item({ billStartDate: d('2026-12-01'), billEndDate: d('2026-12-31') }), '2026-12-01')
+    expect(r.periods).toEqual([['2026-12-01', '2026-12-31', 100]])
+  })
+
+  it('prorate=false skips partial periods but still advances the watermark', () => {
+    const r = run(item({ prorate: false }), '2026-12-01')
+    expect(r.periods).toEqual([['2026-12-01', '2026-12-31', 100]])
+    expect(r.skipped).toEqual([
+      expect.objectContaining({ reason: 'partial-period-not-prorated' }),
+    ])
+    expect(r.watermark).toBe('2026-12-31')
+  })
+
+  it('prorate=false never credits an ended item and keeps the watermark', () => {
+    const r = run(item({ prorate: false, billedToDate: d('2026-12-31'), billEndDate: d('2026-12-15') }), '2027-01-01')
+    expect(r.lines).toHaveLength(0)
+    expect(r.skipped[0].reason).toBe('ended-after-billing-no-credit')
+    expect(r.watermark).toBe('2026-12-31')
+  })
+
+  it('re-running the same bill date with the new watermark yields nothing (idempotent)', () => {
+    const first = run(item(), '2026-12-01')
+    const again = run(item({ billedToDate: first.newBilledToDate }), '2026-12-01')
+    expect(again.lines).toHaveLength(0)
+  })
+
+  it('switching in arrears → in advance never overlaps or gaps', () => {
+    const arrears = run(item({ chargeTiming: 'in_arrears', billStartDate: d('2026-11-01') }), '2026-12-01')
+    expect(arrears.watermark).toBe('2026-11-30')
+    const advance = run(
+      item({ chargeTiming: 'in_advance', billStartDate: d('2026-11-01'), billedToDate: arrears.newBilledToDate }),
+      '2027-01-01',
+    )
+    expect(advance.periods).toEqual([
+      ['2026-12-01', '2026-12-31', 100],
+      ['2027-01-01', '2027-01-31', 100],
+    ])
+  })
+
+  it('switching in advance → in arrears waits until the prepaid period has passed', () => {
+    const r = run(item({ chargeTiming: 'in_arrears', billedToDate: d('2026-12-31') }), '2027-01-01')
+    expect(r.lines).toHaveLength(0)
+    expect(r.watermark).toBe('2026-12-31')
+  })
+
+  it('handles month-end anchors, leap years and other cycles', () => {
+    expect(run(item({ billStartDate: d('2027-01-31') }), '2027-01-31').periods).toEqual([
+      ['2027-01-31', '2027-02-27', 100],
+    ])
+    expect(run(item({ billStartDate: d('2028-02-01') }), '2028-02-01').periods).toEqual([
+      ['2028-02-01', '2028-02-29', 100],
+    ])
+    expect(run(item({ billStartDate: d('2026-11-16') }), '2026-11-16', 'weekly').periods).toEqual([
+      ['2026-11-16', '2026-11-22', 100],
+    ])
+    expect(run(item({ billStartDate: d('2026-10-01') }), '2026-10-01', 'quarterly').periods).toEqual([
+      ['2026-10-01', '2026-12-31', 100],
+    ])
+    expect(run(item({ billStartDate: d('2026-01-01') }), '2026-01-01', 'annually').periods).toEqual([
+      ['2026-01-01', '2026-12-31', 100],
+    ])
+  })
+
+  it('skips inactive and soft-deleted items', () => {
+    expect(run(item({ isActive: false }), '2026-12-01').skipped[0].reason).toBe('item-inactive')
+    expect(run(item({ deletedAt: d('2026-11-20') }), '2026-12-01').skipped[0].reason).toBe('item-soft-deleted')
+  })
+
+  it('caps runaway backdating', () => {
+    const r = run(item({ chargeTiming: 'in_arrears', billStartDate: d('2000-01-01') }), '2026-12-01')
+    expect(r.lines).toHaveLength(MAX_PERIODS_PER_ITEM)
+    expect(r.skipped.at(-1)?.reason).toBe('period-cap-reached')
+  })
+})

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

@@ -1,5 +1,4 @@
 import { captureTopup } from '../../lib/topupCapture'
-import { __resetInvoiceStatusCacheForTests } from '../../lib/invoiceStatus'
 import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
 
 const ACCOUNT = {
@@ -9,22 +8,6 @@ const ACCOUNT = {
   currencyCode: 'EUR',
 }
 
-function makeDeps() {
-  return {
-    numberGenerator: {
-      generate: jest.fn(async () => ({ number: 'FV/2026/06/0042', format: 'x', sequence: 42 })),
-    },
-    taxService: {
-      calculateUnitAmounts: jest.fn(async (input: { amount: number }) => ({
-        netAmount: input.amount,
-        grossAmount: input.amount,
-        taxAmount: 0,
-        taxRate: 0,
-      })),
-    },
-  }
-}
-
 function makeTopup(overrides: Record<string, unknown> = {}) {
   return {
     id: 'topup-1',
@@ -39,10 +22,6 @@ function makeTopup(overrides: Record<string, unknown> = {}) {
   }
 }
 
-beforeEach(() => {
-  __resetInvoiceStatusCacheForTests()
-})
-
 describe('captureTopup', () => {
   it('credits the balance, issues a receipt, and flips the top-up to captured', async () => {
     const topup = makeTopup()
@@ -50,7 +29,7 @@ describe('captureTopup', () => {
       topup,
       balance: { tenantId: 'ten-1', billAccountId: 'acct-1', balance: '0.0000' },
     })
-    const result = await captureTopup(em as never, makeDeps(), {
+    const result = await captureTopup(em as never, {
       topup: topup as never,
       account: ACCOUNT,
       taxRate: 0,
@@ -61,7 +40,7 @@ describe('captureTopup', () => {
     expect(result.balanceAfter).toBe('100.0000')
     expect(result.transactionId).toBeTruthy()
     expect(result.receiptInvoiceId).toBeTruthy()
-    expect(result.invoiceNumber).toBe('FV/2026/06/0042')
+    expect(result.invoiceNumber).toMatch(/^RC\/\d{4}\/\d{2}\/0042$/)
 
     // The credit transaction carries the deterministic source_ref.
     expect(em.transactions).toHaveLength(1)
@@ -81,7 +60,7 @@ describe('captureTopup', () => {
       topup,
       balance: { tenantId: 'ten-1', billAccountId: 'acct-1', balance: '100.0000' },
     })
-    const result = await captureTopup(em as never, makeDeps(), {
+    const result = await captureTopup(em as never, {
       topup: topup as never,
       account: ACCOUNT,
       taxRate: 0,
@@ -107,8 +86,7 @@ describe('captureTopup', () => {
       billAccountId: 'acct-1',
       createdAt: new Date('2026-06-10'),
     })
-    const deps = makeDeps()
-    const result = await captureTopup(em as never, deps, {
+    const result = await captureTopup(em as never, {
       topup: topup as never,
       account: ACCOUNT,
       taxRate: 0,
@@ -117,7 +95,7 @@ describe('captureTopup', () => {
     expect(result.balanceAfter).toBe('100.0000') // unchanged — dedup hit
     expect(result.receiptInvoiceId).toBe('inv-prior') // returns the existing receipt
     expect(em.transactions).toHaveLength(1) // no new credit transaction
-    // No second fiscal document: the number generator was never called.
-    expect(deps.numberGenerator.generate).not.toHaveBeenCalled()
+    // No second fiscal document: no receipt number was claimed.
+    expect(em.sequenceClaims).toEqual([])
   })
 })

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

@@ -1,5 +1,4 @@
-import { createTopupReceipt, type TopupReceiptDeps } from '../../lib/topupReceipt'
-import { __resetInvoiceStatusCacheForTests } from '../../lib/invoiceStatus'
+import { createTopupReceipt } from '../../lib/topupReceipt'
 import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
 
 const ACCOUNT = {
@@ -9,40 +8,12 @@ const ACCOUNT = {
   currencyCode: 'EUR',
 }
 
-function makeDeps(taxRateOut: number | null): TopupReceiptDeps {
-  return {
-    numberGenerator: {
-      generate: jest.fn(async () => ({
-        number: 'FV/2026/06/0042',
-        format: 'FV/{yyyy}/{mm}/{seq:4}',
-        sequence: 42,
-      })),
-    },
-    taxService: {
-      calculateUnitAmounts: jest.fn(async (input: { amount: number; taxRate?: number | string | null }) => {
-        const rate = typeof input.taxRate === 'number' ? input.taxRate : Number(input.taxRate ?? 0)
-        const gross = input.amount
-        const net = rate > 0 ? gross / (1 + rate / 100) : gross
-        return {
-          netAmount: Math.round(net * 10000) / 10000,
-          grossAmount: Math.round(gross * 10000) / 10000,
-          taxAmount: Math.round((gross - net) * 10000) / 10000,
-          taxRate: taxRateOut,
-        }
-      }),
-    },
-  }
-}
-
-beforeEach(() => {
-  __resetInvoiceStatusCacheForTests()
-})
+const RECEIPT_NUMBER = /^RC\/\d{4}\/\d{2}\/0042$/
 
 describe('createTopupReceipt — VAT at top-up (amount is gross)', () => {
-  it('splits 100 gross @ 23% into net + VAT and posts paid', async () => {
+  it('splits 100 gross @ 23% into net + VAT and issues a paid receipt document', async () => {
     const em = createPrepaidMockEm()
-    const deps = makeDeps(23)
-    const receipt = await createTopupReceipt(em as never, deps, {
+    const receipt = await createTopupReceipt(em as never, {
       account: ACCOUNT,
       topupId: 'topup-1',
       paymentId: 'pay-1',
@@ -50,35 +21,33 @@ describe('createTopupReceipt — VAT at top-up (amount is gross)', () => {
       taxRate: 23,
     })
 
-    expect(receipt.invoiceNumber).toBe('FV/2026/06/0042')
-    expect(receipt.grossAmount).toBe('100.0000')
-    expect(receipt.netAmount).toBe('81.3008')
-    expect(receipt.taxAmount).toBe('18.6992')
-    expect(receipt.taxRate).toBe(23)
+    expect(receipt.invoiceNumber).toMatch(RECEIPT_NUMBER)
+    expect(receipt).toMatchObject({ grossAmount: '100.0000', netAmount: '81.3000', taxAmount: '18.7000', taxRate: 23 })
+    expect(em.sequenceClaims).toEqual(['receipt'])
 
-    // The invoice was persisted as paid with a single top-up line.
-    const invoice = em.persisted.find((e) => (e as { status?: string }).status === 'paid') as Record<
-      string,
-      unknown
-    >
-    expect(invoice).toBeTruthy()
-    expect(invoice.paidTotalAmount).toBe('100.0000')
-    expect(invoice.outstandingAmount).toBe('0')
-    expect((invoice.metadata as Record<string, unknown>).kind).toBe('prepaid_topup')
+    const doc = em.persisted.find((e) => (e as { documentType?: string }).documentType === 'receipt') as Record<string, unknown>
+    expect(doc).toMatchObject({
+      status: 'paid',
+      series: 'receipt',
+      topupId: 'topup-1',
+      billAccountId: 'acct-1',
+      paidTotal: '100.0000',
+      outstanding: '0',
+      totalGross: '100.0000',
+    })
+    const line = em.persisted.find((e) => (e as { billingType?: string }).billingType === 'receipt') as Record<string, unknown>
+    expect(line).toMatchObject({ invoiceId: doc.id, taxRate: '23.0000', netAmount: '81.3000', taxAmount: '18.7000' })
   })
 
   it('0% VAT → net == gross, tax 0', async () => {
     const em = createPrepaidMockEm()
-    const deps = makeDeps(null)
-    const receipt = await createTopupReceipt(em as never, deps, {
+    const receipt = await createTopupReceipt(em as never, {
       account: ACCOUNT,
       topupId: 'topup-2',
       paymentId: 'pay-2',
       amount: '50.0000',
       taxRate: 0,
     })
-    expect(receipt.netAmount).toBe('50.0000')
-    expect(receipt.grossAmount).toBe('50.0000')
-    expect(receipt.taxAmount).toBe('0.0000')
+    expect(receipt).toMatchObject({ netAmount: '50.0000', grossAmount: '50.0000', taxAmount: '0.0000', taxRate: 0 })
   })
 })

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

@@ -0,0 +1,51 @@
+import { DefaultTaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'
+import { lineAmountsFromGross, lineAmountsFromNet, money4, round2, sumTotals } from '../../lib/vat'
+
+describe('vat', () => {
+  it('rounds half-up symmetrically', () => {
+    expect(round2(1.005)).toBe(1.01)
+    expect(round2(-1.005)).toBe(-1.01)
+    expect(round2(2.675)).toBe(2.68)
+  })
+
+  it('computes from net with net + tax = gross', () => {
+    expect(lineAmountsFromNet(100, 23)).toEqual({ net: 100, tax: 23, gross: 123 })
+    expect(lineAmountsFromNet(56.67, 23)).toEqual({ net: 56.67, tax: 13.03, gross: 69.7 })
+    expect(lineAmountsFromNet(10, 0)).toEqual({ net: 10, tax: 0, gross: 10 })
+    expect(lineAmountsFromNet(-51.61, 23)).toEqual({ net: -51.61, tax: -11.87, gross: -63.48 })
+  })
+
+  it('splits gross with net + tax = gross exactly', () => {
+    for (const [gross, rate] of [[100, 23], [99.99, 8], [0.01, 23], [123, 5], [50, 0]] as const) {
+      const r = lineAmountsFromGross(gross, rate)
+      expect(round2(r.net + r.tax)).toBe(r.gross)
+      expect(r.gross).toBe(round2(gross))
+    }
+    expect(lineAmountsFromGross(123, 23)).toEqual({ net: 100, tax: 23, gross: 123 })
+  })
+
+  it('sums rounded lines into 4dp column strings', () => {
+    expect(sumTotals([lineAmountsFromNet(100, 23), lineAmountsFromNet(56.67, 23)])).toEqual({
+      subtotalNet: '156.6700',
+      taxTotal: '36.0300',
+      totalGross: '192.7000',
+    })
+    expect(money4(Number.NaN)).toBe('0.0000')
+  })
+
+  it('stays within half a cent of the core tax service (gross split parity)', async () => {
+    const core = new DefaultTaxCalculationService({} as never)
+    for (const [gross, rate] of [[100, 23], [99.99, 8], [250, 5], [1234.56, 23], [0.99, 23]] as const) {
+      const ours = lineAmountsFromGross(gross, rate)
+      const theirs = await core.calculateUnitAmounts({
+        amount: gross,
+        mode: 'gross',
+        organizationId: 'o',
+        tenantId: 't',
+        taxRate: rate,
+      })
+      expect(Math.abs(ours.net - theirs.netAmount)).toBeLessThanOrEqual(0.005)
+      expect(Math.abs(ours.tax - theirs.taxAmount)).toBeLessThanOrEqual(0.005)
+    }
+  })
+})