@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/api/runs/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 {
   billingRunListQuerySchema,
@@ -40,7 +40,6 @@ const billRunListItemSchema = z.object({
   parent_run_id: z.string().uuid().nullable(),
   dry_run: z.boolean(),
   test_mode: z.boolean(),
-  catch_up: z.boolean(),
   scoped_account_ids: z.array(z.string().uuid()).nullable(),
   as_of_date: z.string(),
   started_at: z.string().nullable(),
@@ -64,7 +63,7 @@ const rawBodySchema = z.object({}).passthrough()
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
-    entity: BillRun,
+    entity: BillingRun,
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',
@@ -79,7 +78,6 @@ const crud = makeCrudRoute({
       'parent_run_id',
       'dry_run',
       'test_mode',
-      'catch_up',
       'scoped_account_ids',
       'as_of_date',
       'started_at',
@@ -111,6 +109,14 @@ const crud = makeCrudRoute({
       if (typeof query.status === 'string') filters.status = { $eq: query.status }
       if (typeof query.triggeredBy === 'string') filters.triggered_by = { $eq: query.triggeredBy }
       if (typeof query.parentRunId === 'string') filters.parent_run_id = { $eq: query.parentRunId }
+      if (query.mode === 'real') {
+        filters.dry_run = { $eq: false }
+        filters.test_mode = { $eq: false }
+      } else if (query.mode === 'test') {
+        filters.test_mode = { $eq: true }
+      } else if (query.mode === 'dry') {
+        filters.dry_run = { $eq: true }
+      }
       if (query.asOfDateFrom instanceof Date) {
         filters.as_of_date = Object.assign(
           (filters.as_of_date as Record<string, unknown>) ?? {},
@@ -161,10 +167,12 @@ export const openApi = createBillingCrudOpenApi({
     schema: billingRunTriggerSchema,
     responseSchema: triggerResponseSchema,
     description:
-      'Triggers a Bill Run. `mode=real` (default) persists drafts and ' +
-      'advances state; `mode=test` persists test-flagged drafts without ' +
-      'advancing state; `mode=dry` computes everything in memory and ' +
-      'persists nothing. Returns HTTP 409 (`billing.run.lock_busy`) when ' +
-      'another run is in flight for the same tenant.',
+      'Triggers a Bill Run. Every run bills **all due cycles** up to `asOfDate` — one ' +
+      'draft invoice per bill date (no catch-up flag; a legacy `catchUp` field is ignored). ' +
+      '`mode=real` (default) persists drafts and advances state; `mode=test` persists ' +
+      'test-flagged drafts for every cycle without advancing state; `mode=dry` simulates ' +
+      'every cycle in memory and persists nothing. Per-cycle results are on each outcome\'s ' +
+      '`cycles`. Returns HTTP 409 (`billing.run.lock_busy`) when another run is in flight ' +
+      'for the same tenant.',
   },
 })

package/src/modules/billing/api/settings/number-preview/route.ts

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { DOCUMENT_SERIES, renderNumber, sequenceScopeKey, validateMask } from '../../../lib/numbering'
+
+/**
+ * `GET /api/billing/settings/number-preview?mask=…` — validates a number
+ * mask and renders an example for today (sequence 1) plus the counter scope
+ * it would use. Pure: no sequence is read or claimed.
+ */
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.settings.view'] },
+}
+
+const querySchema = z.object({ mask: z.string().max(200), series: z.enum(DOCUMENT_SERIES).optional() })
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  const parsed = querySchema.safeParse(Object.fromEntries(new URL(req.url).searchParams.entries()))
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid query' }, { status: 400 })
+  }
+  const errors = validateMask(parsed.data.mask)
+  if (errors.length > 0) return NextResponse.json({ valid: false, errors })
+  const today = new Date()
+  return NextResponse.json({
+    valid: true,
+    errors: [],
+    example: renderNumber(parsed.data.mask, { seq: 1, issueDate: today }),
+    scopeKey: sequenceScopeKey(parsed.data.mask, today),
+  })
+}
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Preview a document number mask',
+      description: 'Validates a number mask and returns an example number for today and its counter scope.',
+    },
+  },
+}

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

@@ -0,0 +1,116 @@
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+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 { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { BillingSettings } from '../../data/entities'
+import { billingEntityIds } from '../../data/entityIds'
+import { billingSettingsUpdateSchema } from '../../data/validators'
+import { getBillingSettings, missingSellerFields, serializeBillingSettings } from '../../lib/billingSettings'
+import { isPaymentGatewayAvailable } from '../../lib/paymentGateway'
+
+/**
+ * `GET /api/billing/settings` — the caller organization's billing settings
+ * (created with defaults on first read) plus runtime capabilities.
+ * `PUT /api/billing/settings` — partial update via `billing.settings.update`.
+ *
+ * Spec 0: prepaid defaults (moved from core `configs`) and document number
+ * masks. `capabilities.gatewayTopups` tells the UI whether online top-ups
+ * are available (the `payment_gateways` module is optional, E-D1).
+ * Spec B: seller / payment / document fields, plus `completeness` — posting
+ * is blocked until the printable minimum (legal name, address, tax id, IBAN)
+ * is filled.
+ */
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['billing.settings.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['billing.settings.manage'] },
+}
+
+export const metadata = routeMetadata
+
+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 em = (container.resolve('em') as EntityManager).fork()
+    const settings = await getBillingSettings(em, { tenantId: auth.tenantId, organizationId })
+    const missing = missingSellerFields(settings)
+    return NextResponse.json({
+      settings: serializeBillingSettings(settings),
+      capabilities: { gatewayTopups: isPaymentGatewayAvailable(container as never) },
+      completeness: { ready: missing.length === 0, missing },
+    })
+  } catch (err) {
+    console.error('[billing/settings.GET]', err)
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+
+const rawBodySchema = z.object({}).passthrough()
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingSettings,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.settings,
+    fields: ['id'],
+    buildFilters: async () => ({}),
+  },
+  actions: {
+    update: {
+      commandId: 'billing.settings.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        return billingSettingsUpdateSchema.parse(withScopedPayload(raw ?? {}, ctx, translate))
+      },
+      response: ({ result }) => ({ settings: result }),
+    },
+  },
+})
+
+export const PUT = crud.PUT
+
+export const openApi = {
+  methods: {
+    GET: {
+      tags: ['Billing'],
+      summary: 'Get billing settings',
+      description:
+        'Billing settings of the caller organization (prepaid defaults, number masks per series, ' +
+        'seller / bank / document fields, default payment terms and VAT rate, `prepaidTaxPoint` ' +
+        '(`topup` = VAT on the top-up receipt, `consumption` = VAT on each prepaid debit)), ' +
+        '`capabilities.gatewayTopups` and `completeness { ready, missing[] }` (posting needs ' +
+        '`legalName`, `sellerAddress`, `taxId`, `iban`). The row is created with defaults on first read.',
+    },
+    PUT: {
+      tags: ['Billing'],
+      summary: 'Update billing settings',
+      description:
+        'Partial update. Number masks use `{YYYY} {YY} {MM} {DD}` plus exactly one of ' +
+        '`{SEQUENCE_NUM}` (never resets), `{SEQUENCE_NUM_YEAR}` (yearly — needs a year token) or ' +
+        '`{SEQUENCE_NUM_MONTH}` (monthly — needs year + month), with an optional `:N` zero-pad. ' +
+        'Invalid masks → 400 with the mask error code. IBAN is normalised and mod-97 checked, ' +
+        'BIC must be 8 or 11 characters; an empty string clears a text field.',
+      requestBody: { schema: billingSettingsUpdateSchema },
+    },
+  },
+}

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

@@ -35,6 +35,10 @@ const billingStatementListItemSchema = z.object({
   total_adjustments: z.string(),
   closing_balance: z.string(),
   debit_breakdown: z.record(z.string(), z.unknown()).nullable(),
+  /** Spec F: per-rate VAT of the period's prepaid debits (empty when VAT is charged at top-up). */
+  vat_summary: z
+    .array(z.object({ rate: z.string(), net: z.string(), tax: z.string(), gross: z.string() }))
+    .nullable(),
   status: z.string(),
   organization_id: z.string().uuid(),
   tenant_id: z.string().uuid(),
@@ -67,6 +71,7 @@ const crud = makeCrudRoute({
       'total_adjustments',
       'closing_balance',
       'debit_breakdown',
+      'vat_summary',
       'status',
       'organization_id',
       'tenant_id',

package/src/modules/billing/api/test-invoices/wipe/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 { billingWipeTestInvoicesSchema } from '../../../data/validators'
 import { createBillingCrudOpenApi } from '../../openapi'
+import { BillingInvoice } from '../../../data/entities'
 
 /**
  * `POST /api/billing/test-invoices/wipe` — hard-delete invoices
@@ -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',