@vercel/queue 0.0.0-alpha.11 → 0.0.0-alpha.2

package/dist/index.mjs

@@ -1,90 +1,130 @@
-// src/transports.ts
-var JsonTransport = class {
-  contentType = "application/json";
-  serialize(value) {
-    return Buffer.from(JSON.stringify(value), "utf8");
-  }
-  async deserialize(stream) {
-    const reader = stream.getReader();
-    let totalLength = 0;
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-        totalLength += value.length;
-      }
-    } finally {
-      reader.releaseLock();
-    }
-    const buffer = Buffer.concat(chunks, totalLength);
-    return JSON.parse(buffer.toString("utf8"));
-  }
-};
-var BufferTransport = class {
-  contentType = "application/octet-stream";
-  serialize(value) {
-    return value;
-  }
-  async deserialize(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-    const buffer = new Uint8Array(totalLength);
-    let offset = 0;
-    for (const chunk of chunks) {
-      buffer.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return Buffer.from(buffer);
-  }
-};
-var StreamTransport = class {
-  contentType = "application/octet-stream";
-  serialize(value) {
-    return value;
-  }
-  async deserialize(stream) {
-    return stream;
-  }
-  async finalize(payload) {
-    const reader = payload.getReader();
-    try {
-      while (true) {
-        const { done } = await reader.read();
-        if (done) break;
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-};
-
-// src/client.ts
-import { parseMultipartStream } from "mixpart";
-
 // src/oidc.ts
-function getVercelOidcToken() {
+async function getVercelOidcToken() {
   const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
   const fromSymbol = globalThis;
   const context = fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
   const token = context.headers?.["x-vercel-oidc-token"] ?? process.env.VERCEL_OIDC_TOKEN;
   if (!token) {
-    return null;
+    throw new Error(
+      `The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`
+    );
   }
   return token;
 }
 
+// src/client.ts
+import { parseMultipartStream } from "mixpart";
+
+// src/local.ts
+import { spawn } from "child_process";
+function isLocalhostWithPort(url) {
+  try {
+    const parsedUrl = new URL(url);
+    const isLocalhost = parsedUrl.hostname === "localhost";
+    const port = parsedUrl.port ? parseInt(parsedUrl.port, 10) : 0;
+    return { isLocalhost, port };
+  } catch {
+    return { isLocalhost: false };
+  }
+}
+function isSupportedPlatform() {
+  const platform = process.platform;
+  return platform === "darwin" || platform === "linux";
+}
+function processDevelopmentCallbacks(callbacks) {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  if (!isDevelopment) {
+    return [];
+  }
+  if (!isSupportedPlatform()) {
+    const hasLocalhostCallbacks = Object.values(callbacks).some((config) => {
+      const { isLocalhost } = isLocalhostWithPort(config.url);
+      return isLocalhost;
+    });
+    if (hasLocalhostCallbacks) {
+      console.warn(
+        `Queue Development Mode: Localhost callbacks are not supported on ${process.platform}. Localhost callback handling requires bash, nc, and curl which are available on macOS and Linux only. Consider using a production callback URL or developing on a supported platform.`
+      );
+    }
+    return [];
+  }
+  const localhostCallbacks = [];
+  Object.entries(callbacks).forEach(([group, config]) => {
+    const { isLocalhost, port } = isLocalhostWithPort(config.url);
+    if (isLocalhost && port && port > 0) {
+      localhostCallbacks.push({ group, config, port });
+    } else {
+      console.warn(
+        `Queue Development Mode: Skipping non-localhost callback for group "${group}": ${config.url}. Only localhost callbacks with explicit ports are supported in development.`
+      );
+    }
+  });
+  return localhostCallbacks;
+}
+function fireLocalhostCallbacks(localhostCallbacks, queueName, responseData) {
+  localhostCallbacks.forEach(({ group, config, port }) => {
+    const callbackHeaders = new Headers();
+    callbackHeaders.set("Vqs-Message-Id", responseData.messageId);
+    callbackHeaders.set("Vqs-Queue-Name", queueName);
+    callbackHeaders.set("Vqs-Consumer-Group", group);
+    fireAndForgetWaitForHttpReady(
+      config.url,
+      port,
+      config.delay || 0,
+      3,
+      // Default retry frequency
+      callbackHeaders
+    );
+  });
+}
+function fireAndForgetWaitForHttpReady(url, port, initialDelaySeconds = 0, retryFrequencySeconds = 3, headers) {
+  if (!isSupportedPlatform()) {
+    console.warn(
+      `Queue: fireAndForgetWaitForHttpReady is not supported on ${process.platform}. This function requires bash, nc, and curl which are available on macOS and Linux only.`
+    );
+    return;
+  }
+  let headerArgs = "";
+  if (headers) {
+    const headerArray = [];
+    headers.forEach((value, key) => {
+      headerArray.push(`-H '${key}: ${value}'`);
+    });
+    headerArgs = headerArray.join(" ");
+  }
+  const bashScript = `
+    # Wait for any initial boot time
+    sleep ${initialDelaySeconds}
+
+    missed=0
+    while true; do
+      # 1) Check if TCP port is listening
+      if nc -z localhost ${port} 2>/dev/null; then
+        missed=0
+        # 2) If port is open, try HTTP POST check
+        if curl -sSL --fail -o /dev/null -X POST ${headerArgs} "${url}"; then
+          # Success: port is up AND HTTP returned 2xx (following redirects)
+          exit 0
+        fi
+      else
+        # Port was closed\u2014increment miss counter
+        ((missed+=1))
+        # If closed twice in a row, give up immediately
+        if [ "$missed" -ge 2 ]; then
+          exit 1
+        fi
+      fi
+      # Wait before next cycle
+      sleep ${retryFrequencySeconds}
+    done
+  `;
+  const childProcess = spawn("bash", ["-c", bashScript], {
+    stdio: "ignore",
+    detached: true
+  });
+  childProcess.unref();
+}
+
 // src/types.ts
 var MessageNotFoundError = class extends Error {
   constructor(messageId) {
@@ -100,6 +140,16 @@ var MessageNotAvailableError = class extends Error {
     this.name = "MessageNotAvailableError";
   }
 };
+var FifoOrderingViolationError = class extends Error {
+  nextMessageId;
+  constructor(messageId, nextMessageId, reason) {
+    super(
+      `FIFO ordering violation for message ${messageId}: ${reason}. Process message ${nextMessageId} first.`
+    );
+    this.name = "FifoOrderingViolationError";
+    this.nextMessageId = nextMessageId;
+  }
+};
 var MessageCorruptedError = class extends Error {
   constructor(messageId, reason) {
     super(`Message ${messageId} is corrupted: ${reason}`);
@@ -141,6 +191,16 @@ var BadRequestError = class extends Error {
     this.name = "BadRequestError";
   }
 };
+var FailedDependencyError = class extends Error {
+  nextMessageId;
+  constructor(messageId, nextMessageId) {
+    super(
+      `Failed dependency: FIFO ordering violation for message ${messageId}. Must process message ${nextMessageId} first.`
+    );
+    this.name = "FailedDependencyError";
+    this.nextMessageId = nextMessageId;
+  }
+};
 var InternalServerError = class extends Error {
   constructor(message = "Unexpected server error") {
     super(message);
@@ -153,6 +213,12 @@ var InvalidLimitError = class extends Error {
     this.name = "InvalidLimitError";
   }
 };
+var InvalidCallbackError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidCallbackError";
+  }
+};
 
 // src/client.ts
 async function consumeStream(stream) {
@@ -182,33 +248,40 @@ function parseQueueHeaders(headers) {
   return {
     messageId,
     deliveryCount,
-    createdAt: new Date(timestamp),
+    timestamp,
     contentType,
     ticket
   };
 }
-var QueueClient = class {
+var QueueClient = class _QueueClient {
   baseUrl;
-  basePath;
   token;
   /**
    * Create a new Vercel Queue Service client
-   * @param options Client configuration options (optional - will auto-detect Vercel Function environment)
+   * @param options Client configuration options
    */
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl || "https://api.vercel.com";
-    this.basePath = options.basePath || "/v1/queues/messages";
-    if (options.token) {
-      this.token = options.token;
-    } else {
-      const token = getVercelOidcToken();
-      if (!token) {
-        throw new Error(
-          "Failed to get OIDC token from Vercel Functions. Make sure you are running in a Vercel Function environment, or provide a token explicitly.\n\nTo set up your environment:\n1. Link your project: 'vercel link'\n2. Pull environment variables: 'vercel env pull'\n3. Run with environment: 'dotenv -e .env.local -- your-command'"
-        );
-      }
-      this.token = token;
+  constructor(options) {
+    this.baseUrl = options.baseUrl || "https://vqs.vercel.sh";
+    this.token = options.token;
+  }
+  /**
+   * Create a QueueClient automatically configured for Vercel Functions
+   * This method automatically retrieves the OIDC token from the Vercel Function environment
+   * Always creates a fresh instance since OIDC tokens expire after 15 minutes
+   * @param baseUrl Optional base URL override
+   * @returns Promise resolving to a new QueueClient instance
+   */
+  static async fromVercelFunction(baseUrl) {
+    const token = await getVercelOidcToken();
+    if (!token) {
+      throw new Error(
+        "Failed to get OIDC token from Vercel Functions. Make sure you are running in a Vercel Function environment."
+      );
     }
+    return new _QueueClient({
+      token,
+      baseUrl
+    });
   }
   /**
    * Send a message to a queue
@@ -221,23 +294,40 @@ var QueueClient = class {
    * @throws {InternalServerError} When server encounters an error
    */
   async sendMessage(options, transport) {
-    const { queueName, payload, idempotencyKey, retentionSeconds } = options;
+    const { queueName, payload, idempotencyKey, retentionSeconds, callbacks } = options;
     const headers = new Headers({
       Authorization: `Bearer ${this.token}`,
       "Vqs-Queue-Name": queueName,
       "Content-Type": transport.contentType
     });
-    if (process.env.VERCEL_DEPLOYMENT_ID) {
-      headers.set("Vqs-Deployment-Id", process.env.VERCEL_DEPLOYMENT_ID);
-    }
     if (idempotencyKey) {
       headers.set("Vqs-Idempotency-Key", idempotencyKey);
     }
     if (retentionSeconds !== void 0) {
       headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
     }
+    let localhostCallbacks = [];
+    if (callbacks) {
+      const isDevelopment = process.env.NODE_ENV === "development";
+      if (isDevelopment) {
+        localhostCallbacks = processDevelopmentCallbacks(callbacks);
+      } else {
+        const endpoints = Object.entries(callbacks).map(
+          ([group, config]) => `${group}=${Buffer.from(config.url).toString("base64")}`
+        ).join(",");
+        headers.set("Vqs-Callback-Url", endpoints);
+        const delays = Object.entries(callbacks).filter(([, config]) => config.delay !== void 0).map(([group, config]) => `${group}=${config.delay}`).join(",");
+        if (delays) {
+          headers.set("Vqs-Callback-Delay", delays);
+        }
+        const frequencies = Object.entries(callbacks).filter(([, config]) => config.frequency !== void 0).map(([group, config]) => `${group}=${config.frequency}`).join(",");
+        if (frequencies) {
+          headers.set("Vqs-Callback-Frequency", frequencies);
+        }
+      }
+    }
     const body = transport.serialize(payload);
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
+    const response = await fetch(`${this.baseUrl}/api/v2/messages`, {
       method: "POST",
       headers,
       body
@@ -266,6 +356,9 @@ var QueueClient = class {
       );
     }
     const responseData = await response.json();
+    if (localhostCallbacks.length > 0) {
+      fireLocalhostCallbacks(localhostCallbacks, queueName, responseData);
+    }
     return responseData;
   }
   /**
@@ -275,7 +368,7 @@ var QueueClient = class {
    * @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 {MessageLockedError} When FIFO queue has locked messages (423)
    * @throws {BadRequestError} When request parameters are invalid
    * @throws {UnauthorizedError} When authentication fails
    * @throws {ForbiddenError} When access is denied (environment mismatch)
@@ -301,7 +394,7 @@ var QueueClient = class {
     if (limit !== void 0) {
       headers.set("Vqs-Limit", limit.toString());
     }
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
+    const response = await fetch(`${this.baseUrl}/api/v2/messages`, {
       method: "GET",
       headers
     });
@@ -326,7 +419,7 @@ var QueueClient = class {
           const parsed = parseInt(retryAfterHeader, 10);
           retryAfter = isNaN(parsed) ? void 0 : parsed;
         }
-        throw new MessageLockedError("next message", retryAfter);
+        throw new MessageLockedError("next message in FIFO queue", retryAfter);
       }
       if (response.status >= 500) {
         throw new InternalServerError(
@@ -383,7 +476,7 @@ var QueueClient = class {
       headers.set("Vqs-Skip-Payload", "1");
     }
     const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
       {
         method: "GET",
         headers
@@ -412,7 +505,37 @@ var QueueClient = class {
         }
         throw new MessageLockedError(messageId, retryAfter);
       }
+      if (response.status === 424) {
+        try {
+          const errorData = await response.json();
+          if (errorData.meta?.nextMessageId) {
+            throw new FailedDependencyError(
+              messageId,
+              errorData.meta.nextMessageId
+            );
+          }
+        } catch (parseError) {
+          if (parseError instanceof FailedDependencyError) {
+            throw parseError;
+          }
+        }
+        throw new MessageNotAvailableError(
+          messageId,
+          "FIFO ordering violation"
+        );
+      }
       if (response.status === 409) {
+        try {
+          const errorData = await response.json();
+          if (errorData.nextMessageId) {
+            throw new FifoOrderingViolationError(
+              messageId,
+              errorData.nextMessageId,
+              errorData.error
+            );
+          }
+        } catch (parseError) {
+        }
         throw new MessageNotAvailableError(messageId);
       }
       if (response.status >= 500) {
@@ -492,7 +615,7 @@ var QueueClient = class {
   async deleteMessage(options) {
     const { queueName, consumerGroup, messageId, ticket } = options;
     const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
       {
         method: "DELETE",
         headers: new Headers({
@@ -553,7 +676,7 @@ var QueueClient = class {
       visibilityTimeoutSeconds
     } = options;
     const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
       {
         method: "PATCH",
         headers: new Headers({
@@ -599,6 +722,82 @@ var QueueClient = class {
   }
 };
 
+// src/transports.ts
+var JsonTransport = class {
+  contentType = "application/json";
+  serialize(value) {
+    return Buffer.from(JSON.stringify(value), "utf8");
+  }
+  async deserialize(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      buffer.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return JSON.parse(Buffer.from(buffer).toString("utf8"));
+  }
+};
+var BufferTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      buffer.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return Buffer.from(buffer);
+  }
+};
+var StreamTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    return stream;
+  }
+  async finalize(payload) {
+    const reader = payload.getReader();
+    try {
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+
 // src/consumer-group.ts
 var ConsumerGroup = class {
   client;
@@ -698,11 +897,7 @@ var ConsumerGroup = class {
       message.ticket
     );
     try {
-      const result = await handler(message.payload, {
-        messageId: message.messageId,
-        deliveryCount: message.deliveryCount,
-        createdAt: message.createdAt
-      });
+      const result = await handler(message);
       await stopExtension();
       if (result && "timeoutSeconds" in result) {
         await this.client.changeVisibility({
@@ -732,58 +927,219 @@ var ConsumerGroup = class {
       throw error;
     }
   }
-  async consume(handler, options) {
-    if (options?.messageId) {
-      if (options.skipPayload) {
-        const response = await this.client.receiveMessageById(
+  /**
+   * Start continuous processing of messages from the topic
+   * @param signal AbortSignal to control when to stop processing
+   * @param handler Function to process each message
+   * @param options Processing options
+   * @returns Promise that resolves when processing stops (due to signal or error)
+   */
+  async subscribe(signal, handler, options = {}) {
+    const pollingInterval = options.pollingInterval || 1e3;
+    while (!signal.aborted) {
+      try {
+        for await (const message of this.client.receiveMessages(
           {
             queueName: this.topicName,
             consumerGroup: this.consumerGroupName,
-            messageId: options.messageId,
             visibilityTimeoutSeconds: this.visibilityTimeout,
-            skipPayload: true
+            limit: 1
+            // Always process one message at a time
           },
           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
-        );
-      }
-    } else {
-      let messageFound = false;
-      for await (const message of this.client.receiveMessages(
-        {
-          queueName: this.topicName,
-          consumerGroup: this.consumerGroupName,
-          visibilityTimeoutSeconds: this.visibilityTimeout,
-          limit: 1
-        },
-        this.transport
-      )) {
-        messageFound = true;
-        await this.processMessage(message, handler);
-        break;
-      }
-      if (!messageFound) {
-        throw new Error("No messages available");
+        )) {
+          if (signal.aborted) {
+            break;
+          }
+          try {
+            await this.processMessage(message, handler);
+          } catch (error) {
+            console.error("Error processing message:", error);
+          }
+        }
+        if (!signal.aborted) {
+          await new Promise((resolve) => {
+            const timeoutId = setTimeout(resolve, pollingInterval);
+            signal.addEventListener(
+              "abort",
+              () => {
+                clearTimeout(timeoutId);
+                resolve();
+              },
+              { once: true }
+            );
+          });
+        }
+      } catch (error) {
+        if (error instanceof QueueEmptyError) {
+          if (!signal.aborted) {
+            await new Promise((resolve) => {
+              const timeoutId = setTimeout(resolve, pollingInterval);
+              signal.addEventListener(
+                "abort",
+                () => {
+                  clearTimeout(timeoutId);
+                  resolve();
+                },
+                { once: true }
+              );
+            });
+          }
+          continue;
+        }
+        if (error instanceof MessageLockedError) {
+          const waitTime = error.retryAfter ? error.retryAfter * 1e3 : pollingInterval;
+          if (!signal.aborted) {
+            await new Promise((resolve) => {
+              const timeoutId = setTimeout(resolve, waitTime);
+              signal.addEventListener(
+                "abort",
+                () => {
+                  clearTimeout(timeoutId);
+                  resolve();
+                },
+                { once: true }
+              );
+            });
+          }
+          continue;
+        }
+        console.error("Error polling topic:", error);
+        throw error;
       }
     }
   }
+  /**
+   * Receive and process a specific message by its ID with full payload
+   * @param messageId The ID of the message to receive and process
+   * @param handler Function to process the message with full payload
+   * @returns Promise that resolves when the message is processed or rejects with specific errors
+   * @throws {MessageNotFoundError} When the message doesn't exist (404)
+   * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
+   * @throws {MessageLockedError} When the message is temporarily locked (423)
+   * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
+   * @throws {FailedDependencyError} When FIFO ordering is violated (424)
+   * @throws {MessageCorruptedError} When the message data is corrupted
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async receiveMessage(messageId, handler) {
+    const response = await this.client.receiveMessageById(
+      {
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        messageId,
+        visibilityTimeoutSeconds: this.visibilityTimeout
+      },
+      this.transport
+    );
+    await this.processMessage(response.message, handler);
+  }
+  /**
+   * Receive and process the next available message from the queue
+   * @param handler Function to process the message
+   * @returns Promise that resolves when the message is processed or rejects with specific errors
+   * @throws {QueueEmptyError} When no messages are available in the queue (204)
+   * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async receiveNextMessage(handler) {
+    let messageFound = false;
+    for await (const message of this.client.receiveMessages(
+      {
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        visibilityTimeoutSeconds: this.visibilityTimeout,
+        limit: 1
+      },
+      this.transport
+    )) {
+      messageFound = true;
+      await this.processMessage(message, handler);
+      break;
+    }
+    if (!messageFound) {
+      throw new Error("No messages available");
+    }
+  }
+  /**
+   * Receive and process multiple next available messages from the queue
+   * @param limit Number of messages to process (1-10)
+   * @param handler Function to process each message
+   * @returns Promise that resolves to an array of PromiseSettledResult (same as Promise.allSettled)
+   * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
+   * @throws {QueueEmptyError} When no messages are available in the queue (204)
+   * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async receiveNextMessages(limit, handler) {
+    if (limit < 1 || limit > 10) {
+      throw new InvalidLimitError(limit);
+    }
+    const processingPromises = [];
+    let messageCount = 0;
+    for await (const message of this.client.receiveMessages(
+      {
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        visibilityTimeoutSeconds: this.visibilityTimeout,
+        limit
+      },
+      this.transport
+    )) {
+      messageCount++;
+      const wrappedPromise = this.processMessage(message, handler).then(
+        (value) => ({
+          status: "fulfilled",
+          value
+        }),
+        (reason) => ({ status: "rejected", reason })
+      );
+      processingPromises.push(wrappedPromise);
+    }
+    if (messageCount === 0) {
+      throw new Error("No messages available");
+    }
+    const results = await Promise.all(processingPromises);
+    return results;
+  }
+  /**
+   * Handle a specific message by its ID without downloading the payload (metadata only)
+   * @param messageId The ID of the message to handle
+   * @param handler Function to process the message metadata (payload will be void)
+   * @returns Promise that resolves when the message is handled or rejects with specific errors
+   * @throws {MessageNotFoundError} When the message doesn't exist (404)
+   * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
+   * @throws {MessageLockedError} When the message is temporarily locked (423)
+   * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
+   * @throws {FailedDependencyError} When FIFO ordering is violated (424)
+   * @throws {MessageCorruptedError} When the message data is corrupted
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async handleMessage(messageId, handler) {
+    const response = await this.client.receiveMessageById(
+      {
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        messageId,
+        visibilityTimeoutSeconds: this.visibilityTimeout,
+        skipPayload: true
+      },
+      this.transport
+    );
+    await this.processMessage(response.message, handler);
+  }
   /**
    * Get the consumer group name
    */
@@ -830,7 +1186,8 @@ var Topic = class {
         queueName: this.topicName,
         payload,
         idempotencyKey: options?.idempotencyKey,
-        retentionSeconds: options?.retentionSeconds
+        retentionSeconds: options?.retentionSeconds,
+        callbacks: options?.callbacks
       },
       this.transport
     );
@@ -869,138 +1226,53 @@ var Topic = class {
 };
 
 // src/factory.ts
-async function send(topicName, payload, options) {
-  const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
-  const result = await client.sendMessage(
-    {
-      queueName: topicName,
-      payload,
-      idempotencyKey: options?.idempotencyKey,
-      retentionSeconds: options?.retentionSeconds
-    },
-    transport
-  );
-  return { messageId: result.messageId };
-}
-async function receive(topicName, consumerGroup, handler, options) {
-  const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
-  const topic = new Topic(client, topicName, transport);
-  const { messageId, skipPayload, ...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 });
-    }
-  } else {
-    return consumer.consume(handler);
-  }
+function createTopic(client, topicName, transport) {
+  return new Topic(client, topicName, transport);
 }
 
 // src/callback.ts
-async function parseCallbackRequest(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(", ")}`
+function parseCallbackRequest(request) {
+  const headers = request.headers;
+  const messageId = headers.get("Vqs-Message-Id");
+  const queueName = headers.get("Vqs-Queue-Name");
+  const consumerGroup = headers.get("Vqs-Consumer-Group");
+  const missingHeaders = [];
+  if (!messageId) missingHeaders.push("Vqs-Message-Id");
+  if (!queueName) missingHeaders.push("Vqs-Queue-Name");
+  if (!consumerGroup) missingHeaders.push("Vqs-Consumer-Group");
+  if (missingHeaders.length > 0) {
+    throw new InvalidCallbackError(
+      `Missing required queue callback headers: ${missingHeaders.join(", ")}`
     );
   }
-  const { messageId, queueName, consumerGroup } = cloudEvent.data;
   return {
+    messageId,
     queueName,
-    consumerGroup,
-    messageId
-  };
-}
-function handleCallback(handlers) {
-  return async (request) => {
-    try {
-      const { queueName, consumerGroup, messageId } = await parseCallbackRequest(request);
-      const topicHandler = handlers[queueName];
-      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 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 }
-      );
-    }
+    consumerGroup
   };
 }
 export {
   BadRequestError,
   BufferTransport,
+  ConsumerGroup,
+  FailedDependencyError,
+  FifoOrderingViolationError,
   ForbiddenError,
   InternalServerError,
+  InvalidCallbackError,
   InvalidLimitError,
   JsonTransport,
   MessageCorruptedError,
   MessageLockedError,
   MessageNotAvailableError,
   MessageNotFoundError,
+  QueueClient,
   QueueEmptyError,
   StreamTransport,
+  Topic,
   UnauthorizedError,
-  handleCallback,
-  receive,
-  send
+  createTopic,
+  getVercelOidcToken,
+  parseCallbackRequest
 };
 //# sourceMappingURL=index.mjs.map