@vercel/queue 0.0.0-alpha.37 → 0.0.0-alpha.39

package/dist/index.d.ts

@@ -1,328 +1,34 @@
-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-CAA8nT8x.js';
-export { i as BadRequestError, B as BufferTransport, j as ConsumerDiscoveryError, k as ConsumerRegistryNotConfiguredError, l as DuplicateMessageError, F as ForbiddenError, I as InternalServerError, m as InvalidLimitError, J as JsonTransport, n as MessageAlreadyProcessedError, o as MessageCorruptedError, p as MessageLockedError, t as MessageMetadata, q as MessageNotAvailableError, r as MessageNotFoundError, s as QueueEmptyError, h as StreamTransport, U as UnauthorizedError } from './types-CAA8nT8x.js';
+import { M as MessageHandler, C as ConsumerGroupOptions, Q as QueueClient, P as PublishOptions } from './callback-lq_sorrn.js';
+export { g as BadRequestError, B as BufferTransport, a as CLOUD_EVENT_TYPE_V1BETA, b as CLOUD_EVENT_TYPE_V2BETA, i as ConsumerDiscoveryError, j as ConsumerRegistryNotConfiguredError, D as DuplicateMessageError, F as ForbiddenError, H as HandleCallbackOptions, I as InternalServerError, k as InvalidLimitError, J as JsonTransport, s as Message, l as MessageAlreadyProcessedError, m as MessageCorruptedError, n as MessageLockedError, t as MessageMetadata, o as MessageNotAvailableError, q as MessageNotFoundError, d as ParsedCallbackRequest, e as ParsedCallbackV1, f as ParsedCallbackV2, u as QueueClientOptions, r as QueueEmptyError, v as SendMessageOptions, w as SendMessageResponse, S as StreamTransport, T as Transport, U as UnauthorizedError, h as handleCallback, p as parseCallback, c as parseRawCallback } from './callback-lq_sorrn.js';
 
-declare class QueueClient {
-    private baseUrl;
-    private basePath;
-    private customHeaders;
-    private providedToken?;
-    private defaultDeploymentId?;
-    private pinToDeployment;
-    constructor(options?: QueueClientOptions);
-    private getSendDeploymentId;
-    private getConsumeDeploymentId;
-    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 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 {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 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 {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.
-     * 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>;
-}
-
-/**
- * Queue Callback utilities for handling incoming webhook payloads from Vercel triggers
- */
-
-/**
- * Configuration object with handlers for different topics and consumer groups
- */
-type CallbackHandlers = {
-    [topicName: string]: {
-        [consumerGroup: string]: MessageHandler;
-    };
-};
 /**
- * Options for handleCallback.
+ * Options for consuming a specific message by ID.
  */
-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
- */
-type ParsedCallbackRequest = {
-    queueName: string;
-    consumerGroup: string;
+interface ConsumeByIdOptions {
+    /** The specific message ID to consume */
     messageId: string;
-};
-/**
- * Parse and validate callback request using CloudEvent specification
- *
- * Extracts queue information from CloudEvent format and validates
- * that all required fields are present.
- *
- * @param request The incoming webhook request
- * @returns Parsed queue information
- * @throws Error if required fields are missing
- *
- * @example
- * ```typescript
- * // In Next.js API route
- * export async function POST(request: Request) {
- *   try {
- *     const { queueName, consumerGroup, messageId } = parseCallback(request);
- *
- *     // Use the parsed information...
- *     await myWorkflow.handleWebhook(queueName, consumerGroup, messageId);
- *
- *     return Response.json({ status: "success" });
- *   } catch (error) {
- *     return Response.json({ error: error.message }, { status: 400 });
- *   }
- * }
- * ```
- */
-declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
-/**
- * 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 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
- * // Basic usage
- * export const POST = handleCallback({
- *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing", message),
- *     "resize": (message, metadata) => console.log("Resizing", message),
- *   }
- * });
- *
- * // With custom visibility timeout for long-running handlers
- * export const POST = handleCallback({
- *   "video-processing": {
- *     "transcode": async (video, metadata) => {
- *       // Long-running transcoding operation
- *       await transcodeVideo(video);
- *     },
- *   }
- * }, {
- *   visibilityTimeoutSeconds: 300,  // 5 minutes
- * });
- * ```
- */
-declare function handleCallback(handlers: CallbackHandlers, options?: HandleCallbackOptions): (request: Request) => Promise<Response>;
-
+}
 /**
- * Client - User-facing wrapper for the Vercel Queue Service
- *
- * This provides a simple interface with send() and handleCallback() methods
- * while delegating to the internal QueueClient and factory functions.
+ * Options for consuming messages from the queue.
  */
-
-/**
- * Client provides a simple interface to the Vercel Queue Service.
- *
- * @example
- * ```typescript
- * // Create a client with custom options
- * const client = new Client({
- *   token: "my-token",
- *   headers: { "X-Custom": "header" },
- * });
- *
- * // Send a message
- * await client.send("my-topic", { hello: "world" });
- *
- * // Handle callbacks
- * export const POST = client.handleCallback({
- *   "my-topic": {
- *     "my-group": async (msg, meta) => console.log(msg),
- *   },
- * });
- * ```
- */
-declare class Client {
-    private client;
-    /**
-     * Create a new Client
-     * @param options QueueClient configuration options
-     */
-    constructor(options?: QueueClientOptions);
+interface ConsumeBatchOptions {
     /**
-     * Send a message to a topic
-     * @param topicName Name of the topic to send to
-     * @param payload The data to send
-     * @param options Optional publish options and transport
-     * @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
+     * Maximum number of messages to retrieve in a single request.
+     * @default 1
+     * @minimum 1
+     * @maximum 10
      */
-    send<T = unknown>(topicName: string, payload: T, options?: PublishOptions & {
-        transport?: Transport<T>;
-    }): Promise<{
-        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
-     * @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, options?: Omit<HandleCallbackOptions, "client">): (request: Request) => Promise<Response>;
-}
-
-/**
- * Options for the consume method
- */
-interface ConsumeOptions {
-    /** The specific message ID to consume (if not provided, consumes next available message) */
-    messageId?: string;
+    limit?: number;
 }
 
 /**
  * Options for the send function.
  */
-interface SendOptions<T = unknown> extends PublishOptions {
-    /**
-     * Serializer for the payload.
-     * @default JsonTransport
-     */
-    transport?: Transport<T>;
+interface SendOptions extends PublishOptions {
     /**
      * QueueClient instance to use for sending the message.
-     * If not provided, a default client is created with OIDC authentication.
+     * Configure transport on the client if you need custom serialization.
+     * If not provided, a default client is created with OIDC authentication and JsonTransport.
      */
     client?: QueueClient;
 }
@@ -337,8 +43,7 @@ interface SendOptions<T = unknown> extends PublishOptions {
  * @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
+ * @param options.client - Custom QueueClient instance (configure transport on the client)
  * @returns Promise with the generated messageId
  * @throws {DuplicateMessageError} When idempotency key was already used
  * @throws {BadRequestError} When parameters are invalid
@@ -348,7 +53,7 @@ interface SendOptions<T = unknown> extends PublishOptions {
  *
  * @example
  * ```typescript
- * // Basic usage (OIDC auth)
+ * // Basic usage (OIDC auth, JSON serialization)
  * await send("my-topic", { hello: "world" });
  *
  * // With options
@@ -358,43 +63,81 @@ interface SendOptions<T = unknown> extends PublishOptions {
  *   delaySeconds: 60,            // Delay 1 minute
  * });
  *
- * // Using custom client
- * const client = new QueueClient({ token: "my-token" });
- * await send("my-topic", payload, { client });
+ * // Using custom client with custom transport
+ * const client = new QueueClient({
+ *   token: "my-token",
+ *   transport: new BufferTransport(),
+ * });
+ * await send("my-topic", myBuffer, { client });
  * ```
  */
-declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions<T>): Promise<{
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions): Promise<{
     messageId: string;
 }>;
 /**
- * Options for the receive function.
+ * Base options shared by all receive variants.
  */
-interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOptions {
+interface ReceiveBaseOptions extends ConsumerGroupOptions {
     /**
      * QueueClient instance to use for receiving the message.
-     * If not provided, a default client is created with OIDC authentication.
+     * Configure transport on the client if you need custom deserialization.
+     * If not provided, a default client is created with OIDC authentication and JsonTransport.
      */
     client?: QueueClient;
 }
 /**
- * Receive a message from a topic.
+ * Options for receiving a specific message by ID.
+ */
+type ReceiveByIdOptions = ReceiveBaseOptions & ConsumeByIdOptions;
+/**
+ * Options for receiving messages from the queue with an optional batch limit.
+ */
+type ReceiveBatchOptions = ReceiveBaseOptions & ConsumeBatchOptions;
+/**
+ * Options for the receive function. Either receive by message ID or receive
+ * from the queue with an optional limit. These options are mutually exclusive.
+ */
+type ReceiveOptions = ReceiveByIdOptions | ReceiveBatchOptions;
+/**
+ * Receive messages from a topic.
  *
- * Shorthand for creating a topic and consumer group. The message is automatically:
+ * Shorthand for creating a topic and consumer group. Each message is automatically:
  * - Locked with the configured visibility timeout
  * - Kept alive via periodic visibility extensions during processing
  * - Deleted upon successful handler completion
  *
+ * When the queue is empty, the handler is called with `null` for both
+ * message and metadata, allowing graceful handling without exceptions.
+ *
  * @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 handler - Function to process each message payload and metadata.
+ *                  Receives (null, null) when queue is empty.
  * @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
+ * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
+ * @param options.limit - Maximum messages to retrieve (default: 1, min: 1, max: 10)
+ * @param options.client - Custom QueueClient instance (configure transport on the client)
+ * @returns Promise that resolves when all messages are processed and deleted,
+ *          or when the handler returns after receiving null (empty queue)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (OIDC auth, JSON deserialization)
+ * await receive("my-topic", "my-group", async (payload, metadata) => {
+ *   console.log("Received:", payload);
+ * });
+ *
+ * // Batch processing - fetch up to 10 messages in one request
+ * await receive("my-topic", "my-group", handler, { limit: 10 });
+ *
+ * // Using custom client with custom transport
+ * const client = new QueueClient({
+ *   transport: new BufferTransport(),
+ * });
+ * await receive("my-topic", "my-group", handler, { client });
+ * ```
  */
-declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions<T>): Promise<void>;
+declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveBatchOptions): Promise<void>;
 /**
  * Receive a specific message by its ID.
  *
@@ -410,8 +153,6 @@ declare function receive<T = unknown>(topicName: string, consumerGroup: string,
  * @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>;
+declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options: ReceiveByIdOptions): Promise<void>;
 
-export { type CallbackHandlers, Client, type HandleCallbackOptions, Message, MessageHandler, type ParsedCallbackRequest, PublishOptions, QueueClientOptions, type ReceiveOptions, SendMessageOptions, SendMessageResponse, type SendOptions, Transport, handleCallback, parseCallback, receive, send };
+export { MessageHandler, PublishOptions, QueueClient, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type SendOptions, receive, send };