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

package/dist/index.d.ts

@@ -80,8 +80,9 @@ interface QueueClientOptions {
     /**
      * Vercel function OIDC token
      * Can be obtained from x-vercel-oidc-token header in Vercel Serverless Functions
+     * If not provided, will automatically attempt to retrieve from Vercel Function environment
      */
-    token: string;
+    token?: string;
 }
 /**
  * Callback configuration for a consumer group
@@ -100,15 +101,10 @@ interface CallbackConfig {
      */
     frequency?: number;
 }
-interface SendMessageOptions<T = unknown> {
-    /**
-     * The queue name to send the message to
-     */
-    queueName: string;
-    /**
-     * The message payload
-     */
-    payload: T;
+/**
+ * Shared options for publishing messages
+ */
+interface PublishOptions {
     /**
      * Unique key to prevent duplicate message submissions
      * @default random UUID
@@ -122,10 +118,21 @@ interface SendMessageOptions<T = unknown> {
      */
     retentionSeconds?: number;
     /**
-     * Consumer group callback configurations
-     * Format: { consumerGroup: { url, delay?, frequency? } }
+     * 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
      */
-    callbacks?: Record<string, CallbackConfig>;
+    callback?: Record<string, CallbackConfig> | CallbackConfig;
+}
+interface SendMessageOptions<T = unknown> extends PublishOptions {
+    /**
+     * The queue name to send the message to
+     */
+    queueName: string;
+    /**
+     * The message payload
+     */
+    payload: T;
 }
 interface SendMessageResponse {
     /**
@@ -248,10 +255,18 @@ interface MessageTimeoutResult {
  * Result returned by message handlers
  */
 type MessageHandlerResult = void | MessageTimeoutResult;
+/**
+ * Message metadata provided to handlers
+ */
+interface MessageMetadata {
+    messageId: string;
+    deliveryCount: number;
+    timestamp: string;
+}
 /**
  * Message handler function type
  */
-type MessageHandler<T = unknown> = (message: Message<T>) => Promise<MessageHandlerResult> | MessageHandlerResult;
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
 /**
  * Options for creating a ConsumerGroup instance
  */
@@ -300,16 +315,6 @@ interface ReceiveMessageByIdOptions<T = unknown> {
 interface ReceiveMessageByIdResponse<T = unknown, TSkipPayload extends boolean = false> {
     message: TSkipPayload extends true ? Message<void> : Message<T>;
 }
-interface FifoOrderingError {
-    /**
-     * Error message describing the FIFO ordering violation
-     */
-    error: string;
-    /**
-     * The message ID that must be processed first
-     */
-    nextMessageId: string;
-}
 /**
  * Error thrown when a message is not found (404)
  */
@@ -324,11 +329,10 @@ declare class MessageNotAvailableError extends Error {
     constructor(messageId: string, reason?: string);
 }
 /**
- * Error thrown when there's a FIFO ordering violation (409 with nextMessageId)
+ * Error thrown when there's a FIFO ordering violation (409)
  */
 declare class FifoOrderingViolationError extends Error {
-    readonly nextMessageId: string;
-    constructor(messageId: string, nextMessageId: string, reason: string);
+    constructor(messageId: string, reason: string);
 }
 /**
  * Error thrown when message data is corrupted or can't be parsed
@@ -371,8 +375,7 @@ declare class BadRequestError extends Error {
  * Error thrown when there's a failed dependency (424) - FIFO ordering violation in receive by ID
  */
 declare class FailedDependencyError extends Error {
-    readonly nextMessageId: string;
-    constructor(messageId: string, nextMessageId: string);
+    constructor(messageId: string);
 }
 /**
  * Error thrown for internal server errors (500)
@@ -416,19 +419,26 @@ declare class InvalidCallbackError extends Error {
 declare class QueueClient {
     private baseUrl;
     private token;
+    /**
+     * Internal default instance for use by createTopic and other convenience functions
+     * @internal
+     */
+    private static _defaultInstance;
     /**
      * Create a new Vercel Queue Service client
-     * @param options Client configuration options
+     * @param options Client configuration options (optional - will auto-detect Vercel Function environment)
      */
-    constructor(options: QueueClientOptions);
+    constructor(options?: QueueClientOptions);
     /**
-     * Create a QueueClient automatically configured for Vercel Functions
-     * This method automatically retrieves the OIDC token from the Vercel Function environment
-     * Always creates a fresh instance since OIDC tokens expire after 15 minutes
-     * @param baseUrl Optional base URL override
-     * @returns Promise resolving to a new QueueClient instance
+     * Get the default client instance for internal use by convenience functions
+     * @internal
      */
-    static fromVercelFunction(baseUrl?: string): Promise<QueueClient>;
+    static _getDefaultInstance(): QueueClient;
+    /**
+     * Synchronously get OIDC token from environment
+     * Used internally by constructor - mirrors the logic from getVercelOidcToken but synchronously
+     */
+    private getVercelOidcTokenSync;
     /**
      * Send a message to a queue
      * @param options Send message options
@@ -463,7 +473,6 @@ declare class QueueClient {
      * @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 {FifoOrderingViolationError} When FIFO ordering is violated (409 with nextMessageId)
      * @throws {MessageCorruptedError} When message data is corrupted
      * @throws {BadRequestError} When request parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
@@ -502,6 +511,15 @@ declare class QueueClient {
     changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
 }
 
+/**
+ * Options for the consume method
+ */
+interface ConsumeOptions {
+    /** The specific message ID to consume (if not provided, consumes next available message) */
+    messageId?: string;
+    /** Whether to skip downloading the payload (only allowed when messageId is provided) */
+    skipPayload?: boolean;
+}
 /**
  * A ConsumerGroup represents a named group of consumers that process messages from a topic
  */
@@ -546,75 +564,34 @@ declare class ConsumerGroup<T = unknown> {
      */
     private processMessage;
     /**
-     * Start continuous processing of messages from the topic
-     * @param signal AbortSignal to control when to stop processing
-     * @param handler Function to process each message
-     * @param options Processing options
-     * @returns Promise that resolves when processing stops (due to signal or error)
-     */
-    subscribe(signal: AbortSignal, handler: MessageHandler<T>, options?: {
-        pollingInterval?: number;
-    }): Promise<void>;
-    /**
-     * Receive and process a specific message by its ID with full payload
-     * @param messageId The ID of the message to receive and process
-     * @param handler Function to process the message with full payload
-     * @returns Promise that resolves when the message is processed or rejects with specific errors
-     * @throws {MessageNotFoundError} When the message doesn't exist (404)
-     * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
-     * @throws {MessageLockedError} When the message is temporarily locked (423)
-     * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
-     * @throws {FailedDependencyError} When FIFO ordering is violated (424)
-     * @throws {MessageCorruptedError} When the message data is corrupted
-     * @throws {BadRequestError} When request parameters are invalid
-     * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied
-     * @throws {InternalServerError} When server encounters an error
-     */
-    receiveMessage(messageId: string, handler: MessageHandler<T>): Promise<void>;
-    /**
-     * Receive and process the next available message from the queue
+     * Consume the next available message from the queue
      * @param handler Function to process the message
-     * @returns Promise that resolves when the message is processed or rejects with specific errors
-     * @throws {QueueEmptyError} When no messages are available in the queue (204)
-     * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
-     * @throws {BadRequestError} When request parameters are invalid
-     * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied
-     * @throws {InternalServerError} When server encounters an error
+     * @returns Promise that resolves when the message is processed
+     * @throws All the same errors as the underlying client methods
      */
-    receiveNextMessage(handler: MessageHandler<T>): Promise<void>;
+    consume(handler: MessageHandler<T>): Promise<void>;
     /**
-     * Receive and process multiple next available messages from the queue
-     * @param limit Number of messages to process (1-10)
-     * @param handler Function to process each message
-     * @returns Promise that resolves to an array of PromiseSettledResult (same as Promise.allSettled)
-     * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
-     * @throws {QueueEmptyError} When no messages are available in the queue (204)
-     * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
-     * @throws {BadRequestError} When request parameters are invalid
-     * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied
-     * @throws {InternalServerError} When server encounters an error
+     * Consume a specific message by its ID with full payload
+     * @param handler Function to process the message
+     * @param options Consume options with messageId specified
+     * @returns Promise that resolves when the message is processed
+     * @throws All the same errors as the underlying client methods
      */
-    receiveNextMessages(limit: number, handler: MessageHandler<T>): Promise<PromiseSettledResult<void>[]>;
+    consume(handler: MessageHandler<T>, options: {
+        messageId: string;
+        skipPayload?: false | undefined;
+    }): Promise<void>;
     /**
-     * Handle a specific message by its ID without downloading the payload (metadata only)
-     * @param messageId The ID of the message to handle
+     * Consume a specific message by its ID without downloading the payload (metadata only)
      * @param handler Function to process the message metadata (payload will be void)
-     * @returns Promise that resolves when the message is handled or rejects with specific errors
-     * @throws {MessageNotFoundError} When the message doesn't exist (404)
-     * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
-     * @throws {MessageLockedError} When the message is temporarily locked (423)
-     * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
-     * @throws {FailedDependencyError} When FIFO ordering is violated (424)
-     * @throws {MessageCorruptedError} When the message data is corrupted
-     * @throws {BadRequestError} When request parameters are invalid
-     * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied
-     * @throws {InternalServerError} When server encounters an error
+     * @param options Consume options with messageId and skipPayload specified
+     * @returns Promise that resolves when the message is processed
+     * @throws All the same errors as the underlying client methods
      */
-    handleMessage(messageId: string, handler: MessageHandler<void>): Promise<void>;
+    consume(handler: MessageHandler<void>, options: {
+        messageId: string;
+        skipPayload: true;
+    }): Promise<void>;
     /**
      * Get the consumer group name
      */
@@ -649,11 +626,7 @@ declare class Topic<T = unknown> {
      * @throws {ForbiddenError} When access is denied (environment mismatch)
      * @throws {InternalServerError} When server encounters an error
      */
-    publish(payload: T, options?: {
-        idempotencyKey?: string;
-        retentionSeconds?: number;
-        callbacks?: Record<string, CallbackConfig>;
-    }): Promise<{
+    publish(payload: T, options?: PublishOptions): Promise<{
         messageId: string;
     }>;
     /**
@@ -674,13 +647,79 @@ declare class Topic<T = unknown> {
 }
 
 /**
- * Create a new Topic instance
- * @param client QueueClient instance to use for API calls
+ * Create a new Topic instance using the default QueueClient
+ * For custom client configuration, use `new Topic(customClient, topicName, transport)` directly
  * @param topicName Name of the topic
  * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
  * @returns A Topic instance
  */
-declare function createTopic<T = unknown>(client: QueueClient, topicName: string, transport?: Transport<T>): Topic<T>;
+declare function createTopic<T = unknown>(topicName: string, transport?: Transport<T>): Topic<T>;
+/**
+ * Options for the send function
+ */
+interface SendOptions<T = unknown> extends PublishOptions {
+    /**
+     * Serializer/deserializer for the payload
+     * @default JsonTransport instance
+     */
+    transport?: Transport<T>;
+}
+/**
+ * Send a message to a topic (shorthand for topic creation and publishing)
+ * Uses the default QueueClient with automatic OIDC token detection
+ * @param topicName Name of the topic to send to
+ * @param payload The data to send
+ * @param options Optional send options including transport and publish settings
+ * @returns Promise with the message ID
+ * @throws {BadRequestError} When request parameters are invalid
+ * @throws {UnauthorizedError} When authentication fails
+ * @throws {ForbiddenError} When access is denied (environment mismatch)
+ * @throws {InternalServerError} When server encounters an error
+ */
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions<T>): Promise<{
+    messageId: string;
+}>;
+/**
+ * Options for the receive function
+ */
+interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOptions {
+}
+/**
+ * Receive a message from a topic (shorthand for topic and consumer group creation)
+ * Uses the default QueueClient with automatic OIDC token detection
+ * @param topicName Name of the topic to receive from
+ * @param consumerGroup Name of the consumer group
+ * @param handler Function to process the message
+ * @returns Promise that resolves when the message is processed
+ * @throws All the same errors as the underlying client methods
+ */
+declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions<T>): Promise<void>;
+/**
+ * Receive a specific message by its ID with full payload
+ * @param topicName Name of the topic to receive from
+ * @param consumerGroup Name of the consumer group
+ * @param handler Function to process the message
+ * @param options Receive options with messageId specified
+ * @returns Promise that resolves when the message is processed
+ * @throws All the same errors as the underlying client methods
+ */
+declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options: ReceiveOptions<T> & {
+    messageId: string;
+    skipPayload?: false | undefined;
+}): Promise<void>;
+/**
+ * Receive a specific message by its ID without downloading the payload (metadata only)
+ * @param topicName Name of the topic to receive from
+ * @param consumerGroup Name of the consumer group
+ * @param handler Function to process the message metadata (payload will be void)
+ * @param options Receive options with messageId and skipPayload specified
+ * @returns Promise that resolves when the message is processed
+ * @throws All the same errors as the underlying client methods
+ */
+declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<void>, options: ReceiveOptions<T> & {
+    messageId: string;
+    skipPayload: true;
+}): Promise<void>;
 
 /**
  * Queue Callback utilities for handling incoming webhook payloads
@@ -719,7 +758,41 @@ declare function createTopic<T = unknown>(client: QueueClient, topicName: string
  * ```
  */
 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;
+    };
+};
+/**
+ * Simplified queue callback handler for NextJS route handlers
+ *
+ * @param handlers Object with topic-specific handlers
+ * @returns A NextJS route handler function
+ *
+ * @example
+ * ```typescript
+ * // Topic handler (uses 'default' consumer group)
+ * export const POST = handleCallback({
+ *   "new-users": (message, metadata) => {
+ *     console.log(`New user event:`, message, metadata);
+ *   }
+ * });
+ *
+ * // Consumer group specific handlers
+ * export const POST = handleCallback({
+ *   "image-processing": {
+ *     "compress": (message, metadata) => console.log("Compressing image", message),
+ *     "resize": (message, metadata) => console.log("Resizing image", message),
+ *   }
+ * });
+ * ```
+ */
+declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
 
-declare function getVercelOidcToken(): Promise<string>;
-
-export { BadRequestError, BufferTransport, type CallbackConfig, type CallbackMessageOptions, type ChangeVisibilityOptions, type ChangeVisibilityResponse, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, FailedDependencyError, type FifoOrderingError, FifoOrderingViolationError, ForbiddenError, InternalServerError, InvalidCallbackError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type SendMessageOptions, type SendMessageResponse, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, getVercelOidcToken, parseCallbackRequest };
+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 };