@dainamite/billing 0.17.0

package/src/modules/billing/__tests__/commands/itemsBulk.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Unit tests for `billing.items.bulk_create`.
+ *
+ * Focus: the batching contract — one account query, one idempotency
+ * query, one flush — plus the dedup paths (existing source_ref,
+ * in-batch repeated source_ref) and the missing-account 404.
+ */
+
+import { bulkCreateItemsCommand } from '../../commands/items'
+import { BillingAccount, BillingItem } from '../../data/entities'
+
+const TENANT = '11111111-1111-4111-8111-111111111111'
+const ORG = '22222222-2222-4222-8222-222222222222'
+const ACCOUNT_A = '33333333-3333-4333-8333-333333333333'
+const ACCOUNT_B = '44444444-4444-4444-8444-444444444444'
+
+type FakeItem = {
+  id: string
+  billAccountId: string
+  sourceRef: string | null
+}
+
+type Env = {
+  ctx: { container: { resolve: jest.MockedFunction<(name: string) => unknown> }; auth: null }
+  em: {
+    find: jest.MockedFunction<(entity: unknown, where: unknown) => Promise<unknown[]>>
+    create: jest.MockedFunction<(entity: unknown, data: Record<string, unknown>) => unknown>
+    persist: jest.MockedFunction<(entity: unknown) => unknown>
+    flush: jest.MockedFunction<() => Promise<void>>
+    fork: jest.MockedFunction<() => Env['em']>
+  }
+  flushCount: () => number
+  persistedCount: () => number
+}
+
+let createSeq = 0
+
+function createEnv(
+  options: {
+    existingAccountIds?: string[]
+    existingItems?: FakeItem[]
+  } = {},
+): Env {
+  const existingAccountIds = options.existingAccountIds ?? [ACCOUNT_A, ACCOUNT_B]
+  const existingItems = options.existingItems ?? []
+  let flushes = 0
+  let persists = 0
+  const pendingPersist: Record<string, unknown>[] = []
+
+  const em: Env['em'] = {
+    find: jest.fn(async (entity: unknown, where: unknown) => {
+      const ctor = (entity as { name?: string }).name ?? ''
+      if (ctor === 'BillingAccount') {
+        const ids = (where as { id?: { $in?: string[] } }).id?.$in ?? []
+        return ids
+          .filter((id) => existingAccountIds.includes(id))
+          .map((id) => ({ id, tenantId: TENANT, organizationId: ORG }))
+      }
+      if (ctor === 'BillingItem') {
+        const refs = (where as { sourceRef?: { $in?: string[] } }).sourceRef?.$in ?? []
+        const accountIds = (where as { billAccountId?: { $in?: string[] } }).billAccountId?.$in ?? []
+        return existingItems.filter(
+          (it) =>
+            it.sourceRef != null &&
+            refs.includes(it.sourceRef) &&
+            accountIds.includes(it.billAccountId),
+        )
+      }
+      return []
+    }) as never,
+    create: jest.fn((_entity: unknown, data: Record<string, unknown>) => {
+      // Real MikroORM leaves the UUID PK unassigned until flush — the
+      // mock mirrors that so id-before-flush bugs surface in tests.
+      return { ...data }
+    }) as never,
+    persist: jest.fn((entity: unknown) => {
+      persists += 1
+      pendingPersist.push(entity as Record<string, unknown>)
+    }) as never,
+    flush: jest.fn(async () => {
+      flushes += 1
+      // The flush is what assigns the DB-generated UUID PK.
+      for (const entity of pendingPersist) {
+        if (!entity.id) {
+          createSeq += 1
+          entity.id = `new-item-${createSeq}`
+        }
+      }
+      pendingPersist.length = 0
+    }) as never,
+    fork: jest.fn() as never,
+  }
+  em.fork = jest.fn(() => em) as never
+
+  const container = {
+    resolve: jest.fn((name: string) => {
+      if (name === 'em') return em
+      if (name === 'dataEngine') return { markOrmEntityChange: jest.fn() }
+      return null
+    }) as never,
+  }
+
+  return {
+    ctx: { container, auth: null },
+    em,
+    flushCount: () => flushes,
+    persistedCount: () => persists,
+  }
+}
+
+beforeEach(() => {
+  createSeq = 0
+})
+
+function recurringEntry(billAccountId: string, sourceRef?: string) {
+  // `billStartDate` is a Date here because `BillingItemBulkCreateInput`
+  // is the *parsed* schema type (`z.coerce.date()` output). The route
+  // layer hands the command already-coerced values.
+  return {
+    billAccountId,
+    type: 'recurring' as const,
+    billStartDate: new Date('2026-05-01T00:00:00.000Z'),
+    description: 'MRC',
+    rateJson: { unit_price: 49.99 } as unknown,
+    ...(sourceRef ? { sourceRef } : {}),
+  }
+}
+
+describe('bulkCreateItemsCommand', () => {
+  it('creates every item in a clean batch with a single flush', async () => {
+    const env = createEnv()
+    const result = await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [
+          recurringEntry(ACCOUNT_A, 'ref-1'),
+          recurringEntry(ACCOUNT_A, 'ref-2'),
+          recurringEntry(ACCOUNT_B, 'ref-3'),
+        ],
+      },
+      env.ctx as never,
+    )
+    expect(result.created).toBe(3)
+    expect(result.deduplicated).toBe(0)
+    expect(result.items).toHaveLength(3)
+    // Every created row carries the id the flush assigned — the
+    // result must not snapshot the pre-flush (undefined) value.
+    for (const item of result.items) {
+      expect(item.id).toMatch(/^new-item-/)
+      expect(item.deduplicated).toBe(false)
+    }
+    // The batching contract: ONE flush for the whole batch.
+    expect(env.flushCount()).toBe(1)
+    expect(env.persistedCount()).toBe(3)
+  })
+
+  it('uses a single batched idempotency query (not one per item)', async () => {
+    const env = createEnv()
+    await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [
+          recurringEntry(ACCOUNT_A, 'ref-1'),
+          recurringEntry(ACCOUNT_A, 'ref-2'),
+          recurringEntry(ACCOUNT_A, 'ref-3'),
+        ],
+      },
+      env.ctx as never,
+    )
+    // find calls: 1 for BillingAccount, 1 for BillingItem idempotency.
+    const billingItemFinds = env.em.find.mock.calls.filter(
+      (call) => (call[0] as { name?: string }).name === 'BillingItem',
+    )
+    expect(billingItemFinds).toHaveLength(1)
+  })
+
+  it('dedups against an existing source_ref (returns the existing id)', async () => {
+    const env = createEnv({
+      existingItems: [{ id: 'existing-99', billAccountId: ACCOUNT_A, sourceRef: 'ref-dup' }],
+    })
+    const result = await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [
+          recurringEntry(ACCOUNT_A, 'ref-dup'),
+          recurringEntry(ACCOUNT_A, 'ref-new'),
+        ],
+      },
+      env.ctx as never,
+    )
+    expect(result.created).toBe(1)
+    expect(result.deduplicated).toBe(1)
+    const dup = result.items.find((i) => i.sourceRef === 'ref-dup')
+    expect(dup).toMatchObject({ id: 'existing-99', deduplicated: true })
+  })
+
+  it('dedups a source_ref repeated within the same payload (first wins)', async () => {
+    const env = createEnv()
+    const result = await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [
+          recurringEntry(ACCOUNT_A, 'ref-twice'),
+          recurringEntry(ACCOUNT_A, 'ref-twice'),
+        ],
+      },
+      env.ctx as never,
+    )
+    // Only ONE row actually persisted — the unique index would
+    // otherwise reject the second on flush.
+    expect(result.created).toBe(1)
+    expect(result.deduplicated).toBe(1)
+    expect(env.persistedCount()).toBe(1)
+    // The repeat reports the SAME id as the row that persisted, and
+    // that id is the flush-assigned value (not '' captured pre-flush).
+    const created = result.items.find((i) => !i.deduplicated)
+    const repeated = result.items.find((i) => i.deduplicated)
+    expect(created?.id).toMatch(/^new-item-/)
+    expect(repeated?.id).toBe(created?.id)
+  })
+
+  it('items without source_ref are always created (no dedup)', async () => {
+    const env = createEnv()
+    const result = await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [recurringEntry(ACCOUNT_A), recurringEntry(ACCOUNT_A)],
+      },
+      env.ctx as never,
+    )
+    expect(result.created).toBe(2)
+    expect(result.deduplicated).toBe(0)
+  })
+
+  it('throws 404 when any referenced account is missing', async () => {
+    const env = createEnv({ existingAccountIds: [ACCOUNT_A] })
+    await expect(
+      bulkCreateItemsCommand.execute(
+        {
+          tenantId: TENANT,
+          organizationId: ORG,
+          items: [recurringEntry(ACCOUNT_A), recurringEntry(ACCOUNT_B)],
+        },
+        env.ctx as never,
+      ),
+    ).rejects.toMatchObject({
+      status: 404,
+      body: expect.objectContaining({ billAccountId: ACCOUNT_B }),
+    })
+  })
+
+  it('queries the distinct account ids in one $in (not one per item)', async () => {
+    const env = createEnv()
+    await bulkCreateItemsCommand.execute(
+      {
+        tenantId: TENANT,
+        organizationId: ORG,
+        items: [
+          recurringEntry(ACCOUNT_A),
+          recurringEntry(ACCOUNT_A),
+          recurringEntry(ACCOUNT_B),
+        ],
+      },
+      env.ctx as never,
+    )
+    const accountFinds = env.em.find.mock.calls.filter(
+      (call) => (call[0] as { name?: string }).name === 'BillingAccount',
+    )
+    expect(accountFinds).toHaveLength(1)
+    const where = accountFinds[0][1] as { id?: { $in?: string[] } }
+    // Distinct — A appears twice in the payload but once in the query.
+    expect(new Set(where.id?.$in)).toEqual(new Set([ACCOUNT_A, ACCOUNT_B]))
+  })
+})
+
+// Suppress unused-import warnings — the entity classes are referenced
+// only through the mock's `.name` discriminator.
+void BillingAccount
+void BillingItem

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

@@ -0,0 +1,131 @@
+import {
+  advanceNextBillDate,
+  cloneAtMidnight,
+  cycleContaining,
+  deriveBillPeriod,
+  isCycleDue,
+} from '../../lib/billPeriod'
+
+function date(iso: string): Date {
+  return new Date(`${iso}T00:00:00.000Z`)
+}
+
+function iso(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+describe('deriveBillPeriod — spec reference table', () => {
+  it('monthly anchor 1: next=2026-06-01 → 2026-05-01..2026-05-31', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-06-01'), 'monthly')
+    expect(iso(periodStart)).toBe('2026-05-01')
+    expect(iso(periodEnd)).toBe('2026-05-31')
+  })
+
+  it('monthly anchor 1: next=2026-03-01 → 2026-02-01..2026-02-28', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-03-01'), 'monthly')
+    expect(iso(periodStart)).toBe('2026-02-01')
+    expect(iso(periodEnd)).toBe('2026-02-28')
+  })
+
+  it('monthly anchor 1: leap year — next=2024-03-01 → 2024-02-01..2024-02-29', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2024-03-01'), 'monthly')
+    expect(iso(periodStart)).toBe('2024-02-01')
+    expect(iso(periodEnd)).toBe('2024-02-29')
+  })
+
+  it('quarterly anchor 1: next=2026-07-01 → 2026-04-01..2026-06-30', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-07-01'), 'quarterly')
+    expect(iso(periodStart)).toBe('2026-04-01')
+    expect(iso(periodEnd)).toBe('2026-06-30')
+  })
+
+  it('weekly anchor mon: next=2026-05-04 (Mon) → 2026-04-27 (Mon)..2026-05-03 (Sun)', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-05-04'), 'weekly')
+    expect(iso(periodStart)).toBe('2026-04-27')
+    expect(iso(periodEnd)).toBe('2026-05-03')
+  })
+
+  it('annually: next=2026-01-01 → 2025-01-01..2025-12-31', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-01-01'), 'annually')
+    expect(iso(periodStart)).toBe('2025-01-01')
+    expect(iso(periodEnd)).toBe('2025-12-31')
+  })
+
+  it('month-end clamp: next=2026-03-31 → 2026-02-28..2026-03-30 (Feb has 28 days)', () => {
+    const { periodStart, periodEnd } = deriveBillPeriod(date('2026-03-31'), 'monthly')
+    expect(iso(periodStart)).toBe('2026-02-28')
+    expect(iso(periodEnd)).toBe('2026-03-30')
+  })
+})
+
+describe('advanceNextBillDate', () => {
+  it.each([
+    ['monthly', '2026-05-01', '2026-06-01'],
+    ['monthly', '2024-01-31', '2024-02-29'], // leap clamp
+    ['quarterly', '2026-04-01', '2026-07-01'],
+    ['weekly', '2026-04-27', '2026-05-04'],
+    ['annually', '2025-01-01', '2026-01-01'],
+  ] as const)('%s: %s → %s', (cycle, from, to) => {
+    expect(iso(advanceNextBillDate(date(from), cycle))).toBe(to)
+  })
+
+  it('chained advances stay anchored (monthly: 2024-01-31 → … → 2024-04-30)', () => {
+    let d = date('2024-01-31')
+    d = advanceNextBillDate(d, 'monthly') // → 2024-02-29
+    d = advanceNextBillDate(d, 'monthly') // → 2024-03-29 (drifts off 31)
+    d = advanceNextBillDate(d, 'monthly') // → 2024-04-29
+    // Calendar drift is the documented JS semantic — once we clamp on
+    // Feb 29 we lose the "always last day of month" intent. This test
+    // pins the behavior so it doesn't quietly change.
+    expect(iso(d)).toBe('2024-04-29')
+  })
+})
+
+describe('isCycleDue', () => {
+  it('returns true when nextBillDate ≤ asOfDate', () => {
+    expect(isCycleDue(date('2026-06-01'), date('2026-06-01'))).toBe(true)
+    expect(isCycleDue(date('2026-05-15'), date('2026-06-01'))).toBe(true)
+  })
+
+  it('returns false when nextBillDate > asOfDate', () => {
+    expect(isCycleDue(date('2026-06-02'), date('2026-06-01'))).toBe(false)
+  })
+
+  it('ignores time-of-day (date-only comparison)', () => {
+    const next = new Date('2026-06-01T23:59:59Z')
+    const asOf = new Date('2026-06-01T00:00:00Z')
+    expect(isCycleDue(next, asOf)).toBe(true)
+  })
+})
+
+describe('cloneAtMidnight', () => {
+  it('zeros UTC time without mutating the source', () => {
+    const src = new Date('2026-06-01T13:45:30Z')
+    const result = cloneAtMidnight(src)
+    expect(result.toISOString()).toBe('2026-06-01T00:00:00.000Z')
+    expect(src.toISOString()).toBe('2026-06-01T13:45:30.000Z')
+  })
+})
+
+describe('cycleContaining', () => {
+  it.each([
+    // anchor (a known boundary), cycle, target, expectedStart, expectedEnd
+    ['2026-06-01', 'monthly', '2026-05-15', '2026-05-01', '2026-05-31'],
+    ['2026-06-01', 'monthly', '2026-06-01', '2026-06-01', '2026-06-30'], // anchor = cycle start
+    ['2026-06-01', 'monthly', '2026-06-10', '2026-06-01', '2026-06-30'],
+    ['2026-06-01', 'monthly', '2026-07-15', '2026-07-01', '2026-07-31'], // walk forward
+    ['2026-06-01', 'monthly', '2026-02-15', '2026-02-01', '2026-02-28'], // walk backward
+    ['2026-05-04', 'weekly', '2026-05-06', '2026-05-04', '2026-05-10'],
+    ['2026-07-01', 'quarterly', '2026-05-20', '2026-04-01', '2026-06-30'],
+  ] as const)('%s %s containing %s → %s..%s', (anchor, cycle, target, start, end) => {
+    const period = cycleContaining(date(anchor), cycle, date(target))
+    expect(iso(period.periodStart)).toBe(start)
+    expect(iso(period.periodEnd)).toBe(end)
+  })
+
+  it('accepts YYYY-MM-DD strings for anchor and target', () => {
+    const period = cycleContaining('2026-06-01', 'monthly', '2026-05-15')
+    expect(iso(period.periodStart)).toBe('2026-05-01')
+    expect(iso(period.periodEnd)).toBe('2026-05-31')
+  })
+})