feat(quickbooks): add observable PO-to-bill linking

[BillLeoutsakosvl346]

What changed

• Extended Create Bill with optional Purchase Order ID and PO line ID pairs on individual Bill lines.
• Added truthful post-create linkage reporting through linkingRequested, linkingSucceeded, linkedLines, missingLinks, and linkingWarning.
• Preserved the native QuickBooks Bill response and standalone Bill behavior.
• Documented native PO/Bill line IDs and linked-transaction fields without adding a new QuickBooks operation.

Why

QuickBooks requires line-level TxnLineId values to establish PO-to-Bill relationships. It may also create the Bill while silently omitting an invalid or unavailable requested link. The tool therefore verifies the returned Bill and reports exactly which requested links QuickBooks established instead of treating HTTP success as proof of linkage.

Validation

• Independent full-integration review against staging: approved with no actionable findings.
• 539 reviewer-run targeted tests; 313 final local QuickBooks/OAuth/serializer/redaction tests.
• Sim TypeScript type-check.
• Tool metadata and generated documentation checks.
• API validation, bare-icon validation, and client-boundary validation.
• Repository format and lint checks.
• git diff --check and memory-load audit.
• Sandbox acceptance for standalone, full, partial, mixed, multi-line, multi-PO, omitted-link, already-linked, and vendor-mismatch cases.

Stack

• Base: feat/quickbooks-04-accounting at 8d443814c4f29f3a8f4acb36fabed7d0df44d182
• Head: feat/quickbooks-04a-po-bill-linking

This PR must not be merged automatically.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 3, 2026 11:53pm

[cursor]

PR Summary

High Risk
Changes bill creation and PO linkage against live QuickBooks payables data, and adds document/attachment flows that move user files through Intuit and temporary URLs with new security boundaries.

Overview
Create Bill can now request Purchase Order links by supplying paired purchaseOrderId and purchaseOrderLineId on individual expense lines (via parseQuickBooksBillLines instead of generic purchasing line parsing). After QuickBooks responds, the tool verifies returned Line / LinkedTxn data and surfaces linkingRequested, linkingSucceeded, linkedLines, missingLinks, and linkingWarning so workflows do not treat HTTP success as proof that every requested PO line was linked.

The same changeset also expands QuickBooks integration docs and the block: master-data class/department reads and filters, employee create/update, list filters on transaction reads, richer purchasing line outputs, financial reports, transaction email/PDF, and attachment read/add/download APIs with size limits, file auth, and abort-aware pinned fetches.

^{Reviewed by Cursor Bugbot for commit c8e3098. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR extends QuickBooks Create Bill with optional line-level Purchase Order references and reports whether QuickBooks returned each requested link.

• Validates paired Purchase Order and line identifiers while preserving standalone Bill behavior.
• Adds transaction- and line-level QuickBooks linkage fields to the create payload.
• Verifies returned Bill lines and exposes confirmed links, missing links, and a partial-link warning.
• Updates block metadata, generated contracts, documentation, and focused tests.

Confidence Score: 5/5

The PR appears safe to merge, although the user explicitly requested that it not be merged automatically.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/tools/quickbooks/purchasing_utils.ts	Adds Bill-specific line parsing, PO linkage payload construction, and post-create linkage verification while retaining the shared purchasing-line path.
apps/sim/tools/quickbooks/create_bill.ts	Extends Create Bill response transformation and output metadata with observable linkage results.
apps/sim/tools/quickbooks/types.ts	Defines linked-transaction shapes, Bill-link inputs and outputs, and richer purchasing transaction line metadata.
apps/sim/blocks/blocks/quickbooks.ts	Maps Create Bill through the Bill-specific parser and exposes linkage status fields to workflows.
apps/sim/tools/quickbooks/purchasing.test.ts	Covers standalone, linked, partial, missing, mixed, duplicate, and operation-scoped PO-link behavior.

Sequence Diagram

sequenceDiagram
  participant Workflow
  participant Tool as Create Bill Tool
  participant QBO as QuickBooks
  Workflow->>Tool: Bill lines with optional PO and PO-line IDs
  Tool->>Tool: Validate paired IDs and build LinkedTxn fields
  Tool->>QBO: POST Bill
  QBO-->>Tool: Created native Bill
  Tool->>Tool: Compare requested links with Bill Line[].LinkedTxn
  Tool-->>Workflow: Bill plus linkingSucceeded, linkedLines, missingLinks, warning

Loading

_{Reviews (2): Last reviewed commit: "fix(quickbooks): keep shared line exampl..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 702149c. Configure here.}

[BillLeoutsakosvl346]

@greptileai