Realtime

Nuvem Realtime provee WebSockets sobre Durable Objects. Soporta canales pub/sub, presencia en línea y suscripciones a cambios en la base de datos.

Conectar

import { createClient } from '@nuvem/js';

const nuvem = createClient({ apiKey: 'nv_live_...' });
const rt = nuvem.realtime.connect();

Canales

// Suscribirse a un canal
const channel = rt.channel('chat:sala-principal');

channel.on('message', (event) => {
  console.log(event.payload);
});

await channel.subscribe();

// Publicar mensaje
await channel.publish('message', {
  text: 'Hola a todos!',
  userId: 'usr_abc',
});

// Desuscribirse
await channel.unsubscribe();

API REST para canales

# Listar canales activos
GET /v1/realtime/channels
Authorization: Bearer <api_key>

# Crear canal con config
POST /v1/realtime/channels
{
  "name": "notifications:usuarios",
  "maxConnections": 1000,
  "rateLimit": { "messages": 100, "windowSeconds": 60 }
}

# Publicar desde el servidor
POST /v1/realtime/channels/:channelId/publish
{ "event": "new_order", "payload": { "orderId": "rec_abc" } }

Presencia

// Anunciar presencia
await channel.track({
  userId: 'usr_abc',
  username: 'pedro',
  status: 'online',
});

// Escuchar cambios de presencia
channel.on('presence', (event) => {
  if (event.type === 'join') console.log(`${event.user.username} se unió`);
  if (event.type === 'leave') console.log(`${event.user.username} se fue`);
});

// Obtener lista actual
const users = await channel.getPresence();

Suscripciones a DB

// Escuchar cambios en una tabla
const sub = rt.subscribe('orders', {
  event: 'INSERT',
  filter: { status: 'pending' },
});

sub.on('change', (record) => {
  console.log('Nuevo pedido:', record);
});

API REST

# Crear suscripción
POST /v1/realtime/subscriptions
{
  "table": "orders",
  "events": ["INSERT", "UPDATE"],
  "channel": "orders:live"
}

# Listar suscripciones
GET /v1/realtime/subscriptions

Historial de mensajes

GET /v1/realtime/channels/:channelId/history?limit=50

Límites

Plan	Conexiones simultáneas	Mensajes/mes
Free	100	500,000
Builder	5,000	50,000,000
Scale	100,000	Ilimitado

Errores comunes

Código	Mensaje	Causa
channel_not_found	Canal inexistente	ID inválido
connection_limit_exceeded	Límite de conexiones alcanzado	Upgrade de plan
rate_limit_exceeded	Rate limit del canal	Reducir frecuencia de mensajes