@dainamite/billing 0.17.0 → 0.18.0

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

@@ -0,0 +1,123 @@
+import { captureTopup } from '../../lib/topupCapture'
+import { __resetInvoiceStatusCacheForTests } from '../../lib/invoiceStatus'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+const ACCOUNT = {
+  id: 'acct-1',
+  organizationId: 'org-1',
+  tenantId: 'ten-1',
+  currencyCode: 'EUR',
+}
+
+function makeDeps() {
+  return {
+    numberGenerator: {
+      generate: jest.fn(async () => ({ number: 'FV/2026/06/0042', format: 'x', sequence: 42 })),
+    },
+    taxService: {
+      calculateUnitAmounts: jest.fn(async (input: { amount: number }) => ({
+        netAmount: input.amount,
+        grossAmount: input.amount,
+        taxAmount: 0,
+        taxRate: 0,
+      })),
+    },
+  }
+}
+
+function makeTopup(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'topup-1',
+    status: 'pending',
+    amount: '100.0000',
+    paymentId: 'pay-1',
+    providerKey: 'stripe',
+    billAccountId: 'acct-1',
+    tenantId: 'ten-1',
+    organizationId: 'org-1',
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  __resetInvoiceStatusCacheForTests()
+})
+
+describe('captureTopup', () => {
+  it('credits the balance, issues a receipt, and flips the top-up to captured', async () => {
+    const topup = makeTopup()
+    const em = createPrepaidMockEm({
+      topup,
+      balance: { tenantId: 'ten-1', billAccountId: 'acct-1', balance: '0.0000' },
+    })
+    const result = await captureTopup(em as never, makeDeps(), {
+      topup: topup as never,
+      account: ACCOUNT,
+      taxRate: 0,
+      gatewayTransactionId: 'gw-1',
+    })
+
+    expect(result.status).toBe('captured')
+    expect(result.balanceAfter).toBe('100.0000')
+    expect(result.transactionId).toBeTruthy()
+    expect(result.receiptInvoiceId).toBeTruthy()
+    expect(result.invoiceNumber).toBe('FV/2026/06/0042')
+
+    // The credit transaction carries the deterministic source_ref.
+    expect(em.transactions).toHaveLength(1)
+    expect(em.transactions[0].type).toBe('topup')
+    expect(em.transactions[0].amount).toBe('100.0000')
+    expect(em.transactions[0].sourceRef).toBe('topup-pay-1')
+
+    // The top-up itself transitioned + backfilled.
+    expect(topup.status).toBe('captured')
+    expect((topup as Record<string, unknown>).transactionId).toBe(result.transactionId)
+    expect((topup as Record<string, unknown>).receiptInvoiceId).toBe(result.receiptInvoiceId)
+  })
+
+  it('is a no-op on an already-captured top-up (idempotent re-fire)', async () => {
+    const topup = makeTopup({ status: 'captured' })
+    const em = createPrepaidMockEm({
+      topup,
+      balance: { tenantId: 'ten-1', billAccountId: 'acct-1', balance: '100.0000' },
+    })
+    const result = await captureTopup(em as never, makeDeps(), {
+      topup: topup as never,
+      account: ACCOUNT,
+      taxRate: 0,
+    })
+    expect(result.status).toBe('already_captured')
+    expect(em.transactions).toHaveLength(0) // no second credit
+  })
+
+  it('does not double-credit OR issue a second receipt when the source_ref exists', async () => {
+    // Simulates an at-least-once / concurrent re-fire that raced past the stale
+    // status check: the credit dedups AND no second fiscal receipt is minted.
+    const topup = makeTopup({ transactionId: 'txn-prior', receiptInvoiceId: 'inv-prior' })
+    const em = createPrepaidMockEm({
+      topup,
+      balance: { tenantId: 'ten-1', billAccountId: 'acct-1', balance: '100.0000' },
+    })
+    em.transactions.push({
+      id: 'txn-prior',
+      type: 'topup',
+      amount: '100.0000',
+      balanceAfter: '100.0000',
+      sourceRef: 'topup-pay-1',
+      billAccountId: 'acct-1',
+      createdAt: new Date('2026-06-10'),
+    })
+    const deps = makeDeps()
+    const result = await captureTopup(em as never, deps, {
+      topup: topup as never,
+      account: ACCOUNT,
+      taxRate: 0,
+    })
+    expect(result.status).toBe('already_captured')
+    expect(result.balanceAfter).toBe('100.0000') // unchanged — dedup hit
+    expect(result.receiptInvoiceId).toBe('inv-prior') // returns the existing receipt
+    expect(em.transactions).toHaveLength(1) // no new credit transaction
+    // No second fiscal document: the number generator was never called.
+    expect(deps.numberGenerator.generate).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,84 @@
+import { createTopupReceipt, type TopupReceiptDeps } from '../../lib/topupReceipt'
+import { __resetInvoiceStatusCacheForTests } from '../../lib/invoiceStatus'
+import { createPrepaidMockEm } from '../helpers/prepaidMockEm'
+
+const ACCOUNT = {
+  id: 'acct-1',
+  organizationId: 'org-1',
+  tenantId: 'ten-1',
+  currencyCode: 'EUR',
+}
+
+function makeDeps(taxRateOut: number | null): TopupReceiptDeps {
+  return {
+    numberGenerator: {
+      generate: jest.fn(async () => ({
+        number: 'FV/2026/06/0042',
+        format: 'FV/{yyyy}/{mm}/{seq:4}',
+        sequence: 42,
+      })),
+    },
+    taxService: {
+      calculateUnitAmounts: jest.fn(async (input: { amount: number; taxRate?: number | string | null }) => {
+        const rate = typeof input.taxRate === 'number' ? input.taxRate : Number(input.taxRate ?? 0)
+        const gross = input.amount
+        const net = rate > 0 ? gross / (1 + rate / 100) : gross
+        return {
+          netAmount: Math.round(net * 10000) / 10000,
+          grossAmount: Math.round(gross * 10000) / 10000,
+          taxAmount: Math.round((gross - net) * 10000) / 10000,
+          taxRate: taxRateOut,
+        }
+      }),
+    },
+  }
+}
+
+beforeEach(() => {
+  __resetInvoiceStatusCacheForTests()
+})
+
+describe('createTopupReceipt — VAT at top-up (amount is gross)', () => {
+  it('splits 100 gross @ 23% into net + VAT and posts paid', async () => {
+    const em = createPrepaidMockEm()
+    const deps = makeDeps(23)
+    const receipt = await createTopupReceipt(em as never, deps, {
+      account: ACCOUNT,
+      topupId: 'topup-1',
+      paymentId: 'pay-1',
+      amount: '100.0000',
+      taxRate: 23,
+    })
+
+    expect(receipt.invoiceNumber).toBe('FV/2026/06/0042')
+    expect(receipt.grossAmount).toBe('100.0000')
+    expect(receipt.netAmount).toBe('81.3008')
+    expect(receipt.taxAmount).toBe('18.6992')
+    expect(receipt.taxRate).toBe(23)
+
+    // The invoice was persisted as paid with a single top-up line.
+    const invoice = em.persisted.find((e) => (e as { status?: string }).status === 'paid') as Record<
+      string,
+      unknown
+    >
+    expect(invoice).toBeTruthy()
+    expect(invoice.paidTotalAmount).toBe('100.0000')
+    expect(invoice.outstandingAmount).toBe('0')
+    expect((invoice.metadata as Record<string, unknown>).kind).toBe('prepaid_topup')
+  })
+
+  it('0% VAT → net == gross, tax 0', async () => {
+    const em = createPrepaidMockEm()
+    const deps = makeDeps(null)
+    const receipt = await createTopupReceipt(em as never, deps, {
+      account: ACCOUNT,
+      topupId: 'topup-2',
+      paymentId: 'pay-2',
+      amount: '50.0000',
+      taxRate: 0,
+    })
+    expect(receipt.netAmount).toBe('50.0000')
+    expect(receipt.grossAmount).toBe('50.0000')
+    expect(receipt.taxAmount).toBe('0.0000')
+  })
+})

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

@@ -77,8 +77,8 @@ describe('billing setup — contract', () => {
 })
 
 describe('billing acl — surface', () => {
-  it('exports exactly 12 features per Phase 0 spec', () => {
-    expect(features).toHaveLength(12)
+  it('exports exactly 19 features (12 Phase 0 + 7 SPEC-002 prepaid)', () => {
+    expect(features).toHaveLength(19)
   })
 
   it('all feature IDs are prefixed `billing.` (no leaking module boundary)', () => {
@@ -101,7 +101,33 @@ describe('billing acl — surface', () => {
     'billing.invoice.post',
     'billing.invoice.edit_draft',
     'billing.invoice.view',
+    // SPEC-002 prepaid
+    'billing.balance.view',
+    'billing.balance.adjust',
+    'billing.topup.create',
+    'billing.topup.view',
+    'billing.statement.view',
+    'billing.statement.generate',
+    'billing.credit.view',
   ])('declares feature %s', (id) => {
     expect(featureIds.has(id)).toBe(true)
   })
 })
+
+describe('billing setup — prepaid read grants (SPEC-002)', () => {
+  it('billing_finance_user can read prepaid balances, top-ups, statements, credit', () => {
+    const grants = setup.defaultRoleFeatures?.billing_finance_user ?? []
+    expect(grants).toEqual(
+      expect.arrayContaining([
+        'billing.balance.view',
+        'billing.credit.view',
+        'billing.topup.view',
+        'billing.statement.view',
+      ]),
+    )
+    // …but cannot adjust balances or initiate top-ups (read-only persona)
+    expect(grants).not.toContain('billing.balance.adjust')
+    expect(grants).not.toContain('billing.topup.create')
+    expect(grants).not.toContain('billing.statement.generate')
+  })
+})

package/src/modules/billing/acl.ts

@@ -11,6 +11,14 @@ export const features = [
   { id: 'billing.invoice.post', title: 'Post Draft Invoice', module: 'billing' },
   { id: 'billing.invoice.edit_draft', title: 'Edit Draft Invoice', module: 'billing' },
   { id: 'billing.invoice.view', title: 'View Billing Invoices', module: 'billing' },
+  // ─── Prepaid balance billing (SPEC-002) ──────────────────────
+  { id: 'billing.balance.view', title: 'View Balance & Transactions', module: 'billing' },
+  { id: 'billing.balance.adjust', title: 'Adjust Balance (manual credit/debit)', module: 'billing' },
+  { id: 'billing.topup.create', title: 'Initiate Account Top-up', module: 'billing' },
+  { id: 'billing.topup.view', title: 'View Account Top-ups', module: 'billing' },
+  { id: 'billing.statement.view', title: 'View Consumption Statements', module: 'billing' },
+  { id: 'billing.statement.generate', title: 'Generate Consumption Statement', module: 'billing' },
+  { id: 'billing.credit.view', title: 'View Account Credit Status', module: 'billing' },
 ] as const
 
 export default features

package/src/modules/billing/api/accounts/[id]/balance/route.ts

@@ -0,0 +1,74 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { BillingAccount } from '../../../../data/entities'
+import { getBalanceSnapshot } from '../../../../lib/accountStatus'
+
+/**
+ * `GET /api/billing/accounts/[id]/balance` — current prepaid balance, status,
+ * and resolved low-balance threshold (SPEC-002). Read-only.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.balance.view'] },
+}
+
+export async function GET(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  let container: Awaited<ReturnType<typeof createRequestContainer>> | null = null
+  try {
+    container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const organizationId = (auth as { orgId?: string }).orgId ?? null
+    if (!organizationId) {
+      return NextResponse.json({ error: 'Organization scope required' }, { status: 403 })
+    }
+
+    const { id: accountId } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const account = await em.findOne(BillingAccount, {
+      id: accountId,
+      tenantId: auth.tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      return NextResponse.json({ error: 'Account not found' }, { status: 404 })
+    }
+    if (account.billingMode !== 'prepaid') {
+      return NextResponse.json(
+        { error: 'Account is not prepaid', code: 'billing.account.not_prepaid' },
+        { status: 409 },
+      )
+    }
+
+    const snapshot = await getBalanceSnapshot(em, account)
+    return NextResponse.json(snapshot)
+  } catch (err) {
+    console.error('[billing/accounts/balance.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get a prepaid account balance + status',
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
+      ],
+      description:
+        'Returns the current running balance, `balanceStatus` (ok/low/exhausted), ' +
+        'the resolved low-balance threshold, the currency, and the last-movement ' +
+        'timestamp for a prepaid account. 409 (`billing.account.not_prepaid`) for ' +
+        'postpaid accounts.',
+    },
+  },
+}

package/src/modules/billing/api/accounts/[id]/credit-status/route.ts

@@ -0,0 +1,71 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { BillingAccount } from '../../../../data/entities'
+import { getCreditSnapshot } from '../../../../lib/accountStatus'
+
+/**
+ * `GET /api/billing/accounts/[id]/credit-status` — credit limit / used /
+ * available / status for BOTH modes (SPEC-002 P6). Report-only — billing never
+ * blocks; the quote→order flow (e.g. a CPQ credit guard) decides what to do.
+ *
+ *   - prepaid:  credit_used = max(0, −balance)
+ *   - postpaid: credit_used = Σ posted-unpaid invoice outstanding (core/sales)
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.credit.view'] },
+}
+
+export async function GET(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  let container: Awaited<ReturnType<typeof createRequestContainer>> | null = null
+  try {
+    container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const organizationId = (auth as { orgId?: string }).orgId ?? null
+    if (!organizationId) {
+      return NextResponse.json({ error: 'Organization scope required' }, { status: 403 })
+    }
+
+    const { id: accountId } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const account = await em.findOne(BillingAccount, {
+      id: accountId,
+      tenantId: auth.tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      return NextResponse.json({ error: 'Account not found' }, { status: 404 })
+    }
+
+    const snapshot = await getCreditSnapshot(em, account)
+    return NextResponse.json(snapshot)
+  } catch (err) {
+    console.error('[billing/accounts/credit-status.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get an account credit status (both modes)',
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
+      ],
+      description:
+        'Returns `{ mode, creditLimit, creditUsed, availableCredit, creditStatus, ' +
+        'currencyCode }`. Prepaid creditUsed = max(0,−balance); postpaid = Σ ' +
+        'posted-unpaid invoice outstanding. Report-only — billing never blocks.',
+    },
+  },
+}

package/src/modules/billing/api/accounts/[id]/topups/route.ts

@@ -0,0 +1,49 @@
+import { POST as topupsPost } from '../../../topups/route'
+
+/**
+ * `POST /api/billing/accounts/{id}/topups` (SPEC-002 P2).
+ *
+ * Spec-faithful nested path. Injects the path `id` as `billAccountId` into the
+ * body and delegates to the flat `POST /api/billing/topups` handler so all the
+ * RBAC / command-bus / side-effect plumbing lives in exactly one place.
+ */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.topup.create'] },
+}
+
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  const { id } = await params
+  const body = (await req.json().catch(() => ({}))) as Record<string, unknown>
+  const merged = { ...body, billAccountId: id }
+  // Rebuild headers WITHOUT the stale content-length (the body changed); keep
+  // auth (cookies / Authorization) intact and force JSON content-type.
+  const headers = new Headers(req.headers)
+  headers.delete('content-length')
+  headers.set('content-type', 'application/json')
+  const forwarded = new Request(req.url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(merged),
+  })
+  return topupsPost(forwarded)
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Initiate a prepaid top-up for an account',
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
+      ],
+      description:
+        'Registers a BillingTopup (pending) and opens a payment session. The ' +
+        'path `id` is the prepaid account; the balance is credited on capture. ' +
+        'Body: `{ amount, providerKey?, successUrl?, cancelUrl?, sourceRef? }`.',
+    },
+  },
+}

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

@@ -43,6 +43,8 @@ const billingAccountListItemSchema = z.object({
   invoice_address: z.record(z.string(), z.unknown()),
   next_bill_date: z.string(),
   last_bill_date: z.string().nullable(),
+  billing_mode: z.string(),
+  credit_limit: z.string(),
   is_active: z.boolean(),
   organization_id: z.string().uuid(),
   tenant_id: z.string().uuid(),
@@ -79,6 +81,8 @@ const crud = makeCrudRoute({
       'invoice_address',
       'next_bill_date',
       'last_bill_date',
+      'billing_mode',
+      'credit_limit',
       'is_active',
       'organization_id',
       'tenant_id',
@@ -107,6 +111,9 @@ const crud = makeCrudRoute({
       if (typeof query.billCycle === 'string' && query.billCycle) {
         filters.bill_cycle = { $eq: query.billCycle }
       }
+      if (typeof query.billingMode === 'string' && query.billingMode) {
+        filters.billing_mode = { $eq: query.billingMode }
+      }
       if (typeof query.isActive === 'boolean') {
         filters.is_active = { $eq: query.isActive }
       }

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

@@ -4,8 +4,12 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import {
   BillingAccount,
+  BillingAccountBalance,
+  BillingAccountTransaction,
   BillingAccountUsage,
   BillingItem,
+  BillingStatement,
+  BillingTopup,
   BillRunOutcome,
   DraftInvoiceEdit,
 } from '../../../../data/entities'
@@ -83,7 +87,7 @@ export async function GET(
       ?? defaultSince()
     const until = parseDate(url.searchParams.get('until')) ?? new Date()
 
-    const [items, usage, outcomes] = await Promise.all([
+    const [items, usage, outcomes, balance, transactions, topups, statements] = await Promise.all([
       // Items are bounded by integration volume (typically <100 per
       // account); no time-window needed — they often outlive a single
       // export window and the operator needs to see active items
@@ -113,6 +117,41 @@ export async function GET(
         } as never,
         { limit: EXPORT_HARD_LIMIT, orderBy: { createdAt: 'DESC' } },
       ),
+      // SPEC-002 prepaid data — the balance row + the windowed money trail.
+      em.findOne(BillingAccountBalance, {
+        tenantId,
+        billAccountId: account.id,
+      } as never),
+      em.find(
+        BillingAccountTransaction,
+        {
+          tenantId,
+          organizationId,
+          billAccountId: account.id,
+          createdAt: { $gte: since, $lte: until },
+        } as never,
+        { limit: EXPORT_HARD_LIMIT, orderBy: { createdAt: 'DESC' } },
+      ),
+      em.find(
+        BillingTopup,
+        {
+          tenantId,
+          organizationId,
+          billAccountId: account.id,
+          createdAt: { $gte: since, $lte: until },
+        } as never,
+        { limit: EXPORT_HARD_LIMIT, orderBy: { createdAt: 'DESC' } },
+      ),
+      em.find(
+        BillingStatement,
+        {
+          tenantId,
+          organizationId,
+          billAccountId: account.id,
+          periodEnd: { $gte: since, $lte: until },
+        } as never,
+        { limit: EXPORT_HARD_LIMIT, orderBy: { periodEnd: 'DESC' } },
+      ),
     ])
 
     // Invoices created in the window. The `metadata->>'bill_account_id'`
@@ -150,7 +189,8 @@ export async function GET(
 
     return NextResponse.json({
       exportedAt: new Date().toISOString(),
-      schemaVersion: 1,
+      // v2 adds prepaid balance / transactions / top-ups / statements (SPEC-002).
+      schemaVersion: 2,
       tenantId,
       organizationId,
       window: {
@@ -164,6 +204,11 @@ export async function GET(
       runOutcomes: outcomes,
       invoices: invoiceRows,
       draftInvoiceEdits: draftEdits,
+      // SPEC-002 prepaid section.
+      balance,
+      transactions,
+      topups,
+      statements,
     })
   } catch (err) {
     console.error('[billing/export/account.GET]', err)

package/src/modules/billing/api/statements/generate/route.ts

@@ -0,0 +1,78 @@
+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 { BillingStatement } from '../../../data/entities'
+import { billingEntityIds } from '../../../data/entityIds'
+import { billingStatementGenerateSchema } from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+/**
+ * `POST /api/billing/statements/generate` (SPEC-002 P3) — manual statement
+ * generation for a prepaid account. Reuses the Bill Run engine scoped to the
+ * one account (same recurring-charge + anti-duplicate machinery).
+ */
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.statement.generate'] },
+}
+
+export const metadata = routeMetadata
+
+const generateResponseSchema = z.object({
+  statementId: z.string().uuid().nullable(),
+  billRunId: z.string().uuid(),
+  status: z.string(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingStatement,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.statement,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.statements.generate',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingStatementGenerateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        statementId: result?.statementId ?? null,
+        billRunId: result?.billRunId ?? null,
+        status: result?.status ?? null,
+      }),
+      status: 201,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingStatementGenerate',
+  pluralName: 'BillingStatementGenerations',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingStatementGenerateSchema,
+    responseSchema: generateResponseSchema,
+    description:
+      'Generates a consumption statement for a prepaid account by running the ' +
+      'period close (recurring charges → balance + statement) scoped to that ' +
+      'account. Returns the statement id (null when the account is not due).',
+  },
+})