@dainamite/billing 0.17.0

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

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

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

@@ -0,0 +1,119 @@
+import { buildInvoiceLinesFromItems } from '../../lib/invoiceWriter'
+import type { BillingItem } from '../../data/entities'
+
+function makeItem(overrides: Partial<BillingItem>): BillingItem {
+  return {
+    id: overrides.id ?? 'item-1',
+    organizationId: overrides.organizationId ?? 'org-1',
+    tenantId: overrides.tenantId ?? 'tenant-1',
+    billAccountId: overrides.billAccountId ?? 'account-1',
+    type: overrides.type ?? 'recurring',
+    billStartDate: overrides.billStartDate ?? new Date('2026-01-01'),
+    billEndDate: overrides.billEndDate ?? null,
+    description: overrides.description ?? 'desc',
+    rateJson: overrides.rateJson ?? { unit_price: 49.99 },
+    uomCode: overrides.uomCode ?? null,
+    subscriptionId: overrides.subscriptionId ?? null,
+    subscriptionItemId: overrides.subscriptionItemId ?? null,
+    sourceRef: overrides.sourceRef ?? null,
+    currencyMismatch: overrides.currencyMismatch ?? false,
+    billedToDate: overrides.billedToDate ?? null,
+    isActive: overrides.isActive ?? true,
+    createdAt: overrides.createdAt ?? new Date(),
+    updatedAt: overrides.updatedAt ?? new Date(),
+    deletedAt: overrides.deletedAt ?? null,
+  } as BillingItem
+}
+
+describe('buildInvoiceLinesFromItems — recurring', () => {
+  it('builds one line per recurring item with unit_price = rateJson.unit_price', () => {
+    const items = [
+      makeItem({ id: 'a', type: 'recurring', description: 'MRC A', rateJson: { unit_price: 49.99 } }),
+      makeItem({ id: 'b', type: 'recurring', description: 'MRC B', rateJson: { unit_price: 29 } }),
+    ]
+    const lines = buildInvoiceLinesFromItems(items)
+    expect(lines).toHaveLength(2)
+    expect(lines[0]).toEqual({
+      billingItemId: 'a',
+      billingType: 'recurring',
+      description: 'MRC A',
+      unitPriceNet: '49.9900',
+      quantity: '1',
+      totalNetAmount: '49.9900',
+    })
+    expect(lines[1].unitPriceNet).toBe('29.0000')
+  })
+
+  it('rounds unit_price half-up to 2dp before persisting', () => {
+    const items = [
+      makeItem({ type: 'recurring', rateJson: { unit_price: 1.005 } }), // half-up → 1.01
+      makeItem({ type: 'recurring', rateJson: { unit_price: 1.004 } }), // half-down → 1.00
+    ]
+    const lines = buildInvoiceLinesFromItems(items)
+    expect(lines[0].unitPriceNet).toBe('1.0100')
+    expect(lines[1].unitPriceNet).toBe('1.0000')
+  })
+
+  it('skips a recurring item with malformed rateJson (defensive)', () => {
+    const wrong = makeItem({ type: 'recurring', rateJson: { amount: 49 } as never })
+    // Override directly because `makeItem`'s `??` would replace a null
+    // with the default — we need the actual null on the persisted item
+    // to exercise the builder's guard.
+    const nullRate = makeItem({ type: 'recurring' })
+    ;(nullRate as { rateJson: unknown }).rateJson = null
+    expect(buildInvoiceLinesFromItems([wrong, nullRate])).toEqual([])
+  })
+})
+
+describe('buildInvoiceLinesFromItems — one_time', () => {
+  it('builds one line with amount = rateJson.amount, quantity 1', () => {
+    const items = [
+      makeItem({
+        id: 'fee',
+        type: 'one_time',
+        description: 'Activation fee',
+        rateJson: { amount: 99 },
+      }),
+    ]
+    const lines = buildInvoiceLinesFromItems(items)
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toEqual({
+      billingItemId: 'fee',
+      billingType: 'one_time',
+      description: 'Activation fee',
+      unitPriceNet: '99.0000',
+      quantity: '1',
+      totalNetAmount: '99.0000',
+    })
+  })
+
+  it('preserves negative amounts (credit / refund / negative proration)', () => {
+    const items = [
+      makeItem({
+        type: 'one_time',
+        description: 'Cancellation credit',
+        rateJson: { amount: -25.5 },
+      }),
+    ]
+    const lines = buildInvoiceLinesFromItems(items)
+    expect(lines[0].unitPriceNet).toBe('-25.5000')
+  })
+})
+
+describe('buildInvoiceLinesFromItems — mixed + usage exclusion', () => {
+  it('mixes one_time and recurring while excluding usage', () => {
+    const items = [
+      makeItem({ id: 'mrc', type: 'recurring', description: 'MRC', rateJson: { unit_price: 49 } }),
+      makeItem({ id: 'fee', type: 'one_time', description: 'Setup', rateJson: { amount: 99 } }),
+      makeItem({
+        id: 'metered',
+        type: 'usage',
+        description: 'API',
+        rateJson: { unit_price: 0.001 },
+      }),
+    ]
+    const lines = buildInvoiceLinesFromItems(items)
+    expect(lines.map((l) => l.billingType)).toEqual(['recurring', 'one_time'])
+    expect(lines.find((l) => l.billingItemId === 'metered')).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,192 @@
+import {
+  selectItemsForPeriod,
+  shouldIncludeItem,
+  type SelectableItem,
+} from '../../lib/itemSelector'
+import { deriveBillPeriod } from '../../lib/billPeriod'
+
+function date(iso: string): Date {
+  return new Date(`${iso}T00:00:00.000Z`)
+}
+
+function baseItem(overrides: Partial<SelectableItem> = {}): SelectableItem {
+  return {
+    id: overrides.id ?? 'item-x',
+    type: overrides.type ?? 'recurring',
+    billStartDate: overrides.billStartDate ?? date('2026-01-01'),
+    billEndDate: overrides.billEndDate ?? null,
+    billedToDate: overrides.billedToDate ?? null,
+    description: overrides.description ?? 'desc',
+    rateJson: overrides.rateJson ?? { unit_price: 49.99 },
+    isActive: overrides.isActive ?? true,
+    deletedAt: overrides.deletedAt ?? null,
+  }
+}
+
+// May 2026 monthly period: 2026-05-01..2026-05-31
+const MAY_PERIOD = deriveBillPeriod(date('2026-06-01'), 'monthly')
+
+describe('shouldIncludeItem — type=recurring', () => {
+  it('includes a standard ongoing item (started before, no end)', () => {
+    const decision = shouldIncludeItem(baseItem({ type: 'recurring' }), MAY_PERIOD)
+    expect(decision.include).toBe(true)
+  })
+
+  it('skips an item that starts mid-cycle (2026-05-15)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'recurring', billStartDate: date('2026-05-15') }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({ include: false, reason: 'recurring-starts-mid-cycle' })
+  })
+
+  it('skips an item that ends mid-cycle (2026-05-15)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'recurring', billEndDate: date('2026-05-15') }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({ include: false, reason: 'recurring-ends-mid-cycle' })
+  })
+
+  it('skips an item already billed through this period (billed_to_date >= period_end)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'recurring', billedToDate: date('2026-05-31') }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({
+      include: false,
+      reason: 'recurring-already-billed-through-period',
+    })
+  })
+
+  it('includes when billed_to_date is from a prior cycle (< period_end)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'recurring', billedToDate: date('2026-04-30') }),
+      MAY_PERIOD,
+    )
+    expect(decision.include).toBe(true)
+  })
+
+  it('includes when item starts exactly on period_start', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'recurring', billStartDate: date('2026-05-01') }),
+      MAY_PERIOD,
+    )
+    expect(decision.include).toBe(true)
+  })
+
+  it('includes when item ends exactly on period_end (full cycle covered)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({
+        type: 'recurring',
+        billStartDate: date('2026-05-01'),
+        billEndDate: date('2026-05-31'),
+      }),
+      MAY_PERIOD,
+    )
+    expect(decision.include).toBe(true)
+  })
+})
+
+describe('shouldIncludeItem — type=one_time', () => {
+  it('includes when window overlaps period and billed_to_date is null', () => {
+    const decision = shouldIncludeItem(
+      baseItem({ type: 'one_time', rateJson: { amount: 99 } }),
+      MAY_PERIOD,
+    )
+    expect(decision.include).toBe(true)
+  })
+
+  it('skips when already billed (billed_to_date set)', () => {
+    const decision = shouldIncludeItem(
+      baseItem({
+        type: 'one_time',
+        rateJson: { amount: 99 },
+        billedToDate: date('2026-04-30'),
+      }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({ include: false, reason: 'one_time-already-billed' })
+  })
+
+  it('skips when window is entirely after period_end', () => {
+    const decision = shouldIncludeItem(
+      baseItem({
+        type: 'one_time',
+        billStartDate: date('2026-06-01'),
+        rateJson: { amount: 99 },
+      }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({ include: false, reason: 'one_time-window-outside-period' })
+  })
+
+  it('skips when window ends before period_start', () => {
+    const decision = shouldIncludeItem(
+      baseItem({
+        type: 'one_time',
+        billStartDate: date('2026-04-01'),
+        billEndDate: date('2026-04-15'),
+        rateJson: { amount: 99 },
+      }),
+      MAY_PERIOD,
+    )
+    expect(decision).toEqual({ include: false, reason: 'one_time-window-outside-period' })
+  })
+
+  it('includes a mid-cycle proration item (the canonical add-package case)', () => {
+    // Mirrors spec Story 2: New package on 2026-05-15 → one_time proration
+    // with bill_start_date=2026-05-15. Overlaps May period → included.
+    const decision = shouldIncludeItem(
+      baseItem({
+        type: 'one_time',
+        billStartDate: date('2026-05-15'),
+        rateJson: { amount: 15.9 },
+      }),
+      MAY_PERIOD,
+    )
+    expect(decision.include).toBe(true)
+  })
+})
+
+describe('shouldIncludeItem — guards', () => {
+  it('skips inactive items', () => {
+    expect(
+      shouldIncludeItem(baseItem({ isActive: false }), MAY_PERIOD),
+    ).toEqual({ include: false, reason: 'item-inactive' })
+  })
+
+  it('skips soft-deleted items', () => {
+    expect(
+      shouldIncludeItem(baseItem({ deletedAt: date('2026-04-01') }), MAY_PERIOD),
+    ).toEqual({ include: false, reason: 'item-soft-deleted' })
+  })
+
+  it('skips usage items (handled by Phase 3 rater)', () => {
+    expect(
+      shouldIncludeItem(
+        baseItem({ type: 'usage', rateJson: { unit_price: 0.001 } }),
+        MAY_PERIOD,
+      ),
+    ).toEqual({ include: false, reason: 'usage-handled-by-rater' })
+  })
+})
+
+describe('selectItemsForPeriod', () => {
+  it('partitions a mix into included + skipped with reasons', () => {
+    const items = [
+      baseItem({ id: 'a', type: 'recurring' }), // include
+      baseItem({ id: 'b', type: 'recurring', billStartDate: date('2026-05-15') }), // mid-cycle start
+      baseItem({ id: 'c', type: 'one_time', rateJson: { amount: 99 } }), // include
+      baseItem({ id: 'd', type: 'usage', rateJson: { unit_price: 0.001 } }), // usage → skipped
+      baseItem({ id: 'e', type: 'recurring', billedToDate: date('2026-05-31') }), // already billed
+    ]
+    const { included, skipped } = selectItemsForPeriod(items, MAY_PERIOD)
+    expect(included.map((i) => i.id)).toEqual(['a', 'c'])
+    expect(skipped.map((s) => ({ id: s.item.id, reason: s.reason }))).toEqual([
+      { id: 'b', reason: 'recurring-starts-mid-cycle' },
+      { id: 'd', reason: 'usage-handled-by-rater' },
+      { id: 'e', reason: 'recurring-already-billed-through-period' },
+    ])
+  })
+})

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

@@ -0,0 +1,86 @@
+import { seedBillingDemo, resetBillingDemo } from '../../lib/seeds/demo'
+
+/**
+ * In-memory mock EM that mirrors the find-or-create contract the seed relies
+ * on: `findOne` matches accounts by `name` and items/usage by `sourceRef`,
+ * `create` mints an id, `persist` stores, `nativeDelete` records calls.
+ */
+function makeMockEm() {
+  const store: Array<Record<string, unknown>> = []
+  let idSeq = 0
+  const nativeDeleteCalls: unknown[] = []
+
+  const em = {
+    store,
+    nativeDeleteCalls,
+    findOne: jest.fn(async (_entity: unknown, where: Record<string, unknown>) => {
+      return (
+        store.find((row) => {
+          if (typeof where.name === 'string') return row.name === where.name
+          if (typeof where.sourceRef === 'string') return row.sourceRef === where.sourceRef
+          return false
+        }) ?? null
+      )
+    }),
+    create: jest.fn((_entity: unknown, data: Record<string, unknown>) => {
+      return { id: `id-${++idSeq}`, ...data }
+    }),
+    persist: jest.fn((entity: Record<string, unknown>) => {
+      store.push(entity)
+      return entity
+    }),
+    flush: jest.fn(async () => undefined),
+    nativeDelete: jest.fn(async (_entity: unknown, where: unknown) => {
+      nativeDeleteCalls.push(where)
+      return 0
+    }),
+  }
+  return em as never as Parameters<typeof seedBillingDemo>[0] & {
+    store: Array<Record<string, unknown>>
+    nativeDeleteCalls: unknown[]
+  }
+}
+
+const SCOPE = { tenantId: 'tnt-1', organizationId: 'org-1' }
+const NOW = new Date('2026-06-08T12:00:00Z')
+
+describe('seedBillingDemo', () => {
+  it('creates the demo accounts, items and usage on a fresh tenant', async () => {
+    const em = makeMockEm()
+    const res = await seedBillingDemo(em, SCOPE, { now: NOW })
+
+    expect(res).toEqual({ accountsCreated: 2, itemsCreated: 3, usageCreated: 1 })
+  })
+
+  it('is idempotent — a second run creates nothing', async () => {
+    const em = makeMockEm()
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+    const second = await seedBillingDemo(em, SCOPE, { now: NOW })
+
+    expect(second).toEqual({ accountsCreated: 0, itemsCreated: 0, usageCreated: 0 })
+  })
+
+  it('dates the primary account so the previous month is billable', async () => {
+    const em = makeMockEm()
+    await seedBillingDemo(em, SCOPE, { now: NOW })
+
+    const account = em.store.find((r) => r.name === 'Demo — Northwind Telecom') as
+      | { nextBillDate: Date }
+      | undefined
+    const usage = em.store.find((r) => r.sourceRef === 'demo-billing-nw-usage') as
+      | { periodStart: Date; periodEnd: Date }
+      | undefined
+
+    // next_bill = 1st of the current (UTC) month → due for any later as-of date.
+    expect(account?.nextBillDate.toISOString().slice(0, 10)).toBe('2026-06-01')
+    // usage sits in the previous month, the period that run will cover.
+    expect(usage?.periodStart.toISOString().slice(0, 10)).toBe('2026-05-01')
+    expect(usage?.periodEnd.toISOString().slice(0, 10)).toBe('2026-05-31')
+  })
+
+  it('reset issues a delete for usage, items and accounts', async () => {
+    const em = makeMockEm()
+    await resetBillingDemo(em, SCOPE)
+    expect(em.nativeDelete).toHaveBeenCalledTimes(3)
+  })
+})

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

@@ -0,0 +1,126 @@
+import {
+  buildLockKey,
+  TenantLockBusyError,
+  withTenantLock,
+} from '../../lib/tenantLock'
+
+type MockEm = {
+  transactional: jest.MockedFunction<
+    (fn: (tem: MockEm) => Promise<unknown>) => Promise<unknown>
+  >
+  execute: jest.MockedFunction<(sql: string, params?: unknown[]) => Promise<unknown>>
+}
+
+function createMockEm(): MockEm {
+  const em: MockEm = {
+    transactional: jest.fn(async (fn) => fn(em)),
+    execute: jest.fn(),
+  }
+  return em
+}
+
+const TENANT_A = '00000000-0000-0000-0000-000000000001'
+const TENANT_B = '00000000-0000-0000-0000-000000000002'
+
+describe('buildLockKey', () => {
+  it('builds a stable, namespaced key', () => {
+    expect(buildLockKey(TENANT_A, 'billing-run')).toBe(
+      `dainamite-billing:${TENANT_A}:billing-run`,
+    )
+  })
+
+  it('returns distinct keys per tenant', () => {
+    expect(buildLockKey(TENANT_A, 'billing-run')).not.toEqual(
+      buildLockKey(TENANT_B, 'billing-run'),
+    )
+  })
+
+  it('returns distinct keys per lockName', () => {
+    expect(buildLockKey(TENANT_A, 'billing-run')).not.toEqual(
+      buildLockKey(TENANT_A, 'other-job'),
+    )
+  })
+})
+
+describe('withTenantLock', () => {
+  it('runs the callback when the advisory lock is acquired', async () => {
+    const em = createMockEm()
+    em.execute.mockResolvedValueOnce([{ acquired: true }])
+
+    const inner = jest.fn(async () => 'work-result')
+    const result = await withTenantLock(
+      em as never,
+      { tenantId: TENANT_A, lockName: 'billing-run' },
+      inner,
+    )
+
+    expect(result).toBe('work-result')
+    expect(em.transactional).toHaveBeenCalledTimes(1)
+    expect(em.execute).toHaveBeenCalledTimes(1)
+    expect(inner).toHaveBeenCalledTimes(1)
+  })
+
+  it('passes the expected lock key into pg_try_advisory_xact_lock', async () => {
+    const em = createMockEm()
+    em.execute.mockResolvedValueOnce([{ acquired: true }])
+
+    await withTenantLock(
+      em as never,
+      { tenantId: TENANT_A, lockName: 'billing-run' },
+      async () => 'ok',
+    )
+
+    const [sql, params] = em.execute.mock.calls[0]
+    expect(sql).toMatch(/pg_try_advisory_xact_lock/i)
+    expect(sql).toMatch(/hashtext/i)
+    expect(params).toEqual([buildLockKey(TENANT_A, 'billing-run')])
+  })
+
+  it('throws TenantLockBusyError when the lock is already held', async () => {
+    const em = createMockEm()
+    em.execute.mockResolvedValueOnce([{ acquired: false }])
+
+    const inner = jest.fn(async () => 'should-not-run')
+
+    await expect(
+      withTenantLock(
+        em as never,
+        { tenantId: TENANT_A, lockName: 'billing-run' },
+        inner,
+      ),
+    ).rejects.toBeInstanceOf(TenantLockBusyError)
+
+    expect(inner).not.toHaveBeenCalled()
+  })
+
+  it('TenantLockBusyError carries tenantId + lockName for HTTP 409 mapping', async () => {
+    const em = createMockEm()
+    em.execute.mockResolvedValueOnce([{ acquired: false }])
+
+    try {
+      await withTenantLock(
+        em as never,
+        { tenantId: TENANT_A, lockName: 'billing-run' },
+        async () => 'never',
+      )
+      throw new Error('expected throw')
+    } catch (err) {
+      expect(err).toBeInstanceOf(TenantLockBusyError)
+      const lockErr = err as TenantLockBusyError
+      expect(lockErr.tenantId).toBe(TENANT_A)
+      expect(lockErr.lockName).toBe('billing-run')
+    }
+  })
+
+  it('tolerates the driver returning a single row object instead of an array', async () => {
+    const em = createMockEm()
+    em.execute.mockResolvedValueOnce({ acquired: true } as never)
+
+    const result = await withTenantLock(
+      em as never,
+      { tenantId: TENANT_A, lockName: 'billing-run' },
+      async () => 'ok',
+    )
+    expect(result).toBe('ok')
+  })
+})