@procflow/sdk-web

Browser SDK that reports process/step events to a self-hosted Process Inspector hub.

Use an ingest (write) token only. Never put the viewer/read token in a frontend bundle.

import pi, { configure } from '@procflow/sdk-web';
import spec from './processes.json';

configure({
  hubUrl: 'http://127.0.0.1:3100',
  ingestToken: 'dev-ingest-token',
  spec,
  redact: ['password'],
  // propagateContinue: true (default) — patch fetch to inject continue headers
});

await pi.wrapProcess('checkout', input, async () => {
  await pi.wrapStep('validateForm', input, async () => input);
  // continue headers are added to fetch automatically while the run is active
  await fetch('http://127.0.0.1:3030/checkout', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(input),
  });
});

Continue propagation

With propagateContinue: true (default), any fetch during an active wrapProcess gets:

• x-process-inspector-run-id
• x-process-inspector-process-id
• x-process-inspector-continue-sig

Hub ingest calls are excluded. Disable with propagateContinue: false. Manual pi.continueHeaders() still works.

Process annotation (YAML or JSON)

The optional spec is used only for local process/step id warnings (not sent to the hub). Pass either format:

import pi, { configure, parseDocument } from '@procflow/sdk-web';
import jsonSpec from './processes.json';
import yamlSource from './processes.yaml?raw';

configure({ hubUrl, ingestToken, spec: jsonSpec });
configure({ hubUrl, ingestToken, spec: yamlSource });
configure({ hubUrl, ingestToken, spec: parseDocument(yamlSource) });

parseDocument accepts a ProcessDocument object, JSON text, or YAML text.

Payloads are redacted client-side before ingest. Reporting is fail-open: if the hub is down, your fn still runs; ingest errors are never thrown into app code.

See docs/security.md and docs/hub.md.