Testing instructions — Sendtonium Klaviyo Audit

App name: Sendtonium Klaviyo Audit
Developer: Sendtonium
Auth: OAuth 2.0 with PKCE (S256) — read-only scopes only
Purpose: Instant marketing health audit of a merchant's Klaviyo email/SMS program. We never write to Klaviyo, send messages, or change account settings.

After install, the app fetches Klaviyo account data, grades a 100+ point checklist across six categories, and shows an overall letter grade plus opportunities. An optional full web report supports screen-share walkthroughs.

Requested OAuth scopes (exact list)

• accounts:read
• campaigns:read
• flows:read
• forms:read
• lists:read
• metrics:read
• profiles:read
• segments:read
• subscriptions:read
• tags:read
• templates:read

Space-separated value used in authorize requests: accounts:read campaigns:read flows:read forms:read lists:read metrics:read profiles:read segments:read subscriptions:read tags:read templates:read

Important: Sendtonium account login is required before Klaviyo OAuth

Customers create or sign into a Sendtonium account first. Klaviyo OAuth is only started from an authenticated session. Access/refresh tokens are exchanged and stored server-side (encrypted at rest) and bound to the customer's lead via leads.user_id.

A. Install from Klaviyo App Marketplace (Install button)

1. Reviewer clicks Install on the Sendtonium listing in Klaviyo.
2. Browser opens https://app.sendtonium.com/api/klaviyo/install.
3. If not signed in to Sendtonium, the user is redirected to /account/login (with option to Create account at /account/signup — email + password). Signup immediately signs the user in; no email verification is required.
4. After authentication, Sendtonium creates/claims a lead owned by that user and continues to /account/connect → PKCE authorize → Klaviyo consent.
5. User reviews read-only permissions and clicks Allow (or Deny — see Testing details).
6. Callback stores encrypted tokens, starts the audit, and redirects to the score page /audit/[leadId]?token=….
7. Results also appear on the customer dashboard at /account.

B. Install from the Sendtonium app (partner side)

1. Open /account/signup or /account.
2. Create an account (email + password) and continue immediately—there is no email verification step—or sign in to an existing account.
3. From the dashboard, click Connect Klaviyo (or complete the intake form at /audit while signed in).
4. Approve scopes in Klaviyo → return to score page / dashboard with results.

C. Settings / reconnect

1. Open https://app.sendtonium.com/settings
2. Confirm the page shows Status: connected (not only Connect).
3. Click Disconnect Klaviyo and confirm. The page should show not connected, and Sendtonium should leave Klaviyo Integrations.
4. Optionally click Add another Klaviyo account to start a new OAuth install.

D. Uninstall

1. In Sendtonium: Integration settings → Disconnect Klaviyo (calls POST /oauth/revoke).
2. Confirm the app is no longer enabled under Klaviyo → Settings → Integrations.

All calls use Klaviyo REST revision 2025-10-15 with the merchant's OAuth access token. No write scopes are requested.

Data flow between Klaviyo and Sendtonium (read-only):

Merchant / Reviewer
        |
        |  (1) Install (Marketplace) or /audit form
        v
app.sendtonium.com
  /api/klaviyo/install  →  create lead
  /api/klaviyo/authorize →  PKCE state + code_challenge
        |
        |  (2) Redirect to Klaviyo OAuth consent
        v
klaviyo.com/oauth/authorize
        |
        |  (3) Allow → code + state
        v
/api/klaviyo/callback
  exchange code → access + refresh tokens (encrypted at rest)
  GET /api/accounts → store account id
        |
        |  (4) runAudit()
        v
Klaviyo REST API (revision 2025-10-15)
  accounts, flows, campaigns, metrics, lists, segments,
  templates, forms, tags, reports, metric-aggregates
        |
        +---- optional: headless capture of store_url
        |
        v
Supabase (audits, audit_results, report_content)
        |
        v
Score page  /audit/[leadId]?token=…
Optional report  /report/[auditId]

Tokens are AES-256-GCM encrypted. Service-role DB access is server-side only. Score/report pages require a per-lead reveal token (or admin session).

A recorded walkthrough of installation + use cases is available for the Ecosystem and Security teams. Request the latest Loom / video link from kyle@sendtonium.com (or use the link provided in the Manage App submission notes if attached).

Suggested demo script (2–4 minutes):

1. Start from Klaviyo Install URL → approve read-only scopes.
2. Show score page loading → overall grade + six categories.
3. Show flow quality chips and opportunities.
4. Optional: open full report if generated.
5. Show Settings page + how to revoke in Klaviyo.

Test plan — installation

1. Marketplace install (logged out): open Install URL in a private window → you are prompted to Create account or Sign in on Sendtonium (email + password) → account is created and signed in immediately, without email verification → Klaviyo OAuth consent appears → Allow → score page.
2. Marketplace install (already logged in): open Install URL while signed in to Sendtonium → goes straight to Klaviyo consent (no second partner login).
3. Partner-app install: create account at /account/signup → open /account → Connect Klaviyo → OAuth. Alternatively complete the intake form at /audit while signed in.
4. Settings install: open /settings → Connect Klaviyo → authenticate if needed → OAuth.
5. Deny permissions: on Klaviyo consent, click Deny / Cancel. You should return to Sendtonium with a clear message that permissions were not approved, and a path to retry after signing in again.

Test plan — functionality

1. Wait for audit status to leave “running” (usually under ~2 minutes).
2. Confirm overall grade/score, six category bars, flow quality section, and opportunity bullets render.
3. Confirm the score page URL includes ?token= and that opening the same path without the token does not show results (404 / not found).
4. Confirm the audit appears on /account while signed in.
5. Optional: if a full report is generated for the audit, open /report/[auditId] (admin session or share token).

Test plan — uninstall

1. In Klaviyo, remove/revoke the Sendtonium app.
2. Attempting a new audit without re-consent should fail to use prior tokens; merchant must reinstall / reconnect while signed in to Sendtonium.
3. Settings page documents revoke steps: /settings.

Expected permissions screen copy

Reviewers should see only the read scopes listed in Overview (accounts, campaigns, flows, forms, lists, metrics, profiles, segments, subscriptions, tags, templates — all :read). No write scopes.

• Install URL directs as expected — /api/klaviyo/install requires a Sendtonium session first, then starts PKCE and redirects into Klaviyo authorize.
• Works logged in / not logged in to partner app — logged out users are redirected through signup/login; logged-in users go straight to OAuth.
• Settings URL — /settings
• Deny permission workflow — clear incomplete/denied messaging + retry path via /audit.
• Client-facing docs — /user-guide, privacy policy, settings.
• Support — kyle@sendtonium.com

Related pages: User guide · Settings · Privacy policy