feat(quickbooks): add read-only procurement integration - #6099
feat(quickbooks): add read-only procurement integration#6099BillLeoutsakosvl346 wants to merge 32 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
PR SummaryHigh Risk Overview The QuickBooks block and tools cover master data CRUD, sales and purchasing transactions (create/update/void where supported), journal entries, deposits, financial reports, emailing transactions, PDF downloads, and file/note attachments. List reads expose explicit pagination ( Docs and UI: new Reviewed by Cursor Bugbot for commit ed74a2f. Bugbot is set up for automated code reviews on this repo. Configure here. |
Greptile SummaryAdds a read-only QuickBooks Online procurement integration.
Confidence Score: 5/5The 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.
|
| 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
Reviews (1): Last reviewed commit: "feat(quickbooks): add read-only procurem..." | Re-trigger Greptile
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
@cursor review |
There was a problem hiding this comment.
✅ 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.
|
@cursor review |
There was a problem hiding this comment.
✅ 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.
|
@cursor review |
|
@cursor review |
There was a problem hiding this comment.
✅ 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.
|
@cursor review |
There was a problem hiding this comment.
✅ 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.
* feat(quickbooks): add master data and CRUD tools * feat(quickbooks): expose compact master data operations * docs(quickbooks): document master data actions * fix(quickbooks): harden master data outputs * fix(redaction): preserve workflow state tokens * fix(quickbooks): address integration review findings * fix(quickbooks): align item updates and generated docs * fix(quickbooks): sanitize customer tax identifiers * fix(quickbooks): preserve read-write compatibility * fix(quickbooks): use action-first operation labels * test(quickbooks): align operation label expectations * fix(quickbooks): align catalog operation labels * fix(redaction): cover namespaced secret fields * fix(quickbooks): expose master data pagination metadata * fix(quickbooks): omit null optional values * fix(quickbooks): validate master data inputs * chore(tools): sync master data metadata * fix(redaction): anchor workflow token allowlist * feat(quickbooks): add sales and accounts receivable (#6130) * feat(quickbooks): add bounded sales transaction reads * feat(quickbooks): add sales and receivables mutations * feat(quickbooks): expose sales operations in the block * fix(quickbooks): address independent sales review * fix(quickbooks): address final integration review * fix(quickbooks): clarify master data output metadata * fix(quickbooks): mark sales pagination outputs optional * fix(quickbooks): validate calculated sales amounts * fix(quickbooks): generate sales arrays correctly * fix(quickbooks): align sales metadata conditions * chore(tools): sync sales metadata * feat(quickbooks): add purchasing and payables (#6159) * feat(quickbooks): add safe purchasing and payables tools * feat(quickbooks): expose purchasing and payables operations * docs(quickbooks): document purchasing and payables tools * fix(quickbooks): require current purchase payment type * fix(quickbooks): allow rounded purchasing line totals * fix(quickbooks): generate purchasing arrays correctly * fix(quickbooks): validate bill payment accounts * fix(quickbooks): validate bill allocations before account lookup * chore(tools): sync purchasing metadata * fix(quickbooks): sanitize bill payment faults * feat(quickbooks): add general accounting operations (#6185) * feat(quickbooks): add accounting transaction tools * feat(quickbooks): expose accounting operations * docs(quickbooks): generate accounting catalog * fix(quickbooks): preserve accounting amount precision * fix(quickbooks): balance journal entries in exact cents * fix(quickbooks): include account in deposit updates * chore(quickbooks): sync accounting catalog * feat(quickbooks): add observable PO-to-bill linking (#6194) * feat(quickbooks): link bills to purchase order lines * docs(quickbooks): document observable bill linking * fix(quickbooks): document purchase order link identifiers * fix(quickbooks): keep shared line example valid * chore(quickbooks): sync bill linking catalog * feat(quickbooks): add accountant-focused financial reports (#6197) * feat(quickbooks): add verified financial report contracts * feat(quickbooks): expose reports in block and catalog * test(quickbooks): cover null report filters * fix(quickbooks): expose report header time * chore(quickbooks): sync reports catalog * feat(quickbooks): add documents and attachments (#6200) * feat(quickbooks): add document and attachment tools * feat(quickbooks): add bounded document file routes * feat(quickbooks): expose document workflows * fix(quickbooks): enforce attachment upload bounds * fix(quickbooks): tighten document handling * fix(quickbooks): align file response limits * test(quickbooks): cover missing PDF content type * test(quickbooks): cover attachment MIME fallback * fix(quickbooks): redact attachment access URLs * fix(quickbooks): store downloaded documents safely * fix(quickbooks): stop cancelled attachment downloads * fix(quickbooks): correct document schemas and upload bytes * chore(quickbooks): sync document catalog * feat(quickbooks): add accountant filters (#6208) * feat(quickbooks): add safe n8n parity tools * feat(quickbooks): expose accountant parity options * fix(quickbooks): address parity review findings * fix(quickbooks): require recipient for payment email * chore(quickbooks): sync parity catalog --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain> --------- Co-authored-by: Bill Leoutsakos <billleoutsakos@Bills-MacBook-Pro.local> Co-authored-by: Bill Leoutsakos <billleoutsakos@Mac.localdomain>
|
| GitGuardian id | GitGuardian status | Secret | Commit | Filename | |
|---|---|---|---|---|---|
| 35640005 | Triggered | Generic Password | 0c3de74 | apps/desktop/src/main/browser-import/import-service.test.ts | View secret |
🛠 Guidelines to remediate hardcoded secrets
- Understand the implications of revoking this secret by investigating where it is used in your code.
- Replace and store your secret safely. Learn here the best practices.
- Revoke and rotate this secret.
- If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.
To avoid such incidents in the future consider
- following these best practices for managing and storing secrets including API keys and other credentials
- install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.
🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.
QuickBooks PR file inventoryI reviewed the effective PR diff against the latest Files are grouped into:
For semi-standard and unique files, I have explained why the change is necessary and why it belongs in this PR. Diff sizeExcluding tests:
Tests:
Complete PR:
The non-test total includes the generated 2,915-line QuickBooks documentation and generated catalogues, so it is not all handwritten source. StandardThese are the conventional files expected when adding a substantial Sim integration. Block and integration catalogue
Tool registration and generated catalogues
QuickBooks tool infrastructure
Read, report, and document tools
Create tools
Update and void tools
Generated integration documentation
Semi-standardThese files follow established Sim patterns, but they are needed only by integrations with features such as OAuth, binary files, internal routes, or specialized provider errors. OAuth configuration and registration
Why these are neededQuickBooks uses OAuth in the same general way as Slack, Microsoft, Atlassian, Google, and other OAuth-backed integrations. These files register:
Why they belong in this PRThe QuickBooks tools cannot operate without a registered OAuth provider and verified access to the selected QuickBooks company. These are direct integration dependencies rather than unrelated platform features. Binary-document routes and contracts
Why these are neededIntegrations that upload or download files need more than a normal JSON tool request. These routes provide:
Why they belong in this PRAttachments and transaction PDFs are user-facing QuickBooks operations included in this integration. Moving these routes elsewhere would leave those operations incomplete or force unsafe binary handling into ordinary tool requests. Error and documentation infrastructure
Why these are neededThe error extractor follows Sim’s existing provider-specific error pattern and turns QuickBooks The documentation generator was updated to:
Why they belong in this PRQuickBooks errors otherwise lose important validation, authentication, tracking-ID, and rate-limit information. The documentation changes are needed to generate the QuickBooks document safely without exposing hidden connection fields or rewriting unrelated documentation. UniqueThese are shared-platform changes specifically required by unusual QuickBooks behavior. Company identity binding
Why these are neededIntuit supplies the selected QuickBooks company as Sim captures that value during OAuth, validates the selected company, binds it to the credential, and supplies it automatically during tool execution. Why they belong in this PRWithout this behavior:
Automatic company binding is therefore part of the core QuickBooks authentication contract, not optional platform cleanup. QuickBooks refresh concurrency
Why this is neededIntuit rotates refresh tokens. A normal short follower wait could expire while Intuit’s token request was still running, potentially allowing two refresh leaders to race and invalidate one another’s credentials. QuickBooks therefore receives a 30-second refresh-lock TTL and follower wait, while other providers retain their established defaults. Why it belongs in this PRThis is a small provider-specific branch inside the existing refresh orchestration. Shipping QuickBooks without it would create unreliable long-lived credentials, especially when workflows execute concurrently. Operational token redaction
Why this is neededQuickBooks calls its optimistic-concurrency version a The change keeps unknown tokens redacted while preserving narrow categories of operational values such as:
OAuth access and refresh tokens remain redacted. Why it belongs in this PRQuickBooks updates require the current This is the most broadly applicable shared change in the PR, but QuickBooks directly depends on it and the behavior is covered by regression tests. Advanced-mode credential serialization
Why this is neededOpening “additional fields” caused a singleton OAuth credential to be treated like the advanced half of a nonexistent basic/advanced input pair. As a result, the selected QuickBooks credential disappeared during serialization. The correction makes singleton canonical groups preserve their sole value while leaving real basic/advanced pairs unchanged. Why it belongs in this PRMost QuickBooks operations contain advanced accounting fields. Without this correction, opening those fields could make an otherwise valid QuickBooks block fail before execution. The correction is only one focused serializer change and has dedicated regression coverage. Tool execution plumbing
Why this is neededThis file contains the centralized execution behavior required to:
Why it belongs in this PRImplementing this separately in every QuickBooks tool would duplicate security-sensitive logic across 47 operations. The centralized implementation ensures consistent company isolation, response limits, error handling, and sanitization throughout the entire integration. Test filesThe following tests were added or changed to cover the integration and the shared behavior it relies upon. Modified tests
Created tests
|
…rink shared-logic surface Validation of the integration against Intuit's published attribute tables (static.developer.intuit.com/JSONObjects/*, the payload behind the docs SPA) surfaced defects that write wrong data to customers' books, plus shared-module changes broader than this integration needs. Data integrity: - update_customer_payment now reads the payment and merges allocations. QuickBooks applies payment lines ALL-or-NONE, so sending a subset silently unapplied every omitted invoice. Destructive replacement stays reachable via a user-only unapplyOmittedInvoices flag. Also validates the merged total, not just the caller's allocations. - create_item required ExpenseAccountRef (required for Service and NonInventory) as optional while mandating IncomeAccountRef (not required for NonInventory). - create_employee required DisplayName, which QuickBooks derives and treats as read-only under Payroll, while leaving the real at-least-one GivenName/FamilyName rule unchecked. Both tools threw a raw TypeError on their schema-minimal call. - create_purchase sent PaymentRefNum, absent from the Purchase entity; QuickBooks discards unknown fields silently, so check numbers vanished. Now DocNumber. - A Fault nested in QueryResponse was reported as an empty result set. Detected in parseQuickBooksJson so every response path is covered. - assertQuickBooksSparseUpdate never checked sparse despite its name. - Bill header-level LinkedTxn omitted the required TxnLineId and duplicated the line-level links; DescriptionOnly lines omitted DescriptionLineDetail. - Line amounts were positive-only, making discounts, returns and credits unrepresentable, and bare Number() silently coerced true and [5] onto the wire. - Phantom report parameters removed; aging method and period split so each report only offers the control it accepts. Safety and boundaries: - confirmVoid and confirmPosting moved to user-only, so an agent can no longer supply its own approval for voids and journal postings. - Split the runtime-free helpers out of tools/quickbooks/utils.ts. The block was the only one in the repo dragging error-extractors, client.ts, microsoft_excel/utils and stream-limits into the client bundle. - Attachment routes: 20 MB cap per Intuit's limit, outbound timeouts, extension preserved through filename truncation, Unicode filenames, wider MIME acceptance. - The two download routes merged into one; extracted storeToolOutputFile. Shared logic reduced to what this integration needs: - redaction.ts back to a bypass-set entry for SyncToken; every origin/staging assertion retained. - refreshOAuthToken read the body before the ok check, so a token response over 64 KiB became a spurious failure for every provider. Provider error text is restored to logs, redacted and truncated, and kept out of the caller message. - maxResponseBytes clamped to the global ceiling. - generate-docs is deterministic again; its output no longer depends on what is already on disk. The generic redaction engine, the serializer singleton-canonical fix and the visibility-based docs filter are deferred to their own PRs. Sparse-update semantics for ten write tools remain unverified against a live sandbox; apps/sim/scripts/quickbooks-sparse-probe.ts settles it.
…tegration # Conflicts: # apps/sim/.env.example # apps/sim/tools/generated/tool-metadata.ts # apps/sim/tools/generated/tool-outputs.ts
QuickBooks codebase-standardization updateI 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
The cleanup removed substantially more code than it added:
No QuickBooks operations, block fields, OAuth scopes, endpoints, accounting behavior, or output contracts changed. Standard filesThese now follow the normal structure used by other Sim integrations:
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 filesThese use established Sim patterns needed by integrations with OAuth metadata, binary files, or structured provider errors. OAuth and company binding
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 The credential-derived Binary documents and attachments
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 Structured faults and operational tokens
QuickBooks faults use Sim’s existing extractor registry. Unique infrastructureNone. 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
Cleanup commit: |
…tegration # Conflicts: # apps/sim/tools/generated/tool-metadata.ts # apps/sim/tools/generated/tool-outputs.ts
2 participants
Summary
Adds a clean, read-only QuickBooks Online procurement integration with one OAuth connection bound to one selected QuickBooks company.
realmIdto the validated OAuth credential, so workflows cannot choose or override a company.Review fixes included
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 terminalfit()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.READY FOR DRAFT PR.Manual sandbox acceptance still required
This PR remains a draft until a live Intuit sandbox confirms UserInfo
realmIddelivery 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.