@dainamite/billing 0.20.0 → 0.22.0

package/src/modules/billing/migrations/Migration20261116000000_billing_invoice_documents.ts

@@ -0,0 +1,58 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Invoice documents (Spec B): VAT per item, payment terms, seller settings.
+ *
+ *   - `billing_items.tax_rate` — existing items get 0 (P-D5: no back-fill, a
+ *     default would silently re-price live subscriptions; demo data reseeds);
+ *   - `billing_accounts.payment_terms_days` / `auto_send_invoice`;
+ *   - `billing_settings` seller block, bank, footer, logo, default terms and
+ *     default tax rate.
+ *
+ * Additive only. Hand-written like the package's earlier migrations (`yarn
+ * mercato db generate` only diffs `@app` modules); columns mirror
+ * `data/entities.ts` 1:1.
+ */
+export class Migration20261116000000_billing_invoice_documents extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `alter table "billing_items" add column if not exists "tax_rate" numeric(7, 4) not null default '0';`,
+    )
+    this.addSql(
+      `alter table "billing_accounts" add column if not exists "payment_terms_days" int null, add column if not exists "auto_send_invoice" boolean not null default false;`,
+    )
+    this.addSql(
+      `alter table "billing_settings"
+        add column if not exists "legal_name" text null,
+        add column if not exists "seller_address" jsonb null,
+        add column if not exists "tax_id" text null,
+        add column if not exists "bank_name" text null,
+        add column if not exists "iban" text null,
+        add column if not exists "bic" text null,
+        add column if not exists "invoice_footer" text null,
+        add column if not exists "logo_attachment_id" uuid null,
+        add column if not exists "default_payment_terms_days" int not null default 14,
+        add column if not exists "default_tax_rate" numeric(7, 4) not null default '23';`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(
+      `alter table "billing_settings"
+        drop column if exists "legal_name",
+        drop column if exists "seller_address",
+        drop column if exists "tax_id",
+        drop column if exists "bank_name",
+        drop column if exists "iban",
+        drop column if exists "bic",
+        drop column if exists "invoice_footer",
+        drop column if exists "logo_attachment_id",
+        drop column if exists "default_payment_terms_days",
+        drop column if exists "default_tax_rate";`,
+    )
+    this.addSql(
+      `alter table "billing_accounts" drop column if exists "payment_terms_days", drop column if exists "auto_send_invoice";`,
+    )
+    this.addSql(`alter table "billing_items" drop column if exists "tax_rate";`)
+  }
+}

package/src/modules/billing/migrations/Migration20261117000000_billing_payments.ts

@@ -0,0 +1,97 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Payments (Spec C): billing-owned payment register, source-typed
+ * allocations (payments now, credit memos in Spec D) and CSV import batches.
+ *
+ * Hand-written like the package's earlier migrations (`yarn mercato db
+ * generate` only diffs `@app` modules). Partial unique indexes cannot be
+ * expressed with decorators, so they live here only.
+ */
+export class Migration20261117000000_billing_payments extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`create table if not exists "billing_payments" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "received_at" date not null,
+      "amount" numeric(18, 4) not null,
+      "currency_code" text not null,
+      "reference" text null,
+      "payer_name" text null,
+      "payer_account" text null,
+      "source" text not null,
+      "import_id" uuid null,
+      "bill_account_id" uuid null,
+      "status" text not null,
+      "unallocated_amount" numeric(18, 4) not null,
+      "match_reason" text null,
+      "source_ref" text not null,
+      "external_ref" text null,
+      "topup_id" uuid null,
+      "metadata" jsonb null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_payments_pkey" primary key ("id"),
+      constraint "billing_payments_amount_positive" check ("amount" > 0),
+      constraint "billing_payments_unallocated_range" check ("unallocated_amount" >= 0 and "unallocated_amount" <= "amount")
+    );`)
+    this.addSql(`create index if not exists "billing_payments_status_idx" on "billing_payments" ("tenant_id", "organization_id", "status");`)
+    this.addSql(`create index if not exists "billing_payments_account_idx" on "billing_payments" ("bill_account_id", "status");`)
+    this.addSql(`create index if not exists "billing_payments_import_idx" on "billing_payments" ("import_id");`)
+    this.addSql(
+      `create unique index if not exists "billing_payments_source_ref_uq" on "billing_payments" ("tenant_id", "organization_id", "source_ref") where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create unique index if not exists "billing_payments_external_ref_uq" on "billing_payments" ("tenant_id", "organization_id", "external_ref") where "external_ref" is not null;`,
+    )
+
+    this.addSql(`create table if not exists "billing_allocations" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "source_type" text not null,
+      "source_id" uuid not null,
+      "invoice_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "amount" numeric(18, 4) not null,
+      "currency_code" text not null,
+      "allocated_by" text not null,
+      "user_id" uuid null,
+      "deallocated_by_user_id" uuid null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_allocations_pkey" primary key ("id"),
+      constraint "billing_allocations_amount_positive" check ("amount" > 0)
+    );`)
+    this.addSql(`create index if not exists "billing_allocations_source_idx" on "billing_allocations" ("source_type", "source_id") where "deleted_at" is null;`)
+    this.addSql(`create index if not exists "billing_allocations_invoice_idx" on "billing_allocations" ("invoice_id") where "deleted_at" is null;`)
+    this.addSql(`create index if not exists "billing_allocations_account_idx" on "billing_allocations" ("bill_account_id") where "deleted_at" is null;`)
+
+    this.addSql(`create table if not exists "billing_payment_imports" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "file_name" text not null,
+      "row_count" int not null,
+      "counts" jsonb null,
+      "errors" jsonb null,
+      "user_id" uuid null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_payment_imports_pkey" primary key ("id")
+    );`)
+    this.addSql(
+      `create index if not exists "billing_payment_imports_scope_idx" on "billing_payment_imports" ("tenant_id", "organization_id", "created_at");`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop table if exists "billing_payment_imports";`)
+    this.addSql(`drop table if exists "billing_allocations";`)
+    this.addSql(`drop table if exists "billing_payments";`)
+  }
+}

package/src/modules/billing/migrations/Migration20261118000000_billing_memos.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Credit / debit memos (Spec D). Memo columns `document_type`,
+ * `corrects_invoice_id`, `correction_reason` and `credited_total` exist since
+ * Spec 0; this adds the snapshot of the corrected document printed on the
+ * memo. Additive, hand-written like the package's earlier migrations.
+ */
+export class Migration20261118000000_billing_memos extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `alter table "billing_invoices" add column if not exists "corrects_invoice_number" text null, add column if not exists "corrects_issue_date" date null;`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(
+      `alter table "billing_invoices" drop column if exists "corrects_invoice_number", drop column if exists "corrects_issue_date";`,
+    )
+  }
+}

package/src/modules/billing/migrations/Migration20261119000000_billing_operator_feedback.ts

@@ -0,0 +1,39 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Operator feedback round 1 (Spec F).
+ *
+ * - `billing_items.price_basis` ('net' | 'gross', default 'net'): the item
+ *   price is stored as typed; invoice lines and prepaid debits are computed
+ *   from that basis (F-D2).
+ * - `billing_settings.prepaid_tax_point` ('topup' | 'consumption', default
+ *   'topup'): where prepaid VAT is charged (F-D3).
+ * - `billing_statements.vat_summary` jsonb: per-rate net / tax / gross of the
+ *   period's prepaid debits (empty in `topup` mode).
+ *
+ * Hand-written like the package's earlier migrations: `yarn mercato db
+ * generate` only diffs `@app` modules. Columns mirror `data/entities.ts` 1:1.
+ */
+export class Migration20261119000000_billing_operator_feedback extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`alter table "billing_items" add column if not exists "price_basis" text not null default 'net';`)
+    this.addSql(
+      `alter table "billing_items" add constraint "billing_items_price_basis_check" check ("price_basis" in ('net', 'gross'));`,
+    )
+    this.addSql(
+      `alter table "billing_settings" add column if not exists "prepaid_tax_point" text not null default 'topup';`,
+    )
+    this.addSql(
+      `alter table "billing_settings" add constraint "billing_settings_prepaid_tax_point_check" check ("prepaid_tax_point" in ('topup', 'consumption'));`,
+    )
+    this.addSql(`alter table "billing_statements" add column if not exists "vat_summary" jsonb null;`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`alter table "billing_statements" drop column if exists "vat_summary";`)
+    this.addSql(`alter table "billing_settings" drop constraint if exists "billing_settings_prepaid_tax_point_check";`)
+    this.addSql(`alter table "billing_settings" drop column if exists "prepaid_tax_point";`)
+    this.addSql(`alter table "billing_items" drop constraint if exists "billing_items_price_basis_check";`)
+    this.addSql(`alter table "billing_items" drop column if exists "price_basis";`)
+  }
+}

package/src/modules/billing/migrations/Migration20261120000000_billing_allocation_scope_indexes.ts

@@ -0,0 +1,35 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * `billing_allocations` lookup indexes lead with the tenant scope, like every
+ * other billing table. Each allocation read filters by tenant + organization
+ * plus the invoice, the source (payment / credit memo) or the account.
+ *
+ * Hand-written like the package's earlier migrations: `yarn mercato db
+ * generate` only diffs `@app` modules. Indexes mirror `data/entities.ts` 1:1.
+ */
+export class Migration20261120000000_billing_allocation_scope_indexes extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`drop index if exists "billing_allocations_source_idx";`)
+    this.addSql(`drop index if exists "billing_allocations_invoice_idx";`)
+    this.addSql(`drop index if exists "billing_allocations_account_idx";`)
+    this.addSql(
+      `create index if not exists "billing_allocations_source_idx" on "billing_allocations" ("tenant_id", "organization_id", "source_type", "source_id") where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "billing_allocations_invoice_idx" on "billing_allocations" ("tenant_id", "organization_id", "invoice_id") where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "billing_allocations_account_idx" on "billing_allocations" ("tenant_id", "organization_id", "bill_account_id") where "deleted_at" is null;`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop index if exists "billing_allocations_source_idx";`)
+    this.addSql(`drop index if exists "billing_allocations_invoice_idx";`)
+    this.addSql(`drop index if exists "billing_allocations_account_idx";`)
+    this.addSql(`create index if not exists "billing_allocations_source_idx" on "billing_allocations" ("source_type", "source_id") where "deleted_at" is null;`)
+    this.addSql(`create index if not exists "billing_allocations_invoice_idx" on "billing_allocations" ("invoice_id") where "deleted_at" is null;`)
+    this.addSql(`create index if not exists "billing_allocations_account_idx" on "billing_allocations" ("bill_account_id") where "deleted_at" is null;`)
+  }
+}

package/src/modules/billing/setup.ts

@@ -1,11 +1,7 @@
 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'
+import { getBillingSettings } from './lib/billingSettings'
 
 /**
  * Billing module setup — per-tenant defaults at module installation.
@@ -14,17 +10,11 @@ import { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'
  *   - 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`).
+ * What this file seeds (Spec 0 — no core `configs` / `dictionaries` /
+ * `sales` rows any more):
+ *   - one `billing_settings` row per organization with the defaults
+ *     (prepaid defaults + number masks). `getBillingSettings` also creates
+ *     it lazily, so this is only a warm-up.
  *
  * Default role-feature grants:
  *   - `admin` gets every `billing.*` feature.
@@ -33,214 +23,6 @@ import { ModuleConfig } from '@open-mercato/core/modules/configs/data/entities'
  *   - `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',
-  })
-
-  // ─── Prepaid balance billing (SPEC-002) ──────────────────────
-  // Fallback low-balance threshold when a prepaid account leaves its own
-  // `low_balance_threshold` null. 0 = off (status never flips to `low`
-  // until an operator sets a per-account threshold).
-  await ensureModuleConfig(em, {
-    moduleId: 'billing',
-    name: 'prepaid.low_balance_threshold_default',
-    value: 0,
-  })
-  // Default gateway provider key for top-up sessions.
-  await ensureModuleConfig(em, {
-    moduleId: 'billing',
-    name: 'prepaid.topup_provider',
-    value: 'stripe',
-  })
-  // Master switch for period statements.
-  await ensureModuleConfig(em, {
-    moduleId: 'billing',
-    name: 'prepaid.statement_enabled',
-    value: true,
-  })
-  // VAT rate (percent) applied to top-up receipts. The top-up `amount` is
-  // treated as GROSS (what the customer pays = what the balance is credited);
-  // the core tax service computes net + VAT from this rate. 0 = no VAT until
-  // an operator sets the jurisdiction's rate. (Deviation from xd-249, which
-  // never resolves a rate — see CHANGELOG.)
-  await ensureModuleConfig(em, {
-    moduleId: 'billing',
-    name: 'prepaid.topup_tax_rate',
-    value: 0,
-  })
-  // Fallback buffer for the `near_limit` credit status. 0 = warn only at the
-  // limit itself.
-  await ensureModuleConfig(em, {
-    moduleId: 'billing',
-    name: 'credit.near_limit_buffer_default',
-    value: 0,
-  })
-}
-
 // 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.
@@ -269,6 +51,8 @@ export const setup: ModuleSetupConfig = {
       'billing.credit.view',
       'billing.topup.view',
       'billing.statement.view',
+      'billing.settings.view',
+      'billing.payment.view',
     ],
 
     // Narrow scope for external usage-ingestion API keys.
@@ -276,21 +60,11 @@ export const setup: ModuleSetupConfig = {
   },
 
   /**
-   * 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.
+   * Reference data: the organization's billing settings row (Spec 0).
+   * Always runs during `mercato init`. Idempotent (race-safe upsert).
    */
   async seedDefaults({ em, tenantId, organizationId }) {
-    const scope = { tenantId, organizationId }
-    await seedBillingUomDictionary(em, scope)
-    await seedInvoiceStatusDictionary(em, scope)
+    await getBillingSettings(em as EntityManager, { tenantId, organizationId })
   },
 }
 

package/src/modules/billing/subscribers/credit-memo-auto-send.ts

@@ -0,0 +1,15 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { autoSendInvoice } from './invoice-auto-send'
+
+/** Auto-send of posted credit memos for accounts with `auto_send_invoice` (Spec D, P-D9). */
+export const metadata = {
+  event: 'billing.credit_memo.posted',
+  persistent: true,
+  id: 'billing-credit-memo-auto-send',
+}
+
+export default async function handle(payload: { invoiceId?: string; tenantId?: string; organizationId?: string }): Promise<void> {
+  const container = await createRequestContainer()
+  await autoSendInvoice((container.resolve('em') as EntityManager).fork(), payload)
+}

package/src/modules/billing/subscribers/debit-memo-apply-credit.ts

@@ -0,0 +1,15 @@
+import { applyCreditForAccount, type PostedPayload } from './invoice-apply-credit'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/** Credit auto-apply when a debit memo is posted (Spec D, P-D6) — same handler as for invoices. */
+export const metadata = {
+  event: 'billing.debit_memo.posted',
+  persistent: true,
+  id: 'billing-debit-memo-apply-credit',
+}
+
+export default async function handle(payload: PostedPayload): Promise<void> {
+  const container = await createRequestContainer()
+  await applyCreditForAccount((container.resolve('em') as EntityManager).fork(), payload)
+}

package/src/modules/billing/subscribers/debit-memo-auto-send.ts

@@ -0,0 +1,15 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { autoSendInvoice } from './invoice-auto-send'
+
+/** Auto-send of posted debit memos for accounts with `auto_send_invoice` (Spec D, P-D9). */
+export const metadata = {
+  event: 'billing.debit_memo.posted',
+  persistent: true,
+  id: 'billing-debit-memo-auto-send',
+}
+
+export default async function handle(payload: { invoiceId?: string; tenantId?: string; organizationId?: string }): Promise<void> {
+  const container = await createRequestContainer()
+  await autoSendInvoice((container.resolve('em') as EntityManager).fork(), payload)
+}

package/src/modules/billing/subscribers/invoice-apply-credit.ts

@@ -0,0 +1,39 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { BillingAccount } from '../data/entities'
+import { withAccountLock } from '../lib/accountLock'
+import { applyAccountCredit } from '../lib/allocation'
+import { emitAllocationEffects } from '../lib/allocationEvents'
+
+/**
+ * Credit auto-apply on post (Spec C, D12): when an invoice is posted, any
+ * unapplied credit of its account (overpayments, unallocated payments,
+ * open credit memos) is spent on the account's open receivables, oldest due
+ * date first. Persistent and safe to re-run (it only spends what is left).
+ */
+
+export const metadata = {
+  event: 'billing.invoice.posted',
+  persistent: true,
+  id: 'billing-invoice-apply-credit',
+}
+
+export type PostedPayload = { billAccountId?: string; tenantId?: string; organizationId?: string }
+
+export async function applyCreditForAccount(em: EntityManager, payload: PostedPayload): Promise<number> {
+  if (!payload?.billAccountId || !payload.tenantId || !payload.organizationId) return 0
+  const scope = { tenantId: payload.tenantId, organizationId: payload.organizationId }
+  const account = await em.findOne(BillingAccount, { id: payload.billAccountId, ...scope } as never)
+  if (!account || account.billingMode === 'prepaid') return 0
+  const effects = await withAccountLock(em, { tenantId: scope.tenantId, billAccountId: account.id }, (tem) =>
+    applyAccountCredit(tem, scope, { id: account.id, currencyCode: account.currencyCode }),
+  )
+  await emitAllocationEffects(scope, effects)
+  return effects.created.length
+}
+
+export default async function handle(payload: PostedPayload): Promise<void> {
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  await applyCreditForAccount(em, payload)
+}