Browser SDK

The browser SDK requests channel tokens, maintains the connection, and delivers channel events.

Installation#

Install @seuraa/edge from npm:

npm install @seuraa/edge

Client#

import { Client } from "@seuraa/edge";

const edge = new Client({
  appKey: "app-key",
  auth: "/api/edge/token",
});

Use edge.channel(name) to get a local handle for a channel:

const channel = edge.channel("public:updates");

This does not make a network request or create a remote resource. The channel connects when you call subscribe, onRawEvent, or connect.

Subscribe#

const off = channel.subscribe<{ message: string }>("update.created", (event) => {
  console.log(event.data.message);
});

subscribe joins the channel and registers a handler for one event name. The returned function removes that handler.

Publish#

const result = channel.publish("typing.started", {
  documentId: "document-123",
});

result contains the generated clientEventId and whether the event was sent immediately. The channel token must grant permission for the event name.

Use browser publishing for events your application treats as untrusted input. Publish authoritative business events from your backend.

Leave A Channel#

channel.unsubscribe();

This removes the channel subscription. The shared connection closes when no subscribed channels remain.

Observe Raw Channel Events#

Use onRawEvent when you need snapshots, presence updates, publish acknowledgements, or server errors in addition to application events:

const off = channel.onRawEvent((event) => {
  if (event.type === "presence.updated") {
    console.log(event.presence);
  }
});

For named application events, prefer subscribe.

Publish Acknowledgements#

Successful client publishes produce a publish.accepted event:

channel.onRawEvent((event) => {
  if (event.type === "publish.accepted") {
    console.log(event.clientEventId);
  }
});

Match clientEventId with the value returned by channel.publish(...) when you need to confirm that a publish was accepted.

Connection Status#

const off = channel.onStatus((event) => {
  console.log(event.status);
});

Status values are idle, connecting, open, retrying, closed, and error.

Debug Events#

Use onDebug to inspect client, server, and transport activity while diagnosing an integration:

const off = edge.onDebug((event) => {
  console.log(event.direction, event.type, event.detail);
});

Debug events are diagnostic and should not drive application behavior.

Reconnection And Replay#

The client reconnects automatically after an unexpected disconnection and restores its active channel subscriptions.

On plans with persisted replay, the client also sends the latest event cursor for each channel. Edge returns events missed while the client was disconnected when that cursor remains inside the configured replay window.

Applications using replay should handle events idempotently because reconnect recovery can deliver an event more than once.