@open-stream/client

TypeScript client for OpenStream — send and tail end-to-end encrypted events. Zero runtime dependencies; works in Node 18+ and browsers (fetch + WebCrypto).

npm install @open-stream/client

Send

import { OpenStreamClient, generateKey } from "@open-stream/client";

const client = new OpenStreamClient("https://your-openstream-host");

const { streamId, ingestToken, viewerUrl } = await client.createStream();
const key = generateKey(); // base64url, 32 bytes — share out-of-band, never with the server

const producer = client.producer(streamId, ingestToken, { key });
await producer.send({ kind: "deploy", status: "canary healthy" }); // objects → JSON
await producer.send("plain string");                               // strings as-is
await producer.send(new Uint8Array([1, 2, 3]));                    // raw bytes

// watch in a browser (the fragment never reaches the server):
console.log(`${viewerUrl}#k=${key}`);

Every payload is sealed with AES-256-GCM before the request is made. Omit key to send plaintext.

Pull

const consumer = client.consumer(streamId, { key });

// one-shot pull, oldest first
const events = await consumer.pull({ since: 0, limit: 500 });
events[0].json(); // { kind: "deploy", status: "canary healthy" }

// live tail over SSE — replays from `since`, reconnects on drops,
// ends when the stream is deleted or the signal aborts
const controller = new AbortController();
for await (const event of consumer.tail({ since: 0, signal: controller.signal })) {
  console.log(event.seq, event.ts, event.text());
}

Each event is { seq, ts, data, sealed, text(), json() }. With the right key, data holds the decrypted bytes and sealed is false. Without a key, sealed events pass through as ciphertext with sealed: true. A wrong key throws DecryptError — real failures are never papered over.

Also on the client: client.stats(streamId) and client.deleteStream(streamId, ingestToken).

Develop

npm install
npm test        # unit tests always; integration runs when a server is up
npm run build   # dist/ (ESM + CJS + d.ts)

Integration tests target http://localhost:4000 (override with OPEN_STREAM_URL) and skip when no server is reachable.