awaitly 2.0.0 → 3.0.0

package/dist/hitl.js

@@ -0,0 +1,605 @@
+// src/core/index.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error, options) {
+  const cause = options?.cause;
+  return { ok: false, error, ...cause !== void 0 ? { cause } : {} };
+}
+
+// src/workflow/guards.ts
+function isStepComplete(event) {
+  return event.type === "step_complete";
+}
+function isPendingApproval(error) {
+  return typeof error === "object" && error !== null && error.type === "PENDING_APPROVAL";
+}
+function isApprovalRejected(error) {
+  return typeof error === "object" && error !== null && error.type === "APPROVAL_REJECTED";
+}
+
+// src/workflow/resume-state.ts
+function injectApproval(state, options) {
+  const newSteps = new Map(state.steps);
+  newSteps.set(options.stepKey, {
+    result: ok(options.value)
+  });
+  return { steps: newSteps };
+}
+function clearStep(state, stepKey) {
+  const newSteps = new Map(state.steps);
+  newSteps.delete(stepKey);
+  return { steps: newSteps };
+}
+function hasPendingApproval(state, stepKey) {
+  const entry = state.steps.get(stepKey);
+  if (!entry || entry.result.ok) return false;
+  return isPendingApproval(entry.result.error);
+}
+function getPendingApprovals(state) {
+  const pending = [];
+  for (const [key, entry] of state.steps) {
+    if (!entry.result.ok && isPendingApproval(entry.result.error)) {
+      pending.push(key);
+    }
+  }
+  return pending;
+}
+function createApprovalStateCollector() {
+  const steps = /* @__PURE__ */ new Map();
+  return {
+    handleEvent: (event) => {
+      if (isStepComplete(event)) {
+        steps.set(event.stepKey, { result: event.result, meta: event.meta });
+      }
+    },
+    getResumeState: () => ({ steps: new Map(steps) }),
+    clear: () => steps.clear(),
+    hasPendingApprovals: () => {
+      for (const entry of steps.values()) {
+        if (!entry.result.ok && isPendingApproval(entry.result.error)) {
+          return true;
+        }
+      }
+      return false;
+    },
+    getPendingApprovals: () => {
+      const pending = [];
+      for (const [key, entry] of steps) {
+        if (!entry.result.ok && isPendingApproval(entry.result.error)) {
+          pending.push({ stepKey: key, error: entry.result.error });
+        }
+      }
+      return pending;
+    },
+    injectApproval: (stepKey, value) => {
+      steps.set(stepKey, { result: ok(value) });
+      return { steps: new Map(steps) };
+    }
+  };
+}
+
+// src/workflow/hitl.ts
+function pendingApproval(stepKey, options) {
+  return err({
+    type: "PENDING_APPROVAL",
+    stepKey,
+    reason: options?.reason,
+    metadata: options?.metadata
+  });
+}
+function createApprovalStep(options) {
+  return async () => {
+    const result = await options.checkApproval();
+    switch (result.status) {
+      case "pending":
+        return err({
+          type: "PENDING_APPROVAL",
+          stepKey: options.key,
+          reason: options.pendingReason,
+          metadata: options.metadata
+        });
+      case "rejected":
+        return err({
+          type: "APPROVAL_REJECTED",
+          stepKey: options.key,
+          reason: result.reason
+        });
+      case "approved":
+        return ok(result.value);
+    }
+  };
+}
+function gatedStep(operation, options) {
+  return async (args) => {
+    const requiresApproval = typeof options.requiresApproval === "function" ? await options.requiresApproval(args) : options.requiresApproval;
+    if (!requiresApproval) {
+      return operation(args);
+    }
+    if (options.checkApproval) {
+      const approvalStatus = await options.checkApproval();
+      switch (approvalStatus.status) {
+        case "approved":
+          return operation(args);
+        case "rejected":
+          return err({
+            type: "APPROVAL_REJECTED",
+            stepKey: options.key,
+            reason: approvalStatus.reason
+          });
+        case "pending":
+          break;
+      }
+    }
+    const description = typeof options.description === "function" ? options.description(args) : options.description;
+    return err({
+      type: "PENDING_APPROVAL",
+      stepKey: options.key,
+      reason: description,
+      metadata: {
+        ...options.metadata,
+        pendingArgs: args,
+        gatedOperation: true
+      }
+    });
+  };
+}
+
+// src/hitl/index.ts
+function createMemoryApprovalStore() {
+  const approvals = /* @__PURE__ */ new Map();
+  return {
+    async getApproval(key) {
+      const approval = approvals.get(key);
+      if (!approval) {
+        return { status: "pending" };
+      }
+      if (approval.expiresAt && Date.now() > approval.expiresAt) {
+        return { status: "expired", expiredAt: approval.expiresAt };
+      }
+      return approval;
+    },
+    async createApproval(key, options) {
+      approvals.set(key, {
+        status: "pending",
+        metadata: options?.metadata,
+        expiresAt: options?.expiresAt
+      });
+    },
+    async grantApproval(key, value, options) {
+      approvals.set(key, {
+        status: "approved",
+        value,
+        approvedBy: options?.approvedBy,
+        approvedAt: Date.now()
+      });
+    },
+    async rejectApproval(key, reason, options) {
+      approvals.set(key, {
+        status: "rejected",
+        reason,
+        rejectedBy: options?.rejectedBy,
+        rejectedAt: Date.now()
+      });
+    },
+    async editApproval(key, originalValue, editedValue, options) {
+      approvals.set(key, {
+        status: "edited",
+        originalValue,
+        editedValue,
+        editedBy: options?.editedBy,
+        editedAt: Date.now()
+      });
+    },
+    async cancelApproval(key) {
+      approvals.delete(key);
+    },
+    async listPending(options) {
+      const pending = [];
+      for (const [key, approval] of approvals) {
+        if (approval.status === "pending") {
+          if (!options?.prefix || key.startsWith(options.prefix)) {
+            pending.push(key);
+          }
+        }
+      }
+      return pending;
+    }
+  };
+}
+function createMemoryWorkflowStateStore() {
+  const states = /* @__PURE__ */ new Map();
+  return {
+    async save(state) {
+      states.set(state.runId, { ...state, updatedAt: Date.now() });
+    },
+    async load(runId) {
+      return states.get(runId);
+    },
+    async delete(runId) {
+      states.delete(runId);
+    },
+    async list(options) {
+      const results = [];
+      for (const [runId, state] of states) {
+        if (options?.workflowName && state.workflowName !== options.workflowName) {
+          continue;
+        }
+        if (options?.hasPendingApprovals !== void 0) {
+          const hasPending = state.pendingApprovals.length > 0;
+          if (options.hasPendingApprovals !== hasPending) {
+            continue;
+          }
+        }
+        results.push(runId);
+      }
+      return results;
+    },
+    async findByPendingApproval(approvalKey) {
+      const results = [];
+      for (const [runId, state] of states) {
+        if (state.pendingApprovals.includes(approvalKey)) {
+          results.push(runId);
+        }
+      }
+      return results;
+    }
+  };
+}
+function createHITLOrchestrator(options) {
+  const {
+    approvalStore,
+    workflowStateStore,
+    defaultExpirationMs = 7 * 24 * 60 * 60 * 1e3,
+    // 7 days
+    logger = () => {
+    },
+    notificationChannel
+  } = options;
+  async function execute(workflowName, workflowFactory, workflowFn, input, opts) {
+    const runId = opts?.runId ?? crypto.randomUUID();
+    const collector = createApprovalStateCollector();
+    const workflow = workflowFactory({
+      onEvent: collector.handleEvent
+    });
+    const args = input;
+    const result = await workflow.run(
+      async (context) => workflowFn({ ...context, args })
+    );
+    const pendingApprovals = collector.getPendingApprovals().map((p) => p.stepKey);
+    if (pendingApprovals.length > 0) {
+      const state = {
+        runId,
+        workflowName,
+        resumeState: collector.getResumeState(),
+        pendingApprovals,
+        input,
+        metadata: opts?.metadata,
+        startedAt: Date.now(),
+        updatedAt: Date.now()
+      };
+      await workflowStateStore.save(state);
+      let reason;
+      let pendingMetadata;
+      if (!result.ok && isPendingApproval(result.error)) {
+        reason = result.error.reason;
+        pendingMetadata = result.error.metadata;
+      }
+      const expiresAt = Date.now() + defaultExpirationMs;
+      for (const key of pendingApprovals) {
+        await approvalStore.createApproval(key, {
+          metadata: { ...pendingMetadata, runId, workflowName },
+          expiresAt
+        });
+      }
+      if (notificationChannel) {
+        for (const key of pendingApprovals) {
+          try {
+            const pendingInfo = collector.getPendingApprovals().find((p) => p.stepKey === key);
+            await notificationChannel.onApprovalNeeded({
+              approvalKey: key,
+              runId,
+              workflowName,
+              reason,
+              metadata: { ...opts?.metadata, ...pendingMetadata },
+              expiresAt,
+              summary: reason ?? `Approval needed for ${key}`,
+              pendingArgs: pendingInfo?.error.metadata
+            });
+          } catch (notifyError) {
+            logger(`Failed to notify for approval ${key}: ${notifyError}`);
+          }
+        }
+      }
+      logger(`Workflow ${runId} paused, waiting for: ${pendingApprovals.join(", ")}`);
+      return {
+        status: "paused",
+        runId,
+        pendingApprovals,
+        reason
+      };
+    }
+    logger(`Workflow ${runId} completed`);
+    return { status: "completed", result };
+  }
+  async function resume(runId, workflowFactory, workflowFn) {
+    const savedState = await workflowStateStore.load(runId);
+    if (!savedState) {
+      throw new Error(`Workflow run not found: ${runId}`);
+    }
+    for (const key of savedState.pendingApprovals) {
+      const status = await approvalStore.getApproval(key);
+      if (status.status === "pending") {
+        return {
+          status: "paused",
+          runId,
+          pendingApprovals: savedState.pendingApprovals
+        };
+      }
+      if (status.status === "rejected") {
+      }
+      if (status.status === "expired") {
+        throw new Error(`Approval ${key} has expired`);
+      }
+    }
+    let resumeState = savedState.resumeState;
+    for (const key of savedState.pendingApprovals) {
+      const status = await approvalStore.getApproval(key);
+      if (status.status === "approved") {
+        resumeState = injectApproval(resumeState, {
+          stepKey: key,
+          value: status.value
+        });
+      } else if (status.status === "edited") {
+        resumeState = injectApproval(resumeState, {
+          stepKey: key,
+          value: status.editedValue
+        });
+      }
+    }
+    const collector = createApprovalStateCollector();
+    const workflow = workflowFactory({
+      resumeState,
+      onEvent: collector.handleEvent
+    });
+    const args = savedState.input;
+    const result = await workflow.run(
+      async (context) => workflowFn({ ...context, args })
+    );
+    const newPendingApprovals = collector.getPendingApprovals().map((p) => p.stepKey);
+    if (newPendingApprovals.length > 0) {
+      const updatedState = {
+        ...savedState,
+        resumeState: collector.getResumeState(),
+        pendingApprovals: newPendingApprovals,
+        updatedAt: Date.now()
+      };
+      await workflowStateStore.save(updatedState);
+      for (const key of newPendingApprovals) {
+        await approvalStore.createApproval(key, {
+          metadata: { runId, workflowName: savedState.workflowName },
+          expiresAt: Date.now() + defaultExpirationMs
+        });
+      }
+      logger(`Workflow ${runId} paused again, waiting for: ${newPendingApprovals.join(", ")}`);
+      let reason;
+      if (!result.ok && isPendingApproval(result.error)) {
+        reason = result.error.reason;
+      }
+      return {
+        status: "paused",
+        runId,
+        pendingApprovals: newPendingApprovals,
+        reason
+      };
+    }
+    await workflowStateStore.delete(runId);
+    logger(`Workflow ${runId} resumed and completed`);
+    return { status: "resumed", runId, result };
+  }
+  async function grantApprovalFn(approvalKey, value, opts) {
+    await approvalStore.grantApproval(approvalKey, value, {
+      approvedBy: opts?.approvedBy
+    });
+    const grantedAt = Date.now();
+    const resumedWorkflows = [];
+    if (opts?.autoResume !== false) {
+      const waitingWorkflows = await workflowStateStore.findByPendingApproval(approvalKey);
+      for (const runId of waitingWorkflows) {
+        resumedWorkflows.push(runId);
+      }
+    }
+    if (notificationChannel?.onApprovalResolved) {
+      await notificationChannel.onApprovalResolved({
+        approvalKey,
+        action: "approved",
+        actorId: opts?.approvedBy,
+        resolvedAt: grantedAt,
+        value
+      });
+    }
+    logger(`Approval ${approvalKey} granted by ${opts?.approvedBy ?? "unknown"}`);
+    return { grantedAt, resumedWorkflows };
+  }
+  async function rejectApprovalFn(approvalKey, reason, opts) {
+    await approvalStore.rejectApproval(approvalKey, reason, {
+      rejectedBy: opts?.rejectedBy
+    });
+    if (notificationChannel?.onApprovalResolved) {
+      await notificationChannel.onApprovalResolved({
+        approvalKey,
+        action: "rejected",
+        actorId: opts?.rejectedBy,
+        resolvedAt: Date.now(),
+        reason
+      });
+    }
+    logger(`Approval ${approvalKey} rejected: ${reason}`);
+  }
+  async function editApprovalFn(approvalKey, originalValue, editedValue, opts) {
+    await approvalStore.editApproval(approvalKey, originalValue, editedValue, {
+      editedBy: opts?.editedBy
+    });
+    const editedAt = Date.now();
+    if (notificationChannel?.onApprovalResolved) {
+      await notificationChannel.onApprovalResolved({
+        approvalKey,
+        action: "edited",
+        actorId: opts?.editedBy,
+        resolvedAt: editedAt,
+        value: editedValue,
+        originalValue
+      });
+    }
+    logger(`Approval ${approvalKey} edited by ${opts?.editedBy ?? "unknown"}`);
+    return { editedAt };
+  }
+  async function pollApproval(approvalKey, opts) {
+    const {
+      intervalMs = 1e3,
+      maxPolls,
+      timeoutMs,
+      onPollStart,
+      onPollComplete
+    } = opts ?? {};
+    const startTime = Date.now();
+    let pollCount = 0;
+    while (true) {
+      onPollStart?.();
+      const status = await approvalStore.getApproval(approvalKey);
+      onPollComplete?.(status);
+      if (status.status !== "pending") {
+        return status;
+      }
+      pollCount++;
+      if (maxPolls !== void 0 && pollCount >= maxPolls) {
+        return { status: "pending" };
+      }
+      if (timeoutMs !== void 0 && Date.now() - startTime >= timeoutMs) {
+        return { status: "pending" };
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+  async function getWorkflowStatus(runId) {
+    return workflowStateStore.load(runId);
+  }
+  async function listPendingWorkflows(workflowName) {
+    return workflowStateStore.list({
+      workflowName,
+      hasPendingApprovals: true
+    });
+  }
+  async function cleanup(maxAgeMs) {
+    const allWorkflows = await workflowStateStore.list();
+    let cleaned = 0;
+    const cutoff = Date.now() - maxAgeMs;
+    for (const runId of allWorkflows) {
+      const state = await workflowStateStore.load(runId);
+      if (state && state.updatedAt < cutoff && state.pendingApprovals.length === 0) {
+        await workflowStateStore.delete(runId);
+        cleaned++;
+      }
+    }
+    logger(`Cleaned up ${cleaned} old workflow states`);
+    return cleaned;
+  }
+  return {
+    execute,
+    resume,
+    grantApproval: grantApprovalFn,
+    rejectApproval: rejectApprovalFn,
+    editApproval: editApprovalFn,
+    pollApproval,
+    getWorkflowStatus,
+    listPendingWorkflows,
+    cleanup
+  };
+}
+function createApprovalWebhookHandler(store) {
+  return async (request) => {
+    const { key, action, value, originalValue, editedValue, reason, actorId } = request;
+    try {
+      switch (action) {
+        case "approve":
+          await store.grantApproval(key, value, { approvedBy: actorId });
+          return {
+            success: true,
+            message: `Approval ${key} granted`,
+            data: { key, action, timestamp: Date.now() }
+          };
+        case "reject":
+          if (!reason) {
+            return { success: false, message: "Reason is required for rejection" };
+          }
+          await store.rejectApproval(key, reason, { rejectedBy: actorId });
+          return {
+            success: true,
+            message: `Approval ${key} rejected`,
+            data: { key, action, timestamp: Date.now() }
+          };
+        case "edit":
+          if (originalValue === void 0 || editedValue === void 0) {
+            return { success: false, message: "Both originalValue and editedValue are required for edit" };
+          }
+          await store.editApproval(key, originalValue, editedValue, { editedBy: actorId });
+          return {
+            success: true,
+            message: `Approval ${key} edited`,
+            data: { key, action, timestamp: Date.now() }
+          };
+        case "cancel":
+          await store.cancelApproval(key);
+          return {
+            success: true,
+            message: `Approval ${key} cancelled`,
+            data: { key, action, timestamp: Date.now() }
+          };
+        default:
+          return { success: false, message: `Unknown action: ${action}` };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : String(error)
+      };
+    }
+  };
+}
+function createApprovalChecker(store) {
+  return (key) => async () => {
+    const status = await store.getApproval(key);
+    switch (status.status) {
+      case "pending":
+        return { status: "pending" };
+      case "approved":
+        return { status: "approved", value: status.value };
+      case "edited":
+        return { status: "approved", value: status.editedValue };
+      case "rejected":
+        return { status: "rejected", reason: status.reason };
+      case "expired":
+        return { status: "rejected", reason: "Approval request expired" };
+      default:
+        return { status: "pending" };
+    }
+  };
+}
+export {
+  clearStep,
+  createApprovalChecker,
+  createApprovalStateCollector,
+  createApprovalStep,
+  createApprovalWebhookHandler,
+  createHITLOrchestrator,
+  createMemoryApprovalStore,
+  createMemoryWorkflowStateStore,
+  gatedStep,
+  getPendingApprovals,
+  hasPendingApproval,
+  injectApproval,
+  isApprovalRejected,
+  isPendingApproval,
+  pendingApproval
+};
+//# sourceMappingURL=hitl.js.map