awaitly 2.0.0 → 3.0.0

package/dist/hitl-pYfkQMv_.d.ts

@@ -0,0 +1,468 @@
+import { W as WorkflowEvent, A as AsyncResult, q as Err } from './index-Cv4K_3sZ.js';
+import { R as ResumeState, P as PendingApproval, a as ApprovalStepOptions, A as ApprovalRejected, G as GatedStepOptions } from './types-BDTxgKKc.js';
+
+/**
+ * Resume state helpers: collectors and state manipulation for workflow replay.
+ */
+
+/**
+ * Create a collector for step results to build resume state.
+ *
+ * ## When to Use
+ *
+ * Use `createResumeStateCollector` when you need to:
+ * - **Save workflow state** for later replay/resume
+ * - **Persist step results** to a database or file system
+ * - **Build resume state** from workflow execution
+ * - **Enable workflow replay** after application restarts
+ *
+ * ## Why Use This Instead of Manual Collection
+ *
+ * - **Automatic filtering**: Only collects `step_complete` events (ignores other events)
+ * - **Metadata preservation**: Captures both result and meta for proper error replay
+ * - **Type-safe**: Returns properly typed `ResumeState`
+ * - **Convenient API**: Simple `handleEvent` → `getResumeState` pattern
+ *
+ * ## How It Works
+ *
+ * 1. Create collector and pass `handleEvent` to workflow's `onEvent` option
+ * 2. Workflow emits `step_complete` events for keyed steps
+ * 3. Collector automatically captures these events
+ * 4. Call `getResumeState()` to get the collected `ResumeState`
+ * 5. Persist state (e.g., to database) for later resume
+ *
+ * ## When step_complete Events Are Emitted
+ *
+ * Events are emitted for ANY step that has a `key` option, regardless of calling pattern:
+ *
+ * ```typescript
+ * // Function-wrapped pattern - emits step_complete
+ * await step(() => fetchUser("1"), { key: "user:1" });
+ *
+ * // Direct AsyncResult pattern - also emits step_complete
+ * await step(fetchUser("1"), { key: "user:1" });
+ * ```
+ *
+ * Both patterns above will emit `step_complete` events and be captured by the collector.
+ *
+ * ## Important Notes
+ *
+ * - Only steps with a `key` option are collected (unkeyed steps are not saved)
+ * - The collector preserves error metadata for proper replay behavior
+ * - State can be serialized to JSON (but complex cause types may need custom handling)
+ *
+ * @returns An object with:
+ *   - `handleEvent`: Function to pass to workflow's `onEvent` option
+ *   - `getResumeState`: Get collected resume state (call after workflow execution)
+ *   - `clear`: Clears the collector's internal recorded entries (does not mutate workflow state)
+ *
+ * @example
+ * ```typescript
+ * // Collect state during workflow execution
+ * const collector = createResumeStateCollector();
+ *
+ * const workflow = createWorkflow({ fetchUser, fetchPosts }, {
+ *   onEvent: collector.handleEvent, // Pass collector's handler
+ * });
+ *
+ * await workflow(async ({ step }) => {
+ *   // Only keyed steps are collected
+ *   const user = await step(() => fetchUser("1"), { key: "user:1" });
+ *   const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` });
+ *   return { user, posts };
+ * });
+ *
+ * // Get collected state for persistence
+ * const state = collector.getResumeState();
+ * // state.steps contains: 'user:1' and 'posts:1' entries
+ *
+ * // Save to database
+ * await db.saveWorkflowState(workflowId, state);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Resume workflow from saved state
+ * const savedState = await db.loadWorkflowState(workflowId);
+ * const workflow = createWorkflow({ fetchUser, fetchPosts }, {
+ *   resumeState: savedState // Pre-populate cache from saved state
+ * });
+ *
+ * // Cached steps skip execution, new steps run normally
+ * await workflow(async ({ step }) => {
+ *   const user = await step(() => fetchUser("1"), { key: "user:1" }); // Cache hit
+ *   const posts = await step(() => fetchPosts(user.id), { key: `posts:${user.id}` }); // Cache hit
+ *   return { user, posts };
+ * });
+ * ```
+ */
+declare function createResumeStateCollector(): {
+    /** Handle workflow events. Pass this to workflow's `onEvent` option. */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Get the collected resume state. Call after workflow execution. */
+    getResumeState: () => ResumeState;
+    /** Clears the collector's internal recorded entries (does not mutate workflow state). */
+    clear: () => void;
+};
+/**
+ * Inject an approved value into resume state.
+ * Use this when an external approval is granted and you want to resume the workflow.
+ *
+ * @param state - The resume state to update
+ * @param options - Object with stepKey and the approved value
+ * @returns A new ResumeState with the approval injected
+ *
+ * @example
+ * ```typescript
+ * // When approval is granted externally:
+ * const updatedState = injectApproval(savedState, {
+ *   stepKey: 'deploy:prod',
+ *   value: { approvedBy: 'admin', approvedAt: Date.now() }
+ * });
+ *
+ * // Resume workflow with the approval injected
+ * const workflow = createWorkflow({ ... }, { resumeState: updatedState });
+ * ```
+ */
+declare function injectApproval<T>(state: ResumeState, options: {
+    stepKey: string;
+    value: T;
+}): ResumeState;
+/**
+ * Remove a step from resume state (e.g., to force re-execution).
+ * This is an immutable operation - returns a new ResumeState without modifying the original.
+ *
+ * @param state - The resume state to update
+ * @param stepKey - The key of the step to remove
+ * @returns A new ResumeState with the step removed (original is unchanged)
+ *
+ * @example
+ * ```typescript
+ * // Force a step to re-execute on resume
+ * const updatedState = clearStep(savedState, 'approval:123');
+ * ```
+ */
+declare function clearStep(state: ResumeState, stepKey: string): ResumeState;
+/**
+ * Check if a step in resume state has a pending approval error.
+ *
+ * @param state - The resume state to check
+ * @param stepKey - The key of the step to check
+ * @returns `true` if the step has a pending approval, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasPendingApproval(savedState, 'deploy:prod')) {
+ *   // Show approval UI
+ * }
+ * ```
+ */
+declare function hasPendingApproval(state: ResumeState, stepKey: string): boolean;
+/**
+ * Get all pending approval step keys from resume state.
+ *
+ * @param state - The resume state to check
+ * @returns Array of step keys that have pending approvals
+ *
+ * @example
+ * ```typescript
+ * const pendingKeys = getPendingApprovals(savedState);
+ * // ['deploy:prod', 'deploy:staging']
+ * ```
+ */
+declare function getPendingApprovals(state: ResumeState): string[];
+/**
+ * Inject a hook callback value into resume state.
+ * Call this when the app receives the HTTP callback (e.g. POST /hook/:hookId) and pass the request body as value.
+ *
+ * @param state - The resume state to update
+ * @param options - hookId (from the callback URL) and value (e.g. request body)
+ * @returns A new ResumeState with the hook step set to ok(value)
+ */
+declare function injectHook<T>(state: ResumeState, options: {
+    hookId: string;
+    value: T;
+}): ResumeState;
+/**
+ * Check if a step in resume state has a pending hook error.
+ *
+ * @param state - The resume state to check
+ * @param hookId - The hook id (from createHook() or the callback URL)
+ * @returns `true` if that hook step is pending, `false` otherwise
+ */
+declare function hasPendingHook(state: ResumeState, hookId: string): boolean;
+/**
+ * Get all pending hook hookIds from resume state.
+ *
+ * @param state - The resume state to check
+ * @returns Array of hookIds that have pending callbacks
+ */
+declare function getPendingHooks(state: ResumeState): string[];
+/**
+ * Extended resume state collector that tracks pending approvals.
+ * Use this for human-in-the-loop workflows that need to track approval state.
+ *
+ * @returns An object with methods to handle events, get state, and manage approvals
+ *
+ * @example
+ * ```typescript
+ * const collector = createApprovalStateCollector();
+ *
+ * const workflow = createWorkflow({ fetchUser, requireApproval }, {
+ *   onEvent: collector.handleEvent,
+ * });
+ *
+ * const result = await workflow(async ({ step }) => {
+ *   const user = await step(() => fetchUser("1"), { key: "user:1" });
+ *   const approval = await step(requireApproval, { key: "approval:1" });
+ *   return { user, approval };
+ * });
+ *
+ * // Check for pending approvals
+ * if (collector.hasPendingApprovals()) {
+ *   const pending = collector.getPendingApprovals();
+ *   // pending: [{ stepKey: 'approval:1', error: PendingApproval }]
+ *   await saveToDatabase(collector.getResumeState());
+ * }
+ *
+ * // Later, when approved:
+ * const resumeState = collector.injectApproval('approval:1', { approvedBy: 'admin' });
+ * ```
+ */
+declare function createApprovalStateCollector(): {
+    /** Handle workflow events. Pass this to workflow's `onEvent` option. */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Get the collected resume state. Call after workflow execution. */
+    getResumeState: () => ResumeState;
+    /** Clears the collector's internal recorded entries (does not mutate workflow state). */
+    clear: () => void;
+    /** Check if any steps have pending approvals */
+    hasPendingApprovals: () => boolean;
+    /** Get all pending approval entries with their errors */
+    getPendingApprovals: () => Array<{
+        stepKey: string;
+        error: PendingApproval;
+    }>;
+    /** Inject an approval result, updating the collector's internal state. Returns a copy for use as resumeState. */
+    injectApproval: <T>(stepKey: string, value: T) => ResumeState;
+};
+
+/**
+ * Human-in-the-Loop (HITL) helpers: pendingApproval, createApprovalStep, gatedStep.
+ */
+
+/**
+ * Create a PendingApproval error result.
+ * Convenience helper for approval-gated steps.
+ *
+ * @param stepKey - Stable key for this approval step (used for resume)
+ * @param options - Optional reason and metadata for the pending approval
+ * @returns A Result with a PendingApproval error
+ *
+ * @example
+ * ```typescript
+ * const requireApproval = async (userId: string) => {
+ *   const status = await db.getApproval(userId);
+ *   if (!status) return pendingApproval(`approval:${userId}`);
+ *   return ok(status);
+ * };
+ * ```
+ */
+declare function pendingApproval(stepKey: string, options?: {
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}): Err<PendingApproval>;
+/**
+ * Create a Result-returning function that checks external approval status.
+ *
+ * ## When to Use
+ *
+ * Use `createApprovalStep` when you need:
+ * - **Human-in-the-loop workflows**: Steps that require human approval
+ * - **External approval systems**: Integrate with approval databases/APIs
+ * - **Workflow pausing**: Workflows that pause and resume after approval
+ * - **Approval tracking**: Track who approved what and when
+ *
+ * ## Why Use This Instead of Manual Approval Checks
+ *
+ * - **Standardized pattern**: Consistent approval step interface
+ * - **Type-safe**: Returns typed `PendingApproval` or `ApprovalRejected` errors
+ * - **Resume-friendly**: Works seamlessly with `injectApproval()` and resume state
+ * - **Metadata support**: Can include approval reason and metadata
+ *
+ * ## How It Works
+ *
+ * 1. Create approval step with `checkApproval` function
+ * 2. `checkApproval` returns one of:
+ *    - `{ status: 'pending' }` - Approval not yet granted (workflow pauses)
+ *    - `{ status: 'approved', value: T }` - Approval granted (workflow continues)
+ *    - `{ status: 'rejected', reason: string }` - Approval rejected (workflow fails)
+ * 3. Use in workflow with `step()` - workflow pauses if pending
+ * 4. When approval granted externally, use `injectApproval()` to resume
+ *
+ * ## Typical Approval Flow
+ *
+ * 1. Workflow executes → reaches approval step
+ * 2. `checkApproval()` called → returns `{ status: 'pending' }`
+ * 3. Workflow returns `PendingApproval` error
+ * 4. Save workflow state → persist for later resume
+ * 5. Show approval UI → user sees pending approval
+ * 6. User grants/rejects → update approval system
+ * 7. Inject approval → call `injectApproval()` with approved value
+ * 8. Resume workflow → continue from approval step
+ *
+ * @param options - Configuration for the approval step:
+ *   - `key`: Stable key for this approval (must match step key in workflow)
+ *   - `checkApproval`: Async function that checks current approval status
+ *   - `pendingReason`: Optional reason shown when approval is pending
+ *   - `metadata`: Optional metadata attached to the approval request
+ *
+ * @returns A function that returns an AsyncResult checking approval status.
+ *          The function can be used directly with `step()` in workflows.
+ *
+ * @example
+ * ```typescript
+ * // Create approval step that checks database
+ * const requireManagerApproval = createApprovalStep<{ approvedBy: string }>({
+ *   key: 'manager-approval',
+ *   checkApproval: async () => {
+ *     const approval = await db.getApproval('manager-approval');
+ *     if (!approval) {
+ *       return { status: 'pending' }; // Workflow pauses here
+ *     }
+ *     if (approval.rejected) {
+ *       return { status: 'rejected', reason: approval.reason };
+ *     }
+ *     return {
+ *       status: 'approved',
+ *       value: { approvedBy: approval.approvedBy }
+ *     };
+ *   },
+ *   pendingReason: 'Waiting for manager approval',
+ * });
+ *
+ * // Use in workflow
+ * const workflow = createWorkflow({ requireManagerApproval });
+ * const result = await workflow(async ({ step }) => {
+ *   const approval = await step(requireManagerApproval, { key: 'manager-approval' });
+ *   // If pending, workflow exits with PendingApproval error
+ *   // If approved, continues with approval value
+ *   return approval;
+ * });
+ *
+ * // Handle pending state
+ * if (!result.ok && isPendingApproval(result.error)) {
+ *   // Workflow paused - show approval UI
+ *   showApprovalUI(result.error.stepKey);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With approval injection for resume
+ * const collector = createApprovalStateCollector();
+ * const workflow = createWorkflow({ requireApproval }, {
+ *   onEvent: collector.handleEvent,
+ * });
+ *
+ * const result = await workflow(async ({ step }) => {
+ *   const approval = await step(requireApproval, { key: 'approval:1' });
+ *   return approval;
+ * });
+ *
+ * // When approval granted externally
+ * if (collector.hasPendingApprovals()) {
+ *   const resumeState = collector.injectApproval('approval:1', {
+ *     approvedBy: 'admin@example.com'
+ *   });
+ *
+ *   // Resume workflow
+ *   const workflow2 = createWorkflow({ requireApproval }, { resumeState });
+ *   const result2 = await workflow2(async ({ step }) => {
+ *     const approval = await step(requireApproval, { key: 'approval:1' });
+ *     return approval; // Now succeeds with injected value
+ *   });
+ * }
+ * ```
+ */
+declare function createApprovalStep<T>(options: ApprovalStepOptions<T>): () => AsyncResult<T, PendingApproval | ApprovalRejected>;
+/**
+ * Create a gated step that requires approval before execution.
+ *
+ * This is the AI SDK / LangChain-style pattern where you intercept
+ * tool calls *before* they execute, allowing humans to see the args
+ * and approve, edit, or reject before the operation runs.
+ *
+ * ## When to Use
+ *
+ * Use `gatedStep` when you want to:
+ * - **Show args before execution**: Let humans see what the operation will do
+ * - **Allow editing args**: Humans can modify args before operation runs
+ * - **Conditional gating**: Only require approval for certain conditions
+ * - **AI safety**: Gate dangerous AI tool calls (send email, delete file, etc.)
+ *
+ * ## Difference from createApprovalStep
+ *
+ * - `createApprovalStep`: Checks external approval status, operation already defined
+ * - `gatedStep`: Gates before operation, shows args, allows editing, then executes
+ *
+ * ## Flow
+ *
+ * 1. Call gatedStep with args
+ * 2. Check if approval is required (based on requiresApproval condition)
+ * 3. If required and not approved:
+ *    - Return PendingApproval with args visible in metadata
+ *    - Human sees: "Send email to external@example.com with subject X"
+ *    - Human can approve (run as-is), edit (modify args), or reject
+ * 4. If approved or not required:
+ *    - Execute the operation with (potentially edited) args
+ *
+ * @param operation - The operation to gate (a function returning AsyncResult)
+ * @param options - Gating configuration
+ * @returns A gated function that checks approval before execution
+ *
+ * @example
+ * ```typescript
+ * // Gate external email sends
+ * const sendEmail = async (to: string, subject: string, body: string) => { ... };
+ *
+ * const gatedSendEmail = gatedStep(
+ *   sendEmail,
+ *   {
+ *     key: 'email',
+ *     requiresApproval: (args) => !args.to.endsWith('@mycompany.com'),
+ *     description: (args) => `Send email to ${args.to}: "${args.subject}"`,
+ *   }
+ * );
+ *
+ * // In workflow:
+ * const result = await step(
+ *   () => gatedSendEmail({ to: 'external@other.com', subject: 'Hello', body: '...' }),
+ *   { key: 'send-welcome-email' }
+ * );
+ *
+ * // If gated, returns PendingApproval with:
+ * // {
+ * //   stepKey: 'email',
+ * //   reason: 'Send email to external@other.com: "Hello"',
+ * //   metadata: { pendingArgs: { to: '...', subject: '...', body: '...' } }
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Gate file deletion with explicit approval check
+ * const gatedDelete = gatedStep(
+ *   (path: string) => deleteFile(path),
+ *   {
+ *     key: 'delete-file',
+ *     requiresApproval: true, // Always require approval
+ *     description: (args) => `Delete file: ${args.path}`,
+ *     checkApproval: () => approvalStore.getApproval('delete-file'),
+ *   }
+ * );
+ * ```
+ */
+declare function gatedStep<TArgs extends Record<string, unknown>, T, E>(operation: (args: TArgs) => AsyncResult<T, E>, options: GatedStepOptions<TArgs, T>): (args: TArgs) => AsyncResult<T, E | PendingApproval | ApprovalRejected>;
+
+export { createApprovalStateCollector as a, createApprovalStep as b, clearStep as c, getPendingApprovals as d, createResumeStateCollector as e, getPendingHooks as f, gatedStep as g, hasPendingApproval as h, injectApproval as i, hasPendingHook as j, injectHook as k, pendingApproval as p };