Sync real-time shared state end to end

export ORBIT_API_KEY="dv_live_sk_your_key_here"
BASE="https://api.orbit.devotel.io/api/v1/sync"

curl -X POST "$BASE/documents" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_name": "room_42_config",
    "data": { "theme": "dark", "max_participants": 25 },
    "ttl": 0
  }'

curl "$BASE/documents/room_42_config" -H "X-API-Key: $ORBIT_API_KEY"

# 1. Read and note the revision (e.g. 3).
REV=$(curl -s "$BASE/documents/room_42_config" -H "X-API-Key: $ORBIT_API_KEY" | jq -r .data.revision)

# 2. Write.
curl -X POST "$BASE/documents/room_42_config" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "theme": "light" }, "ttl": 0 }'

# 3. Re-read; if revision > $REV, converge on the newer state.

curl -X DELETE "$BASE/documents/room_42_config" -H "X-API-Key: $ORBIT_API_KEY"

curl -X PUT "$BASE/maps/room_42_presence/items/user_123" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "status": "online" }, "ttl": 0 }'

curl "$BASE/maps/room_42_presence/items" -H "X-API-Key: $ORBIT_API_KEY"

curl -X POST "$BASE/lists/room_42_audit/items" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "actor": "user_123", "action": "joined" } }'

curl -X POST "$BASE/streams/room_42_viewers/messages" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "viewers": 27 } }'

wss://api.orbit.devotel.io/api/v1/ws/sync

import WebSocket from "ws"; // npm install ws

const socket = new WebSocket(
  "wss://api.orbit.devotel.io/api/v1/ws/sync",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY } },
);

const socket = new WebSocket(
  "wss://api.orbit.devotel.io/api/v1/ws/sync",
  ["orbit-sync-v1", `ApiKey.${apiKey}`], // or `Bearer.${sessionJwt}`
);

socket.send(JSON.stringify({
  type: "subscribe",
  kind: "map",           // document | map | list | stream
  name: "room_42_presence",
}));
// → { "type": "subscribed", "kind": "map", "name": "room_42_presence" }

{
  "type": "map.item.set",
  "kind": "map",
  "unique_name": "room_42_presence",
  "key": "user_123",
  "revision": 7,
  "data": { "status": "online" },
  "ts": 1756147200000
}

const API_KEY = process.env.ORBIT_API_KEY;
const BASE = "https://api.orbit.devotel.io/api/v1/sync";
const WS_URL = "wss://api.orbit.devotel.io/api/v1/ws/sync";
const room = "room_42";

// REST helpers -----------------------------------------------------
async function call(method, path, body) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}`);
  return res.status === 204 ? {} : (await res.json()).data;
}

const setPresence = (userId, status) =>
  call("PUT", `/maps/${room}_presence/items/${userId}`, {
    data: { status, last_seen: new Date().toISOString() },
  });

const publishViewers = (count) =>
  call("POST", `/streams/${room}_viewers/messages`, {
    data: { viewers: count },
  });

// Presence rendering ------------------------------------------------
const presence = new Map(); // userId -> { status, last_seen }
function render(presence, viewers) {
  console.log(`viewers: ${viewers ?? "?"} | online: ${[...presence.entries()]
    .filter(([, v]) => v.status === "online")
    .map(([id]) => id)
    .join(", ")}`);
}
let viewers;

// Socket -------------------------------------------------------------
function connect(userId) {
  const socket = new WebSocket(WS_URL, {
    headers: { "X-API-Key": API_KEY }, // browser: use subprotocols instead
  });

  socket.on("open", () => {
    for (const kind of ["map", "stream"]) {
      const name = kind === "map" ? `${room}_presence` : `${room}_viewers`;
      socket.send(JSON.stringify({ type: "subscribe", kind, name }));
    }
  });

  socket.on("message", (raw) => {
    const msg = JSON.parse(raw.toString());
    if (msg.type === "hello") return;
    if (msg.type === "map.item.set") {
      presence.set(msg.key, msg.data);
    } else if (msg.type === "map.item.removed") {
      presence.delete(msg.key);
    } else if (msg.type === "map.removed") {
      presence.clear();
    } else if (msg.type === "stream.message") {
      viewers = msg.data.viewers;
    }
    render(presence, viewers);
  });

  socket.on("close", () => {
    // Re-hydrate, then reconnect with backoff.
    setTimeout(async () => {
      const items = await call("GET", `/maps/${room}_presence/items`);
      presence.clear();
      for (const item of items) presence.set(item.key, item.data);
      connect(userId);
    }, 500);
  });

  // Announce yourself with a TTL so a dead client drops off the roster.
  setPresence(userId, "online");
  return socket;
}

const client = connect("user_123");