@dainamite/billing 0.19.0 → 0.21.0

package/src/modules/billing/events.ts

@@ -5,15 +5,44 @@ import { createModuleEvents } from '@open-mercato/shared/modules/events'
  *
  * Emission contract:
  *   - `billing.invoice.posted` fires once per posted draft AFTER the post
- *     transaction commits (sequence number assigned, status set to `posted`
- *     in core/sales). Consumed by mailers / accounting bridges / analytics.
+ *     transaction commits (series number, issue/due dates assigned, status
+ *     `posted` in `billing_invoices`) and after the PDF is frozen. Consumed by
+ *     the auto-send subscriber, accounting bridges, analytics.
+ *   - `billing.invoice.sent` / `billing.invoice.send_failed` fire once per
+ *     email delivery attempt (Spec B), manual or automatic.
  *   - `billing.invoice.line_posted` fires once per line on a posted invoice
- *     so analytics can aggregate without scanning core/sales lines directly.
+ *     so analytics can aggregate without scanning invoice lines directly.
  *   - `billing.run.completed` fires once per Bill Run after all per-account
  *     transactions finished (status is one of `completed` / `partial_failure`
  *     / `failed`). Useful for "did the nightly run go OK?" alerts.
+ *
+ * CRUD events (`billing.<entity>.<action>`) are emitted by the data engine
+ * from the commands' `emitCrudSideEffects({ events: { module: 'billing',
+ * entity } })`. Only the (entity, action) pairs a command actually emits are
+ * declared — `__tests__/events.test.ts` fails when a command emits one that
+ * is missing here (the data engine would log "Emitting undeclared event").
  */
 const events = [
+  // ─── CRUD (commands/*.ts) ────────────────────────────────────
+  { id: 'billing.account.created', label: 'Billing Account Created', entity: 'account', category: 'crud' },
+  { id: 'billing.account.updated', label: 'Billing Account Updated', entity: 'account', category: 'crud' },
+  { id: 'billing.account.deleted', label: 'Billing Account Deleted', entity: 'account', category: 'crud' },
+  { id: 'billing.item.created', label: 'Billing Item Created', entity: 'item', category: 'crud' },
+  { id: 'billing.item.updated', label: 'Billing Item Updated', entity: 'item', category: 'crud' },
+  { id: 'billing.item.deleted', label: 'Billing Item Deleted', entity: 'item', category: 'crud' },
+  {
+    // One per usage upload, on the same high-throughput path as
+    // `billing.usage.rated` — excluded from workflow triggers for the same
+    // reason (see Open Question #2).
+    id: 'billing.usage.created',
+    label: 'Billing Usage Record Created',
+    entity: 'usage',
+    category: 'crud',
+    excludeFromTriggers: true,
+  },
+  { id: 'billing.transaction.created', label: 'Billing Balance Transaction Created', entity: 'transaction', category: 'crud' },
+  { id: 'billing.topup.created', label: 'Billing Top-up Created', entity: 'topup', category: 'crud' },
+  // ─── Lifecycle ───────────────────────────────────────────────
   {
     id: 'billing.invoice.posted',
     label: 'Billing Invoice Posted',
@@ -21,6 +50,48 @@ const events = [
     category: 'lifecycle',
     clientBroadcast: true,
   },
+  {
+    id: 'billing.invoice.sent',
+    label: 'Billing Invoice Sent',
+    entity: 'invoice',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  {
+    id: 'billing.invoice.send_failed',
+    label: 'Billing Invoice Send Failed',
+    entity: 'invoice',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  // ─── Payments (Spec C) ───────────────────────────────────────
+  { id: 'billing.payment.created', label: 'Billing Payment Created', entity: 'payment', category: 'lifecycle' },
+  { id: 'billing.payment.allocated', label: 'Billing Payment Allocated', entity: 'payment', category: 'lifecycle' },
+  { id: 'billing.payment.unallocated', label: 'Billing Payment Unallocated', entity: 'payment', category: 'lifecycle' },
+  {
+    id: 'billing.payment.converted_to_topup',
+    label: 'Billing Payment Converted to Top-up',
+    entity: 'payment',
+    category: 'lifecycle',
+  },
+  {
+    id: 'billing.payment_import.completed',
+    label: 'Billing Payment Import Completed',
+    entity: 'payment_import',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
+  { id: 'billing.invoice.paid', label: 'Billing Invoice Paid', entity: 'invoice', category: 'lifecycle', clientBroadcast: true },
+  // ─── Corrective documents (Spec D) ───────────────────────────
+  { id: 'billing.credit_memo.posted', label: 'Billing Credit Memo Posted', entity: 'credit_memo', category: 'lifecycle', clientBroadcast: true },
+  { id: 'billing.debit_memo.posted', label: 'Billing Debit Memo Posted', entity: 'debit_memo', category: 'lifecycle', clientBroadcast: true },
+  { id: 'billing.invoice.credited', label: 'Billing Invoice Credited', entity: 'invoice', category: 'lifecycle', clientBroadcast: true },
+  {
+    id: 'billing.invoice.partially_paid',
+    label: 'Billing Invoice Partially Paid',
+    entity: 'invoice',
+    category: 'lifecycle',
+  },
   {
     id: 'billing.invoice.line_posted',
     label: 'Billing Invoice Line Posted',
@@ -34,6 +105,14 @@ const events = [
     category: 'lifecycle',
     clientBroadcast: true,
   },
+  // Spec F — a test / dry run and its test invoices were deleted.
+  {
+    id: 'billing.run.deleted',
+    label: 'Bill Run Deleted',
+    entity: 'bill_run',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
   // ─── Prepaid balance billing (SPEC-002) ──────────────────────
   {
     id: 'billing.balance.topped_up',