npm package: @promptordie/plugin-twitter-enhanced
Description: Enhanced Twitter plugin with credential-based authentication, real-time notification monitoring, and RSS feed management for ElizaOS. Supabase integration is optional and will be used if @supabase/supabase-js is installed.
Latest version: 1.0.3

# Twitter Enhanced Plugin for ElizaOS

Enhanced Twitter plugin with credential-based authentication, real-time notification monitoring, and RSS feed management for ElizaOS.

## Features

- **Credential-based Authentication**: Login with username/password/email
- **Cookie-based Authentication**: Use saved cookies for persistent sessions
- **Real-time Monitoring**: Track mentions, replies, retweets, and quotes
- **RSS Feed Management**: Manage and monitor RSS feeds
- **Engagement Tracking**: Monitor and track engagement metrics
- **Optional Supabase Integration**: Database storage for engagement data

## Installation

```bash
# Basic installation
bun install @promptordie/plugin-twitter-enhanced

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

## Setup

### 1. Environment Variables

Create a `.env` file in your project root:

```env
# Twitter Authentication (Required)
TWITTER_USERNAME=your_twitter_username
TWITTER_PASSWORD=your_twitter_password
TWITTER_EMAIL=your_twitter_email

# Alternative: Use cookies instead of credentials
TWITTER_COOKIES=["cookie1=value1", "cookie2=value2"]

# Supabase (Optional - for engagement tracking)
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_key

# Plugin Configuration
TWITTER_ENGAGEMENT_TRACKING=true
```

### 2. Twitter Authentication Methods

#### Method 1: Username/Password Login
```typescript
import { Scraper } from 'agent-twitter-client';

const scraper = new Scraper();
await scraper.login('username', 'password', 'email');
```

#### Method 2: Cookie-based Login
```typescript
import { Scraper } from 'agent-twitter-client';

const scraper = new Scraper();
const cookies = ['cookie1=value1', 'cookie2=value2'];
await scraper.setCookies(cookies);
```

### 3. Basic Usage

```typescript
import { Scraper, SearchMode } from 'agent-twitter-client';

async function twitterExample() {
  const scraper = new Scraper();
  
  // Login
  await scraper.login('username', 'password', 'email');
  
  // Check login status
  const isLoggedIn = await scraper.isLoggedIn();
  console.log('Logged in:', isLoggedIn);
  
  if (isLoggedIn) {
    // Post a tweet
    const result = await scraper.sendTweet('Hello from ElizaOS!');
    console.log('Tweet posted:', result);
    
    // Get tweets from a user
    const tweets = scraper.getTweets('elonmusk', 5);
    for await (const tweet of tweets) {
      console.log('Tweet:', tweet.text);
    }
    
    // Search tweets
    const searchResults = scraper.searchTweets('AI', 10, SearchMode.Latest);
    for await (const tweet of searchResults) {
      console.log('Search result:', tweet.text);
    }
  }
}
```

## Available Methods

### Authentication
- `scraper.login(username, password, email)` - Login with credentials
- `scraper.setCookies(cookies)` - Login with cookies
- `scraper.isLoggedIn()` - Check login status
- `scraper.getCookies()` - Get current cookies

### Tweet Operations
- `scraper.sendTweet(text, replyToTweetId?, media?)` - Post a tweet
- `scraper.getTweet(id)` - Get a specific tweet
- `scraper.likeTweet(id)` - Like a tweet
- `scraper.retweet(id)` - Retweet
- `scraper.sendQuoteTweet(text, quotedTweetId, mediaOptions?)` - Quote tweet

### User Operations
- `scraper.getProfile(username)` - Get user profile
- `scraper.followUser(username)` - Follow a user
- `scraper.getFollowers(userId, count)` - Get user followers
- `scraper.getFollowing(userId, count)` - Get user following

### Search and Discovery
- `scraper.getTweets(username, count)` - Get user tweets
- `scraper.searchTweets(query, count, mode)` - Search tweets
- `scraper.getTrends()` - Get trending topics

### Search Modes
- `SearchMode.Top` (0) - Top tweets
- `SearchMode.Latest` (1) - Latest tweets
- `SearchMode.Photos` (2) - Photos only
- `SearchMode.Videos` (3) - Videos only

## Error Handling

```typescript
async function robustTwitterExample() {
  const scraper = new Scraper();
  const maxRetries = 3;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      console.log(`Login attempt ${attempt}/${maxRetries}`);
      
      await scraper.login('username', 'password', 'email');
      const isLoggedIn = await scraper.isLoggedIn();
      
      if (isLoggedIn) {
        console.log('Login successful!');
        // Your operations here
        break;
      } else {
        throw new Error('Login failed');
      }
      
    } catch (error) {
      console.error(`Attempt ${attempt} failed:`, error);
      
      if (attempt === maxRetries) {
        console.error('All login attempts failed');
        throw error;
      }
      
      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
}
```

## Troubleshooting

### Common Issues

1. **Login Failed**
   - Check your credentials are correct
   - Try using cookies instead of password
   - Ensure 2FA is disabled or use app passwords

2. **Rate Limiting**
   - Add delays between requests
   - Use retry logic with exponential backoff
   - Monitor your request frequency

3. **Network Issues**
   - Check your internet connection
   - Try using a VPN if Twitter is blocked
   - Ensure firewall isn't blocking requests

### Getting Cookies

To get Twitter cookies for cookie-based authentication:

1. Open Twitter in your browser
2. Open Developer Tools (F12)
3. Go to Application/Storage tab
4. Find Cookies under twitter.com
5. Copy the cookie values

### Environment Setup

```bash
# Install dependencies
bun install

# Build the plugin
bun run build

# Run tests
bun test

# Type checking
bun run type-check
```

## Development

```bash
# Development mode with watch
bun run dev

# Format code
bun run format

# Lint code
bun run lint

# Full check
bun run check-all
```

## Notes

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

## License

MIT License - see LICENSE file for details