@voyantjs/workflows 0.0.0 → 0.6.8

package/src/auth/index.ts

@@ -22,7 +22,7 @@
 //   const verify = await createHmacVerifier(env.VOYANT_SIGNING_KEY);
 //   export default { fetch: createStepHandler({ verifyRequest: verify }) };
 
-export const AUTH_HEADER = "x-voyant-dispatch-auth" as const;
+export const AUTH_HEADER = "x-voyant-dispatch-auth" as const
 
 /**
  * Returns a verifier that accepts `Authorization: Bearer <token>`
@@ -34,45 +34,41 @@ export const AUTH_HEADER = "x-voyant-dispatch-auth" as const;
  * Intended for dev + single-tenant deployments. Production should
  * issue per-tenant, short-lived tokens from a control plane.
  */
-export function createBearerVerifier(
-  validTokens: readonly string[],
-): (req: Request) => void {
+export function createBearerVerifier(validTokens: readonly string[]): (req: Request) => void {
   if (validTokens.length === 0) {
-    throw new Error("createBearerVerifier: need at least one valid token");
+    throw new Error("createBearerVerifier: need at least one valid token")
   }
   return (req) => {
-    const header = req.headers.get("authorization");
-    if (!header) throw new Error("missing Authorization header");
-    const match = /^Bearer (.+)$/.exec(header);
+    const header = req.headers.get("authorization")
+    if (!header) throw new Error("missing Authorization header")
+    const match = /^Bearer (.+)$/.exec(header)
     if (!match) {
-      throw new Error("Authorization header must use the Bearer scheme");
+      throw new Error("Authorization header must use the Bearer scheme")
     }
-    const presented = match[1]!;
+    const presented = match[1]!
     for (const valid of validTokens) {
-      if (constantTimeEquals(presented, valid)) return;
+      if (constantTimeEquals(presented, valid)) return
     }
-    throw new Error("bearer token does not match any configured value");
-  };
+    throw new Error("bearer token does not match any configured value")
+  }
 }
 
 function constantTimeEquals(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
+  if (a.length !== b.length) return false
+  let diff = 0
   for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
   }
-  return diff === 0;
+  return diff === 0
 }
 
 /** Returns a signer: `(body: string) => Promise<string>` (base64 HMAC-SHA256). */
-export async function createHmacSigner(
-  secret: string,
-): Promise<(body: string) => Promise<string>> {
-  const key = await importKey(secret, ["sign"]);
+export async function createHmacSigner(secret: string): Promise<(body: string) => Promise<string>> {
+  const key = await importKey(secret, ["sign"])
   return async (body) => {
-    const sig = await crypto.subtle.sign("HMAC", key, encode(body));
-    return toBase64(sig);
-  };
+    const sig = await crypto.subtle.sign("HMAC", key, encode(body))
+    return toBase64(sig)
+  }
 }
 
 /**
@@ -85,27 +81,25 @@ export async function createHmacSigner(
  * need the body downstream should pre-clone: `req.clone()` before
  * passing in.
  */
-export async function createHmacVerifier(
-  secret: string,
-): Promise<(req: Request) => Promise<void>> {
-  const key = await importKey(secret, ["verify"]);
+export async function createHmacVerifier(secret: string): Promise<(req: Request) => Promise<void>> {
+  const key = await importKey(secret, ["verify"])
   return async (req) => {
-    const header = req.headers.get(AUTH_HEADER);
+    const header = req.headers.get(AUTH_HEADER)
     if (!header) {
-      throw new Error(`missing ${AUTH_HEADER} header`);
+      throw new Error(`missing ${AUTH_HEADER} header`)
     }
-    let sig: ArrayBuffer;
+    let sig: ArrayBuffer
     try {
-      sig = fromBase64(header);
+      sig = fromBase64(header)
     } catch {
-      throw new Error(`malformed ${AUTH_HEADER} header (expected base64)`);
+      throw new Error(`malformed ${AUTH_HEADER} header (expected base64)`)
     }
-    const body = await req.clone().text();
-    const ok = await crypto.subtle.verify("HMAC", key, sig, encode(body));
+    const body = await req.clone().text()
+    const ok = await crypto.subtle.verify("HMAC", key, sig, encode(body))
     if (!ok) {
-      throw new Error(`${AUTH_HEADER} signature does not match request body`);
+      throw new Error(`${AUTH_HEADER} signature does not match request body`)
     }
-  };
+  }
 }
 
 // ---- Internals ----
@@ -115,7 +109,7 @@ async function importKey(
   usages: readonly ("sign" | "verify")[],
 ): Promise<CryptoKey> {
   if (secret.length === 0) {
-    throw new Error("HMAC secret must be a non-empty string");
+    throw new Error("HMAC secret must be a non-empty string")
   }
   return crypto.subtle.importKey(
     "raw",
@@ -123,7 +117,7 @@ async function importKey(
     { name: "HMAC", hash: "SHA-256" },
     false,
     usages as KeyUsage[],
-  );
+  )
 }
 
 /**
@@ -133,24 +127,24 @@ async function importKey(
  * Copying into a new ArrayBuffer sidesteps the nominal mismatch.
  */
 function encode(s: string): ArrayBuffer {
-  const view = new TextEncoder().encode(s);
-  const buf = new ArrayBuffer(view.byteLength);
-  new Uint8Array(buf).set(view);
-  return buf;
+  const view = new TextEncoder().encode(s)
+  const buf = new ArrayBuffer(view.byteLength)
+  new Uint8Array(buf).set(view)
+  return buf
 }
 
 function toBase64(buffer: ArrayBuffer): string {
   // btoa is available in every modern runtime (Node 16+, Workers, browsers).
-  const bytes = new Uint8Array(buffer);
-  let bin = "";
-  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
-  return btoa(bin);
+  const bytes = new Uint8Array(buffer)
+  let bin = ""
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!)
+  return btoa(bin)
 }
 
 function fromBase64(s: string): ArrayBuffer {
-  const bin = atob(s);
-  const buf = new ArrayBuffer(bin.length);
-  const view = new Uint8Array(buf);
-  for (let i = 0; i < bin.length; i++) view[i] = bin.charCodeAt(i);
-  return buf;
+  const bin = atob(s)
+  const buf = new ArrayBuffer(bin.length)
+  const view = new Uint8Array(buf)
+  for (let i = 0; i < bin.length; i++) view[i] = bin.charCodeAt(i)
+  return buf
 }

package/src/conditions.ts

@@ -2,33 +2,33 @@
 // and in event-filter match expressions.
 // Authoritative contract in docs/sdk-surface.md §4.
 
-import type { Duration, RunStatus } from "./types.js";
+import type { Duration, RunStatus } from "./types.js"
 
 export interface EventCondition {
-  event: string;
-  match?: Record<string, unknown> | ((payload: unknown) => boolean);
+  event: string
+  match?: Record<string, unknown> | ((payload: unknown) => boolean)
 }
 
 export interface SignalCondition {
-  signal: string;
-  match?: Record<string, unknown> | ((payload: unknown) => boolean);
+  signal: string
+  match?: Record<string, unknown> | ((payload: unknown) => boolean)
 }
 
 export interface TimeCondition {
-  after?: Duration | Date;
-  before?: Duration | Date;
+  after?: Duration | Date
+  before?: Duration | Date
 }
 
 export interface RunStatusCondition {
-  run: { id: string; status: RunStatus[] };
+  run: { id: string; status: RunStatus[] }
 }
 
 export interface OrCondition {
-  or: Condition[];
+  or: Condition[]
 }
 
 export interface AndCondition {
-  and: Condition[];
+  and: Condition[]
 }
 
 export type Condition =
@@ -37,7 +37,7 @@ export type Condition =
   | TimeCondition
   | RunStatusCondition
   | OrCondition
-  | AndCondition;
+  | AndCondition
 
-export const or = (...conditions: Condition[]): OrCondition => ({ or: conditions });
-export const and = (...conditions: Condition[]): AndCondition => ({ and: conditions });
+export const or = (...conditions: Condition[]): OrCondition => ({ or: conditions })
+export const and = (...conditions: Condition[]): AndCondition => ({ and: conditions })

package/src/handler/index.ts

@@ -17,17 +17,23 @@
 // and the executor-shape already round-trips losslessly, we keep the
 // full discriminated union here. The orchestrator adapter can collapse.
 
-import { executeWorkflowStep, type ExecuteWorkflowStepRequest, type ExecuteWorkflowStepResponse, type StepRunner } from "../runtime/executor.js";
+import {
+  type ExecuteWorkflowStepRequest,
+  type ExecuteWorkflowStepResponse,
+  executeWorkflowStep,
+  type StepRunner,
+} from "../runtime/executor.js"
 
-export { executeWorkflowStep };
-export type { StepRunner, ExecuteWorkflowStepRequest, ExecuteWorkflowStepResponse };
-export type { StepJournalEntry } from "../runtime/journal.js";
-import type { JournalSlice, StepJournalEntry } from "../runtime/journal.js";
-import type { RuntimeEnvironment } from "../runtime/ctx.js";
-import { getWorkflow } from "../workflow.js";
-import type { RunTrigger } from "../types.js";
-import type { RateLimiter } from "../rate-limit/index.js";
-import { PROTOCOL_VERSION, type ProtocolVersion } from "../protocol/index.js";
+export type { StepJournalEntry } from "../runtime/journal.js"
+export type { ExecuteWorkflowStepRequest, ExecuteWorkflowStepResponse, StepRunner }
+export { executeWorkflowStep }
+
+import { PROTOCOL_VERSION, type ProtocolVersion } from "../protocol/index.js"
+import type { RateLimiter } from "../rate-limit/index.js"
+import type { RuntimeEnvironment } from "../runtime/ctx.js"
+import type { JournalSlice, StepJournalEntry } from "../runtime/journal.js"
+import type { RunTrigger } from "../types.js"
+import { getWorkflow } from "../workflow.js"
 
 export interface StepHandlerDeps {
   /**
@@ -36,11 +42,11 @@ export interface StepHandlerDeps {
    * this verifies the `X-Voyant-Dispatch-Auth` HMAC against a public
    * key embedded by `voyant build`.
    */
-  verifyRequest?: (req: Request) => void | Promise<void>;
+  verifyRequest?: (req: Request) => void | Promise<void>
   /** Injectable clock. Defaults to Date.now. */
-  now?: () => number;
+  now?: () => number
   /** Optional structured logger. */
-  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+  logger?: (level: "info" | "warn" | "error", msg: string, data?: object) => void
   /**
    * Rate limiter shared across step invocations. Required when any
    * registered workflow declares `options.rateLimit` on a step; see
@@ -48,7 +54,7 @@ export interface StepHandlerDeps {
    * the reference impl. One instance per Worker process is the
    * intended cardinality — state is kept in the limiter's closure.
    */
-  rateLimiter?: RateLimiter;
+  rateLimiter?: RateLimiter
   /**
    * Runner for steps declared with `options.runtime === "node"`.
    * Leave unset for handlers that only run edge steps; any node step
@@ -62,88 +68,84 @@ export interface StepHandlerDeps {
    * This is bring-your-own because the right dispatch shape depends on
    * the target runtime; the executor only cares that a runner exists.
    */
-  nodeStepRunner?: StepRunner;
+  nodeStepRunner?: StepRunner
 }
 
 /** The HTTP request body the orchestrator sends. */
 export interface WorkflowStepRequest {
-  protocolVersion: ProtocolVersion;
-  runId: string;
-  workflowId: string;
-  workflowVersion: string;
-  invocationCount: number;
-  input: unknown;
-  journal: JournalSlice;
-  environment: "production" | "preview" | "development";
-  deadline: number;
+  protocolVersion: ProtocolVersion
+  runId: string
+  workflowId: string
+  workflowVersion: string
+  invocationCount: number
+  input: unknown
+  journal: JournalSlice
+  environment: "production" | "preview" | "development"
+  deadline: number
   tenantMeta: {
-    tenantId: string;
-    projectId: string;
-    organizationId: string;
-    projectSlug?: string;
-    organizationSlug?: string;
-  };
+    tenantId: string
+    projectId: string
+    organizationId: string
+    projectSlug?: string
+    organizationSlug?: string
+  }
   runMeta: {
-    number: number;
-    attempt: number;
-    triggeredBy: RunTrigger;
-    tags: string[];
-    startedAt: number;
-  };
+    number: number
+    attempt: number
+    triggeredBy: RunTrigger
+    tags: string[]
+    startedAt: number
+  }
 }
 
 /** The JSON response body the tenant returns. */
-export type WorkflowStepResponse = ExecuteWorkflowStepResponse;
+export type WorkflowStepResponse = ExecuteWorkflowStepResponse
 
 /** Error-response envelope used for HTTP 4xx/5xx. */
 export interface StepHandlerError {
-  error: string;
-  message: string;
-  details?: unknown;
+  error: string
+  message: string
+  details?: unknown
 }
 
 /** Build an HTTP fetch-style handler. */
-export function createStepHandler(
-  deps: StepHandlerDeps = {},
-): (req: Request) => Promise<Response> {
+export function createStepHandler(deps: StepHandlerDeps = {}): (req: Request) => Promise<Response> {
   return async (req) => {
     if (req.method !== "POST") {
-      return jsonResponse(405, errorBody("method_not_allowed", "POST required"));
+      return jsonResponse(405, errorBody("method_not_allowed", "POST required"))
     }
     try {
-      if (deps.verifyRequest) await deps.verifyRequest(req);
+      if (deps.verifyRequest) await deps.verifyRequest(req)
     } catch (err) {
       deps.logger?.("warn", "step handler: auth rejected", {
         error: err instanceof Error ? err.message : String(err),
-      });
-      return jsonResponse(401, errorBody("unauthorized", errMessage(err)));
+      })
+      return jsonResponse(401, errorBody("unauthorized", errMessage(err)))
     }
-    let raw: unknown;
+    let raw: unknown
     try {
-      raw = await req.json();
+      raw = await req.json()
     } catch (err) {
-      return jsonResponse(400, errorBody("invalid_json", errMessage(err)));
+      return jsonResponse(400, errorBody("invalid_json", errMessage(err)))
     }
     // The incoming Request carries its own AbortSignal; threading it
     // through lets `ctx.signal` observe client-side aborts (orchestrator
     // cancellations, closed fetches, etc.) during step execution.
-    const out = await runStepInner(raw, deps, { signal: req.signal });
-    return jsonResponse(out.status, out.body);
-  };
+    const out = await runStepInner(raw, deps, { signal: req.signal })
+    return jsonResponse(out.status, out.body)
+  }
 }
 
 /** Per-invocation options available to callers of the transport-free entry point. */
 export interface StepRequestOptions {
   /** AbortSignal forwarded to `ctx.signal` inside the step body. */
-  signal?: AbortSignal;
+  signal?: AbortSignal
   /**
    * Fires synchronously from `ctx.stream.*` as each chunk is produced.
    * Used by orchestrators that want to broadcast chunks live
    * (dashboards, queues) before the invocation returns.
    */
-  onStreamChunk?: (
-    chunk: import("../runtime/executor.js").StreamChunk,
-  ) => void;
+  onStreamChunk?: (chunk: import("../runtime/executor.js").StreamChunk) => void
 }
 
 /**
@@ -157,10 +159,9 @@ export async function handleStepRequest(
   deps: StepHandlerDeps = {},
   opts: StepRequestOptions = {},
 ): Promise<
-  | { status: number; body: WorkflowStepResponse }
-  | { status: number; body: StepHandlerError }
+  { status: number; body: WorkflowStepResponse } | { status: number; body: StepHandlerError }
 > {
-  return runStepInner(raw, deps, opts);
+  return runStepInner(raw, deps, opts)
 }
 
 async function runStepInner(
@@ -168,13 +169,12 @@ async function runStepInner(
   deps: StepHandlerDeps,
   opts: StepRequestOptions = {},
 ): Promise<
-  | { status: number; body: WorkflowStepResponse }
-  | { status: number; body: StepHandlerError }
+  { status: number; body: WorkflowStepResponse } | { status: number; body: StepHandlerError }
 > {
-  const parsed = parseRequest(raw);
-  if (!parsed.ok) return { status: 400, body: errorBody("invalid_request", parsed.message) };
+  const parsed = parseRequest(raw)
+  if (!parsed.ok) return { status: 400, body: errorBody("invalid_request", parsed.message) }
 
-  const reqBody = parsed.value;
+  const reqBody = parsed.value
   if (reqBody.protocolVersion !== PROTOCOL_VERSION) {
     return {
       status: 426,
@@ -182,19 +182,22 @@ async function runStepInner(
         "protocol_version_mismatch",
         `tenant supports protocol ${PROTOCOL_VERSION}, got ${String(reqBody.protocolVersion)}`,
       ),
-    };
+    }
   }
 
-  const def = getWorkflow(reqBody.workflowId);
+  const def = getWorkflow(reqBody.workflowId)
   if (!def) {
     return {
       status: 404,
-      body: errorBody("workflow_not_found", `workflow "${reqBody.workflowId}" is not registered in this bundle`),
-    };
+      body: errorBody(
+        "workflow_not_found",
+        `workflow "${reqBody.workflowId}" is not registered in this bundle`,
+      ),
+    }
   }
 
-  const now = deps.now ?? (() => Date.now());
-  const stepRunner = createInProcessStepRunner(now);
+  const now = deps.now ?? (() => Date.now())
+  const stepRunner = createInProcessStepRunner(now)
 
   const runtimeEnv: RuntimeEnvironment = {
     run: {
@@ -215,7 +218,7 @@ async function runStepInner(
       id: reqBody.tenantMeta.organizationId,
       slug: reqBody.tenantMeta.organizationSlug ?? reqBody.tenantMeta.organizationId,
     },
-  };
+  }
 
   try {
     const response = await executeWorkflowStep(def, {
@@ -235,16 +238,16 @@ async function runStepInner(
       now,
       abortSignal: opts.signal,
       onStreamChunk: opts.onStreamChunk,
-    });
-    return { status: 200, body: response };
+    })
+    return { status: 200, body: response }
   } catch (err) {
     deps.logger?.("error", "step handler: executor threw", {
       error: err instanceof Error ? err.message : String(err),
-    });
+    })
     return {
       status: 500,
       body: errorBody("executor_error", errMessage(err)),
-    };
+    }
   }
 }
 
@@ -254,23 +257,24 @@ async function runStepInner(
  * will swap this for a dispatching runner that POSTs to a pod.
  */
 function createInProcessStepRunner(now: () => number): StepRunner {
-  return async ({ stepId, attempt, fn, stepCtx }): Promise<StepJournalEntry> => {
-    const startedAt = now();
+  return async ({ stepId: _stepId, attempt, fn, stepCtx }): Promise<StepJournalEntry> => {
+    const startedAt = now()
     try {
-      const output = await fn(stepCtx);
+      const output = await fn(stepCtx)
       return {
         attempt,
         status: "ok",
         output,
         startedAt,
         finishedAt: now(),
-      };
+      }
     } catch (err) {
-      const e = err as Error;
-      const code = typeof (err as { code?: unknown }).code === "string"
-        ? (err as { code: string }).code
-        : "UNKNOWN";
-      const retryAfter = (err as { retryAfter?: unknown }).retryAfter;
+      const e = err as Error
+      const code =
+        typeof (err as { code?: unknown }).code === "string"
+          ? (err as { code: string }).code
+          : "UNKNOWN"
+      const retryAfter = (err as { retryAfter?: unknown }).retryAfter
       return {
         attempt,
         status: "err",
@@ -284,9 +288,9 @@ function createInProcessStepRunner(now: () => number): StepRunner {
         },
         startedAt,
         finishedAt: now(),
-      };
+      }
     }
-  };
+  }
 }
 
 // ---- Parsing ----
@@ -295,9 +299,9 @@ function parseRequest(
   raw: unknown,
 ): { ok: true; value: WorkflowStepRequest } | { ok: false; message: string } {
   if (raw === null || typeof raw !== "object") {
-    return { ok: false, message: "body must be a JSON object" };
+    return { ok: false, message: "body must be a JSON object" }
   }
-  const r = raw as Record<string, unknown>;
+  const r = raw as Record<string, unknown>
   const required: (keyof WorkflowStepRequest)[] = [
     "protocolVersion",
     "runId",
@@ -309,36 +313,36 @@ function parseRequest(
     "deadline",
     "tenantMeta",
     "runMeta",
-  ];
+  ]
   for (const k of required) {
-    if (!(k in r)) return { ok: false, message: `missing required field "${k}"` };
+    if (!(k in r)) return { ok: false, message: `missing required field "${k}"` }
   }
   if (typeof r.protocolVersion !== "number") {
-    return { ok: false, message: "`protocolVersion` must be a number" };
+    return { ok: false, message: "`protocolVersion` must be a number" }
   }
   if (typeof r.runId !== "string" || r.runId.length === 0) {
-    return { ok: false, message: "`runId` must be a non-empty string" };
+    return { ok: false, message: "`runId` must be a non-empty string" }
   }
   if (typeof r.workflowId !== "string" || r.workflowId.length === 0) {
-    return { ok: false, message: "`workflowId` must be a non-empty string" };
+    return { ok: false, message: "`workflowId` must be a non-empty string" }
   }
   if (typeof r.invocationCount !== "number" || r.invocationCount < 1) {
-    return { ok: false, message: "`invocationCount` must be >= 1" };
+    return { ok: false, message: "`invocationCount` must be >= 1" }
   }
   if (!r.journal || typeof r.journal !== "object") {
-    return { ok: false, message: "`journal` must be an object" };
+    return { ok: false, message: "`journal` must be an object" }
   }
-  const env = r.environment;
+  const env = r.environment
   if (env !== "production" && env !== "preview" && env !== "development") {
-    return { ok: false, message: "`environment` must be production | preview | development" };
+    return { ok: false, message: "`environment` must be production | preview | development" }
   }
   if (!r.tenantMeta || typeof r.tenantMeta !== "object") {
-    return { ok: false, message: "`tenantMeta` must be an object" };
+    return { ok: false, message: "`tenantMeta` must be an object" }
   }
   if (!r.runMeta || typeof r.runMeta !== "object") {
-    return { ok: false, message: "`runMeta` must be an object" };
+    return { ok: false, message: "`runMeta` must be an object" }
   }
-  return { ok: true, value: r as unknown as WorkflowStepRequest };
+  return { ok: true, value: r as unknown as WorkflowStepRequest }
 }
 
 // ---- Helpers ----
@@ -347,15 +351,15 @@ function jsonResponse(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,
     headers: { "content-type": "application/json; charset=utf-8" },
-  });
+  })
 }
 
 function errorBody(error: string, message: string, details?: unknown): StepHandlerError {
-  const out: StepHandlerError = { error, message };
-  if (details !== undefined) out.details = details;
-  return out;
+  const out: StepHandlerError = { error, message }
+  if (details !== undefined) out.details = details
+  return out
 }
 
 function errMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+  return err instanceof Error ? err.message : String(err)
 }

package/src/index.ts

@@ -4,15 +4,15 @@
 //   docs/sdk-surface.md §2–§8
 //   docs/design.md §3–§4
 
-export * from "./types.js";
-export * from "./workflow.js";
-export * from "./trigger.js";
-export * from "./conditions.js";
 export {
   FatalError,
-  RetryableError,
-  TimeoutError,
   HookConflictError,
   QuotaExceededError,
+  RetryableError,
+  TimeoutError,
   ValidationError,
-} from "@voyantjs/workflows-errors";
+} from "@voyantjs/workflows-errors"
+export * from "./conditions.js"
+export * from "./trigger.js"
+export * from "./types.js"
+export * from "./workflow.js"