# @metered-ca/peer — JavaScript / TypeScript SDK reference

For developers using the `@metered-ca/peer` npm package — this file documents the SDK surface end-to-end. The SDK wraps the Realtime Messaging wire protocol with framing, ack correlation, auto-reconnect, perfect-negotiation WebRTC, multi-stream + per-track metadata, and TURN credential injection. **You should not need to read the wire-protocol layer to build with the SDK** — but if you do, see [the raw-WebSocket reference](https://www.metered.ca/docs/llms-realtime-messaging-raw-websocket.txt) (also useful when interoperating with non-JS clients).

- npm: https://www.npmjs.com/package/@metered-ca/peer
- Docs: https://www.metered.ca/docs/realtime-messaging/sdk-javascript/
- Dashboard: https://dashboard.metered.ca | Pricing: https://www.metered.ca/pricing

---

## Install

```
npm install @metered-ca/peer
```

ESM + CJS + UMD bundles. Full UMD ~13 KB gzipped (WebRTC included), within a 30 KB budget. Zero runtime dependencies. Works in browser + Node 18+.

For browser `<script>` tag:

```html
<script src="https://unpkg.com/@metered-ca/peer/dist/index.umd.js"></script>
<script>
  const { MeteredPeer, SignallingClient } = window.MeteredPeer;
</script>
```

---

## Two classes

Pick by what you're building:

| You're building… | Use | Why |
|---|---|---|
| **WebRTC video / voice call**, screen share, peer-to-peer game | `MeteredPeer` | Joins a channel, discovers peers via presence, manages each `RTCPeerConnection`, fans `MediaStream`s out automatically, recovers ICE on network changes |
| **Live chat with presence**, classroom roster, multiplayer lobby | `MeteredPeer` | The `peer-joined` / `peer-left` events drive your UI; `peer.send(data)` broadcasts or directs |
| **IoT telemetry**, MQTT-style pub/sub, AI agent message bus, collaborative cursors | `SignallingClient` | Pub/sub + directed messages without the WebRTC overhead. Smaller, simpler, multiple channels per connection |

Not sure? Start with `MeteredPeer`. Drop to `SignallingClient` later if you find you don't need the channel-+-peer model.

---

## Quick start — `MeteredPeer` (WebRTC + presence + chat)

```ts
import { MeteredPeer } from "@metered-ca/peer";

const peer = new MeteredPeer({
  // exactly one of:
  apiKey: "pk_live_…",      // pk_ keys must have `Send` ticked in the dashboard
                            // for WebRTC; off by default. See "pk_ gotcha" below.
  tokenProvider: async () => fetchJwt(),
});

peer.on("peer-joined", ({ peer: remote }) => {
  remote.on("stream-added", ({ stream, metadata }) => {
    // Preferred over `track` — fires once per remote MediaStream.
    attachToVideoTile(stream, metadata?.role);
  });
});
peer.on("peer-left", ({ peer: remote }) => removeVideoTile(remote.id));
peer.on("data", ({ senderPeerId, data, kind, senderMetadata }) => {
  // `senderPeerId` is server-stamped — trust it.
  // `kind` discriminates broadcast vs direct.
  // `senderMetadata` requires JWT path + `includeSenderMetadata` on join for broadcasts.
});

const localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
peer.addStream(localStream, { role: "camera", label: "front cam" });
await peer.join("room-42");

await peer.send({ chat: "hi everyone" });        // broadcast to channel
await peer.sendTo(otherPeerId, { hi: "you" });   // directed to one peer
```

**Public methods on `MeteredPeer`:**
- `join(channel, opts?)` — `opts: { includeSenderMetadata?: boolean }`
- `close(reason?)` — terminal. To reconnect after closing, construct a new `MeteredPeer`.
- `send(data)` — broadcast to channel
- `sendTo(peerId, data)` — directed to one peer
- `addStream(stream, metadata?)` / `removeStream(stream)`
- `addTrack(track, stream?, metadata?)` / `removeTrack(track)`
- `replaceTrack(oldTrack, newTrack)` — swap without renegotiation
- `getStreamMetadata(stream)` / `getTrackMetadata(track)` — local lookups for what YOU attached
- `on(event, handler)` / `off(event, handler)` / `once(event, handler)`

**Read-only state:** `peer.state`, `peer.peerId`, `peer.channel`, `peer.remotePeers` (snapshot).

**pk_ key gotcha — `Send` permission is required for WebRTC.** When you create a publishable key in the dashboard, `Subscribe` / `Publish` / `Presence` are checked by default but `Send` is OFF (because the key lives in users' browsers and `Send` lets anyone holding it direct-message any peer). MeteredPeer's WebRTC layer uses the wire protocol's `send` op under the hood to exchange SDP and ICE between peers — without it, `peer.join()` and `peer.addStream()` complete, presence fires, but `peer-joined → stream-added` never fires because no `RTCPeerConnection` ever negotiates. **For pk_ + WebRTC, tick `Send` when creating the key.** For pk_ + pub/sub-only (`SignallingClient`, no WebRTC), `Send` is only required if you call `client.send(peerId, ...)` directly.

---

## Quick start — `SignallingClient` (pub/sub only)

```ts
import { SignallingClient } from "@metered-ca/peer";

const client = new SignallingClient({ apiKey: "pk_live_…" });
await client.connect();

await client.subscribe("alerts/critical");
client.on("message", ({ channel, from, data }) => console.log(from, data));
await client.publish("alerts/critical", { sensor: "T-12", value: 92 });

// Direct point-to-point send
await client.send(otherPeerId, { type: "challenge", nonce: "abc" });
```

**Public methods on `SignallingClient`:**
- `connect()` / `close(code?, reason?)`
- `subscribe(channel, opts?)` / `unsubscribe(channel)`
- `publish(channel, data, opts?)` / `send(toPeerId, data, opts?)`
- `on` / `off` / `once`

**Read-only state:** `client.state`.

**Naming asymmetry vs `MeteredPeer`:**
- SignallingClient keeps `client.send(toPeerId, data)` (no `sendTo` rename) — wire-faithful to the JSON `send` frame.
- SignallingClient's directed-message event is `direct { from, ... }` (not `senderPeerId`) — same wire-faithfulness rationale.
- MeteredPeer earns the more verbose names because it merges sources; SignallingClient stays lower-level.

---

## Auth modes

Two paths. Pick by where your code runs.

### Path 1 — `apiKey` (publishable key)

Direct browser use. Fixed scope from dashboard. No backend required.

```ts
const peer = new MeteredPeer({ apiKey: "pk_live_…" });
```

Set `allowedOrigins` on the key from the dashboard to lock it to your domain. Use for static sites, prototypes, anywhere per-user scoping isn't needed.

**For WebRTC: tick `Send` when creating the key.** It's off by default for publishable keys (the dashboard's amber warning explains why — anyone holding the key could direct-message any peer). MeteredPeer's WebRTC layer needs `Send` because the wire protocol's `send` operation carries SDP and ICE between peers. The dashboard's amber callout specifically allows enabling it for static-page browser-to-browser WebRTC, which is this exact use case.

**Limitations vs the JWT path:**
- Server assigns random UUID as `peerId` (no stable per-user identity)
- No `peerMetadata` (no JWT to carry it)
- `iceServers` come from auto-injection (when the key has "Auto-inject TURN" enabled, default) — you do not need to fetch TURN credentials separately. See [WebRTC No-Backend guide](https://www.metered.ca/docs/realtime-messaging/sdk-javascript/guides/webrtc-no-backend) for the full pattern.

### Path 2 — `tokenProvider` (sk_-minted JWT)

Backend mints an HS256 JWT signed with `sk_live_…`. SDK calls your provider on first connect AND every reconnect (auto-refresh).

```ts
const peer = new MeteredPeer({
  tokenProvider: async () => {
    const r = await fetch("/api/mint-realtime-token");
    if (!r.ok) throw new Error("mint failed");
    return (await r.json()).token;
  },
});
```

### Minting JWTs server-side (Node.js)

```js
const jwt = require("jsonwebtoken");

app.get("/api/mint-realtime-token", requireAuth, async (req, res) => {
  // Optional: fetch TURN creds for WebRTC use cases
  const turnCreds = await fetchTurnForUser(req.user.id);

  const token = jwt.sign(
    {
      sub: req.user.id,                                    // becomes peerId
      channels: [`app_${req.appId}/call-*`],               // wildcard
      permissions: ["publish", "subscribe", "presence", "send"],
      metadata: { iceServers: turnCreds },                 // welcome-only (TURN)
      peerMetadata: { username: req.user.name, avatarUrl: req.user.avatar }, // visible to other peers
      exp: Math.floor(Date.now() / 1000) + 3600,
    },
    process.env.SK_SECRET,
    { algorithm: "HS256", header: { alg: "HS256", kid: process.env.SK_ID } },
  );
  res.json({ token });
});
```

**Critical:** `tokenProvider` is called on every reconnect — your endpoint must return a FRESH JWT each call, or cache with a TTL well under the JWT's `exp`. Returning a stale JWT triggers 4002 → re-mint → stale JWT loop.

### JWT claims reference

| Claim | Required | What it does |
|---|---|---|
| `sub` | yes | Becomes the peer's `peerId`. Up to 128 chars. Use your user ID. |
| `exp` | yes | Unix seconds. ≤ 24h. |
| `channels` | yes | Array of wildcard patterns (`*` = one segment, `**` = multi-segment). |
| `permissions` | yes | Subset of `["publish", "subscribe", "presence", "send"]`. |
| `metadata` | no | Up to 8 KB. Server returns it on `welcome`. WebRTC: put `iceServers` here. |
| `peerMetadata` | no | Up to 4 KB. Server stamps onto presence + direct + opt-in channel messages. |

### Or skip the JWT signing — use the REST API

```js
const { token } = await fetch("https://rms.metered.ca/v1/tokens", {
  method: "POST",
  headers: { Authorization: `Bearer ${SK_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    peerId, channels, permissions, expiresInSec: 3600,
    metadata: { iceServers }, peerMetadata: { username, avatarUrl },
  }),
}).then(r => r.json());
```

---

## Multi-stream + per-track metadata

`addStream` and `addTrack` accept an optional `StreamMetadata` bag:

```ts
interface StreamMetadata {
  role?: string;     // convention: "camera" | "screen" | "canvas" | "file" | custom
  label?: string;    // human-readable, e.g. "front cam", "shared screen"
  [key: string]: unknown;
}
```

The bag arrives at the receiver on `track` and `stream-added` events. Use it to label streams so receivers can lay out simultaneous camera + screen share correctly.

```ts
// Sender
peer.addStream(cam, { role: "camera", label: "front cam" });
peer.addStream(screen, { role: "screen", label: "shared window" });

// Receiver
peer.on("peer-joined", ({ peer: remote }) => {
  remote.on("stream-added", ({ stream, metadata }) => {
    if (metadata?.role === "camera") attachToFaceTile(stream);
    if (metadata?.role === "screen") attachToScreenTile(stream);
  });
  remote.on("stream-removed", ({ stream }) => removeTile(stream.id));
});
```

**Trust model:** `StreamMetadata` is sender-stamped and server-routed verbatim, NOT JWT-signed. Treat as untrusted. For server-verified identity, use the JWT's `peerMetadata` (surfaces as `senderMetadata` on data + `remote.metadata` on RemotePeer).

**Reconcile semantics:**
- `stream-added` fires fresh after reconcile with same `stream.id` but a NEW `MediaStream` object — customer must re-bind `<video>.srcObject`
- `stream-removed` is suppressed during reconcile (no false "they left" signals)
- The metadata bag survives reconcile (SDK re-sends before track re-attachment)

`peer.getStreamMetadata(stream)` / `peer.getTrackMetadata(track)` look up what YOU attached locally. To get the remote's metadata, read it off the `stream-added` event.

---

## Reconnect — 3 layers (handled automatically)

1. **Signalling WebSocket** — exp backoff (500ms→30s), jitter, close-code-aware. Default 100 attempts.
2. **ICE-restart ladder** — per-peer, 9 attempts over ~121 s, surfaces as `remote.state === "reconnecting"`.
3. **Channel reconcile** — on signalling WS reconnect, `RemotePeer` refs are PRESERVED across the drop (same `===` object); underlying `RTCPeerConnection` is silently swapped with fresh TURN creds. Local streams auto-reattach.

**What survives:** `RemotePeer` references, `remote.id`, `remote.metadata`, `remote.state`, stream-level metadata, local streams attached via `addStream`.

**What doesn't survive:**
- `remote.pc` — different `RTCPeerConnection` object after reconcile; re-read every time you need it
- `RTCDataChannel` opened via `remote.pc.createDataChannel(...)` — tied to old PC, re-open on `state-change` to `"connected"`
- `MediaStream` object identity (stream.id is stable, the object is fresh) — re-bind on each `stream-added`
- Customer-held listeners on `remote.pc` (via `addEventListener`) — old PC closed; listen on the `RemotePeer` wrapper instead (`remote.on(...)`)

**Default reconnect options:**
```ts
{ initialDelayMs: 500, multiplier: 2, maxDelayMs: 30_000, jitterRatio: 0.2, maxAttempts: 100 }
```

For server-side / agent / IoT processes:
```ts
new SignallingClient({
  tokenProvider,
  reconnect: { maxAttempts: Infinity, maxDelayMs: 60_000 },
});
```

---

## Routing model — `peer.send` / `peer.sendTo` is SERVER-routed (not P2P)

Both methods route through the signalling server, NOT WebRTC DataChannel. Trade-offs:
- works before ICE completes
- same code path for broadcast + direct
- counts against signalling-message quota

For low-latency P2P data (game ticks, telemetry stream, file transfer), open a real `RTCDataChannel` via the `remote.pc.createDataChannel(...)` escape hatch. **Wire DC creation to `remote.on("state-change", ({ to }) => to === "connected" && …)`** — this fires on initial connect AND each reconcile cycle, so the DC survives reconnects.

`remote.send(data)` is shorthand for `peer.sendTo(remote.id, data)`.

---

## MeteredPeer events

- `joined { peerId, channel }` — after `join()` resolves
- `left { peerId, channel, reason? }` — terminal. `peerId`/`channel` are snapshots; both `null` if `close()` fired before welcome / subscribe-ack
- `state-change { from, to }` — `"idle"` | `"joining"` | `"joined"` | `"reconnecting"` | `"leaving"` | `"closed"` — drives reconnect UI
- `peer-joined { peer: RemotePeer }`
- `peer-left { peer: RemotePeer }`
- `data { senderPeerId, data, kind: "broadcast" | "direct", senderMetadata? }` — use `senderPeerId` (server-stamped), NOT `data.from`. `kind` discriminates channel broadcasts from one-to-one direct sends. `senderMetadata` is the sender's JWT `peerMetadata` (only on opt-in via `join({ includeSenderMetadata: true })` for broadcasts; always present for directs when sender's JWT had peerMetadata). **Only fires for senders currently in the channel** — SDK drops cross-channel direct messages here; use `SignallingClient` directly for unscoped routing.
- `error { err: Error }` — unified fatal-condition surface. Fires for terminal WS close codes (4001/4002/4003/4012/4020), fatal server-error frames, and `tokenProvider` failures past the retry threshold. `err.name` carries the symbolic code so customers can wire a single switch.

---

## RemotePeer events (subscribe on each `peer-joined`'s `remote`)

- `state-change { from, to }` — per-peer connection state: `"idle"` | `"connecting"` | `"connected"` | `"reconnecting"` | `"closed"`
- `track { track, streams, metadata? }` — per-track event (use for per-track routing like audio→pipeline)
- `stream-added { stream, metadata? }` — per-stream lifecycle (preferred for tile-per-stream UIs)
- `stream-removed { stream }` — counterpart; suppressed during reconcile
- `data-channel { channel: RTCDataChannel }` — remote opened a DC via the escape hatch
- `negotiation-error { err }` / `ice-candidate-error { err }` — mostly ignorable

**RemotePeer read-only props:** `remote.id`, `remote.metadata` (peer-level peerMetadata from sender's JWT — readonly but refreshes if remote rotates JWT during reconnect), `remote.state`, `remote.polite` (perfect-negotiation tie-break), `remote.pc` (escape hatch — RTCPeerConnection ref).

**Methods on RemotePeer:** `remote.send(data)` (shorthand for `peer.sendTo(remote.id, data)`), `on` / `off` / `once`.

---

## SignallingClient events

- `connected { peerId, serverTime, expiresAt, isReconnect, maxMessageSize, iceServers? }`
- `disconnected { code, reason, willReconnect }` — `willReconnect: false` = SDK gave up
- `state-change { from, to }` — `"idle"` | `"connecting"` | `"connected"` | `"reconnecting"` | `"closed"`
- `message { channel, from, fromMetadata?, data }` — channel broadcast
- `direct { from, fromMetadata?, data }` — point-to-point send to you
- `presence { channel, joined, left }` — both arrays of `{ peerId, metadata? }`
- `server-error { code, message?, requestId? }` — server-rejected request (renamed from `error` to disambiguate from `MeteredPeer.error` which is exception-style)
- `going-away { retryAfterMs }` — informational; SDK does NOT automatically delay by `retryAfterMs` (uses normal backoff)
- `token-provider-error { consecutiveFailures, err }` — fires after 3 consecutive `tokenProvider()` failures

---

## Error classes

All extend `Error`. Use `instanceof` to branch.

| Class | Thrown from | Fields |
|---|---|---|
| `SignallingConnectError` | `client.connect()` | `closeCode`, `closeReason` |
| `MeteredPeerSendError` | `peer.send` / `peer.sendTo` / `peer.join` / `remote.send` | `code: "reserved_channel" \| "not_joined" \| "invalid_args" \| "self_send"` |
| `MeteredPeerStateError` | `addStream` / `addTrack` / `removeStream` / `removeTrack` / `replaceTrack` / `join` | `code: "invalid_state" \| "track_already_attached"`, `method`, `currentState?` |
| `MeteredPeerOversizedError` | `peer.send` / `peer.sendTo` / `addStream` / `addTrack` (oversized metadata) | `size`, `cap` |
| `MeteredPeerReplaceTrackError` | `peer.replaceTrack` (partial failure) | `succeeded: string[]`, `failed: { peerId, err }[]` |
| `DataChannelOverflowError` | `DataChannel.send` (queue full) | `queued`, `cap` |

**Stable contract for 1.0:** class names, `e.code` literal values, and field names are SemVer-stable. `e.message` text is human-readable and may change between minor versions — branch on `instanceof` / `e.code` / `e.name`, never parse `e.message`.

---

## Close codes (`WsCloseCode` enum)

Exported value enum. Most SDK customers never branch on close codes directly — they read `err.name` from `MeteredPeer.error` (symbolic name) or `code` from `SignallingClient.disconnected`.

| Code | Constant | What it means | What to do |
|---|---|---|---|
| 1001 | `GoingAway` | Server shutdown for deploy | SDK auto-reconnects |
| 1008 | `PolicyViolation` | Client wire-format bug | Fix your code |
| 1009 | `MessageTooBig` | Payload exceeded cap | Use `MeteredPeerOversizedError` to catch pre-send |
| 4000 | `ClientInactivity` | SDK inactivity watchdog fired | SDK self-heals |
| 4001 | `InvalidToken` | JWT signature / kid / format wrong | **Terminal — re-auth user** |
| 4002 | `TokenExpired` | JWT `exp` past | SDK auto-refreshes via tokenProvider |
| 4003 | `ChannelNotAuthorized` | JWT `channels` doesn't include channel | **Terminal — fix JWT scope** |
| 4010 | `OverConcurrentLimit` | At plan's concurrent-connection cap | SDK retries with ≥30 s floor; raise plan or fix leaks |
| 4011 | `OverMessageRate` | Per-connection rate limit | SDK reconnects (fresh bucket); throttle producer |
| 4012 | `AccountSuspended` | Customer suspended | **Terminal — direct to billing** |
| 4020 | `AdminDisconnect` | `DELETE /v1/peers/:id` from REST | **Terminal — show "you were disconnected"** |

**MeteredPeer's unified `error` event** fires for the bolded "Terminal" codes (4001/4002/4003/4012/4020), plus fatal server-error frames and `tokenProvider` exhaustion. Wire a single handler:

```ts
peer.on("error", ({ err }) => {
  switch (err.name) {
    case "invalid_token": case "token_expired":  showLoginPrompt(); break;
    case "channel_not_authorized":               showAccessDenied(); break;
    case "account_suspended":                    showBillingUI(); break;
    case "admin_disconnect":                     showKickedUI(); break;
    case "TokenProviderError":                   showAuthFlowBroken(); break;
    default:                                     reportToSentry(err);
  }
});
```

---

## Reconnect UI patterns (customer code owns these)

1. **Banner** — listen for `state-change` → `"reconnecting"`, show banner. Delay show by ~1 s to avoid flicker on fast reconnects.
2. **Stuck-reconnect** — after 30 s in `"reconnecting"`, surface a "retry now?" button → `peer.close()` then `new MeteredPeer(opts).join(channel)`.
3. **DataChannel reopen** — wire `remote.pc.createDataChannel(...)` to `state-change` → `"connected"` (fires once on initial connect AND once per reconcile cycle).
4. **Terminal close codes** — MeteredPeer: wire `peer.on("error", ({err}) => switch(err.name))` (covered above). SignallingClient: branch on `disconnected.code`.
5. **TokenProviderError** — `err.name === "TokenProviderError"` after 3 consecutive `tokenProvider()` failures; show "please log in again".

---

## When to use which class

- **WebRTC video / voice / screen share** → MeteredPeer
- **Multi-peer presence with media** → MeteredPeer
- **Chat / classroom / lobby (no media)** → MeteredPeer if you want `peer-joined`/`peer-left` per-peer state; SignallingClient if you want multi-channel
- **IoT telemetry, AI agents, collaborative cursors** → SignallingClient
- **One connection subscribing to many channels** → SignallingClient (MeteredPeer is one-channel-per-instance)

---

## Reserved channel prefixes + channel naming

- `_metered/`, `_internal/`, `_system/` — server-reserved. `peer.join()` rejects synchronously with `MeteredPeerSendError({ code: "reserved_channel" })`.
- Channel names ≤ 256 chars.
- Wildcard patterns (in your JWT's `channels` claim or the dashboard key's `channelPatterns`): `*` matches one path segment, `**` matches any number of segments.

---

## Server-side REST publish (from your backend)

Even with SDK-using browsers, your backend may want to publish on behalf of a system actor (chat moderation announcement, IoT command, agent fan-out). Use the REST control plane — no WebSocket needed:

```js
await fetch(`https://rms.metered.ca/v1/channels/${channel}/publish`, {
  method: "POST",
  headers: { Authorization: `Bearer ${SK_SECRET}`, "Content-Type": "application/json" },
  body: JSON.stringify({ data: { type: "system", message: "..." }, from: "system" }),
});
```

Other useful endpoints: `GET /v1/channels/:id/peers` (list subscribers), `DELETE /v1/peers/:id` (force-disconnect with close code 4020), `GET /v1/usage` (concurrent + message counters).

---

## React Native

The same package runs on React Native — RN executes JavaScript. Supply WebRTC with `react-native-webrtc`; `WebSocket` is already global. **Requires `@metered-ca/peer` ≥ 1.0.4** (earlier versions needed a global `TextEncoder`, absent on some Hermes versions).

```bash
npm install @metered-ca/peer react-native-webrtc   # peer ≥ 1.0.4
```

Wire WebRTC via `rtcPeerConnectionFactory` (or call `registerGlobals()` once at startup and omit it):

```ts
import { MeteredPeer, type RTCPeerConnectionLike } from "@metered-ca/peer";
import { RTCPeerConnection, mediaDevices } from "react-native-webrtc";

const peer = new MeteredPeer({
  apiKey: "pk_live_…",
  rtcPeerConnectionFactory: (cfg) =>
    new RTCPeerConnection(cfg as object) as unknown as RTCPeerConnectionLike,
});
const stream = await mediaDevices.getUserMedia({ audio: true, video: true });
peer.addStream(stream as never, { role: "camera" });
await peer.join("room-42");
// Render remote media with <RTCView streamURL={stream.toURL()} /> (not <video>);
// re-read .toURL() on every stream-added (it re-fires across reconcile).
```

- **Expo:** needs a dev build + `@config-plugins/react-native-webrtc` — does NOT run in Expo Go.
- **Bare RN:** `cd ios && pod install`; iOS camera/mic usage strings + Android permissions; `minSdkVersion 24`; ProGuard `-keep class org.webrtc.** { *; }`.
- **TypeScript:** peer-lib types against the DOM lib — cast the factory return to `RTCPeerConnectionLike` and the `MediaStream` at the `addStream` / `stream-added` boundary.
- Everything else — events, reconnect, reconcile, multi-stream metadata — is identical to the browser.
- Full guide: https://www.metered.ca/docs/realtime-messaging/sdk-javascript/guides/react-native

---

## Bundle / build

- ESM: `dist/index.mjs`
- CJS: `dist/index.cjs`
- UMD: `dist/index.umd.js` (browser global `MeteredPeer`)
- Types: `dist/index.d.ts`
- `"sideEffects": false`, tree-shakable
- Full UMD ~13 KB gzipped (WebRTC included), within a 30 KB budget

---

## Examples

- Basic video call (one HTML file, two tabs): https://www.metered.ca/docs/realtime-messaging/sdk-javascript/examples/basic-call
- P2P DataChannel (reconcile-aware reopen + backpressure): https://www.metered.ca/docs/realtime-messaging/sdk-javascript/examples/data-channel
- React integration (`useMeteredPeer` hook + `<VideoCall>`): https://www.metered.ca/docs/realtime-messaging/sdk-javascript/examples/react-integration
- React Native (RN hook + `<RTCView>` tiles; Expo + bare apps; Detox e2e): https://www.metered.ca/docs/realtime-messaging/sdk-javascript/examples/react-native

---

## Documentation pages

- Overview: https://www.metered.ca/docs/realtime-messaging/sdk-javascript/
- Getting Started: /sdk-javascript/getting-started
- API Reference: /sdk-javascript/api-reference/metered-peer, /signalling-client, /remote-peer, /data-channel, /errors-and-codes
- Guides: /sdk-javascript/guides/authentication, /reconnect-best-practices, /webrtc-video-call, /webrtc-no-backend, /react-native, /presence-and-chat, /data-channel-low-latency, /ai-agent-communication, /iot-telemetry
- Migration: /sdk-javascript/migration/from-simple-peer, /from-peerjs

---

## Links

- npm: https://www.npmjs.com/package/@metered-ca/peer
- [Full SDK documentation](https://www.metered.ca/docs/realtime-messaging/sdk-javascript/)
- [Raw-WebSocket llms reference](https://www.metered.ca/docs/llms-realtime-messaging-raw-websocket.txt) — for non-JS stacks or peeking at the wire
- [Unified llms reference (SDK + wire)](https://www.metered.ca/docs/llms-realtime-messaging.txt)
- [Dashboard](https://dashboard.metered.ca)
- [Pricing](https://www.metered.ca/pricing)
- [Metered TURN Server](https://www.metered.ca/docs/llms-turn-server.txt) — the natural pairing for WebRTC signalling
- [Metered Global Cloud SFU](https://www.metered.ca/docs/llms-sfu.txt) — for media plane on group calls > 6 peers