@defikitdotnet/x-ai-combat/README.md

XCombatAI - Social Media Engagement Template for the Agent Framework

# 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:

```typescript
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