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

package/README.md

@@ -1,12 +1,17 @@
 # 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
+with customizable serialization/deserialization (transport) support, including
+**streaming support** for memory-efficient processing of large payloads.
 
 ## 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
+- **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
@@ -19,7 +24,8 @@ npm install @vercel/queue
 
 ## Quick Start
 
-For local development, you'll need to pull your Vercel environment variables (including the OIDC token):
+For local development, you'll need to pull your Vercel environment variables
+(including the OIDC token):
 
 ```bash
 # Install Vercel CLI if you haven't already
@@ -33,16 +39,33 @@ Publishing and consuming messages on a queue
 
 ```typescript
 // index.ts
-import { QueueClient, createTopic, JsonTransport } from "@vercel/queue";
+import { send, receive } from "@vercel/queue";
 
-// Create a client - automatically authenticated using the OIDC token
-const client = QueueClient.fromVercelFunction();
+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
+
+import { createTopic } from "@vercel/queue";
 
 // Create a topic with JSON serialization (default)
-const topic = createTopic<{ message: string; timestamp: number }>(
-  client,
-  "my-topic",
-);
+// Uses default QueueClient automatically authenticated from Vercel environment
+const topic = createTopic<Message>("my-topic");
 
 // Publish a message
 await topic.publish({
@@ -51,41 +74,45 @@ await topic.publish({
 });
 
 // Create a consumer group
-const consumer = topic.consumerGroup("my-processors");
-
-// Process messages continuously with cancellation support
-const controller = new AbortController();
+const consumer = topic.consumerGroup("my-consumer-group");
 
-// Start processing (blocks until aborted or error)
+// Process next available message (one-shot processing)
 try {
-  await consumer.subscribe(controller.signal, async (message) => {
-    console.log("Received:", message.payload.message);
-    console.log("Timestamp:", new Date(message.payload.timestamp));
+  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 stopped due to error:", error);
+  console.error("Processing error:", error);
 }
-
-// Stop processing from elsewhere in your code
-// controller.abort();
 ```
 
 Run the script
 
 ```bash
-# Using dotenv to load the OIDC token
-dotenv -e .env.local node index.ts
+# Install dotenv-cli and ts-node if you need it
+npm i -g dotenv-cli ts-node typescript
+
+# Run the script with the OIDC token
+dotenv -e .env.local ts-node index.ts
 ```
 
 ## Usage with Vercel
 
-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.
+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).
+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 Configuration
 
-Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
+Update your `tsconfig.json` to use `"bundler"` module resolution for proper
+package export resolution:
 
 ```json
 {
@@ -101,38 +128,75 @@ Update your `tsconfig.json` to use `"bundler"` module resolution for proper pack
 Create a new server function to publish messages
 
 ```typescript
-// app/action.ts
+// app/actions.ts
 "use server";
 
-import { QueueClient, createTopic } from "@vercel/queue";
+import { send } from "@vercel/queue";
 
 export async function publishTestMessage(message: string) {
-  // Initialize a queue client
-  const client = await QueueClient.fromVercelFunction();
-
-  // Create a topic with JSON serialization (default)
-  const topic = createTopic<{ message: string; timestamp: number }>(
-    client,
+  // 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
+      },
+    },
   );
 
+  console.log(`Published message ${messageId}`);
+}
+
+// Option 2: Customize the topic, transport, consumer groups, etc.
+import { createTopic } from "@vercel/queue";
+
+export async function publishTestMessage(message: string) {
+  // Create a topic with JSON serialization (default)
+  const topic = createTopic<{ message: string; timestamp: number }>("my-topic");
+
   // Publish the message
   const { messageId } = await topic.publish(
     { message, timestamp: Date.now() },
     {
-      // Provide a callback URL to invoke a consumer when the message is ready to be processed
-      callbacks: {
-        webhook: {
-          url: process.env.VERCEL_PROJECT_PRODUCTION_URL
-            ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}/api/queue/handle`
-            : "http://localhost:3000/api/queue/handle",
-        },
+      // 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
+          },
+        }
       },
     },
   );
 
   console.log(`Published message ${messageId}`);
 }
+
+// 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
+    );
+  }
+
+  return callbackUrl.toString();
+}
+
 ```
 
 Now wire up the server function to your app
@@ -142,76 +206,56 @@ Now wire up the server function to your app
 "use client";
 import { publishTestMessage } from "./actions";
 
-export default function Button() {
+export default function Page() {
   return (
     // ...
-    <Button onClick={() => publishTestMessage("Hello world")} >
+    <button onClick={() => publishTestMessage("Hello world")}>
       Publish Test Message
-    </a>
+    </button>
   );
 }
 ```
 
 ### Consuming the queue
 
-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.
+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.
+
+The `handleCallback` helper function simplifies queue callback handling in NextJS:
 
 ```typescript
 // app/api/queue/handle/route.ts
-import { QueueClient, Topic, parseCallbackRequest } from "@vercel/queue";
-import { NextRequest } from "next/server";
-
-// Handle Vercel Queue callback requests
-export async function POST(request: NextRequest) {
-  try {
-    // Parse the queue callback information
-    const { queueName, consumerGroup, messageId } =
-      parseCallbackRequest(request);
-
-    // Create client
-    const client = await QueueClient.fromVercelFunction();
-
-    // Create topic and consumer group from the callback info
-    const topic = new Topic(client, queueName);
-    const cg = topic.consumerGroup(consumerGroup);
-
-    // Process the message
-    await cg.receiveMessage(messageId, async (message) => {
-      const payload = message.payload as { message: string; timestamp: number };
-      console.log(
-        `Received message "${payload.message}" (Sent at: ${payload.timestamp})`,
-      );
-    });
+import { handleCallback } from "@vercel/queue";
 
-    return Response.json({ status: "success" });
-  } catch (error) {
-    console.error("Webhook error:", error);
-    return Response.json(
-      { error: "Failed to process webhook" },
-      { status: 500 },
-    );
-  }
-}
-```
+// 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 }
+  },
+
+  // .. more topic handlers can be provided here
+});
+
+// This consumes messages on the "default" consumer group, which is used when no consumer groups
+// were specified in the publish `callback` earlierA
 
-> ![NOTE]
-> A single webhook handle can be used to process messages across various queues and consumer groups. Use the values of `queueName` and `consumerGroup` from `parseCallbackRequest()` to dynamically handle different code paths:
->
-> ```typescript
-> if (queueName === "upload-queue") {
->   processImageQueue(consumerGroup, message);
-> }
-> // ...
-> function processImageQueue(consumerGroup, message) {
->   if (consumerGroup === "compress") {
->     // handle image compression
->   }
->   // ...
-> }
-> // ...
-> ```
->
-> We are building an SDK to make queues and workflow easier to use. Reach out if you're interested.
+// 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);
+    },
+  },
+});
+```
 
 ## Key Features
 
@@ -220,18 +264,16 @@ export async function POST(request: NextRequest) {
 Handle large files and data streams without loading them into memory:
 
 ```typescript
-import { StreamTransport } from "@vercel/queue";
+import { createTopic, StreamTransport } from "@vercel/queue";
 
 const videoTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "video-processing",
   new StreamTransport(),
 );
 
 // Process large video files efficiently
 const processor = videoTopic.consumerGroup("processors");
-await processor.subscribe(signal, async (message) => {
-  const videoStream = message.payload;
+await processor.consume(async (videoStream) => {
   // Process stream chunk by chunk
   const reader = videoStream.getReader();
   while (true) {
@@ -261,12 +303,14 @@ const webhooks = topic.consumerGroup("webhooks");
 ## Architecture
 
 - **Topics**: Named message channels with configurable serialization
-- **Consumer Groups**: Named groups of consumers that process messages in parallel
-  - `subscribe()`: Continuously process messages with automatic polling
-  - `receiveMessage()`: Process a specific message by ID
-  - `receiveNextMessage()`: Process the next available message (one-shot)
-  - `handleMessage()`: Process message metadata only (without payload)
-- **Transports**: Pluggable serialization/deserialization for different data types
+- **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
 
@@ -277,55 +321,53 @@ 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
+- **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 at the **topic level** when creating a topic, or at the **consumer group level** when creating a consumer group.
+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.
 
 ### Built-in Transports
 
 #### JsonTransport (Default)
 
-Buffers data for JSON parsing - suitable for structured data that fits in memory.
+Buffers data for JSON parsing - suitable for structured data that fits in
+memory.
 
 ```typescript
-import { JsonTransport, createTopic } from "@vercel/queue";
+import { createTopic, JsonTransport } from "@vercel/queue";
 
-const topic = createTopic<{ data: any }>(
-  client,
-  "json-topic",
-  new JsonTransport(),
-);
+const topic = createTopic<{ data: any }>("json-topic", new JsonTransport());
 // or simply (JsonTransport is the default):
-const topic = createTopic<{ data: any }>(client, "json-topic");
+const topic = createTopic<{ data: any }>("json-topic");
 ```
 
 #### BufferTransport
 
-Buffers the entire payload into memory as a Buffer - suitable for binary data that fits in memory.
+Buffers the entire payload into memory as a Buffer - suitable for binary data
+that fits in memory.
 
 ```typescript
 import { BufferTransport, createTopic } from "@vercel/queue";
 
-const topic = createTopic<Buffer>(
-  client,
-  "binary-topic",
-  new BufferTransport(),
-);
+const topic = createTopic<Buffer>("binary-topic", new BufferTransport());
 const binaryData = Buffer.from("Binary data", "utf8");
 await topic.publish(binaryData);
 ```
 
 #### StreamTransport
 
-**True streaming support** - passes ReadableStream directly without buffering. Ideal for large files and memory-efficient processing.
+**True streaming support** - passes ReadableStream directly without buffering.
+Ideal for large files and memory-efficient processing.
 
 ```typescript
-import { StreamTransport, createTopic } from "@vercel/queue";
+import { createTopic, StreamTransport } from "@vercel/queue";
 
 const topic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "streaming-topic",
   new StreamTransport(),
 );
@@ -346,7 +388,8 @@ await topic.publish(fileStream);
 
 ### Custom Transport
 
-You can create your own serialization format by implementing the `Transport` interface:
+You can create your own serialization format by implementing the `Transport`
+interface:
 
 ```typescript
 import { Transport } from "@vercel/queue";
@@ -373,8 +416,12 @@ interface Transport<T = unknown> {
 ### QueueClient
 
 ```typescript
+// Simple usage - automatically gets OIDC token from Vercel environment
+const client = new QueueClient();
+
+// Or with options
 const client = new QueueClient({
-  token: string;
+  token?: string; // Optional - will auto-detect if not provided
   baseUrl?: string; // defaults to 'https://vqs.vercel.sh'
 });
 ```
@@ -382,37 +429,88 @@ const client = new QueueClient({
 ### Topic
 
 ```typescript
-const topic = createTopic<T>(client, topicName, transport?);
+// Simple usage with default client
+const topic = createTopic<T>(topicName, transport?);
+
+// 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?);
 
 // Publish a message (uses topic's transport)
 await topic.publish(payload, options?);
 
+// Trigger a callback URL when the message is
+// ready for consumption
+await topic.publish(payload, {
+  callback: { url: "https://example.com/webhook" }
+});
+
+// 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 }
+  }
+});
+
 // Create a consumer group (can override transport)
 const consumer = topic.consumerGroup<U>(groupName, options?);
 ```
 
-### ConsumerGroup
+### Send (Shorthand)
 
 ```typescript
-// Start continuous processing (blocks until signal is aborted or error occurs)
-await consumer.subscribe(signal, handler, options?);
+// 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;
+});
+
+// Examples:
+await send("notifications", { userId: "123", message: "Welcome!" });
+
+await send("images", imageBuffer, {
+  transport: new BufferTransport(),
+  callback: { url: "https://example.com/process-image" }
+});
 
-// Process a specific message by ID
-await consumer.receiveMessage(messageId, handler);
+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 }
+  }
+});
+```
 
-// Process the next available message
-await consumer.receiveNextMessage(handler);
+### ConsumerGroup
 
-// Handle a specific message by ID without payload
-await consumer.handleMessage(messageId, handler);
+```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" });
+
+// 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
 
 ```typescript
 // Handler function signature
-type MessageHandler<T> = (
-  message: Message<T>,
+type MessageHandler<T = unknown> = (
+  message: T,
+  metadata: MessageMetadata,
 ) => Promise<MessageHandlerResult> | MessageHandlerResult;
 
 // Handler result types
@@ -421,6 +519,22 @@ type MessageHandlerResult = void | MessageTimeoutResult;
 interface MessageTimeoutResult {
   timeoutSeconds: number; // seconds before message becomes available again
 }
+
+// Message Metadata
+interface MessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  timestamp: string;
+}
+```
+
+### ConsumeOptions Interface
+
+```typescript
+interface ConsumeOptions {
+  messageId?: string; // Process specific message by ID
+  skipPayload?: boolean; // Skip payload download (requires messageId)
+}
 ```
 
 ### Transport Interface
@@ -445,6 +559,29 @@ interface CallbackMessageOptions {
   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);
+  },
+
+  // 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;
@@ -461,7 +598,15 @@ interface UserEvent {
   timestamp: number;
 }
 
-const userTopic = createTopic<UserEvent>(client, "user-events");
+// 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",
@@ -470,27 +615,21 @@ await userTopic.publish({
 });
 
 const consumer = userTopic.consumerGroup("processors");
-const controller = new AbortController();
 
+// Process next available message
 try {
-  await consumer.subscribe(controller.signal, async (message) => {
-    console.log(
-      `User ${message.payload.userId} performed ${message.payload.action}`,
-    );
+  await consumer.consume(async (message) => {
+    console.log(`User ${message.userId} performed ${message.action}`);
   });
 } catch (error) {
   console.error("Processing error:", error);
 }
-
-// Stop processing when needed
-// controller.abort();
 ```
 
 ### Processing Specific Messages by ID
 
 ```typescript
 const userTopic = createTopic<{ userId: string; action: string }>(
-  client,
   "user-events",
 );
 const consumer = userTopic.consumerGroup("processors");
@@ -499,12 +638,13 @@ const consumer = userTopic.consumerGroup("processors");
 const messageId = "01234567-89ab-cdef-0123-456789abcdef";
 
 try {
-  await consumer.receiveMessage(messageId, async (message) => {
-    console.log(`Processing specific message: ${message.messageId}`);
-    console.log(
-      `User ${message.payload.userId} performed ${message.payload.action}`,
-    );
-  });
+  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");
 } catch (error) {
   if (error.message.includes("not found or not available")) {
@@ -520,17 +660,14 @@ try {
 ### Processing Next Available Message
 
 ```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>(
-  client,
-  "work-queue",
-);
+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.receiveNextMessage(async (message) => {
-    console.log(`Processing task: ${message.payload.taskType}`);
-    await processTask(message.payload.taskType, message.payload.data);
+  await worker.consume(async (message) => {
+    console.log(`Processing task: ${message.taskType}`);
+    await processTask(message.taskType, message.data);
   });
   console.log("Message processed successfully");
 } catch (error) {
@@ -546,31 +683,37 @@ try {
   }
 }
 
-// You can also use it with timeout results
-await worker.receiveNextMessage(async (message) => {
-  if (!canProcessTaskType(message.payload.taskType)) {
+// Handle conditional timeouts
+await worker.consume(async (message) => {
+  if (!canProcessTaskType(message.taskType)) {
     // Return timeout to retry later
     return { timeoutSeconds: 60 };
   }
 
-  await processTask(message.payload.taskType, message.payload.data);
+  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
 
 ```typescript
-const workTopic = createTopic<{ taskType: string; data: any }>(
-  client,
-  "work-queue",
-);
+const workTopic = createTopic<{ taskType: string; data: any }>("work-queue");
 const worker = workTopic.consumerGroup("workers");
-const controller = new AbortController();
 
+// Process a message with conditional timeout
 try {
-  await worker.subscribe(controller.signal, async (message) => {
-    const { taskType, data } = message.payload;
-
+  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)
@@ -593,15 +736,12 @@ try {
 }
 
 // Example with exponential backoff
-const backoffController = new AbortController();
-
 try {
-  await worker.subscribe(backoffController.signal, async (message) => {
+  await worker.consume(async (message, { deliveryCount }) => {
     const maxRetries = 3;
-    const deliveryCount = message.deliveryCount;
 
     try {
-      await processMessage(message.payload);
+      await processMessage(message);
       // Successful processing - message will be deleted
     } catch (error) {
       if (deliveryCount < maxRetries) {
@@ -625,114 +765,101 @@ try {
 
 ### Complete Example: Video Processing Pipeline
 
-Here's a comprehensive example showing a video processing pipeline that processes videos with FFmpeg and stores the results in Vercel Blob:
+Here's a comprehensive example showing a video processing pipeline that
+processes videos with FFmpeg and stores the results in Vercel Blob:
 
 ```typescript
-import { QueueClient, createTopic, StreamTransport } from "@vercel/queue";
+import { createTopic, StreamTransport } from "@vercel/queue";
 import { spawn } from "child_process";
 import ffmpeg from "ffmpeg-static";
 import { put } from "@vercel/blob";
 
-const client = new QueueClient({
-  token: "your-vercel-oidc-token",
-});
-
 // Input topic with unoptimized videos
 const unoptimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "unoptimized-videos",
   new StreamTransport(),
 );
 
 // Output topic for optimized videos
 const optimizedVideosTopic = createTopic<ReadableStream<Uint8Array>>(
-  client,
   "optimized-videos",
   new StreamTransport(),
 );
 
 // Step 1: Process videos with FFmpeg
 const videoProcessor = unoptimizedVideosTopic.consumerGroup("processors");
-const processingController = new AbortController();
 
 try {
-  await videoProcessor.subscribe(
-    processingController.signal,
-    async (message) => {
-      const inputVideoStream = message.payload;
-      console.log("Processing video...");
-
-      if (!ffmpeg) {
-        throw new Error("FFmpeg not available");
-      }
+  await videoProcessor.consume(async (inputVideoStream) => {
+    console.log("Processing video...");
 
-      // 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}`));
+    if (!ffmpeg) {
+      throw new Error("FFmpeg not available");
+    }
+
+    // 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");
-    },
-  );
+    // 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");
-const uploadController = new AbortController();
 
 try {
-  await blobUploader.subscribe(uploadController.signal, async (message) => {
-    const optimizedVideo = message.payload;
-
+  await blobUploader.consume(async (optimizedVideo) => {
     // Upload to Vercel Blob storage
     const filename = `optimized-${Date.now()}.webm`;
     const blob = await put(filename, optimizedVideo, {
@@ -745,12 +872,6 @@ try {
 } catch (error) {
   console.error("Blob upload error:", error);
 }
-
-// Graceful shutdown
-process.on("SIGINT", () => {
-  processingController.abort();
-  uploadController.abort();
-});
 ```
 
 ## Error Handling
@@ -759,30 +880,36 @@ 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)
+- **`QueueEmptyError`**: Thrown when attempting to receive messages from an
+  empty queue (204 status)
 
-  - Only thrown when directly using `client.receiveMessages()`
-  - `ConsumerGroup.subscribe()` handles this error internally and continues polling
+  - 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)
+- **`MessageLockedError`**: Thrown when a message is temporarily locked (423
+  status)
 
   - Contains optional `retryAfter` property with seconds to wait before retry
-  - For `receiveMessages()` on FIFO queues: the next message in sequence is locked
-  - For `receiveMessageById()`: the requested message is locked
-  - `ConsumerGroup.subscribe()` handles this error internally when polling
+  - 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)
+- **`MessageNotAvailableError`**: Message exists but isn't available for
+  processing (409 status)
 
-- **`FifoOrderingViolationError`**: FIFO queue ordering violation (409 status with nextMessageId)
+- **`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)
+- **`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
+  - 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
 
@@ -805,14 +932,14 @@ The queue client provides specific error types for different failure scenarios:
 
 ```typescript
 import {
-  QueueEmptyError,
-  MessageLockedError,
-  FifoOrderingViolationError,
-  FailedDependencyError,
   BadRequestError,
-  UnauthorizedError,
+  FailedDependencyError,
+  FifoOrderingViolationError,
   ForbiddenError,
   InternalServerError,
+  MessageLockedError,
+  QueueEmptyError,
+  UnauthorizedError,
 } from "@vercel/queue";
 
 // Handle empty queue or locked messages
@@ -833,7 +960,7 @@ try {
 
 // Handle locked message with retry
 try {
-  await consumer.receiveMessage(messageId, handler);
+  await consumer.consume(handler, { messageId });
 } catch (error) {
   if (error instanceof MessageLockedError) {
     console.log("Message is locked by another consumer");