@vercel/queue 0.0.0-alpha.9 → 0.0.2

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,45 +32,66 @@ var index_exports = {};
 __export(index_exports, {
   BadRequestError: () => BadRequestError,
   BufferTransport: () => BufferTransport,
+  CLOUD_EVENT_TYPE_V1BETA: () => CLOUD_EVENT_TYPE_V1BETA,
+  CLOUD_EVENT_TYPE_V2BETA: () => CLOUD_EVENT_TYPE_V2BETA,
+  ConsumerDiscoveryError: () => ConsumerDiscoveryError,
+  ConsumerRegistryNotConfiguredError: () => ConsumerRegistryNotConfiguredError,
+  DuplicateMessageError: () => DuplicateMessageError,
   ForbiddenError: () => ForbiddenError,
   InternalServerError: () => InternalServerError,
   InvalidLimitError: () => InvalidLimitError,
   JsonTransport: () => JsonTransport,
+  MessageAlreadyProcessedError: () => MessageAlreadyProcessedError,
   MessageCorruptedError: () => MessageCorruptedError,
   MessageLockedError: () => MessageLockedError,
   MessageNotAvailableError: () => MessageNotAvailableError,
   MessageNotFoundError: () => MessageNotFoundError,
+  QueueClient: () => QueueClient,
   QueueEmptyError: () => QueueEmptyError,
   StreamTransport: () => StreamTransport,
   UnauthorizedError: () => UnauthorizedError,
-  handleCallback: () => handleCallback,
-  receive: () => receive,
-  send: () => send
+  parseCallback: () => parseCallback,
+  parseRawCallback: () => parseRawCallback
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/transports.ts
+async function streamToBuffer(stream) {
+  let totalLength = 0;
+  const reader = stream.getReader();
+  const chunks = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalLength += value.length;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, totalLength);
+}
 var JsonTransport = class {
   contentType = "application/json";
+  replacer;
+  reviver;
+  /**
+   * Create a new JsonTransport.
+   * @param options - Optional JSON serialization options
+   * @param options.replacer - Custom replacer for JSON.stringify
+   * @param options.reviver - Custom reviver for JSON.parse
+   */
+  constructor(options = {}) {
+    this.replacer = options.replacer;
+    this.reviver = options.reviver;
+  }
   serialize(value) {
-    return Buffer.from(JSON.stringify(value), "utf8");
+    return Buffer.from(JSON.stringify(value, this.replacer), "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"));
+    const buffer = await streamToBuffer(stream);
+    return JSON.parse(buffer.toString("utf8"), this.reviver);
   }
 };
 var BufferTransport = class {
@@ -69,25 +100,7 @@ var BufferTransport = class {
     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);
+    return await streamToBuffer(stream);
   }
 };
 var StreamTransport = class {
@@ -98,6 +111,10 @@ var StreamTransport = class {
   async deserialize(stream) {
     return stream;
   }
+  /**
+   * Consume any remaining stream data to prevent resource leaks.
+   * Called automatically by ConsumerGroup; manual call required for direct client usage.
+   */
   async finalize(payload) {
     const reader = payload.getReader();
     try {
@@ -111,20 +128,12 @@ var StreamTransport = class {
   }
 };
 
-// src/client.ts
+// src/api-client.ts
 var import_mixpart = require("mixpart");
 
-// src/oidc.ts
-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;
-  }
-  return token;
-}
+// src/dev.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
 
 // src/types.ts
 var MessageNotFoundError = class extends Error {
@@ -156,6 +165,7 @@ var QueueEmptyError = class extends Error {
   }
 };
 var MessageLockedError = class extends Error {
+  /** Suggested retry delay in seconds, if provided by the server. */
   retryAfter;
   constructor(messageId, retryAfter) {
     const retryMessage = retryAfter ? ` Retry after ${retryAfter} seconds.` : " Try again later.";
@@ -194,635 +204,305 @@ var InvalidLimitError = class extends Error {
     this.name = "InvalidLimitError";
   }
 };
-
-// src/client.ts
-async function consumeStream(stream) {
-  const reader = stream.getReader();
-  try {
-    while (true) {
-      const { done } = await reader.read();
-      if (done) break;
-    }
-  } finally {
-    reader.releaseLock();
+var MessageAlreadyProcessedError = class extends Error {
+  constructor(messageId) {
+    super(`Message ${messageId} has already been processed`);
+    this.name = "MessageAlreadyProcessedError";
   }
-}
-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) {
-    return null;
+};
+var DuplicateMessageError = class extends Error {
+  idempotencyKey;
+  constructor(message, idempotencyKey) {
+    super(message);
+    this.name = "DuplicateMessageError";
+    this.idempotencyKey = idempotencyKey;
   }
-  const deliveryCount = parseInt(deliveryCountStr, 10);
-  if (isNaN(deliveryCount)) {
-    return null;
+};
+var ConsumerDiscoveryError = class extends Error {
+  deploymentId;
+  constructor(message, deploymentId) {
+    super(message);
+    this.name = "ConsumerDiscoveryError";
+    this.deploymentId = deploymentId;
   }
-  return {
-    messageId,
-    deliveryCount,
-    timestamp,
-    contentType,
-    ticket
-  };
+};
+var ConsumerRegistryNotConfiguredError = class extends Error {
+  constructor(message = "Consumer registry not configured") {
+    super(message);
+    this.name = "ConsumerRegistryNotConfiguredError";
+  }
+};
+
+// src/consumer-group.ts
+var DEFAULT_VISIBILITY_TIMEOUT_SECONDS = 300;
+var MIN_VISIBILITY_TIMEOUT_SECONDS = 30;
+var MAX_RENEWAL_INTERVAL_SECONDS = 60;
+var MIN_RENEWAL_INTERVAL_SECONDS = 10;
+var RETRY_INTERVAL_MS = 3e3;
+function calculateRenewalInterval(visibilityTimeoutSeconds) {
+  return Math.min(
+    MAX_RENEWAL_INTERVAL_SECONDS,
+    Math.max(MIN_RENEWAL_INTERVAL_SECONDS, visibilityTimeoutSeconds / 5)
+  );
 }
-var QueueClient = class {
-  baseUrl;
-  basePath;
-  token;
+var ConsumerGroup = class {
+  client;
+  topicName;
+  consumerGroupName;
+  visibilityTimeout;
   /**
-   * Create a new Vercel Queue Service client
-   * @param options Client configuration options (optional - will auto-detect Vercel Function environment)
+   * Create a new ConsumerGroup instance.
+   *
+   * @param client - ApiClient instance to use for API calls (transport is configured on the client)
+   * @param topicName - Name of the topic to consume from (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroupName - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param options - Optional configuration
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
    */
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl || "https://api.vercel.com";
-    this.basePath = options.basePath || "/v1/queue/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(client, topicName, consumerGroupName, options = {}) {
+    this.client = client;
+    this.topicName = topicName;
+    this.consumerGroupName = consumerGroupName;
+    this.visibilityTimeout = Math.max(
+      MIN_VISIBILITY_TIMEOUT_SECONDS,
+      options.visibilityTimeoutSeconds ?? DEFAULT_VISIBILITY_TIMEOUT_SECONDS
+    );
   }
   /**
-   * 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
+   * Check if an error is a 4xx client error that should stop retries.
+   * 4xx errors indicate the request is fundamentally invalid and retrying won't help.
+   * - 409: Ticket mismatch (lost ownership to another consumer)
+   * - 404: Message/receipt handle not found
+   * - 400, 401, 403: Other client errors
    */
-  async sendMessage(options, transport) {
-    const { queueName, payload, idempotencyKey, retentionSeconds } = 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());
-    }
-    const body = transport.serialize(payload);
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
-      method: "POST",
-      headers,
-      body
-    });
-    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 === 409) {
-        throw new Error("Duplicate idempotency key detected");
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
-        );
-      }
-      throw new Error(
-        `Failed to send message: ${response.status} ${response.statusText}`
-      );
-    }
-    const responseData = await response.json();
-    return responseData;
+  isClientError(error) {
+    return error instanceof MessageNotAvailableError || // 409 - ticket mismatch, lost ownership
+    error instanceof MessageNotFoundError || // 404 - receipt handle not found
+    error instanceof BadRequestError || // 400 - invalid parameters
+    error instanceof UnauthorizedError || // 401 - auth failed
+    error instanceof ForbiddenError;
   }
   /**
-   * 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
+   * Starts a background loop that periodically extends the visibility timeout for a message.
+   *
+   * Timing strategy:
+   * - Renewal interval: min(60s, max(10s, visibilityTimeout/5))
+   * - Extensions request the same duration as the initial visibility timeout
+   * - When `visibilityDeadline` is provided (binary mode small body), the first
+   *   extension delay is calculated from the time remaining until the deadline
+   *   using the same renewal formula, ensuring the first extension fires before
+   *   the server-assigned lease expires. Subsequent renewals use the standard interval.
+   *
+   * Retry strategy:
+   * - On transient failures (5xx, network errors): retry every 3 seconds
+   * - On 4xx client errors: stop retrying (the lease is lost or invalid)
+   *
+   * @param receiptHandle - The receipt handle to extend visibility for
+   * @param options - Optional configuration
+   * @param options.visibilityDeadline - Absolute deadline (from server's `ce-vqsvisibilitydeadline`)
+   *   when the current visibility timeout expires. Used to calculate the first extension delay.
    */
-  async *receiveMessages(options, transport) {
-    const { queueName, consumerGroup, visibilityTimeoutSeconds, limit } = options;
-    if (limit !== void 0 && (limit < 1 || limit > 10)) {
-      throw new InvalidLimitError(limit);
-    }
-    const headers = new Headers({
-      Authorization: `Bearer ${this.token}`,
-      "Vqs-Queue-Name": queueName,
-      "Vqs-Consumer-Group": consumerGroup,
-      Accept: "multipart/mixed"
-    });
-    if (visibilityTimeoutSeconds !== void 0) {
-      headers.set(
-        "Vqs-Visibility-Timeout",
-        visibilityTimeoutSeconds.toString()
-      );
-    }
-    if (limit !== void 0) {
-      headers.set("Vqs-Limit", limit.toString());
+  startVisibilityExtension(receiptHandle, options) {
+    let isRunning = true;
+    let isResolved = false;
+    let resolveLifecycle;
+    let timeoutId = null;
+    const renewalIntervalMs = calculateRenewalInterval(this.visibilityTimeout) * 1e3;
+    let firstDelayMs = renewalIntervalMs;
+    if (options?.visibilityDeadline) {
+      const timeRemainingMs = options.visibilityDeadline.getTime() - Date.now();
+      if (timeRemainingMs > 0) {
+        const timeRemainingSeconds = timeRemainingMs / 1e3;
+        firstDelayMs = calculateRenewalInterval(timeRemainingSeconds) * 1e3;
+      } else {
+        firstDelayMs = 0;
+      }
     }
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
-      method: "GET",
-      headers
+    const lifecyclePromise = new Promise((resolve) => {
+      resolveLifecycle = resolve;
     });
-    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();
+    const safeResolve = () => {
+      if (!isResolved) {
+        isResolved = true;
+        resolveLifecycle();
       }
-      if (response.status === 403) {
-        throw new ForbiddenError();
+    };
+    const extend = async () => {
+      if (!isRunning) {
+        safeResolve();
+        return;
       }
-      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;
+      try {
+        await this.client.changeVisibility({
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          receiptHandle,
+          visibilityTimeoutSeconds: this.visibilityTimeout
+        });
+        if (isRunning) {
+          timeoutId = setTimeout(() => extend(), renewalIntervalMs);
+        } else {
+          safeResolve();
         }
-        throw new MessageLockedError("next message", retryAfter);
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+      } catch (error) {
+        if (this.isClientError(error)) {
+          console.error(
+            `Visibility extension failed with client error for receipt handle ${receiptHandle} (stopping retries):`,
+            error
+          );
+          safeResolve();
+          return;
+        }
+        console.error(
+          `Failed to extend visibility for receipt handle ${receiptHandle} (will retry in ${RETRY_INTERVAL_MS / 1e3}s):`,
+          error
         );
+        if (isRunning) {
+          timeoutId = setTimeout(() => extend(), RETRY_INTERVAL_MS);
+        } else {
+          safeResolve();
+        }
       }
-      throw new Error(
-        `Failed to receive messages: ${response.status} ${response.statusText}`
-      );
-    }
-    for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
+    };
+    timeoutId = setTimeout(() => extend(), firstDelayMs);
+    return async (waitForCompletion = false) => {
+      isRunning = false;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      if (waitForCompletion) {
+        await lifecyclePromise;
+      } else {
+        safeResolve();
+      }
+    };
+  }
+  /**
+   * Clean up the message payload if the transport supports it and payload exists.
+   */
+  async finalizePayload(payload) {
+    const transport = this.client.getTransport();
+    if (transport.finalize && payload !== void 0 && payload !== null) {
       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
-        };
-        yield message;
-      } catch (error) {
-        console.warn("Failed to process multipart message:", error);
-        await consumeStream(multipartMessage.payload);
+        await transport.finalize(payload);
+      } catch (finalizeError) {
+        console.warn("Failed to finalize message payload:", finalizeError);
       }
     }
   }
-  async receiveMessageById(options, transport) {
-    const {
-      queueName,
-      consumerGroup,
-      messageId,
-      visibilityTimeoutSeconds,
-      skipPayload
-    } = options;
-    const headers = new Headers({
-      Authorization: `Bearer ${this.token}`,
-      "Vqs-Queue-Name": queueName,
-      "Vqs-Consumer-Group": consumerGroup,
-      Accept: "multipart/mixed"
-    });
-    if (visibilityTimeoutSeconds !== void 0) {
-      headers.set(
-        "Vqs-Visibility-Timeout",
-        visibilityTimeoutSeconds.toString()
-      );
-    }
-    if (skipPayload) {
-      headers.set("Vqs-Skip-Payload", "1");
-    }
-    const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
-      {
-        method: "GET",
-        headers
-      }
+  async processMessage(message, handler, options) {
+    const stopExtension = this.startVisibilityExtension(
+      message.receiptHandle,
+      options
     );
-    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 === 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;
+    const metadata = {
+      messageId: message.messageId,
+      deliveryCount: message.deliveryCount,
+      createdAt: message.createdAt,
+      expiresAt: message.expiresAt,
+      topicName: this.topicName,
+      consumerGroup: this.consumerGroupName,
+      region: this.client.getRegion()
+    };
+    try {
+      await handler(message.payload, metadata);
+      await stopExtension();
+      await this.client.acknowledgeMessage({
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        receiptHandle: message.receiptHandle
+      });
+    } catch (error) {
+      await stopExtension();
+      if (options?.retry) {
+        let directive;
+        try {
+          directive = options.retry(error, metadata);
+        } catch (retryError) {
+          console.warn("retry handler threw:", retryError);
+        }
+        if (directive) {
+          if ("acknowledge" in directive && directive.acknowledge) {
+            try {
+              await this.client.acknowledgeMessage({
+                queueName: this.topicName,
+                consumerGroup: this.consumerGroupName,
+                receiptHandle: message.receiptHandle
+              });
+            } catch (ackError) {
+              console.warn("Failed to acknowledge message:", ackError);
+            }
+            await this.finalizePayload(message.payload);
+            return;
+          }
+          if ("afterSeconds" in directive && typeof directive.afterSeconds === "number") {
+            try {
+              await this.client.changeVisibility({
+                queueName: this.topicName,
+                consumerGroup: this.consumerGroupName,
+                receiptHandle: message.receiptHandle,
+                visibilityTimeoutSeconds: directive.afterSeconds
+              });
+            } catch (changeError) {
+              console.warn(
+                "Failed to reschedule message for retry:",
+                changeError
+              );
+            }
+            await this.finalizePayload(message.payload);
+            return;
+          }
         }
-        throw new MessageLockedError(messageId, retryAfter);
-      }
-      if (response.status === 409) {
-        throw new MessageNotAvailableError(messageId);
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
-        );
       }
-      throw new Error(
-        `Failed to receive message by ID: ${response.status} ${response.statusText}`
-      );
+      await this.finalizePayload(message.payload);
+      throw error;
     }
-    if (skipPayload && response.status === 204) {
-      const parsedHeaders = parseQueueHeaders(response.headers);
-      if (!parsedHeaders) {
-        throw new MessageCorruptedError(
-          messageId,
-          "Missing required queue headers in 204 response"
-        );
-      }
-      const message = {
-        ...parsedHeaders,
-        payload: void 0
-      };
-      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)}`,
-      {
-        method: "DELETE",
-        headers: new Headers({
-          Authorization: `Bearer ${this.token}`,
-          "Vqs-Queue-Name": queueName,
-          "Vqs-Consumer-Group": consumerGroup,
-          "Vqs-Ticket": ticket
-        })
-      }
-    );
-    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();
-      }
-      if (response.status === 404) {
-        throw new MessageNotFoundError(messageId);
-      }
-      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}`
-        );
-      }
-      throw new Error(
-        `Failed to delete message: ${response.status} ${response.statusText}`
-      );
-    }
-    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,
-      visibilityTimeoutSeconds
-    } = options;
-    const response = await fetch(
-      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
-      {
-        method: "PATCH",
-        headers: new Headers({
-          Authorization: `Bearer ${this.token}`,
-          "Vqs-Queue-Name": queueName,
-          "Vqs-Consumer-Group": consumerGroup,
-          "Vqs-Ticket": ticket,
-          "Vqs-Visibility-Timeout": visibilityTimeoutSeconds.toString()
-        })
-      }
-    );
-    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();
-      }
-      if (response.status === 404) {
-        throw new MessageNotFoundError(messageId);
-      }
-      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}`
-        );
-      }
-      throw new Error(
-        `Failed to change visibility: ${response.status} ${response.statusText}`
-      );
-    }
-    return { updated: true };
-  }
-};
-
-// src/consumer-group.ts
-var ConsumerGroup = class {
-  client;
-  topicName;
-  consumerGroupName;
-  visibilityTimeout;
-  refreshInterval;
-  transport;
-  /**
-   * Create a new ConsumerGroup instance
-   * @param client QueueClient instance to use for API calls
-   * @param topicName Name of the topic to consume from
-   * @param consumerGroupName Name of the consumer group
-   * @param options Optional configuration
-   */
-  constructor(client, topicName, consumerGroupName, options = {}) {
-    this.client = client;
-    this.topicName = topicName;
-    this.consumerGroupName = consumerGroupName;
-    this.visibilityTimeout = options.visibilityTimeoutSeconds || 30;
-    this.refreshInterval = options.refreshInterval || 10;
-    this.transport = options.transport || new JsonTransport();
   }
   /**
-   * Starts a background loop that periodically extends the visibility timeout for a message.
-   * This prevents the message from becoming visible to other consumers while it's being processed.
+   * Process a pre-fetched message directly, without calling `receiveMessageById`.
    *
-   * The extension loop runs every `refreshInterval` seconds and updates the message's
-   * visibility timeout to `visibilityTimeout` seconds from the current time.
+   * Used by the binary mode (v2beta) small body fast path, where the server
+   * pushes the full message payload in the callback request. The message is
+   * processed with the same lifecycle guarantees as `consume()`:
+   * - Visibility timeout is extended periodically during processing
+   * - Message is acknowledged on successful handler completion
+   * - Payload is finalized on error if the transport supports it
    *
-   * @param messageId - The unique identifier of the message to extend visibility for
-   * @param ticket - The receipt ticket that proves ownership of the message
-   * @returns A function that when called will stop the extension loop
-   *
-   * @remarks
-   * - The first extension attempt occurs after `refreshInterval` seconds, not immediately
-   * - If an extension fails, the loop terminates with an error logged to console
-   * - The returned stop function is idempotent - calling it multiple times is safe
-   * - 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) {
-    let isRunning = true;
-    let resolveLifecycle;
-    let timeoutId = null;
-    const lifecyclePromise = new Promise((resolve) => {
-      resolveLifecycle = resolve;
-    });
-    const extend = async () => {
-      if (!isRunning) {
-        resolveLifecycle();
-        return;
-      }
-      try {
-        await this.client.changeVisibility({
-          queueName: this.topicName,
-          consumerGroup: this.consumerGroupName,
-          messageId,
-          ticket,
-          visibilityTimeoutSeconds: this.visibilityTimeout
-        });
-        if (isRunning) {
-          timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
-        } else {
-          resolveLifecycle();
-        }
-      } catch (error) {
-        console.error(
-          `Failed to extend visibility for message ${messageId}:`,
-          error
-        );
-        resolveLifecycle();
-      }
-    };
-    timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
-    return async (waitForCompletion = false) => {
-      isRunning = false;
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        timeoutId = null;
-      }
-      if (waitForCompletion) {
-        await lifecyclePromise;
-      } else {
-        resolveLifecycle();
-      }
-    };
-  }
-  /**
-   * Process a single message with the given handler
-   * @param message The message to process
-   * @param handler Function to process the message
+   * @param handler - Function to process the message payload and metadata
+   * @param message - The complete message including payload and receipt handle
+   * @param options - Optional configuration
+   * @param options.visibilityDeadline - Absolute deadline when the server-assigned
+   *   visibility timeout expires (from `ce-vqsvisibilitydeadline`). Used to
+   *   schedule the first visibility extension before the lease expires.
    */
-  async processMessage(message, handler) {
-    const stopExtension = this.startVisibilityExtension(
-      message.messageId,
-      message.ticket
-    );
-    try {
-      const result = await handler(message.payload, {
-        messageId: message.messageId,
-        deliveryCount: message.deliveryCount,
-        timestamp: message.timestamp
-      });
-      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
-        });
-      } else {
-        await this.client.deleteMessage({
-          queueName: this.topicName,
-          consumerGroup: this.consumerGroupName,
-          messageId: message.messageId,
-          ticket: message.ticket
-        });
-      }
-    } catch (error) {
-      await stopExtension();
-      if (this.transport.finalize && message.payload !== void 0 && message.payload !== null) {
-        try {
-          await this.transport.finalize(message.payload);
-        } catch (finalizeError) {
-          console.warn("Failed to finalize message payload:", finalizeError);
-        }
-      }
-      throw error;
-    }
+  async consumeMessage(handler, message, options) {
+    await this.processMessage(message, handler, options);
   }
   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 retry = options?.retry;
+    if (options && "messageId" in options) {
+      const response = await this.client.receiveMessageById({
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        messageId: options.messageId,
+        visibilityTimeoutSeconds: this.visibilityTimeout
+      });
+      await this.processMessage(response.message, handler, { retry });
+      return 1;
     } 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");
+      const limit = options && "limit" in options ? options.limit : 1;
+      let messagesProcessed = 0;
+      for await (const message of this.client.receiveMessages({
+        queueName: this.topicName,
+        consumerGroup: this.consumerGroupName,
+        visibilityTimeoutSeconds: this.visibilityTimeout,
+        limit
+      })) {
+        messagesProcessed++;
+        await this.processMessage(message, handler, { retry });
       }
+      return messagesProcessed;
     }
   }
   /**
@@ -843,38 +523,40 @@ var ConsumerGroup = class {
 var Topic = class {
   client;
   topicName;
-  transport;
   /**
-   * Create a new Topic instance
-   * @param client QueueClient instance to use for API calls
+   * @param client ApiClient instance to use for API calls
    * @param topicName Name of the topic to work with
-   * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
    */
-  constructor(client, topicName, transport) {
+  constructor(client, topicName) {
     this.client = client;
     this.topicName = topicName;
-    this.transport = transport || new JsonTransport();
   }
   /**
    * Publish a message to the topic
    * @param payload The data to publish
    * @param options Optional publish options
-   * @returns An object containing the message ID
+   * @returns `{ messageId }` — `messageId` is `null` when deferred
    * @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 publish(payload, options) {
-    const result = await this.client.sendMessage(
-      {
-        queueName: this.topicName,
-        payload,
-        idempotencyKey: options?.idempotencyKey,
-        retentionSeconds: options?.retentionSeconds
-      },
-      this.transport
-    );
+    const result = await this.client.sendMessage({
+      queueName: this.topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds,
+      delaySeconds: options?.delaySeconds,
+      headers: options?.headers
+    });
+    if (result.messageId && isDevMode()) {
+      triggerDevCallbacks(
+        this.topicName,
+        result.messageId,
+        this.client.getRegion()
+      );
+    }
     return { messageId: result.messageId };
   }
   /**
@@ -884,15 +566,11 @@ var Topic = class {
    * @returns A ConsumerGroup instance
    */
   consumerGroup(consumerGroupName, options) {
-    const consumerOptions = {
-      ...options,
-      transport: options?.transport || this.transport
-    };
     return new ConsumerGroup(
       this.client,
       this.topicName,
       consumerGroupName,
-      consumerOptions
+      options
     );
   }
   /**
@@ -901,148 +579,1124 @@ var Topic = class {
   get name() {
     return this.topicName;
   }
-  /**
-   * Get the transport used by this topic
-   */
-  get serializer() {
-    return this.transport;
-  }
 };
 
-// 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 };
+// src/callback.ts
+var CLOUD_EVENT_TYPE_V1BETA = "com.vercel.queue.v1beta";
+var CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta";
+function matchesWildcardPattern(topicName, pattern) {
+  const prefix = pattern.slice(0, -1);
+  return topicName.startsWith(prefix);
 }
-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 isRecord(value) {
+  return typeof value === "object" && value !== null;
 }
-
-// src/callback.ts
-async function parseCallbackRequest(request) {
-  const contentType = request.headers.get("content-type");
+function parseV1StructuredBody(body, contentType) {
   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) {
+  if (!isRecord(body) || !body.type || !body.source || !body.id || !isRecord(body.data)) {
     throw new Error("Invalid CloudEvent: missing required fields");
   }
-  if (cloudEvent.type !== "com.vercel.queue.v1beta") {
+  if (body.type !== CLOUD_EVENT_TYPE_V1BETA) {
     throw new Error(
-      `Invalid CloudEvent type: expected 'com.vercel.queue.v1beta', got '${cloudEvent.type}'`
+      `Invalid CloudEvent type: expected '${CLOUD_EVENT_TYPE_V1BETA}', got '${String(body.type)}'`
     );
   }
+  const { data } = body;
   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 (!("queueName" in data)) missingFields.push("queueName");
+  if (!("consumerGroup" in data)) missingFields.push("consumerGroup");
+  if (!("messageId" in 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: String(data.queueName),
+    consumerGroup: String(data.consumerGroup),
+    messageId: String(data.messageId)
+  };
+}
+function getHeader(headers, name) {
+  if (headers instanceof Headers) {
+    return headers.get(name);
+  }
+  const value = headers[name];
+  if (Array.isArray(value)) return value[0] ?? null;
+  return value ?? null;
+}
+function parseBinaryHeaders(headers) {
+  const ceType = getHeader(headers, "ce-type");
+  if (ceType !== CLOUD_EVENT_TYPE_V2BETA) {
+    throw new Error(
+      `Invalid CloudEvent type: expected '${CLOUD_EVENT_TYPE_V2BETA}', got '${ceType}'`
+    );
+  }
+  const queueName = getHeader(headers, "ce-vqsqueuename");
+  const consumerGroup = getHeader(headers, "ce-vqsconsumergroup");
+  const messageId = getHeader(headers, "ce-vqsmessageid");
+  const missingFields = [];
+  if (!queueName) missingFields.push("ce-vqsqueuename");
+  if (!consumerGroup) missingFields.push("ce-vqsconsumergroup");
+  if (!messageId) missingFields.push("ce-vqsmessageid");
+  if (missingFields.length > 0) {
+    throw new Error(
+      `Missing required CloudEvent headers: ${missingFields.join(", ")}`
+    );
+  }
+  const region = getHeader(headers, "ce-vqsregion") ?? void 0;
+  const base = {
     queueName,
     consumerGroup,
-    messageId
+    messageId,
+    region
   };
+  const receiptHandle = getHeader(headers, "ce-vqsreceipthandle");
+  if (!receiptHandle) {
+    return base;
+  }
+  const result = { ...base, receiptHandle };
+  const deliveryCount = getHeader(headers, "ce-vqsdeliverycount");
+  if (deliveryCount) {
+    result.deliveryCount = parseInt(deliveryCount, 10);
+  }
+  const createdAt = getHeader(headers, "ce-vqscreatedat");
+  if (createdAt) {
+    result.createdAt = createdAt;
+  }
+  const expiresAt = getHeader(headers, "ce-vqsexpiresat");
+  if (expiresAt) {
+    result.expiresAt = expiresAt;
+  }
+  const contentType = getHeader(headers, "content-type");
+  if (contentType) {
+    result.contentType = contentType;
+  }
+  const visibilityDeadline = getHeader(headers, "ce-vqsvisibilitydeadline");
+  if (visibilityDeadline) {
+    result.visibilityDeadline = visibilityDeadline;
+  }
+  return result;
 }
-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 }
-      );
+function parseRawCallback(body, headers) {
+  const ceType = getHeader(headers, "ce-type");
+  if (ceType === CLOUD_EVENT_TYPE_V2BETA) {
+    const result = parseBinaryHeaders(headers);
+    if ("receiptHandle" in result) {
+      result.parsedPayload = body;
     }
-  };
+    return result;
+  }
+  return parseV1StructuredBody(body, getHeader(headers, "content-type"));
+}
+async function parseCallback(request) {
+  const ceType = request.headers.get("ce-type");
+  if (ceType === CLOUD_EVENT_TYPE_V2BETA) {
+    const result = parseBinaryHeaders(request.headers);
+    if ("receiptHandle" in result && request.body) {
+      result.rawBody = request.body;
+    }
+    return result;
+  }
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    throw new Error("Failed to parse CloudEvent from request body");
+  }
+  const headers = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  return parseRawCallback(body, headers);
 }
+async function handleCallback(handler, request, options) {
+  const { queueName, consumerGroup, messageId } = request;
+  if (!options?.client) {
+    throw new Error("HandleCallbackOptions.client is required");
+  }
+  let api = getApiClient(options.client);
+  if (request.region) {
+    api = api.withRegion(request.region);
+  }
+  const topic = new Topic(api, queueName);
+  const cg = topic.consumerGroup(
+    consumerGroup,
+    options?.visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds: options.visibilityTimeoutSeconds } : void 0
+  );
+  if ("receiptHandle" in request) {
+    const transport = api.getTransport();
+    let payload;
+    if (request.rawBody) {
+      payload = await transport.deserialize(request.rawBody);
+    } else if (request.parsedPayload !== void 0) {
+      payload = request.parsedPayload;
+    } else {
+      throw new Error(
+        "Binary mode callback with receipt handle is missing payload"
+      );
+    }
+    const message = {
+      messageId,
+      payload,
+      deliveryCount: request.deliveryCount ?? 1,
+      createdAt: request.createdAt ? new Date(request.createdAt) : /* @__PURE__ */ new Date(),
+      expiresAt: request.expiresAt ? new Date(request.expiresAt) : void 0,
+      contentType: request.contentType ?? transport.contentType,
+      receiptHandle: request.receiptHandle
+    };
+    const visibilityDeadline = request.visibilityDeadline ? new Date(request.visibilityDeadline) : void 0;
+    await cg.consumeMessage(handler, message, {
+      visibilityDeadline,
+      retry: options?.retry
+    });
+  } else {
+    await cg.consume(handler, { messageId, retry: options?.retry });
+  }
+}
+
+// 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|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
+  if (!urlPath.startsWith("/")) {
+    urlPath = "/" + urlPath;
+  }
+  return urlPath;
+}
+function filePathToConsumerGroup(filePath) {
+  return filePath.replace(/_/g, "__").replace(/\//g, "_S").replace(/\./g, "_D");
+}
+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) {
+          mappings.push({
+            urlPath: filePathToUrlPath(filePath),
+            topic: trigger.topic,
+            consumer: filePathToConsumerGroup(filePath)
+          });
+        }
+      }
+    }
+    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, region) {
+  const client = new ApiClient({ region });
+  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
+      });
+      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, region, delaySeconds) {
+  if (delaySeconds && delaySeconds > 0) {
+    console.log(
+      `[Dev Mode] Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
+    );
+    setTimeout(() => {
+      triggerDevCallbacks(topicName, messageId, region);
+    }, 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,
+      region
+    );
+    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}"`
+      );
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "ce-type": CLOUD_EVENT_TYPE_V2BETA,
+            "ce-vqsqueuename": topicName,
+            "ce-vqsconsumergroup": route.consumer,
+            "ce-vqsmessageid": messageId,
+            "ce-vqsregion": region
+          }
+        });
+        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/api-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 {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  } finally {
+    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 receiptHandle = headers.get("Vqs-Receipt-Handle");
+  if (!messageId || !timestamp || !receiptHandle) {
+    return null;
+  }
+  const deliveryCount = parseInt(deliveryCountStr, 10);
+  if (Number.isNaN(deliveryCount)) {
+    return null;
+  }
+  return {
+    messageId,
+    deliveryCount,
+    createdAt: new Date(timestamp),
+    contentType,
+    receiptHandle
+  };
+}
+var DEFAULT_BASE_URL_RESOLVER = (region) => new URL(`https://${region}.vercel-queue.com`);
+function resolveBaseUrl(region, resolver) {
+  return (resolver ?? DEFAULT_BASE_URL_RESOLVER)(region);
+}
+var BASE_PATH = "/api/v3/topic";
+var ApiClient = class _ApiClient {
+  baseUrl;
+  customHeaders;
+  providedToken;
+  resolvedDeploymentId;
+  pinSends;
+  explicitlyUnpinned;
+  transport;
+  region;
+  baseUrlResolver;
+  constructor(options) {
+    this.region = options.region;
+    this.baseUrlResolver = options.resolveBaseUrl;
+    this.baseUrl = resolveBaseUrl(this.region, this.baseUrlResolver);
+    this.customHeaders = options.headers || {};
+    this.providedToken = options.token;
+    this.transport = options.transport || new JsonTransport();
+    if (options.deploymentId === null) {
+      this.pinSends = false;
+      this.explicitlyUnpinned = true;
+    } else {
+      this.resolvedDeploymentId = options.deploymentId || process.env.VERCEL_DEPLOYMENT_ID;
+      this.pinSends = true;
+      this.explicitlyUnpinned = false;
+    }
+  }
+  /**
+   * Return a new ApiClient targeting the given region, sharing all other
+   * configuration (token, transport, headers, deployment ID, resolver).
+   * Used internally by handleCallback to route follow-up API calls to the
+   * region indicated by the incoming `ce-vqsregion` header.
+   */
+  withRegion(region) {
+    return new _ApiClient({
+      region,
+      resolveBaseUrl: this.baseUrlResolver,
+      token: this.providedToken,
+      headers: { ...this.customHeaders },
+      deploymentId: this.explicitlyUnpinned ? null : this.resolvedDeploymentId,
+      transport: this.transport
+    });
+  }
+  getRegion() {
+    return this.region;
+  }
+  getTransport() {
+    return this.transport;
+  }
+  requireDeploymentId() {
+    if (isDevMode() || this.explicitlyUnpinned || this.resolvedDeploymentId) {
+      return;
+    }
+    throw new Error(
+      'No deployment ID available. VERCEL_DEPLOYMENT_ID is not set.\n\nThis usually means the code is running outside a Vercel deployment (e.g. during build or in a non-Vercel environment).\n\nTo fix this, create a new QueueClient with an explicit deploymentId:\n  new QueueClient({ region: "iad1", deploymentId: "dpl_xxx" })\nOr explicitly opt out of deployment pinning:\n  new QueueClient({ region: "iad1", deploymentId: null })'
+    );
+  }
+  getSendDeploymentId() {
+    if (isDevMode()) {
+      return void 0;
+    }
+    this.requireDeploymentId();
+    return this.pinSends ? this.resolvedDeploymentId : void 0;
+  }
+  getConsumeDeploymentId() {
+    if (isDevMode()) {
+      return void 0;
+    }
+    this.requireDeploymentId();
+    return this.resolvedDeploymentId;
+  }
+  async getToken() {
+    if (this.providedToken) {
+      return this.providedToken;
+    }
+    const token = await (0, import_oidc.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'"
+      );
+    }
+    return token;
+  }
+  buildUrl(queueName, ...pathSegments) {
+    const encodedQueue = encodeURIComponent(queueName);
+    const segments = pathSegments.map((s) => encodeURIComponent(s));
+    const path2 = segments.length > 0 ? "/" + segments.join("/") : "";
+    const basePath = this.baseUrl.pathname.replace(/\/+$/, "");
+    return `${this.baseUrl.origin}${basePath}${BASE_PATH}/${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));
+    }
+    init.headers.set("User-Agent", `@vercel/queue/${"0.0.2"}`);
+    init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
+    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) {
+    const transport = this.transport;
+    const {
+      queueName,
+      payload,
+      idempotencyKey,
+      retentionSeconds,
+      delaySeconds,
+      headers: optionHeaders
+    } = options;
+    const headers = new Headers();
+    if (this.customHeaders) {
+      for (const [name, value] of Object.entries(this.customHeaders)) {
+        headers.append(name, value);
+      }
+    }
+    if (optionHeaders) {
+      const protectedHeaderNames = /* @__PURE__ */ new Set(["authorization", "content-type"]);
+      const isProtectedHeader = (name) => {
+        const lower = name.toLowerCase();
+        if (protectedHeaderNames.has(lower)) return true;
+        return lower.startsWith("vqs-");
+      };
+      for (const [name, value] of Object.entries(optionHeaders)) {
+        if (!isProtectedHeader(name) && value !== void 0) {
+          headers.append(name, value);
+        }
+      }
+    }
+    headers.set("Authorization", `Bearer ${await this.getToken()}`);
+    headers.set("Content-Type", transport.contentType);
+    const deploymentId = this.getSendDeploymentId();
+    if (deploymentId) {
+      headers.set("Vqs-Deployment-Id", deploymentId);
+    }
+    if (idempotencyKey) {
+      headers.set("Vqs-Idempotency-Key", idempotencyKey);
+    }
+    if (retentionSeconds !== void 0) {
+      headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
+    }
+    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) {
+      const errorText = await response.text();
+      if (response.status === 409) {
+        throw new DuplicateMessageError(
+          errorText || "Duplicate idempotency key detected",
+          idempotencyKey
+        );
+      }
+      if (response.status === 502) {
+        throw new ConsumerDiscoveryError(
+          errorText || "Consumer discovery failed",
+          deploymentId
+        );
+      }
+      if (response.status === 503) {
+        throw new ConsumerRegistryNotConfiguredError(
+          errorText || "Consumer registry not configured"
+        );
+      }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "send message"
+      );
+    }
+    if (response.status === 202) {
+      return { messageId: null };
+    }
+    const responseData = await response.json();
+    return responseData;
+  }
+  async *receiveMessages(options) {
+    const transport = this.transport;
+    const { queueName, consumerGroup, visibilityTimeoutSeconds, limit } = options;
+    if (limit !== void 0 && (limit < 1 || limit > 10)) {
+      throw new InvalidLimitError(limit);
+    }
+    const headers = new Headers({
+      Authorization: `Bearer ${await this.getToken()}`,
+      Accept: "multipart/mixed",
+      ...this.customHeaders
+    });
+    if (visibilityTimeoutSeconds !== void 0) {
+      headers.set(
+        "Vqs-Visibility-Timeout-Seconds",
+        visibilityTimeoutSeconds.toString()
+      );
+    }
+    if (limit !== void 0) {
+      headers.set("Vqs-Max-Messages", limit.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) {
+      return;
+    }
+    if (!response.ok) {
+      const errorText = await response.text();
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive messages"
+      );
+    }
+    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
+        };
+        yield message;
+      } catch (error) {
+        console.warn("Failed to process multipart message:", error);
+        await consumeStream(multipartMessage.payload);
+      }
+    }
+  }
+  async receiveMessageById(options) {
+    const transport = this.transport;
+    const { queueName, consumerGroup, messageId, visibilityTimeoutSeconds } = options;
+    const headers = new Headers({
+      Authorization: `Bearer ${await this.getToken()}`,
+      Accept: "multipart/mixed",
+      ...this.customHeaders
+    });
+    if (visibilityTimeoutSeconds !== void 0) {
+      headers.set(
+        "Vqs-Visibility-Timeout-Seconds",
+        visibilityTimeoutSeconds.toString()
+      );
+    }
+    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: "POST",
+        headers
+      }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 404) {
+        throw new MessageNotFoundError(messageId);
+      }
+      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 === 410) {
+        throw new MessageAlreadyProcessedError(messageId);
+      }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive message by ID"
+      );
+    }
+    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 response"
+        );
+      }
+      const deserializedPayload = await transport.deserialize(
+        multipartMessage.payload
+      );
+      const message = {
+        ...parsedHeaders,
+        payload: deserializedPayload
+      };
+      return { message };
+    }
+    throw new MessageNotFoundError(messageId);
+  }
+  async acknowledgeMessage(options) {
+    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
+      }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 404) {
+        throw new MessageNotFoundError(receiptHandle);
+      }
+      if (response.status === 409) {
+        throw new MessageNotAvailableError(
+          receiptHandle,
+          errorText || "Invalid receipt handle, message not in correct state, or already processed"
+        );
+      }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "acknowledge message",
+        "Missing or invalid receipt handle"
+      );
+    }
+    return { acknowledged: true };
+  }
+  async changeVisibility(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);
+    }
+    const response = await this.fetch(
+      this.buildUrl(
+        queueName,
+        "consumer",
+        consumerGroup,
+        "lease",
+        receiptHandle
+      ),
+      {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ visibilityTimeoutSeconds })
+      }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 404) {
+        throw new MessageNotFoundError(receiptHandle);
+      }
+      if (response.status === 409) {
+        throw new MessageNotAvailableError(
+          receiptHandle,
+          errorText || "Invalid receipt handle, message not in correct state, or already processed"
+        );
+      }
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "change visibility",
+        "Missing receipt handle or invalid visibility timeout"
+      );
+    }
+    return { success: true };
+  }
+};
+
+// src/client.ts
+var apiClients = /* @__PURE__ */ new WeakMap();
+function getApiClient(client) {
+  const api = apiClients.get(client);
+  if (!api) {
+    throw new Error("QueueClient not initialized");
+  }
+  return api;
+}
+var QueueClient = class {
+  constructor(options) {
+    apiClients.set(this, new ApiClient(options));
+  }
+  /**
+   * Send a message to a topic.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * await send("my-topic", payload);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param payload - The data to send (serialized via the configured transport)
+   * @param options - Optional send options (idempotencyKey, retentionSeconds, delaySeconds, headers)
+   * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+   *   the message for deferred processing (no ID available yet)
+   */
+  send = async (topicName, payload, options) => {
+    const api = getApiClient(this);
+    const result = await api.sendMessage({
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds,
+      delaySeconds: options?.delaySeconds,
+      headers: options?.headers
+    });
+    if (result.messageId && isDevMode()) {
+      triggerDevCallbacks(
+        topicName,
+        result.messageId,
+        api.getRegion(),
+        options?.delaySeconds
+      );
+    }
+    return { messageId: result.messageId };
+  };
+  /**
+   * Receive and process messages from a topic.
+   *
+   * Each message is automatically locked, kept alive via periodic visibility
+   * extensions during processing, and acknowledged upon successful handler completion.
+   * The handler is not called when the queue is empty — check `result.ok` instead.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { receive } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const result = await receive("my-topic", "my-group", handler);
+   * if (!result.ok) console.log(result.reason);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param handler - Function to process each message payload and metadata.
+   *                  Not called when the queue is empty.
+   * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
+   * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
+   */
+  receive = async (topicName, consumerGroup, handler, options) => {
+    const api = getApiClient(this);
+    const topic = new Topic(api, topicName);
+    const visibilityTimeoutSeconds = options && "visibilityTimeoutSeconds" in options ? options.visibilityTimeoutSeconds : void 0;
+    const consumer = topic.consumerGroup(
+      consumerGroup,
+      visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
+    );
+    try {
+      let count;
+      const retry = options?.retry;
+      if (options && "messageId" in options) {
+        count = await consumer.consume(handler, {
+          messageId: options.messageId,
+          retry
+        });
+      } else {
+        const limit = options && "limit" in options ? options.limit : void 0;
+        count = await consumer.consume(handler, {
+          ...limit !== void 0 ? { limit } : {},
+          retry
+        });
+      }
+      if (count === 0) {
+        return { ok: false, reason: "empty" };
+      }
+      return { ok: true };
+    } catch (error) {
+      if (options && "messageId" in options && error instanceof MessageNotFoundError) {
+        return { ok: false, reason: "not_found", messageId: options.messageId };
+      }
+      if (options && "messageId" in options && error instanceof MessageNotAvailableError) {
+        return {
+          ok: false,
+          reason: "not_available",
+          messageId: options.messageId
+        };
+      }
+      if (options && "messageId" in options && error instanceof MessageAlreadyProcessedError) {
+        return {
+          ok: false,
+          reason: "already_processed",
+          messageId: options.messageId
+        };
+      }
+      throw error;
+    }
+  };
+  /**
+   * Create a Web API route handler for processing queue callback messages.
+   *
+   * Parses incoming `Request` as a CloudEvent and invokes the handler.
+   * For use on Vercel — Vercel invokes this route when messages are available.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * export const POST = handleCallback(handler);
+   * ```
+   *
+   * @param handler - Function to process the message payload and metadata
+   * @param options - Optional configuration
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
+   * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
+   *   reschedule the message for redelivery after N seconds.
+   * @returns A `(request: Request) => Promise<Response>` route handler
+   */
+  handleCallback = (handler, options) => {
+    return async (request) => {
+      try {
+        const parsed = await parseCallback(request);
+        await handleCallback(handler, parsed, {
+          client: this,
+          visibilityTimeoutSeconds: options?.visibilityTimeoutSeconds,
+          retry: options?.retry
+        });
+        return Response.json({ status: "success" });
+      } catch (error) {
+        console.error("Queue callback error:", error);
+        if (error instanceof Error && (error.message.includes("Invalid content type") || error.message.includes("Invalid CloudEvent") || error.message.includes("Missing required CloudEvent") || error.message.includes("Failed to parse CloudEvent") || error.message.includes("Binary mode callback"))) {
+          return Response.json({ error: error.message }, { status: 400 });
+        }
+        return Response.json(
+          { error: "Failed to process queue message" },
+          { status: 500 }
+        );
+      }
+    };
+  };
+  /**
+   * Create a Connect-style route handler for processing queue callback messages.
+   * For use on Vercel — Vercel invokes this route when messages are available.
+   *
+   * For frameworks using the `(req, res)` middleware pattern where `req.body`
+   * is pre-parsed (Next.js Pages Router, etc.).
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * app.post("/api/queue", handleNodeCallback(handler));
+   * ```
+   *
+   * @param handler - Function to process the message payload and metadata
+   * @param options - Optional configuration
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
+   * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
+   *   reschedule the message for redelivery after N seconds.
+   * @returns A `(req, res) => Promise<void>` route handler
+   */
+  handleNodeCallback = (handler, options) => {
+    return async (req, res) => {
+      if (req.method !== "POST") {
+        res.status(200).end();
+        return;
+      }
+      try {
+        const parsed = parseRawCallback(req.body, req.headers);
+        await handleCallback(handler, parsed, {
+          client: this,
+          visibilityTimeoutSeconds: options?.visibilityTimeoutSeconds,
+          retry: options?.retry
+        });
+        res.status(200).json({ status: "success" });
+      } catch (error) {
+        console.error("Queue callback error:", error);
+        if (error instanceof Error && (error.message.includes("Invalid content type") || error.message.includes("Invalid CloudEvent") || error.message.includes("Missing required CloudEvent") || error.message.includes("Failed to parse CloudEvent") || error.message.includes("Binary mode callback"))) {
+          res.status(400).json({ error: error.message });
+          return;
+        }
+        res.status(500).json({ error: "Failed to process queue message" });
+      }
+    };
+  };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BadRequestError,
   BufferTransport,
+  CLOUD_EVENT_TYPE_V1BETA,
+  CLOUD_EVENT_TYPE_V2BETA,
+  ConsumerDiscoveryError,
+  ConsumerRegistryNotConfiguredError,
+  DuplicateMessageError,
   ForbiddenError,
   InternalServerError,
   InvalidLimitError,
   JsonTransport,
+  MessageAlreadyProcessedError,
   MessageCorruptedError,
   MessageLockedError,
   MessageNotAvailableError,
   MessageNotFoundError,
+  QueueClient,
   QueueEmptyError,
   StreamTransport,
   UnauthorizedError,
-  handleCallback,
-  receive,
-  send
+  parseCallback,
+  parseRawCallback
 });
 //# sourceMappingURL=index.js.map