Relay SDK Reference

## Vibes Relay SDK Reference (App-Tier / Creator)

### Tier Requirement

vibes.relay is a **Creator-tier feature**. Free accounts cannot host a relay room.
If you call vibes.relay.join() from an app whose owner does not have an active Creator
subscription, the SDK throws { code: 'TIER_REQUIRED' }.

### When to Use relay vs shared

| Need | Use |
|------|-----|
| Named-event broadcast (game ticks, player moves, scores) | vibes.relay.send() — Broadcast |
| Peer-to-peer heavy traffic (streaming, high-frequency game data) | RTCDataChannel (P2P direct) |
| Peer roster (who is online in the room) | vibes.relay on('join'/'leave') — Presence |
| WebRTC handshake (offer/answer/ICE exchange) | vibes.relay.signal() |
| Per-user persistence | vibes.save() / vibes.load() |
| Widget-level shared state (Free-compatible) | vibes.shared — NOT vibes.relay |

**Critical rule:** Use Broadcast (relay.send) for ALL named events and game data.
Presence is used internally for the peer roster only — it caps at ~20 msg/s and is
NOT suitable for carrying game tick data. All game data must flow through relay.send
(Broadcast) or an RTCDataChannel, never through Presence.

### Tier-Scoped Quotas (Creator plan)

| Limit | Value | Enforced by |
|-------|-------|-------------|
| Concurrent relay rooms per user | 5 | join gate (server) |
| Connections per room | 10 | join gate (server) |
| Payload size per message | 8 KB | join gate (server) + SDK pre-check |
| Per-connection send rate | 5 msg/s | SDK client-side UX throttle only |

Note: the per-message rate (5 msg/s) is a **client-side UX throttle** — the relay
broker does NOT enforce per-message rate server-side. The hard server gates are the
connection cap, room cap, and payload size limit. Size your traffic accordingly.

### Setup

vibes.relay is available as window.vibes.relay (or just vibes.relay) in every app
running on run.itjustvibes.com. No imports needed — the platform injects it.

```js
vibes.onReady(async () => {
  const { peerId } = await vibes.relay.join('my-room');
  console.log('joined as', peerId);
});
```

### vibes.relay.join(roomName)

Join a relay room. Must be called before any other relay method.

```js
const { roomName, peerId } = await vibes.relay.join('game-room');
// peerId is your stable peer ID for this SDK session
```

- Returns Promise<{ roomName: string, peerId: string }>
- Throws { code: 'TIER_REQUIRED' } if owner is not a Creator subscriber
- Throws { code: 'ROOM_FULL' } if connections per room limit is reached
- Throws { code: 'MAX_ROOMS_REACHED' } if per-user room limit is exceeded
- Throws { code: 'NO_CLIENT' } if Supabase Realtime is unavailable

### vibes.relay.send(eventName, data)

Broadcast a named event to all other peers in the room.

```js
vibes.relay.send('move', { x: 42, y: 100 });
vibes.relay.send('score', { player: peerId, points: 10 });
```

- data must be JSON-serializable and under 8 KB
- Client-side rate throttle: 5 msg/s per connection (UX guard — warns in console if exceeded)
- Does NOT send to the sender (self: false)
- Throws nothing — drops silently with console.warn if not joined or limits exceeded

### vibes.relay.on(eventName, callback)

Listen for incoming events from other peers.

```js
// Named game event
vibes.relay.on('move', (data) => {
  updatePosition(data.x, data.y);
});

// Peer roster events
vibes.relay.on('join', (peerId) => {
  console.log('peer joined:', peerId);
});
vibes.relay.on('leave', (peerId) => {
  console.log('peer left:', peerId);
});

// Reconnect notification
vibes.relay.on('reconnect', () => {
  console.log('relay reconnected');
});
```

- Special event names: 'join', 'leave', 'reconnect' (roster/lifecycle)
- All other event names are game/app events forwarded from relay.send()

### vibes.relay.signal(peerId, payload)

Send a WebRTC signaling payload (offer, answer, or ICE candidate) to a specific peer.
This is for the WebRTC handshake ONLY — never send game data through signal().

```js
// Initiator sends offer
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
vibes.relay.signal(remotePeerId, { type: 'offer', sdp: offer.sdp });

// Responder sends answer
vibes.relay.signal(remotePeerId, { type: 'answer', sdp: answer.sdp });

// Both sides send ICE candidates
pc.onicecandidate = (e) => {
  if (e.candidate) vibes.relay.signal(remotePeerId, { type: 'ice', candidate: e.candidate });
};
```

- payload is any JSON-serializable object
- Delivered ONLY to the addressed peer (server routes on peerId — not broadcast to all)

### vibes.relay.onSignal(callback)

Register a callback for incoming WebRTC signals addressed to this peer.

```js
vibes.relay.onSignal((fromPeerId, payload) => {
  if (payload.type === 'offer') {
    // handle WebRTC offer
  } else if (payload.type === 'answer') {
    // handle WebRTC answer
  } else if (payload.type === 'ice') {
    pc.addIceCandidate(payload.candidate);
  }
});
```

- callback(fromPeerId: string, payload: any)

### vibes.relay.getIceServers()

Returns the ICE server list (STUN/TURN) for RTCPeerConnection configuration.
Cached from the join response; fetches from the server if called before join.

```js
const iceServers = await vibes.relay.getIceServers();
const pc = new RTCPeerConnection({ iceServers });
```

- Returns Promise<Array<RTCIceServer>>

### vibes.relay.getPeers()

Returns a snapshot of the current peer roster (Presence state).

```js
const peers = vibes.relay.getPeers();
// [{ peerId: 'peer-abc123-...', joinedAt: 1718000000000 }, ...]
```

- Returns Array<{ peerId: string, joinedAt: number, ... }>
- Synchronous — no await needed
- Returns [] if not joined

### vibes.relay.leave(roomName)

Unsubscribe from a relay room, clear the heartbeat, and notify the server.

```js
vibes.relay.leave('game-room');
// or leave the most recently joined room:
vibes.relay.leave();
```

- If roomName is omitted, leaves the first joined room
- Does NOT throw — safe to call even if not joined

### Full P2P WebRTC Example

```js
vibes.onReady(async () => {
  const { peerId: myId } = await vibes.relay.join('battle-room');
  const iceServers = await vibes.relay.getIceServers();
  let pc = null;

  // Peer roster: elect the initiator lexicographically
  vibes.relay.on('join', async (remotePeerId) => {
    const isInitiator = myId < remotePeerId;
    pc = new RTCPeerConnection({ iceServers });
    const dc = isInitiator ? pc.createDataChannel('game') : null;

    pc.onicecandidate = (e) => {
      if (e.candidate) vibes.relay.signal(remotePeerId, { type: 'ice', candidate: e.candidate });
    };

    if (dc) {
      dc.onmessage = (e) => console.log('p2p message:', e.data);
      const offer = await pc.createOffer();
      await pc.setLocalDescription(offer);
      vibes.relay.signal(remotePeerId, { type: 'offer', sdp: offer.sdp });
    } else {
      pc.ondatachannel = (e) => {
        e.channel.onmessage = (m) => console.log('p2p message:', m.data);
      };
    }
  });

  vibes.relay.onSignal(async (from, payload) => {
    if (payload.type === 'offer') {
      const answer = await pc.createAnswer();
      await pc.setLocalDescription(answer);
      vibes.relay.signal(from, { type: 'answer', sdp: answer.sdp });
    } else if (payload.type === 'answer') {
      await pc.setRemoteDescription({ type: 'answer', sdp: payload.sdp });
    } else if (payload.type === 'ice') {
      await pc.addIceCandidate(payload.candidate);
    }
  });
});
```

### Rules

1. **Call vibes.relay.join() once per room at startup** — before send, on, signal, or getPeers.
2. **Use relay.send() for game data** — not Presence, not relay.signal().
3. **Use relay.signal() for WebRTC handshake only** — offer/answer/ICE exchange, not game ticks.
4. **For high-frequency or large game data** — send over RTCDataChannel once P2P is connected.
5. **Await all relay methods that return Promises** (join, getIceServers).
6. **Wrap relay.join() in try/catch** — TIER_REQUIRED and ROOM_FULL are expected error codes.
7. **Do NOT use localStorage, sessionStorage, or window.storage** — use vibes.save/vibes.load for persistence.