@dainamite/billing 0.20.0 → 0.22.0

package/src/modules/billing/subscribers/invoice-auto-send.ts

@@ -0,0 +1,46 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingAccount, BillingInvoice } from '../data/entities'
+import { hasSuccessfulDelivery, isDeliverableEmail, sendInvoice, type SendInvoiceDeps } from '../lib/invoiceDelivery'
+
+/**
+ * Auto-send (Spec B): `billing.invoice.posted` → email the document when the
+ * account has `auto_send_invoice` on.
+ *
+ * Persistent and idempotent: a redelivered event finds a `sent` auto
+ * delivery in `metadata.deliveries` and does nothing. Receipts, test
+ * documents and accounts with a placeholder / missing email are skipped
+ * without a delivery entry (the operator can still send manually once the
+ * address is fixed). A transport failure is recorded as a `failed`
+ * delivery by `sendInvoice` and not retried automatically.
+ */
+
+export const metadata = {
+  event: 'billing.invoice.posted',
+  persistent: true,
+  id: 'billing-invoice-auto-send',
+}
+
+type PostedPayload = {
+  invoiceId?: string
+  tenantId?: string
+  organizationId?: string
+}
+
+export async function autoSendInvoice(em: EntityManager, payload: PostedPayload, deps: SendInvoiceDeps = {}): Promise<'sent' | 'failed' | 'skipped'> {
+  if (!payload?.invoiceId || !payload.tenantId || !payload.organizationId) return 'skipped'
+  const scope = { tenantId: payload.tenantId, organizationId: payload.organizationId }
+  const invoice = await em.findOne(BillingInvoice, { id: payload.invoiceId, ...scope, deletedAt: null } as never)
+  if (!invoice || invoice.testRun || invoice.status === 'draft' || invoice.documentType === 'receipt') return 'skipped'
+  if (hasSuccessfulDelivery(invoice, 'auto')) return 'skipped'
+  const account = await em.findOne(BillingAccount, { id: invoice.billAccountId, ...scope } as never)
+  if (!account?.autoSendInvoice || !isDeliverableEmail(account.invoiceEmail)) return 'skipped'
+  const result = await sendInvoice(em, { invoiceId: invoice.id, ...scope, trigger: 'auto' }, deps)
+  return result.status
+}
+
+export default async function handle(payload: PostedPayload): Promise<void> {
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await autoSendInvoice(em, payload)
+}

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

@@ -1,34 +1,24 @@
 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'
+import { BillingInvoice, BillingPayment } from '../data/entities'
+import { withAccountLock } from '../lib/accountLock'
+import { allocate, applyAccountCredit, emptyEffects, mergeEffects, toCents, type AllocationEffects } from '../lib/allocation'
+import { emitAllocationEffects } from '../lib/allocationEvents'
+import { emitBillingEvent } from '../events'
 
 /**
- * Subscriber: payment captured → billing invoice paid.
+ * Subscriber: gateway payment captured → billing payment + allocation
+ * (Spec C, P-D9 — the single code path to "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.
+ * The payment session is created with `paymentId = invoice.id`, so the
+ * captured event identifies the billing invoice. Instead of flipping the
+ * invoice status, the capture becomes a `BillingPayment` (`source =
+ * gateway`, `external_ref = transactionId ?? paymentId`) allocated to that
+ * invoice through the allocation service; any remainder is account credit.
  *
- * 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.
+ * Idempotent: a re-delivered event finds the payment by `external_ref` and
+ * does nothing. Payments for anything that is not an open billing
+ * receivable are ignored (other modules own them).
  */
 
 export const metadata = {
@@ -37,53 +27,85 @@ export const metadata = {
   id: 'billing-payment-captured-to-paid',
 }
 
-type CapturedPayload = {
+export type CapturedPayload = {
   paymentId?: string
   transactionId?: string
   organizationId?: string
   tenantId?: string
   providerKey?: string
+  amount?: number | string
+  currencyCode?: string
 }
 
-export default async function handle(payload: CapturedPayload): Promise<void> {
-  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) {
-    return
-  }
+export async function recordGatewayCapture(
+  em: EntityManager,
+  payload: CapturedPayload,
+): Promise<'recorded' | 'duplicate' | 'skipped'> {
+  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) return 'skipped'
+  const scope = { tenantId: payload.tenantId, organizationId: payload.organizationId }
+  const invoice = await em.findOne(BillingInvoice, { id: payload.paymentId, ...scope, deletedAt: null } as never)
+  if (!invoice || invoice.testRun || !['invoice', 'debit_memo'].includes(invoice.documentType)) return 'skipped'
+  const externalRef = payload.transactionId ?? payload.paymentId
+  const existing = await em.findOne(BillingPayment, { ...scope, externalRef } as never)
+  if (existing) return 'duplicate'
+  if (!['posted', 'partially_paid'].includes(invoice.status)) return 'skipped'
 
-  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,
+  const captured = toCents(payload.amount ?? invoice.outstanding)
+  if (captured <= 0) return 'skipped'
+  const amount = (captured / 100).toFixed(4)
+  const now = new Date()
+  const payment = em.create(BillingPayment, {
+    ...scope,
+    receivedAt: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())),
+    amount,
+    currencyCode: (payload.currencyCode ?? invoice.currencyCode).toUpperCase(),
+    reference: invoice.number,
+    source: 'gateway',
+    billAccountId: invoice.billAccountId,
+    status: 'matched',
+    unallocatedAmount: amount,
+    sourceRef: `gateway:${externalRef}`,
+    externalRef,
+    metadata: { provider_key: payload.providerKey ?? null },
+    createdAt: now,
+    updatedAt: now,
   })
-  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
-  }
+  em.persist(payment)
+  await em.flush()
 
-  const paidStatusEntryId = await resolveInvoiceStatusEntryId(
+  const effects: AllocationEffects = await withAccountLock(
     em,
-    payload.tenantId,
-    payload.organizationId,
-    'paid',
+    { tenantId: scope.tenantId, billAccountId: invoice.billAccountId },
+    async (tem) => {
+      const all = emptyEffects()
+      const take = Math.min(captured, toCents(invoice.outstanding))
+      if (take > 0 && payment.currencyCode === invoice.currencyCode) {
+        mergeEffects(
+          all,
+          await allocate(tem, scope, {
+            source: { type: 'payment', id: payment.id },
+            invoiceId: invoice.id,
+            amountCents: take,
+            by: 'gateway',
+          }),
+        )
+      }
+      mergeEffects(
+        all,
+        await applyAccountCredit(tem, scope, { id: invoice.billAccountId, currencyCode: payment.currencyCode }, {
+          onlySources: [{ type: 'payment', id: payment.id }],
+        }),
+      )
+      return all
+    },
   )
-  invoice.status = 'paid'
-  invoice.statusEntryId = paidStatusEntryId
-  invoice.paidTotalAmount = invoice.grandTotalGrossAmount
-  invoice.outstandingAmount = '0'
-  invoice.updatedAt = new Date()
-  await em.flush()
+  await emitBillingEvent('billing.payment.created', { ...scope, paymentId: payment.id, source: 'gateway' })
+  await emitAllocationEffects(scope, effects)
+  return 'recorded'
+}
+
+export default async function handle(payload: CapturedPayload): Promise<void> {
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await recordGatewayCapture(em, payload)
 }

package/src/modules/billing/subscribers/prepaid-topup-captured.ts

@@ -1,7 +1,5 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
-import type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'
 import { BillingAccount, BillingTopup } from '../data/entities'
 import { emitBillingEvent } from '../events'
 import { captureTopup } from '../lib/topupCapture'
@@ -66,15 +64,13 @@ export default async function handle(payload: CapturedPayload): Promise<void> {
     return
   }
 
-  const taxRate = await getTopupTaxRate(em)
-  const numberGenerator = container.resolve(
-    'salesDocumentNumberGenerator',
-  ) as SalesDocumentNumberGenerator
-  const taxService = container.resolve('taxCalculationService') as TaxCalculationService
+  const taxRate = await getTopupTaxRate(em, {
+    tenantId: account.tenantId,
+    organizationId: account.organizationId,
+  })
 
   const result = await captureTopup(
     em,
-    { numberGenerator, taxService },
     {
       topup,
       account: {

package/dist/modules/billing/lib/invoiceStatus.js

@@ -1,38 +0,0 @@
-import {
-  Dictionary,
-  DictionaryEntry
-} from "@open-mercato/core/modules/dictionaries/data/entities";
-const SALES_INVOICE_STATUS_DICTIONARY_KEY = "sales.invoice_status";
-const cache = /* @__PURE__ */ new Map();
-function key(tenantId, organizationId, status) {
-  return `${tenantId}:${organizationId}:${status}`;
-}
-async function resolveInvoiceStatusEntryId(em, tenantId, organizationId, status) {
-  const cacheKey = key(tenantId, organizationId, status);
-  const cached = cache.get(cacheKey);
-  if (cached) return cached;
-  const dictionary = await em.findOne(Dictionary, {
-    tenantId,
-    organizationId,
-    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,
-    deletedAt: null
-  });
-  if (!dictionary) return null;
-  const entry = await em.findOne(DictionaryEntry, {
-    dictionary,
-    tenantId,
-    organizationId,
-    value: status
-  });
-  if (!entry) return null;
-  cache.set(cacheKey, entry.id);
-  return entry.id;
-}
-function __resetInvoiceStatusCacheForTests() {
-  cache.clear();
-}
-export {
-  __resetInvoiceStatusCacheForTests,
-  resolveInvoiceStatusEntryId
-};
-//# sourceMappingURL=invoiceStatus.js.map

package/dist/modules/billing/lib/invoiceStatus.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../src/modules/billing/lib/invoiceStatus.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport {\n  Dictionary,\n  DictionaryEntry,\n} from '@open-mercato/core/modules/dictionaries/data/entities'\nimport type { InvoiceStatus } from '../data/validators'\n\n/**\n * Resolve the `sales.invoice_status` dictionary entry id for a given\n * status value, scoped per `(tenantId, organizationId)`.\n *\n * Used by:\n *   - `invoiceWriter` to set `statusEntryId` on the draft at create time.\n *   - The \"post\" command to flip draft \u2192 posted.\n *   - The payment-captured subscriber to flip posted \u2192 paid.\n *\n * Cached because the lookup is hot (every Bill Run draft hits it\n * once, every posted invoice hits it twice, every paid invoice once)\n * and the dictionary entry id never changes for the lifetime of a\n * tenant. Exposed `__resetInvoiceStatusCacheForTests` to keep tests\n * deterministic across runs.\n */\n\nconst SALES_INVOICE_STATUS_DICTIONARY_KEY = 'sales.invoice_status'\n\nconst cache = new Map<string, string>()\n\nfunction key(tenantId: string, organizationId: string, status: InvoiceStatus): string {\n  return `${tenantId}:${organizationId}:${status}`\n}\n\nexport async function resolveInvoiceStatusEntryId(\n  em: EntityManager,\n  tenantId: string,\n  organizationId: string,\n  status: InvoiceStatus,\n): Promise<string | null> {\n  const cacheKey = key(tenantId, organizationId, status)\n  const cached = cache.get(cacheKey)\n  if (cached) return cached\n  const dictionary = await em.findOne(Dictionary, {\n    tenantId,\n    organizationId,\n    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,\n    deletedAt: null,\n  })\n  if (!dictionary) return null\n  const entry = await em.findOne(DictionaryEntry, {\n    dictionary,\n    tenantId,\n    organizationId,\n    value: status,\n  })\n  if (!entry) return null\n  cache.set(cacheKey, entry.id)\n  return entry.id\n}\n\nexport function __resetInvoiceStatusCacheForTests(): void {\n  cache.clear()\n}\n"],
-  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAmBP,MAAM,sCAAsC;AAE5C,MAAM,QAAQ,oBAAI,IAAoB;AAEtC,SAAS,IAAI,UAAkB,gBAAwB,QAA+B;AACpF,SAAO,GAAG,QAAQ,IAAI,cAAc,IAAI,MAAM;AAChD;AAEA,eAAsB,4BACpB,IACA,UACA,gBACA,QACwB;AACxB,QAAM,WAAW,IAAI,UAAU,gBAAgB,MAAM;AACrD,QAAM,SAAS,MAAM,IAAI,QAAQ;AACjC,MAAI,OAAQ,QAAO;AACnB,QAAM,aAAa,MAAM,GAAG,QAAQ,YAAY;AAAA,IAC9C;AAAA,IACA;AAAA,IACA,KAAK;AAAA,IACL,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,WAAY,QAAO;AACxB,QAAM,QAAQ,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC9C;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO;AAAA,EACT,CAAC;AACD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,IAAI,UAAU,MAAM,EAAE;AAC5B,SAAO,MAAM;AACf;AAEO,SAAS,oCAA0C;AACxD,QAAM,MAAM;AACd;",
-  "names": []
-}

package/src/modules/billing/__tests__/lib/invoiceStatus.test.ts

@@ -1,97 +0,0 @@
-import {
-  __resetInvoiceStatusCacheForTests,
-  resolveInvoiceStatusEntryId,
-} from '../../lib/invoiceStatus'
-
-type MockEm = {
-  findOne: jest.MockedFunction<(entity: unknown, where: Record<string, unknown>) => Promise<unknown>>
-}
-
-function createMockEm(): MockEm {
-  return { findOne: jest.fn() }
-}
-
-const TENANT = 'tenant-1'
-const ORG = 'org-1'
-
-beforeEach(() => {
-  __resetInvoiceStatusCacheForTests()
-})
-
-describe('resolveInvoiceStatusEntryId', () => {
-  it('looks up dictionary then matching entry', async () => {
-    const em = createMockEm()
-    em.findOne
-      .mockResolvedValueOnce({ id: 'dict-1' })
-      .mockResolvedValueOnce({ id: 'entry-draft' })
-
-    const result = await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'draft')
-
-    expect(result).toBe('entry-draft')
-    expect(em.findOne).toHaveBeenCalledTimes(2)
-    const [, dictWhere] = em.findOne.mock.calls[0]
-    expect((dictWhere as { key: string }).key).toBe('sales.invoice_status')
-    const [, entryWhere] = em.findOne.mock.calls[1]
-    expect((entryWhere as { value: string }).value).toBe('draft')
-  })
-
-  it('caches the resolved id per (tenant, org, status)', async () => {
-    const em = createMockEm()
-    em.findOne
-      .mockResolvedValueOnce({ id: 'dict-1' })
-      .mockResolvedValueOnce({ id: 'entry-paid' })
-
-    const a = await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'paid')
-    const b = await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'paid')
-
-    expect(a).toBe('entry-paid')
-    expect(b).toBe('entry-paid')
-    // Second call hits cache — no extra findOne invocations.
-    expect(em.findOne).toHaveBeenCalledTimes(2)
-  })
-
-  it('separate cache entries per status (draft vs posted vs paid vs void)', async () => {
-    const em = createMockEm()
-    em.findOne
-      .mockResolvedValueOnce({ id: 'dict-1' })
-      .mockResolvedValueOnce({ id: 'entry-draft' })
-      .mockResolvedValueOnce({ id: 'dict-1' })
-      .mockResolvedValueOnce({ id: 'entry-posted' })
-
-    expect(await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'draft')).toBe(
-      'entry-draft',
-    )
-    expect(await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'posted')).toBe(
-      'entry-posted',
-    )
-  })
-
-  it('returns null when the dictionary is missing', async () => {
-    const em = createMockEm()
-    em.findOne.mockResolvedValueOnce(null)
-    expect(await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'draft')).toBeNull()
-  })
-
-  it('returns null when the entry value is missing', async () => {
-    const em = createMockEm()
-    em.findOne.mockResolvedValueOnce({ id: 'dict-1' }).mockResolvedValueOnce(null)
-    expect(await resolveInvoiceStatusEntryId(em as never, TENANT, ORG, 'void')).toBeNull()
-  })
-
-  it('separate cache entries per tenant', async () => {
-    const em = createMockEm()
-    em.findOne
-      .mockResolvedValueOnce({ id: 'dict-A' })
-      .mockResolvedValueOnce({ id: 'entry-A' })
-      .mockResolvedValueOnce({ id: 'dict-B' })
-      .mockResolvedValueOnce({ id: 'entry-B' })
-
-    expect(await resolveInvoiceStatusEntryId(em as never, 't-A', ORG, 'draft')).toBe(
-      'entry-A',
-    )
-    expect(await resolveInvoiceStatusEntryId(em as never, 't-B', ORG, 'draft')).toBe(
-      'entry-B',
-    )
-    expect(em.findOne).toHaveBeenCalledTimes(4)
-  })
-})

package/src/modules/billing/lib/invoiceStatus.ts

@@ -1,61 +0,0 @@
-import type { EntityManager } from '@mikro-orm/postgresql'
-import {
-  Dictionary,
-  DictionaryEntry,
-} from '@open-mercato/core/modules/dictionaries/data/entities'
-import type { InvoiceStatus } from '../data/validators'
-
-/**
- * Resolve the `sales.invoice_status` dictionary entry id for a given
- * status value, scoped per `(tenantId, organizationId)`.
- *
- * Used by:
- *   - `invoiceWriter` to set `statusEntryId` on the draft at create time.
- *   - The "post" command to flip draft → posted.
- *   - The payment-captured subscriber to flip posted → paid.
- *
- * Cached because the lookup is hot (every Bill Run draft hits it
- * once, every posted invoice hits it twice, every paid invoice once)
- * and the dictionary entry id never changes for the lifetime of a
- * tenant. Exposed `__resetInvoiceStatusCacheForTests` to keep tests
- * deterministic across runs.
- */
-
-const SALES_INVOICE_STATUS_DICTIONARY_KEY = 'sales.invoice_status'
-
-const cache = new Map<string, string>()
-
-function key(tenantId: string, organizationId: string, status: InvoiceStatus): string {
-  return `${tenantId}:${organizationId}:${status}`
-}
-
-export async function resolveInvoiceStatusEntryId(
-  em: EntityManager,
-  tenantId: string,
-  organizationId: string,
-  status: InvoiceStatus,
-): Promise<string | null> {
-  const cacheKey = key(tenantId, organizationId, status)
-  const cached = cache.get(cacheKey)
-  if (cached) return cached
-  const dictionary = await em.findOne(Dictionary, {
-    tenantId,
-    organizationId,
-    key: SALES_INVOICE_STATUS_DICTIONARY_KEY,
-    deletedAt: null,
-  })
-  if (!dictionary) return null
-  const entry = await em.findOne(DictionaryEntry, {
-    dictionary,
-    tenantId,
-    organizationId,
-    value: status,
-  })
-  if (!entry) return null
-  cache.set(cacheKey, entry.id)
-  return entry.id
-}
-
-export function __resetInvoiceStatusCacheForTests(): void {
-  cache.clear()
-}