npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@blindsignal/sdk

v0.1.1

Published

Browser SDK for BlindSignal: authenticated signaling for WebRTC DataChannels.

Readme

@blindsignal/sdk

The browser client for BlindSignal: it authenticates with a token from the application backend, joins namespaces, discovers devices, and opens one WebRTC DataChannel per session. Application payloads travel only over the DataChannel, never through the signaling server.

The package ships ESM and leaves bundling to the application (ADR 0001). It imports only @blindsignal/protocol and web-standard globals (ADR 0002). examples/browser-demo runs it in a page, and its Playwright tests cover Chromium, Firefox, and WebKit. examples/minimal-app is the shortest complete use: a page whose backend issues bound tokens and grants pairings.

Installation

npm install @blindsignal/sdk

The package ships JavaScript and types in dist/, and depends on @blindsignal/protocol of the same version. Releases follow semantic versioning (docs/adr/0043-semantic-versioning.md), and packages/sdk/CHANGELOG.md in the repository describes each.

In this workspace, a package depends on it as the examples do, and its exports point at the TypeScript sources, which the examples serve to the browser as they are:

{ "dependencies": { "@blindsignal/sdk": "workspace:*" } }

Browser support

Chrome and Edge 119, Firefox 121, and Safari 17.4, and later, on desktop and iOS (docs/adr/0047-supported-browsers.md). The SDK needs WebRTC DataChannels, WebCrypto ECDSA P-256, and Promise.withResolvers; DeviceKey.load() needs IndexedDB and a secure context. CI runs Chromium, Firefox, and WebKit; in WebKit only through a TURN relay, so direct connections in Safari and every iOS browser are untested.

Usage

import { BlindSignalClient, BlindSignalError } from "@blindsignal/sdk";

const client = new BlindSignalClient({
  serverUrl: "wss://signal.example.com",
  // Called for every authentication and refresh: tokens are single-use.
  accessTokenProvider: () => fetch("/blindsignal-token").then((response) => response.text()),
  iceServers: [{ urls: ["stun:stun.example.com:3478"] }],
});

client.on("state", ({ state, error }) => console.log(state, error));
client.on("presence", ({ userId, deviceId, present }) => console.log(userId, deviceId, present));
client.on("sessionRequest", (request) => {
  // The application decides; an unanswered request times out.
  void request.accept().then((session) => session.on("data", console.log));
});

try {
  await client.connect();
} catch (error) {
  // The client stopped: a terminal error, or close() before it connected.
  if (error instanceof BlindSignalError) console.log(error.code);
  throw error;
}
await client.join("notes:workspace");
const [device] = await client.discover("notes:workspace");
if (device) {
  const session = await client.createSession({ namespace: "notes:workspace", ...device });
  session.on("open", () => session.send("hello"));
}

BlindSignalClient

new BlindSignalClient(options) takes BlindSignalClientOptions:

| Option | Default | Meaning | |---|---|---| | serverUrl | required | wss://, or ws:// on localhost, 127.0.0.1, or [::1]; no userinfo, query, or fragment. | | accessTokenProvider | required | Returns a new token from the application backend. | | deviceKey | none | A DeviceKey: proves possession on every authentication, for tokens bound with cnf.jkt (ADR 0041). | | iceServers | [] | STUN servers only, without username or credential; TURN comes from the server's rtc.ice_config. Copied when the client is built. | | iceTransportPolicy | all | relay uses TURN candidates only, hiding this device's addresses from its peers. | | refreshMarginMs | 60000 | How long before expiry auth.refresh is sent. | | backoff | { baseMs: 1000, maxMs: 30000 } | BackoffOptions: reconnect and refresh retry delays, with full jitter. | | backoffResetMs | 30000 | Time connected after which the reconnect count resets. | | heartbeat | { intervalMs: 25000, timeoutMs: 10000 } | HeartbeatOptions: connection.ping interval and pong timeout. | | maxIceRestarts | 3 | ICE restarts in a row before a failed connection closes. | | connectTimeoutMs | 30000 | Time to connect after each offer/answer exchange before the connection counts as failed (ADR 0018). | | createSocket, createPeerConnection | browser globals | Replaced in tests; see Testing. |

| Member | Meaning | |---|---| | connect() | Connects, retrying with backoff; resolves to an Identity, { userId, deviceId }, once authenticated, and rejects with a BlindSignalError when the client stops. | | join(namespace), leave(namespace) | Presence in a namespace; joined namespaces are joined again after a reconnect. | | discover(namespace) | The other devices present in a joined namespace: each a Device, { userId, deviceId }. A namespace too large for one message lists only the devices that fit; presence events report every change. | | createSession({ namespace, userId, deviceId }) | A requester's Session, pending until the target accepts. | | requestPairing(namespace) | Asks this user's devices in namespace to approve this one; see Pairing. | | refresh() | Sends auth.refresh now with a new token, for when the backend changed what the token grants; rejects with a BlindSignalError and keeps the current token. Refreshes before expiry need no call. | | close() | Closes the connection and stops reconnecting; open DataChannels stay until their sessions close. | | state | A ConnectionState: disconnected, connecting, or connected. |

ClientEvents maps each event to its payload:

| Event | Payload | |---|---| | state | { state, error? }; error is the code that stopped the client. | | presence | A Presence: { namespace, userId, deviceId, present }. | | rejoinFailed | { namespace, error }: a namespace not joined again after a reconnect. | | sessionRequest | A SessionRequest: the peer's namespace, userId, and deviceId, sessionId, accept(), which resolves to the target's Session, and reject(). | | pairingRequest | A PairingRequest: pairingId, the new device's namespace, userId, deviceId, and jkt, approve(), and reject(). | | pairingEnded | { pairingId, reason }: a pairing request ended without this device's answer: answered, timeout, requester_gone, namespace_unauthorized, or a reason a later server adds. |

on(event, listener) returns the function that removes the listener.

DeviceKey

A token bound to a device key with cnf.jkt works only for the device holding that key (docs/token-issuance.md#proof-of-possession). DeviceKey.load() returns this origin's P-256 key, generated non-extractable on first use and kept in IndexedDB; a reload, or another tab, gets the same one.

import { BlindSignalClient, DeviceKey } from "@blindsignal/sdk";

const deviceKey = await DeviceKey.load();
// The backend records the thumbprint for this device and puts it in each token's cnf.jkt.
const client = new BlindSignalClient({
  serverUrl: "wss://signal.example.com",
  accessTokenProvider: () =>
    fetch(`/blindsignal-token?jkt=${deviceKey.thumbprint}`).then((response) => response.text()),
  deviceKey,
});

With deviceKey, the client waits for the server's auth.challenge, up to heartbeat.timeoutMs, and signs a proof for each token. Clearing the site's data loses the key: the backend then binds the new one. DeviceKey.from(keyPair) wraps a non-extractable P-256 ECDSA pair kept elsewhere, and throws a TypeError for any other.

| Member | Meaning | |---|---| | thumbprint | The key's JWK thumbprint (RFC 7638), base64url: the value of cnf.jkt. | | approval(device) | Signs a pairing approval for an ApprovedDevice, { pairingId, namespace, userId, deviceId, jkt }; PairingRequest.approve() calls it. |

Pairing

A device the user adds asks the user's devices already in a namespace to approve it, then takes the approval to the backend, which issues it tokens with the namespace (docs/adr/0042-pairing.md, docs/token-issuance.md#pairing). Both sides need a deviceKey and tokens bound to it; the new device's token lists the namespace in pairing.

// The new device; requestPairing() without a deviceKey rejects with a TypeError.
const result = await client.requestPairing("notes:workspace");
if (result.status === "approved") {
  await fetch("/pairings", { method: "POST", body: result.approval });
  // The next token lists the namespace.
  await client.refresh();
  await client.join("notes:workspace");
}

// A device already in the namespace, joined there.
client.on("pairingRequest", (request) => {
  // The application asks its user; approve() signs the approval with the device key.
  void request.approve();
});

requestPairing resolves to a PairingResult: { status: "approved", approval }, { status: "rejected" }, or { status: "timeout" }. It rejects with a BlindSignalError: peer_unavailable when no device can be asked, not_authorized, also when a refresh drops the namespace from the token's pairing claim before an answer, rate_limited, or connection_closed when the connection drops before an answer. The approval is a JWT valid for 5 minutes.

Session

| Member | Meaning | |---|---| | id, peer, role | The session ID, the peer, a Peer: { namespace, userId, deviceId }, and requester or target. | | state | A SessionState: pending, active, or ended: the server-side session. | | connectionType | A ConnectionType: direct, relay, or unknown, from the selected ICE candidate pair. | | send(data) | ChannelData: a string, ArrayBuffer, or typed array; throws InvalidStateError until open. | | close() | Ends the session and closes its DataChannel. |

SessionEvents maps each event to its payload:

| Event | Payload | |---|---| | accepted | The target accepted (requester only). | | open | The DataChannel opened. | | data | A string or an ArrayBuffer. | | connectionType | The type, read each time the connection connects. | | ended | { reason }: signaling for the session ended. | | close | The DataChannel closed, or the connection failed for good. |

The ended reason is a SessionEndReason:

  • a TerminationReason the server sent, listed in terminationReasons: closed_by_peer, peer_disconnected, peer_revoked, timeout, namespace_unauthorized, or a reason a later server adds;
  • rejected: the target rejected the request;
  • closed: this side called close();
  • disconnected: this client's own connection dropped.

A session that ends only because a signaling path dropped (peer_disconnected, or disconnected) keeps a DataChannel that is already open; every other end closes it. The full behavior is in docs/protocol.md §10.

Errors

Requests reject with BlindSignalError. Its code is an ErrorCode (docs/protocol.md §9), connection_closed, or protocol_error; retryAfterMs is set for rate_limited. errorClasses maps each ErrorCode to its ErrorClass: retryable, terminal, or superseded. A code missing from errorClasses comes from a later server and counts as retryable (ADR 0045). Retryable failures reconnect on their own. A terminal error stops the client and closes every DataChannel; a superseded one (another connection took the device) stops it until the application calls connect() again.

Testing

@blindsignal/sdk/testing exports FakePeerConnection and FakeDataChannel, driven by the test, to return from createPeerConnection, a PeerConnectionFactory, where no WebRTC stack exists, as in Node:

import { BlindSignalClient } from "@blindsignal/sdk";
import { FakePeerConnection } from "@blindsignal/sdk/testing";

const peers: FakePeerConnection[] = [];
const client = new BlindSignalClient({
  serverUrl: "ws://localhost:8080",
  accessTokenProvider: () => fetch("http://localhost:3000/token").then((response) => response.text()),
  createPeerConnection: (configuration) => {
    const peer = new FakePeerConnection(configuration);
    peers.push(peer);
    return peer as unknown as RTCPeerConnection;
  },
});

| FakePeerConnection member | Meaning | |---|---| | channels, candidates | The DataChannels created or received, and the remote candidates added. | | gather(candidate) | Gathers a local candidate, which the client relays; null ends gathering. | | remoteChannel() | The peer's DataChannel arrives, as on the target. | | state(state) | Sets connectionState and fires connectionstatechange. | | fail | Makes the next setRemoteDescription or addIceCandidate reject. | | stats | What getStats() resolves to, where connectionType reads the selected pair; undefined makes it reject. |

| FakeDataChannel member | Meaning | |---|---| | open() | Opens the channel. | | receive(data) | The peer sends data. | | sent | What the client sent. |

API stability

The public API is what @blindsignal/sdk and @blindsignal/sdk/testing export, versioned as ADR 0043 defines. Members tagged @internal, which the client calls on its own objects, are left out of the published types and of that contract (docs/adr/0046-sdk-public-api.md). This README names every export, and a test fails when one is missing (apps/server/src/sdk-readme.test.ts).