XCombatAI

XCombatAI is a social media engagement template for the Agent Framework that utilizes the @defikitdotnet/agent-twitter-client package for Twitter interactions without requiring the Twitter API.

Features

• Login with X API: A dedicated API endpoint to handle Twitter authentication for users on the web platform
• Interaction Scanner: Scheduled job that scans posts mentioning the agent and identifies user interactions
• Bot Responder: Monitors posts and replies to unlinked users with contextual AI-generated prompts
• Fame Points System: Track and reward user engagement with a leaderboard

Architecture

The system consists of the following components:

Resource Models

• User: Stores information about users who link their Twitter accounts via the Login with X API
• Post: Uses the Tweet class from @defikitdotnet/agent-twitter-client to store tweet data
• Interaction: Tracks user interactions (likes, retweets, quotes, replies) with posts mentioning the agent

API Endpoints

• Full CRUD operations for User, Post, and Interaction management
• Custom endpoints for:
  • Login with X API (Twitter OAuth flow)
  • Fetching posts interacted by users
  • Retrieving interaction statistics

Plugins

• InteractionScanner: Scans Twitter for posts mentioning the agent and identifies user interactions
• BotResponder: Monitors posts and replies to unlinked users with contextual prompts

Services

• AI Service: Powered by Google Gemini to generate contextual reply prompts

Frontend Components

• PostPanel: Displays a list of posts a user has interacted with
• LeaderboardPanel: Ranks users based on Fame Points calculated from interactions

Setup

1. Clone the repository
2. Install dependencies:

   npm install

3. Create a .env file based on .env.example with your Twitter credentials and other configuration
4. Run the development server:

   npm run dev

Environment Variables

• PORT: Server port (default: 3000)
• DATABASE_URL: Postgres database connection string
• JWT_SECRET: Secret key for JWT tokens
• TWITTER_USERNAME: Twitter username for the bot account
• TWITTER_PASSWORD: Twitter password for the bot account
• TWITTER_EMAIL: Twitter email for the bot account (optional)
• AGENT_TWITTER_HANDLE: Twitter handle for the agent (default: @XCombatAI)
• GEMINI_API_KEY: Google Gemini API key for AI-generated replies
• TELEGRAM_BOT_TOKEN: Telegram bot token for notifications
• TELEGRAM_CHAT_ID: Telegram chat ID for notifications
• WEB_PLATFORM_URL: URL to your web platform for the "Login with X" flow

Fame Points System

Fame Points are calculated as follows:

• Likes: 0.5 points
• Retweets: 2 points
• Quotes: 2 points
• Replies: 1 point

Authentication Options

Regular Authentication

The application supports regular username/password authentication for Twitter:

TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password 
TWITTER_EMAIL=your_email

Cookie-Based Authentication

To bypass the login process entirely, you can provide Twitter cookies directly:

1. Extract cookies from a browser session where you're logged into Twitter
2. Format them as a JSON array and set in your environment:

TWITTER_COOKIES=[ ... cookie array ... ]

To get your cookies:

1. Log in to Twitter using the application once
2. Use the provided utility to export cookies:

import { TwitterService } from './services/twitter-service';

async function exportCookies() {
  const service = TwitterService.getInstance();
  await service.initialize();
  const cookieJson = await service.getCookiesForExport();
  console.log('Add this to your .env file:');
  console.log(`TWITTER_COOKIES='${cookieJson}'`);
}

Cookie Caching with Redis

For improved reliability, the app can cache cookies using Redis:

REDIS_URL=redis://localhost:6379

When Redis is configured, successful logins will cache cookies for future use, reducing the need for frequent logins.

License

ISC