@upstash/workflow 0.3.0-rc → 0.3.0-rc1

package/astro.js

@@ -38,26 +38,36 @@ var WorkflowError = class extends import_qstash.QstashError {
   }
 };
 var WorkflowAbort = class extends Error {
-  stepInfo;
   stepName;
+  stepInfo;
   /**
-   * whether workflow is to be canceled on abort
-   */
-  cancelWorkflow;
-  /**
-   *
    * @param stepName name of the aborting step
    * @param stepInfo step information
-   * @param cancelWorkflow
    */
-  constructor(stepName, stepInfo, cancelWorkflow = false) {
+  constructor(stepName, stepInfo) {
     super(
       `This is an Upstash Workflow error thrown after a step executes. It is expected to be raised. Make sure that you await for each step. Also, if you are using try/catch blocks, you should not wrap context.run/sleep/sleepUntil/call methods with try/catch. Aborting workflow after executing step '${stepName}'.`
     );
     this.name = "WorkflowAbort";
     this.stepName = stepName;
     this.stepInfo = stepInfo;
-    this.cancelWorkflow = cancelWorkflow;
+  }
+};
+var WorkflowAuthError = class extends WorkflowAbort {
+  /**
+   * @param stepName name of the step found during authorization
+   */
+  constructor(stepName) {
+    super(stepName);
+    this.name = "WorkflowAuthError";
+    this.message = `This is an Upstash Workflow error thrown during authorization check. Found step '${stepName}' during dry-run.`;
+  }
+};
+var WorkflowCancelAbort = class extends WorkflowAbort {
+  constructor() {
+    super("cancel");
+    this.name = "WorkflowCancelAbort";
+    this.message = "Workflow has been canceled by user via context.cancel().";
   }
 };
 var WorkflowNonRetryableError = class extends WorkflowAbort {
@@ -65,22 +75,22 @@ var WorkflowNonRetryableError = class extends WorkflowAbort {
    * @param message error message to be displayed
    */
   constructor(message) {
-    super("fail", void 0, false);
+    super("non-retryable-error");
     this.name = "WorkflowNonRetryableError";
-    if (message) this.message = message;
+    this.message = message ?? "Workflow failed with non-retryable error.";
   }
 };
 var WorkflowRetryAfterError = class extends WorkflowAbort {
   retryAfter;
   /**
-   * @param retryAfter time in seconds after which the workflow should be retried
    * @param message error message to be displayed
+   * @param retryAfter time in seconds after which the workflow should be retried
    */
   constructor(message, retryAfter) {
-    super("retry", void 0, false);
+    super("retry-after-error");
     this.name = "WorkflowRetryAfterError";
+    this.message = message;
     this.retryAfter = retryAfter;
-    if (message) this.message = message;
   }
 };
 var formatWorkflowError = (error) => {
@@ -132,15 +142,21 @@ var makeCancelRequest = async (requester, workflowRunId) => {
   });
   return true;
 };
-var getSteps = async (requester, workflowRunId, messageId, debug) => {
+var getSteps = async (requester, workflowRunId, messageId, dispatchDebug) => {
   try {
     const steps = await requester.request({
       path: ["v2", "workflows", "runs", workflowRunId],
       parseResponseAsJson: true
     });
+    if (steps.length === 1) {
+      return {
+        steps,
+        workflowRunEnded: false
+      };
+    }
     if (!messageId) {
-      await debug?.log("INFO", "ENDPOINT_START", {
-        message: `Pulled ${steps.length} steps from QStashand returned them without filtering with messageId.`
+      await dispatchDebug?.("onInfo", {
+        info: `Pulled ${steps.length} steps from QStashand returned them without filtering with messageId.`
       });
       return { steps, workflowRunEnded: false };
     } else {
@@ -149,16 +165,15 @@ var getSteps = async (requester, workflowRunId, messageId, debug) => {
         return { steps: [], workflowRunEnded: false };
       }
       const filteredSteps = steps.slice(0, index + 1);
-      await debug?.log("INFO", "ENDPOINT_START", {
-        message: `Pulled ${steps.length} steps from QStash and filtered them to ${filteredSteps.length} using messageId.`
+      await dispatchDebug?.("onInfo", {
+        info: `Pulled ${steps.length} steps from QStash and filtered them to ${filteredSteps.length} using messageId.`
       });
       return { steps: filteredSteps, workflowRunEnded: false };
     }
   } catch (error) {
     if (isInstanceOf(error, import_qstash2.QstashError) && error.status === 404) {
-      await debug?.log("WARN", "ENDPOINT_START", {
-        message: "Couldn't fetch workflow run steps. This can happen if the workflow run succesfully ends before some callback is executed.",
-        error
+      await dispatchDebug?.("onWarning", {
+        warning: "Couldn't fetch workflow run steps. This can happen if the workflow run succesfully ends before some callback is executed."
       });
       return { steps: void 0, workflowRunEnded: true };
     } else {
@@ -172,15 +187,18 @@ var WORKFLOW_ID_HEADER = "Upstash-Workflow-RunId";
 var WORKFLOW_INIT_HEADER = "Upstash-Workflow-Init";
 var WORKFLOW_URL_HEADER = "Upstash-Workflow-Url";
 var WORKFLOW_FAILURE_HEADER = "Upstash-Workflow-Is-Failure";
+var WORKFLOW_FAILURE_CALLBACK_HEADER = "Upstash-Workflow-Failure-Callback";
 var WORKFLOW_FEATURE_HEADER = "Upstash-Feature-Set";
 var WORKFLOW_INVOKE_COUNT_HEADER = "Upstash-Workflow-Invoke-Count";
 var WORKFLOW_LABEL_HEADER = "Upstash-Label";
+var WORKFLOW_UNKOWN_SDK_VERSION_HEADER = "Upstash-Workflow-Unknown-Sdk";
+var WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER = "upstash-workflow-trigger-by-sdk";
 var WORKFLOW_PROTOCOL_VERSION = "1";
 var WORKFLOW_PROTOCOL_VERSION_HEADER = "Upstash-Workflow-Sdk-Version";
 var DEFAULT_CONTENT_TYPE = "application/json";
 var NO_CONCURRENCY = 1;
 var DEFAULT_RETRIES = 3;
-var VERSION = "v0.3.0-rc";
+var VERSION = "v1.0.0";
 var SDK_TELEMETRY = `@upstash/workflow@${VERSION}`;
 var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
@@ -198,8 +216,8 @@ var NANOID_LENGTH = 21;
 function getRandomInt() {
   return Math.floor(Math.random() * NANOID_CHARS.length);
 }
-function nanoid() {
-  return Array.from({ length: NANOID_LENGTH }).map(() => NANOID_CHARS[getRandomInt()]).join("");
+function nanoid(length = NANOID_LENGTH) {
+  return Array.from({ length }).map(() => NANOID_CHARS[getRandomInt()]).join("");
 }
 function getWorkflowRunId(id) {
   return `wfr_${id ?? nanoid()}`;
@@ -216,6 +234,46 @@ function decodeBase64(base64) {
     return binString;
   }
 }
+function getUserIdFromToken(qstashClient) {
+  try {
+    const token = qstashClient.token;
+    const decodedToken = decodeBase64(token);
+    const tokenPayload = JSON.parse(decodedToken);
+    const userId = tokenPayload.UserID;
+    if (!userId) {
+      throw new WorkflowError("QStash token payload does not contain userId");
+    }
+    return userId;
+  } catch (error) {
+    throw new WorkflowError(
+      `Failed to decode QStash token while running create webhook step: ${error.message}`
+    );
+  }
+}
+function getQStashUrl(qstashClient) {
+  try {
+    const requester = qstashClient.http;
+    const baseUrl = requester.baseUrl;
+    if (!baseUrl) {
+      throw new WorkflowError("QStash client does not have a baseUrl");
+    }
+    return baseUrl;
+  } catch (error) {
+    throw new WorkflowError(`Failed to get QStash URL from client: ${error.message}`);
+  }
+}
+function getEventId() {
+  return `evt_${nanoid(15)}`;
+}
+function stringifyBody(body) {
+  if (body === void 0) {
+    return void 0;
+  }
+  if (typeof body === "string") {
+    return body;
+  }
+  return JSON.stringify(body);
+}
 
 // node_modules/neverthrow/dist/index.es.js
 var defaultErrorConfig = {
@@ -641,7 +699,9 @@ var StepTypes = [
   "Call",
   "Wait",
   "Notify",
-  "Invoke"
+  "Invoke",
+  "CreateWebhook",
+  "WaitForWebhook"
 ];
 
 // src/workflow-requests.ts
@@ -657,23 +717,26 @@ var triggerFirstInvocation = async (params) => {
       invokeCount,
       delay,
       notBefore,
-      keepTriggerConfig
+      failureUrl,
+      retries,
+      retryDelay,
+      flowControl,
+      unknownSdk
     }) => {
       const { headers } = getHeaders({
         initHeaderValue: "true",
         workflowConfig: {
           workflowRunId: workflowContext.workflowRunId,
           workflowUrl: workflowContext.url,
-          failureUrl: workflowContext.failureUrl,
-          retries: workflowContext.retries,
-          retryDelay: workflowContext.retryDelay,
+          failureUrl,
+          retries,
+          retryDelay,
           telemetry: telemetry2,
-          flowControl: workflowContext.flowControl,
+          flowControl,
           useJSONContent: useJSONContent ?? false
         },
         invokeCount: invokeCount ?? 0,
-        userHeaders: workflowContext.headers,
-        keepTriggerConfig
+        userHeaders: workflowContext.headers
       });
       if (workflowContext.headers.get("content-type")) {
         headers["content-type"] = workflowContext.headers.get("content-type");
@@ -681,6 +744,9 @@ var triggerFirstInvocation = async (params) => {
       if (useJSONContent) {
         headers["content-type"] = "application/json";
       }
+      if (unknownSdk) {
+        headers[WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER] = "true";
+      }
       if (workflowContext.label) {
         headers[WORKFLOW_LABEL_HEADER] = workflowContext.label;
       }
@@ -701,21 +767,15 @@ var triggerFirstInvocation = async (params) => {
     for (let i = 0; i < results.length; i++) {
       const result = results[i];
       const invocationParams = firstInvocationParams[i];
+      invocationParams.middlewareManager?.assignContext(invocationParams.workflowContext);
       if (result.deduplicated) {
-        await invocationParams.debug?.log("WARN", "SUBMIT_FIRST_INVOCATION", {
-          message: `Workflow run ${invocationParams.workflowContext.workflowRunId} already exists. A new one isn't created.`,
-          headers: invocationBatch[i].headers,
-          requestPayload: invocationParams.workflowContext.requestPayload,
-          url: invocationParams.workflowContext.url,
-          messageId: result.messageId
+        await invocationParams.middlewareManager?.dispatchDebug("onWarning", {
+          warning: `Workflow run ${invocationParams.workflowContext.workflowRunId} already exists. A new one isn't created.`
         });
         invocationStatuses.push("workflow-run-already-exists");
       } else {
-        await invocationParams.debug?.log("SUBMIT", "SUBMIT_FIRST_INVOCATION", {
-          headers: invocationBatch[i].headers,
-          requestPayload: invocationParams.workflowContext.requestPayload,
-          url: invocationParams.workflowContext.url,
-          messageId: result.messageId
+        await invocationParams.middlewareManager?.dispatchDebug("onInfo", {
+          info: `Workflow run started successfully with URL ${invocationParams.workflowContext.url}.`
         });
         invocationStatuses.push("success");
       }
@@ -737,7 +797,7 @@ var triggerRouteFunction = async ({
   onCleanup,
   onStep,
   onCancel,
-  debug
+  middlewareManager
 }) => {
   try {
     const result = await onStep();
@@ -746,27 +806,25 @@ var triggerRouteFunction = async ({
   } catch (error) {
     const error_ = error;
     if (isInstanceOf(error, import_qstash3.QstashError) && error.status === 400) {
-      await debug?.log("WARN", "RESPONSE_WORKFLOW", {
-        message: `tried to append to a cancelled workflow. exiting without publishing.`,
-        name: error.name,
-        errorMessage: error.message
+      await middlewareManager?.dispatchDebug("onWarning", {
+        warning: `Tried to append to a cancelled workflow. Exiting without publishing. Error: ${error.message}`
       });
       return ok("workflow-was-finished");
     } else if (isInstanceOf(error_, WorkflowNonRetryableError) || isInstanceOf(error_, WorkflowRetryAfterError)) {
       return ok(error_);
-    } else if (!isInstanceOf(error_, WorkflowAbort)) {
-      return err(error_);
-    } else if (error_.cancelWorkflow) {
+    } else if (isInstanceOf(error_, WorkflowCancelAbort)) {
       await onCancel();
       return ok("workflow-finished");
-    } else {
+    } else if (isInstanceOf(error_, WorkflowAbort)) {
       return ok("step-finished");
+    } else {
+      return err(error_);
     }
   }
 };
-var triggerWorkflowDelete = async (workflowContext, result, debug, cancel = false) => {
-  await debug?.log("SUBMIT", "SUBMIT_CLEANUP", {
-    deletedWorkflowRunId: workflowContext.workflowRunId
+var triggerWorkflowDelete = async (workflowContext, result, cancel = false, dispatchDebug) => {
+  await dispatchDebug?.("onInfo", {
+    info: `Deleting workflow run ${workflowContext.workflowRunId} from QStash` + (cancel ? " with cancel=true." : ".")
   });
   await workflowContext.qstashClient.http.request({
     path: ["v2", "workflows", "runs", `${workflowContext.workflowRunId}?cancel=${cancel}`],
@@ -774,18 +832,16 @@ var triggerWorkflowDelete = async (workflowContext, result, debug, cancel = fals
     parseResponseAsJson: false,
     body: JSON.stringify(result)
   });
-  await debug?.log(
-    "SUBMIT",
-    "SUBMIT_CLEANUP",
-    `workflow run ${workflowContext.workflowRunId} deleted.`
-  );
+  await dispatchDebug?.("onInfo", {
+    info: `Workflow run ${workflowContext.workflowRunId} deleted from QStash successfully.`
+  });
 };
 var recreateUserHeaders = (headers) => {
   const filteredHeaders = new Headers();
   const pairs = headers.entries();
   for (const [header, value] of pairs) {
     const headerLowerCase = header.toLowerCase();
-    const isUserHeader = !headerLowerCase.startsWith("upstash-workflow-") && // https://vercel.com/docs/edge-network/headers/request-headers#x-vercel-id
+    const isUserHeader = headerLowerCase !== "upstash-region" && !headerLowerCase.startsWith("upstash-workflow-") && // https://vercel.com/docs/edge-network/headers/request-headers#x-vercel-id
     !headerLowerCase.startsWith("x-vercel-") && !headerLowerCase.startsWith("x-forwarded-") && // https://blog.cloudflare.com/preventing-request-loops-using-cdn-loop/
     headerLowerCase !== "cf-connecting-ip" && headerLowerCase !== "cdn-loop" && headerLowerCase !== "cf-ew-via" && headerLowerCase !== "cf-ray" && // For Render https://render.com
     headerLowerCase !== "render-proxy-ttl" || headerLowerCase === WORKFLOW_LABEL_HEADER.toLocaleLowerCase();
@@ -800,12 +856,8 @@ var handleThirdPartyCallResult = async ({
   requestPayload,
   client,
   workflowUrl,
-  failureUrl,
-  retries,
-  retryDelay,
   telemetry: telemetry2,
-  flowControl,
-  debug
+  middlewareManager
 }) => {
   try {
     if (request.headers.get("Upstash-Workflow-Callback")) {
@@ -822,7 +874,7 @@ var handleThirdPartyCallResult = async ({
           client.http,
           workflowRunId2,
           messageId,
-          debug
+          middlewareManager?.dispatchDebug.bind(middlewareManager)
         );
         if (workflowRunEnded) {
           return ok("workflow-ended");
@@ -836,9 +888,8 @@ var handleThirdPartyCallResult = async ({
       }
       const callbackMessage = JSON.parse(callbackPayload);
       if (!(callbackMessage.status >= 200 && callbackMessage.status < 300) && callbackMessage.maxRetries && callbackMessage.retried !== callbackMessage.maxRetries) {
-        await debug?.log("WARN", "SUBMIT_THIRD_PARTY_RESULT", {
-          status: callbackMessage.status,
-          body: atob(callbackMessage.body ?? "")
+        await middlewareManager?.dispatchDebug("onWarning", {
+          warning: `Third party call returned status ${callbackMessage.status}. Retrying (${callbackMessage.retried} out of ${callbackMessage.maxRetries}).`
         });
         console.warn(
           `Workflow Warning: "context.call" failed with status ${callbackMessage.status} and will retry (retried ${callbackMessage.retried ?? 0} out of ${callbackMessage.maxRetries} times). Error Message:
@@ -871,11 +922,7 @@ ${atob(callbackMessage.body ?? "")}`
         workflowConfig: {
           workflowRunId,
           workflowUrl,
-          failureUrl,
-          retries,
-          retryDelay,
-          telemetry: telemetry2,
-          flowControl
+          telemetry: telemetry2
         },
         userHeaders,
         invokeCount: Number(invokeCount)
@@ -892,19 +939,17 @@ ${atob(callbackMessage.body ?? "")}`
         out: JSON.stringify(callResponse),
         concurrent: Number(concurrentString)
       };
-      await debug?.log("SUBMIT", "SUBMIT_THIRD_PARTY_RESULT", {
-        step: callResultStep,
-        headers: requestHeaders,
-        url: workflowUrl
+      await middlewareManager?.dispatchDebug("onInfo", {
+        info: `Submitting third party call result, step ${stepName} (${stepIdString}).`
       });
-      const result = await client.publishJSON({
+      await client.publishJSON({
         headers: requestHeaders,
         method: "POST",
         body: callResultStep,
         url: workflowUrl
       });
-      await debug?.log("SUBMIT", "SUBMIT_THIRD_PARTY_RESULT", {
-        messageId: result.messageId
+      await middlewareManager?.dispatchDebug("onInfo", {
+        info: `Third party call result submitted successfully, step ${stepName} (${stepIdString}).`
       });
       return ok("is-call-return");
     } else {
@@ -953,15 +998,17 @@ If you want to disable QStash Verification, you should clear env variables QSTAS
 // src/context/steps.ts
 var BaseLazyStep = class _BaseLazyStep {
   stepName;
-  constructor(stepName) {
+  context;
+  constructor(context, stepName) {
+    this.context = context;
     if (!stepName) {
       throw new WorkflowError(
         "A workflow step name cannot be undefined or an empty string. Please provide a name for your workflow step."
       );
     }
     if (typeof stepName !== "string") {
-      console.warn(
-        "Workflow Warning: A workflow step name must be a string. In a future release, this will throw an error."
+      throw new WorkflowError(
+        `A workflow step name must be a string. Received "${stepName}" (${typeof stepName}).`
       );
     }
     this.stepName = stepName;
@@ -971,13 +1018,14 @@ var BaseLazyStep = class _BaseLazyStep {
    *
    * will be called when returning the steps to the context from auto executor
    *
-   * @param out field of the step
+   * @param step step
    * @returns parsed out field
    */
-  parseOut(out) {
+  parseOut(step) {
+    const out = step.out;
     if (out === void 0) {
       if (this.allowUndefinedOut) {
-        return void 0;
+        return this.handleUndefinedOut(step);
       } else {
         throw new WorkflowError(
           `Error while parsing output of ${this.stepType} step. Expected a string, but got: undefined`
@@ -985,27 +1033,26 @@ var BaseLazyStep = class _BaseLazyStep {
       }
     }
     if (typeof out === "object") {
-      if (this.stepType !== "Wait") {
-        console.warn(
-          `Error while parsing ${this.stepType} step output. Expected a string, but got object. Please reach out to Upstash Support.`
-        );
-        return out;
-      }
-      return {
-        ...out,
-        eventData: _BaseLazyStep.tryParsing(out.eventData)
-      };
+      console.warn(
+        `Error while parsing ${this.stepType} step output. Expected a string, but got object. Please reach out to Upstash Support.`
+      );
+      return out;
     }
     if (typeof out !== "string") {
       throw new WorkflowError(
         `Error while parsing output of ${this.stepType} step. Expected a string or undefined, but got: ${typeof out}`
       );
     }
-    return this.safeParseOut(out);
+    return this.safeParseOut(out, step);
   }
-  safeParseOut(out) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  safeParseOut(out, step) {
     return _BaseLazyStep.tryParsing(out);
   }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  handleUndefinedOut(step) {
+    return void 0;
+  }
   static tryParsing(stepOut) {
     try {
       return JSON.parse(stepOut);
@@ -1023,12 +1070,8 @@ var BaseLazyStep = class _BaseLazyStep {
       workflowConfig: {
         workflowRunId: context.workflowRunId,
         workflowUrl: context.url,
-        failureUrl: context.failureUrl,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
         useJSONContent: false,
-        telemetry: telemetry2,
-        flowControl: context.flowControl
+        telemetry: telemetry2
       },
       userHeaders: context.headers,
       invokeCount,
@@ -1044,9 +1087,6 @@ var BaseLazyStep = class _BaseLazyStep {
         body,
         headers,
         method: "POST",
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         url: context.url
       }
     ]);
@@ -1056,8 +1096,8 @@ var LazyFunctionStep = class extends BaseLazyStep {
   stepFunction;
   stepType = "Run";
   allowUndefinedOut = true;
-  constructor(stepName, stepFunction) {
-    super(stepName);
+  constructor(context, stepName, stepFunction) {
+    super(context, stepName);
     this.stepFunction = stepFunction;
   }
   getPlanStep(concurrent, targetStep) {
@@ -1087,8 +1127,8 @@ var LazySleepStep = class extends BaseLazyStep {
   sleep;
   stepType = "SleepFor";
   allowUndefinedOut = true;
-  constructor(stepName, sleep) {
-    super(stepName);
+  constructor(context, stepName, sleep) {
+    super(context, stepName);
     this.sleep = sleep;
   }
   getPlanStep(concurrent, targetStep) {
@@ -1117,9 +1157,6 @@ var LazySleepStep = class extends BaseLazyStep {
         headers,
         method: "POST",
         url: context.url,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         delay: isParallel ? void 0 : this.sleep
       }
     ]);
@@ -1129,8 +1166,8 @@ var LazySleepUntilStep = class extends BaseLazyStep {
   sleepUntil;
   stepType = "SleepUntil";
   allowUndefinedOut = true;
-  constructor(stepName, sleepUntil) {
-    super(stepName);
+  constructor(context, stepName, sleepUntil) {
+    super(context, stepName);
     this.sleepUntil = sleepUntil;
   }
   getPlanStep(concurrent, targetStep) {
@@ -1162,9 +1199,6 @@ var LazySleepUntilStep = class extends BaseLazyStep {
         headers,
         method: "POST",
         url: context.url,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         notBefore: isParallel ? void 0 : this.sleepUntil
       }
     ]);
@@ -1179,20 +1213,18 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
   retryDelay;
   timeout;
   flowControl;
-  stringifyBody;
   stepType = "Call";
   allowUndefinedOut = false;
-  constructor(stepName, url, method, body, headers, retries, retryDelay, timeout, flowControl, stringifyBody) {
-    super(stepName);
-    this.url = url;
-    this.method = method;
-    this.body = body;
-    this.headers = headers;
-    this.retries = retries;
-    this.retryDelay = retryDelay;
-    this.timeout = timeout;
-    this.flowControl = flowControl;
-    this.stringifyBody = stringifyBody;
+  constructor(params) {
+    super(params.context, params.stepName);
+    this.url = params.url;
+    this.method = params.method ?? "GET";
+    this.body = params.body;
+    this.headers = params.headers ?? {};
+    this.retries = params.retries ?? 0;
+    this.retryDelay = params.retryDelay;
+    this.timeout = params.timeout;
+    this.flowControl = params.flowControl;
   }
   getPlanStep(concurrent, targetStep) {
     return {
@@ -1289,7 +1321,7 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
         "Upstash-Callback-Workflow-CallType": "fromCallback",
         "Upstash-Callback-Workflow-Init": "false",
         "Upstash-Callback-Workflow-Url": context.url,
-        "Upstash-Callback-Feature-Set": "LazyFetch,InitialBody,WF_DetectTrigger",
+        "Upstash-Callback-Feature-Set": "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig",
         "Upstash-Callback-Forward-Upstash-Workflow-Callback": "true",
         "Upstash-Callback-Forward-Upstash-Workflow-StepId": step.stepId.toString(),
         "Upstash-Callback-Forward-Upstash-Workflow-StepName": this.stepName,
@@ -1302,22 +1334,10 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
     };
   }
   async submitStep({ context, headers }) {
-    let callBody;
-    if (this.stringifyBody) {
-      callBody = JSON.stringify(this.body);
-    } else {
-      if (typeof this.body === "string") {
-        callBody = this.body;
-      } else {
-        throw new WorkflowError(
-          "When stringifyBody is false, body must be a string. Please check the body type of your call step."
-        );
-      }
-    }
     return await context.qstashClient.batch([
       {
         headers,
-        body: callBody,
+        body: this.body,
         method: this.method,
         url: this.url,
         retries: DEFAULT_RETRIES === this.retries ? void 0 : this.retries,
@@ -1327,13 +1347,12 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
     ]);
   }
 };
-var LazyWaitForEventStep = class extends BaseLazyStep {
+var LazyWaitEventStep = class extends BaseLazyStep {
   eventId;
   timeout;
-  stepType = "Wait";
   allowUndefinedOut = false;
-  constructor(stepName, eventId, timeout) {
-    super(stepName);
+  constructor(context, stepName, eventId, timeout) {
+    super(context, stepName);
     this.eventId = eventId;
     this.timeout = timeout;
   }
@@ -1358,13 +1377,6 @@ var LazyWaitForEventStep = class extends BaseLazyStep {
       concurrent
     });
   }
-  safeParseOut(out) {
-    const result = JSON.parse(out);
-    return {
-      ...result,
-      eventData: BaseLazyStep.tryParsing(result.eventData)
-    };
-  }
   getHeaders({ context, telemetry: telemetry2, invokeCount, step }) {
     const headers = super.getHeaders({ context, telemetry: telemetry2, invokeCount, step });
     headers.headers["Upstash-Workflow-CallType"] = "step";
@@ -1398,7 +1410,7 @@ var LazyWaitForEventStep = class extends BaseLazyStep {
       timeoutHeaders,
       step: {
         stepId: step.stepId,
-        stepType: "Wait",
+        stepType: this.stepType,
         stepName: step.stepName,
         concurrent: step.concurrent,
         targetStep: step.targetStep
@@ -1419,8 +1431,8 @@ var LazyWaitForEventStep = class extends BaseLazyStep {
 };
 var LazyNotifyStep = class extends LazyFunctionStep {
   stepType = "Notify";
-  constructor(stepName, eventId, eventData, requester) {
-    super(stepName, async () => {
+  constructor(context, stepName, eventId, eventData, requester) {
+    super(context, stepName, async () => {
       const notifyResponse = await makeNotifyRequest(requester, eventId, eventData);
       return {
         eventId,
@@ -1445,28 +1457,10 @@ var LazyInvokeStep = class extends BaseLazyStep {
    * workflow id of the invoked workflow
    */
   workflowId;
-  constructor(stepName, {
-    workflow,
-    body,
-    headers = {},
-    workflowRunId,
-    retries,
-    retryDelay,
-    flowControl,
-    stringifyBody = true
-  }) {
-    super(stepName);
-    this.params = {
-      workflow,
-      body,
-      headers,
-      workflowRunId: getWorkflowRunId(workflowRunId),
-      retries,
-      retryDelay,
-      flowControl,
-      stringifyBody
-    };
-    const { workflowId } = workflow;
+  constructor(context, stepName, params) {
+    super(context, stepName);
+    this.params = params;
+    const { workflowId } = params.workflow;
     if (!workflowId) {
       throw new WorkflowError("You can only invoke workflow which has a workflowId");
     }
@@ -1506,31 +1500,18 @@ var LazyInvokeStep = class extends BaseLazyStep {
       workflowConfig: {
         workflowRunId: context.workflowRunId,
         workflowUrl: context.url,
-        failureUrl: context.failureUrl,
-        retries: context.retries,
-        retryDelay: context.retryDelay,
         telemetry: telemetry2,
-        flowControl: context.flowControl,
         useJSONContent: false
       },
       userHeaders: context.headers,
       invokeCount
     });
+    context.qstashClient.http.headers?.forEach((value, key) => {
+      invokerHeaders[key] = value;
+    });
     invokerHeaders["Upstash-Workflow-Runid"] = context.workflowRunId;
-    let invokeBody;
-    if (this.params.stringifyBody) {
-      invokeBody = JSON.stringify(this.params.body);
-    } else {
-      if (typeof this.params.body === "string") {
-        invokeBody = this.params.body;
-      } else {
-        throw new WorkflowError(
-          "When stringifyBody is false, body must be a string. Please check the body type of your invoke step."
-        );
-      }
-    }
     const request = {
-      body: invokeBody,
+      body: stringifyBody(this.params.body),
       headers: Object.fromEntries(
         Object.entries(invokerHeaders).map((pairs) => [pairs[0], [pairs[1]]])
       ),
@@ -1541,34 +1522,19 @@ var LazyInvokeStep = class extends BaseLazyStep {
     return JSON.stringify(request);
   }
   getHeaders({ context, telemetry: telemetry2, invokeCount }) {
-    const {
-      workflow,
-      headers = {},
-      workflowRunId = getWorkflowRunId(),
-      retries,
-      retryDelay,
-      flowControl
-    } = this.params;
+    const { workflow, headers = {}, workflowRunId, retries, retryDelay, flowControl } = this.params;
     const newUrl = context.url.replace(/[^/]+$/, this.workflowId);
-    const {
-      retries: workflowRetries,
-      retryDelay: workflowRetryDelay,
-      failureFunction,
-      failureUrl,
-      useJSONContent,
-      flowControl: workflowFlowControl
-    } = workflow.options;
     const { headers: triggerHeaders, contentType } = getHeaders({
       initHeaderValue: "true",
       workflowConfig: {
-        workflowRunId,
+        workflowRunId: getWorkflowRunId(workflowRunId),
         workflowUrl: newUrl,
-        retries: retries ?? workflowRetries,
-        retryDelay: retryDelay ?? workflowRetryDelay,
+        retries,
+        retryDelay,
         telemetry: telemetry2,
-        failureUrl: failureFunction ? newUrl : failureUrl,
-        flowControl: flowControl ?? workflowFlowControl,
-        useJSONContent: useJSONContent ?? false
+        failureUrl: newUrl,
+        flowControl,
+        useJSONContent: workflow.useJSONContent ?? false
       },
       invokeCount: invokeCount + 1,
       userHeaders: new Headers(headers)
@@ -1587,6 +1553,88 @@ var LazyInvokeStep = class extends BaseLazyStep {
     return [result];
   }
 };
+var LazyCreateWebhookStep = class extends BaseLazyStep {
+  stepType = "CreateWebhook";
+  allowUndefinedOut = false;
+  getPlanStep(concurrent, targetStep) {
+    return {
+      stepId: 0,
+      stepName: this.stepName,
+      stepType: this.stepType,
+      concurrent,
+      targetStep
+    };
+  }
+  async getResultStep(concurrent, stepId) {
+    return {
+      stepId,
+      stepName: this.stepName,
+      stepType: this.stepType,
+      out: void 0,
+      concurrent
+    };
+  }
+  getBody({ step, context }) {
+    const userId = getUserIdFromToken(context.qstashClient);
+    const workflowRunId = context.workflowRunId;
+    const eventId = getEventId();
+    const qstashUrl = getQStashUrl(this.context.qstashClient);
+    return JSON.stringify({
+      ...step,
+      out: JSON.stringify({
+        webhookUrl: `${qstashUrl}/v2/workflows/hooks/${userId}/${workflowRunId}/${eventId}`,
+        eventId
+      })
+    });
+  }
+};
+var LazyWaitForWebhookStep = class extends LazyWaitEventStep {
+  stepType = "WaitForWebhook";
+  allowUndefinedOut = true;
+  constructor(context, stepName, webhook, timeout) {
+    super(context, stepName, webhook.eventId, timeout);
+  }
+  safeParseOut(out) {
+    const eventData = decodeBase64(out);
+    const parsedEventData = BaseLazyStep.tryParsing(eventData);
+    const body = parsedEventData.body;
+    const parsedBody = typeof body === "string" ? decodeBase64(body) : void 0;
+    const request = new Request(
+      `${parsedEventData.proto}://${parsedEventData.host}${parsedEventData.url}`,
+      {
+        method: parsedEventData.method,
+        headers: parsedEventData.header,
+        body: parsedBody
+      }
+    );
+    return {
+      request,
+      timeout: false
+    };
+  }
+  handleUndefinedOut() {
+    return {
+      timeout: true,
+      request: void 0
+    };
+  }
+};
+var LazyWaitForEventStep = class extends LazyWaitEventStep {
+  stepType = "Wait";
+  allowUndefinedOut = true;
+  parseWaitForEventOut(out, waitTimeout) {
+    return {
+      eventData: out ? BaseLazyStep.tryParsing(decodeBase64(out)) : void 0,
+      timeout: waitTimeout ?? false
+    };
+  }
+  safeParseOut(out, step) {
+    return this.parseWaitForEventOut(out, step.waitTimeout);
+  }
+  handleUndefinedOut(step) {
+    return this.parseWaitForEventOut(void 0, step.waitTimeout);
+  }
+};
 
 // src/qstash/headers.ts
 var WorkflowHeaders = class {
@@ -1596,14 +1644,15 @@ var WorkflowHeaders = class {
   initHeaderValue;
   stepInfo;
   headers;
-  keepTriggerConfig;
+  /**
+   * @param params workflow header parameters
+   */
   constructor({
     userHeaders,
     workflowConfig,
     invokeCount,
     initHeaderValue,
-    stepInfo,
-    keepTriggerConfig
+    stepInfo
   }) {
     this.userHeaders = userHeaders;
     this.workflowConfig = workflowConfig;
@@ -1615,7 +1664,6 @@ var WorkflowHeaders = class {
       workflowHeaders: {},
       failureHeaders: {}
     };
-    this.keepTriggerConfig = keepTriggerConfig;
   }
   getHeaders() {
     this.addBaseHeaders();
@@ -1634,7 +1682,7 @@ var WorkflowHeaders = class {
       [WORKFLOW_INIT_HEADER]: this.initHeaderValue,
       [WORKFLOW_ID_HEADER]: this.workflowConfig.workflowRunId,
       [WORKFLOW_URL_HEADER]: this.workflowConfig.workflowUrl,
-      [WORKFLOW_FEATURE_HEADER]: "LazyFetch,InitialBody,WF_DetectTrigger" + (this.keepTriggerConfig ? ",WF_TriggerOnConfig" : ""),
+      [WORKFLOW_FEATURE_HEADER]: "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig",
       [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
       ...this.workflowConfig.telemetry ? getTelemetryHeaders(this.workflowConfig.telemetry) : {}
     };
@@ -1704,12 +1752,12 @@ var WorkflowHeaders = class {
     }
     this.headers.workflowHeaders["Failure-Callback"] = this.workflowConfig.failureUrl;
     this.headers.failureHeaders[`Forward-${WORKFLOW_FAILURE_HEADER}`] = "true";
-    this.headers.failureHeaders[`Forward-Upstash-Workflow-Failure-Callback`] = "true";
+    this.headers.failureHeaders[`Forward-${WORKFLOW_FAILURE_CALLBACK_HEADER}`] = "true";
     this.headers.failureHeaders["Workflow-Runid"] = this.workflowConfig.workflowRunId;
     this.headers.failureHeaders["Workflow-Init"] = "false";
     this.headers.failureHeaders["Workflow-Url"] = this.workflowConfig.workflowUrl;
     this.headers.failureHeaders["Workflow-Calltype"] = "failureCall";
-    this.headers.failureHeaders["Feature-Set"] = "LazyFetch,InitialBody,WF_DetectTrigger";
+    this.headers.failureHeaders["Feature-Set"] = "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig";
     if (this.workflowConfig.retries !== void 0 && this.workflowConfig.retries !== DEFAULT_RETRIES) {
       this.headers.failureHeaders["Retries"] = this.workflowConfig.retries.toString();
     }
@@ -1779,14 +1827,13 @@ var submitParallelSteps = async ({
   initialStepCount,
   invokeCount,
   telemetry: telemetry2,
-  debug
+  dispatchDebug
 }) => {
   const planSteps = steps.map(
     (step, index) => step.getPlanStep(steps.length, initialStepCount + index)
   );
-  await debug?.log("SUBMIT", "SUBMIT_STEP", {
-    length: planSteps.length,
-    steps: planSteps
+  await dispatchDebug("onInfo", {
+    info: `Submitting ${planSteps.length} parallel steps.`
   });
   const result = await context.qstashClient.batch(
     planSteps.map((planStep) => {
@@ -1795,10 +1842,6 @@ var submitParallelSteps = async ({
         workflowConfig: {
           workflowRunId: context.workflowRunId,
           workflowUrl: context.url,
-          failureUrl: context.failureUrl,
-          retries: context.retries,
-          retryDelay: context.retryDelay,
-          flowControl: context.flowControl,
           telemetry: telemetry2
         },
         userHeaders: context.headers,
@@ -1814,13 +1857,11 @@ var submitParallelSteps = async ({
       };
     })
   );
-  await debug?.log("INFO", "SUBMIT_STEP", {
-    messageIds: result.map((message) => {
-      return {
-        message: message.messageId
-      };
-    })
-  });
+  if (result && result.length > 0) {
+    await dispatchDebug("onInfo", {
+      info: `Submitted ${planSteps.length} parallel steps. messageIds: ${result.filter((r) => r).map((r) => r.messageId).join(", ")}.`
+    });
+  }
   throw new WorkflowAbort(planSteps[0].stepName, planSteps[0]);
 };
 var submitSingleStep = async ({
@@ -1830,14 +1871,13 @@ var submitSingleStep = async ({
   invokeCount,
   concurrency,
   telemetry: telemetry2,
-  debug
+  dispatchDebug,
+  dispatchLifecycle
 }) => {
-  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
-  await debug?.log("INFO", "RUN_SINGLE", {
-    fromRequest: false,
-    step: resultStep,
-    stepCount: stepId
+  await dispatchLifecycle("beforeExecution", {
+    stepName: lazyStep.stepName
   });
+  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
   const { headers } = lazyStep.getHeaders({
     context,
     step: resultStep,
@@ -1851,10 +1891,6 @@ var submitSingleStep = async ({
     invokeCount,
     telemetry: telemetry2
   });
-  await debug?.log("SUBMIT", "SUBMIT_STEP", {
-    length: 1,
-    steps: [resultStep]
-  });
   const submitResult = await lazyStep.submitStep({
     context,
     body,
@@ -1864,13 +1900,11 @@ var submitSingleStep = async ({
     step: resultStep,
     telemetry: telemetry2
   });
-  await debug?.log("INFO", "SUBMIT_STEP", {
-    messageIds: submitResult.map((message) => {
-      return {
-        message: message.messageId
-      };
-    })
-  });
+  if (submitResult && submitResult[0]) {
+    await dispatchDebug("onInfo", {
+      info: `Submitted step "${resultStep.stepName}" with messageId: ${submitResult[0].messageId}.`
+    });
+  }
   return resultStep;
 };
 
@@ -1879,21 +1913,31 @@ var AutoExecutor = class _AutoExecutor {
   context;
   promises = /* @__PURE__ */ new WeakMap();
   activeLazyStepList;
-  debug;
   nonPlanStepCount;
   steps;
   indexInCurrentList = 0;
   invokeCount;
   telemetry;
+  dispatchDebug;
+  dispatchLifecycle;
   stepCount = 0;
   planStepCount = 0;
   executingStep = false;
-  constructor(context, steps, telemetry2, invokeCount, debug) {
+  /**
+   * @param context workflow context
+   * @param steps list of steps
+   * @param dispatchDebug debug event dispatcher
+   * @param dispatchLifecycle lifecycle event dispatcher
+   * @param telemetry optional telemetry information
+   * @param invokeCount optional invoke count
+   */
+  constructor(context, steps, dispatchDebug, dispatchLifecycle, telemetry2, invokeCount) {
     this.context = context;
     this.steps = steps;
+    this.dispatchDebug = dispatchDebug;
+    this.dispatchLifecycle = dispatchLifecycle;
     this.telemetry = telemetry2;
     this.invokeCount = invokeCount ?? 0;
-    this.debug = debug;
     this.nonPlanStepCount = this.steps.filter((step) => !step.targetStep).length;
   }
   /**
@@ -1961,7 +2005,7 @@ var AutoExecutor = class _AutoExecutor {
   /**
    * Executes a step:
    * - If the step result is available in the steps, returns the result
-   * - If the result is not avaiable, runs the function
+   * - If the result is not available, runs the function
    * - Sends the result to QStash
    *
    * @param lazyStep lazy step to execute
@@ -1971,12 +2015,15 @@ var AutoExecutor = class _AutoExecutor {
     if (this.stepCount < this.nonPlanStepCount) {
       const step = this.steps[this.stepCount + this.planStepCount];
       validateStep(lazyStep, step);
-      await this.debug?.log("INFO", "RUN_SINGLE", {
-        fromRequest: true,
-        step,
-        stepCount: this.stepCount
-      });
-      return lazyStep.parseOut(step.out);
+      const parsedOut = lazyStep.parseOut(step);
+      const isLastMemoized = this.stepCount + 1 === this.nonPlanStepCount && this.steps.at(-1).stepId !== 0;
+      if (isLastMemoized) {
+        await this.dispatchLifecycle("afterExecution", {
+          stepName: lazyStep.stepName,
+          result: parsedOut
+        });
+      }
+      return parsedOut;
     }
     const resultStep = await submitSingleStep({
       context: this.context,
@@ -1985,15 +2032,15 @@ var AutoExecutor = class _AutoExecutor {
       invokeCount: this.invokeCount,
       concurrency: 1,
       telemetry: this.telemetry,
-      debug: this.debug
+      dispatchDebug: this.dispatchDebug,
+      dispatchLifecycle: this.dispatchLifecycle
     });
     throw new WorkflowAbort(lazyStep.stepName, resultStep);
   }
   /**
    * Runs steps in parallel.
    *
-   * @param stepName parallel step name
-   * @param stepFunctions list of async functions to run in parallel
+   * @param parallelSteps list of lazy steps to run in parallel
    * @returns results of the functions run in parallel
    */
   async runParallel(parallelSteps) {
@@ -2006,12 +2053,14 @@ var AutoExecutor = class _AutoExecutor {
         `Incompatible number of parallel steps when call state was '${parallelCallState}'. Expected ${parallelSteps.length}, got ${plannedParallelStepCount} from the request.`
       );
     }
-    await this.debug?.log("INFO", "RUN_PARALLEL", {
-      parallelCallState,
-      initialStepCount,
-      plannedParallelStepCount,
-      stepCount: this.stepCount,
-      planStepCount: this.planStepCount
+    await this.dispatchDebug("onInfo", {
+      info: `Executing parallel steps with: ` + JSON.stringify({
+        parallelCallState,
+        initialStepCount,
+        plannedParallelStepCount,
+        stepCount: this.stepCount,
+        planStepCount: this.planStepCount
+      })
     });
     switch (parallelCallState) {
       case "first": {
@@ -2021,7 +2070,7 @@ var AutoExecutor = class _AutoExecutor {
           initialStepCount,
           invokeCount: this.invokeCount,
           telemetry: this.telemetry,
-          debug: this.debug
+          dispatchDebug: this.dispatchDebug
         });
         break;
       }
@@ -2043,7 +2092,8 @@ var AutoExecutor = class _AutoExecutor {
             invokeCount: this.invokeCount,
             concurrency: parallelSteps.length,
             telemetry: this.telemetry,
-            debug: this.debug
+            dispatchDebug: this.dispatchDebug,
+            dispatchLifecycle: this.dispatchLifecycle
           });
           throw new WorkflowAbort(parallelStep.stepName, resultStep);
         } catch (error) {
@@ -2057,13 +2107,34 @@ var AutoExecutor = class _AutoExecutor {
         break;
       }
       case "discard": {
+        const resultStep = this.steps.at(-1);
+        const lazyStep = parallelSteps.find(
+          (planStep, index) => resultStep.stepId - index === initialStepCount
+        );
+        if (lazyStep) {
+          await this.dispatchLifecycle("afterExecution", {
+            stepName: lazyStep.stepName,
+            result: lazyStep.parseOut(resultStep)
+          });
+        }
         throw new WorkflowAbort("discarded parallel");
       }
       case "last": {
         const parallelResultSteps = sortedSteps.filter((step) => step.stepId >= initialStepCount).slice(0, parallelSteps.length);
         validateParallelSteps(parallelSteps, parallelResultSteps);
+        const isLastMemoized = this.stepCount + 1 === this.nonPlanStepCount && this.steps.at(-1).stepId !== 0;
+        if (isLastMemoized) {
+          const resultStep = this.steps.at(-1);
+          const lazyStep = parallelSteps.find(
+            (planStep, index) => resultStep.stepId - index === initialStepCount
+          );
+          await this.dispatchLifecycle("afterExecution", {
+            stepName: lazyStep.stepName,
+            result: lazyStep.parseOut(resultStep)
+          });
+        }
         return parallelResultSteps.map(
-          (step, index) => parallelSteps[index].parseOut(step.out)
+          (step, index) => parallelSteps[index].parseOut(step)
         );
       }
     }
@@ -2119,7 +2190,6 @@ var AutoExecutor = class _AutoExecutor {
    * @param index index of the current step
    * @returns result[index] if lazyStepList > 1, otherwise result
    */
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
   static getResult(lazyStepList, result, index) {
     if (lazyStepList.length === 1) {
       return result;
@@ -2206,15 +2276,18 @@ var getProviderInfo = (api) => {
 // src/context/api/base.ts
 var BaseWorkflowApi = class {
   context;
+  /**
+   * @param context workflow context
+   */
   constructor({ context }) {
     this.context = context;
   }
   /**
    * context.call which uses a QStash API
    *
-   * @param stepName
-   * @param settings
-   * @returns
+   * @param stepName name of the step
+   * @param settings call settings including api configuration
+   * @returns call response
    */
   async callApi(stepName, settings) {
     const { url, appendHeaders, method } = getProviderInfo(settings.api);
@@ -2222,7 +2295,7 @@ var BaseWorkflowApi = class {
     return await this.context.call(stepName, {
       url,
       method: userMethod ?? method,
-      body,
+      body: typeof body === "string" ? body : JSON.stringify(body),
       headers: {
         ...appendHeaders,
         ...headers
@@ -2374,6 +2447,129 @@ var getNewUrlFromWorkflowId = (url, workflowId) => {
   return url.replace(/[^/]+$/, workflowId);
 };
 
+// src/middleware/default-callbacks.ts
+var onErrorWithConsole = async ({ workflowRunId, error }) => {
+  console.error(`  [Upstash Workflow]: Error in workflow run ${workflowRunId}: ` + error);
+};
+var onWarningWithConsole = async ({ workflowRunId, warning }) => {
+  console.warn(`  [Upstash Workflow]: Warning in workflow run ${workflowRunId}: ` + warning);
+};
+var onInfoWithConsole = async ({
+  workflowRunId,
+  info
+}) => {
+  console.info(`  [Upstash Workflow]: Info in workflow run ${workflowRunId}: ` + info);
+};
+
+// src/middleware/manager.ts
+var MiddlewareManager = class {
+  middlewares;
+  workflowRunId;
+  context;
+  /**
+   * @param middlewares list of workflow middlewares
+   */
+  constructor(middlewares = []) {
+    this.middlewares = middlewares;
+  }
+  /**
+   * Assign workflow run ID - will be passed to debug events
+   *
+   * @param workflowRunId workflow run id to assign
+   */
+  assignWorkflowRunId(workflowRunId) {
+    this.workflowRunId = workflowRunId;
+  }
+  /**
+   * Assign context - required for lifecycle events
+   *
+   * also assigns workflowRunId from context
+   *
+   * @param context workflow context to assign
+   */
+  assignContext(context) {
+    this.context = context;
+    this.workflowRunId = context.workflowRunId;
+  }
+  /**
+   * Internal method to execute middlewares with common error handling logic
+   *
+   * @param event event name to dispatch
+   * @param params event parameters
+   */
+  async executeMiddlewares(event, params) {
+    await Promise.all(this.middlewares.map((m) => m.ensureInit()));
+    await Promise.all(
+      this.middlewares.map(async (middleware) => {
+        const callback = middleware.getCallback(event);
+        if (callback) {
+          try {
+            await callback(params);
+          } catch (error) {
+            try {
+              const onErrorCallback = middleware.getCallback("onError") ?? onErrorWithConsole;
+              await onErrorCallback({
+                workflowRunId: this.workflowRunId,
+                error
+              });
+            } catch (onErrorError) {
+              console.error(
+                `Failed while executing "onError" of middleware "${middleware.name}", falling back to logging the error to console. Error: ${onErrorError}`
+              );
+              onErrorWithConsole({
+                workflowRunId: this.workflowRunId,
+                error
+              });
+            }
+          }
+        }
+      })
+    );
+    if (event === "onError") {
+      onErrorWithConsole({
+        workflowRunId: this.workflowRunId,
+        ...params
+      });
+    } else if (event === "onWarning") {
+      onWarningWithConsole({
+        workflowRunId: this.workflowRunId,
+        ...params
+      });
+    }
+  }
+  /**
+   * Dispatch a debug event (onError, onWarning, onInfo)
+   *
+   * @param event debug event name
+   * @param params event parameters
+   */
+  async dispatchDebug(event, params) {
+    const paramsWithRunId = {
+      ...params,
+      workflowRunId: this.workflowRunId
+    };
+    await this.executeMiddlewares(event, paramsWithRunId);
+  }
+  /**
+   * Dispatch a lifecycle event (beforeExecution, afterExecution, runStarted, runCompleted)
+   *
+   * @param event lifecycle event name
+   * @param params event parameters
+   */
+  async dispatchLifecycle(event, params) {
+    if (!this.context) {
+      throw new WorkflowError(
+        `Something went wrong while calling middlewares. Lifecycle event "${event}" was called before assignContext.`
+      );
+    }
+    const paramsWithContext = {
+      ...params,
+      context: this.context
+    };
+    await this.executeMiddlewares(event, paramsWithContext);
+  }
+};
+
 // src/context/context.ts
 var WorkflowContext = class {
   executor;
@@ -2419,32 +2615,13 @@ var WorkflowContext = class {
    */
   url;
   /**
-   * URL to call in case of workflow failure with QStash failure callback
-   *
-   * https://upstash.com/docs/qstash/features/callbacks#what-is-a-failure-callback
+   * Payload of the request which started the workflow.
    *
-   * Can be overwritten by passing a `failureUrl` parameter in `serve`:
+   * To specify its type, you can define `serve` as follows:
    *
    * ```ts
-   * export const POST = serve(
-   *   async (context) => {
-   *     ...
-   *   },
-   *   {
-   *     failureUrl: "new-url-value"
-   *   }
-   * )
-   * ```
-   */
-  failureUrl;
-  /**
-   * Payload of the request which started the workflow.
-   *
-   * To specify its type, you can define `serve` as follows:
-   *
-   * ```ts
-   * // set requestPayload type to MyPayload:
-   * export const POST = serve<MyPayload>(
+   * // set requestPayload type to MyPayload:
+   * export const POST = serve<MyPayload>(
    *   async (context) => {
    *     ...
    *   }
@@ -2492,46 +2669,6 @@ var WorkflowContext = class {
    * Default value is set to `process.env`.
    */
   env;
-  /**
-   * Number of retries
-   */
-  retries;
-  /**
-   * Delay between retries.
-   *
-   * By default, the `retryDelay` is exponential backoff.
-   * More details can be found in: https://upstash.com/docs/qstash/features/retry.
-   *
-   * The `retryDelay` option allows you to customize the delay (in milliseconds) between retry attempts when message delivery fails.
-   *
-   * You can use mathematical expressions and the following built-in functions to calculate the delay dynamically.
-   * The special variable `retried` represents the current retry attempt count (starting from 0).
-   *
-   * Supported functions:
-   * - `pow`
-   * - `sqrt`
-   * - `abs`
-   * - `exp`
-   * - `floor`
-   * - `ceil`
-   * - `round`
-   * - `min`
-   * - `max`
-   *
-   * Examples of valid `retryDelay` values:
-   * ```ts
-   * 1000 // 1 second
-   * 1000 * (1 + retried)  // 1 second multiplied by the current retry attempt
-   * pow(2, retried) // 2 to the power of the current retry attempt
-   * max(10, pow(2, retried)) // The greater of 10 or 2^retried
-   * ```
-   */
-  retryDelay;
-  /**
-   * Settings for controlling the number of active requests
-   * and number of requests per second with the same key.
-   */
-  flowControl;
   /**
    * Label to apply to the workflow run.
    *
@@ -2554,30 +2691,31 @@ var WorkflowContext = class {
     headers,
     steps,
     url,
-    failureUrl,
-    debug,
     initialPayload,
     env,
-    retries,
-    retryDelay,
     telemetry: telemetry2,
     invokeCount,
-    flowControl,
-    label
+    label,
+    middlewareManager
   }) {
     this.qstashClient = qstashClient;
     this.workflowRunId = workflowRunId;
     this.steps = steps;
     this.url = url;
-    this.failureUrl = failureUrl;
     this.headers = headers;
     this.requestPayload = initialPayload;
     this.env = env ?? {};
-    this.retries = retries ?? DEFAULT_RETRIES;
-    this.retryDelay = retryDelay;
-    this.flowControl = flowControl;
     this.label = label;
-    this.executor = new AutoExecutor(this, this.steps, telemetry2, invokeCount, debug);
+    const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
+    middlewareManagerInstance.assignContext(this);
+    this.executor = new AutoExecutor(
+      this,
+      this.steps,
+      middlewareManagerInstance.dispatchDebug.bind(middlewareManagerInstance),
+      middlewareManagerInstance.dispatchLifecycle.bind(middlewareManagerInstance),
+      telemetry2,
+      invokeCount
+    );
   }
   /**
    * Executes a workflow step
@@ -2608,7 +2746,7 @@ var WorkflowContext = class {
    */
   async run(stepName, stepFunction) {
     const wrappedStepFunction = (() => this.executor.wrapStep(stepName, stepFunction));
-    return await this.addStep(new LazyFunctionStep(stepName, wrappedStepFunction));
+    return await this.addStep(new LazyFunctionStep(this, stepName, wrappedStepFunction));
   }
   /**
    * Stops the execution for the duration provided.
@@ -2622,7 +2760,7 @@ var WorkflowContext = class {
    * @returns undefined
    */
   async sleep(stepName, duration) {
-    await this.addStep(new LazySleepStep(stepName, duration));
+    await this.addStep(new LazySleepStep(this, stepName, duration));
   }
   /**
    * Stops the execution until the date time provided.
@@ -2644,48 +2782,38 @@ var WorkflowContext = class {
       datetime = typeof datetime === "string" ? new Date(datetime) : datetime;
       time = Math.round(datetime.getTime() / 1e3);
     }
-    await this.addStep(new LazySleepUntilStep(stepName, time));
+    await this.addStep(new LazySleepUntilStep(this, stepName, time));
   }
   async call(stepName, settings) {
     let callStep;
     if ("workflow" in settings) {
       const url = getNewUrlFromWorkflowId(this.url, settings.workflow.workflowId);
-      callStep = new LazyCallStep(
+      const stringBody = typeof settings.body === "string" ? settings.body : settings.body === void 0 ? void 0 : JSON.stringify(settings.body);
+      callStep = new LazyCallStep({
+        context: this,
         stepName,
         url,
-        "POST",
-        settings.body,
-        settings.headers || {},
-        settings.retries || 0,
-        settings.retryDelay,
-        settings.timeout,
-        settings.flowControl ?? settings.workflow.options.flowControl,
-        settings.stringifyBody ?? true
-      );
+        method: "POST",
+        body: stringBody,
+        headers: settings.headers || {},
+        retries: settings.retries || 0,
+        retryDelay: settings.retryDelay,
+        timeout: settings.timeout,
+        flowControl: settings.flowControl
+      });
     } else {
-      const {
-        url,
-        method = "GET",
-        body,
-        headers = {},
-        retries = 0,
-        retryDelay,
-        timeout,
-        flowControl,
-        stringifyBody = true
-      } = settings;
-      callStep = new LazyCallStep(
+      callStep = new LazyCallStep({
+        context: this,
         stepName,
-        url,
-        method,
-        body,
-        headers,
-        retries,
-        retryDelay,
-        timeout,
-        flowControl,
-        stringifyBody
-      );
+        url: settings.url,
+        method: settings.method ?? "GET",
+        body: settings.body,
+        headers: settings.headers ?? {},
+        retries: settings.retries ?? 0,
+        retryDelay: settings.retryDelay,
+        timeout: settings.timeout,
+        flowControl: settings.flowControl
+      });
     }
     return await this.addStep(callStep);
   }
@@ -2726,7 +2854,9 @@ var WorkflowContext = class {
   async waitForEvent(stepName, eventId, options = {}) {
     const { timeout = "7d" } = options;
     const timeoutStr = typeof timeout === "string" ? timeout : `${timeout}s`;
-    return await this.addStep(new LazyWaitForEventStep(stepName, eventId, timeoutStr));
+    return await this.addStep(
+      new LazyWaitForEventStep(this, stepName, eventId, timeoutStr)
+    );
   }
   /**
    * Notify workflow runs waiting for an event
@@ -2751,20 +2881,28 @@ var WorkflowContext = class {
    */
   async notify(stepName, eventId, eventData) {
     return await this.addStep(
-      new LazyNotifyStep(stepName, eventId, eventData, this.qstashClient.http)
+      new LazyNotifyStep(this, stepName, eventId, eventData, this.qstashClient.http)
     );
   }
   async invoke(stepName, settings) {
-    return await this.addStep(new LazyInvokeStep(stepName, settings));
+    return await this.addStep(
+      new LazyInvokeStep(this, stepName, settings)
+    );
+  }
+  async createWebhook(stepName) {
+    return await this.addStep(new LazyCreateWebhookStep(this, stepName));
+  }
+  async waitForWebhook(stepName, webhook, timeout) {
+    return await this.addStep(new LazyWaitForWebhookStep(this, stepName, webhook, timeout));
   }
   /**
    * Cancel the current workflow run
    *
-   * Will throw WorkflowAbort to stop workflow execution.
+   * Will throw WorkflowCancelAbort to stop workflow execution.
    * Shouldn't be inside try/catch.
    */
   async cancel() {
-    throw new WorkflowAbort("cancel", void 0, true);
+    throw new WorkflowCancelAbort();
   }
   /**
    * Adds steps to the executor. Needed so that it can be overwritten in
@@ -2780,74 +2918,25 @@ var WorkflowContext = class {
   }
 };
 
-// src/logger.ts
-var LOG_LEVELS = ["DEBUG", "INFO", "SUBMIT", "WARN", "ERROR"];
-var WorkflowLogger = class _WorkflowLogger {
-  logs = [];
-  options;
-  workflowRunId = void 0;
-  constructor(options) {
-    this.options = options;
-  }
-  async log(level, eventType, details) {
-    if (this.shouldLog(level)) {
-      const timestamp = Date.now();
-      const logEntry = {
-        timestamp,
-        workflowRunId: this.workflowRunId ?? "",
-        logLevel: level,
-        eventType,
-        details
-      };
-      this.logs.push(logEntry);
-      if (this.options.logOutput === "console") {
-        this.writeToConsole(logEntry);
-      }
-      await new Promise((resolve) => setTimeout(resolve, 100));
-    }
-  }
-  setWorkflowRunId(workflowRunId) {
-    this.workflowRunId = workflowRunId;
-  }
-  writeToConsole(logEntry) {
-    const JSON_SPACING = 2;
-    const logMethod = logEntry.logLevel === "ERROR" ? console.error : logEntry.logLevel === "WARN" ? console.warn : console.log;
-    logMethod(JSON.stringify(logEntry, void 0, JSON_SPACING));
-  }
-  shouldLog(level) {
-    return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(this.options.logLevel);
-  }
-  static getLogger(verbose) {
-    if (typeof verbose === "object") {
-      return verbose;
-    } else {
-      return verbose ? new _WorkflowLogger({
-        logLevel: "INFO",
-        logOutput: "console"
-      }) : void 0;
-    }
-  }
-};
-
 // src/serve/authorization.ts
 var import_qstash9 = require("@upstash/qstash");
 var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowContext {
   static disabledMessage = "disabled-qstash-worklfow-run";
   disabled = true;
   /**
-   * overwrite the WorkflowContext.addStep method to always raise WorkflowAbort
+   * overwrite the WorkflowContext.addStep method to always raise WorkflowAuthError
    * error in order to stop the execution whenever we encounter a step.
    *
    * @param _step
    */
   async addStep(_step) {
-    throw new WorkflowAbort(_DisabledWorkflowContext.disabledMessage);
+    throw new WorkflowAuthError(_DisabledWorkflowContext.disabledMessage);
   }
   /**
-   * overwrite cancel method to throw WorkflowAbort with the disabledMessage
+   * overwrite cancel method to throw WorkflowAuthError with the disabledMessage
    */
   async cancel() {
-    throw new WorkflowAbort(_DisabledWorkflowContext.disabledMessage);
+    throw new WorkflowAuthError(_DisabledWorkflowContext.disabledMessage);
   }
   /**
    * copies the passed context to create a DisabledWorkflowContext. Then, runs the
@@ -2870,18 +2959,14 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       headers: context.headers,
       steps: [],
       url: context.url,
-      failureUrl: context.failureUrl,
       initialPayload: context.requestPayload,
       env: context.env,
-      retries: context.retries,
-      retryDelay: context.retryDelay,
-      flowControl: context.flowControl,
       label: context.label
     });
     try {
       await routeFunction(disabledContext);
     } catch (error) {
-      if (isInstanceOf(error, WorkflowAbort) && error.stepName === this.disabledMessage || isInstanceOf(error, WorkflowNonRetryableError) || isInstanceOf(error, WorkflowRetryAfterError)) {
+      if (isInstanceOf(error, WorkflowAuthError) && error.stepName === this.disabledMessage || isInstanceOf(error, WorkflowNonRetryableError) || isInstanceOf(error, WorkflowRetryAfterError)) {
         return ok("step-found");
       }
       console.warn(
@@ -2914,13 +2999,6 @@ var processRawSteps = (rawSteps) => {
   const stepsToDecode = encodedSteps.filter((step) => step.callType === "step");
   const otherSteps = stepsToDecode.map((rawStep) => {
     const step = JSON.parse(decodeBase64(rawStep.body));
-    if (step.waitEventId) {
-      const newOut = {
-        eventData: step.out ? decodeBase64(step.out) : void 0,
-        timeout: step.waitTimeout ?? false
-      };
-      step.out = newOut;
-    }
     return step;
   });
   const steps = [initialStep, ...otherSteps];
@@ -2948,7 +3026,7 @@ var deduplicateSteps = (steps) => {
   }
   return deduplicatedSteps;
 };
-var checkIfLastOneIsDuplicate = async (steps, debug) => {
+var checkIfLastOneIsDuplicate = async (steps, dispatchDebug) => {
   if (steps.length < 2) {
     return false;
   }
@@ -2959,14 +3037,41 @@ var checkIfLastOneIsDuplicate = async (steps, debug) => {
     const step = steps[index];
     if (step.stepId === lastStepId && step.targetStep === lastTargetStepId) {
       const message = `Upstash Workflow: The step '${step.stepName}' with id '${step.stepId}'  has run twice during workflow execution. Rest of the workflow will continue running as usual.`;
-      await debug?.log("WARN", "RESPONSE_DEFAULT", message);
-      console.warn(message);
+      await dispatchDebug?.("onWarning", {
+        warning: message
+      });
       return true;
     }
   }
   return false;
 };
 var validateRequest = (request) => {
+  if (request.headers.get(WORKFLOW_UNKOWN_SDK_VERSION_HEADER)) {
+    const workflowRunId2 = request.headers.get(WORKFLOW_ID_HEADER);
+    if (!workflowRunId2) {
+      throw new WorkflowError(
+        "Couldn't get workflow id from header when handling unknown sdk request"
+      );
+    }
+    return {
+      unknownSdk: true,
+      isFirstInvocation: true,
+      workflowRunId: workflowRunId2
+    };
+  }
+  if (request.headers.get(WORKFLOW_FAILURE_CALLBACK_HEADER)) {
+    const workflowRunId2 = request.headers.get(WORKFLOW_ID_HEADER);
+    if (!workflowRunId2) {
+      throw new WorkflowError(
+        "Couldn't get workflow id from header when handling failure callback request"
+      );
+    }
+    return {
+      unknownSdk: false,
+      isFirstInvocation: true,
+      workflowRunId: workflowRunId2
+    };
+  }
   const versionHeader = request.headers.get(WORKFLOW_PROTOCOL_VERSION_HEADER);
   const isFirstInvocation = !versionHeader;
   if (!isFirstInvocation && versionHeader !== WORKFLOW_PROTOCOL_VERSION) {
@@ -2980,11 +3085,20 @@ var validateRequest = (request) => {
   }
   return {
     isFirstInvocation,
-    workflowRunId
+    workflowRunId,
+    unknownSdk: false
   };
 };
-var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requester, messageId, debug) => {
-  if (isFirstInvocation) {
+var parseRequest = async ({
+  requestPayload,
+  isFirstInvocation,
+  unknownSdk,
+  workflowRunId,
+  requester,
+  messageId,
+  dispatchDebug
+}) => {
+  if (isFirstInvocation && !unknownSdk) {
     return {
       rawInitialPayload: requestPayload ?? "",
       steps: [],
@@ -2994,16 +3108,14 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
   } else {
     let rawSteps;
     if (!requestPayload) {
-      await debug?.log(
-        "INFO",
-        "ENDPOINT_START",
-        "request payload is empty, steps will be fetched from QStash."
-      );
+      await dispatchDebug?.("onInfo", {
+        info: "request payload is empty, steps will be fetched from QStash."
+      });
       const { steps: fetchedSteps, workflowRunEnded } = await getSteps(
         requester,
         workflowRunId,
         messageId,
-        debug
+        dispatchDebug
       );
       if (workflowRunEnded) {
         return {
@@ -3018,7 +3130,7 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
       rawSteps = JSON.parse(requestPayload);
     }
     const { rawInitialPayload, steps } = processRawSteps(rawSteps);
-    const isLastDuplicate = await checkIfLastOneIsDuplicate(steps, debug);
+    const isLastDuplicate = await checkIfLastOneIsDuplicate(steps, dispatchDebug);
     const deduplicatedSteps = deduplicateSteps(steps);
     return {
       rawInitialPayload,
@@ -3028,16 +3140,21 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
     };
   }
 };
-var handleFailure = async (request, requestPayload, qstashClient, initialPayloadParser, routeFunction, failureFunction, env, retries, retryDelay, flowControl, debug) => {
-  if (request.headers.get(WORKFLOW_FAILURE_HEADER) !== "true") {
+var handleFailure = async ({
+  request,
+  requestPayload,
+  qstashClient,
+  initialPayloadParser,
+  routeFunction,
+  failureFunction,
+  env,
+  dispatchDebug
+}) => {
+  if (request.headers.get(WORKFLOW_FAILURE_HEADER) !== "true" && !request.headers.get(WORKFLOW_FAILURE_CALLBACK_HEADER)) {
     return ok({ result: "not-failure-callback" });
   }
   if (!failureFunction) {
-    return err(
-      new WorkflowError(
-        "Workflow endpoint is called to handle a failure, but a failureFunction is not provided in serve options. Either provide a failureUrl or a failureFunction."
-      )
-    );
+    return ok({ result: "failure-function-undefined" });
   }
   try {
     const { status, header, body, url, sourceBody, workflowRunId } = JSON.parse(requestPayload);
@@ -3065,23 +3182,21 @@ var handleFailure = async (request, requestPayload, qstashClient, initialPayload
       headers: userHeaders,
       steps: [],
       url,
-      failureUrl: url,
-      debug,
       env,
-      retries,
-      retryDelay,
-      flowControl,
       telemetry: void 0,
       // not going to make requests in authentication check
-      label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0
+      label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0,
+      middlewareManager: void 0
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
       workflowContext
     );
     if (authCheck.isErr()) {
-      await debug?.log("ERROR", "ERROR", { error: authCheck.error.message });
-      throw authCheck.error;
+      await dispatchDebug?.("onError", {
+        error: authCheck.error
+      });
+      return err(authCheck.error);
     } else if (authCheck.value === "run-ended") {
       return err(new WorkflowError("Not authorized to run the failure function."));
     }
@@ -3092,74 +3207,309 @@ var handleFailure = async (request, requestPayload, qstashClient, initialPayload
       failHeaders: header,
       failStack
     });
-    return ok({ result: "is-failure-callback", response: failureResponse });
+    return ok({ result: "failure-function-executed", response: failureResponse });
   } catch (error) {
     return err(error);
   }
 };
 
-// src/serve/options.ts
+// src/serve/multi-region/handlers.ts
 var import_qstash10 = require("@upstash/qstash");
-var import_qstash11 = require("@upstash/qstash");
-var processOptions = (options) => {
-  const environment = options?.env ?? (typeof process === "undefined" ? {} : process.env);
-  const receiverEnvironmentVariablesSet = Boolean(
-    environment.QSTASH_CURRENT_SIGNING_KEY && environment.QSTASH_NEXT_SIGNING_KEY
+
+// src/serve/multi-region/utils.ts
+var VALID_REGIONS = ["EU_CENTRAL_1", "US_EAST_1"];
+var getRegionFromEnvironment = (environment) => {
+  const region = environment.QSTASH_REGION;
+  return normalizeRegionHeader(region);
+};
+function readEnvironmentVariables(environmentVariables, environment, region) {
+  const result = {};
+  for (const variable of environmentVariables) {
+    const key = region ? `${region}_${variable}` : variable;
+    result[variable] = environment[key];
+  }
+  return result;
+}
+function readClientEnvironmentVariables(environment, region) {
+  return readEnvironmentVariables(["QSTASH_URL", "QSTASH_TOKEN"], environment, region);
+}
+function readReceiverEnvironmentVariables(environment, region) {
+  return readEnvironmentVariables(
+    ["QSTASH_CURRENT_SIGNING_KEY", "QSTASH_NEXT_SIGNING_KEY"],
+    environment,
+    region
   );
-  return {
-    qstashClient: options?.qstashClient ?? new import_qstash11.Client({
-      baseUrl: environment.QSTASH_URL,
-      token: environment.QSTASH_TOKEN
-    }),
-    onStepFinish: (workflowRunId, _finishCondition, detailedFinishCondition) => {
-      if (detailedFinishCondition?.condition === "auth-fail") {
-        console.error(AUTH_FAIL_MESSAGE);
-        return new Response(
-          JSON.stringify({
-            message: AUTH_FAIL_MESSAGE,
-            workflowRunId
-          }),
-          {
-            status: 400,
-            headers: {
-              [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-            }
-          }
-        );
-      } else if (detailedFinishCondition?.condition === "non-retryable-error") {
-        return new Response(JSON.stringify(formatWorkflowError(detailedFinishCondition.result)), {
-          headers: {
-            "Upstash-NonRetryable-Error": "true",
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          },
-          status: 489
-        });
-      } else if (detailedFinishCondition?.condition === "retry-after-error") {
-        return new Response(JSON.stringify(formatWorkflowError(detailedFinishCondition.result)), {
-          headers: {
-            "Retry-After": detailedFinishCondition.result.retryAfter.toString(),
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          },
-          status: 429
-        });
-      } else if (detailedFinishCondition?.condition === "failure-callback") {
-        return new Response(
-          JSON.stringify({ result: detailedFinishCondition.result ?? void 0 }),
-          {
-            status: 200,
-            headers: {
-              [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-            }
-          }
+}
+function normalizeRegionHeader(region) {
+  if (!region) {
+    return void 0;
+  }
+  region = region.replaceAll("-", "_").toUpperCase();
+  if (VALID_REGIONS.includes(region)) {
+    return region;
+  }
+  console.warn(
+    `[Upstash Workflow] Invalid UPSTASH-REGION header value: "${region}". Expected one of: ${VALID_REGIONS.join(
+      ", "
+    )}.`
+  );
+  return void 0;
+}
+
+// src/serve/multi-region/handlers.ts
+var getHandlersForRequest = (qstashHandlers, regionHeader, isFirstInvocation) => {
+  if (qstashHandlers.mode === "single-region") {
+    return qstashHandlers.handlers;
+  }
+  let targetRegion;
+  if (isFirstInvocation) {
+    targetRegion = qstashHandlers.defaultRegion;
+  } else {
+    const normalizedRegion = regionHeader ? normalizeRegionHeader(regionHeader) : void 0;
+    targetRegion = normalizedRegion ?? qstashHandlers.defaultRegion;
+  }
+  const handler = qstashHandlers.handlers[targetRegion];
+  if (!handler) {
+    console.warn(
+      `[Upstash Workflow] No handler found for region "${targetRegion}". Falling back to default region.`
+    );
+    return qstashHandlers.handlers[qstashHandlers.defaultRegion];
+  }
+  return handler;
+};
+var createRegionalHandler = (environment, receiverConfig, region, clientOptions) => {
+  const clientEnv = readClientEnvironmentVariables(environment, region);
+  const client = new import_qstash10.Client({
+    ...clientOptions,
+    baseUrl: clientEnv.QSTASH_URL,
+    token: clientEnv.QSTASH_TOKEN
+  });
+  const receiver = getReceiver(environment, receiverConfig, region);
+  return { client, receiver };
+};
+var shouldUseMultiRegionMode = (environment, qstashClientOption) => {
+  const hasRegionEnv = Boolean(getRegionFromEnvironment(environment));
+  if (hasRegionEnv && (!qstashClientOption || !("http" in qstashClientOption))) {
+    return {
+      isMultiRegion: true,
+      defaultRegion: getRegionFromEnvironment(environment),
+      clientOptions: qstashClientOption
+    };
+  } else {
+    return { isMultiRegion: false };
+  }
+};
+var getQStashHandlers = ({
+  environment,
+  qstashClientOption,
+  receiverConfig
+}) => {
+  const multiRegion = shouldUseMultiRegionMode(environment, qstashClientOption);
+  if (multiRegion.isMultiRegion) {
+    const regions = ["US_EAST_1", "EU_CENTRAL_1"];
+    const handlers = {};
+    for (const region of regions) {
+      try {
+        handlers[region] = createRegionalHandler(
+          environment,
+          receiverConfig,
+          region,
+          multiRegion.clientOptions
         );
+      } catch (error) {
+        console.warn(`[Upstash Workflow] Failed to create handler for region ${region}:`, error);
       }
-      return new Response(JSON.stringify({ workflowRunId }), {
-        status: 200,
-        headers: {
-          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-        }
+    }
+    return {
+      mode: "multi-region",
+      handlers,
+      defaultRegion: multiRegion.defaultRegion
+    };
+  } else {
+    return {
+      mode: "single-region",
+      handlers: {
+        client: qstashClientOption && "http" in qstashClientOption ? qstashClientOption : new import_qstash10.Client({
+          ...qstashClientOption,
+          baseUrl: environment.QSTASH_URL,
+          token: environment.QSTASH_TOKEN
+        }),
+        receiver: getReceiver(environment, receiverConfig)
+      }
+    };
+  }
+};
+var getReceiver = (environment, receiverConfig, region) => {
+  if (typeof receiverConfig === "string") {
+    if (receiverConfig === "set-to-undefined") {
+      return void 0;
+    }
+    const receiverEnv = readReceiverEnvironmentVariables(environment, region);
+    return receiverEnv.QSTASH_CURRENT_SIGNING_KEY && receiverEnv.QSTASH_NEXT_SIGNING_KEY ? new import_qstash10.Receiver({
+      currentSigningKey: receiverEnv.QSTASH_CURRENT_SIGNING_KEY,
+      nextSigningKey: receiverEnv.QSTASH_NEXT_SIGNING_KEY
+    }) : void 0;
+  } else {
+    return receiverConfig;
+  }
+};
+var getQStashHandlerOptions = (...params) => {
+  const handlers = getQStashHandlers(...params);
+  return {
+    qstashHandlers: handlers,
+    defaultReceiver: handlers.mode === "single-region" ? handlers.handlers.receiver : handlers.handlers[handlers.defaultRegion].receiver,
+    defaultClient: handlers.mode === "single-region" ? handlers.handlers.client : handlers.handlers[handlers.defaultRegion].client
+  };
+};
+
+// src/middleware/middleware.ts
+var WorkflowMiddleware = class {
+  name;
+  initCallbacks;
+  /**
+   * Callback functions
+   *
+   * Initially set to undefined, will be populated after init is called
+   */
+  middlewareCallbacks = void 0;
+  constructor(parameters) {
+    this.name = parameters.name;
+    if ("init" in parameters) {
+      this.initCallbacks = parameters.init;
+    } else {
+      this.middlewareCallbacks = parameters.callbacks;
+    }
+  }
+  async ensureInit() {
+    if (!this.middlewareCallbacks) {
+      if (!this.initCallbacks) {
+        throw new WorkflowError(`Middleware "${this.name}" has no callbacks or init defined.`);
+      }
+      this.middlewareCallbacks = await this.initCallbacks();
+    }
+  }
+  /**
+   * Gets a callback function by name.
+   *
+   * @param callback name of the callback to retrieve
+   */
+  getCallback(callback) {
+    return this.middlewareCallbacks?.[callback];
+  }
+};
+
+// src/middleware/logging.ts
+var loggingMiddleware = new WorkflowMiddleware({
+  name: "logging",
+  callbacks: {
+    afterExecution(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Step executed:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    beforeExecution(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Step execution started:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
       });
     },
+    runStarted(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Workflow run started:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    runCompleted(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Workflow run completed:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    onError: onErrorWithConsole,
+    onWarning: onWarningWithConsole,
+    onInfo: onInfoWithConsole
+  }
+});
+
+// src/serve/options.ts
+var createResponseData = (workflowRunId, detailedFinishCondition) => {
+  const baseHeaders = {
+    [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
+    "Upstash-workflow-sdk": VERSION
+  };
+  if (detailedFinishCondition?.condition === "auth-fail") {
+    return {
+      text: JSON.stringify({
+        message: AUTH_FAIL_MESSAGE,
+        workflowRunId
+      }),
+      status: 400,
+      headers: baseHeaders
+    };
+  } else if (detailedFinishCondition?.condition === "non-retryable-error") {
+    return {
+      text: JSON.stringify(formatWorkflowError(detailedFinishCondition.result)),
+      status: 489,
+      headers: {
+        ...baseHeaders,
+        "Upstash-NonRetryable-Error": "true"
+      }
+    };
+  } else if (detailedFinishCondition?.condition === "retry-after-error") {
+    return {
+      text: JSON.stringify(formatWorkflowError(detailedFinishCondition.result)),
+      status: 429,
+      headers: {
+        ...baseHeaders,
+        "Retry-After": detailedFinishCondition.result.retryAfter.toString()
+      }
+    };
+  } else if (detailedFinishCondition?.condition === "failure-callback-executed") {
+    return {
+      text: JSON.stringify({ result: detailedFinishCondition.result ?? void 0 }),
+      status: 200,
+      headers: baseHeaders
+    };
+  } else if (detailedFinishCondition?.condition === "failure-callback-undefined") {
+    return {
+      text: JSON.stringify({
+        workflowRunId,
+        finishCondition: detailedFinishCondition.condition
+      }),
+      status: 200,
+      headers: {
+        ...baseHeaders,
+        "Upstash-Workflow-Failure-Callback-Notfound": "true"
+      }
+    };
+  }
+  return {
+    text: JSON.stringify({
+      workflowRunId,
+      finishCondition: detailedFinishCondition.condition
+    }),
+    status: 200,
+    headers: baseHeaders
+  };
+};
+var processOptions = (options, internalOptions) => {
+  const environment = options?.env ?? (typeof process === "undefined" ? {} : process.env);
+  const {
+    qstashHandlers,
+    defaultClient: qstashClient,
+    defaultReceiver: receiver
+  } = getQStashHandlerOptions({
+    environment,
+    qstashClientOption: options?.qstashClient,
+    receiverConfig: options && "receiver" in options ? options.receiver ? options.receiver : "set-to-undefined" : "not-set"
+  });
+  return {
+    qstashClient,
     initialPayloadParser: (initialRequest) => {
       if (!initialRequest) {
         return void 0;
@@ -3174,35 +3524,38 @@ var processOptions = (options) => {
         throw error;
       }
     },
-    receiver: receiverEnvironmentVariablesSet ? new import_qstash10.Receiver({
-      currentSigningKey: environment.QSTASH_CURRENT_SIGNING_KEY,
-      nextSigningKey: environment.QSTASH_NEXT_SIGNING_KEY
-    }) : void 0,
+    receiver,
     baseUrl: environment.UPSTASH_WORKFLOW_URL,
     env: environment,
-    retries: DEFAULT_RETRIES,
-    useJSONContent: false,
     disableTelemetry: false,
-    onError: console.error,
-    ...options
+    ...options,
+    // merge middlewares
+    middlewares: [options?.middlewares ?? [], options?.verbose ? [loggingMiddleware] : []].flat(),
+    internal: {
+      generateResponse: internalOptions?.generateResponse ?? ((responseData) => {
+        return new Response(responseData.text, {
+          status: responseData.status,
+          headers: responseData.headers
+        });
+      }),
+      useJSONContent: internalOptions?.useJSONContent ?? false,
+      qstashHandlers
+    }
   };
 };
-var determineUrls = async (request, url, baseUrl, failureFunction, failureUrl, debug) => {
+var determineUrls = async (request, url, baseUrl, dispatchDebug) => {
   const initialWorkflowUrl = url ?? request.url;
   const workflowUrl = baseUrl ? initialWorkflowUrl.replace(/^(https?:\/\/[^/]+)(\/.*)?$/, (_, matchedBaseUrl, path) => {
     return baseUrl + (path || "");
   }) : initialWorkflowUrl;
   if (workflowUrl !== initialWorkflowUrl) {
-    await debug?.log("WARN", "ENDPOINT_START", {
-      warning: `Upstash Workflow: replacing the base of the url with "${baseUrl}" and using it as workflow endpoint.`,
-      originalURL: initialWorkflowUrl,
-      updatedURL: workflowUrl
+    await dispatchDebug("onInfo", {
+      info: `The workflow URL's base URL has been replaced with the provided baseUrl. Original URL: ${initialWorkflowUrl}, New URL: ${workflowUrl}`
     });
   }
-  const workflowFailureUrl = failureFunction ? workflowUrl : failureUrl;
   if (workflowUrl.includes("localhost")) {
-    await debug?.log("WARN", "ENDPOINT_START", {
-      message: `Workflow URL contains localhost. This can happen in local development, but shouldn't happen in production unless you have a route which contains localhost. Received: ${workflowUrl}`
+    await dispatchDebug("onInfo", {
+      info: `Workflow URL contains localhost. This can happen in local development, but shouldn't happen in production unless you have a route which contains localhost. Received: ${workflowUrl}`
     });
   }
   if (!(workflowUrl.startsWith("http://") || workflowUrl.startsWith("https://"))) {
@@ -3211,205 +3564,224 @@ var determineUrls = async (request, url, baseUrl, failureFunction, failureUrl, d
     );
   }
   return {
-    workflowUrl,
-    workflowFailureUrl
+    workflowUrl
   };
 };
 var AUTH_FAIL_MESSAGE = `Failed to authenticate Workflow request. If this is unexpected, see the caveat https://upstash.com/docs/workflow/basics/caveats#avoid-non-deterministic-code-outside-context-run`;
 
 // src/serve/index.ts
-var serveBase = (routeFunction, telemetry2, options) => {
+var serveBase = (routeFunction, telemetry2, options, internalOptions) => {
   const {
-    qstashClient,
-    onStepFinish,
     initialPayloadParser,
     url,
-    verbose,
-    receiver,
-    failureUrl,
     failureFunction,
     baseUrl,
     env,
-    retries,
-    retryDelay,
-    useJSONContent,
     disableTelemetry,
-    flowControl,
-    onError
-  } = processOptions(options);
+    middlewares,
+    internal
+  } = processOptions(options, internalOptions);
   telemetry2 = disableTelemetry ? void 0 : telemetry2;
-  const debug = WorkflowLogger.getLogger(verbose);
-  const handler = async (request) => {
-    await debug?.log("INFO", "ENDPOINT_START");
-    const { workflowUrl, workflowFailureUrl } = await determineUrls(
+  const { generateResponse: responseGenerator, useJSONContent } = internal;
+  const handler = async (request, middlewareManager) => {
+    await middlewareManager.dispatchDebug("onInfo", {
+      info: `Received request for workflow execution.`
+    });
+    const { workflowUrl } = await determineUrls(
       request,
       url,
       baseUrl,
-      failureFunction,
-      failureUrl,
-      debug
+      middlewareManager.dispatchDebug.bind(middlewareManager)
+    );
+    const { isFirstInvocation, workflowRunId, unknownSdk } = validateRequest(request);
+    const regionHeader = request.headers.get("upstash-region");
+    const { client: regionalClient, receiver: regionalReceiver } = getHandlersForRequest(
+      internal.qstashHandlers,
+      regionHeader,
+      isFirstInvocation
     );
     const requestPayload = await getPayload(request) ?? "";
-    await verifyRequest(requestPayload, request.headers.get("upstash-signature"), receiver);
-    const { isFirstInvocation, workflowRunId } = validateRequest(request);
-    debug?.setWorkflowRunId(workflowRunId);
-    const { rawInitialPayload, steps, isLastDuplicate, workflowRunEnded } = await parseRequest(
+    await verifyRequest(requestPayload, request.headers.get("upstash-signature"), regionalReceiver);
+    middlewareManager.assignWorkflowRunId(workflowRunId);
+    await middlewareManager.dispatchDebug("onInfo", {
+      info: `Run id identified. isFirstInvocation: ${isFirstInvocation}, unknownSdk: ${unknownSdk}`
+    });
+    const { rawInitialPayload, steps, isLastDuplicate, workflowRunEnded } = await parseRequest({
       requestPayload,
       isFirstInvocation,
+      unknownSdk,
       workflowRunId,
-      qstashClient.http,
-      request.headers.get("upstash-message-id"),
-      debug
-    );
+      requester: regionalClient.http,
+      messageId: request.headers.get("upstash-message-id"),
+      dispatchDebug: middlewareManager.dispatchDebug.bind(middlewareManager)
+    });
     if (workflowRunEnded) {
-      return onStepFinish(workflowRunId, "workflow-already-ended", {
-        condition: "workflow-already-ended"
-      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "workflow-already-ended"
+        })
+      );
     }
     if (isLastDuplicate) {
-      return onStepFinish(workflowRunId, "duplicate-step", {
-        condition: "duplicate-step"
-      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "duplicate-step"
+        })
+      );
     }
-    const failureCheck = await handleFailure(
+    const failureCheck = await handleFailure({
       request,
       requestPayload,
-      qstashClient,
+      qstashClient: regionalClient,
       initialPayloadParser,
       routeFunction,
       failureFunction,
       env,
-      retries,
-      retryDelay,
-      flowControl,
-      debug
-    );
+      dispatchDebug: middlewareManager.dispatchDebug.bind(middlewareManager)
+    });
     if (failureCheck.isErr()) {
       throw failureCheck.error;
-    } else if (failureCheck.value.result === "is-failure-callback") {
-      await debug?.log("WARN", "RESPONSE_DEFAULT", "failureFunction executed");
-      return onStepFinish(workflowRunId, "failure-callback", {
-        condition: "failure-callback",
-        result: failureCheck.value.response
+    } else if (failureCheck.value.result === "failure-function-executed") {
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Handled failure callback.`
       });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "failure-callback-executed",
+          result: failureCheck.value.response
+        })
+      );
+    } else if (failureCheck.value.result === "failure-function-undefined") {
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Failure callback invoked but no failure function defined.`
+      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "failure-callback-undefined"
+        })
+      );
     }
     const invokeCount = Number(request.headers.get(WORKFLOW_INVOKE_COUNT_HEADER) ?? "0");
     const label = request.headers.get(WORKFLOW_LABEL_HEADER) ?? void 0;
     const workflowContext = new WorkflowContext({
-      qstashClient,
+      qstashClient: regionalClient,
       workflowRunId,
       initialPayload: initialPayloadParser(rawInitialPayload),
       headers: recreateUserHeaders(request.headers),
       steps,
       url: workflowUrl,
-      failureUrl: workflowFailureUrl,
-      debug,
       env,
-      retries,
-      retryDelay,
       telemetry: telemetry2,
       invokeCount,
-      flowControl,
-      label
+      label,
+      middlewareManager
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
       workflowContext
     );
     if (authCheck.isErr()) {
-      await debug?.log("ERROR", "ERROR", { error: authCheck.error.message });
       throw authCheck.error;
     } else if (authCheck.value === "run-ended") {
-      await debug?.log("ERROR", "ERROR", { error: AUTH_FAIL_MESSAGE });
-      return onStepFinish(
-        isFirstInvocation ? "no-workflow-id" : workflowContext.workflowRunId,
-        "auth-fail",
-        { condition: "auth-fail" }
+      await middlewareManager.dispatchDebug("onError", {
+        error: new Error(AUTH_FAIL_MESSAGE)
+      });
+      return responseGenerator(
+        createResponseData(isFirstInvocation ? "no-workflow-id" : workflowContext.workflowRunId, {
+          condition: "auth-fail"
+        })
       );
     }
     const callReturnCheck = await handleThirdPartyCallResult({
       request,
       requestPayload: rawInitialPayload,
-      client: qstashClient,
+      client: regionalClient,
       workflowUrl,
-      failureUrl: workflowFailureUrl,
-      retries,
-      retryDelay,
-      flowControl,
       telemetry: telemetry2,
-      debug
+      middlewareManager
     });
     if (callReturnCheck.isErr()) {
-      await debug?.log("ERROR", "SUBMIT_THIRD_PARTY_RESULT", {
-        error: callReturnCheck.error.message
-      });
       throw callReturnCheck.error;
     } else if (callReturnCheck.value === "continue-workflow") {
       const result = isFirstInvocation ? await triggerFirstInvocation({
         workflowContext,
         useJSONContent,
         telemetry: telemetry2,
-        debug,
-        invokeCount
+        invokeCount,
+        middlewareManager,
+        unknownSdk
       }) : await triggerRouteFunction({
-        onStep: async () => routeFunction(workflowContext),
+        onStep: async () => {
+          if (steps.length === 1) {
+            await middlewareManager.dispatchLifecycle("runStarted", {});
+          }
+          return await routeFunction(workflowContext);
+        },
         onCleanup: async (result2) => {
-          await triggerWorkflowDelete(workflowContext, result2, debug);
+          await middlewareManager.dispatchLifecycle("runCompleted", {
+            result: result2
+          });
+          await triggerWorkflowDelete(
+            workflowContext,
+            result2,
+            false,
+            middlewareManager.dispatchDebug.bind(middlewareManager)
+          );
         },
         onCancel: async () => {
           await makeCancelRequest(workflowContext.qstashClient.http, workflowRunId);
         },
-        debug
+        middlewareManager
       });
       if (result.isOk() && isInstanceOf(result.value, WorkflowNonRetryableError)) {
-        return onStepFinish(workflowRunId, result.value, {
-          condition: "non-retryable-error",
-          result: result.value
-        });
+        return responseGenerator(
+          createResponseData(workflowRunId, {
+            condition: "non-retryable-error",
+            result: result.value
+          })
+        );
       }
       if (result.isOk() && isInstanceOf(result.value, WorkflowRetryAfterError)) {
-        return onStepFinish(workflowRunId, result.value, {
-          condition: "retry-after-error",
-          result: result.value
-        });
+        return responseGenerator(
+          createResponseData(workflowRunId, {
+            condition: "retry-after-error",
+            result: result.value
+          })
+        );
       }
       if (result.isErr()) {
-        await debug?.log("ERROR", "ERROR", { error: result.error.message });
         throw result.error;
       }
-      await debug?.log("INFO", "RESPONSE_WORKFLOW");
-      return onStepFinish(workflowContext.workflowRunId, "success", {
-        condition: "success"
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Workflow endpoint execution completed successfully.`
       });
+      return responseGenerator(
+        createResponseData(workflowContext.workflowRunId, {
+          condition: "success"
+        })
+      );
     } else if (callReturnCheck.value === "workflow-ended") {
-      return onStepFinish(workflowContext.workflowRunId, "workflow-already-ended", {
-        condition: "workflow-already-ended"
-      });
+      return responseGenerator(
+        createResponseData(workflowContext.workflowRunId, {
+          condition: "workflow-already-ended"
+        })
+      );
     }
-    await debug?.log("INFO", "RESPONSE_DEFAULT");
-    return onStepFinish("no-workflow-id", "fromCallback", {
-      condition: "fromCallback"
-    });
+    return responseGenerator(
+      createResponseData(workflowContext.workflowRunId, {
+        condition: "fromCallback"
+      })
+    );
   };
   const safeHandler = async (request) => {
+    const middlewareManager = new MiddlewareManager(middlewares);
     try {
-      return await handler(request);
+      return await handler(request, middlewareManager);
     } catch (error) {
       const formattedError = formatWorkflowError(error);
-      try {
-        onError?.(error);
-      } catch (onErrorError) {
-        const formattedOnErrorError = formatWorkflowError(onErrorError);
-        const errorMessage = `Error while running onError callback: '${formattedOnErrorError.message}'.
-Original error: '${formattedError.message}'`;
-        console.error(errorMessage);
-        return new Response(JSON.stringify({ error: errorMessage }), {
-          status: 500,
-          headers: {
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          }
-        });
-      }
+      await middlewareManager.dispatchDebug("onError", {
+        error: isInstanceOf(error, Error) ? error : new Error(formattedError.message)
+      });
       return new Response(JSON.stringify(formattedError), {
         status: 500,
         headers: {