feat(referrals): implement referral system with code gen, tracking, a…

.env.example

@@ -58,6 +58,7 @@ MIXPANEL_PRIVACY_MODE=strict
 MIXPANEL_INCLUDE_IP=false
 MIXPANEL_INCLUDE_ERROR_STACKS=false
 NEXT_PUBLIC_ENABLE_EMAIL_IN_ANALYTICS=false
+NEXT_PUBLIC_FEE_RECIPIENT_ADDRESS=
 
 # =============================================================================
 # Security
@@ -125,3 +126,8 @@ SANITY_STUDIO_PROJECT_ID=your_project_id_here
 # Next.js App (client-side)
 NEXT_PUBLIC_SANITY_DATASET=production
 NEXT_PUBLIC_SANITY_PROJECT_ID=your_project_id_here
+
+# Sentry
+SENTRY_DSN=https://abc123@o456.ingest.glitchtip.pycrst.xyz/789
+SENTRY_URL=
+SENTRY_AUTH_TOKEN=

.github/workflows/node.js.yml

@@ -0,0 +1,46 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Node.js CI
+
+on:
+  push:
+    branches: ['stable']
+  pull_request:
+    branches: ['main', 'stable']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Verify pnpm installation
+        run: pnpm --version
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build

app/api/aggregator.ts

@@ -18,6 +18,9 @@ import type {
   RecipientDetails,
   RecipientDetailsWithId,
   SavedRecipientsResponse,
+  ReferralData,
+  ApiResponse,
+  SubmitReferralResult,
 } from "../types";
 import {
   trackServerEvent,
@@ -609,6 +612,93 @@ export const fetchTokens = async (): Promise<APIToken[]> => {
   }
 };
 
+/**
+ * Submit a referral code for a new user
+ */
+export async function submitReferralCode(
+  code: string,
+  accessToken?: string,
+): Promise<ApiResponse<SubmitReferralResult>> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  if (accessToken) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  }
+
+  try {
+    const response = await axios.post(`/api/referral/submit`, { referral_code: code }, { headers });
+
+    if (!response.data?.success) {
+      return { success: false, error: response.data?.error || response.data?.message || "Failed to submit referral code", status: response.status };
+    }
+
+    return { success: true, data: response.data?.data || response.data } as ApiResponse<SubmitReferralResult>;
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      const message = error.response?.data?.message || error.message || "Failed to submit referral code";
+      return { success: false, error: message, status: error.response?.status };
+    }
+    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+  }
+}
+
+
+/**
+ * Get user's referral data (code, earnings, referral list)
+ */
+export async function getReferralData(
+  accessToken: string,
+  walletAddress?: string,
+): Promise<ApiResponse<ReferralData>> {
+  if (!accessToken) {
+    return {
+      success: false,
+      error: "Authentication token is required",
+    };
+  }
+
+  const url = walletAddress
+    ? `/api/referral/referral-data?wallet_address=${encodeURIComponent(walletAddress)}`
+    : `/api/referral/referral-data`;
+
+  try {
+    const response = await axios.get<ApiResponse<ReferralData>>(url, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!response.data?.success) {
+      return {
+        success: false,
+        error: response.data?.error || "Failed to fetch referral data",
+        status: response.status,
+      };
+    }
+
+    // The endpoint auto-generates code if missing, so data.referral_code should always exist
+    return { success: true, data: response.data.data };
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      const message =
+        error.response?.data?.message ||
+        error.message ||
+        "Failed to fetch referral data";
+      return {
+        success: false,
+        error: message,
+        status: error.response?.status,
+      };
+    }
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
 /**
  * Fetches saved recipients for a wallet address
  * @param {string} accessToken - The access token for authentication