navflow-browser-server/README.md

Standalone Playwright browser server for NavFlow - enables browser automation with API key authentication, workspace device management, session sync, LLM discovery tools, and requires Node.js v22+

# NavFlow Browser Server

A standalone Playwright browser server that enables remote browser automation through secure API key authentication. Perfect for running browser automation workflows from cloud-based frontends.

## Quick Start

```bash
npx navflow-browser-server
```

The server will start and display an API key that you can use in the NavFlow frontend at [https://buildship-pfw15o.web.app](https://buildship-pfw15o.web.app).

## Features

✅ **Playwright Integration** - Full support for Chromium, Firefox, and WebKit browsers  
✅ **API Key Authentication** - Secure device-based authentication with generated API keys  
✅ **Auto-Installation** - Automatically detects and installs Playwright browsers on first run  
✅ **Node.js v22+ Support** - Built for modern Node.js with version validation  
✅ **Session Management** - Persistent browser sessions with cookie/storage support  
✅ **Flow Execution** - Execute complex automation workflows  
✅ **LLM Discovery Tools** - AI-powered flow creation with real-time validation  
✅ **Real-time Communication** - WebSocket support for live updates  
✅ **Easy Installation** - No setup required, works with npx  

## Usage

### Basic Usage

```bash
# Start server on default port (3002)
npx navflow-browser-server

# Start server on custom port
npx navflow-browser-server --port=3003

# Show help
npx navflow-browser-server --help

# Show version
npx navflow-browser-server --version
```

### Using with NavFlow Frontend

1. **Start the server:**
   ```bash
   npx navflow-browser-server
   ```

2. **Copy the API key** from the console output:
   ```
   📋 API KEY (Copy this to your NavFlow webapp):
   ────────────────────────────────────────────────────────
   abc123def456789...your-api-key-here
   ────────────────────────────────────────────────────────
   ```

3. **Configure the frontend:**
   - Go to [https://buildship-pfw15o.web.app](https://buildship-pfw15o.web.app)
   - Complete the onboarding flow
   - Paste your API key when prompted
   - The device will connect automatically

4. **Start automating!** Create and run browser automation flows from the cloud interface.

## System Requirements

### Automatic Validation
The server automatically checks and validates:

- ✅ **Node.js v22+** - Required for optimal performance and security
- ✅ **Playwright Browsers** - Auto-installs if not detected
- ✅ **System Compatibility** - Validates environment before starting

### Manual Requirements
- Internet connection for Playwright browser downloads
- ~1GB disk space for Playwright browsers
- Modern operating system (Windows 10+, macOS 10.14+, Linux)

## API Endpoints

The server exposes several REST endpoints for browser automation (all require API key authentication):

### Health Check
```
GET /health
```
Returns server status and device information.

### Device Information
```
GET /device
```
Returns device details including MAC address and configuration.

### Session Management
```
POST /sessions                    # Create browser session
GET /sessions/:id                 # Get session info  
DELETE /sessions/:id              # Close session
POST /sessions/:id/actions        # Execute browser action
```

### Flow Execution
```
POST /execute-flow               # Execute automation flow
```

### Authentication Sessions
```
GET /api/sessions                # List saved sessions
POST /api/sessions               # Create new session
DELETE /api/sessions/:name       # Delete session
```

### Discovery Tools (LLM Self-Discovery System)

The browser server includes specialized endpoints for AI-powered flow creation. These tools allow Large Language Models to interact with real browsers to validate and test automation steps in real-time:

```
POST /discovery/checkSelector     # Validate CSS selectors exist on page
POST /discovery/getHTML          # Extract HTML content from elements  
POST /discovery/screenshot       # Capture page screenshots for AI analysis
POST /discovery/executeStep      # Test automation steps (click, type, navigate)
POST /discovery/getCurrentURL    # Get current page URL and status
```

**Example: Checking if a selector exists**
```javascript
// Request
{
  "sessionId": "my-session",
  "selector": "button[aria-label='Submit']"
}

// Response
{
  "exists": true,
  "count": 1,
  "visible": true
}
```

**Example: Testing an automation step**
```javascript
// Request
{
  "sessionId": "my-session", 
  "action": "click",
  "selector": "button.submit-btn"
}

// Response
{
  "success": true,
  "error": "",
  "newUrl": "https://example.com/success"
}
```

These tools enable the LLM to:
- Test multiple selector candidates to find reliable ones
- Verify that automation steps actually work before including them in flows
- Understand page context through screenshots and HTML inspection
- Build flows incrementally with real-time validation

All discovery endpoints require API key authentication and operate within isolated browser sessions.

## Authentication

All API endpoints (except `/health` and `/device`) require API key authentication:

```bash
# Include in Authorization header
Authorization: Bearer your-api-key-here

# Or as query parameter
GET /sessions?apiKey=your-api-key-here
```

## Environment Variables

- `BROWSER_SERVER_PORT` - Port to run server on (default: 3002)

## Data Storage

The server creates data directories to store:
- **Device Configuration**: `device-config.json` (API key, MAC address)
- **Session Data**: `data/sessions/` (authentication profiles, cookies)
- **Temporary Files**: Various runtime data

## Troubleshooting

### Node.js Version Issues
If you see a Node.js version error:
1. Visit [https://nodejs.org/](https://nodejs.org/)
2. Download Node.js v22 or higher
3. Install and restart your terminal
4. Run the command again

### Port Already in Use
```bash
npx navflow-browser-server --port=3003
```

### Playwright Installation Issues
The server auto-installs Playwright browsers, but if you encounter issues:
```bash
npx playwright install
```

### API Key Issues
- API keys are unique per device (MAC address)
- Keys are automatically generated on first run
- If you need a new key, delete `device-config.json` and restart

## Security

- ✅ **Device-Based Authentication** - Unique API keys per machine
- ✅ **Local Data Storage** - All browser data stays on your device
- ✅ **Secure Communication** - API key authentication for all requests
- ✅ **No Cloud Dependencies** - Direct connection, no proxy servers

## Startup Output

When everything is working correctly, you'll see:

```
🌊 NavFlow Browser Server starting on port 3002...
📍 Health check: http://localhost:3002/health
🔌 WebSocket: ws://localhost:3002

🔍 Checking Playwright browser installation...
✅ Playwright browsers are installed and ready

🖥️  SYSTEM STATUS
──────────────────────────────────────────────────
Node.js: v22.14.0 ✅
Playwright: 1.54.1
Browsers: ✅ Installed

🔧 Initializing device registry...

================================================================================
🔐 NAVFLOW DEVICE REGISTRATION
================================================================================
Device Name: Your-Computer-abc123
MAC Address: 12:34:56:78:90:ab
Port: 3002
Created: 31/07/2025, 10:30:15 am

📋 API KEY (Copy this to your NavFlow webapp):
────────────────────────────────────────────────────────────────────────────────
your-unique-api-key-will-appear-here
────────────────────────────────────────────────────────────────────────────────

📝 To add this device to your workspace:
   1. Open your NavFlow webapp
   2. Go to Workspace Settings → Devices
   3. Click "Add Device" and paste the API key above

✅ Device is ready to receive connections!
================================================================================

🚀 NavFlow Browser Server is ready for API key connections!
```

## Support

- **Issues**: [GitHub Issues](https://github.com/buildship/navflow/issues)
- **Frontend**: [https://buildship-pfw15o.web.app](https://buildship-pfw15o.web.app)
- **Documentation**: [GitHub Repository](https://github.com/buildship/navflow)

## License

MIT License - see LICENSE file for details.

---

**Made with ❤️ by the NavFlow team**