@dainamite/billing 0.19.0 → 0.21.0

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

@@ -0,0 +1,170 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import {
+  createPersonFixture,
+  deleteEntityIfExists,
+} from '@open-mercato/core/helpers/integration/crmFixtures'
+
+/**
+ * TC-BILL-004: B2C billing accounts, invoice-language picklist, return-to-account navigation
+ * Category: BILL — API + UI
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-account-workspace.md (Phase 1, D21–D23)
+ *
+ * Self-contained: creates its own person, account and item; removes them
+ * in teardown. Avoids `GET /api/billing/accounts?id=` (known CI flake, see
+ * TC-BILL-001) — reads back through the `customerKind` + `search` filters.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+function accountPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    customerId: `cust-${uniq()}`,
+    name: `B2C Account ${uniq()}`,
+    currencyCode: 'PLN',
+    billCycle: 'monthly',
+    billCycleAnchor: '1',
+    invoiceEmail: `inv-${uniq()}@example.com`,
+    invoiceLanguage: 'pl',
+    nextBillDate: '2026-12-01',
+    invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    ...overrides,
+  }
+}
+
+async function createAccount(
+  request: APIRequestContext,
+  token: string,
+  data: Record<string, unknown>,
+): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/accounts', { token, data })
+  expect(res.ok(), `POST /api/billing/accounts status was ${res.status()}`).toBeTruthy()
+  const body = (await res.json()) as { id?: string }
+  expect(body.id).toBeTruthy()
+  return body.id as string
+}
+
+async function createItem(request: APIRequestContext, token: string, billAccountId: string): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: {
+      billAccountId,
+      type: 'recurring',
+      billStartDate: '2026-12-01',
+      description: `Internet 300 ${uniq()}`,
+      rateJson: { unit_price: 79 },
+    },
+  })
+  expect(res.ok(), `POST /api/billing/items status was ${res.status()}`).toBeTruthy()
+  return ((await res.json()) as { id: string }).id
+}
+
+test.describe('TC-BILL-004: B2C accounts + navigation', () => {
+  let token: string
+  const accountIds: string[] = []
+  const itemIds: string[] = []
+  const personIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (itemIds.length) {
+      await apiRequest(request, 'DELETE', '/api/billing/items', { token, data: { id: itemIds.pop() } })
+    }
+    while (accountIds.length) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id: accountIds.pop() } })
+    }
+    while (personIds.length) {
+      await deleteEntityIfExists(request, token, '/api/customers/people', personIds.pop() ?? null)
+    }
+  })
+
+  test('creates a person (B2C) account and filters by customer kind', async ({ request }) => {
+    const suffix = uniq()
+    const personId = await createPersonFixture(request, token, {
+      firstName: 'Jan',
+      lastName: `Kowalski ${suffix}`,
+      displayName: `Jan Kowalski ${suffix}`,
+      primaryEmail: `jan-${suffix}@example.com`,
+    })
+    personIds.push(personId)
+    const name = `B2C ${suffix}`
+    accountIds.push(
+      await createAccount(request, token, accountPayload({ customerId: personId, customerKind: 'person', name })),
+    )
+
+    const persons = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=person&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const personRows = ((await persons.json()) as { items: Array<{ name: string; customer_kind: string }> }).items
+    expect(personRows.find((row) => row.name === name)?.customer_kind).toBe('person')
+
+    const companies = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=company&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const companyRows = ((await companies.json()) as { items: Array<{ name: string }> }).items
+    expect(companyRows.some((row) => row.name === name)).toBe(false)
+  })
+
+  test('defaults customer kind to company', async ({ request }) => {
+    const name = `Company ${uniq()}`
+    accountIds.push(await createAccount(request, token, accountPayload({ name })))
+    const res = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=company&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const rows = ((await res.json()) as { items: Array<{ name: string; customer_kind: string }> }).items
+    expect(rows.find((row) => row.name === name)?.customer_kind).toBe('company')
+  })
+
+  test('rejects an invoice language the template does not support', async ({ request }) => {
+    const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: accountPayload({ invoiceLanguage: 'de' }),
+    })
+    expect(res.status()).toBe(400)
+  })
+
+  test('item pages return to the owning account; from the items list they return to the list', async ({
+    page,
+    request,
+  }) => {
+    const accountId = await createAccount(request, token, accountPayload())
+    accountIds.push(accountId)
+    const itemId = await createItem(request, token, accountId)
+    itemIds.push(itemId)
+
+    await login(page, 'admin')
+
+    // FormHeader's back link is the anchor rendering the "←" glyph. (The
+    // detail body also links to the account, so match the header link only.)
+    const backLink = page.locator('a', { hasText: '←' }).first()
+
+    // Opened in account context → back goes to the account's Items tab (Spec F, F8).
+    await page.goto(`/backend/billing/items/${itemId}`, { waitUntil: 'domcontentloaded' })
+    await expect(backLink).toHaveAttribute('href', `/backend/billing/accounts/${accountId}?tab=items`)
+
+    // Opened from the global Items list → back goes to the list.
+    await page.goto(`/backend/billing/items/${itemId}?from=items`, { waitUntil: 'domcontentloaded' })
+    await expect(backLink).toHaveAttribute('href', '/backend/billing/items')
+
+    // "Add item" from an account → Cancel returns to that account's Items tab.
+    await page.goto(`/backend/billing/items/create?billAccountId=${accountId}`, {
+      waitUntil: 'domcontentloaded',
+    })
+    await page.getByRole('button', { name: /cancel/i }).first().click()
+    await expect(page).toHaveURL(new RegExp(`/backend/billing/accounts/${accountId}\\?tab=items$`))
+  })
+})

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

@@ -0,0 +1,134 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-005: Bill Run catches up on every due cycle (Spec A)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-cycle-semantics.md
+ *
+ * An account whose next bill date lies three cycles before the as-of date,
+ * with one monthly in-advance item:
+ *   - a dry run previews 3 cycles and writes no invoice;
+ *   - a test run writes 3 TEST drafts (one per bill date), each covering its
+ *     own month, and leaves the account untouched;
+ *   - a legacy `catchUp` flag in the body is accepted and ignored.
+ * Self-contained: creates its own account + item, wipes its test drafts.
+ * Scoped with `scopedAccountIds` so other tenant data can't interfere.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type Cycle = { bill_date: string; period_start: string | null; period_end: string | null; status: string; invoice_id: string | null }
+
+async function createAccountWithItem(request: APIRequestContext, token: string): Promise<string> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Catch-up ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      invoiceLanguage: 'en',
+      nextBillDate: '2026-08-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-08-01',
+      description: 'Internet 300',
+      rateJson: { unit_price: 100 },
+      chargeTiming: 'in_advance',
+    },
+  })
+  expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+  return accountId
+}
+
+async function runCycles(
+  request: APIRequestContext,
+  token: string,
+  accountId: string,
+  mode: 'dry' | 'test',
+): Promise<{ billRunId: string; cycles: Cycle[] }> {
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+    token,
+    data: { mode, asOfDate: '2026-10-15', scopedAccountIds: [accountId], catchUp: true },
+  })
+  expect(run.ok(), `POST run (${mode}) 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 }> }
+  const outcome = body.items.find((row) => row.bill_account_id === accountId)
+  expect(outcome, 'outcome for the scoped account').toBeTruthy()
+  return { billRunId, cycles: outcome?.cycles ?? [] }
+}
+
+test.describe('TC-BILL-005: Bill Run catch-up (Spec A)', () => {
+  let token: string
+  let accountId: string | null = null
+  const testRunIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (testRunIds.length) {
+      await apiRequest(request, 'POST', '/api/billing/test-invoices/wipe', {
+        token,
+        data: { billRunId: testRunIds.pop() },
+      })
+    }
+    if (accountId) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id: accountId } })
+      accountId = null
+    }
+  })
+
+  test('dry run previews every due cycle without writing invoices', async ({ request }) => {
+    accountId = await createAccountWithItem(request, token)
+    const { cycles } = await runCycles(request, token, accountId, 'dry')
+    expect(cycles.map((c) => [c.bill_date, c.status, c.invoice_id])).toEqual([
+      ['2026-08-01', 'previewed', null],
+      ['2026-09-01', 'previewed', null],
+      ['2026-10-01', 'previewed', null],
+    ])
+  })
+
+  test('test run writes one TEST draft per bill date, each for its own month', async ({ request }) => {
+    accountId = await createAccountWithItem(request, token)
+    const { billRunId, cycles } = await runCycles(request, token, accountId, 'test')
+    testRunIds.push(billRunId)
+
+    expect(cycles.map((c) => [c.bill_date, c.period_start, c.period_end, c.status])).toEqual([
+      ['2026-08-01', '2026-08-01', '2026-08-31', 'invoiced'],
+      ['2026-09-01', '2026-09-01', '2026-09-30', 'invoiced'],
+      ['2026-10-01', '2026-10-01', '2026-10-31', 'invoiced'],
+    ])
+    expect(new Set(cycles.map((c) => c.invoice_id)).size).toBe(3)
+
+    const invoices = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/invoices?billAccountId=${accountId}&testRun=true`,
+      { token },
+    )
+    const invoiceRows = ((await invoices.json()) as { items: unknown[] }).items
+    expect(invoiceRows).toHaveLength(3)
+
+    // Test mode never advances the account: a second dry run still sees 3 cycles.
+    const again = await runCycles(request, token, accountId, 'dry')
+    expect(again.cycles).toHaveLength(3)
+  })
+})

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