@upstash/workflow 1.2.0 → 1.3.0

package/index.d.ts

@@ -1,5 +1,5 @@
-import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-B2S08hRU.js';
-export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-B2S08hRU.js';
+import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-B_E1VAK6.js';
+export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-B_E1VAK6.js';
 import { FlowControl, PublishRequest, HTTPMethods, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 
@@ -431,6 +431,7 @@ type TriggerOptions = {
         header?: true | string[];
     };
 };
+/** @deprecated Use `resume(dlqId)` or `resume([dlqId1, dlqId2])` instead of `resume({ dlqId })` */
 type DLQResumeRestartOptions<TDLQId extends string | string[] = string | string[]> = {
     dlqId: TDLQId;
 } & Pick<TriggerOptions, "flowControl" | "retries">;
@@ -517,12 +518,116 @@ declare const serveBase: <TInitialPayload = unknown, TRequest extends Request =
  */
 declare const serve: <TInitialPayload = unknown, TRequest extends Request = Request, TResponse extends Response = Response, TResult = unknown>(routeFunction: RouteFunction<TInitialPayload, TResult>, options?: WorkflowServeOptions<TInitialPayload, TResult>) => ReturnType<typeof serveBase<TInitialPayload, TRequest, TResponse, TResult>>;
 
-type QStashDLQFilterOptions = NonNullable<Required<Parameters<Client$1["dlq"]["listMessages"]>[0]>>["filter"];
-type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus"> & {
-    workflowRunId?: string;
-    workflowCreatedAt?: string;
-    failureFunctionState?: FailureCallbackInfo["state"];
+type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>>;
+}[keyof T];
+/** Shared filter fields accepted by every qstash & workflow endpoint. */
+type UniversalFilterFields = {
+    fromDate?: Date | number;
+    toDate?: Date | number;
+    callerIp?: string;
     label?: string;
+    flowControlKey?: string;
+};
+/** Workflow-specific filter fields for DLQ and bulk endpoints. */
+type WorkflowFilterFields = {
+    workflowUrl?: string;
+    workflowRunId?: string;
+    workflowCreatedAt?: number;
+    failureFunctionState?: string;
+};
+type WorkflowLogsFilterFields = {
+    state?: WorkflowRunLog["workflowState"];
+    messageId?: string;
+};
+type DLQActionFilterFields = UniversalFilterFields & WorkflowFilterFields;
+/** Cancel filter: exact URL match. Cannot combine with `workflowUrlStartingWith`. */
+type CancelFilterWithExactUrl = UniversalFilterFields & {
+    workflowUrl: string;
+    workflowUrlStartingWith?: never;
+};
+/** Cancel filter: URL prefix match. Cannot combine with `workflowUrl`. */
+type CancelFilterWithPrefixUrl = UniversalFilterFields & {
+    workflowUrlStartingWith: string;
+    workflowUrl?: never;
+};
+/** Cancel filter: no URL. Requires at least one other filter field. */
+type CancelFilterWithoutUrl = RequireAtLeastOne<UniversalFilterFields> & {
+    workflowUrl?: never;
+    workflowUrlStartingWith?: never;
+};
+type CancelFilter = CancelFilterWithExactUrl | CancelFilterWithPrefixUrl | CancelFilterWithoutUrl;
+type WorkflowDLQBulkCount = {
+    cursor?: string;
+    /**
+     * Maximum number of messages to process per call.
+     *
+     * @default 100
+     */
+    count?: number;
+};
+/**
+ * DLQ bulk actions (resume, restart, delete) support three modes:
+ * - By dlqIds (no cursor)
+ * - By filter fields (with optional cursor and count)
+ * - All (with optional cursor and count)
+ */
+type WorkflowDLQActionFilters = {
+    dlqIds: string | string[];
+    filter?: never;
+    all?: never;
+    count?: never;
+    cursor?: never;
+} | ({
+    filter: RequireAtLeastOne<DLQActionFilterFields>;
+    dlqIds?: never;
+    all?: never;
+} & WorkflowDLQBulkCount) | ({
+    all: true;
+    dlqIds?: never;
+    filter?: never;
+} & WorkflowDLQBulkCount);
+type WorkflowDLQListFilters = UniversalFilterFields & WorkflowFilterFields & {
+    /** @deprecated Use `workflowUrl` instead. */
+    url?: string;
+    /** @deprecated No longer supported in the new API. */
+    responseStatus?: number;
+};
+type WorkflowCancelCount = {
+    /**
+     * Maximum number of workflow runs to cancel per call.
+     *
+     * @default 100
+     */
+    count?: number;
+};
+/**
+ * We don't accept a single workflowRunId or workflowCreatedAt because there
+ * could only be one running workflow with a single wfrid at the same time.
+ * So using these do not make sense.
+ *
+ * Also failureFunctionState is not available.
+ * Cancel does not support cursor.
+ */
+type WorkflowRunCancelFilters = {
+    workflowRunIds: string[];
+    filter?: never;
+    all?: never;
+    count?: never;
+} | ({
+    filter: CancelFilter;
+    workflowRunIds?: never;
+    all?: never;
+} & WorkflowCancelCount) | ({
+    all: true;
+    workflowRunIds?: never;
+    filter?: never;
+} & WorkflowCancelCount);
+type WorkflowLogsListFilters = UniversalFilterFields & Pick<WorkflowFilterFields, "workflowUrl" | "workflowRunId" | "workflowCreatedAt"> & WorkflowLogsFilterFields;
+
+type ResumeRestartOptions = {
+    flowControl?: FlowControl;
+    retries?: number;
 };
 type FailureCallbackInfo = {
     state?: "CALLBACK_FAIL" | "CALLBACK_SUCCESS" | "CALLBACK_INPROGRESS";
@@ -587,7 +692,7 @@ declare class DLQ {
     list(parameters?: {
         cursor?: string;
         count?: number;
-        filter?: DLQFilterOptions;
+        filter?: WorkflowDLQListFilters;
     }): Promise<{
         messages: PublicDLQMessage[];
         cursor?: string;
@@ -601,41 +706,31 @@ declare class DLQ {
      * If you want to restart the workflow run from the beginning, use
      * `restart` method instead.
      *
-     * Example with a single DLQ ID:
-     * ```ts
-     * const response = await client.dlq.resume({
-     *   dlqId: "dlq-12345",
-     *   flowControl: {
-     *     key: "my-flow-control-key",
-     *     value: "my-flow-control-value",
-     *   },
-     *   retries: 3,
-     * });
+     * Can be called with:
+     * - A single dlqId: `resume("id")`
+     * - An array of dlqIds: `resume(["id1", "id2"])`
+     * - A filter object: `resume({ filter: { label: "my-label", fromDate: 1640995200000 } })`
+     * - To target all entries: `resume({ all: true })`
      *
-     * console.log(response.workflowRunId); // ID of the new workflow run
-     * ```
+     * Processes up to `count` messages per call (defaults to 100).
+     * Call in a loop until cursor is undefined to process all:
      *
-     * Example with multiple DLQ IDs:
      * ```ts
-     * const response = await client.dlq.resume({
-     *  dlqId: ["dlq-12345", "dlq-67890"],
-     *  // other parameters...
-     * });
-     * console.log(response[0].workflowRunId); // ID of the first workflow run
-     * console.log(response[1].workflowRunId); // ID of the second workflow run
+     * let cursor: string | undefined;
+     * do {
+     *   const result = await client.dlq.resume({ all: true, count: 100, cursor });
+     *   cursor = result.cursor;
+     * } while (cursor);
      * ```
-     *
-     * if the dlqId is not found, throws an error.
-     *
-     * @param dlqId - The ID(s) of the DLQ message(s) to resume.
-     * @param flowControl - Optional flow control parameters. If not passed, flow
-     *     control of the failing workflow will be used
-     * @param retries - Optional number of retries to perform if the request fails.
-     *     If not passed, retries settings of the failing workflow will be used.
-     * @returns run id and creation time of the new workflow run(s).
      */
-    resume(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
-    resume(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    resume(request: string | string[] | WorkflowDLQActionFilters, options?: ResumeRestartOptions): Promise<{
+        cursor?: string;
+        workflowRuns: DLQResumeRestartResponse[];
+    }>;
+    /** @deprecated Use `resume(dlqId)` instead */
+    resume(request: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
+    /** @deprecated Use `resume([dlqId1, dlqId2])` instead */
+    resume(request: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
     /**
      * Restarts the workflow run for the given DLQ message(s).
      *
@@ -645,41 +740,31 @@ declare class DLQ {
      * If you want to resume the workflow run from where it failed, use
      * `resume` method instead.
      *
-     * Example with a single DLQ ID:
-     * ```ts
-     * const response = await client.dlq.restart({
-     *   dlqId: "dlq-12345",
-     *   flowControl: {
-     *     key: "my-flow-control-key",
-     *     value: "my-flow-control-value",
-     *   },
-     *   retries: 3,
-     * });
+     * Can be called with:
+     * - A single dlqId: `restart("id")`
+     * - An array of dlqIds: `restart(["id1", "id2"])`
+     * - A filter object: `restart({ filter: { label: "my-label", fromDate: 1640995200000 } })`
+     * - To target all entries: `restart({ all: true })`
      *
-     * console.log(response.workflowRunId); // ID of the new workflow run
-     * ```
+     * Processes up to `count` messages per call (defaults to 100).
+     * Call in a loop until cursor is undefined to process all:
      *
-     * Example with multiple DLQ IDs:
      * ```ts
-     * const response = await client.dlq.restart({
-     *  dlqId: ["dlq-12345", "dlq-67890"],
-     *  // other parameters...
-     * });
-     * console.log(response[0].workflowRunId); // ID of the first workflow run
-     * console.log(response[1].workflowRunId); // ID of the second workflow run
+     * let cursor: string | undefined;
+     * do {
+     *   const result = await client.dlq.restart({ all: true, count: 100, cursor });
+     *   cursor = result.cursor;
+     * } while (cursor);
      * ```
-     *
-     * if the dlqId is not found, throws an error.
-     *
-     * @param dlqId - The ID(s) of the DLQ message(s) to restart.
-     * @param flowControl - Optional flow control parameters. If not passed, flow
-     *     control of the failing workflow will be used
-     * @param retries - Optional number of retries to perform if the request fails.
-     *     If not passed, retries settings of the failing workflow will be used.
-     * @returns run id and creation time of the new workflow run(s).
      */
-    restart(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
-    restart(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    restart(request: string | string[] | WorkflowDLQActionFilters, options?: ResumeRestartOptions): Promise<{
+        cursor?: string;
+        workflowRuns: DLQResumeRestartResponse[];
+    }>;
+    /** @deprecated Use `restart(dlqId)` instead */
+    restart(request: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
+    /** @deprecated Use `restart([dlqId1, dlqId2])` instead */
+    restart(request: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
     /**
      * Retry the failure callback of a workflow run whose failureUrl/failureFunction
      * request has failed.
@@ -691,17 +776,31 @@ declare class DLQ {
         error?: string;
     }>;
     /**
-     * Handles DLQ options and prepares headers and query parameters.
+     * Delete DLQ messages.
      *
-     * @param options - DLQ resume/restart options
-     */
-    private static handleDLQOptions;
-    /**
-     * 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);
+     * ```
      */
-    private static getDlqIdQueryParameter;
+    delete(request: string | string[] | WorkflowDLQActionFilters): Promise<{
+        cursor?: string;
+        deleted: number;
+    } & {
+        error?: string;
+    }>;
 }
 
 type ClientConfig = ConstructorParameters<typeof Client$1>[0];
@@ -718,64 +817,32 @@ declare class Client {
     private client;
     constructor(clientConfig: ClientConfig);
     /**
-     * Cancel an ongoing workflow
-     *
-     * Returns true if workflow is canceled succesfully. Otherwise, throws error.
+     * Cancel an ongoing workflow.
      *
-     * 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
+     * Can be called with:
+     * - A single workflow run id: `cancel("wfr_123")`
+     * - An array of workflow run ids: `cancel(["wfr_123", "wfr_456"])`
+     * - By exact URL: `cancel({ filter: { workflowUrl: "https://..." } })`
+     * - By URL prefix: `cancel({ filter: { workflowUrlStartingWith: "https://..." } })`
+     * - With other filters: `cancel({ filter: { label: "my-label" } })`
+     * - To target all: `cancel({ all: true })`
      *
-     * ### Cancel a set of workflow runs
+     * Cancels up to `count` workflow runs per call (defaults to 100).
      *
      * ```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>",
-     * ]})
+     * const result = await client.cancel({ all: true, count: 50 });
      * ```
-     *
-     * ### 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
      */
-    cancel({ ids, urlStartingWith, all, }: {
+    cancel(request: string | string[] | WorkflowRunCancelFilters): Promise<{
+        cancelled: number;
+    }>;
+    /** @deprecated Use `cancel(id)`, `cancel([id1, id2])`, `cancel({ filter: { workflowUrlStartingWith } })` instead. */
+    cancel(request: {
         ids?: string | string[];
         urlStartingWith?: string;
         all?: true;
     }): Promise<{
         cancelled: number;
-    } & {
-        error?: string;
     }>;
     /**
      * Notify a workflow run waiting for an event
@@ -923,13 +990,19 @@ declare class Client {
      * ```
      */
     logs(params?: {
-        workflowRunId?: WorkflowRunLog["workflowRunId"];
         cursor?: string;
         count?: number;
-        state?: WorkflowRunLog["workflowState"];
-        workflowUrl?: WorkflowRunLog["workflowUrl"];
-        workflowCreatedAt?: WorkflowRunLog["workflowRunCreatedAt"];
-        label?: WorkflowRunLog["label"];
+        filter?: WorkflowLogsListFilters;
+        /** @deprecated Use `filter.workflowRunId` instead. */
+        workflowRunId?: string;
+        /** @deprecated Use `filter.state` instead. */
+        state?: string;
+        /** @deprecated Use `filter.workflowUrl` instead. */
+        workflowUrl?: string;
+        /** @deprecated Use `filter.label` instead. */
+        label?: string;
+        /** @deprecated Use `filter.workflowCreatedAt` instead. */
+        workflowCreatedAt?: number;
     }): Promise<WorkflowRunLogs>;
     get dlq(): DLQ;
 }