@vercel/queue 0.0.1 → 0.1.0

package/README.md

@@ -4,9 +4,9 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 
 ## Features
 
-- **Simple API**: `send` and `receive` are all you need
+- **Simple API**: `send` and `handleCallback` are all you need for push-based workflows
 - **Automatic Triggering on Vercel**: Vercel invokes your route handlers when messages are ready
-- **Works Anywhere**: `send` and `receive` work in any Node.js environment
+- **Works Anywhere**: `send` and `receive` work in any Node.js environment, including self-hosted and non-Vercel platforms
 - **Type Safety**: Full TypeScript generics support
 - **Customizable Serialization**: Built-in JSON, Buffer, and Stream transports
 - **Local Dev Mode**: Messages sent locally trigger your handlers automatically
@@ -19,29 +19,17 @@ npm install @vercel/queue
 
 ## Quick Start
 
-Set up your region via environment variables. If your framework supports `.env` files (Next.js, Vite, Nuxt, etc.):
-
-```bash
-# .env.production (on Vercel, inherits the platform's region)
-QUEUE_REGION=${VERCEL_REGION}
-
-# .env.development (fixed region for local dev — iad1 is recommended)
-QUEUE_REGION=iad1
-```
-
-Otherwise, set `QUEUE_REGION` in your environment directly (e.g. via your hosting provider's dashboard or a `dotenv` setup).
-
-Create a shared queue client:
+**1. Create a shared queue client:**
 
 ```typescript
 // lib/queue.ts
 import { QueueClient } from "@vercel/queue";
 
-const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
-export const { send, receive, handleCallback, handleNodeCallback } = queue;
+const queue = new QueueClient();
+export const { send, handleCallback } = queue;
 ```
 
-Send a message anywhere in your app:
+**2. Send a message anywhere in your app:**
 
 ```typescript
 import { send } from "@/lib/queue";
@@ -49,7 +37,7 @@ import { send } from "@/lib/queue";
 await send("my-topic", { message: "Hello world" });
 ```
 
-Handle incoming messages with a route handler:
+**3. Handle incoming messages with a route handler:**
 
 ```typescript
 // app/api/queue/my-topic/route.ts
@@ -60,7 +48,7 @@ export const POST = handleCallback(async (message, metadata) => {
 });
 ```
 
-Configure your `vercel.json`:
+**4. Configure `vercel.json`:**
 
 ```json
 {
@@ -72,9 +60,7 @@ Configure your `vercel.json`:
 }
 ```
 
-### Project Setup
-
-For local development, link your Vercel project:
+**5. Link your project for local development:**
 
 ```bash
 npm i -g vercel
@@ -82,6 +68,8 @@ vc link
 vc env pull
 ```
 
+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`.
+
 ## 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.
@@ -93,7 +81,7 @@ vc env pull
 ```typescript
 import { QueueClient } from "@vercel/queue";
 
-const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+const { send } = new QueueClient();
 
 // Simple send
 await send("my-topic", { message: "Hello world" });
@@ -310,37 +298,62 @@ The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `
 
 ## Custom Client Configuration
 
-All configuration lives on the `QueueClient`:
+### QueueClient (push mode)
+
+For push-based workflows where Vercel delivers messages to your route handlers:
 
 ```typescript
 import { QueueClient, BufferTransport } from "@vercel/queue";
 
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
+  region: "iad1", // Optional — auto-detected from VERCEL_REGION, falls back to "iad1"
   token: "my-token", // Auth token (default: OIDC auto-detection)
   transport: new BufferTransport(), // Serialization (default: JsonTransport)
   headers: { "X-Custom": "header" }, // Custom headers on all requests
   deploymentId: null, // null = unpinned, omit = auto from env, or explicit string
 });
 
-// Use directly
-await queue.send("my-topic", myBuffer);
+export const { send, handleCallback, handleNodeCallback } = queue;
+```
+
+### PollingQueueClient (poll mode)
 
-// Or destructure
-export const { send, receive, handleCallback, handleNodeCallback } = queue;
+For manual polling workflows where you call `receive` to poll for messages. Works anywhere — on Vercel, self-hosted, or any Node.js environment:
+
+```typescript
+import { PollingQueueClient, BufferTransport } from "@vercel/queue";
+
+const queue = new PollingQueueClient({
+  region: "iad1", // Required — messages must be received from a fixed region
+  token: "my-token",
+  transport: new BufferTransport(),
+  headers: { "X-Custom": "header" },
+  deploymentId: null,
+});
+
+export const { send, receive } = queue;
 ```
 
-The client sends requests to `https://${region}.vercel-queue.com`. When `handleCallback` receives a message, it reads the `ce-vqsregion` header and routes follow-up API calls to the correct regional endpoint.
+Both clients send requests to `https://${region}.vercel-queue.com`. When `handleCallback` receives a message, it reads the `ce-vqsregion` header and routes follow-up API calls to the correct regional endpoint.
 
-To customize the URL scheme, provide a `resolveBaseUrl`:
+To customize the URL scheme, provide a `resolveBaseUrl` that returns a `URL`:
 
 ```typescript
+// Custom domain
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
-  resolveBaseUrl: (region) => `https://${region}.my-proxy.example`,
+  resolveBaseUrl: (region) => new URL(`https://${region}.my-proxy.example`),
+});
+
+// Custom domain with a base path (e.g. reverse proxy prefix)
+const queue = new QueueClient({
+  resolveBaseUrl: (region) =>
+    new URL(`https://my-proxy.example/queues/${region}`),
+  // → requests go to https://my-proxy.example/queues/<region>/api/v3/…
 });
 ```
 
+The SDK always appends its own API path (`/api/v3/…`) to the returned URL.
+
 ## Transports
 
 The transport controls how message payloads are serialized and deserialized.
@@ -361,7 +374,6 @@ import {
 
 // JSON 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),
@@ -370,14 +382,12 @@ const queue = new QueueClient({
 
 // Binary data
 const binQueue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   transport: new BufferTransport(),
 });
 await binQueue.send("binary-topic", myBuffer);
 
 // Streaming for large payloads
 const streamQueue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   transport: new StreamTransport(),
 });
 await streamQueue.send("large-file", myReadableStream);
@@ -385,30 +395,25 @@ await streamQueue.send("large-file", myReadableStream);
 
 ## Manual Receive
 
-Use `receive` to pull and process messages directly. This is an advanced alternative to `handleCallback` that works in any Node.js environment, both on and off Vercel.
+Use `PollingQueueClient` to poll for and process messages directly. This is an advanced alternative to `handleCallback` that works in any Node.js environment, both on and off Vercel.
 
 ### Region considerations
 
-Messages can only be received from the region they were sent to. When using `receive`, use a **fixed region** (e.g. `"iad1"`) for both sending and receiving — do not use `VERCEL_REGION` (or `QUEUE_REGION=${VERCEL_REGION}`), because Vercel may route requests to different regions due to failover or load balancing, distributing your messages across regions unpredictably.
-
-```bash
-# .env.production — fixed region for manual receive workflows
-QUEUE_REGION=iad1
-
-# .env.development
-QUEUE_REGION=iad1
-```
+Messages can only be received from the region they were sent to. When using `receive`, use a **fixed region** (e.g. `"iad1"`) for both sending and receiving — do not use `VERCEL_REGION`, because Vercel may route requests to different regions due to failover or load balancing, distributing your messages across regions unpredictably.
 
 A single region is still highly available — Vercel deploys across 3+ availability zones within each region. If you need multi-region availability, you are responsible for designing your own HA strategy (e.g. sending to multiple regions and receiving from each).
 
-For most use cases on Vercel, `handleCallback` is the recommended approach — the platform handles region routing automatically and the SDK routes follow-up calls to the correct region via the `ce-vqsregion` header.
+For most use cases on Vercel, `handleCallback` via `QueueClient` is the recommended approach — the platform handles region routing automatically and the SDK routes follow-up calls to the correct region via the `ce-vqsregion` header.
 
 ### Usage
 
 ```typescript
-import { QueueClient } from "@vercel/queue";
+import { PollingQueueClient } from "@vercel/queue";
 
-const { receive } = new QueueClient({ region: "iad1" });
+const { send, receive } = new PollingQueueClient({ region: "iad1" });
+
+// Send a message
+await send("my-topic", { message: "Hello world" });
 
 // Process next available message
 const result = await receive(
@@ -481,12 +486,11 @@ All error types:
 
 ## Environment Variables
 
-| Variable               | Description                                     | Default |
-| ---------------------- | ----------------------------------------------- | ------- |
-| `QUEUE_REGION`         | Region code for the queue client (user-defined) | -       |
-| `VERCEL_REGION`        | Current region (auto-set by Vercel)             | -       |
-| `VERCEL_QUEUE_DEBUG`   | Enable debug logging (`1` or `true`)            | -       |
-| `VERCEL_DEPLOYMENT_ID` | Deployment ID (auto-set by Vercel)              | -       |
+| Variable               | Description                          | Default |
+| ---------------------- | ------------------------------------ | ------- |
+| `VERCEL_REGION`        | Current region (auto-set by Vercel)  | -       |
+| `VERCEL_QUEUE_DEBUG`   | Enable debug logging (`1` or `true`) | -       |
+| `VERCEL_DEPLOYMENT_ID` | Deployment ID (auto-set by Vercel)   | -       |
 
 ## Service Limits & Constraints
 
@@ -547,12 +551,14 @@ All error types:
 
 ### `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.
+
 ```typescript
 import { QueueClient } from "@vercel/queue";
 
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
-  resolveBaseUrl: (r) => `https://${r}.vercel-queue.com`, // Default resolver
+  region: "iad1", // Optional — auto-detected from VERCEL_REGION, falls back to "iad1"
+  resolveBaseUrl: (r) => new URL(`https://${r}.vercel-queue.com`), // Default resolver
   token: "my-token", // Auto-fetched via OIDC if omitted
   headers: { "X-Custom": "value" },
   transport: new JsonTransport(), // Default: JsonTransport
@@ -560,11 +566,29 @@ const queue = new QueueClient({
 });
 
 // Methods (arrow functions — safe to destructure)
-const { send, receive, handleCallback, handleNodeCallback } = queue;
+const { send, handleCallback, handleNodeCallback } = queue;
+```
+
+### `PollingQueueClient`
+
+Poll-based client for manually receiving messages. Works in any Node.js environment, including self-hosted and non-Vercel platforms. Region is required to ensure send and receive target the same endpoint.
+
+```typescript
+import { PollingQueueClient } from "@vercel/queue";
+
+const queue = new PollingQueueClient({
+  region: "iad1", // Required — use a fixed region for polling
+  // ... same options as QueueClient (except region is required)
+});
+
+// Methods (arrow functions — safe to destructure)
+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
@@ -578,6 +602,8 @@ const { messageId } = await send("my-topic", payload, {
 
 ### `receive(topicName, consumerGroup, handler, options?)`
 
+Available on `PollingQueueClient` only.
+
 Returns a discriminated result: `{ ok: true }` on success, or `{ ok: false, reason }` when no message was processed. The handler is never called when the queue is empty.
 
 For receive-by-id, operational errors are returned instead of thrown:
@@ -602,7 +628,9 @@ const result = await receive("my-topic", "my-group", handler, {
 
 ### `handleCallback(handler, options?)`
 
-Vercel only. Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
+Available on `QueueClient` only. Vercel only.
+
+Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
 
 ```typescript
 export const POST = handleCallback(
@@ -620,7 +648,9 @@ export const POST = handleCallback(
 
 ### `handleNodeCallback(handler, options?)`
 
-Vercel only. Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
+Available on `QueueClient` only. Vercel only.
+
+Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
 ```typescript
 // pages/api/queue/my-topic.ts

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...
  * });
@@ -130,11 +129,24 @@ declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
  */
 type VercelRegion = "arn1" | "bom1" | "cdg1" | "cle1" | "cpt1" | "dub1" | "dxb1" | "fra1" | "gru1" | "hkg1" | "hnd1" | "iad1" | "icn1" | "kix1" | "lhr1" | "pdx1" | "sfo1" | "sin1" | "syd1" | "yul1" | (string & {});
 /**
- * Resolves a region code to a base URL for the Vercel Queue Service API.
+ * Resolves a region code to a base {@link URL} for the Vercel Queue Service API.
+ *
+ * The SDK appends its own API path (`/api/v3/…`) to the returned URL.
+ * To add a prefix (e.g. when routing through a reverse proxy), include it
+ * in the pathname of the returned URL:
  *
- * Default: `` (region) => `https://${region}.vercel-queue.com` ``
+ * ```ts
+ * // Default — domain only, no prefix:
+ * (region) => new URL(`https://${region}.vercel-queue.com`)
+ *
+ * // Custom domain with a base path:
+ * (region) => new URL(`https://my-proxy.example/custom-prefix`)
+ * // → requests go to https://my-proxy.example/custom-prefix/api/v3/…
+ * ```
+ *
+ * Default: `` (region) => new URL(`https://${region}.vercel-queue.com`) ``
  */
-type BaseUrlResolver = (region: string) => string;
+type BaseUrlResolver = (region: string) => URL;
 interface QueueClientOptions {
     /**
      * Vercel region code for API routing.
@@ -142,18 +154,28 @@ 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 URL.
-     * @default (region) => `https://${region}.vercel-queue.com`
+     * Custom resolver that maps a region code to a base {@link URL}.
+     *
+     * The SDK always appends its own API path (`/api/v3/…`) to the returned URL.
+     * Include a pathname to add a prefix (e.g. for reverse-proxy routing):
+     *
+     * ```ts
+     * resolveBaseUrl: (region) => new URL(`https://my-proxy.example/prefix`)
+     * ```
+     *
+     * @default (region) => new URL(`https://${region}.vercel-queue.com`)
      */
     resolveBaseUrl?: BaseUrlResolver;
     /**
@@ -184,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.
  */
@@ -475,14 +519,37 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+/**
+ * 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);
      * ```
      *
@@ -493,28 +560,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.
      *
@@ -523,7 +568,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);
      * ```
      *
@@ -547,7 +592,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));
      * ```
      *
@@ -573,6 +618,67 @@ 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>;
+}
 
 /**
  * Core queue callback utilities for handling incoming webhook payloads
@@ -647,4 +753,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, parseCallback, parseRawCallback };