OUT-3543: Type and Zod-validate IntuitAPI responses

[SandipBajracharya]

Summary

Brings every IntuitAPI method onto a uniform Zod-parse-at-boundary contract and removes any from the IntuitAPI surface. Linear: OUT-3543.

Before: ~5 methods parsed; ~13 returned raw responses with no validation. Three as any casts, one Record<string, any> body, three inline TS interfaces, _customQuery typed as any.

After:

• Every method ends with Schema.parse(raw) and declares Promise<z.infer<typeof Schema>>.
• _customQuery: Promise<unknown> — every caller parses an envelope before reading fields.
• Three hoisted overload types replace as any with as unknown as XxxOverloads.
• postFetchWithHeaders + postFetcher body narrowed to unknown.
• Row + envelope decomposition applied uniformly across Item / Account / Invoice / Payment / Purchase, with dedicated delete and query envelopes.

$ rg ': any|<any>|as any' src/utils/intuitAPI.ts src/type/dto/intuitAPI.dto.ts
(empty)

Out of scope

Documented in docs/superpowers/specs/2026-05-12-out-3543-intuit-response-types-design.md. Briefly: copilotAPI.ts catch-block narrowing, withRetry / withErrorHandler generics, axios error guards, framework-boundary any (logger / crypto / swr / module decls). Copilot webhook + request-body Zod schemas were already in place pre-branch — the work concentrated on response types where the gap was.

Design choices

• .passthrough() not used; consumers only read modeled fields, default .strip() matches intent.
• Fault checks stay imperative (separate from shape parsing).
• _customQuery returns unknown; callers parse the envelope matching their SQL.
• CustomerListEnvelopeSchema wraps CustomerQueryResponseSchema directly (no duplicate row schema).

Follow-ups (not blockers)

• CI test gap: integration tests mock @/utils/intuitAPI entirely, so production .parse never runs in CI. Worth a separate ticket: unit suite parsing captured real QBO sample responses against each schema.
• postFetcher returns Promise<any> — local invoice / item between fetch and parse is any; .Fault checks read off any. Out of scope but worth tightening next.

Test plan

• npx tsc --noEmit — clean
• npx vitest run --project unit — 77/77 pass
• yarn lint:check / yarn prettier:check — clean
• Full suite at branch HEAD — 87/87 (5 unit + 7 integration via testcontainers)
• Smoke against QBO sandbox before un-drafting (createItem / createCustomer / createInvoice / createPayment / createPurchase / void / delete)

🤖 Generated with Claude Code

[linear-code]

OUT-3543

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Ready	Preview, Comment	May 13, 2026 9:19am
quickbooks-sync (dev)	Ready	Preview, Comment	May 13, 2026 9:19am

[greptile-apps]

Greptile Summary

This PR brings every IntuitAPI method onto a uniform Zod-parse-at-boundary contract, eliminating all any from the public surface and replacing thirteen duplicated fault-check blocks with a single assertNotQBFault helper.

• New Zod schemas: ~15 row/envelope/delete schemas added to intuitAPI.dto.ts; PrimaryEmailAddr.Address made .nullish() to survive malformed QBO rows without poisoning paginated walks.
• Typed return values: Every public method now declares an explicit Promise<XxxType> return; _customQuery widens to Promise<unknown> and callers parse their own envelopes.
• Test coverage: New intuitAPI.responses.test.ts exercises the production .parse paths against canonical QBO shapes for all major read and write methods; existing getCustomerByEmail tests updated to match the revised schema.

Confidence Score: 5/5

Safe to merge — all fault-check logic is preserved and the new Zod parse boundary is additive, not destructive.

Every mutation is either narrowing an any to a concrete type or adding a .parse() call after an already-passing fault check. assertNotQBFault correctly uses safeParse and only throws when Fault is genuinely present. The two style observations have no runtime impact.

No files require special attention for correctness. The double-parse in _getAllItems and inline schema duplication in intuitAPI.dto.ts are worth cleaning up in a follow-on.

Important Files Changed

Filename	Overview
src/utils/intuitAPI.ts	Major refactor: all methods gain return types, assertNotQBFault replaces duplicated fault-check blocks, _customQuery returns unknown, overload types hoisted. One schema redundancy in _getAllItems (double-parse) noted.
src/type/dto/intuitAPI.dto.ts	Adds ~15 new Zod schemas and types for rows, envelopes, and delete responses; PrimaryEmailAddr.Address made nullish; QBItemsResponseSchema still has its own inline schema rather than reusing the new QBItemRowSchema.
test/unit/utils/intuitAPI.responses.test.ts	New 20-test suite exercising the production Zod parse paths against canonical QBO shapes for all key read and write methods. Several write paths are not yet covered.
test/unit/utils/intuitAPI.test.ts	Updated row() helper and test for null/nullish PrimaryEmailAddr to match the schema change.
src/helper/fetch.helper.ts	Narrows postFetcher body from Record<string, any> to Record<string, unknown>; safe, no logic changes.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant IntuitAPI
    participant QBO as QBO API
    participant Zod

    Note over IntuitAPI: POST-based writes (createInvoice, createCustomer, etc.)
    Caller->>IntuitAPI: createInvoice(payload)
    IntuitAPI->>QBO: POST /invoice
    QBO-->>IntuitAPI: raw: unknown
    IntuitAPI->>IntuitAPI: if (!raw) throw APIError
    IntuitAPI->>Zod: QBFaultSchema.safeParse(raw)
    alt Fault response
        Zod-->>IntuitAPI: "success=true"
        IntuitAPI-->>Caller: throw APIError
    else Valid response
        Zod-->>IntuitAPI: "success=false"
        IntuitAPI->>Zod: QBInvoiceResponseSchema.parse(raw)
        Zod-->>IntuitAPI: parsed: QBInvoiceResponseType
        IntuitAPI-->>Caller: parsed
    end

    Note over IntuitAPI: Query-based reads
    Caller->>IntuitAPI: getAllItems(limit)
    IntuitAPI->>QBO: GET /query
    QBO-->>IntuitAPI: raw: unknown
    IntuitAPI->>IntuitAPI: assertNotQBFault(raw)
    IntuitAPI->>IntuitAPI: return raw.QueryResponse
    IntuitAPI->>Zod: QBItemQueryResponseSchema.parse(queryResponse)
    Zod-->>IntuitAPI: envelope
    IntuitAPI->>Zod: QBItemsResponseSchema.parse(envelope.Item)
    Zod-->>IntuitAPI: result: QBItemsResponseType
    IntuitAPI-->>Caller: result

Loading

_{Reviews (2): Last reviewed commit: "fix(OUT-3543): address Greptile review —..." | Re-trigger Greptile}

[SandipBajracharya]

@greptileai