@vercel/queue 0.0.0-alpha.5 → 0.0.0-alpha.6

package/dist/index.d.mts

@@ -84,23 +84,6 @@ interface QueueClientOptions {
      */
     token?: string;
 }
-/**
- * Callback configuration for a consumer group
- */
-interface CallbackConfig {
-    /**
-     * Webhook URL to notify when messages are available
-     */
-    url: string;
-    /**
-     * Delay in seconds before sending the first callback
-     */
-    delay?: number;
-    /**
-     * Delay in seconds between retry attempts when the callback fails
-     */
-    frequency?: number;
-}
 /**
  * Shared options for publishing messages
  */
@@ -117,12 +100,6 @@ interface PublishOptions {
      * @max 86400
      */
     retentionSeconds?: number;
-    /**
-     * Callback configuration
-     * - If a single CallbackConfig is provided, it will use the "default" consumer group
-     * - If an object is provided, keys are consumer group names with their respective callback configs
-     */
-    callback?: Record<string, CallbackConfig> | CallbackConfig;
 }
 interface SendMessageOptions<T = unknown> extends PublishOptions {
     /**
@@ -186,7 +163,6 @@ interface ReceiveMessagesOptions<T = unknown> {
      * Maximum number of messages to retrieve
      * @default 10
      * @max 10
-     * @note FIFO queues must use limit=1
      */
     limit?: number;
 }
@@ -328,12 +304,6 @@ declare class MessageNotFoundError extends Error {
 declare class MessageNotAvailableError extends Error {
     constructor(messageId: string, reason?: string);
 }
-/**
- * Error thrown when there's a FIFO ordering violation (409)
- */
-declare class FifoOrderingViolationError extends Error {
-    constructor(messageId: string, reason: string);
-}
 /**
  * Error thrown when message data is corrupted or can't be parsed
  */
@@ -347,7 +317,7 @@ declare class QueueEmptyError extends Error {
     constructor(queueName: string, consumerGroup: string);
 }
 /**
- * Error thrown when a message is temporarily locked in a FIFO queue (423)
+ * Error thrown when a message is temporarily locked (423)
  */
 declare class MessageLockedError extends Error {
     readonly retryAfter?: number;
@@ -371,12 +341,6 @@ declare class ForbiddenError extends Error {
 declare class BadRequestError extends Error {
     constructor(message: string);
 }
-/**
- * Error thrown when there's a failed dependency (424) - FIFO ordering violation in receive by ID
- */
-declare class FailedDependencyError extends Error {
-    constructor(messageId: string);
-}
 /**
  * Error thrown for internal server errors (500)
  */
@@ -389,29 +353,6 @@ declare class InternalServerError extends Error {
 declare class InvalidLimitError extends Error {
     constructor(limit: number, min?: number, max?: number);
 }
-/**
- * Options extracted from a queue callback request
- */
-interface CallbackMessageOptions {
-    /**
-     * The queue name extracted from Vqs-Queue-Name header
-     */
-    queueName: string;
-    /**
-     * The consumer group extracted from Vqs-Consumer-Group header
-     */
-    consumerGroup: string;
-    /**
-     * The message ID extracted from Vqs-Message-Id header
-     */
-    messageId: string;
-}
-/**
- * Error thrown when queue callback headers are missing or invalid
- */
-declare class InvalidCallbackError extends Error {
-    constructor(message: string);
-}
 
 /**
  * Client for interacting with the Vercel Queue Service API
@@ -457,7 +398,7 @@ declare class QueueClient {
      * @returns AsyncGenerator that yields messages as they arrive
      * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
      * @throws {QueueEmptyError} When no messages are available (204)
-     * @throws {MessageLockedError} When FIFO queue has locked messages (423)
+     * @throws {MessageLockedError} When messages are temporarily locked (423)
      * @throws {BadRequestError} When request parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
      * @throws {ForbiddenError} When access is denied (environment mismatch)
@@ -471,7 +412,6 @@ declare class QueueClient {
      * @returns Promise with the message or null if not found/available
      * @throws {MessageNotFoundError} When the message doesn't exist (404)
      * @throws {MessageLockedError} When the message is temporarily locked (423)
-     * @throws {FailedDependencyError} When FIFO ordering is violated (424)
      * @throws {MessageNotAvailableError} When message exists but isn't available (409)
      * @throws {MessageCorruptedError} When message data is corrupted
      * @throws {BadRequestError} When request parameters are invalid
@@ -722,77 +662,85 @@ declare function receive<T = unknown>(topicName: string, consumerGroup: string,
 }): Promise<void>;
 
 /**
- * Queue Callback utilities for handling incoming webhook payloads
+ * Queue Callback utilities for handling incoming webhook payloads from Vercel triggers
  */
 
 /**
- * Parse a queue callback request and extract the required information for receiveMessageById
+ * Configuration object with handlers for different topics and consumer groups
+ */
+type CallbackHandlers = {
+    [topicName: string]: {
+        [consumerGroup: string]: MessageHandler;
+    };
+};
+/**
+ * Parsed callback request information
+ */
+type ParsedCallbackRequest = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+};
+/**
+ * Parse and validate callback request headers
  *
- * @param request The incoming Request object from the queue callback
- * @returns CallbackMessageOptions that can be used with receiveMessageById
- * @throws {InvalidCallbackError} When required queue headers are missing or invalid
+ * Extracts queue information from Vercel-provided headers and validates
+ * that all required headers are present.
+ *
+ * @param request The incoming webhook request
+ * @returns Parsed queue information
+ * @throws Error if required headers are missing
  *
  * @example
  * ```typescript
- * import { parseCallbackRequest } from '@vercel/queue';
- *
- * // In your webhook handler
+ * // In Next.js API route
  * export async function POST(request: Request) {
  *   try {
- *     const callbackOptions = parseCallbackRequest(request);
+ *     const { queueName, consumerGroup, messageId } = parseCallbackRequest(request);
  *
- *     // Use with receiveMessageById
- *     const message = await client.receiveMessageById({
- *       ...callbackOptions,
- *       visibilityTimeoutSeconds: 30
- *     }, transport);
+ *     // Use the parsed information...
+ *     await myWorkflow.handleWebhook(queueName, consumerGroup, messageId);
  *
- *     // Process the message...
+ *     return Response.json({ status: "success" });
  *   } catch (error) {
- *     if (error instanceof InvalidCallbackError) {
- *       return new Response('Invalid callback', { status: 400 });
- *     }
- *     throw error;
+ *     return Response.json({ error: error.message }, { status: 400 });
  *   }
  * }
  * ```
  */
-declare function parseCallbackRequest(request: Request): CallbackMessageOptions;
-/**
- * Configuration object with handlers for different topics
- * Each topic can have either:
- * - A single handler function (uses 'default' consumer group)
- * - An object with handlers for specific consumer groups
- */
-type CallbackHandlers = {
-    [topicName: string]: MessageHandler | {
-        [consumerGroup: string]: MessageHandler;
-    };
-};
+declare function parseCallbackRequest(request: Request): ParsedCallbackRequest;
 /**
- * Simplified queue callback handler for NextJS route handlers
+ * Simplified queue callback handler for Next.js route handlers
  *
- * @param handlers Object with topic-specific handlers
- * @returns A NextJS route handler function
+ * Automatically extracts queue information from Vercel-provided headers
+ * 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 route handler function
  *
  * @example
  * ```typescript
- * // Topic handler (uses 'default' consumer group)
+ * // Single topic with multiple consumer groups
  * export const POST = handleCallback({
- *   "new-users": (message, metadata) => {
- *     console.log(`New user event:`, message, metadata);
+ *   "image-processing": {
+ *     "compress": (message, metadata) => console.log("Compressing image", message),
+ *     "resize": (message, metadata) => console.log("Resizing image", message),
  *   }
  * });
  *
- * // Consumer group specific handlers
+ * // Multiple topics with consumer groups
  * export const POST = handleCallback({
- *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing image", message),
- *     "resize": (message, metadata) => console.log("Resizing image", message),
+ *   "user-events": {
+ *     "welcome": (user, metadata) => console.log("Welcoming user", user),
+ *     "analytics": (user, metadata) => console.log("Tracking user", user),
+ *   },
+ *   "order-events": {
+ *     "fulfillment": (order, metadata) => console.log("Fulfilling order", order),
+ *     "notifications": (order, metadata) => console.log("Notifying order", order),
  *   }
  * });
  * ```
  */
 declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-export { BadRequestError, BufferTransport, type CallbackConfig, type CallbackMessageOptions, type ChangeVisibilityOptions, type ChangeVisibilityResponse, type ConsumeOptions, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, FailedDependencyError, FifoOrderingViolationError, ForbiddenError, InternalServerError, InvalidCallbackError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type PublishOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, handleCallback, parseCallbackRequest, receive, send };
+export { BadRequestError, BufferTransport, type ChangeVisibilityOptions, type ChangeVisibilityResponse, type ConsumeOptions, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type ParsedCallbackRequest, type PublishOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, handleCallback, parseCallbackRequest, receive, send };

package/dist/index.d.ts

@@ -84,23 +84,6 @@ interface QueueClientOptions {
      */
     token?: string;
 }
-/**
- * Callback configuration for a consumer group
- */
-interface CallbackConfig {
-    /**
-     * Webhook URL to notify when messages are available
-     */
-    url: string;
-    /**
-     * Delay in seconds before sending the first callback
-     */
-    delay?: number;
-    /**
-     * Delay in seconds between retry attempts when the callback fails
-     */
-    frequency?: number;
-}
 /**
  * Shared options for publishing messages
  */
@@ -117,12 +100,6 @@ interface PublishOptions {
      * @max 86400
      */
     retentionSeconds?: number;
-    /**
-     * Callback configuration
-     * - If a single CallbackConfig is provided, it will use the "default" consumer group
-     * - If an object is provided, keys are consumer group names with their respective callback configs
-     */
-    callback?: Record<string, CallbackConfig> | CallbackConfig;
 }
 interface SendMessageOptions<T = unknown> extends PublishOptions {
     /**
@@ -186,7 +163,6 @@ interface ReceiveMessagesOptions<T = unknown> {
      * Maximum number of messages to retrieve
      * @default 10
      * @max 10
-     * @note FIFO queues must use limit=1
      */
     limit?: number;
 }
@@ -328,12 +304,6 @@ declare class MessageNotFoundError extends Error {
 declare class MessageNotAvailableError extends Error {
     constructor(messageId: string, reason?: string);
 }
-/**
- * Error thrown when there's a FIFO ordering violation (409)
- */
-declare class FifoOrderingViolationError extends Error {
-    constructor(messageId: string, reason: string);
-}
 /**
  * Error thrown when message data is corrupted or can't be parsed
  */
@@ -347,7 +317,7 @@ declare class QueueEmptyError extends Error {
     constructor(queueName: string, consumerGroup: string);
 }
 /**
- * Error thrown when a message is temporarily locked in a FIFO queue (423)
+ * Error thrown when a message is temporarily locked (423)
  */
 declare class MessageLockedError extends Error {
     readonly retryAfter?: number;
@@ -371,12 +341,6 @@ declare class ForbiddenError extends Error {
 declare class BadRequestError extends Error {
     constructor(message: string);
 }
-/**
- * Error thrown when there's a failed dependency (424) - FIFO ordering violation in receive by ID
- */
-declare class FailedDependencyError extends Error {
-    constructor(messageId: string);
-}
 /**
  * Error thrown for internal server errors (500)
  */
@@ -389,29 +353,6 @@ declare class InternalServerError extends Error {
 declare class InvalidLimitError extends Error {
     constructor(limit: number, min?: number, max?: number);
 }
-/**
- * Options extracted from a queue callback request
- */
-interface CallbackMessageOptions {
-    /**
-     * The queue name extracted from Vqs-Queue-Name header
-     */
-    queueName: string;
-    /**
-     * The consumer group extracted from Vqs-Consumer-Group header
-     */
-    consumerGroup: string;
-    /**
-     * The message ID extracted from Vqs-Message-Id header
-     */
-    messageId: string;
-}
-/**
- * Error thrown when queue callback headers are missing or invalid
- */
-declare class InvalidCallbackError extends Error {
-    constructor(message: string);
-}
 
 /**
  * Client for interacting with the Vercel Queue Service API
@@ -457,7 +398,7 @@ declare class QueueClient {
      * @returns AsyncGenerator that yields messages as they arrive
      * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
      * @throws {QueueEmptyError} When no messages are available (204)
-     * @throws {MessageLockedError} When FIFO queue has locked messages (423)
+     * @throws {MessageLockedError} When messages are temporarily locked (423)
      * @throws {BadRequestError} When request parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
      * @throws {ForbiddenError} When access is denied (environment mismatch)
@@ -471,7 +412,6 @@ declare class QueueClient {
      * @returns Promise with the message or null if not found/available
      * @throws {MessageNotFoundError} When the message doesn't exist (404)
      * @throws {MessageLockedError} When the message is temporarily locked (423)
-     * @throws {FailedDependencyError} When FIFO ordering is violated (424)
      * @throws {MessageNotAvailableError} When message exists but isn't available (409)
      * @throws {MessageCorruptedError} When message data is corrupted
      * @throws {BadRequestError} When request parameters are invalid
@@ -722,77 +662,85 @@ declare function receive<T = unknown>(topicName: string, consumerGroup: string,
 }): Promise<void>;
 
 /**
- * Queue Callback utilities for handling incoming webhook payloads
+ * Queue Callback utilities for handling incoming webhook payloads from Vercel triggers
  */
 
 /**
- * Parse a queue callback request and extract the required information for receiveMessageById
+ * Configuration object with handlers for different topics and consumer groups
+ */
+type CallbackHandlers = {
+    [topicName: string]: {
+        [consumerGroup: string]: MessageHandler;
+    };
+};
+/**
+ * Parsed callback request information
+ */
+type ParsedCallbackRequest = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+};
+/**
+ * Parse and validate callback request headers
  *
- * @param request The incoming Request object from the queue callback
- * @returns CallbackMessageOptions that can be used with receiveMessageById
- * @throws {InvalidCallbackError} When required queue headers are missing or invalid
+ * Extracts queue information from Vercel-provided headers and validates
+ * that all required headers are present.
+ *
+ * @param request The incoming webhook request
+ * @returns Parsed queue information
+ * @throws Error if required headers are missing
  *
  * @example
  * ```typescript
- * import { parseCallbackRequest } from '@vercel/queue';
- *
- * // In your webhook handler
+ * // In Next.js API route
  * export async function POST(request: Request) {
  *   try {
- *     const callbackOptions = parseCallbackRequest(request);
+ *     const { queueName, consumerGroup, messageId } = parseCallbackRequest(request);
  *
- *     // Use with receiveMessageById
- *     const message = await client.receiveMessageById({
- *       ...callbackOptions,
- *       visibilityTimeoutSeconds: 30
- *     }, transport);
+ *     // Use the parsed information...
+ *     await myWorkflow.handleWebhook(queueName, consumerGroup, messageId);
  *
- *     // Process the message...
+ *     return Response.json({ status: "success" });
  *   } catch (error) {
- *     if (error instanceof InvalidCallbackError) {
- *       return new Response('Invalid callback', { status: 400 });
- *     }
- *     throw error;
+ *     return Response.json({ error: error.message }, { status: 400 });
  *   }
  * }
  * ```
  */
-declare function parseCallbackRequest(request: Request): CallbackMessageOptions;
-/**
- * Configuration object with handlers for different topics
- * Each topic can have either:
- * - A single handler function (uses 'default' consumer group)
- * - An object with handlers for specific consumer groups
- */
-type CallbackHandlers = {
-    [topicName: string]: MessageHandler | {
-        [consumerGroup: string]: MessageHandler;
-    };
-};
+declare function parseCallbackRequest(request: Request): ParsedCallbackRequest;
 /**
- * Simplified queue callback handler for NextJS route handlers
+ * Simplified queue callback handler for Next.js route handlers
  *
- * @param handlers Object with topic-specific handlers
- * @returns A NextJS route handler function
+ * Automatically extracts queue information from Vercel-provided headers
+ * 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 route handler function
  *
  * @example
  * ```typescript
- * // Topic handler (uses 'default' consumer group)
+ * // Single topic with multiple consumer groups
  * export const POST = handleCallback({
- *   "new-users": (message, metadata) => {
- *     console.log(`New user event:`, message, metadata);
+ *   "image-processing": {
+ *     "compress": (message, metadata) => console.log("Compressing image", message),
+ *     "resize": (message, metadata) => console.log("Resizing image", message),
  *   }
  * });
  *
- * // Consumer group specific handlers
+ * // Multiple topics with consumer groups
  * export const POST = handleCallback({
- *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing image", message),
- *     "resize": (message, metadata) => console.log("Resizing image", message),
+ *   "user-events": {
+ *     "welcome": (user, metadata) => console.log("Welcoming user", user),
+ *     "analytics": (user, metadata) => console.log("Tracking user", user),
+ *   },
+ *   "order-events": {
+ *     "fulfillment": (order, metadata) => console.log("Fulfilling order", order),
+ *     "notifications": (order, metadata) => console.log("Notifying order", order),
  *   }
  * });
  * ```
  */
 declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-export { BadRequestError, BufferTransport, type CallbackConfig, type CallbackMessageOptions, type ChangeVisibilityOptions, type ChangeVisibilityResponse, type ConsumeOptions, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, FailedDependencyError, FifoOrderingViolationError, ForbiddenError, InternalServerError, InvalidCallbackError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type PublishOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, handleCallback, parseCallbackRequest, receive, send };
+export { BadRequestError, BufferTransport, type ChangeVisibilityOptions, type ChangeVisibilityResponse, type ConsumeOptions, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type ParsedCallbackRequest, type PublishOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, handleCallback, parseCallbackRequest, receive, send };