@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/__tests__/commands/runsPostDrafts.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Posting a real run's draft invoices in cursor batches (`billing.runs.post_drafts`).
+ */
+
+jest.mock('../../events', () => ({ emitBillingEvent: jest.fn(async () => undefined) }))
+jest.mock('../../lib/billRunEngine', () => ({ runBillRun: jest.fn() }))
+
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { postDraftsCommand } from '../../commands/runs'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const RUN_ID = '33333333-3333-4333-8333-333333333333'
+const A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const B = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+const C = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc'
+
+type RunRow = { id: string; dryRun: boolean; testMode: boolean; status: string }
+
+function createEnv(opts: { run: RunRow | null; drafts: Array<{ id: string; number: string }>; remaining?: number; failOn?: Record<string, { code: string; error: string }> }) {
+  const posted: string[] = []
+  const executed: Array<{ sql: string; params: unknown[] }> = []
+  const em = {
+    findOne: jest.fn(async () => opts.run),
+    execute: jest.fn(async (sql: string, params: unknown[] = []) => {
+      executed.push({ sql, params })
+      if (sql.includes('COUNT(*)')) return [{ remaining: opts.remaining ?? 0 }]
+      return opts.drafts
+    }),
+    fork: jest.fn((): unknown => em),
+  }
+  const commandBus = {
+    execute: jest.fn(async (_id: string, args: { input: { invoiceId: string } }) => {
+      const failure = opts.failOn?.[args.input.invoiceId]
+      if (failure) throw new CrudHttpError(409, failure)
+      posted.push(args.input.invoiceId)
+      return { result: { status: 'posted' } }
+    }),
+  }
+  const ctx = {
+    container: { resolve: jest.fn((name: string) => (name === 'commandBus' ? commandBus : em)) },
+    auth: { tenantId: TENANT, orgId: ORG },
+    selectedOrganizationId: ORG,
+    organizationIds: [ORG],
+    organizationScope: null,
+  }
+  return { ctx, posted, executed, commandBus }
+}
+
+const realRun: RunRow = { id: RUN_ID, dryRun: false, testMode: false, status: 'completed' }
+const input = { tenantId: TENANT, organizationId: ORG, billRunId: RUN_ID }
+
+describe('postDraftsCommand', () => {
+  it('posts each draft through billing.invoices.post and returns the cursor + remaining', async () => {
+    const env = createEnv({ run: realRun, drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }], remaining: 5 })
+    const result = await postDraftsCommand.execute({ ...input, limit: 2 }, env.ctx as never)
+    expect(env.posted).toEqual([A, B])
+    expect(env.commandBus.execute).toHaveBeenCalledWith('billing.invoices.post', expect.objectContaining({
+      input: { tenantId: TENANT, organizationId: ORG, invoiceId: A },
+    }))
+    expect(result).toEqual({ posted: 2, failed: [], nextCursor: B, remaining: 5, stoppedReason: null })
+    // Draft selection is scoped, real-only and keyset-paged.
+    const select = env.executed[0]
+    expect(select.sql).toContain("status = 'draft'")
+    expect(select.sql).toContain('test_run = false')
+    expect(select.params).toEqual([TENANT, ORG, RUN_ID, null, null, 2])
+  })
+
+  it('reports a failing invoice and carries on with the rest', async () => {
+    const env = createEnv({
+      run: realRun,
+      drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }, { id: C, number: 'DRAFT-C' }],
+      failOn: { [B]: { code: 'billing.invoice.number_conflict', error: 'Number already issued' } },
+    })
+    const result = await postDraftsCommand.execute(input, env.ctx as never)
+    expect(env.posted).toEqual([A, C])
+    expect(result.failed).toEqual([
+      { invoiceId: B, number: 'DRAFT-B', error: 'Number already issued', code: 'billing.invoice.number_conflict' },
+    ])
+    expect(result.nextCursor).toBe(C)
+  })
+
+  it('stops at incomplete seller settings and keeps the starting cursor', async () => {
+    const env = createEnv({
+      run: realRun,
+      drafts: [{ id: A, number: 'DRAFT-A' }, { id: B, number: 'DRAFT-B' }],
+      remaining: 2,
+      failOn: { [A]: { code: 'billing.settings.incomplete', error: 'Fill in the seller details' } },
+    })
+    const result = await postDraftsCommand.execute(input, env.ctx as never)
+    expect(env.commandBus.execute).toHaveBeenCalledTimes(1)
+    expect(result).toMatchObject({ posted: 0, stoppedReason: 'billing.settings.incomplete', nextCursor: null, remaining: 2 })
+  })
+
+  it('refuses test / dry runs (422), running runs (409) and unknown runs (404)', async () => {
+    await expect(
+      postDraftsCommand.execute(input, createEnv({ run: { ...realRun, testMode: true }, drafts: [] }).ctx as never),
+    ).rejects.toMatchObject({ status: 422, body: { code: 'billing.run.not_real' } })
+    await expect(
+      postDraftsCommand.execute(input, createEnv({ run: { ...realRun, status: 'running' }, drafts: [] }).ctx as never),
+    ).rejects.toMatchObject({ status: 409 })
+    await expect(postDraftsCommand.execute(input, createEnv({ run: null, drafts: [] }).ctx as never)).rejects.toMatchObject({
+      status: 404,
+    })
+  })
+})

package/src/modules/billing/__tests__/commands/topups.test.ts

@@ -25,6 +25,8 @@ function makeCtx(em: MockEm, gateway: unknown) {
   return {
     auth: { sub: '99999999-9999-4999-8999-999999999999', tenantId: TENANT, orgId: ORG },
     container: {
+      // E-D1: the gateway is optional — registered only when one is passed.
+      hasRegistration: jest.fn((name: string) => name !== 'paymentGatewayService' || gateway != null),
       resolve: jest.fn((name: string) => {
         if (name === 'em') return em
         if (name === 'dataEngine') return dataEngine
@@ -101,4 +103,13 @@ describe('createTopupCommand', () => {
     expect(result.redirectUrl).toBe('https://pay.example/prior')
     expect(gateway.createPaymentSession).not.toHaveBeenCalled()
   })
+
+  it('returns 501 gateway_unavailable without persisting when payment_gateways is not installed', async () => {
+    const em = createPrepaidMockEm({ account: prepaidAccount(), topup: null })
+    await expect(createTopupCommand.execute(baseInput, makeCtx(em, null) as never)).rejects.toMatchObject({
+      status: 501,
+      body: expect.objectContaining({ code: 'billing.topup.gateway_unavailable' }),
+    })
+    expect(em.persisted.some((e) => (e as { status?: string }).status === 'pending')).toBe(false)
+  })
 })

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

@@ -0,0 +1,326 @@
+/**
+ * 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',
+  [billingEntityIds.invoice]: 'billing_invoices',
+  [billingEntityIds.invoiceLine]: 'billing_invoice_lines',
+  [billingEntityIds.documentSequence]: 'billing_document_sequences',
+  [billingEntityIds.settings]: 'billing_settings',
+  [billingEntityIds.payment]: 'billing_payments',
+  [billingEntityIds.allocation]: 'billing_allocations',
+  [billingEntityIds.paymentImport]: 'billing_payment_imports',
+}
+
+/** 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(17)
+  })
+
+  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)
+  })
+})