@dainamite/billing 0.20.0 → 0.21.0

package/src/modules/billing/__tests__/commands/itemsBulk.test.ts

@@ -24,6 +24,7 @@ type Env = {
   ctx: { container: { resolve: jest.MockedFunction<(name: string) => unknown> }; auth: null }
   em: {
     find: jest.MockedFunction<(entity: unknown, where: unknown) => Promise<unknown[]>>
+    findOne: jest.MockedFunction<(entity: unknown, where: unknown) => Promise<unknown>>
     create: jest.MockedFunction<(entity: unknown, data: Record<string, unknown>) => unknown>
     persist: jest.MockedFunction<(entity: unknown) => unknown>
     flush: jest.MockedFunction<() => Promise<void>>
@@ -68,6 +69,10 @@ function createEnv(
       }
       return []
     }) as never,
+    // Spec B: the org default VAT rate comes from BillingSettings.
+    findOne: jest.fn(async (entity: unknown) =>
+      (entity as { name?: string }).name === 'BillingSettings' ? { defaultTaxRate: '23' } : null,
+    ) as never,
     create: jest.fn((_entity: unknown, data: Record<string, unknown>) => {
       // Real MikroORM leaves the UUID PK unassigned until flush — the
       // mock mirrors that so id-before-flush bugs surface in tests.
@@ -276,6 +281,34 @@ describe('bulkCreateItemsCommand', () => {
     // Distinct — A appears twice in the payload but once in the query.
     expect(new Set(where.id?.$in)).toEqual(new Set([ACCOUNT_A, ACCOUNT_B]))
   })
+
+  it('fills the org default VAT rate once for entries without one; explicit rates win (Spec B)', async () => {
+    const env = createEnv()
+    await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [recurringEntry(ACCOUNT_A, 'ref-1'), { ...recurringEntry(ACCOUNT_A, 'ref-2'), taxRate: 8 }],
+      },
+      env.ctx as never,
+    )
+    const created = env.em.create.mock.calls.map(([, data]) => data.taxRate)
+    expect(created).toEqual(['23', '8'])
+    const settingsReads = env.em.findOne.mock.calls.filter(
+      ([entity]) => (entity as { name?: string }).name === 'BillingSettings',
+    )
+    expect(settingsReads).toHaveLength(1)
+  })
+
+  it('does not read settings when every entry carries a rate', async () => {
+    const env = createEnv()
+    await bulkCreateItemsCommand.execute(
+      { tenantId: TENANT, organizationId: ORG, items: [{ ...recurringEntry(ACCOUNT_A, 'ref-1'), taxRate: 0 }] },
+      env.ctx as never,
+    )
+    expect(env.em.findOne).not.toHaveBeenCalled()
+    expect(env.em.create.mock.calls[0][1].taxRate).toBe('0')
+  })
 })
 
 // Suppress unused-import warnings — the entity classes are referenced

package/src/modules/billing/__tests__/commands/memos.test.ts

@@ -0,0 +1,205 @@
+import { createMemoCommand, deleteDraftMemoCommand } from '../../commands/memos'
+import { BillingInvoice, BillingInvoiceLine, BillingSettings } from '../../data/entities'
+import { canCorrect, displaySign, isMemo, isReceivable, seriesFor } from '../../lib/documentTypes'
+import { creditFits, creditHeadroomCents } from '../../lib/memoGuards'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const ORIGINAL = '33333333-3333-4333-8333-333333333333'
+const LINE_A = '44444444-4444-4444-8444-444444444444'
+const LINE_B = '55555555-5555-4555-8555-555555555555'
+const base = { tenantId: TENANT, organizationId: ORG }
+
+type Row = Record<string, unknown>
+
+function original(overrides: Row = {}): Row {
+  return {
+    id: ORIGINAL,
+    ...base,
+    billAccountId: 'acc-1',
+    documentType: 'invoice',
+    status: 'posted',
+    testRun: false,
+    number: 'INV/2026/11/0001',
+    issueDate: new Date('2026-11-14T00:00:00Z'),
+    periodStart: new Date('2026-11-01T00:00:00Z'),
+    periodEnd: new Date('2026-11-30T00:00:00Z'),
+    currencyCode: 'PLN',
+    totalGross: '146.0000',
+    ...overrides,
+  }
+}
+
+const lines: Row[] = [
+  { id: LINE_A, description: 'Internet', quantity: '1.0000', unitPriceNet: '100.0000', taxRate: '23', billingType: 'recurring', servicePeriodStart: null, servicePeriodEnd: null },
+  { id: LINE_B, description: 'Router', quantity: '2.0000', unitPriceNet: '10.0000', taxRate: '8', billingType: 'one_time', servicePeriodStart: null, servicePeriodEnd: null },
+]
+
+function env(opts: { original?: Row | null; corrections?: Array<{ document_type: string; gross: string }>; target?: Row | null } = {}) {
+  const created: Array<{ entity: unknown; data: Row }> = []
+  const executed: string[] = []
+  const em = {
+    findOne: jest.fn(async (entity: unknown) => {
+      if (entity === BillingInvoice) return opts.target !== undefined ? opts.target : opts.original === undefined ? original() : opts.original
+      if (entity === BillingSettings) return { defaultTaxRate: '5' }
+      return null
+    }),
+    find: jest.fn(async (entity: unknown) => (entity === BillingInvoiceLine ? lines : [])),
+    execute: jest.fn(async (sql: string) => {
+      executed.push(sql)
+      if (sql.includes('SUM(total_gross)')) return opts.corrections ?? []
+      return []
+    }),
+    create: jest.fn((entity: unknown, data: Row) => {
+      const row = { id: `new-${created.length + 1}`, ...data }
+      created.push({ entity, data: row })
+      return row
+    }),
+    persist: jest.fn(),
+    flush: jest.fn(async () => undefined),
+    transactional: jest.fn(),
+    fork: jest.fn(),
+  }
+  em.transactional.mockImplementation(async (fn: (tem: unknown) => Promise<unknown>) => fn(em))
+  em.fork.mockReturnValue(em)
+  const ctx = { container: { resolve: jest.fn(() => em) }, auth: { sub: 'u', tenantId: TENANT, orgId: ORG } }
+  return { em, ctx, created, executed }
+}
+
+const memoOf = (e: ReturnType<typeof env>) => e.created.find((c) => c.entity === BillingInvoice)!.data
+const linesOf = (e: ReturnType<typeof env>) => e.created.filter((c) => c.entity === BillingInvoiceLine).map((c) => c.data)
+
+describe('createMemoCommand', () => {
+  it('full credit copies every original line with its own VAT rate and snapshots the original', async () => {
+    const e = env()
+    const result = await createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: 'credit_memo', reason: 'Wrong price' }, e.ctx as never)
+    expect(result.number).toMatch(/^DRAFT-/)
+    expect(memoOf(e)).toMatchObject({
+      documentType: 'credit_memo',
+      status: 'draft',
+      correctsInvoiceId: ORIGINAL,
+      correctsInvoiceNumber: 'INV/2026/11/0001',
+      correctionReason: 'Wrong price',
+      billAccountId: 'acc-1',
+      currencyCode: 'PLN',
+      subtotalNet: '120.0000',
+      taxTotal: '24.6000',
+      totalGross: '144.6000',
+    })
+    expect(linesOf(e).map((l) => [l.correctsLineId, l.taxRate, l.grossAmount])).toEqual([
+      [LINE_A, '23', '123.0000'],
+      [LINE_B, '8', '21.6000'],
+    ])
+  })
+
+  it('partial credit: copied lines keep the original rate even if another is sent; new lines take the org default', async () => {
+    const e = env()
+    await createMemoCommand.execute(
+      {
+        ...base,
+        invoiceId: ORIGINAL,
+        type: 'credit_memo',
+        reason: 'Goodwill',
+        lines: [
+          { correctsLineId: LINE_A, description: 'Internet (3 days)', quantity: 1, unitPriceNet: 10, taxRate: 0 },
+          { description: 'Goodwill', quantity: 1, unitPriceNet: 5 },
+        ],
+      },
+      e.ctx as never,
+    )
+    expect(linesOf(e).map((l) => [l.correctsLineId, l.taxRate, l.netAmount])).toEqual([
+      [LINE_A, '23', '10.0000'],
+      [null, '5', '5.0000'],
+    ])
+  })
+
+  it('debit memo without lines starts empty', async () => {
+    const e = env()
+    await createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: 'debit_memo', reason: 'Missed fee' }, e.ctx as never)
+    expect(memoOf(e)).toMatchObject({ documentType: 'debit_memo', totalGross: '0.0000' })
+    expect(linesOf(e)).toHaveLength(0)
+  })
+
+  it.each([
+    [{ status: 'draft' }, 'credit_memo'],
+    [{ testRun: true }, 'credit_memo'],
+    [{ documentType: 'credit_memo' }, 'credit_memo'],
+    [{ documentType: 'receipt', status: 'paid' }, 'debit_memo'],
+    [{ status: 'credited' }, 'credit_memo'],
+  ])('refuses originals %j for %s', async (overrides, type) => {
+    const e = env({ original: original(overrides) })
+    await expect(
+      createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: type as 'credit_memo', reason: 'x' }, e.ctx as never),
+    ).rejects.toMatchObject({ status: 409, body: expect.objectContaining({ code: 'billing.memo.invalid_original' }) })
+  })
+
+  it('allows a debit memo on a fully credited invoice', async () => {
+    const e = env({ original: original({ status: 'credited' }) })
+    await expect(
+      createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: 'debit_memo', reason: 'Re-bill' }, e.ctx as never),
+    ).resolves.toMatchObject({ documentType: 'debit_memo' })
+  })
+
+  it('requires a reason and rejects lines of another invoice', async () => {
+    const e = env()
+    await expect(createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: 'credit_memo', reason: '  ' }, e.ctx as never)).rejects.toThrow()
+    await expect(
+      createMemoCommand.execute(
+        {
+          ...base,
+          invoiceId: ORIGINAL,
+          type: 'credit_memo',
+          reason: 'x',
+          lines: [{ correctsLineId: '99999999-9999-4999-8999-999999999999', description: 'x', quantity: 1, unitPriceNet: 1 }],
+        },
+        e.ctx as never,
+      ),
+    ).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.memo.invalid_line' }) })
+  })
+
+  it('refuses a credit above what is left to credit (early guard)', async () => {
+    const e = env({ corrections: [{ document_type: 'credit_memo', gross: '100.0000' }] })
+    await expect(
+      createMemoCommand.execute({ ...base, invoiceId: ORIGINAL, type: 'credit_memo', reason: 'Full' }, e.ctx as never),
+    ).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.memo.exceeds_invoice' }) })
+  })
+})
+
+describe('deleteDraftMemoCommand', () => {
+  it('deletes a draft memo with its lines', async () => {
+    const e = env({ target: { id: 'm-1', ...base, status: 'draft', documentType: 'credit_memo' } })
+    await expect(deleteDraftMemoCommand.execute({ ...base, invoiceId: '66666666-6666-4666-8666-666666666666' }, e.ctx as never)).resolves.toEqual({ deleted: true })
+    expect(e.executed.filter((sql) => sql.startsWith('DELETE'))).toHaveLength(2)
+  })
+
+  it('never deletes posted memos or invoice drafts', async () => {
+    for (const target of [
+      { id: 'm-1', ...base, status: 'posted', documentType: 'credit_memo' },
+      { id: 'i-1', ...base, status: 'draft', documentType: 'invoice' },
+    ]) {
+      const e = env({ target })
+      await expect(deleteDraftMemoCommand.execute({ ...base, invoiceId: '66666666-6666-4666-8666-666666666666' }, e.ctx as never)).rejects.toMatchObject({
+        body: expect.objectContaining({ code: 'billing.memo.not_draft' }),
+      })
+    }
+  })
+})
+
+describe('document type helpers and credit guard', () => {
+  it('classifies document types', () => {
+    expect(seriesFor('credit_memo')).toBe('credit_memo')
+    expect(seriesFor('debit_memo')).toBe('invoice')
+    expect(seriesFor('receipt')).toBe('receipt')
+    expect(isReceivable('debit_memo')).toBe(true)
+    expect(isReceivable('credit_memo')).toBe(false)
+    expect(isMemo('credit_memo')).toBe(true)
+    expect(displaySign('credit_memo')).toBe(-1)
+    expect(canCorrect({ documentType: 'invoice', status: 'paid', testRun: false }, 'credit_memo')).toBe(true)
+  })
+
+  it('computes the credit headroom including debit memos', () => {
+    expect(creditHeadroomCents(10000, { creditCents: 3000, debitCents: 2000 })).toBe(9000)
+    expect(creditFits(10000, { creditCents: 3000, debitCents: 2000 }, 9000)).toBe(true)
+    expect(creditFits(10000, { creditCents: 3000, debitCents: 2000 }, 9001)).toBe(false)
+  })
+})

package/src/modules/billing/__tests__/commands/payments.test.ts

@@ -0,0 +1,241 @@
+jest.mock('../../lib/accountLock', () => ({
+  withAccountLock: jest.fn(async (em: unknown, _s: unknown, fn: (tem: unknown) => Promise<unknown>) => fn(em)),
+}))
+jest.mock('../../lib/allocation', () => {
+  const actual = jest.requireActual('../../lib/allocation')
+  return {
+    ...actual,
+    allocate: jest.fn(async () => actual.emptyEffects()),
+    unallocate: jest.fn(async () => actual.emptyEffects()),
+    applyAccountCredit: jest.fn(async () => actual.emptyEffects()),
+  }
+})
+jest.mock('../../lib/topupCapture', () => ({ captureTopup: jest.fn(async () => ({ status: 'captured' })) }))
+jest.mock('../../events', () => ({ emitBillingEvent: jest.fn(async () => undefined) }))
+
+import { BillingAccount, BillingInvoice, BillingPayment, BillingSettings, BillingTopup } from '../../data/entities'
+import { allocate, applyAccountCredit, unallocate } from '../../lib/allocation'
+import { captureTopup } from '../../lib/topupCapture'
+import { emitBillingEvent } from '../../events'
+import {
+  allocatePaymentCommand,
+  assignPaymentCommand,
+  convertToTopupCommand,
+  createPaymentCommand,
+  ignorePaymentCommand,
+  restorePaymentCommand,
+  unallocateCommand,
+  unassignPaymentCommand,
+} from '../../commands/payments'
+import { recordGatewayCapture } from '../../subscribers/payment-captured-to-paid'
+import { applyCreditForAccount } from '../../subscribers/invoice-apply-credit'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const PAY = '33333333-3333-4333-8333-333333333333'
+const ACC = '44444444-4444-4444-8444-444444444444'
+const INV = '55555555-5555-4555-8555-555555555555'
+const ALLOC = '66666666-6666-4666-8666-666666666666'
+const base = { tenantId: TENANT, organizationId: ORG }
+
+type Row = Record<string, unknown>
+
+function env(opts: { payment?: Row | null; account?: Row | null; invoice?: Row | null; allocations?: number; existingByExternalRef?: Row | null } = {}) {
+  const executed: Array<{ sql: string; params: unknown[] }> = []
+  const created: Row[] = []
+  const em = {
+    findOne: jest.fn(async (entity: unknown, where: Row) => {
+      if (entity === BillingPayment) return 'externalRef' in where ? (opts.existingByExternalRef ?? null) : (opts.payment ?? null)
+      if (entity === BillingAccount) return opts.account ?? null
+      if (entity === BillingInvoice) return opts.invoice ?? null
+      if (entity === BillingSettings) return { topupTaxRate: '23' }
+      if (entity === BillingTopup) return null
+      return null
+    }),
+    execute: jest.fn(async (sql: string, params: unknown[] = []) => {
+      executed.push({ sql, params })
+      if (sql.includes('COUNT(*)::int AS n FROM billing_allocations')) return [{ n: opts.allocations ?? 0 }]
+      if (sql.includes('SELECT status, unallocated_amount')) return [{ status: 'matched', unallocated_amount: '10.0000' }]
+      if (sql.includes('SELECT bill_account_id FROM billing_allocations')) return opts.allocations === -1 ? [] : [{ bill_account_id: ACC }]
+      return []
+    }),
+    create: jest.fn((_e: unknown, data: Row) => {
+      const row = { id: `new-${created.length + 1}`, ...data }
+      created.push(row)
+      return row
+    }),
+    persist: jest.fn(),
+    flush: jest.fn(async () => undefined),
+    fork: jest.fn(),
+  }
+  em.fork.mockReturnValue(em)
+  const ctx = { container: { resolve: jest.fn(() => em) }, auth: { sub: 'user-1', tenantId: TENANT, orgId: ORG } }
+  return { em, ctx, executed, created }
+}
+
+const payment = (overrides: Row = {}): Row => ({
+  id: PAY,
+  ...base,
+  amount: '100.0000',
+  unallocatedAmount: '100.0000',
+  currencyCode: 'PLN',
+  status: 'unmatched',
+  billAccountId: null,
+  reference: 'x',
+  ...overrides,
+})
+const account = (overrides: Row = {}): Row => ({
+  id: ACC,
+  ...base,
+  currencyCode: 'PLN',
+  billingMode: 'postpaid',
+  ...overrides,
+})
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('payment commands', () => {
+  it('manual payment with an account is matched and spends its credit', async () => {
+    const e = env({ account: account() })
+    await createPaymentCommand.execute(
+      { ...base, receivedAt: '2026-11-20', amount: 50, currencyCode: 'pln', billAccountId: ACC },
+      e.ctx as never,
+    )
+    expect(e.created[0]).toMatchObject({ status: 'matched', amount: '50.0000', unallocatedAmount: '50.0000', source: 'manual', billAccountId: ACC })
+    expect(applyAccountCredit).toHaveBeenCalledWith(e.em, base, { id: ACC, currencyCode: 'PLN' }, { onlySources: [{ type: 'payment', id: 'new-1' }] })
+    expect(emitBillingEvent).toHaveBeenCalledWith('billing.payment.created', expect.objectContaining({ source: 'manual' }))
+  })
+
+  it('manual payment without an account stays unmatched', async () => {
+    const e = env()
+    await createPaymentCommand.execute({ ...base, receivedAt: '2026-11-20', amount: 50, currencyCode: 'PLN' }, e.ctx as never)
+    expect(e.created[0]).toMatchObject({ status: 'unmatched', matchReason: 'manual' })
+    expect(applyAccountCredit).not.toHaveBeenCalled()
+  })
+
+  it('assigns an unmatched payment and applies it as credit; refuses prepaid / currency / non-unmatched', async () => {
+    const ok = env({ payment: payment(), account: account() })
+    await assignPaymentCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, ok.ctx as never)
+    expect(ok.executed.some((x) => x.sql.includes("status = 'matched'"))).toBe(true)
+    expect(applyAccountCredit).toHaveBeenCalled()
+
+    const prepaid = env({ payment: payment(), account: account({ billingMode: 'prepaid' }) })
+    await expect(assignPaymentCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, prepaid.ctx as never)).rejects.toMatchObject({
+      body: expect.objectContaining({ code: 'billing.payment.prepaid_account' }),
+    })
+    const eur = env({ payment: payment({ currencyCode: 'EUR' }), account: account() })
+    await expect(assignPaymentCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, eur.ctx as never)).rejects.toMatchObject({
+      body: expect.objectContaining({ code: 'billing.payment.currency_mismatch' }),
+    })
+    const done = env({ payment: payment({ status: 'allocated' }), account: account() })
+    await expect(assignPaymentCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, done.ctx as never)).rejects.toMatchObject({ status: 409 })
+  })
+
+  it('unassign requires no allocations', async () => {
+    const busy = env({ payment: payment({ status: 'matched', billAccountId: ACC }), allocations: 1 })
+    await expect(unassignPaymentCommand.execute({ ...base, paymentId: PAY }, busy.ctx as never)).rejects.toMatchObject({
+      body: expect.objectContaining({ code: 'billing.payment.has_allocations' }),
+    })
+    const free = env({ payment: payment({ status: 'matched', billAccountId: ACC }) })
+    await unassignPaymentCommand.execute({ ...base, paymentId: PAY }, free.ctx as never)
+    expect(free.executed.some((x) => x.sql.includes('bill_account_id = NULL'))).toBe(true)
+  })
+
+  it('allocates each requested amount in cents through the allocation service', async () => {
+    const e = env({ payment: payment({ status: 'matched', billAccountId: ACC }) })
+    await allocatePaymentCommand.execute({ ...base, paymentId: PAY, allocations: [{ invoiceId: INV, amount: 12.34 }] }, e.ctx as never)
+    expect(allocate).toHaveBeenCalledWith(e.em, base, {
+      source: { type: 'payment', id: PAY },
+      invoiceId: INV,
+      amountCents: 1234,
+      by: 'user',
+      userId: 'user-1',
+    })
+    const unassigned = env({ payment: payment() })
+    await expect(
+      allocatePaymentCommand.execute({ ...base, paymentId: PAY, allocations: [{ invoiceId: INV, amount: 1 }] }, unassigned.ctx as never),
+    ).rejects.toMatchObject({ body: expect.objectContaining({ code: 'billing.payment.unassigned' }) })
+  })
+
+  it('un-allocates by allocation id (404 when unknown)', async () => {
+    const e = env()
+    await unallocateCommand.execute({ ...base, allocationId: ALLOC }, e.ctx as never)
+    expect(unallocate).toHaveBeenCalledWith(e.em, base, { allocationId: ALLOC, userId: 'user-1' })
+    const missing = env({ allocations: -1 })
+    await expect(unallocateCommand.execute({ ...base, allocationId: ALLOC }, missing.ctx as never)).rejects.toMatchObject({ status: 404 })
+  })
+
+  it('ignores only unallocated payments and restores them to their previous state', async () => {
+    const busy = env({ payment: payment({ status: 'matched', billAccountId: ACC }), allocations: 2 })
+    await expect(ignorePaymentCommand.execute({ ...base, paymentId: PAY }, busy.ctx as never)).rejects.toMatchObject({ status: 409 })
+    const ok = env({ payment: payment() })
+    await ignorePaymentCommand.execute({ ...base, paymentId: PAY }, ok.ctx as never)
+    expect(ok.executed.some((x) => x.sql.includes("status = 'ignored'"))).toBe(true)
+
+    const ignored = env({ payment: payment({ status: 'ignored', billAccountId: ACC }), account: account() })
+    await restorePaymentCommand.execute({ ...base, paymentId: PAY }, ignored.ctx as never)
+    expect(ignored.executed.some((x) => x.params[0] === 'matched')).toBe(true)
+    expect(applyAccountCredit).toHaveBeenCalled()
+  })
+
+  it('converts an unmatched payment of a prepaid account into a captured top-up', async () => {
+    const e = env({ payment: payment(), account: account({ billingMode: 'prepaid' }) })
+    const result = await convertToTopupCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, e.ctx as never)
+    expect(e.created[0]).toMatchObject({ providerKey: 'bank_transfer', paymentId: PAY, sourceRef: `topup-${PAY}`, amount: '100.0000' })
+    expect(captureTopup).toHaveBeenCalledWith(e.em, expect.objectContaining({ taxRate: 23 }))
+    expect(e.executed.some((x) => x.sql.includes("status = 'converted_to_topup'"))).toBe(true)
+    expect(result.topupId).toBe('new-1')
+    expect(emitBillingEvent).toHaveBeenCalledWith('billing.payment.converted_to_topup', expect.anything())
+
+    const postpaid = env({ payment: payment(), account: account() })
+    await expect(convertToTopupCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, postpaid.ctx as never)).rejects.toMatchObject({
+      body: expect.objectContaining({ code: 'billing.payment.not_prepaid' }),
+    })
+    const partly = env({ payment: payment({ unallocatedAmount: '40.0000' }), account: account({ billingMode: 'prepaid' }) })
+    await expect(convertToTopupCommand.execute({ ...base, paymentId: PAY, billAccountId: ACC }, partly.ctx as never)).rejects.toMatchObject({
+      body: expect.objectContaining({ code: 'billing.payment.not_convertible' }),
+    })
+  })
+})
+
+describe('gateway capture subscriber', () => {
+  const invoice = (overrides: Row = {}): Row => ({
+    id: INV,
+    ...base,
+    billAccountId: ACC,
+    documentType: 'invoice',
+    status: 'posted',
+    testRun: false,
+    number: 'INV/2026/11/0001',
+    currencyCode: 'PLN',
+    outstanding: '123.0000',
+    ...overrides,
+  })
+
+  it('records a gateway payment allocated to the invoice', async () => {
+    const e = env({ invoice: invoice() })
+    expect(await recordGatewayCapture(e.em as never, { ...base, paymentId: INV, transactionId: 'tx-1', amount: 123 })).toBe('recorded')
+    expect(e.created[0]).toMatchObject({ source: 'gateway', externalRef: 'tx-1', amount: '123.0000', billAccountId: ACC, status: 'matched' })
+    expect(allocate).toHaveBeenCalledWith(e.em, base, expect.objectContaining({ invoiceId: INV, amountCents: 12300, by: 'gateway' }))
+  })
+
+  it('is idempotent and ignores non-billing payments', async () => {
+    const dup = env({ invoice: invoice(), existingByExternalRef: { id: 'p' } })
+    expect(await recordGatewayCapture(dup.em as never, { ...base, paymentId: INV, transactionId: 'tx-1' })).toBe('duplicate')
+    const foreign = env({ invoice: null })
+    expect(await recordGatewayCapture(foreign.em as never, { ...base, paymentId: INV })).toBe('skipped')
+    expect(await recordGatewayCapture(env().em as never, { paymentId: INV })).toBe('skipped')
+    expect(allocate).not.toHaveBeenCalled()
+  })
+})
+
+describe('credit on post subscriber', () => {
+  it('spends account credit for postpaid accounts only', async () => {
+    const e = env({ account: account() })
+    await applyCreditForAccount(e.em as never, { ...base, billAccountId: ACC })
+    expect(applyAccountCredit).toHaveBeenCalledWith(e.em, base, { id: ACC, currencyCode: 'PLN' })
+    jest.clearAllMocks()
+    await applyCreditForAccount(env({ account: account({ billingMode: 'prepaid' }) }).em as never, { ...base, billAccountId: ACC })
+    expect(applyAccountCredit).not.toHaveBeenCalled()
+  })
+})

package/src/modules/billing/__tests__/commands/runsDelete.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Spec F (F1): deleting test / dry Bill Runs and the shared test-run cleanup.
+ */
+
+jest.mock('../../events', () => ({ emitBillingEvent: jest.fn(async () => undefined) }))
+jest.mock('../../lib/billRunEngine', () => ({ runBillRun: jest.fn() }))
+
+import { emitBillingEvent } from '../../events'
+import { deleteRunCommand, runMode } from '../../commands/runs'
+import { deleteTestRunArtifacts } from '../../lib/testRunCleanup'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const RUN_ID = '33333333-3333-4333-8333-333333333333'
+
+type Executed = { sql: string; params: unknown[] }
+type RunRow = { id: string; dryRun: boolean; testMode: boolean; status: string }
+
+function createEnv(opts: { run: RunRow | null; testInvoiceIds?: string[] }) {
+  const executed: Executed[] = []
+  type RunsMockEm = {
+    findOne: jest.Mock
+    execute: jest.Mock
+    transactional: jest.Mock
+    fork: jest.Mock
+  }
+  const em: RunsMockEm = {
+    findOne: jest.fn(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (!opts.run) return null
+      if (where.tenantId !== TENANT || where.organizationId !== ORG) return null
+      return opts.run
+    }),
+    execute: jest.fn(async (sql: string, params: unknown[] = []) => {
+      executed.push({ sql, params })
+      if (sql.trim().startsWith('SELECT id FROM billing_invoices')) {
+        return (opts.testInvoiceIds ?? []).map((id) => ({ id }))
+      }
+      return []
+    }),
+    transactional: jest.fn(async (fn: (tem: unknown) => Promise<unknown>): Promise<unknown> => fn(em)),
+    fork: jest.fn((): unknown => em),
+  }
+  const ctx = {
+    container: { resolve: jest.fn(() => em) },
+    auth: { tenantId: TENANT, orgId: ORG },
+    selectedOrganizationId: ORG,
+    organizationIds: [ORG],
+    organizationScope: null,
+  }
+  return { em, ctx, executed }
+}
+
+const input = { tenantId: TENANT, organizationId: ORG, billRunId: RUN_ID }
+
+describe('runMode', () => {
+  it('maps the run flags to a mode', () => {
+    expect(runMode({ dryRun: true, testMode: false })).toBe('dry')
+    expect(runMode({ dryRun: false, testMode: true })).toBe('test')
+    expect(runMode({ dryRun: false, testMode: false })).toBe('real')
+  })
+})
+
+describe('deleteRunCommand', () => {
+  beforeEach(() => jest.clearAllMocks())
+
+  it('refuses a real run with 422 and touches nothing', async () => {
+    const env = createEnv({ run: { id: RUN_ID, dryRun: false, testMode: false, status: 'completed' } })
+    await expect(deleteRunCommand.execute(input, env.ctx as never)).rejects.toMatchObject({
+      status: 422,
+      body: { code: 'billing.run.delete_real_forbidden' },
+    })
+    expect(env.executed).toHaveLength(0)
+    expect(emitBillingEvent).not.toHaveBeenCalled()
+  })
+
+  it('refuses a running run with 409', async () => {
+    const env = createEnv({ run: { id: RUN_ID, dryRun: false, testMode: true, status: 'running' } })
+    await expect(deleteRunCommand.execute(input, env.ctx as never)).rejects.toMatchObject({
+      status: 409,
+      body: { code: 'billing.run.running' },
+    })
+  })
+
+  it('returns 404 when the run is missing or belongs to another organization', async () => {
+    const env = createEnv({ run: null })
+    await expect(deleteRunCommand.execute(input, env.ctx as never)).rejects.toMatchObject({ status: 404 })
+  })
+
+  it('deletes a test run: invoices (edits, lines, headers), parent links, outcomes, then the run', async () => {
+    const env = createEnv({
+      run: { id: RUN_ID, dryRun: false, testMode: true, status: 'completed' },
+      testInvoiceIds: ['inv-a', 'inv-b'],
+    })
+    const result = await deleteRunCommand.execute(input, env.ctx as never)
+    expect(result).toEqual({ ok: true, invoicesRemoved: 2 })
+    const writes = env.executed.filter((e) => !e.sql.trim().startsWith('SELECT')).map((e) => e.sql.split(/\s+/).slice(0, 3).join(' '))
+    expect(writes).toEqual([
+      'DELETE FROM billing_draft_invoice_edits',
+      'DELETE FROM billing_invoice_lines',
+      'DELETE FROM billing_invoices',
+      'UPDATE billing_runs SET',
+      'DELETE FROM billing_run_outcomes',
+      'DELETE FROM billing_runs',
+    ])
+    // Every write that filters by scope carries tenant + organization.
+    const scoped = env.executed.filter((e) => e.sql.includes('tenant_id = ?'))
+    for (const row of scoped) {
+      expect(row.params.slice(0, 2)).toEqual([TENANT, ORG])
+    }
+    expect(emitBillingEvent).toHaveBeenCalledWith(
+      'billing.run.deleted',
+      expect.objectContaining({ billRunId: RUN_ID, mode: 'test', invoicesRemoved: 2 }),
+      { persistent: true },
+    )
+  })
+
+  it('deletes a dry run that wrote no invoices', async () => {
+    const env = createEnv({ run: { id: RUN_ID, dryRun: true, testMode: false, status: 'completed' } })
+    const result = await deleteRunCommand.execute(input, env.ctx as never)
+    expect(result.invoicesRemoved).toBe(0)
+    expect(env.executed.some((e) => e.sql.startsWith('DELETE FROM billing_invoices'))).toBe(false)
+    expect(env.executed.some((e) => e.sql.startsWith('DELETE FROM billing_runs'))).toBe(true)
+  })
+})
+
+describe('deleteTestRunArtifacts', () => {
+  it('only targets test invoices (never memos or real documents) and scopes by run', async () => {
+    const env = createEnv({ run: null, testInvoiceIds: [] })
+    await deleteTestRunArtifacts(env.em as never, { tenantId: TENANT, organizationId: ORG, billRunId: RUN_ID })
+    const select = env.executed[0]
+    expect(select.sql).toContain('test_run = true')
+    expect(select.sql).toContain("document_type = 'invoice'")
+    expect(select.sql).toContain('bill_run_id = ?')
+    expect(select.params).toEqual([TENANT, ORG, RUN_ID])
+  })
+
+  it('removes draft-edit audit rows before lines and invoices', async () => {
+    const env = createEnv({ run: null, testInvoiceIds: ['x'] })
+    expect(await deleteTestRunArtifacts(env.em as never, { tenantId: TENANT, organizationId: ORG })).toBe(1)
+    expect(env.executed.slice(1).map((e) => e.sql.split(' ')[2])).toEqual([
+      'billing_draft_invoice_edits',
+      'billing_invoice_lines',
+      'billing_invoices',
+    ])
+  })
+})