Wait tokens

Pause a run until a person or another system answers.

A wait token is a one-time callback URL. A run waits on it; whoever holds the URL completes it, and the run carries on with the data they sent.

Wait in a workflow

import { defineWorkflow, waitForToken } from "@duraton/sdk";
import { createClient } from "@duraton/sdk/client";

const client = createClient({ url, apiKey: process.env.DURATON_SECRET_KEY ?? "" });

export const approveRefund = defineWorkflow<{ orderId: string }>({
  name: "approve-refund",
  triggers: [{ event: "refund/requested" }],
  handler: async ({ step }) => {
    const token = await step.run("create-token", () =>
      client.tokens.create({ timeoutSeconds: 3600 }),
    );
    await step.run("ask-approver", () => sendApprovalLink(token.callbackUrl));

    const answer = await waitForToken(step, token.id, { timeout: "1h" });
    if (!answer.ok) return "timed out";
    return answer.data;
  },
});

Create the token inside step.run, so a replay keeps the same one. waitForToken answers { ok: true, data } once the token is completed and { ok: false, reason: "timeout" } when the wait times out; a timeout is not an error.

Create and complete

POST /tokens { timeoutSeconds, data?, runId? } answers the token with a callbackUrl, shown once. Anyone holding that URL completes the token with POST <callbackUrl> { data }, no key; a GET is refused, so a link preview never completes one. A second completion is 409 token_not_waiting.

With a secret key you can also complete it by id: client.tokens.complete(id, data), or POST /tokens/{id}/complete. GET /tokens and GET /tokens/{id} read them; a token’s callback URL is never shown again.

Linked to its run

Every token answer carries runId: the run the token was made for, or null. client.tokens.create called in workflow code (as in the step above) sends the current run’s id, so the token is linked to that run; called anywhere else, it sends none. Pass runId to name another run of the project, or runId: null to link none. A runId that names no run of the project is 422 unprocessable, and no token is made.

While workflows are turned off for the project, completing a token, by POST /tokens/{id}/complete or its callbackUrl, is 409 workflows_suspended and the token stays waiting.