test(OUT-4011): cover mixed-payout invoice numbers and stale-object void

- mixed payout persists affected invoice numbers to remark; resolvePayments
  returns them
- notifier surfaces the invoice list through the real copy (both channels)
- invoice.voided on an OPEN row surfaces QBO 5010 as error_code (QB_STALE_OBJECT)
- fix duplicate createDeposit mock key; add IU-notify Copilot mocks

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

Author: SandipBajracharya

test/helpers/mocks.ts

@@ -71,6 +71,9 @@ export function createMockCopilotAPI(overrides: CopilotAPIOverrides = {}) {
       id: TEST_COPILOT_INVOICE_ID,
       number: TEST_INVOICE_NUMBER,
     }),
+    // Deferred SyncErrorNotifier dispatch calls these; empty IU list = no-op.
+    getInternalUsers: vi.fn().mockResolvedValue({ data: [] }),
+    createNotification: vi.fn().mockResolvedValue({ id: 'notif-1' }),
     ...overrides,
   }
 }
@@ -154,9 +157,6 @@ export function createMockIntuitAPI(overrides: IntuitAPIOverrides = {}) {
     createPurchase: vi.fn().mockResolvedValue({
       Purchase: { Id: TEST_QB_PURCHASE_ID, SyncToken: '0' },
     }),
-    createDeposit: vi.fn().mockResolvedValue({
-      Deposit: { Id: 'qb-deposit-1', SyncToken: '0' },
-    }),
     deletePurchase: vi.fn().mockResolvedValue({
       Purchase: { Id: TEST_QB_PURCHASE_ID, status: 'Deleted' },
     }),

test/integration/quickbooks/invoiceVoided/qbVoidStaleObject.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest'
+import { and, eq } from 'drizzle-orm'
+
+import { db } from '@/db'
+import { QBSyncLog } from '@/db/schema/qbSyncLogs'
+import { EntityType, EventType, LogStatus } from '@/app/api/core/types/log'
+import { QBOErrorCodes } from '@/constant/intuitErrorCode'
+import { HttpFetchError } from '@/utils/error'
+
+import { invoiceVoidedPayload } from '@test/fixtures/invoiceVoided.webhook'
+import {
+  seedHealthyPortal,
+  seedQBCustomer,
+  seedQBInvoiceSync,
+  seedInvoiceCreatedLog,
+  TEST_COPILOT_INVOICE_ID,
+} from '@test/helpers/seed'
+import { createMockIntuitAPI } from '@test/helpers/mocks'
+import { setupInvoiceVoidedTest } from '@test/helpers/invoiceVoidedTestSetup'
+import { postWebhook } from '@test/helpers/webhook'
+
+// Invoice voided out-of-band in QBO leaves our row OPEN, so the void hits a
+// stale SyncToken → 5010 → FAILED with error_code=5010 (routes to QB_STALE_OBJECT).
+describe('POST /api/quickbooks/webhook — invoice.voided (QBO returns 5010 stale object)', () => {
+  const apis = setupInvoiceVoidedTest(() => ({
+    intuit: createMockIntuitAPI({
+      voidInvoice: vi.fn().mockRejectedValue(
+        new HttpFetchError({
+          status: 400,
+          statusText: 'Bad Request',
+          url: 'https://quickbooks.api.intuit.com/v3/company/realm/invoice',
+          body: {
+            Fault: {
+              Error: [
+                {
+                  code: String(QBOErrorCodes.STALE_OBJECT),
+                  Message: 'Stale Object Error',
+                  Detail:
+                    'Stale Object Error : You and quickbooks-sync were working on this at the same time.',
+                },
+              ],
+              type: 'ValidationFault',
+            },
+          },
+        }),
+      ),
+    }),
+  }))
+
+  it('marks the voided log FAILED with error_code 5010 (routes to QB_STALE_OBJECT)', async () => {
+    await seedHealthyPortal()
+    const customer = await seedQBCustomer()
+    await seedQBInvoiceSync({ customerId: customer.id }) // defaults to OPEN
+    await seedInvoiceCreatedLog()
+
+    const res = await postWebhook(invoiceVoidedPayload)
+    expect(res.status).toBe(200)
+
+    const [voidedLog] = await db
+      .select()
+      .from(QBSyncLog)
+      .where(
+        and(
+          eq(QBSyncLog.copilotId, TEST_COPILOT_INVOICE_ID),
+          eq(QBSyncLog.eventType, EventType.VOIDED),
+        ),
+      )
+    expect(voidedLog.entityType).toBe(EntityType.INVOICE)
+    expect(voidedLog.status).toBe(LogStatus.FAILED)
+    // The QBO fault code must survive as error_code to route to QB_STALE_OBJECT.
+    expect(voidedLog.errorCode).toBe(String(QBOErrorCodes.STALE_OBJECT))
+
+    expect(apis.intuit.voidInvoice).toHaveBeenCalledTimes(1)
+  })
+})

test/integration/quickbooks/payoutReconciliation/mixed.test.ts

@@ -5,6 +5,7 @@ import { db } from '@/db'
 import { QBSyncLog } from '@/db/schema/qbSyncLogs'
 import { EntityType, EventType, LogStatus } from '@/app/api/core/types/log'
 
+import { PAYOUT_MIXED_INTENT_CODE } from '@/constant/intuitErrorCode'
 import { payoutPayload } from '@test/fixtures/payout.webhook'
 import {
   seedHealthyPortal,
@@ -53,5 +54,13 @@ describe('payout — invoices froze a mix of batched and non-batched', () => {
     expect(payoutLog.status).toBe(LogStatus.FAILED)
     expect(payoutLog.shouldRetry).toBe(false)
     expect(payoutLog.errorMessage).toContain('mixes batched and non-batched')
+    // Routable sentinel so SyncErrorNotifier notifies IUs for manual reconciliation.
+    expect(payoutLog.errorCode).toBe(PAYOUT_MIXED_INTENT_CODE)
+    // No qbItemName: it would outrank copilotId in the notification's entity
+    // reference, hiding which payout to reconcile.
+    expect(payoutLog.qbItemName).toBeNull()
+    // remark carries the affected invoice numbers so the IU notification can
+    // name which invoices went unrecorded.
+    expect(payoutLog.remark).toBe('INV-A, INV-B')
   })
 })

test/integration/quickbooks/payoutReconciliation/resolvePayments.test.ts

@@ -59,6 +59,7 @@ describe('SyncLogService.getSuccessfulPaidPaymentIds', () => {
     expect(result.get('inv_a')).toEqual({
       paymentId: 'qbpay_a',
       isBatchedDeposit: true,
+      invoiceNumber: 'INV-A',
     })
     expect(result.has('inv_b')).toBe(false) // FAILED excluded
     expect(result.has('inv_c')).toBe(false) // other portal excluded

test/unit/notification/notification.helper.test.ts

@@ -82,6 +82,38 @@ describe('getInProductNotificationDetail', () => {
     expect(detail.body).not.toContain('payment completion')
   })
 
+  it('renders payout reconciliation with the payout id as ref and names the affected invoices', () => {
+    const ctx: NotificationContext = {
+      entityType: 'payout',
+      eventType: 'settled',
+      entityKey: 'po_test_1',
+      invoiceNumbers: 'INV-A, INV-B',
+    }
+    const detail = getInProductNotificationDetail(
+      NotificationActions.QB_PAYOUT_MIXED_INTENT,
+      ctx,
+    )
+    expect(detail.body).toContain('during payout reconciliation, ref po_test_1')
+    expect(detail.body).not.toContain('ref Stripe payout')
+    expect(detail.body).toContain(
+      'No deposit was created for invoices INV-A, INV-B',
+    )
+  })
+
+  it('omits the invoice list from the payout body when no invoice numbers are present', () => {
+    const ctx: NotificationContext = {
+      entityType: 'payout',
+      eventType: 'settled',
+      entityKey: 'po_test_1',
+    }
+    const detail = getInProductNotificationDetail(
+      NotificationActions.QB_PAYOUT_MIXED_INTENT,
+      ctx,
+    )
+    expect(detail.body).toContain('No deposit was created, so nothing')
+    expect(detail.body).not.toContain('for invoices')
+  })
+
   it('5010 (invoice-only after suppression) warns that the failure is final', () => {
     const ctx: NotificationContext = {
       entityType: 'invoice',

test/unit/quickbooks/syncErrorNotifier.test.ts

@@ -42,9 +42,15 @@ import {
   getEntityKey,
 } from '@/app/api/quickbooks/syncLog/syncErrorNotifier'
 import {
+  AppActionableErrorCodes,
+  PAYOUT_MIXED_INTENT_CODE,
   QBOErrorCodes,
   UserActionableErrorCodes,
 } from '@/constant/intuitErrorCode'
+import {
+  getIEmailNotificationDetail,
+  getInProductNotificationDetail,
+} from '@/app/api/notification/notification.helper'
 
 const baseLog: QBSyncLogSelectSchemaType = {
   id: 'log-1',
@@ -70,6 +76,7 @@ const baseLog: QBSyncLogSelectSchemaType = {
   errorCode: String(QBOErrorCodes.CLOSED_PERIOD),
   category: 'qb_api_error' as never,
   attempt: 0,
+  shouldRetry: true,
   createdAt: new Date(),
   updatedAt: new Date(),
   deletedAt: null,
@@ -86,6 +93,14 @@ describe('getActionForErrorCode', () => {
     },
   )
 
+  // Self-extending over the app-level sentinel registry, mirroring the QBO one.
+  it.each(Object.entries(AppActionableErrorCodes))(
+    'maps app sentinel code %s to action %s',
+    (code, expectedAction) => {
+      expect(getActionForErrorCode(code)).toBe(expectedAction)
+    },
+  )
+
   it('returns null for unknown / transient / auth codes', () => {
     expect(getActionForErrorCode('429')).toBeNull()
     expect(getActionForErrorCode('500')).toBeNull()
@@ -223,6 +238,43 @@ describe('SyncErrorNotifier#notify', () => {
     },
   )
 
+  it('dispatches the mixed-payout notification for a FAILED payout with the sentinel code', async () => {
+    const notifier = new SyncErrorNotifier(user)
+
+    await notifier.notify({
+      ...baseLog,
+      entityType: 'payout' as never,
+      eventType: 'settled' as never,
+      errorCode: PAYOUT_MIXED_INTENT_CODE,
+      quickbooksId: null,
+      invoiceNumber: null,
+      copilotId: 'po_test_1',
+      // Webhook stashes the affected invoice numbers in remark for this action.
+      remark: 'INV-A, INV-B',
+      errorMessage:
+        'Payout po_test_1 mixes batched and non-batched invoices; unsupported',
+    })
+
+    expect(sendNotificationToIU).toHaveBeenCalledTimes(1)
+    const [, action, ctx] = sendNotificationToIU.mock.calls[0]
+    expect(action).toBe(NotificationActions.QB_PAYOUT_MIXED_INTENT)
+    // copilotId stays the ref; the invoice list rides in invoiceNumbers.
+    expect(ctx).toMatchObject({
+      entityType: 'payout',
+      entityKey: 'po_test_1',
+      invoiceNumbers: 'INV-A, INV-B',
+    })
+
+    // Close the seam: the ctx extracted from `remark` must render the invoice
+    // list in the real copy (both channels), with the payout id as the ref.
+    const inProduct = getInProductNotificationDetail(action, ctx)
+    const email = getIEmailNotificationDetail(action, ctx)
+    for (const body of [inProduct.body, email.body]) {
+      expect(body).toContain('ref po_test_1')
+      expect(body).toContain('No deposit was created for invoices INV-A, INV-B')
+    }
+  })
+
   it('dispatches a notification for a FAILED row with a user-actionable code', async () => {
     const notifier = new SyncErrorNotifier(user)