npm package: @stochain/referral-system
Description: Referral system with tree structure and virtualized lists
Author: Stochain
Latest version: 1.0.0

# @stochain/referral-system

React Native referral system with tree structure and virtualized lists.

## Installation

```bash
npm install @stochain/referral-system react-native-vector-icons
```

## Features

- 🌲 Tree-structured referral hierarchy
- 📊 11-level ranking system (Bronze to Legend)
- 🎨 Dynamic level colors and progress bars
- 📱 Optimized for React Native
- ⚡ Efficient tree traversal
- 🔍 Search functionality
- 📈 Progress tracking
- 💎 Member statistics

## Usage

### Basic Tree View

```tsx
import { ReferralTree } from '@stochain/referral-system';

function ReferralScreen() {
  const members = [
    {
      mb_id: 'user1',
      mb_name: 'John Doe',
      level: 3,
      totalMemberCount: 150,
      directMemberCount: 15,
      children: [
        {
          mb_id: 'user2',
          mb_name: 'Jane Smith',
          level: 2,
          totalMemberCount: 35,
          directMemberCount: 8,
          children: []
        }
      ]
    }
  ];

  return (
    <ReferralTree
      members={members}
      currentUserId="user1"
      onMemberPress={(member) => console.log('Pressed:', member)}
    />
  );
}
```

### Individual Member Item

```tsx
import { ReferralMemberItem } from '@stochain/referral-system';

<ReferralMemberItem
  item={{
    mb_id: 'user1',
    mb_name: 'John Doe',
    level: 5,
    totalMemberCount: 1200,
    directMemberCount: 50
  }}
  isCurrentUser={true}
  onPress={(member) => console.log('Pressed:', member)}
/>
```

### Level Utilities

```tsx
import {
  getLevelColor,
  getLevelName,
  calculateLevel,
  getMemberCountRequirement
} from '@stochain/referral-system';

// Get color for level
const color = getLevelColor(5); // '#E57373'

// Get level name
const name = getLevelName(5); // 'Diamond II'

// Calculate level from member count
const level = calculateLevel(1500); // 5

// Get requirement for level
const requirement = getMemberCountRequirement(6); // 3000
```

### Search Members

```tsx
import { searchMembers } from '@stochain/referral-system';

const filteredMembers = searchMembers(members, 'john');
```

### Tree Operations

```tsx
import { flattenTree, calculateTotalDownline } from '@stochain/referral-system';

// Flatten tree structure
const flatMembers = flattenTree(members, 0, expandedIds);

// Calculate total downline
const totalDownline = calculateTotalDownline(member);
```

## Level System

| Level | Name | Min Members | Color |
|-------|------|-------------|-------|
| 0 | Bronze | 0 | Grey |
| 1 | Silver | 10 | Brown |
| 2 | Gold | 30 | Light Grey |
| 3 | Platinum | 100 | Orange |
| 4 | Diamond I | 300 | Red Orange |
| 5 | Diamond II | 1,000 | Red |
| 6 | Diamond III | 3,000 | Pink |
| 7 | Master I | 5,000 | Purple |
| 8 | Master II | 10,000 | Deep Purple |
| 9 | Grand Master | 50,000 | Indigo |
| 10 | Legend | 100,000 | Blue |

## Components

### ReferralTree

Displays hierarchical tree of referral members.

**Props:**
- `members` (ReferralMember[]): Array of referral members
- `searchText` (string, optional): Search query
- `onMemberPress` (function, optional): Callback when member pressed
- `currentUserId` (string, optional): ID of current user
- `containerStyle` (ViewStyle, optional): Custom container style

### ReferralMemberItem

Individual member card with stats.

**Props:**
- `item` (ReferralMember): Member data
- `depth` (number, optional): Tree depth level
- `isExpanded` (boolean, optional): Whether node is expanded
- `hasChildren` (boolean, optional): Whether member has children
- `onToggle` (function, optional): Toggle expand/collapse
- `onPress` (function, optional): Press callback
- `isCurrentUser` (boolean, optional): Highlight current user
- `containerStyle` (ViewStyle, optional): Custom container style
- `textStyle` (TextStyle, optional): Custom text style

## Types

```typescript
interface ReferralMember {
  mb_id: string;
  mb_name?: string;
  mb_email?: string;
  level?: number;
  totalMemberCount?: number;
  directMemberCount?: number;
  children?: ReferralMember[];
  created_at?: string;
}

interface LevelConfig {
  level: number;
  color: string;
  minMembers: number;
  name: string;
}
```

## API Reference

### Utility Functions

- `getLevelColor(level)`: Get color for level
- `getLevelName(level)`: Get name for level
- `getMemberCountRequirement(level)`: Get member requirement
- `calculateLevel(memberCount)`: Calculate level from count
- `calculateTotalDownline(member)`: Calculate total downline
- `flattenTree(members, depth, expandedIds)`: Flatten tree structure
- `searchMembers(members, searchText)`: Filter members by search
- `formatNumber(num)`: Format number with commas
- `calculateProgress(currentCount, currentLevel)`: Calculate progress %

## License

MIT