@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,101 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { ensureSellerSettings } from './sellerSettings'
+
+/**
+ * TC-BILL-006: Billing-owned invoice ledger (Spec 0)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-standalone-invoice-ledger.md
+ *
+ *   1. A real Bill Run for a fresh account writes a draft numbered `DRAFT-…`.
+ *   2. Posting assigns the series number (default mask `INV/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}`),
+ *      status `posted`, outstanding = gross; a second post → 409.
+ *   3. The document lives in billing only — core sales never lists it.
+ *
+ * Self-contained: its own account + item, scoped run. Posted documents are
+ * immutable by design (no delete), so they stay in the test database.
+ */
+
+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; document_type: string }
+
+async function createBilledAccount(request: APIRequestContext, token: string): Promise<string> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Ledger ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      nextBillDate: '2026-10-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-10-01',
+      description: 'Internet 300',
+      rateJson: { unit_price: 79 },
+    },
+  })
+  expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+  return accountId
+}
+
+async function listInvoices(request: APIRequestContext, token: string, accountId: string): Promise<InvoiceRow[]> {
+  const res = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=false`, { token })
+  expect(res.ok()).toBeTruthy()
+  return ((await res.json()) as { items: InvoiceRow[] }).items
+}
+
+test.describe('TC-BILL-006: billing-owned invoice ledger', () => {
+  let token: string
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+    // Spec B: posting is blocked until the seller details are filled.
+    await ensureSellerSettings(request, token)
+  })
+
+  test('draft → post assigns the series number; the document never appears in core sales', async ({ request }) => {
+    const accountId = await createBilledAccount(request, token)
+
+    const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+      token,
+      data: { mode: 'real', asOfDate: '2026-10-15', scopedAccountIds: [accountId] },
+    })
+    expect(run.ok(), `POST run status was ${run.status()}`).toBeTruthy()
+
+    const [draft] = await listInvoices(request, token, accountId)
+    expect(draft).toMatchObject({ status: 'draft', document_type: 'invoice' })
+    expect(draft.number).toMatch(/^DRAFT-/)
+
+    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 posted = (await post.json()) as { invoiceNumber: string; status: string }
+    expect(posted.status).toBe('posted')
+    expect(posted.invoiceNumber).toMatch(/^INV\/\d{4}\/\d{2}\/\d{4}$/)
+
+    const [after] = await listInvoices(request, token, accountId)
+    expect(after).toMatchObject({ id: draft.id, status: 'posted', number: posted.invoiceNumber })
+    expect(after.outstanding).toBe(after.total_gross)
+
+    const again = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId: draft.id } })
+    expect(again.status()).toBe(409)
+
+    const sales = await apiRequest(request, 'GET', `/api/sales/invoices?search=${encodeURIComponent(posted.invoiceNumber)}`, { token })
+    if (sales.ok()) {
+      const salesItems = ((await sales.json()) as { items?: Array<{ id: string }> }).items ?? []
+      expect(salesItems.some((row) => row.id === draft.id)).toBe(false)
+    }
+  })
+})

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

@@ -0,0 +1,140 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { ensureSellerSettings } from './sellerSettings'
+
+/**
+ * TC-BILL-007: Invoice documents — VAT, due date, PDF (Spec B)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-invoice-documents.md
+ *
+ *   1. Items carry VAT rates (23 % explicit, 0 % explicit) → the draft has
+ *      per-line VAT and totals = Σ lines.
+ *   2. The draft PDF renders (watermarked preview) before posting.
+ *   3. Posting sets due date = issue date + the account's terms (7 days) and
+ *      freezes the PDF; the list exposes due_date / days_overdue.
+ *   4. The account summary counts the posted invoice as open, not overdue.
+ *
+ * Self-contained: own account + items, scoped run. Posted documents are
+ * immutable by design, so they stay in the test database.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type InvoiceRow = {
+  id: string
+  number: string
+  status: string
+  subtotal_net: string
+  tax_total: string
+  total_gross: string
+  issue_date: string | null
+  due_date: string | null
+  days_overdue: number
+}
+
+async function createAccountWithVatItems(request: APIRequestContext, token: string): Promise<string> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `VAT ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `vat-${uniq()}@example.com`,
+      invoiceLanguage: 'pl',
+      nextBillDate: '2026-10-01',
+      paymentTermsDays: 7,
+      invoiceAddress: { line1: 'ul. Kupującego 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
+  for (const [description, unitPrice, taxRate] of [
+    ['Internet 300', 100, 23],
+    ['Usługa zwolniona', 15, 0],
+  ] as const) {
+    const item = await apiRequest(request, 'POST', '/api/billing/items', {
+      token,
+      data: {
+        billAccountId: accountId,
+        type: 'recurring',
+        billStartDate: '2026-10-01',
+        description,
+        rateJson: { unit_price: unitPrice },
+        taxRate,
+      },
+    })
+    expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+  }
+  return accountId
+}
+
+async function listInvoices(request: APIRequestContext, token: string, accountId: string): Promise<InvoiceRow[]> {
+  const res = await apiRequest(request, 'GET', `/api/billing/invoices?billAccountId=${accountId}&testRun=false`, { token })
+  expect(res.ok()).toBeTruthy()
+  return ((await res.json()) as { items: InvoiceRow[] }).items
+}
+
+test.describe('TC-BILL-007: VAT, due date and PDF', () => {
+  let token: string
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+    await ensureSellerSettings(request, token)
+  })
+
+  test('VAT per line, draft PDF preview, due date and frozen PDF at post', async ({ request }) => {
+    const accountId = await createAccountWithVatItems(request, token)
+    const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+      token,
+      data: { mode: 'real', asOfDate: '2026-10-15', scopedAccountIds: [accountId] },
+    })
+    expect(run.ok(), `POST run status was ${run.status()}`).toBeTruthy()
+
+    const [draft] = await listInvoices(request, token, accountId)
+    expect(draft).toMatchObject({ status: 'draft' })
+    // 100 @ 23 % + 15 @ 0 %
+    expect(Number(draft.subtotal_net)).toBeCloseTo(115, 2)
+    expect(Number(draft.tax_total)).toBeCloseTo(23, 2)
+    expect(Number(draft.total_gross)).toBeCloseTo(138, 2)
+
+    const detail = await apiRequest(request, 'GET', `/api/billing/invoices/${draft.id}`, { token })
+    const { lines } = (await detail.json()) as { lines: Array<{ tax_rate: string; tax_amount: string }> }
+    expect(lines.map((l) => Number(l.tax_rate)).sort((a, b) => a - b)).toEqual([0, 23])
+
+    const preview = await apiRequest(request, 'GET', `/api/billing/invoices/${draft.id}/pdf`, { token })
+    expect(preview.status()).toBe(200)
+    expect(preview.headers()['content-type']).toContain('application/pdf')
+    expect((await preview.body()).subarray(0, 4).toString()).toBe('%PDF')
+
+    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 [posted] = await listInvoices(request, token, accountId)
+    expect(posted.status).toBe('posted')
+    const issue = new Date(`${posted.issue_date!.slice(0, 10)}T00:00:00Z`)
+    const due = new Date(`${posted.due_date!.slice(0, 10)}T00:00:00Z`)
+    expect((due.getTime() - issue.getTime()) / 86_400_000).toBe(7)
+    expect(posted.days_overdue).toBe(0)
+
+    const frozen = await apiRequest(request, 'GET', `/api/billing/invoices/${draft.id}/pdf?download=1`, { token })
+    expect(frozen.status()).toBe(200)
+    expect(frozen.headers()['content-disposition']).toContain('attachment')
+
+    const summary = await apiRequest(request, 'GET', `/api/billing/accounts/${accountId}/summary`, { token })
+    expect(summary.ok()).toBeTruthy()
+    const body = (await summary.json()) as { open_amount: string; overdue_count: number }
+    expect(Number(body.open_amount)).toBeCloseTo(138, 2)
+    expect(body.overdue_count).toBe(0)
+
+    const overdueOnly = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/invoices?billAccountId=${accountId}&overdue=true`,
+      { token },
+    )
+    expect(((await overdueOnly.json()) as { items: unknown[] }).items).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,108 @@
+import { readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { ensureSellerSettings } from './sellerSettings'
+
+/**
+ * TC-BILL-008: Sending invoices by email (Spec B)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-invoice-documents.md
+ *
+ *   1. A draft cannot be sent (409 billing.invoice.not_posted).
+ *   2. A posted invoice is sent through the platform `sendEmail()`; with
+ *      `OM_TEST_MODE` the message is captured (recipient + subject) and the
+ *      attempt is logged in `metadata.deliveries`.
+ *   3. A placeholder address (`@invalid.local`) is refused with 422.
+ *
+ * Delivery status may be `sent` or `failed` depending on whether the test
+ * instance has an outbound transport; either way exactly one attempt is
+ * logged. The capture-file assertion runs only when the server shares this
+ * machine's temp dir (local runs).
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+const capturePath = process.env.OM_TEST_EMAIL_CAPTURE_PATH?.trim() || join(tmpdir(), 'open-mercato-email-capture.jsonl')
+
+async function postedInvoiceFor(request: APIRequestContext, token: string, invoiceEmail: string) {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Send ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail,
+      nextBillDate: '2026-10-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-10-01', description: 'Plan', rateJson: { unit_price: 50 } },
+  })
+  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: Array<{ id: string }> }).items
+  return { accountId, invoiceId: draft.id }
+}
+
+test.describe('TC-BILL-008: send invoice by email', () => {
+  let token: string
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+    await ensureSellerSettings(request, token)
+  })
+
+  test('draft refused; posted invoice sent and logged', async ({ request }) => {
+    const email = `send-${uniq()}@example.com`
+    const { invoiceId } = await postedInvoiceFor(request, token, email)
+
+    const early = await apiRequest(request, 'POST', `/api/billing/invoices/${invoiceId}/send`, { token, data: {} })
+    expect(early.status()).toBe(409)
+
+    const post = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId } })
+    expect(post.ok()).toBeTruthy()
+    const { invoiceNumber } = (await post.json()) as { invoiceNumber: string }
+
+    const send = await apiRequest(request, 'POST', `/api/billing/invoices/${invoiceId}/send`, { token, data: {} })
+    expect(send.status()).toBe(200)
+    const result = (await send.json()) as { to: string; status: 'sent' | 'failed' }
+    expect(result.to).toBe(email)
+    expect(['sent', 'failed']).toContain(result.status)
+
+    const detail = await apiRequest(request, 'GET', `/api/billing/invoices/${invoiceId}`, { token })
+    const { invoice } = (await detail.json()) as {
+      invoice: { metadata: { deliveries?: Array<{ to: string; status: string; trigger: string }> } }
+    }
+    expect(invoice.metadata.deliveries).toEqual([expect.objectContaining({ to: email, trigger: 'manual', status: result.status })])
+
+    if (existsSync(capturePath)) {
+      const captured = readFileSync(capturePath, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as { to: string; subject: string })
+      expect(captured.some((m) => m.to === email && m.subject.includes(invoiceNumber))).toBe(true)
+    }
+  })
+
+  test('placeholder address is refused with 422', async ({ request }) => {
+    const { invoiceId } = await postedInvoiceFor(request, token, `shell-${uniq()}@invalid.local`)
+    const post = await apiRequest(request, 'POST', '/api/billing/invoices/post', { token, data: { invoiceId } })
+    expect(post.ok()).toBeTruthy()
+    const send = await apiRequest(request, 'POST', `/api/billing/invoices/${invoiceId}/send`, { token, data: {} })
+    expect(send.status()).toBe(422)
+    expect(((await send.json()) as { code: string }).code).toBe('billing.invoice.email_invalid')
+  })
+})

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'])
+  })
+})