first commit

STEAM_BOT_SETUP.md

@@ -0,0 +1,655 @@
+# Steam Bot Setup Guide
+
+## 🤖 Overview
+
+The Steam bot system handles trade offers for buying items from users. When a user sells items, instead of immediately crediting funds, the system:
+
+1. ✅ Creates a trade offer via Steam bot
+2. ⏳ Tracks trade state (pending, accepted, declined, etc.)
+3. 💰 Credits user balance ONLY after trade is accepted
+4. 🔄 Handles failures, expirations, and retries
+
+---
+
+## 📋 Prerequisites
+
+### 1. Steam Bot Account
+
+You need a separate Steam account for the bot:
+
+- ✅ Account with Steam Mobile Authenticator enabled
+- ✅ Public inventory
+- ✅ Valid trade URL
+- ✅ API key from https://steamcommunity.com/dev/apikey
+- ✅ Not limited (must have spent $5+ on Steam)
+- ✅ Trade cooldown period expired (if newly set up)
+
+### 2. Required Packages
+
+Already installed in package.json:
+```json
+{
+  "steam-user": "^5.0.0",
+  "steamcommunity": "^3.47.0",
+  "steam-tradeoffer-manager": "^2.10.6",
+  "steam-totp": "^2.1.1"
+}
+```
+
+Install if needed:
+```bash
+npm install steam-user steamcommunity steam-tradeoffer-manager steam-totp
+```
+
+---
+
+## 🔐 Getting Steam Bot Credentials
+
+### Step 1: Get Shared Secret & Identity Secret
+
+1. **Enable Steam Mobile Authenticator** on bot account
+2. Use one of these tools to extract secrets:
+   - **SDA (Steam Desktop Authenticator)**: https://github.com/Jessecar96/SteamDesktopAuthenticator
+   - **Android**: Use app like "Steam Guard Mobile Authenticator"
+   - **Manual extraction**: Follow guides online
+
+3. You'll need:
+   - `shared_secret` - For generating 2FA codes
+   - `identity_secret` - For confirming trades
+
+### Step 2: Get Steam API Key
+
+1. Go to: https://steamcommunity.com/dev/apikey
+2. Register domain: `turbotrades.com` (or your domain)
+3. Copy the API key
+
+### Step 3: Get Bot Trade URL
+
+1. Login to bot account
+2. Go to: https://steamcommunity.com/id/me/tradeoffers/privacy
+3. Copy the trade URL (looks like: `https://steamcommunity.com/tradeoffer/new/?partner=XXXXX&token=XXXXXXXX`)
+
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+Add to your `.env` file:
+
+```env
+# Steam Bot Credentials
+STEAM_BOT_USERNAME=your_bot_username
+STEAM_BOT_PASSWORD=your_bot_password
+STEAM_BOT_SHARED_SECRET=your_shared_secret_here
+STEAM_BOT_IDENTITY_SECRET=your_identity_secret_here
+
+# Steam API
+STEAM_API_KEY=your_steam_api_key
+
+# Bot Trade URL
+STEAM_BOT_TRADE_URL=https://steamcommunity.com/tradeoffer/new/?partner=XXXXX&token=XXXXXXXX
+
+# Optional: Bot Settings
+STEAM_BOT_POLL_INTERVAL=30000
+STEAM_BOT_AUTO_START=true
+```
+
+### Security Notes
+
+- ⚠️ **NEVER commit `.env` to git**
+- ⚠️ Keep secrets secure
+- ⚠️ Use different account from your personal Steam
+- ⚠️ Enable Steam Guard on bot account
+- ⚠️ Use strong password
+
+---
+
+## 🚀 Starting the Bot
+
+### Automatic Start (Recommended)
+
+Bot starts automatically when backend launches if `STEAM_BOT_AUTO_START=true`
+
+```bash
+npm run dev
+```
+
+You'll see:
+```
+🔐 Logging into Steam...
+✅ Steam bot logged in successfully
+✅ Steam web session established
+🤖 Steam bot ready for trades
+```
+
+### Manual Start
+
+```javascript
+import { getSteamBot } from './services/steamBot.js';
+
+const bot = getSteamBot();
+await bot.login();
+
+console.log('Bot ready:', bot.isOnline());
+```
+
+---
+
+## 🔄 How It Works
+
+### User Sells Items Flow
+
+```
+1. User selects items on Sell page
+2. User clicks "Sell Selected Items"
+   ↓
+3. Backend creates Trade record (state: pending)
+   - Does NOT credit balance yet
+   ↓
+4. Steam bot creates trade offer
+   - Requests items from user
+   - User sees trade offer in Steam
+   ↓
+5. User accepts trade in Steam app
+   ↓
+6. Bot receives "trade accepted" event
+   ↓
+7. Backend:
+   - Updates Trade state to "accepted"
+   - Creates Transaction record
+   - Credits user balance
+   - Updates WebSocket
+   ↓
+8. User sees balance update in UI
+```
+
+### Trade States
+
+| State | Description | User Balance | Can Retry |
+|-------|-------------|--------------|-----------|
+| **pending** | Trade offer sent, waiting for user | ❌ Not credited | ✅ Yes |
+| **accepted** | User accepted, items received | ✅ Credited | ❌ No |
+| **declined** | User declined the offer | ❌ Not credited | ⚠️ Maybe |
+| **expired** | Trade offer expired (10min timeout) | ❌ Not credited | ✅ Yes |
+| **canceled** | Trade was canceled | ❌ Not credited | ✅ Yes |
+| **failed** | Technical error occurred | ❌ Not credited | ✅ Yes |
+| **escrow** | Trade in Steam escrow | ❌ Not credited | ⏳ Wait |
+
+---
+
+## 📊 Database Schema
+
+### Trade Model
+
+```javascript
+{
+  offerId: String,           // Steam trade offer ID
+  userId: ObjectId,          // User who's selling
+  steamId: String,           // User's Steam ID
+  state: String,             // pending, accepted, declined, etc.
+  items: [{
+    assetId: String,
+    name: String,
+    price: Number,
+    image: String,
+    // ... item details
+  }],
+  totalValue: Number,        // Total price of all items
+  fee: Number,               // Platform fee (e.g., 5%)
+  feePercentage: Number,     // Fee percentage
+  userReceives: Number,      // Amount user gets (after fees)
+  tradeUrl: String,          // User's trade URL
+  tradeOfferUrl: String,     // Link to view offer on Steam
+  sentAt: Date,              // When trade was sent
+  acceptedAt: Date,          // When user accepted
+  completedAt: Date,         // When balance was credited
+  expiresAt: Date,           // When trade expires (10min)
+  transactionId: ObjectId,   // Transaction created after acceptance
+  sessionId: ObjectId,       // User's session
+  errorMessage: String,      // If failed
+  retryCount: Number,        // How many times retried
+  metadata: Mixed            // Additional data
+}
+```
+
+---
+
+## 🎮 Bot Events
+
+The bot emits events you can listen to:
+
+```javascript
+const bot = getSteamBot();
+
+// Bot is ready
+bot.on('ready', () => {
+  console.log('Bot is ready!');
+});
+
+// Trade accepted
+bot.on('tradeAccepted', async (offer, tradeData) => {
+  console.log('Trade accepted:', offer.id);
+  // Credit user balance here
+});
+
+// Trade declined
+bot.on('tradeDeclined', async (offer, tradeData) => {
+  console.log('Trade declined:', offer.id);
+  // Notify user
+});
+
+// Trade expired
+bot.on('tradeExpired', async (offer, tradeData) => {
+  console.log('Trade expired:', offer.id);
+  // Can retry or cancel
+});
+
+// Bot error
+bot.on('error', (err) => {
+  console.error('Bot error:', err);
+});
+
+// Bot disconnected
+bot.on('disconnected', () => {
+  console.warn('Bot disconnected, will reconnect...');
+});
+```
+
+---
+
+## 🛠️ API Endpoints
+
+### Create Trade Offer
+
+```http
+POST /api/trade/create
+Authorization: Bearer <token>
+
+{
+  "items": [
+    {
+      "assetId": "123456789",
+      "name": "AK-47 | Redline (Field-Tested)",
+      "price": 12.50,
+      "image": "https://...",
+      // ... other item data
+    }
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "trade": {
+    "id": "trade_id",
+    "offerId": "steam_offer_id",
+    "state": "pending",
+    "totalValue": 12.50,
+    "userReceives": 11.88,
+    "items": [...],
+    "tradeOfferUrl": "https://steamcommunity.com/tradeoffer/...",
+    "expiresAt": "2024-01-10T12:10:00Z"
+  },
+  "message": "Trade offer sent! Check your Steam app to accept."
+}
+```
+
+### Get Trade Status
+
+```http
+GET /api/trade/:tradeId
+Authorization: Bearer <token>
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "trade": {
+    "id": "trade_id",
+    "offerId": "steam_offer_id",
+    "state": "accepted",
+    "totalValue": 12.50,
+    "userReceives": 11.88,
+    "acceptedAt": "2024-01-10T12:05:00Z",
+    "timeElapsed": "5m ago"
+  }
+}
+```
+
+### Cancel Trade
+
+```http
+POST /api/trade/:tradeId/cancel
+Authorization: Bearer <token>
+```
+
+### Retry Trade
+
+```http
+POST /api/trade/:tradeId/retry
+Authorization: Bearer <token>
+```
+
+---
+
+## 🔧 Bot Management
+
+### Check Bot Status
+
+```javascript
+const bot = getSteamBot();
+
+const health = bot.getHealth();
+console.log(health);
+// {
+//   isReady: true,
+//   isLoggedIn: true,
+//   activeTradesCount: 5,
+//   username: "bot_username"
+// }
+```
+
+### Get Active Trades
+
+```javascript
+const activeTrades = bot.getActiveTrades();
+console.log(`${activeTrades.length} trades active`);
+```
+
+### Cancel All Pending Trades
+
+```javascript
+const pendingTrades = await Trade.getPendingTrades();
+
+for (const trade of pendingTrades) {
+  if (trade.isExpired) {
+    await bot.cancelTradeOffer(trade.offerId);
+    await trade.markAsExpired();
+  }
+}
+```
+
+---
+
+## 🧪 Testing
+
+### Test Bot Login
+
+```bash
+node -e "import('./services/steamBot.js').then(async m => {
+  const bot = m.getSteamBot();
+  await bot.login();
+  console.log('Bot logged in:', bot.isOnline());
+  bot.logout();
+  process.exit(0);
+})"
+```
+
+### Test Trade Creation
+
+```javascript
+const bot = getSteamBot();
+await bot.login();
+
+const result = await bot.createTradeOffer({
+  tradeUrl: "https://steamcommunity.com/tradeoffer/new/?partner=XXX&token=XXX",
+  itemsToReceive: [
+    { assetid: "123456789", appid: 730, contextid: 2 }
+  ],
+  message: "Test trade offer"
+});
+
+console.log('Trade created:', result);
+```
+
+---
+
+## 📈 Monitoring
+
+### Database Queries
+
+```javascript
+// Get all pending trades
+const pending = await Trade.find({ state: 'pending' });
+
+// Get expired trades
+const expired = await Trade.getExpiredTrades();
+
+// Get trade stats
+const stats = await Trade.getStats();
+console.log(`
+  Total trades: ${stats.total}
+  Accepted: ${stats.accepted}
+  Pending: ${stats.pending}
+  Declined: ${stats.declined}
+`);
+
+// Get user's trades
+const userTrades = await Trade.getUserTrades(userId);
+```
+
+### Admin Panel Integration
+
+Add to admin panel:
+- ✅ View pending trades
+- ✅ Cancel stale trades
+- ✅ Retry failed trades
+- ✅ View trade statistics
+- ✅ Bot health status
+
+---
+
+## 🐛 Troubleshooting
+
+### Bot Won't Login
+
+**Check:**
+- ✅ Username and password correct
+- ✅ Shared secret is valid
+- ✅ Steam account not limited
+- ✅ No active VAC ban
+- ✅ No trade cooldown
+
+**Solution:**
+```bash
+# Test credentials
+node -e "console.log('Username:', process.env.STEAM_BOT_USERNAME)"
+node -e "console.log('Has password:', !!process.env.STEAM_BOT_PASSWORD)"
+node -e "console.log('Has shared secret:', !!process.env.STEAM_BOT_SHARED_SECRET)"
+```
+
+### Trades Not Confirming
+
+**Check:**
+- ✅ Identity secret is correct
+- ✅ Mobile authenticator is active
+- ✅ Bot has trade URL
+
+**Solution:**
+- Manually confirm in Steam app first time
+- Check if identity secret is correct
+- Regenerate secrets if needed
+
+### Trades Stuck in Pending
+
+**Reasons:**
+- User hasn't accepted yet
+- Trade expired (10 minutes)
+- Steam API issues
+- User's inventory is private
+
+**Solution:**
+```javascript
+// Cancel expired trades
+const expired = await Trade.find({
+  state: 'pending',
+  expiresAt: { $lt: new Date() }
+});
+
+for (const trade of expired) {
+  await bot.cancelTradeOffer(trade.offerId);
+  await trade.markAsExpired();
+}
+```
+
+### Bot Keeps Disconnecting
+
+**Check:**
+- ✅ Network connection stable
+- ✅ Steam not under maintenance
+- ✅ No rate limiting
+
+**Solution:**
+- Implement auto-reconnect (already built-in)
+- Use connection pooling
+- Monitor logs for error patterns
+
+---
+
+## 🔒 Security Best Practices
+
+### 1. Secure Credentials
+- ✅ Never hardcode credentials
+- ✅ Use environment variables
+- ✅ Keep .env out of git
+- ✅ Rotate secrets regularly
+
+### 2. Trade Validation
+- ✅ Verify user owns items before creating trade
+- ✅ Check item values match database
+- ✅ Validate trade URLs
+- ✅ Prevent duplicate trades
+
+### 3. Rate Limiting
+- ✅ Limit trades per user per hour
+- ✅ Limit total trades per minute
+- ✅ Queue trades during high load
+
+### 4. Monitoring
+- ✅ Log all trade events
+- ✅ Alert on failed trades
+- ✅ Track bot uptime
+- ✅ Monitor Steam API status
+
+---
+
+## 📊 Performance Optimization
+
+### Trade Queue System
+
+For high volume, implement trade queue:
+
+```javascript
+// Redis-based queue
+import Bull from 'bull';
+
+const tradeQueue = new Bull('trades', {
+  redis: { host: 'localhost', port: 6379 }
+});
+
+tradeQueue.process(async (job) => {
+  const { userId, items } = job.data;
+  return await createTradeOffer(userId, items);
+});
+
+// Add to queue
+await tradeQueue.add({ userId, items }, {
+  attempts: 3,
+  backoff: {
+    type: 'exponential',
+    delay: 2000
+  }
+});
+```
+
+### Retry Strategy
+
+```javascript
+async function createTradeWithRetry(data, maxRetries = 3) {
+  let lastError;
+  
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await bot.createTradeOffer(data);
+    } catch (error) {
+      lastError = error;
+      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
+    }
+  }
+  
+  throw lastError;
+}
+```
+
+---
+
+## 🎯 Next Steps
+
+### Phase 1: Basic Setup (You are here)
+- [x] Install packages
+- [x] Create bot service
+- [x] Create Trade model
+- [ ] Configure environment variables
+- [ ] Test bot login
+
+### Phase 2: Integration
+- [ ] Update sell endpoint to create trades
+- [ ] Add trade event handlers
+- [ ] Credit balance on acceptance
+- [ ] Add trade status polling
+
+### Phase 3: Frontend
+- [ ] Show trade status in UI
+- [ ] Add "View Trade" button
+- [ ] Show pending trades list
+- [ ] Add trade notifications
+
+### Phase 4: Admin Tools
+- [ ] Bot health dashboard
+- [ ] Trade management panel
+- [ ] Retry/cancel controls
+- [ ] Statistics and reports
+
+### Phase 5: Advanced
+- [ ] Trade queue system
+- [ ] Multiple bot support
+- [ ] Automatic retries
+- [ ] Fraud detection
+
+---
+
+## 📚 Additional Resources
+
+- **Steam Web API**: https://developer.valvesoftware.com/wiki/Steam_Web_API
+- **Trade Offer Manager**: https://github.com/DoctorMcKay/node-steam-tradeoffer-manager
+- **Steam User**: https://github.com/DoctorMcKay/node-steam-user
+- **Steam TOTP**: https://github.com/DoctorMcKay/node-steam-totp
+
+---
+
+## ✅ Configuration Checklist
+
+Before going live:
+
+- [ ] Bot account created and funded ($5+ spent)
+- [ ] Steam Mobile Authenticator enabled
+- [ ] Shared secret and identity secret extracted
+- [ ] API key obtained from Steam
+- [ ] Environment variables configured
+- [ ] Bot successfully logs in
+- [ ] Test trade offer sent and accepted
+- [ ] Trade events properly handled
+- [ ] Balance credits on acceptance
+- [ ] Error handling tested
+- [ ] Monitoring set up
+- [ ] Backup credentials stored securely
+
+---
+
+**Status**: Implementation Ready
+**Next**: Configure bot credentials and test login
+**Priority**: High - Required for production sell functionality