trading_bot_v3/SESSION_PERSISTENCE.md

# TradingView Session Persistence & Captcha Avoidance

## Problem

TradingView implements "Are you human?" captcha checks that block automated login attempts. This prevents our trading bot from automatically logging in and capturing screenshots for analysis.

## Solution

We've implemented **session persistence** that saves login sessions and reuses them across runs, effectively avoiding captcha challenges.

## How It Works

### 1. Session Data Storage

The system saves three types of session data:

- **Cookies**: Authentication tokens and session identifiers
- **localStorage**: User preferences and settings
- **sessionStorage**: Temporary session data

Session data is stored in `.tradingview-session/` directory:
```
.tradingview-session/
├── cookies.json         # Authentication cookies
└── session-storage.json # Browser storage data
```

### 2. Stealth Features

To reduce bot detection, the browser is configured with:

- Custom user agent strings
- Disabled automation indicators
- Realistic browser headers
- Plugin and language mocking

### 3. Smart Login Process

The `smartLogin()` method follows this priority:

1. **Check existing session**: If already logged in, continue
2. **Test saved session**: Load and validate saved session data
3. **Manual intervention**: If needed, prompt for manual login
4. **Save new session**: Store successful login for future use

## Usage

### First Time Setup

```javascript
import { TradingViewAutomation } from './lib/tradingview-automation.js'

const automation = new TradingViewAutomation()
await automation.init()

// First run - manual login required
const success = await automation.smartLogin()
// This will open TradingView and wait for manual login
// Once you log in manually, the session is saved
```

### Subsequent Runs

```javascript
// Future runs automatically use saved session
const automation = new TradingViewAutomation()
await automation.init()

const success = await automation.smartLogin()
// This will use saved session - no captcha!
```

### Testing Session Persistence

```bash
# Run the test script
node test-session-avoid-captcha.js
```

## API Integration

The analysis API automatically uses session persistence:

```bash
curl -X POST http://localhost:3000/api/analyze \\
  -H "Content-Type: application/json" \\
  -d '{
    "symbol": "SOLUSD",
    "timeframe": "5"
  }'
```

The API will:
1. Check for saved session
2. Use it if valid (no captcha)
3. Return analysis results

## Session Management

### Check Session Status

```javascript
const info = await automation.getSessionInfo()
console.log(info)
// {
//   isAuthenticated: true,
//   hasSavedCookies: true,
//   hasSavedStorage: true,
//   cookiesCount: 15,
//   currentUrl: "https://www.tradingview.com"
// }
```

### Refresh Session

```javascript
// Keep session alive
const refreshed = await automation.refreshSession()
```

### Clear Session

```javascript
// Clear expired or invalid session
await automation.clearSession()
```

### Test Session Validity

```javascript
const test = await automation.testSessionPersistence()
// {
//   hasSessionData: true,
//   isValid: true,
//   sessionInfo: {...}
// }
```

## Manual Setup Process

1. **Run the bot for the first time**
2. **Browser opens automatically** (in Docker, this happens in headless mode)
3. **Manual login required**: Log in through the browser interface
4. **Session saved**: Once logged in, session data is automatically saved
5. **Future runs**: No more captcha challenges!

## Docker Integration

In Docker environment:

```bash
# Start the container
docker-compose up -d

# Run session setup (manual login required once)
docker exec -it trading_bot_v3 node test-session-avoid-captcha.js

# After setup, API calls work without captcha
curl -X POST http://localhost:3000/api/analyze \\
  -H "Content-Type: application/json" \\
  -d '{"symbol": "SOLUSD", "timeframe": "5"}'
```

## Session Persistence Benefits

✅ **No more captcha challenges** after initial setup  
✅ **Faster login process** (reuses existing session)  
✅ **Automatic session refresh** to keep sessions alive  
✅ **Docker compatible** session storage  
✅ **Fallback to manual login** when needed  

## Troubleshooting

### Session Expired

If you get login failures:

```javascript
// Clear expired session and start fresh
await automation.clearSession()
await automation.smartLogin() // Will prompt for manual login
```

### No Manual Browser Available

For servers without display:

1. Run initial setup on local machine
2. Copy `.tradingview-session/` to server
3. Server uses saved session data

### Session Not Working

Check session status:

```javascript
const info = await automation.getSessionInfo()
if (!info.isAuthenticated || !info.hasSavedCookies) {
  // Need fresh login
  await automation.clearSession()
  await automation.smartLogin()
}
```

## Files Modified

- `lib/tradingview-automation.ts`: Core session persistence logic
- `lib/enhanced-screenshot.ts`: Updated to use smart login
- `test-session-avoid-captcha.js`: Test script for session setup
- `.tradingview-session/`: Session data storage directory (auto-created)

## Security

- Session data is stored locally only
- No credentials are permanently stored
- Session files can be manually deleted if needed
- Works with environment variables for credentials