Eve library

WebSocket API

Guide

Revision 1

On this page

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:

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

Or pass userId for anonymous connections (limited functionality):

text
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