runwork 0.2.0

package/bundled-types/core-workflow-types.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Workflow Types - Shared types for native workflow engine
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ */
+import type { Env } from './core-utils';
+import type { IntegrationClient } from './core-integrations';
+export type NativeWorkflowStatus = 'pending' | 'running' | 'sleeping' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timedOut';
+export type NativeStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+export type NativeStepType = 'do' | 'sleep' | 'sleepUntil' | 'waitEvent';
+export interface NativeWorkflowError {
+    code: string;
+    message: string;
+    stack?: string;
+    retryable: boolean;
+}
+export interface NativeStepAttempt {
+    attemptNumber: number;
+    startedAt: number;
+    completedAt?: number;
+    error?: NativeWorkflowError;
+}
+export interface NativeStepExecution {
+    id: string;
+    name: string;
+    type: NativeStepType;
+    status: NativeStepStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: NativeWorkflowError;
+    attempts: NativeStepAttempt[];
+    maxRetries: number;
+    startedAt?: number;
+    completedAt?: number;
+    timeoutMs?: number;
+    sleepUntil?: number;
+    eventType?: string;
+    eventTimeoutAt?: number;
+}
+export interface NativeWorkflowInstance {
+    id: string;
+    workflowName: string;
+    status: NativeWorkflowStatus;
+    input: unknown;
+    output?: unknown;
+    error?: NativeWorkflowError;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    steps: NativeStepExecution[];
+    currentStepId?: string;
+    config: NativeWorkflowConfig;
+    metadata?: Record<string, unknown>;
+}
+export interface NativeWorkflowConfig {
+    maxRetries: number;
+    retryBackoffMs: number;
+    stepTimeoutMs: number;
+    workflowTimeoutMs: number;
+}
+export declare const DEFAULT_WORKFLOW_CONFIG: NativeWorkflowConfig;
+export interface NativeStepContext {
+    /** Unique instance ID for this workflow execution */
+    instanceId: string;
+    /** Input passed when workflow was started */
+    workflowInput: unknown;
+    /** Results from previous steps */
+    previousSteps: Record<string, {
+        output: unknown;
+        status: NativeStepStatus;
+    }>;
+}
+export interface WorkflowIndexEntry {
+    instanceId: string;
+    workflowName: string;
+    status: NativeWorkflowStatus;
+    createdAt: number;
+    completedAt?: number;
+}
+export interface ListWorkflowsOptions {
+    workflowName?: string;
+    status?: NativeWorkflowStatus;
+    limit?: number;
+    offset?: number;
+}
+export interface ExecuteStepRequest {
+    instanceId: string;
+    stepId: string;
+    stepName: string;
+    workflowName: string;
+    workflowInput: unknown;
+    previousSteps: Record<string, {
+        output: unknown;
+        status: NativeStepStatus;
+    }>;
+}
+export interface ExecuteStepResponse {
+    success: boolean;
+    output?: unknown;
+    error?: NativeWorkflowError;
+}
+export interface PendingEvent {
+    instanceId: string;
+    stepId: string;
+    eventType: string;
+    waitingSince: number;
+    timeoutAt?: number;
+}
+export interface ReceivedEvent {
+    type: string;
+    payload: unknown;
+    timestamp: number;
+}
+/**
+ * Result returned by a workflow execution
+ */
+export interface WorkflowResult {
+    success: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Possible states of a workflow instance
+ */
+export type WorkflowStatus = 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting';
+/**
+ * Information about a workflow instance
+ */
+export interface WorkflowInstanceInfo {
+    id: string;
+    workflowName: string;
+    status: WorkflowStatus;
+    params?: Record<string, unknown>;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    error?: string;
+    result?: WorkflowResult;
+}
+/**
+ * Interface for WorkflowInstance DO stub methods
+ * Used to type the DurableObjectStub without importing the class
+ */
+export interface WorkflowInstanceStub {
+    create(workflowName: string, params: Record<string, unknown>, instanceId: string, config?: Partial<NativeWorkflowConfig>, metadata?: Record<string, unknown>): Promise<void>;
+    getStatus(): Promise<NativeWorkflowInstance | null>;
+    signal(eventType: string, payload: unknown): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+}
+/**
+ * Interface for WorkflowCoordinator DO stub methods
+ * Used to type the DurableObjectStub without importing the class
+ */
+export interface WorkflowCoordinatorStub {
+    create(workflowName: string, params: Record<string, unknown>, config?: Partial<NativeWorkflowConfig>, metadata?: Record<string, unknown>): Promise<string>;
+    signal(instanceId: string, eventType: string, payload: unknown): Promise<void>;
+    getInstanceInfo(instanceId: string): Promise<WorkflowInstanceInfo | null>;
+    listInstances(options?: ListWorkflowsOptions): Promise<WorkflowInstanceInfo[]>;
+    updateIndex(instanceId: string, workflowName: string, status: NativeWorkflowStatus): Promise<void>;
+    pause(instanceId: string): Promise<void>;
+    resume(instanceId: string): Promise<void>;
+    cancel(instanceId: string): Promise<void>;
+}
+/**
+ * Definition for a workflow handler
+ */
+export interface WorkflowDefinition<TParams = unknown, TResult = unknown> {
+    /** Unique name for this workflow (kebab-case, e.g., "order-fulfillment") */
+    name: string;
+    /** Human-readable description of what this workflow does */
+    description?: string;
+    /** The workflow handler function */
+    handler: (ctx: WorkflowContext<TParams>) => Promise<TResult>;
+    /** Whether the workflow is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Context passed to workflow handlers
+ */
+export interface WorkflowContext<TParams = unknown> {
+    /** Environment bindings */
+    env: Env;
+    /** Unique instance ID for this workflow execution */
+    instanceId: string;
+    /** Parameters passed when workflow was started */
+    params: TParams;
+    /** Step utilities for durable execution */
+    step: WorkflowStepUtilities;
+    /** Integration client for external service calls */
+    integrations: IntegrationClient;
+    /** Logger for structured workflow logging */
+    logger: WorkflowLogger;
+}
+/**
+ * Step utilities for durable workflow execution
+ */
+export interface WorkflowStepUtilities {
+    /** Execute a step with automatic retry and persistence */
+    do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    do<T>(name: string, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    /** Sleep for a duration (e.g., '5 minutes', '1 hour', '24 hours') */
+    sleep(name: string, duration: string): Promise<void>;
+    /** Sleep until a specific timestamp */
+    sleepUntil(name: string, timestamp: Date): Promise<void>;
+    /** Wait for an external event */
+    waitForEvent<T = unknown>(name: string, options?: WaitEventOptions): Promise<T>;
+}
+/**
+ * Options for step execution
+ */
+export interface StepOptions {
+    retries?: {
+        limit: number;
+        delay: string;
+        backoff?: 'constant' | 'linear' | 'exponential';
+    };
+    timeout?: string;
+}
+/**
+ * Options for waitForEvent
+ */
+export interface WaitEventOptions {
+    type?: string;
+    timeout?: string;
+}
+/**
+ * Logger interface for workflow execution
+ */
+export interface WorkflowLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * State of a registered workflow
+ */
+export interface WorkflowState {
+    name: string;
+    description?: string;
+    enabled: boolean;
+    activeInstances: number;
+    totalRuns: number;
+    lastRun: number | null;
+    lastError?: string;
+}
+/**
+ * Response from workflow status API
+ */
+export interface WorkflowStatusResponse {
+    workflows: WorkflowState[];
+}

package/bundled-types/core-workflows.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Core Workflow Framework - Public API
+ * DO NOT MODIFY THIS FILE - You may break the project functionality
+ *
+ * This module provides the public API for workflow operations.
+ * Uses native DO-based engine (WorkflowCoordinator/WorkflowInstance).
+ *
+ * Implementation details:
+ * - Types are defined in core-workflow-types.ts
+ * - Native DO-based implementation is in core-workflow-instance.ts and core-workflow-coordinator.ts
+ */
+import type { Env } from './core-utils';
+export type { WorkflowResult, WorkflowStatus, WorkflowInstanceInfo, WorkflowDefinition, WorkflowContext, WorkflowStepUtilities, StepOptions, WaitEventOptions, WorkflowLogger, WorkflowState, WorkflowStatusResponse, } from './core-workflow-types';
+import type { WorkflowInstanceInfo } from './core-workflow-types';
+/**
+ * Trigger a workflow by name with the given parameters.
+ * This is a convenience function that creates a new workflow instance.
+ *
+ * @param env - The environment bindings
+ * @param workflowName - The name of the workflow to trigger (must be defined in workflows.ts)
+ * @param params - Parameters to pass to the workflow
+ * @returns The instance ID of the created workflow
+ *
+ * @example
+ * ```ts
+ * const instanceId = await triggerWorkflow(ctx.env, 'order-fulfillment', {
+ *   orderId: '12345',
+ *   customerId: 'cust-001',
+ * });
+ * ```
+ */
+export declare function triggerWorkflow(env: Env, workflowName: string, params?: Record<string, unknown>): Promise<string>;
+/**
+ * Send an event to a running workflow instance.
+ * Use this to trigger workflows waiting on `step.waitForEvent()`.
+ *
+ * @param env - The environment bindings
+ * @param instanceId - The workflow instance ID to send event to
+ * @param eventType - The event type name (must match the name in waitForEvent)
+ * @param payload - Data to send with the event
+ *
+ * @example
+ * ```ts
+ * // In an API endpoint handler
+ * await sendWorkflowEvent(c.env, instanceId, 'approval-response', {
+ *   approved: true,
+ *   approvedBy: 'user123',
+ * });
+ * ```
+ */
+export declare function sendWorkflowEvent(env: Env, instanceId: string, eventType: string, payload?: Record<string, unknown>): Promise<void>;
+/**
+ * Get the current status of a workflow instance.
+ *
+ * @param env - The environment bindings
+ * @param instanceId - The workflow instance ID
+ * @returns The workflow instance info or null if not found
+ *
+ * @example
+ * ```ts
+ * const status = await getWorkflowStatus(c.env, instanceId);
+ * if (status?.status === 'completed') {
+ *   console.log('Workflow completed:', status.result);
+ * }
+ * ```
+ */
+export declare function getWorkflowStatus(env: Env, instanceId: string): Promise<WorkflowInstanceInfo | null>;
+import type { Hono } from 'hono';
+/**
+ * Mount workflow routes on the Hono app
+ * Provides internal API for workflow management
+ */
+export declare function workflowRoutes(app: Hono<{
+    Bindings: Env;
+}>): void;