@dainamite/billing 0.20.0 → 0.22.0

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