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.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 1, 2026 1:41am

[cursor]

PR Summary

High Risk
Touches OAuth callbacks, credential binding, and token issuance for financial accounting data; incorrect realm handling could cross-wire companies or leak tokens in errors.

Overview
Adds a read-only QuickBooks Online integration: OAuth connects one Intuit company per credential; workflows cannot override the company via realmId input.

OAuth & identity: New Intuit OAuth provider, QUICKBOOKS_* env vars, callback handling that validates realmId and binds it during token exchange via async-local storage, company-scoped accountId encoding, and realmId on the OAuth token API for tool execution only.

Tools & block: Four GET actions—company info, vendors, purchase orders, bills—with fixed queries, minor version 75, explicit pagination (startPosition / maxResults 1–100), no retries, 8 MiB response caps, and a dedicated QuickBooks Fault error extractor (not global fallback).

Hardening: Sanitized fault handling on HTTP 200, bounded OAuth/UserInfo reads, safer token-refresh logging, ambiguous multi-workspace credential drafts fail closed, and tool executor rejects workflow-supplied realmId when the credential omits binding.

Docs & registry: QuickBooks icon, block metadata/templates, integration docs, and registry entries.

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

[greptile-apps]

Greptile Summary

Adds a read-only QuickBooks Online procurement integration.

• Registers four tools for company information, vendors, purchase orders, and bills.
• Binds QuickBooks company identity to OAuth credentials and propagates the validated realm into tool execution.
• Adds bounded response parsing, sanitized fault handling, explicit pagination, environment-selected API hosts, and token-refresh hardening.
• Adds the block configuration, registries, icons, generated documentation, templates, and contract tests.

Confidence Score: 5/5

The PR appears safe to merge based on the reviewed code, with no actionable defects identified.

The company identifier remains credential-bound through OAuth validation and tool execution, requests are constrained to fixed read-only entities and configured hosts, and response, pagination, refresh, and error-handling paths include explicit bounds and validation.

Important Files Changed

Filename	Overview
apps/sim/lib/oauth/quickbooks.ts	Defines and validates the company-bound QuickBooks account identity and OAuth connection profile.
apps/sim/lib/auth/auth.ts	Registers the QuickBooks generic OAuth flow and validates the selected company during connection.
apps/sim/app/api/auth/oauth/token/route.ts	Extracts the bound QuickBooks realm from authorized credentials and returns it to tool execution.
apps/sim/lib/quickbooks/client.ts	Centralizes environment-specific hosts, URL construction, response limits, headers, and CompanyInfo validation.
apps/sim/tools/quickbooks/utils.ts	Implements fixed-entity queries, bounded JSON parsing, fault detection, pagination validation, and response transformation.
apps/sim/tools/index.ts	Propagates provider context, supports per-tool response limits, and sanitizes QuickBooks errors before output or logging.
apps/sim/blocks/blocks/quickbooks.ts	Adds the QuickBooks block, four fixed operations, validated pagination mapping, templates, and skills.
apps/sim/lib/oauth/oauth.ts	Registers QuickBooks OAuth metadata and hardens shared refresh-response parsing and logging.

Sequence Diagram

sequenceDiagram
  participant User
  participant OAuth as QuickBooks OAuth
  participant Auth as Sim Auth
  participant Token as OAuth Token Route
  participant Tool as QuickBooks Tool
  participant QBO as QuickBooks Accounting API
  User->>OAuth: Authorize selected company
  OAuth-->>Auth: Authorization code
  Auth->>OAuth: Exchange code and fetch UserInfo
  Auth->>QBO: Validate CompanyInfo for realmId
  Auth-->>User: Store company-bound credential
  Tool->>Token: Request refreshed credential context
  Token-->>Tool: accessToken and bound realmId
  Tool->>QBO: Fixed read-only request for bound company
  QBO-->>Tool: CompanyInfo or paginated entities
  Tool-->>User: Sanitized bounded response

Loading

_{Reviews (1): Last reviewed commit: "feat(quickbooks): add read-only procurem..." | 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]

@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 6df18b0. Configure here.}