@vercel/queue 0.0.0-alpha.39 → 0.0.0-alpha.40

package/dist/index.mjs

@@ -71,7 +71,7 @@ var StreamTransport = class {
   }
 };
 
-// src/client.ts
+// src/api-client.ts
 import { parseMultipartStream } from "mixpart";
 
 // src/dev.ts
@@ -196,7 +196,7 @@ var ConsumerGroup = class {
   /**
    * Create a new ConsumerGroup instance.
    *
-   * @param client - QueueClient instance to use for API calls (transport is configured on the client)
+   * @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
@@ -321,35 +321,84 @@ var ConsumerGroup = class {
       }
     };
   }
+  /**
+   * 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 {
+        await transport.finalize(payload);
+      } catch (finalizeError) {
+        console.warn("Failed to finalize message payload:", finalizeError);
+      }
+    }
+  }
   async processMessage(message, handler, options) {
     const stopExtension = this.startVisibilityExtension(
       message.receiptHandle,
       options
     );
+    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, {
-        messageId: message.messageId,
-        deliveryCount: message.deliveryCount,
-        createdAt: message.createdAt,
-        topicName: this.topicName,
-        consumerGroup: this.consumerGroupName
-      });
+      await handler(message.payload, metadata);
       await stopExtension();
-      await this.client.deleteMessage({
+      await this.client.acknowledgeMessage({
         queueName: this.topicName,
         consumerGroup: this.consumerGroupName,
         receiptHandle: message.receiptHandle
       });
     } catch (error) {
       await stopExtension();
-      const transport = this.client.getTransport();
-      if (transport.finalize && message.payload !== void 0 && message.payload !== null) {
+      if (options?.retry) {
+        let directive;
         try {
-          await transport.finalize(message.payload);
-        } catch (finalizeError) {
-          console.warn("Failed to finalize message payload:", finalizeError);
+          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;
+          }
         }
       }
+      await this.finalizePayload(message.payload);
       throw error;
     }
   }
@@ -360,7 +409,7 @@ var ConsumerGroup = class {
    * 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 deleted on successful handler completion
+   * - Message is acknowledged on successful handler completion
    * - Payload is finalized on error if the transport supports it
    *
    * @param handler - Function to process the message payload and metadata
@@ -374,6 +423,7 @@ var ConsumerGroup = class {
     await this.processMessage(message, handler, options);
   }
   async consume(handler, options) {
+    const retry = options?.retry;
     if (options && "messageId" in options) {
       const response = await this.client.receiveMessageById({
         queueName: this.topicName,
@@ -381,22 +431,21 @@ var ConsumerGroup = class {
         messageId: options.messageId,
         visibilityTimeoutSeconds: this.visibilityTimeout
       });
-      await this.processMessage(response.message, handler);
+      await this.processMessage(response.message, handler, { retry });
+      return 1;
     } else {
       const limit = options && "limit" in options ? options.limit : 1;
-      let messageFound = false;
+      let messagesProcessed = 0;
       for await (const message of this.client.receiveMessages({
         queueName: this.topicName,
         consumerGroup: this.consumerGroupName,
         visibilityTimeoutSeconds: this.visibilityTimeout,
         limit
       })) {
-        messageFound = true;
-        await this.processMessage(message, handler);
-      }
-      if (!messageFound) {
-        await handler(null, null);
+        messagesProcessed++;
+        await this.processMessage(message, handler, { retry });
       }
+      return messagesProcessed;
     }
   }
   /**
@@ -418,8 +467,7 @@ var Topic = class {
   client;
   topicName;
   /**
-   * Create a new Topic instance
-   * @param client QueueClient instance to use for API calls (transport is configured on the client)
+   * @param client ApiClient instance to use for API calls
    * @param topicName Name of the topic to work with
    */
   constructor(client, topicName) {
@@ -430,7 +478,7 @@ var Topic = class {
    * 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)
@@ -445,8 +493,12 @@ var Topic = class {
       delaySeconds: options?.delaySeconds,
       headers: options?.headers
     });
-    if (isDevMode()) {
-      triggerDevCallbacks(this.topicName, result.messageId);
+    if (result.messageId && isDevMode()) {
+      triggerDevCallbacks(
+        this.topicName,
+        result.messageId,
+        this.client.getRegion()
+      );
     }
     return { messageId: result.messageId };
   }
@@ -539,10 +591,12 @@ function parseBinaryHeaders(headers) {
       `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) {
@@ -557,6 +611,10 @@ function parseBinaryHeaders(headers) {
   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;
@@ -601,14 +659,20 @@ async function parseCallback(request) {
 }
 async function handleCallback(handler, request, options) {
   const { queueName, consumerGroup, messageId } = request;
-  const client = options?.client || new QueueClient();
-  const topic = new Topic(client, queueName);
+  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 = client.getTransport();
+    const transport = api.getTransport();
     let payload;
     if (request.rawBody) {
       payload = await transport.deserialize(request.rawBody);
@@ -624,13 +688,17 @@ async function handleCallback(handler, request, options) {
       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 });
+    await cg.consumeMessage(handler, message, {
+      visibilityDeadline,
+      retry: options?.retry
+    });
   } else {
-    await cg.consume(handler, { messageId });
+    await cg.consume(handler, { messageId, retry: options?.retry });
   }
 }
 
@@ -701,8 +769,8 @@ function isDevMode() {
 var DEV_VISIBILITY_POLL_INTERVAL = 50;
 var DEV_VISIBILITY_MAX_WAIT = 5e3;
 var DEV_VISIBILITY_BACKOFF_MULTIPLIER = 2;
-async function waitForMessageVisibility(topicName, consumerGroup, messageId) {
-  const client = new QueueClient();
+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) {
@@ -742,13 +810,13 @@ async function waitForMessageVisibility(topicName, consumerGroup, messageId) {
   );
   return false;
 }
-function triggerDevCallbacks(topicName, messageId, delaySeconds) {
+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);
+      triggerDevCallbacks(topicName, messageId, region);
     }, delaySeconds * 1e3);
     return;
   }
@@ -771,7 +839,8 @@ function triggerDevCallbacks(topicName, messageId, delaySeconds) {
     const isVisible = await waitForMessageVisibility(
       topicName,
       firstRoute.consumer,
-      messageId
+      messageId,
+      region
     );
     if (!isVisible) {
       console.warn(
@@ -793,7 +862,8 @@ function triggerDevCallbacks(topicName, messageId, delaySeconds) {
             "ce-type": CLOUD_EVENT_TYPE_V2BETA,
             "ce-vqsqueuename": topicName,
             "ce-vqsconsumergroup": route.consumer,
-            "ce-vqsmessageid": messageId
+            "ce-vqsmessageid": messageId,
+            "ce-vqsregion": region
           }
         });
         if (response.ok) {
@@ -841,7 +911,7 @@ if (process.env.NODE_ENV === "test" || process.env.VITEST) {
 // src/oidc.ts
 import { getVercelOidcToken } from "@vercel/oidc";
 
-// src/client.ts
+// src/api-client.ts
 function isDebugEnabled() {
   return process.env.VERCEL_QUEUE_DEBUG === "1" || process.env.VERCEL_QUEUE_DEBUG === "true";
 }
@@ -894,40 +964,80 @@ function parseQueueHeaders(headers) {
     receiptHandle
   };
 }
-var QueueClient = class {
+var DEFAULT_BASE_URL_RESOLVER = (region) => `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;
-  basePath;
   customHeaders;
   providedToken;
-  defaultDeploymentId;
-  pinToDeployment;
+  resolvedDeploymentId;
+  pinSends;
+  explicitlyUnpinned;
   transport;
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl || process.env.VERCEL_QUEUE_BASE_URL || "https://vercel-queue.com";
-    this.basePath = options.basePath || process.env.VERCEL_QUEUE_BASE_PATH || "/api/v3/topic";
+  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.defaultDeploymentId = options.deploymentId || process.env.VERCEL_DEPLOYMENT_ID;
-    this.pinToDeployment = options.pinToDeployment ?? true;
     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;
     }
-    if (this.pinToDeployment) {
-      return this.defaultDeploymentId;
-    }
-    return void 0;
+    this.requireDeploymentId();
+    return this.pinSends ? this.resolvedDeploymentId : void 0;
   }
   getConsumeDeploymentId() {
     if (isDevMode()) {
       return void 0;
     }
-    return this.defaultDeploymentId;
+    this.requireDeploymentId();
+    return this.resolvedDeploymentId;
   }
   async getToken() {
     if (this.providedToken) {
@@ -945,7 +1055,7 @@ var QueueClient = class {
     const encodedQueue = encodeURIComponent(queueName);
     const segments = pathSegments.map((s) => encodeURIComponent(s));
     const path2 = segments.length > 0 ? "/" + segments.join("/") : "";
-    return `${this.baseUrl}${this.basePath}/${encodedQueue}${path2}`;
+    return `${this.baseUrl}${BASE_PATH}/${encodedQueue}${path2}`;
   }
   async fetch(url, init) {
     const method = init.method || "GET";
@@ -969,7 +1079,7 @@ var QueueClient = class {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.0.0-alpha.39"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.0.0-alpha.40"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -984,24 +1094,6 @@ var QueueClient = class {
     }
     return response;
   }
-  /**
-   * Send a message to a topic.
-   *
-   * @param options - Message options including queue name, payload, and optional settings
-   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
-   * @param options.payload - Message payload
-   * @param options.idempotencyKey - Optional deduplication key (dedup window: min(retention, 24h))
-   * @param options.retentionSeconds - Message TTL (default: 86400, min: 60, max: 86400)
-   * @param options.delaySeconds - Delivery delay (default: 0, max: retentionSeconds)
-   * @returns Promise with the generated messageId
-   * @throws {DuplicateMessageError} When idempotency key was already used
-   * @throws {ConsumerDiscoveryError} When consumer discovery fails
-   * @throws {ConsumerRegistryNotConfiguredError} When registry not configured
-   * @throws {BadRequestError} When parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
   async sendMessage(options) {
     const transport = this.transport;
     const {
@@ -1079,28 +1171,12 @@ var QueueClient = class {
         "send message"
       );
     }
+    if (response.status === 202) {
+      return { messageId: null };
+    }
     const responseData = await response.json();
     return responseData;
   }
-  /**
-   * Receive messages from a topic as an async generator.
-   *
-   * When the queue is empty, the generator completes without yielding any
-   * messages. Callers should handle the case where no messages are yielded.
-   *
-   * @param options - Receive options
-   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
-   * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
-   * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
-   * @param options.limit - Max messages to retrieve (default: 1, min: 1, max: 10)
-   * @yields Message objects with payload, messageId, receiptHandle, etc.
-   *         Yields nothing if queue is empty.
-   * @throws {InvalidLimitError} When limit is outside 1-10 range
-   * @throws {BadRequestError} When parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
   async *receiveMessages(options) {
     const transport = this.transport;
     const { queueName, consumerGroup, visibilityTimeoutSeconds, limit } = options;
@@ -1166,23 +1242,6 @@ var QueueClient = class {
       }
     }
   }
-  /**
-   * Receive a specific message by its ID.
-   *
-   * @param options - Receive options
-   * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
-   * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
-   * @param options.messageId - Message ID to retrieve
-   * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
-   * @returns Promise with the message
-   * @throws {MessageNotFoundError} When message doesn't exist
-   * @throws {MessageNotAvailableError} When message is in wrong state or was a duplicate
-   * @throws {MessageAlreadyProcessedError} When message was already processed
-   * @throws {BadRequestError} When parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
   async receiveMessageById(options) {
     const transport = this.transport;
     const { queueName, consumerGroup, messageId, visibilityTimeoutSeconds } = options;
@@ -1257,22 +1316,7 @@ var QueueClient = class {
     }
     throw new MessageNotFoundError(messageId);
   }
-  /**
-   * Delete (acknowledge) a message after successful processing.
-   *
-   * @param options - Delete options
-   * @param options.queueName - Topic name
-   * @param options.consumerGroup - Consumer group name
-   * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
-   * @returns Promise indicating deletion success
-   * @throws {MessageNotFoundError} When receipt handle not found
-   * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
-   * @throws {BadRequestError} When parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async deleteMessage(options) {
+  async acknowledgeMessage(options) {
     const { queueName, consumerGroup, receiptHandle } = options;
     const headers = new Headers({
       Authorization: `Bearer ${await this.getToken()}`,
@@ -1310,29 +1354,12 @@ var QueueClient = class {
         response.status,
         response.statusText,
         errorText,
-        "delete message",
+        "acknowledge message",
         "Missing or invalid receipt handle"
       );
     }
-    return { deleted: true };
+    return { acknowledged: true };
   }
-  /**
-   * Extend or change the visibility timeout of a message.
-   * Used to prevent message redelivery while still processing.
-   *
-   * @param options - Visibility options
-   * @param options.queueName - Topic name
-   * @param options.consumerGroup - Consumer group name
-   * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
-   * @param options.visibilityTimeoutSeconds - New timeout (min: 0, max: 3600, cannot exceed message expiration)
-   * @returns Promise indicating success
-   * @throws {MessageNotFoundError} When receipt handle not found
-   * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
-   * @throws {BadRequestError} When parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
   async changeVisibility(options) {
     const {
       queueName,
@@ -1384,100 +1411,211 @@ var QueueClient = class {
     }
     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));
+  }
   /**
-   * Alternative endpoint for changing message visibility timeout.
-   * Uses the /visibility path suffix and expects visibilityTimeoutSeconds in the body.
-   * Functionally equivalent to changeVisibility but follows an alternative API pattern.
+   * 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 options - Options for changing visibility
-   * @returns Promise resolving to change visibility response
+   * @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)
    */
-  async changeVisibilityAlt(options) {
-    const {
-      queueName,
-      consumerGroup,
-      receiptHandle,
-      visibilityTimeoutSeconds
-    } = options;
-    const headers = new Headers({
-      Authorization: `Bearer ${await this.getToken()}`,
-      "Content-Type": "application/json",
-      ...this.customHeaders
+  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
     });
-    const effectiveDeploymentId = this.getConsumeDeploymentId();
-    if (effectiveDeploymentId) {
-      headers.set("Vqs-Deployment-Id", effectiveDeploymentId);
+    if (result.messageId && isDevMode()) {
+      triggerDevCallbacks(
+        topicName,
+        result.messageId,
+        api.getRegion(),
+        options?.delaySeconds
+      );
     }
-    const response = await this.fetch(
-      this.buildUrl(
-        queueName,
-        "consumer",
-        consumerGroup,
-        "lease",
-        receiptHandle,
-        "visibility"
-      ),
-      {
-        method: "PATCH",
-        headers,
-        body: JSON.stringify({ visibilityTimeoutSeconds })
-      }
+    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 } : {}
     );
-    if (!response.ok) {
-      const errorText = await response.text();
-      if (response.status === 404) {
-        throw new MessageNotFoundError(receiptHandle);
+    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 (response.status === 409) {
-        throw new MessageNotAvailableError(
-          receiptHandle,
-          errorText || "Invalid receipt handle, message not in correct state, or already processed"
-        );
+      if (count === 0) {
+        return { ok: false, reason: "empty" };
       }
-      throwCommonHttpError(
-        response.status,
-        response.statusText,
-        errorText,
-        "change visibility (alt)",
-        "Missing receipt handle or invalid visibility timeout"
-      );
+      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;
     }
-    return { success: true };
-  }
+  };
+  /**
+   * 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" });
+      }
+    };
+  };
 };
-
-// src/factory.ts
-async function send(topicName, payload, options) {
-  const client = options?.client || new QueueClient();
-  const result = await client.sendMessage({
-    queueName: topicName,
-    payload,
-    idempotencyKey: options?.idempotencyKey,
-    retentionSeconds: options?.retentionSeconds,
-    delaySeconds: options?.delaySeconds,
-    headers: options?.headers
-  });
-  if (isDevMode()) {
-    triggerDevCallbacks(topicName, result.messageId, options?.delaySeconds);
-  }
-  return { messageId: result.messageId };
-}
-async function receive(topicName, consumerGroup, handler, options) {
-  const client = options?.client || new QueueClient();
-  const topic = new Topic(client, topicName);
-  const { client: _, ...rest } = options || {};
-  const { visibilityTimeoutSeconds } = rest;
-  const consumer = topic.consumerGroup(
-    consumerGroup,
-    visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
-  );
-  if (options && "messageId" in options) {
-    return consumer.consume(handler, { messageId: options.messageId });
-  } else {
-    const limit = options && "limit" in options ? options.limit : void 0;
-    return consumer.consume(handler, limit !== void 0 ? { limit } : {});
-  }
-}
 export {
   BadRequestError,
   BufferTransport,
@@ -1499,10 +1637,7 @@ export {
   QueueEmptyError,
   StreamTransport,
   UnauthorizedError,
-  handleCallback,
   parseCallback,
-  parseRawCallback,
-  receive,
-  send
+  parseRawCallback
 };
 //# sourceMappingURL=index.mjs.map