js-bao-wss-client / WorkflowsAPI
Interface: WorkflowsAPI
Workflows API, available as client.workflows. Starts, monitors, and terminates server-side workflow runs, and manages the client-side apply lifecycle for workflows whose results are applied to a document by the client.
Deprecated
Call a server function instead: client.functions.invoke for a result, or client.functions.start for a long-running run (see the Server Functions guide).
Methods
claimApply()
claimApply(
options):Promise<ClaimApplyResult>
Claim a workflow result for client-side apply. Returns { claimed: true } if this client won the lock.
Parameters
options
Returns
Promise<ClaimApplyResult>
Deprecated
Call a server function instead: a function writes the document itself, so no client applies its result (see the Server Functions guide).
confirmApply()
confirmApply(
options):Promise<ConfirmApplyResult>
Confirm that a claimed workflow result has been applied to the document.
Parameters
options
Returns
Promise<ConfirmApplyResult>
Deprecated
Call a server function instead: a function writes the document itself, so no client applies its result (see the Server Functions guide).
define()
define<
O>(workflowKey,options):void
Define a workflow with its apply handler. Call once at app initialization so any client can handle apply.
The optional generic O types the apply handler's output. It is additive and defaults to today's untyped any, so existing callers are unaffected.
Type Parameters
O
O = unknown
Parameters
workflowKey
string
options
Returns
void
Deprecated
Call a server function instead: a function writes the document itself, so no client applies its result (see the Server Functions guide).
getPendingApplies()
getPendingApplies(
options):Promise<PendingApply[]>
Fetch pending workflow applies for a document.
Returns a concrete PendingApply[]. The server element carries no output, so there is no output generic here — the apply output is typed on define/onApply<O>, where it is actually delivered.
Parameters
options
contextDocId
string
Returns
Promise<PendingApply[]>
Deprecated
Call a server function instead: a function writes the document itself, so no client applies its result (see the Server Functions guide).
getStatus()
getStatus<
O>(options):Promise<WorkflowStatusResult<O>>
Get the status of a workflow run. If contextDocId is not provided, uses the user's root document.
status is one canonical WorkflowStatusValue, reconciled by the server across the run's execution state and its stored record — read it as-is. A status read never changes the run's recorded state, and once a run reports completed / failed / terminated it keeps reporting that.
One caveat while a run finishes: a run whose execution has just ended can briefly report running while the platform publishes its output, so that status and output never contradict each other. A non-terminal read is therefore not proof the run is still executing — keep polling (or use WorkflowsAPI.waitFor, which handles this) rather than treating it as an error. run.status on the same response carries the recorded terminal status throughout.
A run executed with runSync reports its persisted status here too, but without output — the runSync call itself already returned that.
The optional generic O types the result envelope's output. It is additive and defaults to today's untyped any, so existing callers are unaffected. The generated per-workflow <key>(client) factory supplies it from the workflow's outputSchema.
Type Parameters
O
O = unknown
Parameters
options
Returns
Promise<WorkflowStatusResult<O>>
Deprecated
Call a server function instead: start it with client.functions.start and read the run with client.functions.getStatus (see the Server Functions guide).
listRuns()
listRuns(
options?):Promise<ListWorkflowRunsResult>
List workflow runs for the current user
Parameters
options?
Returns
Promise<ListWorkflowRunsResult>
Deprecated
Call a server function instead: start it with client.functions.start and read each run with client.functions.getStatus (see the Server Functions guide).
listStepRuns()
listStepRuns(
options):Promise<ListWorkflowStepRunsResult>
List step runs for a specific workflow run. The run must have been started by the current user.
Parameters
options
Returns
Promise<ListWorkflowStepRunsResult>
Deprecated
Call a server function instead: start it with client.functions.start and read the run with client.functions.getStatus (see the Server Functions guide).
releaseApply()
releaseApply(
options):Promise<ReleaseApplyResult>
Release a claimed workflow apply so another client can retry. Called automatically on apply handler failure.
Parameters
options
Returns
Promise<ReleaseApplyResult>
Deprecated
Call a server function instead: a function writes the document itself, so no client applies its result (see the Server Functions guide).
runSync()
runSync<
I,O>(options):Promise<RunSyncWorkflowResult<O>>
Synchronously invoke a workflow and wait for the final result.
Only callable on workflows marked syncCallable: true in their server-side definition. Use this for low-latency, short-task workflows. Long-running workflows should keep using start() plus the WebSocket / polling lifecycle.
The promise resolves with the final envelope for every outcome, including engine failure and timeout — failure surfaces as status: "failed" (or "timeout" / "terminated"), not a thrown error. Network / transport errors still reject as usual.
The optional generics I (input) and O (output) type the payload and the result envelope. Both are additive and default to today's untyped Record<string, any> / any, so existing callers are unaffected. The generated per-workflow <key>(client) factory supplies them from the workflow's inputSchema/outputSchema.
Type Parameters
I
I = Record<string, any>
O
O = any
Parameters
options
Omit<RunSyncWorkflowOptions, "input"> & object
Returns
Promise<RunSyncWorkflowResult<O>>
Deprecated
Call a server function instead: client.functions.invoke (see the Server Functions guide).
start()
start<
I>(options):Promise<StartWorkflowResult>
Start a workflow and return the run information.
The optional generic I types the input payload. It is additive and defaults to today's untyped Record<string, any>, so existing callers that pass no type argument are unaffected. The generated per-workflow <key>(client) factory (primitive workflows codegen) supplies it from the workflow's inputSchema.
Type Parameters
I
I = Record<string, any>
Parameters
options
Omit<StartWorkflowOptions, "input"> & object
Returns
Promise<StartWorkflowResult>
Deprecated
Call a server function instead: client.functions.start (see the Server Functions guide).
terminate()
terminate<
O>(options):Promise<WorkflowStatusResult<O>>
Terminate a running workflow. If contextDocId is not provided, uses the user's root document.
The optional generic O types the result envelope's output — a terminated run can still carry partial output. Additive, defaults to any. The generated per-workflow factory emits a terminate member that binds this generic to the workflow's <Key>Output.
Type Parameters
O
O = unknown
Parameters
options
Returns
Promise<WorkflowStatusResult<O>>
Deprecated
Call a server function instead: stop its run with client.functions.terminate (see the Server Functions guide).
waitFor()
waitFor(
runId,options?):Promise<WaitForWorkflowResult>
Wait for an async workflow run to reach a terminal state, then resolve { status, output?, error? }.
Event-driven: it subscribes to the existing workflowStatus WebSocket frame and issues no polling. One reconcile fetch runs immediately after subscribing to close the started-before-subscribed race (the terminal frame is only delivered to live connections and is not replayed). On a WS reconnect it re-runs that single reconcile fetch — still no interval timer.
Resolves on every terminal state, including workflow failure (status: "failed") — a failing run does NOT reject. Terminality is decided by the status the server reports: completed, failed, terminated, apply_pending, or apply_claimed. The server reconciles that status before returning it, so the reported terminal state is the run's real one (a terminated run resolves as "terminated", never "completed").
If a reconcile lands while a run is finishing — the server reports the execution's status until the platform has published the run's output, while the run record already carries its terminal status — waitFor re-checks on a one-second timer until the status endpoint agrees, so a caller that missed the terminal frame settles in seconds rather than waiting out timeoutMs.
Rejects on three conditions: the reconcile fetch 404s (unknown or not-owned runId → NOT_FOUND), the run reports missing (its record no longer resolves to an execution, so it will never reach a terminal state → NOT_FOUND), or timeoutMs elapses (WORKFLOW_WAIT_TIMEOUT). Every path removes the listener and clears the timers, so there is no leak.
Parameters
runId
string
options?
Returns
Promise<WaitForWorkflowResult>
Deprecated
Call a server function instead: start it with client.functions.start and wait with client.functions.waitFor (see the Server Functions guide).