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

package/README.md

@@ -4,14 +4,12 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 
 ## Features
 
-- **Automatic Queue Triggering**: Vercel automatically triggers your API routes when messages are ready
-- **Next.js Integration**: Built-in support for Next.js App Router and Pages Router
-- **Generic Payload Support**: Send and receive any type of data with type safety
-- **Pub/Sub Pattern**: Topic-based messaging with consumer groups
-- **Type Safety**: Full TypeScript support with generic types
-- **Streaming Support**: Handle large payloads efficiently
-- **Customizable Serialization**: Use built-in transports (JSON, Buffer, Stream) or create your own
-- **Framework Adapters**: Web API, Next.js App Router, and Pages Router support
+- **Simple API**: `send` and `receive` are all you need
+- **Automatic Triggering on Vercel**: Vercel invokes your route handlers when messages are ready
+- **Works Anywhere**: `send` and `receive` work in any Node.js environment
+- **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
 
 ## Installation
 
@@ -21,58 +19,93 @@ npm install @vercel/queue
 
 ## Quick Start
 
-For local development, you'll need to set up your Vercel project:
+Set up your region via environment variables. If your framework supports `.env` files (Next.js, Vite, Nuxt, etc.):
 
 ```bash
-# Install Vercel CLI if you haven't already
-npm i -g vercel
+# .env.production (on Vercel, inherits the platform's region)
+QUEUE_REGION=${VERCEL_REGION}
 
-# Link your project to Vercel
-vc link
+# .env.development (fixed region for local dev — iad1 is recommended)
+QUEUE_REGION=iad1
+```
 
-# Pull environment variables from your Vercel project
-vc env pull
+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:
+
+```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;
 ```
 
-## Local Development
+Send a message anywhere in your app:
 
-**Queues just work locally.** After you have setup your Vercel project, when you `send()` messages in development mode, they automatically trigger your handlers locally - no external queue infrastructure needed.
+```typescript
+import { send } from "@/lib/queue";
 
-The library reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically when messages are sent.
+await send("my-topic", { message: "Hello world" });
+```
 
-> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically when running `npm run dev`.
+Handle incoming messages with a route handler:
 
-### Example Workflow
+```typescript
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@/lib/queue";
 
-```bash
-# Start your dev server
-npm run dev
+export const POST = handleCallback(async (message, metadata) => {
+  console.log("Processing:", message);
+});
+```
 
-# Send messages - they process locally automatically!
+Configure your `vercel.json`:
+
+```json
+{
+  "functions": {
+    "app/api/queue/my-topic/route.ts": {
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "my-topic" }]
+    }
+  }
+}
 ```
 
-### Publishing Messages
+### Project Setup
 
-The `send` function can be used anywhere in your codebase to publish messages to a queue:
+For local development, link your Vercel project:
+
+```bash
+npm i -g vercel
+vc link
+vc env pull
+```
+
+## 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.
+
+> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically during `npm run dev`.
+
+## Publishing Messages
 
 ```typescript
-import { send } from "@vercel/queue";
+import { QueueClient } from "@vercel/queue";
 
-// Send a message to a topic
-await send("my-topic", {
-  message: "Hello world",
-});
+const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
 
-// With additional options
+// Simple send
+await send("my-topic", { message: "Hello world" });
+
+// With options
 await send(
   "my-topic",
+  { message: "Hello world" },
   {
-    message: "Hello world",
-  },
-  {
-    idempotencyKey: "unique-key", // Optional: prevent duplicate messages
-    retentionSeconds: 3600, // Optional: override retention time (defaults to 24 hours)
-    delaySeconds: 60, // Optional: delay message delivery by N seconds
+    idempotencyKey: "unique-key", // Prevent duplicate messages
+    retentionSeconds: 3600, // 1 hour TTL (default: 24h)
+    delaySeconds: 60, // Delay delivery by 1 minute
   },
 );
 ```
@@ -81,41 +114,37 @@ Example usage in an API route:
 
 ```typescript
 // app/api/send-message/route.ts
-import { send } from "@vercel/queue";
+import { send } from "@/lib/queue";
 
 export async function POST(request: Request) {
   const body = await request.json();
-
-  const { messageId } = await send("my-topic", {
-    message: body.message,
-  });
-
+  const { messageId } = await send("my-topic", { message: body.message });
   return Response.json({ messageId });
 }
 ```
 
-### Consuming Messages
+> **Note:** `messageId` is `null` when the server accepts the message for deferred processing (e.g. during a server-side outage). The message will still be delivered.
 
-Messages are consumed using API routes that Vercel automatically triggers when messages are available.
+## Consuming Messages
 
-#### 1. Create API Routes
+### On Vercel
 
-##### Web API (`@vercel/queue/web`)
+On Vercel, messages are consumed using API route handlers that Vercel automatically invokes when messages are available. Use `handleCallback` or `handleNodeCallback` to create these route handlers.
 
-The `handleCallback` from `@vercel/queue/web` returns a standard `(Request) => Promise<Response>` handler. It works with any framework that uses the Web API `Request`/`Response` types, including Next.js App Router, Hono, and others.
+#### Web API — `handleCallback`
+
+Returns `(Request) => Promise<Response>`. For frameworks that export Web API route handlers (Next.js App Router, Hono, etc.).
 
 **Next.js App Router:**
 
 ```typescript
 // app/api/queue/my-topic/route.ts
-import { handleCallback } from "@vercel/queue/web";
+import { handleCallback } from "@/lib/queue";
 
 export const POST = handleCallback(async (message, metadata) => {
-  // metadata includes: { messageId, deliveryCount, createdAt, topicName, consumerGroup }
-  console.log("Processing message:", message);
-
-  // If this throws an error, the message will be automatically retried
+  // metadata: { messageId, deliveryCount, createdAt, expiresAt?, topicName, consumerGroup, region }
   await processMessage(message);
+  // Throwing an error will automatically retry the message
 });
 ```
 
@@ -123,57 +152,53 @@ export const POST = handleCallback(async (message, metadata) => {
 
 ```typescript
 import { Hono } from "hono";
-import { handleCallback } from "@vercel/queue/web";
+import { handleCallback } from "@/lib/queue";
 
 const app = new Hono();
-
 app.post(
   "/api/queue",
   handleCallback(async (message, metadata) => {
-    console.log("Processing:", message);
+    await processMessage(message);
   }),
 );
-
 export default app;
 ```
 
-For multiple topics/consumers, create separate route files:
+#### Connect-style — `handleNodeCallback`
 
-```typescript
-// app/api/queue/orders/fulfillment/route.ts
-import { handleCallback } from "@vercel/queue/web";
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Express, Next.js Pages Router, etc.).
 
-export const POST = handleCallback(async (order, metadata) => {
-  await processOrder(order);
-});
-```
+**Next.js Pages Router:**
 
 ```typescript
-// app/api/queue/orders/analytics/route.ts
-import { handleCallback } from "@vercel/queue/web";
+// pages/api/queue/my-topic.ts
+import { handleNodeCallback } from "@/lib/queue";
 
-export const POST = handleCallback(async (order, metadata) => {
-  await trackOrder(order);
+export default handleNodeCallback(async (message, metadata) => {
+  await processMessage(message);
 });
 ```
 
-##### Pages Router (`@vercel/queue/nextjs/pages`)
-
-For Next.js Pages Router, import from `@vercel/queue/nextjs/pages`. This returns a `(req, res) => Promise<void>` handler:
+**Express:**
 
 ```typescript
-// pages/api/queue/my-topic.ts
-import { handleCallback } from "@vercel/queue/nextjs/pages";
+import express from "express";
+import { handleNodeCallback } from "@/lib/queue";
 
-export default handleCallback(async (message, metadata) => {
-  console.log("Processing message:", message);
-  await processMessage(message);
-});
+const app = express();
+app.use(express.json());
+app.post(
+  "/api/queue/my-topic",
+  handleNodeCallback(async (message, metadata) => {
+    await processMessage(message);
+  }),
+);
+export default app;
 ```
 
-#### 2. Configure vercel.json
+### 2. Configure vercel.json
 
-Configure which topics and consumers your API routes handle.
+Tell Vercel which routes handle which topics:
 
 ```json
 {
@@ -190,10 +215,7 @@ Configure which topics and consumers your API routes handle.
     },
     "app/api/queue/orders/fulfillment/route.ts": {
       "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "order-events"
-        }
+        { "type": "queue/v2beta", "topic": "order-events" }
       ]
     },
     "app/api/queue/orders/analytics/route.ts": {
@@ -209,152 +231,207 @@ Configure which topics and consumers your API routes handle.
 }
 ```
 
-### Key Concepts
+Multiple route files for the same topic create separate consumer groups — each receives a copy of every message.
 
-- **Topics**: Named message channels that can have multiple consumer groups
-- **Consumer Groups**: Named groups of consumers that process messages in parallel
-  - Different consumer groups for the same topic each get a copy of every message
-  - Multiple consumers in the same group share/split messages for load balancing
-- **Automatic Triggering**: Vercel triggers your API routes when messages are available
-- **Message Processing**: Your API routes receive message metadata via headers
-- **Configuration**: The `vercel.json` file tells Vercel which routes handle which topics/consumers
-- **Delivery Modes**: The server uses CloudEvents binary content mode to deliver messages. For small messages, the full payload and receipt handle are pushed directly in the HTTP body and headers, avoiding an extra API fetch. For large messages, only the message ID is sent and the SDK fetches the payload.
+### 3. Retry and Backoff
 
-## Advanced Features
+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:
+
+```typescript
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => {
+      if (error instanceof RateLimitError) return { afterSeconds: 60 };
+      // Return undefined to let the error propagate normally
+    },
+  },
+);
+```
 
-### Custom Client Configuration
+When `retry` returns `{ afterSeconds: N }`, the message is rescheduled for redelivery after N seconds. Return `{ acknowledge: true }` to acknowledge the message so it is never retried. When it returns `undefined`, the error propagates normally and the message is retried at the default interval.
 
-For custom configuration (tokens, headers, transport), create a `QueueClient` and pass it via options:
+**Exponential backoff** uses `metadata.deliveryCount` (starts at 1, increments each delivery):
 
 ```typescript
-import { QueueClient, send } from "@vercel/queue";
-import { handleCallback } from "@vercel/queue/web";
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => {
+      // 5s → 10s → 20s → 40s → ... capped at 5 min
+      const delay = Math.min(300, 2 ** metadata.deliveryCount * 5);
+      return { afterSeconds: delay };
+    },
+  },
+);
+```
 
-const client = new QueueClient({
-  token: "my-token",
-  headers: { "X-Custom": "header" },
-});
+**Conditional retry** — only retry transient errors:
+
+```typescript
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => {
+      if (error instanceof RateLimitError) return { afterSeconds: 60 };
+      if (error instanceof TemporaryError) return { afterSeconds: 30 };
+      // Permanent errors: return undefined → retried at the default interval
+    },
+  },
+);
+```
 
-// Send with custom client
-await send("my-topic", { hello: "world" }, { client });
+**Acknowledging poison messages** — stop retrying messages that can never succeed:
 
-// Handle callbacks with custom client
-export const POST = handleCallback(async (msg, meta) => console.log(msg), {
-  client,
-});
+```typescript
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => {
+      if (error instanceof ValidationError) return { acknowledge: true };
+      if (metadata.deliveryCount > 5) return { acknowledge: true };
+      return { afterSeconds: Math.min(300, 2 ** metadata.deliveryCount * 5) };
+    },
+  },
+);
 ```
 
-### Core Handler (Framework Agnostic)
+The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `receive`.
+
+## Custom Client Configuration
 
-For custom framework integration, use the core `handleCallback` from `@vercel/queue`. It takes parsed request data and throws on errors:
+All configuration lives on the `QueueClient`:
 
 ```typescript
-import { handleCallback, parseRawCallback } from "@vercel/queue";
+import { QueueClient, BufferTransport } from "@vercel/queue";
+
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
+  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
+});
 
-// In your framework handler:
-const parsed = parseRawCallback(body, headers);
-try {
-  await handleCallback(async (msg, meta) => {
-    console.log("Processing:", msg);
-  }, parsed);
-  // success
-} catch (error) {
-  // handle error → 500
-}
+// Use directly
+await queue.send("my-topic", myBuffer);
+
+// Or destructure
+export const { send, receive, handleCallback, handleNodeCallback } = queue;
 ```
 
-### Serialization (Transport) System
+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.
 
-The queue client supports customizable serialization through the `Transport` interface:
+To customize the URL scheme, provide a `resolveBaseUrl`:
+
+```typescript
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  resolveBaseUrl: (region) => `https://${region}.my-proxy.example`,
+});
+```
 
-#### Built-in Transports
+## Transports
 
-1. **JsonTransport (Default)**: For structured data that fits in memory
-2. **BufferTransport**: For binary data that fits in memory
-3. **StreamTransport**: For large files and memory-efficient processing
+The transport controls how message payloads are serialized and deserialized.
 
-Example:
+| Use Case        | Transport         | Memory Usage | Notes                   |
+| --------------- | ----------------- | ------------ | ----------------------- |
+| Structured data | `JsonTransport`   | Low          | Default, JSON encoding  |
+| Binary data     | `BufferTransport` | Medium       | Raw bytes               |
+| Large payloads  | `StreamTransport` | Very Low     | No buffering, streaming |
 
 ```typescript
-import { send, JsonTransport } from "@vercel/queue";
+import {
+  QueueClient,
+  JsonTransport,
+  BufferTransport,
+  StreamTransport,
+} from "@vercel/queue";
 
-// JsonTransport is the default
-await send("json-topic", { data: "example" });
+// 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),
+  }),
+});
 
-// Explicit transport configuration
-await send(
-  "json-topic",
-  { data: "example" },
-  { transport: new JsonTransport() },
-);
+// Binary data
+const binQueue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  transport: new BufferTransport(),
+});
+await binQueue.send("binary-topic", myBuffer);
 
-// JsonTransport with custom serialization
-const transport = new JsonTransport({
-  replacer: (key, value) => (key === "password" ? undefined : value),
-  reviver: (key, value) => (key === "date" ? new Date(value) : value),
+// Streaming for large payloads
+const streamQueue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  transport: new StreamTransport(),
 });
-await send("json-topic", { data: "example" }, { transport });
+await streamQueue.send("large-file", myReadableStream);
 ```
 
-### Transport Selection Guide
+## Manual Receive
 
-| Use Case           | Recommended Transport | Memory Usage | Performance |
-| ------------------ | --------------------- | ------------ | ----------- |
-| Small JSON objects | JsonTransport         | Low          | High        |
-| Binary data        | BufferTransport       | Medium       | High        |
-| Large payloads     | StreamTransport       | Very Low     | Medium      |
-| Real-time streams  | StreamTransport       | Very Low     | High        |
+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.
 
-## Handling Empty Queues
+### Region considerations
 
-When no messages are available in the queue, the handler receives `null` for both the message and metadata parameters. This allows graceful handling without exceptions:
+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.
 
-```typescript
-await receive("my-topic", "my-consumer", async (message, metadata) => {
-  if (!message) {
-    console.log("No message received - queue is empty");
-    return;
-  }
+```bash
+# .env.production — fixed region for manual receive workflows
+QUEUE_REGION=iad1
 
-  // Process the message
-  console.log("Processing:", message);
-  console.log("Message ID:", metadata.messageId);
-});
+# .env.development
+QUEUE_REGION=iad1
 ```
 
-The same pattern works with `handleCallback`:
+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.
+
+### Usage
 
 ```typescript
-import { handleCallback } from "@vercel/queue/web";
+import { QueueClient } from "@vercel/queue";
 
-export const POST = handleCallback(async (message, metadata) => {
-  if (!message) {
-    // No message available - handle gracefully
-    return;
-  }
-  await processMessage(message);
-});
-```
+const { receive } = new QueueClient({ region: "iad1" });
 
-## Error Handling
+// Process next available message
+const result = await receive(
+  "my-topic",
+  "my-group",
+  async (message, metadata) => {
+    console.log("Processing:", message);
+  },
+);
+if (!result.ok) {
+  console.log("Queue was empty:", result.reason);
+}
+
+// Batch processing: up to 10 messages in one request
+await receive("my-topic", "my-group", handler, { limit: 10 });
 
-The queue client provides specific error types:
+// Process a specific message by ID
+await receive("my-topic", "my-group", handler, { messageId: "msg-123" });
+```
 
-- **`MessageLockedError`**: Message is being processed by another consumer
-- **`MessageNotFoundError`**: Message doesn't exist or has expired
-- **`MessageNotAvailableError`**: Message exists but cannot be claimed
-- **`MessageAlreadyProcessedError`**: Message was already successfully processed
-- **`MessageCorruptedError`**: Message data could not be parsed
-- **`BadRequestError`**: Invalid request parameters
-- **`UnauthorizedError`**: Authentication failed (invalid or missing token)
-- **`ForbiddenError`**: Access denied (wrong environment or project)
-- **`DuplicateMessageError`**: Idempotency key was already used
-- **`ConsumerDiscoveryError`**: Could not reach the consumer deployment
-- **`ConsumerRegistryNotConfiguredError`**: Project not configured for queues
-- **`InternalServerError`**: Unexpected server error
-- **`InvalidLimitError`**: Batch limit outside valid range (1-10)
+> **Note:** `limit` and `messageId` are mutually exclusive options. The handler is never called when the queue is empty — check `result.ok` instead.
 
-Example error handling:
+## Error Handling
 
 ```typescript
 import {
@@ -364,6 +441,7 @@ import {
   InternalServerError,
   UnauthorizedError,
 } from "@vercel/queue";
+import { send } from "@/lib/queue";
 
 try {
   await send("my-topic", payload);
@@ -382,63 +460,33 @@ try {
 }
 ```
 
-## Environment Variables
-
-The following environment variables can be used to configure the queue client:
-
-| Variable                 | Description                          | Default                    |
-| ------------------------ | ------------------------------------ | -------------------------- |
-| `VERCEL_QUEUE_BASE_URL`  | Override the queue service URL       | `https://vercel-queue.com` |
-| `VERCEL_QUEUE_BASE_PATH` | Override the API base path           | `/api/v3/topic`            |
-| `VERCEL_QUEUE_DEBUG`     | Enable debug logging (`1` or `true`) | -                          |
-| `VERCEL_DEPLOYMENT_ID`   | Deployment ID (auto-set by Vercel)   | -                          |
-
-## Advanced Usage
-
-### Direct Message Processing
+All error types:
+
+| Error                                | Description                                   |
+| ------------------------------------ | --------------------------------------------- |
+| `BadRequestError`                    | Invalid request parameters                    |
+| `UnauthorizedError`                  | Authentication failed (invalid/missing token) |
+| `ForbiddenError`                     | Access denied (wrong environment/project)     |
+| `DuplicateMessageError`              | Idempotency key already used                  |
+| `ConsumerDiscoveryError`             | Could not reach consumer deployment           |
+| `ConsumerRegistryNotConfiguredError` | Project not configured for queues             |
+| `InternalServerError`                | Unexpected server error                       |
+| `InvalidLimitError`                  | Batch limit outside valid range (1-10)        |
+| `MessageNotFoundError`               | Message doesn't exist or expired              |
+| `MessageNotAvailableError`           | Message exists but cannot be claimed          |
+| `MessageAlreadyProcessedError`       | Message already successfully processed        |
+| `MessageLockedError`                 | Message being processed by another consumer   |
+| `MessageCorruptedError`              | Message data could not be parsed              |
+| `QueueEmptyError`                    | No messages available in queue                |
 
-> **Note**: The `receive` function is for advanced use cases where you need direct message processing control outside of Vercel's automatic triggering.
-
-```typescript
-import { receive } from "@vercel/queue";
-
-// Process next available message (or null if queue is empty)
-await receive<T>(topicName, consumerGroup, async (message, metadata) => {
-  if (!message) {
-    console.log("Queue is empty");
-    return;
-  }
-  // Process message
-});
-
-// Batch processing: fetch up to 10 messages in one request
-await receive<T>(topicName, consumerGroup, handler, {
-  limit: 10, // Default: 1, Min: 1, Max: 10
-});
-
-// Process specific message by ID
-await receive<T>(topicName, consumerGroup, handler, {
-  messageId: "message-id",
-});
+## Environment Variables
 
-// Note: limit and messageId are mutually exclusive options
-
-// Handler function signature
-// When queue is empty, both message and metadata are null
-type MessageHandler<T = unknown> = (
-  message: T | null,
-  metadata: MessageMetadata | null,
-) => Promise<void> | void;
-
-// MessageMetadata type
-interface MessageMetadata {
-  messageId: string;
-  deliveryCount: number;
-  createdAt: Date;
-  topicName: string;
-  consumerGroup: string;
-}
-```
+| 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)              | -       |
 
 ## Service Limits & Constraints
 
@@ -464,57 +512,32 @@ interface MessageMetadata {
 
 #### Receiving Messages
 
-| Parameter                  | Default | Min | Max   | Notes                       |
-| -------------------------- | ------- | --- | ----- | --------------------------- |
-| `visibilityTimeoutSeconds` | 30      | 0   | 3,600 | 0 = immediate re-visibility |
-| `limit`                    | 1       | 1   | 10    | Messages per request        |
-
-#### Visibility Extension
-
-| Constraint                 | Value                              |
-| -------------------------- | ---------------------------------- |
-| `visibilityTimeoutSeconds` | 0 - 3,600 seconds                  |
-| Cannot extend beyond       | Message's original expiration time |
-| Receipt handle             | Must match the receive operation   |
+| Parameter                  | Default | Min | Max   | Notes                           |
+| -------------------------- | ------- | --- | ----- | ------------------------------- |
+| `visibilityTimeoutSeconds` | 300     | 30  | 3,600 | Lock duration during processing |
+| `limit`                    | 1       | 1   | 10    | Messages per request            |
 
 ### Identifier Formats
 
-| Identifier       | Pattern          | Example                          |
-| ---------------- | ---------------- | -------------------------------- |
-| Topic/Queue name | `[A-Za-z0-9_-]+` | `my-queue`, `task_queue_v2`      |
-| Consumer group   | `[A-Za-z0-9_-]+` | `worker-1`, `analytics_consumer` |
-| Message ID       | Opaque string    | `0-1`, `3-7K9mNpQrS`             |
-| Receipt handle   | Opaque string    | Used for delete/visibility ops   |
-
-### Content-Type Handling
-
-| Scenario                        | Result                     |
-| ------------------------------- | -------------------------- |
-| Client provides `Content-Type`  | Used as-is                 |
-| No header, magic bytes detected | Auto-detected MIME type    |
-| No header, detection fails      | `application/octet-stream` |
+| Identifier     | Pattern          | Example                             |
+| -------------- | ---------------- | ----------------------------------- |
+| Topic name     | `[A-Za-z0-9_-]+` | `my-queue`, `task_queue_v2`         |
+| Consumer group | `[A-Za-z0-9_-]+` | `worker-1`, `analytics_consumer`    |
+| Message ID     | Opaque string    | `0-1`, `3-7K9mNpQrS`                |
+| Receipt handle | Opaque string    | Used for acknowledge/visibility ops |
 
 ### Wildcard Topics
 
-Topic patterns support wildcards for flexible routing:
-
 ```json
 {
   "functions": {
     "app/api/queue/route.ts": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "user-*"
-        }
-      ]
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "user-*" }]
     }
   }
 }
 ```
 
-**Wildcard Rules:**
-
 - `*` may only appear **once** in the pattern
 - `*` must be at the **end** of the topic name
 - Valid: `user-*`, `orders-*`
@@ -522,142 +545,111 @@ Topic patterns support wildcards for flexible routing:
 
 ## API Reference
 
-### Export Structure
-
-| Import Path                  | `handleCallback`                                                 |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `@vercel/queue`              | Core async function: `(handler, parsed, opts?) => Promise<void>` |
-| `@vercel/queue/web`          | Returns `(request: Request) => Promise<Response>`                |
-| `@vercel/queue/nextjs/pages` | Returns `(req, res) => Promise<void>`                            |
-
-Additional exports from `@vercel/queue`:
-
-| Export                    | Description                                                   |
-| ------------------------- | ------------------------------------------------------------- |
-| `parseCallback`           | Parse a Web API `Request` into a `ParsedCallbackRequest`      |
-| `parseRawCallback`        | Parse a pre-parsed body + headers (e.g. Pages Router)         |
-| `CLOUD_EVENT_TYPE_V2BETA` | `"com.vercel.queue.v2beta"` — binary CloudEvent type constant |
-
-### QueueClient Configuration
+### `QueueClient`
 
 ```typescript
 import { QueueClient } from "@vercel/queue";
 
-const client = new QueueClient({
-  // Base URL for the queue service
-  // Default: "https://vercel-queue.com"
-  // Env: VERCEL_QUEUE_BASE_URL
-  baseUrl: "https://vercel-queue.com",
-
-  // API path prefix
-  // Default: "/api/v3/topic"
-  // Env: VERCEL_QUEUE_BASE_PATH
-  basePath: "/api/v3/topic",
-
-  // Auth token (auto-fetched via OIDC if not provided)
-  token: "my-token",
-
-  // Custom headers for all requests
+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
+  token: "my-token", // Auto-fetched via OIDC if omitted
   headers: { "X-Custom": "value" },
-
-  // Deployment ID for message routing
-  // Default: process.env.VERCEL_DEPLOYMENT_ID
-  deploymentId: "dpl_xxx",
-
-  // Pin messages to current deployment when publishing
-  // Default: true
-  pinToDeployment: true,
+  transport: new JsonTransport(), // Default: JsonTransport
+  deploymentId: undefined, // omit = auto from env (pinned), null = unpinned, or explicit string
 });
 
-// Pass to any function via options
-await send("my-topic", payload, { client });
-export const POST = handleCallback(handler, { client });
+// Methods (arrow functions — safe to destructure)
+const { send, receive, handleCallback, handleNodeCallback } = queue;
 ```
 
-### Send Options
-
-```typescript
-await send("my-topic", payload, {
-  // Deduplication key
-  // Dedup window: min(retentionSeconds, 24 hours)
-  idempotencyKey: "unique-key",
-
-  // Message TTL in seconds
-  // Default: 86400, Min: 60, Max: 86400
-  retentionSeconds: 3600,
+### `send(topicName, payload, options?)`
 
-  // Delay before message becomes visible
-  // Default: 0, Min: 0, Max: retentionSeconds
-  delaySeconds: 60,
+Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
 
-  // Custom serializer (default: JsonTransport)
-  transport: new JsonTransport(),
+```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 Options
+### `receive(topicName, consumerGroup, handler, options?)`
+
+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.
 
-The `receive` function supports two mutually exclusive modes:
+For receive-by-id, operational errors are returned instead of thrown:
 
 ```typescript
-// Batch mode: receive multiple messages
-await receive("my-topic", "my-consumer", handler, {
-  // Maximum messages to retrieve in a single request
-  // Default: 1, Min: 1, Max: 10
-  limit: 10,
-
-  // Message lock duration in seconds
-  // Default: 300, Min: 30, Max: 3600
-  visibilityTimeoutSeconds: 60,
+const result = await receive("my-topic", "my-group", handler, {
+  messageId: "msg-123",
 });
+if (!result.ok) {
+  // result.reason is "not_found" | "not_available" | "already_processed"
+  console.log(result.reason, result.messageId);
+}
+```
 
-// By-ID mode: receive a specific message
-await receive("my-topic", "my-consumer", handler, {
-  // Specific message ID to consume
-  messageId: "0-1",
-
-  // Message lock duration in seconds
-  // Default: 300, Min: 30, Max: 3600
-  visibilityTimeoutSeconds: 60,
+```typescript
+// Batch mode
+const result = await receive("my-topic", "my-group", handler, {
+  limit: 10, // Max messages (default: 1, max: 10)
+  visibilityTimeoutSeconds: 60, // Lock duration (default: 300)
 });
 ```
 
-> **Note**: `limit` and `messageId` cannot be used together - they are mutually exclusive options.
+### `handleCallback(handler, options?)`
 
-### handleCallback Options
+Vercel only. Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
 
 ```typescript
-import { handleCallback } from "@vercel/queue/web";
-
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
   },
   {
-    // Message lock duration for long-running handlers
-    // Default: 300, Min: 30, Max: 3600
-    visibilityTimeoutSeconds: 300, // 5 minutes
+    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
+    retry: (error, metadata) => {
+      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
+    },
   },
 );
 ```
 
-### Core handleCallback
+### `handleNodeCallback(handler, options?)`
 
-The core `handleCallback` is an async function that takes already-parsed request data. Use it to build custom framework integrations:
+Vercel only. Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
 ```typescript
-import { handleCallback, parseCallback, parseRawCallback } from "@vercel/queue";
+// pages/api/queue/my-topic.ts
+export default handleNodeCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => ({ afterSeconds: 60 }),
+  },
+);
+```
 
-// Web API Request
-const parsed = await parseCallback(request);
+### Handler Signature
 
-// Or, for frameworks that pre-parse the body (e.g. Pages Router)
-const parsed = parseRawCallback(req.body, req.headers);
+```typescript
+type MessageHandler<T> = (
+  message: T,
+  metadata: MessageMetadata,
+) => Promise<void> | void;
 
-try {
-  await handleCallback(handler, parsed);
-} catch (error) {
-  // handle error → 500
+interface MessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  createdAt: Date;
+  expiresAt?: Date;
+  topicName: string;
+  consumerGroup: string;
+  region: string;
 }
 ```