# Twitch Channel Points Miner v2 - Codebase Analysis

**Date:** February 17, 2026  
**Purpose:** Understanding the existing codebase before converting to a Twitch Drops-focused bot  
**Original Project:** https://github.com/rdavydov/Twitch-Channel-Points-Miner-v2

---

## 📋 Executive Summary

This bot is a Python-based application designed to automatically watch Twitch streams to earn channel points. It includes existing drops functionality that we can leverage and expand upon for our Twitch Drops-focused implementation.

**Key Finding:** The bot already has a solid drops infrastructure including:
- Drop claiming mechanisms
- Campaign tracking
- Inventory synchronization
- Drop progress monitoring

---

## 🏗️ Architecture Overview

### Core Components

#### 1. **TwitchChannelPointsMiner** (Main Entry Point)
- **Location:** `TwitchChannelPointsMiner/TwitchChannelPointsMiner.py`
- **Purpose:** Main orchestrator class that manages the entire bot lifecycle
- **Key Features:**
  - Handles authentication via `Twitch` class
  - Manages multiple streamers simultaneously
  - Coordinates WebSocket connections for real-time updates
  - Implements priority system for streamer selection
  - Spawns threads for monitoring and synchronization

**Important Parameters:**
```python
- username: Twitch account username
- password: Optional password (prompts if not provided)
- claim_drops_startup: Auto-claim all drops on startup (Boolean)
- priority: List defining watch priority [STREAK, DROPS, ORDER, etc.]
- enable_analytics: Track statistics (Boolean)
- logger_settings: Logging configuration
- streamer_settings: Default settings for all streamers
```

#### 2. **Twitch Class** (API Handler)
- **Location:** `TwitchChannelPointsMiner/classes/Twitch.py`
- **Purpose:** Handles all Twitch API interactions via GraphQL
- **Key Methods for Drops:**
  - `claim_drop(drop)` - Claims a single drop
  - `claim_all_drops_from_inventory()` - Claims all available drops from inventory
  - `sync_campaigns(streamers, chunk_size)` - Synchronizes campaign data every 30 minutes
  - `__get_inventory()` - Fetches user's drops inventory
  - `__get_drops_dashboard(status)` - Gets active/expired campaigns
  - `__get_campaigns_details(campaigns)` - Gets detailed campaign information
  - `__sync_campaigns(campaigns)` - Updates campaign progress

#### 3. **Drop Entity**
- **Location:** `TwitchChannelPointsMiner/classes/entities/Drop.py`
- **Purpose:** Represents a single drop reward
- **Properties:**
  ```python
  - id: Unique drop identifier
  - name: Drop name
  - benefit: Reward description
  - minutes_required: Watch time needed
  - current_minutes_watched: Progress
  - percentage_progress: Completion percentage
  - is_claimable: Whether drop can be claimed
  - is_claimed: Whether drop has been claimed
  - drop_instance_id: Instance identifier for claiming
  ```

#### 4. **Campaign Entity**
- **Location:** `TwitchChannelPointsMiner/classes/entities/Campaign.py`
- **Purpose:** Represents a Twitch Drops campaign
- **Properties:**
  ```python
  - id: Campaign identifier
  - game: Associated game information
  - name: Campaign name
  - status: Campaign status (ACTIVE, EXPIRED, etc.)
  - drops: List of Drop objects
  - channels: Eligible channel IDs
  - start_at/end_at: Campaign timeframe
  ```
- **Key Methods:**
  - `clear_drops()` - Removes expired/claimed drops
  - `sync_drops(drops, callback)` - Updates drop progress

#### 5. **Priority System**
- **Location:** `TwitchChannelPointsMiner/classes/Settings.py`
- **Enum Values:**
  ```python
  Priority.STREAK      # Watch streak priority
  Priority.DROPS       # Drops collection priority
  Priority.ORDER       # Custom ordering
  Priority.SUBSCRIBED  # Subscribed channels first
  Priority.POINTS_ASCENDING / POINTS_DESCENDING
  ```

---

## 🔄 Workflow & Data Flow

### Current Bot Flow:

1. **Initialization**
   - Authenticate with Twitch
   - Load streamer list
   - Configure logger and settings
   - Check for updates

2. **Startup Phase**
   - If `claim_drops_startup=True`, claim all available drops
   - Initialize WebSocket pool for real-time updates
   - Start analytics server (if enabled)

3. **Main Loop**
   - **Streamer Selection:** Choose streamer based on priority system
     - `Priority.STREAK`: Prioritize maintaining watch streaks
     - `Priority.DROPS`: Prioritize streamers with active drop campaigns
     - `Priority.ORDER`: Use custom ordering
   
   - **Watching:** Join stream via WebSocket, simulate viewing
   
   - **Background Threads:**
     - `minute_watcher_thread`: Tracks watch time, handles bonuses
     - `sync_campaigns_thread`: Syncs drops every 30 minutes

4. **Drop Handling** (Current Implementation)
   ```
   Every 30 minutes:
   └─ sync_campaigns()
      ├─ claim_all_drops_from_inventory()
      ├─ Fetch active campaigns from dashboard
      ├─ Update campaign/drop progress
      ├─ Check if drops are claimable
      └─ Auto-claim claimable drops
   ```

5. **Events & Notifications**
   - Events fired: `Events.DROP_CLAIM`, `Events.DROP_STATUS`
   - Notifications via: Discord, Telegram, Matrix, Pushover, Gotify, Webhook

---

## 📊 Key Files & Directory Structure

```
TwitchBot/
├── TwitchChannelPointsMiner/
│   ├── TwitchChannelPointsMiner.py      # Main orchestrator
│   ├── classes/
│   │   ├── Twitch.py                    # API handler
│   │   ├── TwitchLogin.py               # Authentication
│   │   ├── TwitchWebSocket.py           # WebSocket handling
│   │   ├── WebSocketsPool.py            # Socket pool manager
│   │   ├── Chat.py                      # Chat interaction
│   │   ├── Settings.py                  # Global settings & enums
│   │   ├── AnalyticsServer.py           # Flask analytics server
│   │   ├── entities/
│   │   │   ├── Drop.py                  # Drop model
│   │   │   ├── Campaign.py              # Campaign model
│   │   │   ├── Streamer.py              # Streamer model
│   │   │   ├── Stream.py                # Stream model
│   │   │   ├── Bet.py                   # Betting model
│   │   │   └── ...
│   │   └── [Notification classes]       # Discord, Telegram, etc.
│   ├── constants.py                     # API endpoints & constants
│   ├── logger.py                        # Logging configuration
│   └── utils.py                         # Helper functions
├── example.py                           # Configuration template
├── requirements.txt                     # Dependencies
└── Docs/                                # Documentation (new)
```

---

## 🎯 Current Drops Implementation Details

### How Drops Currently Work:

1. **Campaign Discovery:**
   - Fetches active campaigns from Twitch Drops Dashboard
   - Filters campaigns by date range (start_at < now < end_at)
   - Associates campaigns with eligible streamers

2. **Progress Tracking:**
   - Watches are tracked via WebSocket "watching" messages
   - Progress updates come from inventory sync (every 30 min)
   - Drop progress calculated: `currentMinutesWatched / minutesRequired`

3. **Claiming Logic:**
   - Drop becomes claimable when:
     - `currentMinutesWatched >= minutesRequired`
     - `hasPreconditionsMet == true`
     - `drop_instance_id` is available
   - Claim via GraphQL mutation: `DropsPage_ClaimDropRewards`
   - Automatic retry with 5-10 second random delay

4. **Per-Streamer Configuration:**
   ```python
   StreamerSettings(
       claim_drops=True,  # Enable drops for this streamer
       ...
   )
   ```

### Current Limitations for Our Use Case:

1. **Primary Focus:** Channel points, not drops
   - Drops are secondary to point mining
   - Priority system favors streaks over drops
   - Limited drop-specific logging

2. **Fixed Sync Interval:** 30-minute campaign sync
   - Could miss time-sensitive drops
   - Not optimized for drop-focused workflow

3. **Limited Drop Intelligence:**
   - No prediction of drop completion times
   - No optimization for multi-campaign scenarios
   - No handling of channel-specific drop requirements

4. **Streamer Selection:**
   - Priority system doesn't optimize for drop efficiency
   - No automatic discovery of best streams for active campaigns

---

## 🔍 Dependencies Analysis

**Core Dependencies:**
```
requests              # HTTP requests
websocket-client      # WebSocket connections
pillow                # Image processing (for OCR?)
python-dateutil       # Date parsing
emoji                 # Emoji support
millify               # Number formatting
colorama              # Colored terminal output
flask                 # Analytics server
irc                   # IRC chat (minimal usage)
pandas                # Analytics data
pytz                  # Timezone handling
validators            # Input validation
pre-commit            # Development tool
```

**All dependencies are standard and well-maintained.**

---

## 🎨 Notification System

The bot supports multiple notification channels for events:

- **Discord** - Via webhook
- **Telegram** - Via bot API
- **Matrix** - Matrix protocol
- **Pushover** - Push notifications
- **Gotify** - Self-hosted notifications
- **Webhook** - Generic webhooks

**Relevant Events for Drops:**
- `Events.DROP_CLAIM` - Drop claimed
- `Events.DROP_STATUS` - Drop progress update

---

## 💡 Recommendations for Drops-Focused Bot

### What to Keep:
✅ Drop & Campaign entity models (well-designed)  
✅ Twitch API/GraphQL integration (solid)  
✅ WebSocket infrastructure (essential)  
✅ Notification system (useful for alerts)  
✅ Logger system (comprehensive)  
✅ Authentication mechanism (working)

### What to Modify:
🔧 Priority system → Make drops the primary focus  
🔧 Sync interval → Reduce to ~5-10 minutes for drops  
🔧 Streamer selection → Algorithm optimized for drop campaigns  
🔧 Progress tracking → More granular, per-campaign insights  
🔧 Configuration → Simplify for drops-only use case

### What to Remove/Deprecate:
❌ Betting system (not needed for drops)  
❌ Channel points tracking (secondary concern)  
❌ Community goals (not relevant)  
❌ Watch streak priority (not needed)  
❌ Analytics system (or simplify significantly)

### New Features to Add:
➕ Campaign prioritization algorithm  
➕ Automatic discovery of best streams per campaign  
➕ Drop progress predictions & ETA  
➕ Multi-account support for faster farming  
➕ Campaign completion tracking  
➕ Smart switching between campaigns  
➕ Detailed drop statistics dashboard

---

## 🚀 Next Steps

1. **Phase 1:** Configuration & Setup
   - Create drops-focused default config
   - Update example.py for drops use case
   - Simplify unnecessary features

2. **Phase 2:** Core Logic Modifications
   - Implement drops-first priority system
   - Reduce campaign sync interval
   - Enhance drop progress logging

3. **Phase 3:** New Features
   - Campaign optimizer
   - Smart streamer selection
   - Drop ETA predictions

4. **Phase 4:** Testing & Documentation
   - Test with active campaigns
   - Document new usage patterns
   - Create user guide

---

## 📝 Technical Notes

### GraphQL Operations Used:
- `DropsPage_ClaimDropRewards` - Claim drop
- `Inventory` - Get user inventory
- `ViewerDropsDashboard` - Get campaigns
- `DropCampaignDetails` - Get campaign details

### WebSocket Topics:
- `video-playback-by-id` - Stream events
- `predictions-channel-v1` - Predictions
- Drops progress updates come via API polling, not WebSocket

### Authentication:
- Uses OAuth login flow
- Stores auth token and cookies
- Handles token refresh automatically

---

## 🎓 Conclusion

The codebase is well-structured and maintainable. The existing drops functionality provides a solid foundation. Our main task is to shift focus from channel points to drops, optimize the workflow, and add drop-specific enhancements.

**Confidence Level:** High - The codebase is ready for modification with minimal breaking changes needed.

---

*Document created during initial codebase review - February 17, 2026*