@dainamite/billing 0.19.0 → 0.21.0

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

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

package/src/modules/billing/__tests__/lib/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' } })
+  })
+})