SDKs · ArcFlow

ArcFlow SDK

The node authoring interface for ArcFlow — Surface's native workflow engine. Write custom nodes, register handlers, and compose Flows, Cycles, and One-Shots from typed building blocks.

SDK TypeScript Workflows ArcFlow

Overview

ArcFlow is Surface's built-in workflow engine. Workflows are directed acyclic graphs of nodes — each node receives the output of its upstream nodes, runs its execute function, and passes a StepResult downstream. The engine handles scheduling, retries, gate suspensions, and parallel branches.

All nodes live in surface/src/lib/arcflow/nodes/ and are registered in index.ts. Adding a new node means writing one file and adding one line to the registry map.

Node interface

NodeHandler

Every node exports a NodeHandler — an object with a kind string and an async execute function.

import type { NodeHandler, WorkflowNode, StepResult, RunContext } from '../types' export const myNode: NodeHandler = { kind: 'my-node', async execute( node: WorkflowNode, input: Record<string, unknown>, ctx: RunContext ): Promise<StepResult> { const cfg = node.config as { my_param?: string } // ... do work return { output: { result: 'value' } } }, }

RunContext

The ctx argument carries everything the node needs to do its work without hitting the database directly.

FieldTypeDescription
runIdstringID of the current workflow run
workflowIdstringID of the parent workflow
versionnumberWorkflow version number
triggeredBystringMember ID or system identifier that started the run
payloadRecord<string, unknown>Original trigger payload (webhook body, manual input, etc.)
secretsRecord<string, string>Tenant secrets map — use ctx.secrets['KEY'] instead of env vars
stepOutputsMap<string, Record<string, unknown>>Outputs of all previously completed steps, keyed by node ID
getStandingApprovals?functionReturns active standing approvals for gate nodes
scheduleWait?functionSuspends the run until a future ISO timestamp (used by wait node)

StepResult

Return an object with an output map and an optional error string. A non-empty error marks the step as failed and stops the run unless the workflow has error-handling edges.

// Success return { output: { id: '123', status: 'sent' } } // Failure (stops the run) return { output: {}, error: 'my-node: required field missing' }

Interpolation

Node config values are plain strings at rest. Before executing, call interpolate() from ./utils to resolve template tokens against the run context.

import { interpolate } from './utils' // In execute(): const url = interpolate(cfg.url ?? '', input, ctx.secrets, ctx.payload, ctx.stepOutputs)
TokenResolves from
{'{{key}}'}input — current step's merged upstream output
{'{{secret.NAME}}'}ctx.secrets — tenant secret store
{'{{payload.key}}'}ctx.payload — original trigger payload
{'{{steps.NODE_ID.field}}'}ctx.stepOutputs — a prior step's output field

Nested paths work: {'{{steps.step1.user.email}}'} traverses the output object. Unresolved tokens return an empty string — never throw.

Node catalog

All registered node kinds as of Oct 2026:

llm
Call ArcRouter with a model alias and prompt template
http
Outbound HTTP request with full method/header/body control
transform
Reshape data with a JavaScript expression
condition
Boolean branch — routes to true or false edge
switch
Multi-branch routing on a value match
gate
Human approval gate — suspends run until approved
email
Send transactional email via Resend
slack
Post message to Slack channel via webhook
discord
Post message or embeds to Discord webhook
ghl
GoHighLevel CRM operations (contacts, notes, pipeline)
notify
Internal Surface notification to a member
database
Read or write Supabase rows
postgres
Raw SQL query against the Surface database
graph-read
Query the neo4j Brain graph
schedule
Cron trigger entry point
wait
Suspend run until a future timestamp
parallel
Fan-out: run multiple branches concurrently
merge
Fan-in: wait for all parallel branches then combine outputs
foreach
Iterate a sub-workflow over an array
sub-workflow
Invoke another workflow as a step
qa-cycle
LLM quality check with retry until pass or max attempts
webhook-response
Emit a response body back to the triggering webhook caller
form
Collect structured input from a member mid-run
error
Explicit failure with a message — ends the run
note
No-op annotation node for documentation in the canvas

trigger and form are entry-point types — they are not executed as steps within a run.

Registration

Add a new node in two steps:

1. Create surface/src/lib/arcflow/nodes/my-node.ts exporting a NodeHandler.

2. Add it to index.ts:

import { myNode } from './my-node' const registry = new Map<NodeKind, NodeHandler>([ // ... existing entries ['my-node', myNode], ])

Also add 'my-node' to the NodeKind union in types.ts.

Worked example

A minimal node that calls an external webhook and returns the response status:

import type { NodeHandler, WorkflowNode, StepResult, RunContext } from '../types' import { interpolate } from './utils' /** * ping node - POST to a URL and return the HTTP status. * * Config: * url - target URL (interpolated, required) * payload - JSON body template (interpolated, optional) */ export const pingNode: NodeHandler = { kind: 'ping', async execute(node: WorkflowNode, input: Record<string, unknown>, ctx: RunContext): Promise<StepResult> { const cfg = node.config as { url?: string; payload?: string } const url = interpolate(cfg.url ?? '', input, ctx.secrets, ctx.payload, ctx.stepOutputs) if (!url) return { output: {}, error: 'ping node: url is required' } const body = cfg.payload ? interpolate(cfg.payload, input, ctx.secrets, ctx.payload, ctx.stepOutputs) : undefined try { const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: body ?? '{}', signal: AbortSignal.timeout(10_000), }) return { output: { status: res.status, ok: res.ok } } } catch (e) { return { output: {}, error: `ping node: ${String(e)}` } } }, }