@dainamite/billing 0.17.0

package/src/modules/billing/setup.ts

@@ -0,0 +1,252 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { features as billingAclFeatures } from './acl'
+import {
+  Dictionary,
+  DictionaryEntry,
+} from '@open-mercato/core/modules/dictionaries/data/entities'
+import { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'
+
+/**
+ * Billing module setup — per-tenant defaults at module installation.
+ *
+ * Idempotency contract:
+ *   - All seed helpers below check for an existing row before inserting.
+ *   - Safe to re-run on every `mercato init` and on `auth sync-role-acls`.
+ *
+ * What this file seeds:
+ *   - `billing.uom` dictionary with 16 global codes (operators can add more).
+ *   - `sales.invoice_status` dictionary with `draft` / `posted` / `paid` /
+ *     `void` so the core/sales Invoice entity's dictionary-driven status
+ *     workflow has values to point at. (Core/sales does NOT seed these —
+ *     billing owns them per Phase 0 validation.)
+ *   - `billing.cron_schedule` + `billing.cron_enabled` module configs.
+ *   - `billing.invoice_number.format` + `.reset_cycle` configs (per-tenant
+ *     defaults; the actual atomic numbering uses core/sales'
+ *     `SalesDocumentSequence` which is created by core/sales' own
+ *     `onTenantCreated`).
+ *
+ * Default role-feature grants:
+ *   - `admin` gets every `billing.*` feature.
+ *   - `billing_admin` is the day-to-day finance operator.
+ *   - `billing_finance_user` is read + dry-run (no posting / no real trigger).
+ *   - `billing_usage_writer` is the narrow scope for external system API keys.
+ */
+
+const BILLING_UOM_DICTIONARY_KEY = 'billing.uom'
+const SALES_INVOICE_STATUS_DICTIONARY_KEY = 'sales.invoice_status'
+
+const BILLING_UOM_CODES = [
+  // time
+  { value: 'hour', label: 'Hour' },
+  { value: 'day', label: 'Day' },
+  { value: 'week', label: 'Week' },
+  { value: 'month', label: 'Month' },
+  // volume
+  { value: 'gb', label: 'Gigabyte' },
+  { value: 'tb', label: 'Terabyte' },
+  { value: 'mb', label: 'Megabyte' },
+  // requests / tokens
+  { value: 'request', label: 'Request' },
+  { value: 'api_request', label: 'API Request' },
+  { value: 'token', label: 'Token' },
+  { value: 'input_token', label: 'Input Token' },
+  { value: 'output_token', label: 'Output Token' },
+  // seats / devices
+  { value: 'seat', label: 'Seat' },
+  { value: 'user', label: 'User' },
+  { value: 'device', label: 'Device' },
+  { value: 'active_user', label: 'Active User' },
+] as const
+
+const INVOICE_STATUS_ENTRIES = [
+  // `posted` is the canonical "issued" state and is also the default a
+  // freshly created invoice transitions to — but billing creates drafts,
+  // so `draft` is the default DictionaryEntry for new rows.
+  { value: 'draft', label: 'Draft', isDefault: true, color: '#9ca3af' },
+  { value: 'posted', label: 'Posted', isDefault: false, color: '#2563eb' },
+  { value: 'paid', label: 'Paid', isDefault: false, color: '#16a34a' },
+  { value: 'void', label: 'Void', isDefault: false, color: '#dc2626' },
+] as const
+
+type SeedScope = { tenantId: string; organizationId: string }
+
+async function ensureDictionary(
+  em: EntityManager,
+  scope: SeedScope,
+  params: { key: string; name: string; description: string },
+): Promise<Dictionary> {
+  const existing = await em.findOne(Dictionary, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    key: params.key,
+    deletedAt: null,
+  })
+  if (existing) return existing
+  const dictionary = em.create(Dictionary, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    key: params.key,
+    name: params.name,
+    description: params.description,
+    isSystem: true,
+    isActive: true,
+    managerVisibility: 'hidden',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  })
+  em.persist(dictionary)
+  await em.flush()
+  return dictionary
+}
+
+async function ensureDictionaryEntries(
+  em: EntityManager,
+  scope: SeedScope,
+  dictionary: Dictionary,
+  entries: ReadonlyArray<{
+    value: string
+    label: string
+    isDefault?: boolean
+    color?: string
+  }>,
+): Promise<void> {
+  const existing = await em.find(DictionaryEntry, {
+    dictionary,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  })
+  const existingValues = new Set(existing.map((e) => e.value))
+  let position = existing.length
+  for (const entry of entries) {
+    if (existingValues.has(entry.value)) continue
+    em.persist(
+      em.create(DictionaryEntry, {
+        dictionary,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        value: entry.value,
+        normalizedValue: entry.value.trim().toLowerCase(),
+        label: entry.label,
+        color: entry.color ?? null,
+        position,
+        isDefault: entry.isDefault ?? false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    )
+    position += 1
+  }
+  await em.flush()
+}
+
+async function seedBillingUomDictionary(em: EntityManager, scope: SeedScope): Promise<void> {
+  const dict = await ensureDictionary(em, scope, {
+    key: BILLING_UOM_DICTIONARY_KEY,
+    name: 'Billing units of measure',
+    description: 'Units billing accepts on usage records (exact match — no conversion).',
+  })
+  await ensureDictionaryEntries(em, scope, dict, BILLING_UOM_CODES)
+}
+
+async function seedInvoiceStatusDictionary(em: EntityManager, scope: SeedScope): Promise<void> {
+  const dict = await ensureDictionary(em, scope, {
+    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,
+    name: 'Sales invoice statuses',
+    description: 'draft → posted → paid (or void). Drives the billing draft/post lifecycle.',
+  })
+  await ensureDictionaryEntries(em, scope, dict, INVOICE_STATUS_ENTRIES)
+}
+
+async function ensureModuleConfig(
+  em: EntityManager,
+  params: { moduleId: string; name: string; value: unknown },
+): Promise<void> {
+  const existing = await em.findOne(ModuleConfig, {
+    moduleId: params.moduleId,
+    name: params.name,
+  })
+  if (existing) return
+  em.persist(
+    em.create(ModuleConfig, {
+      moduleId: params.moduleId,
+      name: params.name,
+      valueJson: params.value as Record<string, unknown> | null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }),
+  )
+  await em.flush()
+}
+
+async function seedBillingConfigs(em: EntityManager): Promise<void> {
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'cron_schedule',
+    value: '0 2 * * *',
+  })
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'cron_enabled',
+    value: true,
+  })
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'invoice_number.format',
+    value: 'INV-{YYYY}-{0000001}',
+  })
+  await ensureModuleConfig(em, {
+    moduleId: 'billing',
+    name: 'invoice_number.reset_cycle',
+    value: 'yearly',
+  })
+}
+
+// Derived from `acl.ts` so a new feature added there automatically lands
+// in every role that should get "everything billing" — no parallel list
+// to keep in sync.
+const ALL_BILLING_FEATURES = billingAclFeatures.map((f) => f.id)
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    // Org admins get every billing feature — `billing.*` wildcard is matched
+    // by the shared feature matcher (`hasFeature` is wildcard-aware).
+    admin: ['billing.*'],
+
+    // Day-to-day finance operator persona.
+    billing_admin: [...ALL_BILLING_FEATURES],
+
+    // Read-only + dry-run preview — auditor / finance-watcher persona.
+    billing_finance_user: [
+      'billing.account.view',
+      'billing.item.view',
+      'billing.usage.view',
+      'billing.run.view',
+      'billing.run.dry_run',
+      'billing.invoice.view',
+    ],
+
+    // Narrow scope for external usage-ingestion API keys.
+    billing_usage_writer: ['billing.usage.ingest'],
+  },
+
+  /**
+   * Tenant init: per-tenant module configs (cron, invoice number defaults).
+   * Runs inside `setupInitialTenant()`, always — no `--no-examples` gate.
+   */
+  async onTenantCreated({ em }) {
+    await seedBillingConfigs(em)
+  },
+
+  /**
+   * Reference data: dictionaries (UoM, invoice statuses). Always runs
+   * during `mercato init`. Idempotent — re-seed is safe.
+   */
+  async seedDefaults({ em, tenantId, organizationId }) {
+    const scope = { tenantId, organizationId }
+    await seedBillingUomDictionary(em, scope)
+    await seedInvoiceStatusDictionary(em, scope)
+  },
+}
+
+export default setup

package/src/modules/billing/subscribers/payment-captured-to-paid.ts

@@ -0,0 +1,89 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'
+import { resolveInvoiceStatusEntryId } from '../lib/invoiceStatus'
+
+/**
+ * Subscriber: payment captured → billing invoice paid.
+ *
+ * Spec wishlist was `payments.payment.completed` carrying `invoice_id`.
+ * The actual upstream event is `payment_gateways.payment.captured` and
+ * its payload carries `paymentId` — set by whoever created the payment
+ * session. Billing flows that drive their own payment sessions can
+ * pass `paymentId = invoice.id`; the subscriber matches on that.
+ *
+ * Behaviour:
+ *   1. Try to find a `core/sales` invoice with `id = payload.paymentId`
+ *      scoped to the same tenant/organization.
+ *   2. If found AND its `status == 'posted'`, flip it to `'paid'`
+ *      (resolves the `paid` `DictionaryEntry`, updates `status` +
+ *      `status_entry_id`). Drafts and already-paid / voided invoices
+ *      are left untouched.
+ *   3. If `paymentId` does not point at a billing-known invoice (e.g.
+ *      the payment was for a `sales.order`), the subscriber is a
+ *      no-op — every other module's own subscriber owns its slice.
+ *
+ * Cross-tenant safety: we always re-scope by `tenantId` +
+ * `organizationId` from the event payload. A malformed payload (e.g.
+ * missing scope fields) short-circuits without touching the DB.
+ *
+ * Idempotency: re-firing the same captured event finds the invoice
+ * already paid and skips silently.
+ */
+
+export const metadata = {
+  event: 'payment_gateways.payment.captured',
+  persistent: true,
+  id: 'billing-payment-captured-to-paid',
+}
+
+type CapturedPayload = {
+  paymentId?: string
+  transactionId?: string
+  organizationId?: string
+  tenantId?: string
+  providerKey?: string
+}
+
+export default async function handle(payload: CapturedPayload): Promise<void> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) {
+    return
+  }
+
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+
+  const invoice = await em.findOne(SalesInvoice, {
+    id: payload.paymentId,
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+    deletedAt: null,
+  })
+  if (!invoice) {
+    // The captured payment isn't for a billing invoice — silent
+    // no-op. Other subscribers (sales, checkout) handle their slice.
+    return
+  }
+  if (invoice.status === 'paid') {
+    // Already paid — idempotent re-firing.
+    return
+  }
+  if (invoice.status !== 'posted') {
+    // A captured payment for a draft / void invoice is suspicious but
+    // not actionable here. Future iteration: log to audit_logs.
+    return
+  }
+
+  const paidStatusEntryId = await resolveInvoiceStatusEntryId(
+    em,
+    payload.tenantId,
+    payload.organizationId,
+    'paid',
+  )
+  invoice.status = 'paid'
+  invoice.statusEntryId = paidStatusEntryId
+  invoice.paidTotalAmount = invoice.grandTotalGrossAmount
+  invoice.outstandingAmount = '0'
+  invoice.updatedAt = new Date()
+  await em.flush()
+}

package/src/modules/billing/translations.ts

@@ -0,0 +1,9 @@
+/**
+ * Translatable fields for billing entities.
+ *
+ * Phase 0 keeps this empty — the Billing Account name and invoice line
+ * descriptions are user-entered free text, not localizable templates.
+ * If we ever ship localized invoice templates (Phase 4 admin UI), the
+ * template label fields land here.
+ */
+export const translatableFields: Record<string, string[]> = {}

package/src/modules/billing/workers/reap-stale-bill-runs.ts

@@ -0,0 +1,57 @@
+import type { JobContext, QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import type { FilterQuery } from '@mikro-orm/core'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillRun } from '../data/entities'
+
+export const metadata: WorkerMeta = {
+  queue: 'billing-reap-stale-runs',
+  id: 'billing:reap-stale-bill-runs',
+  concurrency: 1,
+}
+
+type HandlerContext = JobContext & {
+  resolve: <T = unknown>(name: string) => T
+}
+
+/**
+ * Reaper for "zombie" Bill Runs left in `status='running'` after a crash.
+ *
+ * Background — the Bill Run engine acquires a per-tenant Postgres
+ * transaction-scoped advisory lock (`pg_try_advisory_xact_lock`). When the
+ * holding transaction ends (commit / rollback / process death) the lock is
+ * released automatically — so there is no lock leak — but the `BillRun`
+ * row's `status='running'` stays set forever, blocking restarts and
+ * confusing the dashboard.
+ *
+ * Phase 0 ships this as the **registered worker shell** so the module's
+ * worker auto-discovery includes it from day one. The active-advisory-lock
+ * check (which is what distinguishes a real zombie from a healthy
+ * long-running run) lands with the Bill Run engine itself in Phase 2.
+ *
+ * For now the heuristic is time-only: any `running` row older than 1 hour
+ * is marked failed with an explanatory message. That is conservative —
+ * real runs almost never take an hour even for 500k-account tenants
+ * (see spec Performance Considerations).
+ */
+const STALE_THRESHOLD_MS = 60 * 60 * 1000 // 1 hour
+
+export default async function handle(_job: QueuedJob, ctx: HandlerContext): Promise<void> {
+  const em = ctx.resolve<EntityManager>('em')
+  const threshold = new Date(Date.now() - STALE_THRESHOLD_MS)
+  const stale = await em.find(BillRun, {
+    status: 'running',
+    startedAt: { $lt: threshold },
+  } satisfies FilterQuery<BillRun>)
+  if (stale.length === 0) return
+  const now = new Date()
+  for (const run of stale) {
+    run.status = 'failed'
+    run.finishedAt = now
+    const summary = (run.summary ?? {}) as Record<string, unknown>
+    summary.reaper_message =
+      'Stale running run reaped after crash; advisory lock released'
+    summary.reaped_at = now.toISOString()
+    run.summary = summary
+  }
+  await em.flush()
+}