[V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { ApprovalChainCodeWorkbench } from "@/components/approval-chain-code-workbench"; type DemoStatus = "idle" | "running" | "approved" | "rejected" | "expired"; type ApprovalRole = "manager" | "director" | "vp"; type ApiLevelStatus = "pending" | "active" | "approved" | "rejected" | "expired"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type GutterMarkKind = "success" | "fail"; type WorkflowLineMap = { loop: number[]; notify: number[]; race: number[]; timeout: number[]; approve: number[]; reject: number[]; expire: number[]; }; type StepLineMap = { notify: number[]; timeout: number[]; approve: number[]; reject: number[]; }; type StatusLevel = { role: ApprovalRole; label: string; required: boolean; status: ApiLevelStatus; timeoutMs: number; countdownMs: number; decidedAt?: number; }; type StatusSnapshot = { runId: string; amount: number; status: Exclude; currentLevelIndex: number; levels: StatusLevel[]; history: Array<{ id: string; kind: string; role: ApprovalRole | null; atMs: number; message: string; }>; }; type StartResponse = { ok: true; runId: string; levels: ApprovalRole[]; }; type Props = { workflowCode: string; workflowHtmlLines: string[]; workflowLineMap: WorkflowLineMap; stepCode: string; stepHtmlLines: string[]; stepLineMap: StepLineMap; }; const ROLE_ORDER: ApprovalRole[] = ["manager", "director", "vp"]; const POLL_INTERVAL_MS = 500; const AMOUNT_OPTIONS = [ { value: 250, label: "$250" }, { value: 2500, label: "$2500" }, { value: 7500, label: "$7500" }, ] as const; function mergeUniqueLines(...groups: number[][]): number[] { return [...new Set(groups.flat())].sort((a, b) => a - b); } async function postJson(url: string, body: Record, signal: AbortSignal): Promise { const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal, }); const payload = (await res.json().catch(() => ({ error: { message: "Request failed" } }))) as | T | { error?: { message?: string; }; }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!res.ok) { const message = typeof payload === "object" && payload !== null && "error" in payload && typeof payload.error?.message === "string" ? payload.error.message : `Request failed (${res.status})`; throw new Error(message); } return payload as T; } export function ApprovalChainDemo({ workflowCode, workflowHtmlLines, workflowLineMap, stepCode, stepHtmlLines, stepLineMap, }: Props) { const [demoStatus, setDemoStatus] = useState("idle"); const [amount, setAmount] = useState(AMOUNT_OPTIONS[0].value); const [runId, setRunId] = useState(null); const [requiredLevels, setRequiredLevels] = useState(ROLE_ORDER); const [snapshot, setSnapshot] = useState(null); const [isDeciding, setIsDeciding] = useState(false); const [error, setError] = useState(null); const pollTimerRef = useRef | null>(null); const inFlightRef = useRef(false); const abortRef = useRef(null); const stopPolling = useCallback(() => { if (pollTimerRef.current) { clearInterval(pollTimerRef.current); pollTimerRef.current = null; } inFlightRef.current = false; }, []); const ensureAbortController = useCallback(() => { if (!abortRef.current || abortRef.current.signal.aborted) { abortRef.current = new AbortController(); } return abortRef.current; }, []); useEffect(() => { return () => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; }; }, [stopPolling]); const fetchStatus = useCallback(async (targetRunId: string, signal: AbortSignal) => { const res = await fetch(`/api/mock/status?runId=${encodeURIComponent(targetRunId)}`, { cache: "no-store", signal, }); const payload = (await res.json().catch(() => ({ error: { message: "Status request failed" } }))) as | StatusSnapshot | { error?: { message?: string; }; }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!res.ok) { const message = typeof payload === "object" && payload !== null && "error" in payload && typeof payload.error?.message === "string" ? payload.error.message : `Status request failed (${res.status})`; throw new Error(message); } return payload as StatusSnapshot; }, []); const applySnapshot = useCallback( (next: StatusSnapshot) => { setSnapshot(next); setDemoStatus(next.status); if (next.status !== "running") { stopPolling(); } }, [stopPolling] ); const beginPolling = useCallback( (targetRunId: string) => { stopPolling(); const poll = async () => { if (inFlightRef.current) return; inFlightRef.current = true; let signal: AbortSignal | null = null; try { const controller = ensureAbortController(); signal = controller.signal; const next = await fetchStatus(targetRunId, signal); if (signal.aborted) return; applySnapshot(next); } catch (pollError) { if ((signal && signal.aborted) || (pollError instanceof Error && pollError.name === "AbortError")) { return; } stopPolling(); setError(pollError instanceof Error ? pollError.message : "Failed to fetch mock status"); } finally { inFlightRef.current = false; } }; void poll(); pollTimerRef.current = setInterval(() => void poll(), POLL_INTERVAL_MS); }, [applySnapshot, ensureAbortController, fetchStatus, stopPolling] ); const handleStart = useCallback(async () => { setError(null); setSnapshot(null); setRunId(null); setDemoStatus("running"); stopPolling(); abortRef.current?.abort(); abortRef.current = null; const controller = ensureAbortController(); const signal = controller.signal; try { const start = await postJson("/api/mock/start", { amount }, signal); if (signal.aborted) return; setRunId(start.runId); setRequiredLevels(start.levels); beginPolling(start.runId); } catch (startError) { if (signal.aborted || (startError instanceof Error && startError.name === "AbortError")) { return; } setDemoStatus("idle"); setError(startError instanceof Error ? startError.message : "Failed to start mock workflow"); } }, [amount, beginPolling, ensureAbortController, stopPolling]); const handleDecision = useCallback( async (approved: boolean) => { if (!runId || demoStatus !== "running") return; setError(null); setIsDeciding(true); const controller = ensureAbortController(); const signal = controller.signal; try { const next = await postJson( "/api/mock/decide", { runId, approved, }, signal ); if (signal.aborted) return; applySnapshot(next); } catch (decisionError) { if (signal.aborted || (decisionError instanceof Error && decisionError.name === "AbortError")) { return; } setError(decisionError instanceof Error ? decisionError.message : "Failed to submit decision"); } finally { setIsDeciding(false); } }, [applySnapshot, demoStatus, ensureAbortController, runId] ); const handleReset = useCallback(() => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; setDemoStatus("idle"); setRunId(null); setRequiredLevels(ROLE_ORDER); setSnapshot(null); setError(null); setIsDeciding(false); }, [stopPolling]); const snapshotLevels = snapshot?.levels; const levels = useMemo(() => { const byRole = new Map((snapshotLevels ?? []).map((level) => [level.role, level])); return ROLE_ORDER.map((role) => { const existing = byRole.get(role); if (existing) return existing; return { role, label: role === "vp" ? "VP" : role[0].toUpperCase() + role.slice(1), required: requiredLevels.includes(role), status: "pending" as const, timeoutMs: role === "manager" ? 10_000 : role === "director" ? 8_000 : 6_000, countdownMs: 0, }; }); }, [requiredLevels, snapshotLevels]); const statusMessage = useMemo(() => { if (demoStatus === "idle") { return "Pick an amount and start a mock approval run."; } if (demoStatus === "running") { const activeLevel = snapshot && snapshot.currentLevelIndex >= 0 ? snapshot.levels[snapshot.currentLevelIndex] : null; if (!activeLevel) { return "Bootstrapping run state and entering the first approval level..."; } return `${activeLevel.label} is active. The workflow is durably suspended at Promise.race() and consumes zero compute while waiting.`; } if (demoStatus === "approved") { return "Approval received. The workflow resumed and finished successfully."; } if (demoStatus === "rejected") { return "A level rejected the request. The workflow resumed and stopped."; } return "All required levels timed out. The workflow expired after escalation."; }, [demoStatus, snapshot]); const codeState = useMemo(() => { const workflowGutterMarks: Record = {}; const stepGutterMarks: Record = {}; for (const level of levels) { if (level.status === "approved") { for (const line of workflowLineMap.approve) workflowGutterMarks[line] = "success"; for (const line of stepLineMap.approve) stepGutterMarks[line] = "success"; } if (level.status === "rejected") { for (const line of workflowLineMap.reject) workflowGutterMarks[line] = "fail"; for (const line of stepLineMap.reject) stepGutterMarks[line] = "fail"; } if (level.status === "expired") { for (const line of workflowLineMap.timeout) workflowGutterMarks[line] = "fail"; for (const line of stepLineMap.timeout) stepGutterMarks[line] = "fail"; } } if (demoStatus === "idle") { return { tone: "amber" as HighlightTone, workflowActiveLines: [] as number[], workflowGutterMarks, stepActiveLines: [] as number[], stepGutterMarks, }; } if (demoStatus === "running") { const activeLevel = levels.find((level) => level.status === "active"); if (!activeLevel) { return { tone: "amber" as HighlightTone, workflowActiveLines: mergeUniqueLines(workflowLineMap.loop, workflowLineMap.notify), workflowGutterMarks, stepActiveLines: stepLineMap.notify, stepGutterMarks, }; } return { tone: "cyan" as HighlightTone, workflowActiveLines: mergeUniqueLines(workflowLineMap.loop, workflowLineMap.race), workflowGutterMarks, stepActiveLines: stepLineMap.timeout, stepGutterMarks, }; } if (demoStatus === "approved") { return { tone: "green" as HighlightTone, workflowActiveLines: workflowLineMap.approve, workflowGutterMarks, stepActiveLines: stepLineMap.approve, stepGutterMarks, }; } if (demoStatus === "rejected") { return { tone: "red" as HighlightTone, workflowActiveLines: workflowLineMap.reject, workflowGutterMarks, stepActiveLines: stepLineMap.reject, stepGutterMarks, }; } return { tone: "red" as HighlightTone, workflowActiveLines: mergeUniqueLines(workflowLineMap.timeout, workflowLineMap.expire), workflowGutterMarks, stepActiveLines: stepLineMap.timeout, stepGutterMarks, }; }, [demoStatus, levels, stepLineMap, workflowLineMap]); const history = snapshot?.history ?? []; const canStart = demoStatus === "idle"; return (

{error ? (

{error}

) : null}

Expense amount {runId ? `run: ${runId}` : "run: —"}

{statusMessage}

{levels.map((level) => { const isActive = level.status === "active"; const isApproved = level.status === "approved"; const isRejected = level.status === "rejected"; const isExpired = level.status === "expired"; const isDone = isApproved || isRejected || isExpired; const cardTone = isActive ? "border-amber-700/50 bg-amber-700/10" : isApproved ? "border-green-700/50 bg-green-700/10" : isRejected || isExpired ? "border-red-700/50 bg-red-700/10" : "border-gray-400/60 bg-background-200"; const badgeTone = isActive ? "border-amber-700/40 bg-amber-700/20 text-amber-700" : isApproved ? "border-green-700/40 bg-green-700/20 text-green-700" : isRejected || isExpired ? "border-red-700/40 bg-red-700/20 text-red-700" : "border-gray-400/60 bg-background-100 text-gray-900"; const badgeLabel = !level.required ? "Not Required" : level.status === "active" ? "Waiting" : level.status === "approved" ? "Approved" : level.status === "rejected" ? "Rejected" : level.status === "expired" ? "Timed Out" : "Pending"; const countdownLabel = level.status === "active" ? `${Math.max(0, level.countdownMs / 1000).toFixed(1)}s` : level.status === "expired" ? "0.0s" : "—"; return (

{level.label}

{badgeLabel} {countdownLabel}

{level.decidedAt ? (

decided at{" "} {new Date(level.decidedAt).toLocaleTimeString("en-US", { hour12: false, })}

) : null} {isActive && demoStatus === "running" ? (

) : null} {!level.required ? (

Skipped for this amount.

) : isDone ? (

{isApproved ? "Approval signal received" : isRejected ? "Rejection signal received" : "Level timed out and escalated"}

) : null}

); })}

History

{history.length === 0 ? (

No events yet.

) : (

)}

); } [V0_FILE]typescriptreact:file="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Approval Chain - Workflow DevKit Example", description: "Demonstrates multi-level expense approval with durable auto-escalation using defineHook and Promise.race", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( Skip to main content {children} ); } [V0_FILE]typescript:file="app/api/mock/decide/route.ts" import { MockApprovalError, decideCurrentLevel, type ApprovalRole, type LevelStatus, type MockApprovalSnapshot, type RunStatus, } from "@/app/api/mock/store"; type DecideRequestBody = { runId?: unknown; approved?: unknown; }; type ApiRunStatus = "running" | "approved" | "rejected" | "expired"; type ApiLevelStatus = "pending" | "active" | "approved" | "rejected" | "expired"; type ApiLevelSnapshot = { role: ApprovalRole; label: string; required: boolean; token: string; status: ApiLevelStatus; timeoutMs: number; countdownMs: number; requestedAtMs: number | null; decidedAt?: number; }; type ApiStatusSnapshot = { runId: string; amount: number; status: ApiRunStatus; currentLevelIndex: number; levels: ApiLevelSnapshot[]; history: MockApprovalSnapshot["history"]; }; function createError(status: number, message: string, code: string, details?: Record) { return Response.json( { ok: false, error: { code, message, details, }, }, { status, headers: { "cache-control": "no-store" }, } ); } function mapRunStatus(status: RunStatus): ApiRunStatus { switch (status) { case "timed_out": return "expired"; case "approved": case "rejected": return status; case "running": default: return "running"; } } function mapLevelStatus(status: LevelStatus): ApiLevelStatus { switch (status) { case "waiting": return "active"; case "timed_out": return "expired"; case "approved": case "rejected": return status; case "pending": default: return "pending"; } } function normalizeSnapshot(snapshot: MockApprovalSnapshot): ApiStatusSnapshot { const levels: ApiLevelSnapshot[] = snapshot.levels.map((level) => ({ role: level.role, label: level.label, required: level.required, token: level.token, status: mapLevelStatus(level.status), timeoutMs: level.timeoutMs, countdownMs: level.countdownMs, requestedAtMs: level.enteredAtMs, ...(typeof level.resolvedAtMs === "number" ? { decidedAt: level.resolvedAtMs } : {}), })); let currentLevelIndex = levels.findIndex((level) => level.status === "active"); if (currentLevelIndex === -1 && snapshot.status === "running") { currentLevelIndex = levels.findIndex( (level) => level.required && level.status === "pending" ); } return { runId: snapshot.runId, amount: snapshot.amount, status: mapRunStatus(snapshot.status), currentLevelIndex, levels, history: snapshot.history, }; } export async function POST(request: Request) { let body: DecideRequestBody; try { body = (await request.json()) as DecideRequestBody; } catch { return createError(400, "Invalid JSON body", "INVALID_JSON"); } if (typeof body.runId !== "string" || body.runId.trim().length === 0) { return createError(400, "runId is required", "MISSING_RUN_ID"); } if (typeof body.approved !== "boolean") { return createError(400, "approved must be a boolean", "INVALID_APPROVED"); } const runId = body.runId.trim(); try { const snapshot = decideCurrentLevel({ runId, decision: body.approved ? "approve" : "reject", }); const response = normalizeSnapshot(snapshot); console.info("[approval-chain:mock:decide] level_decided", { runId, approved: body.approved, status: response.status, currentLevelIndex: response.currentLevelIndex, }); return Response.json(response, { headers: { "cache-control": "no-store" }, }); } catch (error) { if (error instanceof MockApprovalError) { const statusCode = error.code === "RUN_NOT_FOUND" ? 404 : error.code === "RUN_NOT_ACTIVE" ? 409 : error.code === "NO_ACTIVE_LEVEL" || error.code === "DECISION_ALREADY_SUBMITTED" ? 409 : 400; return createError(statusCode, error.message, error.code, error.details); } const message = error instanceof Error ? error.message : "Failed to apply decision"; return createError(500, message, "DECISION_FAILED"); } } [V0_FILE]typescript:file="app/api/mock/start/route.ts" import { getRequiredLevelsForAmount, startMockRun } from "@/app/api/mock/store"; type StartRequestBody = { amount?: unknown; }; function createError(status: number, message: string, code: string) { return Response.json( { ok: false, error: { code, message, }, }, { status, headers: { "cache-control": "no-store" }, } ); } export async function POST(request: Request) { let body: StartRequestBody; try { body = (await request.json()) as StartRequestBody; } catch { return createError(400, "Invalid JSON body", "INVALID_JSON"); } if (typeof body.amount !== "number" || !Number.isFinite(body.amount) || body.amount <= 0) { return createError(400, "amount must be a positive number", "INVALID_AMOUNT"); } const amount = body.amount; const runId = crypto.randomUUID(); const levels = getRequiredLevelsForAmount(amount); const run = startMockRun(amount, Date.now(), runId); console.info("[approval-chain:mock:start] run_created", { runId: run.runId, amount, levels, }); return Response.json( { ok: true, runId: run.runId, levels, }, { headers: { "cache-control": "no-store" }, } ); } [V0_FILE]typescript:file="app/api/mock/status/route.ts" import { MockApprovalError, getMockSnapshot, type ApprovalRole, type LevelStatus, type MockApprovalSnapshot, type RunStatus, } from "@/app/api/mock/store"; type ApiRunStatus = "running" | "approved" | "rejected" | "expired"; type ApiLevelStatus = "pending" | "active" | "approved" | "rejected" | "expired"; type ApiLevelSnapshot = { role: ApprovalRole; label: string; required: boolean; token: string; status: ApiLevelStatus; timeoutMs: number; countdownMs: number; requestedAtMs: number | null; decidedAt?: number; }; type ApiStatusSnapshot = { runId: string; amount: number; status: ApiRunStatus; currentLevelIndex: number; levels: ApiLevelSnapshot[]; history: MockApprovalSnapshot["history"]; }; function createError(status: number, message: string, code: string, details?: Record) { return Response.json( { ok: false, error: { code, message, details, }, }, { status, headers: { "cache-control": "no-store" }, } ); } function mapRunStatus(status: RunStatus): ApiRunStatus { switch (status) { case "timed_out": return "expired"; case "approved": case "rejected": return status; case "running": default: return "running"; } } function mapLevelStatus(status: LevelStatus): ApiLevelStatus { switch (status) { case "waiting": return "active"; case "timed_out": return "expired"; case "approved": case "rejected": return status; case "pending": default: return "pending"; } } function normalizeSnapshot(snapshot: MockApprovalSnapshot): ApiStatusSnapshot { const levels: ApiLevelSnapshot[] = snapshot.levels.map((level) => ({ role: level.role, label: level.label, required: level.required, token: level.token, status: mapLevelStatus(level.status), timeoutMs: level.timeoutMs, countdownMs: level.countdownMs, requestedAtMs: level.enteredAtMs, ...(typeof level.resolvedAtMs === "number" ? { decidedAt: level.resolvedAtMs } : {}), })); let currentLevelIndex = levels.findIndex((level) => level.status === "active"); if (currentLevelIndex === -1 && snapshot.status === "running") { currentLevelIndex = levels.findIndex( (level) => level.required && level.status === "pending" ); } return { runId: snapshot.runId, amount: snapshot.amount, status: mapRunStatus(snapshot.status), currentLevelIndex, levels, history: snapshot.history, }; } export async function GET(request: Request) { const { searchParams } = new URL(request.url); const runId = searchParams.get("runId"); if (!runId || runId.trim().length === 0) { return createError(400, "runId is required", "MISSING_RUN_ID"); } try { const snapshot = getMockSnapshot(runId.trim()); const response = normalizeSnapshot(snapshot); console.info("[approval-chain:mock:status] snapshot_read", { runId: response.runId, status: response.status, currentLevelIndex: response.currentLevelIndex, }); return Response.json(response, { headers: { "cache-control": "no-store" }, }); } catch (error) { if (error instanceof MockApprovalError && error.code === "RUN_NOT_FOUND") { return createError(404, error.message, error.code, error.details); } const message = error instanceof Error ? error.message : "Failed to load mock status"; return createError(500, message, "STATUS_READ_FAILED"); } } [V0_FILE]typescript:file="app/api/mock/store.ts" export type ApprovalRole = "manager" | "director" | "vp"; export type ApprovalDecision = "approve" | "reject"; export type LevelStatus = "pending" | "waiting" | "approved" | "rejected" | "timed_out"; export type RunStatus = "running" | "approved" | "rejected" | "timed_out"; export type MockHistoryEvent = { id: string; kind: | "started" | "entered" | "approved" | "rejected" | "timed_out" | "escalated" | "completed"; role: ApprovalRole | null; atMs: number; message: string; }; export type MockLevelSnapshot = { role: ApprovalRole; label: string; required: boolean; token: string; timeoutMs: number; status: LevelStatus; enteredAtMs: number | null; resolvedAtMs: number | null; countdownMs: number; pendingDecision: ApprovalDecision | null; decisionRequestedAtMs: number | null; escalationAtMs: number | null; }; export type MockApprovalSnapshot = { runId: string; expenseId: string; amount: number; status: RunStatus; elapsedMs: number; currentLevelRole: ApprovalRole | null; currentLevelToken: string | null; countdownMs: number; levels: MockLevelSnapshot[]; escalationTimestamps: Array<{ role: ApprovalRole; atMs: number }>; history: MockHistoryEvent[]; }; type StoredDecision = { decision: ApprovalDecision; requestedAtMs: number; effectiveAtMs: number; }; type MockRun = { runId: string; expenseId: string; amount: number; startedAtMs: number; requiredLevels: ApprovalRole[]; decisions: Partial>; }; type MockStore = { runs: Map; }; const GLOBAL_STORE_KEY = "__wfdk_approval_chain_mock_store__"; const STEP_DELAY_MS = 600; const ROLE_ORDER: readonly ApprovalRole[] = ["manager", "director", "vp"]; const ROLE_DETAILS: Record< ApprovalRole, { label: string; timeoutMs: number; } > = { manager: { label: "Manager", timeoutMs: 10_000 }, director: { label: "Director", timeoutMs: 8_000 }, vp: { label: "VP", timeoutMs: 6_000 }, }; export class MockApprovalError extends Error { constructor( public readonly code: string, message: string, public readonly details?: Record ) { super(message); this.name = "MockApprovalError"; } } declare global { // eslint-disable-next-line no-var var __wfdk_approval_chain_mock_store__: MockStore | undefined; } function getStore(): MockStore { const root = globalThis as unknown as Record; const existing = root[GLOBAL_STORE_KEY]; if (existing && typeof existing === "object") { return existing as MockStore; } const created: MockStore = { runs: new Map() }; root[GLOBAL_STORE_KEY] = created; return created; } export function getMockRunStore(): Map { return getStore().runs; } export function getMockRun(runId: string): MockRun | undefined { return getStore().runs.get(runId); } function createRunId(): string { if (typeof crypto !== "undefined" && "randomUUID" in crypto) { return crypto.randomUUID(); } return `mock_run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`; } function createExpenseId(): string { return `exp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`; } export function getRequiredLevelsForAmount(amount: number): ApprovalRole[] { if (amount < 500) return ["manager"]; if (amount < 5000) return ["manager", "director"]; return ["manager", "director", "vp"]; } function createHistoryEvent(input: { kind: MockHistoryEvent["kind"]; role: ApprovalRole | null; atMs: number; message: string; }): MockHistoryEvent { return { id: `${input.kind}:${input.role ?? "none"}:${input.atMs}`, kind: input.kind, role: input.role, atMs: input.atMs, message: input.message, }; } function createBaseLevelSnapshot( role: ApprovalRole, expenseId: string, required: boolean ): MockLevelSnapshot { const details = ROLE_DETAILS[role]; return { role, label: details.label, required, token: `approval:${expenseId}:${role}`, timeoutMs: details.timeoutMs, status: "pending", enteredAtMs: null, resolvedAtMs: null, countdownMs: 0, pendingDecision: null, decisionRequestedAtMs: null, escalationAtMs: null, }; } export function startMockRun( amount: number, nowMs: number = Date.now(), runId: string = createRunId() ): MockRun { const expenseId = createExpenseId(); const run: MockRun = { runId, expenseId, amount, startedAtMs: nowMs, requiredLevels: getRequiredLevelsForAmount(amount), decisions: {}, }; getStore().runs.set(run.runId, run); console.info("[approval-chain:mock] run_started", { runId: run.runId, expenseId: run.expenseId, amount: run.amount, requiredLevels: run.requiredLevels, }); return run; } function getRunOrThrow(runId: string): MockRun { const run = getStore().runs.get(runId); if (!run) { throw new MockApprovalError("RUN_NOT_FOUND", "Run not found", { attemptedRunId: runId, }); } return run; } function deriveSnapshot(run: MockRun, nowMs: number): MockApprovalSnapshot { const elapsedMs = Math.max(0, nowMs - run.startedAtMs); const levels = ROLE_ORDER.map((role) => createBaseLevelSnapshot(role, run.expenseId, run.requiredLevels.includes(role)) ); const byRole = new Map(levels.map((level) => [level.role, level])); const history: MockHistoryEvent[] = [ createHistoryEvent({ kind: "started", role: null, atMs: 0, message: `Expense ${run.expenseId} submitted for approval`, }), ]; const escalationTimestamps: Array<{ role: ApprovalRole; atMs: number }> = []; let status: RunStatus = "running"; let currentLevelRole: ApprovalRole | null = null; let currentLevelToken: string | null = null; let currentCountdownMs = 0; let cursorMs = run.startedAtMs; for (let index = 0; index < run.requiredLevels.length; index += 1) { const role = run.requiredLevels[index]!; const level = byRole.get(role)!; const enteredAtMs = cursorMs + STEP_DELAY_MS; level.enteredAtMs = enteredAtMs; if (nowMs < enteredAtMs) { break; } history.push( createHistoryEvent({ kind: "entered", role, atMs: enteredAtMs - run.startedAtMs, message: `${level.label} approval requested`, }) ); const deadlineMs = enteredAtMs + level.timeoutMs; const decision = run.decisions[role]; if (decision) { level.decisionRequestedAtMs = decision.requestedAtMs; const decisionCanApply = decision.effectiveAtMs <= nowMs && decision.effectiveAtMs <= deadlineMs; if (decisionCanApply) { level.resolvedAtMs = decision.effectiveAtMs; level.countdownMs = 0; if (decision.decision === "approve") { level.status = "approved"; status = "approved"; history.push( createHistoryEvent({ kind: "approved", role, atMs: decision.effectiveAtMs - run.startedAtMs, message: `${level.label} approved the expense`, }) ); history.push( createHistoryEvent({ kind: "completed", role, atMs: decision.effectiveAtMs - run.startedAtMs, message: "Workflow completed with approval", }) ); break; } level.status = "rejected"; status = "rejected"; history.push( createHistoryEvent({ kind: "rejected", role, atMs: decision.effectiveAtMs - run.startedAtMs, message: `${level.label} rejected the expense`, }) ); history.push( createHistoryEvent({ kind: "completed", role, atMs: decision.effectiveAtMs - run.startedAtMs, message: "Workflow stopped after rejection", }) ); break; } level.pendingDecision = decision.decision; } if (nowMs >= deadlineMs) { level.status = "timed_out"; level.resolvedAtMs = deadlineMs; level.countdownMs = 0; history.push( createHistoryEvent({ kind: "timed_out", role, atMs: deadlineMs - run.startedAtMs, message: `${level.label} timed out`, }) ); const hasNextLevel = index < run.requiredLevels.length - 1; if (!hasNextLevel) { status = "timed_out"; history.push( createHistoryEvent({ kind: "completed", role, atMs: deadlineMs - run.startedAtMs, message: "Workflow finished after all levels timed out", }) ); break; } const escalationAtMs = deadlineMs + STEP_DELAY_MS; level.escalationAtMs = escalationAtMs; escalationTimestamps.push({ role, atMs: escalationAtMs - run.startedAtMs }); if (nowMs >= escalationAtMs) { history.push( createHistoryEvent({ kind: "escalated", role, atMs: escalationAtMs - run.startedAtMs, message: `Auto-escalated from ${level.label}`, }) ); cursorMs = deadlineMs; continue; } break; } level.status = "waiting"; level.countdownMs = Math.max(0, deadlineMs - nowMs); currentLevelRole = role; currentLevelToken = level.token; currentCountdownMs = level.countdownMs; break; } return { runId: run.runId, expenseId: run.expenseId, amount: run.amount, status, elapsedMs, currentLevelRole, currentLevelToken, countdownMs: currentCountdownMs, levels, escalationTimestamps, history, }; } export function getMockSnapshot(runId: string, nowMs: number = Date.now()): MockApprovalSnapshot { const run = getRunOrThrow(runId); return deriveSnapshot(run, nowMs); } export function decideCurrentLevel(input: { runId: string; decision: ApprovalDecision; nowMs?: number; }): MockApprovalSnapshot { const nowMs = input.nowMs ?? Date.now(); const run = getRunOrThrow(input.runId); const snapshot = deriveSnapshot(run, nowMs); if (snapshot.status !== "running") { throw new MockApprovalError("RUN_NOT_ACTIVE", "Run is no longer active", { attemptedRunId: input.runId, runStatus: snapshot.status, attemptedDecision: input.decision, }); } const activeLevel = snapshot.levels.find((level) => level.status === "waiting"); if (!activeLevel) { throw new MockApprovalError("NO_ACTIVE_LEVEL", "No active approval level to resolve", { attemptedRunId: input.runId, attemptedDecision: input.decision, currentLevelRole: snapshot.currentLevelRole, snapshotStatus: snapshot.status, }); } if (run.decisions[activeLevel.role]) { throw new MockApprovalError( "DECISION_ALREADY_SUBMITTED", "A decision is already pending for the current level", { attemptedRunId: input.runId, role: activeLevel.role, attemptedDecision: input.decision, } ); } run.decisions[activeLevel.role] = { decision: input.decision, requestedAtMs: nowMs, effectiveAtMs: nowMs + STEP_DELAY_MS, }; console.info("[approval-chain:mock] level_decision_requested", { runId: input.runId, role: activeLevel.role, decision: input.decision, requestedAtMs: nowMs, effectiveAtMs: nowMs + STEP_DELAY_MS, }); return deriveSnapshot(run, nowMs); } [V0_FILE]typescript:file="app/api/approve/route.ts" import { resumeHook } from "workflow/api"; import type { ApprovalSignal } from "@/workflows/approval-chain"; function createError(status: number, error: string, code: string) { return Response.json( { ok: false, error: { code, message: error, }, }, { status, headers: { "cache-control": "no-store" }, } ); } export async function POST(request: Request) { let body: Record; try { body = await request.json(); } catch { return createError(400, "Invalid JSON body", "INVALID_JSON"); } const token = body.token; const approved = body.approved; const comment = body.comment; const decidedBy = body.decidedBy; if (typeof token !== "string" || token.trim().length === 0) { return createError(400, "token is required", "MISSING_TOKEN"); } if (typeof approved !== "boolean") { return createError(400, "approved must be a boolean", "INVALID_APPROVED_VALUE"); } const payload: ApprovalSignal = { approved, comment: typeof comment === "string" ? comment : undefined, decidedBy: typeof decidedBy === "string" ? decidedBy : undefined, }; try { const result = await resumeHook(token.trim(), payload); if (!result) { return createError(404, "Hook not found or already resolved", "HOOK_NOT_FOUND"); } return Response.json({ ok: true, runId: result.runId, token: token.trim(), approved, comment: payload.comment, decidedBy: payload.decidedBy, }); } catch (error) { const message = error instanceof Error ? error.message : "Failed to resume hook"; return createError(500, message, "HOOK_RESUME_FAILED"); } } [V0_FILE]typescript:file="app/api/approval-chain/route.ts" import { start } from "workflow/api"; import { approvalChain } from "@/workflows/approval-chain"; function createError(status: number, error: string, code: string) { return Response.json( { ok: false, error: { code, message: error, }, }, { status, headers: { "cache-control": "no-store" }, } ); } function createExpenseId() { return `exp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`; } export async function POST(request: Request) { let body: Record; try { body = await request.json(); } catch { return createError(400, "Invalid JSON body", "INVALID_JSON"); } const amount = body.amount; const expenseId = body.expenseId; if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) { return createError(400, "amount must be a positive number", "INVALID_AMOUNT"); } if ( expenseId !== undefined && (typeof expenseId !== "string" || expenseId.trim().length === 0) ) { return createError(400, "expenseId must be a non-empty string", "INVALID_EXPENSE_ID"); } const normalizedExpenseId = typeof expenseId === "string" ? expenseId.trim() : createExpenseId(); try { const run = await start(approvalChain, [normalizedExpenseId, amount]); return Response.json({ ok: true, runId: run.runId, expenseId: normalizedExpenseId, amount, }); } catch (error) { const message = error instanceof Error ? error.message : "Failed to start workflow"; return createError(500, message, "WORKFLOW_START_FAILED"); } } [V0_FILE]typescriptreact:file="app/page.tsx" import { highlightCodeToHtmlLines } from "@/components/code-highlight-server"; import { ApprovalChainDemo } from "./components/demo"; const directiveUseWorkflow = `"use ${"workflow"}"`; const directiveUseStep = `"use ${"step"}"`; type ApprovalWorkflowLineMap = { loop: number[]; notify: number[]; race: number[]; timeout: number[]; approve: number[]; reject: number[]; expire: number[]; }; type ApprovalStepLineMap = { notify: number[]; timeout: number[]; approve: number[]; reject: number[]; }; const workflowCode = `import { defineHook, sleep } from "workflow"; export async function approvalChain(expenseId: string, amount: number) { ${directiveUseWorkflow}; const levels = getApprovalLevelsForAmount(amount); for (const level of levels) { await notifyLevel(expenseId, level.role); const levelHook = defineHook(); const hook = levelHook.create({ token: \`approval:\${expenseId}:\${level.role}\`, }); const result = await Promise.race([ hook.then((payload) => ({ type: "decision" as const, payload })), sleep(level.timeout).then(() => ({ type: "timeout" as const })), ]); if (result.type === "timeout") { await recordTimeout(expenseId, level.role); continue; } if (!result.payload.approved) { await rejectExpense(expenseId, level.role); return { status: "rejected" as const }; } await approveExpense(expenseId, level.role); return { status: "approved" as const }; } await expireExpense(expenseId); return { status: "timed_out" as const }; }`; const stepCode = `async function notifyLevel(expenseId: string, role: ApprovalRole) { ${directiveUseStep}; console.info("[approval-chain] notify_level", { expenseId, role, token: \`approval:\${expenseId}:\${role}\`, }); } async function recordTimeout(expenseId: string, role: ApprovalRole) { ${directiveUseStep}; console.info("[approval-chain] level_timeout", { expenseId, role, }); } async function approveExpense(expenseId: string, role: ApprovalRole) { ${directiveUseStep}; console.info("[approval-chain] expense_approved", { expenseId, role, }); } async function rejectExpense(expenseId: string, role: ApprovalRole) { ${directiveUseStep}; console.info("[approval-chain] expense_rejected", { expenseId, role, }); }`; function findLines(code: string, includes: string): number[] { return code .split("\n") .map((line, idx) => (line.includes(includes) ? idx + 1 : null)) .filter((line): line is number => line !== null); } function buildWorkflowLineMap(code: string): ApprovalWorkflowLineMap { return { loop: findLines(code, "for (const level of levels)"), notify: findLines(code, "await notifyLevel("), race: findLines(code, "const result = await Promise.race"), timeout: findLines(code, 'if (result.type === "timeout")'), approve: findLines(code, "await approveExpense("), reject: findLines(code, "await rejectExpense("), expire: findLines(code, "await expireExpense("), }; } function buildStepLineMap(code: string): ApprovalStepLineMap { return { notify: findLines(code, 'console.info("[approval-chain] notify_level"'), timeout: findLines(code, 'console.info("[approval-chain] level_timeout"'), approve: findLines(code, 'console.info("[approval-chain] expense_approved"'), reject: findLines(code, 'console.info("[approval-chain] expense_rejected"'), }; } const workflowHtmlLines = highlightCodeToHtmlLines(workflowCode); const stepHtmlLines = highlightCodeToHtmlLines(stepCode); const workflowLineMap = buildWorkflowLineMap(workflowCode); const stepLineMap = buildStepLineMap(stepCode); export default function Home() { return (

Workflow DevKit Example

Approval Chain

Route high-value expenses through multi-level approvals with deterministic hook tokens. This workflow runs defineHook() inside a for loop and races each level's decision against a per-level timeout using Promise.race().

Try It

); } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @theme { --color-background-100: #0a0a0a; --color-background-200: #171717; --color-gray-100: #1a1a1a; --color-gray-200: #1f1f1f; --color-gray-300: #292929; --color-gray-400: #737373; --color-gray-500: #525252; --color-gray-600: #404040; --color-gray-700: #262626; --color-gray-800: #171717; --color-gray-900: #a1a1a1; --color-gray-1000: #ededed; --color-blue-700: #0070F3; --color-red-700: #E5484D; --color-amber-700: #FFB224; --color-green-700: #46A758; --color-violet-700: #8B5CF6; --color-cyan-700: #06B6D4; --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } body { background: #0a0a0a; color: #ededed; font-family: var(--font-sans), -apple-system, BlinkMacSystemFont, sans-serif; } /* sugar-high syntax tokens */ :root, .dark { --sh-class: #52a8ff; --sh-identifier: #ededed; --sh-sign: #a1a1a1; --sh-property: #ff6166; --sh-entity: #62c073; --sh-jsxliterals: #ededed; --sh-string: #62c073; --sh-keyword: #f75f8f; --sh-comment: #a1a1a1; } /* Prism token colors - Geist dark-mode palette Extracted from vercel.com/geist/code-block (dark theme) */ .token.keyword, .token.keyword.control-flow { color: #f75f8f; } /* pink - keywords */ .token.plain, .token.parameter, .token.punctuation, .token.plain-text, .token.property-access, .token.operator, .token.tag.punctuation { color: #ededed; } /* gray-1000 - plain text */ .token.function, .token.function.maybe-class-name { color: #bf7af0; } /* purple - functions */ .token.tag { color: #62c073; } /* green - JSX/HTML tags */ .token.literal-property.property { color: #ff6166; } /* red - properties */ .token.string, .token.boolean { color: #62c073; } /* green - strings, booleans */ .token.comment { color: #a1a1a1; } /* gray-900 - comments */ .token.class-name { color: #52a8ff; } /* blue - types */ .token.number { color: #62c073; } /* green - numbers */ .token.attr-name { color: #ff6166; } /* red - attribute names */ .token.attr-value { color: #62c073; } /* green - attribute values */ .token.builtin { color: #52a8ff; } /* blue - builtins */ .token.template-string { color: #62c073; } /* green - template literals */ .token.interpolation { color: #ededed; } /* gray-1000 - interpolation */ [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; [V0_FILE]typescript:file="workflows/approval-chain.ts" import { defineHook, sleep } from "workflow"; export type ApprovalRole = "manager" | "director" | "vp"; export type ApprovalSignal = { approved: boolean; comment?: string; decidedBy?: string; }; type ApprovalLevel = { role: ApprovalRole; timeout: "10s" | "8s" | "6s"; }; const LEVEL_CHAIN: readonly ApprovalLevel[] = [ { role: "manager", timeout: "10s" }, { role: "director", timeout: "8s" }, { role: "vp", timeout: "6s" }, ] as const; export function getApprovalLevelsForAmount(amount: number): ApprovalLevel[] { if (amount < 500) return [LEVEL_CHAIN[0]]; if (amount < 5000) return [LEVEL_CHAIN[0], LEVEL_CHAIN[1]]; return [...LEVEL_CHAIN]; } export async function approvalChain(expenseId: string, amount: number) { "use workflow"; const levels = getApprovalLevelsForAmount(amount); await submitExpense(expenseId, amount, levels.map((level) => level.role)); for (const level of levels) { await notifyLevel(expenseId, level.role); const levelHook = defineHook(); const hook = levelHook.create({ token: `approval:${expenseId}:${level.role}`, }); const result = await Promise.race([ hook.then((payload) => ({ type: "decision" as const, payload })), sleep(level.timeout).then(() => ({ type: "timeout" as const })), ]); if (result.type === "timeout") { await recordTimeout(expenseId, level.role); continue; } if (!result.payload.approved) { await rejectExpense(expenseId, level.role, result.payload.comment); return { expenseId, amount, status: "rejected" as const, decidedBy: level.role, comment: result.payload.comment, }; } await approveExpense(expenseId, level.role, result.payload.comment); return { expenseId, amount, status: "approved" as const, decidedBy: level.role, comment: result.payload.comment, }; } await expireExpense(expenseId); return { expenseId, amount, status: "timed_out" as const, }; } async function submitExpense(expenseId: string, amount: number, levels: ApprovalRole[]) { "use step"; console.info("[approval-chain] submit_expense", { expenseId, amount, levels, }); } async function notifyLevel(expenseId: string, role: ApprovalRole) { "use step"; console.info("[approval-chain] notify_level", { expenseId, role, token: `approval:${expenseId}:${role}`, }); } async function recordTimeout(expenseId: string, role: ApprovalRole) { "use step"; console.info("[approval-chain] level_timeout", { expenseId, role, }); } async function approveExpense(expenseId: string, role: ApprovalRole, comment?: string) { "use step"; console.info("[approval-chain] expense_approved", { expenseId, role, comment, }); } async function rejectExpense(expenseId: string, role: ApprovalRole, comment?: string) { "use step"; console.info("[approval-chain] expense_rejected", { expenseId, role, comment, }); } async function expireExpense(expenseId: string) { "use step"; console.info("[approval-chain] expense_timed_out", { expenseId, }); } [V0_FILE]typescript:file="components/code-highlight-server.ts" import { highlight } from "sugar-high"; export function highlightCodeToHtmlLines(code: string): string[] { const html = highlight(code); return html.split("\n").map((line) => (line.length === 0 ? " " : line)); } [V0_FILE]typescriptreact:file="components/approval-chain-code-workbench.tsx" "use client"; import { useCallback, useMemo, useRef, useState } from "react"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type GutterMarkKind = "success" | "fail"; type CodePaneProps = { filename: string; label: "use workflow" | "use step"; code: string; htmlLines: string[]; activeLines: number[]; gutterMarks: Record; tone: HighlightTone; }; export type ApprovalChainCodeWorkbenchProps = { workflowCode: string; workflowHtmlLines: string[]; workflowActiveLines: number[]; workflowGutterMarks: Record; stepCode: string; stepHtmlLines: string[]; stepActiveLines: number[]; stepGutterMarks: Record; tone: HighlightTone; }; function getToneClasses(tone: HighlightTone) { switch (tone) { case "green": return { line: "border-l-2 border-green-700 bg-green-700/15", gutter: "text-green-700", }; case "red": return { line: "border-l-2 border-red-700 bg-red-700/15", gutter: "text-red-700", }; case "cyan": return { line: "border-l-2 border-cyan-700 bg-cyan-700/15", gutter: "text-cyan-700", }; case "amber": default: return { line: "border-l-2 border-amber-700 bg-amber-700/15", gutter: "text-amber-700", }; } } function GutterIcon({ kind }: { kind: GutterMarkKind }) { if (kind === "success") { return ( ); } return ( ); } function CodePane({ filename, label, code, htmlLines, activeLines, gutterMarks, tone, }: CodePaneProps) { const [copyState, setCopyState] = useState<"idle" | "copied">("idle"); const activeLineSet = useMemo(() => new Set(activeLines), [activeLines]); const previousMarksRef = useRef>({}); const toneClasses = getToneClasses(tone); const handleCopy = useCallback(async () => { try { await navigator.clipboard.writeText(code); setCopyState("copied"); window.setTimeout(() => setCopyState("idle"), 900); } catch { // Ignore clipboard errors. } }, [code]); for (const [lineKey, mark] of Object.entries(gutterMarks)) { const line = Number(lineKey); if (!Number.isNaN(line)) { previousMarksRef.current[line] = mark; } } return (

{filename}

{label}

          {htmlLines.map((lineHtml, index) => {
            const lineNo = index + 1;
            const currentMark = gutterMarks[lineNo];
            const previousMark = previousMarksRef.current[lineNo];
            const markToRender = currentMark ?? previousMark;
            const showMark = Boolean(currentMark);
            const isActive = activeLineSet.has(lineNo);

            return (
              
                
                  {lineNo}
                

                
                  {markToRender ? (
                    
                      
                    
                  ) : null}
                

                
              
            );
          })}

); } export function ApprovalChainCodeWorkbench({ workflowCode, workflowHtmlLines, workflowActiveLines, workflowGutterMarks, stepCode, stepHtmlLines, stepActiveLines, stepGutterMarks, tone, }: ApprovalChainCodeWorkbenchProps) { return (

); } [V0_FILE]json:file="package.json" { "name": "approval-chain", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "16.0.10", "react": "19.2.3", "react-dom": "19.2.3", "sugar-high": "^0.9.5", "workflow": "4.1.0-beta.53" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5" } } [V0_FILE]json:file="tsconfig.json" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "react-jsx", "incremental": true, "plugins": [ { "name": "next" }, { "name": "workflow" } ], "paths": { "@/*": ["./*"] } }, "include": [ "next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", "**/*.mts" ], "exclude": ["node_modules"] } [V0_FILE]typescript:file="next.config.ts" import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = {}; export default withWorkflow(nextConfig);