fix(quickbooks): correct API conformance, prevent write data loss, shrink shared-logic surface

Validation of the integration against Intuit's published attribute tables
(static.developer.intuit.com/JSONObjects/*, the payload behind the docs SPA)
surfaced defects that write wrong data to customers' books, plus shared-module
changes broader than this integration needs.

Data integrity:
- update_customer_payment now reads the payment and merges allocations. QuickBooks
  applies payment lines ALL-or-NONE, so sending a subset silently unapplied every
  omitted invoice. Destructive replacement stays reachable via a user-only
  unapplyOmittedInvoices flag. Also validates the merged total, not just the
  caller's allocations.
- create_item required ExpenseAccountRef (required for Service and NonInventory)
  as optional while mandating IncomeAccountRef (not required for NonInventory).
- create_employee required DisplayName, which QuickBooks derives and treats as
  read-only under Payroll, while leaving the real at-least-one GivenName/FamilyName
  rule unchecked. Both tools threw a raw TypeError on their schema-minimal call.
- create_purchase sent PaymentRefNum, absent from the Purchase entity; QuickBooks
  discards unknown fields silently, so check numbers vanished. Now DocNumber.
- A Fault nested in QueryResponse was reported as an empty result set. Detected in
  parseQuickBooksJson so every response path is covered.
- assertQuickBooksSparseUpdate never checked sparse despite its name.
- Bill header-level LinkedTxn omitted the required TxnLineId and duplicated the
  line-level links; DescriptionOnly lines omitted DescriptionLineDetail.
- Line amounts were positive-only, making discounts, returns and credits
  unrepresentable, and bare Number() silently coerced true and [5] onto the wire.
- Phantom report parameters removed; aging method and period split so each report
  only offers the control it accepts.

Safety and boundaries:
- confirmVoid and confirmPosting moved to user-only, so an agent can no longer
  supply its own approval for voids and journal postings.
- Split the runtime-free helpers out of tools/quickbooks/utils.ts. The block was
  the only one in the repo dragging error-extractors, client.ts,
  microsoft_excel/utils and stream-limits into the client bundle.
- Attachment routes: 20 MB cap per Intuit's limit, outbound timeouts, extension
  preserved through filename truncation, Unicode filenames, wider MIME acceptance.
- The two download routes merged into one; extracted storeToolOutputFile.

Shared logic reduced to what this integration needs:
- redaction.ts back to a bypass-set entry for SyncToken; every origin/staging
  assertion retained.
- refreshOAuthToken read the body before the ok check, so a token response over
  64 KiB became a spurious failure for every provider. Provider error text is
  restored to logs, redacted and truncated, and kept out of the caller message.
- maxResponseBytes clamped to the global ceiling.
- generate-docs is deterministic again; its output no longer depends on what is
  already on disk.

The generic redaction engine, the serializer singleton-canonical fix and the
visibility-based docs filter are deferred to their own PRs.

Sparse-update semantics for ten write tools remain unverified against a live
sandbox; apps/sim/scripts/quickbooks-sparse-probe.ts settles it.

Author: waleedlatif1

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

@@ -5,7 +5,7 @@ description: Manage QuickBooks Online company, transactions, reports, emails, PD
 
 import { BlockInfoCard } from "@/components/ui/block-info-card"
 
-<BlockInfoCard
+<BlockInfoCard 
   type="quickbooks"
   color="#2CA01C"
 />
@@ -60,7 +60,10 @@ Get information about the connected QuickBooks Online company
 |   ↳ `CompanyStartDate` | string | Company start date |
 |   ↳ `Country` | string | Company country code |
 |   ↳ `FiscalYearStartMonth` | string | Fiscal year starting month |
-|   ↳ `DefaultTimeZone` | string | Company default time zone |
+|   ↳ `SupportedLanguages` | string | Comma-separated list of languages supported by the company |
+|   ↳ `EmployerId` | string | Employer Identification Number, when defined in company settings |
+|   ↳ `domain` | string | Originating Intuit domain |
+|   ↳ `sparse` | boolean | Whether QuickBooks returned a partial representation |
 |   ↳ `NameValue` | array | QuickBooks company settings represented as name/value entries |
 |   ↳ `MetaData` | json | CompanyInfo creation and update timestamps |
 |     ↳ `CreateTime` | string | Entity creation timestamp |
@@ -309,9 +312,9 @@ Create a non-payroll employee profile in the connected QuickBooks Online company
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `displayName` | string | Yes | Unique employee display name |
-| `givenName` | string | No | Employee given name |
-| `familyName` | string | No | Employee family name |
+| `displayName` | string | No | Unique employee display name. When omitted QuickBooks derives it from the supplied name components, and it is read-only when QuickBooks Payroll is enabled |
+| `givenName` | string | No | Employee given name. At least one of givenName or familyName is required |
+| `familyName` | string | No | Employee family name. At least one of givenName or familyName is required |
 | `primaryEmail` | string | No | Employee primary email address |
 | `primaryPhone` | string | No | Employee primary phone number |
 | `primaryAddress` | json | No | Employee primary address |
@@ -499,12 +502,12 @@ Create a Service or Non-inventory item in QuickBooks Online
 | --------- | ---- | -------- | ----------- |
 | `name` | string | Yes | Unique item name |
 | `itemType` | string | Yes | Writable item type: service or non_inventory |
-| `incomeAccountId` | string | Yes | Income account ID used when the item is sold |
+| `incomeAccountId` | string | No | Sales of Product Income account ID recording proceeds from the sale. Required for Service items, optional for Non-inventory items and for France locales |
 | `description` | string | No | Sales description |
 | `unitPrice` | number | No | Sales price per unit |
 | `purchaseDescription` | string | No | Purchase description |
 | `purchaseCost` | number | No | Purchase cost per unit |
-| `expenseAccountId` | string | No | Expense account ID used when the item is purchased |
+| `expenseAccountId` | string | Yes | Cost of Goods Sold account ID used to pay the vendor for this item. Required for both Service and Non-inventory items, except in France locales where it is optional |
 | `taxable` | boolean | No | Whether the item is taxable |
 | `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 
@@ -764,7 +767,7 @@ Sparse-update an estimate using its current sync token
 | `transactionId` | string | Yes | Estimate ID to update |
 | `syncToken` | string | Yes | Current estimate sync token |
 | `customerId` | string | No | Replacement customer ID |
-| `lines` | json | No | Replacement bounded estimate lines |
+| `lines` | json | No | Complete replacement set of estimate lines: any existing line omitted here is deleted from the estimate |
 | `transactionDate` | string | No | Replacement estimate date in YYYY-MM-DD format |
 | `expirationDate` | string | No | Replacement expiration date in YYYY-MM-DD format |
 | `documentNumber` | string | No | Replacement estimate number |
@@ -879,7 +882,7 @@ Sparse-update an invoice using its current sync token
 | `transactionId` | string | Yes | Invoice ID to update |
 | `syncToken` | string | Yes | Current invoice sync token |
 | `customerId` | string | No | Replacement customer ID |
-| `lines` | json | No | Replacement bounded invoice lines |
+| `lines` | json | No | Complete replacement set of invoice lines: any existing line omitted here is deleted from the invoice |
 | `transactionDate` | string | No | Replacement invoice date in YYYY-MM-DD format |
 | `dueDate` | string | No | Replacement due date in YYYY-MM-DD format |
 | `documentNumber` | string | No | Replacement invoice number |
@@ -1049,7 +1052,7 @@ Sparse-update a sales receipt using its current sync token
 | `transactionId` | string | Yes | Sales receipt ID to update |
 | `syncToken` | string | Yes | Current sales receipt sync token |
 | `customerId` | string | No | Replacement customer ID |
-| `lines` | json | No | Replacement bounded sales receipt lines |
+| `lines` | json | No | Complete replacement set of sales receipt lines: any existing line omitted here is deleted from the sales receipt |
 | `transactionDate` | string | No | Replacement receipt date in YYYY-MM-DD format |
 | `documentNumber` | string | No | Replacement sales receipt number |
 | `privateNote` | string | No | Replacement internal note |
@@ -1173,7 +1176,8 @@ Sparse-update a customer payment using its current sync token
 | `paymentReferenceNumber` | string | No | Replacement payment reference number |
 | `paymentMethodId` | string | No | Replacement payment method ID |
 | `depositAccountId` | string | No | Replacement deposit account ID |
-| `invoiceAllocations` | json | No | Replacement bounded invoice allocations |
+| `invoiceAllocations` | json | No | Bounded invoice allocations to apply. Each entry sets the amount applied to that invoice; invoices already applied on the payment and not listed here keep their current amounts |
+| `unapplyOmittedInvoices` | boolean | No | Replace the payment allocations outright. Every invoice not listed in invoiceAllocations is UNAPPLIED and returns to open |
 
 #### Output
 
@@ -1335,7 +1339,7 @@ Sparse-update a credit memo using its current sync token
 | `transactionId` | string | Yes | Credit memo ID to update |
 | `syncToken` | string | Yes | Current credit memo sync token |
 | `customerId` | string | No | Replacement customer ID |
-| `lines` | json | No | Replacement bounded credit memo lines |
+| `lines` | json | No | Complete replacement set of credit memo lines: any existing line omitted here is deleted from the credit memo |
 | `transactionDate` | string | No | Replacement credit memo date in YYYY-MM-DD format |
 | `documentNumber` | string | No | Replacement credit memo number |
 | `privateNote` | string | No | Replacement internal note |
@@ -1451,7 +1455,7 @@ Sparse-update a refund receipt using its current sync token
 | `transactionId` | string | Yes | Refund receipt ID to update |
 | `syncToken` | string | Yes | Current refund receipt sync token |
 | `customerId` | string | No | Replacement customer ID |
-| `lines` | json | No | Replacement bounded refund lines |
+| `lines` | json | No | Complete replacement set of refund receipt lines: any existing line omitted here is deleted from the refund receipt |
 | `transactionDate` | string | No | Replacement refund date in YYYY-MM-DD format |
 | `documentNumber` | string | No | Replacement refund receipt number |
 | `privateNote` | string | No | Replacement internal note |
@@ -2234,7 +2238,7 @@ Record a cash, check, or credit-card purchase with bounded expense lines
 | `lines` | json | Yes | Bounded account-based or item-based expense lines |
 | `vendorId` | string | No | Optional vendor payee ID |
 | `transactionDate` | string | No | Purchase date in YYYY-MM-DD format |
-| `paymentReference` | string | No | Optional payment reference number |
+| `paymentReference` | string | No | Optional transaction reference number, such as a check number, sent as the purchase DocNumber |
 | `privateNote` | string | No | Internal purchase note |
 | `requestId` | string | No | Optional Intuit idempotency request ID, up to 50 characters |
 
@@ -2308,7 +2312,7 @@ Sparse-update purchase header fields without changing lines or payment accounts
 | `currentPaymentType` | string | Yes | Current purchase payment type, re-sent unchanged because QuickBooks requires it for sparse updates |
 | `vendorId` | string | No | Replacement vendor payee ID |
 | `transactionDate` | string | No | Replacement purchase date in YYYY-MM-DD format |
-| `paymentReference` | string | No | Replacement payment reference number |
+| `paymentReference` | string | No | Replacement transaction reference number, such as a check number, sent as the purchase DocNumber |
 | `privateNote` | string | No | Replacement internal note |
 
 #### Output
@@ -2913,3 +2917,5 @@ Download a QuickBooks file attachment through its short-lived URL
 | `mimeType` | string | Downloaded file MIME type |
 | `size` | number | Downloaded file size in bytes |
 | `attachmentId` | string | Downloaded QuickBooks attachment ID |
+
+

apps/sim/app/api/tools/quickbooks/add-attachment/route.ts

@@ -9,14 +9,18 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { processFilesToUserFiles } from '@/lib/uploads/utils/file-utils'
 import { downloadServableFileFromStorage } from '@/lib/uploads/utils/file-utils.server'
 import { docNotReadyResponse } from '@/lib/uploads/utils/servable-file-response'
-import { MAX_FILE_SIZE } from '@/lib/uploads/utils/validation'
 import { assertToolFileAccess } from '@/app/api/files/authorization'
 import { buildQuickBooksCompanyUrl, buildQuickBooksHeaders } from '@/tools/quickbooks/client'
 import {
+  assertQuickBooksAttachmentExtension,
   assertSingleQuickBooksFile,
   buildQuickBooksAttachableMetadata,
   getQuickBooksDocumentError,
   parseQuickBooksAttachableResponse,
+  QUICKBOOKS_DOCUMENT_METADATA_TIMEOUT_MS,
+  QUICKBOOKS_DOCUMENT_TRANSFER_TIMEOUT_MS,
+  QUICKBOOKS_MAX_ATTACHMENT_BYTES,
+  quickBooksDocumentSignal,
   sanitizeQuickBooksFileName,
   validateQuickBooksAttachmentFileType,
 } from '@/tools/quickbooks/documents_utils'
@@ -67,21 +71,27 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           'Content-Type': 'application/json',
         },
         body: JSON.stringify(metadata),
-        signal: request.signal,
+        signal: quickBooksDocumentSignal(request.signal, QUICKBOOKS_DOCUMENT_METADATA_TIMEOUT_MS),
       })
     } else {
       request.signal.throwIfAborted()
       const rawFile = assertSingleQuickBooksFile(data.file ?? undefined)
       const files = processFilesToUserFiles([rawFile], requestId, logger)
       if (files.length !== 1) throw new Error('Exactly one valid file is required')
       const file = files[0]
-      assertKnownSizeWithinLimit(file.size, MAX_FILE_SIZE, 'QuickBooks attachment file')
+      assertKnownSizeWithinLimit(
+        file.size,
+        QUICKBOOKS_MAX_ATTACHMENT_BYTES,
+        'QuickBooks attachment file'
+      )
+      const resolvedName = sanitizeQuickBooksFileName(data.fileName ?? undefined, file.name)
+      assertQuickBooksAttachmentExtension(resolvedName)
       const denied = await assertToolFileAccess(file.key, authResult.userId, requestId, logger)
       if (denied) return denied
       let downloaded: Awaited<ReturnType<typeof downloadServableFileFromStorage>>
       try {
         downloaded = await downloadServableFileFromStorage(file, requestId, logger, {
-          maxBytes: MAX_FILE_SIZE,
+          maxBytes: QUICKBOOKS_MAX_ATTACHMENT_BYTES,
           signal: request.signal,
         })
       } catch (error) {
@@ -92,12 +102,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       request.signal.throwIfAborted()
       assertKnownSizeWithinLimit(
         downloaded.buffer.length,
-        MAX_FILE_SIZE,
+        QUICKBOOKS_MAX_ATTACHMENT_BYTES,
         'QuickBooks attachment file'
       )
       if (downloaded.buffer.length === 0)
         throw new Error('QuickBooks attachment file cannot be empty')
-      const resolvedName = sanitizeQuickBooksFileName(data.fileName ?? undefined, file.name)
       const storedMime = (downloaded.contentType || file.type || '')
         .split(';', 1)[0]
         .trim()
@@ -137,7 +146,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         method: 'POST',
         headers: buildQuickBooksHeaders(data.accessToken),
         body: formData,
-        signal: request.signal,
+        signal: quickBooksDocumentSignal(request.signal, QUICKBOOKS_DOCUMENT_TRANSFER_TIMEOUT_MS),
       })
     }