# WebSocket API

Real-time event streaming for generation progress, collaboration, and pipeline
monitoring.

## Overview

The WebSocket API provides bidirectional real-time communication for receiving
instant updates on long-running operations, collaborative editing, and system
events.

**WebSocket URL:** `wss://api.yemaya.io/ws` **Development URL:**
`ws://localhost:3000/ws`

## Connection

### Establishing Connection

Connect to the WebSocket server with authentication:

```javascript
const ws = new WebSocket('wss://api.yemaya.io/ws?token=YOUR_JWT_TOKEN');

ws.onopen = () => {
  console.log('Connected to Yemaya WebSocket');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  handleMessage(message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = (event) => {
  console.log('WebSocket closed:', event.code, event.reason);
};
```

### Authentication

Include your JWT token as a query parameter:

```
wss://api.yemaya.io/ws?token=eyJhbGciOiJIUzI1NiIs...
```

Or pass userId for anonymous connections (limited functionality):

```
wss://api.yemaya.io/ws?userId=user_abc123
```

## REST Endpoints

### Get Connection Info

```http
GET /ws/info
```

**Response:**

```json
{
  "success": true,
  "data": {
    "url": "wss://api.yemaya.io/ws",
    "protocols": ["json"],
    "version": "1.0.0",
    "authentication": {
      "method": "query_param",
      "param": "token",
      "type": "jwt"
    },
    "channels": [
      {
        "name": "job",
        "description": "Subscribe to job-specific events",
        "events": [
          "generation:progress",
          "generation:complete",
          "generation:failed"
        ]
      },
      {
        "name": "project",
        "description": "Subscribe to project-wide events",
        "events": ["phase:*", "quality:*", "pipeline:*"]
      }
    ]
  }
}
```

### Get Server Statistics

```http
GET /ws/stats
Authorization: Bearer <token>
```

**Response:**

```json
{
  "success": true,
  "data": {
    "totalConnections": 150,
    "authenticatedConnections": 120,
    "totalSubscriptions": 420,
    "channelStats": {
      "job": 45,
      "project": 30,
      "collaboration": 75,
      "pipeline": 20
    }
  }
}
```

### Get Presence

Get users present on a specific resource.

```http
GET /ws/presence/{channel}/{resourceId}
Authorization: Bearer <token>
```

**Response:**

```json
{
  "success": true,
  "data": {
    "channel": "collaboration",
    "resourceId": "doc_abc123",
    "users": [
      {
        "connectionId": "conn_123",
        "userId": "usr_abc",
        "metadata": { "userAgent": "Chrome/120" }
      }
    ],
    "count": 1
  }
}
```

---

## Message Protocol

### Message Format

All messages follow this structure:

```json
{
  "type": "message_type",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "requestId": "optional_correlation_id",
  ...additional fields
}
```

### Client Messages

#### Subscribe

Subscribe to events for a resource.

```json
{
  "type": "subscribe",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "channel": "job",
  "resourceId": "job_3d_abc123",
  "events": ["generation:progress", "generation:complete", "generation:failed"]
}
```

**Channels:**

| Channel         | Description                 | Resource ID          |
| --------------- | --------------------------- | -------------------- |
| `job`           | Generation/training jobs    | Job ID               |
| `project`       | Project-wide events         | Project ID           |
| `asset`         | Asset lock/edit events      | Asset ID             |
| `collaboration` | Real-time collaboration     | Document/Resource ID |
| `pipeline`      | Pipeline execution events   | Pipeline ID          |
| `agent`         | Agent activity events       | Agent/Task ID        |
| `user`          | User-specific notifications | User ID              |

#### Unsubscribe

```json
{
  "type": "unsubscribe",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "channel": "job",
  "resourceId": "job_3d_abc123"
}
```

#### Ping

Keep connection alive (recommended every 30 seconds):

```json
{
  "type": "connection:ping",
  "timestamp": "2024-01-15T10:00:00.000Z"
}
```

### Server Messages

#### Connection Opened

```json
{
  "type": "connection:open",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "connectionId": "conn_abc123"
}
```

#### Subscription Confirmed

```json
{
  "type": "subscription:confirm",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "channel": "job",
  "resourceId": "job_3d_abc123",
  "subscriptionId": "sub_xyz789"
}
```

#### Pong

```json
{
  "type": "connection:pong",
  "timestamp": "2024-01-15T10:00:00.000Z"
}
```

---

## Event Types

### Generation Events

#### generation:progress

```json
{
  "type": "generation:progress",
  "timestamp": "2024-01-15T10:00:30.000Z",
  "jobId": "job_3d_abc123",
  "jobType": "text_to_3d",
  "progress": 45,
  "stage": "generating_mesh",
  "message": "Creating base geometry...",
  "estimatedSecondsRemaining": 65,
  "metadata": {
    "polyCount": 12000,
    "currentOperation": "subdivision"
  }
}
```

#### generation:complete

```json
{
  "type": "generation:complete",
  "timestamp": "2024-01-15T10:01:35.000Z",
  "jobId": "job_3d_abc123",
  "jobType": "text_to_3d",
  "resultUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/model.glb",
  "previewUrl": "https://cdn.yemaya.io/3d/job_3d_abc123/thumb.png",
  "processingTime": 95000,
  "metadata": {
    "polyCount": 45000,
    "textureCount": 3
  }
}
```

#### generation:failed

```json
{
  "type": "generation:failed",
  "timestamp": "2024-01-15T10:01:00.000Z",
  "jobId": "job_3d_abc123",
  "jobType": "text_to_3d",
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Model generation failed due to invalid prompt",
    "details": { "reason": "safety_filter" }
  },
  "retryable": true
}
```

### Queue Events

#### queue:position

```json
{
  "type": "queue:position",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_3d_abc123",
  "position": 3,
  "totalInQueue": 15,
  "estimatedWaitSeconds": 180
}
```

#### queue:eta

```json
{
  "type": "queue:eta",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_3d_abc123",
  "estimatedStartTime": "2024-01-15T10:03:00.000Z",
  "estimatedCompletionTime": "2024-01-15T10:05:30.000Z",
  "confidence": 0.85
}
```

### Training Events

#### training:progress

```json
{
  "type": "training:progress",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_train_abc123",
  "trainingType": "gaussian_splatting",
  "currentIteration": 5000,
  "totalIterations": 30000,
  "progress": 16.7,
  "elapsedSeconds": 1200,
  "estimatedSecondsRemaining": 6000
}
```

#### training:metrics

```json
{
  "type": "training:metrics",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_train_abc123",
  "iteration": 5000,
  "metrics": {
    "loss": 0.0234,
    "psnr": 28.5,
    "ssim": 0.92,
    "lpips": 0.08,
    "learningRate": 0.0001,
    "numGaussians": 250000
  }
}
```

#### training:checkpoint

```json
{
  "type": "training:checkpoint",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_train_abc123",
  "checkpointId": "ckpt_5000",
  "iteration": 5000,
  "loss": 0.0234,
  "checkpointUrl": "https://cdn.yemaya.io/checkpoints/ckpt_5000.ply"
}
```

### Render Events

#### render:progress

```json
{
  "type": "render:progress",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_render_abc123",
  "renderType": "video",
  "currentFrame": 120,
  "totalFrames": 300,
  "progress": 40,
  "fps": 2.5,
  "estimatedSecondsRemaining": 72
}
```

#### render:frame

```json
{
  "type": "render:frame",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "jobId": "job_render_abc123",
  "frameNumber": 120,
  "frameUrl": "https://cdn.yemaya.io/frames/frame_0120.png",
  "renderTimeMs": 400
}
```

### Collaboration Events

#### lock:acquired

```json
{
  "type": "lock:acquired",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceType": "asset",
  "resourceId": "ast_abc123",
  "userId": "usr_def456",
  "userName": "John Doe",
  "lockType": "exclusive",
  "expiresAt": "2024-01-15T10:30:00.000Z"
}
```

#### lock:released

```json
{
  "type": "lock:released",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceType": "asset",
  "resourceId": "ast_abc123",
  "userId": "usr_def456"
}
```

#### edit:update

Real-time edit operation (for collaborative editing):

```json
{
  "type": "edit:update",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceType": "script",
  "resourceId": "scr_abc123",
  "userId": "usr_def456",
  "userName": "John Doe",
  "operation": {
    "type": "insert",
    "path": "scenes[0].dialogue[5].text",
    "value": "Hello, world!",
    "range": { "start": 45, "end": 45 }
  },
  "version": 127
}
```

#### presence:join

```json
{
  "type": "presence:join",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceId": "doc_abc123",
  "user": {
    "id": "usr_def456",
    "name": "John Doe",
    "avatarUrl": "https://...",
    "color": "#FF5733"
  }
}
```

#### presence:leave

```json
{
  "type": "presence:leave",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceId": "doc_abc123",
  "userId": "usr_def456"
}
```

#### cursor:move

```json
{
  "type": "cursor:move",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "resourceId": "doc_abc123",
  "userId": "usr_def456",
  "userName": "John Doe",
  "color": "#FF5733",
  "position": {
    "line": 42,
    "column": 15
  }
}
```

### Pipeline Events

#### phase:started

```json
{
  "type": "phase:started",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "phaseId": "phase_concept",
  "phaseName": "Concept Development",
  "phaseType": "pre_production",
  "totalTasks": 15
}
```

#### phase:progress

```json
{
  "type": "phase:progress",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "phaseId": "phase_concept",
  "phaseName": "Concept Development",
  "progress": 60,
  "completedTasks": 9,
  "totalTasks": 15,
  "currentTask": "Generate character concepts"
}
```

#### quality:passed

```json
{
  "type": "quality:passed",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "phaseId": "phase_concept",
  "gateId": "gate_visual_quality",
  "gateName": "Visual Quality Check",
  "score": 0.92,
  "threshold": 0.85,
  "checksPassed": 12,
  "checksTotal": 12
}
```

#### quality:failed

```json
{
  "type": "quality:failed",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "phaseId": "phase_concept",
  "gateId": "gate_visual_quality",
  "gateName": "Visual Quality Check",
  "score": 0.72,
  "threshold": 0.85,
  "issues": [
    {
      "severity": "error",
      "description": "Character proportions inconsistent",
      "location": "character_hero.png",
      "suggestion": "Regenerate with stricter proportion constraints"
    }
  ],
  "canOverride": true
}
```

### Agent Events

#### agent:started

```json
{
  "type": "agent:started",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "taskId": "task_abc123",
  "agentType": "script_writer",
  "agentName": "Script Writer Agent",
  "taskName": "Write opening scene dialogue"
}
```

#### agent:progress

```json
{
  "type": "agent:progress",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "taskId": "task_abc123",
  "agentType": "script_writer",
  "progress": 45,
  "activity": "Drafting dialogue for scene 1",
  "tokensUsed": 1250
}
```

#### agent:output

```json
{
  "type": "agent:output",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "projectId": "proj_abc123",
  "taskId": "task_abc123",
  "agentType": "script_writer",
  "outputType": "text",
  "preview": "INT. CASTLE THRONE ROOM - NIGHT\n\nThe King sits alone...",
  "fullOutputUrl": "https://cdn.yemaya.io/outputs/script_draft.txt"
}
```

---

## JavaScript SDK Example

```javascript
class YemayaWebSocket {
  constructor(token) {
    this.token = token;
    this.ws = null;
    this.subscriptions = new Map();
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;
  }

  connect() {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(`wss://api.yemaya.io/ws?token=${this.token}`);

      this.ws.onopen = () => {
        console.log('Connected');
        this.reconnectAttempts = 0;
        this.startPingInterval();
        resolve();
      };

      this.ws.onmessage = (event) => {
        const message = JSON.parse(event.data);
        this.handleMessage(message);
      };

      this.ws.onclose = (event) => {
        this.handleClose(event);
      };

      this.ws.onerror = reject;
    });
  }

  subscribe(channel, resourceId, events, callback) {
    const key = `${channel}:${resourceId}`;
    this.subscriptions.set(key, callback);

    this.send({
      type: 'subscribe',
      timestamp: new Date().toISOString(),
      channel,
      resourceId,
      events,
    });
  }

  unsubscribe(channel, resourceId) {
    const key = `${channel}:${resourceId}`;
    this.subscriptions.delete(key);

    this.send({
      type: 'unsubscribe',
      timestamp: new Date().toISOString(),
      channel,
      resourceId,
    });
  }

  handleMessage(message) {
    if (message.type === 'connection:pong') return;

    // Route to appropriate subscription handler
    for (const [key, callback] of this.subscriptions) {
      if (message.jobId || message.resourceId || message.projectId) {
        callback(message);
      }
    }
  }

  send(data) {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(data));
    }
  }

  startPingInterval() {
    this.pingInterval = setInterval(() => {
      this.send({
        type: 'connection:ping',
        timestamp: new Date().toISOString(),
      });
    }, 30000);
  }

  handleClose(event) {
    clearInterval(this.pingInterval);

    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
    }
  }

  disconnect() {
    clearInterval(this.pingInterval);
    this.ws?.close();
  }
}

// Usage
const ws = new YemayaWebSocket('your_jwt_token');
await ws.connect();

// Subscribe to generation progress
ws.subscribe(
  'job',
  'job_3d_abc123',
  ['generation:progress', 'generation:complete'],
  (event) => {
    console.log(`Progress: ${event.progress}%`);
  }
);
```

---

## Error Handling

### Connection Errors

| Code   | Description           |
| ------ | --------------------- |
| `4001` | Authentication failed |
| `4002` | Token expired         |
| `4003` | Invalid subscription  |
| `4004` | Rate limited          |
| `4005` | Resource not found    |

### Error Message

```json
{
  "type": "connection:error",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "error": "Invalid authentication token",
  "code": 4001
}
```

---

## Best Practices

1. **Reconnection**: Implement exponential backoff for reconnections
2. **Ping/Pong**: Send ping every 30 seconds to keep connection alive
3. **Subscription Management**: Track subscriptions and resubscribe after
   reconnection
4. **Error Handling**: Handle all error types gracefully
5. **Resource Cleanup**: Unsubscribe when no longer needed to reduce server load
