Browser SDK API (@arcflow/static)
Package path: packages/arcflow-static. Production browser client for published workflows via Relay, direct server (dev only), or BFF.
Installation
Build from monorepo:
ArcFlowClient
Primary entry point.
Constructor options
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl | string | required | Relay host or server URL (no trailing slash) |
apiKey | string | required | Site token (relay) or server key (direct) |
mode | "relay" | "direct" | "bff" | "relay" | Routing mode |
siteId | string | parsed from URL | Required for relay if not in baseUrl path |
useArcFlowHeader | boolean | true for direct | Use X-ArcFlow-Api-Key vs Bearer |
runPublished
Resolve semver range from registry and execute:
Sends:
Polls until Completed or throws on Failed / Interrupted.
runWorkflow
Inline workflow (dev or allow_inline: true sites only):
Production sites should set allow_inline: false so browsers cannot override published definitions.
getRun / pollUntilComplete
Registry helpers
Registry calls require direct server URL with server API key (operator/backend scripts, not browser).
Client modes
| mode | Use | Security |
|---|---|---|
relay | Production | Site token + Origin via Relay |
direct | Local dev only | Never ship server API key in production bundles |
bff | Your backend holds keys | Static SDK treats as relay to your BFF URL |
StepForm
Structured multi-turn input for workflows reading initial_state.conversation_turns:
Errors
| Class | When |
|---|---|
StaticConfigurationError | Invalid client options |
StaticExecutionError | Run failed or HTTP error |
WorkflowInterruptedError | HITL pause; includes runId, approvalKey |
Streaming note (streaming deferred)
There is no SSE client in the static SDK for server events. For token-progress UI, poll trace via Relay and read TokenEmitted metadata. See guides/streaming/streaming-in-the-browser.md.
Exports
Agent, Workflow, Tool, MemoryConfig, HitlConfig, buildExecConfig, parseRunStatus, graph helpers, and error types are re-exported from packages/arcflow-static/src/index.ts.