OUT-3539: extract findOrMapInvoiceFromQBO helper for invoice sync resilience

[SandipBajracharya]

Summary

• Adds findOrMapInvoiceFromQBO() helper that queries QBO by invoice number, resolves/creates the customer mapping, and inserts a qb_invoice_sync row when found
• Integrates the helper into all 4 webhook handlers (created, paid, voided, deleted) as a fallback when no local mapping exists
• Refactors checkIfInvoiceExistsInQBO() to delegate to the new helper, so existing callers (syncMissedInvoices, backfillTimedOutInvoices) automatically gain mapping creation

Problem

When an invoice is manually created in QBO, our app tries to create the same invoice and fails. Subsequent invoice.paid, invoice.void, and invoice.delete events also silently skip because no qb_invoice_sync mapping row exists in our database.

Test plan

• Invoice exists in QBO but not in local DB → created webhook maps it and skips creation
• paid / voided / deleted webhooks with unmapped invoice → maps from QBO and proceeds
• Invoice already mapped locally → handlers continue as before (no extra QBO API call)
• Invoice not in QBO at all → handlers silently return as before
• Calling findOrMapInvoiceFromQBO twice for the same invoice does not create duplicates

🤖 Generated with Claude Code

[linear]

OUT-3539 Extract "find-or-map" helper for invoice sync resilience

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync (dev)	Ready	Preview, Comment	Apr 23, 2026 0:40am
quickbooks-sync	Ready	Preview, Comment	Apr 23, 2026 0:40am

[greptile-apps]

Greptile Summary

This PR introduces findOrMapInvoiceFromQBO, a helper that queries QBO by invoice number, resolves the customer mapping, and creates a qb_invoice_sync row when a locally unmapped invoice is found. It is wired into all four webhook handlers (created, paid, voided, deleted) as a fallback path and refactors checkIfInvoiceExistsInQBO to delegate to it.

• P1 — wrong payment amount: findOrMapInvoiceFromQBO stores amount: total.toFixed(2) (raw dollars) in the CREATED sync log, but webhookInvoicePaid reads invoiceAmount = Number(amount) / 100. Every payment created via the new fallback path will be sent to QBO at 1/100th of the correct value (e.g. $1.00 for a $100 invoice). The fix is (total * 100).toFixed(2), matching the convention at line 790.
• P2 — no idempotency inside the helper: findOrMapInvoiceFromQBO calls createQBInvoice without first checking for an existing row; concurrent webhook deliveries or retries will hit a unique-constraint failure rather than a graceful short-circuit.

Confidence Score: 3/5

Do not merge until the ×100 amount bug is fixed — payments created via the fallback path will be 100× too small in QBO.

A P1 financial bug causes QBO payments to be created at 1/100th of the correct amount whenever the new findOrMapInvoiceFromQBO helper is the first to record the CREATED sync log. This directly corrupts payment records in QBO and must be fixed before merging.

src/app/api/quickbooks/invoice/invoice.service.ts — specifically the amount and taxAmount fields in the logSync call inside findOrMapInvoiceFromQBO, and the DELETED-event log amount in handleInvoiceDeleted.

Important Files Changed

Filename	Overview
src/app/api/quickbooks/invoice/invoice.service.ts	Extracts findOrMapInvoiceFromQBO helper and integrates it into all 4 webhook handlers; P1 bug: amounts stored without ×100 factor, causing payments sent to QBO to be 100× too small when the helper creates the CREATED sync log.
src/app/api/quickbooks/syncLog/syncLog.service.ts	Adds softDeleteLogsByCopilotId method; correctly scoped to workspace and uses isNull(deletedAt) guard to prevent double-deletion. No issues found.

Sequence Diagram

sequenceDiagram
    participant W as Webhook Handler
    participant IS as InvoiceService
    participant DB as Local DB
    participant QBO as QuickBooks Online

    W->>IS: webhookInvoicePaid / Voided / Deleted / Created
    IS->>DB: getInvoiceByNumber()
    alt mapping found
        DB-->>IS: invoiceSync row
        IS->>IS: proceed with normal flow
    else no mapping
        DB-->>IS: null
        IS->>IS: findOrMapInvoiceFromQBO()
        IS->>QBO: getInvoice(invoiceNumber)
        alt invoice in QBO
            QBO-->>IS: qbInvoice {Id, SyncToken}
            IS->>DB: createQBInvoice (mapping row)
            IS->>DB: logSync CREATED — amount=total.toFixed(2) missing x100
            IS-->>W: invoiceSync = mappedInvoice
            W->>W: paid path: amount divided by 100 → payment 100x too small
        else invoice not in QBO
            QBO-->>IS: null
            IS-->>W: null → throw or return
        end
    end

Loading

_{Reviews (1): Last reviewed commit: "fix(OUT-3539): log subsequent invoice ev..." | Re-trigger Greptile}

[priosshrsth]

Won't this cause regression?

[SandipBajracharya]

This shouldn’t cause any regression. The change is only in the invoice void/delete function, and we’re not actually using the total amount for syncing anyway—it’s just there for logging.

[priosshrsth]

lgtm