test(OUT-3617): cover the bank-deposit AB gate end to end

Unit tests for the gate util, the freeze and reconcile gates, and the
settings write path + bankDepositEnabled signal. Integration test drives
the real webhook -> invoice.service -> DB path to confirm an excluded
portal freezes non-batched. The gate is env-parsed at config load, so the
integration harness mocks it via a globalThis-pinned allowlist (default
= all portals) driven per-test by test/helpers/abTestGate.ts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: SandipBajracharya

test/helpers/abTestGate.ts

@@ -0,0 +1,17 @@
+// Drives the bank-deposit AB gate mocked in test/integration/setup.ts. The mock
+// reads its allowlist from a globalThis-pinned holder (the real allowlist is
+// env-parsed at module load and can't be varied per-test). `null` = feature on
+// for all portals. Always reset in afterEach so state doesn't leak across files.
+const AB_GATE_GLOBAL_KEY = '__qbsync_ab_test_gate__'
+type ABGate = { allowlist: string[] | null }
+const ref = globalThis as unknown as Record<string, ABGate | undefined>
+ref[AB_GATE_GLOBAL_KEY] ??= { allowlist: null }
+
+export const abTestGate = {
+  setAllowlist(portalIds: string[] | null) {
+    ref[AB_GATE_GLOBAL_KEY]!.allowlist = portalIds
+  },
+  reset() {
+    ref[AB_GATE_GLOBAL_KEY]!.allowlist = null
+  },
+}

test/integration/quickbooks/invoiceCreated/abTestingGate.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { db } from '@/db'
+import { QBInvoiceSync } from '@/db/schema/qbInvoiceSync'
+import invoiceCreatedPayload from '@test/fixtures/invoiceCreated.webhook'
+import {
+  seedHealthyPortal,
+  seedProductSync,
+  TEST_PORTAL_ID,
+} from '@test/helpers/seed'
+import { setupInvoiceCreatedTest } from '@test/helpers/invoiceCreatedTestSetup'
+import { postWebhook } from '@test/helpers/webhook'
+import { abTestGate } from '@test/helpers/abTestGate'
+
+// The freeze gate must win over the stored flag: a portal outside the AB
+// allowlist freezes non-batched even with bankDepositFeeFlag=true, so the whole
+// downstream payout/deposit path never engages for it.
+describe('POST /api/quickbooks/webhook — invoice.created AB gate on batched intent', () => {
+  setupInvoiceCreatedTest()
+
+  afterEach(() => {
+    abTestGate.reset()
+  })
+
+  it('freezes non-batched for a portal outside the allowlist despite the flag being on', async () => {
+    abTestGate.setAllowlist(['some-other-portal'])
+    await seedHealthyPortal({ setting: { bankDepositFeeFlag: true } })
+    await seedProductSync()
+
+    await postWebhook(invoiceCreatedPayload)
+
+    const [row] = await db.select().from(QBInvoiceSync)
+    expect(row.isBatchedDeposit).toBe(false)
+  })
+
+  it('freezes batched for a portal on the allowlist with the flag on', async () => {
+    abTestGate.setAllowlist([TEST_PORTAL_ID])
+    await seedHealthyPortal({ setting: { bankDepositFeeFlag: true } })
+    await seedProductSync()
+
+    await postWebhook(invoiceCreatedPayload)
+
+    const [row] = await db.select().from(QBInvoiceSync)
+    expect(row.isBatchedDeposit).toBe(true)
+  })
+})

test/integration/setup.ts

@@ -103,6 +103,23 @@ vi.mock('@/utils/sleep', () => ({
   sleep: vi.fn().mockResolvedValue(undefined),
 }))
 
+// AB gate for the bank deposit rollout. The real allowlist is parsed from env
+// at `@/config` module load, so it can't be varied per-test once loaded. We
+// mock the gate here (setupFiles runs before any app module binds it) and drive
+// it via a globalThis-pinned allowlist. Default `null` = feature on for all
+// portals, matching the empty-env behavior so existing tests are unaffected.
+// A test opts in by setting `abTestGate.allowlist`; reset it in afterEach.
+const AB_GATE_GLOBAL_KEY = '__qbsync_ab_test_gate__'
+type ABGate = { allowlist: string[] | null }
+const abGateRef = globalThis as unknown as Record<string, ABGate | undefined>
+abGateRef[AB_GATE_GLOBAL_KEY] ??= { allowlist: null }
+vi.mock('@/utils/abTesting', () => ({
+  isPortalInBankDepositABTest: (portalId: string) => {
+    const gate = abGateRef[AB_GATE_GLOBAL_KEY]!
+    return gate.allowlist === null || gate.allowlist.includes(portalId)
+  },
+}))
+
 // Importing modules that pull `next/server` corrupts NTARH's AsyncLocalStorage.
 // Shimming this entry point keeps the next/server import out of the graph.
 vi.mock('@/app/api/core/utils/afterIfAvailable', () => ({

test/unit/app/api/quickbooks/invoice/invoice.service.bankDepositGate.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Freeze-point coverage for InvoiceService#readBankDepositFeeFlag — the one
+ * place invoice creation decides batched intent. A portal outside the AB
+ * allowlist must freeze non-batched regardless of its stored setting, and must
+ * not even read the setting. readBankDepositFeeFlag is private, reached via a
+ * type cast (same approach as invoice.service.docNumber.test.ts).
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('@sentry/nextjs', () => ({
+  withScope: vi.fn((cb: (scope: unknown) => void) =>
+    cb({ setTag: vi.fn(), setExtra: vi.fn(), addEventProcessor: vi.fn() }),
+  ),
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+  addBreadcrumb: vi.fn(),
+  init: vi.fn(),
+}))
+vi.mock('@/utils/logger', () => ({
+  default: { info: vi.fn(), error: vi.fn() },
+}))
+vi.mock('@/utils/copilotAPI', () => ({ CopilotAPI: vi.fn() }))
+vi.mock('@/utils/intuitAPI', () => ({
+  default: vi.fn(),
+  IntuitAPIErrorMessage: '#IntuitAPIErrorMessage#',
+}))
+// BaseService imports `@/db`, which initialises postgres at module load.
+vi.mock('@/db', () => ({ db: {}, client: {} }))
+vi.mock('@/utils/sentry', () => ({
+  addSyncBreadcrumb: vi.fn(),
+  captureSyncError: vi.fn(),
+}))
+// SyncLogService is instantiated in the InvoiceService constructor.
+vi.mock('@/app/api/quickbooks/syncLog/syncLog.service', () => ({
+  SyncLogService: vi.fn(function () {
+    return {}
+  }),
+}))
+
+const { getOneByPortalId, isPortalInBankDepositABTest } = vi.hoisted(() => ({
+  getOneByPortalId: vi.fn(),
+  isPortalInBankDepositABTest: vi.fn(),
+}))
+vi.mock('@/app/api/quickbooks/setting/setting.service', () => ({
+  SettingService: vi.fn(function () {
+    return { getOneByPortalId }
+  }),
+}))
+vi.mock('@/utils/abTesting', () => ({ isPortalInBankDepositABTest }))
+
+import { InvoiceService } from '@/app/api/quickbooks/invoice/invoice.service'
+import User from '@/app/api/core/models/User.model'
+
+const stubUser = {
+  workspaceId: 'test-portal-00000001',
+  token: 'tkn',
+  qbConnection: undefined,
+} as unknown as User
+
+type WithReadFlag = { readBankDepositFeeFlag: () => Promise<boolean> }
+const newSvc = () => new InvoiceService(stubUser) as unknown as WithReadFlag
+
+describe('InvoiceService#readBankDepositFeeFlag — AB freeze gate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('freezes non-batched and skips the setting read for an excluded portal', async () => {
+    isPortalInBankDepositABTest.mockReturnValue(false)
+    getOneByPortalId.mockResolvedValue({ bankDepositFeeFlag: true })
+
+    expect(await newSvc().readBankDepositFeeFlag()).toBe(false)
+    expect(getOneByPortalId).not.toHaveBeenCalled()
+  })
+
+  it('honors the stored flag for an allowlisted portal', async () => {
+    isPortalInBankDepositABTest.mockReturnValue(true)
+    getOneByPortalId.mockResolvedValue({ bankDepositFeeFlag: true })
+
+    expect(await newSvc().readBankDepositFeeFlag()).toBe(true)
+  })
+
+  it('defaults to false when an allowlisted portal has no setting row', async () => {
+    isPortalInBankDepositABTest.mockReturnValue(true)
+    getOneByPortalId.mockResolvedValue(undefined)
+
+    expect(await newSvc().readBankDepositFeeFlag()).toBe(false)
+  })
+})

test/unit/payout/payout.service.bankDepositGate.test.ts

@@ -0,0 +1,76 @@
+/**
+ * AB-gate coverage for PayoutService#reconcile — the deposit-creating step,
+ * shared by the payout webhook and the resync cron. An excluded portal must
+ * short-circuit to { depositId: null } before any token check or QBO call.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { QBPayoutSyncSelectSchemaType } from '@/db/schema/qbPayoutSync'
+import type { IntuitAPITokensType } from '@/utils/intuitAPI'
+
+vi.mock('@sentry/nextjs', () => ({
+  withScope: vi.fn(),
+  captureException: vi.fn(),
+  captureMessage: vi.fn(),
+  addBreadcrumb: vi.fn(),
+  init: vi.fn(),
+}))
+// BaseService imports `@/db`, which initialises postgres at module load.
+vi.mock('@/db', () => ({ db: {}, client: {} }))
+vi.mock('@/utils/copilotAPI', () => ({ CopilotAPI: vi.fn() }))
+vi.mock('@/utils/intuitAPI', () => ({ default: vi.fn() }))
+vi.mock('@/app/api/quickbooks/syncLog/syncLog.service', () => ({
+  SyncLogService: vi.fn(function () {
+    return {}
+  }),
+}))
+
+const { validateAccessToken, isPortalInBankDepositABTest } = vi.hoisted(() => ({
+  validateAccessToken: vi.fn(),
+  isPortalInBankDepositABTest: vi.fn(),
+}))
+vi.mock('@/utils/auth', () => ({ validateAccessToken }))
+vi.mock('@/utils/abTesting', () => ({ isPortalInBankDepositABTest }))
+
+import { PayoutService } from '@/app/api/quickbooks/payout/payout.service'
+import User from '@/app/api/core/models/User.model'
+
+const stubUser = { workspaceId: 'test-portal-00000001' } as unknown as User
+const stubRow = {
+  payoutId: 'po_123',
+} as unknown as QBPayoutSyncSelectSchemaType
+const stubTokens = {} as IntuitAPITokensType
+
+describe('PayoutService#reconcile — AB gate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('short-circuits to no deposit for an excluded portal without checking the token', async () => {
+    isPortalInBankDepositABTest.mockReturnValue(false)
+
+    const result = await new PayoutService(stubUser).reconcile(
+      stubRow,
+      stubTokens,
+      { runIdempotencyCheck: true },
+    )
+
+    expect(result).toEqual({ depositId: null })
+    expect(validateAccessToken).not.toHaveBeenCalled()
+  })
+
+  it('proceeds past the gate for an allowlisted portal', async () => {
+    isPortalInBankDepositABTest.mockReturnValue(true)
+    // Force a stop right after the gate so we assert only that it advanced.
+    validateAccessToken.mockImplementation(() => {
+      throw new Error('advanced past gate')
+    })
+
+    await expect(
+      new PayoutService(stubUser).reconcile(stubRow, stubTokens, {
+        runIdempotencyCheck: true,
+      }),
+    ).rejects.toThrow('advanced past gate')
+    expect(validateAccessToken).toHaveBeenCalledTimes(1)
+  })
+})