@graph8/sdk 0.303.0 → 0.357.0

package/blocks/workflows/components/workflow-list.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+/**
+ * WorkflowList: the workspace's workflows with run, enable/disable, create and delete.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listWorkflows    GET    /workflows                    (read; `{ actions, total }`)
+ *   2. createWorkflow   POST   /workflows                    (external: a saved workflow can start acting on triggers)
+ *   3. planWorkflow     POST   /workflows/{id}/plan          (read; what a run would do, touch and cost)
+ *   4. executeWorkflow  POST   /workflows/{id}/execute       (external: a run can message people and change records)
+ *   5. updateWorkflow   PUT    /workflows/{id}               (external; here only `{ enabled }`)
+ *   6. deleteWorkflow   DELETE /workflows/{id}               (destructive)
+ *
+ * Run shows the plan first (steps, audience, advisory credits) inside the confirm dialog, with the run input as
+ * JSON. The `action_id` of each row is the id every other call needs; the run response carries `execution_id`,
+ * which is handed to `onRunStarted` so you can open RunHistory on it.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Textarea, Input } from "@graph8/sdk/ui";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { blankConfig, payload, str } from "../lib/graph";
+import type { Rec, WorkflowRow } from "../lib/graph";
+
+export interface WorkflowListProps {
+  /** Open a workflow in your WorkflowEditor route. */
+  onOpen?: (actionId: string) => void;
+  /** Called with `(actionId, executionId)` after a run starts, so you can show RunHistory. */
+  onRunStarted?: (actionId: string, executionId: string) => void;
+  className?: string;
+}
+
+type Pending =
+  | { kind: "create"; name: string }
+  | { kind: "run"; workflow: WorkflowRow }
+  | { kind: "toggle"; workflow: WorkflowRow }
+  | { kind: "delete"; workflow: WorkflowRow };
+
+/** Plan numbers shown in the run dialog. Every field is optional: the plan is advisory. */
+function planFacts(plan: Rec): { credits?: number; audience?: number; steps: number; approval: boolean; external: boolean } {
+  const cost = (plan.estimated_cost ?? {}) as Rec;
+  const credits = (cost.estimated_for_audience ?? cost.estimated_total_per_target) as number | undefined;
+  const policy = (plan.policy ?? {}) as Rec;
+  return {
+    credits: typeof credits === "number" ? credits : undefined,
+    audience: typeof plan.audience_size === "number" ? plan.audience_size : undefined,
+    steps: Array.isArray(plan.steps) ? plan.steps.length : 0,
+    approval: policy.requires_approval === true,
+    external: policy.has_external_effects === true,
+  };
+}
+
+function RunPlan({ actionId, input, setInput }: { actionId: string; input: string; setInput: (v: string) => void }) {
+  const plan = useG8Query((signal) => g8Post(`/workflows/${encodeURIComponent(actionId)}/plan`, {}, { signal }), [actionId]);
+  const facts = planFacts(payload(plan.data));
+  let valid = true;
+  try { JSON.parse(input || "{}"); } catch { valid = false; }
+  return (
+    <div className="space-y-2 text-left">
+      {plan.loading ? <Skeleton className="h-4 w-48" /> : plan.error ? <p className="text-xs">The preview is unavailable; the run still works.</p> : (
+        <p className="text-xs" data-testid="run-plan">
+          {facts.steps} steps{facts.audience != null ? `, ${facts.audience.toLocaleString()} contacts in scope` : ""}
+          {facts.credits != null ? `, about ${Math.round(facts.credits).toLocaleString()} credits (advisory)` : ""}
+          {facts.approval ? ", waits for a human approval" : ""}{facts.external ? ", contacts people or systems outside graph8" : ""}.
+        </p>
+      )}
+      <label className="block text-xs font-medium" htmlFor="run-input">Run input (JSON)</label>
+      <Textarea id="run-input" rows={3} value={input} onChange={(e) => setInput(e.target.value)} aria-invalid={!valid} />
+      {!valid ? <p className="text-destructive text-xs">That is not valid JSON.</p> : null}
+    </div>
+  );
+}
+
+function confirmCopy(p: Pending): { tier: "external" | "destructive"; title: string; label: string; description?: string } {
+  if (p.kind === "create") return { tier: "external", title: `Create workflow "${p.name || "Untitled workflow"}"`, label: "Create", description: "A manual-trigger workflow with no steps yet. Add steps in the editor." };
+  if (p.kind === "run") return { tier: "external", title: `Run "${p.workflow.name}"`, label: "Run now" };
+  if (p.kind === "toggle") {
+    const on = p.workflow.enabled !== false;
+    return { tier: "external", title: `${on ? "Disable" : "Enable"} "${p.workflow.name}"`, label: on ? "Disable" : "Enable", description: on ? "Its trigger stops firing." : "Its trigger starts firing and the workflow can act on real contacts." };
+  }
+  return { tier: "destructive", title: `Delete "${p.workflow.name}"`, label: "Delete", description: "The workflow and its trigger are removed. Past runs stay in history." };
+}
+
+export function WorkflowList({ onOpen, onRunStarted, className }: WorkflowListProps) {
+  const list = useG8Query((signal) => g8Get("/workflows", undefined, { signal }), []);
+  const [name, setName] = useState("");
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [input, setInput] = useState("{}");
+  useEffect(() => setInput("{}"), [pending]);
+
+  const run = useG8Mutation(async (p: Pending) => {
+    if (p.kind === "create") return g8Post("/workflows", { name: p.name || "Untitled workflow", description: "", config: blankConfig(p.name || "Untitled workflow") });
+    const base = `/workflows/${encodeURIComponent(p.workflow.action_id)}`;
+    if (p.kind === "run") return g8Post(`${base}/execute`, { input_data: JSON.parse(input || "{}") });
+    if (p.kind === "toggle") return g8Put(base, { enabled: p.workflow.enabled === false });
+    return g8Delete(base);
+  }, {
+    onSuccess: (res, p) => {
+      setPending(null);
+      if (p.kind === "create") { setName(""); const id = str(payload(res).action_id); if (id) onOpen?.(id); }
+      if (p.kind === "run") onRunStarted?.(p.workflow.action_id, str(payload(res).execution_id));
+      void list.refetch();
+    },
+  });
+
+  const rows = (Array.isArray(payload(list.data).actions) ? payload(list.data).actions : []) as WorkflowRow[];
+  const copy = pending ? confirmCopy(pending) : null;
+  let inputOk = true;
+  try { JSON.parse(input || "{}"); } catch { inputOk = false; }
+
+  return (
+    <div className={className}>
+      <div className="mb-4 flex items-center justify-end gap-2">
+        <Input aria-label="New workflow name" placeholder="Workflow name" value={name} onChange={(e) => setName(e.target.value)} className="w-64" />
+        <Button onClick={() => setPending({ kind: "create", name: name.trim() })}>New workflow</Button>
+      </div>
+      {list.error ? <ApiError error={list.error} onRetry={() => void list.refetch()} /> : null}
+      {run.error ? <ApiError error={run.error} title="That action failed" /> : null}
+      {list.loading && !list.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div> : !list.error && rows.length === 0 ? (
+        <EmptyState title="No workflows yet" description="A workflow runs steps automatically when its trigger fires or when you run it. Create one, then add steps." />
+      ) : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead><TableHead>Category</TableHead><TableHead className="text-right">Actions</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {rows.map((w) => (
+              <TableRow key={w.action_id}>
+                <TableCell><button type="button" className="font-medium hover:underline" onClick={() => onOpen?.(w.action_id)}>{w.name}</button>{w.description ? <div className="text-muted-foreground text-xs">{w.description}</div> : null}</TableCell>
+                <TableCell>{w.enabled === false ? "Disabled" : "Enabled"}</TableCell>
+                <TableCell>{w.category ?? ""}</TableCell>
+                <TableCell className="space-x-1 text-right">
+                  <Button size="sm" variant="outline" onClick={() => setPending({ kind: "run", workflow: w })}>Run</Button>
+                  <Button size="sm" variant="ghost" onClick={() => setPending({ kind: "toggle", workflow: w })}>{w.enabled === false ? "Enable" : "Disable"}</Button>
+                  <Button size="sm" variant="ghost" aria-label={`Delete ${w.name}`} onClick={() => setPending({ kind: "delete", workflow: w })}>Delete</Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      {pending && copy ? (
+        <ConfirmSpendDialog open tier={copy.tier} title={copy.title} confirmLabel={copy.label} confirming={run.loading}
+          affected={pending.kind === "delete" ? 1 : undefined}
+          description={pending.kind === "run" ? <RunPlan actionId={pending.workflow.action_id} input={input} setInput={setInput} /> : copy.description}
+          onConfirm={() => { if (pending.kind !== "run" || inputOk) void run.mutate(pending); }} onCancel={() => setPending(null)} />
+      ) : null}
+    </div>
+  );
+}

package/blocks/workflows/hooks/use-workflow.ts

@@ -0,0 +1,51 @@
+"use client";
+
+/**
+ * useWorkflow: load one workflow and save changes to its graph.
+ *
+ * SDK operations, in order: getWorkflow (GET /workflows/{id}, read), then updateWorkflow
+ * (PUT /workflows/{id}, external tier: saving can start a trigger or change what a live workflow sends).
+ * Use `saveAndRefresh` so drafts are cleared only after the refetch landed.
+ * The component that calls `save` must ask for confirmation first (ConfirmSpendDialog, tier "external").
+ *
+ *   const { workflow, config, save } = useWorkflow(actionId);
+ *   await save.mutate({ config: nextConfig });
+ */
+
+import { useMemo } from "react";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { configOf, payload } from "../lib/graph";
+import type { Rec } from "../lib/graph";
+
+export interface WorkflowUpdate {
+  config?: Rec;
+  name?: string;
+  description?: string;
+  enabled?: boolean;
+}
+
+export function useWorkflow(actionId: string) {
+  const base = `/workflows/${encodeURIComponent(actionId)}`;
+  const query = useG8Query((signal) => g8Get(base, undefined, { signal }), [actionId]);
+  const save = useG8Mutation((update: WorkflowUpdate) => g8Put(base, update));
+  /** Save, then WAIT for the fresh copy: callers clear their drafts after this resolves, so nothing shows pre-save data. */
+  const saveAndRefresh = async (update: WorkflowUpdate): Promise<unknown> => {
+    const result = await save.mutate(update);
+    if (result) await query.refetch();
+    return result;
+  };
+  // Memoised: callers key effects on `workflow`, and a fresh `{}` per render would loop them.
+  const workflow = useMemo(() => payload(query.data), [query.data]);
+  const config = useMemo(() => configOf(workflow), [workflow]);
+  return {
+    workflow,
+    config,
+    loading: query.loading && !query.data,
+    error: query.error,
+    refetch: query.refetch,
+    save,
+    saveAndRefresh,
+  };
+}

package/blocks/workflows/lib/graph.ts

@@ -0,0 +1,187 @@
+"use client";
+
+/**
+ * Pure helpers for a workflow graph (`config` of a workflow): read it as an ordered list of steps, and edit it
+ * as a list. No network, no React, so the rules are easy to test and to change.
+ *
+ * A saved graph is stored TWICE (see docs/workflow-authoring-guide.md): per-node `connections` /
+ * `conditionalConnections` that the runtime walks, and a top-level `edges` array the canvas draws. The two must
+ * agree, so every structural edit here rewrites both. Key casing follows the graph you loaded (`node_id` or
+ * `nodeId`): the API accepts either and normalises on save, but we never mix styles inside one graph.
+ *
+ * Only LINEAR graphs (every node has at most one next node, no branches) can be restructured here. A branching
+ * graph can still have its steps' names and config edited; add, remove and move are disabled for it, because a
+ * list cannot show where a branch goes. Use the graph8 app's canvas for branching logic.
+ */
+
+export type Rec = Record<string, unknown>;
+export type WfNode = Rec;
+
+export function asRec(value: unknown): Rec {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Rec) : {};
+}
+
+/**
+ * The body of a response. Workflow routes pass the service's JSON through as-is (no `{ data }` wrapper), while most
+ * other graph8 routes wrap it; accept both so a later API change does not blank the screens.
+ */
+export function payload(res: unknown): Rec {
+  const r = asRec(res);
+  return r.data && typeof r.data === "object" && !Array.isArray(r.data) ? asRec(r.data) : r;
+}
+
+export function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : value == null ? fallback : String(value);
+}
+
+/** The graph inside a workflow record (`config`, or voice's older name `skill_config`). */
+export function configOf(workflow: unknown): Rec {
+  const w = asRec(workflow);
+  return asRec(w.config ?? w.skill_config);
+}
+
+export function nodesOf(config: Rec): WfNode[] {
+  return Array.isArray(config.nodes) ? (config.nodes as WfNode[]) : [];
+}
+
+export const nodeIdOf = (n: WfNode): string => str(n.node_id ?? n.nodeId ?? n.id);
+export const nodeTypeOf = (n: WfNode): string => str(n.node_type ?? n.nodeType ?? n.type);
+export const nodeNameOf = (n: WfNode): string => str(n.name) || nodeTypeOf(n).replace(/_/g, " ") || nodeIdOf(n);
+export const startIdOf = (config: Rec): string => str(config.start_node_id ?? config.startNodeId);
+
+const nextIds = (n: WfNode): string[] => (Array.isArray(n.connections) ? (n.connections as unknown[]).map((c) => str(c)) : []);
+const branches = (n: WfNode): Rec => asRec(n.conditionalConnections ?? n.conditional_connections);
+
+/** No branches and no fan-out anywhere: the graph is one chain. */
+export function isLinear(config: Rec): boolean {
+  return nodesOf(config).every((n) => nextIds(n).length <= 1 && Object.keys(branches(n)).length === 0);
+}
+
+/** Steps in run order: follow `connections` from the start node, then any node the walk did not reach. */
+export function orderedSteps(config: Rec): WfNode[] {
+  const nodes = nodesOf(config);
+  const byId = new Map(nodes.map((n) => [nodeIdOf(n), n]));
+  const out: WfNode[] = [];
+  const seen = new Set<string>();
+  let cursor: WfNode | undefined = byId.get(startIdOf(config)) ?? nodes[0];
+  while (cursor && !seen.has(nodeIdOf(cursor))) {
+    seen.add(nodeIdOf(cursor));
+    out.push(cursor);
+    const next: string | undefined = [...nextIds(cursor), ...Object.values(branches(cursor)).map((v) => str(v))][0];
+    cursor = next ? byId.get(next) : undefined;
+  }
+  return [...out, ...nodes.filter((n) => !seen.has(nodeIdOf(n)))];
+}
+
+const snake = (config: Rec): boolean => nodesOf(config).some((n) => "node_id" in n) || "start_node_id" in config;
+
+/** Rewrite `connections` and `edges` so the given order is the chain start -> ... -> last. */
+export function relink(config: Rec, order: WfNode[]): Rec {
+  const linked = order.map((n, i) => {
+    const next = order[i + 1];
+    return { ...n, connections: next ? [nodeIdOf(next)] : [] };
+  });
+  const edges = order.slice(0, -1).map((n, i) => ({
+    id: `e-${nodeIdOf(n)}-${nodeIdOf(order[i + 1])}`,
+    source: nodeIdOf(n),
+    target: nodeIdOf(order[i + 1]),
+    type: "default",
+  }));
+  const startKey = snake(config) ? "start_node_id" : "startNodeId";
+  return { ...config, nodes: linked, edges, [startKey]: order.length ? nodeIdOf(order[0]) : "" };
+}
+
+export function setStep(config: Rec, id: string, patch: Rec): Rec {
+  return { ...config, nodes: nodesOf(config).map((n) => (nodeIdOf(n) === id ? { ...n, ...patch } : n)) };
+}
+
+export function uniqueId(config: Rec, type: string): string {
+  const taken = new Set(nodesOf(config).map(nodeIdOf));
+  const base = type.replace(/_/g, "-");
+  let i = 1;
+  while (taken.has(`${base}-${i}`)) i++;
+  return `${base}-${i}`;
+}
+
+export function newStep(config: Rec, type: string, name: string): WfNode {
+  const id = uniqueId(config, type);
+  const ids = snake(config) ? { node_id: id, node_type: type } : { nodeId: id, nodeType: type };
+  return { ...ids, name, position: { x: 100, y: 200 }, config: {}, connections: [] };
+}
+
+/** Insert a step after `afterId`: undefined appends to the chain, null inserts at the very start. Linear graphs only. */
+export function addStep(config: Rec, step: WfNode, afterId?: string | null): Rec {
+  const order = orderedSteps(config);
+  const at = afterId === null ? 0 : afterId ? order.findIndex((n) => nodeIdOf(n) === afterId) + 1 : order.length;
+  return relink(config, [...order.slice(0, at), step, ...order.slice(at)]);
+}
+
+export function removeStep(config: Rec, id: string): Rec {
+  return relink(config, orderedSteps(config).filter((n) => nodeIdOf(n) !== id));
+}
+
+const FIXED_TYPES = new Set(["trigger", "end"]);
+
+/** A step can move one place only if neither it nor the step it would swap with is the trigger or the end. */
+export function canMove(config: Rec, id: string, delta: -1 | 1): boolean {
+  const order = orderedSteps(config);
+  const from = order.findIndex((n) => nodeIdOf(n) === id);
+  const to = from + delta;
+  if (from < 0 || to < 0 || to >= order.length) return false;
+  return !FIXED_TYPES.has(nodeTypeOf(order[from])) && !FIXED_TYPES.has(nodeTypeOf(order[to]));
+}
+
+export function moveStep(config: Rec, id: string, delta: -1 | 1): Rec {
+  if (!canMove(config, id, delta)) return config;
+  const order = orderedSteps(config);
+  const from = order.findIndex((n) => nodeIdOf(n) === id);
+  const to = from + delta;
+  const next = [...order];
+  [next[from], next[to]] = [next[to], next[from]];
+  return relink(config, next);
+}
+
+/** A new workflow: a manual (`tool_call`) trigger and an end step, ready for steps to be inserted between. */
+export function blankConfig(name: string): Rec {
+  const trigger = { nodeId: "trigger-1", nodeType: "trigger", name: "Trigger", position: { x: 100, y: 200 }, config: { trigger_type: "tool_call" }, connections: ["end-1"] };
+  const end = { nodeId: "end-1", nodeType: "end", name: "End", position: { x: 400, y: 200 }, config: {}, connections: [] };
+  return {
+    metadata: { name, version: 1 },
+    startNodeId: "trigger-1",
+    nodes: [trigger, end],
+    edges: [{ id: "e-trigger-1-end-1", source: "trigger-1", target: "end-1", type: "default" }],
+    settings: { stop_on_failure: true },
+  };
+}
+
+export const triggerOf = (config: Rec): WfNode | undefined => nodesOf(config).find((n) => nodeTypeOf(n) === "trigger");
+
+export interface WorkflowRow {
+  action_id: string;
+  name: string;
+  description?: string | null;
+  enabled?: boolean;
+  category?: string | null;
+  is_template?: boolean;
+  updated_at?: string | null;
+  workflow_summary?: Rec | null;
+}
+
+export interface ExecutionRow {
+  execution_id: string;
+  action_id: string;
+  status: string;
+  triggered_by?: string | null;
+  trigger_type?: string | null;
+  error_message?: string | null;
+  output_data?: Rec | null;
+  input_data?: Rec | null;
+  started_at?: string | null;
+  completed_at?: string | null;
+  duration_ms?: number | null;
+  created_at?: string | null;
+}
+
+/** Statuses after which a run will not change on its own (paused and pending_approval wait for a person). */
+export const TERMINAL_STATUSES = ["completed", "failed", "stopped"];
+export const WAITING_STATUSES = ["paused", "pending_approval"];

package/blocks/workflows/recipes/create-workflow.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Create a workflow from a list of steps, validate it, and save it
+ * @when The customer describes an automation ("when a form is submitted, add the contact to a list and notify
+ * Slack"). Read the node catalog first (getNodeTypesSchema) so every `config` uses real field names. Saving is
+ * external tier: a saved, enabled workflow can start acting on live events, so confirm with the person, and create
+ * it disabled when in doubt.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export interface StepSpec {
+  type: string;
+  name: string;
+  config: Record<string, unknown>;
+}
+
+export async function createWorkflow(name: string, triggerType: string, steps: StepSpec[]): Promise<string> {
+  const nodes = [
+    { nodeId: "trigger-1", nodeType: "trigger", name: "Trigger", position: { x: 100, y: 200 }, config: { trigger_type: triggerType } },
+    ...steps.map((s, i) => ({ nodeId: `step-${i + 1}`, nodeType: s.type, name: s.name, position: { x: 400 + i * 300, y: 200 }, config: s.config })),
+    { nodeId: "end-1", nodeType: "end", name: "End", position: { x: 400 + steps.length * 300, y: 200 }, config: {} },
+  ].map((n, i, all) => ({ ...n, connections: all[i + 1] ? [all[i + 1].nodeId] : [] }));
+  const edges = nodes.slice(0, -1).map((n, i) => ({ id: `e-${n.nodeId}-${nodes[i + 1].nodeId}`, source: n.nodeId, target: nodes[i + 1].nodeId, type: "default" }));
+  const config = { metadata: { name, version: 1 }, startNodeId: "trigger-1", nodes, edges };
+
+  // 1. Validate before saving: errors block the save, missing_references are ids that do not exist (fix them first).
+  const check = (await g8.api.workflows.validateWorkflow({ body: { config } })) as { valid?: boolean; errors?: string[] };
+  if (check.valid === false) throw new Error(`Workflow is not valid: ${(check.errors ?? []).join("; ")}`);
+
+  // 2. Save. Returns the new workflow's action_id, the id every other call needs.
+  const created = (await g8.api.workflows.createWorkflow({ body: { name, description: "", config } })) as { action_id?: string };
+  if (!created.action_id) throw new Error("The API did not return an action_id");
+  return created.action_id;
+}

package/blocks/workflows/recipes/find-failed-runs.ts

@@ -0,0 +1,15 @@
+/**
+ * @title List a workflow's failed runs with their errors
+ * @when Something did not happen and the customer wants to know why. Reading runs is free. Restarting a failed run
+ * is external tier (steps that message people run again): ask first.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function failedRuns(actionId: string, limit = 25): Promise<Array<{ executionId: string; startedAt: string; error: string }>> {
+  const res = (await g8.api.workflows.listWorkflowExecutions({ query: { action_id: actionId, status_filter: "failed", limit } })) as {
+    executions?: Array<{ execution_id: string; started_at?: string | null; created_at?: string | null; error_message?: string | null }>;
+  };
+  return (res.executions ?? []).map((e) => ({ executionId: e.execution_id, startedAt: e.started_at ?? e.created_at ?? "", error: e.error_message ?? "no error recorded" }));
+}

package/blocks/workflows/recipes/run-workflow-and-wait.ts

@@ -0,0 +1,32 @@
+/**
+ * @title Preview a workflow run, start it, and wait for the result
+ * @when The customer wants to run a workflow now. The plan is free and shows steps, audience size and advisory
+ * credits; the run itself is external tier (it can message people), so show the plan to the person first. The run
+ * is asynchronous: poll the execution until it is completed, failed or stopped. `paused` and `pending_approval`
+ * wait for a person and never finish on their own.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+type Body = Record<string, unknown>;
+
+export async function runWorkflow(actionId: string, input: Body = {}): Promise<Body> {
+  // 1. Preview. Read-only.
+  const plan = (await g8.api.workflows.planWorkflow({ path: { action_id: actionId }, body: {} })) as Body;
+  console.log("steps:", Array.isArray(plan.steps) ? plan.steps.length : 0, "audience:", plan.audience_size ?? "unknown");
+
+  // 2. Start. The response carries execution_id (outcome "unknown" means check the executions list before retrying).
+  const started = (await g8.api.workflows.executeWorkflow({ path: { action_id: actionId }, body: { input_data: input } })) as Body;
+  const executionId = String(started.execution_id ?? "");
+  if (!executionId) throw new Error(`Run not confirmed (outcome: ${String(started.outcome)}); list executions before retrying`);
+
+  // 3. Poll with backoff until the run settles.
+  for (let attempt = 0; attempt < 60; attempt++) {
+    const run = (await g8.api.workflows.getExecution({ path: { execution_id: executionId } })) as Body;
+    if (["completed", "failed", "stopped", "paused", "pending_approval"].includes(String(run.status))) return run;
+    await sleep(Math.min(15_000, 1_500 * 1.4 ** attempt));
+  }
+  throw new Error(`Execution ${executionId} is still running; check it later`);
+}

package/blocks/workflows/recipes/set-trigger.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Change a workflow's trigger and skip the backlog
+ * @when The customer wants a different start event or interval. Updating is external tier (new events start real
+ * runs). Resetting the cursor skips events that arrived while the trigger was off, so say so before doing it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Node = { nodeId?: string; node_id?: string; nodeType?: string; node_type?: string; config?: Record<string, unknown> };
+
+export async function setTrigger(actionId: string, triggerType: string, pollingMinutes?: number, resetCursor = false): Promise<void> {
+  const workflow = (await g8.api.workflows.getWorkflow({ path: { action_id: actionId } })) as { config?: { nodes?: Node[] } & Record<string, unknown> };
+  const config = workflow.config;
+  const nodes = config?.nodes ?? [];
+  const trigger = nodes.find((n) => (n.nodeType ?? n.node_type) === "trigger");
+  if (!config || !trigger) throw new Error("This workflow has no trigger node");
+
+  trigger.config = { ...trigger.config, trigger_type: triggerType, ...(pollingMinutes ? { polling_interval_minutes: pollingMinutes } : {}) };
+  await g8.api.workflows.updateWorkflow({ path: { action_id: actionId }, body: { config } });
+  if (resetCursor) await g8.api.workflows.resetTriggerCursor({ path: { action_id: actionId } });
+}