@dainamite/billing 0.20.0 → 0.22.0

package/dist/modules/billing/subscribers/prepaid-topup-captured.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/billing/subscribers/prepaid-topup-captured.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'\nimport type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'\nimport { BillingAccount, BillingTopup } from '../data/entities'\nimport { emitBillingEvent } from '../events'\nimport { captureTopup } from '../lib/topupCapture'\nimport { getTopupTaxRate } from '../lib/prepaidConfig'\n\n/**\n * Subscriber: `payment_gateways.payment.captured` \u2192 prepaid top-up captured.\n *\n * Coexists with `payment-captured-to-paid.ts`: that subscriber matches\n * `paymentId == invoiceId` (postpaid), while a top-up's `paymentId` is a\n * minted UUID that only ever matches a `BillingTopup`. Finding the\n * BillingTopup IS the guard \u2014 for any non-top-up payment this is a silent\n * no-op.\n *\n * Idempotent: a re-fired capture on an already-captured top-up is a no-op\n * (the gateway delivers webhooks at-least-once).\n */\n\nexport const metadata = {\n  event: 'payment_gateways.payment.captured',\n  persistent: true,\n  id: 'billing-prepaid-topup-captured',\n}\n\ntype CapturedPayload = {\n  paymentId?: string\n  transactionId?: string\n  organizationId?: string\n  tenantId?: string\n  providerKey?: string\n}\n\nexport default async function handle(payload: CapturedPayload): Promise<void> {\n  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) {\n    return\n  }\n\n  const container = await createRequestContainer()\n  const em = (container.resolve('em') as EntityManager).fork()\n\n  const topup = await em.findOne(BillingTopup, {\n    paymentId: payload.paymentId,\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n    deletedAt: null,\n  })\n  if (!topup) {\n    // Not a prepaid top-up \u2014 other subscribers own this captured payment.\n    return\n  }\n  if (topup.status === 'captured') {\n    return // idempotent re-fire\n  }\n\n  const account = await em.findOne(BillingAccount, {\n    id: topup.billAccountId,\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n    deletedAt: null,\n  })\n  if (!account) {\n    return\n  }\n\n  const taxRate = await getTopupTaxRate(em)\n  const numberGenerator = container.resolve(\n    'salesDocumentNumberGenerator',\n  ) as SalesDocumentNumberGenerator\n  const taxService = container.resolve('taxCalculationService') as TaxCalculationService\n\n  const result = await captureTopup(\n    em,\n    { numberGenerator, taxService },\n    {\n      topup,\n      account: {\n        id: account.id,\n        organizationId: account.organizationId,\n        tenantId: account.tenantId,\n        currencyCode: account.currencyCode,\n      },\n      taxRate,\n      gatewayTransactionId: payload.transactionId ?? null,\n    },\n  )\n\n  if (result.status !== 'captured') return\n\n  // Side effects fire AFTER the capture transaction commits.\n  await emitBillingEvent('billing.balance.topped_up', {\n    billAccountId: account.id,\n    tenantId: account.tenantId,\n    organizationId: account.organizationId,\n    topupId: topup.id,\n    amount: topup.amount,\n    currencyCode: account.currencyCode,\n    balance: result.balanceAfter ?? null,\n    transactionId: result.transactionId ?? null,\n    receiptInvoiceId: result.receiptInvoiceId ?? null,\n  })\n\n  // Reuse the postpaid receipt path so the existing mailer / accounting bridge\n  // sends the top-up VAT receipt.\n  if (result.receiptInvoiceId) {\n    await emitBillingEvent('billing.invoice.posted', {\n      invoiceId: result.receiptInvoiceId,\n      invoiceNumber: result.invoiceNumber ?? null,\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      grandTotalGross: result.grossAmount ?? null,\n      currencyCode: account.currencyCode,\n      billAccountId: account.id,\n      kind: 'prepaid_topup',\n    })\n  }\n}\n"],
-  "mappings": "AACA,SAAS,8BAA8B;AAGvC,SAAS,gBAAgB,oBAAoB;AAC7C,SAAS,wBAAwB;AACjC,SAAS,oBAAoB;AAC7B,SAAS,uBAAuB;AAezB,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAUA,eAAO,OAA8B,SAAyC;AAC5E,MAAI,CAAC,SAAS,aAAa,CAAC,QAAQ,YAAY,CAAC,QAAQ,gBAAgB;AACvE;AAAA,EACF;AAEA,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,KAAM,UAAU,QAAQ,IAAI,EAAoB,KAAK;AAE3D,QAAM,QAAQ,MAAM,GAAG,QAAQ,cAAc;AAAA,IAC3C,WAAW,QAAQ;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,OAAO;AAEV;AAAA,EACF;AACA,MAAI,MAAM,WAAW,YAAY;AAC/B;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,GAAG,QAAQ,gBAAgB;AAAA,IAC/C,IAAI,MAAM;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,SAAS;AACZ;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,gBAAgB,EAAE;AACxC,QAAM,kBAAkB,UAAU;AAAA,IAChC;AAAA,EACF;AACA,QAAM,aAAa,UAAU,QAAQ,uBAAuB;AAE5D,QAAM,SAAS,MAAM;AAAA,IACnB;AAAA,IACA,EAAE,iBAAiB,WAAW;AAAA,IAC9B;AAAA,MACE;AAAA,MACA,SAAS;AAAA,QACP,IAAI,QAAQ;AAAA,QACZ,gBAAgB,QAAQ;AAAA,QACxB,UAAU,QAAQ;AAAA,QAClB,cAAc,QAAQ;AAAA,MACxB;AAAA,MACA;AAAA,MACA,sBAAsB,QAAQ,iBAAiB;AAAA,IACjD;AAAA,EACF;AAEA,MAAI,OAAO,WAAW,WAAY;AAGlC,QAAM,iBAAiB,6BAA6B;AAAA,IAClD,eAAe,QAAQ;AAAA,IACvB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,SAAS,MAAM;AAAA,IACf,QAAQ,MAAM;AAAA,IACd,cAAc,QAAQ;AAAA,IACtB,SAAS,OAAO,gBAAgB;AAAA,IAChC,eAAe,OAAO,iBAAiB;AAAA,IACvC,kBAAkB,OAAO,oBAAoB;AAAA,EAC/C,CAAC;AAID,MAAI,OAAO,kBAAkB;AAC3B,UAAM,iBAAiB,0BAA0B;AAAA,MAC/C,WAAW,OAAO;AAAA,MAClB,eAAe,OAAO,iBAAiB;AAAA,MACvC,UAAU,QAAQ;AAAA,MAClB,gBAAgB,QAAQ;AAAA,MACxB,iBAAiB,OAAO,eAAe;AAAA,MACvC,cAAc,QAAQ;AAAA,MACtB,eAAe,QAAQ;AAAA,MACvB,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACF;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { createRequestContainer } from '@open-mercato/shared/lib/di/container'\nimport { BillingAccount, BillingTopup } from '../data/entities'\nimport { emitBillingEvent } from '../events'\nimport { captureTopup } from '../lib/topupCapture'\nimport { getTopupTaxRate } from '../lib/prepaidConfig'\n\n/**\n * Subscriber: `payment_gateways.payment.captured` \u2192 prepaid top-up captured.\n *\n * Coexists with `payment-captured-to-paid.ts`: that subscriber matches\n * `paymentId == invoiceId` (postpaid), while a top-up's `paymentId` is a\n * minted UUID that only ever matches a `BillingTopup`. Finding the\n * BillingTopup IS the guard \u2014 for any non-top-up payment this is a silent\n * no-op.\n *\n * Idempotent: a re-fired capture on an already-captured top-up is a no-op\n * (the gateway delivers webhooks at-least-once).\n */\n\nexport const metadata = {\n  event: 'payment_gateways.payment.captured',\n  persistent: true,\n  id: 'billing-prepaid-topup-captured',\n}\n\ntype CapturedPayload = {\n  paymentId?: string\n  transactionId?: string\n  organizationId?: string\n  tenantId?: string\n  providerKey?: string\n}\n\nexport default async function handle(payload: CapturedPayload): Promise<void> {\n  if (!payload?.paymentId || !payload.tenantId || !payload.organizationId) {\n    return\n  }\n\n  const container = await createRequestContainer()\n  const em = (container.resolve('em') as EntityManager).fork()\n\n  const topup = await em.findOne(BillingTopup, {\n    paymentId: payload.paymentId,\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n    deletedAt: null,\n  })\n  if (!topup) {\n    // Not a prepaid top-up \u2014 other subscribers own this captured payment.\n    return\n  }\n  if (topup.status === 'captured') {\n    return // idempotent re-fire\n  }\n\n  const account = await em.findOne(BillingAccount, {\n    id: topup.billAccountId,\n    tenantId: payload.tenantId,\n    organizationId: payload.organizationId,\n    deletedAt: null,\n  })\n  if (!account) {\n    return\n  }\n\n  const taxRate = await getTopupTaxRate(em, {\n    tenantId: account.tenantId,\n    organizationId: account.organizationId,\n  })\n\n  const result = await captureTopup(\n    em,\n    {\n      topup,\n      account: {\n        id: account.id,\n        organizationId: account.organizationId,\n        tenantId: account.tenantId,\n        currencyCode: account.currencyCode,\n      },\n      taxRate,\n      gatewayTransactionId: payload.transactionId ?? null,\n    },\n  )\n\n  if (result.status !== 'captured') return\n\n  // Side effects fire AFTER the capture transaction commits.\n  await emitBillingEvent('billing.balance.topped_up', {\n    billAccountId: account.id,\n    tenantId: account.tenantId,\n    organizationId: account.organizationId,\n    topupId: topup.id,\n    amount: topup.amount,\n    currencyCode: account.currencyCode,\n    balance: result.balanceAfter ?? null,\n    transactionId: result.transactionId ?? null,\n    receiptInvoiceId: result.receiptInvoiceId ?? null,\n  })\n\n  // Reuse the postpaid receipt path so the existing mailer / accounting bridge\n  // sends the top-up VAT receipt.\n  if (result.receiptInvoiceId) {\n    await emitBillingEvent('billing.invoice.posted', {\n      invoiceId: result.receiptInvoiceId,\n      invoiceNumber: result.invoiceNumber ?? null,\n      tenantId: account.tenantId,\n      organizationId: account.organizationId,\n      grandTotalGross: result.grossAmount ?? null,\n      currencyCode: account.currencyCode,\n      billAccountId: account.id,\n      kind: 'prepaid_topup',\n    })\n  }\n}\n"],
+  "mappings": "AACA,SAAS,8BAA8B;AACvC,SAAS,gBAAgB,oBAAoB;AAC7C,SAAS,wBAAwB;AACjC,SAAS,oBAAoB;AAC7B,SAAS,uBAAuB;AAezB,MAAM,WAAW;AAAA,EACtB,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,IAAI;AACN;AAUA,eAAO,OAA8B,SAAyC;AAC5E,MAAI,CAAC,SAAS,aAAa,CAAC,QAAQ,YAAY,CAAC,QAAQ,gBAAgB;AACvE;AAAA,EACF;AAEA,QAAM,YAAY,MAAM,uBAAuB;AAC/C,QAAM,KAAM,UAAU,QAAQ,IAAI,EAAoB,KAAK;AAE3D,QAAM,QAAQ,MAAM,GAAG,QAAQ,cAAc;AAAA,IAC3C,WAAW,QAAQ;AAAA,IACnB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,OAAO;AAEV;AAAA,EACF;AACA,MAAI,MAAM,WAAW,YAAY;AAC/B;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,GAAG,QAAQ,gBAAgB;AAAA,IAC/C,IAAI,MAAM;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,WAAW;AAAA,EACb,CAAC;AACD,MAAI,CAAC,SAAS;AACZ;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,gBAAgB,IAAI;AAAA,IACxC,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,EAC1B,CAAC;AAED,QAAM,SAAS,MAAM;AAAA,IACnB;AAAA,IACA;AAAA,MACE;AAAA,MACA,SAAS;AAAA,QACP,IAAI,QAAQ;AAAA,QACZ,gBAAgB,QAAQ;AAAA,QACxB,UAAU,QAAQ;AAAA,QAClB,cAAc,QAAQ;AAAA,MACxB;AAAA,MACA;AAAA,MACA,sBAAsB,QAAQ,iBAAiB;AAAA,IACjD;AAAA,EACF;AAEA,MAAI,OAAO,WAAW,WAAY;AAGlC,QAAM,iBAAiB,6BAA6B;AAAA,IAClD,eAAe,QAAQ;AAAA,IACvB,UAAU,QAAQ;AAAA,IAClB,gBAAgB,QAAQ;AAAA,IACxB,SAAS,MAAM;AAAA,IACf,QAAQ,MAAM;AAAA,IACd,cAAc,QAAQ;AAAA,IACtB,SAAS,OAAO,gBAAgB;AAAA,IAChC,eAAe,OAAO,iBAAiB;AAAA,IACvC,kBAAkB,OAAO,oBAAoB;AAAA,EAC/C,CAAC;AAID,MAAI,OAAO,kBAAkB;AAC3B,UAAM,iBAAiB,0BAA0B;AAAA,MAC/C,WAAW,OAAO;AAAA,MAClB,eAAe,OAAO,iBAAiB;AAAA,MACvC,UAAU,QAAQ;AAAA,MAClB,gBAAgB,QAAQ;AAAA,MACxB,iBAAiB,OAAO,eAAe;AAAA,MACvC,cAAc,QAAQ;AAAA,MACtB,eAAe,QAAQ;AAAA,MACvB,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACF;",
   "names": []
 }

package/generated/entities/billing_account/index.ts

@@ -5,6 +5,7 @@ export const id = "id"
 export const organization_id = "organization_id"
 export const tenant_id = "tenant_id"
 export const customer_id = "customer_id"
+export const customer_kind = "customer_kind"
 export const name = "name"
 export const currency_code = "currency_code"
 export const bill_cycle = "bill_cycle"
@@ -17,6 +18,8 @@ export const next_bill_date = "next_bill_date"
 export const last_bill_date = "last_bill_date"
 export const billing_mode = "billing_mode"
 export const credit_limit = "credit_limit"
+export const payment_terms_days = "payment_terms_days"
+export const auto_send_invoice = "auto_send_invoice"
 export const is_active = "is_active"
 export const created_at = "created_at"
 export const updated_at = "updated_at"

package/generated/entities/billing_allocation/index.ts

@@ -0,0 +1,18 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_allocation (BillingAllocation, table billing_allocations).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const source_type = "source_type"
+export const source_id = "source_id"
+export const invoice_id = "invoice_id"
+export const bill_account_id = "bill_account_id"
+export const amount = "amount"
+export const currency_code = "currency_code"
+export const allocated_by = "allocated_by"
+export const user_id = "user_id"
+export const deallocated_by_user_id = "deallocated_by_user_id"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_document_sequence/index.ts

@@ -0,0 +1,11 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_document_sequence (BillingDocumentSequence, table billing_document_sequences).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const series = "series"
+export const scope_key = "scope_key"
+export const next_value = "next_value"
+export const created_at = "created_at"
+export const updated_at = "updated_at"

package/generated/entities/billing_invoice/index.ts

@@ -0,0 +1,38 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_invoice (BillingInvoice, table billing_invoices).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const bill_account_id = "bill_account_id"
+export const document_type = "document_type"
+export const number = "number"
+export const series = "series"
+export const status = "status"
+export const test_run = "test_run"
+export const bill_run_id = "bill_run_id"
+export const bill_date = "bill_date"
+export const period_start = "period_start"
+export const period_end = "period_end"
+export const issue_date = "issue_date"
+export const due_date = "due_date"
+export const currency_code = "currency_code"
+export const subtotal_net = "subtotal_net"
+export const tax_total = "tax_total"
+export const total_gross = "total_gross"
+export const paid_total = "paid_total"
+export const credited_total = "credited_total"
+export const outstanding = "outstanding"
+export const corrects_invoice_id = "corrects_invoice_id"
+export const correction_reason = "correction_reason"
+export const corrects_invoice_number = "corrects_invoice_number"
+export const corrects_issue_date = "corrects_issue_date"
+export const buyer_snapshot = "buyer_snapshot"
+export const seller_snapshot = "seller_snapshot"
+export const pdf_attachment_id = "pdf_attachment_id"
+export const topup_id = "topup_id"
+export const posted_at = "posted_at"
+export const metadata = "metadata"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_invoice_line/index.ts

@@ -0,0 +1,24 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_invoice_line (BillingInvoiceLine, table billing_invoice_lines).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const invoice_id = "invoice_id"
+export const line_number = "line_number"
+export const billing_item_id = "billing_item_id"
+export const billing_type = "billing_type"
+export const description = "description"
+export const quantity = "quantity"
+export const unit_price_net = "unit_price_net"
+export const tax_rate = "tax_rate"
+export const net_amount = "net_amount"
+export const tax_amount = "tax_amount"
+export const gross_amount = "gross_amount"
+export const service_period_start = "service_period_start"
+export const service_period_end = "service_period_end"
+export const corrects_line_id = "corrects_line_id"
+export const metadata = "metadata"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_item/index.ts

@@ -16,6 +16,10 @@ export const subscription_item_id = "subscription_item_id"
 export const source_ref = "source_ref"
 export const currency_mismatch = "currency_mismatch"
 export const billed_to_date = "billed_to_date"
+export const charge_timing = "charge_timing"
+export const prorate = "prorate"
+export const tax_rate = "tax_rate"
+export const price_basis = "price_basis"
 export const is_active = "is_active"
 export const created_at = "created_at"
 export const updated_at = "updated_at"

package/generated/entities/billing_payment/index.ts

@@ -0,0 +1,25 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_payment (BillingPayment, table billing_payments).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const received_at = "received_at"
+export const amount = "amount"
+export const currency_code = "currency_code"
+export const reference = "reference"
+export const payer_name = "payer_name"
+export const payer_account = "payer_account"
+export const source = "source"
+export const import_id = "import_id"
+export const bill_account_id = "bill_account_id"
+export const status = "status"
+export const unallocated_amount = "unallocated_amount"
+export const match_reason = "match_reason"
+export const source_ref = "source_ref"
+export const external_ref = "external_ref"
+export const topup_id = "topup_id"
+export const metadata = "metadata"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_payment_import/index.ts

@@ -0,0 +1,14 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_payment_import (BillingPaymentImport, table billing_payment_imports).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const file_name = "file_name"
+export const row_count = "row_count"
+export const counts = "counts"
+export const errors = "errors"
+export const user_id = "user_id"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_run/index.ts

@@ -8,7 +8,6 @@ export const triggered_by = "triggered_by"
 export const parent_run_id = "parent_run_id"
 export const dry_run = "dry_run"
 export const test_mode = "test_mode"
-export const catch_up = "catch_up"
 export const scoped_account_ids = "scoped_account_ids"
 export const as_of_date = "as_of_date"
 export const started_at = "started_at"

package/generated/entities/billing_run_outcome/index.ts

@@ -11,6 +11,7 @@ export const error_message = "error_message"
 export const warnings = "warnings"
 export const draft_invoice_id = "draft_invoice_id"
 export const statement_id = "statement_id"
+export const cycles = "cycles"
 export const is_active = "is_active"
 export const created_at = "created_at"
 export const updated_at = "updated_at"

package/generated/entities/billing_settings/index.ts

@@ -0,0 +1,26 @@
+// AUTO-GENERATED by @dainamite/billing scripts/generate-entity-registry.mjs — do not edit.
+// Columns of billing:billing_settings (BillingSettings, table billing_settings).
+
+export const id = "id"
+export const organization_id = "organization_id"
+export const tenant_id = "tenant_id"
+export const low_balance_threshold_default = "low_balance_threshold_default"
+export const near_limit_buffer_default = "near_limit_buffer_default"
+export const statement_enabled = "statement_enabled"
+export const topup_tax_rate = "topup_tax_rate"
+export const prepaid_tax_point = "prepaid_tax_point"
+export const topup_provider = "topup_provider"
+export const number_masks = "number_masks"
+export const legal_name = "legal_name"
+export const seller_address = "seller_address"
+export const tax_id = "tax_id"
+export const bank_name = "bank_name"
+export const iban = "iban"
+export const bic = "bic"
+export const invoice_footer = "invoice_footer"
+export const logo_attachment_id = "logo_attachment_id"
+export const default_payment_terms_days = "default_payment_terms_days"
+export const default_tax_rate = "default_tax_rate"
+export const created_at = "created_at"
+export const updated_at = "updated_at"
+export const deleted_at = "deleted_at"

package/generated/entities/billing_statement/index.ts

@@ -16,6 +16,7 @@ export const total_recurring = "total_recurring"
 export const total_adjustments = "total_adjustments"
 export const closing_balance = "closing_balance"
 export const debit_breakdown = "debit_breakdown"
+export const vat_summary = "vat_summary"
 export const status = "status"
 export const created_at = "created_at"
 export const updated_at = "updated_at"

package/generated/entities.ids.generated.ts

@@ -21,6 +21,13 @@ export const E = {
     billing_account_transaction: 'billing:billing_account_transaction',
     billing_topup: 'billing:billing_topup',
     billing_statement: 'billing:billing_statement',
+    billing_invoice: 'billing:billing_invoice',
+    billing_invoice_line: 'billing:billing_invoice_line',
+    billing_document_sequence: 'billing:billing_document_sequence',
+    billing_settings: 'billing:billing_settings',
+    billing_payment: 'billing:billing_payment',
+    billing_allocation: 'billing:billing_allocation',
+    billing_payment_import: 'billing:billing_payment_import',
   },
 } as const
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dainamite/billing",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Dainamite Billing — lightweight recurring-billing engine for Open Mercato (Bill Runs, one-time / recurring / usage items, draft invoices in core/sales with human approval).",
   "type": "module",
   "main": "./dist/modules/billing/index.js",
@@ -145,5 +145,9 @@
   "license": "MIT",
   "engines": {
     "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@pdf-lib/fontkit": "^1.1.1",
+    "pdf-lib": "^1.17.1"
   }
 }

package/src/modules/billing/__integration__/TC-BILL-004.spec.ts

@@ -0,0 +1,171 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+import {
+  createPersonFixture,
+  deleteEntityIfExists,
+} from '@open-mercato/core/helpers/integration/crmFixtures'
+
+/**
+ * TC-BILL-004: B2C billing accounts, invoice-language picklist, return-to-account navigation
+ * Category: BILL — API + UI
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-account-workspace.md (Phase 1, D21–D23)
+ *
+ * Self-contained: creates its own person, account and item; removes them
+ * in teardown. Avoids `GET /api/billing/accounts?id=` (known CI flake, see
+ * TC-BILL-001) — reads back through the `customerKind` + `search` filters.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+function accountPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    customerId: `cust-${uniq()}`,
+    name: `B2C Account ${uniq()}`,
+    currencyCode: 'PLN',
+    billCycle: 'monthly',
+    billCycleAnchor: '1',
+    invoiceEmail: `inv-${uniq()}@example.com`,
+    invoiceLanguage: 'pl',
+    nextBillDate: '2026-12-01',
+    invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    ...overrides,
+  }
+}
+
+async function createAccount(
+  request: APIRequestContext,
+  token: string,
+  data: Record<string, unknown>,
+): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/accounts', { token, data })
+  expect(res.ok(), `POST /api/billing/accounts status was ${res.status()}`).toBeTruthy()
+  const body = (await res.json()) as { id?: string }
+  expect(body.id).toBeTruthy()
+  return body.id as string
+}
+
+async function createItem(request: APIRequestContext, token: string, billAccountId: string): Promise<string> {
+  const res = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: {
+      billAccountId,
+      type: 'recurring',
+      billStartDate: '2026-12-01',
+      description: `Internet 300 ${uniq()}`,
+      rateJson: { unit_price: 79 },
+    },
+  })
+  expect(res.ok(), `POST /api/billing/items status was ${res.status()}`).toBeTruthy()
+  return ((await res.json()) as { id: string }).id
+}
+
+test.describe('TC-BILL-004: B2C accounts + navigation', () => {
+  let token: string
+  const accountIds: string[] = []
+  const itemIds: string[] = []
+  const personIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (itemIds.length) {
+      await apiRequest(request, 'DELETE', '/api/billing/items', { token, data: { id: itemIds.pop() } })
+    }
+    while (accountIds.length) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id: accountIds.pop() } })
+    }
+    while (personIds.length) {
+      await deleteEntityIfExists(request, token, '/api/customers/people', personIds.pop() ?? null)
+    }
+  })
+
+  test('creates a person (B2C) account and filters by customer kind', async ({ request }) => {
+    const suffix = uniq()
+    const personId = await createPersonFixture(request, token, {
+      firstName: 'Jan',
+      lastName: `Kowalski ${suffix}`,
+      displayName: `Jan Kowalski ${suffix}`,
+      primaryEmail: `jan-${suffix}@example.com`,
+    })
+    personIds.push(personId)
+    const name = `B2C ${suffix}`
+    accountIds.push(
+      await createAccount(request, token, accountPayload({ customerId: personId, customerKind: 'person', name })),
+    )
+
+    const persons = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=person&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const personRows = ((await persons.json()) as { items: Array<{ name: string; customer_kind: string }> }).items
+    expect(personRows.find((row) => row.name === name)?.customer_kind).toBe('person')
+
+    const companies = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=company&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const companyRows = ((await companies.json()) as { items: Array<{ name: string }> }).items
+    expect(companyRows.some((row) => row.name === name)).toBe(false)
+  })
+
+  test('defaults customer kind to company', async ({ request }) => {
+    const name = `Company ${uniq()}`
+    accountIds.push(await createAccount(request, token, accountPayload({ name })))
+    const res = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/accounts?customerKind=company&search=${encodeURIComponent(name)}`,
+      { token },
+    )
+    const rows = ((await res.json()) as { items: Array<{ name: string; customer_kind: string }> }).items
+    expect(rows.find((row) => row.name === name)?.customer_kind).toBe('company')
+  })
+
+  test('rejects an invoice language the template does not support', async ({ request }) => {
+    const res = await apiRequest(request, 'POST', '/api/billing/accounts', {
+      token,
+      // `fr` has no document template (spec 2026-11-15-billing-multi-language).
+      data: accountPayload({ invoiceLanguage: 'fr' }),
+    })
+    expect(res.status()).toBe(400)
+  })
+
+  test('item pages return to the owning account; from the items list they return to the list', async ({
+    page,
+    request,
+  }) => {
+    const accountId = await createAccount(request, token, accountPayload())
+    accountIds.push(accountId)
+    const itemId = await createItem(request, token, accountId)
+    itemIds.push(itemId)
+
+    await login(page, 'admin')
+
+    // FormHeader's back link is the anchor rendering the "←" glyph. (The
+    // detail body also links to the account, so match the header link only.)
+    const backLink = page.locator('a', { hasText: '←' }).first()
+
+    // Opened in account context → back goes to the account's Items tab (Spec F, F8).
+    await page.goto(`/backend/billing/items/${itemId}`, { waitUntil: 'domcontentloaded' })
+    await expect(backLink).toHaveAttribute('href', `/backend/billing/accounts/${accountId}?tab=items`)
+
+    // Opened from the global Items list → back goes to the list.
+    await page.goto(`/backend/billing/items/${itemId}?from=items`, { waitUntil: 'domcontentloaded' })
+    await expect(backLink).toHaveAttribute('href', '/backend/billing/items')
+
+    // "Add item" from an account → Cancel returns to that account's Items tab.
+    await page.goto(`/backend/billing/items/create?billAccountId=${accountId}`, {
+      waitUntil: 'domcontentloaded',
+    })
+    await page.getByRole('button', { name: /cancel/i }).first().click()
+    await expect(page).toHaveURL(new RegExp(`/backend/billing/accounts/${accountId}\\?tab=items$`))
+  })
+})

package/src/modules/billing/__integration__/TC-BILL-005.spec.ts

@@ -0,0 +1,134 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+import { getAuthToken, apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-BILL-005: Bill Run catches up on every due cycle (Spec A)
+ * Category: BILL — API
+ * Priority: High
+ * Spec: .ai/specs/2026-11-14-billing-cycle-semantics.md
+ *
+ * An account whose next bill date lies three cycles before the as-of date,
+ * with one monthly in-advance item:
+ *   - a dry run previews 3 cycles and writes no invoice;
+ *   - a test run writes 3 TEST drafts (one per bill date), each covering its
+ *     own month, and leaves the account untouched;
+ *   - a legacy `catchUp` flag in the body is accepted and ignored.
+ * Self-contained: creates its own account + item, wipes its test drafts.
+ * Scoped with `scopedAccountIds` so other tenant data can't interfere.
+ */
+
+const uniq = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+type Cycle = { bill_date: string; period_start: string | null; period_end: string | null; status: string; invoice_id: string | null }
+
+async function createAccountWithItem(request: APIRequestContext, token: string): Promise<string> {
+  const account = await apiRequest(request, 'POST', '/api/billing/accounts', {
+    token,
+    data: {
+      customerId: `cust-${uniq()}`,
+      name: `Catch-up ${uniq()}`,
+      currencyCode: 'PLN',
+      billCycle: 'monthly',
+      billCycleAnchor: '1',
+      invoiceEmail: `inv-${uniq()}@example.com`,
+      invoiceLanguage: 'en',
+      nextBillDate: '2026-08-01',
+      invoiceAddress: { line1: 'ul. Testowa 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+    },
+  })
+  expect(account.ok(), `POST account status was ${account.status()}`).toBeTruthy()
+  const accountId = ((await account.json()) as { id: string }).id
+
+  const item = await apiRequest(request, 'POST', '/api/billing/items', {
+    token,
+    data: {
+      billAccountId: accountId,
+      type: 'recurring',
+      billStartDate: '2026-08-01',
+      description: 'Internet 300',
+      rateJson: { unit_price: 100 },
+      chargeTiming: 'in_advance',
+    },
+  })
+  expect(item.ok(), `POST item status was ${item.status()}`).toBeTruthy()
+  return accountId
+}
+
+async function runCycles(
+  request: APIRequestContext,
+  token: string,
+  accountId: string,
+  mode: 'dry' | 'test',
+): Promise<{ billRunId: string; cycles: Cycle[] }> {
+  const run = await apiRequest(request, 'POST', '/api/billing/runs', {
+    token,
+    data: { mode, asOfDate: '2026-10-15', scopedAccountIds: [accountId], catchUp: true },
+  })
+  expect(run.ok(), `POST run (${mode}) status was ${run.status()}`).toBeTruthy()
+  const { billRunId } = (await run.json()) as { billRunId: string }
+
+  const outcomes = await apiRequest(request, 'GET', `/api/billing/run-outcomes?billRunId=${billRunId}`, { token })
+  const body = (await outcomes.json()) as { items: Array<{ bill_account_id: string; cycles: Cycle[] | null }> }
+  const outcome = body.items.find((row) => row.bill_account_id === accountId)
+  expect(outcome, 'outcome for the scoped account').toBeTruthy()
+  return { billRunId, cycles: outcome?.cycles ?? [] }
+}
+
+test.describe('TC-BILL-005: Bill Run catch-up (Spec A)', () => {
+  let token: string
+  let accountId: string | null = null
+  const testRunIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    token = await getAuthToken(request, 'admin')
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (testRunIds.length) {
+      await apiRequest(request, 'POST', '/api/billing/test-invoices/wipe', {
+        token,
+        data: { billRunId: testRunIds.pop() },
+      })
+    }
+    if (accountId) {
+      await apiRequest(request, 'DELETE', '/api/billing/accounts', { token, data: { id: accountId } })
+      accountId = null
+    }
+  })
+
+  test('dry run previews every due cycle without writing invoices', async ({ request }) => {
+    accountId = await createAccountWithItem(request, token)
+    const { cycles } = await runCycles(request, token, accountId, 'dry')
+    expect(cycles.map((c) => [c.bill_date, c.status, c.invoice_id])).toEqual([
+      ['2026-08-01', 'previewed', null],
+      ['2026-09-01', 'previewed', null],
+      ['2026-10-01', 'previewed', null],
+    ])
+  })
+
+  test('test run writes one TEST draft per bill date, each for its own month', async ({ request }) => {
+    accountId = await createAccountWithItem(request, token)
+    const { billRunId, cycles } = await runCycles(request, token, accountId, 'test')
+    testRunIds.push(billRunId)
+
+    expect(cycles.map((c) => [c.bill_date, c.period_start, c.period_end, c.status])).toEqual([
+      ['2026-08-01', '2026-08-01', '2026-08-31', 'invoiced'],
+      ['2026-09-01', '2026-09-01', '2026-09-30', 'invoiced'],
+      ['2026-10-01', '2026-10-01', '2026-10-31', 'invoiced'],
+    ])
+    expect(new Set(cycles.map((c) => c.invoice_id)).size).toBe(3)
+
+    const invoices = await apiRequest(
+      request,
+      'GET',
+      `/api/billing/invoices?billAccountId=${accountId}&testRun=true`,
+      { token },
+    )
+    const invoiceRows = ((await invoices.json()) as { items: unknown[] }).items
+    expect(invoiceRows).toHaveLength(3)
+
+    // Test mode never advances the account: a second dry run still sees 3 cycles.
+    const again = await runCycles(request, token, accountId, 'dry')
+    expect(again.cycles).toHaveLength(3)
+  })
+})