Tomo Retro SDK

Cliente TypeScript sin dependencias para crear y operar sesiones de Tomo Retro y streams genéricos desde otra plataforma.

Instalación

Durante el developer preview, instálalo directamente desde GitHub:

npm install github:Tomo-Social/tomo-retro-sdk

Para cámara, escritorio y plugins genéricos recomendamos @tomo-social/streaming-sdk. Este paquete conserva el cliente retro por compatibilidad.

Configuración del servidor

Define una clave de al menos 24 caracteres en tomo-signaling:

TOMO_RETRO_API_KEY="replace-with-a-random-secret"

Para múltiples integraciones usa un objeto JSON. Cada cliente sólo puede listar, consultar, operar o cerrar sus propias sesiones:

TOMO_RETRO_API_KEYS='{"discord":"secret-with-at-least-24-chars","mobile":"another-secret-with-24-chars"}'

Las claves son credenciales de servidor. No deben incluirse en JavaScript entregado al navegador. La plataforma debe llamar a la API desde su backend y entregar al cliente únicamente session.connection.

Uso

import { TomoRetroClient } from "@tomo-social/retro-sdk";

const retro = new TomoRetroClient({
  baseUrl: "https://retro.example.com",
  apiKey: process.env.TOMO_RETRO_API_KEY!,
});

const session = await retro.createSession({
  rom: "super-mario.nes",
  bandwidth: "medium",
  name: "Friday retro night",
  idempotencyKey: crypto.randomUUID(),
});

const socket = new WebSocket(retro.signalingUrl(session));
socket.addEventListener("open", () => {
  socket.send(JSON.stringify(retro.joinMessage(session, "player-one")));
});

Para cámara y escritorio usa TomoStreamClient:

import { TomoStreamClient, TomoStreamInput } from "@tomo-social/retro-sdk";

const streams = new TomoStreamClient({
  baseUrl: "https://tomo.example.com",
  apiKey: process.env.TOMO_RETRO_API_KEY!,
});

const camera = await streams.createSession({
  type: "camera-stream-server",
  videoDevice: "/dev/video0",
  width: 1280,
  height: 720,
  captureAudio: true,
});

// El resultado es ArrayBuffer y funciona directamente con RTCDataChannel.send.
inputChannel.send(TomoStreamInput.keyboard(0x04, true));

La API genérica vive en /api/v1/streams y ofrece list/create/get/delete más acciones pause, resume y restart. La sesión devuelve únicamente el token de jugador; el token del host se entrega sólo al contenedor.

API REST v1

Base: /api/v1/retro

El contrato para generación de clientes y herramientas está en openapi.yaml.

| Método | Ruta | Descripción | | --- | --- | --- | | GET | /capabilities | Sistemas, acciones, capacidad y estado de la API. No requiere clave. | | GET | /sessions | Lista las sesiones del cliente. | | POST | /sessions | Crea una sesión privada y temporal. | | GET | /sessions/:id | Consulta estado, conectados y metadata. | | POST | /sessions/:id/actions | Ejecuta pause, resume o restart. | | DELETE | /sessions/:id | Cierra y elimina el runtime. |

Las rutas protegidas requieren x-api-key. POST /sessions acepta idempotency-key; los resultados se conservan 24 horas en la instancia actual.

La ROM debe existir previamente en el catálogo montado en ROMS_DIR/ROMS_HOST_DIR. La API no acepta rutas arbitrarias ni realiza uploads.

Escalabilidad

La API separa cliente, contrato HTTP y orquestación Docker. Para crecer horizontalmente todavía se debe mover el registro de sesiones e idempotencia de memoria a Redis o PostgreSQL y sustituir el runtime Docker local por un scheduler compartido (Kubernetes, Nomad o un servicio equivalente). El contrato del SDK no necesita cambiar para realizar esa migración.