@vercel/queue 0.0.0-alpha.33 → 0.0.0-alpha.35

package/dist/index.d.ts

@@ -1,95 +1,123 @@
-import { Q as QueueClientOptions, S as SendMessageOptions, T as Transport, a as SendMessageResponse, R as ReceiveMessagesOptions, M as Message, b as ReceiveMessageByIdOptions, c as ReceiveMessageByIdResponse, D as DeleteMessageOptions, d as DeleteMessageResponse, C as ChangeVisibilityOptions, e as ChangeVisibilityResponse, f as MessageHandler, P as PublishOptions, g as ConsumerGroupOptions } from './types-Dw29Fr9y.js';
-export { i as BadRequestError, B as BufferTransport, F as ForbiddenError, I as InternalServerError, j as InvalidLimitError, J as JsonTransport, k as MessageCorruptedError, p as MessageHandlerResult, l as MessageLockedError, q as MessageMetadata, m as MessageNotAvailableError, n as MessageNotFoundError, r as MessageTimeoutResult, o as QueueEmptyError, h as StreamTransport, U as UnauthorizedError } from './types-Dw29Fr9y.js';
+import { Q as QueueClientOptions, S as SendMessageOptions, T as Transport, a as SendMessageResponse, R as ReceiveMessagesOptions, M as Message, b as ReceiveMessageByIdOptions, c as ReceiveMessageByIdResponse, D as DeleteMessageOptions, d as DeleteMessageResponse, C as ChangeVisibilityOptions, e as ChangeVisibilityResponse, f as MessageHandler, P as PublishOptions, g as ConsumerGroupOptions } from './types-BLG4ASI_.js';
+export { i as BadRequestError, B as BufferTransport, j as ConcurrencyLimitError, k as ConsumerDiscoveryError, l as ConsumerRegistryNotConfiguredError, m as DuplicateMessageError, F as ForbiddenError, I as InternalServerError, n as InvalidLimitError, J as JsonTransport, o as MessageAlreadyProcessedError, p as MessageCorruptedError, q as MessageLockedError, u as MessageMetadata, r as MessageNotAvailableError, s as MessageNotFoundError, t as QueueEmptyError, h as StreamTransport, U as UnauthorizedError } from './types-BLG4ASI_.js';
 
-/**
- * Internal client for interacting with the Vercel Queue Service API
- * Use Client for the public-facing wrapper with send/handleCallback methods
- */
 declare class QueueClient {
     private baseUrl;
     private basePath;
     private customHeaders;
     private providedToken?;
-    /**
-     * Create a new Vercel Queue Service client
-     * @param options QueueClient configuration options
-     */
+    private defaultDeploymentId?;
+    private pinToDeployment;
     constructor(options?: QueueClientOptions);
+    private getSendDeploymentId;
+    private getConsumeDeploymentId;
     private getToken;
-    /**
-     * Internal fetch wrapper that automatically handles debug logging
-     * when VERCEL_QUEUE_DEBUG is enabled
-     */
+    private buildUrl;
     private fetch;
     /**
-     * Send a message to a queue
-     * @param options Send message options
-     * @param transport Serializer/deserializer for the payload
-     * @returns Promise with the message ID
-     * @throws {BadRequestError} When request parameters are invalid
+     * Send a message to a topic.
+     *
+     * @param options - Message options including queue name, payload, and optional settings
+     * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+     * @param options.payload - Message payload
+     * @param options.idempotencyKey - Optional deduplication key (dedup window: min(retention, 24h))
+     * @param options.retentionSeconds - Message TTL (default: 86400, min: 60, max: 86400)
+     * @param options.delaySeconds - Delivery delay (default: 0, max: retentionSeconds)
+     * @param transport - Serializer for the payload
+     * @returns Promise with the generated messageId
+     * @throws {DuplicateMessageError} When idempotency key was already used
+     * @throws {ConsumerDiscoveryError} When consumer discovery fails
+     * @throws {ConsumerRegistryNotConfiguredError} When registry not configured
+     * @throws {BadRequestError} When parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {ForbiddenError} When access is denied
      * @throws {InternalServerError} When server encounters an error
      */
     sendMessage<T = unknown>(options: SendMessageOptions<T>, transport: Transport<T>): Promise<SendMessageResponse>;
     /**
-     * Receive messages from a queue
-     * @param options Receive messages options
-     * @param transport Serializer/deserializer for the payload
-     * @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 messages are temporarily locked (423)
-     * @throws {BadRequestError} When request parameters are invalid
+     * Receive messages from a topic as an async generator.
+     *
+     * @param options - Receive options
+     * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+     * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
+     * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
+     * @param options.limit - Max messages to retrieve (default: 1, min: 1, max: 10)
+     * @param options.maxConcurrency - Max in-flight messages (default: unlimited, min: 1)
+     * @param transport - Deserializer for message payloads
+     * @yields Message objects with payload, messageId, receiptHandle, etc.
+     * @throws {QueueEmptyError} When no messages available
+     * @throws {InvalidLimitError} When limit is outside 1-10 range
+     * @throws {ConcurrencyLimitError} When maxConcurrency exceeded
+     * @throws {BadRequestError} When parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {ForbiddenError} When access is denied
      * @throws {InternalServerError} When server encounters an error
      */
     receiveMessages<T = unknown>(options: ReceiveMessagesOptions<T>, transport: Transport<T>): AsyncGenerator<Message<T>, void, unknown>;
     /**
-     * Receive a specific message by its ID from a queue
-     * @param options Receive message by ID options
-     * @param transport Serializer/deserializer for the payload
-     * @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 {MessageNotAvailableError} When message exists but isn't available (409)
-     * @throws {MessageCorruptedError} When message data is corrupted
-     * @throws {BadRequestError} When request parameters are invalid
+     * Receive a specific message by its ID.
+     *
+     * @param options - Receive options
+     * @param options.queueName - Topic name (pattern: `[A-Za-z0-9_-]+`)
+     * @param options.consumerGroup - Consumer group name (pattern: `[A-Za-z0-9_-]+`)
+     * @param options.messageId - Message ID to retrieve
+     * @param options.visibilityTimeoutSeconds - Lock duration (default: 30, min: 0, max: 3600)
+     * @param options.maxConcurrency - Max in-flight messages (default: unlimited, min: 1)
+     * @param transport - Deserializer for the message payload
+     * @returns Promise with the message
+     * @throws {MessageNotFoundError} When message doesn't exist
+     * @throws {MessageNotAvailableError} When message is in wrong state or was a duplicate
+     * @throws {MessageAlreadyProcessedError} When message was already processed
+     * @throws {ConcurrencyLimitError} When maxConcurrency exceeded
+     * @throws {BadRequestError} When parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {ForbiddenError} When access is denied
      * @throws {InternalServerError} When server encounters an error
      */
-    receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T> & {
-        skipPayload: true;
-    }, transport?: Transport<T>): Promise<ReceiveMessageByIdResponse<T, true>>;
-    receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T> & {
-        skipPayload?: false | undefined;
-    }, transport: Transport<T>): Promise<ReceiveMessageByIdResponse<T, false>>;
+    receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T>, transport: Transport<T>): Promise<ReceiveMessageByIdResponse<T>>;
     /**
-     * Delete a message (acknowledge processing)
-     * @param options Delete message options
-     * @returns Promise with delete status
-     * @throws {MessageNotFoundError} When the message doesn't exist (404)
-     * @throws {MessageNotAvailableError} When message can't be deleted (409)
-     * @throws {BadRequestError} When ticket is missing or invalid (400)
+     * Delete (acknowledge) a message after successful processing.
+     *
+     * @param options - Delete options
+     * @param options.queueName - Topic name
+     * @param options.consumerGroup - Consumer group name
+     * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
+     * @returns Promise indicating deletion success
+     * @throws {MessageNotFoundError} When receipt handle not found
+     * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
+     * @throws {BadRequestError} When parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {ForbiddenError} When access is denied
      * @throws {InternalServerError} When server encounters an error
      */
     deleteMessage(options: DeleteMessageOptions): Promise<DeleteMessageResponse>;
     /**
-     * Change the visibility timeout of a message
-     * @param options Change visibility options
-     * @returns Promise with update status
-     * @throws {MessageNotFoundError} When the message doesn't exist (404)
-     * @throws {MessageNotAvailableError} When message can't be updated (409)
-     * @throws {BadRequestError} When ticket is missing or visibility timeout invalid (400)
+     * Extend or change the visibility timeout of a message.
+     * Used to prevent message redelivery while still processing.
+     *
+     * @param options - Visibility options
+     * @param options.queueName - Topic name
+     * @param options.consumerGroup - Consumer group name
+     * @param options.receiptHandle - Receipt handle from the received message (must use same deployment ID as receive)
+     * @param options.visibilityTimeoutSeconds - New timeout (min: 0, max: 3600, cannot exceed message expiration)
+     * @returns Promise indicating success
+     * @throws {MessageNotFoundError} When receipt handle not found
+     * @throws {MessageNotAvailableError} When receipt handle invalid or message already processed
+     * @throws {BadRequestError} When parameters are invalid
      * @throws {UnauthorizedError} When authentication fails
-     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {ForbiddenError} When access is denied
      * @throws {InternalServerError} When server encounters an error
      */
     changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
+    /**
+     * Alternative endpoint for changing message visibility timeout.
+     * Uses the /visibility path suffix and expects visibilityTimeoutSeconds in the body.
+     * Functionally equivalent to changeVisibility but follows an alternative API pattern.
+     *
+     * @param options - Options for changing visibility
+     * @returns Promise resolving to change visibility response
+     */
+    changeVisibilityAlt(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
 }
 
 /**
@@ -104,6 +132,24 @@ type CallbackHandlers = {
         [consumerGroup: string]: MessageHandler;
     };
 };
+/**
+ * Options for handleCallback.
+ */
+interface HandleCallbackOptions {
+    /**
+     * QueueClient instance to use for processing messages.
+     * If not provided, a default client is created with OIDC authentication.
+     */
+    client?: QueueClient;
+    /**
+     * Time in seconds that messages will be invisible to other consumers during processing.
+     * The handler will automatically extend this timeout while processing.
+     * @default 30
+     * @minimum 0
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+}
 /**
  * Parsed callback request information
  */
@@ -141,39 +187,41 @@ type ParsedCallbackRequest = {
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 /**
- * Simplified queue callback handler for Next.js route handlers
+ * Simplified queue callback handler for Next.js route handlers.
  *
  * 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
- * @param client Optional QueueClient instance to use. If not provided, a default client is created.
+ * @param handlers - Object with topic-specific handlers organized by consumer groups
+ * @param options - Optional configuration
+ * @param options.client - QueueClient instance (default: new client with OIDC auth)
+ * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
  * @returns A Next.js route handler function
  *
  * @example
  * ```typescript
- * // Single topic with multiple consumer groups
+ * // Basic usage
  * export const POST = handleCallback({
  *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing image", message),
- *     "resize": (message, metadata) => console.log("Resizing image", message),
+ *     "compress": (message, metadata) => console.log("Compressing", message),
+ *     "resize": (message, metadata) => console.log("Resizing", message),
  *   }
  * });
  *
- * // Multiple topics with consumer groups
+ * // With custom visibility timeout for long-running handlers
  * export const POST = handleCallback({
- *   "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),
+ *   "video-processing": {
+ *     "transcode": async (video, metadata) => {
+ *       // Long-running transcoding operation
+ *       await transcodeVideo(video);
+ *     },
  *   }
+ * }, {
+ *   visibilityTimeoutSeconds: 300,  // 5 minutes
  * });
  * ```
  */
-declare function handleCallback(handlers: CallbackHandlers, client?: QueueClient): (request: Request) => Promise<Response>;
+declare function handleCallback(handlers: CallbackHandlers, options?: HandleCallbackOptions): (request: Request) => Promise<Response>;
 
 /**
  * Client - User-facing wrapper for the Vercel Queue Service
@@ -228,22 +276,35 @@ declare class Client {
         messageId: string;
     }>;
     /**
-     * Create a callback handler for processing queue messages
-     * Returns a Next.js route handler function that routes messages to appropriate handlers
-     * @param handlers Object with topic-specific handlers organized by consumer groups
+     * Create a callback handler for processing queue messages.
+     * Returns a Next.js route handler function that routes messages to appropriate handlers.
+     *
+     * @param handlers - Object with topic-specific handlers organized by consumer groups
+     * @param options - Optional configuration
+     * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
      * @returns A Next.js route handler function
      *
      * @example
      * ```typescript
+     * // Basic usage
      * export const POST = client.handleCallback({
      *   "user-events": {
      *     "welcome": (user, metadata) => console.log("Welcoming user", user),
      *     "analytics": (user, metadata) => console.log("Tracking user", user),
      *   },
      * });
+     *
+     * // With custom visibility timeout
+     * export const POST = client.handleCallback({
+     *   "video-processing": {
+     *     "transcode": async (video) => await transcodeVideo(video),
+     *   },
+     * }, {
+     *   visibilityTimeoutSeconds: 300,  // 5 minutes for long operations
+     * });
      * ```
      */
-    handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
+    handleCallback(handlers: CallbackHandlers, options?: Omit<HandleCallbackOptions, "client">): (request: Request) => Promise<Response>;
 }
 
 /**
@@ -252,95 +313,110 @@ declare class Client {
 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;
 }
 
 /**
- * Options for the send function
+ * Options for the send function.
  */
 interface SendOptions<T = unknown> extends PublishOptions {
     /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
+     * Serializer for the payload.
+     * @default JsonTransport
      */
     transport?: Transport<T>;
     /**
-     * QueueClient instance to use for sending the message
-     * If not provided, a default client is created
+     * QueueClient instance to use for sending the message.
+     * If not provided, a default client is created with OIDC authentication.
      */
     client?: QueueClient;
 }
 /**
- * Send a message to a topic (shorthand for topic creation and publishing)
- * Uses the default QueueClient with automatic OIDC token detection, or a provided client
- * @param topicName Name of the topic to send to
- * @param payload The data to send
- * @param options Optional send options including transport, publish settings, and client
- * @returns Promise with the message ID
- * @throws {BadRequestError} When request parameters are invalid
+ * Send a message to a topic.
+ *
+ * Uses the default QueueClient with automatic OIDC token detection, or a provided client.
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param payload - The data to send
+ * @param options - Optional send options
+ * @param options.idempotencyKey - Deduplication key (dedup window: min(retention, 24h))
+ * @param options.retentionSeconds - Message TTL (default: 86400, min: 60, max: 86400)
+ * @param options.delaySeconds - Delivery delay (default: 0, max: retentionSeconds)
+ * @param options.transport - Payload serializer (default: JsonTransport)
+ * @param options.client - Custom QueueClient instance
+ * @returns Promise with the generated messageId
+ * @throws {DuplicateMessageError} When idempotency key was already used
+ * @throws {BadRequestError} When parameters are invalid
  * @throws {UnauthorizedError} When authentication fails
- * @throws {ForbiddenError} When access is denied (environment mismatch)
+ * @throws {ForbiddenError} When access is denied
  * @throws {InternalServerError} When server encounters an error
  *
  * @example
  * ```typescript
- * // Using default client (OIDC token)
+ * // Basic usage (OIDC auth)
  * await send("my-topic", { hello: "world" });
  *
+ * // With options
+ * await send("my-topic", payload, {
+ *   idempotencyKey: "unique-key",
+ *   retentionSeconds: 3600,      // 1 hour TTL
+ *   delaySeconds: 60,            // Delay 1 minute
+ * });
+ *
  * // Using custom client
  * const client = new QueueClient({ token: "my-token" });
- * await send("my-topic", { hello: "world" }, { client });
+ * await send("my-topic", payload, { client });
  * ```
  */
 declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions<T>): Promise<{
     messageId: string;
 }>;
 /**
- * Options for the receive function
+ * Options for the receive function.
  */
 interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOptions {
     /**
-     * QueueClient instance to use for receiving the message
-     * If not provided, a default client is created
+     * QueueClient instance to use for receiving the message.
+     * If not provided, a default client is created with OIDC authentication.
      */
     client?: QueueClient;
 }
 /**
- * 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
+ * Receive a message from a topic.
+ *
+ * Shorthand for creating a topic and consumer group. The message is automatically:
+ * - Locked with the configured visibility timeout
+ * - Kept alive via periodic visibility extensions during processing
+ * - Deleted upon successful handler completion
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Optional receive options
+ * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
+ * @param options.visibilityRefreshInterval - Lock refresh interval (default: visibilityTimeout / 3)
+ * @param options.transport - Payload deserializer (default: JsonTransport)
+ * @returns Promise that resolves when the message is processed and deleted
+ * @throws {QueueEmptyError} When no messages available
+ * @throws {ConcurrencyLimitError} When maxConcurrency exceeded
  */
 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
+ * Receive a specific message by its ID.
+ *
+ * Used for targeted message processing, typically from webhook callbacks.
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Receive options with messageId
+ * @param options.messageId - Specific message ID to consume
+ * @returns Promise that resolves when the message is processed and deleted
+ * @throws {MessageNotFoundError} When message doesn't exist
+ * @throws {MessageNotAvailableError} When message in wrong state
+ * @throws {MessageAlreadyProcessedError} When already processed
  */
 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>;
 
-export { type CallbackHandlers, Client, Message, MessageHandler, type ParsedCallbackRequest, PublishOptions, QueueClientOptions, type ReceiveOptions, SendMessageOptions, SendMessageResponse, type SendOptions, Transport, handleCallback, parseCallback, receive, send };
+export { type CallbackHandlers, Client, type HandleCallbackOptions, Message, MessageHandler, type ParsedCallbackRequest, PublishOptions, QueueClientOptions, type ReceiveOptions, SendMessageOptions, SendMessageResponse, type SendOptions, Transport, handleCallback, parseCallback, receive, send };