@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/api/payments/ignore/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/ignore` — ignore a payment (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.ignore',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/ignore.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Ignore a payment',
+      description: 'Excludes an unallocated payment from matching and credit (fees, misdirected transfers). Reversible with restore.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 409, description: '`billing.payment.has_allocations`' },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/payments/import/route.ts

@@ -0,0 +1,72 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { PAYMENT_IMPORT_MAX_BYTES } from '../../../data/validators'
+import { readRequestBody, runCommandRoute } from '../../../lib/commandRoute'
+
+/**
+ * `POST /api/billing/payments/import` — bank CSV upload (Spec C, C-D4).
+ * Accepts `multipart/form-data` (`file`) or JSON `{ fileName, content }`.
+ * 413 over 2 MB. Returns the import summary (counts per outcome + row errors).
+ */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.import'] },
+}
+
+const bodySchema = z.object({
+  fileName: z.string().trim().min(1).max(255),
+  content: z.string().max(PAYMENT_IMPORT_MAX_BYTES),
+})
+
+async function readUpload(req: Request): Promise<unknown | Response> {
+  const declared = Number(req.headers.get('content-length') ?? '0')
+  if (declared > PAYMENT_IMPORT_MAX_BYTES + 64 * 1024) {
+    return NextResponse.json({ error: 'The file is larger than 2 MB', code: 'billing.payment_import.too_large' }, { status: 413 })
+  }
+  if ((req.headers.get('content-type') ?? '').includes('multipart/form-data')) {
+    const form = await req.formData()
+    const file = form.get('file')
+    if (!file || typeof file === 'string') return { fileName: '', content: '' }
+    if (file.size > PAYMENT_IMPORT_MAX_BYTES) {
+      return NextResponse.json({ error: 'The file is larger than 2 MB', code: 'billing.payment_import.too_large' }, { status: 413 })
+    }
+    return { fileName: file.name || 'payments.csv', content: await file.text() }
+  }
+  return readRequestBody(req)
+}
+
+export async function POST(req: Request) {
+  const body = await readUpload(req.clone())
+  if (body instanceof Response) return body
+  return runCommandRoute(
+    req,
+    {
+      commandId: 'billing.payments.import',
+      bodySchema,
+      resourceKind: 'billing.payment_import',
+      resourceId: () => null,
+      logLabel: 'billing/payments/import.POST',
+    },
+    body,
+  )
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Import bank payments from CSV',
+      description:
+        'CSV header `date,amount,currency,reference,payer_name,payer_account` (UTF-8, comma separated, ' +
+        '"." decimals, amount > 0, ≤ 5,000 rows, ≤ 2 MB). Each new row becomes a payment, matched by the ' +
+        'invoice number in `reference`; re-uploaded lines are counted as duplicates. Send multipart `file` or ' +
+        'JSON `{ fileName, content }`.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: '`{ importId, fileName, rowCount, counts, errors[] }`' }],
+      errors: [
+        { status: 400, description: '`billing.payment_import.invalid_file` (header / empty / too many rows)' },
+        { status: 413, description: '`billing.payment_import.too_large`' },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/payments/restore/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/restore` — restore an ignored payment (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.restore',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/restore.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Restore an ignored payment',
+      description: 'Restores an ignored payment to matched (credit applied again) or unmatched.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 409, description: '`billing.payment.not_ignored`' },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,147 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+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 {
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '@open-mercato/shared/lib/auth/organizationScope'
+import { buildQueryParams } from '@open-mercato/shared/lib/crud/query-params'
+import { billingPaymentListQuerySchema } from '../../data/validators'
+import { runCommandRoute } from '../../lib/commandRoute'
+
+/**
+ * `GET /api/billing/payments` — the payment register (Spec C), newest first.
+ * Filters: status, billAccountId, importId, receivedFrom / receivedTo,
+ * search (reference / payer name / payer account). Rows carry the account
+ * name (joined). Hand-written SQL like the invoice list.
+ *
+ * `POST /api/billing/payments` — manual payment entry (`billing.payments.create`).
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.payment.view'] },
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+export type BillingPaymentRow = {
+  id: string
+  received_at: string
+  amount: string
+  currency_code: string
+  reference: string | null
+  payer_name: string | null
+  payer_account: string | null
+  source: string
+  import_id: string | null
+  bill_account_id: string | null
+  bill_account_name: string | null
+  status: string
+  unallocated_amount: string
+  match_reason: string | null
+  topup_id: string | null
+  created_at: string
+}
+
+export async function GET(req: Request) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const organizationId = resolveActiveOrganizationId(auth)
+    if (!organizationId) return organizationScopeRequiredResponse()
+    const query = billingPaymentListQuerySchema.parse(buildQueryParams(new URL(req.url).searchParams))
+    const em = (container.resolve('em') as EntityManager).fork()
+
+    const where: string[] = ['p.tenant_id = ?', 'p.organization_id = ?', 'p.deleted_at IS NULL']
+    const params: unknown[] = [auth.tenantId, organizationId]
+    const filters: Array<[unknown, string]> = [
+      [query.id, 'p.id = ?'],
+      [query.status, 'p.status = ?'],
+      [query.billAccountId, 'p.bill_account_id = ?'],
+      [query.importId, 'p.import_id = ?'],
+      [query.receivedFrom, 'p.received_at >= ?::date'],
+      [query.receivedTo, 'p.received_at <= ?::date'],
+    ]
+    for (const [value, clause] of filters) {
+      if (value === undefined || value === null || value === '') continue
+      where.push(clause)
+      params.push(value)
+    }
+    if (query.search) {
+      const like = `%${query.search.replace(/[%_\\]/g, (m) => `\\${m}`)}%`
+      where.push('(p.reference ILIKE ? OR p.payer_name ILIKE ? OR p.payer_account ILIKE ?)')
+      params.push(like, like, like)
+    }
+    const whereSql = where.join(' AND ')
+    const totalRows = (await em.execute(`SELECT COUNT(*)::int AS total FROM billing_payments p WHERE ${whereSql}`, params)) as unknown as Array<{ total: number }>
+    const total = totalRows?.[0]?.total ?? 0
+    const items = (await em.execute(
+      `SELECT p.id, p.received_at, p.amount, p.currency_code, p.reference, p.payer_name, p.payer_account, p.source,
+              p.import_id, p.bill_account_id, a.name AS bill_account_name, p.status, p.unallocated_amount,
+              p.match_reason, p.topup_id, p.created_at
+         FROM billing_payments p
+         LEFT JOIN billing_accounts a ON a.id = p.bill_account_id AND a.tenant_id = p.tenant_id
+        WHERE ${whereSql}
+        ORDER BY p.received_at DESC, p.created_at DESC
+        LIMIT ? OFFSET ?`,
+      [...params, query.pageSize, (query.page - 1) * query.pageSize],
+    )) as unknown as BillingPaymentRow[]
+    return NextResponse.json({
+      items,
+      total,
+      page: query.page,
+      pageSize: query.pageSize,
+      totalPages: total === 0 ? 1 : Math.ceil(total / query.pageSize),
+    })
+  } catch (err) {
+    if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid query', issues: err.issues }, { status: 400 })
+    console.error('[billing/payments.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+const createBodySchema = z.object({
+  receivedAt: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  amount: z.coerce.number().positive(),
+  currencyCode: z.string().trim().length(3),
+  reference: z.string().trim().max(500).optional(),
+  payerName: z.string().trim().max(255).optional(),
+  payerAccount: z.string().trim().max(64).optional(),
+  billAccountId: z.string().uuid().optional(),
+})
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.create',
+    bodySchema: createBodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: () => null,
+    logLabel: 'billing/payments.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'List billing payments',
+      description:
+        'Payment register (bank CSV lines, manual entries, gateway captures). Filters: status ' +
+        '(`unmatched | matched | partially_allocated | allocated | ignored | converted_to_topup`), billAccountId, ' +
+        'importId, receivedFrom / receivedTo (YYYY-MM-DD), search (reference, payer). pageSize ≤ 100.',
+      query: billingPaymentListQuerySchema,
+    },
+    POST: {
+      tags: ['Billing'],
+      summary: 'Record a payment manually',
+      description:
+        'Creates a manual payment. With `billAccountId` it is matched and applied as credit to the ' +
+        "account's open invoices (oldest due first); otherwise it stays unmatched.",
+      requestBody: { schema: createBodySchema },
+      responses: [{ status: 200, description: '`{ paymentId, status, unallocatedAmount }`' }],
+      errors: [{ status: 409, description: '`billing.payment.currency_mismatch`' }],
+    },
+  },
+}

package/src/modules/billing/api/payments/unallocate/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/unallocate` — remove an allocation (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ allocationId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.unallocate',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.allocationId,
+    logLabel: 'billing/payments/unallocate.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Remove an allocation',
+      description: 'Un-allocates a payment or credit memo allocation (soft delete, history kept). The source\'s unallocated amount is restored and the invoice recomputed.',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 404, description: 'Allocation not found' },
+      ],
+    },
+  },
+}

package/src/modules/billing/api/payments/unassign/route.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/payments/unassign` — unassign a payment (Spec C). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.payment.manage'] },
+}
+
+const bodySchema = z.object({ paymentId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.payments.unassign',
+    bodySchema,
+    resourceKind: 'billing.payment',
+    resourceId: (body) => body.paymentId,
+    logLabel: 'billing/payments/unassign.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Unassign a payment',
+      description: 'Reverses an assignment of a matched payment that has no allocations (status → unmatched).',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Updated payment state' }],
+      errors: [
+        { status: 409, description: '`billing.payment.has_allocations` — un-allocate first' },
+      ],
+    },
+  },
+}

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

@@ -1,9 +1,9 @@
 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 { BillingAccount, BillingRun, BillingRunOutcome, BillingInvoice } from '../../data/entities'
+import { toIsoDate } from '../../lib/dateOnly'
 import { billingEntityIds } from '../../data/entityIds'
 import {
   BILL_RUN_OUTCOME_STATUSES,
@@ -45,8 +45,30 @@ const billRunOutcomeListItemSchema = z.object({
   errorMessage: z.string().nullable(),
   warnings: z.record(z.string(), z.unknown()).nullable(),
   draftInvoiceId: z.string().uuid().nullable(),
+  // Spec A: one entry per bill date processed for the account (catch-up).
+  cycles: z
+    .array(
+      z.object({
+        bill_date: z.string(),
+        period_start: z.string().nullable(),
+        period_end: z.string().nullable(),
+        // Spec F: `charged` = prepaid charges debited from the balance.
+        status: z.enum(['invoiced', 'charged', 'previewed', 'empty', 'skipped_existing']),
+        line_count: z.number(),
+        total_net: z.string(),
+        invoice_id: z.string().uuid().nullable(),
+        invoice_number: z.string().nullable(),
+        // Spec F (prepaid): what left the balance, and the period's statement.
+        total_debit: z.string().optional(),
+        statement_id: z.string().uuid().nullable().optional(),
+      }),
+    )
+    .nullable(),
   bill_account_name: z.string().nullable(),
   invoice_number: z.string().nullable(),
+  /** Spec F: mode and as-of date of the run this outcome belongs to. */
+  run_mode: z.enum(['real', 'test', 'dry']).nullable(),
+  run_as_of_date: z.string().nullable(),
   organizationId: z.string().uuid(),
   tenantId: z.string().uuid(),
   createdAt: z.string(),
@@ -56,7 +78,7 @@ const billRunOutcomeListItemSchema = z.object({
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: BillRunOutcome,
+    entity: BillingRunOutcome,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',
@@ -73,6 +95,7 @@ const crud = makeCrudRoute({
       'error_message',
       'warnings',
       'draft_invoice_id',
+      'cycles',
       'organization_id',
       'tenant_id',
       'created_at',
@@ -107,33 +130,53 @@ const crud = makeCrudRoute({
             .filter((v): v is string => typeof v === 'string' && v.length > 0),
         ),
       )
+      const cycleInvoiceIds = (row: Record<string, unknown>): unknown[] =>
+        Array.isArray(row.cycles)
+          ? (row.cycles as Array<Record<string, unknown>>).map((cycle) => cycle?.invoice_id)
+          : []
       const invoiceIds = Array.from(
         new Set(
           items
-            .map((row) => row.draft_invoice_id)
+            .flatMap((row) => [row.draft_invoice_id, ...cycleInvoiceIds(row)])
             .filter((v): v is string => typeof v === 'string' && v.length > 0),
         ),
       )
-      const [accounts, invoices] = await Promise.all([
+      const runIds = Array.from(
+        new Set(items.map((row) => row.bill_run_id).filter((v): v is string => typeof v === 'string' && v.length > 0)),
+      )
+      const [accounts, invoices, runs] = await Promise.all([
         accountIds.length
           ? em.find(BillingAccount, { id: { $in: accountIds } })
           : [],
         invoiceIds.length
-          ? em.find(SalesInvoice, { id: { $in: invoiceIds } })
+          ? em.find(BillingInvoice, { id: { $in: invoiceIds } })
           : [],
+        // Spec F: the run's mode and as-of date (account Bill runs tab).
+        runIds.length ? em.find(BillingRun, { id: { $in: runIds } }) : [],
       ])
+      const runById = new Map(runs.map((run) => [String(run.id), run] as const))
       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]),
+        invoices.map((i) => [String(i.id), i.number] as [string, unknown]),
       )
       for (const row of items) {
         row.bill_account_name = accountName.get(String(row.bill_account_id)) ?? null
+        const run = runById.get(String(row.bill_run_id))
+        row.run_mode = run ? (run.dryRun ? 'dry' : run.testMode ? 'test' : 'real') : null
+        row.run_as_of_date = run?.asOfDate ? toIsoDate(run.asOfDate) : null
         row.invoice_number =
           typeof row.draft_invoice_id === 'string'
             ? invoiceNumber.get(row.draft_invoice_id) ?? null
             : null
+        if (Array.isArray(row.cycles)) {
+          row.cycles = (row.cycles as Array<Record<string, unknown>>).map((cycle) => ({
+            ...cycle,
+            invoice_number:
+              typeof cycle?.invoice_id === 'string' ? invoiceNumber.get(cycle.invoice_id) ?? null : null,
+          }))
+        }
       }
     },
   },

package/src/modules/billing/api/runs/[id]/post-drafts/route.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+import { readRequestBody, runCommandRoute } from '../../../../lib/commandRoute'
+
+/**
+ * `POST /api/billing/runs/{id}/post-drafts` — post the draft invoices of a
+ * REAL Bill Run, one bounded batch per call (ascending id). Call again with
+ * `afterInvoiceId = nextCursor` until `remaining` is 0. Each invoice is posted
+ * through `billing.invoices.post`; failures are reported per invoice and do
+ * not stop the batch, except incomplete seller settings (`stoppedReason`).
+ */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.post'] },
+}
+
+const paramsSchema = z.object({ id: z.string().uuid() })
+const bodySchema = z.object({
+  afterInvoiceId: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+})
+
+const responseSchema = z.object({
+  posted: z.number().int().nonnegative(),
+  failed: z.array(
+    z.object({ invoiceId: z.string().uuid(), number: z.string(), error: z.string(), code: z.string().nullable() }),
+  ),
+  nextCursor: z.string().uuid().nullable(),
+  remaining: z.number().int().nonnegative(),
+  stoppedReason: z.string().nullable(),
+})
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const parsedParams = paramsSchema.safeParse(await params)
+  if (!parsedParams.success) {
+    return Response.json({ error: 'Invalid Bill Run id', code: 'billing.request.invalid' }, { status: 400 })
+  }
+  const billRunId = parsedParams.data.id
+  return runCommandRoute(
+    req,
+    {
+      commandId: 'billing.runs.post_drafts',
+      bodySchema,
+      resourceKind: 'billing.bill_run',
+      resourceId: () => billRunId,
+      toInput: (body, scope) => ({ ...body, ...scope, billRunId }),
+      logLabel: 'billing/runs/[id]/post-drafts.POST',
+    },
+    await readRequestBody(req),
+  )
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: "Post a real Bill Run's draft invoices (batched)",
+      description:
+        'Posts up to `limit` (default 25, max 100) draft invoices of a real Bill Run, ascending by id. ' +
+        'Pass `nextCursor` back as `afterInvoiceId` until `remaining` is 0. Per-invoice failures are listed in ' +
+        '`failed`; incomplete seller settings stop the batch (`stoppedReason: billing.settings.incomplete`).',
+      pathParams: paramsSchema,
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: 'Batch result', schema: responseSchema }],
+      errors: [
+        { status: 404, description: '`billing.run.not_found`' },
+        { status: 409, description: '`billing.run.running`' },
+        { status: 422, description: '`billing.run.not_real`' },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,59 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/**
+ * `DELETE /api/billing/runs/{id}` — delete a TEST or DRY Bill Run with its
+ * test invoices and outcomes (Spec F, F-D1). Real runs are refused (422).
+ */
+
+export const metadata = {
+  DELETE: { requireAuth: true, requireFeatures: ['billing.run.delete'] },
+}
+
+const paramsSchema = z.object({ id: z.string().uuid() })
+const emptyBodySchema = z.object({}).passthrough()
+
+const deleteResponseSchema = z.object({
+  ok: z.literal(true),
+  invoicesRemoved: z.number().int().nonnegative(),
+})
+
+export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const parsedParams = paramsSchema.safeParse(await params)
+  if (!parsedParams.success) {
+    return Response.json({ error: 'Invalid Bill Run id', code: 'billing.request.invalid' }, { status: 400 })
+  }
+  const billRunId = parsedParams.data.id
+  return runCommandRoute(
+    req,
+    {
+      commandId: 'billing.runs.delete',
+      bodySchema: emptyBodySchema,
+      resourceKind: 'billing.bill_run',
+      resourceId: () => billRunId,
+      operation: 'delete',
+      toInput: (_body, scope) => ({ ...scope, billRunId }),
+      logLabel: 'billing/runs/[id].DELETE',
+    },
+    {},
+  )
+}
+
+export const openApi = {
+  methods: {
+    DELETE: {
+      tags: ['Billing'],
+      summary: 'Delete a test or dry Bill Run',
+      description:
+        'Hard-deletes a test or dry-run Bill Run, its outcomes and the test invoices it wrote (with lines and draft-edit audit rows). ' +
+        'Retry runs that point at it keep existing with their parent link cleared. Real runs are never deleted.',
+      pathParams: paramsSchema,
+      responses: [{ status: 200, description: 'Deleted', schema: deleteResponseSchema }],
+      errors: [
+        { status: 404, description: '`billing.run.not_found`' },
+        { status: 409, description: '`billing.run.running`' },
+        { status: 422, description: '`billing.run.delete_real_forbidden`' },
+      ],
+    },
+  },
+}

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',
@@ -81,7 +81,8 @@ export const openApi = createBillingCrudOpenApi({
     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 ' +
+      'inherits the parent run\'s `asOfDate` (and, like every run, bills all due ' +
+      'cycles up to it); its ' +
       '`parent_run_id` points back at the source. Returns 409 if there ' +
       'are no failed outcomes or if another run is in flight.',
   },