Final report — Joy integrations roadmap

What was done

Step Output
Read the two input documents (local copies) tong-quan-integration-va-ha-tang.md, ke-hoach-phat-trien-integrations.md, brief.md
Prod log analysis, 18 days (bucket retention limit), read-only via the support service account Roadmap section 4 (findings per integration, root-cause rollup in the user's five types)
Research: new apps, designs, existing integrations, infrastructure (with the per-integration map), architecture (today and target), potential apps research-*.md (6 reports)
Draft v1, then one normal review review-roadmap-v1.md
Cross-critique: 2 claude + 2 codex, two rounds critique-*.md, critique-*-round2.md
Reconcile (union of verified findings) reconcile-v3.md
Final verification on fable, every section against HEAD verify-final-fable.md
Independent critique on gpt-6-astra critique-astra.md
Scope pass: integrations only scope-review-fable.md (v6)
Rewrite into a work-first document roadmap-v7.md, rewrite-v7-report.md
Partner-API verification against official documentation, 32 claims in two reports (no partner API called) verify-partner-api-A.md (marketing and messaging), verify-partner-api-B.md (Shopify, helpdesk, social, reviews, subscriptions, new apps)
Apply the verification to the roadmap roadmap.md v8, apply-partner-verify-report.md (every change, with its source claim)

Headline findings

  1. Joy has enough compute and queue throughput; what it lacks is reliable delivery. About 205,000 deliveries were dropped after rate limits in 18 days (Omnisend contacts, Klaviyo profiles, Omnisend events). These are log lines, not unique customers.
  2. Much of the noise is self-inflicted or "dead credential, keep calling": the admin probes apps that are not connected; Klaviyo, Mailchimp, Gorgias and Instagram credentials that are dead are never marked broken; the merchant gets no signal.
  3. Secrets and personal data leak into logs: Mailchimp merchant credentials, Recharge order addresses, Apple pass auth headers, SMTP recipients.
  4. Order webhooks were lost on "Task size too large" while Shopify was told success (344 in 18 days; 9 shops for the size error). The fix is in the plan (durable acceptance by reference), with a check of the affected orders before 25/11.
  5. New integrations, in order: Flow review templates, the F1 partner API, the Tapcart secure block, the Loop listing and exchange bonus (behind a demand gate), and a Postscript beta (behind gates). Joy can lead where no competitor does: points for choosing an exchange on Loop.

What the partner verification changed (v8)

Of the 32 claims checked, by the two reports' own summaries, 11 were confirmed, 18 were partly right, 1 was wrong as the roadmap used it and 2 could not be verified from documentation. No item was added or removed. The changes that alter a fix, not only its wording:

  1. One Retry-After rule does not exist. Only Klaviyo documents that header. Each adapter now owns its retry timing, and the worker never answers 429 or 503 to Cloud Tasks, because Cloud Tasks would slow the whole queue.
  2. Partner-side dedupe exists for Klaviyo and LINE only. Omnisend does not dedupe events that trigger automations, so ambiguous Omnisend events are quarantined from Wave 1. The deliveryId must be a UUID.
  3. Omnisend has left /v5 for a date-versioned API, sends no Retry-After header, and limits a brand to 400 requests a minute shared by all its integrations. The new adapters target the new version (decision 7).
  4. Shopify: the documented dedupe key is X-Shopify-Webhook-Id, and Joy dedupes on X-Shopify-Event-Id; a GraphQL throttle is HTTP 200 with a THROTTLED error; the existing bulk tag code replaces the whole tag array; Flow resends for 36 hours after a timeout, a 429 or a 5xx; the mandatory compliance webhooks must answer 401 to a bad HMAC.
  5. Reviews and subscriptions: Fera signs its webhooks with a JWT and Joy already holds the key, so it can be verified now; Yotpo cannot be signed. Recharge's signature is a SHA-256 of the API client secret and the body, a secret Joy does not store (decision 9).
  6. Smaller corrections: Attentive texts a person who is subscribed again (decision 8); LINE cannot duplicate a message on a 429; Gorgias invalid_client on 8 of 58 accounts points at the accounts before it points at Joy's client; an Instagram token must be refreshed before its 60-day expiry; Loop's topic is return and its payload has no "customer chose exchange" field; Okendo's trigger fires before moderation; the health UI shows one banner at most.

The work, in five groups (roadmap section 6)

  1. Stop data loss now, before BFCM (10 items, by 25/11).
  2. Fix existing integrations (22 items, per integration).
  3. Build the shared integration infrastructure (16 items: outcome log, registry, delivery worker, health service, verifiers, health UI and the rest).
  4. New integrations (7 items).
  5. Partner API and cleanup (7 items).

Every item states what to do, why, where in code, when it is done and what it depends on. Section 7 places the items in Wave 0 (20/11 → 01/12), Wave 1 (02/12 → 18/12), Wave 2 (21/12 → 18/01/2027) and Wave 3 (19/01 → 17/02/2027), and lists the seven safety gates (G-0 to G-6) that guard each production change.

Not verified

Decisions needed from Winn (roadmap section 8)

  1. Who staffs new-app work: hire, borrow a developer, or run the reliability-first fallback? Needed before Wave 1 starts on 02/12.
  2. The F1 plan and pricing rule, with product, by 25/11. It blocks F1, Loop and Tapcart's reach.
  3. Gorgias: is Joy's OAuth client still valid, and what changed on 05/11? By 25/11, before support contacts the Gorgias shops.
  4. Health thresholds: the false-positive limit, auto-disconnect (none until decided), and whether "degraded" is shown to merchants. Before Klaviyo enforcement in the week of 04/01.
  5. The policy for ambiguous sends that trigger an SMS, and the maximum replay age. Before the first such adapter in Wave 2; it gates the Postscript beta.
  6. Smax: still in use? Drain the stored batches or remove the code. Before Wave 3.
  7. Omnisend API version (new in v8): ask Omnisend when /v5 retires; the new adapters target the date-versioned API. Before the delivery-worker slice 1 is built.
  8. Attentive subscribe (new in v8): how does Joy learn that a customer is already subscribed, or does the bulk sync stop subscribing? Before item 2.10, in Wave 2.
  9. Recharge verification secret (new in v8): ask the 23 connected shops for their API client secret, or use a per-shop secret in the URL. Before the Recharge verifier, in Wave 2.

Decision 3 now carries its test (refresh one healthy Gorgias account and compare), and decision 5 now also covers Omnisend events and PushOwl pushes, with a replay-age limit per partner.