Referral Program

Format: ABCD1234
Example: K7M2P9X4

https://joip.app?r=SzdNMlA5WDQ

// Referrer (you)
+10 credits → "Referral bonus - new user signup"

// Referred user (your friend)
+25 credits → "Welcome bonus - referred by friend"

K7M2P9X4

SzdNMlA5WDQ

function generateCode(): string {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  return Array.from({ length: 8 }, () =>
    chars[Math.floor(Math.random() * chars.length)]
  ).join('');
}

https://joip.app?r=SzdNMlA5WDQ

pending_referral=K7M2P9X4
referral_source=direct

https://joip.app/shared/abc123?r=SzdNMlA5WDQ

pending_referral=K7M2P9X4
referral_source=session_share
referral_source_id=abc123

if (referrerId === referredUserId) {
  return { success: false, error: 'Cannot refer yourself' };
}

// Check if user already has a referrer
if (user.referredBy !== null) {
  return { success: false, error: 'User already referred' };
}

// Also check referrals table
const existing = await db
  .select()
  .from(userReferrals)
  .where(eq(userReferrals.referredUserId, userId));

if (existing.length > 0) {
  return { success: false, error: 'User already referred' };
}

const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);

const recentReferrals = await db
  .select({ count: sql`count(*)` })
  .from(userReferrals)
  .where(
    and(
      eq(userReferrals.referrerId, referrerId),
      gte(userReferrals.createdAt, oneHourAgo)
    )
  );

if (recentReferrals[0].count >= maxPerHour) {
  return { success: false, error: 'Rate limit exceeded' };
}

// Format validation
const REFERRAL_CODE_REGEX = /^[A-Z0-9]{8}$/;

function isValidCodeFormat(code: string): boolean {
  return REFERRAL_CODE_REGEX.test(code);
}

// Decode validation
function decodeReferralParam(encoded: string): string | null {
  // Length check
  if (encoded.length === 0 || encoded.length > 128) {
    return null;
  }
  
  // Decode
  try {
    const decoded = Buffer.from(encoded, 'base64url').toString('utf8');
    
    // Validate decoded format
    if (!isValidCodeFormat(decoded)) {
      return null;
    }
    
    return decoded;
  } catch {
    return null;
  }
}

CREATE TABLE users (
  id VARCHAR PRIMARY KEY,
  referral_code VARCHAR UNIQUE,     -- User's unique referral code
  referred_by VARCHAR,              -- ID of user who referred this user
  -- ... other fields
);

CREATE TABLE user_referrals (
  id SERIAL PRIMARY KEY,
  referrer_id VARCHAR NOT NULL REFERENCES users(id),
  referred_user_id VARCHAR NOT NULL UNIQUE REFERENCES users(id),
  referral_code VARCHAR NOT NULL,   -- Code used (for audit)
  credits_awarded INTEGER NOT NULL DEFAULT 10,
  bonus_credits_given INTEGER NOT NULL DEFAULT 25,
  source_type VARCHAR,              -- 'direct' | 'session_share'
  source_id VARCHAR,                -- Share code if from session
  created_at TIMESTAMP DEFAULT NOW(),
  
  CONSTRAINT unique_referred_user UNIQUE (referred_user_id)
);

CREATE INDEX idx_referrals_referrer ON user_referrals(referrer_id);
CREATE INDEX idx_referrals_created ON user_referrals(created_at);

CREATE TABLE referral_settings (
  id SERIAL PRIMARY KEY,
  referrer_credits INTEGER NOT NULL DEFAULT 10,
  referred_credits INTEGER NOT NULL DEFAULT 25,
  is_active BOOLEAN NOT NULL DEFAULT TRUE,
  max_referrals_per_hour INTEGER NOT NULL DEFAULT 10,
  updated_at TIMESTAMP DEFAULT NOW(),
  updated_by VARCHAR
);

return await db.transaction(async (tx) => {
  // 1. Lock both users
  const lockedUsers = await tx
    .select()
    .from(users)
    .where(inArray(users.id, [referrerId, referredUserId]))
    .for('update');
  
  // 2. Validate
  if (referredUser.referredBy) {
    throw new Error('User already referred');
  }
  
  // 3. Check rate limit
  const recentCount = await tx
    .select({ count: sql`count(*)` })
    .from(userReferrals)
    .where(/* recent referrals */);
  
  if (recentCount >= maxPerHour) {
    throw new Error('Rate limit exceeded');
  }
  
  // 4. Insert referral record
  await tx.insert(userReferrals).values({
    referrerId,
    referredUserId,
    referralCode: code,
    creditsAwarded: 10,
    bonusCreditsGiven: 25,
    sourceType,
    sourceId
  });
  
  // 5. Update user's referredBy
  await tx
    .update(users)
    .set({ referredBy: referrerId })
    .where(eq(users.id, referredUserId));
  
  // 6. Award credits (using same transaction)
  await creditService.addCredits(
    referrerId, 10, 'bonus',
    'Referral bonus - new user signup',
    undefined,
    tx // Pass transaction
  );
  
  await creditService.addCredits(
    referredUserId, 25, 'bonus',
    'Welcome bonus - referred by friend',
    undefined,
    tx // Pass transaction
  );
  
  return { success: true };
});

await storage.logUserActivity({
  userId: referredUserId,
  action: 'referral_signup',
  feature: 'referrals',
  details: {
    referrerId,
    referralCode,
    sourceType,
    creditsEarned: referredCredits
  },
  ipAddress: req.ip,
  userAgent: req.get('User-Agent'),
  sessionId: req.sessionID
});