fix(quickbooks): address independent sales review

Author: Bill Leoutsakos

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

@@ -10,6 +10,19 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
   color="#2CA01C"
 />
 
+{/* MANUAL-CONTENT-START:intro */}
+Connect one QuickBooks Online company per credential. During OAuth, choose the company that the workflow should access; Sim binds that company to the credential automatically, so you do not enter a realm ID or API host.
+
+Master Data and Sales transaction reads support **List** and **By ID** modes. List actions return at most one page. Use `nextStartPosition` in another workflow step when `hasMore` is true. Sim does not paginate, retry, or fetch related records automatically.
+
+QuickBooks updates are sparse: provide the record ID, its current `SyncToken`, and only the fields you want to change. Use the latest `SyncToken` returned by a read or mutation. Voiding keeps the transaction in QuickBooks with a zeroed financial effect; it is not deletion and requires explicit confirmation. Create actions accept an optional `requestId` that QuickBooks uses for idempotency when the same request may be submitted again.
+
+Sandbox credentials call only Intuit's sandbox API and are suitable for disposable test data. Production credentials call the production API and affect the selected live company.
+
+Reports and attachments are not exposed by this version of the block, so report date-range and attachment-size controls do not apply here.
+{/* MANUAL-CONTENT-END */}
+
+
 ## Usage Instructions
 
 Connect one QuickBooks Online company to manage master data and bounded sales and receivables workflows, while preserving existing purchase-order and bill reads.

apps/sim/blocks/blocks/quickbooks.ts

@@ -1,6 +1,6 @@
 import { QuickBooksIcon } from '@/components/icons'
 import { getScopesForService } from '@/lib/oauth/utils'
-import type { BlockConfig, BlockMeta } from '@/blocks/types'
+import type { BlockConfig, BlockMeta, OutputCondition } from '@/blocks/types'
 import { AuthMode, IntegrationType } from '@/blocks/types'
 import {
   parseQuickBooksInvoiceAllocations,
@@ -69,16 +69,16 @@ const MUTATION_OPERATIONS = [
   ...VENDOR_OPERATIONS,
   ...SALES_MUTATION_OPERATIONS,
 ] as const
-const PAGINATED_OPERATIONS = [
-  MASTER_DATA_OPERATION,
-  SALES_READ_OPERATION,
-  'quickbooks_list_purchase_orders',
-  'quickbooks_list_bills',
-] as const
 const TRANSACTION_LIST_OPERATIONS = [
   'quickbooks_list_purchase_orders',
   'quickbooks_list_bills',
 ] as const
+const LIST_OUTPUT_CONDITION: OutputCondition = {
+  field: 'operation',
+  value: [MASTER_DATA_OPERATION, SALES_READ_OPERATION],
+  and: { field: 'readMode', value: 'list' },
+  or: { field: 'operation', value: [...TRANSACTION_LIST_OPERATIONS] },
+}
 const QUICKBOOKS_OPERATIONS = [
   'quickbooks_get_company_info',
   MASTER_DATA_OPERATION,
@@ -1027,27 +1027,27 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       type: 'array',
       description:
         'Master-data, sales transaction, PurchaseOrder, or Bill objects with native QuickBooks fields',
-      condition: { field: 'operation', value: [...PAGINATED_OPERATIONS] },
+      condition: LIST_OUTPUT_CONDITION,
     },
     startPosition: {
       type: 'number',
       description: 'One-based position of the first returned list item',
-      condition: { field: 'operation', value: [...PAGINATED_OPERATIONS] },
+      condition: LIST_OUTPUT_CONDITION,
     },
     maxResults: {
       type: 'number',
       description: 'Actual number of items reported for the list response',
-      condition: { field: 'operation', value: [...PAGINATED_OPERATIONS] },
+      condition: LIST_OUTPUT_CONDITION,
     },
     nextStartPosition: {
       type: 'number',
       description: 'Position to pass into an explicit next-page request',
-      condition: { field: 'operation', value: [...PAGINATED_OPERATIONS] },
+      condition: LIST_OUTPUT_CONDITION,
     },
     hasMore: {
       type: 'boolean',
       description: 'Conservative indication that another list page may exist',
-      condition: { field: 'operation', value: [...PAGINATED_OPERATIONS] },
+      condition: LIST_OUTPUT_CONDITION,
     },
     record: {
       type: 'json',

apps/sim/lib/workflows/blocks/block-outputs.ts

@@ -52,7 +52,7 @@ function isConditionPrimitive(value: unknown): value is ConditionValue {
  * Evaluates an output condition against subBlock values.
  * Returns true if the condition is met and the output should be shown.
  */
-function evaluateOutputCondition(
+export function evaluateOutputCondition(
   condition: OutputCondition,
   subBlocks: Record<string, SubBlockWithValue> | undefined
 ): boolean {
@@ -93,6 +93,10 @@ function evaluateOutputCondition(
     matches = matches && andMatches
   }
 
+  if (condition.or) {
+    matches = matches || evaluateOutputCondition(condition.or, subBlocks)
+  }
+
   return matches
 }
 

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

@@ -1,5 +1,6 @@
 import { resetEnvMock, setEnv } from '@sim/testing'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { evaluateOutputCondition } from '@/lib/workflows/blocks/block-outputs'
 import { evaluateSubBlockCondition } from '@/lib/workflows/subblocks/visibility'
 import { QuickBooksBlock } from '@/blocks/blocks/quickbooks'
 import {
@@ -865,13 +866,32 @@ describe('QuickBooks tool and block boundaries', () => {
     ).toBe(true)
     expect(QuickBooksBlock.outputs.items.condition).toEqual({
       field: 'operation',
-      value: [
-        'quickbooks_read_master_data',
-        'quickbooks_read_sales_transactions',
-        'quickbooks_list_purchase_orders',
-        'quickbooks_list_bills',
-      ],
+      value: ['quickbooks_read_master_data', 'quickbooks_read_sales_transactions'],
+      and: { field: 'readMode', value: 'list' },
+      or: {
+        field: 'operation',
+        value: ['quickbooks_list_purchase_orders', 'quickbooks_list_bills'],
+      },
     })
+    const listOutputCondition = QuickBooksBlock.outputs.items.condition!
+    expect(
+      evaluateOutputCondition(listOutputCondition, {
+        operation: { value: 'quickbooks_read_sales_transactions' },
+        readMode: { value: 'by_id' },
+      })
+    ).toBe(false)
+    expect(
+      evaluateOutputCondition(listOutputCondition, {
+        operation: { value: 'quickbooks_read_sales_transactions' },
+        readMode: { value: 'list' },
+      })
+    ).toBe(true)
+    expect(
+      evaluateOutputCondition(listOutputCondition, {
+        operation: { value: 'quickbooks_list_bills' },
+        readMode: { value: 'by_id' },
+      })
+    ).toBe(true)
     expect(subBlocks.syncToken.condition).toEqual({
       field: 'operation',
       value: [

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

@@ -129,6 +129,23 @@ describe('QuickBooks sales reader', () => {
     })
   })
 
+  it('rejects malformed records without usable QuickBooks IDs', async () => {
+    await expect(
+      quickbooksReadSalesTransactionsTool.transformResponse!(
+        Response.json({ QueryResponse: { Invoice: [null] } }),
+        listParams
+      )
+    ).rejects.toThrow('malformed Invoice record')
+
+    await expect(
+      quickbooksReadSalesTransactionsTool.transformResponse!(Response.json({ Invoice: {} }), {
+        ...listParams,
+        readMode: 'by_id',
+        transactionId: '12',
+      })
+    ).rejects.toThrow('without an Id')
+  })
+
   it('rejects unknown types, modes, and missing by-ID values before a request', () => {
     const requestUrl = quickbooksReadSalesTransactionsTool.request.url as (
       params: QuickBooksReadSalesTransactionsParams
@@ -328,6 +345,17 @@ describe('QuickBooks customer payments and voids', () => {
         invoiceAllocations: [{ invoiceId: '12', amount: 101 }],
       })
     ).toThrow('cannot exceed')
+
+    expect(
+      buildQuickBooksCreatePaymentBody({
+        ...params,
+        totalAmount: 0.06,
+        invoiceAllocations: [
+          { invoiceId: '12', amount: 0.01 },
+          { invoiceId: '13', amount: 0.05 },
+        ],
+      })
+    ).toMatchObject({ TotalAmt: 0.06 })
   })
 
   it('builds sparse payment updates and rejects allocations without a replacement total', () => {
@@ -353,6 +381,19 @@ describe('QuickBooks customer payments and voids', () => {
         invoiceAllocations: [{ invoiceId: '12', amount: 25 }],
       })
     ).toThrow('totalAmount is required')
+
+    expect(
+      buildQuickBooksUpdatePaymentBody({
+        ...authParams,
+        paymentId: '15',
+        syncToken: '2',
+        totalAmount: 0.06,
+        invoiceAllocations: [
+          { invoiceId: '12', amount: 0.01 },
+          { invoiceId: '13', amount: 0.05 },
+        ],
+      })
+    ).toMatchObject({ TotalAmt: 0.06 })
   })
 
   it('uses the verified payment endpoints', () => {

apps/sim/tools/quickbooks/sales_utils.ts

@@ -1,4 +1,5 @@
 import { filterUndefined } from '@sim/utils/object'
+import Decimal from 'decimal.js'
 import type {
   QuickBooksCreateCustomerPaymentParams,
   QuickBooksCreateSalesDocumentParams,
@@ -190,8 +191,11 @@ function buildPaymentLines(
   if (totalAmount === undefined) {
     throw new Error('totalAmount is required when invoice allocations are supplied')
   }
-  const allocationTotal = allocations.reduce((sum, allocation) => sum + allocation.amount, 0)
-  if (allocationTotal > totalAmount) {
+  const allocationTotal = allocations.reduce(
+    (sum, allocation) => sum.plus(allocation.amount),
+    new Decimal(0)
+  )
+  if (allocationTotal.greaterThan(totalAmount)) {
     throw new Error('Invoice allocation amounts cannot exceed totalAmount')
   }
   return allocations.map((allocation) => ({

apps/sim/tools/quickbooks/utils.ts

@@ -43,6 +43,17 @@ interface QuickBooksQueryResponse<T> {
   time?: string
 }
 
+function assertQuickBooksEntity<T>(candidate: unknown, entity: QuickBooksQueryEntity): T {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error(`QuickBooks ${entity} response contains a malformed ${entity} record`)
+  }
+  const recordId = (candidate as { Id?: unknown }).Id
+  if (typeof recordId !== 'string' || !recordId.trim()) {
+    throw new Error(`QuickBooks ${entity} response contains a record without an Id`)
+  }
+  return candidate as T
+}
+
 export const QUICKBOOKS_MASTER_DATA_ENTITIES = {
   account: { entity: 'Account', resource: 'account' },
   customer: { entity: 'Customer', resource: 'customer' },
@@ -172,7 +183,7 @@ export async function transformQuickBooksListResponse<T>(
     throw new Error(`QuickBooks ${entity} response contains a malformed entity list`)
   }
 
-  const items = (candidate ?? []) as T[]
+  const items = (candidate ?? []).map((item) => assertQuickBooksEntity<T>(item, entity))
   const startPosition = Number.isInteger(queryResponse.startPosition)
     ? (queryResponse.startPosition as number)
     : params.startPosition
@@ -201,11 +212,11 @@ export async function transformQuickBooksEntityResponse<
     `QuickBooks ${entity} response`
   )
   const candidate = data[entity]
-  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+  if (!candidate) {
     throw new Error(`QuickBooks ${entity} response is missing ${entity}`)
   }
   return {
-    item: candidate as T,
+    item: assertQuickBooksEntity<T>(candidate, entity),
     time: typeof data.time === 'string' ? data.time : null,
   }
 }

packages/workflow-types/src/blocks.ts

@@ -71,6 +71,7 @@ export interface OutputCondition {
       | null
     not?: boolean
   }
+  or?: OutputCondition
 }
 
 export type OutputFieldDefinition =