fix(quickbooks): stop replace-allocations detaching non-invoice payment links

buildPaymentLines returned only invoice LinkedTxn entries, and the
unapplyOmittedInvoices path sent that array as the payment's entire Line
collection. Intuit documents Payment Line.LinkedTxn.TxnType as one of
Expense, Check, CreditCardCredit, JournalEntry, CreditMemo or Invoice, and
an update as "send all the Lines that need to be present MINUS the lines
that need to be removed" — so replacing invoice allocations silently
detached every applied credit memo, expense, check and journal entry.
Non-invoice lines are now carried forward first, in the order QuickBooks
returned them, and counted against the payment total.

Also aligned with Intuit's documented model:
- salesreceiptrequest requires only Line, refundreceiptrequest only
  DepositToAccountRef and Line; neither lists CustomerRef, so customerId is
  optional on both receipt paths and CustomerRef is emitted only when given.
- Line.Amount, SalesItemLineDetail.Qty and UnitPrice carry no positivity or
  non-zero constraint, so zero is accepted (finite/2-decimal/safe-range
  checks unchanged).
- Enforce the documented maximum lengths locally: DocNumber 21,
  MemoRef.value 1000, Line.Description 4000.
- Add void_sales_receipt, the documented
  salesreceipt?operation=update&include=void sparse void.
- read_sales_transactions maxResults description now says 1–1000, matching
  validateQuickBooksPagination.

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/create_refund_receipt.ts

@@ -46,9 +46,9 @@ export const quickbooksCreateRefundReceiptTool: ToolConfig<
     },
     customerId: {
       type: 'string',
-      required: true,
+      required: false,
       visibility: 'user-or-llm',
-      description: 'Customer receiving the refund',
+      description: 'Customer receiving the refund, omitted for an anonymous refund',
     },
     lines: {
       type: 'json',
@@ -121,7 +121,10 @@ export const quickbooksCreateRefundReceiptTool: ToolConfig<
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
     body: (params) =>
-      buildQuickBooksCreateSalesDocumentBody(params, { requireDepositAccount: true }),
+      buildQuickBooksCreateSalesDocumentBody(params, {
+        requireDepositAccount: true,
+        customerOptional: true,
+      }),
     retry: { enabled: false },
   },
   transformResponse: (response) =>

apps/sim/tools/quickbooks/create_sales_receipt.ts

@@ -46,9 +46,9 @@ export const quickbooksCreateSalesReceiptTool: ToolConfig<
     },
     customerId: {
       type: 'string',
-      required: true,
+      required: false,
       visibility: 'user-or-llm',
-      description: 'Customer for the sales receipt',
+      description: 'Customer for the sales receipt, omitted for an anonymous sale',
     },
     lines: {
       type: 'json',
@@ -120,7 +120,7 @@ export const quickbooksCreateSalesReceiptTool: ToolConfig<
       ).toString(),
     method: 'POST',
     headers: (params) => getQuickBooksToolHeaders(params.accessToken, 'application/json'),
-    body: (params) => buildQuickBooksCreateSalesDocumentBody(params),
+    body: (params) => buildQuickBooksCreateSalesDocumentBody(params, { customerOptional: true }),
     retry: { enabled: false },
   },
   transformResponse: (response) =>

apps/sim/tools/quickbooks/read_sales_transactions.ts

@@ -75,7 +75,7 @@ export const quickbooksReadSalesTransactionsTool: ToolConfig<
       required: false,
       visibility: 'user-or-llm',
       default: 25,
-      description: 'Number of list records to request (1–100)',
+      description: 'Number of list records to request (1–1000)',
     },
     startDate: {
       type: 'string',

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

@@ -7,11 +7,16 @@ vi.mock('@/lib/core/config/env', () => ({
 
 import {
   buildQuickBooksCreatePaymentBody,
+  buildQuickBooksCreateSalesDocumentBody,
   buildQuickBooksUpdatePaymentBody,
+  buildQuickBooksUpdateSalesDocumentBody,
   parseQuickBooksInvoiceAllocations,
   parseQuickBooksSalesLines,
 } from '@/tools/quickbooks/sales_utils'
 import { getQuickBooksOperationError } from '@/tools/quickbooks/utils'
+import { quickbooksVoidCustomerPaymentTool } from '@/tools/quickbooks/void_customer_payment'
+import { quickbooksVoidInvoiceTool } from '@/tools/quickbooks/void_invoice'
+import { quickbooksVoidSalesReceiptTool } from '@/tools/quickbooks/void_sales_receipt'
 
 describe('QuickBooks sales monetary validation', () => {
   it.each([
@@ -274,3 +279,199 @@ describe('QuickBooks customer payment allocations', () => {
     })
   })
 })
+
+describe('QuickBooks payment allocation replacement', () => {
+  const paymentWithCreditMemo = {
+    Id: 'payment-1',
+    TotalAmt: 30,
+    Line: [
+      { Amount: 10, LinkedTxn: [{ TxnId: 'credit-memo-1', TxnType: 'CreditMemo' }] },
+      { Amount: 5, LinkedTxn: [{ TxnId: 'expense-1', TxnType: 'Expense' }] },
+      { Amount: 15, LinkedTxn: [{ TxnId: 'invoice-1', TxnType: 'Invoice' }] },
+    ],
+  }
+
+  it('keeps every non-invoice linked line when replacing invoice allocations', () => {
+    expect(
+      buildQuickBooksUpdatePaymentBody(
+        {
+          accessToken: 'token',
+          realmId: 'realm',
+          paymentId: 'payment-1',
+          syncToken: '0',
+          invoiceAllocations: [{ invoiceId: 'invoice-2', amount: 15 }],
+          unapplyOmittedInvoices: true,
+        },
+        paymentWithCreditMemo
+      ).Line
+    ).toEqual([
+      { Amount: 10, LinkedTxn: [{ TxnId: 'credit-memo-1', TxnType: 'CreditMemo' }] },
+      { Amount: 5, LinkedTxn: [{ TxnId: 'expense-1', TxnType: 'Expense' }] },
+      { Amount: 15, LinkedTxn: [{ TxnId: 'invoice-2', TxnType: 'Invoice' }] },
+    ])
+  })
+
+  it('counts carried-forward lines against the payment total', () => {
+    expect(() =>
+      buildQuickBooksUpdatePaymentBody(
+        {
+          accessToken: 'token',
+          realmId: 'realm',
+          paymentId: 'payment-1',
+          syncToken: '0',
+          invoiceAllocations: [{ invoiceId: 'invoice-2', amount: 16 }],
+          unapplyOmittedInvoices: true,
+        },
+        paymentWithCreditMemo
+      )
+    ).toThrow('Invoice allocation amounts cannot exceed totalAmount')
+  })
+})
+
+describe('QuickBooks sales line numeric bounds', () => {
+  it('accepts a zero amount, quantity, and unit price', () => {
+    expect(
+      parseQuickBooksSalesLines([
+        { lineType: 'item', amount: 0, itemId: 'item-1', quantity: 0, unitPrice: 0 },
+      ])
+    ).toEqual([
+      {
+        lineType: 'item',
+        amount: 0,
+        itemId: 'item-1',
+        description: undefined,
+        quantity: 0,
+        unitPrice: 0,
+        serviceDate: undefined,
+      },
+    ])
+  })
+})
+
+describe('QuickBooks sales document bodies', () => {
+  const line = { lineType: 'item' as const, amount: 10, itemId: 'item-1' }
+
+  it('emits the documented detail types for item and description lines', () => {
+    expect(
+      buildQuickBooksCreateSalesDocumentBody({
+        accessToken: 'token',
+        realmId: 'realm',
+        customerId: 'customer-1',
+        lines: [line, { lineType: 'description', description: 'Thanks' }],
+      }).Line
+    ).toEqual([
+      {
+        Amount: 10,
+        DetailType: 'SalesItemLineDetail',
+        SalesItemLineDetail: { ItemRef: { value: 'item-1' } },
+      },
+      { DetailType: 'DescriptionOnly', Description: 'Thanks', DescriptionLineDetail: {} },
+    ])
+  })
+
+  it('omits CustomerRef on a receipt created without a customer', () => {
+    expect(
+      buildQuickBooksCreateSalesDocumentBody(
+        { accessToken: 'token', realmId: 'realm', customerId: '', lines: [line] },
+        { customerOptional: true }
+      )
+    ).not.toHaveProperty('CustomerRef')
+  })
+
+  it('still requires a customer on the documents that list CustomerRef', () => {
+    expect(() =>
+      buildQuickBooksCreateSalesDocumentBody({
+        accessToken: 'token',
+        realmId: 'realm',
+        customerId: '',
+        lines: [line],
+      })
+    ).toThrow()
+  })
+
+  it('rejects values past the documented QuickBooks maximum lengths', () => {
+    expect(() =>
+      buildQuickBooksCreateSalesDocumentBody({
+        accessToken: 'token',
+        realmId: 'realm',
+        customerId: 'customer-1',
+        lines: [line],
+        documentNumber: 'D'.repeat(22),
+      })
+    ).toThrow('documentNumber cannot exceed 21 characters')
+
+    expect(() =>
+      buildQuickBooksCreateSalesDocumentBody({
+        accessToken: 'token',
+        realmId: 'realm',
+        customerId: 'customer-1',
+        lines: [line],
+        customerMemo: 'M'.repeat(1001),
+      })
+    ).toThrow('customerMemo cannot exceed 1000 characters')
+
+    expect(() => parseQuickBooksSalesLines([{ ...line, description: 'x'.repeat(4001) }])).toThrow(
+      'lines[0].description cannot exceed 4000 characters'
+    )
+  })
+
+  it('builds a sparse update body carrying the identifiers and the patch', () => {
+    expect(
+      buildQuickBooksUpdateSalesDocumentBody({
+        accessToken: 'token',
+        realmId: 'realm',
+        transactionId: 'invoice-1',
+        syncToken: '3',
+        privateNote: 'Updated',
+      })
+    ).toEqual({
+      Id: 'invoice-1',
+      SyncToken: '3',
+      sparse: true,
+      PrivateNote: 'Updated',
+    })
+  })
+})
+
+describe('QuickBooks void request shapes', () => {
+  const params = {
+    accessToken: 'token',
+    realmId: '123',
+    quickBooksEnvironment: 'sandbox' as const,
+    transactionId: 'txn-1',
+    syncToken: '4',
+    confirmVoid: true,
+  }
+
+  it('voids an invoice through operation=void with no sparse flag', () => {
+    const url = new URL(quickbooksVoidInvoiceTool.request.url(params))
+    expect(url.pathname).toContain('/invoice')
+    expect(url.searchParams.get('operation')).toBe('void')
+    expect(url.searchParams.get('include')).toBeNull()
+    expect(quickbooksVoidInvoiceTool.request.body?.(params)).toEqual({
+      Id: 'txn-1',
+      SyncToken: '4',
+    })
+  })
+
+  it.each([
+    ['payment', quickbooksVoidCustomerPaymentTool],
+    ['salesreceipt', quickbooksVoidSalesReceiptTool],
+  ])('voids %s through operation=update&include=void with sparse', (resource, tool) => {
+    const url = new URL(tool.request.url(params))
+    expect(url.pathname).toContain(`/${resource}`)
+    expect(url.searchParams.get('operation')).toBe('update')
+    expect(url.searchParams.get('include')).toBe('void')
+    expect(tool.request.body?.(params)).toEqual({
+      Id: 'txn-1',
+      SyncToken: '4',
+      sparse: true,
+    })
+  })
+
+  it('refuses to void a sales receipt without explicit confirmation', () => {
+    expect(() =>
+      quickbooksVoidSalesReceiptTool.request.body?.({ ...params, confirmVoid: false })
+    ).toThrow('Confirm void before voiding the sales receipt')
+  })
+})