@voyant-travel/workflow-runs 0.107.10

package/dist/recorder.js

@@ -0,0 +1,242 @@
+/**
+ * Recorder API — wraps an in-process workflow run with start / step
+ * lifecycle / finish writes against the `workflow_runs` +
+ * `workflow_run_steps` tables.
+ *
+ * Designed for the `@voyant-travel/core/workflows` saga primitive:
+ * callers do
+ *
+ *   const recorder = await beginWorkflowRun(db, { workflowName, ... })
+ *   try {
+ *     const result = await runFn(recorder)
+ *     await recorder.complete(result)
+ *   } catch (err) {
+ *     await recorder.fail(err)
+ *     throw err
+ *   }
+ *
+ * — and inside `runFn` the caller (or, more naturally, an
+ * instrumented version of `runCheckoutFinalize`) calls
+ * `recorder.startStep(name)` / `recorder.completeStep(name, output)` /
+ * `recorder.failStep(name, error)` per step.
+ *
+ * The recorder is fire-and-forget around the actual run — it logs
+ * persistence failures rather than rethrowing, so observability
+ * outages never break the underlying business operation.
+ */
+import { and, desc, eq } from "drizzle-orm";
+import { workflowRunSteps, workflowRuns, } from "./schema.js";
+/**
+ * Start a run and return a recorder bound to its id. The row is
+ * inserted with `status: "running"` and a `startedAt` of "now".
+ *
+ * Persistence errors are caught — if the table doesn't exist or the
+ * DB is unreachable, returns a no-op recorder so the caller's
+ * workflow keeps running. The whole point of this layer is
+ * observability, not durability.
+ */
+export async function beginWorkflowRun(db, input, options = {}) {
+    if (options.reuseRunningRun && input.correlationId) {
+        const existingRunId = await findRunningWorkflowRun(db, input);
+        if (existingRunId)
+            return workflowRunRecorder(db, existingRunId);
+    }
+    const insert = {
+        workflowName: input.workflowName,
+        trigger: input.trigger ?? "manual",
+        correlationId: input.correlationId ?? null,
+        tags: [...(input.tags ?? [])],
+        input: input.input ?? null,
+        status: "running",
+        parentRunId: input.parentRunId ?? null,
+        triggeredByUserId: input.triggeredByUserId ?? null,
+        resumeFromStep: input.resumeFromStep ?? null,
+    };
+    let runId = null;
+    try {
+        const [row] = await db.insert(workflowRuns).values(insert).returning({ id: workflowRuns.id });
+        runId = row?.id ?? null;
+    }
+    catch (err) {
+        console.warn(`[workflow-runs] could not record run start for "${input.workflowName}":`, err instanceof Error ? err.message : err);
+    }
+    if (!runId)
+        return noopRecorder();
+    return workflowRunRecorder(db, runId);
+}
+async function findRunningWorkflowRun(db, input) {
+    const correlationId = input.correlationId;
+    if (!correlationId)
+        return null;
+    try {
+        const [row] = await db
+            .select({ id: workflowRuns.id })
+            .from(workflowRuns)
+            .where(and(eq(workflowRuns.workflowName, input.workflowName), eq(workflowRuns.correlationId, correlationId), eq(workflowRuns.status, "running")))
+            .orderBy(desc(workflowRuns.startedAt))
+            .limit(1);
+        return row?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function workflowRunRecorder(db, runId) {
+    const stepStarts = new Map();
+    let nextSequence = 1;
+    return {
+        runId,
+        async startStep(name) {
+            const sequence = nextSequence++;
+            const insertStep = {
+                runId,
+                stepName: name,
+                sequence,
+                status: "running",
+            };
+            try {
+                const [row] = await db
+                    .insert(workflowRunSteps)
+                    .values(insertStep)
+                    .returning({ id: workflowRunSteps.id });
+                if (row?.id) {
+                    stepStarts.set(name, { stepId: row.id, sequence, startedAt: Date.now() });
+                    return { stepId: row.id };
+                }
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step start "${name}" insert failed:`, err);
+            }
+            return { stepId: null };
+        },
+        async completeStep(name, output) {
+            const tracking = stepStarts.get(name);
+            if (!tracking)
+                return;
+            const completedAt = new Date();
+            try {
+                await db
+                    .update(workflowRunSteps)
+                    .set({
+                    status: "succeeded",
+                    output: output ?? null,
+                    completedAt,
+                    durationMs: completedAt.getTime() - tracking.startedAt,
+                })
+                    .where(eq(workflowRunSteps.id, tracking.stepId));
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step complete "${name}" update failed:`, err);
+            }
+        },
+        async failStep(name, error) {
+            const tracking = stepStarts.get(name);
+            if (!tracking)
+                return;
+            const completedAt = new Date();
+            try {
+                await db
+                    .update(workflowRunSteps)
+                    .set({
+                    status: "failed",
+                    error: serializeError(error, name),
+                    completedAt,
+                    durationMs: completedAt.getTime() - tracking.startedAt,
+                })
+                    .where(eq(workflowRunSteps.id, tracking.stepId));
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step fail "${name}" update failed:`, err);
+            }
+        },
+        async recordSkippedStep(name, output) {
+            const sequence = nextSequence++;
+            const now = new Date();
+            const insertStep = {
+                runId,
+                stepName: name,
+                sequence,
+                status: "skipped",
+                output: output ?? null,
+                startedAt: now,
+                completedAt: now,
+                durationMs: 0,
+            };
+            try {
+                await db.insert(workflowRunSteps).values(insertStep);
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step skipped "${name}" insert failed:`, err);
+            }
+        },
+        complete: (result) => finalize(db, runId, "succeeded", result, null),
+        fail: (error, opts) => finalize(db, runId, "failed", null, serializeError(error, opts?.stepName)),
+        cancel: (reason) => finalize(db, runId, "cancelled", null, {
+            message: reason ?? "Cancelled",
+        }),
+    };
+}
+async function finalize(db, runId, status, result, error) {
+    const completedAt = new Date();
+    try {
+        const [existing] = await db
+            .select({ startedAt: workflowRuns.startedAt })
+            .from(workflowRuns)
+            .where(eq(workflowRuns.id, runId))
+            .limit(1);
+        const durationMs = existing ? completedAt.getTime() - existing.startedAt.getTime() : null;
+        await db
+            .update(workflowRuns)
+            .set({
+            status,
+            result: result ?? null,
+            error: error ?? null,
+            completedAt,
+            durationMs,
+            updatedAt: completedAt,
+        })
+            .where(eq(workflowRuns.id, runId));
+    }
+    catch (err) {
+        console.warn(`[workflow-runs] finalize ${status} failed for ${runId}:`, err);
+    }
+}
+function serializeError(error, stepName) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            ...(stepName ? { stepName } : {}),
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return {
+        message: typeof error === "string" ? error : JSON.stringify(error),
+        ...(stepName ? { stepName } : {}),
+    };
+}
+function noopRecorder() {
+    return {
+        runId: "",
+        async startStep() {
+            return { stepId: null };
+        },
+        async completeStep() {
+            // no-op
+        },
+        async failStep() {
+            // no-op
+        },
+        async recordSkippedStep() {
+            // no-op
+        },
+        async complete() {
+            // no-op
+        },
+        async fail() {
+            // no-op
+        },
+        async cancel() {
+            // no-op
+        },
+    };
+}

package/dist/routes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hono routes for the workflow-runs admin surface.
+ *
+ *   GET  /v1/admin/workflow-runs          → list (filter by workflow / status / tag)
+ *   GET  /v1/admin/workflow-runs/:id      → run + ordered steps
+ *   POST /v1/admin/workflows/:name/runs   → trigger registered workflow by name
+ *   POST /v1/admin/workflow-runs/:id/rerun  → fresh run with the recorded input
+ *   POST /v1/admin/workflow-runs/:id/resume → re-run starting at the failed step
+ *
+ * Templates mount via `mountWorkflowRunsAdminRoutes(hono, opts)` —
+ * the routes are attached directly to the supplied Hono instance so
+ * they inherit the parent's middleware (auth + db). The optional
+ * `runners` registry is consulted for rerun/resume; if it's not
+ * provided (or doesn't have a runner for the workflow), those
+ * endpoints return 501 with a clear error.
+ */
+import type { Hono } from "hono";
+import type { WorkflowRunnerRegistry } from "./runner.js";
+export type WorkflowAdminSurface = "tenant" | "cloud" | "disabled";
+export declare function resolveWorkflowAdminSurface(value: string | undefined): WorkflowAdminSurface;
+export interface MountWorkflowRunsAdminRoutesOptions {
+    /**
+     * Registry of executable runners keyed by workflow name. Required
+     * for the rerun/resume endpoints; bundles register their runners
+     * on bootstrap.
+     */
+    runners?: WorkflowRunnerRegistry;
+    /**
+     * Resolves the acting user id from the request context — used to
+     * stamp `triggered_by_user_id` on rerun runs. When omitted, runs
+     * are recorded without an actor.
+     */
+    resolveUserId?: (c: unknown) => string | null;
+    /**
+     * Controls whether tenant-admin workflow management actions are exposed.
+     * `tenant` preserves local/self-host behavior. `cloud` and `disabled`
+     * reject tenant-admin trigger/rerun/resume routes server-side while leaving
+     * read paths mounted for observability consumers that still need them.
+     */
+    adminSurface?: WorkflowAdminSurface;
+}
+export declare function mountWorkflowRunsAdminRoutes(hono: Hono, opts?: MountWorkflowRunsAdminRoutesOptions): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAGhC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AA0BzD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAA;AAElE,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,CAQ3F;AAmBD,MAAM,WAAW,mCAAmC;IAClD;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAA;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAA;IAC7C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAA;CACpC;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,mCAAwC,GAC7C,IAAI,CAiSN"}

package/dist/routes.js

@@ -0,0 +1,311 @@
+/**
+ * Hono routes for the workflow-runs admin surface.
+ *
+ *   GET  /v1/admin/workflow-runs          → list (filter by workflow / status / tag)
+ *   GET  /v1/admin/workflow-runs/:id      → run + ordered steps
+ *   POST /v1/admin/workflows/:name/runs   → trigger registered workflow by name
+ *   POST /v1/admin/workflow-runs/:id/rerun  → fresh run with the recorded input
+ *   POST /v1/admin/workflow-runs/:id/resume → re-run starting at the failed step
+ *
+ * Templates mount via `mountWorkflowRunsAdminRoutes(hono, opts)` —
+ * the routes are attached directly to the supplied Hono instance so
+ * they inherit the parent's middleware (auth + db). The optional
+ * `runners` registry is consulted for rerun/resume; if it's not
+ * provided (or doesn't have a runner for the workflow), those
+ * endpoints return 501 with a clear error.
+ */
+import { handleApiError, parseJsonBody } from "@voyant-travel/hono";
+import { z } from "zod";
+import { workflowRunsService } from "./service.js";
+const listQuerySchema = z.object({
+    workflowName: z.string().min(1).optional(),
+    status: z.enum(["running", "succeeded", "failed", "cancelled"]).optional(),
+    tag: z.string().min(1).optional(),
+    parentRunId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+});
+const rerunBodySchema = z.object({
+    /** Required when runner.idempotency === "unsafe". */
+    confirm: z.boolean().optional(),
+});
+const triggerWorkflowBodySchema = z
+    .object({
+    input: z.unknown().optional(),
+    idempotencyKey: z.string().trim().min(1).max(255).optional(),
+    correlationId: z.string().trim().min(1).max(255).optional(),
+    tags: z.array(z.string().trim().min(1).max(128)).max(50).optional(),
+})
+    .strict();
+export function resolveWorkflowAdminSurface(value) {
+    if (value === "tenant" || value === "cloud" || value === "disabled")
+        return value;
+    if (value !== undefined && value.trim().length > 0) {
+        throw new Error(`Invalid workflow admin surface "${value}". Expected tenant, cloud, or disabled.`);
+    }
+    return "tenant";
+}
+function hasWorkflowTriggerScope(scopes) {
+    if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string")) {
+        return false;
+    }
+    return scopes.some((scope) => {
+        const normalized = scope.trim().toLowerCase();
+        return (normalized === "*" ||
+            normalized === "*:*" ||
+            normalized === "*:trigger" ||
+            normalized === "workflows:*" ||
+            normalized === "workflows:trigger");
+    });
+}
+export function mountWorkflowRunsAdminRoutes(hono, opts = {}) {
+    const adminSurface = opts.adminSurface ?? defaultWorkflowAdminSurface();
+    hono.get("/v1/admin/workflow-runs", async (c) => {
+        const params = Object.fromEntries(new URL(c.req.url).searchParams);
+        const parsed = listQuerySchema.safeParse(params);
+        if (!parsed.success) {
+            return c.json({ error: "invalid_query", detail: parsed.error.issues }, 400);
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed -- owner: workflow-runs; existing suppression is intentional pending typed cleanup.
+        const db = c.var.db;
+        if (!db) {
+            console.error("[workflow-runs] c.var.db is undefined — middleware ordering issue?");
+            return c.json({ error: "db_unavailable" }, 500);
+        }
+        try {
+            const result = await workflowRunsService.listRuns(db, parsed.data);
+            return c.json(result);
+        }
+        catch (err) {
+            console.error("[workflow-runs] listRuns failed", err);
+            return c.json({
+                error: "list_failed",
+                detail: err instanceof Error ? err.message : String(err),
+            }, 500);
+        }
+    });
+    hono.get("/v1/admin/workflow-runs/:id", async (c) => {
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed -- owner: workflow-runs; existing suppression is intentional pending typed cleanup.
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        try {
+            const result = await workflowRunsService.getRunById(db, c.req.param("id"));
+            if (!result)
+                return c.json({ error: "not_found" }, 404);
+            return c.json({ data: result });
+        }
+        catch (err) {
+            console.error("[workflow-runs] getRunById failed", err);
+            return c.json({
+                error: "get_failed",
+                detail: err instanceof Error ? err.message : String(err),
+            }, 500);
+        }
+    });
+    hono.post("/v1/admin/workflows/:name/runs", async (c) => {
+        const blocked = rejectWorkflowAdminAction(adminSurface, c);
+        if (blocked)
+            return blocked;
+        if (!opts.runners) {
+            return c.json({ error: "trigger_not_configured", detail: "no WorkflowRunnerRegistry mounted" }, 501);
+        }
+        let body;
+        try {
+            body = await parseJsonBody(c, triggerWorkflowBodySchema);
+        }
+        catch (err) {
+            return handleApiError(err, c);
+        }
+        const workflowName = c.req.param("name");
+        const runner = opts.runners.get(workflowName);
+        if (!runner) {
+            return c.json({
+                error: "runner_not_registered",
+                detail: `No runner registered for workflow "${workflowName}"`,
+            }, 404);
+        }
+        if (!runner.trigger) {
+            return c.json({
+                error: "trigger_not_supported",
+                detail: `Workflow "${runner.name}" does not expose admin trigger support.`,
+            }, 501);
+        }
+        const auth = c;
+        if (auth.get("callerType") === "api_key" && !hasWorkflowTriggerScope(auth.get("scopes"))) {
+            return c.json({ error: "Forbidden: API key missing workflows:trigger permission" }, 403);
+        }
+        const userId = opts.resolveUserId?.(c) ?? null;
+        try {
+            const input = Object.hasOwn(body, "input") ? body.input : {};
+            const { runId } = await runner.trigger(input, {
+                triggeredByUserId: userId,
+                correlationId: body.correlationId ?? null,
+                tags: body.tags ?? [],
+                idempotencyKey: body.idempotencyKey ?? null,
+            });
+            return c.json({ data: { runId, workflowName: runner.name, status: "queued" } }, 202);
+        }
+        catch (err) {
+            console.error("[workflow-runs] trigger failed", err);
+            return c.json({ error: "trigger_failed", detail: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    hono.post("/v1/admin/workflow-runs/:id/rerun", async (c) => {
+        const blocked = rejectWorkflowAdminAction(adminSurface, c);
+        if (blocked)
+            return blocked;
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed -- owner: workflow-runs; existing suppression is intentional pending typed cleanup.
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        if (!opts.runners) {
+            return c.json({ error: "rerun_not_configured", detail: "no WorkflowRunnerRegistry mounted" }, 501);
+        }
+        const parentId = c.req.param("id");
+        const detail = await workflowRunsService.getRunById(db, parentId);
+        if (!detail)
+            return c.json({ error: "not_found" }, 404);
+        const runner = opts.runners.get(detail.run.workflowName);
+        if (!runner) {
+            return c.json({
+                error: "runner_not_registered",
+                detail: `No runner registered for workflow "${detail.run.workflowName}"`,
+            }, 501);
+        }
+        if (runner.idempotency === "resume-only") {
+            return c.json({
+                error: "rerun_not_allowed",
+                detail: `Workflow "${runner.name}" is resume-only; use POST /:id/resume instead.`,
+            }, 409);
+        }
+        let body = {};
+        try {
+            body = rerunBodySchema.parse(await c.req.json().catch(() => ({})));
+        }
+        catch (err) {
+            return c.json({ error: "invalid_body", detail: err instanceof Error ? err.message : String(err) }, 400);
+        }
+        if (runner.idempotency === "unsafe" && !body.confirm) {
+            return c.json({
+                error: "confirmation_required",
+                detail: `Workflow "${runner.name}" has side effects; pass { confirm: true } to rerun.`,
+                idempotency: runner.idempotency,
+            }, 409);
+        }
+        if (runner.canRerun) {
+            const guard = await runner.canRerun(detail.run.input);
+            if (!guard.ok) {
+                return c.json({ error: "rerun_blocked", detail: guard.reason }, 409);
+            }
+        }
+        const userId = opts.resolveUserId?.(c) ?? null;
+        try {
+            const { runId } = await runner.rerun(detail.run.input, {
+                parentRunId: detail.run.id,
+                triggeredByUserId: userId,
+                correlationId: detail.run.correlationId,
+                tags: detail.run.tags,
+            });
+            return c.json({ data: { runId, parentRunId: detail.run.id } }, 202);
+        }
+        catch (err) {
+            console.error("[workflow-runs] rerun failed", err);
+            return c.json({ error: "rerun_failed", detail: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    hono.post("/v1/admin/workflow-runs/:id/resume", async (c) => {
+        const blocked = rejectWorkflowAdminAction(adminSurface, c);
+        if (blocked)
+            return blocked;
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed -- owner: workflow-runs; existing suppression is intentional pending typed cleanup.
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        if (!opts.runners) {
+            return c.json({ error: "resume_not_configured", detail: "no WorkflowRunnerRegistry mounted" }, 501);
+        }
+        const parentId = c.req.param("id");
+        const detail = await workflowRunsService.getRunById(db, parentId);
+        if (!detail)
+            return c.json({ error: "not_found" }, 404);
+        if (detail.run.status !== "failed") {
+            return c.json({
+                error: "resume_not_allowed",
+                detail: `Cannot resume a run with status "${detail.run.status}"; only failed runs are resumable.`,
+            }, 409);
+        }
+        const runner = opts.runners.get(detail.run.workflowName);
+        if (!runner) {
+            return c.json({
+                error: "runner_not_registered",
+                detail: `No runner registered for workflow "${detail.run.workflowName}"`,
+            }, 501);
+        }
+        // Find the failed step and seed prior step outputs.
+        const failedStep = detail.steps.find((s) => s.status === "failed");
+        if (!failedStep) {
+            return c.json({
+                error: "no_failed_step",
+                detail: "Run is marked failed but has no failed step row to resume from.",
+            }, 409);
+        }
+        const seedResults = {};
+        for (const s of detail.steps) {
+            if (s.sequence >= failedStep.sequence)
+                break;
+            if (s.status === "succeeded" || s.status === "skipped") {
+                if (s.output && typeof s.output === "object") {
+                    seedResults[s.stepName] = s.output;
+                }
+                else {
+                    // Preserve null/primitive outputs explicitly so downstream
+                    // steps that read them don't see undefined.
+                    seedResults[s.stepName] = s.output ?? null;
+                }
+            }
+            else {
+                return c.json({
+                    error: "incomplete_prior_step",
+                    detail: `Step "${s.stepName}" (sequence ${s.sequence}) is not complete; cannot resume past it.`,
+                }, 409);
+            }
+        }
+        const userId = opts.resolveUserId?.(c) ?? null;
+        try {
+            const { runId } = await runner.resume(detail.run.input, {
+                parentRunId: detail.run.id,
+                triggeredByUserId: userId,
+                correlationId: detail.run.correlationId,
+                tags: detail.run.tags,
+                resumeFromStep: failedStep.stepName,
+                seedResults,
+            });
+            return c.json({ data: { runId, parentRunId: detail.run.id, resumeFromStep: failedStep.stepName } }, 202);
+        }
+        catch (err) {
+            console.error("[workflow-runs] resume failed", err);
+            return c.json({ error: "resume_failed", detail: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+}
+function rejectWorkflowAdminAction(surface, c) {
+    if (surface === "tenant")
+        return undefined;
+    return c.json({
+        error: "workflow_admin_surface_restricted",
+        detail: surface === "cloud"
+            ? "Workflow management actions are owned by Voyant Cloud for this deployment."
+            : "Workflow management actions are disabled for this deployment.",
+        surface,
+    }, 403);
+}
+function defaultWorkflowAdminSurface() {
+    const env = globalThis.process?.env;
+    if (env?.VOYANT_WORKFLOW_ADMIN_SURFACE !== undefined) {
+        return resolveWorkflowAdminSurface(env.VOYANT_WORKFLOW_ADMIN_SURFACE);
+    }
+    if (env?.VOYANT_CLOUD_WORKFLOWS_URL || env?.VOYANT_CLOUD_APP_SLUG)
+        return "cloud";
+    return "tenant";
+}