@vercel/queue 0.0.0-alpha.29 → 0.0.0-alpha.30

package/README.md

@@ -134,6 +134,8 @@ Messages are consumed using API routes that Vercel automatically triggers when m
 
 #### 1. Create API Routes
 
+##### App Router (Recommended)
+
 The recommended approach is to handle multiple topics and consumers in a single API route to keep your `vercel.json` configuration simple:
 
 ```typescript
@@ -179,9 +181,42 @@ export const POST = handleCallback({
 
 While you can split handlers into separate routes if needed (e.g., for code organization or deployment flexibility), consolidating them in one route is recommended for simpler configuration.
 
+##### Pages Router
+
+For Next.js Pages Router, import from `@vercel/queue/pages` to get a handler compatible with the Pages Router API (`NextApiRequest`/`NextApiResponse`):
+
+```typescript
+// pages/api/queue.ts
+import { handleCallback } from "@vercel/queue/pages";
+
+export default handleCallback({
+  "my-topic": {
+    "my-consumer": async (message, metadata) => {
+      console.log("Processing message:", message);
+      await processMessage(message);
+    },
+  },
+  "order-events": {
+    fulfillment: async (order, metadata) => {
+      if (!isSystemReady()) {
+        return { timeoutSeconds: 300 };
+      }
+      await processOrder(order);
+    },
+    analytics: async (order, metadata) => {
+      await trackOrder(order);
+    },
+  },
+});
+```
+
+The `/pages` subpath export automatically adapts the handler to work with the Pages Router API.
+
 #### 2. Configure vercel.json
 
-Configure which topics and consumers your API route handles:
+Configure which topics and consumers your API route handles.
+
+**For App Router:**
 
 ```json
 {
@@ -212,6 +247,37 @@ Configure which topics and consumers your API route handles:
 }
 ```
 
+**For Pages Router:**
+
+```json
+{
+  "functions": {
+    "pages/api/queue.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v1beta",
+          "topic": "my-topic",
+          "consumer": "my-consumer",
+          "retryAfterSeconds": 60,
+          "initialDelaySeconds": 0
+        },
+        {
+          "type": "queue/v1beta",
+          "topic": "order-events",
+          "consumer": "fulfillment"
+        },
+        {
+          "type": "queue/v1beta",
+          "topic": "order-events",
+          "consumer": "analytics",
+          "retryAfterSeconds": 300
+        }
+      ]
+    }
+  }
+}
+```
+
 ### Key Concepts
 
 - **Topics**: Named message channels that can have multiple consumer groups

package/dist/index.d.mts

@@ -1,257 +1,5 @@
-/**
- * Serializer/Deserializer interface for message payloads
- */
-interface Transport<T = unknown> {
-    /**
-     * Serialize a value to a buffer or stream for transmission
-     */
-    serialize(value: T): Buffer | ReadableStream<Uint8Array>;
-    /**
-     * Deserialize a readable stream back to the original value
-     */
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-    /**
-     * Optional cleanup method for deserialized payloads that may contain resources
-     * Should be called when the payload is no longer needed, especially in error cases
-     * @param payload The deserialized payload to clean up
-     */
-    finalize?(payload: T): Promise<void>;
-    /**
-     * MIME type for this serialization format
-     */
-    contentType: string;
-}
-/**
- * Built-in JSON serializer/deserializer
- * This implementation reads the entire stream into memory for JSON parsing
- */
-declare class JsonTransport<T = unknown> implements Transport<T> {
-    readonly contentType = "application/json";
-    readonly replacer?: Parameters<typeof JSON.parse>[1];
-    readonly reviver?: Parameters<typeof JSON.parse>[1];
-    constructor(options?: {
-        replacer?: Parameters<typeof JSON.parse>[1];
-        reviver?: Parameters<typeof JSON.parse>[1];
-    });
-    serialize(value: T): Buffer;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-}
-/**
- * Built-in Buffer serializer/deserializer (reads entire stream into a Buffer)
- */
-declare class BufferTransport implements Transport<Buffer> {
-    readonly contentType = "application/octet-stream";
-    serialize(value: Buffer): Buffer;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
-}
-/**
- * Stream serializer/deserializer (pass-through for streaming binary data)
- * This is ideal for large payloads that don't need to be buffered in memory
- *
- * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
- * processing the message to prevent resource leaks, especially in error cases.
- * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
- *
- * Example usage:
- * ```typescript
- * const transport = new StreamTransport();
- * try {
- *   for await (const message of client.receiveMessages(options, transport)) {
- *     // Process the stream...
- *     const reader = message.payload.getReader();
- *     // ... handle stream data
- *   }
- * } catch (error) {
- *   // Cleanup is handled automatically by ConsumerGroup
- *   // or manually: await transport.finalize(message.payload);
- * }
- */
-declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
-    readonly contentType = "application/octet-stream";
-    serialize(value: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
-    finalize(payload: ReadableStream<Uint8Array>): Promise<void>;
-}
-
-/**
- * Vercel Queue Service client types
- */
-
-/**
- * Shared options for publishing messages
- */
-interface PublishOptions {
-    /**
-     * Unique key to prevent duplicate message submissions
-     * @default random UUID
-     */
-    idempotencyKey?: string;
-    /**
-     * Message retention time in seconds
-     * @default 86400 (24 hours)
-     * @min 60
-     * @max 86400
-     */
-    retentionSeconds?: number;
-    /**
-     * Explicit deployment identifier to include in the `Vqs-Deployment-Id` header
-     * If provided, this takes precedence over any value from the environment
-     */
-    deploymentId?: string;
-}
-interface SendMessageOptions<T = unknown> extends PublishOptions {
-    /**
-     * The queue name to send the message to
-     */
-    queueName: string;
-    /**
-     * The message payload
-     */
-    payload: T;
-}
-interface SendMessageResponse {
-    /**
-     * The generated message ID
-     */
-    messageId: string;
-}
-interface Message<T = unknown> {
-    /**
-     * The message ID
-     */
-    messageId: string;
-    /**
-     * The deserialized message payload
-     * Note: If using streaming transports, ensure proper cleanup by calling transport.finalize(payload)
-     * when done processing, especially in error cases
-     */
-    payload: T;
-    /**
-     * Number of times this message has been delivered
-     */
-    deliveryCount: number;
-    /**
-     * When the message was created
-     */
-    createdAt: Date;
-    /**
-     * MIME type of the message content
-     */
-    contentType: string;
-    /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
-     */
-    ticket: string;
-}
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
-    /**
-     * Time in seconds before the message becomes visible again
-     */
-    timeoutSeconds: number;
-}
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
-/**
- * Message metadata provided to handlers
- */
-interface MessageMetadata {
-    messageId: string;
-    deliveryCount: number;
-    createdAt: Date;
-    topicName: string;
-    consumerGroup: string;
-}
-/**
- * Message handler function type
- */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
-/**
- * Options for creating a ConsumerGroup instance
- */
-interface ConsumerGroupOptions<T = unknown> {
-    /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
-     */
-    transport?: Transport<T>;
-    /**
-     * Time in seconds that messages will be invisible to other consumers
-     * @default 30
-     */
-    visibilityTimeoutSeconds?: number;
-    /**
-     * How often to refresh the visibility timeout during processing (in seconds)
-     * @default 10
-     */
-    refreshInterval?: number;
-}
-/**
- * Error thrown when a message is not found (404)
- */
-declare class MessageNotFoundError extends Error {
-    constructor(messageId: string);
-}
-/**
- * Error thrown when a message is not available for processing (409)
- * This can happen when the message is in the wrong state, already claimed, etc.
- */
-declare class MessageNotAvailableError extends Error {
-    constructor(messageId: string, reason?: string);
-}
-/**
- * Error thrown when message data is corrupted or can't be parsed
- */
-declare class MessageCorruptedError extends Error {
-    constructor(messageId: string, reason: string);
-}
-/**
- * Error thrown when there are no messages available in the queue (204)
- */
-declare class QueueEmptyError extends Error {
-    constructor(queueName: string, consumerGroup: string);
-}
-/**
- * Error thrown when a message is temporarily locked (423)
- */
-declare class MessageLockedError extends Error {
-    readonly retryAfter?: number;
-    constructor(messageId: string, retryAfter?: number);
-}
-/**
- * Error thrown when authentication fails (401)
- */
-declare class UnauthorizedError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown when access is forbidden (403)
- */
-declare class ForbiddenError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown for bad requests (400)
- */
-declare class BadRequestError extends Error {
-    constructor(message: string);
-}
-/**
- * Error thrown for internal server errors (500)
- */
-declare class InternalServerError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown when batch limit parameter is invalid
- */
-declare class InvalidLimitError extends Error {
-    constructor(limit: number, min?: number, max?: number);
-}
+import { M as MessageHandler, C as ConsumerGroupOptions, P as PublishOptions, T as Transport } from './types-JvOenjfT.mjs';
+export { a as BadRequestError, B as BufferTransport, F as ForbiddenError, I as InternalServerError, b as InvalidLimitError, J as JsonTransport, g as Message, c as MessageCorruptedError, h as MessageHandlerResult, d as MessageLockedError, i as MessageMetadata, e as MessageNotAvailableError, f as MessageNotFoundError, j as MessageTimeoutResult, Q as QueueEmptyError, k as SendMessageOptions, l as SendMessageResponse, S as StreamTransport, U as UnauthorizedError } from './types-JvOenjfT.mjs';
 
 /**
  * Options for the consume method
@@ -408,4 +156,4 @@ declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>
  */
 declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-export { BadRequestError, BufferTransport, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type ParsedCallbackRequest, type PublishOptions, QueueEmptyError, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, type Transport, UnauthorizedError, handleCallback, parseCallback, receive, send };
+export { MessageHandler, type ParsedCallbackRequest, PublishOptions, type ReceiveOptions, type SendOptions, Transport, handleCallback, parseCallback, receive, send };

package/dist/index.d.ts

@@ -1,257 +1,5 @@
-/**
- * Serializer/Deserializer interface for message payloads
- */
-interface Transport<T = unknown> {
-    /**
-     * Serialize a value to a buffer or stream for transmission
-     */
-    serialize(value: T): Buffer | ReadableStream<Uint8Array>;
-    /**
-     * Deserialize a readable stream back to the original value
-     */
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-    /**
-     * Optional cleanup method for deserialized payloads that may contain resources
-     * Should be called when the payload is no longer needed, especially in error cases
-     * @param payload The deserialized payload to clean up
-     */
-    finalize?(payload: T): Promise<void>;
-    /**
-     * MIME type for this serialization format
-     */
-    contentType: string;
-}
-/**
- * Built-in JSON serializer/deserializer
- * This implementation reads the entire stream into memory for JSON parsing
- */
-declare class JsonTransport<T = unknown> implements Transport<T> {
-    readonly contentType = "application/json";
-    readonly replacer?: Parameters<typeof JSON.parse>[1];
-    readonly reviver?: Parameters<typeof JSON.parse>[1];
-    constructor(options?: {
-        replacer?: Parameters<typeof JSON.parse>[1];
-        reviver?: Parameters<typeof JSON.parse>[1];
-    });
-    serialize(value: T): Buffer;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
-}
-/**
- * Built-in Buffer serializer/deserializer (reads entire stream into a Buffer)
- */
-declare class BufferTransport implements Transport<Buffer> {
-    readonly contentType = "application/octet-stream";
-    serialize(value: Buffer): Buffer;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
-}
-/**
- * Stream serializer/deserializer (pass-through for streaming binary data)
- * This is ideal for large payloads that don't need to be buffered in memory
- *
- * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
- * processing the message to prevent resource leaks, especially in error cases.
- * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
- *
- * Example usage:
- * ```typescript
- * const transport = new StreamTransport();
- * try {
- *   for await (const message of client.receiveMessages(options, transport)) {
- *     // Process the stream...
- *     const reader = message.payload.getReader();
- *     // ... handle stream data
- *   }
- * } catch (error) {
- *   // Cleanup is handled automatically by ConsumerGroup
- *   // or manually: await transport.finalize(message.payload);
- * }
- */
-declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
-    readonly contentType = "application/octet-stream";
-    serialize(value: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
-    deserialize(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
-    finalize(payload: ReadableStream<Uint8Array>): Promise<void>;
-}
-
-/**
- * Vercel Queue Service client types
- */
-
-/**
- * Shared options for publishing messages
- */
-interface PublishOptions {
-    /**
-     * Unique key to prevent duplicate message submissions
-     * @default random UUID
-     */
-    idempotencyKey?: string;
-    /**
-     * Message retention time in seconds
-     * @default 86400 (24 hours)
-     * @min 60
-     * @max 86400
-     */
-    retentionSeconds?: number;
-    /**
-     * Explicit deployment identifier to include in the `Vqs-Deployment-Id` header
-     * If provided, this takes precedence over any value from the environment
-     */
-    deploymentId?: string;
-}
-interface SendMessageOptions<T = unknown> extends PublishOptions {
-    /**
-     * The queue name to send the message to
-     */
-    queueName: string;
-    /**
-     * The message payload
-     */
-    payload: T;
-}
-interface SendMessageResponse {
-    /**
-     * The generated message ID
-     */
-    messageId: string;
-}
-interface Message<T = unknown> {
-    /**
-     * The message ID
-     */
-    messageId: string;
-    /**
-     * The deserialized message payload
-     * Note: If using streaming transports, ensure proper cleanup by calling transport.finalize(payload)
-     * when done processing, especially in error cases
-     */
-    payload: T;
-    /**
-     * Number of times this message has been delivered
-     */
-    deliveryCount: number;
-    /**
-     * When the message was created
-     */
-    createdAt: Date;
-    /**
-     * MIME type of the message content
-     */
-    contentType: string;
-    /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
-     */
-    ticket: string;
-}
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
-    /**
-     * Time in seconds before the message becomes visible again
-     */
-    timeoutSeconds: number;
-}
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
-/**
- * Message metadata provided to handlers
- */
-interface MessageMetadata {
-    messageId: string;
-    deliveryCount: number;
-    createdAt: Date;
-    topicName: string;
-    consumerGroup: string;
-}
-/**
- * Message handler function type
- */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
-/**
- * Options for creating a ConsumerGroup instance
- */
-interface ConsumerGroupOptions<T = unknown> {
-    /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
-     */
-    transport?: Transport<T>;
-    /**
-     * Time in seconds that messages will be invisible to other consumers
-     * @default 30
-     */
-    visibilityTimeoutSeconds?: number;
-    /**
-     * How often to refresh the visibility timeout during processing (in seconds)
-     * @default 10
-     */
-    refreshInterval?: number;
-}
-/**
- * Error thrown when a message is not found (404)
- */
-declare class MessageNotFoundError extends Error {
-    constructor(messageId: string);
-}
-/**
- * Error thrown when a message is not available for processing (409)
- * This can happen when the message is in the wrong state, already claimed, etc.
- */
-declare class MessageNotAvailableError extends Error {
-    constructor(messageId: string, reason?: string);
-}
-/**
- * Error thrown when message data is corrupted or can't be parsed
- */
-declare class MessageCorruptedError extends Error {
-    constructor(messageId: string, reason: string);
-}
-/**
- * Error thrown when there are no messages available in the queue (204)
- */
-declare class QueueEmptyError extends Error {
-    constructor(queueName: string, consumerGroup: string);
-}
-/**
- * Error thrown when a message is temporarily locked (423)
- */
-declare class MessageLockedError extends Error {
-    readonly retryAfter?: number;
-    constructor(messageId: string, retryAfter?: number);
-}
-/**
- * Error thrown when authentication fails (401)
- */
-declare class UnauthorizedError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown when access is forbidden (403)
- */
-declare class ForbiddenError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown for bad requests (400)
- */
-declare class BadRequestError extends Error {
-    constructor(message: string);
-}
-/**
- * Error thrown for internal server errors (500)
- */
-declare class InternalServerError extends Error {
-    constructor(message?: string);
-}
-/**
- * Error thrown when batch limit parameter is invalid
- */
-declare class InvalidLimitError extends Error {
-    constructor(limit: number, min?: number, max?: number);
-}
+import { M as MessageHandler, C as ConsumerGroupOptions, P as PublishOptions, T as Transport } from './types-JvOenjfT.js';
+export { a as BadRequestError, B as BufferTransport, F as ForbiddenError, I as InternalServerError, b as InvalidLimitError, J as JsonTransport, g as Message, c as MessageCorruptedError, h as MessageHandlerResult, d as MessageLockedError, i as MessageMetadata, e as MessageNotAvailableError, f as MessageNotFoundError, j as MessageTimeoutResult, Q as QueueEmptyError, k as SendMessageOptions, l as SendMessageResponse, S as StreamTransport, U as UnauthorizedError } from './types-JvOenjfT.js';
 
 /**
  * Options for the consume method
@@ -408,4 +156,4 @@ declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>
  */
 declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-export { BadRequestError, BufferTransport, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type ParsedCallbackRequest, type PublishOptions, QueueEmptyError, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, type Transport, UnauthorizedError, handleCallback, parseCallback, receive, send };
+export { MessageHandler, type ParsedCallbackRequest, PublishOptions, type ReceiveOptions, type SendOptions, Transport, handleCallback, parseCallback, receive, send };

package/dist/pages.d.mts

@@ -0,0 +1,47 @@
+import { M as MessageHandler } from './types-JvOenjfT.mjs';
+
+type CallbackHandlers = {
+    [topicName: string]: {
+        [consumerGroup: string]: MessageHandler;
+    };
+};
+interface NextApiRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: any;
+    on(event: "data", listener: (chunk: Buffer) => void): void;
+    on(event: "end", listener: () => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+}
+interface NextApiResponse {
+    status(statusCode: number): NextApiResponse;
+    setHeader(name: string, value: string): void;
+    json(data: any): void;
+    send(data: any): void;
+}
+/**
+ * Queue callback handler for Next.js Pages Router
+ *
+ * Automatically extracts queue information from CloudEvent format
+ * and routes to the appropriate handler based on topic and consumer group.
+ *
+ * @param handlers Object with topic-specific handlers organized by consumer groups
+ * @returns A Next.js Pages Router handler function
+ *
+ * @example
+ * ```typescript
+ * // pages/api/queue.ts
+ * import { handleCallback } from "@vercel/queue/pages";
+ *
+ * export default handleCallback({
+ *   "image-processing": {
+ *     "compress": (message, metadata) => console.log("Compressing image", message),
+ *     "resize": (message, metadata) => console.log("Resizing image", message),
+ *   }
+ * });
+ * ```
+ */
+declare function handleCallback(handlers: CallbackHandlers): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+export { handleCallback };