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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-BHtRP_i_.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-BHtRP_i_.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';
 
 declare class QueueClient {
     private baseUrl;
@@ -14,10 +14,100 @@ declare class QueueClient {
     private getToken;
     private buildUrl;
     private fetch;
+    /**
+     * 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
+     * @throws {InternalServerError} When server encounters an error
+     */
     sendMessage<T = unknown>(options: SendMessageOptions<T>, transport: Transport<T>): Promise<SendMessageResponse>;
+    /**
+     * 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
+     * @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.
+     *
+     * @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
+     * @throws {InternalServerError} When server encounters an error
+     */
     receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T>, transport: Transport<T>): Promise<ReceiveMessageByIdResponse<T>>;
+    /**
+     * 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
+     * @throws {InternalServerError} When server encounters an error
+     */
     deleteMessage(options: DeleteMessageOptions): Promise<DeleteMessageResponse>;
+    /**
+     * 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
+     * @throws {InternalServerError} When server encounters an error
+     */
     changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
     /**
      * Alternative endpoint for changing message visibility timeout.
@@ -42,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
  */
@@ -79,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
@@ -166,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>;
 }
 
 /**
@@ -193,76 +316,107 @@ interface ConsumeOptions {
 }
 
 /**
- * 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
- * @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;
 }): 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 };

package/dist/index.js

@@ -77,6 +77,12 @@ var JsonTransport = class {
   contentType = "application/json";
   replacer;
   reviver;
+  /**
+   * Create a new JsonTransport.
+   * @param options - Optional JSON serialization options
+   * @param options.replacer - Custom replacer for JSON.stringify
+   * @param options.reviver - Custom reviver for JSON.parse
+   */
   constructor(options = {}) {
     this.replacer = options.replacer;
     this.reviver = options.reviver;
@@ -106,6 +112,10 @@ var StreamTransport = class {
   async deserialize(stream) {
     return stream;
   }
+  /**
+   * Consume any remaining stream data to prevent resource leaks.
+   * Called automatically by ConsumerGroup; manual call required for direct client usage.
+   */
   async finalize(payload) {
     const reader = payload.getReader();
     try {
@@ -156,6 +166,7 @@ var QueueEmptyError = class extends Error {
   }
 };
 var MessageLockedError = class extends Error {
+  /** Suggested retry delay in seconds, if provided by the server. */
   retryAfter;
   constructor(messageId, retryAfter) {
     const retryMessage = retryAfter ? ` Retry after ${retryAfter} seconds.` : " Try again later.";
@@ -201,7 +212,9 @@ var MessageAlreadyProcessedError = class extends Error {
   }
 };
 var ConcurrencyLimitError = class extends Error {
+  /** Current number of in-flight messages for this consumer group. */
   currentInflight;
+  /** Maximum allowed concurrent messages (as configured). */
   maxConcurrency;
   constructor(message = "Concurrency limit exceeded", currentInflight, maxConcurrency) {
     super(message);
@@ -588,6 +601,25 @@ var QueueClient = class {
     }
     return response;
   }
+  /**
+   * 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
+   * @throws {InternalServerError} When server encounters an error
+   */
   async sendMessage(options, transport) {
     const {
       queueName,
@@ -650,6 +682,25 @@ var QueueClient = class {
     const responseData = await response.json();
     return responseData;
   }
+  /**
+   * 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
+   * @throws {InternalServerError} When server encounters an error
+   */
   async *receiveMessages(options, transport) {
     const {
       queueName,
@@ -735,6 +786,26 @@ var QueueClient = class {
       }
     }
   }
+  /**
+   * 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
+   * @throws {InternalServerError} When server encounters an error
+   */
   async receiveMessageById(options, transport) {
     const {
       queueName,
@@ -829,6 +900,21 @@ var QueueClient = class {
     }
     throw new MessageNotFoundError(messageId);
   }
+  /**
+   * 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
+   * @throws {InternalServerError} When server encounters an error
+   */
   async deleteMessage(options) {
     const { queueName, consumerGroup, receiptHandle } = options;
     const headers = new Headers({
@@ -873,6 +959,23 @@ var QueueClient = class {
     }
     return { deleted: true };
   }
+  /**
+   * 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
+   * @throws {InternalServerError} When server encounters an error
+   */
   async changeVisibility(options) {
     const {
       queueName,
@@ -995,36 +1098,26 @@ var ConsumerGroup = class {
   refreshInterval;
   transport;
   /**
-   * Create a new ConsumerGroup instance
-   * @param client QueueClient instance to use for API calls
-   * @param topicName Name of the topic to consume from
-   * @param consumerGroupName Name of the consumer group
-   * @param options Optional configuration
+   * Create a new ConsumerGroup instance.
+   *
+   * @param client - QueueClient instance to use for API calls
+   * @param topicName - Name of the topic to consume from (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroupName - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param options - Optional configuration
+   * @param options.transport - Payload serializer (default: JsonTransport)
+   * @param options.visibilityTimeoutSeconds - Message lock duration (default: 30, max: 3600)
+   * @param options.visibilityRefreshInterval - Lock refresh interval in seconds (default: visibilityTimeout / 3)
    */
   constructor(client, topicName, consumerGroupName, options = {}) {
     this.client = client;
     this.topicName = topicName;
     this.consumerGroupName = consumerGroupName;
-    this.visibilityTimeout = options.visibilityTimeoutSeconds || 30;
-    this.refreshInterval = options.refreshInterval || 10;
+    this.visibilityTimeout = options.visibilityTimeoutSeconds ?? 30;
+    this.refreshInterval = options.visibilityRefreshInterval ?? Math.floor(this.visibilityTimeout / 3);
     this.transport = options.transport || new JsonTransport();
   }
   /**
    * Starts a background loop that periodically extends the visibility timeout for a message.
-   * This prevents the message from becoming visible to other consumers while it's being processed.
-   *
-   * The extension loop runs every `refreshInterval` seconds and updates the message's
-   * visibility timeout to `visibilityTimeout` seconds from the current time.
-   *
-   * @param receiptHandle - The receipt handle that proves ownership of the message
-   * @returns A function that when called will stop the extension loop
-   *
-   * @remarks
-   * - The first extension attempt occurs after `refreshInterval` seconds, not immediately
-   * - If an extension fails, the loop terminates with an error logged to console
-   * - The returned stop function is idempotent - calling it multiple times is safe
-   * - By default, the stop function returns immediately without waiting for in-flight
-   * - Pass `true` to the stop function to wait for any in-flight extension to complete
    */
   startVisibilityExtension(receiptHandle) {
     let isRunning = true;
@@ -1296,7 +1389,7 @@ async function parseCallback(request) {
     messageId
   };
 }
-function createCallbackHandler(handlers, client) {
+function createCallbackHandler(handlers, client, visibilityTimeoutSeconds) {
   for (const topicPattern in handlers) {
     if (topicPattern.includes("*")) {
       if (!validateWildcardPattern(topicPattern)) {
@@ -1332,7 +1425,10 @@ function createCallbackHandler(handlers, client) {
         );
       }
       const topic = new Topic(client, queueName);
-      const cg = topic.consumerGroup(consumerGroup);
+      const cg = topic.consumerGroup(
+        consumerGroup,
+        visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : void 0
+      );
       await cg.consume(consumerGroupHandler, { messageId });
       return Response.json({ status: "success" });
     } catch (error) {
@@ -1348,8 +1444,12 @@ function createCallbackHandler(handlers, client) {
   };
   return routeHandler;
 }
-function handleCallback(handlers, client) {
-  return createCallbackHandler(handlers, client || new QueueClient());
+function handleCallback(handlers, options) {
+  return createCallbackHandler(
+    handlers,
+    options?.client || new QueueClient(),
+    options?.visibilityTimeoutSeconds
+  );
 }
 
 // src/factory.ts
@@ -1412,23 +1512,39 @@ var Client = class {
     });
   }
   /**
-   * 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) {
-    return handleCallback(handlers, this.client);
+  handleCallback(handlers, options) {
+    return handleCallback(handlers, {
+      ...options,
+      client: this.client
+    });
   }
 };
 // Annotate the CommonJS export names for ESM import in node: