DX-2238: document bulk actions (#654)

* DX-2238: document bulk actions

* Update docs for new bulk action APIs

Update QStash and Workflow SDK docs to reflect new filter-based bulk
action APIs. Add cursor pagination to all bulk operations (delete,
retry, cancel, resume, restart). Update Workflow docs for new API
signatures where filters move into a filter object, dlqId becomes
a direct argument, and new filter fields (callerIp, flowControlKey,
etc.) are documented.

---------

Co-authored-by: ytkimirti <yusuftaha9@gmail.com>

Author: CahidArda

docs.json

@@ -1308,6 +1308,7 @@
                               "workflow/basics/client/dlq/list",
                               "workflow/basics/client/dlq/restart",
                               "workflow/basics/client/dlq/resume",
+                              "workflow/basics/client/dlq/delete",
                               "workflow/basics/client/dlq/callback"
                             ]
                           },
@@ -1345,6 +1346,7 @@
                       "workflow/features/dlq",
                       "workflow/features/dlq/restart",
                       "workflow/features/dlq/resume",
+                      "workflow/features/dlq/delete",
                       "workflow/features/dlq/callback"
                     ]
                   },

qstash/sdks/ts/examples/dlq.mdx

@@ -10,12 +10,11 @@ You can go through the results using the `cursor`.
 ```typescript
 import { Client } from "@upstash/qstash";
 
-const client = new Client("<QSTASH_TOKEN>");
-const dlq = client.dlq;
+const client = new Client({ token: "<QSTASH_TOKEN>" });
 const all_messages = [];
 let cursor = null;
 while (true) {
-  const res = await dlq.listMessages({ cursor });
+  const res = await client.dlq.listMessages({ cursor });
   all_messages.push(...res.messages);
   cursor = res.cursor;
   if (!cursor) {
@@ -24,12 +23,80 @@ while (true) {
 }
 ```
 
-#### Delete a message from the DLQ
+#### List messages with filters
 
 ```typescript
 import { Client } from "@upstash/qstash";
 
 const client = new Client({ token: "<QSTASH_TOKEN>" });
-const dlq = client.dlq;
-await dlq.delete("dlqId");
+
+// filter and paginate with top-level options
+const res = await client.dlq.listMessages({
+  count: 10,
+  order: "latestFirst",
+  filter: { url: "https://example.com" }
+})
+
+// fetch specific DLQ messages by ID
+const res2 = await client.dlq.listMessages({
+  dlqIds: ["dlq-id-1", "dlq-id-2"]
+})
+```
+
+#### Delete messages from the DLQ
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+
+// delete a single message
+await client.dlq.delete("dlqId");
+
+// delete multiple messages
+await client.dlq.delete(["dlq-id-1", "dlq-id-2"]);
+
+// delete with filters
+let cursor: string | undefined;
+do {
+  const result = await client.dlq.delete({
+    filter: { url: "https://example.com", responseStatus: 500 },
+    cursor,
+  });
+  cursor = result.cursor;
+} while (cursor);
+
+// delete all DLQ messages
+do {
+  const result = await client.dlq.delete({ all: true, cursor });
+  cursor = result.cursor;
+} while (cursor);
+```
+
+<Note>
+  `client.dlq.deleteMany()` is deprecated. Use `client.dlq.delete()` with an array of dlqIds or filters instead.
+</Note>
+
+#### Retry messages from the DLQ
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+
+// retry a single message
+await client.dlq.retry("dlqId");
+
+// retry multiple messages
+await client.dlq.retry(["dlq-id-1", "dlq-id-2"]);
+
+// retry with filters
+let cursor: string | undefined;
+do {
+  const result = await client.dlq.retry({
+    filter: { queueName: "my-queue" },
+    cursor,
+  });
+  cursor = result.cursor;
+} while (cursor);
 ```

qstash/sdks/ts/examples/logs.mdx

@@ -23,7 +23,7 @@ while (true) {
 }
 ```
 
-#### Filter logs by state and only return the first 50.
+#### Filter logs by state and limit results
 
 <Info>
 More filters can be found in the [API Reference](/qstash/api-reference/logs/list-logs).
@@ -33,10 +33,21 @@ More filters can be found in the [API Reference](/qstash/api-reference/logs/list
 import { Client } from "@upstash/qstash";
 
 const client = new Client({ token: "<QSTASH_TOKEN>" });
-const res = await client.logs({ 
+const res = await client.logs({
+  count: 50,
   filter: {
     state: "DELIVERED",
-    count: 50
   }
 });
+```
+
+#### Fetch logs by message IDs
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+const res = await client.logs({
+  messageIds: ["msg-id-1", "msg-id-2"]
+});
 ```

qstash/sdks/ts/examples/messages.mdx

@@ -16,32 +16,55 @@ const messages = client.messages
 const msg = await messages.get("msgId");
 ```
 
-#### Cancel/delete a message
+#### Cancel a message
 
 ```typescript
 import { Client } from "@upstash/qstash";
 
 const client = new Client({ token: "<QSTASH_TOKEN>" });
-const messages = client.messages
-const msg = await messages.delete("msgId");
+await client.messages.cancel("msgId");
 ```
 
-#### Cancel messages in bulk
-
-Cancel many messages at once or cancel all messages
+#### Cancel multiple messages
 
 ```typescript
 import { Client } from "@upstash/qstash";
 
 const client = new Client({ token: "<QSTASH_TOKEN>" });
 
-// deleting two messages at once
-await client.messages.deleteMany([
-  "message-id-1",
-  "message-id-2",
-])
+// cancel two messages at once
+await client.messages.cancel(["message-id-1", "message-id-2"])
+
+// cancel all messages
+let cancelled: number;
+do {
+  const result = await client.messages.cancel({ all: true });
+  cancelled = result.cancelled;
+} while (cancelled > 0);
+```
 
+#### Cancel messages with filters
+
+```typescript
+import { Client } from "@upstash/qstash";
+
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+
+// cancel messages matching a URL and label
+let cancelled: number;
+do {
+  const result = await client.messages.cancel({
+    filter: {
+      url: "https://example.com",
+      label: "my-label",
+    }
+  });
+  cancelled = result.cancelled;
+} while (cancelled > 0);
 
-// deleting all messages
-await client.messages.deleteAll()
 ```
+
+<Note>
+  `client.messages.delete()`, `client.messages.deleteMany()`, and `client.messages.deleteAll()`
+  are deprecated. Use `client.messages.cancel()` instead.
+</Note>

workflow/basics/client.mdx

@@ -35,4 +35,5 @@ The client exposes a set of functions to manage workflow runs and inspect their
     - [client.dlq.list](/workflow/basics/client/dlq/list)
     - [client.dlq.restart](/workflow/basics/client/dlq/restart)
     - [client.dlq.resume](/workflow/basics/client/dlq/resume)
+    - [client.dlq.delete](/workflow/basics/client/dlq/delete)
     - [client.dlq.retryFailureFunction](/workflow/basics/client/dlq/callback)

workflow/basics/client/cancel.mdx

@@ -2,55 +2,135 @@
 title: "client.cancel"
 ---
 
-There are multiple ways you can cancel workflow runs:
-
-- 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 one or more workflow runs. You can pass IDs directly, use filters, or cancel all at once.
 
 ## Arguments
 
-<ParamField body="ids" type="array">
-    The set of workflow run IDs you want to cancel
+The `cancel` method accepts one of the following:
+
+### By ID
+
+Pass a single workflow run ID or an array of IDs directly:
+
+```ts
+await client.cancel("<WORKFLOW_RUN_ID>");
+await client.cancel(["<ID_1>", "<ID_2>"]);
+```
+
+### By filters
+
+Pass an object with a `filter` field containing one or more filter criteria:
+
+<ParamField body="filter" type="object">
+    <Expandable defaultOpen>
+        <ParamField body="workflowUrl" type="string" optional>
+            Cancel workflows matching this exact URL. Cannot be combined with `workflowUrlStartingWith`.
+        </ParamField>
+
+        <ParamField body="workflowUrlStartingWith" type="string" optional>
+            Cancel workflows whose URL starts with this prefix. Cannot be combined with `workflowUrl`.
+        </ParamField>
+
+        <ParamField body="label" type="string" optional>
+            Cancel workflows with this label.
+        </ParamField>
+
+        <ParamField body="fromDate" type="Date | number" optional>
+            Cancel workflows created after this date. Accepts `Date` objects or Unix timestamps (ms).
+        </ParamField>
+
+        <ParamField body="toDate" type="Date | number" optional>
+            Cancel workflows created before this date. Accepts `Date` objects or Unix timestamps (ms).
+        </ParamField>
+
+        <ParamField body="callerIp" type="string" optional>
+            Cancel workflows triggered by this IP address.
+        </ParamField>
+
+        <ParamField body="flowControlKey" type="string" optional>
+            Cancel workflows with this flow control key.
+        </ParamField>
+    </Expandable>
 </ParamField>
 
-<ParamField body="urlStartingWith" type="string">
-    The URL address you want to filter while canceling
+<ParamField body="count" type="number" optional>
+    Maximum number of workflow runs to cancel per call. Defaults to `100`.
 </ParamField>
 
-<ParamField body="all" type="bool">
-    Whether you want to cancel all workflow runs without any filter.
+### Cancel all
+
+<ParamField body="all" type="boolean">
+    Set to `true` to cancel all pending and active workflow runs.
 </ParamField>
 
+## Response
+
+<ResponseField name="cancelled" type="number">
+    The number of workflow runs that were cancelled.
+</ResponseField>
+
 ## Usage
 
-### Cancel a set of workflow runs
+### Cancel by ID
 
 ```ts
 // cancel a single workflow
-await client.cancel({ ids: "<WORKFLOW_RUN_ID>" });
+await client.cancel("<WORKFLOW_RUN_ID>");
 
 // cancel a set of workflow runs
-await client.cancel({ ids: ["<WORKFLOW_RUN_ID_1>", "<WORKFLOW_RUN_ID_2>"] });
+await client.cancel(["<WORKFLOW_RUN_ID_1>", "<WORKFLOW_RUN_ID_2>"]);
 ```
 
-### Cancel workflow runs with URL filter
+### Cancel with URL filter
 
-If you have an endpoint called `https://your-endpoint.com` and you
-want to cancel all workflow runs on it, you can use `urlStartingWith`.
+Cancel all workflow runs on a specific endpoint using a URL prefix:
+
+```ts
+await client.cancel({
+  filter: { workflowUrlStartingWith: "https://your-endpoint.com" }
+});
+```
 
-Note that this will cancel workflows in all endpoints under
-`https://your-endpoint.com`.
+For an exact URL match:
 
 ```ts
-await client.cancel({ urlStartingWith: "https://your-endpoint.com" });
+await client.cancel({
+  filter: { workflowUrl: "https://your-endpoint.com/api/workflow" }
+});
 ```
 
-### Cancel _all_ workflows
+### Cancel with filters
+
+You can combine multiple filter parameters:
+
+```ts
+// cancel by label
+await client.cancel({ filter: { label: "my-label" } });
+
+// cancel by label and date range
+await client.cancel({
+  filter: {
+    label: "my-label",
+    fromDate: 1640995200000,
+  }
+});
+
+// cancel by URL and date range
+await client.cancel({
+  filter: {
+    workflowUrl: "https://your-endpoint.com/api/workflow",
+    fromDate: new Date("2024-01-01"),
+    toDate: new Date("2024-06-01"),
+  }
+});
+```
 
-To cancel all pending and currently running workflows, you can
-do it like this:
+### Cancel _all_ workflows
 
 ```ts
-await client.cancel({ all: true });
+let cancelled: number;
+do {
+  const result = await client.cancel({ all: true });
+  cancelled = result.cancelled;
+} while (cancelled > 0);
 ```