@vercel/queue 0.0.2 → 0.1.1

package/dist/index.d.mts

@@ -37,12 +37,11 @@ interface Transport<T = unknown> {
  * @example
  * ```typescript
  * // Default (JsonTransport is used automatically)
- * const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+ * const queue = new QueueClient();
  * await queue.send("topic", { data: "example" });
  *
  * // With custom serialization
  * const queue = new QueueClient({
- *   region: process.env.QUEUE_REGION!,
  *   transport: new JsonTransport({
  *     replacer: (key, value) => key === "password" ? undefined : value,
  *     reviver: (key, value) => key === "date" ? new Date(value) : value,
@@ -75,7 +74,7 @@ declare class JsonTransport<T = unknown> implements Transport<T> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new BufferTransport() });
+ * const queue = new QueueClient({ transport: new BufferTransport() });
  * await queue.send("binary-topic", myBuffer);
  * ```
  */
@@ -95,13 +94,13 @@ declare class BufferTransport implements Transport<Buffer> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new StreamTransport() });
- *
  * // Sending a stream
+ * const queue = new QueueClient({ transport: new StreamTransport() });
  * await queue.send("large-file", myReadableStream);
  *
  * // Receiving - cleanup handled automatically
- * await queue.receive("large-file", "processor", async (stream, meta) => {
+ * const poller = new PollingQueueClient({ region: "iad1", transport: new StreamTransport() });
+ * await poller.receive("large-file", "processor", async (stream, meta) => {
  *   const reader = stream.getReader();
  *   // Process chunks...
  * });
@@ -155,15 +154,17 @@ interface QueueClientOptions {
      * Requests are sent to the regional endpoint resolved by
      * {@link BaseUrlResolver} (default: `https://${region}.vercel-queue.com`).
      *
-     * Use a `QUEUE_REGION` env var set to `${VERCEL_REGION}` in production
-     * and a fixed region (e.g. `"iad1"`) in development.
+     * When omitted, the region is auto-detected from the `VERCEL_REGION`
+     * environment variable (set automatically on Vercel). If not available,
+     * defaults to `"iad1"` with a console warning.
      *
      * @example
      * ```ts
-     * new QueueClient({ region: process.env.QUEUE_REGION! })
+     * new QueueClient()                         // auto-detect, falls back to "iad1"
+     * new QueueClient({ region: "iad1" })       // explicit
      * ```
      */
-    region: VercelRegion;
+    region?: VercelRegion;
     /**
      * Custom resolver that maps a region code to a base {@link URL}.
      *
@@ -205,6 +206,28 @@ interface QueueClientOptions {
      */
     transport?: Transport;
 }
+/**
+ * Options for creating a {@link PollingQueueClient}.
+ *
+ * Identical to {@link QueueClientOptions} except `region` is **required**
+ * because messages can only be received from the region they were sent to.
+ * Using a fixed region (e.g. `"iad1"`) ensures that `send` and `receive`
+ * target the same endpoint.
+ */
+interface PollingQueueClientOptions extends QueueClientOptions {
+    /**
+     * Vercel region code for API routing — **required** for polling.
+     *
+     * Messages can only be received from the region they were sent to.
+     * Use a fixed region (e.g. `"iad1"`) for both sending and receiving.
+     *
+     * @example
+     * ```ts
+     * new PollingQueueClient({ region: "iad1" })
+     * ```
+     */
+    region: VercelRegion;
+}
 /**
  * Options for sending messages.
  */
@@ -496,14 +519,40 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
+/**
+ * Queue client for push-based (callback) workflows.
+ *
+ * Use this client when Vercel delivers messages to your route handlers.
+ * Provides {@link send}, {@link handleCallback}, and {@link handleNodeCallback}.
+ *
+ * Region is resolved automatically:
+ * 1. Explicit `region` option (highest priority)
+ * 2. `VERCEL_REGION` environment variable (set automatically on Vercel)
+ * 3. Falls back to `"iad1"` with a console warning
+ *
+ * The constructor never throws — `new QueueClient()` always works.
+ *
+ * For manual polling workflows, use {@link PollingQueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { QueueClient } from "@vercel/queue";
+ *
+ * const queue = new QueueClient();
+ * export const { send, handleCallback, handleNodeCallback } = queue;
+ * ```
+ */
 declare class QueueClient {
-    constructor(options: QueueClientOptions);
+    constructor(options?: QueueClientOptions);
     /**
      * 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! });
+     * const { send } = new QueueClient();
      * await send("my-topic", payload);
      * ```
      *
@@ -514,28 +563,6 @@ declare class QueueClient {
      *   the message for deferred processing (no ID available yet)
      */
     send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
-    /**
-     * 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: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
     /**
      * Create a Web API route handler for processing queue callback messages.
      *
@@ -544,7 +571,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleCallback } = new QueueClient();
      * export const POST = handleCallback(handler);
      * ```
      *
@@ -553,12 +580,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.
@@ -568,7 +595,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleNodeCallback } = new QueueClient();
      * app.post("/api/queue", handleNodeCallback(handler));
      * ```
      *
@@ -594,6 +621,119 @@ declare class QueueClient {
         end(): void;
     }) => Promise<void>);
 }
+/**
+ * Queue client for poll-based (manual receive) workflows.
+ *
+ * Use this client when you manually poll for messages with {@link receive}.
+ * Also provides {@link send} for publishing messages.
+ *
+ * Region is **required** because messages can only be received from the
+ * region they were sent to. Use a fixed region (e.g. `"iad1"`) for both
+ * sending and receiving.
+ *
+ * For push-based (callback) workflows on Vercel, use {@link QueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { PollingQueueClient } from "@vercel/queue";
+ *
+ * const queue = new PollingQueueClient({ region: "iad1" });
+ * export const { send, receive } = queue;
+ * ```
+ */
+declare class PollingQueueClient {
+    constructor(options: PollingQueueClientOptions);
+    /**
+     * Send a message to a topic.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { send } = new PollingQueueClient({ region: "iad1" });
+     * 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: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
+    /**
+     * 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 PollingQueueClient({ region: "iad1" });
+     * 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: <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
@@ -668,4 +808,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, 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

@@ -37,12 +37,11 @@ interface Transport<T = unknown> {
  * @example
  * ```typescript
  * // Default (JsonTransport is used automatically)
- * const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+ * const queue = new QueueClient();
  * await queue.send("topic", { data: "example" });
  *
  * // With custom serialization
  * const queue = new QueueClient({
- *   region: process.env.QUEUE_REGION!,
  *   transport: new JsonTransport({
  *     replacer: (key, value) => key === "password" ? undefined : value,
  *     reviver: (key, value) => key === "date" ? new Date(value) : value,
@@ -75,7 +74,7 @@ declare class JsonTransport<T = unknown> implements Transport<T> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new BufferTransport() });
+ * const queue = new QueueClient({ transport: new BufferTransport() });
  * await queue.send("binary-topic", myBuffer);
  * ```
  */
@@ -95,13 +94,13 @@ declare class BufferTransport implements Transport<Buffer> {
  *
  * @example
  * ```typescript
- * const queue = new QueueClient({ region: "iad1", transport: new StreamTransport() });
- *
  * // Sending a stream
+ * const queue = new QueueClient({ transport: new StreamTransport() });
  * await queue.send("large-file", myReadableStream);
  *
  * // Receiving - cleanup handled automatically
- * await queue.receive("large-file", "processor", async (stream, meta) => {
+ * const poller = new PollingQueueClient({ region: "iad1", transport: new StreamTransport() });
+ * await poller.receive("large-file", "processor", async (stream, meta) => {
  *   const reader = stream.getReader();
  *   // Process chunks...
  * });
@@ -155,15 +154,17 @@ interface QueueClientOptions {
      * Requests are sent to the regional endpoint resolved by
      * {@link BaseUrlResolver} (default: `https://${region}.vercel-queue.com`).
      *
-     * Use a `QUEUE_REGION` env var set to `${VERCEL_REGION}` in production
-     * and a fixed region (e.g. `"iad1"`) in development.
+     * When omitted, the region is auto-detected from the `VERCEL_REGION`
+     * environment variable (set automatically on Vercel). If not available,
+     * defaults to `"iad1"` with a console warning.
      *
      * @example
      * ```ts
-     * new QueueClient({ region: process.env.QUEUE_REGION! })
+     * new QueueClient()                         // auto-detect, falls back to "iad1"
+     * new QueueClient({ region: "iad1" })       // explicit
      * ```
      */
-    region: VercelRegion;
+    region?: VercelRegion;
     /**
      * Custom resolver that maps a region code to a base {@link URL}.
      *
@@ -205,6 +206,28 @@ interface QueueClientOptions {
      */
     transport?: Transport;
 }
+/**
+ * Options for creating a {@link PollingQueueClient}.
+ *
+ * Identical to {@link QueueClientOptions} except `region` is **required**
+ * because messages can only be received from the region they were sent to.
+ * Using a fixed region (e.g. `"iad1"`) ensures that `send` and `receive`
+ * target the same endpoint.
+ */
+interface PollingQueueClientOptions extends QueueClientOptions {
+    /**
+     * Vercel region code for API routing — **required** for polling.
+     *
+     * Messages can only be received from the region they were sent to.
+     * Use a fixed region (e.g. `"iad1"`) for both sending and receiving.
+     *
+     * @example
+     * ```ts
+     * new PollingQueueClient({ region: "iad1" })
+     * ```
+     */
+    region: VercelRegion;
+}
 /**
  * Options for sending messages.
  */
@@ -496,14 +519,40 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
+/**
+ * Queue client for push-based (callback) workflows.
+ *
+ * Use this client when Vercel delivers messages to your route handlers.
+ * Provides {@link send}, {@link handleCallback}, and {@link handleNodeCallback}.
+ *
+ * Region is resolved automatically:
+ * 1. Explicit `region` option (highest priority)
+ * 2. `VERCEL_REGION` environment variable (set automatically on Vercel)
+ * 3. Falls back to `"iad1"` with a console warning
+ *
+ * The constructor never throws — `new QueueClient()` always works.
+ *
+ * For manual polling workflows, use {@link PollingQueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { QueueClient } from "@vercel/queue";
+ *
+ * const queue = new QueueClient();
+ * export const { send, handleCallback, handleNodeCallback } = queue;
+ * ```
+ */
 declare class QueueClient {
-    constructor(options: QueueClientOptions);
+    constructor(options?: QueueClientOptions);
     /**
      * 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! });
+     * const { send } = new QueueClient();
      * await send("my-topic", payload);
      * ```
      *
@@ -514,28 +563,6 @@ declare class QueueClient {
      *   the message for deferred processing (no ID available yet)
      */
     send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
-    /**
-     * 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: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
     /**
      * Create a Web API route handler for processing queue callback messages.
      *
@@ -544,7 +571,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleCallback } = new QueueClient();
      * export const POST = handleCallback(handler);
      * ```
      *
@@ -553,12 +580,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.
@@ -568,7 +595,7 @@ declare class QueueClient {
      *
      * This is an arrow function property so it can be destructured:
      * ```typescript
-     * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const { handleNodeCallback } = new QueueClient();
      * app.post("/api/queue", handleNodeCallback(handler));
      * ```
      *
@@ -594,6 +621,119 @@ declare class QueueClient {
         end(): void;
     }) => Promise<void>);
 }
+/**
+ * Queue client for poll-based (manual receive) workflows.
+ *
+ * Use this client when you manually poll for messages with {@link receive}.
+ * Also provides {@link send} for publishing messages.
+ *
+ * Region is **required** because messages can only be received from the
+ * region they were sent to. Use a fixed region (e.g. `"iad1"`) for both
+ * sending and receiving.
+ *
+ * For push-based (callback) workflows on Vercel, use {@link QueueClient} instead.
+ *
+ * @example
+ * ```typescript
+ * import { PollingQueueClient } from "@vercel/queue";
+ *
+ * const queue = new PollingQueueClient({ region: "iad1" });
+ * export const { send, receive } = queue;
+ * ```
+ */
+declare class PollingQueueClient {
+    constructor(options: PollingQueueClientOptions);
+    /**
+     * Send a message to a topic.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { send } = new PollingQueueClient({ region: "iad1" });
+     * 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: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
+    /**
+     * 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 PollingQueueClient({ region: "iad1" });
+     * 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: <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
@@ -668,4 +808,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, 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 };