@dainamite/billing 0.17.0

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

@@ -0,0 +1,97 @@
+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 { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'
+import { billingEntityIds } from '../../../data/entityIds'
+import {
+  billingInvoiceAddLineSchema,
+  billingInvoiceEditLineSchema,
+  billingInvoiceRemoveLineSchema,
+} from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+/**
+ * `POST /api/billing/invoices/edit-line` — edits one line of a draft
+ * invoice. Refuses non-drafts (409 / `billing.invoice.not_draft`).
+ * Writes a `DraftInvoiceEdit` audit row per spec. Recomputes invoice
+ * totals from the surviving lines after the edit.
+ *
+ * Operator surface: route is gated by `billing.invoice.edit_draft`.
+ * Future Phase 4c admin UI calls into the same command via this route.
+ */
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.edit_draft'] },
+}
+
+export const metadata = routeMetadata
+
+const editLineResponseSchema = z.object({
+  invoiceId: z.string().uuid(),
+  invoiceLineId: z.string().uuid(),
+  auditId: z.string().uuid(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: SalesInvoice,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.draftInvoiceEdit,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.invoices.edit_draft_line',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingInvoiceEditLineSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        invoiceId: result?.invoiceId ?? null,
+        invoiceLineId: result?.invoiceLineId ?? null,
+        auditId: result?.auditId ?? null,
+      }),
+      status: 200,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingInvoiceLineEdit',
+  pluralName: 'BillingInvoiceLineEdits',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingInvoiceEditLineSchema,
+    responseSchema: editLineResponseSchema,
+    description:
+      'Edits one line of a draft invoice (description, quantity, ' +
+      "unit_price, or explicit `totalNetAmount` override). Writes a " +
+      '`DraftInvoiceEdit` audit row with before+after snapshots and ' +
+      'recomputes invoice totals. Refuses non-draft invoices with ' +
+      'HTTP 409 + `billing.invoice.not_draft`.',
+  },
+})
+
+// Re-export the add/remove route schemas so the OpenAPI bundle keeps
+// them discoverable from a single import surface — the dedicated
+// routes (sibling folders) own the actual handlers.
+export const _phaseSchemaRefs = {
+  add: billingInvoiceAddLineSchema,
+  remove: billingInvoiceRemoveLineSchema,
+}

package/src/modules/billing/api/invoices/post/route.ts

@@ -0,0 +1,97 @@
+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 { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'
+import { billingEntityIds } from '../../../data/entityIds'
+import { billingInvoicePostSchema } from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+/**
+ * `POST /api/billing/invoices/post`
+ *
+ * Operator action: flip a billing-drafted invoice from `draft` →
+ * `posted`. The command refuses non-draft inputs (409 with
+ * `billing.invoice.not_draft`) and test-mode invoices (409 with
+ * `billing.invoice.test_run`). The invoice number is NOT re-assigned
+ * (it was set at draft create — see Phase 2 deviation note in the
+ * spec).
+ *
+ * Implemented as a create-only `makeCrudRoute` so it inherits the same
+ * RBAC + OpenAPI plumbing as the rest of the billing surface. The
+ * `entity` is `SalesInvoice` only because the factory requires one;
+ * the GET half is never exposed on this URL.
+ */
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.post'] },
+}
+
+export const metadata = routeMetadata
+
+const postResponseSchema = z.object({
+  invoiceId: z.string().uuid(),
+  invoiceNumber: z.string(),
+  status: z.literal('posted'),
+  lineCount: z.number().int().nonnegative(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: SalesInvoice,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    // `entityId` is technically a core/sales concept, but the factory
+    // only needs it as an identifier — using a billing-namespaced one
+    // keeps the registry tidy (no surprise list endpoints).
+    entityId: billingEntityIds.draftInvoiceEdit,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.invoices.post',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingInvoicePostSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        invoiceId: result?.invoiceId ?? null,
+        invoiceNumber: result?.invoiceNumber ?? null,
+        status: result?.status ?? null,
+        lineCount: result?.lineCount ?? 0,
+      }),
+      status: 200,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingInvoicePost',
+  pluralName: 'BillingInvoicePosts',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingInvoicePostSchema,
+    responseSchema: postResponseSchema,
+    description:
+      'Flips a billing-drafted `core/sales` invoice from `draft` to ' +
+      '`posted`. Refuses non-draft invoices (409 / ' +
+      '`billing.invoice.not_draft`) and test-mode invoices (409 / ' +
+      '`billing.invoice.test_run`). Fires `billing.invoice.posted` + ' +
+      'one `billing.invoice.line_posted` per line. The invoice number ' +
+      'is NOT re-assigned (set at draft create — see Phase 2 deviation).',
+  },
+})

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

@@ -0,0 +1,75 @@
+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 { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'
+import { billingEntityIds } from '../../../data/entityIds'
+import { billingInvoiceRemoveLineSchema } from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.edit_draft'] },
+}
+
+export const metadata = routeMetadata
+
+const removeLineResponseSchema = z.object({
+  invoiceId: z.string().uuid(),
+  invoiceLineId: z.string().uuid(),
+  auditId: z.string().uuid(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: SalesInvoice,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.draftInvoiceEdit,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.invoices.remove_draft_line',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingInvoiceRemoveLineSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        invoiceId: result?.invoiceId ?? null,
+        invoiceLineId: result?.invoiceLineId ?? null,
+        auditId: result?.auditId ?? null,
+      }),
+      status: 200,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingInvoiceLineRemove',
+  pluralName: 'BillingInvoiceLineRemoves',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingInvoiceRemoveLineSchema,
+    responseSchema: removeLineResponseSchema,
+    description:
+      'Removes one line from a draft invoice (hard delete — the line ' +
+      'never existed as far as future readers are concerned). Writes ' +
+      'a `DraftInvoiceEdit` audit row (action=`line_removed`, ' +
+      '`after_json=null`) carrying the before-snapshot for forensics. ' +
+      'Recomputes invoice totals. Refuses non-draft invoices.',
+  },
+})

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

@@ -0,0 +1,167 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+
+/**
+ * `GET /api/billing/invoices`
+ *
+ * Lists `core/sales` invoices that the billing engine emitted (i.e.
+ * carry `metadata.bill_run_id`). Hand-rolled rather than wrapped via
+ * `makeCrudRoute` because the filter predicate is a JSONB
+ * `metadata->>'bill_run_id' IS NOT NULL` check that doesn't map
+ * cleanly onto the factory's `where`-shaped filter API, and the
+ * entity itself is owned by `core/sales` — keeping the surface
+ * read-only and hand-rolled avoids surprising the cross-module
+ * reviewer.
+ *
+ * Filters:
+ *   - `status` — draft / posted / paid / void
+ *   - `billRunId` — exact match on `metadata->>'bill_run_id'`
+ *   - `billAccountId` — exact match on `metadata->>'bill_account_id'`
+ *   - `testRun=true|false` — flips the `metadata->>'test_run'` filter
+ *   - `search` — substring on invoice_number
+ *
+ * Sort: started_at DESC (most recent first). Pagination: standard
+ * page / pageSize (capped at 100).
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.invoice.view'] },
+}
+
+const querySchema = z
+  .object({
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(50),
+    status: z.enum(['draft', 'posted', 'paid', 'void']).optional(),
+    billRunId: z.string().uuid().optional(),
+    billAccountId: z.string().uuid().optional(),
+    testRun: z.coerce.boolean().optional(),
+    search: z.string().optional(),
+  })
+  .passthrough()
+
+type BillingInvoiceRow = {
+  id: string
+  invoice_number: string
+  status: string | null
+  currency_code: string
+  issue_date: string | null
+  due_date: string | null
+  subtotal_net_amount: string
+  grand_total_net_amount: string
+  grand_total_gross_amount: string
+  paid_total_amount: string
+  outstanding_amount: string
+  metadata: Record<string, unknown> | null
+  created_at: string
+  updated_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 = (auth as { orgId?: string }).orgId ?? null
+    if (!organizationId) {
+      return NextResponse.json(
+        { error: 'Organization scope required' },
+        { status: 403 },
+      )
+    }
+
+    const url = new URL(req.url)
+    const query = querySchema.parse(
+      Object.fromEntries(url.searchParams.entries()),
+    )
+
+    const em = (container.resolve('em') as EntityManager).fork()
+
+    // Build the predicate. `jsonb_exists(metadata, 'bill_run_id')` is
+    // the function form of the JSONB `?` "key exists" operator — the
+    // operator form cannot be used here because `em.execute` treats a
+    // literal `?` as a positional parameter placeholder. Keeps us
+    // narrow to billing-managed invoices, never bleeding into invoices
+    // written by other modules.
+    const whereClauses: string[] = [
+      'tenant_id = ?',
+      'organization_id = ?',
+      'deleted_at IS NULL',
+      "jsonb_exists(metadata, 'bill_run_id')",
+    ]
+    const params: unknown[] = [auth.tenantId, organizationId]
+
+    if (query.status) {
+      whereClauses.push('status = ?')
+      params.push(query.status)
+    }
+    if (query.billRunId) {
+      whereClauses.push("metadata->>'bill_run_id' = ?")
+      params.push(query.billRunId)
+    }
+    if (query.billAccountId) {
+      whereClauses.push("metadata->>'bill_account_id' = ?")
+      params.push(query.billAccountId)
+    }
+    if (typeof query.testRun === 'boolean') {
+      if (query.testRun) {
+        whereClauses.push("metadata->>'test_run' = 'true'")
+      } else {
+        whereClauses.push("(metadata->>'test_run' IS NULL OR metadata->>'test_run' != 'true')")
+      }
+    }
+    if (typeof query.search === 'string' && query.search.trim()) {
+      whereClauses.push('invoice_number ILIKE ?')
+      params.push(`%${query.search.trim().replace(/[%_]/g, (m) => `\\${m}`)}%`)
+    }
+
+    const whereSql = whereClauses.join(' AND ')
+    const countRows = (await em.execute(
+      `SELECT COUNT(*)::int AS total FROM sales_invoices WHERE ${whereSql}`,
+      params,
+    )) as unknown as Array<{ total: number }>
+    const total = countRows?.[0]?.total ?? 0
+
+    const offset = (query.page - 1) * query.pageSize
+    const itemRows = (await em.execute(
+      `SELECT id, invoice_number, status, currency_code, issue_date, due_date,
+              subtotal_net_amount, grand_total_net_amount, grand_total_gross_amount,
+              paid_total_amount, outstanding_amount, metadata, created_at, updated_at
+       FROM sales_invoices
+       WHERE ${whereSql}
+       ORDER BY created_at DESC
+       LIMIT ? OFFSET ?`,
+      [...params, query.pageSize, offset],
+    )) as unknown as BillingInvoiceRow[]
+
+    return NextResponse.json({
+      items: itemRows,
+      total,
+      page: query.page,
+      pageSize: query.pageSize,
+      totalPages: total === 0 ? 1 : Math.ceil(total / query.pageSize),
+    })
+  } catch (err) {
+    console.error('[billing/invoices.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'List billing-managed invoices',
+      description:
+        'Returns a paginated list of `core/sales` invoices that the ' +
+        'billing engine emitted (matched via `metadata->>\'bill_run_id\'` ' +
+        'presence). Supports status / billRunId / billAccountId / testRun ' +
+        '/ invoice_number search filters.',
+    },
+  },
+}

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

@@ -0,0 +1,92 @@
+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 { BillingItem } from '../../../data/entities'
+import { billingEntityIds } from '../../../data/entityIds'
+import { billingItemBulkCreateSchema } from '../../../data/validators'
+import { createBillingCrudOpenApi } from '../../openapi'
+
+/**
+ * `POST /api/billing/items/bulk` — batch-create Billing Items.
+ *
+ * One scope envelope, up to 500 item payloads. Idempotent per
+ * `source_ref` with a *single* batched existence check, then a
+ * single flush. The CPQ connector's subscription-activated /
+ * -amended / -renewed subscribers are the primary callers — bulk
+ * collapses what used to be one `billing.items.create` round-trip
+ * per charge.
+ */
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.item.manage'] },
+}
+
+export const metadata = routeMetadata
+
+const bulkResultEntrySchema = z.object({
+  sourceRef: z.string().nullable(),
+  id: z.string().uuid(),
+  deduplicated: z.boolean(),
+})
+
+const bulkResponseSchema = z.object({
+  created: z.number().int().nonnegative(),
+  deduplicated: z.number().int().nonnegative(),
+  items: z.array(bulkResultEntrySchema),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingItem,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.item,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    create: {
+      commandId: 'billing.items.bulk_create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingItemBulkCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        created: result?.created ?? 0,
+        deduplicated: result?.deduplicated ?? 0,
+        items: result?.items ?? [],
+      }),
+      status: 200,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingItemBulkCreate',
+  pluralName: 'BillingItemBulkCreates',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingItemBulkCreateSchema,
+    responseSchema: bulkResponseSchema,
+    description:
+      'Batch-creates up to 500 Billing Items under one scope envelope. ' +
+      'Idempotent per `sourceRef` (one batched existence check). ' +
+      'Returns `{ created, deduplicated, items: [{ sourceRef, id, ' +
+      'deduplicated }] }`. Always HTTP 200 — duplicates are reported ' +
+      'in the body, never an error.',
+  },
+})