Client

@der-ablauf/client is a lightweight browser client for consuming Ablauf workflows from your frontend. It provides type-safe access to the dashboard API and real-time WebSocket subscriptions.

Installation

npm install @der-ablauf/client

The client connects to the oRPC endpoint exposed by your worker. Make sure you've set up the dashboard API first.

Creating the Client

import { createAblaufClient } from '@der-ablauf/client';

const client = createAblaufClient({
	url: 'https://your-worker.example.com/__ablauf/rpc',
});

Configuration Options

Option	Type	Description
`url`	`string`	Base URL for the oRPC endpoint
`wsUrl`	`string`	Base URL for WebSocket connections (defaults to `url` with protocol swapped to ws)
`withCredentials`	`boolean`	Include cookies in requests (for auth)
`headers`	`Record<string, string>`	Custom headers to send with every request

// With authentication
const client = createAblaufClient({
	url: 'https://your-worker.example.com/__ablauf/rpc',
	withCredentials: true,
	headers: {
		Authorization: 'Bearer your-token',
	},
});

Listing Workflows

Query workflow instances with filtering:

// List all workflow instances
const { items } = await client.workflows.list({});

// Filter by type and status
const { items } = await client.workflows.list({
	type: 'process-order',
	status: 'running',
});

Getting Workflow Status

Fetch details for a specific workflow:

const workflow = await client.workflows.get({ id: 'order-123' });
// workflow.status, workflow.payload, workflow.result, etc.

Execution Timeline

Get the step-by-step execution timeline:

const timeline = await client.workflows.timeline({ id: 'order-123' });
// Array of step executions with timing, retries, and results

Real-Time Subscriptions

Subscribe to live updates from a running workflow using WebSockets:

import type { InferSSEUpdates } from '@der-ablauf/client';
import type { OrderWorkflow } from './workflows/order';

// Type-safe WebSocket subscription
const stream = client.subscribe<typeof OrderWorkflow>('order-123');

for await (const update of stream) {
	switch (update.event) {
		case 'progress':
			console.log('Progress:', update.data);
			break;
		case 'status':
			console.log('Status changed:', update.data);
			break;
	}
}

With AbortController

Cancel subscriptions when they're no longer needed:

const controller = new AbortController();

const stream = client.subscribe<typeof OrderWorkflow>('order-123', {
	signal: controller.signal,
});

// Later...
controller.abort();

Type Inference

Use InferSSEUpdates to extract the update event types from a workflow class:

import type { InferSSEUpdates } from '@der-ablauf/client';
import type { OrderWorkflow } from './workflows/order';

type OrderUpdates = InferSSEUpdates<typeof OrderWorkflow>;
// { event: "progress"; data: { percent: number } } | { event: "shipped"; data: { trackingId: string } }

React Example

Here's how you might use the client in a React component:

import { useEffect, useState } from 'react';
import { createAblaufClient } from '@der-ablauf/client';

const client = createAblaufClient({
	url: '/__ablauf/rpc',
});

function WorkflowStatus({ id }: { id: string }) {
	const [status, setStatus] = useState<string>('loading');

	useEffect(() => {
		const controller = new AbortController();

		async function subscribe() {
			const stream = client.subscribe(id, {
				signal: controller.signal,
			});

			for await (const update of stream) {
				if (update.event === 'status') {
					setStatus(update.data);
				}
			}
		}

		subscribe().catch(() => {});
		return () => controller.abort();
	}, [id]);

	return <div>Status: {status}</div>;
}

For a full-featured monitoring UI, check out the Dashboard — a ready-made React app for workflow observability.

Client

On this page