REST client

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

const duraton = createClient({
  apiKey: process.env.DURATON_API_KEY,
});

const res = await duraton.events.send({
  name: "ticket.created",
  app: "support-app",
  data: { ticketId: "T-421" },
});
res.runId;       // the run started, when exactly one workflow matched
res.triggered;   // one entry per matched workflow

const events = await duraton.events.list({ app: "support-app", limit: 20 });
const one = await duraton.events.get(events[0].id);

// Live tail (Server-Sent Events). Iterate to consume; abort to stop.
const ac = new AbortController();
for await (const ev of duraton.events.stream({ signal: ac.signal })) {
  console.log(ev.name, ev.triggered);
}

// One page, newest first, plus the keyset cursor for the next page.
const page = await duraton.runs.list({ status: "failed", sort: "duration", dir: "desc", limit: 20 });
page.runs;
page.nextCursor;   // pass back as { cursor } for the next page, or null on the last

// Walk every run across pages - the cursor is managed for you.
for await (const run of duraton.runs.listAll({ app: "support-app" })) {
  console.log(run.id, run.status);
}

const run = await duraton.runs.get("01HXYZ...");
const steps = await duraton.runs.steps("01HXYZ...");
const stats = await duraton.runs.stats({ app: "support-app" });

// Look one run up by a business tag instead of its id - returns the match, or null.
const ticket = await duraton.runs.find({ tags: { ticketId: "123" } });

const { runId } = await duraton.events.send({ name: "ticket.created", data: { ticketId: "T-421" } });
const run = await duraton.runs.wait(runId!, { timeoutMs: 60_000 });

if (run.status === "succeeded") console.log(run.result);
else console.error(run.error);

// A run's timeline: status transitions and ctx.log lines, in order. Ends when the run is
// terminal; { from } resumes past a seq.
for await (const frame of duraton.runs.watch("01HXYZ...")) {
  if (frame.kind === "log") console.log(frame.level, frame.message);
  else console.log(frame.kind, frame.status);
}

// A run's persisted ctx.log history, oldest first; page forward with { from }.
const lines = await duraton.runs.logs("01HXYZ...", { from: 0, limit: 100 });

// Run status changes across the whole project. Only run_status frames flow and there is no
// per-run cursor - treat each frame as "refetch", not as a lossless log.
for await (const frame of duraton.runs.watchAll()) {
  console.log(frame.runId, "->", frame.status);
}

// Each returns the affected run; replay and retryFromStep return the NEW run.
await duraton.runs.cancel("01HXYZ...");
await duraton.runs.pause("01HXYZ...");
await duraton.runs.resume("01HXYZ...");

const replayed = await duraton.runs.replay("01HXYZ...");                       // or replay(id, editedInput)
const resumed = await duraton.runs.retryFromStep("01HXYZ...", "triage");       // fork from a step
const bulk = await duraton.runs.bulkReplay({ status: "failed", since: "2026-06-01T00:00:00Z" });

// The audit log of control actions (newest first), optionally filtered.
const history = await duraton.runs.controlActions({ runId: "01HXYZ..." });

const series = await duraton.runs.timeseries({
  app: "support-app",
  since: "2026-07-01T00:00:00Z",
  bucket: 3600,   // bucket width in seconds
});

series.bucketSeconds;
for (const b of series.buckets) {
  console.log(b.ts, b.total, b.counts.failed, b.avgMs, b.maxMs);
}

const state = await duraton.flowState({ app: "support-app" });

for (const d of state.debounce) console.log(d.workflow, d.pending, d.nextFireAt);
for (const b of state.batch) console.log(b.workflow, b.buffered, b.oldestAt);

// AI conversations: runs grouped by session id, most recent first.
const sessions = await duraton.sessions.list({ app: "support", limit: 20 });

// AI spend rolled up by hour, model, and workflow.
const spend = await duraton.ai.spend({ app: "support", since: "2026-07-01T00:00:00Z" });

// Decide an open human-in-the-loop gate, which resumes its parked run. The decider is
// recorded from the authenticated actor, so the decision cannot be attributed to anyone else.
const open = await duraton.approvals.list({ status: "pending" });
await duraton.approvals.decide(open[0].id, { status: "approved" });

await duraton.workflows.list();   // registered workflows, with their triggers and flow control

// Start one off-schedule run of a workflow, by identity - works even for a cron-only
// workflow. See "Trigger a run manually" in the triggers guide.
const res = await duraton.workflows.trigger("support-app", "nightly-report", { input: { force: true } });
res.runId; // absent if a flow-control gate short-circuited it

await duraton.apps.list();        // registered apps
await duraton.runners.list();     // registered runners and their liveness
await duraton.health();           // { status: "ok" }
await duraton.ready();            // { status, checks, draining }

import { DuratonApiError } from "@duraton/sdk/client";

try {
  await duraton.runs.cancel(id);
} catch (err) {
  if (err instanceof DuratonApiError && err.isConflict()) {
    // 409: the run is already terminal
  } else if (err instanceof DuratonApiError && err.isNotFound()) {
    // 404: no such run
  } else {
    throw err;
  }
}

const duraton = createClient({
  url: process.env.DURATON_URL!,
  apiKey: process.env.DURATON_API_KEY,
  fetch: myInstrumentedFetch,   // any fetch-compatible implementation
});