Browser SDK

@promptjuggler/browser is the client for streaming: it opens the SSE connection, speaks the whole protocol — segments, resets, resume, staleness — and hands you one maintained text per run. Everything in the package is safe to ship to an end user’s browser; it authenticates with a thread-scoped credential and never sees your API key.

Installation

npm install @promptjuggler/browser

It runs in every modern browser (fetch + ReadableStream) and in Node.js 22+.

The credential flow

Your backend mints the credential with a server SDK and returns it verbatim; the browser hands it to getToken. That one function is the entire auth story:

Your backend (Node example)

import { PromptJuggler } from '@promptjuggler/sdk';

const pj = new PromptJuggler(process.env.PROMPTJUGGLER_API_KEY);

app.get('/api/stream-token', async (req, res) => {
  // Authenticate YOUR user first — the credential grants read access to the thread.
  res.json(await pj.createStreamToken(req.query.thread));
});

Browser

import { PromptJugglerStream } from '@promptjuggler/browser';

const stream = new PromptJugglerStream({
  // Called on connect and on every reconnect, so token expiry renews itself.
  getToken: async () => {
    const res = await fetch(`/api/stream-token?thread=${threadId}`);
    return res.json(); // { token, url } — createStreamToken's response, verbatim
  },
});

Events

const finished = new Set<string>();

stream.on('text', ({ runId, text }) => render(runId, text));
stream.on('data', ({ runId, data }) => renderCards(runId, data));
stream.on('done', ({ runId, gapped }) => {
  finished.add(runId);
  if (gapped) refetch(runId);
});
// gap can arrive even after a clean done — a late token proving the finished
// text incomplete — and no second done follows. Refetch settled runs it names.
stream.on('gap', ({ runId }) => {
  if (finished.has(runId)) refetch(runId);
});
stream.on('failure', ({ runId, message }) => showError(runId, message));
stream.connect();

Event	Payload highlights	When
`text`	`runId`, `text`, `gapped`	The run’s full text so far, maintained for you — subscribe to this to just render.
`data`	`runId`, `data`	The run’s emit-tool payloads so far, maintained — structured data beside the text.
`done` / `failure`	`runId`, `gapped` (+ `code`, `message`)	The run reached its terminal state.
`gap`	`runId`, `segment`	Part of this run’s text is missing (e.g. you joined mid-run).
`stale`	—	The server lost history; runs still streaming should be treated as gapped.
`token` / `reset`	raw protocol events	For append-style UIs that assemble text themselves.
`connected` / `disconnected`	—	Connection lifecycle.

The one flag that matters is gapped: when a terminal event carries gapped: true, the streamed text is (or may be) incomplete — fetch the run through your backend for the authoritative result. When it is false, the text you rendered is the full output and no fetch is needed — with one edge for raw-event consumers: a gap arriving after a clean done retroactively proves that text incomplete (as in the sample above). The React hook folds all of this into runs[runId].gapped, which is why it is the recommended surface. Reconnection is automatic — exponential backoff after failures, immediate when the server hands the connection off during a deploy — and resumes exactly where it left off. disconnect() stops everything.

Connecting after the run started

A new connection starts at the live tip of the thread, so the usual order is to connect first and trigger the run second. When your frontend only learns the thread from the run it triggered, set replay: true:

const stream = new PromptJugglerStream({ getToken, replay: true });

The first connection replays what the thread’s recent history still holds, so a run already under way streams from its first token. Runs that finished in that window replay too, each ending with its done or failure event, so handle only the runs you show.

React

import { usePromptJugglerStream } from '@promptjuggler/browser/react';

function Chat({ threadId }: { threadId: string }) {
  const { connected, runs } = usePromptJugglerStream(
    { getToken: () => fetch(`/api/stream-token?thread=${threadId}`).then(r => r.json()) },
    [threadId], // what identifies the subscription: change it, and the hook resubscribes
  );

  return Object.entries(runs).map(([runId, run]) => (
    <Message key={runId} text={run.text} pending={run.status === 'streaming'} />
  ));
}

runs[runId] is { text, data?, transcript?, channel, status: 'streaming' | 'done' | 'failed', gapped?, error? } — render text and you have a chatbot. Render transcript instead when the UI shows tool activity: it is the same run as an ordered sequence of prose, tool chips and emit payloads, in the same shape getPromptRun returns. The options object is read through a ref, so inline literals never cause reconnects; only the deps array does.

Angular

The same surface as signals, for Angular 17+:

import { Component, signal } from '@angular/core';
import { injectPromptJugglerStream } from '@promptjuggler/browser/angular';

@Component({
  selector: 'app-chat',
  template: `
    @for (run of stream.runs() | keyvalue; track run.key) {
      <p>{{ run.value.text }}</p>
    }
  `,
})
export class ChatComponent {
  readonly threadId = signal('0198…');

  readonly stream = injectPromptJugglerStream(() => {
    // Read the signal HERE, in the factory itself — that read is what the
    // adapter tracks. Inside getToken it would run too late to be seen.
    const thread = this.threadId();
    return {
      getToken: () => fetch(`/api/stream-token?thread=${thread}`).then((r) => r.json()),
    };
  });
}

stream.connected and stream.runs are signals holding the same shapes as the React hook. Reactivity follows Angular’s grain: any signal read during the factory call — here threadId, hoisted into a local — is tracked, and changing it drops the old subscription (and its runs) and connects a fresh one. Reads deferred into getToken happen after tracking ends, so hoist them as above. Call it in an injection context (a field initializer or constructor); the subscription disconnects when the component is destroyed. Signals-only, so it works in zoneless applications.

Workflows

Every prompt node of a workflow streams into the same connection, keyed by runId and tagged with its channel. Follow only the user-facing lanes with channels: ['support']. See the chatbot guide for the full end-to-end walkthrough.

Getting Started

Roadmap

Core Concepts

Workflow Nodes

Tools

Guides

Backend SDKs

API Reference

Browser SDK

Installation

The credential flow

Events

Connecting after the run started

React

Angular

Workflows

​Installation

​The credential flow

​Events

​Connecting after the run started

​React

​Angular

​Workflows

Installation

The credential flow

Events

Connecting after the run started

React

Angular

Workflows