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

package/dist/index.d.ts

@@ -1,82 +1,100 @@
-import { M as MessageHandler, C as ConsumerGroupOptions, P as PublishOptions, T as Transport } from './types-JvOenjfT.js';
-export { a as BadRequestError, B as BufferTransport, F as ForbiddenError, I as InternalServerError, b as InvalidLimitError, J as JsonTransport, g as Message, c as MessageCorruptedError, h as MessageHandlerResult, d as MessageLockedError, i as MessageMetadata, e as MessageNotAvailableError, f as MessageNotFoundError, j as MessageTimeoutResult, Q as QueueEmptyError, k as SendMessageOptions, l as SendMessageResponse, S as StreamTransport, U as UnauthorizedError } from './types-JvOenjfT.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-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';
 
 /**
- * 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;
-}
-
-/**
- * Options for the send function
+ * Internal client for interacting with the Vercel Queue Service API
+ * Use Client for the public-facing wrapper with send/handleCallback methods
  */
-interface SendOptions<T = unknown> extends PublishOptions {
+declare class QueueClient {
+    private baseUrl;
+    private basePath;
+    private customHeaders;
+    private providedToken?;
     /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
+     * Create a new Vercel Queue Service client
+     * @param options QueueClient configuration options
      */
-    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 {
+    constructor(options?: QueueClientOptions);
+    private getToken;
+    /**
+     * Internal fetch wrapper that automatically handles debug logging
+     * when VERCEL_QUEUE_DEBUG is enabled
+     */
+    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
+     * @throws {UnauthorizedError} When authentication fails
+     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @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
+     * @throws {UnauthorizedError} When authentication fails
+     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @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
+     * @throws {UnauthorizedError} When authentication fails
+     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @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>>;
+    /**
+     * 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)
+     * @throws {UnauthorizedError} When authentication fails
+     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @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)
+     * @throws {UnauthorizedError} When authentication fails
+     * @throws {ForbiddenError} When access is denied (environment mismatch)
+     * @throws {InternalServerError} When server encounters an error
+     */
+    changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
 }
+
 /**
- * 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
+ * Queue Callback utilities for handling incoming webhook payloads from Vercel triggers
  */
-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>;
 
 /**
  * Configuration object with handlers for different topics and consumer groups
@@ -129,6 +147,7 @@ declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>
  * 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.
  * @returns A Next.js route handler function
  *
  * @example
@@ -154,6 +173,174 @@ declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>
  * });
  * ```
  */
-declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
+declare function handleCallback(handlers: CallbackHandlers, client?: QueueClient): (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.
+ */
+
+/**
+ * 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);
+    /**
+     * 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
+     */
+    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
+     * @returns A Next.js route handler function
+     *
+     * @example
+     * ```typescript
+     * export const POST = client.handleCallback({
+     *   "user-events": {
+     *     "welcome": (user, metadata) => console.log("Welcoming user", user),
+     *     "analytics": (user, metadata) => console.log("Tracking user", user),
+     *   },
+     * });
+     * ```
+     */
+    handleCallback(handlers: CallbackHandlers): (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;
+    /** Whether to skip downloading the payload (only allowed when messageId is provided) */
+    skipPayload?: boolean;
+}
+
+/**
+ * Options for the send function
+ */
+interface SendOptions<T = unknown> extends PublishOptions {
+    /**
+     * Serializer/deserializer for the payload
+     * @default JsonTransport instance
+     */
+    transport?: Transport<T>;
+    /**
+     * QueueClient instance to use for sending the message
+     * If not provided, a default client is created
+     */
+    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
+ * @throws {UnauthorizedError} When authentication fails
+ * @throws {ForbiddenError} When access is denied (environment mismatch)
+ * @throws {InternalServerError} When server encounters an error
+ *
+ * @example
+ * ```typescript
+ * // Using default client (OIDC token)
+ * await send("my-topic", { hello: "world" });
+ *
+ * // Using custom client
+ * const client = new QueueClient({ token: "my-token" });
+ * await send("my-topic", { hello: "world" }, { client });
+ * ```
+ */
+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 {
+    /**
+     * QueueClient instance to use for receiving the message
+     * If not provided, a default client is created
+     */
+    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
+ */
+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>;
 
-export { MessageHandler, type ParsedCallbackRequest, PublishOptions, type ReceiveOptions, type SendOptions, Transport, handleCallback, parseCallback, receive, send };
+export { type CallbackHandlers, Client, Message, MessageHandler, type ParsedCallbackRequest, PublishOptions, QueueClientOptions, type ReceiveOptions, SendMessageOptions, SendMessageResponse, type SendOptions, Transport, handleCallback, parseCallback, receive, send };