@dainamite/billing 0.17.0

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

@@ -0,0 +1,255 @@
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+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 { BillingAccount, BillingItem } from '../../data/entities'
+import { billingEntityIds } from '../../data/entityIds'
+import {
+  billingItemCreateSchema,
+  billingItemListQuerySchema,
+  billingItemUpdateSchema,
+} from '../../data/validators'
+import {
+  createBillingCrudOpenApi,
+  createPagedListResponseSchema,
+  defaultOkResponseSchema,
+} from '../openapi'
+
+// ─── Auth / RBAC ─────────────────────────────────────────────────
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.item.view'] },
+  POST: { requireAuth: true, requireFeatures: ['billing.item.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['billing.item.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['billing.item.manage'] },
+}
+
+export const metadata = routeMetadata
+
+// The list endpoint projects raw column names — snake_case.
+const billingItemListItemSchema = z.object({
+  id: z.string().uuid(),
+  bill_account_id: z.string().uuid(),
+  bill_account_name: z.string().nullable(),
+  type: z.string(),
+  bill_start_date: z.string(),
+  bill_end_date: z.string().nullable(),
+  description: z.string(),
+  rate_json: z.record(z.string(), z.unknown()),
+  uom_code: z.string().nullable(),
+  subscription_id: z.string().nullable(),
+  subscription_item_id: z.string().nullable(),
+  source_ref: z.string().nullable(),
+  currency_mismatch: z.boolean(),
+  billed_to_date: z.string().nullable(),
+  is_active: z.boolean(),
+  organization_id: z.string().uuid(),
+  tenant_id: z.string().uuid(),
+  created_at: z.string(),
+  updated_at: z.string(),
+})
+
+// Response for create includes `deduplicated` so integrators can tell
+// whether their POST resulted in a new row or hit the idempotency
+// short-circuit on `source_ref`.
+const itemCreateResponseSchema = z.object({
+  id: z.string().uuid().nullable(),
+  deduplicated: z.boolean(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingItem,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: billingItemListQuerySchema,
+    entityId: billingEntityIds.item,
+    fields: [
+      'id',
+      'bill_account_id',
+      'type',
+      'bill_start_date',
+      'bill_end_date',
+      'description',
+      'rate_json',
+      'uom_code',
+      'subscription_id',
+      'subscription_item_id',
+      'source_ref',
+      'currency_mismatch',
+      'billed_to_date',
+      'is_active',
+      'organization_id',
+      'tenant_id',
+      'created_at',
+      'updated_at',
+    ],
+    sortFieldMap: {
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+      billStartDate: 'bill_start_date',
+      billEndDate: 'bill_end_date',
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      // `?id=<uuid>` narrows the list to one row — the detail page
+      // reads a single item through this filter.
+      if (typeof query.id === 'string' && query.id) {
+        filters.id = { $eq: query.id }
+      }
+      if (typeof query.search === 'string' && query.search.trim()) {
+        const pattern = `%${query.search.trim().replace(/[%_]/g, (m) => `\\${m}`)}%`
+        filters.description = { $ilike: pattern }
+      }
+      if (typeof query.billAccountId === 'string' && query.billAccountId) {
+        filters.bill_account_id = { $eq: query.billAccountId }
+      }
+      if (typeof query.type === 'string' && query.type) {
+        filters.type = { $eq: query.type }
+      }
+      if (typeof query.subscriptionId === 'string' && query.subscriptionId) {
+        filters.subscription_id = { $eq: query.subscriptionId }
+      }
+      if (typeof query.isActive === 'boolean') {
+        filters.is_active = { $eq: query.isActive }
+      }
+      // `activeAt=<date>` returns items whose validity window covers
+      // the supplied date (Bill Run engine uses the same predicate
+      // shape internally — see spec "Mid-cycle recurring items").
+      if (query.activeAt instanceof Date) {
+        filters.bill_start_date = { $lte: query.activeAt }
+        filters.$or = [
+          { bill_end_date: null },
+          { bill_end_date: { $gte: query.activeAt } },
+        ]
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'billing.items.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingItemCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        id: result?.id ?? null,
+        deduplicated: Boolean(result?.deduplicated),
+      }),
+      // Idempotent create returns 200 (vs 201). The spec mandates
+      // duplicate POST returns the existing row, never creates a
+      // duplicate — keeping the success status consistent makes
+      // client-side handling trivial.
+      status: 200,
+    },
+    update: {
+      commandId: 'billing.items.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingItemUpdateSchema.parse(scoped)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: 'billing.items.delete',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        // The factory hands delete a `{ body, query }` envelope — the
+        // id may arrive in either, depending on the caller.
+        const envelope = (raw ?? {}) as {
+          body?: Record<string, unknown>
+          query?: Record<string, unknown>
+        }
+        const body = envelope.body ?? {}
+        const query = envelope.query ?? {}
+        const scoped = withScopedPayload(body, ctx, translate)
+        const id =
+          (typeof body.id === 'string' && body.id) ||
+          (typeof query.id === 'string' && query.id) ||
+          null
+        if (!id) {
+          throw new Error('id is required')
+        }
+        return {
+          id,
+          tenantId: (scoped as { tenantId?: string }).tenantId,
+          organizationId: (scoped as { organizationId?: string }).organizationId,
+        }
+      },
+      response: () => ({ ok: true }),
+    },
+  },
+  hooks: {
+    // Items reference their account by FK id only; the list + detail UI
+    // wants the human-readable account name. One bounded query
+    // (≤ pageSize ids) resolves it after the page is fetched.
+    afterList: async (payload: unknown, ctx: unknown) => {
+      const items = ((payload as { items?: unknown[] } | null)?.items ?? []) as Array<
+        Record<string, unknown>
+      >
+      const accountIds = Array.from(
+        new Set(
+          items
+            .map((row) => row.bill_account_id)
+            .filter((v): v is string => typeof v === 'string' && v.length > 0),
+        ),
+      )
+      if (accountIds.length === 0) return
+      const em = (ctx as { container: AwilixContainer }).container.resolve<EntityManager>('em')
+      const accounts = await em.find(BillingAccount, { id: { $in: accountIds } })
+      const nameById = new Map(
+        accounts.map((a) => [String(a.id), a.name] as [string, unknown]),
+      )
+      for (const row of items) {
+        row.bill_account_name = nameById.get(String(row.bill_account_id)) ?? null
+      }
+    },
+  },
+})
+
+const { POST, PUT, DELETE } = crud
+export { POST, PUT, DELETE }
+export const GET = crud.GET
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingItem',
+  pluralName: 'BillingItems',
+  querySchema: billingItemListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billingItemListItemSchema),
+  create: {
+    schema: billingItemCreateSchema,
+    responseSchema: itemCreateResponseSchema,
+    description:
+      'Creates a billing item. Idempotent via `sourceRef`: re-POSTing the same ' +
+      '`(tenantId, billAccountId, sourceRef)` returns the existing row with ' +
+      '`deduplicated: true` instead of creating a duplicate. The unique index ' +
+      'on `(tenant_id, bill_account_id, source_ref)` is the correctness gate.',
+  },
+  update: {
+    schema: billingItemUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description:
+      'Updates a billing item. `type` and `sourceRef` are immutable — to change ' +
+      'either, soft-delete the item and create a new one.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a billing item.',
+  },
+})

package/src/modules/billing/api/openapi.ts

@@ -0,0 +1,33 @@
+import {
+  createCrudOpenApiFactory,
+  createPagedListResponseSchema as createSharedPagedListResponseSchema,
+  defaultCreateResponseSchema,
+  defaultOkResponseSchema,
+  type CrudOpenApiOptions,
+} from '@open-mercato/shared/lib/openapi/crud'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
+import type { ZodTypeAny } from 'zod'
+
+/**
+ * Billing CRUD OpenAPI factory. Every billing API route imports this
+ * and calls it with the resource's `create` / `update` / `del` schemas
+ * — the framework picks up the resulting `openApi` export and merges
+ * it into the global API documentation bundle.
+ */
+const buildBillingCrudOpenApi = createCrudOpenApiFactory({
+  defaultTag: 'Billing',
+  defaultCreateResponseSchema,
+  defaultOkResponseSchema,
+  makeListDescription: ({ pluralLower }) =>
+    `Returns a paginated collection of ${pluralLower} scoped to the authenticated organization.`,
+})
+
+export function createBillingCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {
+  return buildBillingCrudOpenApi(options)
+}
+
+export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
+  return createSharedPagedListResponseSchema(itemSchema, { paginationMetaOptional: true })
+}
+
+export { defaultCreateResponseSchema, defaultOkResponseSchema }

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

@@ -0,0 +1,149 @@
+import { z } from 'zod'
+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 { billingEntityIds } from '../../data/entityIds'
+import {
+  BILL_RUN_OUTCOME_STATUSES,
+} from '../../data/validators'
+import { createBillingCrudOpenApi, createPagedListResponseSchema } from '../openapi'
+
+/**
+ * `GET /api/billing/run-outcomes` — list per-account outcomes,
+ * typically filtered by `billRunId` to populate the "show me what
+ * happened in this run" detail panel.
+ *
+ * Read-only; outcomes are written by the engine itself, never by API
+ * clients.
+ */
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.run.view'] },
+}
+
+export const metadata = routeMetadata
+
+const listQuerySchema = z
+  .object({
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(50),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+    billRunId: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    status: z.enum(BILL_RUN_OUTCOME_STATUSES).optional(),
+  })
+  .passthrough()
+
+const billRunOutcomeListItemSchema = z.object({
+  id: z.string().uuid(),
+  billRunId: z.string().uuid(),
+  billAccountId: z.string().uuid(),
+  status: z.string(),
+  errorMessage: z.string().nullable(),
+  warnings: z.record(z.string(), z.unknown()).nullable(),
+  draftInvoiceId: z.string().uuid().nullable(),
+  bill_account_name: z.string().nullable(),
+  invoice_number: z.string().nullable(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillRunOutcome,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: listQuerySchema,
+    entityId: billingEntityIds.runOutcome,
+    fields: [
+      'id',
+      'bill_run_id',
+      'bill_account_id',
+      'status',
+      'error_message',
+      'warnings',
+      'draft_invoice_id',
+      'organization_id',
+      'tenant_id',
+      'created_at',
+      'updated_at',
+    ],
+    sortFieldMap: {
+      createdAt: 'created_at',
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      if (typeof query.billRunId === 'string') filters.bill_run_id = { $eq: query.billRunId }
+      if (typeof query.billAccountId === 'string') {
+        filters.bill_account_id = { $eq: query.billAccountId }
+      }
+      if (typeof query.status === 'string') filters.status = { $eq: query.status }
+      return filters
+    },
+  },
+  hooks: {
+    // Outcomes reference account + draft invoice by FK id only. The
+    // run detail UI wants names — resolve both in two bounded queries.
+    afterList: async (payload: unknown, ctx: unknown) => {
+      const items = ((payload as { items?: unknown[] } | null)?.items ?? []) as Array<
+        Record<string, unknown>
+      >
+      if (items.length === 0) return
+      const em = (ctx as { container: AwilixContainer }).container.resolve<EntityManager>('em')
+      const accountIds = Array.from(
+        new Set(
+          items
+            .map((row) => row.bill_account_id)
+            .filter((v): v is string => typeof v === 'string' && v.length > 0),
+        ),
+      )
+      const invoiceIds = Array.from(
+        new Set(
+          items
+            .map((row) => row.draft_invoice_id)
+            .filter((v): v is string => typeof v === 'string' && v.length > 0),
+        ),
+      )
+      const [accounts, invoices] = await Promise.all([
+        accountIds.length
+          ? em.find(BillingAccount, { id: { $in: accountIds } })
+          : [],
+        invoiceIds.length
+          ? em.find(SalesInvoice, { id: { $in: invoiceIds } })
+          : [],
+      ])
+      const accountName = new Map(
+        accounts.map((a) => [String(a.id), a.name] as [string, unknown]),
+      )
+      const invoiceNumber = new Map(
+        invoices.map((i) => [String(i.id), i.invoiceNumber] as [string, unknown]),
+      )
+      for (const row of items) {
+        row.bill_account_name = accountName.get(String(row.bill_account_id)) ?? null
+        row.invoice_number =
+          typeof row.draft_invoice_id === 'string'
+            ? invoiceNumber.get(row.draft_invoice_id) ?? null
+            : null
+      }
+    },
+  },
+})
+
+export const GET = crud.GET
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillRunOutcome',
+  pluralName: 'BillRunOutcomes',
+  querySchema: listQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billRunOutcomeListItemSchema),
+})

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

@@ -0,0 +1,88 @@
+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 { billingEntityIds } from '../../../data/entityIds'
+import { billingRunRetryFailedSchema } from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+/**
+ * `POST /api/billing/runs/retry-failed`
+ *
+ * Creates a new Bill Run scoped to the failed-account ids from a parent
+ * run, with `parent_run_id` set on the new run so the retry chain is
+ * traceable. Returns the new run's id + status + outcomes count.
+ *
+ * Implemented as a "create-only" `makeCrudRoute` so the framework's
+ * RBAC + OpenAPI + command-bus plumbing stays consistent with the rest
+ * of the billing surface. The list/get half of the factory is never
+ * exercised on this URL — only POST is exported.
+ */
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.run.trigger'] },
+}
+
+export const metadata = routeMetadata
+
+const retryResponseSchema = z.object({
+  billRunId: z.string().uuid(),
+  status: z.string(),
+  outcomesCount: z.number().int().nonnegative(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillRun,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  // No `list` — POST-only route. Keep a stub so the factory type-checks.
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.run,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.runs.retry_failed',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingRunRetryFailedSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        billRunId: result?.billRunId ?? null,
+        status: result?.status ?? null,
+        outcomesCount: result?.outcomesCount ?? 0,
+      }),
+      status: 201,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillRunRetry',
+  pluralName: 'BillRunRetries',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingRunRetryFailedSchema,
+    responseSchema: retryResponseSchema,
+    description:
+      'Re-runs the failed accounts of an earlier Bill Run. The new run ' +
+      'inherits the parent run\'s `asOfDate` and `catchUp` flag; its ' +
+      '`parent_run_id` points back at the source. Returns 409 if there ' +
+      'are no failed outcomes or if another run is in flight.',
+  },
+})

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

@@ -0,0 +1,170 @@
+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 { billingEntityIds } from '../../data/entityIds'
+import {
+  billingRunListQuerySchema,
+  billingRunTriggerSchema,
+} from '../../data/validators'
+import { createBillingCrudOpenApi, createPagedListResponseSchema } from '../openapi'
+
+/**
+ * `/api/billing/runs` — GET (history list) + POST (manual trigger).
+ *
+ * The triggered-by enum gate:
+ *   - `trigger` feature is required for `real` mode (which mutates
+ *     production state).
+ *   - `dry_run` feature alone is enough for `mode=dry` (finance auditor
+ *     persona). The route-level RBAC check on POST requires `trigger`,
+ *     so dry-run callers must hold both `dry_run` AND `trigger` here —
+ *     a deliberate tightening over what the spec persona table suggests.
+ *
+ *   If we ever want auditors to drive dry-runs without holding `trigger`,
+ *   we split into two routes (POST `/runs` for real, POST `/runs/dry` for
+ *   dry). Postponed until an operator actually asks.
+ */
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.run.view'] },
+  POST: { requireAuth: true, requireFeatures: ['billing.run.trigger'] },
+}
+
+export const metadata = routeMetadata
+
+// The list endpoint projects raw column names — snake_case.
+const billRunListItemSchema = z.object({
+  id: z.string().uuid(),
+  triggered_by: z.string(),
+  parent_run_id: z.string().uuid().nullable(),
+  dry_run: z.boolean(),
+  test_mode: z.boolean(),
+  catch_up: z.boolean(),
+  scoped_account_ids: z.array(z.string().uuid()).nullable(),
+  as_of_date: z.string(),
+  started_at: z.string().nullable(),
+  finished_at: z.string().nullable(),
+  status: z.string(),
+  summary: z.record(z.string(), z.unknown()).nullable(),
+  organization_id: z.string().uuid(),
+  tenant_id: z.string().uuid(),
+  created_at: z.string(),
+  updated_at: z.string(),
+})
+
+const triggerResponseSchema = z.object({
+  billRunId: z.string().uuid(),
+  status: z.string(),
+  outcomesCount: z.number().int().nonnegative(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillRun,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: billingRunListQuerySchema,
+    entityId: billingEntityIds.run,
+    fields: [
+      'id',
+      'triggered_by',
+      'parent_run_id',
+      'dry_run',
+      'test_mode',
+      'catch_up',
+      'scoped_account_ids',
+      'as_of_date',
+      'started_at',
+      'finished_at',
+      'status',
+      'summary',
+      'organization_id',
+      'tenant_id',
+      'created_at',
+      'updated_at',
+    ],
+    sortFieldMap: {
+      startedAt: 'started_at',
+      finishedAt: 'finished_at',
+      asOfDate: 'as_of_date',
+      createdAt: 'created_at',
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      // `?id=<uuid>` narrows the list to one row — the detail page
+      // reads a single Bill Run through this filter.
+      if (typeof query.id === 'string' && query.id) {
+        filters.id = { $eq: query.id }
+      }
+      // Run ids are UUIDs — search matches a pasted id exactly.
+      if (typeof query.search === 'string' && /^[0-9a-fA-F-]{36}$/.test(query.search.trim())) {
+        filters.id = { $eq: query.search.trim() }
+      }
+      if (typeof query.status === 'string') filters.status = { $eq: query.status }
+      if (typeof query.triggeredBy === 'string') filters.triggered_by = { $eq: query.triggeredBy }
+      if (typeof query.parentRunId === 'string') filters.parent_run_id = { $eq: query.parentRunId }
+      if (query.asOfDateFrom instanceof Date) {
+        filters.as_of_date = Object.assign(
+          (filters.as_of_date as Record<string, unknown>) ?? {},
+          { $gte: query.asOfDateFrom },
+        )
+      }
+      if (query.asOfDateTo instanceof Date) {
+        filters.as_of_date = Object.assign(
+          (filters.as_of_date as Record<string, unknown>) ?? {},
+          { $lte: query.asOfDateTo },
+        )
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'billing.runs.trigger',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingRunTriggerSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        billRunId: result?.billRunId ?? null,
+        status: result?.status ?? null,
+        outcomesCount: result?.outcomesCount ?? 0,
+      }),
+      status: 201,
+    },
+    // Runs are append-only — no update / delete on this surface. A
+    // failed run is corrected by triggering a `retry-failed` (separate
+    // route).
+  },
+})
+
+const { POST } = crud
+export { POST }
+export const GET = crud.GET
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillRun',
+  pluralName: 'BillRuns',
+  querySchema: billingRunListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billRunListItemSchema),
+  create: {
+    schema: billingRunTriggerSchema,
+    responseSchema: triggerResponseSchema,
+    description:
+      'Triggers a Bill Run. `mode=real` (default) persists drafts and ' +
+      'advances state; `mode=test` persists test-flagged drafts without ' +
+      'advancing state; `mode=dry` computes everything in memory and ' +
+      'persists nothing. Returns HTTP 409 (`billing.run.lock_busy`) when ' +
+      'another run is in flight for the same tenant.',
+  },
+})