@voyantjs/workflow-runs 0.41.3 → 0.44.0

package/README.md

@@ -29,7 +29,7 @@ export function WorkflowsRoute() {
 
 ## Mount the admin routes
 
-`mountWorkflowRunsAdminRoutes` adds the workflow-run list, detail, rerun, and resume endpoints under `/v1/admin/workflow-runs`.
+`mountWorkflowRunsAdminRoutes` adds the workflow-run list, detail, rerun, and resume endpoints under `/v1/admin/workflow-runs`, plus an explicit trigger endpoint at `POST /v1/admin/workflows/:name/runs`.
 
 ```ts
 import { mountWorkflowRunsAdminRoutes, WorkflowRunnerRegistry } from "@voyantjs/workflow-runs"
@@ -45,6 +45,15 @@ workflowRunnerRegistry.register({
   idempotency: "unsafe",
   description:
     "Confirms the booking and issues the final invoice. Use Resume to retry from a failed step.",
+  trigger: async (input, ctx) => {
+    const saved = await workflowServer.trigger({
+      workflowId: "checkout-finalize",
+      input,
+      tags: ctx.tags,
+      triggeredByUserId: ctx.triggeredByUserId,
+    })
+    return { runId: saved.id }
+  },
   rerun: async (input, ctx) => {
     const saved = await workflowServer.trigger({
       workflowId: "checkout-finalize",
@@ -71,6 +80,32 @@ mountWorkflowRunsAdminRoutes(hono, {
 })
 ```
 
+Triggerable workflows must opt in by implementing `trigger(...)` on their registered runner. This keeps rerun/resume-only workflows closed to arbitrary admin dispatch while still allowing operators, cron jobs, queues, and API keys with `workflows:trigger` permission to call:
+
+```http
+POST /v1/admin/workflows/checkout-finalize/runs
+Content-Type: application/json
+
+{
+  "input": { "bookingId": "bk_123" },
+  "idempotencyKey": "checkout-finalize:bk_123",
+  "correlationId": "bk_123",
+  "tags": ["source:admin"]
+}
+```
+
+The route returns `202 Accepted` with the queued run id:
+
+```json
+{
+  "data": {
+    "runId": "wfrn_...",
+    "workflowName": "checkout-finalize",
+    "status": "queued"
+  }
+}
+```
+
 For self-hosted workflow services, keep runner registration close to the code that mounts the workflow service. The registry should dispatch to your external workflow server instead of importing worker-only runtime code into the admin API process. The resume path sends `ctx.resumeFromStep` plus `ctx.seedResults`; the self-host server starts a new run, pre-populates the journal with the seeded step outputs, and executes from the failed step onward.
 
 ## Record `@voyantjs/workflows` executions
@@ -117,6 +152,6 @@ export const syncCatalogWorkflow = recordedWorkflow(
 )
 ```
 
-This helper only records observability data. Rerun and resume support still uses
-`WorkflowRunnerRegistry` registration so apps can choose which workflows are
-safe to dispatch from the admin UI.
+This helper only records observability data. Trigger, rerun, and resume support
+still uses `WorkflowRunnerRegistry` registration so apps can choose which
+workflows are safe to dispatch from the admin UI.

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  */
 export { type BeginWorkflowRunInput, beginWorkflowRun, type WorkflowRunRecorder, } from "./recorder.js";
 export { mountWorkflowRunsAdminRoutes } from "./routes.js";
-export { type WorkflowIdempotency, type WorkflowRerunContext, type WorkflowResumeContext, type WorkflowRunner, WorkflowRunnerRegistry, } from "./runner.js";
+export { type WorkflowIdempotency, type WorkflowRerunContext, type WorkflowResumeContext, type WorkflowRunner, WorkflowRunnerRegistry, type WorkflowTriggerContext, } from "./runner.js";
 export { type NewWorkflowRun, type NewWorkflowRunStep, type WorkflowRun, type WorkflowRunErrorPayload, type WorkflowRunStep, workflowRunStatusEnum, workflowRunStepStatusEnum, workflowRunSteps, workflowRuns, } from "./schema.js";
 export { type ListWorkflowRunsQuery, type ListWorkflowRunsResult, workflowRunsService, } from "./service.js";
 export { type RecordedWorkflowOptions, type RecordedWorkflowResultContext, type RecordedWorkflowRunContext, recordedWorkflow, } from "./workflows.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,sBAAsB,GACvB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,gBAAgB,GACjB,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,gBAAgB,GACjB,MAAM,gBAAgB,CAAA"}

package/dist/routes.d.ts

@@ -3,6 +3,7 @@
  *
  *   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
  *

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAGhC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAiBzD,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;CAC9C;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,mCAAwC,GAC7C,IAAI,CA0NN"}
+{"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;AA2CzD,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;CAC9C;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,mCAAwC,GAC7C,IAAI,CAsRN"}

package/dist/routes.js

@@ -3,6 +3,7 @@
  *
  *   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
  *
@@ -13,6 +14,7 @@
  * provided (or doesn't have a runner for the workflow), those
  * endpoints return 501 with a clear error.
  */
+import { handleApiError, parseJsonBody } from "@voyantjs/hono";
 import { z } from "zod";
 import { workflowRunsService } from "./service.js";
 const listQuerySchema = z.object({
@@ -27,6 +29,27 @@ 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();
+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 = {}) {
     hono.get("/v1/admin/workflow-runs", async (c) => {
         const params = Object.fromEntries(new URL(c.req.url).searchParams);
@@ -71,6 +94,51 @@ export function mountWorkflowRunsAdminRoutes(hono, opts = {}) {
             }, 500);
         }
     });
+    hono.post("/v1/admin/workflows/:name/runs", async (c) => {
+        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) => {
         // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed
         const db = c.var.db;

package/dist/runner.d.ts

@@ -45,6 +45,16 @@ export interface WorkflowResumeContext extends WorkflowRerunContext {
      */
     seedResults: Record<string, unknown>;
 }
+export interface WorkflowTriggerContext {
+    /** User or API key actor that triggered the workflow, when available. */
+    triggeredByUserId: string | null;
+    /** Optional correlation id supplied by the caller. */
+    correlationId: string | null;
+    /** Tags supplied by the caller for observability and filtering. */
+    tags: ReadonlyArray<string>;
+    /** Optional caller-supplied idempotency key forwarded to the runner. */
+    idempotencyKey: string | null;
+}
 export interface WorkflowRunner {
     /** Workflow name — must match `workflow_runs.workflow_name`. */
     name: string;
@@ -55,6 +65,14 @@ export interface WorkflowRunner {
     idempotency: WorkflowIdempotency;
     /** Human-friendly label shown in the rerun confirm dialog. */
     description?: string;
+    /**
+     * Trigger the workflow by name from an admin/internal route. Runners that
+     * expose this method are intentionally triggerable; missing methods keep
+     * rerun/resume-only workflows closed to arbitrary dispatch.
+     */
+    trigger?(input: unknown, ctx: WorkflowTriggerContext): Promise<{
+        runId: string;
+    }>;
     /**
      * Run the workflow fresh with the recorded input. Returns the new
      * run's id (the recorder's `runId`).

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;AAEnE,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAA;IACnB,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,sFAAsF;IACtF,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC5B;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,WAAW,EAAE,mBAAmB,CAAA;IAChC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5E;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACrF;AAED;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAOtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAIxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,aAAa,CAAC,cAAc,CAAC;CAGtC"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;AAEnE,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAA;IACnB,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,sFAAsF;IACtF,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC5B;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,sDAAsD;IACtD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,mEAAmE;IACnE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC3B,wEAAwE;IACxE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,WAAW,EAAE,mBAAmB,CAAA;IAChC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjF;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5E;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACrF;AAED;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAOtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAIxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,aAAa,CAAC,cAAc,CAAC;CAGtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflow-runs",
-  "version": "0.41.3",
+  "version": "0.44.0",
   "description": "Workflow run recording, admin routes, and rerun/resume dispatch primitives for Voyant operator apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -40,16 +40,16 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.41.3",
-    "@voyantjs/db": "0.41.3",
-    "@voyantjs/hono": "0.41.3",
-    "@voyantjs/workflows": "0.41.3"
+    "@voyantjs/core": "0.44.0",
+    "@voyantjs/db": "0.44.0",
+    "@voyantjs/hono": "0.44.0",
+    "@voyantjs/workflows": "0.44.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
     "@voyantjs/voyant-typescript-config": "0.1.0",
-    "@voyantjs/workflows-orchestrator": "0.41.3"
+    "@voyantjs/workflows-orchestrator": "0.44.0"
   },
   "files": [
     "dist"