@voyantjs/workflows 0.0.0 → 0.6.8

package/dist/auth/index.d.ts

@@ -0,0 +1,26 @@
+export declare const AUTH_HEADER: "x-voyant-dispatch-auth";
+/**
+ * Returns a verifier that accepts `Authorization: Bearer <token>`
+ * where `<token>` matches any of the `validTokens` (case-sensitive,
+ * constant-time compared). Usable as the `verifyRequest` dep on
+ * `handleWorkerRequest` / `createStepHandler` for the public-facing
+ * surface of an orchestrator or tenant Worker.
+ *
+ * Intended for dev + single-tenant deployments. Production should
+ * issue per-tenant, short-lived tokens from a control plane.
+ */
+export declare function createBearerVerifier(validTokens: readonly string[]): (req: Request) => void;
+/** Returns a signer: `(body: string) => Promise<string>` (base64 HMAC-SHA256). */
+export declare function createHmacSigner(secret: string): Promise<(body: string) => Promise<string>>;
+/**
+ * Returns a verifier: `(req: Request) => Promise<void>`. Throws if:
+ *   - the header is missing,
+ *   - the signature is malformed,
+ *   - the signature does not match the current body.
+ *
+ * The verifier consumes `req.body` via `req.text()`. Callers that
+ * need the body downstream should pre-clone: `req.clone()` before
+ * passing in.
+ */
+export declare function createHmacVerifier(secret: string): Promise<(req: Request) => Promise<void>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,WAAW,EAAG,wBAAiC,CAAA;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAiB3F;AAWD,kFAAkF;AAClF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAMjG;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAmBjG"}

package/dist/auth/index.js

@@ -0,0 +1,137 @@
+// @voyantjs/workflows/auth
+//
+// Paired HMAC signer + verifier for the `X-Voyant-Dispatch-Auth`
+// header on `POST /__voyant/workflow-step`. Both sides share a
+// symmetric secret — suitable for local dev and single-region
+// deployments; asymmetric signing (control-plane issuer + tenant
+// public-key) is a later upgrade that keeps the same header shape.
+//
+// Built on Web Crypto (`crypto.subtle`), so it works unchanged in
+// Node 20+, Cloudflare Workers, Deno, Bun, and browsers.
+//
+// Usage on the orchestrator side:
+//
+//   import { createHmacSigner } from "@voyantjs/workflows/auth";
+//   const sign = await createHmacSigner(process.env.VOYANT_SIGNING_KEY!);
+//   createDispatchStepHandler(script, { dispatcher, sign });
+//
+// Usage on the tenant side:
+//
+//   import { createHmacVerifier } from "@voyantjs/workflows/auth";
+//   import { createStepHandler } from "@voyantjs/workflows/handler";
+//   const verify = await createHmacVerifier(env.VOYANT_SIGNING_KEY);
+//   export default { fetch: createStepHandler({ verifyRequest: verify }) };
+export const AUTH_HEADER = "x-voyant-dispatch-auth";
+/**
+ * Returns a verifier that accepts `Authorization: Bearer <token>`
+ * where `<token>` matches any of the `validTokens` (case-sensitive,
+ * constant-time compared). Usable as the `verifyRequest` dep on
+ * `handleWorkerRequest` / `createStepHandler` for the public-facing
+ * surface of an orchestrator or tenant Worker.
+ *
+ * Intended for dev + single-tenant deployments. Production should
+ * issue per-tenant, short-lived tokens from a control plane.
+ */
+export function createBearerVerifier(validTokens) {
+    if (validTokens.length === 0) {
+        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);
+        if (!match) {
+            throw new Error("Authorization header must use the Bearer scheme");
+        }
+        const presented = match[1];
+        for (const valid of validTokens) {
+            if (constantTimeEquals(presented, valid))
+                return;
+        }
+        throw new Error("bearer token does not match any configured value");
+    };
+}
+function constantTimeEquals(a, b) {
+    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);
+    }
+    return diff === 0;
+}
+/** Returns a signer: `(body: string) => Promise<string>` (base64 HMAC-SHA256). */
+export async function createHmacSigner(secret) {
+    const key = await importKey(secret, ["sign"]);
+    return async (body) => {
+        const sig = await crypto.subtle.sign("HMAC", key, encode(body));
+        return toBase64(sig);
+    };
+}
+/**
+ * Returns a verifier: `(req: Request) => Promise<void>`. Throws if:
+ *   - the header is missing,
+ *   - the signature is malformed,
+ *   - the signature does not match the current body.
+ *
+ * The verifier consumes `req.body` via `req.text()`. Callers that
+ * need the body downstream should pre-clone: `req.clone()` before
+ * passing in.
+ */
+export async function createHmacVerifier(secret) {
+    const key = await importKey(secret, ["verify"]);
+    return async (req) => {
+        const header = req.headers.get(AUTH_HEADER);
+        if (!header) {
+            throw new Error(`missing ${AUTH_HEADER} header`);
+        }
+        let sig;
+        try {
+            sig = fromBase64(header);
+        }
+        catch {
+            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));
+        if (!ok) {
+            throw new Error(`${AUTH_HEADER} signature does not match request body`);
+        }
+    };
+}
+// ---- Internals ----
+async function importKey(secret, usages) {
+    if (secret.length === 0) {
+        throw new Error("HMAC secret must be a non-empty string");
+    }
+    return crypto.subtle.importKey("raw", encode(secret), { name: "HMAC", hash: "SHA-256" }, false, usages);
+}
+/**
+ * Encode to a freshly-allocated ArrayBuffer. TextEncoder's Uint8Array
+ * is typed as `Uint8Array<ArrayBufferLike>` under recent TS lib, which
+ * doesn't satisfy the `BufferSource` param of `subtle.sign/verify`.
+ * Copying into a new ArrayBuffer sidesteps the nominal mismatch.
+ */
+function encode(s) {
+    const view = new TextEncoder().encode(s);
+    const buf = new ArrayBuffer(view.byteLength);
+    new Uint8Array(buf).set(view);
+    return buf;
+}
+function toBase64(buffer) {
+    // 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);
+}
+function fromBase64(s) {
+    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/dist/conditions.d.ts

@@ -0,0 +1,29 @@
+import type { Duration, RunStatus } from "./types.js";
+export interface EventCondition {
+    event: string;
+    match?: Record<string, unknown> | ((payload: unknown) => boolean);
+}
+export interface SignalCondition {
+    signal: string;
+    match?: Record<string, unknown> | ((payload: unknown) => boolean);
+}
+export interface TimeCondition {
+    after?: Duration | Date;
+    before?: Duration | Date;
+}
+export interface RunStatusCondition {
+    run: {
+        id: string;
+        status: RunStatus[];
+    };
+}
+export interface OrCondition {
+    or: Condition[];
+}
+export interface AndCondition {
+    and: Condition[];
+}
+export type Condition = EventCondition | SignalCondition | TimeCondition | RunStatusCondition | OrCondition | AndCondition;
+export declare const or: (...conditions: Condition[]) => OrCondition;
+export declare const and: (...conditions: Condition[]) => AndCondition;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAErD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,EAAE,CAAA;KAAE,CAAA;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,SAAS,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,SAAS,EAAE,CAAA;CACjB;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,eAAe,GACf,aAAa,GACb,kBAAkB,GAClB,WAAW,GACX,YAAY,CAAA;AAEhB,eAAO,MAAM,EAAE,GAAI,GAAG,YAAY,SAAS,EAAE,KAAG,WAAmC,CAAA;AACnF,eAAO,MAAM,GAAG,GAAI,GAAG,YAAY,SAAS,EAAE,KAAG,YAAqC,CAAA"}

package/dist/conditions.js

@@ -0,0 +1,5 @@
+// Condition types used in step options (waitFor / cancelIf / skipIf)
+// and in event-filter match expressions.
+// Authoritative contract in docs/sdk-surface.md §4.
+export const or = (...conditions) => ({ or: conditions });
+export const and = (...conditions) => ({ and: conditions });

package/dist/handler/index.d.ts

@@ -0,0 +1,104 @@
+import { type ExecuteWorkflowStepRequest, type ExecuteWorkflowStepResponse, executeWorkflowStep, type StepRunner } from "../runtime/executor.js";
+export type { StepJournalEntry } from "../runtime/journal.js";
+export type { ExecuteWorkflowStepRequest, ExecuteWorkflowStepResponse, StepRunner };
+export { executeWorkflowStep };
+import { type ProtocolVersion } from "../protocol/index.js";
+import type { RateLimiter } from "../rate-limit/index.js";
+import type { JournalSlice } from "../runtime/journal.js";
+import type { RunTrigger } from "../types.js";
+export interface StepHandlerDeps {
+    /**
+     * Optional. Called before parsing the body. Should throw / reject
+     * if the request is not from a trusted orchestrator. In production
+     * this verifies the `X-Voyant-Dispatch-Auth` HMAC against a public
+     * key embedded by `voyant build`.
+     */
+    verifyRequest?: (req: Request) => void | Promise<void>;
+    /** Injectable clock. Defaults to Date.now. */
+    now?: () => number;
+    /** Optional structured logger. */
+    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
+     * `createInMemoryRateLimiter` in `@voyantjs/workflows/rate-limit` for
+     * the reference impl. One instance per Worker process is the
+     * intended cardinality — state is kept in the limiter's closure.
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Runner for steps declared with `options.runtime === "node"`.
+     * Leave unset for handlers that only run edge steps; any node step
+     * will then fail with `NODE_RUNTIME_UNAVAILABLE`.
+     *
+     * Typical impl dispatches to a separate sandboxed context:
+     *   - Local dev: an in-process passthrough (same Node process).
+     *   - CF production: a Cloudflare Container binding, via
+     *     `createCfContainerStepRunner` from `@voyantjs/workflows-orchestrator-cloudflare`.
+     *
+     * 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;
+}
+/** 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;
+    tenantMeta: {
+        tenantId: string;
+        projectId: string;
+        organizationId: string;
+        projectSlug?: string;
+        organizationSlug?: string;
+    };
+    runMeta: {
+        number: number;
+        attempt: number;
+        triggeredBy: RunTrigger;
+        tags: string[];
+        startedAt: number;
+    };
+}
+/** The JSON response body the tenant returns. */
+export type WorkflowStepResponse = ExecuteWorkflowStepResponse;
+/** Error-response envelope used for HTTP 4xx/5xx. */
+export interface StepHandlerError {
+    error: string;
+    message: string;
+    details?: unknown;
+}
+/** Build an HTTP fetch-style handler. */
+export declare function createStepHandler(deps?: StepHandlerDeps): (req: Request) => Promise<Response>;
+/** 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;
+    /**
+     * 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;
+}
+/**
+ * Transport-free entry point. Callers that already parsed the body
+ * (e.g. local orchestrator in-memory, tests) invoke this directly.
+ * Returns either the step response or an error envelope with the HTTP
+ * status the caller should use.
+ */
+export declare function handleStepRequest(raw: unknown, deps?: StepHandlerDeps, opts?: StepRequestOptions): Promise<{
+    status: number;
+    body: WorkflowStepResponse;
+} | {
+    status: number;
+    body: StepHandlerError;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/handler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handler/index.ts"],"names":[],"mappings":"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"}

package/dist/handler/index.js

@@ -0,0 +1,238 @@
+// @voyantjs/workflows/handler
+//
+// The tenant side of the runtime protocol (see docs/runtime-protocol.md §2).
+// The orchestrator invokes `POST /__voyant/workflow-step`; the tenant
+// Worker responds by running the workflow body once (one invocation of
+// the executor) and returning the executor response as JSON.
+//
+//   export default { fetch: createStepHandler() }
+//
+// is enough to make a tenant Worker protocol-conformant. Auth is
+// optional at the SDK level: in production, wire the HMAC verifier
+// bundled by `voyant build`; for local dev, leave it unset.
+//
+// The executor's native response shape is returned verbatim — the wire
+// document calls for compensated/compensation_failed to be folded into
+// "failed" for the first draft, but since the draft is not yet locked
+// and the executor-shape already round-trips losslessly, we keep the
+// full discriminated union here. The orchestrator adapter can collapse.
+import { executeWorkflowStep, } from "../runtime/executor.js";
+export { executeWorkflowStep };
+import { PROTOCOL_VERSION } from "../protocol/index.js";
+import { getWorkflow } from "../workflow.js";
+/** Build an HTTP fetch-style handler. */
+export function createStepHandler(deps = {}) {
+    return async (req) => {
+        if (req.method !== "POST") {
+            return jsonResponse(405, errorBody("method_not_allowed", "POST required"));
+        }
+        try {
+            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)));
+        }
+        let raw;
+        try {
+            raw = await req.json();
+        }
+        catch (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);
+    };
+}
+/**
+ * Transport-free entry point. Callers that already parsed the body
+ * (e.g. local orchestrator in-memory, tests) invoke this directly.
+ * Returns either the step response or an error envelope with the HTTP
+ * status the caller should use.
+ */
+export async function handleStepRequest(raw, deps = {}, opts = {}) {
+    return runStepInner(raw, deps, opts);
+}
+async function runStepInner(raw, deps, opts = {}) {
+    const parsed = parseRequest(raw);
+    if (!parsed.ok)
+        return { status: 400, body: errorBody("invalid_request", parsed.message) };
+    const reqBody = parsed.value;
+    if (reqBody.protocolVersion !== PROTOCOL_VERSION) {
+        return {
+            status: 426,
+            body: errorBody("protocol_version_mismatch", `tenant supports protocol ${PROTOCOL_VERSION}, got ${String(reqBody.protocolVersion)}`),
+        };
+    }
+    const def = getWorkflow(reqBody.workflowId);
+    if (!def) {
+        return {
+            status: 404,
+            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 runtimeEnv = {
+        run: {
+            id: reqBody.runId,
+            number: reqBody.runMeta.number,
+            attempt: reqBody.runMeta.attempt,
+            triggeredBy: reqBody.runMeta.triggeredBy,
+            tags: reqBody.runMeta.tags,
+            startedAt: reqBody.runMeta.startedAt,
+        },
+        workflow: { id: reqBody.workflowId, version: reqBody.workflowVersion },
+        environment: { name: reqBody.environment },
+        project: {
+            id: reqBody.tenantMeta.projectId,
+            slug: reqBody.tenantMeta.projectSlug ?? reqBody.tenantMeta.projectId,
+        },
+        organization: {
+            id: reqBody.tenantMeta.organizationId,
+            slug: reqBody.tenantMeta.organizationSlug ?? reqBody.tenantMeta.organizationId,
+        },
+    };
+    try {
+        const response = await executeWorkflowStep(def, {
+            runId: reqBody.runId,
+            workflowId: reqBody.workflowId,
+            workflowVersion: reqBody.workflowVersion,
+            input: reqBody.input,
+            journal: reqBody.journal,
+            invocationCount: reqBody.invocationCount,
+            environment: runtimeEnv,
+            triggeredBy: reqBody.runMeta.triggeredBy,
+            runStartedAt: reqBody.runMeta.startedAt,
+            tags: reqBody.runMeta.tags,
+            stepRunner,
+            nodeStepRunner: deps.nodeStepRunner,
+            rateLimiter: deps.rateLimiter,
+            now,
+            abortSignal: opts.signal,
+            onStreamChunk: opts.onStreamChunk,
+        });
+        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)),
+        };
+    }
+}
+/**
+ * Build a step runner that executes the step body in the same
+ * process. Suitable for `runtime: "edge"`. Container-runtime steps
+ * will swap this for a dispatching runner that POSTs to a pod.
+ */
+function createInProcessStepRunner(now) {
+    return async ({ stepId: _stepId, attempt, fn, stepCtx }) => {
+        const startedAt = now();
+        try {
+            const output = await fn(stepCtx);
+            return {
+                attempt,
+                status: "ok",
+                output,
+                startedAt,
+                finishedAt: now(),
+            };
+        }
+        catch (err) {
+            const e = err;
+            const code = typeof err.code === "string"
+                ? err.code
+                : "UNKNOWN";
+            const retryAfter = err.retryAfter;
+            return {
+                attempt,
+                status: "err",
+                error: {
+                    category: "USER_ERROR",
+                    code,
+                    message: e?.message ?? String(err),
+                    name: e?.name,
+                    stack: e?.stack,
+                    data: retryAfter !== undefined ? { retryAfter } : undefined,
+                },
+                startedAt,
+                finishedAt: now(),
+            };
+        }
+    };
+}
+// ---- Parsing ----
+function parseRequest(raw) {
+    if (raw === null || typeof raw !== "object") {
+        return { ok: false, message: "body must be a JSON object" };
+    }
+    const r = raw;
+    const required = [
+        "protocolVersion",
+        "runId",
+        "workflowId",
+        "workflowVersion",
+        "invocationCount",
+        "journal",
+        "environment",
+        "deadline",
+        "tenantMeta",
+        "runMeta",
+    ];
+    for (const k of required) {
+        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" };
+    }
+    if (typeof r.runId !== "string" || r.runId.length === 0) {
+        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" };
+    }
+    if (typeof r.invocationCount !== "number" || r.invocationCount < 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" };
+    }
+    const env = r.environment;
+    if (env !== "production" && env !== "preview" && env !== "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" };
+    }
+    if (!r.runMeta || typeof r.runMeta !== "object") {
+        return { ok: false, message: "`runMeta` must be an object" };
+    }
+    return { ok: true, value: r };
+}
+// ---- Helpers ----
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+function errorBody(error, message, details) {
+    const out = { error, message };
+    if (details !== undefined)
+        out.details = details;
+    return out;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "@voyantjs/workflows-errors";
+export * from "./conditions.js";
+export * from "./trigger.js";
+export * from "./types.js";
+export * from "./workflow.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,4BAA4B,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// @voyantjs/workflows
+//
+// Authoring SDK for Voyant Workflows. Full contract in:
+//   docs/sdk-surface.md §2–§8
+//   docs/design.md §3–§4
+export { FatalError, HookConflictError, QuotaExceededError, RetryableError, TimeoutError, ValidationError, } from "@voyantjs/workflows-errors";
+export * from "./conditions.js";
+export * from "./trigger.js";
+export * from "./types.js";
+export * from "./workflow.js";