feat(quickbooks): add read-only procurement integration

[BillLeoutsakosvl346]

Summary

Adds a clean, read-only QuickBooks Online procurement integration with one OAuth connection bound to one selected QuickBooks company.

• Adds four fixed actions: get company info, list vendors, list purchase orders, and list bills.
• Binds realmId to the validated OAuth credential, so workflows cannot choose or override a company.
• Pins Accounting API requests to minor version 75 and selects sandbox/production hosts only from server configuration.
• Adds bounded response parsing, fixed-entity queries, explicit pagination, sanitized QuickBooks Fault handling, and no internal retries or automatic pagination.
• Adds the QuickBooks block, cropped official circular icon, metadata/templates, registry entries, generated integration docs, and contract tests.

Review fixes included

• Keeps the QuickBooks Fault extractor explicit to QuickBooks tools so unrelated provider errors retain their existing behavior.
• Detects QuickBooks Fault envelopes even when Intuit returns HTTP 200, including during OAuth-time CompanyInfo validation.
• Removes raw non-JSON provider bodies from tool output and logs.
• Caps OAuth token refresh responses at 64 KiB and removes token fragments/raw token responses from logging.
• Preserves bounded 1 MiB UserInfo and 8 MiB Accounting API reads.
• Corrects registry ordering and generated CompanyInfo schema documentation.

Validation

• bunx vitest run tools/index.test.ts tools/quickbooks lib/oauth/quickbooks.test.ts lib/oauth/oauth.test.ts lib/oauth/utils.test.ts app/api/auth/oauth/token/route.test.ts blocks/blocks.test.ts — 8 files, 387 tests passed.
• bun run type-check — 23/23 monorepo tasks passed.
• bun run lint:check — passed; only two pre-existing Biome false-positive warnings on terminal fit() method calls.
• bun run generate-docs — passed.
• bun run check:bare-icons — passed.
• bun run check:icon-paths — passed.
• bun run check:api-validation — passed.
• git diff --check origin/staging...HEAD — passed.
• Independent GPT-5.6-sol re-review found no remaining code issues and returned READY FOR DRAFT PR.

Manual sandbox acceptance still required

This PR remains a draft until a live Intuit sandbox confirms UserInfo realmId delivery and the full acceptance flow: CompanyInfo identity matching, all four actions, explicit page continuation, empty pages, two-company isolation, reconnect behavior, refresh-token rotation, revoked-credential guidance, and sandbox-host isolation. No credentials or unsanitized accounting data are committed.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 28, 2026 6:18pm

[cursor]

PR Summary

High Risk
Touches OAuth, token revocation, and live QuickBooks company data with many write, void, email, and file-transfer actions; misconfiguration or bugs could affect customer accounting records or leak credentials.

Overview
Adds QuickBooks Online as a documented integration with a circular brand icon, docs nav entry, and a large generated quickbooks.mdx reference covering company binding, sparse updates, pagination, reports, PDFs, and attachments.

OAuth and credentials are extended so one connected company is fixed at callback time: the auth route validates realmId, scopes Better Auth handling with withQuickBooksCallbackRealm, disconnect revokes Intuit tokens before local deletion, and the token API returns realmId only for QuickBooks credentials (with reconnect guidance on malformed account IDs). Optional QUICKBOOKS_* env vars configure sandbox vs production.

The PR introduces workflow tools and API routes beyond read-only lists—master data CRUD, sales and purchasing transactions (create/update/void where supported), accounting entries, financial reports, transaction email, PDF download, and attachment upload/download—with bounded file handling and SSRF-guarded attachment URLs in the document download path.

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

[greptile-apps]

Greptile Summary

Adds a QuickBooks Online integration with OAuth-bound company selection and generated documentation.

• Registers QuickBooks blocks, tools, contracts, metadata, icons, and deployment capabilities.
• Adds OAuth connection, token-resolution, company-validation, and environment-selection behavior.
• Implements bounded QuickBooks API parsing, sanitized Fault handling, explicit pagination, and accounting operations.
• Adds contract, OAuth, registry, execution, and provider-operation tests.

Confidence Score: 5/5

The PR appears safe to merge with no eligible blocking failure identified in this follow-up review.

No blocking failure remains within the scope of the available previous review threads.

Important Files Changed

Filename	Overview
apps/sim/lib/oauth/quickbooks.ts	Adds QuickBooks OAuth profile resolution and company-bound account identifiers.
apps/sim/tools/quickbooks/client.ts	Centralizes QuickBooks environment selection, bounded API reads, and CompanyInfo validation.
apps/sim/tools/quickbooks/utils.ts	Adds shared request, pagination, response transformation, and Fault-handling utilities.
apps/sim/lib/internal/quickbooks/execute-tool.ts	Dispatches registered QuickBooks operations through the internal tool execution boundary.
apps/sim/lib/internal/quickbooks/provider-operations.ts	Implements provider-facing QuickBooks accounting operations.
apps/sim/lib/internal/tool-operations/registry.server.ts	Registers QuickBooks tool identifiers with the internal operation handler.
apps/sim/blocks/blocks/quickbooks.ts	Defines the QuickBooks workflow block and its supported actions.
apps/sim/app/api/auth/oauth/token/route.ts	Extends OAuth token resolution for QuickBooks credential metadata.
packages/sim-setup/src/capability-config.ts	Adds QuickBooks capability configuration to deployment setup.

Sequence Diagram

sequenceDiagram
  participant User
  participant Sim as Sim Workflow
  participant OAuth as OAuth Connection
  participant Intuit as Intuit OAuth
  participant QBO as QuickBooks API
  User->>Sim: Connect QuickBooks company
  Sim->>Intuit: OAuth authorization
  Intuit-->>OAuth: Tokens and company identity
  OAuth->>QBO: Validate CompanyInfo
  QBO-->>OAuth: Bound company details
  OAuth-->>Sim: Persist company-bound credential
  User->>Sim: Run QuickBooks action
  Sim->>OAuth: Resolve token and realm
  Sim->>QBO: Execute bounded API request
  QBO-->>Sim: Entity response or sanitized Fault
  Sim-->>User: Structured tool output

Loading

_{Reviews (3): Last reviewed commit: "fix(quickbooks): migrate provider operat..." | Re-trigger Greptile}

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 33d9afb. Configure here.}

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 29bfcc5. Configure here.}

[BillLeoutsakosvl346]

@cursor review

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 19e00eb. Configure here.}

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 00fc671. Configure here.}

[BillLeoutsakosvl346]

@cursor review

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 970d3b1. Configure here.}

[BillLeoutsakosvl346]

QuickBooks codebase-standardization update

I simplified the QuickBooks implementation to follow Sim’s existing integration patterns and removed the shared infrastructure that had been introduced specifically for QuickBooks.

What was removed

• Custom QuickBooks authorization-code exchange
• QuickBooks-specific refresh-lock timings
• Per-tool response-size configuration
• Response-header propagation for QuickBooks errors
• Custom error-extractor fallback behavior
• Shared QuickBooks file-storage helper
• Serializer singleton-group exception
• QuickBooks-driven shared secure-fetch changes
• Provider-specific realmId injection logic

The cleanup removed substantially more code than it added:

• 125 lines added
• 712 lines removed

No QuickBooks operations, block fields, OAuth scopes, endpoints, accounting behavior, or output contracts changed.

Standard files

These now follow the normal structure used by other Sim integrations:

• apps/sim/blocks/blocks/quickbooks.ts
• Everything under apps/sim/tools/quickbooks/
• Tool and block registries
• Integration and icon registries
• Generated tool metadata
• Generated QuickBooks documentation

The tools remain provider-local, generally with one file per operation and small shared QuickBooks utilities for sales, purchasing, accounting, reports, faults, and documents.

Semi-standard files

These use established Sim patterns needed by integrations with OAuth metadata, binary files, or structured provider errors.

OAuth and company binding

• apps/sim/lib/auth/connectors/providers.ts
• apps/sim/lib/oauth/quickbooks.ts
• apps/sim/lib/oauth/oauth.ts
• apps/sim/lib/oauth/types.ts
• apps/sim/lib/oauth/utils.ts
• apps/sim/app/api/auth/[...all]/route.ts
• apps/sim/app/api/auth/oauth/token/route.ts
• OAuth API contracts and environment registration

QuickBooks now uses Better Auth’s standard Basic-auth token exchange and Sim’s normal refresh-lock behavior. The remaining provider-specific callback code is required because Intuit returns the selected company’s realmId separately from the OAuth token response.

The credential-derived realmId is propagated through the same generic OAuth metadata path used for values such as Salesforce instanceUrl, Atlassian cloudId, and Zoho apiDomain.

Binary documents and attachments

• apps/sim/app/api/tools/quickbooks/add-attachment/route.ts
• apps/sim/app/api/tools/quickbooks/download-document/route.ts
• apps/sim/lib/api/contracts/tools/quickbooks.ts

These routes follow the established file-backed integration pattern. They are needed for workspace-file authorization, binary size limits, secure downloads, and conversion to Sim UserFile outputs.

Structured faults and operational tokens

• apps/sim/tools/error-extractors.ts
• apps/sim/lib/core/security/redaction.ts

QuickBooks faults use Sim’s existing extractor registry. SyncToken uses the existing exact redaction-allowlist pattern because it is a required record version for updates, not an authentication token.

Unique infrastructure

None.

QuickBooks no longer introduces a custom shared framework or QuickBooks-only platform architecture. Its remaining nonstandard requirements are implemented through patterns already used by comparable integrations.

Validation

• 1,382 test files passed
• 18,668 tests passed
• TypeScript type-check passed
• Formatting and lint checks passed
• API validation passed
• Client and registry boundary checks passed
• Tool metadata and integration catalog checks passed
• git diff --check passed
• BugBot passed with no unresolved findings

Cleanup commit: 1512602f51

[BillLeoutsakosvl346]

@cursor review

[BillLeoutsakosvl346]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 78c0b29. Configure here.}

[waleedlatif1]

@greptile

[waleedlatif1]

@greptile