TypeScript Client

The @stepflowjs/client package is the core SDK for interacting with Stepflow APIs. It works in any JavaScript environment, including browsers, Node.js, and Edge functions.

Installation

pnpm add @stepflowjs/client

Initialization

Initialize the client with your Stepflow API base URL and authentication keys.

import { StepflowClient } from "@stepflowjs/client";

const client = new StepflowClient({
  baseUrl: "https://api.your-app.com/stepflow",
  publicApiKey: "sf_pub_...", // For client-side
  // apiKey: "sf_...",        // For server-side
});

Core Methods

`trigger`

Trigger a new workflow execution.

const { runId, publicAccessToken } = await client.trigger("welcome-user", {
  email: "user@example.com",
  name: "Jane Doe",
});

`getRun`

Retrieve the current state of a workflow run.

const run = await client.getRun(runId, {
  accessToken: publicAccessToken, // Optional if using apiKey
});

console.log(run.status); // "running", "completed", etc.
console.log(run.steps); // Array of step executions

`subscribeToRun`

Subscribe to real-time updates for a run using SSE or WebSockets.

const unsubscribe = client.subscribeToRun(runId, {
  accessToken: publicAccessToken,
  onUpdate: (run) => {
    console.log("Run updated:", run.status);
  },
  onStepComplete: (step) => {
    console.log("Step finished:", step.name);
  },
  onComplete: (result) => {
    console.log("Workflow finished with result:", result);
  },
  onError: (error) => {
    console.error("Workflow failed:", error);
  },
});

// Later...
unsubscribe();

`stream`

Trigger and stream events in a single call using an Async Generator.

const stream = client.stream("generate-report", { reportId: "123" });

for await (const event of stream) {
  if (event.type === "step:complete") {
    console.log(`Step ${event.stepName} completed`);
  }
  if (event.type === "execution:complete") {
    console.log("Done!", event.data);
  }
}

Token Management

The TokenManager helps manage public access tokens, storing them and handling automatic refreshes.

import { TokenManager, LocalStorageTokenStorage } from "@stepflowjs/client";

const tokenManager = new TokenManager({
  storage: new LocalStorageTokenStorage(),
  onTokenRefresh: (runId, newToken) => {
    console.log(`Token refreshed for ${runId}`);
  },
});

// Store a token
await tokenManager.storeToken(runId, token, expiresAt);

// Get a valid token
const token = await tokenManager.getToken(runId);

Real-time Connection

The RealtimeConnection class handles the SSE/WebSocket fallback strategy.

import { RealtimeConnection } from "@stepflowjs/client";

const connection = new RealtimeConnection({
  strategy: "auto", // "sse" | "websocket" | "auto"
  sseUrl: "https://api.your-app.com/runs/123/stream",
  onMessage: (event) => {
    console.log("Received event:", event);
  },
});

await connection.connect();

TypeScript Client

On this page