@upstash/qstash 2.9.1-rc.1 → 2.10.0

package/index.js

@@ -32,11 +32,13 @@ var src_exports = {};
 __export(src_exports, {
   Chat: () => Chat,
   Client: () => Client,
+  FlowControlApi: () => FlowControlApi,
   Messages: () => Messages,
   QStashWorkflowAbort: () => QStashWorkflowAbort,
   QStashWorkflowError: () => QStashWorkflowError,
   QstashChatRatelimitError: () => QstashChatRatelimitError,
   QstashDailyRatelimitError: () => QstashDailyRatelimitError,
+  QstashEmptyArrayError: () => QstashEmptyArrayError,
   QstashError: () => QstashError,
   QstashRatelimitError: () => QstashRatelimitError,
   Receiver: () => Receiver,
@@ -274,6 +276,14 @@ var QstashDailyRatelimitError = class extends QstashError {
     this.reset = args.reset;
   }
 };
+var QstashEmptyArrayError = class extends QstashError {
+  constructor(parameterName) {
+    super(
+      `Empty array provided for query parameter "${parameterName}". This would result in no filter being applied, which could affect all resources.`
+    );
+    this.name = "QstashEmptyArrayError";
+  }
+};
 var QStashWorkflowError = class extends QstashError {
   constructor(message) {
     super(message);
@@ -303,6 +313,7 @@ var formatWorkflowError = (error) => {
 };
 
 // src/client/utils.ts
+var DEFAULT_BULK_COUNT = 100;
 var isIgnoredHeader = (header) => {
   const lowerCaseHeader = header.toLowerCase();
   return lowerCaseHeader.startsWith("content-type") || lowerCaseHeader.startsWith("upstash-");
@@ -389,6 +400,24 @@ function processHeaders(request) {
   if (request.label !== void 0) {
     headers.set("Upstash-Label", request.label);
   }
+  if (request.redact !== void 0) {
+    const redactParts = [];
+    if (request.redact.body) {
+      redactParts.push("body");
+    }
+    if (request.redact.header !== void 0) {
+      if (request.redact.header === true) {
+        redactParts.push("header");
+      } else if (Array.isArray(request.redact.header) && request.redact.header.length > 0) {
+        for (const headerName of request.redact.header) {
+          redactParts.push(`header[${headerName}]`);
+        }
+      }
+    }
+    if (redactParts.length > 0) {
+      headers.set("Upstash-Redact-Fields", redactParts.join(","));
+    }
+  }
   return headers;
 }
 function getRequestPath(request) {
@@ -423,38 +452,39 @@ function decodeBase64(base64) {
     }
   }
 }
-function buildBulkActionFilterPayload(request, options) {
-  const hasDlqIds = "dlqIds" in request && request.dlqIds !== void 0;
-  const hasAll = "all" in request && Boolean(request.all);
-  const filterKeys = Object.keys(request).filter((k) => k !== "dlqIds" && k !== "all");
-  const hasFilters = filterKeys.length > 0;
-  if (hasDlqIds && hasAll) {
-    throw new QstashError("dlqIds and all: true are mutually exclusive.");
-  }
-  if (hasDlqIds && hasFilters) {
-    throw new QstashError(
-      `dlqIds cannot be combined with filter fields: ${filterKeys.join(", ")}.`
-    );
+function buildBulkActionFilterPayload(request) {
+  const cursor = "cursor" in request ? request.cursor : void 0;
+  if ("all" in request) {
+    const count2 = "count" in request ? request.count ?? DEFAULT_BULK_COUNT : DEFAULT_BULK_COUNT;
+    return { count: count2, cursor };
+  }
+  if ("dlqIds" in request) {
+    const ids = request.dlqIds;
+    if (Array.isArray(ids) && ids.length === 0) {
+      throw new QstashError(
+        "Empty dlqIds array provided. If you intend to target all DLQ messages, use { all: true } explicitly."
+      );
+    }
+    return { dlqIds: ids, cursor };
   }
-  if (hasAll && hasFilters) {
-    throw new QstashError(
-      `all: true cannot be combined with filter fields: ${filterKeys.join(", ")}.`
-    );
+  if ("messageIds" in request && request.messageIds) {
+    if (request.messageIds.length === 0) {
+      throw new QstashError(
+        "Empty messageIds array provided. If you intend to target all messages, use { all: true } explicitly."
+      );
+    }
+    return { messageIds: request.messageIds, cursor };
   }
-  if (hasAll)
-    return {};
-  const { urlGroup, callerIp, ...rest } = request;
-  const payload = {
-    ...rest,
-    ...urlGroup === void 0 || typeof urlGroup !== "string" ? {} : { topicName: urlGroup },
-    ...callerIp === void 0 || typeof callerIp !== "string" ? {} : options?.callerIpCasing ? { callerIP: callerIp } : { callerIp }
+  const count = "count" in request ? request.count ?? DEFAULT_BULK_COUNT : DEFAULT_BULK_COUNT;
+  return {
+    ...renameUrlGroup(request.filter),
+    count,
+    cursor
   };
-  if (Object.keys(payload).length === 0) {
-    throw new QstashError(
-      "No filters provided. Pass { all: true } to explicitly target all messages."
-    );
-  }
-  return payload;
+}
+function renameUrlGroup(filter) {
+  const { urlGroup, api, ...rest } = filter;
+  return { ...rest, ...urlGroup === void 0 ? {} : { topicName: urlGroup } };
 }
 function normalizeCursor(response) {
   const cursor = response.cursor;
@@ -688,23 +718,21 @@ var DLQ = class {
   }
   /**
    * List messages in the dlq
+   *
+   * Can be called with:
+   * - Filters: `listMessages({ filter: { url: "https://example.com" } })`
+   * - DLQ IDs: `listMessages({ dlqIds: ["id1", "id2"] })`
+   * - No filter (list all): `listMessages()`
    */
   async listMessages(options = {}) {
-    const { urlGroup, ...restFilter } = options.filter ?? {};
-    const filterPayload = {
-      ...restFilter,
-      ...urlGroup === void 0 ? {} : { topicName: urlGroup }
+    const query = {
+      count: options.count,
+      ..."dlqIds" in options ? { dlqIds: options.dlqIds } : { ...renameUrlGroup(options.filter ?? {}), cursor: options.cursor }
     };
     const messagesPayload = await this.http.request({
       method: "GET",
       path: ["v2", "dlq"],
-      query: {
-        cursor: options.cursor,
-        count: options.count,
-        order: options.order,
-        trimBody: options.trimBody,
-        ...filterPayload
-      }
+      query
     });
     return {
       messages: messagesPayload.messages.map((message) => {
@@ -724,10 +752,19 @@ var DLQ = class {
    * - A single dlqId: `delete("id")`
    * - An array of dlqIds: `delete(["id1", "id2"])`
    * - An object with dlqIds: `delete({ dlqIds: ["id1", "id2"] })`
-   * - A filter object: `delete({ url: "https://example.com", label: "label" })`
+   * - A filter object: `delete({ filter: { url: "https://example.com", label: "label" } })`
    * - All messages: `delete({ all: true })`
    *
-   * Note: passing an empty array returns `{ deleted: 0 }` without making a request.
+   * Pass `count` to limit the number of messages processed per call (defaults to 100).
+   * Call in a loop until cursor is undefined:
+   *
+   * ```ts
+   * let cursor: string | undefined;
+   * do {
+   *   const result = await dlq.delete({ all: true, count: 100, cursor });
+   *   cursor = result.cursor;
+   * } while (cursor);
+   * ```
    */
   async delete(request) {
     if (typeof request === "string") {
@@ -741,13 +778,11 @@ var DLQ = class {
     if (Array.isArray(request) && request.length === 0)
       return { deleted: 0 };
     const filters = Array.isArray(request) ? { dlqIds: request } : request;
-    return normalizeCursor(
-      await this.http.request({
-        method: "DELETE",
-        path: ["v2", "dlq"],
-        query: buildBulkActionFilterPayload(filters)
-      })
-    );
+    return await this.http.request({
+      method: "DELETE",
+      path: ["v2", "dlq"],
+      query: buildBulkActionFilterPayload(filters)
+    });
   }
   /**
    * Remove multiple messages from the dlq using their `dlqId`s
@@ -764,10 +799,19 @@ var DLQ = class {
    * - A single dlqId: `retry("id")`
    * - An array of dlqIds: `retry(["id1", "id2"])`
    * - An object with dlqIds: `retry({ dlqIds: ["id1", "id2"] })`
-   * - A filter object: `retry({ url: "https://example.com", label: "label" })`
+   * - A filter object: `retry({ filter: { url: "https://example.com", label: "label" } })`
    * - All messages: `retry({ all: true })`
    *
-   * Note: passing an empty array returns `{ responses: [] }` without making a request.
+   * Pass `count` to limit the number of messages processed per call (defaults to 100).
+   * Call in a loop until cursor is undefined:
+   *
+   * ```ts
+   * let cursor: string | undefined;
+   * do {
+   *   const result = await dlq.retry({ all: true, count: 100, cursor });
+   *   cursor = result.cursor;
+   * } while (cursor);
+   * ```
    */
   async retry(request) {
     if (typeof request === "string")
@@ -785,6 +829,107 @@ var DLQ = class {
   }
 };
 
+// src/client/flow-control.ts
+var FlowControlApi = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get a single flow control by key.
+   */
+  async get(flowControlKey) {
+    return await this.http.request({
+      method: "GET",
+      path: ["v2", "flowControl", flowControlKey]
+    });
+  }
+  /**
+   * Get the global parallelism info.
+   */
+  async getGlobalParallelism() {
+    const response = await this.http.request({
+      method: "GET",
+      path: ["v2", "globalParallelism"]
+    });
+    return {
+      parallelismMax: response.parallelismMax ?? 0,
+      parallelismCount: response.parallelismCount ?? 0
+    };
+  }
+  /**
+   * Pause message delivery for a flow-control key.
+   *
+   * Messages already in the waitlist will remain there.
+   * New incoming messages will be added directly to the waitlist.
+   */
+  async pause(flowControlKey) {
+    await this.http.request({
+      method: "POST",
+      path: ["v2", "flowControl", flowControlKey, "pause"],
+      parseResponseAsJson: false
+    });
+  }
+  /**
+   * Resume message delivery for a flow-control key.
+   */
+  async resume(flowControlKey) {
+    await this.http.request({
+      method: "POST",
+      path: ["v2", "flowControl", flowControlKey, "resume"],
+      parseResponseAsJson: false
+    });
+  }
+  /**
+   * Pin a processing configuration for a flow-control key.
+   *
+   * While pinned, the system ignores configurations provided by incoming
+   * messages and uses the pinned configuration instead.
+   */
+  async pin(flowControlKey, options) {
+    await this.http.request({
+      method: "POST",
+      path: ["v2", "flowControl", flowControlKey, "pin"],
+      query: {
+        parallelism: options.parallelism,
+        rate: options.rate,
+        period: options.period
+      },
+      parseResponseAsJson: false
+    });
+  }
+  /**
+   * Remove the pinned configuration for a flow-control key.
+   *
+   * After unpinning, the system resumes updating the configuration
+   * based on incoming messages.
+   */
+  async unpin(flowControlKey, options) {
+    await this.http.request({
+      method: "POST",
+      path: ["v2", "flowControl", flowControlKey, "unpin"],
+      query: {
+        parallelism: options.parallelism,
+        rate: options.rate
+      },
+      parseResponseAsJson: false
+    });
+  }
+  /**
+   * Reset the rate configuration state for a flow-control key.
+   *
+   * Clears the current rate count and immediately ends the current period.
+   * The current timestamp becomes the start of the new rate period.
+   */
+  async resetRate(flowControlKey) {
+    await this.http.request({
+      method: "POST",
+      path: ["v2", "flowControl", flowControlKey, "resetRate"],
+      parseResponseAsJson: false
+    });
+  }
+};
+
 // src/client/http.ts
 var HttpClient = class {
   baseUrl;
@@ -885,6 +1030,9 @@ var HttpClient = class {
         if (value === void 0)
           continue;
         if (Array.isArray(value)) {
+          if (value.length === 0) {
+            throw new QstashEmptyArrayError(key);
+          }
           for (const item of value) {
             url.searchParams.append(key, item);
           }
@@ -1126,8 +1274,19 @@ var Messages = class {
    * Can be called with:
    * - A single messageId: `cancel("id")`
    * - An array of messageIds: `cancel(["id1", "id2"])`
-   * - A filter object: `cancel({ flowControlKey: "key", label: "label" })`
+   * - A filter object: `cancel({ filter: { flowControlKey: "key", label: "label" } })`
    * - All messages: `cancel({ all: true })`
+   *
+   * Pass `count` to limit the number of messages processed per call (defaults to 100).
+   * Call in a loop until `cancelled` is 0:
+   *
+   * ```ts
+   * let cancelled: number;
+   * do {
+   *   const result = await messages.cancel({ all: true, count: 100 });
+   *   cancelled = result.cancelled;
+   * } while (cancelled > 0);
+   * ```
    */
   async cancel(request) {
     if (typeof request === "string") {
@@ -1142,7 +1301,7 @@ var Messages = class {
     return await this.http.request({
       method: "DELETE",
       path: ["v2", "messages"],
-      query: buildBulkActionFilterPayload(filters, { callerIpCasing: true })
+      query: buildBulkActionFilterPayload(filters)
     });
   }
   /**
@@ -1376,6 +1535,24 @@ var Schedules = class {
     if (request.label !== void 0) {
       headers.set("Upstash-Label", request.label);
     }
+    if (request.redact !== void 0) {
+      const redactParts = [];
+      if (request.redact.body) {
+        redactParts.push("body");
+      }
+      if (request.redact.header !== void 0) {
+        if (request.redact.header === true) {
+          redactParts.push("header");
+        } else if (Array.isArray(request.redact.header) && request.redact.header.length > 0) {
+          for (const headerName of request.redact.header) {
+            redactParts.push(`header[${headerName}]`);
+          }
+        }
+      }
+      if (redactParts.length > 0) {
+        headers.set("Upstash-Redact-Fields", redactParts.join(","));
+      }
+    }
     return await this.http.request({
       method: "POST",
       headers: wrapWithGlobalHeaders(headers, this.http.headers, this.http.telemetryHeaders),
@@ -1536,7 +1713,7 @@ var Workflow = class {
 };
 
 // version.ts
-var VERSION = "v2.9.1-rc.1";
+var VERSION = "2.10.0";
 
 // src/client/client.ts
 var Client = class {
@@ -1607,6 +1784,14 @@ var Client = class {
   get schedules() {
     return new Schedules(this.http);
   }
+  /**
+   * Access the flow control API.
+   *
+   * List, get, or reset flow controls.
+   */
+  get flowControl() {
+    return new FlowControlApi(this.http);
+  }
   /**
    * Access the workflow API.
    *
@@ -1732,38 +1917,9 @@ var Client = class {
    * ```
    */
   async logs(request = {}) {
-    const {
-      urlGroup,
-      // eslint-disable-next-line @typescript-eslint/no-deprecated
-      topicName,
-      fromDate,
-      toDate,
-      callerIp,
-      messageIds,
-      // eslint-disable-next-line @typescript-eslint/no-deprecated
-      count: filterCount,
-      ...restFilter
-    } = request.filter ?? {};
-    const filterPayload = {
-      ...restFilter,
-      topicName: urlGroup ?? topicName,
-      fromDate,
-      toDate,
-      callerIp
-    };
-    let cursorString;
-    if (typeof request.cursor === "number" && request.cursor > 0) {
-      cursorString = request.cursor.toString();
-    } else if (typeof request.cursor === "string" && request.cursor !== "") {
-      cursorString = request.cursor;
-    }
     const query = {
-      cursor: cursorString,
-      count: request.count ?? filterCount,
-      order: request.order,
-      trimBody: request.trimBody,
-      messageIds,
-      ...filterPayload
+      count: request.count,
+      ..."messageIds" in request ? { messageIds: request.messageIds } : { ...renameUrlGroup(request.filter ?? {}), cursor: request.cursor }
     };
     const responsePayload = await this.http.request({
       path: ["v2", "events"],
@@ -1830,11 +1986,13 @@ var resend = ({
 0 && (module.exports = {
   Chat,
   Client,
+  FlowControlApi,
   Messages,
   QStashWorkflowAbort,
   QStashWorkflowError,
   QstashChatRatelimitError,
   QstashDailyRatelimitError,
+  QstashEmptyArrayError,
   QstashError,
   QstashRatelimitError,
   Receiver,

package/index.mjs

@@ -1,14 +1,16 @@
 import {
   resend
-} from "./chunk-SN6OPGRS.mjs";
+} from "./chunk-FAMFGAMR.mjs";
 import {
   Chat,
   Client,
+  FlowControlApi,
   Messages,
   QStashWorkflowAbort,
   QStashWorkflowError,
   QstashChatRatelimitError,
   QstashDailyRatelimitError,
+  QstashEmptyArrayError,
   QstashError,
   QstashRatelimitError,
   Receiver,
@@ -22,15 +24,17 @@ import {
   openai,
   setupAnalytics,
   upstash
-} from "./chunk-RUCOF5QZ.mjs";
+} from "./chunk-X3MMU3BQ.mjs";
 export {
   Chat,
   Client,
+  FlowControlApi,
   Messages,
   QStashWorkflowAbort,
   QStashWorkflowError,
   QstashChatRatelimitError,
   QstashDailyRatelimitError,
+  QstashEmptyArrayError,
   QstashError,
   QstashRatelimitError,
   Receiver,

package/nextjs.d.mts

@@ -1,6 +1,6 @@
 import { NextApiHandler } from 'next';
 import { NextRequest, NextFetchEvent } from 'next/server';
-import { aa as RouteFunction, ab as WorkflowServeOptions } from './client-Gv4WRTxB.mjs';
+import { ae as RouteFunction, af as WorkflowServeOptions } from './client-CsM1dTnz.mjs';
 import 'neverthrow';
 
 type VerifySignatureConfig = {

package/nextjs.d.ts

@@ -1,6 +1,6 @@
 import { NextApiHandler } from 'next';
 import { NextRequest, NextFetchEvent } from 'next/server';
-import { aa as RouteFunction, ab as WorkflowServeOptions } from './client-Gv4WRTxB.js';
+import { ae as RouteFunction, af as WorkflowServeOptions } from './client-CsM1dTnz.js';
 import 'neverthrow';
 
 type VerifySignatureConfig = {