@dainamite/billing 0.20.0 → 0.22.0

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

@@ -0,0 +1,80 @@
+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 { BillingInvoice } from '../../../../data/entities'
+import { getInvoicePdf } from '../../../../lib/pdf/invoicePdf'
+import { INVOICE_LANGUAGE_CODES } from '../../../../lib/invoiceLanguages'
+
+/**
+ * `GET /api/billing/invoices/[id]/pdf` — the document PDF (Spec B).
+ *
+ * Posted documents: the frozen attachment (rendered and frozen on first
+ * request if freezing failed at post). Drafts / test documents: a live
+ * render with a DRAFT / TEST watermark, never stored. `?download=1` forces
+ * an attachment disposition; otherwise the browser shows it inline.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.invoice.view'] },
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  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 { id } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+    const invoice = await em.findOne(BillingInvoice, {
+      id,
+      tenantId: auth.tenantId,
+      organizationId,
+      deletedAt: null,
+    } as never)
+    if (!invoice) {
+      return NextResponse.json({ error: 'Invoice not found' }, { status: 404 })
+    }
+    const pdf = await getInvoicePdf(em, invoice)
+    const download = new URL(req.url).searchParams.get('download') === '1'
+    return new NextResponse(Buffer.from(pdf.bytes), {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/pdf',
+        'Content-Length': String(pdf.bytes.byteLength),
+        'Content-Disposition': `${download ? 'attachment' : 'inline'}; filename="${pdf.fileName}"`,
+        // Drafts change with every edit; frozen documents never do.
+        'Cache-Control': pdf.frozen ? 'private, max-age=300' : 'no-store',
+        'X-Content-Type-Options': 'nosniff',
+      },
+    })
+  } catch (err) {
+    console.error('[billing/invoices/[id]/pdf.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Download a billing document PDF',
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } },
+        { name: 'download', in: 'query', required: false, schema: { type: 'string', enum: ['1'] } },
+      ],
+      description:
+        '`application/pdf`. Posted documents return the PDF frozen at post (an attachment); drafts ' +
+        'and test documents are rendered live with a DRAFT / TEST watermark and never stored. ' +
+        `Labels follow the account invoice language (${INVOICE_LANGUAGE_CODES.join(' / ')}).`,
+      responses: [{ status: 200, description: 'PDF document (`application/pdf`)' }],
+      errors: [{ status: 404, description: 'Invoice not found in this organization' }],
+    },
+  },
+}

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

@@ -2,57 +2,20 @@ 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 { daysOverdueSql, isoDay } from '../../../lib/overdue'
 
 /**
- * `GET /api/billing/invoices/[id]` — billing-invoice detail.
- *
- * Returns the `core/sales` invoice row + its lines, but only if the
- * invoice is billing-managed (carries `metadata.bill_run_id`). Other
- * `core/sales` invoices return 404 here even though the same UUID
- * resolves at `/api/sales/invoices/[id]` — this endpoint is the
- * billing operator's surface, scoped to the billing universe.
+ * `GET /api/billing/invoices/[id]` — one billing document with its lines
+ * (Spec 0: `billing_invoices` / `billing_invoice_lines`). Documents of other
+ * modules are never reachable here.
  */
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['billing.invoice.view'] },
 }
 
-type InvoiceRow = {
-  id: string
-  invoice_number: string
-  status: string | null
-  status_entry_id: string | null
-  currency_code: string
-  issue_date: string | null
-  due_date: string | null
-  subtotal_net_amount: string
-  subtotal_gross_amount: string
-  discount_total_amount: string
-  tax_total_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
-}
-
-type InvoiceLineRow = {
-  id: string
-  line_number: number
-  kind: string
-  description: string | null
-  quantity: string
-  currency_code: string
-  unit_price_net: string
-  unit_price_gross: string
-  tax_rate: string
-  tax_amount: string
-  total_net_amount: string
-  total_gross_amount: string
-  metadata: Record<string, unknown> | null
-}
+type InvoiceRow = Record<string, unknown> & { id: string; bill_account_id: string }
+type InvoiceLineRow = Record<string, unknown> & { id: string }
 
 export async function GET(
   req: Request,
@@ -75,21 +38,20 @@ export async function GET(
     const { id: invoiceId } = await params
     const em = (container.resolve('em') as EntityManager).fork()
 
+    const today = isoDay(new Date())
     const invoiceRows = (await em.execute(
-      `SELECT id, invoice_number, status, status_entry_id, currency_code,
-              issue_date, due_date,
-              subtotal_net_amount, subtotal_gross_amount,
-              discount_total_amount, tax_total_amount,
-              grand_total_net_amount, grand_total_gross_amount,
-              paid_total_amount, outstanding_amount,
-              metadata, created_at, updated_at
-       FROM sales_invoices
-       WHERE id = ?
-         AND tenant_id = ?
-         AND organization_id = ?
-         AND deleted_at IS NULL
-         AND jsonb_exists(metadata, 'bill_run_id')`,
-      [invoiceId, auth.tenantId, organizationId],
+      `SELECT i.id, i.number, i.document_type, i.series, i.status, i.test_run, i.bill_account_id,
+              a.name AS bill_account_name, i.bill_run_id, i.bill_date, i.period_start, i.period_end,
+              i.issue_date, i.due_date, i.posted_at, i.currency_code, i.subtotal_net, i.tax_total,
+              i.total_gross, i.paid_total, i.credited_total, i.outstanding, i.corrects_invoice_id,
+              i.correction_reason, i.corrects_invoice_number, i.corrects_issue_date,
+              i.buyer_snapshot, i.seller_snapshot, i.topup_id, i.metadata,
+              i.pdf_attachment_id, ${daysOverdueSql('i')}::int AS days_overdue,
+              i.created_at, i.updated_at
+       FROM billing_invoices i
+       LEFT JOIN billing_accounts a ON a.id = i.bill_account_id AND a.tenant_id = i.tenant_id
+       WHERE i.id = ? AND i.tenant_id = ? AND i.organization_id = ? AND i.deleted_at IS NULL`,
+      [today, today, invoiceId, auth.tenantId, organizationId],
     )) as unknown as InvoiceRow[]
 
     if (!invoiceRows || invoiceRows.length === 0) {
@@ -99,20 +61,44 @@ export async function GET(
     const invoice = invoiceRows[0]
 
     const lineRows = (await em.execute(
-      `SELECT id, line_number, kind, description, quantity, currency_code,
-              unit_price_net, unit_price_gross, tax_rate, tax_amount,
-              total_net_amount, total_gross_amount, metadata
-       FROM sales_invoice_lines
-       WHERE invoice_id = ?
-         AND tenant_id = ?
-         AND organization_id = ?
+      `SELECT id, line_number, billing_item_id, billing_type, description, quantity,
+              unit_price_net, tax_rate, net_amount, tax_amount, gross_amount,
+              service_period_start, service_period_end, corrects_line_id, metadata
+       FROM billing_invoice_lines
+       WHERE invoice_id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL
        ORDER BY line_number ASC`,
       [invoiceId, auth.tenantId, organizationId],
     )) as unknown as InvoiceLineRow[]
 
+    // Spec C: what settled this receivable (payments; Spec D adds credit memos).
+    const allocations = await em.execute(
+      `SELECT al.id, al.source_type, al.source_id, al.amount, al.currency_code, al.allocated_by, al.created_at,
+              CASE WHEN al.source_type = 'payment' THEN COALESCE(p.reference, p.payer_name)
+                   ELSE m.number END AS source_label,
+              p.received_at AS payment_received_at
+         FROM billing_allocations al
+         LEFT JOIN billing_payments p ON al.source_type = 'payment' AND p.id = al.source_id
+         LEFT JOIN billing_invoices m ON al.source_type = 'credit_memo' AND m.id = al.source_id
+        WHERE al.invoice_id = ? AND al.tenant_id = ? AND al.organization_id = ? AND al.deleted_at IS NULL
+        ORDER BY al.created_at ASC`,
+      [invoiceId, auth.tenantId, organizationId],
+    )
+
+    // Spec D: memos correcting this document.
+    const corrections = await em.execute(
+      `SELECT id, number, document_type, status, total_gross, outstanding, currency_code, correction_reason, created_at
+         FROM billing_invoices
+        WHERE corrects_invoice_id = ? AND tenant_id = ? AND organization_id = ? AND deleted_at IS NULL
+        ORDER BY created_at ASC`,
+      [invoiceId, auth.tenantId, organizationId],
+    )
+
     return NextResponse.json({
+      corrections,
+      allocations,
       invoice,
-      lines: lineRows,
+      // Lines carry the document currency for display convenience.
+      lines: lineRows.map((line) => ({ ...line, currency_code: invoice.currency_code })),
     })
   } catch (err) {
     console.error('[billing/invoices/[id].GET]', err)
@@ -124,12 +110,13 @@ export const openApi = {
   methods: {
     GET: {
       tags: ['Billing'],
-      summary: 'Get a billing-managed invoice (with lines)',
+      summary: 'Get a billing document (with lines)',
       description:
-        'Returns the `core/sales` invoice + every line, scoped to ' +
-        "billing-managed invoices (`metadata.bill_run_id` set). Non-" +
-        'billing invoices return 404 even when the UUID resolves at ' +
-        '`/api/sales/invoices/[id]`.',
+        'Returns one billing document from `billing_invoices` (invoice, memo or receipt) with its ' +
+        'lines, the frozen buyer / seller snapshots, `bill_account_name` and `allocations[]` (Spec C: ' +
+        'payments / credit memos that settled it, with `source_label`) and `corrections[]` (Spec D memos). ' +
+        '404 outside the ' +
+        'caller\'s organization.',
       parameters: [
         {
           name: 'id',

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

@@ -0,0 +1,127 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+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 type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { bridgeLegacyGuard, runMutationGuards } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import type { SendInvoiceResult } from '../../../../lib/invoiceDelivery'
+
+/**
+ * `POST /api/billing/invoices/[id]/send` — emails a posted billing document
+ * with its frozen PDF to the account's invoice email (Spec B), via the
+ * `billing.invoices.send` command.
+ *
+ * 200 `{ invoiceId, to, status: 'sent' | 'failed', error }` — a transport
+ * failure is a recorded `failed` delivery, not an HTTP error.
+ * 409 `billing.invoice.not_posted` (draft / test). 422
+ * `billing.invoice.email_invalid` (placeholder or malformed address).
+ */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.send'] },
+}
+
+function userFeatures(auth: unknown): string[] {
+  const features = (auth as { features?: unknown })?.features
+  return Array.isArray(features) ? features.filter((value): value is string => typeof value === 'string') : []
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  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 { id } = await params
+    const ctx: CommandRuntimeContext = {
+      container,
+      auth,
+      organizationScope: null,
+      selectedOrganizationId: organizationId,
+      organizationIds: [organizationId],
+      request: req,
+    }
+    // Custom write route → run the shared mutation guards (record locks etc.)
+    // as `update` on the invoice before sending.
+    const guardInput = {
+      tenantId: auth.tenantId,
+      organizationId,
+      userId: auth.sub ?? '',
+      resourceKind: 'billing.invoice',
+      resourceId: id,
+      operation: 'update' as const,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    }
+    const legacyGuard = bridgeLegacyGuard(container)
+    const guardResult = legacyGuard
+      ? await runMutationGuards([legacyGuard], guardInput, { userFeatures: userFeatures(auth) })
+      : { ok: true as const, afterSuccessCallbacks: [] }
+    if (!guardResult.ok) {
+      return NextResponse.json(guardResult.errorBody ?? { error: 'Operation blocked by guard' }, {
+        status: guardResult.errorStatus ?? 422,
+      })
+    }
+
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const response = await commandBus.execute('billing.invoices.send', {
+      input: { tenantId: auth.tenantId, organizationId, invoiceId: id },
+      ctx,
+    })
+    const result = (response as { result?: SendInvoiceResult }).result
+    for (const callback of guardResult.afterSuccessCallbacks) {
+      if (!callback.guard.afterSuccess) continue
+      try {
+        await callback.guard.afterSuccess({ ...guardInput, metadata: callback.metadata ?? null })
+      } catch (err) {
+        console.error('[billing/invoices/[id]/send.POST] guard afterSuccess failed', err)
+      }
+    }
+    return NextResponse.json(result ?? { invoiceId: id, status: 'failed', error: null })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    console.error('[billing/invoices/[id]/send.POST]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Email a posted billing document',
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }],
+      description:
+        'Sends the frozen PDF to the billing account invoice email through the platform email ' +
+        'transport. Each attempt is appended to `metadata.deliveries` and emits ' +
+        '`billing.invoice.sent` / `billing.invoice.send_failed`. Transport failures return ' +
+        '200 with `status: "failed"` and the error.',
+      responses: [
+        {
+          status: 200,
+          description: 'Delivery attempted',
+          schema: z.object({
+            invoiceId: z.string().uuid(),
+            to: z.string(),
+            status: z.enum(['sent', 'failed']),
+            error: z.string().nullable(),
+          }),
+        },
+      ],
+      errors: [
+        { status: 409, description: '`billing.invoice.not_posted` — drafts and test documents cannot be sent' },
+        { status: 422, description: '`billing.invoice.email_invalid` — placeholder or malformed invoice email' },
+      ],
+    },
+  },
+}

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

@@ -2,10 +2,10 @@ 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 } from '../../../data/validators'
 import { createBillingCrudOpenApi } from '../../openapi'
+import { BillingInvoice } from '../../../data/entities'
 
 const routeMetadata = {
   POST: { requireAuth: true, requireFeatures: ['billing.invoice.edit_draft'] },
@@ -24,7 +24,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: SalesInvoice,
+    entity: BillingInvoice,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

package/src/modules/billing/api/invoices/delete-draft/route.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+import { runCommandRoute } from '../../../lib/commandRoute'
+
+/** `POST /api/billing/invoices/delete-draft` — delete a DRAFT credit / debit memo (Spec D, D-D7). */
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.correct'] },
+}
+
+const bodySchema = z.object({ invoiceId: z.string().uuid() })
+
+export async function POST(req: Request) {
+  return runCommandRoute(req, {
+    commandId: 'billing.invoices.delete_draft',
+    bodySchema,
+    resourceKind: 'billing.invoice',
+    resourceId: (body) => body.invoiceId,
+    logLabel: 'billing/invoices/delete-draft.POST',
+  })
+}
+
+export const openApi = {
+  methods: {
+    POST: {
+      tags: ['Billing'],
+      summary: 'Delete a draft memo',
+      description: 'Deletes a draft credit or debit memo with its lines. Posted documents are never deleted (no void).',
+      requestBody: { schema: bodySchema },
+      responses: [{ status: 200, description: '`{ deleted: true }`' }],
+      errors: [{ status: 409, description: '`billing.memo.not_draft`' }],
+    },
+  },
+}

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

@@ -2,7 +2,6 @@ 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,
@@ -10,6 +9,7 @@ import {
   billingInvoiceRemoveLineSchema,
 } from '../../../data/validators'
 import { createBillingCrudOpenApi } from '../../openapi'
+import { BillingInvoice } from '../../../data/entities'
 
 /**
  * `POST /api/billing/invoices/edit-line` — edits one line of a draft
@@ -38,7 +38,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: SalesInvoice,
+    entity: BillingInvoice,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

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

@@ -2,10 +2,10 @@ 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'
+import { BillingInvoice } from '../../../data/entities'
 
 /**
  * `POST /api/billing/invoices/post`
@@ -13,13 +13,14 @@ import { createBillingCrudOpenApi } from '../../openapi'
  * 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).
+ * `billing.invoice.test_run`). The series number is claimed at post
+ * (Spec 0 numbering masks) — drafts carry a temporary `DRAFT-…` number.
+ * 409 `billing.invoice.number_conflict` when the mask repeats an issued
+ * number.
  *
  * 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;
+ * `entity` is `BillingInvoice` only because the factory requires one;
  * the GET half is never exposed on this URL.
  */
 
@@ -41,7 +42,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: SalesInvoice,
+    entity: BillingInvoice,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',

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

@@ -2,10 +2,10 @@ 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'
+import { BillingInvoice } from '../../../data/entities'
 
 const routeMetadata = {
   POST: { requireAuth: true, requireFeatures: ['billing.invoice.edit_draft'] },
@@ -24,7 +24,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: SalesInvoice,
+    entity: BillingInvoice,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',