Workflow SDK

Installation

npm install @altbase/workflows

The package exports the AltBaseWorkflows client class and all associated TypeScript types.

Creating a Client

import { AltBaseWorkflows } from '@altbase/workflows'

const workflows = new AltBaseWorkflows({
  baseUrl: 'https://your-project.atlasdb.io',
  apiKey: 'your-service-key',
})

Option	Required	Description
baseUrl	Yes	Base URL of your AltBase API
apiKey	Yes	API key (service role recommended)
fetch	No	Custom fetch implementation for SSR or testing

All requests hit the /workflows/v1 path prefix with Content-Type: application/json and the apikey header.

Workflow Definitions

A definition describes the automation graph: nodes (steps), edges (connections), trigger type, and metadata.

Create a Workflow

const definition = await workflows.createWorkflow({
  name: 'Onboarding Sequence',
  description: 'Send welcome emails and provision resources',
  trigger_type: 'record',
  definition: {
    version: 1,
    nodes: [
      {
        id: 'send-welcome',
        type: 'email',
        config: { template: 'welcome', to: '{{trigger.email}}' },
        timeout_seconds: 30,
      },
      {
        id: 'provision-account',
        type: 'http',
        config: { url: 'https://api.internal/provision', method: 'POST' },
        retry: {
          max_retries: 3,
          backoff: 'exponential',
          initial_delay_ms: 1000,
          max_delay_ms: 30000,
        },
      },
    ],
    edges: [
      { id: 'e1', source: 'send-welcome', target: 'provision-account' },
    ],
  },
})

Trigger Types

Type	Description
record	Fires on database INSERT, UPDATE, or DELETE
schedule	Fires on a cron schedule
webhook	Fires when a webhook URL receives a POST
manual	Fires only when explicitly started via the API
integration	Fires from an integration event

List and Get

const all = await workflows.listWorkflows()
const active = await workflows.listWorkflows('active')
const wf = await workflows.getWorkflow('wf_abc123')

Update

await workflows.updateWorkflow('wf_abc123', {
  name: 'Updated Onboarding',
  definition: { /* new DSL graph */ },
})

Activate and Pause

await workflows.activateWorkflow('wf_abc123')
await workflows.pauseWorkflow('wf_abc123')

A workflow must be active before it can accept new runs. Status lifecycle: draft -> active -> paused -> active (or archived).

Delete

await workflows.deleteWorkflow('wf_abc123')
// { deleted: true }

Workflow Runs

A run is a single execution of a workflow definition.

Start a Run

const run = await workflows.startRun({
  workflow_id: 'wf_abc123',
  trigger_data: { email: 'user@example.com', plan: 'pro' },
})
console.log(run.id, run.status) // "pending"

Get Run Status

const run = await workflows.getRun('run_xyz789')
// run.status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
// run.current_nodes: ['provision-account']
// run.error: { node_id, message } | null

List Runs and Inspect Steps

const allRuns = await workflows.listRuns()
const wfRuns = await workflows.listRuns('wf_abc123')

const steps = await workflows.getStepRuns('run_xyz789')
// Each step has: node_id, status, input, output, duration_ms, retry_count
// Step statuses: pending, running, completed, failed, skipped, waiting

Cancel a Run

await workflows.cancelRun('run_xyz789')

Cancellation marks all pending steps as skipped and sets the run to cancelled.

Live Run Streaming (SSE)

Monitor a run in real time via Server-Sent Events. watchRun returns an AsyncGenerator:

for await (const event of workflows.watchRun('run_xyz789')) {
  switch (event.type) {
    case 'step_status':
      console.log(`Step ${event.node_id}: ${event.status}`)
      if (event.output) console.log('Output:', event.output)
      break

    case 'approval_required':
      console.log(`Approval needed: ${event.approval_id}`)
      console.log(`Assignee: ${event.assignee}`)
      break

    case 'run_completed':
      console.log(`Done: ${event.status} (${event.total_duration_ms}ms)`)
      break
  }
}

The generator exits automatically on run_completed.

Event Types

Event	Key Fields
step_status	node_id, status, output?, error?, duration_ms?
approval_required	node_id, approval_id, assignee, message
run_completed	status, total_duration_ms

Approvals

Workflow graphs can include approval nodes that pause execution until a human responds.

List Pending Approvals

const pending = await workflows.listPendingApprovals()
for (const a of pending) {
  console.log(a.id, a.node_id, a.assignee_role, a.timeout_at)
}

Respond to an Approval

await workflows.respondApproval('apr_def456', true, 'Looks good')
// { ok: true, approval_id: 'apr_def456', status: 'approved' }

await workflows.respondApproval('apr_ghi789', false, 'Needs revision')
// status: 'rejected'

Rejected approvals follow the node's on_error setting (stop by default).

Node Configuration

Each node has id, type, config, optional retry (with max_retries, backoff, initial_delay_ms, max_delay_ms), on_error (stop or continue), timeout_seconds, and position (for the visual builder).

Built-in Step Types

record, http, integration, approval, email, notification, loop, parallel, switch, delay, error_handler, function_call, code_snippet, subworkflow.

Error Handling

All methods throw AltBaseWorkflowError on non-2xx responses:

import { AltBaseWorkflowError } from '@altbase/workflows'

try {
  await workflows.startRun({ workflow_id: 'invalid' })
} catch (err) {
  if (err instanceof AltBaseWorkflowError) {
    console.error(err.status, err.message)
  }
}