Feat/affiliate referral system

[sweetesty]

Closes #385

---

This PR implements a full affiliate and referral program system for subscription merchants, covering backend commission tracking, payout management, fraud detection, and a frontend affiliate dashboard.

Backend — backend/services/

Referral link generation

• Unique affiliate codes generated per merchant using crypto.randomBytes — not guessable or sequential
• POST /api/affiliates/links — creates a referral link with configurable commission rate and cookie window
• Short URLs stored with full tracking metadata: affiliate ID, merchant ID, commission config, created date

Commission tracking

• Commission recorded on every subscription event: initial conversion and recurring renewals
• Recurring commission model: affiliate earns on each billing cycle for the lifetime of the referred subscription (configurable cap)
• Commission clawback on churn: if a referred subscription cancels within the configurable clawback window, the pending commission is reversed before payout
• All commission events stored with subscription ID, billing cycle, amount, and status (pending | approved | clawed_back | paid)

Payout management

• Configurable payout threshold per affiliate — payouts only trigger once the threshold is reached
• POST /api/affiliates/payouts/request — affiliate requests payout of approved commissions above threshold
• Payout history with status tracking: pending | processing | completed | failed

Cookie-based attribution

• Attribution cookie set on referral link click with configurable window (default 30 days)
• Cookie-blocked fallback: fingerprint-based attribution as secondary signal when cookies are unavailable
• Multi-touch attribution: first-click wins by default; last-click mode configurable per merchant
• Attribution resolved at subscription creation time against active cookies and fingerprints

Fraud detection

• Self-referral detection: affiliate cannot earn commission on their own subscriptions
• Velocity checks: unusually high referral volume in a short window flagged for review
• IP clustering: multiple conversions from the same IP flagged as potential abuse
• Suspicious referrals quarantined in under_review status pending manual approval before commission is approved

Frontend

src/store/affiliateStore.ts

• Zustand store managing affiliate profile, referral links, commission history, payout balance, and pending payouts
• Async actions for fetching dashboard data, requesting payouts, and generating new referral links

src/screens/AffiliateDashboardScreen.tsx

• Earnings summary: total earned, pending, paid out, and current balance
• Referral list with conversion status and commission per referral
• Commission history with recurring payment timeline
• Payout request UI with threshold indicator
• Referral link generator with copy-to-clipboard and share options

Acceptance criteria met:

• ✅ Referral link generation with unique codes
• ✅ Commission tracking per subscription with recurring commissions
• ✅ Commission clawback on churn within configurable window
• ✅ Payout management with configurable thresholds
• ✅ Affiliate dashboard with earnings and referrals
• ✅ Cookie-based attribution with configurable window and cookie-blocked fallback
• ✅ Fraud detection: self-referral, velocity checks, IP clustering

[drips-wave]

@sweetesty Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits