@upstash/workflow 1.2.0 → 1.3.0

package/index.js

@@ -196,6 +196,66 @@ var getSteps = async (requester, workflowRunId, messageId, dispatchDebug) => {
     }
   }
 };
+function normalizeCursor(response) {
+  const cursor = response.cursor;
+  return { ...response, cursor: cursor || void 0 };
+}
+var DEFAULT_BULK_COUNT = 100;
+function buildBulkActionQueryParameters(request, options) {
+  const cursor = "cursor" in request ? request.cursor : void 0;
+  if ("all" in request) {
+    return { count: request.count ?? DEFAULT_BULK_COUNT, cursor };
+  }
+  if ("dlqIds" in request) {
+    const ids = request.dlqIds;
+    if (Array.isArray(ids) && ids.length === 0) {
+      throw new import_qstash2.QstashError(
+        "Empty dlqIds array provided. If you intend to target all DLQ messages, use { all: true } explicitly."
+      );
+    }
+    return { dlqIds: ids, cursor };
+  }
+  if ("workflowRunIds" in request && request.workflowRunIds) {
+    if (request.workflowRunIds.length === 0) {
+      throw new import_qstash2.QstashError(
+        "Empty workflowRunIds array provided. If you intend to target all workflow runs, use { all: true } explicitly."
+      );
+    }
+    return { workflowRunIds: request.workflowRunIds };
+  }
+  const filter = request.filter;
+  if (!filter) {
+    throw new import_qstash2.QstashError(
+      "No filter provided. Use { filter: { ... } } with at least one filter field, or { all: true }."
+    );
+  }
+  if (options?.translateWorkflowUrl) {
+    const { workflowUrlStartingWith, workflowUrl, ...rest } = filter;
+    if (workflowUrlStartingWith && workflowUrl) {
+      throw new import_qstash2.QstashError(
+        "workflowUrl and workflowUrlStartingWith are mutually exclusive. Use workflowUrl for exact match or workflowUrlStartingWith for prefix match."
+      );
+    }
+    const urlParams = {};
+    if (workflowUrlStartingWith) {
+      urlParams.workflowUrl = workflowUrlStartingWith;
+    } else if (workflowUrl) {
+      urlParams.workflowUrl = workflowUrl;
+      urlParams.workflowUrlExactMatch = true;
+    }
+    return {
+      ...rest,
+      ...urlParams,
+      count: request.count ?? DEFAULT_BULK_COUNT,
+      cursor
+    };
+  }
+  return {
+    ...filter,
+    count: request.count ?? DEFAULT_BULK_COUNT,
+    cursor
+  };
+}
 
 // src/constants.ts
 var WORKFLOW_ID_HEADER = "Upstash-Workflow-RunId";
@@ -206,6 +266,7 @@ 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_RETRIED_HEADER = "Upstash-Retried";
 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";
@@ -214,7 +275,7 @@ 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 = "v1.0.0";
+var VERSION = "v1.2.1";
 var SDK_TELEMETRY = `@upstash/workflow@${VERSION}`;
 var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
@@ -869,6 +930,9 @@ var recreateUserHeaders = (headers) => {
   }
   return filteredHeaders;
 };
+var isThirdPartyCallResult = (request) => {
+  return request.headers.get("Upstash-Workflow-Callback") !== null;
+};
 var handleThirdPartyCallResult = async ({
   request,
   requestPayload,
@@ -878,7 +942,7 @@ var handleThirdPartyCallResult = async ({
   middlewareManager
 }) => {
   try {
-    if (request.headers.get("Upstash-Workflow-Callback")) {
+    if (isThirdPartyCallResult(request)) {
       let callbackPayload;
       if (requestPayload) {
         callbackPayload = requestPayload;
@@ -2654,6 +2718,13 @@ var WorkflowContext = class {
    * ```
    */
   label;
+  /**
+   * Number of times QStash has retried delivering the current request.
+   *
+   * Sourced from the `Upstash-Retried` header. `0` on the first delivery,
+   * `1` on the first retry, `2` on the second, and so on.
+   */
+  retried;
   constructor({
     qstashClient,
     workflowRunId,
@@ -2666,6 +2737,7 @@ var WorkflowContext = class {
     telemetry,
     invokeCount,
     label,
+    retried,
     middlewareManager
   }) {
     this.qstashClient = qstashClient;
@@ -2677,6 +2749,7 @@ var WorkflowContext = class {
     this.requestPayload = initialPayload;
     this.env = env ?? {};
     this.label = label;
+    this.retried = retried ?? 0;
     const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
     middlewareManagerInstance.assignContext(this);
     this.executor = new AutoExecutor(
@@ -2940,7 +3013,8 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
     const disabledContext = new _DisabledWorkflowContext({
       qstashClient: new import_qstash10.Client({
         baseUrl: "disabled-client",
-        token: "disabled-client"
+        token: "disabled-client",
+        devMode: false
       }),
       workflowRunId: context.workflowRunId,
       workflowRunCreatedAt: context.workflowRunCreatedAt,
@@ -2949,7 +3023,8 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       url: context.url,
       initialPayload: context.requestPayload,
       env: context.env,
-      label: context.label
+      label: context.label,
+      retried: context.retried
     });
     try {
       await routeFunction(disabledContext);
@@ -3165,6 +3240,7 @@ var handleFailure = async ({
       errorMessage = `Couldn't parse 'failResponse' in 'failureFunction', received: '${decodedBody}'`;
     }
     const userHeaders = recreateUserHeaders(request.headers);
+    const retried = Number(request.headers.get(WORKFLOW_RETRIED_HEADER) ?? "0");
     const workflowContext = new WorkflowContext({
       qstashClient,
       workflowRunId,
@@ -3176,6 +3252,7 @@ var handleFailure = async ({
       telemetry: void 0,
       // not going to make requests in authentication check
       label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0,
+      retried,
       workflowRunCreatedAt: workflowCreatedAt,
       middlewareManager: void 0
     });
@@ -3335,6 +3412,9 @@ var getReceiver = (environment, receiverConfig, region) => {
     if (receiverConfig === "set-to-undefined") {
       return void 0;
     }
+    if (isQStashDevModeEnabled(environment)) {
+      return new import_qstash11.Receiver({ devMode: true });
+    }
     const receiverEnv = readReceiverEnvironmentVariables(environment, region);
     return receiverEnv.QSTASH_CURRENT_SIGNING_KEY && receiverEnv.QSTASH_NEXT_SIGNING_KEY ? new import_qstash11.Receiver({
       currentSigningKey: receiverEnv.QSTASH_CURRENT_SIGNING_KEY,
@@ -3344,6 +3424,10 @@ var getReceiver = (environment, receiverConfig, region) => {
     return receiverConfig;
   }
 };
+var isQStashDevModeEnabled = (env) => {
+  const value = env.QSTASH_DEV;
+  return value === "true" || value === "1";
+};
 var getQStashHandlerOptions = (...params) => {
   const handlers = getQStashHandlers(...params);
   return {
@@ -3653,12 +3737,13 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
       );
     }
     const invokeCount = Number(request.headers.get(WORKFLOW_INVOKE_COUNT_HEADER) ?? "0");
+    const retried = Number(request.headers.get(WORKFLOW_RETRIED_HEADER) ?? "0");
     const label = request.headers.get(WORKFLOW_LABEL_HEADER) ?? void 0;
     const workflowRunCreatedAt = request.headers.get(WORKFLOW_CREATED_AT_HEADER);
     const workflowContext = new WorkflowContext({
       qstashClient: regionalClient,
       workflowRunId,
-      initialPayload: initialPayloadParser(rawInitialPayload),
+      initialPayload: isThirdPartyCallResult(request) ? JSON.parse(rawInitialPayload) : initialPayloadParser(rawInitialPayload),
       headers: recreateUserHeaders(request.headers),
       steps,
       url: workflowUrl,
@@ -3666,6 +3751,7 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
       telemetry,
       invokeCount,
       label,
+      retried,
       workflowRunCreatedAt: Number(workflowRunCreatedAt),
       middlewareManager
     });
@@ -3800,7 +3886,19 @@ var serve = (routeFunction, options) => {
 var import_qstash12 = require("@upstash/qstash");
 
 // src/client/dlq.ts
-var DLQ = class _DLQ {
+function buildResumeRestartHeaders(options) {
+  const headers = {};
+  if (options?.flowControl) {
+    const { flowControlKey, flowControlValue } = prepareFlowControl(options.flowControl);
+    headers["Upstash-Flow-Control-Key"] = flowControlKey;
+    headers["Upstash-Flow-Control-Value"] = flowControlValue;
+  }
+  if (options?.retries !== void 0) {
+    headers["Upstash-Retries"] = options.retries.toString();
+  }
+  return headers;
+}
+var DLQ = class {
   constructor(client) {
     this.client = client;
   }
@@ -3823,40 +3921,66 @@ var DLQ = class _DLQ {
    */
   async list(parameters) {
     const { cursor, count, filter } = parameters || {};
-    return await this.client.http.request({
-      path: ["v2", "dlq"],
-      method: "GET",
-      query: {
-        cursor,
-        count,
-        ...filter,
-        source: "workflow"
-      }
-    });
+    return normalizeCursor(
+      await this.client.http.request({
+        path: ["v2", "dlq"],
+        method: "GET",
+        query: {
+          cursor,
+          count,
+          ...filter,
+          source: "workflow"
+        }
+      })
+    );
   }
-  async resume(parameters) {
-    const { headers, queryParams } = _DLQ.handleDLQOptions(parameters);
-    const { workflowRuns } = await this.client.http.request({
-      path: ["v2", "workflows", "dlq", `resume?${queryParams}`],
-      headers,
-      method: "POST"
-    });
-    if (Array.isArray(parameters.dlqId)) {
-      return workflowRuns;
+  async resume(request, options) {
+    if (typeof request === "object" && !Array.isArray(request) && "dlqId" in request) {
+      const { dlqId, flowControl, retries } = request;
+      const dlqIds = Array.isArray(dlqId) ? dlqId : [dlqId];
+      const { workflowRuns } = await this.client.http.request({
+        path: ["v2", "workflows", "dlq", "resume"],
+        query: { dlqIds },
+        method: "POST",
+        headers: buildResumeRestartHeaders({ flowControl, retries })
+      });
+      return Array.isArray(dlqId) ? workflowRuns : workflowRuns[0];
     }
-    return workflowRuns[0];
+    if (typeof request === "string") request = [request];
+    if (Array.isArray(request) && request.length === 0) return { workflowRuns: [] };
+    const filters = Array.isArray(request) ? { dlqIds: request } : request;
+    return normalizeCursor(
+      await this.client.http.request({
+        path: ["v2", "workflows", "dlq", "resume"],
+        query: buildBulkActionQueryParameters(filters),
+        method: "POST",
+        headers: buildResumeRestartHeaders(options)
+      })
+    );
   }
-  async restart(parameters) {
-    const { headers, queryParams } = _DLQ.handleDLQOptions(parameters);
-    const { workflowRuns } = await this.client.http.request({
-      path: ["v2", "workflows", "dlq", `restart?${queryParams}`],
-      headers,
-      method: "POST"
-    });
-    if (Array.isArray(parameters.dlqId)) {
-      return workflowRuns;
+  async restart(request, options) {
+    if (typeof request === "object" && !Array.isArray(request) && "dlqId" in request) {
+      const { dlqId, flowControl, retries } = request;
+      const dlqIds = Array.isArray(dlqId) ? dlqId : [dlqId];
+      const { workflowRuns } = await this.client.http.request({
+        path: ["v2", "workflows", "dlq", "restart"],
+        query: { dlqIds },
+        method: "POST",
+        headers: buildResumeRestartHeaders({ flowControl, retries })
+      });
+      return Array.isArray(dlqId) ? workflowRuns : workflowRuns[0];
     }
-    return workflowRuns[0];
+    if (typeof request === "string") request = [request];
+    if (Array.isArray(request) && request.length === 0) return { workflowRuns: [] };
+    const filters = Array.isArray(request) ? { dlqIds: request } : request;
+    return normalizeCursor(
+      await this.client.http.request({
+        path: ["v2", "workflows", "dlq", "restart"],
+        query: buildBulkActionQueryParameters(filters),
+        method: "POST",
+        headers: buildResumeRestartHeaders(options)
+      })
+    );
   }
   /**
    * Retry the failure callback of a workflow run whose failureUrl/failureFunction
@@ -3873,35 +3997,36 @@ var DLQ = class _DLQ {
     return response;
   }
   /**
-   * Handles DLQ options and prepares headers and query parameters.
+   * Delete DLQ messages.
    *
-   * @param options - DLQ resume/restart options
-   */
-  static handleDLQOptions(options) {
-    const { dlqId, flowControl, retries } = options;
-    const headers = {};
-    if (flowControl) {
-      const { flowControlKey, flowControlValue } = prepareFlowControl(flowControl);
-      headers["Upstash-Flow-Control-Key"] = flowControlKey;
-      headers["Upstash-Flow-Control-Value"] = flowControlValue;
-    }
-    if (retries !== void 0) {
-      headers["Upstash-Retries"] = retries.toString();
-    }
-    return {
-      queryParams: _DLQ.getDlqIdQueryParameter(dlqId),
-      headers
-    };
-  }
-  /**
-   * Converts DLQ ID(s) to query parameter string.
+   * Can be called with:
+   * - A single dlqId: `delete("id")`
+   * - An array of dlqIds: `delete(["id1", "id2"])`
+   * - A filter object: `delete({ filter: { label: "my-label", fromDate: 1640995200000 } })`
+   * - To target all entries: `delete({ all: true })`
+   *
+   * Processes up to `count` messages per call (defaults to 100).
+   * Call in a loop until cursor is undefined to process all:
    *
-   * @param dlqId - Single DLQ ID or array of DLQ IDs
+   * ```ts
+   * let cursor: string | undefined;
+   * do {
+   *   const result = await client.dlq.delete({ all: true, count: 100, cursor });
+   *   cursor = result.cursor;
+   * } while (cursor);
+   * ```
    */
-  static getDlqIdQueryParameter(dlqId) {
-    const dlqIds = Array.isArray(dlqId) ? dlqId : [dlqId];
-    const paramsArray = dlqIds.map((id) => ["dlqIds", id]);
-    return new URLSearchParams(paramsArray).toString();
+  async delete(request) {
+    if (typeof request === "string") request = [request];
+    if (Array.isArray(request) && request.length === 0) return { deleted: 0 };
+    const filters = Array.isArray(request) ? { dlqIds: request } : request;
+    return normalizeCursor(
+      await this.client.http.request({
+        path: ["v2", "workflows", "dlq"],
+        method: "DELETE",
+        query: buildBulkActionQueryParameters(filters)
+      })
+    );
   }
 };
 
@@ -3911,82 +4036,25 @@ var Client4 = class {
   constructor(clientConfig) {
     this.client = new import_qstash12.Client(clientConfig);
   }
-  /**
-   * Cancel an ongoing workflow
-   *
-   * Returns true if workflow is canceled succesfully. Otherwise, throws error.
-   *
-   * There are multiple ways you can cancel workflows:
-   * - pass one or more workflow run ids to cancel them
-   * - pass a workflow url to cancel all runs starting with this url
-   * - cancel all pending or active workflow runs
-   *
-   * ### Cancel a set of workflow runs
-   *
-   * ```ts
-   * // cancel a single workflow
-   * await client.cancel({ ids: "<WORKFLOW_RUN_ID>" })
-   *
-   * // cancel a set of workflow runs
-   * await client.cancel({ ids: [
-   *   "<WORKFLOW_RUN_ID_1>",
-   *   "<WORKFLOW_RUN_ID_2>",
-   * ]})
-   * ```
-   *
-   * ### Cancel workflows starting with a url
-   *
-   * If you have an endpoint called `https://your-endpoint.com` and you
-   * want to cancel all workflow runs on it, you can use `urlStartingWith`.
-   *
-   * Note that this will cancel workflows in all endpoints under
-   * `https://your-endpoint.com`.
-   *
-   * ```ts
-   * await client.cancel({ urlStartingWith: "https://your-endpoint.com" })
-   * ```
-   *
-   * ### Cancel *all* workflows
-   *
-   * To cancel all pending and currently running workflows, you can
-   * do it like this:
-   *
-   * ```ts
-   * await client.cancel({ all: true })
-   * ```
-   *
-   * @param ids run id of the workflow to delete
-   * @param urlStartingWith cancel workflows starting with this url. Will be ignored
-   *   if `ids` parameter is set.
-   * @param all set to true in order to cancel all workflows. Will be ignored
-   *   if `ids` or `urlStartingWith` parameters are set.
-   * @returns true if workflow is succesfully deleted. Otherwise throws QStashError
-   */
-  async cancel({
-    ids,
-    urlStartingWith,
-    all
-  }) {
-    let body;
-    if (ids) {
-      const runIdArray = typeof ids === "string" ? [ids] : ids;
-      body = JSON.stringify({ workflowRunIds: runIdArray });
-    } else if (urlStartingWith) {
-      body = JSON.stringify({ workflowUrl: urlStartingWith });
-    } else if (all) {
-      body = "{}";
-    } else {
-      throw new TypeError("The `cancel` method cannot be called without any options.");
+  async cancel(request) {
+    if (typeof request === "object" && !Array.isArray(request) && ("ids" in request || "urlStartingWith" in request)) {
+      const legacy = request;
+      if (legacy.ids) {
+        const ids = typeof legacy.ids === "string" ? [legacy.ids] : legacy.ids;
+        return this.cancel(ids);
+      }
+      if (legacy.urlStartingWith) {
+        return this.cancel({ filter: { workflowUrlStartingWith: legacy.urlStartingWith } });
+      }
     }
-    const result = await this.client.http.request({
+    if (typeof request === "string") request = [request];
+    if (Array.isArray(request) && request.length === 0) return { cancelled: 0 };
+    const filters = Array.isArray(request) ? { workflowRunIds: request } : request;
+    return await this.client.http.request({
       path: ["v2", "workflows", "runs"],
       method: "DELETE",
-      body,
-      headers: {
-        "Content-Type": "application/json"
-      }
+      query: buildBulkActionQueryParameters(filters, { translateWorkflowUrl: true })
     });
-    return result;
   }
   /**
    * Notify a workflow run waiting for an event
@@ -4110,33 +4178,17 @@ var Client4 = class {
    * ```
    */
   async logs(params) {
-    const { workflowRunId, cursor, count, state, workflowUrl, workflowCreatedAt } = params ?? {};
-    const urlParams = new URLSearchParams({ groupBy: "workflowRunId" });
-    if (workflowRunId) {
-      urlParams.append("workflowRunId", workflowRunId);
-    }
-    if (cursor) {
-      urlParams.append("cursor", cursor);
-    }
-    if (count) {
-      urlParams.append("count", count.toString());
-    }
-    if (state) {
-      urlParams.append("state", state);
-    }
-    if (workflowUrl) {
-      urlParams.append("workflowUrl", workflowUrl);
-    }
-    if (workflowCreatedAt) {
-      urlParams.append("workflowCreatedAt", workflowCreatedAt.toString());
-    }
-    if (params?.label) {
-      urlParams.append("label", params.label);
-    }
-    const result = await this.client.http.request({
-      path: ["v2", "workflows", `events?${urlParams.toString()}`]
+    const { cursor, count, filter, ...legacyFilter } = params ?? {};
+    return await this.client.http.request({
+      path: ["v2", "workflows", "events"],
+      query: {
+        groupBy: "workflowRunId",
+        ...legacyFilter,
+        cursor,
+        count,
+        ...filter
+      }
     });
-    return result;
   }
   get dlq() {
     return new DLQ(this.client);