@vercel/queue 0.0.0-alpha.32 → 0.0.0-alpha.34

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,10 +32,16 @@ var index_exports = {};
 __export(index_exports, {
   BadRequestError: () => BadRequestError,
   BufferTransport: () => BufferTransport,
+  Client: () => Client,
+  ConcurrencyLimitError: () => ConcurrencyLimitError,
+  ConsumerDiscoveryError: () => ConsumerDiscoveryError,
+  ConsumerRegistryNotConfiguredError: () => ConsumerRegistryNotConfiguredError,
+  DuplicateMessageError: () => DuplicateMessageError,
   ForbiddenError: () => ForbiddenError,
   InternalServerError: () => InternalServerError,
   InvalidLimitError: () => InvalidLimitError,
   JsonTransport: () => JsonTransport,
+  MessageAlreadyProcessedError: () => MessageAlreadyProcessedError,
   MessageCorruptedError: () => MessageCorruptedError,
   MessageLockedError: () => MessageLockedError,
   MessageNotAvailableError: () => MessageNotAvailableError,
@@ -106,8 +122,9 @@ var StreamTransport = class {
 // src/client.ts
 var import_mixpart = require("mixpart");
 
-// src/oidc.ts
-var import_oidc = require("@vercel/oidc");
+// src/dev.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
 
 // src/types.ts
 var MessageNotFoundError = class extends Error {
@@ -177,8 +194,268 @@ var InvalidLimitError = class extends Error {
     this.name = "InvalidLimitError";
   }
 };
+var MessageAlreadyProcessedError = class extends Error {
+  constructor(messageId) {
+    super(`Message ${messageId} has already been processed`);
+    this.name = "MessageAlreadyProcessedError";
+  }
+};
+var ConcurrencyLimitError = class extends Error {
+  currentInflight;
+  maxConcurrency;
+  constructor(message = "Concurrency limit exceeded", currentInflight, maxConcurrency) {
+    super(message);
+    this.name = "ConcurrencyLimitError";
+    this.currentInflight = currentInflight;
+    this.maxConcurrency = maxConcurrency;
+  }
+};
+var DuplicateMessageError = class extends Error {
+  idempotencyKey;
+  constructor(message, idempotencyKey) {
+    super(message);
+    this.name = "DuplicateMessageError";
+    this.idempotencyKey = idempotencyKey;
+  }
+};
+var ConsumerDiscoveryError = class extends Error {
+  deploymentId;
+  constructor(message, deploymentId) {
+    super(message);
+    this.name = "ConsumerDiscoveryError";
+    this.deploymentId = deploymentId;
+  }
+};
+var ConsumerRegistryNotConfiguredError = class extends Error {
+  constructor(message = "Consumer registry not configured") {
+    super(message);
+    this.name = "ConsumerRegistryNotConfiguredError";
+  }
+};
+
+// src/dev.ts
+var ROUTE_MAPPINGS_KEY = Symbol.for("@vercel/queue.devRouteMappings");
+function filePathToUrlPath(filePath) {
+  let urlPath = filePath.replace(/^app\//, "/").replace(/^pages\//, "/").replace(/\/route\.(ts|js|tsx|jsx)$/, "").replace(/\.(ts|js|tsx|jsx)$/, "");
+  if (!urlPath.startsWith("/")) {
+    urlPath = "/" + urlPath;
+  }
+  return urlPath;
+}
+function getDevRouteMappings() {
+  const g = globalThis;
+  if (ROUTE_MAPPINGS_KEY in g) {
+    return g[ROUTE_MAPPINGS_KEY] ?? null;
+  }
+  try {
+    const vercelJsonPath = path.join(process.cwd(), "vercel.json");
+    if (!fs.existsSync(vercelJsonPath)) {
+      g[ROUTE_MAPPINGS_KEY] = null;
+      return null;
+    }
+    const vercelJson = JSON.parse(fs.readFileSync(vercelJsonPath, "utf-8"));
+    if (!vercelJson.functions) {
+      g[ROUTE_MAPPINGS_KEY] = null;
+      return null;
+    }
+    const mappings = [];
+    for (const [filePath, config] of Object.entries(vercelJson.functions)) {
+      if (!config.experimentalTriggers) continue;
+      for (const trigger of config.experimentalTriggers) {
+        if (trigger.type?.startsWith("queue/") && trigger.topic && trigger.consumer) {
+          mappings.push({
+            urlPath: filePathToUrlPath(filePath),
+            topic: trigger.topic,
+            consumer: trigger.consumer
+          });
+        }
+      }
+    }
+    g[ROUTE_MAPPINGS_KEY] = mappings.length > 0 ? mappings : null;
+    return g[ROUTE_MAPPINGS_KEY];
+  } catch (error) {
+    console.warn("[Dev Mode] Failed to read vercel.json:", error);
+    g[ROUTE_MAPPINGS_KEY] = null;
+    return null;
+  }
+}
+function findMatchingRoutes(topicName) {
+  const mappings = getDevRouteMappings();
+  if (!mappings) {
+    return [];
+  }
+  return mappings.filter((mapping) => {
+    if (mapping.topic.includes("*")) {
+      return matchesWildcardPattern(topicName, mapping.topic);
+    }
+    return mapping.topic === topicName;
+  });
+}
+function isDevMode() {
+  return process.env.NODE_ENV === "development";
+}
+var DEV_VISIBILITY_POLL_INTERVAL = 50;
+var DEV_VISIBILITY_MAX_WAIT = 5e3;
+var DEV_VISIBILITY_BACKOFF_MULTIPLIER = 2;
+async function waitForMessageVisibility(topicName, consumerGroup, messageId) {
+  const client = new QueueClient();
+  const transport = new JsonTransport();
+  let elapsed = 0;
+  let interval = DEV_VISIBILITY_POLL_INTERVAL;
+  while (elapsed < DEV_VISIBILITY_MAX_WAIT) {
+    try {
+      await client.receiveMessageById(
+        {
+          queueName: topicName,
+          consumerGroup,
+          messageId,
+          visibilityTimeoutSeconds: 0
+        },
+        transport
+      );
+      return true;
+    } catch (error) {
+      if (error instanceof MessageNotFoundError) {
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        elapsed += interval;
+        interval = Math.min(
+          interval * DEV_VISIBILITY_BACKOFF_MULTIPLIER,
+          DEV_VISIBILITY_MAX_WAIT - elapsed
+        );
+        continue;
+      }
+      if (error instanceof MessageAlreadyProcessedError) {
+        console.log(
+          `[Dev Mode] Message already processed: topic="${topicName}" messageId="${messageId}"`
+        );
+        return false;
+      }
+      console.error(
+        `[Dev Mode] Error polling for message visibility: topic="${topicName}" messageId="${messageId}"`,
+        error
+      );
+      return false;
+    }
+  }
+  console.warn(
+    `[Dev Mode] Message visibility timeout after ${DEV_VISIBILITY_MAX_WAIT}ms: topic="${topicName}" messageId="${messageId}"`
+  );
+  return false;
+}
+function triggerDevCallbacks(topicName, messageId, delaySeconds) {
+  if (delaySeconds && delaySeconds > 0) {
+    console.log(
+      `[Dev Mode] Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
+    );
+    setTimeout(() => {
+      triggerDevCallbacks(topicName, messageId);
+    }, delaySeconds * 1e3);
+    return;
+  }
+  console.log(
+    `[Dev Mode] Message sent: topic="${topicName}" messageId="${messageId}"`
+  );
+  const matchingRoutes = findMatchingRoutes(topicName);
+  if (matchingRoutes.length === 0) {
+    console.log(
+      `[Dev Mode] No matching routes in vercel.json for topic "${topicName}"`
+    );
+    return;
+  }
+  const consumerGroups = matchingRoutes.map((r) => r.consumer);
+  console.log(
+    `[Dev Mode] Scheduling callbacks for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
+  );
+  (async () => {
+    const firstRoute = matchingRoutes[0];
+    const isVisible = await waitForMessageVisibility(
+      topicName,
+      firstRoute.consumer,
+      messageId
+    );
+    if (!isVisible) {
+      console.warn(
+        `[Dev Mode] Skipping callbacks - message not visible: topic="${topicName}" messageId="${messageId}"`
+      );
+      return;
+    }
+    const port = process.env.PORT || 3e3;
+    const baseUrl = `http://localhost:${port}`;
+    for (const route of matchingRoutes) {
+      const url = `${baseUrl}${route.urlPath}`;
+      console.log(
+        `[Dev Mode] Invoking handler: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`
+      );
+      const cloudEvent = {
+        type: "com.vercel.queue.v1beta",
+        source: `/topic/${topicName}/consumer/${route.consumer}`,
+        id: messageId,
+        datacontenttype: "application/json",
+        data: {
+          messageId,
+          queueName: topicName,
+          consumerGroup: route.consumer
+        },
+        time: (/* @__PURE__ */ new Date()).toISOString(),
+        specversion: "1.0"
+      };
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/cloudevents+json"
+          },
+          body: JSON.stringify(cloudEvent)
+        });
+        if (response.ok) {
+          try {
+            const responseData = await response.json();
+            if (responseData.status === "success") {
+              console.log(
+                `[Dev Mode] \u2713 Message processed successfully: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}"`
+              );
+            }
+          } catch {
+            console.warn(
+              `[Dev Mode] Handler returned OK but response was not JSON: topic="${topicName}" consumer="${route.consumer}"`
+            );
+          }
+        } else {
+          try {
+            const errorData = await response.json();
+            console.error(
+              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" error="${errorData.error || response.statusText}"`
+            );
+          } catch {
+            console.error(
+              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" status=${response.status}`
+            );
+          }
+        }
+      } catch (error) {
+        console.error(
+          `[Dev Mode] \u2717 HTTP request failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`,
+          error
+        );
+      }
+    }
+  })();
+}
+function clearDevRouteMappings() {
+  const g = globalThis;
+  delete g[ROUTE_MAPPINGS_KEY];
+}
+if (process.env.NODE_ENV === "test" || process.env.VITEST) {
+  globalThis.__clearDevRouteMappings = clearDevRouteMappings;
+}
+
+// src/oidc.ts
+var import_oidc = require("@vercel/oidc");
 
 // src/client.ts
+function isDebugEnabled() {
+  return process.env.VERCEL_QUEUE_DEBUG === "1" || process.env.VERCEL_QUEUE_DEBUG === "true";
+}
 async function consumeStream(stream) {
   const reader = stream.getReader();
   try {
@@ -190,17 +467,34 @@ async function consumeStream(stream) {
     reader.releaseLock();
   }
 }
+function throwCommonHttpError(status, statusText, errorText, operation, badRequestDefault = "Invalid parameters") {
+  if (status === 400) {
+    throw new BadRequestError(errorText || badRequestDefault);
+  }
+  if (status === 401) {
+    throw new UnauthorizedError(errorText || void 0);
+  }
+  if (status === 403) {
+    throw new ForbiddenError(errorText || void 0);
+  }
+  if (status >= 500) {
+    throw new InternalServerError(
+      errorText || `Server error: ${status} ${statusText}`
+    );
+  }
+  throw new Error(`Failed to ${operation}: ${status} ${statusText}`);
+}
 function parseQueueHeaders(headers) {
   const messageId = headers.get("Vqs-Message-Id");
   const deliveryCountStr = headers.get("Vqs-Delivery-Count") || "0";
   const timestamp = headers.get("Vqs-Timestamp");
   const contentType = headers.get("Content-Type") || "application/octet-stream";
-  const ticket = headers.get("Vqs-Ticket");
-  if (!messageId || !timestamp || !ticket) {
+  const receiptHandle = headers.get("Vqs-Receipt-Handle");
+  if (!messageId || !timestamp || !receiptHandle) {
     return null;
   }
   const deliveryCount = parseInt(deliveryCountStr, 10);
-  if (isNaN(deliveryCount)) {
+  if (Number.isNaN(deliveryCount)) {
     return null;
   }
   return {
@@ -208,30 +502,43 @@ function parseQueueHeaders(headers) {
     deliveryCount,
     createdAt: new Date(timestamp),
     contentType,
-    ticket
+    receiptHandle
   };
 }
 var QueueClient = class {
   baseUrl;
   basePath;
-  customHeaders = {};
-  /**
-   * Create a new Vercel Queue Service client
-   * @param options Client configuration options
-   */
+  customHeaders;
+  providedToken;
+  defaultDeploymentId;
+  pinToDeployment;
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || process.env.VERCEL_QUEUE_BASE_URL || "https://vercel-queue.com";
-    this.basePath = options.basePath || process.env.VERCEL_QUEUE_BASE_PATH || "/api/v2/messages";
-    const VERCEL_QUEUE_HEADER_PREFIX = "VERCEL_QUEUE_HEADER_";
-    this.customHeaders = Object.fromEntries(
-      Object.entries(process.env).filter(([key]) => key.startsWith(VERCEL_QUEUE_HEADER_PREFIX)).map(([key, value]) => [
-        // This allows headers to use dashes independent of shell used
-        key.replace(VERCEL_QUEUE_HEADER_PREFIX, "").replaceAll("__", "-"),
-        value || ""
-      ])
-    );
+    this.basePath = options.basePath || process.env.VERCEL_QUEUE_BASE_PATH || "/api/v3/topic";
+    this.customHeaders = options.headers || {};
+    this.providedToken = options.token;
+    this.defaultDeploymentId = options.deploymentId || process.env.VERCEL_DEPLOYMENT_ID;
+    this.pinToDeployment = options.pinToDeployment ?? true;
+  }
+  getSendDeploymentId() {
+    if (isDevMode()) {
+      return void 0;
+    }
+    if (this.pinToDeployment) {
+      return this.defaultDeploymentId;
+    }
+    return void 0;
+  }
+  getConsumeDeploymentId() {
+    if (isDevMode()) {
+      return void 0;
+    }
+    return this.defaultDeploymentId;
   }
   async getToken() {
+    if (this.providedToken) {
+      return this.providedToken;
+    }
     const token = await (0, import_oidc.getVercelOidcToken)();
     if (!token) {
       throw new Error(
@@ -240,25 +547,61 @@ var QueueClient = class {
     }
     return token;
   }
-  /**
-   * Send a message to a queue
-   * @param options Send message options
-   * @param transport Serializer/deserializer for the payload
-   * @returns Promise with the message ID
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied (environment mismatch)
-   * @throws {InternalServerError} When server encounters an error
-   */
+  buildUrl(queueName, ...pathSegments) {
+    const encodedQueue = encodeURIComponent(queueName);
+    const segments = pathSegments.map((s) => encodeURIComponent(s));
+    const path2 = segments.length > 0 ? "/" + segments.join("/") : "";
+    return `${this.baseUrl}${this.basePath}/${encodedQueue}${path2}`;
+  }
+  async fetch(url, init) {
+    const method = init.method || "GET";
+    if (isDebugEnabled()) {
+      const logData = {
+        method,
+        url,
+        headers: init.headers
+      };
+      const body = init.body;
+      if (body !== void 0 && body !== null) {
+        if (body instanceof ArrayBuffer) {
+          logData.bodySize = body.byteLength;
+        } else if (body instanceof Uint8Array) {
+          logData.bodySize = body.byteLength;
+        } else if (typeof body === "string") {
+          logData.bodySize = body.length;
+        } else {
+          logData.bodyType = typeof body;
+        }
+      }
+      console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
+    }
+    const response = await fetch(url, init);
+    if (isDebugEnabled()) {
+      const logData = {
+        method,
+        url,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+      };
+      console.debug("[VQS Debug] Response:", JSON.stringify(logData, null, 2));
+    }
+    return response;
+  }
   async sendMessage(options, transport) {
-    const { queueName, payload, idempotencyKey, retentionSeconds } = options;
+    const {
+      queueName,
+      payload,
+      idempotencyKey,
+      retentionSeconds,
+      delaySeconds
+    } = options;
     const headers = new Headers({
       Authorization: `Bearer ${await this.getToken()}`,
-      "Vqs-Queue-Name": queueName,
       "Content-Type": transport.contentType,
       ...this.customHeaders
     });
-    const deploymentId = options.deploymentId || process.env.VERCEL_DEPLOYMENT_ID;
+    const deploymentId = this.getSendDeploymentId();
     if (deploymentId) {
       headers.set("Vqs-Deployment-Id", deploymentId);
     }
@@ -268,106 +611,106 @@ var QueueClient = class {
     if (retentionSeconds !== void 0) {
       headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
     }
-    const body = transport.serialize(payload);
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
+    if (delaySeconds !== void 0) {
+      headers.set("Vqs-Delay-Seconds", delaySeconds.toString());
+    }
+    const serialized = transport.serialize(payload);
+    const body = Buffer.isBuffer(serialized) ? new Uint8Array(serialized) : serialized;
+    const response = await this.fetch(this.buildUrl(queueName), {
       method: "POST",
       body,
       headers
     });
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 409) {
-        throw new Error("Duplicate idempotency key detected");
+        throw new DuplicateMessageError(
+          errorText || "Duplicate idempotency key detected",
+          idempotencyKey
+        );
       }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+      if (response.status === 502) {
+        throw new ConsumerDiscoveryError(
+          errorText || "Consumer discovery failed",
+          deploymentId
         );
       }
-      throw new Error(
-        `Failed to send message: ${response.status} ${response.statusText}`
+      if (response.status === 503) {
+        throw new ConsumerRegistryNotConfiguredError(
+          errorText || "Consumer registry not configured"
+        );
+      }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "send message"
       );
     }
     const responseData = await response.json();
     return responseData;
   }
-  /**
-   * Receive messages from a queue
-   * @param options Receive messages options
-   * @param transport Serializer/deserializer for the payload
-   * @returns AsyncGenerator that yields messages as they arrive
-   * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
-   * @throws {QueueEmptyError} When no messages are available (204)
-   * @throws {MessageLockedError} When messages are temporarily locked (423)
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied (environment mismatch)
-   * @throws {InternalServerError} When server encounters an error
-   */
   async *receiveMessages(options, transport) {
-    const { queueName, consumerGroup, visibilityTimeoutSeconds, limit } = options;
+    const {
+      queueName,
+      consumerGroup,
+      visibilityTimeoutSeconds,
+      limit,
+      maxConcurrency
+    } = options;
     if (limit !== void 0 && (limit < 1 || limit > 10)) {
       throw new InvalidLimitError(limit);
     }
     const headers = new Headers({
       Authorization: `Bearer ${await this.getToken()}`,
-      "Vqs-Queue-Name": queueName,
-      "Vqs-Consumer-Group": consumerGroup,
       Accept: "multipart/mixed",
       ...this.customHeaders
     });
     if (visibilityTimeoutSeconds !== void 0) {
       headers.set(
-        "Vqs-Visibility-Timeout",
+        "Vqs-Visibility-Timeout-Seconds",
         visibilityTimeoutSeconds.toString()
       );
     }
     if (limit !== void 0) {
-      headers.set("Vqs-Limit", limit.toString());
+      headers.set("Vqs-Max-Messages", limit.toString());
     }
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
-      method: "GET",
-      headers
-    });
+    if (maxConcurrency !== void 0) {
+      headers.set("Vqs-Max-Concurrency", maxConcurrency.toString());
+    }
+    const effectiveDeploymentId = this.getConsumeDeploymentId();
+    if (effectiveDeploymentId) {
+      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
+    }
+    const response = await this.fetch(
+      this.buildUrl(queueName, "consumer", consumerGroup),
+      {
+        method: "POST",
+        headers
+      }
+    );
     if (response.status === 204) {
       throw new QueueEmptyError(queueName, consumerGroup);
     }
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
-      if (response.status === 423) {
-        const retryAfterHeader = response.headers.get("Retry-After");
-        let retryAfter;
-        if (retryAfterHeader) {
-          const parsed = parseInt(retryAfterHeader, 10);
-          retryAfter = isNaN(parsed) ? void 0 : parsed;
+      const errorText = await response.text();
+      if (response.status === 429) {
+        let errorData = {};
+        try {
+          errorData = JSON.parse(errorText);
+        } catch {
         }
-        throw new MessageLockedError("next message", retryAfter);
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+        throw new ConcurrencyLimitError(
+          errorData.error || "Concurrency limit exceeded or throttled",
+          errorData.currentInflight,
+          errorData.maxConcurrency
         );
       }
-      throw new Error(
-        `Failed to receive messages: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive messages"
       );
     }
     for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
@@ -398,550 +741,250 @@ var QueueClient = class {
       consumerGroup,
       messageId,
       visibilityTimeoutSeconds,
-      skipPayload
+      maxConcurrency
     } = options;
     const headers = new Headers({
       Authorization: `Bearer ${await this.getToken()}`,
-      "Vqs-Queue-Name": queueName,
-      "Vqs-Consumer-Group": consumerGroup,
       Accept: "multipart/mixed",
       ...this.customHeaders
     });
     if (visibilityTimeoutSeconds !== void 0) {
       headers.set(
-        "Vqs-Visibility-Timeout",
+        "Vqs-Visibility-Timeout-Seconds",
         visibilityTimeoutSeconds.toString()
       );
     }
-    if (skipPayload) {
-      headers.set("Vqs-Skip-Payload", "1");
+    if (maxConcurrency !== void 0) {
+      headers.set("Vqs-Max-Concurrency", maxConcurrency.toString());
     }
-    const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+    const effectiveDeploymentId = this.getConsumeDeploymentId();
+    if (effectiveDeploymentId) {
+      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
+    }
+    const response = await this.fetch(
+      this.buildUrl(queueName, "consumer", consumerGroup, "id", messageId),
       {
-        method: "GET",
+        method: "POST",
         headers
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
         throw new MessageNotFoundError(messageId);
       }
-      if (response.status === 423) {
-        const retryAfterHeader = response.headers.get("Retry-After");
-        let retryAfter;
-        if (retryAfterHeader) {
-          const parsed = parseInt(retryAfterHeader, 10);
-          retryAfter = isNaN(parsed) ? void 0 : parsed;
-        }
-        throw new MessageLockedError(messageId, retryAfter);
-      }
       if (response.status === 409) {
+        let errorData = {};
+        try {
+          errorData = JSON.parse(errorText);
+        } catch {
+        }
+        if (errorData.originalMessageId) {
+          throw new MessageNotAvailableError(
+            messageId,
+            `This message was a duplicate - use originalMessageId: ${errorData.originalMessageId}`
+          );
+        }
         throw new MessageNotAvailableError(messageId);
       }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+      if (response.status === 410) {
+        throw new MessageAlreadyProcessedError(messageId);
+      }
+      if (response.status === 429) {
+        let errorData = {};
+        try {
+          errorData = JSON.parse(errorText);
+        } catch {
+        }
+        throw new ConcurrencyLimitError(
+          errorData.error || "Concurrency limit exceeded or throttled",
+          errorData.currentInflight,
+          errorData.maxConcurrency
         );
       }
-      throw new Error(
-        `Failed to receive message by ID: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive message by ID"
       );
     }
-    if (skipPayload && response.status === 204) {
-      const parsedHeaders = parseQueueHeaders(response.headers);
+    for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
+      const parsedHeaders = parseQueueHeaders(multipartMessage.headers);
       if (!parsedHeaders) {
+        await consumeStream(multipartMessage.payload);
         throw new MessageCorruptedError(
           messageId,
-          "Missing required queue headers in 204 response"
+          "Missing required queue headers in response"
         );
       }
+      const deserializedPayload = await transport.deserialize(
+        multipartMessage.payload
+      );
       const message = {
         ...parsedHeaders,
-        payload: void 0
+        payload: deserializedPayload
       };
       return { message };
     }
-    if (!transport) {
-      throw new Error("Transport is required when skipPayload is not true");
-    }
-    try {
-      for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
-        try {
-          const parsedHeaders = parseQueueHeaders(multipartMessage.headers);
-          if (!parsedHeaders) {
-            console.warn("Missing required queue headers in multipart part");
-            await consumeStream(multipartMessage.payload);
-            continue;
-          }
-          const deserializedPayload = await transport.deserialize(
-            multipartMessage.payload
-          );
-          const message = {
-            ...parsedHeaders,
-            payload: deserializedPayload
-          };
-          return { message };
-        } catch (error) {
-          console.warn("Failed to deserialize message by ID:", error);
-          await consumeStream(multipartMessage.payload);
-          throw new MessageCorruptedError(
-            messageId,
-            `Failed to deserialize payload: ${error}`
-          );
-        }
-      }
-    } catch (error) {
-      if (error instanceof MessageCorruptedError) {
-        throw error;
-      }
-      throw new MessageCorruptedError(
-        messageId,
-        `Failed to parse multipart response: ${error}`
-      );
-    }
     throw new MessageNotFoundError(messageId);
   }
-  /**
-   * Delete a message (acknowledge processing)
-   * @param options Delete message options
-   * @returns Promise with delete status
-   * @throws {MessageNotFoundError} When the message doesn't exist (404)
-   * @throws {MessageNotAvailableError} When message can't be deleted (409)
-   * @throws {BadRequestError} When ticket is missing or invalid (400)
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied (environment mismatch)
-   * @throws {InternalServerError} When server encounters an error
-   */
   async deleteMessage(options) {
-    const { queueName, consumerGroup, messageId, ticket } = options;
-    const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+    const { queueName, consumerGroup, receiptHandle } = options;
+    const headers = new Headers({
+      Authorization: `Bearer ${await this.getToken()}`,
+      ...this.customHeaders
+    });
+    const effectiveDeploymentId = this.getConsumeDeploymentId();
+    if (effectiveDeploymentId) {
+      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
+    }
+    const response = await this.fetch(
+      this.buildUrl(
+        queueName,
+        "consumer",
+        consumerGroup,
+        "lease",
+        receiptHandle
+      ),
       {
         method: "DELETE",
-        headers: new Headers({
-          Authorization: `Bearer ${await this.getToken()}`,
-          "Vqs-Queue-Name": queueName,
-          "Vqs-Consumer-Group": consumerGroup,
-          "Vqs-Ticket": ticket,
-          ...this.customHeaders
-        })
+        headers
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        throw new BadRequestError("Missing or invalid ticket");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
-        throw new MessageNotFoundError(messageId);
+        throw new MessageNotFoundError(receiptHandle);
       }
       if (response.status === 409) {
         throw new MessageNotAvailableError(
-          messageId,
-          "Invalid ticket, message not in correct state, or already processed"
-        );
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+          receiptHandle,
+          errorText || "Invalid receipt handle, message not in correct state, or already processed"
         );
       }
-      throw new Error(
-        `Failed to delete message: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "delete message",
+        "Missing or invalid receipt handle"
       );
     }
     return { deleted: true };
   }
-  /**
-   * Change the visibility timeout of a message
-   * @param options Change visibility options
-   * @returns Promise with update status
-   * @throws {MessageNotFoundError} When the message doesn't exist (404)
-   * @throws {MessageNotAvailableError} When message can't be updated (409)
-   * @throws {BadRequestError} When ticket is missing or visibility timeout invalid (400)
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied (environment mismatch)
-   * @throws {InternalServerError} When server encounters an error
-   */
   async changeVisibility(options) {
     const {
       queueName,
       consumerGroup,
-      messageId,
-      ticket,
+      receiptHandle,
       visibilityTimeoutSeconds
     } = options;
-    const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+    const headers = new Headers({
+      Authorization: `Bearer ${await this.getToken()}`,
+      "Content-Type": "application/json",
+      ...this.customHeaders
+    });
+    const effectiveDeploymentId = this.getConsumeDeploymentId();
+    if (effectiveDeploymentId) {
+      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
+    }
+    const response = await this.fetch(
+      this.buildUrl(
+        queueName,
+        "consumer",
+        consumerGroup,
+        "lease",
+        receiptHandle
+      ),
       {
         method: "PATCH",
-        headers: new Headers({
-          Authorization: `Bearer ${await this.getToken()}`,
-          "Vqs-Queue-Name": queueName,
-          "Vqs-Consumer-Group": consumerGroup,
-          "Vqs-Ticket": ticket,
-          "Vqs-Visibility-Timeout": visibilityTimeoutSeconds.toString(),
-          ...this.customHeaders
-        })
+        headers,
+        body: JSON.stringify({ visibilityTimeoutSeconds })
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        throw new BadRequestError(
-          "Missing ticket or invalid visibility timeout"
-        );
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
-        throw new MessageNotFoundError(messageId);
+        throw new MessageNotFoundError(receiptHandle);
       }
       if (response.status === 409) {
         throw new MessageNotAvailableError(
-          messageId,
-          "Invalid ticket, message not in correct state, or already processed"
-        );
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+          receiptHandle,
+          errorText || "Invalid receipt handle, message not in correct state, or already processed"
         );
       }
-      throw new Error(
-        `Failed to change visibility: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "change visibility",
+        "Missing receipt handle or invalid visibility timeout"
       );
     }
-    return { updated: true };
-  }
-};
-
-// src/callback.ts
-function validateWildcardPattern(pattern) {
-  const firstIndex = pattern.indexOf("*");
-  const lastIndex = pattern.lastIndexOf("*");
-  if (firstIndex !== lastIndex) {
-    return false;
-  }
-  if (firstIndex === -1) {
-    return false;
-  }
-  if (firstIndex !== pattern.length - 1) {
-    return false;
+    return { success: true };
   }
-  return true;
-}
-function matchesWildcardPattern(topicName, pattern) {
-  const prefix = pattern.slice(0, -1);
-  return topicName.startsWith(prefix);
-}
-function findTopicHandler(queueName, handlers) {
-  const exactHandler = handlers[queueName];
-  if (exactHandler) {
-    return exactHandler;
-  }
-  for (const pattern in handlers) {
-    if (pattern.includes("*") && matchesWildcardPattern(queueName, pattern)) {
-      return handlers[pattern];
+  /**
+   * Alternative endpoint for changing message visibility timeout.
+   * Uses the /visibility path suffix and expects visibilityTimeoutSeconds in the body.
+   * Functionally equivalent to changeVisibility but follows an alternative API pattern.
+   *
+   * @param options - Options for changing visibility
+   * @returns Promise resolving to change visibility response
+   */
+  async changeVisibilityAlt(options) {
+    const {
+      queueName,
+      consumerGroup,
+      receiptHandle,
+      visibilityTimeoutSeconds
+    } = options;
+    const headers = new Headers({
+      Authorization: `Bearer ${await this.getToken()}`,
+      "Content-Type": "application/json",
+      ...this.customHeaders
+    });
+    const effectiveDeploymentId = this.getConsumeDeploymentId();
+    if (effectiveDeploymentId) {
+      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
     }
-  }
-  return null;
-}
-async function parseCallback(request) {
-  const contentType = request.headers.get("content-type");
-  if (!contentType || !contentType.includes("application/cloudevents+json")) {
-    throw new Error(
-      "Invalid content type: expected 'application/cloudevents+json'"
-    );
-  }
-  let cloudEvent;
-  try {
-    cloudEvent = await request.json();
-  } catch (error) {
-    throw new Error("Failed to parse CloudEvent from request body");
-  }
-  if (!cloudEvent.type || !cloudEvent.source || !cloudEvent.id || typeof cloudEvent.data !== "object" || cloudEvent.data == null) {
-    throw new Error("Invalid CloudEvent: missing required fields");
-  }
-  if (cloudEvent.type !== "com.vercel.queue.v1beta") {
-    throw new Error(
-      `Invalid CloudEvent type: expected 'com.vercel.queue.v1beta', got '${cloudEvent.type}'`
-    );
-  }
-  const missingFields = [];
-  if (!("queueName" in cloudEvent.data)) missingFields.push("queueName");
-  if (!("consumerGroup" in cloudEvent.data))
-    missingFields.push("consumerGroup");
-  if (!("messageId" in cloudEvent.data)) missingFields.push("messageId");
-  if (missingFields.length > 0) {
-    throw new Error(
-      `Missing required CloudEvent data fields: ${missingFields.join(", ")}`
-    );
-  }
-  const { messageId, queueName, consumerGroup } = cloudEvent.data;
-  return {
-    queueName,
-    consumerGroup,
-    messageId
-  };
-}
-function handleCallback(handlers) {
-  for (const topicPattern in handlers) {
-    if (topicPattern.includes("*")) {
-      if (!validateWildcardPattern(topicPattern)) {
-        throw new Error(
-          `Invalid wildcard pattern "${topicPattern}": * may only appear once and must be at the end of the topic name`
-        );
+    const response = await this.fetch(
+      this.buildUrl(
+        queueName,
+        "consumer",
+        consumerGroup,
+        "lease",
+        receiptHandle,
+        "visibility"
+      ),
+      {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ visibilityTimeoutSeconds })
       }
-    }
-  }
-  const routeHandler = async (request) => {
-    try {
-      const { queueName, consumerGroup, messageId } = await parseCallback(request);
-      const topicHandler = findTopicHandler(queueName, handlers);
-      if (!topicHandler) {
-        const availableTopics = Object.keys(handlers).join(", ");
-        return Response.json(
-          {
-            error: `No handler found for topic: ${queueName}`,
-            availableTopics
-          },
-          { status: 404 }
-        );
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 404) {
+        throw new MessageNotFoundError(receiptHandle);
       }
-      const consumerGroupHandler = topicHandler[consumerGroup];
-      if (!consumerGroupHandler) {
-        const availableGroups = Object.keys(topicHandler).join(", ");
-        return Response.json(
-          {
-            error: `No handler found for consumer group "${consumerGroup}" in topic "${queueName}".`,
-            availableGroups
-          },
-          { status: 404 }
+      if (response.status === 409) {
+        throw new MessageNotAvailableError(
+          receiptHandle,
+          errorText || "Invalid receipt handle, message not in correct state, or already processed"
         );
       }
-      const client = new QueueClient();
-      const topic = new Topic(client, queueName);
-      const cg = topic.consumerGroup(consumerGroup);
-      await cg.consume(consumerGroupHandler, { messageId });
-      return Response.json({ status: "success" });
-    } catch (error) {
-      console.error("Queue callback error:", error);
-      if (error instanceof Error && (error.message.includes("Missing required CloudEvent data fields") || error.message.includes("Invalid CloudEvent") || error.message.includes("Invalid CloudEvent type") || error.message.includes("Invalid content type") || error.message.includes("Failed to parse CloudEvent"))) {
-        return Response.json({ error: error.message }, { status: 400 });
-      }
-      return Response.json(
-        { error: "Failed to process queue message" },
-        { status: 500 }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "change visibility (alt)",
+        "Missing receipt handle or invalid visibility timeout"
       );
     }
-  };
-  if (isDevMode()) {
-    registerDevRouteHandler(routeHandler, handlers);
-  }
-  return routeHandler;
-}
-
-// src/dev.ts
-var GLOBAL_KEY = Symbol.for("@vercel/queue.devHandlers");
-function getDevHandlerState() {
-  const g = globalThis;
-  if (!g[GLOBAL_KEY]) {
-    g[GLOBAL_KEY] = {
-      devRouteHandlers: /* @__PURE__ */ new Map(),
-      wildcardRouteHandlers: /* @__PURE__ */ new Map()
-    };
-  }
-  return g[GLOBAL_KEY];
-}
-var { devRouteHandlers, wildcardRouteHandlers } = getDevHandlerState();
-function cleanupDeadRefs(key, refs) {
-  const aliveRefs = refs.filter((ref) => ref.deref() !== void 0);
-  if (aliveRefs.length === 0) {
-    wildcardRouteHandlers.delete(key);
-  } else if (aliveRefs.length < refs.length) {
-    wildcardRouteHandlers.set(key, aliveRefs);
-  }
-}
-function isDevMode() {
-  return process.env.NODE_ENV === "development";
-}
-function registerDevRouteHandler(routeHandler, handlers) {
-  for (const topicName in handlers) {
-    for (const consumerGroup in handlers[topicName]) {
-      const key = `${topicName}:${consumerGroup}`;
-      if (topicName.includes("*")) {
-        const existing = wildcardRouteHandlers.get(key) || [];
-        cleanupDeadRefs(key, existing);
-        const cleanedRefs = wildcardRouteHandlers.get(key) || [];
-        const weakRef = new WeakRef(routeHandler);
-        cleanedRefs.push(weakRef);
-        wildcardRouteHandlers.set(key, cleanedRefs);
-      } else {
-        devRouteHandlers.set(key, {
-          routeHandler,
-          topicPattern: topicName
-        });
-      }
-    }
-  }
-}
-function findRouteHandlersForTopic(topicName) {
-  const handlersMap = /* @__PURE__ */ new Map();
-  for (const [
-    key,
-    { routeHandler, topicPattern }
-  ] of devRouteHandlers.entries()) {
-    const [_, consumerGroup] = key.split(":");
-    if (topicPattern === topicName) {
-      if (!handlersMap.has(routeHandler)) {
-        handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
-      }
-      handlersMap.get(routeHandler).add(consumerGroup);
-    }
+    return { success: true };
   }
-  for (const [key, refs] of wildcardRouteHandlers.entries()) {
-    const [pattern, consumerGroup] = key.split(":");
-    if (matchesWildcardPattern(topicName, pattern)) {
-      cleanupDeadRefs(key, refs);
-      const cleanedRefs = wildcardRouteHandlers.get(key) || [];
-      for (const ref of cleanedRefs) {
-        const routeHandler = ref.deref();
-        if (routeHandler) {
-          if (!handlersMap.has(routeHandler)) {
-            handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
-          }
-          handlersMap.get(routeHandler).add(consumerGroup);
-        }
-      }
-    }
-  }
-  return handlersMap;
-}
-function createMockCloudEventRequest(topicName, consumerGroup, messageId) {
-  const cloudEvent = {
-    type: "com.vercel.queue.v1beta",
-    source: `/topic/${topicName}/consumer/${consumerGroup}`,
-    id: messageId,
-    datacontenttype: "application/json",
-    data: {
-      messageId,
-      queueName: topicName,
-      consumerGroup
-    },
-    time: (/* @__PURE__ */ new Date()).toISOString(),
-    specversion: "1.0"
-  };
-  return new Request("https://localhost/api/queue/callback", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/cloudevents+json"
-    },
-    body: JSON.stringify(cloudEvent)
-  });
-}
-var DEV_CALLBACK_DELAY = 1e3;
-function scheduleDevTimeout(topicName, messageId, timeoutSeconds) {
-  console.log(
-    `[Dev Mode] Message ${messageId} timed out for ${timeoutSeconds}s, will re-trigger`
-  );
-  setTimeout(
-    () => {
-      console.log(
-        `[Dev Mode] Re-triggering callback for timed-out message ${messageId}`
-      );
-      triggerDevCallbacks(topicName, messageId);
-    },
-    timeoutSeconds * 1e3 + DEV_CALLBACK_DELAY
-  );
-}
-function triggerDevCallbacks(topicName, messageId) {
-  const handlersMap = findRouteHandlersForTopic(topicName);
-  if (handlersMap.size === 0) {
-    return;
-  }
-  const consumerGroups = Array.from(
-    new Set(
-      Array.from(handlersMap.values()).flatMap((groups) => Array.from(groups))
-    )
-  );
-  console.log(
-    `[Dev Mode] Triggering local callbacks for topic "${topicName}" \u2192 consumers: ${consumerGroups.join(", ")}`
-  );
-  setTimeout(async () => {
-    for (const [routeHandler, consumerGroups2] of handlersMap.entries()) {
-      for (const consumerGroup of consumerGroups2) {
-        try {
-          const request = createMockCloudEventRequest(
-            topicName,
-            consumerGroup,
-            messageId
-          );
-          const response = await routeHandler(request);
-          if (response.ok) {
-            try {
-              const responseData = await response.json();
-              if (responseData.status === "success") {
-                console.log(
-                  `[Dev Mode] Message processed for ${topicName}/${consumerGroup}`
-                );
-              }
-            } catch (jsonError) {
-              console.error(
-                `[Dev Mode] Failed to parse success response for ${topicName}/${consumerGroup}:`,
-                jsonError
-              );
-            }
-          } else {
-            try {
-              const errorData = await response.json();
-              console.error(
-                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
-                errorData.error || response.statusText
-              );
-            } catch (jsonError) {
-              console.error(
-                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
-                response.statusText
-              );
-            }
-          }
-        } catch (error) {
-          console.error(
-            `[Dev Mode] Error triggering callback for ${topicName}/${consumerGroup}:`,
-            error
-          );
-        }
-      }
-    }
-  }, DEV_CALLBACK_DELAY);
-}
-function clearDevHandlers() {
-  devRouteHandlers.clear();
-  wildcardRouteHandlers.clear();
-}
-if (process.env.NODE_ENV === "test" || process.env.VITEST) {
-  globalThis.__clearDevHandlers = clearDevHandlers;
-}
+};
 
 // src/consumer-group.ts
 var ConsumerGroup = class {
@@ -973,8 +1016,7 @@ var ConsumerGroup = class {
    * The extension loop runs every `refreshInterval` seconds and updates the message's
    * visibility timeout to `visibilityTimeout` seconds from the current time.
    *
-   * @param messageId - The unique identifier of the message to extend visibility for
-   * @param ticket - The receipt ticket that proves ownership of the message
+   * @param receiptHandle - The receipt handle that proves ownership of the message
    * @returns A function that when called will stop the extension loop
    *
    * @remarks
@@ -984,37 +1026,43 @@ var ConsumerGroup = class {
    * - By default, the stop function returns immediately without waiting for in-flight
    * - Pass `true` to the stop function to wait for any in-flight extension to complete
    */
-  startVisibilityExtension(messageId, ticket) {
+  startVisibilityExtension(receiptHandle) {
     let isRunning = true;
+    let isResolved = false;
     let resolveLifecycle;
     let timeoutId = null;
     const lifecyclePromise = new Promise((resolve) => {
       resolveLifecycle = resolve;
     });
+    const safeResolve = () => {
+      if (!isResolved) {
+        isResolved = true;
+        resolveLifecycle();
+      }
+    };
     const extend = async () => {
       if (!isRunning) {
-        resolveLifecycle();
+        safeResolve();
         return;
       }
       try {
         await this.client.changeVisibility({
           queueName: this.topicName,
           consumerGroup: this.consumerGroupName,
-          messageId,
-          ticket,
+          receiptHandle,
           visibilityTimeoutSeconds: this.visibilityTimeout
         });
         if (isRunning) {
           timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
         } else {
-          resolveLifecycle();
+          safeResolve();
         }
       } catch (error) {
         console.error(
-          `Failed to extend visibility for message ${messageId}:`,
+          `Failed to extend visibility for receipt handle ${receiptHandle}:`,
           error
         );
-        resolveLifecycle();
+        safeResolve();
       }
     };
     timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
@@ -1027,22 +1075,14 @@ var ConsumerGroup = class {
       if (waitForCompletion) {
         await lifecyclePromise;
       } else {
-        resolveLifecycle();
+        safeResolve();
       }
     };
   }
-  /**
-   * Process a single message with the given handler
-   * @param message The message to process
-   * @param handler Function to process the message
-   */
   async processMessage(message, handler) {
-    const stopExtension = this.startVisibilityExtension(
-      message.messageId,
-      message.ticket
-    );
+    const stopExtension = this.startVisibilityExtension(message.receiptHandle);
     try {
-      const result = await handler(message.payload, {
+      await handler(message.payload, {
         messageId: message.messageId,
         deliveryCount: message.deliveryCount,
         createdAt: message.createdAt,
@@ -1050,29 +1090,11 @@ var ConsumerGroup = class {
         consumerGroup: this.consumerGroupName
       });
       await stopExtension();
-      if (result && "timeoutSeconds" in result) {
-        await this.client.changeVisibility({
-          queueName: this.topicName,
-          consumerGroup: this.consumerGroupName,
-          messageId: message.messageId,
-          ticket: message.ticket,
-          visibilityTimeoutSeconds: result.timeoutSeconds
-        });
-        if (isDevMode()) {
-          scheduleDevTimeout(
-            this.topicName,
-            message.messageId,
-            result.timeoutSeconds
-          );
-        }
-      } else {
-        await this.client.deleteMessage({
-          queueName: this.topicName,
-          consumerGroup: this.consumerGroupName,
-          messageId: message.messageId,
-          ticket: message.ticket
-        });
-      }
+      await this.client.deleteMessage({
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        receiptHandle: message.receiptHandle
+      });
     } catch (error) {
       await stopExtension();
       if (this.transport.finalize && message.payload !== void 0 && message.payload !== null) {
@@ -1087,36 +1109,16 @@ var ConsumerGroup = class {
   }
   async consume(handler, options) {
     if (options?.messageId) {
-      if (options.skipPayload) {
-        const response = await this.client.receiveMessageById(
-          {
-            queueName: this.topicName,
-            consumerGroup: this.consumerGroupName,
-            messageId: options.messageId,
-            visibilityTimeoutSeconds: this.visibilityTimeout,
-            skipPayload: true
-          },
-          this.transport
-        );
-        await this.processMessage(
-          response.message,
-          handler
-        );
-      } else {
-        const response = await this.client.receiveMessageById(
-          {
-            queueName: this.topicName,
-            consumerGroup: this.consumerGroupName,
-            messageId: options.messageId,
-            visibilityTimeoutSeconds: this.visibilityTimeout
-          },
-          this.transport
-        );
-        await this.processMessage(
-          response.message,
-          handler
-        );
-      }
+      const response = await this.client.receiveMessageById(
+        {
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          messageId: options.messageId,
+          visibilityTimeoutSeconds: this.visibilityTimeout
+        },
+        this.transport
+      );
+      await this.processMessage(response.message, handler);
     } else {
       let messageFound = false;
       for await (const message of this.client.receiveMessages(
@@ -1184,7 +1186,7 @@ var Topic = class {
         payload,
         idempotencyKey: options?.idempotencyKey,
         retentionSeconds: options?.retentionSeconds,
-        deploymentId: options?.deploymentId
+        delaySeconds: options?.delaySeconds
       },
       this.transport
     );
@@ -1225,52 +1227,224 @@ var Topic = class {
   }
 };
 
+// src/callback.ts
+function validateWildcardPattern(pattern) {
+  const firstIndex = pattern.indexOf("*");
+  const lastIndex = pattern.lastIndexOf("*");
+  if (firstIndex !== lastIndex) {
+    return false;
+  }
+  if (firstIndex === -1) {
+    return false;
+  }
+  if (firstIndex !== pattern.length - 1) {
+    return false;
+  }
+  return true;
+}
+function matchesWildcardPattern(topicName, pattern) {
+  const prefix = pattern.slice(0, -1);
+  return topicName.startsWith(prefix);
+}
+function findTopicHandler(queueName, handlers) {
+  const exactHandler = handlers[queueName];
+  if (exactHandler) {
+    return exactHandler;
+  }
+  for (const pattern in handlers) {
+    if (pattern.includes("*") && matchesWildcardPattern(queueName, pattern)) {
+      return handlers[pattern];
+    }
+  }
+  return null;
+}
+async function parseCallback(request) {
+  const contentType = request.headers.get("content-type");
+  if (!contentType || !contentType.includes("application/cloudevents+json")) {
+    throw new Error(
+      "Invalid content type: expected 'application/cloudevents+json'"
+    );
+  }
+  let cloudEvent;
+  try {
+    cloudEvent = await request.json();
+  } catch (error) {
+    throw new Error("Failed to parse CloudEvent from request body");
+  }
+  if (!cloudEvent.type || !cloudEvent.source || !cloudEvent.id || typeof cloudEvent.data !== "object" || cloudEvent.data == null) {
+    throw new Error("Invalid CloudEvent: missing required fields");
+  }
+  if (cloudEvent.type !== "com.vercel.queue.v1beta") {
+    throw new Error(
+      `Invalid CloudEvent type: expected 'com.vercel.queue.v1beta', got '${cloudEvent.type}'`
+    );
+  }
+  const missingFields = [];
+  if (!("queueName" in cloudEvent.data)) missingFields.push("queueName");
+  if (!("consumerGroup" in cloudEvent.data))
+    missingFields.push("consumerGroup");
+  if (!("messageId" in cloudEvent.data)) missingFields.push("messageId");
+  if (missingFields.length > 0) {
+    throw new Error(
+      `Missing required CloudEvent data fields: ${missingFields.join(", ")}`
+    );
+  }
+  const { messageId, queueName, consumerGroup } = cloudEvent.data;
+  return {
+    queueName,
+    consumerGroup,
+    messageId
+  };
+}
+function createCallbackHandler(handlers, client) {
+  for (const topicPattern in handlers) {
+    if (topicPattern.includes("*")) {
+      if (!validateWildcardPattern(topicPattern)) {
+        throw new Error(
+          `Invalid wildcard pattern "${topicPattern}": * may only appear once and must be at the end of the topic name`
+        );
+      }
+    }
+  }
+  const routeHandler = async (request) => {
+    try {
+      const { queueName, consumerGroup, messageId } = await parseCallback(request);
+      const topicHandler = findTopicHandler(queueName, handlers);
+      if (!topicHandler) {
+        const availableTopics = Object.keys(handlers).join(", ");
+        return Response.json(
+          {
+            error: `No handler found for topic: ${queueName}`,
+            availableTopics
+          },
+          { status: 404 }
+        );
+      }
+      const consumerGroupHandler = topicHandler[consumerGroup];
+      if (!consumerGroupHandler) {
+        const availableGroups = Object.keys(topicHandler).join(", ");
+        return Response.json(
+          {
+            error: `No handler found for consumer group "${consumerGroup}" in topic "${queueName}".`,
+            availableGroups
+          },
+          { status: 404 }
+        );
+      }
+      const topic = new Topic(client, queueName);
+      const cg = topic.consumerGroup(consumerGroup);
+      await cg.consume(consumerGroupHandler, { messageId });
+      return Response.json({ status: "success" });
+    } catch (error) {
+      console.error("Queue callback error:", error);
+      if (error instanceof Error && (error.message.includes("Missing required CloudEvent data fields") || error.message.includes("Invalid CloudEvent") || error.message.includes("Invalid CloudEvent type") || error.message.includes("Invalid content type") || error.message.includes("Failed to parse CloudEvent"))) {
+        return Response.json({ error: error.message }, { status: 400 });
+      }
+      return Response.json(
+        { error: "Failed to process queue message" },
+        { status: 500 }
+      );
+    }
+  };
+  return routeHandler;
+}
+function handleCallback(handlers, client) {
+  return createCallbackHandler(handlers, client || new QueueClient());
+}
+
 // src/factory.ts
 async function send(topicName, payload, options) {
   const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
+  const client = options?.client || new QueueClient();
   const result = await client.sendMessage(
     {
       queueName: topicName,
       payload,
       idempotencyKey: options?.idempotencyKey,
       retentionSeconds: options?.retentionSeconds,
-      deploymentId: options?.deploymentId
+      delaySeconds: options?.delaySeconds
     },
     transport
   );
   if (isDevMode()) {
-    triggerDevCallbacks(topicName, result.messageId);
+    triggerDevCallbacks(topicName, result.messageId, options?.delaySeconds);
   }
   return { messageId: result.messageId };
 }
 async function receive(topicName, consumerGroup, handler, options) {
   const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
+  const client = options?.client || new QueueClient();
   const topic = new Topic(client, topicName, transport);
-  const { messageId, skipPayload, ...consumerGroupOptions } = options || {};
+  const { messageId, client: _, ...consumerGroupOptions } = options || {};
   const consumer = topic.consumerGroup(consumerGroup, consumerGroupOptions);
   if (messageId) {
-    if (skipPayload) {
-      return consumer.consume(handler, {
-        messageId,
-        skipPayload: true
-      });
-    } else {
-      return consumer.consume(handler, { messageId });
-    }
+    return consumer.consume(handler, { messageId });
   } else {
     return consumer.consume(handler);
   }
 }
+
+// src/queue-client.ts
+var Client = class {
+  client;
+  /**
+   * Create a new Client
+   * @param options QueueClient configuration options
+   */
+  constructor(options = {}) {
+    this.client = new QueueClient(options);
+  }
+  /**
+   * Send a message to a topic
+   * @param topicName Name of the topic to send to
+   * @param payload The data to send
+   * @param options Optional publish options and transport
+   * @returns Promise with the message ID
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied (environment mismatch)
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async send(topicName, payload, options) {
+    return send(topicName, payload, {
+      ...options,
+      client: this.client
+    });
+  }
+  /**
+   * Create a callback handler for processing queue messages
+   * Returns a Next.js route handler function that routes messages to appropriate handlers
+   * @param handlers Object with topic-specific handlers organized by consumer groups
+   * @returns A Next.js route handler function
+   *
+   * @example
+   * ```typescript
+   * export const POST = client.handleCallback({
+   *   "user-events": {
+   *     "welcome": (user, metadata) => console.log("Welcoming user", user),
+   *     "analytics": (user, metadata) => console.log("Tracking user", user),
+   *   },
+   * });
+   * ```
+   */
+  handleCallback(handlers) {
+    return handleCallback(handlers, this.client);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BadRequestError,
   BufferTransport,
+  Client,
+  ConcurrencyLimitError,
+  ConsumerDiscoveryError,
+  ConsumerRegistryNotConfiguredError,
+  DuplicateMessageError,
   ForbiddenError,
   InternalServerError,
   InvalidLimitError,
   JsonTransport,
+  MessageAlreadyProcessedError,
   MessageCorruptedError,
   MessageLockedError,
   MessageNotAvailableError,