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

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,992 +19,637 @@ 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
-
-```typescript
-// index.ts
-import { send, receive } from "@vercel/queue";
-
-type Message = {
-  message: string;
-  timestamp: number;
-};
-
-// Option 1: Using the send and receive helpers (simplest)
-// Automatically uses default client and JSON transport
-await send<Message>("my-topic", {
-  message: "Hello, World!",
-  timestamp: Date.now(),
-});
-
-// 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", (m) => {
-  console.log(m.message);
-});
-
-// Option 2: Using createTopic for more control
+Otherwise, set `QUEUE_REGION` in your environment directly (e.g. via your hosting provider's dashboard or a `dotenv` setup).
 
-import { createTopic } from "@vercel/queue";
+Create a shared queue client:
 
-// Create a topic with JSON serialization (default)
-// Uses default QueueClient automatically authenticated from Vercel environment
-const topic = createTopic<Message>("my-topic");
-
-// Publish a message
-await topic.publish({
-  message: "Hello, World!",
-  timestamp: Date.now(),
-});
-
-// Create a consumer group
-const consumer = topic.consumerGroup("my-consumer-group");
+```typescript
+// lib/queue.ts
+import { QueueClient } from "@vercel/queue";
 
-// Process next available message (one-shot processing)
-try {
-  await consumer.consume(async (message, metadata) => {
-    console.log("Received:", message.message);
-    console.log("Timestamp:", new Date(message.timestamp));
-    console.log("Message Metadata", metadata);
-    // => { messageId, deliveryCount, timestamp }
-  });
-} catch (error) {
-  console.error("Processing error:", error);
-}
+const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+export const { send, receive, handleCallback, handleNodeCallback } = queue;
 ```
 
-Run the script
+Send a message anywhere in your app:
 
-```bash
-# Install dotenv-cli and ts-node if you need it
-npm i -g dotenv-cli ts-node typescript
+```typescript
+import { send } from "@/lib/queue";
 
-# Run the script with the OIDC token
-dotenv -e .env.local ts-node index.ts
+await send("my-topic", { message: "Hello world" });
 ```
 
-## Usage with Vercel
+Handle incoming messages with a route handler:
 
-When deploying on Vercel, rather than having a persistent server subscribed to a
-queue, Vercel can trigger a callback route when a message is ready for
-consumption.
-
-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).
+```typescript
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@/lib/queue";
 
-### TypeScript Configuration
+export const POST = handleCallback(async (message, metadata) => {
+  console.log("Processing:", message);
+});
+```
 
-Update your `tsconfig.json` to use `"bundler"` module resolution for proper
-package export resolution:
+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:
 
-```typescript
-// app/actions.ts
-"use server";
-
-import { send } from "@vercel/queue";
-
-export async function publishTestMessage(message: string) {
-  // Option 1: Using simple send shorthand
-  const { messageId } = await send(
-    "my-topic",
-    { message, timestamp: Date.now() },
-    {
-      // Provide a callback URL to invoke a consumer when the message is ready to be processed
-      callback: {
-        url: getCallbackUrl() // implementation below
-      },
-    },
-  );
+```bash
+npm i -g vercel
+vc link
+vc env pull
+```
 
-  console.log(`Published message ${messageId}`);
-}
+## Local Development
 
-// Option 2: Customize the topic, transport, consumer groups, etc.
-import { createTopic } from "@vercel/queue";
+**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.
 
-export async function publishTestMessage(message: string) {
-  // Create a topic with JSON serialization (default)
-  const topic = createTopic<{ message: string; timestamp: number }>("my-topic");
+> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically during `npm run dev`.
 
-  // Publish the message
-  const { messageId } = await topic.publish(
-    { message, timestamp: Date.now() },
-    {
-      // Provide multiple callback URLs to invoke multiple consumer groups
-      callback: {
-        {
-          "consumer-group-1": {
-            url: getCallbackUrl()
-          },
-          "consumer-group-2": {
-            url: getCallbackUrl()
-            delay: 5 // Delay callback by 5 seconds
-          },
-        }
-      },
-    },
-  );
+## Publishing Messages
 
-  console.log(`Published message ${messageId}`);
-}
+```typescript
+import { QueueClient } from "@vercel/queue";
 
-// Helper function to generate a local callback URL
-function getCallbackUrl() {
-  const callbackUrl = new URL(
-    process.env.VERCEL_URL
-      ? `https://${process.env.VERCEL_URL}/api/queue/handle`
-      : "http://localhost:3000/api/queue/handle"
-  );
-
-  // Add Vercel automation bypass secret if available (for preview deployments)
-  if (process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
-    callbackUrl.searchParams.set(
-      "x-vercel-protection-bypass",
-      process.env.VERCEL_AUTOMATION_BYPASS_SECRET
-    );
-  }
+const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
 
-  return callbackUrl.toString();
-}
+// Simple send
+await send("my-topic", { message: "Hello world" });
 
+// 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.
 
-Instead of running a persistent server that subscribes to the queue, we use the
-callback functionality of Vercel queues to consume messages on the fly, when a
-message is ready to be processed.
+## Consuming Messages
 
-The `handleCallback` helper function simplifies queue callback handling in NextJS:
+### On Vercel
 
-```typescript
-// app/api/queue/handle/route.ts
-import { handleCallback } from "@vercel/queue";
-
-// Option 1: Specify a single handler for the topic
-export const POST = handleCallback({
-  "my-topic": (message, metadata) => {
-    console.log(`Received message:`, message, metadata);
-    // metadata: { messageId, deliveryCount, timestamp }
-  },
+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.
 
-  // .. more topic handlers can be provided here
-});
+#### Web API — `handleCallback`
 
-// This consumes messages on the "default" consumer group, which is used when no consumer groups
-// were specified in the publish `callback` earlierA
+Returns `(Request) => Promise<Response>`. For frameworks that export Web API route handlers (Next.js App Router, Hono, etc.).
 
-// Option 2: Multiple consumer groups
-export const POST = handleCallback({
-  // topic: "my-topic"
-  "my-topic": {
-    // consumer group: "compress"
-    "consumer-group-1": (message, metadata) => {
-      console.log("Message:", message);
-    },
-    // consumer group: "resize"
-    "consume-group-2": (message, metadata) => {
-      console.log("Message", message);
-    },
-  },
-});
-```
+**Next.js App Router:**
 
-## Key Features
+```typescript
+// app/api/queue/my-topic/route.ts
+import { handleCallback } from "@/lib/queue";
 
-### Streaming Support
+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
+});
+```
 
-Handle large files and data streams without loading them into memory:
+**Hono:**
 
 ```typescript
-import { createTopic, StreamTransport } from "@vercel/queue";
-
-const videoTopic = createTopic<ReadableStream<Uint8Array>>(
-  "video-processing",
-  new StreamTransport(),
+import { Hono } from "hono";
+import { handleCallback } from "@/lib/queue";
+
+const app = new Hono();
+app.post(
+  "/api/queue",
+  handleCallback(async (message, metadata) => {
+    await processMessage(message);
+  }),
 );
-
-// Process large video files efficiently
-const processor = videoTopic.consumerGroup("processors");
-await processor.consume(async (videoStream) => {
-  // Process stream chunk by chunk
-  const reader = videoStream.getReader();
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    await processChunk(value);
-  }
-});
+export default app;
 ```
 
-### Consumer Groups
+#### Connect-style — `handleNodeCallback`
+
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Express, Next.js Pages Router, etc.).
 
-Multiple consumers can process messages from the same topic in parallel:
+**Next.js Pages Router:**
 
 ```typescript
-// Multiple workers in the same group - they share/split messages
-const worker1 = topic.consumerGroup("workers");
-const worker2 = topic.consumerGroup("workers"); // Same group name
-// worker1 and worker2 will receive different messages (load balancing)
+// pages/api/queue/my-topic.ts
+import { handleNodeCallback } from "@/lib/queue";
 
-// Different consumer groups - each gets copies of ALL messages
-const analytics = topic.consumerGroup("analytics");
-const webhooks = topic.consumerGroup("webhooks");
-// analytics and webhooks will both receive every message
+export default handleNodeCallback(async (message, metadata) => {
+  await processMessage(message);
+});
 ```
 
-## Architecture
-
-- **Topics**: Named message channels with configurable serialization
-- **Consumer Groups**: Named groups of consumers that process messages in
-  parallel
-  - `consume()`: Process messages with flexible consumption patterns
-    - No options: 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
+**Express:**
 
-## Performance
+```typescript
+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;
+```
 
-The multipart parser is optimized for high-throughput scenarios:
+### 2. Configure vercel.json
 
-- **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
+Tell Vercel which routes handle which topics:
 
-## Serialization (Transport) System
+```json
+{
+  "functions": {
+    "app/api/queue/my-topic/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "my-topic",
+          "retryAfterSeconds": 60,
+          "initialDelaySeconds": 0
+        }
+      ]
+    },
+    "app/api/queue/orders/fulfillment/route.ts": {
+      "experimentalTriggers": [
+        { "type": "queue/v2beta", "topic": "order-events" }
+      ]
+    },
+    "app/api/queue/orders/analytics/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "order-events",
+          "retryAfterSeconds": 300
+        }
+      ]
+    }
+  }
+}
+```
 
-The queue client supports customizable serialization through the `Transport`
-interface with **streaming support** for memory-efficient processing. Transport
-can be configured at the **topic level** when creating a topic, or at the
-**consumer group level** when creating a consumer group.
+Multiple route files for the same topic create separate consumer groups — each receives a copy of every message.
 
-### Built-in Transports
+### 3. Retry and Backoff
 
-#### JsonTransport (Default)
+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).
 
-Buffers data for JSON parsing - suitable for structured data that fits in
-memory.
+For finer control over retry timing, pass a `retry` option:
 
 ```typescript
-import { createTopic, JsonTransport } from "@vercel/queue";
-
-const topic = createTopic<{ data: any }>("json-topic", new JsonTransport());
-// or simply (JsonTransport is the default):
-const topic = createTopic<{ data: any }>("json-topic");
+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
+    },
+  },
+);
 ```
 
-#### BufferTransport
+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.
 
-Buffers the entire payload into memory as a Buffer - suitable for binary data
-that fits in memory.
+**Exponential backoff** uses `metadata.deliveryCount` (starts at 1, increments each delivery):
 
 ```typescript
-import { BufferTransport, createTopic } from "@vercel/queue";
-
-const topic = createTopic<Buffer>("binary-topic", new BufferTransport());
-const binaryData = Buffer.from("Binary data", "utf8");
-await topic.publish(binaryData);
+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 };
+    },
+  },
+);
 ```
 
-#### StreamTransport
-
-**True streaming support** - passes ReadableStream directly without buffering.
-Ideal for large files and memory-efficient processing.
+**Conditional retry** — only retry transient errors:
 
 ```typescript
-import { createTopic, StreamTransport } from "@vercel/queue";
-
-const topic = createTopic<ReadableStream<Uint8Array>>(
-  "streaming-topic",
-  new StreamTransport(),
-);
-
-// Send large file as stream without loading into memory
-const fileStream = new ReadableStream<Uint8Array>({
-  start(controller) {
-    // Read file in chunks
-    for (const chunk of readFileInChunks("large-file.bin")) {
-      controller.enqueue(chunk);
-    }
-    controller.close();
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
   },
-});
-
-await topic.publish(fileStream);
+  {
+    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
+    },
+  },
+);
 ```
 
-### Custom Transport
-
-You can create your own serialization format by implementing the `Transport`
-interface:
+**Acknowledging poison messages** — stop retrying messages that can never succeed:
 
 ```typescript
-import { Transport } from "@vercel/queue";
-
-interface Transport<T = unknown> {
-  serialize(value: T): Buffer | ReadableStream<Uint8Array>;
-  deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-  contentType: string;
-}
+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) };
+    },
+  },
+);
 ```
 
-### Choosing the Right Transport
-
-| 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      |
+The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `receive`.
 
-## API Reference
+## Custom Client Configuration
 
-### QueueClient
+All configuration lives on the `QueueClient`:
 
 ```typescript
-// Simple usage - automatically gets OIDC token from Vercel environment
-const client = new QueueClient();
-
-// Or with options
-const client = new QueueClient({
-  token?: string; // Optional - will auto-detect if not provided
-  baseUrl?: string; // defaults to 'https://vqs.vercel.sh'
+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
 });
-```
 
-### Topic
+// Use directly
+await queue.send("my-topic", myBuffer);
 
-```typescript
-// Simple usage with default client
-const topic = createTopic<T>(topicName, transport?);
+// Or destructure
+export const { send, receive, handleCallback, handleNodeCallback } = queue;
+```
 
-// For custom client configuration, use Topic constructor directly
-const customClient = new QueueClient({ baseUrl: "https://custom.vqs.vercel.sh" });
-const topic = new Topic<T>(customClient, topicName, transport?);
+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.
 
-// Publish a message (uses topic's transport)
-await topic.publish(payload, options?);
+To customize the URL scheme, provide a `resolveBaseUrl`:
 
-// Trigger a callback URL when the message is
-// ready for consumption
-await topic.publish(payload, {
-  callback: { url: "https://example.com/webhook" }
+```typescript
+const queue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  resolveBaseUrl: (region) => `https://${region}.my-proxy.example`,
 });
+```
 
-// Or provide multiple callbacks (each URL is called
-// with a separate consumer group)
-await topic.publish(payload, {
-  callback: {
-    group1: { url: "https://example.com/webhook1" },
-    group2: { url: "https://example.com/webhook2", delay: 30 }
-  }
-});
+## Transports
 
-// Create a consumer group (can override transport)
-const consumer = topic.consumerGroup<U>(groupName, options?);
-```
+The transport controls how message payloads are serialized and deserialized.
 
-### Send (Shorthand)
+| 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
-// 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;
-  callback?: Record<string, CallbackConfig> | CallbackConfig;
-});
+import {
+  QueueClient,
+  JsonTransport,
+  BufferTransport,
+  StreamTransport,
+} from "@vercel/queue";
 
-// Examples:
-await send("notifications", { userId: "123", message: "Welcome!" });
+// 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),
+  }),
+});
 
-await send("images", imageBuffer, {
+// Binary data
+const binQueue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
   transport: new BufferTransport(),
-  callback: { url: "https://example.com/process-image" }
 });
+await binQueue.send("binary-topic", myBuffer);
 
-await send("events", eventData, {
-  idempotencyKey: "unique-key-123",
-  retentionSeconds: 3600,
-  callback: {
-    analytics: { url: "https://analytics.example.com/webhook" },
-    notifications: { url: "https://notifications.example.com/webhook", delay: 30 }
-  }
+// Streaming for large payloads
+const streamQueue = new QueueClient({
+  region: process.env.QUEUE_REGION!,
+  transport: new StreamTransport(),
 });
+await streamQueue.send("large-file", myReadableStream);
 ```
 
-### ConsumerGroup
-
-```typescript
-// Process next available message (simplest form)
-await consumer.consume(handler);
-
-// Process specific message by ID with payload
-await consumer.consume(handler, { messageId: "message-id" });
+## Manual Receive
 
-// Process specific message by ID without payload (metadata only)
-// handler will be called with `undefined` as the payload
-await consumer.consume(handler, { messageId: "message-id", skipPayload: true });
-```
-
-### Message Handler
+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.
 
-```typescript
-// Handler function signature
-type MessageHandler<T = unknown> = (
-  message: T,
-  metadata: MessageMetadata,
-) => Promise<MessageHandlerResult> | MessageHandlerResult;
+### Region considerations
 
-// Handler result types
-type MessageHandlerResult = void | MessageTimeoutResult;
+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.
 
-interface MessageTimeoutResult {
-  timeoutSeconds: number; // seconds before message becomes available again
-}
+```bash
+# .env.production — fixed region for manual receive workflows
+QUEUE_REGION=iad1
 
-// Message Metadata
-interface MessageMetadata {
-  messageId: string;
-  deliveryCount: number;
-  timestamp: string;
-}
+# .env.development
+QUEUE_REGION=iad1
 ```
 
-### ConsumeOptions 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 ConsumeOptions {
-  messageId?: string; // Process specific message by ID
-  skipPayload?: boolean; // Skip payload download (requires messageId)
-}
-```
+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.
 
-### Transport Interface
+### Usage
 
 ```typescript
-interface Transport<T = unknown> {
-  serialize(value: T): Buffer | ReadableStream<Uint8Array>;
-  deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-  contentType: string;
-}
-```
+import { QueueClient } from "@vercel/queue";
 
-### Callback Utilities
-
-```typescript
-// Parse queue callback request headers
-function parseCallbackRequest(request: Request): CallbackMessageOptions;
+const { receive } = new QueueClient({ region: "iad1" });
 
-// Callback options type
-interface CallbackMessageOptions {
-  queueName: string;
-  consumerGroup: string;
-  messageId: string;
-}
-// Create a callback handler for NextJS route handlers
-function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
-
-// Configuration object with handlers for different topics
-type CallbackHandlers = {
-  [topicName: string]:
-    | MessageHandler // Single handler (uses 'default' consumer group)
-    | { [consumerGroup: string]: MessageHandler }; // Multiple consumer group handlers
-};
-
-// Example usage:
-export const POST = handleCallback({
-  // Topic handler (uses 'default' consumer group)
-  "new-users": (message, metadata) => {
-    console.log(`New user event:`, message, metadata);
+// Process next available message
+const result = await receive(
+  "my-topic",
+  "my-group",
+  async (message, metadata) => {
+    console.log("Processing:", message);
   },
-
-  // Consumer group specific handlers
-  "image-processing": {
-    "compress": (message, metadata) => console.log("Compressing image", message),
-    "resize": (message, metadata) => console.log("Resizing image", message),
-  }
-});
-
-// Error thrown for invalid callback requests
-class InvalidCallbackError extends Error;
-```
-
-## Examples
-
-### Basic JSON Processing
-
-```typescript
-interface UserEvent {
-  userId: string;
-  action: string;
-  timestamp: number;
+);
+if (!result.ok) {
+  console.log("Queue was empty:", result.reason);
 }
 
-// Option 1: Using send shorthand
-await send<UserEvent>("user-events", {
-  userId: "123",
-  action: "login",
-  timestamp: Date.now(),
-});
-
-// Option 2: Using createTopic for consumers
-const userTopic = createTopic<UserEvent>("user-events");
-
-await userTopic.publish({
-  userId: "123",
-  action: "login",
-  timestamp: Date.now(),
-});
-
-const consumer = userTopic.consumerGroup("processors");
+// Batch processing: up to 10 messages in one request
+await receive("my-topic", "my-group", handler, { limit: 10 });
 
-// Process next available message
-try {
-  await consumer.consume(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.
 
-```typescript
-const userTopic = createTopic<{ userId: string; action: string }>(
-  "user-events",
-);
-const consumer = userTopic.consumerGroup("processors");
+## Error Handling
 
-// Process a specific message if you know its ID
-const messageId = "01234567-89ab-cdef-0123-456789abcdef";
+```typescript
+import {
+  BadRequestError,
+  DuplicateMessageError,
+  ForbiddenError,
+  InternalServerError,
+  UnauthorizedError,
+} from "@vercel/queue";
+import { send } from "@/lib/queue";
 
 try {
-  await consumer.consume(
-    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 if (error.message.includes("FIFO ordering violation")) {
-    console.log("FIFO queue requires processing messages in order");
-  } 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
-const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
-const worker = workTopic.consumerGroup("workers");
-
-// Process the next available message (one-shot processing)
-try {
-  await worker.consume(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 (FIFO queue)");
-    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 worker.consume(async (message) => {
-  if (!canProcessTaskType(message.taskType)) {
-    // Return timeout to retry later
-    return { timeoutSeconds: 60 };
-  }
-
-  await processTask(message.taskType, message.data);
-});
-
-// Process specific message metadata only (no payload download)
-await worker.consume(
-  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 },
-);
 ```
 
-### Timing Out Messages
+- `*` may only appear **once** in the pattern
+- `*` must be at the **end** of the topic name
+- Valid: `user-*`, `orders-*`
+- Invalid: `*-events`, `user-*-data`
 
-```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
-const worker = workTopic.consumerGroup("workers");
+## API Reference
 
-// Process a message with conditional timeout
-try {
-  await worker.consume(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 };
-    }
+### `QueueClient`
 
-    // 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);
-}
+```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
+  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 worker.consume(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;
 ```
 
-### Complete Example: Video Processing Pipeline
+### `send(topicName, payload, options?)`
 
-Here's a comprehensive example showing a video processing pipeline that
-processes videos with FFmpeg and stores the results in Vercel Blob:
+Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
 
 ```typescript
-import { createTopic, StreamTransport } from "@vercel/queue";
-import { spawn } from "child_process";
-import ffmpeg from "ffmpeg-static";
-import { put } from "@vercel/blob";
-
-// Input topic with unoptimized videos
-const unoptimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  "unoptimized-videos",
-  new StreamTransport(),
-);
-
-// Output topic for optimized videos
-const optimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  "optimized-videos",
-  new StreamTransport(),
-);
-
-// Step 1: Process videos with FFmpeg
-const videoProcessor = unoptimizedVideosTopic.consumerGroup("processors");
+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
+});
+```
 
-try {
-  await videoProcessor.consume(async (inputVideoStream) => {
-    console.log("Processing video...");
+### `receive(topicName, consumerGroup, handler, options?)`
 
-    if (!ffmpeg) {
-      throw new Error("FFmpeg not available");
-    }
+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.
 
-    // Create optimized video stream using FFmpeg
-    const optimizedStream = new ReadableStream<Uint8Array>({
-      start(controller) {
-        const ffmpegProcess = spawn(
-          ffmpeg,
-          [
-            "-i",
-            "pipe:0", // Input from stdin
-            "-c:v",
-            "libvpx-vp9", // Video codec
-            "-c:a",
-            "libopus", // Audio codec
-            "-crf",
-            "23", // Quality
-            "-f",
-            "webm", // Output format
-            "pipe:1", // Output to stdout
-          ],
-          { stdio: ["pipe", "pipe", "pipe"] },
-        );
-
-        // Pipe input stream to FFmpeg
-        const reader = inputVideoStream.getReader();
-        const pipeInput = async () => {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-              ffmpegProcess.stdin?.end();
-              break;
-            }
-            ffmpegProcess.stdin?.write(value);
-          }
-        };
-        pipeInput();
-
-        // Stream FFmpeg output
-        ffmpegProcess.stdout?.on("data", (chunk) => {
-          controller.enqueue(new Uint8Array(chunk));
-        });
-
-        ffmpegProcess.on("close", (code) => {
-          if (code === 0) {
-            controller.close();
-          } else {
-            controller.error(new Error(`FFmpeg failed with code ${code}`));
-          }
-        });
-      },
-    });
-
-    // Publish optimized video to next topic
-    await optimizedVideosTopic.publish(optimizedStream);
-    console.log("Video optimized and published");
-  });
-} catch (error) {
-  console.error("Video processing error:", error);
-}
-
-// Step 2: Store optimized videos in Vercel Blob
-const blobUploader = optimizedVideosTopic.consumerGroup("blob-uploaders");
+For receive-by-id, operational errors are returned instead of thrown:
 
-try {
-  await blobUploader.consume(async (optimizedVideo) => {
-    // Upload to Vercel Blob storage
-    const filename = `optimized-${Date.now()}.webm`;
-    const blob = await put(filename, optimizedVideo, {
-      access: "public",
-      contentType: "video/webm",
-    });
-
-    console.log(`Video uploaded to blob: ${blob.url} (${blob.size} bytes)`);
-  });
-} catch (error) {
-  console.error("Blob upload error:", error);
+```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);
 }
 ```
 
-## Error Handling
-
-The queue client provides specific error types for different failure scenarios:
-
-### Error Types
-
-- **`QueueEmptyError`**: Thrown when attempting to receive messages from an
-  empty queue (204 status)
-
-  - Thrown by `consume()` when no messages are available
-  - Also thrown when directly using `client.receiveMessages()`
-
-- **`MessageLockedError`**: Thrown when a message is temporarily locked (423
-  status)
-
-  - Contains optional `retryAfter` property with seconds to wait before retry
-  - For `consume()` without options: the next message in FIFO sequence is locked
-  - For `consume()` with messageId: the requested message is locked
-
-- **`MessageNotFoundError`**: Message doesn't exist (404 status)
-
-- **`MessageNotAvailableError`**: Message exists but isn't available for
-  processing (409 status)
-
-- **`FifoOrderingViolationError`**: FIFO queue ordering violation (409 status
-  with nextMessageId)
-
-  - Contains `nextMessageId` property indicating which message to process first
-
-- **`FailedDependencyError`**: FIFO ordering violation when receiving by ID (424
-  status)
-
-  - Contains `nextMessageId` property indicating which message must be processed
-    first
-  - Similar to `FifoOrderingViolationError` but specifically for receive-by-ID
-    operations
-
-- **`MessageCorruptedError`**: Message data is corrupted or can't be parsed
-
-- **`BadRequestError`**: Invalid request parameters (400 status)
-
-  - Invalid queue names, FIFO limit violations, missing required parameters
-
-- **`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,
-  FailedDependencyError,
-  FifoOrderingViolationError,
-  ForbiddenError,
-  InternalServerError,
-  MessageLockedError,
-  QueueEmptyError,
-  UnauthorizedError,
-} from "@vercel/queue";
-
-// Handle empty queue or locked messages
-try {
-  for await (const message of client.receiveMessages(options, transport)) {
-    // Process messages
-  }
-} catch (error) {
-  if (error instanceof QueueEmptyError) {
-    console.log("Queue is empty, retry later");
-  } else if (error instanceof MessageLockedError) {
-    console.log("Next message in FIFO queue 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 consumer.consume(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);
-    }
-  } else if (error instanceof FailedDependencyError) {
-    // FIFO ordering violation for receive by ID
-    console.log(`Must process ${error.nextMessageId} first`);
-  }
-}
+### Handler Signature
 
-// Handle authentication and authorization errors
-try {
-  await topic.publish(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;
 }
 ```