Affiliates

Affiliation Program

Account-centric partner program for marketers and content creators. Distinct from referrals: cash commissions paid via Stripe Connect (not in-app credits), application + admin approval required, and tier-based commission models (recurring monthly or one-time upfront). The system is feature-gated via the AFFILIATES_ENABLED environment variable (server-only) and surfaces as 404 when disabled. Phases 1 and 2 ship the application workflow, tracking, conversion ledger, and admin console; Stripe Connect onboarding + monthly payouts land in Phase 3.

Feature Gate

Set AFFILIATES_ENABLED=true to activate the public landing page, application form, user dashboard, tracking redirect, and admin console. The flag is read once inside config/affiliates.ts and exposed as affiliatesConfig.enabled / isAffiliatesEnabled(). A second env var AFFILIATES_SALT (server-only, distinct from REFERRAL_SALT and LOGS_SALT) is used to hash visitor IPs before storage.

Configuration (config/affiliates.ts)

Per-Tier Commission Model

The subscriptionModel field decides what happens on subscription invoices. Per-affiliate overrides on the affiliates row (subscription_model_override, upfront_multiplier_override, hold_period_days_override, default_commission_pct, cookie_window_days) win over the tier defaults.

Attribution Flow

1. Visitor hits /?aff=ABCD123XYZ  or  /[locale]/affiliate/ABCD123XYZ
            │
            ▼
2. Middleware / route — regex-validates code, sets httpOnly bsk_aff
   cookie (Secure, SameSite=Lax). Tracking redirect fires
   record_affiliate_click RPC (fire-and-forget).
            │
            ▼
3. User signs up → onboarding completes
            │
            ▼
4. Onboarding form fires POST /api/affiliates/attribute. Server reads
   bsk_aff cookie, calls attribute_affiliate RPC, clears cookie.
   Self-referral, same-owner, one-per-lifetime, IP rate-limit guards.
            │
            ▼
5. affiliate_attributions row inserted (status='active', expires_at
   = now + per-tier cookieWindowDays). Persistent record — survives
   cookie expiry.
            │
            ▼
6. When billing event fires (Stripe webhook), maybeRecordAffiliateConversion
   resolves attribution + tier policy + commission math, calls
   record_affiliate_conversion RPC. Idempotent on stripe_event_id.
            │
            ▼
7. Daily cron (approve-mature-affiliate-conversions) flips pending
   conversions to approved after the per-affiliate hold period.
   Refunds / lost disputes call reverse_affiliate_conversions_by_source.

Database Schema

Eight tables, all RLS-enabled with SELECT policies scoped by membership. Writes go exclusively through SECURITY DEFINER RPCs (no INSERT/UPDATE/DELETE policies). affiliate_clicks has zero policies — service-role only (high-volume internal table).

SECURITY DEFINER RPCs

Every RPC runs REVOKE EXECUTE FROM authenticated, anon; GRANT TO service_role; with an auth.role() defense-in-depth check. Stable error code strings (AFFILIATE_*) are mapped back to typed AffiliateError in core/affiliates/error-codes.ts and translated via errors.affiliate_* i18n keys.

Stripe Webhook Integration

Billing hooks call maybeRecordAffiliateConversion from core/billing/mutations.ts after every credit-granting hook. Refund reversals run from the refund path, and lost-dispute reversals run from core/billing/risk-events.ts through reverseAffiliateConversionsBySource. All affiliate hooks are wrapped in try/catch + logError — affiliate failures NEVER break billing. Cache invalidation (revalidateAffiliateStats) fires on success.

User Dashboard

The user-facing dashboard at /private-dashboard/affiliates branches on application state (no application → public landing redirect; pending → "review in progress" card; rejected → reason + re-apply CTA; active affiliate → status banner + KPI grid + recent-conversions table). Per-status conversion KPIs come from the affiliate_conversion_stats_by_status RPC (single round-trip, no JS aggregation).

Admin Console

The admin panel at /admin-dashboard/affiliates renders three sections in parallel via Promise.all: pending-applications queue with approve/reject dialogs (tier dropdown + reason textarea), active-affiliates list with tier + status + lifetime totals, and a recent-conversions table with manual reverse action. Every admin mutation writes an admin_logs row with { actor_user_id, action, target_type, target_id, details: { reason, before } }.

Background Jobs

API Endpoints

Environment Variables

Security Invariants

• Self-attribution blocked at the RPC level (account-id check + same-owner check on accounts.owner_user_id)
• One attribution per account for life (UNIQUE(referred_account_id)) — prevents farming via re-attribution
• One affiliate per account (UNIQUE(affiliates.account_id)); one pending application at a time (partial UNIQUE)
• stripe_event_id UNIQUE on conversions — replayed Stripe webhooks no-op without double-incrementing affiliate aggregates
• IP + User-Agent stored as SHA-256 hashes salted with AFFILIATES_SALT — never raw PII; hash helper degrades to null when salt unset (graceful)
• commission_pct snapshotted on every conversion row — config edits never retroactively change historical commissions
• Refunds and lost disputes automatically reverse all matching conversions for credit_pack + license sources via reverse_affiliate_conversions_by_source
• Every admin mutation (approve / reject / reverse) writes an admin_logs entry with a before-snapshot
• Feature gate returns 404 (not 403) so the surface is invisible when disabled
• CSRF + rate limit enforced on every state-changing endpoint via apiSecurity.*
• Affiliate webhook hooks wrapped in try/catch + logError — affiliate failures NEVER break billing