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('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.
`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.

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, channel, status: 'streaming' | 'done' | 'failed', gapped?, error? } — render text and you have a chatbot. 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

Core Concepts

Workflow Nodes

Tools

Guides

SDKs

API Reference

Installation

The credential flow

Events

React

Angular

Workflows

​Installation

​The credential flow

​Events

​React

​Angular

​Workflows

Installation

The credential flow

Events

React

Angular

Workflows