js-bao-wss-client / FunctionsAPI
Interface: FunctionsAPI
Server functions, available as client.functions.
A function is TypeScript an app's team authored in its config tree and pushed with primitive config push. Invoking one runs it on the platform under the calling user's own authority and returns its result.
Methods
getStatus()
getStatus<
TOutput>(runId):Promise<FunctionRunStatus<TOutput>>
The current status of a function run, by run id.
The answer carries one structured error with the platform's code on it, and a run block with the run's own fields.
A run id that is not this app's, or does not exist, is NOT_FOUND "Function run <id> not found". Every other refusal — a 403 from the access gate, a 5xx — propagates as it arrived.
ONE READ, reporting what it read: the retry waitFor makes does not belong here, because a status read is a question about now. The thrown error carries details.reason for callers who need to tell the two not-founds apart — "instance-unseen" for a live run whose instance the platform cannot see yet, "no-run" for a run id that resolved to nothing.
Type Parameters
TOutput
TOutput = unknown
Parameters
runId
string
Returns
Promise<FunctionRunStatus<TOutput>>
invoke()
invoke<
TOutput,TInput>(functionKey,options?):Promise<FunctionInvokeResult<TOutput>>
Invoke a server function on the REQUEST runtime and wait for its result.
The caller picks the runtime, and the ROUTE is how it is said: this method posts to functions/{key}, which runs the function inside the request. Every pushed function takes this verb and start alike — the config says nothing about how a function runs — so there is no configuration to change and no mismatch to refuse. A function that must NOT run under one of the two tests for it in its own code with assertRuntime, and the platform settles that as status: "failed" with errorCode: "FUNCTION_RUNTIME_REFUSED".
input is sent as the request envelope's rootInput.
Type Parameters
TOutput
TOutput = unknown
TInput
TInput = unknown
Parameters
functionKey
string
options?
FunctionInvokeOptions<TInput> = {}
Returns
Promise<FunctionInvokeResult<TOutput>>
start()
start<
TInput>(functionKey,options?):Promise<FunctionStartResult>
Start a server function on the TASK runtime and get its run id back.
The mirror of invoke, and the route says which: this method posts to functions/{key}/start. Every pushed function takes both verbs.
Follow the run with getStatus or waitFor.
runKey makes the start idempotent per (caller, contextDocId, runKey): a repeat answers the run that already exists with existing: true, never a second run. There is no forceRerun on this route.
Type Parameters
TInput
TInput = unknown
Parameters
functionKey
string
options?
FunctionStartOptions<TInput> = {}
Returns
Promise<FunctionStartResult>
terminate()
terminate<
TOutput>(ref):Promise<FunctionRunStatus<TOutput>>
Terminate a running function run.
A run that does not exist, or whose execution cannot be found, is a NOT_FOUND. A live run the platform could not stop is an UNAVAILABLE carrying the platform's diagnostic verbatim: it is not a run that does not exist, and the diagnostic is what a caller can act on.
Type Parameters
TOutput
TOutput = unknown
Parameters
ref
Returns
Promise<FunctionRunStatus<TOutput>>
waitFor()
waitFor<
TOutput>(runId,options?):Promise<FunctionRunSettled<TOutput>>
Wait for a function run to reach a terminal state.
It polls: a function run sends no status events over the WebSocket.
The interval starts short and backs off, so a function that finishes in a second is not waited out and one that sleeps for an hour is not polled thousands of times.
SETTLES on exactly completed, failed and terminated, which is what FunctionRunSettled says its status is. A read reporting missing is a not-found — that run's execution can no longer be resolved and waiting for it to become terminal is waiting for nothing. A read reporting any other state, which a function run never has, names the status in an INVALID_ARGUMENT rather than waiting out the deadline.
A failed run RESOLVES with status: "failed" and its error; it does not throw. A transient error between polls is retried.
A NOT-FOUND IS RETRIED TOO, and how far depends on which one the platform reported. A run id start has just returned is safe to wait on: it is not reported missing while the run is starting or running.
- The run EXISTS, has not settled, and the platform cannot see its instance yet — which is what a run between its creation and its first execution looks like. Polled to your own
timeoutMs, which is the only bound a live run's wait should have. - The run id resolves to nothing. Real, and usually permanent, but not always: a poll issued a second after a start can be answered by a replica that has not caught up with it. Retried for three seconds from the start of the wait and no longer, so a mistyped run id still fails while you are watching.
Either way the wait ENDS in NOT_FOUND, with the same code and message the first refusal would have thrown; and a wait whose timeoutMs runs out while its last read was a not-found reports that NOT_FOUND rather than WORKFLOW_WAIT_TIMEOUT, which would hide it. A run that is merely slow still raises the timeout.
Type Parameters
TOutput
TOutput = unknown
Parameters
runId
string
options?
Returns
Promise<FunctionRunSettled<TOutput>>