@dainamite/billing 0.17.0

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

@@ -0,0 +1,198 @@
+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 { BillingAccount } from '../../data/entities'
+import { billingEntityIds } from '../../data/entityIds'
+import {
+  billingAccountCreateSchema,
+  billingAccountListQuerySchema,
+  billingAccountUpdateSchema,
+} from '../../data/validators'
+import {
+  createBillingCrudOpenApi,
+  createPagedListResponseSchema,
+  defaultCreateResponseSchema,
+  defaultOkResponseSchema,
+} from '../openapi'
+
+// ─── Auth / RBAC ─────────────────────────────────────────────────
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.account.view'] },
+  POST: { requireAuth: true, requireFeatures: ['billing.account.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['billing.account.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['billing.account.manage'] },
+}
+
+export const metadata = routeMetadata
+
+// ─── List response item shape (informational — used by OpenAPI) ──
+
+// The list endpoint projects raw column names — snake_case.
+const billingAccountListItemSchema = z.object({
+  id: z.string().uuid(),
+  customer_id: z.string(),
+  name: z.string(),
+  currency_code: z.string(),
+  bill_cycle: z.string(),
+  bill_cycle_anchor: z.string(),
+  invoice_email: z.string(),
+  invoice_language: z.string(),
+  tax_id: z.string().nullable(),
+  invoice_address: z.record(z.string(), z.unknown()),
+  next_bill_date: z.string(),
+  last_bill_date: z.string().nullable(),
+  is_active: z.boolean(),
+  organization_id: z.string().uuid(),
+  tenant_id: z.string().uuid(),
+  created_at: z.string(),
+  updated_at: z.string(),
+})
+
+const rawBodySchema = z.object({}).passthrough()
+
+// ─── CRUD route ──────────────────────────────────────────────────
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingAccount,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: billingAccountListQuerySchema,
+    entityId: billingEntityIds.account,
+    fields: [
+      'id',
+      'customer_id',
+      'name',
+      'currency_code',
+      'bill_cycle',
+      'bill_cycle_anchor',
+      'invoice_email',
+      'invoice_language',
+      'tax_id',
+      'invoice_address',
+      'next_bill_date',
+      'last_bill_date',
+      'is_active',
+      'organization_id',
+      'tenant_id',
+      'created_at',
+      'updated_at',
+    ],
+    sortFieldMap: {
+      name: 'name',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+      nextBillDate: 'next_bill_date',
+    },
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      // `?id=<uuid>` narrows the list to one row — the detail page
+      // reads a single account through this filter.
+      if (typeof query.id === 'string' && query.id) {
+        filters.id = { $eq: query.id }
+      }
+      if (typeof query.customerId === 'string' && query.customerId) {
+        filters.customer_id = { $eq: query.customerId }
+      }
+      if (typeof query.currencyCode === 'string' && query.currencyCode) {
+        filters.currency_code = { $eq: query.currencyCode.toUpperCase() }
+      }
+      if (typeof query.billCycle === 'string' && query.billCycle) {
+        filters.bill_cycle = { $eq: query.billCycle }
+      }
+      if (typeof query.isActive === 'boolean') {
+        filters.is_active = { $eq: query.isActive }
+      }
+      if (typeof query.search === 'string' && query.search.trim()) {
+        const pattern = `%${query.search.trim().replace(/[%_]/g, (m) => `\\${m}`)}%`
+        filters.name = { $ilike: pattern }
+      }
+      return filters
+    },
+  },
+  actions: {
+    create: {
+      commandId: 'billing.accounts.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingAccountCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'billing.accounts.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingAccountUpdateSchema.parse(scoped)
+      },
+      response: () => ({ ok: true }),
+    },
+    delete: {
+      commandId: 'billing.accounts.delete',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        // The factory hands delete a `{ body, query }` envelope — the
+        // id may arrive in either, depending on the caller.
+        const envelope = (raw ?? {}) as {
+          body?: Record<string, unknown>
+          query?: Record<string, unknown>
+        }
+        const body = envelope.body ?? {}
+        const query = envelope.query ?? {}
+        const scoped = withScopedPayload(body, ctx, translate)
+        const id =
+          (typeof body.id === 'string' && body.id) ||
+          (typeof query.id === 'string' && query.id) ||
+          null
+        if (!id) {
+          throw new Error('id is required')
+        }
+        return {
+          id,
+          tenantId: (scoped as { tenantId?: string }).tenantId,
+          organizationId: (scoped as { organizationId?: string }).organizationId,
+        }
+      },
+      response: () => ({ ok: true }),
+    },
+  },
+})
+
+const { POST, PUT, DELETE } = crud
+export { POST, PUT, DELETE }
+export const GET = crud.GET
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingAccount',
+  pluralName: 'BillingAccounts',
+  querySchema: billingAccountListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billingAccountListItemSchema),
+  create: {
+    schema: billingAccountCreateSchema,
+    responseSchema: defaultCreateResponseSchema,
+    description: 'Creates a new billing account for a customer.',
+  },
+  update: {
+    schema: billingAccountUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Updates a billing account. `currencyCode` and `customerId` are immutable.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a billing account (sets `deleted_at`).',
+  },
+})

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

@@ -0,0 +1,233 @@
+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,
+  BillingAccountUsage,
+  BillingItem,
+  BillRunOutcome,
+  DraftInvoiceEdit,
+} from '../../../../data/entities'
+
+/**
+ * `GET /api/billing/export/account/[id]` — GDPR portability dump.
+ *
+ * Returns a full JSON serialization of a single Billing Account
+ * including:
+ *   - The account row itself.
+ *   - Every active + soft-deleted `BillingItem` for the account.
+ *   - Every `BillingAccountUsage` record.
+ *   - Every `BillRunOutcome` row referencing the account.
+ *   - Every `core/sales` invoice the engine emitted for the account
+ *     (matched via `metadata->>'bill_account_id'`).
+ *   - Every `DraftInvoiceEdit` audit row for those invoices.
+ *
+ * Scope: the caller's auth tenant/organization is the authority — a
+ * 404 is returned even for valid UUIDs that belong to a different
+ * tenant (no cross-tenant leak).
+ *
+ * Soft-deleted rows are included on purpose: GDPR portability is
+ * about the data we still hold, not just the data the UI shows.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.account.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 tenantId = auth.tenantId
+    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,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!account) {
+      return NextResponse.json({ error: 'Account not found' }, { status: 404 })
+    }
+
+    // Time-window cap for usage records, run outcomes and invoices.
+    //
+    // Scale note: a telco account can carry millions of usage rows.
+    // Returning everything would OOM on the export path. We default
+    // to the last 12 months and let the caller override via `since` /
+    // `until` for full GDPR-compliance dumps (a regulator request that
+    // legitimately needs the lifetime export should set `since=1970-01-01`).
+    // Each query is independently capped by `EXPORT_HARD_LIMIT` so a
+    // single year of pathological volume still returns rather than
+    // hanging.
+    const url = new URL(req.url)
+    const since = parseDate(url.searchParams.get('since'))
+      ?? defaultSince()
+    const until = parseDate(url.searchParams.get('until')) ?? new Date()
+
+    const [items, usage, outcomes] = 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
+      // regardless of when they were created.
+      em.find(
+        BillingItem,
+        { tenantId, organizationId, billAccountId: account.id } as never,
+        { limit: EXPORT_HARD_LIMIT },
+      ),
+      em.find(
+        BillingAccountUsage,
+        {
+          tenantId,
+          organizationId,
+          billAccountId: account.id,
+          periodEnd: { $gte: since, $lte: until },
+        } as never,
+        { limit: EXPORT_HARD_LIMIT, orderBy: { periodEnd: 'DESC' } },
+      ),
+      em.find(
+        BillRunOutcome,
+        {
+          tenantId,
+          organizationId,
+          billAccountId: account.id,
+          createdAt: { $gte: since, $lte: until },
+        } as never,
+        { limit: EXPORT_HARD_LIMIT, orderBy: { createdAt: 'DESC' } },
+      ),
+    ])
+
+    // Invoices created in the window. The `metadata->>'bill_account_id'`
+    // predicate keeps non-billing core/sales invoices out.
+    const invoiceRows = (await em.execute(
+      `SELECT id, invoice_number, status, status_entry_id, issue_date, due_date,
+              currency_code, subtotal_net_amount, grand_total_net_amount,
+              grand_total_gross_amount, paid_total_amount, outstanding_amount,
+              metadata, created_at, updated_at, deleted_at
+       FROM sales_invoices
+       WHERE tenant_id = ?
+         AND organization_id = ?
+         AND deleted_at IS NULL
+         AND metadata->>'bill_account_id' = ?
+         AND created_at >= ?
+         AND created_at <= ?
+       ORDER BY created_at DESC
+       LIMIT ?`,
+      [tenantId, organizationId, account.id, since, until, EXPORT_HARD_LIMIT],
+    )) as unknown as Array<{ id: string }>
+
+    const invoiceIds = invoiceRows.map((r) => r.id)
+    const draftEdits =
+      invoiceIds.length > 0
+        ? await em.find(
+            DraftInvoiceEdit,
+            {
+              tenantId,
+              organizationId,
+              invoiceId: { $in: invoiceIds },
+            } as never,
+            { limit: EXPORT_HARD_LIMIT, orderBy: { createdAt: 'DESC' } },
+          )
+        : []
+
+    return NextResponse.json({
+      exportedAt: new Date().toISOString(),
+      schemaVersion: 1,
+      tenantId,
+      organizationId,
+      window: {
+        since: since.toISOString(),
+        until: until.toISOString(),
+        hardLimit: EXPORT_HARD_LIMIT,
+      },
+      account,
+      items,
+      usage,
+      runOutcomes: outcomes,
+      invoices: invoiceRows,
+      draftInvoiceEdits: draftEdits,
+    })
+  } catch (err) {
+    console.error('[billing/export/account.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+/**
+ * Per-collection cap to keep a single export bounded in size and time
+ * even when the caller asks for `since=1970-01-01`. The full GDPR
+ * lifetime dump for an outlier account requires a follow-up
+ * background-job approach (chunked NDJSON to object storage) — out of
+ * scope for the v1 admin export endpoint.
+ */
+const EXPORT_HARD_LIMIT = 50_000
+
+/**
+ * Default time window for the export — last 12 months. Operators
+ * pulling for routine GDPR requests almost always want a finite
+ * window; the regulator-compliance "lifetime" case overrides via
+ * `?since=1970-01-01`.
+ */
+function defaultSince(): Date {
+  const d = new Date()
+  d.setUTCFullYear(d.getUTCFullYear() - 1)
+  return d
+}
+
+function parseDate(value: string | null | undefined): Date | null {
+  if (!value) return null
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Export a billing account (GDPR portability)',
+      parameters: [
+        {
+          name: 'id',
+          in: 'path',
+          required: true,
+          schema: { type: 'string', format: 'uuid' },
+        },
+        {
+          name: 'since',
+          in: 'query',
+          required: false,
+          description:
+            'ISO timestamp; lower bound for usage / outcomes / invoices windows. Defaults to today − 12 months.',
+          schema: { type: 'string', format: 'date-time' },
+        },
+        {
+          name: 'until',
+          in: 'query',
+          required: false,
+          description: 'ISO timestamp; upper bound. Defaults to now.',
+          schema: { type: 'string', format: 'date-time' },
+        },
+      ],
+      description:
+        "Returns a JSON dump of a single Billing Account: the account itself, every Billing Item (no time cap — items often outlive a single export window), and the Usage records / BillRunOutcomes / emitted core/sales invoices / DraftInvoiceEdit rows whose timestamps fall in the [since, until] window (defaults to the last 12 months). Each collection is independently capped by EXPORT_HARD_LIMIT = 50,000 rows. Lifetime dumps for outlier accounts need a follow-up chunked background-job approach — out of scope for this v1 endpoint.",
+    },
+  },
+}

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

@@ -0,0 +1,143 @@
+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'
+
+/**
+ * `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.
+ */
+
+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
+}
+
+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: invoiceId } = await params
+    const em = (container.resolve('em') as EntityManager).fork()
+
+    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],
+    )) as unknown as InvoiceRow[]
+
+    if (!invoiceRows || invoiceRows.length === 0) {
+      return NextResponse.json({ error: 'Invoice not found' }, { status: 404 })
+    }
+
+    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 = ?
+       ORDER BY line_number ASC`,
+      [invoiceId, auth.tenantId, organizationId],
+    )) as unknown as InvoiceLineRow[]
+
+    return NextResponse.json({
+      invoice,
+      lines: lineRows,
+    })
+  } catch (err) {
+    console.error('[billing/invoices/[id].GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get a billing-managed invoice (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]`.',
+      parameters: [
+        {
+          name: 'id',
+          in: 'path',
+          required: true,
+          schema: { type: 'string', format: 'uuid' },
+        },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,74 @@
+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'
+
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ['billing.invoice.edit_draft'] },
+}
+
+export const metadata = routeMetadata
+
+const addLineResponseSchema = 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.add_draft_line',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return billingInvoiceAddLineSchema.parse(scoped)
+      },
+      response: ({ result }) => ({
+        invoiceId: result?.invoiceId ?? null,
+        invoiceLineId: result?.invoiceLineId ?? null,
+        auditId: result?.auditId ?? null,
+      }),
+      status: 201,
+    },
+  },
+})
+
+export const POST = crud.POST
+
+export const openApi = createBillingCrudOpenApi({
+  resourceName: 'BillingInvoiceLineAdd',
+  pluralName: 'BillingInvoiceLineAdds',
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingInvoiceAddLineSchema,
+    responseSchema: addLineResponseSchema,
+    description:
+      'Appends a new line to a draft invoice (e.g. operator adds a ' +
+      'one-off adjustment). Writes a `DraftInvoiceEdit` audit row ' +
+      '(action=`line_added`, `before_json=null`). Recomputes invoice ' +
+      'totals. Refuses non-draft invoices.',
+  },
+})