@elizaos/plugin-twitter 1.0.13 → 1.2.0

package/README.md

@@ -1,36 +1,166 @@
 # Eliza Twitter/X Client
 
-This package provides Twitter/X integration for the Eliza AI agent using Twitter API v2.
+This package provides Twitter/X integration for the Eliza AI agent using the official Twitter API v2.
+
+## 🚨 TL;DR - Quick Setup
+
+**Just want your bot to post tweets? Here's the fastest path:**
+
+1. **Get Twitter Developer account** → https://developer.twitter.com
+2. **Create an app** → Enable "Read and write" permissions
+3. **Get OAuth 1.0a credentials** (NOT OAuth 2.0!):
+   - API Key & Secret (from "Consumer Keys")
+   - Access Token & Secret (from "Authentication Tokens")
+4. **Add to `.env`:**
+   ```bash
+   TWITTER_API_KEY=xxx
+   TWITTER_API_SECRET_KEY=xxx
+   TWITTER_ACCESS_TOKEN=xxx
+   TWITTER_ACCESS_TOKEN_SECRET=xxx
+   TWITTER_POST_ENABLE=true
+   TWITTER_POST_IMMEDIATELY=true
+   ```
+5. **Run:** `bun start`
+
+⚠️ **Common mistake:** Using OAuth 2.0 credentials instead of OAuth 1.0a - see [Step 3](#step-3-get-the-right-credentials-oauth-10a) for details!
 
 ## Features
 
-- Autonomous tweet posting with configurable intervals
-- Timeline monitoring and interaction
-- Mention and reply handling
-- Search functionality
-- Direct message support
-- Advanced timeline algorithms with weighted scoring
-- Action processing and automated responses
-- Comprehensive caching system
+- ✅ **Autonomous tweet posting** with configurable intervals
+- ✅ **Timeline monitoring** and interaction
+- ✅ **Mention and reply handling**
+- ✅ **Search functionality**
+- ✅ **Direct message support**
+- ✅ **Advanced timeline algorithms** with weighted scoring
+- ✅ **Comprehensive caching system**
+- ✅ **Built-in rate limiting and retry mechanisms**
 
-## Setup Guide
-
-### Prerequisites
+## Prerequisites
 
 - Twitter Developer Account with API v2 access
-- Twitter API v2 credentials (API Key, API Secret, Access Token, Access Token Secret)
+- Twitter OAuth 1.0a credentials (NOT OAuth 2.0)
 - Node.js and bun installed
 
-### Step 1: Configure Environment Variables
+## 🚀 Quick Start
+
+### Step 1: Get Twitter Developer Access
+
+1. Apply for a developer account at https://developer.twitter.com
+2. Create a new app in the [Developer Portal](https://developer.twitter.com/en/portal/projects-and-apps)
+3. Ensure your app has API v2 access
+
+### Step 2: Configure App Permissions for Posting
+
+**⚠️ CRITICAL: Default apps can only READ. You must enable WRITE permissions to post tweets!**
+
+1. In your app settings, go to **"User authentication settings"**
+2. Configure exactly as shown:
+
+   **App permissions**: `Read and write` ✅
+   
+   **Type of App**: `Web App, Automated App or Bot`
+   
+   **Required URLs** (copy these exactly):
+   ```
+   Callback URI: http://localhost:3000/callback
+   Website URL: https://github.com/elizaos/eliza
+   ```
+   
+   **Optional fields**:
+   ```
+   Organization name: ElizaOS
+   Organization URL: https://github.com/elizaos/eliza
+   ```
+
+3. Click **Save**
+
+### Step 3: Get the RIGHT Credentials (OAuth 1.0a)
+
+**⚠️ IMPORTANT: You need OAuth 1.0a credentials, NOT OAuth 2.0!**
+
+In your app's **"Keys and tokens"** page, you'll see several sections. Here's what to use:
+
+```
+✅ USE THESE (OAuth 1.0a):
+┌─────────────────────────────────────────────────┐
+│ Consumer Keys                                   │
+│ ├─ API Key: xxx...xxx          → TWITTER_API_KEY │
+│ └─ API Key Secret: xxx...xxx   → TWITTER_API_SECRET_KEY │
+│                                                 │
+│ Authentication Tokens                           │
+│ ├─ Access Token: xxx...xxx     → TWITTER_ACCESS_TOKEN │
+│ └─ Access Token Secret: xxx    → TWITTER_ACCESS_TOKEN_SECRET │
+└─────────────────────────────────────────────────┘
+
+❌ DO NOT USE THESE (OAuth 2.0):
+┌─────────────────────────────────────────────────┐
+│ OAuth 2.0 Client ID and Client Secret          │
+│ ├─ Client ID: xxx...xxx        ← IGNORE        │
+│ └─ Client Secret: xxx...xxx    ← IGNORE        │
+│                                                 │
+│ Bearer Token                   ← IGNORE        │
+└─────────────────────────────────────────────────┘
+```
+
+**After enabling write permissions, you MUST:**
+1. Click **"Regenerate"** on Access Token & Secret
+2. Copy the NEW tokens (old ones won't have write access)
+3. Look for "Created with Read and Write permissions" ✅
+
+### Step 4: Configure Environment Variables
 
 Create or edit `.env` file in your project root:
 
 ```bash
-# Required Twitter API v2 Credentials
-TWITTER_API_KEY=                    # Your Twitter API Key
-TWITTER_API_SECRET_KEY=             # Your Twitter API Secret Key  
-TWITTER_ACCESS_TOKEN=               # Your Access Token
-TWITTER_ACCESS_TOKEN_SECRET=        # Your Access Token Secret
+# REQUIRED: OAuth 1.0a Credentials (from "Consumer Keys" section)
+TWITTER_API_KEY=your_api_key_here                    # From "API Key"
+TWITTER_API_SECRET_KEY=your_api_key_secret_here      # From "API Key Secret"
+
+# REQUIRED: OAuth 1.0a Tokens (from "Authentication Tokens" section)
+TWITTER_ACCESS_TOKEN=your_access_token_here          # Must have "Read and Write"
+TWITTER_ACCESS_TOKEN_SECRET=your_token_secret_here   # Regenerate after permission change
+
+# Basic Configuration
+TWITTER_DRY_RUN=false              # Set to true to test without posting
+TWITTER_POST_ENABLE=true           # Set to true to enable auto-posting
+
+# Optional: Posting Configuration
+TWITTER_POST_IMMEDIATELY=true      # Post on startup (great for testing)
+TWITTER_POST_INTERVAL_MIN=90       # Minimum minutes between posts
+TWITTER_POST_INTERVAL_MAX=180      # Maximum minutes between posts
+```
+
+### Step 5: Run Your Bot
+
+```typescript
+// Your character should include the twitter plugin
+const character = {
+    // ... other config
+    plugins: [
+        "@elizaos/plugin-bootstrap",  // Required for content generation
+        "@elizaos/plugin-twitter"      // Twitter functionality
+    ],
+    postExamples: [                    // Examples for tweet generation
+        "Just discovered an amazing pattern in the data...",
+        "The future of AI is collaborative intelligence",
+        // ... more examples
+    ]
+};
+```
+
+Then start your bot:
+```bash
+bun run start
+```
+
+## 📋 Complete Configuration Reference
+
+```bash
+# Required Twitter API v2 Credentials (OAuth 1.0a)
+TWITTER_API_KEY=                    # Consumer API Key
+TWITTER_API_SECRET_KEY=             # Consumer API Secret
+TWITTER_ACCESS_TOKEN=               # Access Token (with write permissions)
+TWITTER_ACCESS_TOKEN_SECRET=        # Access Token Secret
 
 # Basic Configuration
 TWITTER_DRY_RUN=false              # Set to true for testing without posting
@@ -42,7 +172,7 @@ TWITTER_POLL_INTERVAL=120          # Timeline polling interval (seconds)
 TWITTER_POST_ENABLE=false          # Enable autonomous tweet posting
 TWITTER_POST_INTERVAL_MIN=90       # Minimum interval between posts (minutes)
 TWITTER_POST_INTERVAL_MAX=180      # Maximum interval between posts (minutes)
-TWITTER_POST_IMMEDIATELY=false     # Skip intervals and post immediately
+TWITTER_POST_IMMEDIATELY=false     # Post immediately on startup
 TWITTER_POST_INTERVAL_VARIANCE=0.2 # Random variance factor for posting intervals
 
 # Interaction Settings
@@ -67,81 +197,98 @@ TWITTER_ENABLE_ACTION_PROCESSING=false  # Enable timeline action processing
 TWITTER_ACTION_INTERVAL=240       # Action processing interval (minutes)
 ```
 
-### Step 2: Initialize the Client
+## 🎯 Common Use Cases
 
-```typescript
-import { TwitterClientInterface } from "@elizaos/plugin-twitter";
+### Just Want to Post Tweets?
 
-const twitterPlugin = {
-    name: "twitter",
-    description: "Twitter client",
-    services: [TwitterService],
-};
+```bash
+# Minimal setup for posting only
+TWITTER_API_KEY=xxx
+TWITTER_API_SECRET_KEY=xxx
+TWITTER_ACCESS_TOKEN=xxx        # Must have write permissions!
+TWITTER_ACCESS_TOKEN_SECRET=xxx
+
+TWITTER_POST_ENABLE=true
+TWITTER_POST_IMMEDIATELY=true   # Great for testing
+TWITTER_SEARCH_ENABLE=false     # Disable interactions
+```
+
+### Want Full Interaction Bot?
 
-// Register with your Eliza runtime
-runtime.registerPlugin(twitterPlugin);
+```bash
+# Full interaction setup
+TWITTER_API_KEY=xxx
+TWITTER_API_SECRET_KEY=xxx
+TWITTER_ACCESS_TOKEN=xxx
+TWITTER_ACCESS_TOKEN_SECRET=xxx
+
+TWITTER_POST_ENABLE=true
+TWITTER_SEARCH_ENABLE=true
+TWITTER_AUTO_RESPOND_MENTIONS=true
+TWITTER_AUTO_RESPOND_REPLIES=true
 ```
 
-## Authentication
+### Testing Without Posting?
 
-This plugin uses **Twitter API v2** with OAuth 1.0a authentication. You need:
+```bash
+# Dry run mode
+TWITTER_DRY_RUN=true            # Simulates all actions
+TWITTER_POST_ENABLE=true
+TWITTER_POST_IMMEDIATELY=true
+```
 
-1. **Twitter Developer Account**: Apply at https://developer.twitter.com
-2. **API v2 Access**: Ensure your app has API v2 access enabled
-3. **Credentials**: Generate API Key, API Secret, Access Token, and Access Token Secret
+## 🔧 Troubleshooting
 
-### Getting Twitter API Credentials
+### "403 Forbidden" When Posting
 
-1. Go to https://developer.twitter.com/en/portal/dashboard
-2. Create a new app or use an existing one
-3. Navigate to "Keys and tokens"
-4. Generate/copy:
-   - API Key (`TWITTER_API_KEY`)
-   - API Secret Key (`TWITTER_API_SECRET_KEY`)
-   - Access Token (`TWITTER_ACCESS_TOKEN`)
-   - Access Token Secret (`TWITTER_ACCESS_TOKEN_SECRET`)
+This is the #1 issue! Your app has read-only permissions.
 
-## Features
+**Solution:**
+1. Go to app settings → "User authentication settings"
+2. Change to "Read and write"
+3. Save settings
+4. **CRITICAL**: Regenerate your Access Token & Secret
+5. Update `.env` with NEW tokens
+6. Restart your bot
+
+**How to verify:** In "Keys and tokens", your Access Token should show "Created with Read and Write permissions"
 
-### Autonomous Posting
+### "Could not authenticate you"
 
-When `TWITTER_POST_ENABLE=true`, the client automatically generates and posts tweets:
-- Configurable posting intervals with randomization
-- Character-based content generation
-- Support for long-form tweets (up to 4000 characters)
-- Dry-run mode for testing
+Wrong credentials or using OAuth 2.0 instead of OAuth 1.0a.
 
-### Timeline Monitoring
+**Solution:**
+- Use credentials from "Consumer Keys" section (API Key/Secret)
+- Use credentials from "Authentication Tokens" section (Access Token/Secret)
+- Do NOT use OAuth 2.0 Client ID, Client Secret, or Bearer Token
 
-The client monitors and processes the Twitter timeline:
-- **Weighted Algorithm**: Scores tweets based on user relationships, time, and relevance
-- **Latest Algorithm**: Processes tweets in chronological order
-- Configurable interaction limits and intervals
-- Smart caching to avoid duplicate processing
+### Bot Not Posting Automatically
 
-### Interaction Handling
+**Checklist:**
+- ✅ Is `TWITTER_POST_ENABLE=true`?
+- ✅ Is `@elizaos/plugin-bootstrap` installed?
+- ✅ Does your character have `postExamples`?
+- ✅ Check logs for "Twitter posting is ENABLED"
+- ✅ Try `TWITTER_POST_IMMEDIATELY=true` for testing
 
-Automatically handles:
-- **Mentions**: Responds to tweets mentioning the bot
-- **Replies**: Handles replies to the bot's tweets
-- **Direct Messages**: Processes DMs when enabled
-- **Target Users**: Can be configured to only interact with specific users
+### Timeline Not Loading
 
-### Search and Discovery
+**Common causes:**
+- Rate limiting (check Twitter Developer Portal)
+- Invalid credentials
+- Account restrictions
 
-- Timeline-based search and interaction
-- Configurable search intervals
-- Relevance-based filtering
-- User targeting with wildcard support
+### "Invalid or expired token"
 
-### Advanced Features
+Your tokens may have been revoked or regenerated.
 
-- **Request Queue**: Manages API rate limiting with exponential backoff
-- **Tweet Caching**: Efficient caching system for processed tweets
-- **Error Handling**: Robust retry mechanisms with configurable limits
-- **State Management**: Persistent state tracking across restarts
+**Solution:**
+1. Go to Twitter Developer Portal
+2. Regenerate all tokens
+3. Update `.env`
+4. Restart bot
 
-## Configuration Options
+## 📚 Advanced Features
 
 ### Timeline Algorithms
 
@@ -161,16 +308,16 @@ Automatically handles:
 # Interact with everyone (default)
 TWITTER_TARGET_USERS=
 
-# Interact with specific users
+# Interact with specific users only
 TWITTER_TARGET_USERS=user1,user2,user3
 
-# Interact with everyone (explicit wildcard)
+# Interact with everyone (explicit)
 TWITTER_TARGET_USERS=*
 ```
 
-### Interval Configuration
+### Natural Posting Intervals
 
-All intervals support variance for more natural behavior:
+All intervals support variance for more human-like behavior:
 ```bash
 # Base interval: 90-180 minutes
 TWITTER_POST_INTERVAL_MIN=90
@@ -179,9 +326,15 @@ TWITTER_POST_INTERVAL_MAX=180
 TWITTER_POST_INTERVAL_VARIANCE=0.2
 ```
 
-## Development
+### Request Queue & Rate Limiting
 
-### Testing
+The plugin includes sophisticated rate limiting:
+- Automatic retry with exponential backoff
+- Request queue to prevent API abuse
+- Configurable retry limits
+- Built-in caching to reduce API calls
+
+## 🧪 Development & Testing
 
 ```bash
 # Run tests
@@ -194,56 +347,47 @@ DEBUG=eliza:* bun start
 TWITTER_DRY_RUN=true bun start
 ```
 
-### Common Issues
-
-#### Authentication Failures
-- Verify all four API credentials are correctly set
-- Ensure your Twitter app has API v2 access enabled
-- Check that Access Token permissions match your use case
-- Verify your developer account is in good standing
-
-#### Rate Limiting
-- The client includes built-in rate limiting and retry mechanisms
-- Adjust `TWITTER_RETRY_LIMIT` if experiencing frequent failures
-- Consider increasing polling intervals for high-volume accounts
-
-#### No Interactions
-- Verify `TWITTER_SEARCH_ENABLE=true`
-- Check `TWITTER_TARGET_USERS` configuration
-- Ensure the timeline contains relevant content
-- Review `TWITTER_MAX_INTERACTIONS_PER_RUN` setting
-
-#### Timeline Issues
-- Try switching between "weighted" and "latest" algorithms
-- Adjust timeline weight parameters for better relevance
-- Check `TWITTER_POLL_INTERVAL` for timeline refresh rate
-
-## Security Notes
-
-- Store credentials in environment variables, never in code
-- Use `.env.local` or similar for local development
-- Regularly rotate API keys and tokens
-- Monitor API usage in Twitter Developer Portal
-- Enable only necessary permissions for Access Tokens
-
-## API Usage
-
-This plugin uses Twitter API v2 endpoints:
-- **Timeline endpoints**: For fetching home timeline and user tweets
-- **Tweet endpoints**: For posting tweets and fetching individual tweets
-- **User endpoints**: For user profile information
-- **Search endpoints**: For content discovery
-
-Monitor your API usage in the Twitter Developer Portal to avoid rate limits.
-
-## Support
-
-For issues or questions:
-1. Check the Common Issues section above
-2. Enable debug logging: `DEBUG=eliza:*`
-3. Verify your API credentials and permissions
-4. Check Twitter API v2 status and limits
-5. Open an issue with:
-   - Error messages and logs
-   - Configuration details (without credentials)
-   - Steps to reproduce
+### Testing Checklist
+
+1. **Test Auth**: Check logs for successful Twitter login
+2. **Test Posting**: Set `TWITTER_POST_IMMEDIATELY=true`
+3. **Test Dry Run**: Use `TWITTER_DRY_RUN=true` first
+4. **Monitor Logs**: Look for "Twitter posting is ENABLED"
+
+## 🔒 Security Best Practices
+
+- Store credentials in `.env` file (never commit!)
+- Use `.env.local` for local development
+- Regularly rotate API keys
+- Monitor API usage in Developer Portal
+- Enable only necessary permissions
+- Review [Twitter's automation rules](https://help.twitter.com/en/rules-and-policies/twitter-automation)
+
+## 📊 API Usage & Limits
+
+This plugin uses Twitter API v2 endpoints efficiently:
+- **Home Timeline**: Cached and refreshed periodically
+- **Tweet Creation**: Rate limited automatically
+- **User Lookups**: Cached to reduce calls
+- **Search**: Configurable intervals
+
+Monitor your usage at: https://developer.twitter.com/en/portal/dashboard
+
+## 📖 Additional Resources
+
+- [Twitter API v2 Documentation](https://developer.twitter.com/en/docs/twitter-api)
+- [Twitter OAuth 1.0a Guide](https://developer.twitter.com/en/docs/authentication/oauth-1-0a)
+- [Rate Limits Reference](https://developer.twitter.com/en/docs/twitter-api/rate-limits)
+- [ElizaOS Documentation](https://github.com/elizaos/eliza)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+1. Check existing issues first
+2. Follow the code style
+3. Add tests for new features
+4. Update documentation
+
+## 📝 License
+
+This plugin is part of the ElizaOS project. See the main repository for license information.