@dainamite/billing 0.17.0

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

@@ -0,0 +1,260 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AwilixContainer } from 'awilix'
+import {
+  SalesInvoice,
+  SalesInvoiceLine,
+} from '@open-mercato/core/modules/sales/data/entities'
+import type { SalesDocumentNumberGenerator } from '@open-mercato/core/modules/sales/services/salesDocumentNumberGenerator'
+import type { BillingAccount, BillingItem } from '../data/entities'
+import type { BillPeriod } from './billPeriod'
+import {
+  __resetInvoiceStatusCacheForTests,
+  resolveInvoiceStatusEntryId,
+} from './invoiceStatus'
+
+/**
+ * Writes a `core/sales` draft invoice for a billing account's bill period.
+ *
+ * Two notable deviations from the spec, documented in CHANGELOG / spec:
+ *
+ *   1. `SalesInvoice.invoice_number` is `NOT NULL` in the upstream
+ *      schema, but the spec says "sequence number assigned at Post."
+ *      Real-mode invoices get a real number via
+ *      `salesDocumentNumberGenerator.generate({ kind: 'invoice' })` at
+ *      *draft create time* — the spec's intent (gap-free numbering via
+ *      atomic SQL upsert) is preserved; the timing differs because the
+ *      upstream column is `NOT NULL`. "Post" then just transitions
+ *      status `draft → posted`.
+ *
+ *   2. Test-mode invoices use a `TEST-<uuid>` placeholder number (not
+ *      the real sequence) so test runs do not burn production numbers
+ *      and can be repeated idempotently.
+ *
+ * VAT is NOT computed here — `core/sales`'s tax service owns the
+ * per-line `tax_rate` / `tax_amount` calculation, and runs on POST.
+ * Drafts therefore carry zeroes in the tax columns; the totals reflect
+ * net amounts only.
+ */
+
+export type WriteMode = 'real' | 'test' | 'dry'
+
+export type InvoiceLineDescriptor = {
+  /** Maps to billing_item_id on the resulting SalesInvoiceLine.metadata. */
+  billingItemId: string
+  /** From the spec's `metadata.billing_type` for traceability. */
+  billingType: 'one_time' | 'recurring' | 'usage'
+  description: string
+  /** Net unit price (numeric string for SalesInvoiceLine.unit_price_net). */
+  unitPriceNet: string
+  /** Quantity (string for the numeric(18,4) column). */
+  quantity: string
+  /** Total net (string). */
+  totalNetAmount: string
+  /** Optional per-line metadata extension — e.g. usage tier breakdown. */
+  metadataExtra?: Record<string, unknown>
+}
+
+export type WriteInvoiceParams = {
+  mode: WriteMode
+  account: BillingAccount
+  period: BillPeriod
+  billRunId: string
+  lines: InvoiceLineDescriptor[]
+}
+
+export type WrittenInvoice = {
+  invoiceId: string | null
+  invoiceNumber: string | null
+  totalNet: string
+}
+
+const DRAFT_INVOICE_STATUS_VALUE = 'draft'
+
+/**
+ * Test hook — clears the shared resolver's status cache so the engine
+ * test suite stays deterministic across mocked-EM environments.
+ */
+export function __resetInvoiceWriterCacheForTests(): void {
+  __resetInvoiceStatusCacheForTests()
+}
+
+function generateTestInvoiceNumber(): string {
+  // Match the pattern operators search by: `TEST-` prefix + random
+  // suffix so the test wipe-out endpoint can filter via `LIKE 'TEST-%'`
+  // (defensive — primary filter is `metadata.test_run=true`).
+  const random = Math.floor(Math.random() * 1e9)
+    .toString(16)
+    .padStart(8, '0')
+  return `TEST-${Date.now().toString(16)}-${random}`
+}
+
+/**
+ * 2dp half-up rounding that survives binary floating-point edge cases
+ * (e.g. `1.005 * 100 === 100.49999...` would otherwise round DOWN to
+ * `1.00` under naive `Math.round`). The `+ EPSILON` nudge pushes
+ * representations like 100.4999...8 up to the true half-up boundary.
+ * Matches the spec's "2 decimal places, half-up" rounding policy.
+ */
+function roundHalfUp2dp(value: number): number {
+  return Math.round((value + Number.EPSILON) * 100) / 100
+}
+
+function format4dp(value: number): string {
+  return roundHalfUp2dp(value).toFixed(4)
+}
+
+function sumNetTotal(lines: InvoiceLineDescriptor[]): string {
+  let total = 0
+  for (const line of lines) {
+    total += Number.parseFloat(line.totalNetAmount)
+  }
+  return format4dp(total)
+}
+
+export async function writeDraftInvoice(
+  em: EntityManager,
+  container: AwilixContainer,
+  params: WriteInvoiceParams,
+): Promise<WrittenInvoice> {
+  const totalNet = sumNetTotal(params.lines)
+
+  if (params.mode === 'dry') {
+    // Compute totals; persist nothing.
+    return { invoiceId: null, invoiceNumber: null, totalNet }
+  }
+
+  const { account, period, billRunId, lines, mode } = params
+
+  let invoiceNumber: string
+  if (mode === 'test') {
+    invoiceNumber = generateTestInvoiceNumber()
+  } else {
+    const numberGenerator = container.resolve(
+      'salesDocumentNumberGenerator',
+    ) as SalesDocumentNumberGenerator
+    const generated = await numberGenerator.generate({
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      kind: 'invoice',
+    })
+    invoiceNumber = generated.number
+  }
+
+  const statusEntryId = await resolveInvoiceStatusEntryId(
+    em,
+    account.tenantId,
+    account.organizationId,
+    'draft',
+  )
+
+  const now = new Date()
+  const invoice = em.create(SalesInvoice, {
+    organizationId: account.organizationId,
+    tenantId: account.tenantId,
+    invoiceNumber,
+    statusEntryId,
+    status: DRAFT_INVOICE_STATUS_VALUE,
+    issueDate: now,
+    currencyCode: account.currencyCode,
+    subtotalNetAmount: totalNet,
+    subtotalGrossAmount: totalNet, // gross == net for drafts (tax computed on post)
+    discountTotalAmount: '0',
+    taxTotalAmount: '0',
+    grandTotalNetAmount: totalNet,
+    grandTotalGrossAmount: totalNet,
+    paidTotalAmount: '0',
+    outstandingAmount: totalNet,
+    metadata: {
+      bill_run_id: billRunId,
+      bill_account_id: account.id,
+      bill_period_start: period.periodStart.toISOString().slice(0, 10),
+      bill_period_end: period.periodEnd.toISOString().slice(0, 10),
+      test_run: mode === 'test' ? true : undefined,
+    },
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(invoice)
+
+  let lineNumber = 1
+  for (const line of lines) {
+    const invoiceLine = em.create(SalesInvoiceLine, {
+      invoice,
+      organizationId: account.organizationId,
+      tenantId: account.tenantId,
+      lineNumber: lineNumber++,
+      kind: 'product',
+      description: line.description,
+      quantity: line.quantity,
+      normalizedQuantity: line.quantity,
+      currencyCode: account.currencyCode,
+      unitPriceNet: line.unitPriceNet,
+      unitPriceGross: line.unitPriceNet, // gross == net until tax computed on post
+      discountAmount: '0',
+      discountPercent: '0',
+      taxRate: '0',
+      taxAmount: '0',
+      totalNetAmount: line.totalNetAmount,
+      totalGrossAmount: line.totalNetAmount,
+      metadata: {
+        billing_item_id: line.billingItemId,
+        billing_type: line.billingType,
+        ...(line.metadataExtra ?? {}),
+      },
+    })
+    em.persist(invoiceLine)
+  }
+
+  await em.flush()
+
+  return { invoiceId: invoice.id, invoiceNumber, totalNet }
+}
+
+/**
+ * Build the InvoiceLineDescriptor list for a single account's eligible
+ * items (the result of `itemSelector.selectItemsForPeriod`). One line
+ * per item; `usage` items are excluded earlier by the selector.
+ *
+ * Per-type pricing per the spec's `BillingItem → InvoiceLine mapping`:
+ *   - `one_time`: unit_price = amount, quantity = 1
+ *   - `recurring`: unit_price = unit_price, quantity = 1
+ *     (one full cycle per bill period; catch-up emits separate drafts
+ *     per missed cycle, never combined)
+ */
+export function buildInvoiceLinesFromItems(
+  items: readonly BillingItem[],
+): InvoiceLineDescriptor[] {
+  const lines: InvoiceLineDescriptor[] = []
+  for (const item of items) {
+    if (item.type === 'one_time') {
+      const rate = item.rateJson as { amount?: number } | null
+      if (!rate || typeof rate.amount !== 'number') continue
+      // For one_time the per-unit price IS the total — quantity is 1.
+      // Both fields therefore carry the same value, with the 2dp
+      // half-up policy applied (unit price + line total are the same
+      // numeric column at numeric(18,4)).
+      const amount = format4dp(rate.amount)
+      lines.push({
+        billingItemId: item.id,
+        billingType: 'one_time',
+        description: item.description,
+        unitPriceNet: amount,
+        quantity: '1',
+        totalNetAmount: amount,
+      })
+    } else if (item.type === 'recurring') {
+      const rate = item.rateJson as { unit_price?: number } | null
+      if (!rate || typeof rate.unit_price !== 'number') continue
+      const unitPrice = format4dp(rate.unit_price)
+      lines.push({
+        billingItemId: item.id,
+        billingType: 'recurring',
+        description: item.description,
+        unitPriceNet: unitPrice,
+        quantity: '1',
+        totalNetAmount: unitPrice,
+      })
+    }
+  }
+  return lines
+}

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

@@ -0,0 +1,154 @@
+import type { BillingItem } from '../data/entities'
+import type { BillPeriod } from './billPeriod'
+
+/**
+ * Decide whether a Billing Item contributes to a given bill period.
+ *
+ * Two anti-duplicate guards working together (spec "Why two anti-duplicate
+ * guards"):
+ *
+ *   1. `billed_to_date` — per-item watermark. Set after a successful
+ *      real-mode run that emitted this item; prevents re-billing the
+ *      same item even if the period boundaries shift.
+ *   2. Open-draft check — per-account, handled by the engine before it
+ *      even invokes this selector (see `billRunEngine`). Not this
+ *      module's concern.
+ *
+ * Per-type semantics from the spec:
+ *
+ *   `one_time` — one shot per item, ever. Eligible only if
+ *      `billed_to_date IS NULL` AND the item's `[bill_start_date,
+ *      bill_end_date]` window overlaps the bill period.
+ *
+ *   `recurring` — one line per full cycle. Eligible only when:
+ *      - `bill_start_date <= bill_period_start`
+ *      - AND (`bill_end_date IS NULL` OR `bill_end_date >= bill_period_end`)
+ *      - AND (`billed_to_date IS NULL` OR `billed_to_date < bill_period_end`)
+ *
+ *      Mid-cycle starts / cancels are SKIPPED — the integrator is
+ *      responsible for posting a `one_time` proration line if the
+ *      partial period should be charged (spec "Mid-cycle recurring
+ *      items").
+ *
+ *   `usage` — not handled here. Phase 3 owns usage rating end-to-end.
+ *
+ * All comparisons treat dates as midnight (consistent with `billPeriod`).
+ */
+
+export type SelectableItem = Pick<
+  BillingItem,
+  | 'id'
+  | 'type'
+  | 'billStartDate'
+  | 'billEndDate'
+  | 'billedToDate'
+  | 'description'
+  | 'rateJson'
+  | 'isActive'
+  | 'deletedAt'
+>
+
+export type SelectionDecision =
+  | { include: true }
+  | { include: false; reason: string }
+
+function asTime(date: Date | null | undefined): number | null {
+  if (!date) return null
+  return new Date(date).getTime()
+}
+
+function isWithin(
+  windowStart: Date,
+  windowEnd: Date | null | undefined,
+  point: Date,
+): boolean {
+  const pointTime = asTime(point)!
+  const startTime = asTime(windowStart)!
+  if (pointTime < startTime) return false
+  const endTime = asTime(windowEnd)
+  if (endTime === null) return true
+  return pointTime <= endTime
+}
+
+function overlapsPeriod(
+  itemStart: Date,
+  itemEnd: Date | null | undefined,
+  period: BillPeriod,
+): boolean {
+  const itemStartTime = asTime(itemStart)!
+  const itemEndTime = asTime(itemEnd)
+  const periodStartTime = asTime(period.periodStart)!
+  const periodEndTime = asTime(period.periodEnd)!
+  if (itemStartTime > periodEndTime) return false
+  if (itemEndTime !== null && itemEndTime < periodStartTime) return false
+  return true
+}
+
+export function shouldIncludeItem(
+  item: SelectableItem,
+  period: BillPeriod,
+): SelectionDecision {
+  if (!item.isActive) return { include: false, reason: 'item-inactive' }
+  if (item.deletedAt) return { include: false, reason: 'item-soft-deleted' }
+
+  switch (item.type) {
+    case 'one_time': {
+      if (item.billedToDate) {
+        return { include: false, reason: 'one_time-already-billed' }
+      }
+      if (!overlapsPeriod(item.billStartDate, item.billEndDate, period)) {
+        return { include: false, reason: 'one_time-window-outside-period' }
+      }
+      return { include: true }
+    }
+    case 'recurring': {
+      const billedToTime = asTime(item.billedToDate)
+      const periodEndTime = asTime(period.periodEnd)!
+      if (billedToTime !== null && billedToTime >= periodEndTime) {
+        return { include: false, reason: 'recurring-already-billed-through-period' }
+      }
+      const periodStartTime = asTime(period.periodStart)!
+      const itemStartTime = asTime(item.billStartDate)!
+      if (itemStartTime > periodStartTime) {
+        return { include: false, reason: 'recurring-starts-mid-cycle' }
+      }
+      const itemEndTime = asTime(item.billEndDate)
+      if (itemEndTime !== null && itemEndTime < periodEndTime) {
+        return { include: false, reason: 'recurring-ends-mid-cycle' }
+      }
+      return { include: true }
+    }
+    case 'usage':
+      // Phase 3 routes usage items through the dedicated usage rater.
+      // The selector returns "skip" so the engine's recurring/one_time
+      // path is unaffected.
+      return { include: false, reason: 'usage-handled-by-rater' }
+    default:
+      return { include: false, reason: `unknown-type:${item.type}` }
+  }
+}
+
+/**
+ * Pure filter — given the items already loaded for an account, returns
+ * those eligible for the bill period together with the decision reason
+ * for diagnostics (the engine logs skipped items in the run outcome's
+ * warnings on demand).
+ */
+export function selectItemsForPeriod<T extends SelectableItem>(
+  items: readonly T[],
+  period: BillPeriod,
+): { included: T[]; skipped: Array<{ item: T; reason: string }> } {
+  const included: T[] = []
+  const skipped: Array<{ item: T; reason: string }> = []
+  for (const item of items) {
+    const decision = shouldIncludeItem(item, period)
+    if (decision.include) {
+      included.push(item)
+    } else {
+      skipped.push({ item, reason: decision.reason })
+    }
+  }
+  return { included, skipped }
+}
+
+export { isWithin, overlapsPeriod }

package/src/modules/billing/lib/seeds/demo.ts

@@ -0,0 +1,199 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { BillingAccount, BillingItem, BillingAccountUsage } from '../../data/entities'
+
+/**
+ * Self-contained billing test-data seed.
+ *
+ * Creates a couple of demo billing accounts with recurring + usage items
+ * and one unrated usage record, scoped to a single tenant. Everything is
+ * idempotent: accounts are matched by name, items/usage by `source_ref`,
+ * so re-running is a no-op rather than a duplicate.
+ *
+ * The accounts are dated so they are immediately billable: `next_bill_date`
+ * is the 1st of the current month, which makes a Bill Run with the default
+ * (today's) as-of date produce an invoice for the previous month — the usage
+ * record is seeded into exactly that period.
+ *
+ * Drives `mercato billing seed`. Kept free of any customer-specific data so
+ * it ships with `@dainamite/billing`.
+ */
+
+export type BillingDemoScope = { tenantId: string; organizationId: string }
+export type BillingDemoResult = {
+  accountsCreated: number
+  itemsCreated: number
+  usageCreated: number
+}
+
+// Shared prefix for every row this seed owns — the reset path keys off it.
+const SRC = 'demo-billing'
+const ACCOUNT_NAME_PREFIX = 'Demo — '
+
+type DemoAccountSpec = {
+  name: string
+  customerId: string
+  currencyCode: string
+  invoiceLanguage: string
+}
+
+type DemoItemSpec = {
+  ref: string
+  type: 'recurring' | 'usage'
+  description: string
+  unitPrice: number
+  uomCode?: string
+}
+
+type DemoUsageSpec = {
+  ref: string
+  uomCode: string
+  quantity: number
+  lineDescription: string
+}
+
+const ACCOUNTS: Array<{
+  account: DemoAccountSpec
+  items: DemoItemSpec[]
+  usage: DemoUsageSpec[]
+}> = [
+  {
+    account: {
+      name: `${ACCOUNT_NAME_PREFIX}Northwind Telecom`,
+      customerId: 'demo-cust-northwind',
+      currencyCode: 'PLN',
+      invoiceLanguage: 'en',
+    },
+    items: [
+      { ref: `${SRC}-nw-rec`, type: 'recurring', description: 'Platform subscription (monthly)', unitPrice: 199 },
+      { ref: `${SRC}-nw-usg`, type: 'usage', description: 'Data transfer (per GB)', unitPrice: 0.5, uomCode: 'gb' },
+    ],
+    usage: [
+      { ref: `${SRC}-nw-usage`, uomCode: 'gb', quantity: 120, lineDescription: 'Data transfer (prev. month)' },
+    ],
+  },
+  {
+    account: {
+      name: `${ACCOUNT_NAME_PREFIX}Globex Cloud`,
+      customerId: 'demo-cust-globex',
+      currencyCode: 'EUR',
+      invoiceLanguage: 'en',
+    },
+    items: [
+      { ref: `${SRC}-gx-rec`, type: 'recurring', description: 'Cloud plan (monthly)', unitPrice: 49 },
+    ],
+    usage: [],
+  },
+]
+
+/** Delete every row this seed owns within the scope (reset before re-seed). */
+export async function resetBillingDemo(em: EntityManager, scope: BillingDemoScope): Promise<void> {
+  await em.nativeDelete(BillingAccountUsage, {
+    ...scope,
+    sourceRef: { $like: `${SRC}-%` },
+  } as never)
+  await em.nativeDelete(BillingItem, {
+    ...scope,
+    sourceRef: { $like: `${SRC}-%` },
+  } as never)
+  await em.nativeDelete(BillingAccount, {
+    ...scope,
+    name: { $like: `${ACCOUNT_NAME_PREFIX}%` },
+  } as never)
+}
+
+export async function seedBillingDemo(
+  em: EntityManager,
+  scope: BillingDemoScope,
+  options: { reset?: boolean; now?: Date } = {},
+): Promise<BillingDemoResult> {
+  if (options.reset) await resetBillingDemo(em, scope)
+
+  const now = options.now ?? new Date()
+  // Bill period the next run will cover, given next_bill = 1st of this month:
+  //   periodStart = 1st of previous month, periodEnd = last day of previous month.
+  // Build at UTC midnight so `date` columns don't drift a day under a positive
+  // local UTC offset (local `new Date(y, m, 1)` would persist as the prev day).
+  const nextBillDate = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1))
+  const prevMonthStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1))
+  const prevMonthEnd = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 0))
+
+  const result: BillingDemoResult = { accountsCreated: 0, itemsCreated: 0, usageCreated: 0 }
+
+  for (const spec of ACCOUNTS) {
+    // ── Account (idempotent by name within scope) ──
+    let account = await em.findOne(BillingAccount, {
+      ...scope,
+      name: spec.account.name,
+      deletedAt: null,
+    } as never)
+    if (!account) {
+      account = em.create(BillingAccount, {
+        ...scope,
+        customerId: spec.account.customerId,
+        name: spec.account.name,
+        currencyCode: spec.account.currencyCode,
+        billCycle: 'monthly',
+        billCycleAnchor: '1',
+        invoiceEmail: `billing@${spec.account.customerId}.demo`,
+        invoiceLanguage: spec.account.invoiceLanguage,
+        taxId: null,
+        invoiceAddress: { line1: 'ul. Demo 1', city: 'Warszawa', postal_code: '00-001', country: 'PL' },
+        nextBillDate,
+        lastBillDate: null,
+        isActive: true,
+      })
+      em.persist(account)
+      await em.flush() // need the id for child rows
+      result.accountsCreated += 1
+    }
+
+    // ── Items (idempotent by source_ref) ──
+    for (const item of spec.items) {
+      const existing = await em.findOne(BillingItem, { ...scope, sourceRef: item.ref } as never)
+      if (existing) continue
+      em.persist(
+        em.create(BillingItem, {
+          ...scope,
+          billAccountId: account.id,
+          type: item.type,
+          billStartDate: prevMonthStart,
+          billEndDate: null,
+          description: item.description,
+          rateJson: { unit_price: item.unitPrice },
+          uomCode: item.uomCode ?? null,
+          subscriptionId: null,
+          subscriptionItemId: null,
+          sourceRef: item.ref,
+          currencyMismatch: false,
+          billedToDate: null,
+          isActive: true,
+        }),
+      )
+      result.itemsCreated += 1
+    }
+
+    // ── Usage records (idempotent by source_ref) ──
+    for (const u of spec.usage) {
+      const existing = await em.findOne(BillingAccountUsage, { ...scope, sourceRef: u.ref } as never)
+      if (existing) continue
+      em.persist(
+        em.create(BillingAccountUsage, {
+          ...scope,
+          billAccountId: account.id,
+          uomCode: u.uomCode,
+          quantity: u.quantity.toFixed(4),
+          periodStart: prevMonthStart,
+          periodEnd: prevMonthEnd,
+          lineDescription: u.lineDescription,
+          sourceRef: u.ref,
+          ratedInBillRunId: null,
+          isActive: true,
+        }),
+      )
+      result.usageCreated += 1
+    }
+  }
+
+  await em.flush()
+  return result
+}

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

@@ -0,0 +1,87 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Per-tenant Postgres transaction-scoped advisory lock primitive.
+ *
+ * The Bill Run engine (Phase 2) uses this to guarantee at most one
+ * concurrently-running run per tenant — the spec requires this so two
+ * cron triggers or a "schedule" + "manual" overlap cannot produce
+ * duplicate drafts.
+ *
+ * Why advisory locks (not row locks):
+ *   - `pg_try_advisory_xact_lock` is non-blocking — we get a clean "busy"
+ *     signal instead of waiting on a row.
+ *   - It's released automatically when the transaction ends (commit,
+ *     rollback, or process death) — so there is no lock-leak path even
+ *     on `kill -9`. The `BillRun` row's `status='running'` may be left
+ *     hanging, but the lock itself vanishes; the reaper worker
+ *     (workers/reap-stale-bill-runs.ts) handles the orphaned row.
+ *   - It works without a sentinel table — we hash a string key into the
+ *     bigint key space the advisory-lock API requires.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { withTenantLock, TenantLockBusyError } from '../lib/tenantLock'
+ *
+ * try {
+ *   await withTenantLock(em, { tenantId, lockName: 'billing-run' }, async (tem) => {
+ *     // tem is the transactional EntityManager; lock is held here.
+ *     // Returns to caller after function resolves and tx commits.
+ *   })
+ * } catch (err) {
+ *   if (err instanceof TenantLockBusyError) {
+ *     // HTTP 409 — another run is in progress.
+ *   }
+ *   throw err
+ * }
+ * ```
+ *
+ * Keep work inside the callback short. The advisory lock is released only
+ * when the transaction ends; long-running work blocks other triggers for
+ * the whole tenant.
+ */
+
+export class TenantLockBusyError extends Error {
+  readonly tenantId: string
+  readonly lockName: string
+
+  constructor(tenantId: string, lockName: string) {
+    super(`Tenant ${tenantId} already holds the billing lock "${lockName}"`)
+    this.name = 'TenantLockBusyError'
+    this.tenantId = tenantId
+    this.lockName = lockName
+  }
+}
+
+const LOCK_KEY_PREFIX = 'dainamite-billing'
+
+/**
+ * Build the deterministic string key fed into `hashtext()`. Exposed for
+ * tests so they can assert lock-key independence across tenants /
+ * lockNames without scraping SQL strings.
+ */
+export function buildLockKey(tenantId: string, lockName: string): string {
+  return `${LOCK_KEY_PREFIX}:${tenantId}:${lockName}`
+}
+
+type AdvisoryLockRow = { acquired: boolean }
+
+export async function withTenantLock<T>(
+  em: EntityManager,
+  params: { tenantId: string; lockName: string },
+  fn: (tem: EntityManager) => Promise<T>,
+): Promise<T> {
+  return em.transactional(async (tem) => {
+    const key = buildLockKey(params.tenantId, params.lockName)
+    const rows = (await tem.execute(
+      'SELECT pg_try_advisory_xact_lock(hashtext(?)::bigint) AS acquired',
+      [key],
+    )) as unknown as AdvisoryLockRow[] | AdvisoryLockRow | undefined
+    const first: AdvisoryLockRow | undefined = Array.isArray(rows) ? rows[0] : rows
+    if (!first?.acquired) {
+      throw new TenantLockBusyError(params.tenantId, params.lockName)
+    }
+    return fn(tem)
+  })
+}