@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/__integration__/TC-BILL-009.spec.ts

@@ -0,0 +1,113 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { ensureSellerSettings } from './sellerSettings'
+
+/**
+ * TC-BILL-009: Payments — CSV import, auto-matching, allocation, credit (Spec C)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-payments.md
+ *
+ *   1. Two posted invoices on a fresh account (monthly, two bill dates).
+ *   2. Upload a CSV: half of invoice 1, invoice 2 + 30 overpayment, a junk
+ *      line, a EUR line → counts; invoice 1 partially paid, invoice 2 paid,
+ *      the 30 overpayment applied to invoice 1 as credit.
+ *   3. Account summary shows the remaining open amount; re-upload = duplicates.
+ *   4. The junk payment is assigned to the account manually → credit applied.
+ *
+ * Self-contained (own account + items). Uses JSON upload (`{ fileName, content }`).
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type InvoiceRow = { id: string; number: string; status: string; total_gross: string; outstanding: string; bill_date: string | null }
+
+async function postedInvoices(request: APIRequestContext, token: string): Promise<{ accountId: string; invoices: InvoiceRow[] }> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Payments ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `pay-${uniq()}@example.com`,
+      nextBillDate: '2026-09-01',
+      invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(account.ok(), `POST account status was ${account.status()}`).toBeTruthy()
+  const accountId = ((await account.json()) as { id: string }).id
+  const item = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: { billAccountId: accountId, type: 'recurring', billStartDate: '2026-09-01', description: 'Plan', rateJson: { unit_price: 100 }, taxRate: 0 },
+  })
+  expect(item.ok()).toBeTruthy()
+  // Catch-up: as of 2026-10-15 → bill dates 2026-09-01 and 2026-10-01 → two drafts.
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+    token,
+    data: { mode: 'real', asOfDate: '2026-10-15', scopedAccountIds: [accountId] },
+  })
+  expect(run.ok()).toBeTruthy()
+  const list = async () =>
+    ((await (await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=false`, { token })).json()) as {
+      items: InvoiceRow[]
+    }).items.sort((a, b) => String(a.bill_date).localeCompare(String(b.bill_date)))
+  for (const draft of await list()) {
+    const post = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId: draft.id } })
+    expect(post.ok(), `POST post status was ${post.status()}`).toBeTruthy()
+  }
+  const invoices = await list()
+  expect(invoices).toHaveLength(2)
+  return { accountId, invoices }
+}
+
+test.describe('TC-BILL-009: payments import and allocation', () => {
+  let token: string
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+    await ensureSellerSettings(request, token)
+  })
+
+  test('CSV upload allocates, applies credit, detects duplicates; manual assign applies credit', async ({ request }) => {
+    const { accountId, invoices } = await postedInvoices(request, token)
+    const [first, second] = invoices
+    const junkRef = `misc ${uniq()}`
+    const content = [
+      'date,amount,currency,reference,payer_name,payer_account',
+      `2026-11-20,50.00,PLN,"Part of ${first.number}",QA,`,
+      `2026-11-20,130.00,PLN,"${second.number} with extra",QA,`,
+      `2026-11-21,20.00,PLN,${junkRef},Someone,`,
+      `2026-11-21,10.00,EUR,${first.number},QA,`,
+    ].join('\n')
+
+    const upload = await apiRequest(request, 'POST', '/api/billing/payments/import', { token, data: { fileName: 'qa.csv', content } })
+    expect(upload.ok(), `import status was ${upload.status()}`).toBeTruthy()
+    const summary = (await upload.json()) as { importId: string; counts: Record<string, number> }
+    expect(summary.counts).toMatchObject({ allocated: 2, unmatched: 2, duplicate: 0, rejected: 0 })
+
+    const detail = async (id: string) =>
+      ((await (await apiRequest(request, 'GET', `/api/billing/invoices/${id}`, { token })).json()) as { invoice: InvoiceRow }).invoice
+    // 50 + 30 credit from the overpayment → invoice 1: 80 of 100 paid.
+    expect(await detail(first.id)).toMatchObject({ status: 'partially_paid' })
+    expect(Number((await detail(first.id)).outstanding)).toBeCloseTo(20, 2)
+    expect(await detail(second.id)).toMatchObject({ status: 'paid' })
+
+    const again = await apiRequest(request, 'POST', '/api/billing/payments/import', { token, data: { fileName: 'qa.csv', content } })
+    expect(((await again.json()) as { counts: Record<string, number> }).counts).toMatchObject({ duplicate: 4, allocated: 0 })
+
+    const junk = ((await (await apiRequest(request, 'GET', `/api/billing/payments?search=${encodeURIComponent(junkRef)}`, { token })).json()) as {
+      items: Array<{ id: string; status: string }>
+    }).items[0]
+    expect(junk.status).toBe('unmatched')
+    const assign = await apiRequest(request, 'POST', '/api/billing/payments/assign', { token, data: { paymentId: junk.id, billAccountId: accountId } })
+    expect(assign.ok(), `assign status was ${assign.status()}`).toBeTruthy()
+    expect(await detail(first.id)).toMatchObject({ status: 'paid' })
+
+    const summaryRes = await apiRequest(request, 'GET', `/api/billing/accounts/${accountId}/summary`, { token })
+    const ar = (await summaryRes.json()) as { open_amount: string; credit_amount: string }
+    expect(Number(ar.open_amount)).toBeCloseTo(0, 2)
+    expect(Number(ar.credit_amount)).toBeCloseTo(0, 2)
+  })
+})

package/src/modules/billing/__integration__/TC-BILL-010.spec.ts

@@ -0,0 +1,118 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { ensureSellerSettings } from './sellerSettings'
+
+/**
+ * TC-BILL-010: Credit and debit memos (Spec D)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-credit-debit-memos.md
+ *
+ *   1. Post an invoice (100 net, 0 % VAT for simple maths).
+ *   2. Partial credit memo (30) → draft `DRAFT-…` → post → `CN/…` number,
+ *      original partially paid with 70 outstanding, memo settled.
+ *   3. A second credit of 80 is refused at creation (exceeds 100 − 30).
+ *   4. Debit memo (+15) → post → invoice-series number, own due date and
+ *      outstanding; the original lists both corrections.
+ *
+ * Self-contained (own account + item). Posted documents stay (no void).
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type Doc = { id: string; number: string; status: string; outstanding: string; total_gross: string; due_date: string | null }
+
+async function postedInvoice(request: APIRequestContext, token: string): Promise<{ invoice: Doc; lineId: string }> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Memos ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `memo-${uniq()}@example.com`,
+      nextBillDate: '2026-10-01',
+      invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(account.ok()).toBeTruthy()
+  const accountId = ((await account.json()) as { id: string }).id
+  const item = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: { billAccountId: accountId, type: 'recurring', billStartDate: '2026-10-01', description: 'Plan', rateJson: { unit_price: 100 }, taxRate: 0 },
+  })
+  expect(item.ok()).toBeTruthy()
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', { token, data: { mode: 'real', asOfDate: '2026-10-15', scopedAccountIds: [accountId] } })
+  expect(run.ok()).toBeTruthy()
+  const list = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=false`, { token })
+  const [draft] = ((await list.json()) as { items: Doc[] }).items
+  const post = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId: draft.id } })
+  expect(post.ok()).toBeTruthy()
+  const detail = (await (await apiRequest(request, 'GET', `/api/billing/invoices/${draft.id}`, { token })).json()) as {
+    invoice: Doc
+    lines: Array<{ id: string }>
+  }
+  return { invoice: detail.invoice, lineId: detail.lines[0].id }
+}
+
+async function getDoc(request: APIRequestContext, token: string, id: string) {
+  return (await (await apiRequest(request, 'GET', `/api/billing/invoices/${id}`, { token })).json()) as {
+    invoice: Doc
+    corrections: Array<{ id: string; document_type: string }>
+  }
+}
+
+test.describe('TC-BILL-010: credit and debit memos', () => {
+  let token: string
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+    await ensureSellerSettings(request, token)
+  })
+
+  test('credit memo settles the original; over-credit refused; debit memo is payable', async ({ request }) => {
+    const { invoice, lineId } = await postedInvoice(request, token)
+
+    const credit = await apiRequest(request, 'POST', `/api/billing/invoices/${invoice.id}/memos`, {
+      token,
+      data: { type: 'credit_memo', reason: 'Goodwill', lines: [{ correctsLineId: lineId, description: 'Plan (part)', quantity: 1, unitPriceNet: 30 }] },
+    })
+    expect(credit.ok(), `create memo status ${credit.status()}`).toBeTruthy()
+    const { memoId, number } = (await credit.json()) as { memoId: string; number: string }
+    expect(number).toMatch(/^DRAFT-/)
+
+    const postMemo = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId: memoId } })
+    expect(postMemo.ok(), `post memo status ${postMemo.status()}`).toBeTruthy()
+    expect(((await postMemo.json()) as { invoiceNumber: string }).invoiceNumber).toMatch(/^CN\//)
+
+    const afterCredit = await getDoc(request, token, invoice.id)
+    expect(afterCredit.invoice.status).toBe('partially_paid')
+    expect(Number(afterCredit.invoice.outstanding)).toBeCloseTo(70, 2)
+    expect((await getDoc(request, token, memoId)).invoice).toMatchObject({ status: 'paid' })
+
+    const tooMuch = await apiRequest(request, 'POST', `/api/billing/invoices/${invoice.id}/memos`, {
+      token,
+      data: { type: 'credit_memo', reason: 'Too much', lines: [{ correctsLineId: lineId, description: 'Plan', quantity: 1, unitPriceNet: 80 }] },
+    })
+    expect(tooMuch.status()).toBe(409)
+    expect(((await tooMuch.json()) as { code: string }).code).toBe('billing.memo.exceeds_invoice')
+
+    const debit = await apiRequest(request, 'POST', `/api/billing/invoices/${invoice.id}/memos`, {
+      token,
+      data: { type: 'debit_memo', reason: 'Missed fee', lines: [{ description: 'Installation', quantity: 1, unitPriceNet: 15, taxRate: 0 }] },
+    })
+    expect(debit.ok()).toBeTruthy()
+    const debitId = ((await debit.json()) as { memoId: string }).memoId
+    const postDebit = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId: debitId } })
+    expect(postDebit.ok()).toBeTruthy()
+    expect(((await postDebit.json()) as { invoiceNumber: string }).invoiceNumber).toMatch(/^INV\//)
+    const debitDoc = (await getDoc(request, token, debitId)).invoice
+    expect(debitDoc.status).toBe('posted')
+    expect(debitDoc.due_date).toBeTruthy()
+    expect(Number(debitDoc.outstanding)).toBeCloseTo(15, 2)
+
+    const corrections = (await getDoc(request, token, invoice.id)).corrections.map((c) => c.document_type).sort()
+    expect(corrections).toEqual(['credit_memo', 'debit_memo'])
+  })
+})

package/src/modules/billing/__integration__/TC-BILL-011.spec.ts

@@ -0,0 +1,142 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-011: Prepaid period close — catch-up, charge timing, tax point (Spec F)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-15-billing-operator-feedback.md (F4, F4b, F5)
+ *
+ * The operator's report (F4), against the real database: a prepaid account
+ * with next bill date 2026-11-14, a 99 setup fee and a 49 monthly plan in
+ * advance. ONE real run as of 2026-12-14 must close BOTH bill dates:
+ *   - Nov 14: setup fee + plan for Nov 14 – Dec 13,
+ *   - Dec 14: plan for Dec 14 – Jan 13,
+ * and leave next_bill_date = 2027-01-14. Then, with the tax point switched to
+ * `consumption`, a 10 net @ 23 % plan debits 12.30.
+ * Self-contained: own accounts (soft-deleted after); the tax point is
+ * restored to `topup` in a finally block. Serial — the tax point is org-wide.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type Cycle = { bill_date: string; status: string; total_debit?: string }
+type Txn = { type: string; amount: string; source_ref: string | null }
+
+async function createPrepaidAccount(request: APIRequestContext, token: string, nextBillDate: string): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Prepaid ${uniq()}`,
+      currencyCode: 'EUR',
+      billCycle: 'monthly',
+      billCycleAnchor: '14',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      invoiceLanguage: 'en',
+      nextBillDate,
+      billingMode: 'prepaid',
+      invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(res.ok(), `POST account status was ${res.status()}`).toBeTruthy()
+  return ((await res.json()) as { id: string }).id
+}
+
+async function createItem(request: APIRequestContext, token: string, data: Record<string, unknown>): Promise<void> {
+  const res = await apiRequest(request, 'POST', '/api/billing/items', { token, data })
+  expect(res.ok(), `POST item status was ${res.status()}`).toBeTruthy()
+}
+
+async function realRun(request: APIRequestContext, token: string, accountId: string, asOfDate: string): Promise<Cycle[]> {
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+    token,
+    data: { mode: 'real', asOfDate, scopedAccountIds: [accountId] },
+  })
+  expect(run.ok(), `POST run status was ${run.status()}`).toBeTruthy()
+  const { billRunId } = (await run.json()) as { billRunId: string }
+  const outcomes = await apiRequest(request, 'GET', `/api/billing/run-outcomes?billRunId=${billRunId}`, { token })
+  const body = (await outcomes.json()) as { items: Array<{ bill_account_id: string; cycles: Cycle[] | null }> }
+  return body.items.find((row) => row.bill_account_id === accountId)?.cycles ?? []
+}
+
+async function charges(request: APIRequestContext, token: string, accountId: string): Promise<Txn[]> {
+  const res = await apiRequest(request, 'GET', `/api/billing/transactions?billAccountId=${accountId}&pageSize=50`, { token })
+  const rows = ((await res.json()) as { items: Txn[] }).items
+  return rows.filter((row) => row.type === 'recurring' || row.type === 'one_time')
+}
+
+async function nextBillDate(request: APIRequestContext, token: string, accountId: string): Promise<string> {
+  const res = await apiRequest(request, 'GET', `/api/billing/accounts?id=${accountId}&pageSize=1`, { token })
+  return ((await res.json()) as { items: Array<{ next_bill_date: string }> }).items[0].next_bill_date.slice(0, 10)
+}
+
+test.describe.serial('TC-BILL-011: prepaid period close (Spec F)', () => {
+  let token: string
+  const accounts: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterAll(async ({ request }) => {
+    for (const id of accounts) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id } })
+    }
+  })
+
+  test('one real run closes every due bill date, in advance (the F4 report)', async ({ request }) => {
+    const accountId = await createPrepaidAccount(request, token, '2026-11-14')
+    accounts.push(accountId)
+    await createItem(request, token, {
+      billAccountId: accountId,
+      type: 'one_time',
+      billStartDate: '2026-11-14',
+      description: 'Setup fee',
+      rateJson: { amount: 99 },
+    })
+    await createItem(request, token, {
+      billAccountId: accountId,
+      type: 'recurring',
+      billStartDate: '2026-11-14',
+      description: 'Plan',
+      rateJson: { unit_price: 49 },
+      chargeTiming: 'in_advance',
+    })
+
+    const cycles = await realRun(request, token, accountId, '2026-12-14')
+    expect(cycles.map((c) => [c.bill_date, c.status, c.total_debit])).toEqual([
+      ['2026-11-14', 'charged', '148.0000'],
+      ['2026-12-14', 'charged', '49.0000'],
+    ])
+    expect(await nextBillDate(request, token, accountId)).toBe('2027-01-14')
+    const refs = (await charges(request, token, accountId)).map((t) => t.source_ref ?? '')
+    expect(refs).toHaveLength(3)
+    expect(refs.filter((ref) => ref.startsWith('one_time-'))).toHaveLength(1)
+    expect(refs.some((ref) => ref.endsWith('-charge-2026-11-14-2026-12-13'))).toBe(true)
+    expect(refs.some((ref) => ref.endsWith('-charge-2026-12-14-2027-01-13'))).toBe(true)
+  })
+
+  test('tax at billing: a 10 net @ 23 % plan debits 12.30', async ({ request }) => {
+    const set = (prepaidTaxPoint: 'topup' | 'consumption') =>
+      apiRequest(request, 'PUT', '/api/billing/settings', { token, data: { prepaidTaxPoint } })
+    try {
+      expect((await set('consumption')).ok()).toBeTruthy()
+      const accountId = await createPrepaidAccount(request, token, '2026-11-14')
+      accounts.push(accountId)
+      await createItem(request, token, {
+        billAccountId: accountId,
+        type: 'recurring',
+        billStartDate: '2026-11-14',
+        description: 'Plan (VAT at billing)',
+        rateJson: { unit_price: 10 },
+        taxRate: 23,
+        chargeTiming: 'in_advance',
+      })
+      await realRun(request, token, accountId, '2026-11-14')
+      expect((await charges(request, token, accountId)).map((t) => t.amount)).toEqual(['-12.3000'])
+    } finally {
+      await set('topup')
+    }
+  })
+})

package/src/modules/billing/__integration__/TC-BILL-012.spec.ts

@@ -0,0 +1,115 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-012: Delete test / dry Bill Runs (Spec F, F1)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-15-billing-operator-feedback.md (F-D1)
+ *
+ *   - deleting a test run removes the run, its outcomes and its test invoices;
+ *   - a dry run deletes cleanly (no invoices);
+ *   - a real run is refused with 422 `billing.run.delete_real_forbidden`;
+ *   - the `mode` list filter narrows runs.
+ * Self-contained: own account (soft-deleted after). The real run is scoped to
+ * an account with nothing due, so it writes no documents.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+async function createAccount(request: APIRequestContext, token: string, nextBillDate: string): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Run delete ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      invoiceLanguage: 'en',
+      nextBillDate,
+      invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(res.ok(), `POST account status was ${res.status()}`).toBeTruthy()
+  const accountId = ((await res.json()) as { id: string }).id
+  const item = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: { billAccountId: accountId, type: 'recurring', billStartDate: nextBillDate, description: 'Plan', rateJson: { unit_price: 100 } },
+  })
+  expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+  return accountId
+}
+
+async function trigger(
+  request: APIRequestContext,
+  token: string,
+  accountId: string,
+  mode: 'real' | 'test' | 'dry',
+  asOfDate: string,
+): Promise<string> {
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+    token,
+    data: { mode, asOfDate, scopedAccountIds: [accountId] },
+  })
+  expect(run.ok(), `POST run (${mode}) status was ${run.status()}`).toBeTruthy()
+  return ((await run.json()) as { billRunId: string }).billRunId
+}
+
+test.describe('TC-BILL-012: delete test / dry Bill Runs (Spec F)', () => {
+  let token: string
+  const accounts: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterAll(async ({ request }) => {
+    for (const id of accounts) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id } })
+    }
+  })
+
+  test('a test run is deleted with its test invoices and outcomes', async ({ request }) => {
+    const accountId = await createAccount(request, token, '2026-08-01')
+    accounts.push(accountId)
+    const runId = await trigger(request, token, accountId, 'test', '2026-09-15')
+
+    const before = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=true`, { token })
+    expect(((await before.json()) as { items: unknown[] }).items.length).toBe(2)
+
+    const filtered = await apiRequest(request, 'GET', `/api/billing/runs?mode=test&id=${runId}`, { token })
+    expect(((await filtered.json()) as { items: unknown[] }).items).toHaveLength(1)
+
+    const del = await apiRequest(request, 'DELETE', `/api/billing/runs/${runId}`, { token })
+    expect(del.status()).toBe(200)
+    expect(await del.json()).toEqual({ ok: true, invoicesRemoved: 2 })
+
+    const after = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=true`, { token })
+    expect(((await after.json()) as { items: unknown[] }).items).toHaveLength(0)
+    const run = await apiRequest(request, 'GET', `/api/billing/runs?id=${runId}`, { token })
+    expect(((await run.json()) as { items: unknown[] }).items).toHaveLength(0)
+    const outcomes = await apiRequest(request, 'GET', `/api/billing/run-outcomes?billRunId=${runId}`, { token })
+    expect(((await outcomes.json()) as { items: unknown[] }).items).toHaveLength(0)
+  })
+
+  test('a dry run deletes cleanly', async ({ request }) => {
+    const accountId = await createAccount(request, token, '2026-08-01')
+    accounts.push(accountId)
+    const runId = await trigger(request, token, accountId, 'dry', '2026-08-15')
+    const del = await apiRequest(request, 'DELETE', `/api/billing/runs/${runId}`, { token })
+    expect(del.status()).toBe(200)
+    expect(((await del.json()) as { invoicesRemoved: number }).invoicesRemoved).toBe(0)
+  })
+
+  test('a real run is never deleted', async ({ request }) => {
+    // Nothing due up to the as-of date → the real run writes no documents.
+    const accountId = await createAccount(request, token, '2030-01-01')
+    accounts.push(accountId)
+    const runId = await trigger(request, token, accountId, 'real', '2026-08-15')
+    const del = await apiRequest(request, 'DELETE', `/api/billing/runs/${runId}`, { token })
+    expect(del.status()).toBe(422)
+    expect(((await del.json()) as { code: string }).code).toBe('billing.run.delete_real_forbidden')
+  })
+})

package/src/modules/billing/__integration__/TC-BILL-013.spec.ts

@@ -0,0 +1,118 @@
+import { test, expect } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-013: Gross-basis item price reaches the invoice exactly (Spec F, F3)
+ * Category: BILL — API
+ * Priority: Medium
+ * Spec: .ai/specs/2026-11-15-billing-operator-feedback.md (F-D2)
+ *
+ * A recurring item entered as 49.99 GROSS at 23 % VAT: the test draft line
+ * carries gross 49.99 (net 40.64 + VAT 9.35) — a value net-only storage
+ * could not reproduce. The item API echoes `price_basis`. A gross basis on a
+ * tiered usage rate is refused (422).
+ * Self-contained: own account (soft-deleted after), test drafts wiped.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+test.describe('TC-BILL-013: gross price basis (Spec F)', () => {
+  let token: string
+  let accountId: string | null = null
+  let runId: string | null = null
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    if (runId) {
+      await apiRequest(request, 'DELETE', `/api/billing/runs/${runId}`, { token })
+      runId = null
+    }
+    if (accountId) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id: accountId } })
+      accountId = null
+    }
+  })
+
+  test('the typed gross is the invoice gross', async ({ request }) => {
+    const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: {
+        customerId: `cust-${uniq()}`,
+        name: `Gross ${uniq()}`,
+        currencyCode: 'PLN',
+        billCycle: 'monthly',
+        billCycleAnchor: '1',
+        invoiceEmail: `inv-${uniq()}@example.com`,
+        invoiceLanguage: 'pl',
+        nextBillDate: '2026-11-01',
+        invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+      },
+    })
+    expect(account.ok()).toBeTruthy()
+    accountId = ((await account.json()) as { id: string }).id
+
+    const item = await apiRequest(request, 'POST', '/api/billing/items', {
+      token,
+      data: {
+        billAccountId: accountId,
+        type: 'recurring',
+        billStartDate: '2026-11-01',
+        description: 'Internet (brutto)',
+        rateJson: { unit_price: 49.99 },
+        taxRate: 23,
+        priceBasis: 'gross',
+      },
+    })
+    expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+    const items = await apiRequest(request, 'GET', `/api/billing/items?billAccountId=${accountId}`, { token })
+    expect(((await items.json()) as { items: Array<{ price_basis: string }> }).items[0].price_basis).toBe('gross')
+
+    const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+      token,
+      data: { mode: 'test', asOfDate: '2026-11-01', scopedAccountIds: [accountId] },
+    })
+    expect(run.ok()).toBeTruthy()
+    runId = ((await run.json()) as { billRunId: string }).billRunId
+
+    const list = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=true`, { token })
+    const invoiceId = ((await list.json()) as { items: Array<{ id: string }> }).items[0].id
+    const detail = await apiRequest(request, 'GET', `/api/billing/invoices/${invoiceId}`, { token })
+    const body = (await detail.json()) as { lines: Array<{ net_amount: string; tax_amount: string; gross_amount: string }> }
+    expect(body.lines.map((l) => [Number(l.net_amount), Number(l.tax_amount), Number(l.gross_amount)])).toEqual([[40.64, 9.35, 49.99]])
+  })
+
+  test('a gross basis on a tiered usage rate is refused', async ({ request }) => {
+    const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: {
+        customerId: `cust-${uniq()}`,
+        name: `Tiered ${uniq()}`,
+        currencyCode: 'PLN',
+        billCycle: 'monthly',
+        billCycleAnchor: '1',
+        invoiceEmail: `inv-${uniq()}@example.com`,
+        invoiceLanguage: 'en',
+        nextBillDate: '2026-11-01',
+        invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+      },
+    })
+    accountId = ((await account.json()) as { id: string }).id
+    const item = await apiRequest(request, 'POST', '/api/billing/items', {
+      token,
+      data: {
+        billAccountId: accountId,
+        type: 'usage',
+        uomCode: 'gb',
+        billStartDate: '2026-11-01',
+        description: 'Data',
+        priceBasis: 'gross',
+        rateJson: { model: 'volume', tiers: [{ up_to: null, unit_price: 1 }] },
+      },
+    })
+    expect(item.status()).toBeGreaterThanOrEqual(400)
+    expect(item.status()).toBeLessThan(500)
+  })
+})

package/src/modules/billing/__integration__/sellerSettings.ts

@@ -0,0 +1,24 @@
+import { expect, type APIRequestContext } from '@playwright/test'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * Spec B: posting needs the seller details (legal name, address, tax id,
+ * IBAN). Integration tests fill them for the test organization before
+ * posting. Idempotent — a PUT of the same values.
+ */
+export async function ensureSellerSettings(request: APIRequestContext, token: string): Promise<void> {
+  const res = await apiRequest(request, 'PUT', '/api/billing/settings', {
+    token,
+    data: {
+      legalName: 'QA Seller sp. z o.o.',
+      sellerAddress: { line1: 'ul. Testowa 10', city: 'Kraków', postal_code: '30-001', country: 'PL' },
+      taxId: 'PL1234563218',
+      bankName: 'QA Bank',
+      iban: 'PL61109010140000071219812874',
+      bic: 'WBKPPLPP',
+      defaultPaymentTermsDays: 14,
+      defaultTaxRate: 23,
+    },
+  })
+  expect(res.ok(), `PUT settings status was ${res.status()}`).toBeTruthy()
+}