wulf-pulse/.planning/quick/260718-9qg-create-a-quickbooks-online-integration-h/260718-9qg-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
quick-260718-9qg	01	execute	1		QBO_INTEGRATION_HANDOFF.md	true	DOC-QBO-HANDOFF	truths artifacts key_links A reader with NO access to the Pulse codebase can understand Pulse's QBO integration end to end from this one file The full OAuth2 authorization-code flow is documented step by step (authorize → callback → token exchange → storage → refresh) Env vars, API base URLs (sandbox vs production), scopes, and minor version are stated explicitly Known gotchas — including anything learned from the recent QBO AR diagnostics work — are captured path provides min_lines QBO_INTEGRATION_HANDOFF.md Self-contained QBO integration handoff document for a new app 120

Produce a single standalone markdown document, `QBO_INTEGRATION_HANDOFF.md` at the repo root, that captures everything Pulse knows about connecting to QuickBooks Online (QBO), so a separate new application's team — who will NOT have access to the Pulse codebase — can implement their own QBO integration with a head start.

Purpose: Transfer hard-won integration knowledge (OAuth2 flow, token storage/refresh, API base URLs, scopes, gotchas) to a team building a brand-new app. Output: QBO_INTEGRATION_HANDOFF.md (new file, repo root).

Docs-only task. No application source code may be modified. The only file written is the handoff document.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/STATE.md

Known QBO surface in this repo (starting points for the executor's investigation — the executor MUST read these, not assume their contents):

• lib/services/qbo-client.ts — QBO API client (expect factory pattern per repo convention: getQboClient() / isQboConfigured())
• lib/services/qbo-sync-service.ts — sync service (invoices, AR, etc.)
• app/api/qbo/auth/route.ts — OAuth2 connect/authorize + callback handling
• app/api/qbo/sync/route.ts — sync trigger endpoint
• app/api/qbo/disconnect/route.ts — token teardown
• app/api/qbo/diagnose-ar/route.ts — AR (accounts receivable) diagnostics (likely source of recently-learned gotchas)
• migrations/051_create_qbo_tables.sql — QBO tables (token storage, invoices, etc.)
• migrations/088_qbo_invoices_soft_delete.sql — soft-delete addition
• No existing QBO guide under docs/ — this handoff is net-new.
• Note: .env did NOT surface QBO_* / QUICKBOOKS_* / INTUIT_* vars by name — the executor MUST grep the source for process.env. inside the QBO files to discover the ACTUAL env var names in use.

Task 1: Investigate Pulse's QBO integration and write the self-contained handoff doc QBO_INTEGRATION_HANDOFF.md First, INVESTIGATE the existing QBO integration in this repo. Do not write anything until the investigation is complete. Read (not skim) each of the following and extract the concrete details:

1. Env vars — grep the QBO files for process.env. to find the REAL variable names, then record each: client id, client secret, environment (sandbox vs production toggle), redirect/callback URI, realm/company id, and any discovery or token endpoint overrides. Command hint: grep -rn "process\.env\." lib/services/qbo-client.ts lib/services/qbo-sync-service.ts app/api/qbo/.

2. OAuth2 authorization-code flow — from app/api/qbo/auth/route.ts and lib/services/qbo-client.ts, capture: the authorize URL (Intuit appcenter.intuit.com/connect/oauth2), the requested scopes (e.g. com.intuit.quickbooks.accounting), the state handling / CSRF protection, the redirect URI, the token-exchange URL (oauth.platform.intuit.com/oauth2/v1/tokens/bearer), the token-refresh flow, and how the realmId (company id) is received on the callback.

3. Token storage — from migrations/051_create_qbo_tables.sql (and 088), document the exact table(s) and columns used to persist access token, refresh token, realm/company id, and expiry timestamps; and from the client code, how expiry is detected and refresh is triggered (proactive vs on-401).

4. API base URLs & versioning — record the sandbox base (sandbox-quickbooks.api.intuit.com) vs production base (quickbooks.api.intuit.com), the minorversion query param if used, and the request path shape (/v3/company/{realmId}/...).

5. What QBO is used for in Pulse — read lib/services/qbo-sync-service.ts and the api routes to summarize the entities synced (invoices, AR, payments/deposits) and the direction of data flow.

6. Gotchas / lessons learned — read app/api/qbo/diagnose-ar/route.ts and run git log --oneline -20 -- app/api/qbo lib/services/qbo-client.ts lib/services/qbo-sync-service.ts migrations/051_create_qbo_tables.sql migrations/088_qbo_invoices_soft_delete.sql (and inspect the "QBO AR diagnostics" work referenced in the recent chore: check in pending work commit) to fold in any real gotchas: rate limits, token-refresh failures, sandbox-vs-production quirks, AR/invoice reconciliation issues, soft-delete handling, realm mismatch, etc. Also check the completed quick-task dirs under .planning/quick/ matching *qbo* (e.g. 260519-0oz-add-qbo-createpayment-createdeposit, 260521-fci-stopgap-nightly-reconciliation) for SUMMARY notes worth distilling.

Then WRITE QBO_INTEGRATION_HANDOFF.md at the repo root as a self-contained document. It MUST be readable by someone with zero access to this codebase: inline every relevant detail; do NOT leave bare "see lib/services/qbo-client.ts" pointers — if a detail lives in a Pulse file, summarize the detail itself. Pulse file paths may appear only as parenthetical "(in Pulse this lives in …)" provenance notes, never as the sole carrier of information.

Structure the document roughly as:

• Overview — what QBO integration does and why (the business purpose).
• Prerequisites — creating an Intuit Developer app, sandbox vs production, redirect URI registration, required scopes.
• Environment variables — a table of every env var (real names discovered from source) with description and example/placeholder value. Do NOT copy any real secret values from .env; use placeholders.
• OAuth2 connection flow — a numbered, step-by-step walkthrough: authorize redirect → user consent → callback with code + realmId → token exchange → persistence → subsequent refresh. Include the exact Intuit URLs.
• Token storage & refresh — the table schema (columns + purpose) and the refresh strategy, generalized so the new app can adapt it (they may not use Postgres).
• API usage — base URLs (sandbox/production), path shape, minor version, an example authenticated request.
• Gotchas & lessons learned — the concrete pitfalls gathered in the investigation.
• Minimal code-flow example — a distilled, framework-agnostic pseudocode/TypeScript sketch of authorize → exchange → refresh → call (NOT a copy-paste of Pulse code; enough that a QBO-unfamiliar team can implement their own).

Write directive prose and generalized examples. Do NOT modify any application source, migrations, env files, or existing docs. test -f QBO_INTEGRATION_HANDOFF.md && test $(grep -v '^#' QBO_INTEGRATION_HANDOFF.md | wc -l) -ge 100 && grep -qi 'oauth' QBO_INTEGRATION_HANDOFF.md && grep -qi 'refresh' QBO_INTEGRATION_HANDOFF.md && grep -qiE 'sandbox|production' QBO_INTEGRATION_HANDOFF.md && echo OK QBO_INTEGRATION_HANDOFF.md exists at repo root, is self-contained (no information-bearing bare file-path pointers), and covers overview, prerequisites, env vars, the full OAuth2 flow, token storage/refresh, API base URLs (sandbox + production), gotchas, and a minimal code-flow example. No application source, migration, env, or existing doc files were modified.

- `git status` shows exactly one new file (`QBO_INTEGRATION_HANDOFF.md`) and no modifications to existing tracked source/docs/migrations. - The document contains no real secret values (placeholders only). - Every major section (overview, prerequisites, env vars, OAuth2 flow, token storage/refresh, API URLs, gotchas, code example) is present and populated with concrete detail drawn from the repo investigation.

<success_criteria> A new-app engineer can read QBO_INTEGRATION_HANDOFF.md alone and understand how to register an Intuit app, run the OAuth2 authorization-code flow, store and refresh tokens, hit the correct sandbox/production API endpoints, and avoid the pitfalls Pulse already hit — without ever opening the Pulse codebase. </success_criteria>

Create `.planning/quick/260718-9qg-create-a-quickbooks-online-integration-h/260718-9qg-SUMMARY.md` when done.