@vercel/queue 0.1.0 → 0.1.2

package/README.md

@@ -19,20 +19,20 @@ npm install @vercel/queue
 
 ## Quick Start
 
-**1. Create a shared queue client:**
+**1. Link your Vercel project and pull credentials:**
 
-```typescript
-// lib/queue.ts
-import { QueueClient } from "@vercel/queue";
+The SDK authenticates via OIDC. Link your project if you haven't already, then pull to get fresh tokens:
 
-const queue = new QueueClient();
-export const { send, handleCallback } = queue;
+```bash
+npm i -g vercel
+vc link   # if you haven't already
+vc env pull
 ```
 
 **2. Send a message anywhere in your app:**
 
 ```typescript
-import { send } from "@/lib/queue";
+import { send } from "@vercel/queue";
 
 await send("my-topic", { message: "Hello world" });
 ```
@@ -41,7 +41,7 @@ await send("my-topic", { message: "Hello world" });
 
 ```typescript
 // app/api/queue/my-topic/route.ts
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
 
 export const POST = handleCallback(async (message, metadata) => {
   console.log("Processing:", message);
@@ -60,28 +60,28 @@ export const POST = handleCallback(async (message, metadata) => {
 }
 ```
 
-**5. Link your project for local development:**
+That's it. The top-level `send` and `handleCallback` use an auto-configured default client. The region is auto-detected from `VERCEL_REGION` (set automatically on Vercel). If the region can't be detected (e.g. local dev), it falls back to `iad1`.
 
-```bash
-npm i -g vercel
-vc link
-vc env pull
+To target a specific region for sending with the top-level `send`, pass the `region` option:
+
+```typescript
+await send("my-topic", payload, { region: "sfo1" });
 ```
 
-That's it. `new QueueClient()` auto-detects the region from `VERCEL_REGION` (set automatically on Vercel). If the region can't be detected (e.g. local dev), it falls back to `iad1`.
+> **Note:** The `region` option is only available on the top-level `send()` convenience export. When using a `QueueClient` instance, the region is set once in the constructor via `new QueueClient({ region: "sfo1" })` and applies to all operations on that client.
 
 ## Local Development
 
-**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically via local HTTP requests. This means your local dev environment behaves identically to production — no surprising behavior differences.
+**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, then invokes your registered `handleCallback` handlers directly in-process using the same code path as production. Your handlers are called with the same lifecycle (receive, visibility extension, ack) as in production. If a handler throws, the message is re-delivered after the configured retry delay (from `retryAfterSeconds` in `vercel.json` or the `retry` callback's `afterSeconds`), with an incrementing `deliveryCount`, matching production retry semantics.
 
-> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically during `npm run dev`.
+Works with Next.js (Turbopack and webpack), Nuxt, SvelteKit, and any framework that runs server-side JavaScript. The SDK automatically discovers handlers from your `vercel.json` configuration and loads route modules on demand — no manual setup required beyond `vercel.json`.
+
+> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks set this automatically during `npm run dev`.
 
 ## Publishing Messages
 
 ```typescript
-import { QueueClient } from "@vercel/queue";
-
-const { send } = new QueueClient();
+import { send } from "@vercel/queue";
 
 // Simple send
 await send("my-topic", { message: "Hello world" });
@@ -94,6 +94,7 @@ await send(
     idempotencyKey: "unique-key", // Prevent duplicate messages
     retentionSeconds: 3600, // 1 hour TTL (default: 24h)
     delaySeconds: 60, // Delay delivery by 1 minute
+    region: "sfo1", // Top-level send() only — not available on QueueClient.send()
   },
 );
 ```
@@ -102,7 +103,7 @@ Example usage in an API route:
 
 ```typescript
 // app/api/send-message/route.ts
-import { send } from "@/lib/queue";
+import { send } from "@vercel/queue";
 
 export async function POST(request: Request) {
   const body = await request.json();
@@ -127,12 +128,43 @@ Returns `(Request) => Promise<Response>`. For frameworks that export Web API rou
 
 ```typescript
 // app/api/queue/my-topic/route.ts
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
+
+export const POST = handleCallback(
+  async (message, metadata) => {
+    // metadata: { messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, region }
+    await processMessage(message);
+    // Throwing an error will automatically retry the message
+  },
+  {
+    visibilityTimeoutSeconds: 600, // Lock duration while processing (default: 300)
+  },
+);
+```
+
+**Nuxt:**
+
+```typescript
+// server/api/queue.ts
+import { handleCallback } from "@vercel/queue";
+
+const handler = handleCallback(async (message, metadata) => {
+  await processMessage(message);
+});
+
+export default defineEventHandler(async (event) => {
+  return handler(toWebRequest(event));
+});
+```
+
+**SvelteKit:**
+
+```typescript
+// src/routes/api/queue/+server.ts
+import { handleCallback } from "@vercel/queue";
 
 export const POST = handleCallback(async (message, metadata) => {
-  // metadata: { messageId, deliveryCount, createdAt, expiresAt?, topicName, consumerGroup, region }
   await processMessage(message);
-  // Throwing an error will automatically retry the message
 });
 ```
 
@@ -140,7 +172,7 @@ export const POST = handleCallback(async (message, metadata) => {
 
 ```typescript
 import { Hono } from "hono";
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
 
 const app = new Hono();
 app.post(
@@ -154,7 +186,26 @@ export default app;
 
 #### Connect-style — `handleNodeCallback`
 
-Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Express, Next.js Pages Router, etc.).
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Vercel Node.js functions, Express, Next.js Pages Router, etc.). **`handleNodeCallback` is not a top-level export** — it is only available via a `QueueClient` instance:
+
+```typescript
+// lib/queue.ts
+import { QueueClient } from "@vercel/queue";
+
+const queue = new QueueClient();
+export const { handleNodeCallback } = queue;
+```
+
+**Vercel Node.js Functions (plain `api/` directory):**
+
+```typescript
+// api/queue.ts
+import { handleNodeCallback } from "./lib/queue";
+
+export default handleNodeCallback(async (message, metadata) => {
+  await processMessage(message);
+});
+```
 
 **Next.js Pages Router:**
 
@@ -225,14 +276,17 @@ Multiple route files for the same topic create separate consumer groups — each
 
 When a handler throws, the message is not acknowledged and becomes available for redelivery after the `retryAfterSeconds` interval configured in `vercel.json`. Retries continue until the handler succeeds or the message expires (default: 24 hours).
 
-For finer control over retry timing, pass a `retry` option:
+For finer control over retry timing, pass a `retry` option. You can also set `visibilityTimeoutSeconds` to control how long the message is locked during processing (default: 300):
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
   },
   {
+    visibilityTimeoutSeconds: 600, // Lock duration while processing (default: 300)
     retry: (error, metadata) => {
       if (error instanceof RateLimitError) return { afterSeconds: 60 };
       // Return undefined to let the error propagate normally
@@ -246,6 +300,8 @@ When `retry` returns `{ afterSeconds: N }`, the message is rescheduled for redel
 **Exponential backoff** uses `metadata.deliveryCount` (starts at 1, increments each delivery):
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -263,6 +319,8 @@ export const POST = handleCallback(
 **Conditional retry** — only retry transient errors:
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -280,6 +338,8 @@ export const POST = handleCallback(
 **Acknowledging poison messages** — stop retrying messages that can never succeed:
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -298,6 +358,8 @@ The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `
 
 ## Custom Client Configuration
 
+For most use cases, the top-level `send` and `handleCallback` functions are all you need. For advanced configuration (custom transports, explicit tokens, deployment pinning), create a `QueueClient` instance directly.
+
 ### QueueClient (push mode)
 
 For push-based workflows where Vercel delivers messages to your route handlers:
@@ -445,8 +507,8 @@ import {
   ForbiddenError,
   InternalServerError,
   UnauthorizedError,
+  send,
 } from "@vercel/queue";
-import { send } from "@/lib/queue";
 
 try {
   await send("my-topic", payload);
@@ -499,7 +561,7 @@ All error types:
 | Limit                       | Value                 | Notes                               |
 | --------------------------- | --------------------- | ----------------------------------- |
 | Message throughput          | 10,000+ msg/sec/topic | Scales horizontally                 |
-| Payload size                | 1 GB                  | Smaller messages have lower latency |
+| Payload size                | 100 MB                | Smaller messages have lower latency |
 | Number of topics            | Unlimited             | No hard limit                       |
 | Consumer groups per message | ~4,000                | Per-message limit                   |
 | Messages per queue          | Unlimited             | No hard limit                       |
@@ -549,9 +611,51 @@ All error types:
 
 ## API Reference
 
+### Top-level `send(topicName, payload, options?)`
+
+The simplest way to send a message. Uses an auto-configured default client that detects the region from `VERCEL_REGION`, falling back to `"iad1"` with a console warning on first use.
+
+```typescript
+import { send } from "@vercel/queue";
+
+const { messageId } = await send("my-topic", payload, {
+  idempotencyKey: "unique-key", // Dedup window: min(retention, 24h)
+  retentionSeconds: 3600, // Message TTL (default: 86400)
+  delaySeconds: 60, // Delay before visible (default: 0)
+  headers: { "X-Custom": "val" }, // Custom headers
+  region: "sfo1", // Override the auto-detected region for this send
+});
+```
+
+The `region` option is exclusive to the top-level `send()`. It creates a one-off client targeting the given region. When using `QueueClient`, the region is set once in the constructor and applies to all operations.
+
+Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
+
+### Top-level `handleCallback(handler, options?)`
+
+The simplest way to handle incoming queue messages. Uses the same auto-configured default client as `send`.
+
+```typescript
+import { handleCallback } from "@vercel/queue";
+
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
+    retry: (error, metadata) => {
+      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
+    },
+  },
+);
+```
+
+Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers. Vercel only. The region for follow-up API calls is determined automatically from the `ce-vqsregion` header in the incoming event.
+
 ### `QueueClient`
 
-Push-based client for workflows where Vercel delivers messages to your route handlers. Region is auto-detected from `VERCEL_REGION` (set automatically on Vercel), falling back to `"iad1"` with a console warning.
+Push-based client for workflows where Vercel delivers messages to your route handlers. Use this when you need custom configuration (transport, token, headers, deployment pinning). Region is auto-detected from `VERCEL_REGION` (set automatically on Vercel), falling back to `"iad1"` with a console warning.
 
 ```typescript
 import { QueueClient } from "@vercel/queue";
@@ -585,21 +689,6 @@ const queue = new PollingQueueClient({
 const { send, receive } = queue;
 ```
 
-### `send(topicName, payload, options?)`
-
-Available on both `QueueClient` and `PollingQueueClient`.
-
-Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
-
-```typescript
-const { messageId } = await send("my-topic", payload, {
-  idempotencyKey: "unique-key", // Dedup window: min(retention, 24h)
-  retentionSeconds: 3600, // Message TTL (default: 86400)
-  delaySeconds: 60, // Delay before visible (default: 0)
-  headers: { "X-Custom": "val" }, // Custom headers
-});
-```
-
 ### `receive(topicName, consumerGroup, handler, options?)`
 
 Available on `PollingQueueClient` only.
@@ -626,33 +715,18 @@ const result = await receive("my-topic", "my-group", handler, {
 });
 ```
 
-### `handleCallback(handler, options?)`
-
-Available on `QueueClient` only. Vercel only.
-
-Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
-
-```typescript
-export const POST = handleCallback(
-  async (message, metadata) => {
-    await processMessage(message);
-  },
-  {
-    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
-    retry: (error, metadata) => {
-      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
-    },
-  },
-);
-```
-
 ### `handleNodeCallback(handler, options?)`
 
-Available on `QueueClient` only. Vercel only.
+Available on `QueueClient` instances only (not a top-level export). Vercel only.
 
 Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
 ```typescript
+import { QueueClient } from "@vercel/queue";
+
+const queue = new QueueClient();
+const { handleNodeCallback } = queue;
+
 // pages/api/queue/my-topic.ts
 export default handleNodeCallback(
   async (message, metadata) => {
@@ -676,7 +750,7 @@ interface MessageMetadata {
   messageId: string;
   deliveryCount: number;
   createdAt: Date;
-  expiresAt?: Date;
+  expiresAt: Date;
   topicName: string;
   consumerGroup: string;
   region: string;

package/dist/index.d.mts

@@ -289,7 +289,8 @@ interface Message<T = unknown> {
     createdAt: Date;
     /**
      * Timestamp when the message expires.
-     * Only present for messages delivered via the v2beta binary callback path.
+     * Present in v2beta binary callback (`ce-vqsexpiresat` header) and
+     * V3 multipart/NDJSON responses (`Vqs-Expires-At` header / `expiresAt` field).
      */
     expiresAt?: Date;
     /**
@@ -311,7 +312,7 @@ interface MessageMetadata {
     messageId: string;
     deliveryCount: number;
     createdAt: Date;
-    expiresAt?: Date;
+    expiresAt: Date;
     topicName: string;
     consumerGroup: string;
     /** Vercel region the client is targeting. */
@@ -519,6 +520,9 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
 /**
  * Queue client for push-based (callback) workflows.
  *
@@ -577,12 +581,12 @@ declare class QueueClient {
      * @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
+     * @returns A route handler that accepts either `Request` or `{ request: Request }`
      */
     handleCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
         visibilityTimeoutSeconds?: number;
         retry?: RetryHandler;
-    }) => ((request: Request) => Promise<Response>);
+    }) => ((requestOrEvent: CallbackRequestInput$1) => Promise<Response>);
     /**
      * Create a Connect-style route handler for processing queue callback messages.
      * For use on Vercel — Vercel invokes this route when messages are available.
@@ -680,6 +684,58 @@ declare class PollingQueueClient {
     receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
 }
 
+type CallbackRequestInput = Request | {
+    request: Request;
+};
+/**
+ * Send a message to a topic using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { send } from "@vercel/queue";
+ * await send("my-topic", { hello: "world" });
+ * ```
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param payload - The data to send (serialized via JsonTransport)
+ * @param options - Optional send options. Pass `region` to route to a specific region.
+ * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+ *   the message for deferred processing
+ */
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions & {
+    region?: VercelRegion;
+}): Promise<SendResult>;
+/**
+ * Create a Web API route handler for processing queue callback messages
+ * using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ * The callback region is determined automatically from the incoming
+ * `ce-vqsregion` header in the v2beta event — no manual configuration needed.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { handleCallback } from "@vercel/queue";
+ * export const POST = handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * });
+ * ```
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Optional configuration (visibilityTimeoutSeconds, retry)
+ * @returns A route handler that accepts either `Request` or `{ request: Request }`
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options?: {
+    visibilityTimeoutSeconds?: number;
+    retry?: RetryHandler;
+}): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -753,4 +809,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, parseCallback, parseRawCallback };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, send };

package/dist/index.d.ts

@@ -289,7 +289,8 @@ interface Message<T = unknown> {
     createdAt: Date;
     /**
      * Timestamp when the message expires.
-     * Only present for messages delivered via the v2beta binary callback path.
+     * Present in v2beta binary callback (`ce-vqsexpiresat` header) and
+     * V3 multipart/NDJSON responses (`Vqs-Expires-At` header / `expiresAt` field).
      */
     expiresAt?: Date;
     /**
@@ -311,7 +312,7 @@ interface MessageMetadata {
     messageId: string;
     deliveryCount: number;
     createdAt: Date;
-    expiresAt?: Date;
+    expiresAt: Date;
     topicName: string;
     consumerGroup: string;
     /** Vercel region the client is targeting. */
@@ -519,6 +520,9 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
 /**
  * Queue client for push-based (callback) workflows.
  *
@@ -577,12 +581,12 @@ declare class QueueClient {
      * @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
+     * @returns A route handler that accepts either `Request` or `{ request: Request }`
      */
     handleCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
         visibilityTimeoutSeconds?: number;
         retry?: RetryHandler;
-    }) => ((request: Request) => Promise<Response>);
+    }) => ((requestOrEvent: CallbackRequestInput$1) => Promise<Response>);
     /**
      * Create a Connect-style route handler for processing queue callback messages.
      * For use on Vercel — Vercel invokes this route when messages are available.
@@ -680,6 +684,58 @@ declare class PollingQueueClient {
     receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
 }
 
+type CallbackRequestInput = Request | {
+    request: Request;
+};
+/**
+ * Send a message to a topic using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { send } from "@vercel/queue";
+ * await send("my-topic", { hello: "world" });
+ * ```
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param payload - The data to send (serialized via JsonTransport)
+ * @param options - Optional send options. Pass `region` to route to a specific region.
+ * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+ *   the message for deferred processing
+ */
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions & {
+    region?: VercelRegion;
+}): Promise<SendResult>;
+/**
+ * Create a Web API route handler for processing queue callback messages
+ * using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ * The callback region is determined automatically from the incoming
+ * `ce-vqsregion` header in the v2beta event — no manual configuration needed.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { handleCallback } from "@vercel/queue";
+ * export const POST = handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * });
+ * ```
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Optional configuration (visibilityTimeoutSeconds, retry)
+ * @returns A route handler that accepts either `Request` or `{ request: Request }`
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options?: {
+    visibilityTimeoutSeconds?: number;
+    retry?: RetryHandler;
+}): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -753,4 +809,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, parseCallback, parseRawCallback };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, send };