framework/examples/website/CONSOLE_API.md

# WebSocket Manager Console API Documentation

The WebSocket Manager provides a browser console interface for interactive testing and debugging of WebSocket connections. When the application loads, the manager is automatically exposed to the global `window` object.

## Quick Start

Open your browser's developer console and you'll see initialization messages:
```
🚀 WebSocket Manager exposed to console!
📖 Use 'wsHelp' to see available commands
🔧 Access manager via 'wsManager'
```

## Global Objects

### `wsManager`
The main WebSocket manager instance with all functionality.

### `wsHelp`
Quick reference object containing usage examples for all commands.

## API Reference

### Connection Status

#### `wsManager.getServerUrls()`
Returns an array of all configured server URLs.

**Returns:** `Array<string>`

**Example:**
```javascript
wsManager.getServerUrls()
// Returns: ["ws://localhost:8080", "ws://localhost:8081", "ws://localhost:8443/ws"]
```

#### `wsManager.getConnectionStatuses()`
Returns an object mapping each server URL to its current connection status.

**Returns:** `Object<string, string>`

**Possible Status Values:**
- `"Connected"` - WebSocket is connected and ready
- `"Disconnected"` - WebSocket is not connected

**Example:**
```javascript
wsManager.getConnectionStatuses()
// Returns: {
//   "ws://localhost:8080": "Disconnected",
//   "ws://localhost:8081": "Disconnected", 
//   "ws://localhost:8443/ws": "Connected"
// }
```

#### `wsManager.isConnected(url)`
Check if a specific server is connected.

**Parameters:**
- `url` (string) - The WebSocket server URL to check

**Returns:** `boolean`

**Example:**
```javascript
wsManager.isConnected('ws://localhost:8443/ws')
// Returns: true or false
```

#### `wsManager.getConnectionCount()`
Get the total number of configured servers (not necessarily connected).

**Returns:** `number`

**Example:**
```javascript
wsManager.getConnectionCount()
// Returns: 3
```

### Script Execution

#### `wsManager.executeScript(url, script)`
Execute a Rhai script on a specific connected server.

**Parameters:**
- `url` (string) - The WebSocket server URL
- `script` (string) - The Rhai script to execute

**Returns:** `Promise<string>` - Resolves with script output or rejects with error

**Example:**
```javascript
// Simple calculation
await wsManager.executeScript('ws://localhost:8443/ws', 'let x = 42; `Result: ${x}`')

// Get current timestamp
await wsManager.executeScript('ws://localhost:8443/ws', '`Current time: ${new Date().toISOString()}`')

// JSON response
await wsManager.executeScript('ws://localhost:8443/ws', `
let data = #{
    message: "Hello from WebSocket!",
    value: 42,
    timestamp: new Date().toISOString()
};
to_json(data)
`)
```

#### `wsManager.executeScriptOnAll(script)`
Execute a Rhai script on all connected servers simultaneously.

**Parameters:**
- `script` (string) - The Rhai script to execute

**Returns:** `Promise<Object>` - Object mapping URLs to their results

**Example:**
```javascript
// Get server info from all connected servers
const results = await wsManager.executeScriptOnAll('`Server response from: ${new Date().toISOString()}`')
console.log(results)
// Returns: {
//   "ws://localhost:8443/ws": "Server response from: 2025-01-16T14:30:00.000Z",
//   "ws://localhost:8080": "Error: Connection failed",
//   "ws://localhost:8081": "Error: Connection failed"
// }
```

### Connection Management

#### `wsManager.reconnect()`
Attempt to reconnect to all configured servers.

**Returns:** `Promise<string>` - Success or error message

**Example:**
```javascript
await wsManager.reconnect()
// Console output: "Reconnected to servers"
```

## Rhai Script Examples

The WebSocket servers execute [Rhai](https://rhai.rs/) scripts. Here are some useful examples:

### Basic Operations
```javascript
// Simple calculation
await wsManager.executeScript(url, 'let result = 2 + 2; `2 + 2 = ${result}`')

// String manipulation
await wsManager.executeScript(url, 'let msg = "Hello"; `${msg.to_upper()} WORLD!`')

// Current timestamp
await wsManager.executeScript(url, '`Current time: ${new Date().toISOString()}`')
```

### JSON Data
```javascript
// Create and return JSON
await wsManager.executeScript(url, `
let data = #{
    id: 123,
    name: "Test User",
    active: true,
    created: new Date().toISOString()
};
to_json(data)
`)
```

### Conditional Logic
```javascript
// Conditional responses
await wsManager.executeScript(url, `
let hour = new Date().getHours();
if hour < 12 {
    "Good morning!"
} else if hour < 18 {
    "Good afternoon!"
} else {
    "Good evening!"
}
`)
```

### Loops and Arrays
```javascript
// Generate data with loops
await wsManager.executeScript(url, `
let numbers = [];
for i in 1..6 {
    numbers.push(i * i);
}
\`Squares: \${numbers}\`
`)
```

## Error Handling

All async operations return Promises that can be caught:

```javascript
try {
    const result = await wsManager.executeScript('ws://localhost:8080', 'let x = 42; x');
    console.log('Success:', result);
} catch (error) {
    console.error('Script failed:', error);
}
```

Common error scenarios:
- **Connection Error**: Server is not connected
- **Script Error**: Invalid Rhai syntax or runtime error
- **Timeout**: Script execution took too long
- **Network Error**: WebSocket connection lost

## Console Logging

The manager automatically logs important events to the console:

- ✅ **Success messages**: Script execution completed
- ❌ **Error messages**: Connection failures, script errors
- 🔄 **Status updates**: Reconnection attempts
- 📡 **Network events**: WebSocket state changes

## Development Tips

1. **Check Connection Status First**:
   ```javascript
   wsManager.getConnectionStatuses()
   ```

2. **Test Simple Scripts First**:
   ```javascript
   await wsManager.executeScript(url, '"Hello World"')
   ```

3. **Use Template Literals for Complex Scripts**:
   ```javascript
   const script = `
   let data = #{
       timestamp: new Date().toISOString(),
       random: Math.random()
   };
   to_json(data)
   `;
   await wsManager.executeScript(url, script)
   ```

4. **Monitor Console for Detailed Logs**:
   The manager provides detailed logging for debugging connection and execution issues.

## Integration with UI

The console API shares the same WebSocket manager instance as the web UI, so:
- Connection status changes are reflected in both
- Scripts executed via console appear in the UI responses
- Authentication state is shared between console and UI

This makes the console API perfect for:
- **Development**: Quick script testing
- **Debugging**: Connection troubleshooting  
- **Automation**: Batch operations
- **Learning**: Exploring Rhai script capabilities