PSA/ee/docs/plans/2026-02-06-qbo-client-migration-off-node-quickbooks/PRD.md

# PRD — QBO client migration off node-quickbooks

- Slug: `qbo-client-migration-off-node-quickbooks`
- Date: `2026-02-06`
- Status: Draft

## Summary

Replace the `node-quickbooks` SDK usage in `packages/integrations/src/lib/qbo/qboClientService.ts` with a small internal QuickBooks Online REST client built on `axios`, while keeping current behavior for query, create/update/read, and customer sync flows.

This is primarily a security-driven migration to remove a dependency chain anchored on deprecated `request`.

## Problem

- `packages/integrations/package.json` currently depends on `node-quickbooks`.
- `node-quickbooks@2.0.47` depends on `request@2.88.0`, which is deprecated and commonly appears in unresolved audit findings.
- We only use a narrow subset of QBO operations, but we currently pay the full dependency and risk surface of a legacy SDK.

## Goals

1. Remove `node-quickbooks` from this codebase and lockfile.
2. Preserve current functional behavior for all existing QBO integration flows.
3. Keep token refresh and secret storage behavior compatible with current tenant/app secrets.
4. Reduce security warnings related to the QBO SDK dependency chain.

## Non-goals

- Redesigning the QBO OAuth connect/callback routes.
- Adding new QBO entities beyond currently used capabilities.
- Reworking UI/UX for integration settings.

## Users and Primary Flows

- Billing admins fetch QBO Items, Tax Codes, and Terms from integration settings.
- Billing admins validate existing QBO connections (CompanyInfo checks).
- Company sync uses QBO customer lookup/create/update flows.

## UX / UI Notes

No user-facing UI changes are expected. Existing pages/actions should behave the same.

## Requirements

### Functional Requirements

- `QboClientService.create(tenantId, realmId)` continues to initialize a ready-to-use client.
- `query(selectQuery)` continues to support current query usage patterns (Item, TaxCode, Term, Customer, CompanyInfo).
- `create(entityType, data)`, `update(entityType, data)`, and `read(entityType, id)` continue to behave the same for current call sites.
- `findCustomerByDisplayName`, `createOrUpdateCustomer`, and sync-token logic remain behaviorally equivalent.
- 401 responses trigger a single token refresh and one retry for idempotent request paths currently retried.
- Error mapping remains compatible with existing `AppError` codes (`QBO_AUTH_ERROR`, `QBO_NOT_FOUND`, `QBO_STALE_OBJECT`, etc.).
- Multi-realm credential map storage format remains unchanged.

### Non-functional Requirements

- No increase in secret exposure risk (no tokens in logs).
- Keep TypeScript compile clean in affected packages.
- Remove `node-quickbooks` transitive dependency tree from lockfile.

## Data / API / Integrations

New internal REST layer targets Intuit QBO endpoints directly:

- `GET /v3/company/{realmId}/query?query=...`
- `GET /v3/company/{realmId}/companyinfo/{realmId}`
- `POST /v3/company/{realmId}/{entityType}` (create)
- `POST /v3/company/{realmId}/{entityType}?operation=update` (update)
- `GET /v3/company/{realmId}/{entityType}/{id}` (read)

Current known usage surface to preserve:

- `packages/integrations/src/actions/qboActions.ts`
- `packages/billing/src/services/companySync/adapters/quickBooksCompanyAdapter.ts`

## Security / Permissions

- Continue using `getSecretProviderInstance()` for app and tenant secrets.
- Keep credentials in `qbo_credentials` tenant secret JSON map keyed by `realmId`.
- Preserve RBAC checks already enforced in actions.

## Observability

- Keep current structured logs around QBO operations and failures.
- Preserve enough operation/entity context in errors for support/debugging.

## Rollout / Migration

### Batch 1 (commit 1)

- Introduce internal REST-backed implementation for `QboClientService` with behavior parity.
- Validate via typechecks/compiles only for this pass; unit test additions are deferred by request.
- Keep current call sites unchanged.

### Batch 2 (commit 2)

- Remove `node-quickbooks` dependency from `packages/integrations/package.json`.
- Refresh lockfile and validate dependency graph no longer includes `node-quickbooks`/`request` via this path.
- Run targeted tests and audit checks.

## Open Questions

- Do we want a short-lived fallback toggle to legacy SDK during rollout, or proceed directly with full cutover?
- Should update requests explicitly use sparse semantics for all entity updates, or only where currently required by behavior?
- Do we need to pin and expose a configurable QBO `minorversion` in the new REST implementation?

## Acceptance Criteria (Definition of Done)

- `node-quickbooks` is fully removed from package manifest and lockfile.
- Existing QBO flows still work:
  - item/tax/term catalog fetch
  - CompanyInfo validation
  - customer lookup/create/update sync flow
- QBO token refresh path still updates tenant secrets and retries failed auth once where expected.
- Error codes/messages remain compatible with existing handling paths.
- Targeted tests for QBO client/service pass.
- Security audit shows reduction of warnings associated with `node-quickbooks` dependency chain.