fix(quickbooks): address final integration review

Author: Bill Leoutsakos

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

@@ -188,8 +188,8 @@ List or read one account, customer, vendor, item, or employee
 |   ↳ `InvStartDate` | string | Inventory tracking start date |
 |   ↳ `PrimaryAddr` | json | Employee primary address |
 |   ↳ `BillableTime` | boolean | Whether employee time is billable |
-| `startPosition` | number | One-based position of the first record in this page |
-| `maxResults` | number | Actual number of records returned in this page |
+| `startPosition` | number | One-based position of the first item in this response |
+| `maxResults` | number | Actual number of items reported for this response |
 | `nextStartPosition` | number | Position to use when explicitly requesting the next page |
 | `hasMore` | boolean | Conservative indication that another page may exist |
 | `time` | string | QuickBooks response timestamp |
@@ -211,6 +211,7 @@ Create a customer in the connected QuickBooks Online company
 | `billingAddress` | json | No | Customer billing address |
 | `shippingAddress` | json | No | Customer shipping address |
 | `taxable` | boolean | No | Whether sales to this customer are taxable |
+| `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 
 #### Output
 
@@ -307,6 +308,7 @@ Create a vendor in the connected QuickBooks Online company
 | `printOnCheckName` | string | No | Name to print on checks |
 | `accountNumber` | string | No | Vendor account number |
 | `vendor1099` | boolean | No | Whether the vendor is tracked for 1099 reporting |
+| `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 
 #### Output
 
@@ -405,6 +407,7 @@ Create a Service or Non-inventory item in QuickBooks Online
 | `purchaseCost` | number | No | Purchase cost per unit |
 | `expenseAccountId` | string | No | Expense account ID used when the item is purchased |
 | `taxable` | boolean | No | Whether the item is taxable |
+| `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 
 #### Output
 
@@ -446,14 +449,15 @@ Create a Service or Non-inventory item in QuickBooks Online
 
 ### `quickbooks_update_item`
 
-Sparse-update supported fields on an item without changing its type
+Sparse-update a Service or Non-inventory item in QuickBooks Online
 
 #### Input
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `itemId` | string | Yes | ID of the item to update |
 | `syncToken` | string | Yes | Current item sync token |
+| `itemType` | string | Yes | Current item type: service or non_inventory |
 | `name` | string | No | Replacement item name |
 | `incomeAccountId` | string | No | Replacement income account ID |
 | `description` | string | No | Replacement sales description |
@@ -590,7 +594,6 @@ List or read one estimate, invoice, sales receipt, payment, credit memo, or refu
 |   ↳ `MetaData` | json | Transaction creation and update timestamps |
 |     ↳ `CreateTime` | string | Entity creation timestamp |
 |     ↳ `LastUpdatedTime` | string | Entity last-updated timestamp |
-
 ### `quickbooks_create_estimate`
 
 Create an estimate with bounded item and description lines

apps/sim/blocks/blocks/quickbooks.ts

@@ -14,6 +14,11 @@ const SALES_READ_OPERATION = 'quickbooks_read_sales_transactions'
 const CUSTOMER_OPERATIONS = ['quickbooks_create_customer', 'quickbooks_update_customer'] as const
 const VENDOR_OPERATIONS = ['quickbooks_create_vendor', 'quickbooks_update_vendor'] as const
 const ITEM_OPERATIONS = ['quickbooks_create_item', 'quickbooks_update_item'] as const
+const MASTER_DATA_CREATE_OPERATIONS = [
+  'quickbooks_create_customer',
+  'quickbooks_create_item',
+  'quickbooks_create_vendor',
+] as const
 const SALES_DOCUMENT_CREATE_OPERATIONS = [
   'quickbooks_create_estimate',
   'quickbooks_create_invoice',
@@ -40,6 +45,7 @@ const SALES_CREATE_OPERATIONS = [
   ...SALES_DOCUMENT_CREATE_OPERATIONS,
   'quickbooks_create_customer_payment',
 ] as const
+const CREATE_OPERATIONS = [...MASTER_DATA_CREATE_OPERATIONS, ...SALES_CREATE_OPERATIONS] as const
 const SALES_UPDATE_OPERATIONS = [
   ...SALES_DOCUMENT_UPDATE_OPERATIONS,
   'quickbooks_update_customer_payment',
@@ -705,7 +711,7 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
       title: 'Request ID',
       type: 'short-input',
       placeholder: 'Optional idempotency key (max 50 characters)',
-      condition: { field: 'operation', value: [...SALES_CREATE_OPERATIONS] },
+      condition: { field: 'operation', value: [...CREATE_OPERATIONS] },
       mode: 'advanced',
     },
     {
@@ -871,6 +877,7 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
           operation === 'quickbooks_create_customer' ||
           operation === 'quickbooks_update_customer'
         ) {
+          const isCreate = operation === 'quickbooks_create_customer'
           return {
             credential: oauthCredentialValue,
             customerId: optionalValue(params.customerId),
@@ -885,9 +892,11 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
             shippingAddress: parseQuickBooksAddress(params.shippingAddress, 'shippingAddress'),
             taxable: parseTriStateBoolean(params.taxable, 'taxable'),
             activeStatus: params.activeStatus ?? 'unchanged',
+            requestId: isCreate ? optionalValue(params.requestId) : undefined,
           }
         }
         if (operation === 'quickbooks_create_vendor' || operation === 'quickbooks_update_vendor') {
+          const isCreate = operation === 'quickbooks_create_vendor'
           return {
             credential: oauthCredentialValue,
             vendorId: optionalValue(params.vendorId),
@@ -903,9 +912,11 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
             accountNumber: optionalValue(params.accountNumber),
             vendor1099: parseTriStateBoolean(params.vendor1099, 'vendor1099'),
             activeStatus: params.activeStatus ?? 'unchanged',
+            requestId: isCreate ? optionalValue(params.requestId) : undefined,
           }
         }
         if (operation === 'quickbooks_create_item' || operation === 'quickbooks_update_item') {
+          const isCreate = operation === 'quickbooks_create_item'
           return {
             credential: oauthCredentialValue,
             itemId: optionalValue(params.itemId),
@@ -921,6 +932,7 @@ export const QuickBooksBlock: BlockConfig<QuickBooksResponse> = {
             expenseAccountId: optionalValue(params.expenseAccountId),
             taxable: parseTriStateBoolean(params.taxable, 'taxable'),
             activeStatus: params.activeStatus ?? 'unchanged',
+            requestId: isCreate ? optionalValue(params.requestId) : undefined,
           }
         }
         return { credential: oauthCredentialValue }

apps/sim/tools/quickbooks/client.ts

@@ -77,6 +77,17 @@ export interface QuickBooksCompanyInfoEnvelope {
   time?: string
 }
 
+export function assertQuickBooksCompanyInfo<T extends { Id?: unknown }>(candidate: unknown): T {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error('QuickBooks CompanyInfo response is missing a valid CompanyInfo object')
+  }
+  const id = (candidate as { Id?: unknown }).Id
+  if (typeof id !== 'string' || !id.trim()) {
+    throw new Error('QuickBooks CompanyInfo response is missing a valid company Id')
+  }
+  return candidate as T
+}
+
 function getQuickBooksTrackingId(headers: Headers): string | null {
   return (
     headers.get('intuit_tid') ?? headers.get('intuit-tid') ?? headers.get('x-request-id') ?? null
@@ -167,9 +178,7 @@ export async function fetchValidatedQuickBooksCompanyInfo(
     )
   }
 
-  if (!data.CompanyInfo || typeof data.CompanyInfo !== 'object') {
-    throw new Error('QuickBooks company validation response is missing CompanyInfo')
-  }
+  assertQuickBooksCompanyInfo(data.CompanyInfo)
 
   return data
 }

apps/sim/tools/quickbooks/create_customer.ts

@@ -11,6 +11,7 @@ import {
   QUICKBOOKS_MUTATION_OUTPUTS,
 } from '@/tools/quickbooks/types'
 import {
+  addQuickBooksRequestId,
   buildQuickBooksEntityUrl,
   getQuickBooksToolHeaders,
   optionalQuickBooksString,
@@ -97,6 +98,12 @@ export const quickbooksCreateCustomerTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Whether sales to this customer are taxable',
     },
+    requestId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional Intuit idempotency request ID, up to 50 characters',
+    },
   },
   oauth: {
     required: true,
@@ -105,7 +112,11 @@ export const quickbooksCreateCustomerTool: ToolConfig<
   },
   errorExtractor: ErrorExtractorId.QUICKBOOKS_FAULT,
   request: {
-    url: (params) => buildQuickBooksEntityUrl(params.realmId, 'customer').toString(),
+    url: (params) =>
+      addQuickBooksRequestId(
+        buildQuickBooksEntityUrl(params.realmId, 'customer'),
+        params.requestId
+      ).toString(),
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) =>

apps/sim/tools/quickbooks/create_item.ts

@@ -8,6 +8,7 @@ import type {
 } from '@/tools/quickbooks/types'
 import { QUICKBOOKS_ITEM_PROPERTIES, QUICKBOOKS_MUTATION_OUTPUTS } from '@/tools/quickbooks/types'
 import {
+  addQuickBooksRequestId,
   buildQuickBooksEntityUrl,
   getQuickBooksToolHeaders,
   optionalQuickBooksString,
@@ -94,6 +95,12 @@ export const quickbooksCreateItemTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Whether the item is taxable',
     },
+    requestId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional Intuit idempotency request ID, up to 50 characters',
+    },
   },
   oauth: {
     required: true,
@@ -102,7 +109,11 @@ export const quickbooksCreateItemTool: ToolConfig<
   },
   errorExtractor: ErrorExtractorId.QUICKBOOKS_FAULT,
   request: {
-    url: (params) => buildQuickBooksEntityUrl(params.realmId, 'item').toString(),
+    url: (params) =>
+      addQuickBooksRequestId(
+        buildQuickBooksEntityUrl(params.realmId, 'item'),
+        params.requestId
+      ).toString(),
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) => {

apps/sim/tools/quickbooks/create_vendor.ts

@@ -8,6 +8,7 @@ import type {
 } from '@/tools/quickbooks/types'
 import { QUICKBOOKS_MUTATION_OUTPUTS, QUICKBOOKS_VENDOR_PROPERTIES } from '@/tools/quickbooks/types'
 import {
+  addQuickBooksRequestId,
   buildQuickBooksEntityUrl,
   getQuickBooksToolHeaders,
   optionalQuickBooksString,
@@ -100,6 +101,12 @@ export const quickbooksCreateVendorTool: ToolConfig<
       visibility: 'user-or-llm',
       description: 'Whether the vendor is tracked for 1099 reporting',
     },
+    requestId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional Intuit idempotency request ID, up to 50 characters',
+    },
   },
   oauth: {
     required: true,
@@ -108,7 +115,11 @@ export const quickbooksCreateVendorTool: ToolConfig<
   },
   errorExtractor: ErrorExtractorId.QUICKBOOKS_FAULT,
   request: {
-    url: (params) => buildQuickBooksEntityUrl(params.realmId, 'vendor').toString(),
+    url: (params) =>
+      addQuickBooksRequestId(
+        buildQuickBooksEntityUrl(params.realmId, 'vendor'),
+        params.requestId
+      ).toString(),
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) =>

apps/sim/tools/quickbooks/get_company_info.ts

@@ -1,5 +1,6 @@
 import { ErrorExtractorId } from '@/tools/error-extractors'
 import {
+  assertQuickBooksCompanyInfo,
   buildQuickBooksCompanyUrl,
   normalizeQuickBooksRealmId,
   QUICKBOOKS_MAX_RESPONSE_BYTES,
@@ -65,13 +66,11 @@ export const quickbooksGetCompanyInfoTool: ToolConfig<
       response,
       'QuickBooks CompanyInfo response'
     )
-    if (!data.CompanyInfo || typeof data.CompanyInfo !== 'object') {
-      throw new Error('QuickBooks CompanyInfo response is missing CompanyInfo')
-    }
+    const company = assertQuickBooksCompanyInfo<QuickBooksCompanyInfo>(data.CompanyInfo)
     return {
       success: true,
       output: {
-        company: data.CompanyInfo,
+        company,
         time: typeof data.time === 'string' ? data.time : null,
       },
     }