OUT-3686: paginate-and-filter QBO customer email lookup

src/app/api/quickbooks/customer/customer.service.ts

@@ -346,26 +346,22 @@ export class CustomerService extends BaseService {
     invoiceResource: InvoiceCreatedResponseType['data']
   }) {
     const displayName = recipientInfo.displayName
+    const sanitizedCompanyName = recipientInfo.companyName
+      ? replaceSpecialCharsForQB(recipientInfo.companyName)
+      : undefined
+
     // 2.1. search client in qb using recipient's email or display name
     let customer = recipientInfo.email
-      ? await intuitApiService.getCustomerByEmail(recipientInfo.email)
+      ? await intuitApiService.getCustomerByEmail(
+          recipientInfo.email,
+          sanitizedCompanyName,
+        )
       : await intuitApiService.getACustomer(
           replaceSpecialCharsForQB(recipientInfo.displayName),
           undefined,
           true,
         )
 
-    // 2.2. verify the matched customer has the same company name. This is needed because a single customer with same email can be part of multiple companies
-    const sanitizedCompanyName = recipientInfo.companyName
-      ? replaceSpecialCharsForQB(recipientInfo.companyName)
-      : undefined
-    if (
-      customer &&
-      (customer.CompanyName || undefined) !== sanitizedCompanyName
-    ) {
-      customer = undefined
-    }
-
     addSyncBreadcrumb('Customer search in QBO', {
       found: !!customer,
     })

src/utils/intuitAPI.ts

@@ -296,20 +296,44 @@ export default class IntuitAPI {
     return CustomerQueryResponseSchema.parse(qbCustomers.Customer[0])
   }
 
+  // QBO's parser mishandles special chars on PrimaryEmailAddr filters, so we
+  // page and match client-side. sanitizedCompanyName disambiguates the same
+  // email across companies; normalisation matches customer.service.ts.
+  // ORDERBY Id ASC pins a stable cursor — QBO's default (LastUpdatedTime DESC)
+  // lets a mid-walk update shift a row past STARTPOSITION (false negative).
   async _getCustomerByEmail(
     email: string,
+    sanitizedCompanyName?: string,
   ): Promise<CustomerQueryResponseType | undefined> {
+    const needle = email.trim().toLowerCase()
+    if (!needle) return
+
     CustomLogger.info({
-      obj: { email },
+      obj: { email, sanitizedCompanyName },
       message: `IntuitAPI#getCustomerByEmail | Customer query start for realmId: ${this.tokens.intuitRealmId}. Email: ${email}`,
     })
-    const customerQuery = `SELECT Id, SyncToken, Active, CompanyName, PrimaryEmailAddr FROM Customer WHERE PrimaryEmailAddr = '${escapeForQBQuery(email)}' AND Active in (true, false)`
-    const qbCustomers = await this.customQuery(customerQuery)
 
-    if (!qbCustomers) return
+    const pageSize = 1000
+    let startPosition = 1
 
-    if (!qbCustomers.Customer) return
-    return CustomerQueryResponseSchema.parse(qbCustomers.Customer[0])
+    while (true) {
+      const customerQuery = `SELECT Id, SyncToken, Active, CompanyName, PrimaryEmailAddr FROM Customer WHERE Active IN (true, false) ORDERBY Id ASC STARTPOSITION ${startPosition} MAXRESULTS ${pageSize}`
+      const qbCustomers = await this.customQuery(customerQuery)
+      const customers = qbCustomers?.Customer ?? []
+      if (customers.length === 0) return
+
+      const match = customers.find((c: CustomerQueryResponseType) => {
+        const addr = c.PrimaryEmailAddr?.Address
+        if (typeof addr !== 'string') return false
+        if (addr.trim().toLowerCase() !== needle) return false
+        if ((c.CompanyName || undefined) !== sanitizedCompanyName) return false
+        return true
+      })
+      if (match) return CustomerQueryResponseSchema.parse(match)
+
+      if (customers.length < pageSize) return
+      startPosition += pageSize
+    }
   }
 
   /**
@@ -892,7 +916,10 @@ export default class IntuitAPI {
       includeInactive?: boolean,
     ): Promise<CustomerQueryResponseType>
   } = this.wrapWithRetry(this._getACustomer) as any
-  getCustomerByEmail = this.wrapWithRetry(this._getCustomerByEmail)
+  // Intentionally NOT wrapped in wrapWithRetry — a transient 429 mid-walk would
+  // replay from page 1 and amplify rate-limit pressure. The inner customQuery
+  // calls already retry on 429 (same reasoning as resolveUniqueCustomerName).
+  getCustomerByEmail = this._getCustomerByEmail.bind(this)
   getAnItem: {
     (
       name: string,