TurboTrades/API_ENDPOINTS.md

# TurboTrades API Endpoints Reference

Complete list of all available API endpoints with examples.

---

## Base URL

- **Development**: `http://localhost:3000`
- **Frontend Proxy**: `http://localhost:5173/api` (proxies to backend)

---

## Authentication Endpoints

### `/auth/*`

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/auth/steam` | Initiate Steam login | No |
| GET | `/auth/steam/return` | Steam OAuth callback | No |
| GET | `/auth/steam/test` | Test Steam config | No |
| GET | `/auth/me` | Get current user | Yes (Access Token) |
| POST | `/auth/refresh` | Refresh access token | Yes (Refresh Token) |
| POST | `/auth/logout` | Logout user | Yes (Access Token) |
| GET | `/auth/verify` | Verify token validity | Yes (Access Token) |
| GET | `/auth/decode-token` | Decode JWT token (debug) | No |

### Example Usage:

```bash
# Login via Steam (opens browser)
curl http://localhost:3000/auth/steam

# Get current user (requires auth)
curl http://localhost:3000/auth/me \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Refresh token
curl -X POST http://localhost:3000/auth/refresh \
  -H "Cookie: refreshToken=YOUR_REFRESH_TOKEN"
```

---

## User Endpoints

### `/user/*`

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/user/profile` | Get user profile | Yes |
| PATCH | `/user/email` | Update email address | Yes |
| GET | `/user/verify-email/:token` | Verify email | No |
| PATCH | `/user/trade-url` | Update Steam trade URL | Yes |
| GET | `/user/balance` | Get user balance | Yes |
| GET | `/user/stats` | Get user statistics | Yes |
| PATCH | `/user/intercom` | Update intercom ID | Yes |
| GET | `/user/:steamId` | Get public user profile | No |

### Example Usage:

```bash
# Get profile
curl http://localhost:3000/user/profile \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Update email
curl -X PATCH http://localhost:3000/user/email \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Update trade URL
curl -X PATCH http://localhost:3000/user/trade-url \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tradeUrl": "https://steamcommunity.com/tradeoffer/new/?partner=123&token=abc"}'
```

---

## Two-Factor Authentication (2FA) Endpoints

### `/user/2fa/*`

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/user/2fa/setup` | Generate QR code & secret | Yes |
| POST | `/user/2fa/verify` | Verify code & enable 2FA | Yes |
| POST | `/user/2fa/disable` | Disable 2FA | Yes |

### Example Usage:

```bash
# Setup 2FA (get QR code)
curl -X POST http://localhost:3000/user/2fa/setup \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Verify 2FA code
curl -X POST http://localhost:3000/user/2fa/verify \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "123456"}'

# Disable 2FA
curl -X POST http://localhost:3000/user/2fa/disable \
  -H "Cookie: accessToken=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "123456"}'
```

---

## Session Management Endpoints

### `/user/sessions/*`

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/user/sessions` | Get all active sessions | Yes |
| DELETE | `/user/sessions/:sessionId` | Revoke specific session | Yes |
| POST | `/user/sessions/revoke-all` | Revoke all other sessions | Yes |

### Example Usage:

```bash
# Get all sessions
curl http://localhost:3000/user/sessions \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Revoke specific session
curl -X DELETE http://localhost:3000/user/sessions/SESSION_ID \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Revoke all other sessions
curl -X POST http://localhost:3000/user/sessions/revoke-all \
  -H "Cookie: accessToken=YOUR_TOKEN"
```

---

## Market Endpoints

### `/market/*`

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/market/items` | Get marketplace items | No |
| GET | `/market/items/:id` | Get item details | No |
| GET | `/market/featured` | Get featured items | No |
| GET | `/market/recent-sales` | Get recent sales | No |
| GET | `/market/stats` | Get market statistics | No |
| POST | `/market/purchase/:id` | Purchase an item | Yes |

### Example Usage:

```bash
# Get all items
curl http://localhost:3000/market/items

# Get items with filters
curl "http://localhost:3000/market/items?game=cs2&minPrice=10&maxPrice=100&limit=20"

# Get featured items
curl http://localhost:3000/market/featured

# Get item details
curl http://localhost:3000/market/items/ITEM_ID

# Purchase item
curl -X POST http://localhost:3000/market/purchase/ITEM_ID \
  -H "Cookie: accessToken=YOUR_TOKEN"

# Get market stats
curl http://localhost:3000/market/stats
```

---

## WebSocket Endpoint

### `/ws`

Real-time updates via WebSocket.

```javascript
// Connect to WebSocket
const ws = new WebSocket('ws://localhost:3000/ws');

// Listen for messages
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Send ping
ws.send(JSON.stringify({ type: 'ping' }));
```

**Events:**
- `listing_update` - Item listing updated
- `listing_removed` - Item removed from market
- `listing_added` - New item added to market
- `price_update` - Item price changed
- `market_update` - Bulk market updates
- `pong` - Response to ping

---

## Testing from Frontend

### Using Axios (already configured):

```javascript
import axios from '@/utils/axios'

// Get user profile
const response = await axios.get('/api/user/profile', {
  withCredentials: true
})

// Update email
await axios.patch('/api/user/email', {
  email: 'user@example.com'
}, {
  withCredentials: true
})

// Setup 2FA
const response = await axios.post('/api/user/2fa/setup', {}, {
  withCredentials: true
})

// Get sessions
const response = await axios.get('/api/user/sessions', {
  withCredentials: true
})
```

---

## Common Issues & Solutions

### 1. "Unauthorized" Error

**Cause**: No access token provided or token expired.

**Solution**:
- Login via Steam first: `http://localhost:3000/auth/steam`
- Ensure cookies are being sent: `withCredentials: true`
- Check if token is expired (15 minutes lifetime)
- Use refresh token to get new access token

### 2. "Route not found"

**Cause**: Incorrect URL or route not registered.

**Solution**:
- Check the route prefix (`/auth`, `/user`, `/market`)
- Verify the HTTP method (GET, POST, PATCH, DELETE)
- Check backend logs for route registration

### 3. CORS Issues

**Cause**: Frontend and backend on different ports.

**Solution**:
- Ensure `CORS_ORIGIN=http://localhost:5173` in `.env`
- Restart backend after changing `.env`
- Use frontend proxy: `/api/*` instead of direct backend URL

### 4. Sessions Not Working

**Cause**: Session model not properly imported or MongoDB issue.

**Solution**:
- Check MongoDB is running: `mongod`
- Verify Session model exists: `models/Session.js`
- Check backend logs for session creation errors
- Ensure TTL index is created on `expiresAt` field

---

## Response Formats

### Success Response:
```json
{
  "success": true,
  "data": { ... }
}
```

### Error Response:
```json
{
  "error": "ErrorType",
  "message": "Human readable error message",
  "details": { ... }
}
```

---

## Authentication Flow

1. User clicks "Login with Steam" → `/auth/steam`
2. Redirects to Steam OpenID
3. User authenticates on Steam
4. Steam redirects back → `/auth/steam/return`
5. Backend generates JWT tokens
6. Sets `accessToken` and `refreshToken` cookies
7. Redirects to frontend → `http://localhost:5173/`

---

## Token Lifetimes

- **Access Token**: 15 minutes
- **Refresh Token**: 7 days
- **Session TTL**: 7 days (auto-deleted by MongoDB)

---

## Frontend Routes

| Route | Component | Auth Required |
|-------|-----------|---------------|
| `/` | HomePage | No |
| `/market` | MarketPage | No |
| `/item/:id` | ItemDetailsPage | No |
| `/profile` | ProfilePage | Yes |
| `/inventory` | InventoryPage | Yes |
| `/sell` | SellPage | Yes |
| `/transactions` | TransactionsPage | Yes |
| `/deposit` | DepositPage | Yes |
| `/withdraw` | WithdrawPage | Yes |
| `/admin` | AdminPage | Yes (Admin only) |
| `/faq` | FAQPage | No |
| `/support` | SupportPage | No |
| `/terms` | TermsPage | No |
| `/privacy` | PrivacyPage | No |

---

## Quick Start Testing

1. **Start MongoDB**: `mongod`
2. **Seed Database**: `npm run seed`
3. **Start Backend**: `npm run dev`
4. **Start Frontend**: `cd frontend && npm run dev`
5. **Login**: Navigate to `http://localhost:5173` and login with Steam
6. **Test Routes**: Use browser DevTools Network tab or curl commands above

---

## Notes

- All timestamps are in UTC
- Prices are in USD
- Image URLs may be Steam CDN or placeholder
- WebSocket connections are optional
- Rate limiting: 100 requests per minute (development)