npm package: @promptordie/plugin-social-raids
Description: Comprehensive Twitter/Telegram raids coordination with engagement tracking, community memory, and leaderboards system for ElizaOS. Includes Twitter functionality via agent-twitter-client. Supabase integration is optional and will be used if @supabase/supa
Latest version: 0.0.3

# @promptordie/plugin-social-raids

Comprehensive Twitter/Telegram raids coordination with engagement tracking, community memory, and leaderboards system for ElizaOS.

## Features

- **🤖 Twitter Integration**: Full Twitter functionality via `agent-twitter-client`
- **📱 Telegram Bot**: Automated raid coordination through Telegram
- **📊 Engagement Tracking**: Real-time monitoring of raid performance
- **🧠 Community Memory**: Persistent storage of raid data and user interactions
- **🏆 Leaderboards**: Competitive tracking of community engagement
- **🔗 Cross-Platform**: Seamless coordination between Twitter and Telegram
- **⚡ Real-time Updates**: Live engagement data and notifications
- **🎯 Smart Targeting**: Intelligent raid suggestions and URL detection

## Installation

```bash
# Basic installation
bun install @promptordie/plugin-social-raids

# With Supabase support (optional)
bun install @supabase/supabase-js
```

## Configuration

### Environment Variables

#### Twitter Configuration
```bash
# Required for Twitter functionality
TWITTER_USERNAME=your_twitter_username
TWITTER_PASSWORD=your_twitter_password
TWITTER_EMAIL=your_twitter_email

# Alternative: Use cookies for authentication
TWITTER_COOKIES='["cookie1", "cookie2", ...]'
TWITTER_AUTH_METHOD=cookies
```

#### Telegram Configuration
```bash
# Required for Telegram bot functionality
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
```

#### Supabase Configuration (Optional)
```bash
# For persistent storage and community memory
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
```

## Usage

### Starting a Raid

#### Via Telegram Bot
```
/raid https://twitter.com/user/status/123456789
```

#### Via ElizaOS Actions
```typescript
// Start a new raid
await runtime.executeAction('START_RAID', {
  platform: 'twitter',
  targetUrl: 'https://twitter.com/user/status/123456789',
  description: 'Support our community!'
});

// Get raid status
await runtime.executeAction('GET_RAID_STATUS', {
  raidId: 'raid-123'
});
```

### Available Actions

- `START_RAID` - Initialize a new raid campaign
- `GET_RAID_STATUS` - Check current raid performance
- `STOP_RAID` - End an active raid
- `GET_LEADERBOARD` - View community engagement rankings
- `ANALYZE_ENGAGEMENT` - Get detailed engagement analytics

### Available Services

- `TWITTER_RAID_SERVICE` - Manages Twitter authentication and posting
- `TELEGRAM_RAID_MANAGER` - Handles Telegram bot interactions
- `COMMUNITY_MEMORY_SERVICE` - Stores and retrieves raid data
- `ENGAGEMENT_TRACKER` - Monitors real-time engagement metrics

## Features in Detail

### Twitter Integration
- **Authentication**: Supports both credential and cookie-based auth
- **Posting**: Automated tweet posting with raid updates
- **Engagement**: Real-time monitoring of likes, retweets, replies
- **Scraping**: Intelligent data extraction from target tweets

### Telegram Bot
- **Smart Commands**: `/raid`, `/status`, `/leaderboard`
- **URL Detection**: Automatically detects Twitter links in chat
- **Interactive Responses**: Rich formatting and inline keyboards
- **Community Management**: User tracking and engagement metrics

### Community Memory
- **Persistent Storage**: All raid data saved for analysis
- **User Profiles**: Track individual community member contributions
- **Historical Data**: Access to past raid performance
- **Analytics**: Detailed insights into community engagement

### Engagement Tracking
- **Real-time Monitoring**: Live updates on raid performance
- **Multi-platform**: Tracks both Twitter and Telegram engagement
- **Metrics**: Likes, retweets, replies, shares, and more
- **Reporting**: Automated status updates and notifications

## Development

### Building
```bash
# Build the plugin
bun run build

# Development mode with watch
bun run dev

# Type checking
bun run type-check

# Run tests
bun run test
```

### Testing
```bash
# Run all tests
bun test

# Run with coverage
bun test --coverage

# Watch mode
bun test --watch
```

## Notes

- **agent-twitter-client is deprecated** but still functional
- Some Twitter methods may not work due to API changes
- Use at your own risk in production environments
- Consider implementing your own Twitter client for critical applications
- Supabase integration is optional but recommended for production use

## License

MIT License - see LICENSE file for details.