@dainamite/billing 0.20.0 → 0.21.0

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

@@ -0,0 +1,42 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Test-run cleanup shared by the "wipe test invoices" and "delete run"
+ * commands (Spec F, P-D1).
+ *
+ * Hard-deletes test drafts (`test_run = true`, `document_type = 'invoice'`)
+ * together with their lines and their draft-edit audit rows. Scoped by
+ * tenant + organization, and optionally by one Bill Run. Must run inside the
+ * caller's transaction.
+ */
+
+export type TestRunCleanupScope = {
+  tenantId: string
+  organizationId: string
+  /** When set, only test invoices written by this Bill Run are removed. */
+  billRunId?: string | null
+}
+
+export async function deleteTestRunArtifacts(
+  em: EntityManager,
+  scope: TestRunCleanupScope,
+): Promise<number> {
+  const params: unknown[] = [scope.tenantId, scope.organizationId]
+  let billRunClause = ''
+  if (scope.billRunId) {
+    billRunClause = ' AND bill_run_id = ?'
+    params.push(scope.billRunId)
+  }
+  const rows = (await em.execute(
+    `SELECT id FROM billing_invoices
+     WHERE tenant_id = ? AND organization_id = ? AND test_run = true AND document_type = 'invoice'${billRunClause}`,
+    params,
+  )) as unknown as Array<{ id: string }> | undefined
+  const ids = (rows ?? []).map((row) => row.id)
+  if (ids.length === 0) return 0
+  const placeholders = ids.map(() => '?').join(',')
+  await em.execute(`DELETE FROM billing_draft_invoice_edits WHERE invoice_id IN (${placeholders})`, ids)
+  await em.execute(`DELETE FROM billing_invoice_lines WHERE invoice_id IN (${placeholders})`, ids)
+  await em.execute(`DELETE FROM billing_invoices WHERE id IN (${placeholders})`, ids)
+  return ids.length
+}

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

@@ -1,7 +1,7 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { BillingTopup } from '../data/entities'
 import { applyBalanceMovement } from './balanceLedger'
-import { createTopupReceipt, type TopupReceiptDeps } from './topupReceipt'
+import { createTopupReceipt } from './topupReceipt'
 
 /**
  * Idempotent top-up capture (SPEC-002 P2).
@@ -10,7 +10,7 @@ import { createTopupReceipt, type TopupReceiptDeps } from './topupReceipt'
  *   - credit the balance (atomic) + append a `type='topup'` transaction with a
  *     deterministic `source_ref = topup-{paymentId}` (so a re-fired capture can
  *     never double-credit),
- *   - create the posted+paid VAT receipt in core/sales,
+ *   - create the paid VAT receipt as a billing document (`document_type = 'receipt'`),
  *   - transition the BillingTopup → captured, backfilling `transaction_id` +
  *     `receipt_invoice_id`.
  *
@@ -45,7 +45,6 @@ export type CaptureTopupResult = {
 
 export async function captureTopup(
   em: EntityManager,
-  deps: TopupReceiptDeps,
   params: CaptureTopupParams,
 ): Promise<CaptureTopupResult> {
   const { topup, account } = params
@@ -88,7 +87,7 @@ export async function captureTopup(
     }
 
     // 2. Fiscal VAT receipt (posted+paid).
-    const receipt = await createTopupReceipt(tem as EntityManager, deps, {
+    const receipt = await createTopupReceipt(tem as EntityManager, {
       account,
       topupId: topup.id,
       paymentId: topup.paymentId,

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

@@ -1,24 +1,24 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
-import {
-  SalesInvoice,
-  SalesInvoiceLine,
-} from '@open-mercato/core/modules/sales/data/entities'
-import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
-import type { TaxCalculationService } from '@open-mercato/core/modules/sales/services/taxCalculationService'
-import { resolveInvoiceStatusEntryId } from './invoiceStatus'
+import { BillingInvoice, BillingInvoiceLine } from '../data/entities'
+import { getBillingSettings, numberMaskFor } from './billingSettings'
+import { claimDocumentNumber } from './numbering'
+import { lineAmountsFromGross, money4 } from './vat'
 
 /**
- * Creates the fiscal VAT receipt for a captured prepaid top-up (SPEC-002 P2).
+ * Creates the fiscal VAT receipt for a captured prepaid top-up (SPEC-002 P2,
+ * Spec 0 E-D3).
  *
- * Deliberate divergence from the postpaid draft→post gate: a captured top-up
- * is a completed, already-paid transaction with nothing to review, so the
- * receipt is created **posted + paid** in one shot (the gate exists for
- * outbound bills, not money already received — mirrors the xd-249 "deviations"
- * convention).
+ * The receipt is a billing-owned document (`billing_invoices` with
+ * `document_type = 'receipt'`, `status = 'paid'`), numbered from the
+ * `receipt` series (default mask `RC/{YYYY}/{MM}/{SEQUENCE_NUM_MONTH:4}`).
+ * Nothing is written to core `sales`.
  *
- * **VAT at top-up.** The top-up `amount` is the GROSS the customer paid (= the
- * balance credited). The core tax service splits it into net + VAT at the
- * configured rate. Gap-free numbering reuses `salesDocumentNumberGenerator`.
+ * VAT at top-up: the top-up `amount` is the GROSS the customer paid (= the
+ * balance credited); `vat.lineAmountsFromGross` splits it into net + tax with
+ * `net + tax = gross` exactly.
+ *
+ * MUST run inside the capture transaction (`captureTopup`) so the receipt
+ * number, the balance credit and the top-up transition commit together.
  */
 
 export type TopupReceiptParams = {
@@ -36,11 +36,6 @@ export type TopupReceiptParams = {
   taxRate: number
 }
 
-export type TopupReceiptDeps = {
-  numberGenerator: Pick<SalesDocumentNumberGenerator, 'generate'>
-  taxService: TaxCalculationService
-}
-
 export type TopupReceipt = {
   invoiceId: string
   invoiceNumber: string
@@ -50,104 +45,76 @@ export type TopupReceipt = {
   taxRate: number
 }
 
-function fmt4(value: number): string {
-  return (Number.isFinite(value) ? value : 0).toFixed(4)
+function todayUtc(): Date {
+  const now = new Date()
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()))
 }
 
-export async function createTopupReceipt(
-  em: EntityManager,
-  deps: TopupReceiptDeps,
-  params: TopupReceiptParams,
-): Promise<TopupReceipt> {
+export async function createTopupReceipt(em: EntityManager, params: TopupReceiptParams): Promise<TopupReceipt> {
   const { account } = params
+  const scope = { tenantId: account.tenantId, organizationId: account.organizationId }
+  const taxRate = Number.isFinite(params.taxRate) && params.taxRate > 0 ? params.taxRate : 0
+  const amounts = lineAmountsFromGross(Number.parseFloat(params.amount), taxRate)
+  const net = money4(amounts.net)
+  const tax = money4(amounts.tax)
+  const gross = money4(amounts.gross)
 
-  // VAT split — the top-up amount is GROSS (what was paid = balance credited).
-  const tax = await deps.taxService.calculateUnitAmounts({
-    amount: Number.parseFloat(params.amount),
-    mode: 'gross',
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    taxRate: params.taxRate,
-  })
-  const net = fmt4(tax.netAmount)
-  const gross = fmt4(tax.grossAmount)
-  const taxAmount = fmt4(tax.taxAmount)
-  const effectiveRate = tax.taxRate ?? 0
-
-  const generated = await deps.numberGenerator.generate({
-    kind: 'invoice',
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-  })
-
-  // Posted+paid in one shot — resolve the `paid` status entry directly.
-  const paidStatusEntryId = await resolveInvoiceStatusEntryId(
-    em,
-    account.tenantId,
-    account.organizationId,
-    'paid',
-  )
+  const settings = await getBillingSettings(em, scope)
+  const issueDate = todayUtc()
+  const claimed = await claimDocumentNumber(em, scope, 'receipt', numberMaskFor(settings, 'receipt'), issueDate)
 
   const now = new Date()
-  const invoice = em.create(SalesInvoice, {
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    invoiceNumber: generated.number,
-    statusEntryId: paidStatusEntryId,
+  const receipt = em.create(BillingInvoice, {
+    ...scope,
+    billAccountId: account.id,
+    documentType: 'receipt',
+    number: claimed.number,
+    series: 'receipt',
     status: 'paid',
-    issueDate: now,
+    testRun: false,
+    issueDate,
+    postedAt: now,
     currencyCode: account.currencyCode,
-    subtotalNetAmount: net,
-    subtotalGrossAmount: gross,
-    discountTotalAmount: '0',
-    taxTotalAmount: taxAmount,
-    grandTotalNetAmount: net,
-    grandTotalGrossAmount: gross,
-    paidTotalAmount: gross,
-    outstandingAmount: '0',
-    metadata: {
-      kind: 'prepaid_topup',
-      bill_account_id: account.id,
-      topup_id: params.topupId,
-      payment_id: params.paymentId,
-    },
+    subtotalNet: net,
+    taxTotal: tax,
+    totalGross: gross,
+    paidTotal: gross,
+    creditedTotal: '0',
+    outstanding: '0',
+    topupId: params.topupId,
+    metadata: { kind: 'prepaid_topup', payment_id: params.paymentId },
     createdAt: now,
     updatedAt: now,
   })
-  em.persist(invoice)
+  em.persist(receipt)
+  await em.flush() // need the receipt id for the line
 
-  const line = em.create(SalesInvoiceLine, {
-    invoice,
-    organizationId: account.organizationId,
-    tenantId: account.tenantId,
-    lineNumber: 1,
-    kind: 'service',
-    description: 'Account top-up',
-    quantity: '1',
-    normalizedQuantity: '1',
-    currencyCode: account.currencyCode,
-    unitPriceNet: net,
-    unitPriceGross: gross,
-    discountAmount: '0',
-    discountPercent: '0',
-    taxRate: fmt4(effectiveRate),
-    taxAmount,
-    totalNetAmount: net,
-    totalGrossAmount: gross,
-    metadata: {
-      kind: 'prepaid_topup',
-      topup_id: params.topupId,
-    },
-  })
-  em.persist(line)
+  em.persist(
+    em.create(BillingInvoiceLine, {
+      ...scope,
+      invoiceId: receipt.id,
+      lineNumber: 1,
+      billingType: 'receipt',
+      description: 'Account top-up',
+      quantity: '1.0000',
+      unitPriceNet: net,
+      taxRate: taxRate.toFixed(4),
+      netAmount: net,
+      taxAmount: tax,
+      grossAmount: gross,
+      metadata: { kind: 'prepaid_topup', topup_id: params.topupId },
+      createdAt: now,
+      updatedAt: now,
+    }),
+  )
   await em.flush()
 
   return {
-    invoiceId: invoice.id,
-    invoiceNumber: generated.number,
+    invoiceId: receipt.id,
+    invoiceNumber: claimed.number,
     netAmount: net,
-    taxAmount,
+    taxAmount: tax,
     grossAmount: gross,
-    taxRate: effectiveRate,
+    taxRate,
   }
 }

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

@@ -11,7 +11,7 @@
  *   - `amount` — numeric string, rounded 2dp half-up, formatted to 4
  *     decimals to match the `core/sales` numeric(18,4) column shape.
  *   - `breakdown` — per-tier rated quantity / amount, persisted into
- *     `SalesInvoiceLine.metadata.usage_tier_breakdown` so operators
+ *     `billing_invoice_lines.metadata.usage_tier_breakdown` so operators
  *     can see how the line was built without re-running the math.
  */
 

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

@@ -1,8 +1,9 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { type BillingAccount, type BillingItem } from '../data/entities'
 import type { BillPeriod } from './billPeriod'
-import type { InvoiceLineDescriptor } from './invoiceWriter'
+import { itemTaxRate, type InvoiceLineDescriptor } from './invoiceWriter'
 import { format4dp, formatUnitPrice, rateUsageForItem, type UsageRate } from './usageRater'
+import { priceBasisOf } from './lineAmounts'
 
 /**
  * Per-account usage processing — Phase 3.
@@ -103,7 +104,13 @@ async function fetchUsageAggregate(
   em: EntityManager,
   account: BillingAccount,
   period: BillPeriod,
+  after: Date | null,
 ): Promise<UsageAggregateRow[]> {
+  // `after` (Spec A): exclusive lower bound for multi-cycle test / dry runs,
+  // which never mark records as rated — without it every simulated cycle
+  // would re-count the usage an earlier simulated cycle already billed.
+  const params: unknown[] = [account.tenantId, account.organizationId, account.id, period.periodEnd]
+  if (after) params.push(after)
   const rows = (await em.execute(
     `SELECT uom_code,
             SUM(quantity)::text AS total_quantity,
@@ -115,8 +122,9 @@ async function fetchUsageAggregate(
        AND deleted_at IS NULL
        AND rated_in_bill_run_id IS NULL
        AND period_end <= ?
+       ${after ? 'AND period_end > ?' : ''}
      GROUP BY uom_code`,
-    [account.tenantId, account.organizationId, account.id, period.periodEnd],
+    params,
   )) as unknown as UsageAggregateRow[] | undefined
   return rows ?? []
 }
@@ -126,8 +134,9 @@ export async function processUsageForAccount(
   account: BillingAccount,
   period: BillPeriod,
   usageItems: readonly BillingItem[],
+  options: { after?: Date | null } = {},
 ): Promise<UsageRunResult> {
-  const aggregateRows = await fetchUsageAggregate(em, account, period)
+  const aggregateRows = await fetchUsageAggregate(em, account, period, options.after ?? null)
   if (aggregateRows.length === 0) return EMPTY_RESULT
 
   const itemByUom = nonNullUomItems(usageItems)
@@ -167,9 +176,12 @@ export async function processUsageForAccount(
       billingItemId: item.id,
       billingType: 'usage',
       description: item.description,
-      unitPriceNet,
+      unitPrice: unitPriceNet,
       quantity: format4dp(totalQuantity),
-      totalNetAmount: rated.amount,
+      lineAmount: rated.amount,
+      // Tiered rates are always net (P-D4); a simple rate keeps the item basis.
+      priceBasis: isSimpleFlat ? priceBasisOf(item.priceBasis) : 'net',
+      taxRate: itemTaxRate(item),
       metadataExtra: {
         uom_code: uom,
         usage_record_count: recordCount,

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

@@ -0,0 +1,56 @@
+/**
+ * VAT arithmetic for billing documents (Spec 0 — replaces core
+ * `taxCalculationService`; billing no longer depends on core `sales`).
+ *
+ * Pure. Money is rounded half-up to 2 dp (fiscal documents) and the
+ * identity `net + tax = gross` always holds exactly:
+ *   - from net:   tax = round2(net × rate), gross = net + tax
+ *   - from gross: net = round2(gross / (1 + rate)), tax = gross − net
+ * Per-line rounding; document totals are sums of rounded lines (both
+ * methods are permitted in PL/EU and this keeps documents internally
+ * consistent).
+ */
+
+export type VatAmounts = { net: number; tax: number; gross: number }
+
+export function round2(value: number): number {
+  const sign = value < 0 ? -1 : 1
+  return (sign * Math.round((Math.abs(value) + Number.EPSILON) * 100)) / 100
+}
+
+function fraction(ratePercent: number): number {
+  return Number.isFinite(ratePercent) && ratePercent > 0 ? ratePercent / 100 : 0
+}
+
+/** Amounts for a net line value (sign preserved for credits). */
+export function lineAmountsFromNet(net: number, ratePercent: number): VatAmounts {
+  const netRounded = round2(net)
+  const tax = round2(netRounded * fraction(ratePercent))
+  return { net: netRounded, tax, gross: round2(netRounded + tax) }
+}
+
+/** Split a gross amount (e.g. a top-up payment) into net + tax. */
+export function lineAmountsFromGross(gross: number, ratePercent: number): VatAmounts {
+  const grossRounded = round2(gross)
+  const net = round2(grossRounded / (1 + fraction(ratePercent)))
+  return { net, tax: round2(grossRounded - net), gross: grossRounded }
+}
+
+/** Column format used by billing numeric(18,4) money columns. */
+export function money4(value: number): string {
+  return (Number.isFinite(value) ? round2(value) : 0).toFixed(4)
+}
+
+export type DocumentTotals = { subtotalNet: string; taxTotal: string; totalGross: string }
+
+export function sumTotals(lines: ReadonlyArray<VatAmounts>): DocumentTotals {
+  let net = 0
+  let tax = 0
+  let gross = 0
+  for (const line of lines) {
+    net += line.net
+    tax += line.tax
+    gross += line.gross
+  }
+  return { subtotalNet: money4(net), taxTotal: money4(tax), totalGross: money4(gross) }
+}

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

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * B2C billing accounts (Spec E, Phase 1).
+ *
+ * Adds `billing_accounts.customer_kind` ('company' | 'person'). Additive
+ * only: existing accounts default to 'company', which is what they were
+ * (the account form could only pick companies until now).
+ *
+ * Hand-written, like the package's earlier migrations: `yarn mercato db
+ * generate` only diffs `@app` modules, so it never reaches this package
+ * module. The column mirrors `data/entities.ts` 1:1 so a future generator
+ * run diffs clean.
+ */
+export class Migration20261114000000_billing_customer_kind extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `alter table "billing_accounts" add column if not exists "customer_kind" text not null default 'company';`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`alter table "billing_accounts" drop column if exists "customer_kind";`)
+  }
+}

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

@@ -0,0 +1,37 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Billing cycle semantics (Spec A).
+ *
+ * - `billing_items.charge_timing` ('in_advance' | 'in_arrears', default
+ *   'in_advance') and `billing_items.prorate` (default true) — recurring
+ *   items are billed in advance and partial periods are prorated.
+ * - `billing_run_outcomes.cycles` — per-bill-date breakdown of a run.
+ * - Drops `billing_runs.catch_up`: every run now catches up on all due
+ *   cycles, so the flag has no meaning. Per the billing improvements
+ *   decision D14 all instances are reseeded; no data is migrated.
+ *
+ * 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 Migration20261114100000_billing_cycle_semantics extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `alter table "billing_items" add column if not exists "charge_timing" text not null default 'in_advance';`,
+    )
+    this.addSql(
+      `alter table "billing_items" add column if not exists "prorate" boolean not null default true;`,
+    )
+    this.addSql(`alter table "billing_run_outcomes" add column if not exists "cycles" jsonb null;`)
+    this.addSql(`alter table "billing_runs" drop column if exists "catch_up";`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(
+      `alter table "billing_runs" add column if not exists "catch_up" boolean not null default false;`,
+    )
+    this.addSql(`alter table "billing_run_outcomes" drop column if exists "cycles";`)
+    this.addSql(`alter table "billing_items" drop column if exists "prorate";`)
+    this.addSql(`alter table "billing_items" drop column if exists "charge_timing";`)
+  }
+}

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

@@ -0,0 +1,132 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Standalone invoice ledger (Spec 0).
+ *
+ * Billing stops writing core `sales_invoices`: invoices, memos and top-up
+ * receipts move to `billing_invoices` / `billing_invoice_lines`, numbered by
+ * `billing_document_sequences`; prepaid settings move from core `configs`
+ * into per-organization `billing_settings`.
+ *
+ * No data migration (billing improvements decision D14 — instances are
+ * reseeded). Billing rows already in `sales_invoices` are left untouched.
+ *
+ * Hand-written: the partial unique indexes can't be expressed in entity
+ * decorators, and `yarn mercato db generate` only diffs `@app` modules.
+ */
+export class Migration20261115000000_billing_invoice_ledger extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`create table if not exists "billing_invoices" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "bill_account_id" uuid not null,
+      "document_type" text not null default 'invoice',
+      "number" text not null,
+      "series" text null,
+      "status" text not null default 'draft',
+      "test_run" boolean not null default false,
+      "bill_run_id" uuid null,
+      "bill_date" date null,
+      "period_start" date null,
+      "period_end" date null,
+      "issue_date" date null,
+      "due_date" date null,
+      "currency_code" text not null,
+      "subtotal_net" numeric(18, 4) not null default 0,
+      "tax_total" numeric(18, 4) not null default 0,
+      "total_gross" numeric(18, 4) not null default 0,
+      "paid_total" numeric(18, 4) not null default 0,
+      "credited_total" numeric(18, 4) not null default 0,
+      "outstanding" numeric(18, 4) not null default 0,
+      "corrects_invoice_id" uuid null,
+      "correction_reason" text null,
+      "buyer_snapshot" jsonb null,
+      "seller_snapshot" jsonb null,
+      "pdf_attachment_id" uuid null,
+      "topup_id" uuid null,
+      "posted_at" timestamptz null,
+      "metadata" jsonb null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_invoices_pkey" primary key ("id")
+    );`)
+    this.addSql(`create index if not exists "billing_invoices_status_idx" on "billing_invoices" ("tenant_id", "organization_id", "status");`)
+    this.addSql(`create index if not exists "billing_invoices_account_idx" on "billing_invoices" ("bill_account_id", "status", "due_date");`)
+    this.addSql(`create index if not exists "billing_invoices_run_idx" on "billing_invoices" ("bill_run_id");`)
+    this.addSql(`create index if not exists "billing_invoices_corrects_idx" on "billing_invoices" ("corrects_invoice_id");`)
+    this.addSql(`create index if not exists "billing_invoices_topup_idx" on "billing_invoices" ("topup_id");`)
+    // Spec A dedupe backstop: one invoice per (account, bill date, test flag).
+    this.addSql(`create unique index if not exists "billing_invoices_bill_date_uq" on "billing_invoices"
+      ("tenant_id", "organization_id", "bill_account_id", "bill_date", "test_run")
+      where "document_type" = 'invoice' and "deleted_at" is null and "bill_date" is not null;`)
+    // A posted number is unique within the organization.
+    this.addSql(`create unique index if not exists "billing_invoices_number_uq" on "billing_invoices"
+      ("tenant_id", "organization_id", "number") where "series" is not null;`)
+
+    this.addSql(`create table if not exists "billing_invoice_lines" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "invoice_id" uuid not null,
+      "line_number" int not null,
+      "billing_item_id" uuid null,
+      "billing_type" text not null,
+      "description" text not null,
+      "quantity" numeric(18, 4) not null,
+      "unit_price_net" numeric(18, 4) not null,
+      "tax_rate" numeric(7, 4) not null default 0,
+      "net_amount" numeric(18, 4) not null,
+      "tax_amount" numeric(18, 4) not null default 0,
+      "gross_amount" numeric(18, 4) not null,
+      "service_period_start" date null,
+      "service_period_end" date null,
+      "corrects_line_id" uuid null,
+      "metadata" jsonb null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_invoice_lines_pkey" primary key ("id")
+    );`)
+    this.addSql(`create index if not exists "billing_invoice_lines_invoice_idx" on "billing_invoice_lines" ("invoice_id", "line_number");`)
+
+    this.addSql(`create table if not exists "billing_document_sequences" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "series" text not null,
+      "scope_key" text not null default '',
+      "next_value" bigint not null default 1,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      constraint "billing_document_sequences_pkey" primary key ("id"),
+      constraint "billing_document_sequences_scope_uq" unique ("tenant_id", "organization_id", "series", "scope_key")
+    );`)
+
+    this.addSql(`create table if not exists "billing_settings" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "low_balance_threshold_default" numeric(18, 4) not null default 0,
+      "near_limit_buffer_default" numeric(18, 4) not null default 0,
+      "statement_enabled" boolean not null default true,
+      "topup_tax_rate" numeric(7, 4) not null default 0,
+      "topup_provider" text not null default 'stripe',
+      "number_masks" jsonb null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "billing_settings_pkey" primary key ("id")
+    );`)
+    this.addSql(`create unique index if not exists "billing_settings_org_uq" on "billing_settings"
+      ("tenant_id", "organization_id") where "deleted_at" is null;`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop table if exists "billing_settings" cascade;`)
+    this.addSql(`drop table if exists "billing_document_sequences" cascade;`)
+    this.addSql(`drop table if exists "billing_invoice_lines" cascade;`)
+    this.addSql(`drop table if exists "billing_invoices" cascade;`)
+  }
+}