@voyantjs/workflows 0.0.0

package/src/trigger.ts

@@ -0,0 +1,146 @@
+// Triggering workflows from server code, plus event filter declarations.
+// Authoritative contract in docs/sdk-surface.md §6.
+
+import type {
+  Duration,
+  EnvironmentName,
+  RunStatus,
+} from "./types.js";
+import type { WorkflowHandle, EnvironmentContext } from "./workflow.js";
+
+// ---- workflows.* ----
+
+export interface WorkflowsClient {
+  trigger<TIn, TOut>(
+    workflow: WorkflowHandle<TIn, TOut> | string,
+    input: TIn,
+    opts?: TriggerOptions,
+  ): Promise<Run<TOut>>;
+
+  signal(runId: string, name: string, payload: unknown, opts?: { nonce?: string }): Promise<void>;
+  completeToken(tokenId: string, payload: unknown): Promise<void>;
+
+  cancel(runId: string, opts?: { compensate?: boolean; reason?: string }): Promise<void>;
+  retry(runId: string, opts: { mode: "re-trigger" | "resume" }): Promise<Run>;
+  replay(runId: string, opts?: { fromStepId?: string; input?: unknown }): Promise<Run>;
+
+  get(runId: string): Promise<RunDetail>;
+  list(opts?: ListRunsOptions): Promise<{ runs: RunSummary[]; nextCursor?: string }>;
+
+  mintAccessToken(opts: MintAccessTokenOptions): Promise<PublicAccessToken>;
+}
+
+export interface TriggerOptions {
+  idempotencyKey?: string;
+  delay?: Duration | Date;
+  debounce?: { key: string; delay: Duration; mode?: "leading" | "trailing" };
+  ttl?: Duration;
+  tags?: string[];
+  priority?: number;
+  concurrencyKey?: string;
+  lockToVersion?: string;
+  environment?: EnvironmentName;
+  issuePublicAccessToken?: boolean;
+}
+
+export interface Run<TOut = unknown> {
+  id: string;
+  workflowId: string;
+  status: RunStatus;
+  startedAt: number;
+  accessToken?: string;
+  /** Phantom; used only for TypeScript inference. */
+  readonly __output?: TOut;
+}
+
+export interface RunSummary {
+  id: string;
+  workflowId: string;
+  status: RunStatus;
+  startedAt: number;
+  completedAt?: number;
+  tags: string[];
+  environment: EnvironmentName;
+}
+
+export interface RunDetail<TOut = unknown> extends RunSummary {
+  version: string;
+  input: unknown;
+  output?: TOut;
+  error?: unknown;
+  durationMs?: number;
+  // ... full shape in docs/runtime-protocol.md §4.2
+}
+
+export interface ListRunsOptions {
+  workflowId?: string;
+  status?: RunStatus | RunStatus[];
+  environment?: EnvironmentName;
+  tag?: string;
+  since?: Date | number;
+  until?: Date | number;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface MintAccessTokenOptions {
+  target:
+    | { kind: "run"; runId: string }
+    | { kind: "workflow"; workflowId: string }
+    | { kind: "tag"; tag: string };
+  scope: ("read" | "trigger" | "cancel")[];
+  ttl?: Duration;
+}
+
+export interface PublicAccessToken {
+  token: string;
+  exp: number;
+}
+
+/**
+ * Top-level server SDK client. Resolves against the configured
+ * Voyant Cloud API key and account. The runtime implementation is
+ * installed by the cloud client package; imported alone, every
+ * method throws with guidance.
+ */
+export const workflows: WorkflowsClient = new Proxy({} as WorkflowsClient, {
+  get(_, method: string) {
+    return () => {
+      throw new Error(
+        `@voyantjs/workflows: workflows.${method}() requires the Voyant Cloud client. ` +
+          `Install + configure it via @voyantjs/client, or see docs/sdk-surface.md §6.`,
+      );
+    };
+  },
+});
+
+// ---- trigger.on ----
+
+export interface EventFilterHandle {
+  readonly id: string;
+  readonly event: string;
+}
+
+export interface EventFilterDeclaration<T> {
+  target: WorkflowHandle<T, unknown>;
+  match?: (
+    payload: T,
+    ctx: { environment: EnvironmentContext; project: { id: string } },
+  ) => boolean;
+  scope?: string;
+  input?: (payload: T) => unknown;
+}
+
+export interface TriggerApi {
+  on<T = unknown>(event: string, filter: EventFilterDeclaration<T>): EventFilterHandle;
+}
+
+export const trigger: TriggerApi = {
+  on<T>(_event: string, _filter: EventFilterDeclaration<T>): EventFilterHandle {
+    throw new Error(
+      "@voyantjs/workflows: trigger.on() must be collected by `voyant workflows build` and " +
+        "registered with the orchestrator at deploy time; it has no runtime behavior when " +
+        "called directly. See docs/sdk-surface.md §6.2.",
+    );
+  },
+};

package/src/types.ts

@@ -0,0 +1,81 @@
+// Core type aliases used across the SDK.
+// Authoritative definitions in docs/sdk-surface.md §0 and §2.
+
+export type Duration =
+  | number
+  | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
+
+/**
+ * Cloudflare Container instance types — the set Voyant Cloud honors
+ * for `runtime: "node"` steps. Match the sizes published at
+ * https://developers.cloudflare.com/containers/ (as of
+ * compat-date 2026-04-01).
+ *
+ * | name        | vCPU  | memory  | disk  |
+ * | ----------- | ----- | ------- | ----- |
+ * | lite        | 1/16  | 256 MiB | 2 GB  |
+ * | basic       | 1/4   | 1 GiB   | 4 GB  |
+ * | standard-1  | 1/2   | 4 GiB   | 8 GB  |
+ * | standard-2  | 1     | 6 GiB   | 12 GB |
+ * | standard-3  | 2     | 8 GiB   | 16 GB |
+ * | standard-4  | 4     | 12 GiB  | 20 GB |
+ *
+ * The open `(string & {})` escape hatch accepts CF custom instance
+ * types (up to 4 vCPU / 12 GiB / 20 GB, min 3 GiB RAM per vCPU) —
+ * rendered as `"custom-<vcpu>-<ramGiB>"` by convention.
+ */
+export type MachineType =
+  | "lite"
+  | "basic"
+  | "standard-1"
+  | "standard-2"
+  | "standard-3"
+  | "standard-4"
+  | (string & {});
+
+export type EnvironmentName = "production" | "preview" | "development";
+
+export type RunStatus =
+  | "pending"
+  | "running"
+  | "waiting"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "cancelled_by_dev_reload"
+  | "cancelled_by_version_sunset"
+  | "compensated"
+  | "compensation_failed"
+  | "timed_out";
+
+export type ExecutionStatus =
+  | "CREATED"
+  | "QUEUED"
+  | "EXECUTING"
+  | "EXECUTING_WITH_WAITPOINTS"
+  | "SUSPENDED"
+  | "PENDING_CANCEL"
+  | "FINISHED";
+
+export type WaitpointKind = "DATETIME" | "EVENT" | "SIGNAL" | "RUN" | "MANUAL";
+
+export interface RetryPolicy {
+  max?: number;
+  backoff?: "exponential" | "linear" | "fixed";
+  initial?: Duration;
+  maxDelay?: Duration;
+}
+
+export interface RateLimitSpec {
+  key: string | ((input: unknown, ctx: { run: { id: string }; project: { id: string } }) => string);
+  limit: number | ((input: unknown) => number);
+  units?: number | ((input: unknown) => number);
+  window: Duration;
+  onLimit?: "queue" | "fail";
+}
+
+export type RunTrigger =
+  | { kind: "api"; actor?: string; accessTokenId?: string }
+  | { kind: "schedule"; scheduleId: string }
+  | { kind: "event"; eventId: string; eventType: string; filterId: string }
+  | { kind: "parent"; parentRunId: string; parentStepId: string };

package/src/workflow.ts

@@ -0,0 +1,306 @@
+// Workflow declaration and the `ctx` object.
+// Authoritative contract in docs/sdk-surface.md §2–§3.
+
+import type {
+  Duration,
+  EnvironmentName,
+  MachineType,
+  RetryPolicy,
+  RateLimitSpec,
+  RunStatus,
+  RunTrigger,
+} from "./types.js";
+import type { Condition } from "./conditions.js";
+
+// ---- Workflow ----
+
+export interface WorkflowHandle<TInput = unknown, TOutput = unknown> {
+  readonly id: string;
+  /** Phantom; used only for TypeScript inference of `workflows.trigger(...)`. */
+  readonly __input?: TInput;
+  readonly __output?: TOutput;
+}
+
+export interface WorkflowConfig<TInput, TOutput> {
+  id: string;
+  input?: unknown;
+  output?: unknown;
+  description?: string;
+  schedule?: ScheduleDeclaration | ScheduleDeclaration[];
+  concurrency?: ConcurrencyPolicy<TInput>;
+  retry?: RetryPolicy;
+  timeout?: Duration;
+  defaultRuntime?: "edge" | "node";
+  tags?: string[];
+  run: (input: TInput, ctx: WorkflowContext<TInput>) => Promise<TOutput>;
+}
+
+/**
+ * Internal registered form of a workflow. The executor takes this
+ * plus a request and drives the body.
+ */
+export interface WorkflowDefinition<TInput = unknown, TOutput = unknown> extends WorkflowHandle<TInput, TOutput> {
+  readonly config: WorkflowConfig<TInput, TOutput>;
+}
+
+export type ScheduleDeclaration = (
+  | { cron: string }
+  | { every: Duration }
+  | { at: string | Date }
+) & {
+  timezone?: string;
+  input?: unknown | (() => unknown | Promise<unknown>);
+  enabled?: boolean;
+  overlap?: "skip" | "queue" | "allow";
+  environments?: EnvironmentName[];
+  name?: string;
+};
+
+export interface ConcurrencyPolicy<TInput> {
+  key?: string | ((input: TInput) => string);
+  limit?: number;
+  strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin";
+}
+
+/**
+ * Process-local registry. Backed by globalThis so bundles that inline
+ * their own copy of @voyantjs/workflows still share the registry with
+ * the loader's copy (voyant build relies on this to extract the
+ * manifest from a user bundle at load-time). Module-local `const`
+ * would create a private map per bundle copy.
+ */
+const REGISTRY_KEY = "__voyantWorkflowRegistry" as const;
+const globalRef = globalThis as unknown as Record<
+  typeof REGISTRY_KEY,
+  Map<string, WorkflowDefinition> | undefined
+>;
+const REGISTRY: Map<string, WorkflowDefinition> =
+  globalRef[REGISTRY_KEY] ??= new Map<string, WorkflowDefinition>();
+
+/** Declare a workflow. See docs/sdk-surface.md §2.1. */
+export function workflow<TInput = unknown, TOutput = unknown>(
+  config: WorkflowConfig<TInput, TOutput>,
+): WorkflowDefinition<TInput, TOutput> {
+  if (REGISTRY.has(config.id)) {
+    throw new Error(`workflow id "${config.id}" is already registered`);
+  }
+  const def: WorkflowDefinition<TInput, TOutput> = {
+    id: config.id,
+    config,
+  };
+  REGISTRY.set(config.id, def as WorkflowDefinition);
+  return def;
+}
+
+/** Internal: look up a registered workflow by id. */
+export function getWorkflow(id: string): WorkflowDefinition | undefined {
+  return REGISTRY.get(id);
+}
+
+/**
+ * Internal: enumerate every registered workflow. Used by the CLI to list
+ * workflows discovered from a loaded entry file. Not part of the stable
+ * public API — implementation detail of the SDK/CLI pair.
+ */
+export function __listRegisteredWorkflows(): WorkflowDefinition[] {
+  return [...REGISTRY.values()];
+}
+
+/**
+ * Internal: clear the workflow registry. Called by the CLI between
+ * builds / hot-reloads to drop stale workflows before re-importing
+ * the tenant bundle, and by test suites in beforeEach to isolate
+ * runs. Not part of the stable public API.
+ */
+export function __resetRegistry(): void {
+  REGISTRY.clear();
+}
+
+// ---- Context ----
+
+export interface RunContext {
+  id: string;
+  number: number;
+  attempt: number;
+  triggeredBy: RunTrigger;
+  tags: readonly string[];
+  startedAt: number;
+}
+
+export interface EnvironmentContext {
+  name: EnvironmentName;
+  git?: {
+    commit: string;
+    branch: string;
+    pr?: { number: number; url: string };
+  };
+}
+
+export interface WorkflowContext<_TInput = unknown> {
+  readonly run: RunContext;
+  readonly workflow: { id: string; version: string };
+  readonly environment: EnvironmentContext;
+  readonly project: { id: string; slug: string };
+  readonly organization: { id: string; slug: string };
+  readonly invocationCount: number;
+  readonly signal: AbortSignal;
+
+  step: StepApi;
+  sleep: (duration: Duration) => Promise<void>;
+  waitForEvent: WaitForEventApi;
+  waitForSignal: WaitForSignalApi;
+  waitForToken: WaitForTokenApi;
+  invoke: InvokeApi;
+  parallel: ParallelApi;
+  stream: StreamApi;
+  group: GroupApi;
+  compensate: () => Promise<never>;
+  metadata: MetadataApi;
+
+  now: () => number;
+  random: () => number;
+  randomUUID: () => string;
+
+  setRetry: (policy: RetryPolicy) => void;
+}
+
+// ---- Step ----
+
+export interface StepApi {
+  <T>(id: string, fn: StepFn<T>): Promise<T>;
+  <T>(id: string, opts: StepOptions<T>, fn: StepFn<T>): Promise<T>;
+}
+
+export type StepFn<T> = (stepCtx: StepContext) => Promise<T>;
+
+export interface StepContext {
+  signal: AbortSignal;
+  attempt: number;
+  log: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+}
+
+export interface StepOptions<T = unknown> {
+  runtime?: "edge" | "node";
+  machine?: MachineType;
+  timeout?: Duration;
+  retry?: RetryPolicy | { max: 0 };
+  idempotencyKey?: string;
+  compensate?: (output: T) => Promise<void>;
+  rateLimit?: RateLimitSpec;
+  waitFor?: Condition;
+  cancelIf?: Condition;
+  skipIf?: Condition;
+}
+
+// ---- Waits ----
+
+export interface Waitable<T> extends PromiseLike<T | null> {
+  [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+  close(): void;
+}
+
+export interface WaitForEventApi {
+  <T = unknown>(eventType: string, opts?: WaitForEventOptions<T>): Waitable<T>;
+}
+
+export interface WaitForEventOptions<T> {
+  match?: Partial<T> | ((payload: T) => boolean);
+  timeout?: Duration;
+  lookback?: Duration;
+  bufferSize?: number;
+  onTimeout?: "null" | "throw";
+}
+
+export interface WaitForSignalApi {
+  <T = unknown>(name: string, opts?: WaitForSignalOptions<T>): Waitable<T>;
+}
+export interface WaitForSignalOptions<T> extends WaitForEventOptions<T> {}
+
+export interface WaitForTokenApi {
+  <T = unknown>(opts?: WaitForTokenOptions<T>): Promise<TokenWait<T>>;
+}
+export interface WaitForTokenOptions<_T> {
+  tokenId?: string;
+  timeout?: Duration;
+  onTimeout?: "null" | "throw";
+  schema?: unknown;
+}
+export interface TokenWait<T> {
+  tokenId: string;
+  url: string;
+  wait: () => Promise<T | null>;
+}
+
+// ---- Invoke / parallel ----
+
+export interface InvokeApi {
+  <TIn, TOut>(
+    workflow: WorkflowHandle<TIn, TOut>,
+    input: TIn,
+    opts?: InvokeOptions,
+  ): Promise<TOut>;
+}
+
+export interface InvokeOptions {
+  idempotencyKey?: string;
+  tags?: string[];
+  lockToVersion?: string;
+  detach?: boolean;
+}
+
+export interface ParallelApi {
+  <T, R>(
+    items: readonly T[],
+    fn: (item: T, index: number) => Promise<R>,
+    opts?: ParallelOptions,
+  ): Promise<R[]>;
+}
+
+export interface ParallelOptions {
+  concurrency?: number;
+  settle?: boolean;
+}
+
+// ---- Streams ----
+
+export interface StreamApi {
+  text(streamId: string, source: AsyncIterable<string>): Promise<void>;
+  json<T>(streamId: string, source: AsyncIterable<T>): Promise<void>;
+  bytes(streamId: string, source: AsyncIterable<Uint8Array>): Promise<void>;
+  <T>(streamId: string, fn: () => AsyncGenerator<T>): Promise<void>;
+}
+
+// ---- Groups (scoped compensation) ----
+
+export interface GroupApi {
+  <T>(name: string, fn: (scope: GroupScope) => Promise<T>): Promise<T>;
+}
+export interface GroupScope {
+  step: StepApi;
+  compensate: () => Promise<never>;
+}
+
+// ---- Metadata ----
+
+export type MetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | MetadataValue[]
+  | { [key: string]: MetadataValue };
+
+export interface MetadataMutatorSubset {
+  set(key: string, value: MetadataValue): void;
+  increment(key: string, by?: number): void;
+  append<T>(key: string, value: T): void;
+  remove(key: string): void;
+}
+
+export interface MetadataApi extends MetadataMutatorSubset {
+  flush(): Promise<void>;
+  parent?: MetadataMutatorSubset;
+  root?: MetadataMutatorSubset;
+}
+
+export type { RunStatus };