JS SDK

Use the rstream JavaScript SDKs for control-plane APIs, tunnels, tokens, TURN, and watch streams.

Written by uartnet

@uartnet

The JavaScript SDKs are designed primarily for backend integrations: API servers, Next.js route handlers, workers, automation services, and other systems that need to talk to rstream programmatically.

Repository: github.com/rstreamlabs/rstream-js

This page focuses on the SDK surface. If you need the raw HTTP routes instead, see APIs. For real-time event semantics, see Signaling.

The repository is split into focused packages. @rstreamlabs/rstream covers managed control-plane APIs and shared types. @rstreamlabs/tunnels covers tunnels engine and data-plane APIs. @rstreamlabs/react provides React hooks and components built on top of @rstreamlabs/tunnels.

Install

npm install @rstreamlabs/rstream @rstreamlabs/tunnels

Control plane vs tunnels engine

Use @rstreamlabs/rstream for managed control-plane operations exposed by https://rstream.io, including whoami, managed tunnel project listing, project-endpoint resolution, and managed TURN credential issuance. Use @rstreamlabs/tunnels for engine and data-plane operations such as listing tunnels and clients, watching engine events, minting short-lived auth tokens from application credentials, deriving TURN credentials locally, and connecting to self-hosted engines.

Managed control-plane usage

@rstreamlabs/rstream supports both bearer tokens and application credentials for control-plane requests.

import { RstreamClient } from "@rstreamlabs/rstream";
 
const client = new RstreamClient({
  credentials: { token: process.env.RSTREAM_AUTHENTICATION_TOKEN! },
});
 
const whoami = await client.whoami();
const projects = await client.tunnels.projects.list();
const project =
  await client.tunnels.projects.resolveByEndpoint("project-endpoint");

Application credentials work as well:

import { RstreamClient } from "@rstreamlabs/rstream";
 
const client = new RstreamClient({
  credentials: {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
});
 
const whoami = await client.whoami();
const projects = await client.tunnels.projects.list();

Direct engine or self-hosted usage

When you already know the engine address, connect directly with @rstreamlabs/tunnels.

import { RstreamTunnelsClient } from "@rstreamlabs/tunnels";
 
const client = new RstreamTunnelsClient({
  credentials: { token: process.env.RSTREAM_AUTHENTICATION_TOKEN! },
  engine: process.env.RSTREAM_ENGINE!,
});
 
const tunnels = await client.tunnels.list();
const clients = await client.clients.list();

This is the usual path for self-hosted deployments where no managed control plane exists.

Managed tunnels with application credentials

For backend integrations, the most useful flow is often to start from an application clientId and clientSecret, then let the SDK resolve the managed project and mint short-lived auth tokens as needed.

import { RstreamTunnelsClient } from "@rstreamlabs/tunnels";
 
const client = new RstreamTunnelsClient({
  apiUrl: "https://rstream.io",
  credentials: {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
  projectEndpoint: "project-endpoint",
});
 
const engine = await client.getEngine();
const tunnels = await client.tunnels.list();

This path keeps long-lived application credentials on the backend, while requests to the engine use short-lived auth tokens minted by the SDK.

Minting short-lived auth tokens

@rstreamlabs/tunnels can mint short-lived app tokens locally from application credentials.

import { RstreamTunnelsClient } from "@rstreamlabs/tunnels";
 
const admin = new RstreamTunnelsClient({
  credentials: {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
  projectEndpoint: "project-endpoint",
});
 
const { token } = await admin.auth.createAuthToken({
  expires_in: 60,
});

You can then hand that token to another backend component, a browser-facing session bootstrap endpoint, or a device/client that should only hold a short-lived token.

Fine-grained tokens

Fine-grained tunnel grants let a backend mint a token with narrow tunnel permissions for downstream clients. Use scopes for a global grant, or tunnelsGrants when the token must be tied to specific workspaces or projects.

import { RstreamTunnelsClient } from "@rstreamlabs/tunnels";
 
const admin = new RstreamTunnelsClient({
  credentials: {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
  projectEndpoint: "project-endpoint",
});
 
const { token } = await admin.auth.createAuthToken({
  expires_in: 60,
  tunnelsGrants: [
    {
      projects: ["project-id"],
      scopes: {
        tunnels: {
          create: {
            filters: {
              protocol: { oneof: ["http"] },
              labels: {
                env: "prod",
              },
            },
          },
          connect: {
            params: {
              path: { regex: "^/api" },
            },
          },
          list: {
            select: {
              id: true,
              name: true,
              protocol: true,
            },
          },
        },
      },
    },
  ],
});

See Fine-Grained Tokens for the full tunnel grants model, scope operators, and deployment constraints.

Watching engine events

The watch helper connects to the engine over SSE or WebSocket and validates incoming events.

import { Watch } from "@rstreamlabs/tunnels";
 
const watch = new Watch(
  {
    auth: process.env.RSTREAM_AUTHENTICATION_TOKEN!,
    engine: process.env.RSTREAM_ENGINE!,
    transport: "sse",
  },
  {
    onEvent: (event) => {
      console.log(event.type);
    },
  },
);
 
await watch.connect();

The React package exposes useRstream and related helpers on top of the same watch model.

TURN credentials

The JS SDK supports both managed TURN issuance and local derivation.

Managed issuance through the control plane:

import { RstreamClient } from "@rstreamlabs/rstream";
 
const control = new RstreamClient({
  credentials: { token: process.env.RSTREAM_AUTHENTICATION_TOKEN! },
});
 
const turn =
  await control.tunnels.projects.createTurnCredentialsByEndpoint(
    "project-endpoint",
  );

Local derivation with application credentials:

import { createTURNCredentials } from "@rstreamlabs/tunnels";
 
const turn = await createTURNCredentials({
  credentials: {
    clientId: process.env.RSTREAM_CLIENT_ID!,
    clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
  },
  projectEndpoint: "project-endpoint",
  clusterDomain: "cluster.example.rstream.test",
});

See STUN and TURN for the full TURN model.

Environment variables

When values are not provided explicitly, the SDK reads:

RSTREAM_API_URL
RSTREAM_ENGINE
RSTREAM_AUTHENTICATION_TOKEN

For backend integrations based on application credentials, prefer passing clientId and clientSecret explicitly rather than relying on ambient process state.

Examples

The repository includes control-plane examples through @rstreamlabs/rstream, tunnels engine and data-plane examples through @rstreamlabs/tunnels, TURN helpers, fine-grained token helpers, and React hooks and components through @rstreamlabs/react.

C++ SDK Editions & Plans