OUT-3742: tighten QBO Fault handling + bind SQL projections to row schemas

[SandipBajracharya]

Problem

• assertNotQBFault only read code on the non-array branch, so APIError.status was always 400 for real QBO faults.
• 8 hand-written QBO SELECT projections drifted from their row schemas — typos/required-key changes only surfaced at runtime.

Shipped

• Tightened QBFaultSchema; simplified assertNotQBFault to read errors[0]?.code. Clamp non-HTTP statuses in withErrorHandler.
• 4 typed constants (QB_INVOICE_COLUMNS, QB_ITEM_COLUMNS, QB_CUSTOMER_COLUMNS, QB_ACCOUNT_COLUMNS) bind each SELECT to its row schema via satisfies. Regression test guards required-key supersets.
• Drive-bys: handleInvoiceDeleted throws on non-voided delete; getMessageAndCodeFromError guards an empty errors[].

Code sites

• src/type/dto/intuitAPI.dto.ts
• src/utils/intuitAPI.ts
• src/app/api/core/utils/withErrorHandler.ts
• src/app/api/quickbooks/invoice/invoice.service.ts
• src/utils/error.ts
• test/unit/utils/intuitAPI.{responses,queryColumns}.test.ts

Behavior change

• qb_sync_logs.failed_record_category for live 6000/6190 faults now resolves to ACCOUNT (was QB_API_ERROR) because getCategory reads the real status. HTTP response still 400.

[linear-code]

OUT-3742

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Building		May 15, 2026 0:33am
quickbooks-sync (dev)	Ready	Preview, Comment	May 15, 2026 0:33am

[greptile-apps]

Greptile Summary

This PR fixes two related bugs: assertNotQBFault was always producing status 400 for QBO faults because it only read code on the non-array branch, and 8 SQL SELECT projections had drifted from their row schemas. The changes introduce a typed QBFaultErrorSchema with safe code coercion, four QB_*_COLUMNS constants bound to their schemas via satisfies, and a status clamp in withErrorHandler for non-HTTP QBO codes.

• Fault handling: QBFaultSchema.Fault.Error is now a strictly typed array; assertNotQBFault reads errors[0]?.code; withErrorHandler clamps QBO fault codes (e.g. 6240) to 400 before returning the HTTP response.
• SQL projection binding: Four QB_*_COLUMNS constants use as const satisfies ReadonlyArray<keyof RowType> so a typo or stale field name fails at compile time; a new regression test checks each constant stays a superset of its schema's required keys.
• Drive-bys: handleInvoiceDeleted now throws on non-voided deletes; getMessageAndCodeFromError guards against an empty errors[].

Confidence Score: 4/5

Safe to merge with one fix: QBFaultSchema strict array check silently drops faults whose Error field is null or a non-array object.

The core fault-handling path now silently swallows a QBO Fault response whenever Fault.Error is null or arrives as a non-array shape — safeParse returns false and assertNotQBFault returns without throwing. The old schema (z.unknown().optional()) always succeeded and always threw. Replacing .optional().default([]) with .catch([]) closes the gap.

src/type/dto/intuitAPI.dto.ts — the QBFaultSchema.Fault.Error definition.

Important Files Changed

Filename	Overview
src/type/dto/intuitAPI.dto.ts	Introduces QBFaultErrorSchema with safe code coercion and tightens QBFaultSchema to expect a typed Error array; the strict array validation (.optional() without .catch) can silently swallow faults when Fault.Error is null or a non-array shape.
src/utils/intuitAPI.ts	Simplifies assertNotQBFault to read errors[0]?.code, adds four typed QB_*_COLUMNS constants bound via satisfies to their row schemas, and expands several SELECT projections to use these constants.
src/app/api/core/utils/withErrorHandler.ts	Clamps non-HTTP status codes (e.g., QBO 6240) to BAD_REQUEST before passing to NextResponse.json, preserving the original code in the errors payload.
src/utils/error.ts	Guards getMessageAndCodeFromError against empty errors[] by using optional chaining with a fallback, and removes the unsafe IntuitErrorType cast in favour of QBFaultErrorSchemaType.
src/app/api/quickbooks/invoice/invoice.service.ts	Changes handleInvoiceDeleted to throw instead of silently returning when a non-voided invoice delete is requested.
test/unit/utils/intuitAPI.queryColumns.test.ts	New regression test asserting each QB_*_COLUMNS constant is a superset of its schema's required keys and contains no keys absent from the schema.

Sequence Diagram

sequenceDiagram
    participant QBO as QBO API
    participant IA as IntuitAPI
    participant WEH as withErrorHandler
    participant Log as qb_sync_logs

    QBO->>IA: "Fault { Error: [{code: 6000, ...}] }"
    IA->>IA: "assertNotQBFault()<br/>QBFaultSchema.safeParse()<br/>errors[0].code to 6000"
    IA->>WEH: throw APIError(6000, msg, errors)
    WEH->>WEH: "getMessageAndCodeFromError()<br/>code = 6000, source = intuit"
    WEH->>WEH: "getCategory(code=6000) to ACCOUNT"
    WEH->>WEH: "httpStatusOut = clamp(6000) to 400"
    WEH->>Log: "FAILED, category=ACCOUNT"
    WEH-->>QBO: "HTTP 400 { error, errors }"

Loading

_{Reviews (4): Last reviewed commit: "chore(OUT-3742): switch Fault.code to tr..." | Re-trigger Greptile}

[SandipBajracharya]

@greptileai

[SandipBajracharya]

@greptileai

[SandipBajracharya]

@greptileai