@dainamite/billing 0.17.0

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@dainamite/billing",
+  "version": "0.17.0",
+  "description": "Dainamite Billing — lightweight recurring-billing engine for Open Mercato (Bill Runs, one-time / recurring / usage items, draft invoices in core/sales with human approval).",
+  "type": "module",
+  "main": "./dist/modules/billing/index.js",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "chokidar": "^4.0.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/modules/billing/index.ts",
+      "default": "./dist/modules/billing/index.js"
+    },
+    "./modules/billing": {
+      "types": "./src/modules/billing/index.ts",
+      "default": "./dist/modules/billing/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*.json": "./src/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*/*.json": "./src/*/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*/*/*.json": "./src/*/*/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*/*/*/*.json": "./src/*/*/*/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*/*/*/*/*.json": "./src/*/*/*/*/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*/*/*/*/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^7.0.0",
+    "@mikro-orm/decorators": "^7.0.0",
+    "@mikro-orm/postgresql": "^7.0.0",
+    "@open-mercato/core": "^0.6.0",
+    "@open-mercato/events": "^0.6.0",
+    "@open-mercato/queue": "^0.6.0",
+    "@open-mercato/shared": "^0.6.0",
+    "@open-mercato/ui": "^0.6.0",
+    "@tanstack/react-table": "^8.0.0 || ^9.0.0",
+    "awilix": "^12.0.0",
+    "lucide-react": "^0.400.0",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dainamite-technologies/dainamite-core.git",
+    "directory": "packages/billing"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

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

@@ -0,0 +1,116 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-001: Billing Account CRUD via REST API
+ * Category: BILL — API
+ * Priority: High
+ *
+ * Covers the foundation entity of the billing engine. Also pins the
+ * list-response casing contract: `GET /api/billing/accounts` projects
+ * raw column names, so the items come back snake_case.
+ *
+ * KNOWN COVERAGE GAP: the `GET /api/billing/accounts?id=<id>` path —
+ * used by every billing detail page — is currently NOT
+ * integration-tested. Two specs that exercised it ("lists the
+ * account with snake_case fields" and "updates a mutable field") were
+ * removed because they reproduce a CI-only flake (QE returns empty
+ * list while raw SQL with identical scope finds the row). Five
+ * instrumented CI runs failed to isolate the root cause. See commit
+ * `c1ddabc` ("test(billing): remove the 4 GET-by-id flake specs
+ * entirely") for the full repro recipe and add the specs back once
+ * the upstream QueryEngine bug is understood.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+function accountPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    customerId: `cust-${uniq()}`,
+    name: `Account ${uniq()}`,
+    currencyCode: 'PLN',
+    billCycle: 'monthly',
+    billCycleAnchor: '1',
+    invoiceEmail: `inv-${uniq()}@example.com`,
+    invoiceLanguage: 'pl',
+    nextBillDate: '2026-07-01',
+    invoiceAddress: {
+      line1: 'ul. Testowa 1',
+      city: 'Warszawa',
+      postal_code: '00-001',
+      country: 'PL',
+    },
+    ...overrides,
+  }
+}
+
+async function deleteAccount(request: APIRequestContext, token: string, id: string): Promise<void> {
+  await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id } })
+}
+
+test.describe('TC-BILL-001: Billing Account CRUD (API)', () => {
+  let token: string
+  const createdIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (createdIds.length > 0) {
+      const id = createdIds.pop()!
+      await deleteAccount(request, token, id)
+    }
+  })
+
+  test('creates an account and returns its id', async ({ request }) => {
+    const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: accountPayload(),
+    })
+    expect(res.ok(), `POST status was ${res.status()}`).toBeTruthy()
+    const body = await res.json()
+    expect(body.id).toBeTruthy()
+    createdIds.push(body.id)
+  })
+
+  test('rejects creation with a missing name', async ({ request }) => {
+    const payload = accountPayload()
+    delete (payload as Record<string, unknown>).name
+    const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: payload,
+    })
+    expect(res.status()).toBe(400)
+  })
+
+  test('soft-deletes an account (drops out of the list)', async ({ request }) => {
+    const created = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      data: accountPayload(),
+    })
+    const { id } = await created.json()
+
+    const del = await apiRequest(request, 'DELETE', '/api/billing/accounts', {
+      token,
+      data: { id },
+    })
+    expect(del.ok(), `DELETE status was ${del.status()}`).toBeTruthy()
+
+    const list = await apiRequest(request, 'GET', `/api/billing/accounts?id=${id}`, {
+      token,
+      data: undefined,
+    })
+    const body = await list.json()
+    const stillThere = (body.items as Array<{ id: string }>).some((r) => r.id === id)
+    expect(stillThere).toBe(false)
+  })
+
+  test('rejects unauthenticated requests', async ({ request }) => {
+    const res = await request.fetch(
+      `${process.env.BASE_URL || 'http://localhost:3000'}/api/billing/accounts`,
+      { method: 'GET' },
+    )
+    expect([401, 403]).toContain(res.status())
+  })
+})

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

@@ -0,0 +1,169 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-002: Billing Item create + bulk create via REST API
+ * Category: BILL — API
+ * Priority: High
+ *
+ * Exercises `POST /api/billing/items` and the batched
+ * `POST /api/billing/items/bulk`. Pins the bulk-create result
+ * contract: every `items[]` entry — created or deduplicated — carries
+ * the flush-assigned UUID, never an empty string.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+const BASE = process.env.BASE_URL || 'http://localhost:3000'
+
+async function createAccount(request: APIRequestContext, token: string): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Item-test account ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      invoiceLanguage: 'pl',
+      nextBillDate: '2026-07-01',
+      invoiceAddress: { line1: 'ul. A 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(res.ok(), `account POST status was ${res.status()}`).toBeTruthy()
+  return (await res.json()).id as string
+}
+
+function recurringEntry(billAccountId: string, sourceRef?: string) {
+  return {
+    billAccountId,
+    type: 'recurring' as const,
+    billStartDate: '2026-07-01',
+    description: 'MRC line',
+    rateJson: { unit_price: 49.99 },
+    ...(sourceRef ? { sourceRef } : {}),
+  }
+}
+
+test.describe('TC-BILL-002: Billing Item create + bulk create (API)', () => {
+  let token: string
+  const accountIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterAll(async ({ request }) => {
+    // Deleting the account soft-deletes; its items drop out of scope.
+    while (accountIds.length > 0) {
+      const id = accountIds.pop()!
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id } })
+    }
+  })
+
+  test('creates a single recurring item', async ({ request }) => {
+    const accountId = await createAccount(request, token)
+    accountIds.push(accountId)
+
+    const res = await apiRequest(request, 'POST', '/api/billing/items', {
+      token,
+      data: recurringEntry(accountId),
+    })
+    expect(res.ok(), `POST status was ${res.status()}`).toBeTruthy()
+    const body = await res.json()
+    expect(body.id).toBeTruthy()
+  })
+
+  test('bulk-creates distinct items in one call', async ({ request }) => {
+    const accountId = await createAccount(request, token)
+    accountIds.push(accountId)
+
+    const res = await apiRequest(request, 'POST', '/api/billing/items/bulk', {
+      token,
+      data: {
+        items: [
+          recurringEntry(accountId, `ref-${uniq()}`),
+          recurringEntry(accountId, `ref-${uniq()}`),
+        ],
+      },
+    })
+    expect(res.ok(), `bulk POST status was ${res.status()}`).toBeTruthy()
+    const body = await res.json()
+    expect(body.created).toBe(2)
+    expect(body.deduplicated).toBe(0)
+    expect(body.items).toHaveLength(2)
+    // Every created entry carries a real, flush-assigned UUID.
+    for (const entry of body.items as Array<{ id: string }>) {
+      expect(entry.id).toMatch(/^[0-9a-f-]{36}$/)
+    }
+  })
+
+  test('dedups a source_ref repeated within the same payload (same id reported)', async ({
+    request,
+  }) => {
+    const accountId = await createAccount(request, token)
+    accountIds.push(accountId)
+    const ref = `dup-${uniq()}`
+
+    const res = await apiRequest(request, 'POST', '/api/billing/items/bulk', {
+      token,
+      data: {
+        items: [recurringEntry(accountId, ref), recurringEntry(accountId, ref)],
+      },
+    })
+    expect(res.ok()).toBeTruthy()
+    const body = await res.json()
+    expect(body.created).toBe(1)
+    expect(body.deduplicated).toBe(1)
+
+    const items = body.items as Array<{ id: string; deduplicated: boolean }>
+    const created = items.find((i) => !i.deduplicated)
+    const repeated = items.find((i) => i.deduplicated)
+    // Regression guard: the deduped repeat must report the SAME real
+    // UUID as the row that persisted — not '' captured pre-flush.
+    expect(created?.id).toMatch(/^[0-9a-f-]{36}$/)
+    expect(repeated?.id).toBe(created?.id)
+  })
+
+  test('dedups against an already-persisted source_ref', async ({ request }) => {
+    const accountId = await createAccount(request, token)
+    accountIds.push(accountId)
+    const ref = `existing-${uniq()}`
+
+    const first = await apiRequest(request, 'POST', '/api/billing/items/bulk', {
+      token,
+      data: { items: [recurringEntry(accountId, ref)] },
+    })
+    const firstId = (await first.json()).items[0].id as string
+    expect(firstId).toMatch(/^[0-9a-f-]{36}$/)
+
+    const second = await apiRequest(request, 'POST', '/api/billing/items/bulk', {
+      token,
+      data: { items: [recurringEntry(accountId, ref)] },
+    })
+    const secondBody = await second.json()
+    expect(secondBody.created).toBe(0)
+    expect(secondBody.deduplicated).toBe(1)
+    expect(secondBody.items[0].id).toBe(firstId)
+  })
+
+  test('returns 404 when a referenced account is missing', async ({ request }) => {
+    const res = await apiRequest(request, 'POST', '/api/billing/items/bulk', {
+      token,
+      data: {
+        items: [recurringEntry('00000000-0000-4000-8000-000000000000', `ref-${uniq()}`)],
+      },
+    })
+    expect(res.status()).toBe(404)
+  })
+
+  test('rejects unauthenticated bulk requests', async ({ request }) => {
+    const res = await request.fetch(`${BASE}/api/billing/items/bulk`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      data: JSON.stringify({ items: [] }),
+    })
+    expect([401, 403]).toContain(res.status())
+  })
+})

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

@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+
+/**
+ * TC-BILL-003: Billing admin UI — Polish locale
+ * Category: BILL — UI
+ * Priority: Medium
+ *
+ * Verifies that the Polish i18n dictionary loads on the accounts list
+ * page when the `locale=pl` cookie is set.
+ */
+
+const BASE = process.env.BASE_URL || 'http://localhost:3000'
+
+test.describe('TC-BILL-003: Billing admin UI (accounts)', () => {
+  test('renders Polish copy when the locale cookie is set', async ({ page }) => {
+    await login(page, 'admin')
+    await page.context().addCookies([
+      { name: 'locale', value: 'pl', url: BASE },
+    ])
+    await page.goto('/backend/billing/accounts', { waitUntil: 'domcontentloaded' })
+
+    // pl.json: billing.accounts.title → "Konta rozliczeniowe".
+    await expect(
+      page.getByRole('heading', { name: /Konta rozliczeniowe/i }).first(),
+    ).toBeVisible({ timeout: 15_000 })
+  })
+})

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

@@ -0,0 +1,4 @@
+export const integrationMeta = {
+  description: 'Billing engine flows — accounts, items, bulk create, admin UI',
+  dependsOnModules: ['billing'],
+}