feat(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 9, 2026 11:03am
quickbooks-sync	Ready	Preview, Comment	Apr 9, 2026 11:03am