WhatsApp commerce: MVP, template manager, cart recovery + strategy and audit docs

[bpalmer77fluid]

Summary

Takes the WhatsApp commerce scaffold (merged in #2) from "compiles and demonstrates the flow" to a deployable sandbox MVP with the two highest-ROI automations, plus the strategy and execution docs built around it.

Code

MVP completion (the four scaffold TODOs)

• Signature verification — config/fastify.ts preserves the raw JSON body; routes/whatsapp.ts verifies X-Hub-Signature-256 over the raw bytes and enforces it whenever WHATSAPP_APP_SECRET is set (401 on mismatch)
• Meta catalog sync — WhatsAppService.syncProductToCatalog via the Commerce Manager items_batch upsert (retailer_id = Fluid SKU), triggered fire-and-forget from the existing Fluid product webhook so catalog failures never block webhook processing
• Fluid order integration — new services/fluidService.ts creates rep-attributed orders on cart submission (DIT token) and marks them paid on M-Pesa settlement; mpesa_payments carries the fluidOrderId link, with local orders as the fallback source of truth
• Multi-tenant routing — new whatsapp_configs model maps phoneNumberId → installation (plus accessToken, catalogId, wabaId); env vars remain the single-tenant fallback, and every outbound send is tenant-aware

Template manager — identified as the critical path, since every out-of-window message requires an approved template

• MessageTemplate model + services/templateService.ts
• Pre-built, compliance-reviewed library of six templates (cart recovery ×3, receipt, order status, payment failed) — all UTILITY category, no health or income claims
• Submits to Meta's message_templates API with the placeholder examples review requires; polls approval status
• routes/templates.ts: library / list / seed / submit / sync, so a client never opens the Meta console

Abandoned-cart recovery — benchmarks: 18–23% recovery, automated flows drive 60–70% of WhatsApp revenue

• CartRecovery model + services/cartRecoveryService.ts
• 30 min / 24 h / 72 h arc, scheduled when the STK push fires, cancelled on payment success, reconciled against paid orders before every run so a race can't nag a paid customer
• 24-hour window handled correctly: plain text inside the window (checked via whatsapp_sessions.lastMessageAt), approved template outside it, and skip rather than send non-compliantly
• Bug fix: the payment-failure message told customers to "reply pay" but no handler existed. pay/lipa now re-fires the STK push for the open cart and writes a fresh payment row for the callback to settle; cancel/stop close the arc. Keyword handling runs before the catalog fallback.
• routes/jobs.ts: secret-protected POST /api/jobs/cart-recovery runner (cron-friendly, multi-instance safe) plus an optional in-process interval for demo boxes

Hardening

• Daraja callback: optional shared-secret guard (MPESA_CALLBACK_SECRET) and idempotent settlement (status = 'pending' guard so retries no-op)
• Session rep binding is explicitly first-touch; carts sent after the initial referral still attribute via the stored session rep

Docs

• docs/whatsapp-commerce-spec.md — updated for the template manager, recovery service, and the 24-hour window rule
• docs/whatsapp-demo-runbook.md — Track A (15-min no-code UX test) and Track B (full sandbox: Meta app + test number, Daraja sandbox, deploy, walk the flow, demo checklist), plus Meta account-integrity guidance
• docs/whatsapp-commerce-competitive-playbook.md — four-layer market map, deep study of Yalo / Haptik / charles, conversion benchmarks with the design rules they imply, ease-of-deployment bar, Fluid's differentiation (nobody else models a salesforce), capability gap analysis
• docs/whatsapp-tech-provider-strategy.md — three-stage path (demo → BSP pilot → Meta Tech Provider) with stage gates, Meta requirements, business model options, market sequencing by payment rail, risks, 90-day plan, metrics
• docs/whatsapp-cx-strategy-handoff.md — handoff package for the next phase: a copy-pasteable prompt directing a fresh session to research best-of-breed WhatsApp commerce providers and produce the client-experience strategy + skill-ready deployment playbook (assumes the Meta Commerce API integration layer is handled separately), plus a standalone context brief
• docs/fl-localization-audit-brief.md — brief for an agent with live browsing access to audit FL's localization strategy (Canada as benchmark), with six hypotheses to verify or falsify
• docs/mist-handoff-1-fidelity.md — process to bring the scraped Fluid clone to parity with the live FL Kenya page, including an Intentional Divergence list so deliberate additions survive the pass
• docs/mist-handoff-2-improvements.md — additive-only conversion tweaks (in-place edits and inserted bands, no redesign), including replacement options for the low-yield "Aloe as Nature Intended" graphic
• docs/forever-living-kenya-teardown.md / -competitive-landscape.md — added the Kyte shadow-commerce finding: reps already DIY WhatsApp storefronts, which validates demand and locates the moat

Verification

• tsc --noEmit passes; prisma validate passes; Prisma client regenerates cleanly
• Fluid order create/pay endpoint shapes follow this template's existing v1 API usage and are flagged for confirmation against current Fluid API docs before production
• Recovery messages currently address customers neutrally ("there") because the Cloud API exposes no verified profile name — pull the real name from the Fluid customer record once the order integration is confirmed
• Remaining P1 from the playbook gap table: order-status / delivery updates (template exists, needs a trigger on Fluid fulfillment events)
• The audit/handoff briefs were written without live access to foreverliving.com or forever-living-kenya.fluid.app (both egress-blocked in the authoring environment), so their findings are framed as labeled hypotheses for the executing agent to confirm or correct