awaitly 2.0.0 → 3.0.0

package/dist/hitl.d.cts

@@ -0,0 +1,440 @@
+import { R as ResumeState, W as Workflow } from './types-C9Y71dua.cjs';
+export { A as ApprovalRejected, a as ApprovalStepOptions, G as GatedStepOptions, P as PendingApproval } from './types-C9Y71dua.cjs';
+export { i as isApprovalRejected, a as isPendingApproval } from './guards-DhhOJZda.cjs';
+export { c as clearStep, a as createApprovalStateCollector, b as createApprovalStep, g as gatedStep, d as getPendingApprovals, h as hasPendingApproval, i as injectApproval, p as pendingApproval } from './hitl-BnnnLzh2.cjs';
+import { R as Result, W as WorkflowEvent } from './index-ICmfQi08.cjs';
+import './types-d8q8iQlk.cjs';
+import '@standard-schema/spec';
+import './errors-sDSeaZBO.cjs';
+
+/**
+ * awaitly/hitl
+ *
+ * Human-in-the-Loop Orchestration Helpers.
+ * Provides pollers, webhook handlers, and resume injectors
+ * for production-ready approval workflows.
+ */
+
+/**
+ * Options passed to the workflow factory by the HITL orchestrator.
+ */
+interface HITLWorkflowFactoryOptions {
+    /** Resume state for replaying completed steps */
+    resumeState?: ResumeState;
+    /** Event handler for tracking workflow events (required for HITL) */
+    onEvent: (event: WorkflowEvent<unknown>) => void;
+}
+/**
+ * Approval status returned from the approval store.
+ */
+type ApprovalStatus<T = unknown> = {
+    status: "pending";
+} | {
+    status: "approved";
+    value: T;
+    approvedBy?: string;
+    approvedAt?: number;
+} | {
+    status: "rejected";
+    reason: string;
+    rejectedBy?: string;
+    rejectedAt?: number;
+} | {
+    status: "expired";
+    expiredAt: number;
+} | {
+    status: "edited";
+    originalValue: T;
+    editedValue: T;
+    editedBy?: string;
+    editedAt?: number;
+};
+/**
+ * Context passed to notification channel when an approval is needed.
+ */
+interface ApprovalNeededContext {
+    /** Unique approval key for correlation */
+    approvalKey: string;
+    /** Workflow run ID */
+    runId: string;
+    /** Workflow name/type */
+    workflowName: string;
+    /** Human-readable reason for the approval */
+    reason?: string;
+    /** Custom metadata attached to the approval */
+    metadata?: Record<string, unknown>;
+    /** When the approval expires (timestamp) */
+    expiresAt?: number;
+    /** Human-readable summary for notifications */
+    summary?: string;
+    /** For gated steps: the operation args that need approval */
+    pendingArgs?: Record<string, unknown>;
+}
+/**
+ * Context passed to notification channel when an approval is resolved.
+ */
+interface ApprovalResolvedContext {
+    /** Unique approval key */
+    approvalKey: string;
+    /** Resolution action */
+    action: "approved" | "rejected" | "edited" | "expired" | "cancelled";
+    /** Who performed the action (if available) */
+    actorId?: string;
+    /** Timestamp of resolution */
+    resolvedAt: number;
+    /** Reason (for rejections) */
+    reason?: string;
+    /** Value (for approvals/edits) */
+    value?: unknown;
+    /** Original value (for edits) */
+    originalValue?: unknown;
+}
+/**
+ * Notification channel for external integrations (Slack, email, etc).
+ * Implement this interface to receive push notifications when approvals
+ * are created or resolved.
+ */
+interface NotificationChannel {
+    /**
+     * Called when a new approval request is created.
+     * Use this to send Slack messages, emails, or push to a UI.
+     */
+    onApprovalNeeded(context: ApprovalNeededContext): Promise<void>;
+    /**
+     * Called when an approval is granted, rejected, edited, or expires.
+     * Use this to update Slack messages, send confirmation emails, etc.
+     */
+    onApprovalResolved?(context: ApprovalResolvedContext): Promise<void>;
+}
+/**
+ * Interface for approval storage backends.
+ */
+interface ApprovalStore {
+    /**
+     * Get the status of an approval.
+     */
+    getApproval(key: string): Promise<ApprovalStatus>;
+    /**
+     * Create or update a pending approval request.
+     */
+    createApproval(key: string, options?: {
+        metadata?: Record<string, unknown>;
+        expiresAt?: number;
+        requestedBy?: string;
+    }): Promise<void>;
+    /**
+     * Grant an approval.
+     */
+    grantApproval<T>(key: string, value: T, options?: {
+        approvedBy?: string;
+    }): Promise<void>;
+    /**
+     * Reject an approval.
+     */
+    rejectApproval(key: string, reason: string, options?: {
+        rejectedBy?: string;
+    }): Promise<void>;
+    /**
+     * Edit an approval (approve with modifications).
+     * Records both the original proposed value and the edited value.
+     */
+    editApproval<T>(key: string, originalValue: T, editedValue: T, options?: {
+        editedBy?: string;
+    }): Promise<void>;
+    /**
+     * Cancel a pending approval.
+     */
+    cancelApproval(key: string): Promise<void>;
+    /**
+     * List all pending approvals.
+     */
+    listPending(options?: {
+        prefix?: string;
+    }): Promise<string[]>;
+}
+/**
+ * Saved workflow state for resumption.
+ */
+interface SavedWorkflowState {
+    /** Unique identifier for this workflow run */
+    runId: string;
+    /** Workflow name/type */
+    workflowName: string;
+    /** Resume state with step results */
+    resumeState: ResumeState;
+    /** Pending approval keys */
+    pendingApprovals: string[];
+    /** Input that was passed to the workflow */
+    input?: unknown;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** When the workflow was started */
+    startedAt: number;
+    /** When the state was last updated */
+    updatedAt: number;
+}
+/**
+ * Interface for workflow state storage.
+ */
+interface WorkflowStateStore {
+    /**
+     * Save workflow state.
+     */
+    save(state: SavedWorkflowState): Promise<void>;
+    /**
+     * Load workflow state by run ID.
+     */
+    load(runId: string): Promise<SavedWorkflowState | undefined>;
+    /**
+     * Delete workflow state.
+     */
+    delete(runId: string): Promise<void>;
+    /**
+     * List all saved workflow states.
+     */
+    list(options?: {
+        workflowName?: string;
+        hasPendingApprovals?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Find workflows waiting for a specific approval.
+     */
+    findByPendingApproval(approvalKey: string): Promise<string[]>;
+}
+/**
+ * Options for the HITL orchestrator.
+ */
+interface HITLOrchestratorOptions {
+    /** Approval store for managing approval states */
+    approvalStore: ApprovalStore;
+    /** Workflow state store for persisting workflow state */
+    workflowStateStore: WorkflowStateStore;
+    /** Default expiration time for approvals (in milliseconds) */
+    defaultExpirationMs?: number;
+    /** Logger function */
+    logger?: (message: string) => void;
+    /**
+     * Notification channel for external integrations.
+     * When provided, the orchestrator will call onApprovalNeeded when
+     * an approval is created, and onApprovalResolved when resolved.
+     */
+    notificationChannel?: NotificationChannel;
+}
+/**
+ * Result of executing a workflow that may pause for approval.
+ * Uses unknown for error type since workflows add UnexpectedError to the union.
+ */
+type HITLExecutionResult<T, E> = {
+    status: "completed";
+    result: Result<T, E | unknown>;
+} | {
+    status: "paused";
+    runId: string;
+    pendingApprovals: string[];
+    reason?: string;
+} | {
+    status: "resumed";
+    runId: string;
+    result: Result<T, E | unknown>;
+};
+/**
+ * Poller configuration.
+ */
+interface PollerOptions {
+    /** Polling interval in milliseconds */
+    intervalMs: number;
+    /** Maximum number of polls (undefined = unlimited) */
+    maxPolls?: number;
+    /** Timeout for the entire polling operation */
+    timeoutMs?: number;
+    /** Callback when polling starts */
+    onPollStart?: () => void;
+    /** Callback when a poll completes */
+    onPollComplete?: (result: ApprovalStatus) => void;
+}
+/**
+ * Create an in-memory approval store for development/testing.
+ */
+declare function createMemoryApprovalStore(): ApprovalStore;
+/**
+ * Create an in-memory workflow state store for development/testing.
+ */
+declare function createMemoryWorkflowStateStore(): WorkflowStateStore;
+/**
+ * HITL orchestrator interface.
+ */
+interface HITLOrchestrator {
+    /**
+     * Execute a workflow that may pause for approvals.
+     * If the workflow pauses, state is automatically saved.
+     *
+     * The workflowFactory receives options including onEvent handler which MUST be
+     * passed to createWorkflow for HITL tracking to work.
+     */
+    execute<T, E, TInput>(workflowName: string, workflowFactory: (options: HITLWorkflowFactoryOptions) => Workflow<E, unknown>, workflowFn: (context: {
+        step: unknown;
+        deps: unknown;
+        args: TInput;
+    }) => Promise<T>, input: TInput, options?: {
+        runId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<HITLExecutionResult<T, E>>;
+    /**
+     * Resume a paused workflow after approvals have been granted.
+     */
+    resume<T, E, TInput>(runId: string, workflowFactory: (options: HITLWorkflowFactoryOptions) => Workflow<E, unknown>, workflowFn: (context: {
+        step: unknown;
+        deps: unknown;
+        args: TInput;
+    }) => Promise<T>): Promise<HITLExecutionResult<T, E>>;
+    /**
+     * Grant an approval and automatically resume any waiting workflows.
+     */
+    grantApproval<T>(approvalKey: string, value: T, options?: {
+        approvedBy?: string;
+        autoResume?: boolean;
+    }): Promise<{
+        grantedAt: number;
+        resumedWorkflows: string[];
+    }>;
+    /**
+     * Reject an approval.
+     */
+    rejectApproval(approvalKey: string, reason: string, options?: {
+        rejectedBy?: string;
+    }): Promise<void>;
+    /**
+     * Edit an approval (approve with modifications).
+     * Use this when a human wants to approve but with changes to the proposed value.
+     * Records both the original and edited values for audit trail.
+     */
+    editApproval<T>(approvalKey: string, originalValue: T, editedValue: T, options?: {
+        editedBy?: string;
+    }): Promise<{
+        editedAt: number;
+    }>;
+    /**
+     * Poll for an approval to be granted.
+     */
+    pollApproval<T>(approvalKey: string, options?: PollerOptions): Promise<ApprovalStatus<T>>;
+    /**
+     * Get the status of a workflow run.
+     */
+    getWorkflowStatus(runId: string): Promise<SavedWorkflowState | undefined>;
+    /**
+     * List all pending workflows.
+     */
+    listPendingWorkflows(workflowName?: string): Promise<string[]>;
+    /**
+     * Clean up completed workflows older than the specified age.
+     */
+    cleanup(maxAgeMs: number): Promise<number>;
+}
+/**
+ * Create a HITL orchestrator for managing approval workflows.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createHITLOrchestrator({
+ *   approvalStore: createMemoryApprovalStore(),
+ *   workflowStateStore: createMemoryWorkflowStateStore(),
+ * });
+ *
+ * // Execute workflow - IMPORTANT: pass onEvent to createWorkflow!
+ * const result = await orchestrator.execute(
+ *   'order-approval',
+ *   ({ resumeState, onEvent }) => createWorkflow('order-approval', deps, { resumeState, onEvent }),
+ *   async ({ step, deps, args: input }) => {
+ *     const order = await step(() => deps.createOrder(input));
+ *     const approval = await step(() => deps.requireApproval(order.id), { key: `approval:${order.id}` });
+ *     await step(() => deps.processOrder(order.id));
+ *     return { orderId: order.id, approvedBy: approval.approvedBy };
+ *   },
+ *   { items: [...], total: 100 }
+ * );
+ *
+ * if (result.status === 'paused') {
+ *   console.log(`Workflow paused, waiting for: ${result.pendingApprovals}`);
+ * }
+ *
+ * // Later, grant approval
+ * await orchestrator.grantApproval(
+ *   `approval:${orderId}`,
+ *   { approvedBy: 'manager@example.com' },
+ *   { autoResume: true }
+ * );
+ * ```
+ */
+declare function createHITLOrchestrator(options: HITLOrchestratorOptions): HITLOrchestrator;
+/**
+ * Approval webhook request body.
+ */
+interface ApprovalWebhookRequest {
+    /** Approval key */
+    key: string;
+    /** Action: approve, reject, edit, or cancel */
+    action: "approve" | "reject" | "edit" | "cancel";
+    /** Value to inject (for approve) */
+    value?: unknown;
+    /** Original value (for edit - what was proposed) */
+    originalValue?: unknown;
+    /** Edited value (for edit - what human changed it to) */
+    editedValue?: unknown;
+    /** Reason (for reject) */
+    reason?: string;
+    /** Who performed this action */
+    actorId?: string;
+}
+/**
+ * Approval webhook response.
+ */
+interface ApprovalWebhookResponse {
+    success: boolean;
+    message: string;
+    data?: {
+        key: string;
+        action: string;
+        timestamp: number;
+    };
+}
+/**
+ * Create a webhook handler for approval actions.
+ *
+ * @example
+ * ```typescript
+ * const handleApproval = createApprovalWebhookHandler(approvalStore);
+ *
+ * // Express
+ * app.post('/api/approvals', async (req, res) => {
+ *   const result = await handleApproval(req.body);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function createApprovalWebhookHandler(store: ApprovalStore): (request: ApprovalWebhookRequest) => Promise<ApprovalWebhookResponse>;
+/**
+ * Create an approval checker function for use in approval steps.
+ * This wraps the approval store with the standard checkApproval interface.
+ *
+ * @example
+ * ```typescript
+ * const checkApproval = createApprovalChecker(approvalStore);
+ *
+ * const requireManagerApproval = createApprovalStep<{ approvedBy: string }>({
+ *   key: 'manager-approval',
+ *   checkApproval: checkApproval('manager-approval'),
+ *   pendingReason: 'Waiting for manager approval',
+ * });
+ * ```
+ */
+declare function createApprovalChecker<T>(store: ApprovalStore): (key: string) => () => Promise<{
+    status: "pending";
+} | {
+    status: "approved";
+    value: T;
+} | {
+    status: "rejected";
+    reason: string;
+}>;
+
+export { type ApprovalNeededContext, type ApprovalResolvedContext, type ApprovalStatus, type ApprovalStore, type ApprovalWebhookRequest, type ApprovalWebhookResponse, type HITLExecutionResult, type HITLOrchestrator, type HITLOrchestratorOptions, type HITLWorkflowFactoryOptions, type NotificationChannel, type PollerOptions, type SavedWorkflowState, type WorkflowStateStore, createApprovalChecker, createApprovalWebhookHandler, createHITLOrchestrator, createMemoryApprovalStore, createMemoryWorkflowStateStore };