Workflow Builder

Associate triggers with graphs and validate schema compatibility with @swirls/sdk/workflow.

Build Swirls workflows in code: associate triggers (forms, webhooks, schedules, agents) with a graph. Validate trigger–graph schema compatibility, serialize for storage, and export Mermaid diagrams showing how triggers flow into the graph.

Installation

bun add @swirls/sdk
# or
npm install @swirls/sdk

Quick start

import { Swirls } from '@swirls/sdk/client'
import { GraphBuilder } from '@swirls/sdk/graph'
import { WorkflowBuilder } from '@swirls/sdk/workflow'

const swirls = new Swirls({ apiKey: process.env.SWIRLS_API_KEY! })

const graph = new GraphBuilder({ client: swirls.client })
  .setName('process_form')
  .setLabel('Process Form')
  .addNode('entry', {
    type: 'code',
    label: 'Entry',
    config: { type: 'code', code: 'return context.nodes' },
    inputSchema: {
      type: 'object',
      required: ['name', 'email'],
      properties: {
        name: { type: 'string' },
        email: { type: 'string' },
      },
      additionalProperties: false,
    },
  })

const workflow = new WorkflowBuilder({ client: swirls.client, graph })
  .addTrigger({
    resourceType: 'form',
    resourceId: 'your-form-id',
    enabled: true,
    sourceSchema: {
      type: 'object',
      required: ['name', 'email'],
      properties: {
        name: { type: 'string' },
        email: { type: 'string' },
      },
      additionalProperties: false,
    },
  })

workflow.validate()
await workflow.save({ projectId: 'your-project-id' })

API reference

WorkflowBuilder

Method	Description
`constructor(options: { graph: GraphBuilder; client?: SwirlsClient })`	New builder. Graph is required. Pass `client` to enable `save()`. Use `SwirlsClient` from `@swirls/sdk/client`.
`setGraph(graph)`	Replace the graph. Returns `this`.
`addTrigger(options)`	Add a trigger. Options: `resourceType`, `resourceId`, `enabled?`, `sourceSchema?` (for form/webhook validation). Returns `this`.
`removeTrigger(resourceType, resourceId)`	Remove a trigger. Returns `this`.
`get graph`	The `GraphBuilder`.
`get graphId`	The graph id.
`get triggerList`	Array of trigger refs.
`validate()`	Throws `WorkflowValidationError` if no graph, graph invalid, no single root, or trigger schema incompatible with root `inputSchema`.
`save({ projectId, folderId? })`	Persist graph (if builder) then create/update/delete triggers to match. Requires `client`.
`toJSON()`	Serialize to a plain object.
`toMermaid()`	Return a Mermaid flowchart string (triggers → graph).
`static fromJSON(json)`	Deserialize from object or JSON string.
`static fromAPI(client, graphId)`	Load workflow from the API by graph id.

WorkflowValidationError

Thrown by validate() or addTrigger() when the workflow or input is invalid.

message: Human-readable message.
code: One of SCHEMA_INCOMPATIBLE, MISSING_ROOT_NODE, MULTIPLE_ROOT_NODES, DUPLICATE_TRIGGER, INVALID_RESOURCE, NO_GRAPH, UNKNOWN.
details: Optional object (e.g. resourceType, resourceId, index).

Schema compatibility

For form and webhook triggers, the trigger’s source schema (form schema or webhook schema) must be compatible with the graph’s root node inputSchema. Compatibility means: any data valid against the source schema is also valid against the root’s input schema.

Pass sourceSchema in addTrigger() when you have it so validate() can check locally.
Schedule and agent triggers have no payload schema and are always considered compatible.

Serialization and Mermaid

toJSON() produces { graph: SerializedGraph, triggers: SerializedTriggerRef[] }.

fromJSON() restores a WorkflowBuilder from a full serialized workflow (graph with nodes and edges).

toMermaid() returns a flowchart with one node per trigger and one node for the graph, with edges from each trigger to the graph.

Learn more

Graph Builder – Define nodes and edges.
Swirls Documentation

Workflow Builder

On this page