@elizaos/plugin-twitter 1.0.0-beta.7 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +159 -0
  3. package/dist/index.js +891 -908
  4. package/dist/index.js.map +1 -1
  5. package/package.json +8 -3
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Shaw Walters, aka Moon aka @lalalune
3
+ Copyright (c) 2025 Shaw Walters and elizaOS Contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # Eliza Twitter/X Client
2
+
3
+ This package provides Twitter/X integration for the Eliza AI agent.
4
+
5
+ ## Features
6
+
7
+ - Post generation and management
8
+ - Interaction handling (mentions, replies)
9
+ - Search functionality
10
+ - Twitter Spaces support with STT/TTS capabilities
11
+ - Media handling (images, videos)
12
+ - Approval workflow via Discord (optional)
13
+
14
+ ## Setup Guide
15
+
16
+ ### Prerequisites
17
+
18
+ - A Twitter/X Developer Account with API access
19
+ - Node.js and pnpm installed
20
+ - Discord bot (if using approval workflow)
21
+ - ElevenLabs API key (if using Spaces with TTS)
22
+
23
+ ### Step 1: Configure Environment Variables
24
+
25
+ Create or edit `.env` file in your project root:
26
+
27
+ ```bash
28
+ # Twitter API Credentials
29
+ TWITTER_USERNAME= # Your Twitter/X username
30
+ TWITTER_PASSWORD= # Your Twitter/X password
31
+ TWITTER_EMAIL= # Your Twitter/X email
32
+ TWITTER_2FA_SECRET= # Optional: 2FA secret for login
33
+
34
+ # Twitter Client Configuration
35
+ TWITTER_DRY_RUN=false # Set to true for testing without posting
36
+ MAX_TWEET_LENGTH=280 # Default tweet length limit
37
+ TWITTER_SEARCH_ENABLE=false # Enable search functionality
38
+ TWITTER_RETRY_LIMIT=5 # Login retry attempts
39
+ TWITTER_POLL_INTERVAL=120 # Poll interval in seconds
40
+ TWITTER_TARGET_USERS= # Comma-separated list of target users
41
+
42
+ # Post Generation Settings
43
+ ENABLE_TWITTER_POST_GENERATION=true
44
+ POST_INTERVAL_MIN=90 # Minimum interval between posts (minutes)
45
+ POST_INTERVAL_MAX=180 # Maximum interval between posts (minutes)
46
+ POST_IMMEDIATELY=false # Skip approval workflow
47
+
48
+ # Action Processing
49
+ ENABLE_ACTION_PROCESSING=false
50
+ ACTION_INTERVAL=5 # Action check interval (minutes)
51
+ MAX_ACTIONS_PROCESSING=1 # Maximum concurrent actions
52
+
53
+ # Spaces Configuration (Optional)
54
+ TWITTER_SPACES_ENABLE=false
55
+ ELEVENLABS_XI_API_KEY= # Required for TTS in Spaces
56
+
57
+ # Approval Workflow (Optional)
58
+ TWITTER_APPROVAL_DISCORD_BOT_TOKEN=
59
+ TWITTER_APPROVAL_DISCORD_CHANNEL_ID=
60
+ TWITTER_APPROVAL_CHECK_INTERVAL=300000 # 5 minutes in milliseconds
61
+ ```
62
+
63
+ ### Step 2: Initialize the Client
64
+
65
+ ```typescript
66
+ import { TwitterClientInterface } from "@elizaos/twitter";
67
+
68
+ const twitterPlugin = {
69
+ name: "twitter",
70
+ description: "Twitter client",
71
+ clients: [TwitterClientInterface],
72
+ };
73
+
74
+ // Register with your Eliza runtime
75
+ runtime.registerPlugin(twitterPlugin);
76
+ ```
77
+
78
+ ## Features
79
+
80
+ ### Post Generation
81
+
82
+ The client can automatically generate and post tweets based on your agent's character profile and topics. Posts can be:
83
+ - Regular tweets (≤280 characters)
84
+ - Long-form tweets (Note Tweets)
85
+ - Media tweets (with images/videos)
86
+
87
+ ### Interactions
88
+
89
+ Handles:
90
+ - Mentions
91
+ - Replies
92
+ - Quote tweets
93
+ - Direct messages
94
+
95
+ ### Search
96
+
97
+ When enabled, periodically searches Twitter for relevant topics and engages with found content.
98
+
99
+ ### Twitter Spaces
100
+
101
+ Supports creating and managing Twitter Spaces with:
102
+ - Speech-to-Text (STT) for transcription
103
+ - Text-to-Speech (TTS) via ElevenLabs
104
+ - Speaker management
105
+ - Idle monitoring
106
+ - Recording capabilities
107
+
108
+ ### Approval Workflow
109
+
110
+ Optional Discord-based approval system for tweets:
111
+ 1. Generated tweets are sent to a Discord channel
112
+ 2. Moderators can approve/reject via reactions
113
+ 3. Approved tweets are automatically posted
114
+
115
+ ## Development
116
+
117
+ ### Testing
118
+
119
+ ```bash
120
+ # Run tests
121
+ pnpm test
122
+
123
+ # Run with debug logging
124
+ DEBUG=eliza:* pnpm start
125
+ ```
126
+
127
+ ### Common Issues
128
+
129
+ #### Login Failures
130
+ - Verify credentials in .env
131
+ - Check 2FA configuration
132
+ - Ensure no rate limiting
133
+
134
+ #### Post Generation Issues
135
+ - Verify character profile configuration
136
+ - Check MAX_TWEET_LENGTH setting
137
+ - Monitor approval workflow logs
138
+
139
+ #### Spaces Issues
140
+ - Verify ELEVENLABS_XI_API_KEY if using TTS
141
+ - Check space configuration in character profile
142
+ - Monitor idle timeout settings
143
+
144
+ ## Security Notes
145
+
146
+ - Never commit .env or credential files
147
+ - Use environment variables for sensitive data
148
+ - Implement proper rate limiting
149
+ - Monitor API usage and costs (especially for ElevenLabs)
150
+
151
+ ## Support
152
+
153
+ For issues or questions:
154
+ 1. Check the Common Issues section
155
+ 2. Review debug logs (enable with DEBUG=eliza:*)
156
+ 3. Open an issue with:
157
+ - Error messages
158
+ - Configuration details
159
+ - Steps to reproduce