feat(quickbooks): add accountant-focused financial reports

[BillLeoutsakosvl346]

Summary

• add one compact Run Financial Report operation backed by 14 sandbox-verified QuickBooks reports
• support verified date, accounting-basis, summarization, entity, and aging controls through a fixed per-report matrix
• add Class and Department to Read Master Data so report filter IDs are discoverable
• preserve native QuickBooks report headers, columns, nested rows, summaries, IDs, and links

Scope decisions

• General Ledger is omitted because the sandbox returned QBO permission fault 5020 for GeneralLedgerDetail
• transaction-type filtering is omitted because the tested parameter was silently ignored rather than proven
• custom columns, multi-ID filters, Transaction List, and Inventory Valuation remain follow-up work
• no OAuth, API-route, retry, pagination, caching, or mutation behavior was added

Safety

• fixed report endpoints only; unsupported report/filter combinations fail before fetch
• one GET per execution with retries disabled
• existing minorversion=75, sandbox/production host selection, OAuth headers, fault handling, and 8 MiB response cap are reused
• empty native reports remain successful; malformed report wrappers fail clearly

Validation

• 13 QuickBooks-related test files / 515 tests
• live sandbox contract proof for all 14 reports and Class/Department; final-code smoke for Profit and Loss and A/P Aging Summary
• independent gpt-5.6-sol high-reasoning full-stack review against staging: no actionable findings
• TypeScript, format, lint, tool metadata, docs, API validation, bare icons, client boundaries, and git diff --check

Stack

• base: feat/quickbooks-04a-po-bill-linking
• this PR is intentionally stacked and must not be merged before its parent

[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:51pm

[cursor]

PR Summary

Medium Risk
Large integration surface with external QuickBooks calls, outbound email, and file upload/download paths; mitigated by contracts, size limits, auth checks, and pinned fetches for attachment URLs.

Overview
Expands the QuickBooks block from bounded transaction/master-data work into accountant reporting, document delivery, and richer read filters, with matching docs and integration metadata (47 operations).

Run Financial Report adds a fixed matrix of QuickBooks financial statements, aging, balance, sales, and expense reports plus Transaction List, with per-report controls (dates, cash/accrual, summarize-by, entity filters, aging). Responses keep native header, columns, and nested rows. Read Master Data now includes Class and Department (and list active status) so report filter IDs are discoverable.

Employee create/update (non-payroll), date range and customer/vendor filters on transaction list reads, and email transaction, download transaction PDF, and attachment read/add/download round out the workflow surface. Document flows use new API routes with internal auth, file size caps, workspace file authorization for uploads, and DNS-pinned fetches for short-lived attachment URLs; downloads land as Sim execution/copilot files.

secureFetchWithPinnedIP now respects abort signals before opening requests and during redirect DNS validation. Broad test coverage includes document API routes and report matrix tests.

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

[greptile-apps]

Greptile Summary

The PR adds a bounded QuickBooks financial-report operation covering 14 report types and extends master-data discovery with Class and Department.

• Defines a fixed report endpoint and supported-control matrix with date, accounting-basis, summarization, entity-filter, and aging validation.
• Preserves native QuickBooks report headers, columns, nested rows, IDs, and links in workflow outputs.
• Registers the new tool across the QuickBooks block, tool registry, generated metadata, documentation, and tests.
• Adds Class and Department list/by-ID reads so workflows can discover report-filter identifiers.

Confidence Score: 5/5

The PR appears safe to merge after its stated parent branch, with no concrete changed-code failure identified.

The report operation is consistently wired through the block, registry, request builder, response contract, generated metadata, documentation, and tests, while unsupported controls are rejected or discarded before the outbound request.

Important Files Changed

Filename	Overview
apps/sim/tools/quickbooks/utils.ts	Adds the fixed report matrix, validation, URL construction, native response transformation, and Class/Department entity mappings without an accepted defect.
apps/sim/tools/quickbooks/run_financial_report.ts	Defines a bounded OAuth-backed GET tool with retries disabled, an 8 MiB response limit, and structured native report outputs.
apps/sim/blocks/blocks/quickbooks.ts	Adds report-specific controls, visibility rules, post-resolution parameter coercion, stale-control filtering, and conditional outputs.
apps/sim/tools/quickbooks/types.ts	Adds report, Class, and Department contracts plus nested output metadata aligned with the new operation.
apps/sim/tools/quickbooks/read_master_data.ts	Extends the existing master-data reader to expose Class and Department through the established list and by-ID paths.
apps/sim/tools/quickbooks/reports.test.ts	Covers all report endpoints, supported controls, validation failures, output preservation, response limits, UI conditions, and master-data discovery.
apps/sim/tools/registry.ts	Registers the new financial-report tool consistently with the block access list and QuickBooks barrel export.
apps/docs/content/docs/en/integrations/quickbooks.mdx	Documents report inputs, native outputs, Class/Department discovery, and the intended performance guidance.

Sequence Diagram

sequenceDiagram
  participant Workflow
  participant Block as QuickBooks Block
  participant Tool as Financial Report Tool
  participant QBO as QuickBooks Online
  Workflow->>Block: report type and supported controls
  Block->>Block: resolve values, coerce aging days, discard stale controls
  Block->>Tool: normalized report parameters and OAuth credential
  Tool->>Tool: validate support matrix and construct fixed URL
  Tool->>QBO: bounded GET, retries disabled
  QBO-->>Tool: native Header, Columns, Rows
  Tool->>Tool: validate report wrapper
  Tool-->>Workflow: preserved native report output

Loading

_{Reviews (1): Last reviewed commit: "feat(quickbooks): expose reports in bloc..." | 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 1edbb50. Configure here.}