@vercel/queue 0.0.0-alpha.9 → 0.0.2

package/README.md

@@ -1,20 +1,15 @@
 # Vercel Queues
 
-A TypeScript client library for interacting with the Vercel Queue Service API
-with customizable serialization/deserialization (transport) support, including
-**streaming support** for memory-efficient processing of large payloads.
+A TypeScript client library for interacting with the Vercel Queue Service API, designed for seamless integration with Vercel deployments.
 
 ## Features
 
-- **Generic Payload Support**: Send and receive any type of data with type
-  safety
-- **Customizable Serialization**: Use built-in transports (JSON, Buffer, Stream)
-  or create your own
-- **Streaming Support**: Handle large payloads without loading them entirely
-  into memory
-- **Pub/Sub Pattern**: Topic-based messaging with consumer groups
-- **Type Safety**: Full TypeScript support with generic types
-- **Automatic Retries**: Built-in visibility timeout management
+- **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
 
@@ -24,245 +19,211 @@ npm install @vercel/queue
 
 ## Quick Start
 
-For local development, you'll need to pull your Vercel environment variables
-(including the OIDC token):
+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}
 
-# Pull environment variables from your Vercel project
-vc env pull
+# .env.development (fixed region for local dev — iad1 is recommended)
+QUEUE_REGION=iad1
 ```
 
-Publishing and consuming messages on a queue
+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
-// index.ts
-import { send, receive } from "@vercel/queue";
-
-type Message = {
-  message: string;
-  timestamp: number;
-};
-
-// Send a message to a topic
-await send<Message>("my-topic", {
-  message: "Hello, World!",
-  timestamp: Date.now(),
-});
+// lib/queue.ts
+import { QueueClient } from "@vercel/queue";
 
-// Consume a single message off the queue
-// (Often wrapped in a loop to keep polling messages off the queue)
-await receive<Message>("my-topic", "my-consumer-group", (message, metadata) => {
-  console.log("Received:", message.message);
-  console.log("Timestamp:", new Date(message.timestamp));
-  console.log("Message Metadata", metadata);
-  // => { messageId, deliveryCount, timestamp }
-});
+const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+export const { send, receive, handleCallback, handleNodeCallback } = queue;
 ```
 
-## Usage with Vercel
+Send a message anywhere in your app:
 
-When deploying on Vercel, rather than having a persistent server subscribed to a
-queue, Vercel can automatically trigger your API routes when messages are ready for
-consumption based on your vercel.json configuration.
+```typescript
+import { send } from "@/lib/queue";
 
-To demonstrate using queues on Vercel, let's use a Next.js app. You can use an
-existing app or create one using
-[create-next-app](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+await send("my-topic", { message: "Hello world" });
+```
 
-### TypeScript Configuration
+Handle incoming messages with a route handler:
 
-Update your `tsconfig.json` to use `"bundler"` module resolution for proper
-package export resolution:
+```typescript
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@/lib/queue";
+
+export const POST = handleCallback(async (message, metadata) => {
+  console.log("Processing:", message);
+});
+```
+
+Configure your `vercel.json`:
 
 ```json
 {
-  "compilerOptions": {
-    "moduleResolution": "bundler"
-    // ... other options
+  "functions": {
+    "app/api/queue/my-topic/route.ts": {
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "my-topic" }]
+    }
   }
 }
 ```
 
-### Publishing messages to a queue
+### Project Setup
 
-Create a new server function to publish messages
+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
-// app/actions.ts
-"use server";
+import { QueueClient } from "@vercel/queue";
 
-import { send } from "@vercel/queue";
+const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
 
-export async function publishTestMessage(message: string) {
-  const { messageId } = await send("my-topic", {
-    message,
-    timestamp: Date.now(),
-  });
+// Simple send
+await send("my-topic", { message: "Hello world" });
 
-  console.log(`Published message ${messageId}`);
-}
+// With options
+await send(
+  "my-topic",
+  { message: "Hello world" },
+  {
+    idempotencyKey: "unique-key", // Prevent duplicate messages
+    retentionSeconds: 3600, // 1 hour TTL (default: 24h)
+    delaySeconds: 60, // Delay delivery by 1 minute
+  },
+);
 ```
 
-Now wire up the server function to your app
+Example usage in an API route:
 
-```jsx
-// app/some/page.tsx
-"use client";
-import { publishTestMessage } from "./actions";
+```typescript
+// app/api/send-message/route.ts
+import { send } from "@/lib/queue";
 
-export default function Page() {
-  return (
-    // ...
-    <button onClick={() => publishTestMessage("Hello world")}>
-      Publish Test Message
-    </button>
-  );
+export async function POST(request: Request) {
+  const body = await request.json();
+  const { messageId } = await send("my-topic", { message: body.message });
+  return Response.json({ messageId });
 }
 ```
 
-### Consuming the queue
+> **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 consumer groups, which provide load balancing and parallel processing capabilities.
+## Consuming Messages
 
-## Usage with Vercel
+### On Vercel
 
-To consume queue messages in a Vercel deployment, you need to create (Next.js) API routes and configure them in your `vercel.json` file.
+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.
 
-### 1. Create API Routes
+#### Web API — `handleCallback`
 
-Create API routes to handle incoming queue messages using the `handleCallback` helper:
+Returns `(Request) => Promise<Response>`. For frameworks that export Web API route handlers (Next.js App Router, Hono, etc.).
 
-```typescript
-// app/api/queue/handle/route.ts
-import { handleCallback } from "@vercel/queue";
-
-// Option 1: Single topic with multiple consumer groups
-export const POST = handleCallback({
-  "my-topic": {
-    "consumer-group-1": async (message, metadata) => {
-      console.log(`Consumer group 1 processing:`, message, metadata);
-      // Handle consumer group 1 logic
-      await processGroup1(message);
-    },
-    "consumer-group-2": async (message, metadata) => {
-      console.log(`Consumer group 2 processing:`, message, metadata);
-      // Handle consumer group 2 logic
-      await processGroup2(message);
-    },
-  },
-});
-
-async function processGroup1(message: any) {
-  // Consumer group 1 specific logic
-}
-
-async function processGroup2(message: any) {
-  // Consumer group 2 specific logic
-}
-```
+**Next.js App Router:**
 
 ```typescript
-// Alternative: Multiple topics in one handler
-export const POST = handleCallback({
-  "user-events": {
-    welcome: async (message, metadata) => {
-      console.log(`New user event:`, message, metadata);
-      await sendWelcomeEmail(message.email);
-    },
-  },
-  "order-events": {
-    fulfillment: async (order, metadata) => {
-      console.log(`Processing order:`, order, metadata);
-      await fulfillOrder(order);
-    },
-    analytics: async (order, metadata) => {
-      console.log(`Tracking order:`, order, metadata);
-      await trackOrder(order);
-    },
-  },
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@/lib/queue";
+
+export const POST = handleCallback(async (message, metadata) => {
+  // metadata: { messageId, deliveryCount, createdAt, expiresAt?, topicName, consumerGroup, region }
+  await processMessage(message);
+  // Throwing an error will automatically retry the message
 });
 ```
 
-### 2. Configure vercel.json
-
-Create a `vercel.json` file in your project root to declare which topics and consumer groups each API route handles:
+**Hono:**
 
-```json
-{
-  "functions": {
-    "app/api/queue/handle/route.ts": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v1beta",
-          "topic": "my-topic",
-          "consumer": "consumer-group-1"
-        },
-        {
-          "type": "queue/v1beta",
-          "topic": "my-topic",
-          "consumer": "consumer-group-2"
-        }
-      ]
-    }
-  }
-}
+```typescript
+import { Hono } from "hono";
+import { handleCallback } from "@/lib/queue";
+
+const app = new Hono();
+app.post(
+  "/api/queue",
+  handleCallback(async (message, metadata) => {
+    await processMessage(message);
+  }),
+);
+export default app;
 ```
 
-### 3. Multiple API Routes
+#### Connect-style — `handleNodeCallback`
 
-You can also create separate API routes for different topics:
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Express, Next.js Pages Router, etc.).
+
+**Next.js Pages Router:**
 
 ```typescript
-// app/api/queue/users/route.ts - Handle user events
-import { handleCallback } from "@vercel/queue";
-
-export const POST = handleCallback({
-  "user-events": {
-    processors: async (user, metadata) => {
-      console.log(`Processing user event:`, user, metadata);
-      await sendWelcomeEmail(user.email);
-    },
-  },
+// pages/api/queue/my-topic.ts
+import { handleNodeCallback } from "@/lib/queue";
+
+export default handleNodeCallback(async (message, metadata) => {
+  await processMessage(message);
 });
 ```
 
+**Express:**
+
 ```typescript
-// app/api/queue/orders/route.ts - Handle order events
-import { handleCallback } from "@vercel/queue";
-
-export const POST = handleCallback({
-  "order-events": {
-    fulfillment: async (order, metadata) => {
-      console.log(`Processing order:`, order, metadata);
-      await fulfillOrder(order);
-    },
-  },
-});
+import express from "express";
+import { handleNodeCallback } from "@/lib/queue";
+
+const app = express();
+app.use(express.json());
+app.post(
+  "/api/queue/my-topic",
+  handleNodeCallback(async (message, metadata) => {
+    await processMessage(message);
+  }),
+);
+export default app;
 ```
 
-With corresponding `vercel.json`:
+### 2. Configure vercel.json
+
+Tell Vercel which routes handle which topics:
 
 ```json
 {
   "functions": {
-    "app/api/queue/users/route.ts": {
+    "app/api/queue/my-topic/route.ts": {
       "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
-          "topic": "user-events",
-          "consumer": "processors"
+          "type": "queue/v2beta",
+          "topic": "my-topic",
+          "retryAfterSeconds": 60,
+          "initialDelaySeconds": 0
         }
       ]
     },
-    "app/api/queue/orders/route.ts": {
+    "app/api/queue/orders/fulfillment/route.ts": {
+      "experimentalTriggers": [
+        { "type": "queue/v2beta", "topic": "order-events" }
+      ]
+    },
+    "app/api/queue/orders/analytics/route.ts": {
       "experimentalTriggers": [
         {
-          "type": "queue/v1beta",
+          "type": "queue/v2beta",
           "topic": "order-events",
-          "consumer": "fulfillment"
+          "retryAfterSeconds": 300
         }
       ]
     }
@@ -270,522 +231,436 @@ With corresponding `vercel.json`:
 }
 ```
 
-### Key Points
+Multiple route files for the same topic create separate consumer groups — each receives a copy of every message.
 
-- **Automatic Triggering**: Vercel automatically triggers your API routes when messages are available for the configured topic/consumer combinations
-- **Message Processing**: Your API routes receive the message ID and other metadata via headers, then use the queue client to process the specific message
-- **Configuration Required**: The `vercel.json` file is essential - it tells Vercel which topics and consumers each route should handle
-- **No Polling**: Unlike traditional queue consumers, you don't need to poll for messages - Vercel handles the triggering automatically
+### 3. Retry and Backoff
 
-## Key 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).
 
-### Consumer Groups
-
-Multiple consumers can process messages from the same topic in parallel:
+For finer control over retry timing, pass a `retry` option:
 
 ```typescript
-// Multiple workers in the same group - they share/split messages
-// Using the same consumer group name means they will load balance messages
-await receive("my-topic", "workers", handler1);
-await receive("my-topic", "workers", handler2);
-// handler1 and handler2 will receive different messages (load balancing)
-
-// Different consumer groups - each gets copies of ALL messages
-await receive("my-topic", "analytics", analyticsHandler);
-await receive("my-topic", "webhooks", webhooksHandler);
-// analyticsHandler and webhooksHandler will both receive every message
+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
+    },
+  },
+);
 ```
 
-## Architecture
+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.
 
-- **Topics**: Named message channels with configurable serialization
-- **Consumer Groups**: Named groups of consumers that process messages in
-  parallel
-  - `receive()`: Process messages with flexible consumption patterns
-    - Basic usage: Process next available message
-    - With `messageId`: Process specific message by ID
-    - With `skipPayload: true`: Process message metadata only (without payload)
-- **Transports**: Pluggable serialization/deserialization for different data
-  types
-- **Streaming**: Memory-efficient processing of large payloads
-- **Visibility Timeouts**: Automatic message lifecycle management
+**Exponential backoff** uses `metadata.deliveryCount` (starts at 1, increments each delivery):
 
-## Performance
-
-The multipart parser is optimized for high-throughput scenarios:
-
-- **Streaming**: Messages are yielded immediately as headers are parsed
-- **Memory Efficient**: No buffering of complete payloads
-- **Fast Parsing**: Native Buffer operations for ~50% performance improvement
-- **Scalable**: Can handle arbitrarily large responses without memory
-  constraints
-
-## Serialization (Transport) System
-
-The queue client supports customizable serialization through the `Transport`
-interface with **streaming support** for memory-efficient processing. Transport
-can be configured using the `transport` option when calling `send()` or `receive()`.
-
-### Built-in Transports
-
-#### JsonTransport (Default)
+```typescript
+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 };
+    },
+  },
+);
+```
 
-Buffers data for JSON parsing - suitable for structured data that fits in
-memory.
+**Conditional retry** — only retry transient errors:
 
 ```typescript
-import { send, JsonTransport } from "@vercel/queue";
-
-// JsonTransport is the default, so these are equivalent:
-await send("json-topic", { data: "example" });
-await send(
-  "json-topic",
-  { data: "example" },
-  { transport: new JsonTransport() },
+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
+    },
+  },
 );
 ```
 
-#### BufferTransport
+**Acknowledging poison messages** — stop retrying messages that can never succeed:
 
-Buffers the entire payload into memory as a Buffer - suitable for binary data
-that fits in memory.
+```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) };
+    },
+  },
+);
+```
 
-#### StreamTransport
+The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `receive`.
 
-**True streaming support** - passes ReadableStream directly without buffering.
-Ideal for large files and memory-efficient processing.
+## Custom Client Configuration
 
-### Custom Transport
+All configuration lives on the `QueueClient`:
 
-You can create your own serialization format by implementing the `Transport`
-interface.
+```typescript
+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
+});
 
-### Choosing the Right Transport
+// Use directly
+await queue.send("my-topic", myBuffer);
 
-| Use Case               | Recommended Transport | Memory Usage | Performance |
-| ---------------------- | --------------------- | ------------ | ----------- |
-| Small JSON objects     | `JsonTransport`       | Low          | High        |
-| Binary files < 100MB   | `BufferTransport`     | Medium       | High        |
-| Large files > 100MB    | `StreamTransport`     | Very Low     | Medium      |
-| Real-time data streams | `StreamTransport`     | Very Low     | High        |
-| Custom protocols       | Custom implementation | Varies       | Varies      |
+// Or destructure
+export const { send, receive, handleCallback, handleNodeCallback } = queue;
+```
 
-## API Reference
+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.
 
-### Send Function
+To customize the URL scheme, provide a `resolveBaseUrl` that returns a `URL`:
 
 ```typescript
-// Simple send - automatically uses default client and JSON transport
-await send<T>(topicName, payload);
-
-// Send with options including custom transport
-await send<T>(topicName, payload, {
-  transport?: Transport<T>;
-  idempotencyKey?: string;
-  retentionSeconds?: number;
-});
-
-// Examples:
-await send("notifications", { userId: "123", message: "Welcome!" });
-
-await send("images", imageBuffer, {
-  transport: new BufferTransport(),
+// Custom domain
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  resolveBaseUrl: (region) => new URL(`https://${region}.my-proxy.example`),
 });
 
-await send("events", eventData, {
-  idempotencyKey: "unique-key-123",
-  retentionSeconds: 3600,
+// Custom domain with a base path (e.g. reverse proxy prefix)
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  resolveBaseUrl: (region) =>
+    new URL(`https://my-proxy.example/queues/${region}`),
+  // → requests go to https://my-proxy.example/queues/<region>/api/v3/…
 });
 ```
 
-### Receive Function
+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.
+
+| 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
-// Process next available message (simplest form)
-await receive("topic-name", "consumer-group", handler);
+import {
+  QueueClient,
+  JsonTransport,
+  BufferTransport,
+  StreamTransport,
+} from "@vercel/queue";
 
-// Process specific message by ID with payload
-await receive("topic-name", "consumer-group", handler, {
-  messageId: "message-id",
+// 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),
+  }),
 });
 
-// Process specific message by ID without payload (metadata only)
-// handler will be called with `undefined` as the payload
-await receive("topic-name", "consumer-group", handler, {
-  messageId: "message-id",
-  skipPayload: true,
+// 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);
 ```
 
-### Message Handler
+## Manual Receive
 
-```typescript
-// Handler function signature
-type MessageHandler<T = unknown> = (
-  message: T,
-  metadata: MessageMetadata,
-) => Promise<MessageHandlerResult> | MessageHandlerResult;
+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.
 
-// Handler result types
-type MessageHandlerResult = void | MessageTimeoutResult;
+### Region considerations
 
-interface MessageTimeoutResult {
-  timeoutSeconds: number; // seconds before message becomes available again
-}
+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.
 
-// Message Metadata
-interface MessageMetadata {
-  messageId: string;
-  deliveryCount: number;
-  timestamp: string;
-}
-```
-
-### Receive Options
+```bash
+# .env.production — fixed region for manual receive workflows
+QUEUE_REGION=iad1
 
-```typescript
-// Options for the receive function
-interface ReceiveOptions<T = unknown> {
-  messageId?: string; // Process specific message by ID
-  skipPayload?: boolean; // Skip payload download (requires messageId)
-  transport?: Transport<T>; // Custom transport (defaults to JsonTransport)
-  visibilityTimeoutSeconds?: number; // Message visibility timeout
-  refreshInterval?: number; // Refresh interval for long-running operations
-}
+# .env.development
+QUEUE_REGION=iad1
 ```
 
-### Transport Interface
+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).
 
-```typescript
-interface Transport<T = unknown> {
-  serialize(value: T): Buffer | ReadableStream<Uint8Array>;
-  deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-  contentType: string;
-}
-```
+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.
 
-### Callback Handler
+### Usage
 
 ```typescript
-// Create a callback handler for Next.js route handlers
-function handleCallback(
-  handlers: CallbackHandlers,
-): (request: Request) => Promise<Response>;
-
-// Configuration object with handlers for different topics and consumer groups
-type CallbackHandlers = {
-  [topicName: string]: { [consumerGroup: string]: MessageHandler };
-};
-
-// Example usage:
-export const POST = handleCallback({
-  "user-events": {
-    welcome: (message, metadata) => {
-      console.log(`New user event:`, message, metadata);
-    },
-  },
+import { QueueClient } from "@vercel/queue";
 
-  // Multiple consumer groups per topic
-  "image-processing": {
-    compress: (message, metadata) => console.log("Compressing image", message),
-    resize: (message, metadata) => console.log("Resizing image", message),
-  },
-});
-```
-
-## Examples
+const { receive } = new QueueClient({ region: "iad1" });
 
-### Basic JSON Processing
-
-```typescript
-interface UserEvent {
-  userId: string;
-  action: string;
-  timestamp: number;
+// 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);
 }
 
-// Send a message
-await send<UserEvent>("user-events", {
-  userId: "123",
-  action: "login",
-  timestamp: Date.now(),
-});
+// Batch processing: up to 10 messages in one request
+await receive("my-topic", "my-group", handler, { limit: 10 });
 
-// Receive and process a message
-try {
-  await receive<UserEvent>("user-events", "processors", async (message) => {
-    console.log(`User ${message.userId} performed ${message.action}`);
-  });
-} catch (error) {
-  console.error("Processing error:", error);
-}
+// Process a specific message by ID
+await receive("my-topic", "my-group", handler, { messageId: "msg-123" });
 ```
 
-### Processing Specific Messages by ID
+> **Note:** `limit` and `messageId` are mutually exclusive options. The handler is never called when the queue is empty — check `result.ok` instead.
+
+## Error Handling
 
 ```typescript
-// Process a specific message if you know its ID
-const messageId = "01234567-89ab-cdef-0123-456789abcdef";
+import {
+  BadRequestError,
+  DuplicateMessageError,
+  ForbiddenError,
+  InternalServerError,
+  UnauthorizedError,
+} from "@vercel/queue";
+import { send } from "@/lib/queue";
 
 try {
-  await receive<{ userId: string; action: string }>(
-    "user-events",
-    "processors",
-    async (message, { messageId }) => {
-      console.log(`Processing specific message: ${messageId}`);
-      console.log(`User ${message.userId} performed ${message.action}`);
-    },
-    { messageId },
-  );
-  console.log("Message processed successfully");
+  await send("my-topic", payload);
 } catch (error) {
-  if (error.message.includes("not found or not available")) {
-    console.log("Message was already processed or does not exist");
-  } else {
-    console.error("Error processing message:", error);
+  if (error instanceof UnauthorizedError) {
+    console.log("Invalid token - refresh authentication");
+  } else if (error instanceof ForbiddenError) {
+    console.log("Environment mismatch - check configuration");
+  } else if (error instanceof BadRequestError) {
+    console.log("Invalid parameters:", error.message);
+  } else if (error instanceof DuplicateMessageError) {
+    console.log("Duplicate message:", error.idempotencyKey);
+  } else if (error instanceof InternalServerError) {
+    console.log("Server error - retry with backoff");
   }
 }
 ```
 
-### Processing Next Available Message
+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                |
+
+## 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)              | -       |
+
+## Service Limits & Constraints
+
+### Throughput & Storage
+
+| Limit                       | Value                 | Notes                               |
+| --------------------------- | --------------------- | ----------------------------------- |
+| Message throughput          | 10,000+ msg/sec/topic | Scales horizontally                 |
+| Payload size                | 1 GB                  | Smaller messages have lower latency |
+| Number of topics            | Unlimited             | No hard limit                       |
+| Consumer groups per message | ~4,000                | Per-message limit                   |
+| Messages per queue          | Unlimited             | No hard limit                       |
+
+### Parameter Constraints
+
+#### Publishing Messages
+
+| Parameter          | Default      | Min | Max         | Notes                               |
+| ------------------ | ------------ | --- | ----------- | ----------------------------------- |
+| `retentionSeconds` | 86,400 (24h) | 60  | 86,400      | Message TTL                         |
+| `delaySeconds`     | 0            | 0   | ≤ retention | Cannot exceed retention             |
+| `idempotencyKey`   | —            | —   | —           | Dedup window: `min(retention, 24h)` |
+
+#### Receiving Messages
+
+| 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 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
 
-```typescript
-// Process the next available message (one-shot processing)
-try {
-  await receive<{ taskType: string; data: any }>(
-    "work-queue",
-    "workers",
-    async (message) => {
-      console.log(`Processing task: ${message.taskType}`);
-      await processTask(message.taskType, message.data);
-    },
-  );
-  console.log("Message processed successfully");
-} catch (error) {
-  if (error instanceof QueueEmptyError) {
-    console.log("No messages available");
-  } else if (error instanceof MessageLockedError) {
-    console.log("Next message is locked");
-    if (error.retryAfter) {
-      console.log(`Retry after ${error.retryAfter} seconds`);
+```json
+{
+  "functions": {
+    "app/api/queue/route.ts": {
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "user-*" }]
     }
-  } else {
-    console.error("Error processing message:", error);
   }
 }
+```
 
-// Handle conditional timeouts
-await receive<{ taskType: string; data: any }>(
-  "work-queue",
-  "workers",
-  async (message) => {
-    if (!canProcessTaskType(message.taskType)) {
-      // Return timeout to retry later
-      return { timeoutSeconds: 60 };
-    }
-
-    await processTask(message.taskType, message.data);
-  },
-);
+- `*` may only appear **once** in the pattern
+- `*` must be at the **end** of the topic name
+- Valid: `user-*`, `orders-*`
+- Invalid: `*-events`, `user-*-data`
 
-// Process specific message metadata only (no payload download)
-await receive<{ taskType: string; data: any }>(
-  "work-queue",
-  "workers",
-  async (_, metadata) => {
-    console.log(`Message ID: ${metadata.messageId}`);
-    console.log(`Delivery count: ${metadata.deliveryCount}`);
-    console.log(`Timestamp: ${metadata.timestamp}`);
-    // _ is undefined - no payload was downloaded
-  },
-  { messageId: "specific-message-id", skipPayload: true },
-);
-```
+## API Reference
 
-### Timing Out Messages
+### `QueueClient`
 
 ```typescript
-// Process a message with conditional timeout
-try {
-  await receive<{ taskType: string; data: any }>(
-    "work-queue",
-    "workers",
-    async ({ taskType, data }) => {
-      // Check if we can process this task type right now
-      if (taskType === "heavy-computation" && isSystemOverloaded()) {
-        // Return timeout to retry later (5 minutes)
-        return { timeoutSeconds: 300 };
-      }
-
-      // Check if we have required resources
-      if (taskType === "external-api" && !isExternalServiceAvailable()) {
-        // Return timeout to retry in 1 minute
-        return { timeoutSeconds: 60 };
-      }
-
-      // Process the message normally
-      console.log(`Processing ${taskType} task`);
-      await processTask(taskType, data);
-      // Message will be automatically deleted on successful completion
-    },
-  );
-} catch (error) {
-  console.error("Worker processing error:", error);
-}
+import { QueueClient } from "@vercel/queue";
+
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
+  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
+  deploymentId: undefined, // omit = auto from env (pinned), null = unpinned, or explicit string
+});
 
-// Example with exponential backoff
-try {
-  await receive<{ taskType: string; data: any }>(
-    "work-queue",
-    "workers",
-    async (message, { deliveryCount }) => {
-      const maxRetries = 3;
-
-      try {
-        await processMessage(message);
-        // Successful processing - message will be deleted
-      } catch (error) {
-        if (deliveryCount < maxRetries) {
-          // Exponential backoff: 2^deliveryCount minutes
-          const timeoutSeconds = Math.pow(2, deliveryCount) * 60;
-          console.log(
-            `Retrying message in ${timeoutSeconds} seconds (attempt ${deliveryCount})`,
-          );
-          return { timeoutSeconds: timeoutSeconds };
-        } else {
-          // Max retries reached, let the message fail and be deleted
-          console.error(
-            "Max retries reached, message will be discarded:",
-            error,
-          );
-          throw error;
-        }
-      }
-    },
-  );
-} catch (error) {
-  console.error("Backoff processing error:", error);
-}
+// Methods (arrow functions — safe to destructure)
+const { send, receive, handleCallback, handleNodeCallback } = queue;
 ```
 
-## Error Handling
+### `send(topicName, payload, options?)`
 
-The queue client provides specific error types for different failure scenarios:
+Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
 
-### Error Types
-
-- **`QueueEmptyError`**: Thrown when attempting to receive messages from an
-  empty queue (204 status)
-
-  - Thrown by `receive()` when no messages are available
-
-- **`MessageLockedError`**: Thrown when a message is temporarily locked (423
-  status)
-
-  - Contains optional `retryAfter` property with seconds to wait before retry
-  - For `receive()` without options: the next message is locked
-  - For `receive()` with messageId: the requested message is locked
-
-- **`MessageNotFoundError`**: Message doesn't exist (404 status)
+```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
+});
+```
 
-- **`MessageNotAvailableError`**: Message exists but isn't available for
-  processing (409 status)
+### `receive(topicName, consumerGroup, handler, options?)`
 
-- **`MessageCorruptedError`**: Message data is corrupted or can't be parsed
+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.
 
-- **`BadRequestError`**: Invalid request parameters (400 status)
+For receive-by-id, operational errors are returned instead of thrown:
 
-  - Invalid queue names, missing required parameters
+```typescript
+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);
+}
+```
 
-- **`UnauthorizedError`**: Authentication failure (401 status)
+```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)
+});
+```
 
-  - Missing or invalid authentication token
+### `handleCallback(handler, options?)`
 
-- **`ForbiddenError`**: Access denied (403 status)
+Vercel only. Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
 
-  - Queue environment doesn't match token environment
+```typescript
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
+    retry: (error, metadata) => {
+      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
+    },
+  },
+);
+```
 
-- **`InternalServerError`**: Server-side errors (500+ status codes)
-  - Unexpected server errors, service unavailable, etc.
+### `handleNodeCallback(handler, options?)`
 
-### Error Handling Examples
+Vercel only. Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
 ```typescript
-import {
-  BadRequestError,
-  ForbiddenError,
-  InternalServerError,
-  MessageLockedError,
-  QueueEmptyError,
-  UnauthorizedError,
-} from "@vercel/queue";
-
-// Handle empty queue or locked messages
-try {
-  await receive("my-topic", "my-consumer", async (message) => {
-    // Process message
-    console.log("Processing message:", message);
-  });
-} catch (error) {
-  if (error instanceof QueueEmptyError) {
-    console.log("Queue is empty, retry later");
-  } else if (error instanceof MessageLockedError) {
-    console.log("Next message is locked");
-    if (error.retryAfter) {
-      console.log(`Retry after ${error.retryAfter} seconds`);
-    }
-  }
-}
+// pages/api/queue/my-topic.ts
+export default handleNodeCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    retry: (error, metadata) => ({ afterSeconds: 60 }),
+  },
+);
+```
 
-// Handle locked message with retry
-try {
-  await receive("my-topic", "my-consumer", handler, { messageId });
-} catch (error) {
-  if (error instanceof MessageLockedError) {
-    console.log("Message is locked by another consumer");
-    if (error.retryAfter) {
-      console.log(`Retry after ${error.retryAfter} seconds`);
-      setTimeout(() => retry(), error.retryAfter * 1000);
-    }
-  }
-}
+### Handler Signature
 
-// Handle authentication and authorization errors
-try {
-  await send("my-topic", payload);
-} catch (error) {
-  if (error instanceof UnauthorizedError) {
-    console.log("Invalid token - refresh authentication");
-  } else if (error instanceof ForbiddenError) {
-    console.log("Environment mismatch - check token/queue configuration");
-  } else if (error instanceof BadRequestError) {
-    console.log("Invalid parameters:", error.message);
-  } else if (error instanceof InternalServerError) {
-    console.log("Server error - retry with backoff");
-  }
-}
+```typescript
+type MessageHandler<T> = (
+  message: T,
+  metadata: MessageMetadata,
+) => Promise<void> | void;
 
-// Complete error handling pattern
-function handleQueueError(error: unknown): void {
-  if (error instanceof QueueEmptyError || error instanceof MessageLockedError) {
-    // Transient errors - safe to retry
-    console.log("Temporary condition, will retry");
-  } else if (
-    error instanceof UnauthorizedError ||
-    error instanceof ForbiddenError
-  ) {
-    // Authentication/authorization errors - need to fix configuration
-    console.log("Auth error - check credentials");
-  } else if (error instanceof BadRequestError) {
-    // Client error - fix the request
-    console.log("Invalid request:", error.message);
-  } else if (error instanceof InternalServerError) {
-    // Server error - implement exponential backoff
-    console.log("Server error - retry with backoff");
-  } else {
-    // Unknown error
-    console.error("Unexpected error:", error);
-  }
+interface MessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  createdAt: Date;
+  expiresAt?: Date;
+  topicName: string;
+  consumerGroup: string;
+  region: string;
 }
 ```