@dainamite/billing 0.19.0 → 0.20.0

package/src/modules/billing/__tests__/entityRegistry.test.ts

@@ -0,0 +1,319 @@
+/**
+ * Shipped entity-id registry (`packages/billing/generated/`).
+ *
+ * A standalone Open Mercato app only registers billing's entity ids if the
+ * package ships `generated/entities.ids.generated.ts` — the compiled
+ * `dist/.../data/entities.js` uses `export { … }`, which the CLI's class
+ * scanner cannot see, so without the registry the app gets
+ * `"billing": {}`. Two things then break:
+ *   - the query-index subscriber rejects every billing write
+ *     (`QueryIndexScopeError: Query index entity type is not registered`);
+ *   - `mercato entities install` registers the ids as virtual custom
+ *     entities and the query engine stops reading the billing tables.
+ *
+ * These tests pin the registry contents, check it is in sync with its
+ * sources, run the real `@open-mercato/cli` generator over the package,
+ * and feed the ids through the framework functions that failed, against
+ * billing's real MikroORM metadata (discovered without a database) — down
+ * to what `billing.accounts.create` hands the real data engine.
+ */
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { MikroORM } from '@mikro-orm/postgresql'
+import {
+  QueryIndexScopeError,
+  resolveQueryIndexSourceMetadata,
+} from '@open-mercato/core/modules/query_index/lib/subscriber-scope'
+import { DefaultDataEngine, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
+import { registerEntityIds } from '@open-mercato/shared/lib/encryption/entityIds'
+import { resolveRegisteredEntityTableName } from '@open-mercato/shared/lib/query/engine'
+import { isEventDeclared } from '@open-mercato/shared/modules/events'
+
+import { createAccountCommand } from '../commands/accounts'
+import '../events'
+import * as billingEntities from '../data/entities'
+import { billingEntityIds } from '../data/entityIds'
+import { E, M } from '../../../../generated/entities.ids.generated'
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../../../..')
+const REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..')
+const GENERATED_ROOT = path.join(PACKAGE_ROOT, 'generated')
+
+const ALL_IDS = Object.values(billingEntityIds)
+const suffixOf = (id: string) => id.split(':')[1]
+
+/** Every billing id → the table the framework must resolve it to. */
+const EXPECTED_TABLES: Record<string, string> = {
+  [billingEntityIds.account]: 'billing_accounts',
+  [billingEntityIds.item]: 'billing_items',
+  [billingEntityIds.usage]: 'billing_account_usage',
+  [billingEntityIds.run]: 'billing_runs',
+  [billingEntityIds.runOutcome]: 'billing_run_outcomes',
+  [billingEntityIds.draftInvoiceEdit]: 'billing_draft_invoice_edits',
+  [billingEntityIds.balance]: 'billing_account_balances',
+  [billingEntityIds.transaction]: 'billing_account_transactions',
+  [billingEntityIds.topup]: 'billing_topups',
+  [billingEntityIds.statement]: 'billing_statements',
+}
+
+/** PascalCase of an id suffix — the class name the framework looks up. */
+const classNameOf = (id: string) =>
+  suffixOf(id)
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+
+/** A registry as a real app would have it: core ids present, billing empty (the bug). */
+const REGISTRY_WITHOUT_BILLING = {
+  directory: { tenant: 'directory:tenant', organization: 'directory:organization' },
+  billing: {},
+}
+
+function readShippedColumns(key: string): string[] {
+  const file = path.join(GENERATED_ROOT, 'entities', key, 'index.ts')
+  const source = fs.readFileSync(file, 'utf8')
+  return Array.from(source.matchAll(/^export const \w+ = "([^"]+)"$/gm), (m) => m[1])
+}
+
+let orm: MikroORM
+let em: EntityManager
+
+beforeAll(() => {
+  // Every runtime export of data/entities.ts is an entity class.
+  const entityClasses = Object.values(billingEntities)
+  // The constructor discovers metadata synchronously; no connection is opened.
+  orm = new MikroORM({ entities: entityClasses, dbName: 'billing_entity_registry_test' })
+  em = orm.em.fork() as EntityManager
+})
+
+afterAll(async () => {
+  await orm.close(true)
+})
+
+describe('shipped registry — generated/entities.ids.generated.ts', () => {
+  it('declares the billing module', () => {
+    expect(M).toEqual({ billing: 'billing' })
+  })
+
+  it('lists every billingEntityIds value under its id suffix, and nothing else', () => {
+    // The CLI ignores the values and registers `billing:<key>`, so the keys
+    // are what matters.
+    const expected = Object.fromEntries(ALL_IDS.map((id) => [suffixOf(id), id]))
+    expect(E.billing).toEqual(expected)
+    expect(Object.keys(E.billing)).toHaveLength(10)
+  })
+
+  it('ships one column file per entity, matching the ORM columns', () => {
+    const shippedDirs = fs.readdirSync(path.join(GENERATED_ROOT, 'entities')).sort()
+    expect(shippedDirs).toEqual(ALL_IDS.map(suffixOf).sort())
+
+    for (const id of ALL_IDS) {
+      const table = EXPECTED_TABLES[id]
+      const meta = orm.getMetadata().getAll()
+      const entityMeta = Array.from(meta.values()).find((candidate) => candidate.tableName === table)
+      expect(entityMeta).toBeDefined()
+      const ormColumns = entityMeta!.props.flatMap((prop) => prop.fieldNames ?? [])
+      expect({ id, columns: readShippedColumns(suffixOf(id)).sort() }).toEqual({ id, columns: [...ormColumns].sort() })
+    }
+  })
+
+  it('is in sync with data/entityIds.ts and data/entities.ts', () => {
+    // Throws (exit 1) and names the stale files when generated/ drifted.
+    expect(() =>
+      execFileSync(process.execPath, [path.join(PACKAGE_ROOT, 'scripts', 'generate-entity-registry.mjs'), '--check'], {
+        cwd: PACKAGE_ROOT,
+        stdio: 'pipe',
+        timeout: 60_000,
+      }),
+    ).not.toThrow()
+  })
+
+  it('is what `mercato generate` registers for billing in a standalone app', () => {
+    // Runs the real @open-mercato/cli entity-ids generator over the package,
+    // resolved the way a standalone app resolves it (dist/modules when built,
+    // else src/modules). Without the registry this yields `billing: {}` (dist)
+    // or class-derived ids such as `billing:bill_run` (src).
+    const script = `
+      import fs from 'node:fs'
+      import os from 'node:os'
+      import path from 'node:path'
+      import { createRequire } from 'node:module'
+      const [repoRoot] = process.argv.slice(1)
+      const require = createRequire(path.join(repoRoot, 'package.json'))
+      const { generateEntityIds } = await import(require.resolve('@open-mercato/cli/lib/generators/entity-ids'))
+      const pkgRoot = path.join(repoRoot, 'node_modules', '@dainamite', 'billing')
+      const distModules = path.join(pkgRoot, 'dist', 'modules')
+      const pkgModules = fs.existsSync(distModules) ? distModules : path.join(pkgRoot, 'src', 'modules')
+      const out = fs.mkdtempSync(path.join(os.tmpdir(), 'billing-entity-ids-'))
+      try {
+        await generateEntityIds({
+          quiet: true,
+          resolver: {
+            isMonorepo: () => false,
+            getOutputDir: () => out,
+            getPackageOutputDir: () => out,
+            loadEnabledModules: () => [{ id: 'billing', from: '@dainamite/billing' }],
+            getModulePaths: (entry) => ({
+              appBase: path.join(repoRoot, 'src', 'modules', entry.id),
+              pkgBase: path.join(pkgModules, entry.id),
+            }),
+            getModuleImportBase: (entry) => ({ appBase: '@/modules/' + entry.id, pkgBase: entry.from + '/modules/' + entry.id }),
+            getPackageRoot: (from) => path.join(repoRoot, 'node_modules', from),
+          },
+        })
+        const source = fs.readFileSync(path.join(out, 'entities.ids.generated.ts'), 'utf8')
+        const match = source.match(/E = (\\{[\\s\\S]*?\\}) as const/)
+        process.stdout.write(match ? match[1] : 'null')
+      } finally {
+        fs.rmSync(out, { recursive: true, force: true })
+      }
+    `
+    const output = execFileSync(process.execPath, ['--input-type=module', '-e', script, REPO_ROOT], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 60_000,
+    })
+    const generated = JSON.parse(output) as { billing?: Record<string, string> }
+    expect(generated.billing).toEqual(E.billing)
+  }, 90_000)
+})
+
+describe('entity id → ORM table (resolveRegisteredEntityTableName)', () => {
+  it.each(ALL_IDS)('resolves %s to its table', (id) => {
+    expect(resolveRegisteredEntityTableName(em, id)).toBe(EXPECTED_TABLES[id])
+  })
+
+  it.each(ALL_IDS)('%s matches its entity class name', (id) => {
+    // The class-name lookup is the only path that works on Open Mercato 0.9
+    // (see the canary below). `billing_run` was `BillRun` until 0.20.0.
+    expect(classNameOf(id) in billingEntities).toBe(true)
+    // Look up by class-name string, as the framework does (MikroORM 7 types
+    // only admit class references here, but the runtime accepts names).
+    expect(orm.getMetadata().find(classNameOf(id) as never)?.tableName).toBe(EXPECTED_TABLES[id])
+  })
+
+  it('canary: the framework table-name fallback never matches on MikroORM 7', () => {
+    // `billing:runs` → candidate table `billing_runs`, which exists. The
+    // fallback iterates `MetadataStorage.getAll()` as an array, but MikroORM 7
+    // returns a Map, so it finds nothing. If this starts failing, upstream
+    // fixed it — the class-name rule in scripts/generate-entity-registry.mjs
+    // can then be relaxed.
+    expect(resolveRegisteredEntityTableName(em, 'billing:runs')).toBeNull()
+  })
+})
+
+describe('query index accepts billing writes', () => {
+  it('rejects billing ids while the app registry has `billing: {}` (the bug)', () => {
+    registerEntityIds(REGISTRY_WITHOUT_BILLING as never)
+    expect(() => resolveQueryIndexSourceMetadata(em, billingEntityIds.account)).toThrow(QueryIndexScopeError)
+    expect(() => resolveQueryIndexSourceMetadata(em, billingEntityIds.account)).toThrow(
+      'Query index entity type is not registered: billing:billing_account',
+    )
+  })
+
+  it.each(ALL_IDS)('resolves the tenant-scoped source of %s once the shipped registry is registered', (id) => {
+    registerEntityIds({ ...REGISTRY_WITHOUT_BILLING, ...E } as never)
+    expect(resolveQueryIndexSourceMetadata(em, id)).toEqual({
+      table: EXPECTED_TABLES[id],
+      organizationColumn: 'organization_id',
+      tenantColumn: 'tenant_id',
+    })
+  })
+})
+
+describe('query engine reads billing ids from their tables', () => {
+  // The hybrid query engine checks `isOrmBackedSystemEntityId` before it
+  // consults `custom_entities`. Only a registered id short-circuits there, so
+  // an active `custom_entities` row (written by `mercato entities install`)
+  // can no longer route billing reads to custom-entity storage.
+  it('does not treat billing ids as ORM-backed while the registry has `billing: {}`', () => {
+    registerEntityIds(REGISTRY_WITHOUT_BILLING as never)
+    for (const id of ALL_IDS) {
+      expect({ id, ormBacked: isOrmBackedSystemEntityId(em, id) }).toEqual({ id, ormBacked: false })
+    }
+  })
+
+  it('treats every billing id as ORM-backed with the shipped registry', () => {
+    registerEntityIds({ ...REGISTRY_WITHOUT_BILLING, ...E } as never)
+    for (const id of ALL_IDS) {
+      expect({ id, ormBacked: isOrmBackedSystemEntityId(em, id) }).toEqual({ id, ormBacked: true })
+    }
+  })
+})
+
+describe('billing.accounts.create side effects', () => {
+  const TENANT = '11111111-1111-4111-8111-111111111111'
+  const ORG = '22222222-2222-4222-8222-222222222222'
+  const ACCOUNT_ID = '33333333-3333-4333-8333-333333333333'
+
+  it('emits a declared CRUD event and a query-index upsert the index accepts', async () => {
+    registerEntityIds({ ...REGISTRY_WITHOUT_BILLING, ...E } as never)
+
+    const emitted: Array<{ event: string; payload: Record<string, unknown> }> = []
+    const eventBus = {
+      emitEvent: jest.fn(async (event: string, payload: Record<string, unknown>) => {
+        emitted.push({ event, payload })
+      }),
+    }
+    const commandEm = {
+      fork: () => commandEm,
+      create: (_entity: unknown, data: Record<string, unknown>) => ({ id: ACCOUNT_ID, ...data }),
+      persist: jest.fn(),
+      flush: jest.fn(async () => undefined),
+    }
+    const container = {
+      resolve: (name: string) => {
+        if (name === 'eventBus') return eventBus
+        if (name === 'em') return commandEm
+        if (name === 'dataEngine') return dataEngine
+        throw new Error(`unexpected resolve(${name})`)
+      },
+    }
+    // The real data engine: it turns the command's side effects into the
+    // CRUD event and the `query_index.upsert_one` call.
+    const dataEngine = new DefaultDataEngine(em as never, container as never)
+
+    await createAccountCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        customerId: 'cust-1',
+        name: 'Acme',
+        currencyCode: 'EUR',
+        billCycle: 'monthly',
+        billCycleAnchor: '1',
+        invoiceEmail: 'billing@acme.test',
+        invoiceLanguage: 'en',
+        invoiceAddress: { line1: 'Main St 1', city: 'Berlin', postal_code: '10115', country: 'DE' },
+        nextBillDate: '2026-12-01',
+      } as never,
+      { auth: null, container } as never,
+    )
+    // The command bus flushes queued side effects after `execute`.
+    await dataEngine.flushOrmEntityChanges()
+
+    const crudEvent = emitted.find((entry) => entry.event.startsWith('billing.'))
+    expect(crudEvent?.event).toBe('billing.account.created')
+    expect(isEventDeclared('billing.account.created')).toBe(true)
+
+    const upsert = emitted.find((entry) => entry.event === 'query_index.upsert_one')
+    expect(upsert?.payload).toMatchObject({
+      entityType: 'billing:billing_account',
+      recordId: ACCOUNT_ID,
+      tenantId: TENANT,
+      organizationId: ORG,
+    })
+    // The first thing the `query_index.upsert_one` subscriber does — the
+    // call that threw QueryIndexScopeError and wrote `indexer_error_logs`.
+    expect(resolveQueryIndexSourceMetadata(em, String(upsert!.payload.entityType))).toEqual({
+      table: 'billing_accounts',
+      organizationColumn: 'organization_id',
+      tenantColumn: 'tenant_id',
+    })
+  })
+})

package/src/modules/billing/__tests__/events.test.ts

@@ -0,0 +1,142 @@
+/**
+ * CRUD event declarations.
+ *
+ * Commands emit CRUD events indirectly: `emitCrudSideEffects({ action,
+ * events: { module: 'billing', entity } })` makes the data engine emit
+ * `billing.<entity>.<action>`. An id missing from events.ts is still emitted,
+ * but logs "Emitting undeclared event" and stays invisible to the event
+ * registry (workflow triggers, subscriber discovery).
+ *
+ * The scan below reads every `emitCrudSideEffects` / `emitCrudUndoSideEffects`
+ * call in commands/ and requires the declared `crud` events to match exactly:
+ * nothing emitted is undeclared, nothing declared is never emitted.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import ts from 'typescript'
+
+import { isEventDeclared } from '@open-mercato/shared/modules/events'
+
+import eventsConfig from '../events'
+
+const COMMANDS_DIR = path.resolve(__dirname, '../commands')
+const SIDE_EFFECT_HELPERS = new Set(['emitCrudSideEffects', 'emitCrudUndoSideEffects'])
+
+type Emission = { eventId: string; file: string }
+
+function unwrap(expression: ts.Expression): ts.Expression {
+  if (ts.isAsExpression(expression) || ts.isParenthesizedExpression(expression) || ts.isSatisfiesExpression(expression)) {
+    return unwrap(expression.expression)
+  }
+  return expression
+}
+
+function propertyOf(objectLiteral: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined {
+  for (const property of objectLiteral.properties) {
+    if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === name) {
+      return unwrap(property.initializer)
+    }
+    if (ts.isShorthandPropertyAssignment(property) && property.name.text === name) {
+      return property.name
+    }
+  }
+  return undefined
+}
+
+function stringValue(expression: ts.Expression | undefined): string | undefined {
+  return expression && ts.isStringLiteralLike(expression) ? expression.text : undefined
+}
+
+/** Every `billing.<entity>.<action>` a command file emits through the CRUD helpers. */
+function scanCommandFile(file: string): Emission[] {
+  const sourceFile = ts.createSourceFile(file, fs.readFileSync(file, 'utf8'), ts.ScriptTarget.ES2022, true, ts.ScriptKind.TS)
+
+  // Module-level `const xEvents = { module, entity, … } as const`.
+  const eventConfigs = new Map<string, ts.ObjectLiteralExpression>()
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue
+      const initializer = unwrap(declaration.initializer)
+      if (ts.isObjectLiteralExpression(initializer)) eventConfigs.set(declaration.name.text, initializer)
+    }
+  }
+
+  const emissions: Emission[] = []
+  const relativeFile = path.relative(COMMANDS_DIR, file)
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      SIDE_EFFECT_HELPERS.has(node.expression.text) &&
+      node.arguments[0] &&
+      ts.isObjectLiteralExpression(unwrap(node.arguments[0]))
+    ) {
+      const options = unwrap(node.arguments[0]) as ts.ObjectLiteralExpression
+      const eventsExpression = propertyOf(options, 'events')
+      if (eventsExpression) {
+        const config = ts.isIdentifier(eventsExpression)
+          ? eventConfigs.get(eventsExpression.text)
+          : ts.isObjectLiteralExpression(eventsExpression)
+            ? eventsExpression
+            : undefined
+        const moduleId = config ? stringValue(propertyOf(config, 'module')) : undefined
+        const entity = config ? stringValue(propertyOf(config, 'entity')) : undefined
+        const action = stringValue(propertyOf(options, 'action'))
+        if (!moduleId || !entity || !action) {
+          const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
+          throw new Error(
+            `${relativeFile}:${line + 1}: cannot statically read the CRUD event of this ${node.expression.text} call — ` +
+              'use a literal `action` and a module-level `events` config so this test can check it',
+          )
+        }
+        emissions.push({ eventId: `${moduleId}.${entity}.${action}`, file: relativeFile })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return emissions
+}
+
+const emissions = fs
+  .readdirSync(COMMANDS_DIR)
+  .filter((name) => name.endsWith('.ts'))
+  .flatMap((name) => scanCommandFile(path.join(COMMANDS_DIR, name)))
+const emittedIds = Array.from(new Set(emissions.map((emission) => emission.eventId))).sort()
+const declaredCrudIds = eventsConfig.events
+  .filter((event) => event.category === 'crud')
+  .map((event) => event.id)
+  .sort()
+
+describe('billing CRUD events', () => {
+  it('finds the CRUD emissions in commands/', () => {
+    // Guards the scanner itself: if it silently found nothing, the checks
+    // below would pass vacuously.
+    expect(emittedIds).toEqual(
+      expect.arrayContaining(['billing.account.created', 'billing.item.updated', 'billing.topup.created']),
+    )
+  })
+
+  it.each(emittedIds)('declares %s, which a command emits', (eventId) => {
+    expect(declaredCrudIds).toContain(eventId)
+    expect(isEventDeclared(eventId)).toBe(true)
+  })
+
+  it('declares no CRUD event that no command emits', () => {
+    expect(declaredCrudIds).toEqual(emittedIds)
+  })
+
+  it('declares every CRUD event against the entity in its id', () => {
+    for (const event of eventsConfig.events.filter((candidate) => candidate.category === 'crud')) {
+      expect({ id: event.id, entity: event.entity }).toEqual({ id: event.id, entity: event.id.split('.')[1] })
+    }
+  })
+
+  it('keeps the per-upload usage event out of workflow triggers, like billing.usage.rated', () => {
+    const byId = new Map(eventsConfig.events.map((event) => [event.id, event]))
+    expect(byId.get('billing.usage.created')?.excludeFromTriggers).toBe(true)
+    expect(byId.get('billing.usage.rated')?.excludeFromTriggers).toBe(true)
+  })
+})

package/src/modules/billing/__tests__/lib/billRunEngine.test.ts

@@ -1,8 +1,8 @@
 import { runBillRun, type RunBillRunParams } from '../../lib/billRunEngine'
 import { __resetInvoiceWriterCacheForTests } from '../../lib/invoiceWriter'
 import {
-  BillRun,
-  BillRunOutcome,
+  BillingRun,
+  BillingRunOutcome,
   BillingAccount,
   BillingAccountUsage,
   BillingItem,
@@ -269,7 +269,7 @@ describe('runBillRun — orchestration', () => {
     // Real-mode advances next_bill_date
     expect(account.nextBillDate.toISOString().slice(0, 10)).toBe('2026-07-01')
     expect(item.billedToDate?.toISOString().slice(0, 10)).toBe('2026-05-31')
-    // Persisted entities: BillRun + SalesInvoice + 1 line + BillingAccountUsage advance + BillRunOutcome
+    // Persisted entities: BillingRun + SalesInvoice + 1 line + BillingAccountUsage advance + BillingRunOutcome
     expect(captured.persisted.length).toBeGreaterThan(0)
   })
 

package/src/modules/billing/api/export/account/[id]/route.ts

@@ -10,8 +10,8 @@ import {
   BillingItem,
   BillingStatement,
   BillingTopup,
-  BillRunOutcome,
-  DraftInvoiceEdit,
+  BillingRunOutcome,
+  BillingDraftInvoiceEdit,
 } from '../../../../data/entities'
 
 /**
@@ -22,10 +22,10 @@ import {
  *   - The account row itself.
  *   - Every active + soft-deleted `BillingItem` for the account.
  *   - Every `BillingAccountUsage` record.
- *   - Every `BillRunOutcome` row referencing the account.
+ *   - Every `BillingRunOutcome` row referencing the account.
  *   - Every `core/sales` invoice the engine emitted for the account
  *     (matched via `metadata->>'bill_account_id'`).
- *   - Every `DraftInvoiceEdit` audit row for those invoices.
+ *   - Every `BillingDraftInvoiceEdit` audit row for those invoices.
  *
  * Scope: the caller's auth tenant/organization is the authority — a
  * 404 is returned even for valid UUIDs that belong to a different
@@ -108,7 +108,7 @@ export async function GET(
         { limit: EXPORT_HARD_LIMIT, orderBy: { periodEnd: 'DESC' } },
       ),
       em.find(
-        BillRunOutcome,
+        BillingRunOutcome,
         {
           tenantId,
           organizationId,
@@ -177,7 +177,7 @@ export async function GET(
     const draftEdits =
       invoiceIds.length > 0
         ? await em.find(
-            DraftInvoiceEdit,
+            BillingDraftInvoiceEdit,
             {
               tenantId,
               organizationId,
@@ -272,7 +272,7 @@ export const openApi = {
         },
       ],
       description:
-        "Returns a JSON dump of a single Billing Account: the account itself, every Billing Item (no time cap — items often outlive a single export window), and the Usage records / BillRunOutcomes / emitted core/sales invoices / DraftInvoiceEdit rows whose timestamps fall in the [since, until] window (defaults to the last 12 months). Each collection is independently capped by EXPORT_HARD_LIMIT = 50,000 rows. Lifetime dumps for outlier accounts need a follow-up chunked background-job approach — out of scope for this v1 endpoint.",
+        "Returns a JSON dump of a single Billing Account: the account itself, every Billing Item (no time cap — items often outlive a single export window), and the Usage records / BillRunOutcomes / emitted core/sales invoices / BillingDraftInvoiceEdit rows whose timestamps fall in the [since, until] window (defaults to the last 12 months). Each collection is independently capped by EXPORT_HARD_LIMIT = 50,000 rows. Lifetime dumps for outlier accounts need a follow-up chunked background-job approach — out of scope for this v1 endpoint.",
     },
   },
 }

package/src/modules/billing/api/invoices/add-line/route.ts

@@ -67,7 +67,7 @@ export const openApi = createBillingCrudOpenApi({
     responseSchema: addLineResponseSchema,
     description:
       'Appends a new line to a draft invoice (e.g. operator adds a ' +
-      'one-off adjustment). Writes a `DraftInvoiceEdit` audit row ' +
+      'one-off adjustment). Writes a `BillingDraftInvoiceEdit` audit row ' +
       '(action=`line_added`, `before_json=null`). Recomputes invoice ' +
       'totals. Refuses non-draft invoices.',
   },

package/src/modules/billing/api/invoices/edit-line/route.ts

@@ -14,7 +14,7 @@ import { createBillingCrudOpenApi } from '../../openapi'
 /**
  * `POST /api/billing/invoices/edit-line` — edits one line of a draft
  * invoice. Refuses non-drafts (409 / `billing.invoice.not_draft`).
- * Writes a `DraftInvoiceEdit` audit row per spec. Recomputes invoice
+ * Writes a `BillingDraftInvoiceEdit` audit row per spec. Recomputes invoice
  * totals from the surviving lines after the edit.
  *
  * Operator surface: route is gated by `billing.invoice.edit_draft`.
@@ -82,7 +82,7 @@ export const openApi = createBillingCrudOpenApi({
     description:
       'Edits one line of a draft invoice (description, quantity, ' +
       "unit_price, or explicit `totalNetAmount` override). Writes a " +
-      '`DraftInvoiceEdit` audit row with before+after snapshots and ' +
+      '`BillingDraftInvoiceEdit` audit row with before+after snapshots and ' +
       'recomputes invoice totals. Refuses non-draft invoices with ' +
       'HTTP 409 + `billing.invoice.not_draft`.',
   },

package/src/modules/billing/api/invoices/remove-line/route.ts

@@ -68,7 +68,7 @@ export const openApi = createBillingCrudOpenApi({
     description:
       'Removes one line from a draft invoice (hard delete — the line ' +
       'never existed as far as future readers are concerned). Writes ' +
-      'a `DraftInvoiceEdit` audit row (action=`line_removed`, ' +
+      'a `BillingDraftInvoiceEdit` audit row (action=`line_removed`, ' +
       '`after_json=null`) carrying the before-snapshot for forensics. ' +
       'Recomputes invoice totals. Refuses non-draft invoices.',
   },

package/src/modules/billing/api/run-outcomes/route.ts

@@ -3,7 +3,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import type { AwilixContainer } from 'awilix'
 import { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
-import { BillingAccount, BillRunOutcome } from '../../data/entities'
+import { BillingAccount, BillingRunOutcome } from '../../data/entities'
 import { billingEntityIds } from '../../data/entityIds'
 import {
   BILL_RUN_OUTCOME_STATUSES,
@@ -56,7 +56,7 @@ const billRunOutcomeListItemSchema = z.object({
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: BillRunOutcome,
+    entity: BillingRunOutcome,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

package/src/modules/billing/api/runs/retry-failed/route.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
-import { BillRun } from '../../../data/entities'
+import { BillingRun } from '../../../data/entities'
 import { billingEntityIds } from '../../../data/entityIds'
 import { billingRunRetryFailedSchema } from '../../../data/validators'
 import { createBillingCrudOpenApi } from '../../openapi'
@@ -37,7 +37,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: BillRun,
+    entity: BillingRun,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

package/src/modules/billing/api/runs/route.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
-import { BillRun } from '../../data/entities'
+import { BillingRun } from '../../data/entities'
 import { billingEntityIds } from '../../data/entityIds'
 import {
   billingRunListQuerySchema,
@@ -64,7 +64,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: BillRun,
+    entity: BillingRun,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

package/src/modules/billing/backend/billing/accounts/[id]/page.tsx

@@ -3,7 +3,7 @@ import * as React from 'react'
 import Link from 'next/link'
 import { Pencil, Plus } from 'lucide-react'
 import { useParams, useRouter } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Page, PageBody, PageHeader } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'

package/src/modules/billing/backend/billing/accounts/page.tsx

@@ -3,7 +3,7 @@ import * as React from 'react'
 import Link from 'next/link'
 import { useRouter } from 'next/navigation'
 import { Plus } from 'lucide-react'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'

package/src/modules/billing/backend/billing/invoices/[id]/page.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import Link from 'next/link'
 import { useParams } from 'next/navigation'
-import type { ColumnDef } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { Pencil, Plus, Trash2 } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { Page, PageBody, PageHeader } from '@open-mercato/ui/backend/Page'