@procflow/sdk-js

JavaScript / TypeScript SDK for Process Inspector.

• Load YAML or JSON process documents (language-agnostic graph)
• Collect runs/steps at runtime
• Report events to the Process Inspector hub (POST /pi/ingest)
• Default singleton pi (axios-style) so you do not pass a collector through your app

Install

npm install @procflow/sdk-js

Quick start (singleton)

import pi, { configure } from '@procflow/sdk-js';

configure({
  // YAML or JSON path (or a parsed ProcessDocument)
  spec: './processes.yaml',
  // spec: './processes.json',
  ingestToken: process.env.PROCESS_INSPECTOR_INGEST_TOKEN!,
  hubUrl: 'http://127.0.0.1:3100',
  redact: ['password', 'token'],
  // propagateContinue: true (default) — inject continue headers on fetch/axios
});

With propagateContinue (default), outgoing fetch and default axios calls made inside wrapProcess automatically get continue headers for Nest/downstream join. Custom axios: installAxiosContinuePropagation(instance, () => getInspector().continueSecret).

Anywhere else in the app — no collector parameter:

import pi from '@procflow/sdk-js';

export async function createOrder(input: { customerId: string; amount: number }) {
  return pi.wrapProcess('createOrder', input, async () => {
    await pi.wrapStep('validate', input, async () => {
      if (!input.customerId) throw new Error('customerId is required');
      return input;
    });
    return pi.wrapStep('persistOrder', input, async () => ({
      orderId: `ord_${Date.now()}`,
    }));
  });
}

Singleton API

| Export | Description | | --- | --- | | configure(options) | Create/replace the default inspector | | pi / default | wrapProcess, wrapStep, continueRun, currentRunId, register, … | | getInspector() / getCollector() | Access the configured instance |

Spec load / export

| Export | Description | | --- | --- | | loadDocumentFromFile(path) | Load YAML or JSON from disk | | loadDocumentFromString(source) | Parse YAML or JSON text | | loadDocumentFromJsonString(source) | Parse JSON text only | | stringifyDocumentAsYaml(doc) | Export YAML | | stringifyDocumentAsJson(doc) | Export JSON |

Isolated instance

import { createInspector } from '@procflow/sdk-js';

const inspector = createInspector({
  spec: './processes.json',
  ingestToken: 'test-token',
  hubUrl: 'http://127.0.0.1:3100',
});

await inspector.collector.wrapProcess('createOrder', input, async () => {
  await inspector.collector.wrapStep('validate', input, async () => input);
});

Options

createInspector({
  spec: './processes.yaml', // or './processes.json' | ProcessDocument
  hubUrl: 'http://127.0.0.1:3100', // required
  ingestToken: '...',
  path: '/pi',
  title: 'My App',
  redact: ['password'],
});

Self-hosted security model: docs/security.md. Hub gateway: docs/hub.md.

Docs

• Plain Node guide
• Getting started
• Transport contract