@daydreamsai/twitter NPM

Enhanced Twitter Client for Daydreams AI

A comprehensive Twitter client package that provides robust Twitter functionality for AI agents, including advanced search, social interactions, direct messaging, analytics, and automated engagement features.

Features

🔍 Search & Discovery

Advanced tweet search with filters
Profile/user search
Hashtag tracking
Location-based search
Media-specific search (photos/videos)
Trending topics monitoring
Multi-criteria search queries

🤝 Social Interactions

Like tweets
Retweet content
Quote tweets with comments
Follow/unfollow users
Get followers and following lists
Engagement rate calculations
Smart engagement based on criteria

💬 Direct Messages

Send and receive DMs
Conversation management
Auto-reply functionality
Search conversations
Unread message tracking

📊 Analytics & Monitoring

Engagement metrics (likes, retweets, replies, views)
Follower statistics
Tweet performance analysis
Real-time mention monitoring
Trending topic tracking

🤖 Automation Features

Auto-engagement based on keywords
Proactive post generation with smart timing
Dynamic content creation using trending topics
Mood-based posting (informative, engaging, humorous, etc.)
Scheduled tweet threads
Bulk operations (follow, like, etc.)
Rate limiting and queue management
Conversation moderation

🎯 Advanced Tweet Features

Long-form tweets (Note Tweets)
Polls and interactive content
Media attachments
Tweet threads
Reply management

Installation

npm install @daydreamsai/twitter

Environment Variables

TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password
TWITTER_EMAIL=your_email
DRY_RUN=true  # Set to false for production
TWITTER_AUTO_ENGAGE=false
TWITTER_RATE_LIMIT_DELAY=1000  # milliseconds
TWITTER_POST_INTERVAL_MINUTES=120  # How often to generate new posts (default: 2 hours)

Quick Start

Basic Usage

import { EnhancedTwitterClient } from "@daydreamsai/twitter";

const client = new EnhancedTwitterClient({
  username: process.env.TWITTER_USERNAME!,
  password: process.env.TWITTER_PASSWORD!,
  email: process.env.TWITTER_EMAIL!,
});

await client.initialize();

// Send a tweet
await client.sendEnhancedTweet({
  content: "Hello from Daydreams AI! 🤖",
  isLongTweet: false,
});

// Search for tweets
const results = await client.searchTweets("AI agents", {
  maxResults: 10,
  mode: SearchMode.Latest,
});

// Auto-engage with relevant content
await client.autoEngage({
  enabled: true,
  keywords: ["AI", "automation", "bots"],
  excludeKeywords: ["spam"],
  minLikes: 5,
  maxLikes: 1000,
  actions: {
    like: true,
    retweet: false,
    reply: true,
  },
  replyTemplates: [
    "Great point about AI!",
    "Interesting perspective 🤔",
    "Thanks for sharing!",
  ],
});

Daydreams Extension Usage

import { enhancedTwitter } from "@daydreamsai/twitter";

// Use in your agent configuration
const agent = createAgent({
  extensions: [enhancedTwitter],
  // ... other config
});

API Reference

Core Classes

`EnhancedTwitterClient`

Main client class that provides all Twitter functionality.

Methods:

initialize() - Initialize the client and authenticate
sendEnhancedTweet(data) - Send tweets with advanced features
sendThread(thread) - Send a thread of connected tweets
searchTweets(query, options) - Search for tweets
searchProfiles(query, options) - Search for users
likeTweet(tweetId) - Like a specific tweet
retweet(tweetId) - Retweet content
quoteTweet(tweetId, comment) - Quote tweet with comment
followUser(username) - Follow a user
getFollowers(userId) - Get user's followers
getFollowing(userId) - Get who user follows
sendDirectMessage(conversationId, text) - Send a DM
autoEngage(config) - Automated engagement
getEngagementMetrics(tweetId) - Get tweet analytics

`TwitterSearchService`

Specialized service for search functionality.

`TwitterSocialService`

Handles social interactions and engagement.

`TwitterMessagesService`

Manages direct messages and conversations.

Extension Outputs

Tweet Operations

// Basic tweet
await agent.output("twitter:tweet", {
  content: "Hello Twitter!",
});

// Enhanced tweet with poll
await agent.output("twitter:tweet", {
  content: "What's your favorite AI framework?",
  poll: {
    options: ["TensorFlow", "PyTorch", "JAX", "Other"],
    durationMinutes: 1440, // 24 hours
  },
});

// Thread
await agent.output("twitter:thread", {
  tweets: [
    "🧵 Thread about AI safety (1/3)",
    "First, we need to consider alignment...",
    "Finally, governance is crucial for responsible AI.",
  ],
  delay: 5, // seconds between tweets
});

Social Interactions

// Like a tweet
await agent.output("twitter:like", {
  tweetId: "1234567890",
});

// Retweet
await agent.output("twitter:retweet", {
  tweetId: "1234567890",
});

// Quote tweet
await agent.output("twitter:quote", {
  tweetId: "1234567890",
  comment: "Great insights! Adding my perspective...",
});

// Follow user
await agent.output("twitter:follow", {
  username: "elonmusk",
});

Search & Discovery

// Search tweets
await agent.output("twitter:search", {
  query: "artificial intelligence",
  maxResults: 20,
  mode: "latest",
});

Analytics

// Get tweet analytics
await agent.output("twitter:analytics", {
  tweetId: "1234567890",
});

Auto-Engagement

await agent.output("twitter:auto-engage", {
  enabled: true,
  keywords: ["AI", "machine learning"],
  excludeKeywords: ["crypto", "NFT"],
  minLikes: 10,
  maxLikes: 500,
  actions: {
    like: true,
    retweet: false,
    reply: true,
  },
  replyTemplates: [
    "Interesting point about AI!",
    "Thanks for sharing this insight",
  ],
});

Proactive Post Generation

The agent automatically receives prompts to create original content:

// Agent receives this input every 2 hours (configurable)
// Input format:
{
  trigger: "scheduled",
  context: "Create a tweet related to current trends. Consider: Artificial Intelligence",
  mood: "engaging",
  maxLength: 280
}

// Agent can then respond with:
await agent.output("twitter:tweet", {
  content: "🤖 AI is transforming how we work and create. What's the most exciting AI development you've seen this week? #AI #Innovation",
});

// Or create a thread:
await agent.output("twitter:thread", {
  tweets: [
    "🧵 Thread: The evolution of AI (1/3)",
    "AI went from science fiction to daily reality in just a few years...",
    "What excites you most about AI's future? Drop your thoughts below! 👇"
  ],
  delay: 5
});

Extension Inputs

The extension automatically monitors:

Mentions - Real-time mention monitoring every 30 seconds
Trending Topics - Trending hashtags and topics every 5 minutes
Post Generation - Proactive tweet creation prompts (configurable interval, default 2 hours)

Post Generation Input

The twitter:generate-post input automatically triggers your agent to create original content:

<post-prompt trigger="scheduled" mood="engaging" maxLength="280">
Create a tweet related to current trends. Consider: AI and automation
</post-prompt>

Features:

Smart timing: Configurable posting intervals via TWITTER_POST_INTERVAL_MINUTES
Dynamic context: Incorporates current trending topics when available
Mood variety: Rotates between informative, engaging, humorous, professional, and casual tones
Trigger types: Scheduled, trending-based, or random prompts

Configuration:

TWITTER_POST_INTERVAL_MINUTES=120  # Post every 2 hours (default)
TWITTER_POST_INTERVAL_MINUTES=60   # Post every hour
TWITTER_POST_INTERVAL_MINUTES=720  # Post every 12 hours

Advanced Features

Rate Limiting

The client includes built-in rate limiting to prevent API abuse:

// Automatic rate limiting with configurable delays
const client = new EnhancedTwitterClient(credentials);
// All methods are automatically rate-limited

Bulk Operations

// Follow multiple users
const results = await client.bulkFollow(["user1", "user2", "user3"]);

// Each operation includes delay to respect rate limits

Smart Engagement

// Engage with content based on sophisticated criteria
const config = {
  enabled: true,
  keywords: ["AI", "automation"],
  excludeKeywords: ["spam", "promotional"],
  minLikes: 5,
  maxLikes: 1000,
  actions: {
    like: true,
    retweet: false,
    reply: true,
  },
  replyTemplates: ["Great point!", "Interesting perspective!"],
};

await client.autoEngage(config);

Analytics Dashboard

// Get comprehensive metrics
const metrics = await client.getEngagementMetrics(tweetId);
console.log({
  likes: metrics.likes,
  retweets: metrics.retweets,
  replies: metrics.replies,
  views: metrics.views,
  engagementRate: metrics.engagementRate,
});

Error Handling

All methods include comprehensive error handling:

try {
  const result = await client.likeTweet(tweetId);
  if (result.success) {
    console.log("Tweet liked successfully");
  } else {
    console.error("Failed to like tweet:", result.error);
  }
} catch (error) {
  console.error("Network or API error:", error);
}