npm package: @rivtor/viral
Description: Product-Led Growth Viral Loops with referral tracking and fraud detection
Author: Rivtor
Latest version: 1.1.0

# @rivtor/viral

**Production-ready product-led growth viral loops with referral tracking and fraud detection**

## Features

- **Referral Code Generator**: Collision detection for unique, memorable codes
- **Attribution Tracking**: Track referrals across multiple touchpoints
- **Fraud Detection**: Rate limits, device fingerprinting, and pattern analysis
- **Reward Distribution**: Credits, discounts, trials, and feature unlocks
- **Analytics Dashboard**: Conversion rates, top referrers, and performance metrics
- **React Widgets**: Pre-built referral widgets and share buttons

## Installation

```bash
npm install @rivtor/viral
# or
yarn add @rivtor/viral
# or
pnpm add @rivtor/viral
```

## Quick Start

### 1. Generate Referral Code

```typescript
import { generateReferralCode } from '@rivtor/viral/server';

const code = await generateReferralCode('user-123', {
  type: 'credits',
  value: 100,
  expiresIn: 30 * 24 * 60 * 60 // 30 days
});

console.log(code);
// Returns: 'GETRIVTORXYZ' or similar
```

### 2. Track Referral Click

```typescript
import { trackReferral } from '@rivtor/viral/server';

const referral = await trackReferral('GETRIVTORXYZ', 'user-456', {
  ipAddress: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  deviceId: 'device-123',
  referrer: 'https://twitter.com'
});

console.log(referral);
// {
//   id: 'referral-123',
//   code: 'GETRIVTORXYZ',
//   referrerId: 'user-123',
//   refereeId: 'user-456',
//   status: 'pending',
//   fraudScore: 0
// }
```

### 3. Convert Referral

```typescript
import { convertReferral } from '@rivtor/viral/server';

const converted = await convertReferral('user-456', 'signup', {
  plan: 'pro',
  value: 29
});

console.log(converted);
// {
//   success: true,
//   referralId: 'referral-123',
//   referrerReward: { type: 'credits', value: 100 },
//   refereeReward: { type: 'discount', value: 10 }
// }
```

### 4. Display Referral Widget

```tsx
'use client';
import { RivtorReferralWidget } from '@rivtor/viral/react';

export default function ReferralPage() {
  return (
    <RivtorReferralWidget
      userId="user-123"
      showStats
      variant="detailed"
      onShare={(platform) => console.log(`Shared on ${platform}`)}
    />
  );
}
```

### 5. Share Buttons

```tsx
'use client';
import { RivtorShareButtons } from '@rivtor/viral/react';

export default function ShareSection() {
  return (
    <RivtorShareButtons
      referralCode="GETRIVTORXYZ"
      title="Join me on Rivtor!"
      message="I've been using Rivtor and love it. Sign up with my code for 10% off!"
      variant="horizontal"
      platforms={['twitter', 'facebook', 'linkedin', 'email', 'copy']}
    />
  );
}
```

## API Reference

### Server Functions

```typescript
import {
  generateReferralCode,
  trackReferral,
  convertReferral,
  getReferralStats,
  validateReferralCode
} from '@rivtor/viral/server';

// Generate referral code
await generateReferralCode(
  userId: string,
  options?: {
    type?: 'credits' | 'discount' | 'trial' | 'feature';
    value?: number;
    expiresIn?: number;
    maxUses?: number;
    customCode?: string;
  }
): Promise<string>; // Returns referral code

// Track referral click
await trackReferral(
  code: string,
  refereeId: string,
  context: {
    ipAddress?: string;
    userAgent?: string;
    deviceId?: string;
    referrer?: string;
  }
): Promise<Referral>;

// Convert referral (when user completes action)
await convertReferral(
  refereeId: string,
  action: 'signup' | 'purchase' | 'subscription',
  metadata?: Record<string, unknown>
): Promise<ConversionResult>;

// Get referral stats
await getReferralStats(userId: string): Promise<{
  totalReferrals: number;
  successfulConversions: number;
  pendingConversions: number;
  totalRewards: number;
  conversionRate: number;
}>;

// Validate referral code
await validateReferralCode(code: string): Promise<{
  valid: boolean;
  code?: string;
  reward?: Reward;
  reason?: string;
}>;
```

### Reward Management

```typescript
import {
  createReward,
  distributeReward,
  getUserRewards,
  applyReward
} from '@rivtor/viral/server';

// Create reward
await createReward({
  name: 'Signup Bonus',
  type: 'credits',
  value: 100,
  expiresIn: 30 * 24 * 60 * 60
});

// Distribute reward to user
await distributeReward('user-123', {
  rewardId: 'reward-123',
  referralId: 'referral-456',
  reason: 'referral_conversion'
});

// Get user rewards
await getUserRewards('user-123', {
  status: 'available',
  type: 'credits'
});

// Apply reward
await applyReward('reward-123', {
  userId: 'user-123',
  orderId: 'order-456'
});
```

### Fraud Detection

```typescript
import {
  checkFraud,
  flagSuspiciousActivity,
  getFraudScore
} from '@rivtor/viral/server';

// Check for fraud
await checkFraud(referralId: string): Promise<{
  isFraudulent: boolean;
  fraudScore: number;
  reasons: string[];
}>;

// Flag suspicious activity
await flagSuspiciousActivity({
  referralId: 'referral-123',
  reason: 'multiple_same_device',
  severity: 'high'
});

// Get fraud score
await getFraudScore(userId: string): Promise<{
  score: number;
  riskLevel: 'low' | 'medium' | 'high';
  factors: {
    sameDeviceReferrals: number;
    sameIpReferrals: number;
    timeBetweenReferrals: number;
    conversionRate: number;
  };
}>;
```

### Analytics

```typescript
import {
  getReferralAnalytics,
  getTopReferrers,
  getConversionMetrics
} from '@rivtor/viral/server';

// Get referral analytics
await getReferralAnalytics({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  groupBy: 'day'
});

// Get top referrers
await getTopReferrers({
  limit: 10,
  sortBy: 'conversions' | 'revenue'
});

// Get conversion metrics
await getConversionMetrics({
  funnel: ['click', 'signup', 'purchase'],
  cohort: 'january_2024'
});
```

## React Components

### RivtorReferralWidget

```tsx
<RivtorReferralWidget
  userId="user-123"
  variant="compact" // | 'detailed' | 'minimal'
  showStats={true}
  showShareButtons={true}
  showLeaderboard={false}
  onShare={(platform) => console.log(`Shared on ${platform}`)}
  onCopy={() => console.log('Code copied')}
  theme="light" // | 'dark' | 'custom'
  customTheme={{
    primaryColor: '#3b82f6',
    borderRadius: '8px'
  }}
/>
```

### RivtorShareButtons

```tsx
<RivtorShareButtons
  referralCode="GETRIVTORXYZ"
  title="Join me on Rivtor!"
  message="I've been using Rivtor and love it. Sign up with my code for 10% off!"
  variant="horizontal" // | 'vertical'
  platforms={[
    'twitter',
    'facebook',
    'linkedin',
    'email',
    'whatsapp',
    'copy'
  ]}
  size="medium" // | 'small' | 'large'
  onShare={(platform) => console.log(`Shared on ${platform}`)}
/>
```

### RivtorLeaderboard

```tsx
<RivtorLeaderboard
  period="month" // | 'week' | 'all-time'
  limit={10}
  showRank={true}
  showStats={true}
  currentUserOnly={false}
  onUserClick={(userId) => console.log(`View ${userId}`)}
/>
```

## Database Schema

```sql
-- Referral codes
CREATE TABLE referral_codes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    code TEXT UNIQUE NOT NULL,
    user_id UUID NOT NULL,
    reward_type TEXT NOT NULL,
    reward_value NUMERIC NOT NULL,
    status TEXT NOT NULL DEFAULT 'active',
    max_uses INTEGER,
    total_uses INTEGER DEFAULT 0,
    expires_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    metadata JSONB
);

-- Referrals
CREATE TABLE referrals (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    referral_code_id UUID NOT NULL REFERENCES referral_codes(id),
    referrer_id UUID NOT NULL,
    referee_id UUID NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',
    converted_at TIMESTAMPTZ,
    reward_applied BOOLEAN DEFAULT FALSE,
    fraud_score NUMERIC DEFAULT 0,
    fraud_reasons TEXT[],
    ip_address TEXT,
    user_agent TEXT,
    device_id TEXT,
    referrer TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Rewards
CREATE TABLE rewards (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL,
    referral_id UUID REFERENCES referrals(id),
    type TEXT NOT NULL,
    value NUMERIC NOT NULL,
    status TEXT NOT NULL DEFAULT 'available',
    expires_at TIMESTAMPTZ,
    applied_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes for efficient queries
CREATE INDEX idx_referral_codes_user ON referral_codes(user_id);
CREATE INDEX idx_referral_codes_code ON referral_codes(code);
CREATE INDEX idx_referrals_referrer ON referrals(referrer_id);
CREATE INDEX idx_referrals_referee ON referrals(referee_id);
CREATE INDEX idx_referrals_status ON referrals(status);
CREATE INDEX idx_rewards_user ON rewards(user_id);
CREATE INDEX idx_rewards_status ON rewards(status);
```

## Configuration

```typescript
import { configureViral } from '@rivtor/viral/server';

configureViral({
  // Referral code settings
  codes: {
    length: 12,
    prefix: 'GET',
    charset: 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789', // No ambiguous characters
    maxUses: 100,
    expiresIn: 30 * 24 * 60 * 60 // 30 days
  },

  // Reward settings
  rewards: {
    referrer: {
      type: 'credits',
      value: 100
    },
    referee: {
      type: 'discount',
      value: 10
    },
    expiresIn: 90 * 24 * 60 * 60 // 90 days
  },

  // Fraud detection
  fraud: {
    enabled: true,
    maxSameDeviceReferrals: 3,
    maxSameIpReferrals: 5,
    minTimeBetweenReferrals: 60 * 60, // 1 hour
    maxConversionRate: 0.5,
    flagThreshold: 0.7
  },

  // Attribution window
  attribution: {
    windowDays: 30,
    touchpoints: ['first', 'last'],
    trackMultipleConversions: false
  }
});
```

## Reward Types

| Type | Description | Example |
|------|-------------|---------|
| credits | Account credits | $100 in credits |
| discount | Percentage discount | 10% off next purchase |
| trial | Free trial extension | 30 days free |
| feature | Feature unlock | Unlock premium feature |
| cash | Cash payout | $50 cash reward |

## Fraud Detection Factors

The fraud detection system considers:

- **Same Device**: Multiple referrals from same device
- **Same IP**: Multiple referrals from same IP address
- **Timing Pattern**: Unusual timing between referrals
- **Conversion Rate**: Abnormally high or low conversion rates
- **User Behavior**: Suspicious user activity patterns

## Best Practices

1. **Set Reasonable Limits**: Limit max uses per referral code
2. **Monitor Fraud**: Regularly review fraud detection logs
3. **A/B Test Rewards**: Test different reward types and values
4. **Clear Communication**: Clearly explain reward terms to users
5. **Track Attribution**: Use multiple touchpoint attribution for accuracy

## License

MIT

---

Made with ❤️ by [Rivtor](https://rivtor.com)