@dainamite/billing 0.20.0 → 0.22.0

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

@@ -1,5 +1,12 @@
-import { buildInvoiceLinesFromItems } from '../../lib/invoiceWriter'
-import type { BillingItem } from '../../data/entities'
+import {
+  buildInvoiceLinesFromItems,
+  buildRecurringLineDescriptors,
+  itemTaxRate,
+  writeDraftInvoice,
+  type InvoiceLineDescriptor,
+} from '../../lib/invoiceWriter'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { BillingAccount, BillingItem } from '../../data/entities'
 
 function makeItem(overrides: Partial<BillingItem>): BillingItem {
   return {
@@ -18,6 +25,8 @@ function makeItem(overrides: Partial<BillingItem>): BillingItem {
     sourceRef: overrides.sourceRef ?? null,
     currencyMismatch: overrides.currencyMismatch ?? false,
     billedToDate: overrides.billedToDate ?? null,
+    taxRate: overrides.taxRate ?? '0',
+    priceBasis: overrides.priceBasis ?? 'net',
     isActive: overrides.isActive ?? true,
     createdAt: overrides.createdAt ?? new Date(),
     updatedAt: overrides.updatedAt ?? new Date(),
@@ -37,11 +46,13 @@ describe('buildInvoiceLinesFromItems — recurring', () => {
       billingItemId: 'a',
       billingType: 'recurring',
       description: 'MRC A',
-      unitPriceNet: '49.9900',
+      unitPrice: '49.9900',
       quantity: '1',
-      totalNetAmount: '49.9900',
+      lineAmount: '49.9900',
+      priceBasis: 'net',
+      taxRate: '0',
     })
-    expect(lines[1].unitPriceNet).toBe('29.0000')
+    expect(lines[1].unitPrice).toBe('29.0000')
   })
 
   it('rounds unit_price half-up to 2dp before persisting', () => {
@@ -50,8 +61,8 @@ describe('buildInvoiceLinesFromItems — recurring', () => {
       makeItem({ type: 'recurring', rateJson: { unit_price: 1.004 } }), // half-down → 1.00
     ]
     const lines = buildInvoiceLinesFromItems(items)
-    expect(lines[0].unitPriceNet).toBe('1.0100')
-    expect(lines[1].unitPriceNet).toBe('1.0000')
+    expect(lines[0].unitPrice).toBe('1.0100')
+    expect(lines[1].unitPrice).toBe('1.0000')
   })
 
   it('skips a recurring item with malformed rateJson (defensive)', () => {
@@ -81,9 +92,11 @@ describe('buildInvoiceLinesFromItems — one_time', () => {
       billingItemId: 'fee',
       billingType: 'one_time',
       description: 'Activation fee',
-      unitPriceNet: '99.0000',
+      unitPrice: '99.0000',
       quantity: '1',
-      totalNetAmount: '99.0000',
+      lineAmount: '99.0000',
+      priceBasis: 'net',
+      taxRate: '0',
     })
   })
 
@@ -96,7 +109,7 @@ describe('buildInvoiceLinesFromItems — one_time', () => {
       }),
     ]
     const lines = buildInvoiceLinesFromItems(items)
-    expect(lines[0].unitPriceNet).toBe('-25.5000')
+    expect(lines[0].unitPrice).toBe('-25.5000')
   })
 })
 
@@ -117,3 +130,192 @@ describe('buildInvoiceLinesFromItems — mixed + usage exclusion', () => {
     expect(lines.find((l) => l.billingItemId === 'metered')).toBeUndefined()
   })
 })
+
+// ─── Spec B: VAT per line ────────────────────────────────────────
+
+describe('itemTaxRate', () => {
+  it('reads the item rate and treats missing / invalid values as 0', () => {
+    expect(itemTaxRate({ taxRate: '23.0000' })).toBe('23')
+    expect(itemTaxRate({ taxRate: '8' })).toBe('8')
+    expect(itemTaxRate({ taxRate: undefined as unknown as string })).toBe('0')
+    expect(itemTaxRate({ taxRate: 'abc' })).toBe('0')
+    expect(itemTaxRate({ taxRate: '-5' })).toBe('0')
+  })
+})
+
+describe('line builders carry the item VAT rate (Spec B)', () => {
+  it('one_time and recurring lines take the item rate', () => {
+    const lines = buildInvoiceLinesFromItems([
+      makeItem({ id: 'r', type: 'recurring', taxRate: '23', rateJson: { unit_price: 100 } }),
+      makeItem({ id: 'o', type: 'one_time', taxRate: '8', rateJson: { amount: 50 } }),
+    ])
+    expect(lines.map((l) => l.taxRate)).toEqual(['23', '8'])
+  })
+
+  it('proration and credit lines inherit the item rate', () => {
+    const item = { id: 'r', description: 'Plan', chargeTiming: 'in_advance' as const, taxRate: '23', priceBasis: 'net' as const }
+    const lines = buildRecurringLineDescriptors(item, [
+      {
+        kind: 'charge',
+        servicePeriodStart: new Date('2026-11-15T00:00:00Z'),
+        servicePeriodEnd: new Date('2026-11-30T00:00:00Z'),
+        amount: 53.33,
+        proration: { activeDays: 16, periodDays: 30 },
+      },
+      {
+        kind: 'credit',
+        servicePeriodStart: new Date('2026-12-10T00:00:00Z'),
+        servicePeriodEnd: new Date('2026-12-31T00:00:00Z'),
+        amount: -71,
+        proration: { activeDays: 22, periodDays: 31 },
+      },
+    ] as never)
+    expect(lines.map((l) => l.taxRate)).toEqual(['23', '23'])
+  })
+})
+
+type Created = { entity: string; data: Record<string, unknown> }
+
+function writerEm() {
+  const created: Created[] = []
+  const em = {
+    create: jest.fn((entity: { name: string }, data: Record<string, unknown>) => {
+      const row = { id: `${entity.name}-${created.length + 1}`, ...data }
+      created.push({ entity: entity.name, data: row })
+      return row
+    }),
+    persist: jest.fn(),
+    flush: jest.fn(async () => undefined),
+  }
+  return { em: em as unknown as EntityManager, created }
+}
+
+const account = {
+  id: 'acc-1',
+  organizationId: 'org-1',
+  tenantId: 'tenant-1',
+  currencyCode: 'PLN',
+} as BillingAccount
+
+function line(amount: string, taxRate: string, priceBasis: 'net' | 'gross' = 'net'): InvoiceLineDescriptor {
+  return {
+    billingItemId: 'item',
+    billingType: 'recurring',
+    description: 'x',
+    unitPrice: amount,
+    quantity: '1',
+    lineAmount: amount,
+    priceBasis,
+    taxRate,
+  }
+}
+
+const baseParams = {
+  account,
+  billDate: new Date('2026-11-01T00:00:00Z'),
+  period: { periodStart: new Date('2026-11-01T00:00:00Z'), periodEnd: new Date('2026-11-30T00:00:00Z') },
+  billRunId: 'run-1',
+}
+
+describe('writeDraftInvoice — VAT (Spec B, B-D2)', () => {
+  it('writes per-line VAT and sums rounded lines into the totals (mixed rates)', async () => {
+    const { em, created } = writerEm()
+    const written = await writeDraftInvoice(em, {
+      ...baseParams,
+      mode: 'real',
+      lines: [line('100.0000', '23'), line('33.3300', '8'), line('15.0000', '0')],
+    })
+    const invoice = created.find((c) => c.entity === 'BillingInvoice')!.data
+    const lines = created.filter((c) => c.entity === 'BillingInvoiceLine').map((c) => c.data)
+    expect(lines.map((l) => [l.taxRate, l.netAmount, l.taxAmount, l.grossAmount])).toEqual([
+      ['23', '100.0000', '23.0000', '123.0000'],
+      ['8', '33.3300', '2.6700', '36.0000'],
+      ['0', '15.0000', '0.0000', '15.0000'],
+    ])
+    expect(invoice).toMatchObject({
+      subtotalNet: '148.3300',
+      taxTotal: '25.6700',
+      totalGross: '174.0000',
+      outstanding: '174.0000',
+    })
+    expect(written).toMatchObject({ totalNet: '148.3300', totalGross: '174.0000' })
+  })
+
+  it('rounds VAT per line half-up (0.005 edge)', async () => {
+    const { em, created } = writerEm()
+    // 0.05 × 23 % = 0.0115 → 0.01 ; 2.15 × 23 % = 0.4945 → 0.49 ; 0.5 × 5 % = 0.025 → 0.03
+    await writeDraftInvoice(em, {
+      ...baseParams,
+      mode: 'real',
+      lines: [line('0.0500', '23'), line('2.1500', '23'), line('0.5000', '5')],
+    })
+    const taxes = created.filter((c) => c.entity === 'BillingInvoiceLine').map((c) => c.data.taxAmount)
+    expect(taxes).toEqual(['0.0100', '0.4900', '0.0300'])
+  })
+
+  it('keeps the sign on credit lines (negative net → negative VAT and gross)', async () => {
+    const { em, created } = writerEm()
+    await writeDraftInvoice(em, {
+      ...baseParams,
+      mode: 'real',
+      lines: [line('100.0000', '23'), line('-40.0000', '23')],
+    })
+    const credit = created.filter((c) => c.entity === 'BillingInvoiceLine')[1].data
+    expect([credit.netAmount, credit.taxAmount, credit.grossAmount]).toEqual(['-40.0000', '-9.2000', '-49.2000'])
+    expect(created.find((c) => c.entity === 'BillingInvoice')!.data.totalGross).toBe('73.8000')
+  })
+
+  it('dry mode computes VAT totals without persisting', async () => {
+    const { em, created } = writerEm()
+    const written = await writeDraftInvoice(em, { ...baseParams, mode: 'dry', lines: [line('10.0000', '23')] })
+    expect(created).toHaveLength(0)
+    expect(written).toEqual({ invoiceId: null, invoiceNumber: null, totalNet: '10.0000', totalGross: '12.3000' })
+  })
+})
+
+// ─── Spec F: price basis (F-D2) ──────────────────────────────────
+
+describe('writeDraftInvoice — gross price basis (Spec F)', () => {
+  it('reproduces a typed gross exactly (49.99 @ 23 %) and derives the net unit price', async () => {
+    const { em, created } = writerEm()
+    await writeDraftInvoice(em, { ...baseParams, mode: 'real', lines: [line('49.9900', '23', 'gross')] })
+    const persisted = created.find((c) => c.entity === 'BillingInvoiceLine')!.data
+    expect([persisted.netAmount, persisted.taxAmount, persisted.grossAmount]).toEqual(['40.6400', '9.3500', '49.9900'])
+    expect(persisted.unitPriceNet).toBe('40.6423')
+    expect(created.find((c) => c.entity === 'BillingInvoice')!.data.totalGross).toBe('49.9900')
+  })
+
+  it('keeps the net path unchanged (regression)', async () => {
+    const { em, created } = writerEm()
+    await writeDraftInvoice(em, { ...baseParams, mode: 'real', lines: [line('40.6400', '23')] })
+    const persisted = created.find((c) => c.entity === 'BillingInvoiceLine')!.data
+    expect([persisted.netAmount, persisted.taxAmount, persisted.grossAmount, persisted.unitPriceNet]).toEqual([
+      '40.6400',
+      '9.3500',
+      '49.9900',
+      '40.6400',
+    ])
+  })
+
+  it('carries the item basis on one-time, recurring and prorated lines', () => {
+    const built = buildInvoiceLinesFromItems([
+      makeItem({ id: 'g', type: 'recurring', priceBasis: 'gross', rateJson: { unit_price: 60 } }),
+      makeItem({ id: 'n', type: 'one_time', rateJson: { amount: 10 } }),
+    ])
+    expect(built.map((l) => l.priceBasis)).toEqual(['gross', 'net'])
+    const prorated = buildRecurringLineDescriptors(
+      { id: 'g', description: 'Plan', chargeTiming: 'in_advance', taxRate: '23', priceBasis: 'gross' },
+      [
+        {
+          billingItemId: 'g',
+          kind: 'charge',
+          servicePeriodStart: new Date('2026-11-15T00:00:00Z'),
+          servicePeriodEnd: new Date('2026-11-30T00:00:00Z'),
+          amount: 32,
+          proration: { activeDays: 16, periodDays: 30 },
+        },
+      ],
+    )
+    expect(prorated[0]).toMatchObject({ priceBasis: 'gross', lineAmount: '32.0000' })
+  })
+})

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

@@ -0,0 +1,42 @@
+import { itemBillingState } from '../../lib/itemBillingState'
+
+const TODAY = '2026-11-15'
+const recurring = (overrides: Record<string, unknown> = {}) => ({
+  type: 'recurring' as const,
+  is_active: true,
+  bill_start_date: '2026-11-01',
+  bill_end_date: null,
+  billed_to_date: null,
+  ...overrides,
+})
+
+describe('itemBillingState', () => {
+  it('inactive and usage items short-circuit', () => {
+    expect(itemBillingState(recurring({ is_active: false }), TODAY).status).toBe('inactive')
+    expect(itemBillingState(recurring({ type: 'usage' }), TODAY).status).toBe('metered')
+  })
+
+  it('not billed yet: scheduled when it starts later, awaiting a run once started', () => {
+    expect(itemBillingState(recurring({ bill_start_date: '2026-12-01' }), TODAY)).toEqual({ status: 'scheduled', date: '2026-12-01' })
+    expect(itemBillingState(recurring(), TODAY)).toEqual({ status: 'awaiting_run', date: null })
+  })
+
+  it('recurring charged ahead is current; charged through a past day is due from the next day', () => {
+    expect(itemBillingState(recurring({ billed_to_date: '2026-12-14' }), TODAY)).toEqual({ status: 'current', date: '2026-12-14' })
+    expect(itemBillingState(recurring({ billed_to_date: '2026-11-15' }), TODAY).status).toBe('current')
+    expect(itemBillingState(recurring({ billed_to_date: '2026-10-31' }), TODAY)).toEqual({ status: 'due', date: '2026-11-01' })
+  })
+
+  it('recurring charged through its end date is fully billed', () => {
+    expect(
+      itemBillingState(recurring({ bill_end_date: '2026-11-30', billed_to_date: '2026-11-30T00:00:00.000Z' }), TODAY),
+    ).toEqual({ status: 'fully_billed', date: '2026-11-30' })
+  })
+
+  it('one-time: billed once a run charged it', () => {
+    const fee = { ...recurring(), type: 'one_time' as const }
+    expect(itemBillingState({ ...fee, billed_to_date: '2026-11-30' }, TODAY).status).toBe('billed')
+    expect(itemBillingState(fee, TODAY).status).toBe('awaiting_run')
+    expect(itemBillingState({ ...fee, bill_start_date: '2027-01-01' }, TODAY).status).toBe('scheduled')
+  })
+})

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

@@ -0,0 +1,165 @@
+jest.mock('@open-mercato/shared/lib/commands/helpers', () => {
+  const actual = jest.requireActual('@open-mercato/shared/lib/commands/helpers')
+  return { ...actual, emitCrudSideEffects: jest.fn(async () => undefined) }
+})
+
+import { planPriceChange } from '../../lib/itemPriceChange'
+import { computeRecurringLines } from '../../lib/servicePeriods'
+import { changeItemPriceCommand } from '../../commands/items'
+
+const iso = (date: Date | null) => (date ? date.toISOString().slice(0, 10) : null)
+const d = (value: string) => new Date(`${value}T00:00:00.000Z`)
+
+const recurring = {
+  type: 'recurring',
+  isActive: true,
+  deletedAt: null,
+  billStartDate: '2026-11-01',
+  billEndDate: null as string | null,
+}
+
+describe('planPriceChange', () => {
+  it('ends the current item the day before and keeps the original end date on the copy', () => {
+    const result = planPriceChange({ ...recurring, billEndDate: '2027-06-30' }, '2026-12-15')
+    if (!result.ok) throw new Error(result.error)
+    expect(iso(result.plan.oldItemEndDate)).toBe('2026-12-14')
+    expect(iso(result.plan.newItemStartDate)).toBe('2026-12-15')
+    expect(iso(result.plan.newItemEndDate)).toBe('2027-06-30')
+  })
+
+  it('refuses non-recurring, inactive, on/before start and after end', () => {
+    expect(planPriceChange({ ...recurring, type: 'one_time' }, '2026-12-15')).toEqual({
+      ok: false,
+      error: 'billing.item.price_change_recurring_only',
+    })
+    expect(planPriceChange({ ...recurring, isActive: false }, '2026-12-15')).toMatchObject({ error: 'billing.item.price_change_inactive' })
+    expect(planPriceChange(recurring, '2026-11-01')).toMatchObject({ error: 'billing.item.price_change_before_start' })
+    expect(planPriceChange({ ...recurring, billEndDate: '2026-12-31' }, '2027-01-01')).toMatchObject({
+      error: 'billing.item.price_change_after_end',
+    })
+  })
+})
+
+describe('price change never bills a day twice (engine maths)', () => {
+  // Monthly in advance, billed through Dec 13 at 30; price changes to 60 on Nov 24.
+  const base = {
+    chargeTiming: 'in_advance' as const,
+    billStartDate: d('2026-11-14'),
+    billedToDate: d('2026-12-13'),
+    isActive: true,
+    deletedAt: null,
+  }
+
+  it('prorate on: the old item credits Nov 24 – Dec 13, the new item charges the same days at the new price', () => {
+    const old = computeRecurringLines(
+      { ...base, id: 'old', prorate: true, billEndDate: d('2026-11-23'), unitPrice: 30 },
+      { billDate: d('2026-12-14'), cycle: 'monthly' },
+    )
+    const fresh = computeRecurringLines(
+      { ...base, id: 'new', prorate: true, billStartDate: d('2026-11-24'), billEndDate: null, billedToDate: null, unitPrice: 60 },
+      { billDate: d('2026-12-14'), cycle: 'monthly' },
+    )
+    const credit = old.lines.find((line) => line.kind === 'credit')!
+    expect([iso(credit.servicePeriodStart), iso(credit.servicePeriodEnd)]).toEqual(['2026-11-24', '2026-12-13'])
+    expect(credit.amount).toBeLessThan(0)
+    const recharge = fresh.lines.find((line) => iso(line.servicePeriodStart) === '2026-11-24')!
+    expect(iso(recharge.servicePeriodEnd)).toBe('2026-12-13')
+    expect(recharge.amount).toBeCloseTo(-credit.amount * 2, 1) // same days, double the price
+  })
+
+  it('prorate off: no credit, and the new item starts charging at its next full period', () => {
+    const old = computeRecurringLines(
+      { ...base, id: 'old', prorate: false, billEndDate: d('2026-11-23'), unitPrice: 30 },
+      { billDate: d('2026-12-14'), cycle: 'monthly' },
+    )
+    const fresh = computeRecurringLines(
+      { ...base, id: 'new', prorate: false, billStartDate: d('2026-11-24'), billEndDate: null, billedToDate: null, unitPrice: 60 },
+      { billDate: d('2026-12-14'), cycle: 'monthly' },
+    )
+    expect(old.lines).toHaveLength(0)
+    expect(fresh.lines.map((line) => [iso(line.servicePeriodStart), iso(line.servicePeriodEnd)])).toEqual([
+      ['2026-12-14', '2027-01-13'],
+    ])
+  })
+})
+
+describe('changeItemPriceCommand', () => {
+  const TENANT = '11111111-1111-4111-8111-111111111111'
+  const ORG = '22222222-2222-4222-8222-222222222222'
+  const ITEM = '33333333-3333-4333-8333-333333333333'
+
+  function env(record: Record<string, unknown> | null) {
+    const created: Record<string, unknown>[] = []
+    const em = {
+      findOne: jest.fn(async () => record),
+      create: jest.fn((_entity: unknown, data: Record<string, unknown>) => {
+        const row = { id: 'new-item', ...data }
+        created.push(row)
+        return row
+      }),
+      persist: jest.fn(),
+      flush: jest.fn(async () => undefined),
+      transactional: jest.fn(async (fn: (tem: unknown) => Promise<unknown>): Promise<unknown> => fn(em)),
+      fork: jest.fn((): unknown => em),
+    }
+    const ctx = {
+      container: { resolve: jest.fn((name: string) => (name === 'dataEngine' ? {} : em)) },
+      auth: { tenantId: TENANT, orgId: ORG },
+      selectedOrganizationId: ORG,
+      organizationIds: [ORG],
+      organizationScope: null,
+    }
+    return { ctx, created }
+  }
+
+  it('ends the item and creates a copy with the new price, keeping everything else', async () => {
+    const record: Record<string, unknown> = {
+      id: ITEM,
+      tenantId: TENANT,
+      organizationId: ORG,
+      billAccountId: 'acc',
+      type: 'recurring',
+      isActive: true,
+      deletedAt: null,
+      billStartDate: '2026-11-01',
+      billEndDate: null,
+      description: 'Plan',
+      rateJson: { unit_price: 49 },
+      chargeTiming: 'in_arrears',
+      prorate: false,
+      taxRate: '23',
+      priceBasis: 'gross',
+      sourceRef: 'cpq-123',
+      subscriptionId: 'sub-1',
+    }
+    const { ctx, created } = env(record)
+    const result = await changeItemPriceCommand.execute(
+      { tenantId: TENANT, organizationId: ORG, id: ITEM, effectiveDate: d('2026-12-15'), unitPrice: 59 },
+      ctx as never,
+    )
+    expect(result).toEqual({ previousItemId: ITEM, newItemId: 'new-item' })
+    expect(iso(record.billEndDate as Date)).toBe('2026-12-14')
+    expect(created[0]).toMatchObject({
+      billAccountId: 'acc',
+      rateJson: { unit_price: 59 },
+      chargeTiming: 'in_arrears',
+      prorate: false,
+      taxRate: '23',
+      priceBasis: 'gross',
+      subscriptionId: 'sub-1',
+      sourceRef: null,
+      billedToDate: null,
+    })
+    expect(iso(created[0].billStartDate as Date)).toBe('2026-12-15')
+  })
+
+  it('maps planning errors to 422 with the code', async () => {
+    const { ctx } = env({ id: ITEM, type: 'one_time', isActive: true, deletedAt: null, billStartDate: '2026-11-01' })
+    await expect(
+      changeItemPriceCommand.execute(
+        { tenantId: TENANT, organizationId: ORG, id: ITEM, effectiveDate: d('2026-12-15'), unitPrice: 59 },
+        ctx as never,
+      ),
+    ).rejects.toMatchObject({ status: 422, body: { code: 'billing.item.price_change_recurring_only' } })
+  })
+})

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

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

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

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