fix(quickbooks): address parity review findings

Author: Bill Leoutsakos

apps/docs/content/docs/en/integrations/quickbooks.mdx

@@ -117,7 +117,7 @@ List or read one account, class, customer, department, employee, item, or vendor
 |   ↳ `BillAddr` | json | Customer or vendor billing address |
 |   ↳ `ShipAddr` | json | Customer shipping address |
 |   ↳ `Balance` | number | Customer or vendor balance |
-|   ↳ `PrintOnCheckName` | string | Employee name printed on checks |
+|   ↳ `PrintOnCheckName` | string | Vendor or employee name printed on checks |
 |   ↳ `Vendor1099` | boolean | Whether the vendor is tracked for 1099 reporting |
 |   ↳ `AcctNum` | string | Vendor account number |
 |   ↳ `Description` | string | Item sales description |
@@ -173,7 +173,7 @@ List or read one account, class, customer, department, employee, item, or vendor
 |   ↳ `BillAddr` | json | Customer or vendor billing address |
 |   ↳ `ShipAddr` | json | Customer shipping address |
 |   ↳ `Balance` | number | Customer or vendor balance |
-|   ↳ `PrintOnCheckName` | string | Employee name printed on checks |
+|   ↳ `PrintOnCheckName` | string | Vendor or employee name printed on checks |
 |   ↳ `Vendor1099` | boolean | Whether the vendor is tracked for 1099 reporting |
 |   ↳ `AcctNum` | string | Vendor account number |
 |   ↳ `Description` | string | Item sales description |

apps/sim/app/api/tools/quickbooks/documents.test.ts

@@ -153,6 +153,30 @@ describe('QuickBooks document API routes', () => {
     expect(String(mockFetch.mock.calls[0][0])).toContain('/invoice/A%2FB/pdf')
   })
 
+  it('accepts Payment through the canonical PDF route contract', async () => {
+    mockFetch.mockResolvedValueOnce(
+      new Response('%PDF-1.4 fixture', {
+        headers: { 'content-type': 'application/pdf' },
+      })
+    )
+
+    const response = await downloadTransactionPdf(
+      createMockRequest('POST', {
+        ...auth,
+        transactionType: 'payment',
+        transactionId: '42',
+      })
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({
+      success: true,
+      output: { transactionType: 'payment', transactionId: '42' },
+    })
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+    expect(String(mockFetch.mock.calls[0][0])).toContain('/payment/42/pdf')
+  })
+
   it('rejects non-PDF and oversized PDF responses', async () => {
     mockFetch.mockResolvedValueOnce(
       new Response('not a PDF', { headers: { 'content-type': 'text/plain' } })

apps/sim/blocks/blocks/quickbooks.ts

@@ -774,11 +774,14 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       description:
         'Supported for purchase orders, bills, bill payments, and vendor credits. Purchase/Expense filtering is not exposed because its reference contract differs.',
       mode: 'advanced',
-      condition: {
+      condition: (values) => ({
         field: 'operation',
         value: PURCHASING_READ_OPERATION,
-        and: { field: 'readMode', value: 'list' },
-      },
+        and:
+          values?.purchasingTransactionType === 'purchase'
+            ? { field: 'purchasingTransactionType', value: 'purchase', not: true }
+            : { field: 'readMode', value: 'list' },
+      }),
     },
     {
       id: 'transactionType',
@@ -2090,7 +2093,10 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
             readMode: params.readMode,
             startDate: optionalValue(params.readStartDate),
             endDate: optionalValue(params.readEndDate),
-            vendorId: optionalValue(params.readVendorId),
+            vendorId:
+              params.purchasingTransactionType === 'purchase'
+                ? undefined
+                : optionalValue(params.readVendorId),
             startPosition: parsePaginationInteger(params.startPosition, 'startPosition', 1),
             maxResults: parsePaginationInteger(params.maxResults, 'maxResults', 25),
           }

apps/sim/lib/api/contracts/tools/quickbooks.ts

@@ -26,6 +26,7 @@ const documentTransactionTypeSchema = z.enum([
   'credit_memo',
   'estimate',
   'invoice',
+  'payment',
   'purchase_order',
   'refund_receipt',
   'sales_receipt',

apps/sim/tools/generated/tool-outputs.ts

@@ -1,5 +1,6 @@
 import { resetEnvMock, setEnv } from '@sim/testing'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { evaluateSubBlockCondition } from '@/lib/workflows/subblocks/visibility'
 import { QuickBooksBlock } from '@/blocks/blocks/quickbooks'
 import {
   quickbooksCreateBillPaymentTool,
@@ -830,6 +831,35 @@ describe('QuickBooks BillPayment account compatibility', () => {
 })
 
 describe('QuickBooks purchasing block', () => {
+  it('hides and omits the unsupported Purchase/Expense vendor filter', () => {
+    const readVendorId = QuickBooksBlock.subBlocks.find(
+      (candidate) => candidate.id === 'readVendorId'
+    )
+    expect(
+      evaluateSubBlockCondition(readVendorId?.condition, {
+        operation: 'quickbooks_read_purchasing_transactions',
+        readMode: 'list',
+        purchasingTransactionType: 'bill',
+      })
+    ).toBe(true)
+    expect(
+      evaluateSubBlockCondition(readVendorId?.condition, {
+        operation: 'quickbooks_read_purchasing_transactions',
+        readMode: 'list',
+        purchasingTransactionType: 'purchase',
+      })
+    ).toBe(false)
+    expect(
+      QuickBooksBlock.tools.config!.params!({
+        operation: 'quickbooks_read_purchasing_transactions',
+        oauthCredential: 'credential-id',
+        purchasingTransactionType: 'purchase',
+        readMode: 'list',
+        readVendorId: '62',
+      })
+    ).toMatchObject({ transactionType: 'purchase', vendorId: undefined })
+  })
+
   it('keeps the shared purchasing-lines example valid for every supported operation', () => {
     const subBlock = QuickBooksBlock.subBlocks.find(
       (candidate) => candidate.id === 'purchasingLines'

apps/sim/tools/quickbooks/purchasing.test.ts

@@ -155,6 +155,23 @@ describe('QuickBooks financial report request construction', () => {
     })
   })
 
+  it.each([
+    ['transactionType', 'bogus'],
+    ['groupBy', 'bogus'],
+    ['accountsPayablePaid', 'bogus'],
+    ['accountsReceivablePaid', 'bogus'],
+    ['clearedStatus', 'bogus'],
+    ['sourceAccountType', 'bogus'],
+  ] as const)('rejects unsupported Transaction List %s values before fetch', (field, value) => {
+    expect(() =>
+      buildQuickBooksReportUrl({
+        ...authParams,
+        reportType: 'transaction_list',
+        [field]: value,
+      } as QuickBooksRunFinancialReportParams)
+    ).toThrow(`Unsupported QuickBooks ${field}`)
+  })
+
   it('omits blank and default controls', () => {
     const url = buildQuickBooksReportUrl({
       ...authParams,
@@ -191,7 +208,7 @@ describe('QuickBooks financial report request construction', () => {
     ).toThrow(message)
   })
 
-  it('contains exactly the sandbox-verified 15-report support matrix', () => {
+  it('contains exactly the fixed 15-report support matrix', () => {
     expect(Object.keys(QUICKBOOKS_REPORTS)).toEqual(reportEndpoints.map(([type]) => type))
     expect(Object.keys(QUICKBOOKS_REPORTS)).not.toContain('general_ledger')
     expect(quickbooksRunFinancialReportTool.params).toHaveProperty('transactionType')

apps/sim/tools/quickbooks/reports.test.ts

@@ -1543,6 +1543,11 @@ export const QUICKBOOKS_MASTER_DATA_PROPERTIES: Record<string, OutputProperty> =
   ...QUICKBOOKS_VENDOR_PROPERTIES,
   ...QUICKBOOKS_ITEM_PROPERTIES,
   ...QUICKBOOKS_EMPLOYEE_PROPERTIES,
+  PrintOnCheckName: {
+    type: 'string',
+    description: 'Vendor or employee name printed on checks',
+    optional: true,
+  },
   Name: {
     type: 'string',
     description: 'Account, item, class, or department name',

apps/sim/tools/quickbooks/types.ts

@@ -408,19 +408,52 @@ const QUICKBOOKS_TRANSACTION_LIST_VALUES = {
   },
 } as const
 
+function getQuickBooksTransactionListControl(
+  value: unknown,
+  values: Record<string, string>,
+  field: string
+): string | undefined {
+  if (value === undefined || value === 'default') return undefined
+  if (typeof value !== 'string' || !Object.hasOwn(values, value) || !values[value]) {
+    throw new Error(`Unsupported QuickBooks ${field}: ${String(value)}`)
+  }
+  return values[value]
+}
+
 function addQuickBooksTransactionListFilters(
   url: URL,
   params: QuickBooksRunFinancialReportParams
 ): void {
-  const transactionType = params.transactionType === 'default' ? undefined : params.transactionType
-  const groupBy = params.groupBy === 'default' ? undefined : params.groupBy
-  const accountsPayablePaid =
-    params.accountsPayablePaid === 'default' ? undefined : params.accountsPayablePaid
-  const accountsReceivablePaid =
-    params.accountsReceivablePaid === 'default' ? undefined : params.accountsReceivablePaid
-  const clearedStatus = params.clearedStatus === 'default' ? undefined : params.clearedStatus
-  const sourceAccountType =
-    params.sourceAccountType === 'default' ? undefined : params.sourceAccountType
+  const transactionType = getQuickBooksTransactionListControl(
+    params.transactionType,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.transactionType,
+    'transactionType'
+  )
+  const groupBy = getQuickBooksTransactionListControl(
+    params.groupBy,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.groupBy,
+    'groupBy'
+  )
+  const accountsPayablePaid = getQuickBooksTransactionListControl(
+    params.accountsPayablePaid,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.paidStatus,
+    'accountsPayablePaid'
+  )
+  const accountsReceivablePaid = getQuickBooksTransactionListControl(
+    params.accountsReceivablePaid,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.paidStatus,
+    'accountsReceivablePaid'
+  )
+  const clearedStatus = getQuickBooksTransactionListControl(
+    params.clearedStatus,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.clearedStatus,
+    'clearedStatus'
+  )
+  const sourceAccountType = getQuickBooksTransactionListControl(
+    params.sourceAccountType,
+    QUICKBOOKS_TRANSACTION_LIST_VALUES.sourceAccountType,
+    'sourceAccountType'
+  )
   const controls = {
     transaction_type: transactionType,
     group_by: groupBy,
@@ -436,37 +469,13 @@ function addQuickBooksTransactionListFilters(
     return
   }
 
-  if (transactionType) {
-    url.searchParams.set(
-      'transaction_type',
-      QUICKBOOKS_TRANSACTION_LIST_VALUES.transactionType[transactionType]
-    )
-  }
-  if (groupBy) {
-    url.searchParams.set('group_by', QUICKBOOKS_TRANSACTION_LIST_VALUES.groupBy[groupBy])
-  }
-  if (accountsPayablePaid) {
-    url.searchParams.set(
-      'appaid',
-      QUICKBOOKS_TRANSACTION_LIST_VALUES.paidStatus[accountsPayablePaid]
-    )
-  }
-  if (accountsReceivablePaid) {
-    url.searchParams.set(
-      'arpaid',
-      QUICKBOOKS_TRANSACTION_LIST_VALUES.paidStatus[accountsReceivablePaid]
-    )
-  }
-  if (clearedStatus) {
-    url.searchParams.set('cleared', QUICKBOOKS_TRANSACTION_LIST_VALUES.clearedStatus[clearedStatus])
-  }
+  if (transactionType) url.searchParams.set('transaction_type', transactionType)
+  if (groupBy) url.searchParams.set('group_by', groupBy)
+  if (accountsPayablePaid) url.searchParams.set('appaid', accountsPayablePaid)
+  if (accountsReceivablePaid) url.searchParams.set('arpaid', accountsReceivablePaid)
+  if (clearedStatus) url.searchParams.set('cleared', clearedStatus)
   if (controls.docnum) url.searchParams.set('docnum', controls.docnum)
-  if (sourceAccountType) {
-    url.searchParams.set(
-      'source_account_type',
-      QUICKBOOKS_TRANSACTION_LIST_VALUES.sourceAccountType[sourceAccountType]
-    )
-  }
+  if (sourceAccountType) url.searchParams.set('source_account_type', sourceAccountType)
 }
 
 export function buildQuickBooksReportUrl(params: QuickBooksRunFinancialReportParams): URL {