fix(quickbooks): align reports and attachments with Intuit's report catalog

Every capability flag is now transcribed from that report's own `*query` model
in Intuit's machine-readable report catalog, which is the source the developer
docs render their parameter tables from.

Reports:
- ap_aging_detail now advertises accountingMethod; `agedpayabledetailquery`
  documents `accounting_method`, so Sim was throwing on a request Intuit accepts.
- ap_aging_summary now accepts customerId; `agedpayablesquery` documents `customer`.
- Adds trial_balance_fr. Intuit documents one report with two endpoints —
  TrialBalanceFR for FR-locale companies, TrialBalance otherwise.
- Adds the ten remaining documented report endpoints: AccountList,
  CustomerBalanceDetail, CustomerIncome, GeneralLedger, InventoryValuationDetail,
  InventoryValuationSummary, ClassSales, DepartmentSales, TaxSummary,
  VendorBalanceDetail. Each one's flags come from its own query model.
- Exposes `date_macro` and `qzurl`, both documented per-report query params.
  `qzurl` is what populates the quick-zoom `href` links the row outputs already
  declare, and `date_macro` is mutually exclusive with an explicit date range.
- Exposes the `employee` filter that only `profitandlossdetailquery` documents,
  and adds the `Employee` report-header echo Intuit's `reportheader` model lists.

Attachments:
- parseQuickBooksAttachableResponse takes an operation label. Reading an
  attachment by id reported failures as "attachment upload failed".
- A dotless file name no longer reports itself as its own extension, so an
  unattachable `backup` is refused as extensionless rather than as "the backup
  file type".
- Records why `.jpg` is canonicalized to image/jpeg: QuickBooks normalizes
  content type on ingest and `attachablerequest` has no ContentType property.

Replaces the file_operations tool-wiring tests, which asserted only that
`operation.input` is an identity projection, with coverage of the extension
allowlist, MIME canonicalization, file-name sanitization, Attachable metadata,
and fault labelling.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RB5M2gk7zZgGomnQqr7WRB

Author: waleedlatif1

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

@@ -0,0 +1,166 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { quickbooksAddAttachmentTool } from '@/tools/quickbooks/add_attachment'
+import {
+  assertQuickBooksAttachmentExtension,
+  buildQuickBooksAttachableMetadata,
+  parseQuickBooksAttachableResponse,
+  sanitizeQuickBooksFileName,
+  validateQuickBooksAttachmentFileType,
+} from '@/tools/quickbooks/documents_utils'
+import { quickbooksDownloadAttachmentTool } from '@/tools/quickbooks/download_attachment'
+import { quickbooksDownloadTransactionPdfTool } from '@/tools/quickbooks/download_transaction_pdf'
+import { quickbooksReadAttachmentsTool } from '@/tools/quickbooks/read_attachments'
+
+function attachableFaultResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      AttachableResponse: [
+        {
+          Fault: {
+            Error: [{ code: '610', Message: 'Object Not Found', Detail: 'Attachable id 99' }],
+            type: 'ValidationFault',
+          },
+        },
+      ],
+    }),
+    { headers: { 'content-type': 'application/json' } }
+  )
+}
+
+describe('QuickBooks file tool wiring', () => {
+  it('materializes only provider input for attachment creation', () => {
+    const input = quickbooksAddAttachmentTool.operation.input({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      attachmentKind: 'note',
+      targetType: 'invoice',
+      targetId: 'invoice-1',
+      note: 'Follow up',
+    })
+
+    expect(quickbooksAddAttachmentTool.request).toBeUndefined()
+    expect(input).toEqual({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      attachmentKind: 'note',
+      targetType: 'invoice',
+      targetId: 'invoice-1',
+      file: undefined,
+      fileName: undefined,
+      contentType: undefined,
+      description: undefined,
+      note: 'Follow up',
+    })
+  })
+
+  it('does not accept execution scope from attachment download parameters', () => {
+    const input = quickbooksDownloadAttachmentTool.operation.input({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      attachmentId: 'attachment-1',
+      fileName: 'receipt.pdf',
+    })
+
+    expect(quickbooksDownloadAttachmentTool.request).toBeUndefined()
+    expect(input).toEqual({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      attachmentId: 'attachment-1',
+      fileName: 'receipt.pdf',
+    })
+  })
+
+  it('materializes only provider input for PDF downloads', () => {
+    const input = quickbooksDownloadTransactionPdfTool.operation.input({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      transactionType: 'invoice',
+      transactionId: 'invoice-1',
+      fileName: 'invoice.pdf',
+    })
+
+    expect(quickbooksDownloadTransactionPdfTool.request).toBeUndefined()
+    expect(input).toEqual({
+      accessToken: 'token',
+      realmId: '123',
+      quickBooksEnvironment: 'sandbox',
+      transactionType: 'invoice',
+      transactionId: 'invoice-1',
+      fileName: 'invoice.pdf',
+    })
+  })
+})
+
+describe('QuickBooks attachment file guards', () => {
+  it('refuses an unsupported extension from the file name alone', () => {
+    expect(() => assertQuickBooksAttachmentExtension('backup.zip')).toThrow(
+      'QuickBooks does not support the zip file type'
+    )
+    expect(() => assertQuickBooksAttachmentExtension('backup')).toThrow(
+      'QuickBooks does not support an extensionless file type'
+    )
+    expect(() => assertQuickBooksAttachmentExtension('receipt.pdf')).not.toThrow()
+  })
+
+  it('canonicalizes a .jpg upload to image/jpeg', () => {
+    expect(validateQuickBooksAttachmentFileType('photo.jpg', 'image/jpg')).toBe('image/jpeg')
+    expect(validateQuickBooksAttachmentFileType('photo.jpg', 'image/pjpeg')).toBe('image/jpeg')
+    expect(() => validateQuickBooksAttachmentFileType('photo.jpg', 'image/png')).toThrow(
+      'QuickBooks does not support the jpg / image/png file type combination'
+    )
+  })
+
+  it('reduces a traversal-shaped file name to a safe leaf', () => {
+    expect(sanitizeQuickBooksFileName('../../etc/passwd', 'fallback.pdf')).toBe('passwd')
+    expect(sanitizeQuickBooksFileName('..', 'fallback.pdf')).toBe('fallback.pdf')
+  })
+
+  it('builds the documented Attachable metadata for the file_metadata_01 part', () => {
+    expect(
+      buildQuickBooksAttachableMetadata('invoice', 'invoice-1', {
+        fileName: 'receipt.pdf',
+        contentType: 'application/pdf',
+        note: 'Signed copy',
+      })
+    ).toEqual({
+      AttachableRef: [{ EntityRef: { type: 'Invoice', value: 'invoice-1' } }],
+      FileName: 'receipt.pdf',
+      ContentType: 'application/pdf',
+      Note: 'Signed copy',
+    })
+  })
+})
+
+describe('QuickBooks Attachable fault reporting', () => {
+  it('names the read operation when a read returns a nested fault', async () => {
+    await expect(
+      parseQuickBooksAttachableResponse(attachableFaultResponse(), undefined, 'attachment read')
+    ).rejects.toThrow(/^QuickBooks attachment read failed:/)
+  })
+
+  it('still names the upload operation for callers that supply no label', async () => {
+    await expect(parseQuickBooksAttachableResponse(attachableFaultResponse())).rejects.toThrow(
+      /^QuickBooks attachment upload failed:/
+    )
+  })
+
+  it('routes attachment reads through the labelled parser', async () => {
+    await expect(
+      quickbooksReadAttachmentsTool.transformResponse?.(attachableFaultResponse(), {
+        accessToken: 'token',
+        realmId: '123',
+        quickBooksEnvironment: 'sandbox',
+        readMode: 'by_id',
+        attachmentId: 'attachment-1',
+      })
+    ).rejects.toThrow(/^QuickBooks attachment read failed:/)
+  })
+})

apps/sim/tools/quickbooks/documents_utils.ts

@@ -71,6 +71,12 @@ interface QuickBooksFileType {
  * Extension allowlist for QuickBooks attachments. Each entry follows Intuit's
  * published extension/content-type table, tolerates common browser and OS MIME
  * aliases, and normalizes them to one canonical content type before upload.
+ *
+ * Sending `image/jpeg` for a `.jpg` file is deliberate and must not be "fixed" back to
+ * `image/jpg`. Intuit's Attachable upload sample sends `image/jpg` while the read response for
+ * that same file returns `image/jpeg`, so QuickBooks normalizes on ingest; and the
+ * `attachablerequest` model has no `ContentType` property at all, which makes the multipart
+ * metadata content type advisory rather than contractual.
  */
 const QUICKBOOKS_FILE_TYPES: Record<string, QuickBooksFileType> = {
   ai: {
@@ -207,8 +213,14 @@ export function sanitizeQuickBooksFileName(value: string | undefined, fallback:
   return (value ? sanitize(value) : undefined) ?? sanitize(fallback) ?? 'quickbooks-file'
 }
 
+/**
+ * Returns the lowercased extension, or an empty string when the name carries none. Splitting on
+ * `.` alone would report a dotless name as its own extension, so an unattachable `backup` file
+ * would be refused as "the backup file type" instead of as an extensionless one.
+ */
 function getQuickBooksFileExtension(fileName: string): string {
-  return fileName.split('.').pop()?.toLowerCase() ?? ''
+  const separator = fileName.lastIndexOf('.')
+  return separator > 0 ? fileName.slice(separator + 1).toLowerCase() : ''
 }
 
 /**
@@ -273,9 +285,17 @@ export function sanitizeQuickBooksAttachable(
   return safeAttachment as QuickBooksAttachable
 }
 
+/**
+ * Parses an Intuit Attachable envelope for any operation that returns one.
+ *
+ * `operationLabel` names the operation in the nested-fault error message. It defaults to the
+ * upload wording because the upload path is the older caller; every other caller passes its own
+ * label so a read failure is not reported as a failed upload.
+ */
 export async function parseQuickBooksAttachableResponse(
   response: Response,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  operationLabel = 'attachment upload'
 ): Promise<{ attachment: QuickBooksAttachable; time: string | null }> {
   const data = await parseQuickBooksJson<QuickBooksAttachableEnvelope>(
     response,
@@ -286,7 +306,7 @@ export async function parseQuickBooksAttachableResponse(
   const sanitizedFault = sanitizeQuickBooksFaultData({ Fault: nestedFault })
   if (sanitizedFault) {
     throw new Error(
-      `QuickBooks attachment upload failed: ${formatQuickBooksFaultDetail(sanitizedFault)}`
+      `QuickBooks ${operationLabel} failed: ${formatQuickBooksFaultDetail(sanitizedFault)}`
     )
   }
   const attachment = data.Attachable ?? data.AttachableResponse?.[0]?.Attachable
@@ -303,6 +323,12 @@ export async function parseQuickBooksAttachableResponse(
   }
 }
 
+/**
+ * Builds the `file_metadata_01` part of an Attachable multipart upload.
+ *
+ * Intuit's `attachablerequest` model has exactly one free-text field, `Note`, so `description`
+ * and `note` both land there and `note` wins when a caller supplies both.
+ */
 export function buildQuickBooksAttachableMetadata(
   targetType: QuickBooksAttachmentTargetType,
   targetId: string,

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

@@ -132,7 +132,7 @@ export const quickbooksReadAttachmentsTool: ToolConfig<
   transformResponse: async (response, params) => {
     if (!params) throw new Error('QuickBooks Read Attachments parameters are required')
     if (params.readMode === 'by_id') {
-      const parsed = await parseQuickBooksAttachableResponse(response)
+      const parsed = await parseQuickBooksAttachableResponse(response, undefined, 'attachment read')
       return { success: true, output: { item: parsed.attachment, time: parsed.time } }
     }
     const pagination = validateQuickBooksPagination(