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

package/README.md

@@ -18,11 +18,6 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 npm install @vercel/queue
 ```
 
-The package includes:
-
-- **Main Library**: Queue client and utilities for production and development
-- **CLI Tool**: `npx vercel-queue-local-init` for local development handler initialization
-
 ## Quick Start
 
 For local development, you'll need to set up your Vercel project:
@@ -42,15 +37,7 @@ vc env pull
 
 **Queues just work locally.** After you have setup your Vercel project, when you `send()` messages in development mode, they automatically trigger your handlers locally - no external queue infrastructure needed.
 
-### Next.js Lazy Loading
-
-For Next.js API routes (or others that are lazy-loaded), run this simple command to initialize handlers:
-
-```bash
-npx vercel-queue-local-init
-```
-
-That's it! The script reads your `vercel.json`, finds your queue handlers, and triggers Next.js to load them.
+The library reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically when messages are sent.
 
 ### Example Workflow
 
@@ -58,22 +45,9 @@ That's it! The script reads your `vercel.json`, finds your queue handlers, and t
 # Start your dev server
 npm run dev
 
-# Initialize handlers (only needed for frameworks that lazy load routes in dev)
-npx vercel-queue-local-init
-
 # Send messages - they process locally automatically!
 ```
 
-### CLI Options
-
-```bash
-# Custom port
-npx vercel-queue-local-init --port 3001
-
-# Different config file
-npx vercel-queue-local-init --config ./my-vercel.json
-```
-
 ### TypeScript Configuration
 
 Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
@@ -157,23 +131,10 @@ export const POST = handleCallback({
   // Multiple consumers for different purposes
   "order-events": {
     fulfillment: async (order, metadata) => {
-      // By default, errors will trigger automatic retries
-      // But you can control retry timing if needed:
-      if (!isSystemReady()) {
-        // Override default retry with a 5 minute delay
-        return { timeoutSeconds: 300 };
-      }
-
       await processOrder(order);
     },
     analytics: async (order, metadata) => {
-      try {
-        await trackOrder(order);
-      } catch (error) {
-        // Optional: Custom exponential backoff instead of default retry timing
-        const timeoutSeconds = Math.pow(2, metadata.deliveryCount) * 60;
-        return { timeoutSeconds };
-      }
+      await trackOrder(order);
     },
   },
 });
@@ -198,9 +159,6 @@ export default handleCallback({
   },
   "order-events": {
     fulfillment: async (order, metadata) => {
-      if (!isSystemReady()) {
-        return { timeoutSeconds: 300 };
-      }
       await processOrder(order);
     },
     analytics: async (order, metadata) => {
@@ -392,14 +350,7 @@ await receive<T>(topicName, consumerGroup, handler, {
 type MessageHandler<T = unknown> = (
   message: T,
   metadata: MessageMetadata
-) => Promise<MessageHandlerResult> | MessageHandlerResult;
-
-// Handler result types
-type MessageHandlerResult = void | MessageTimeoutResult;
-
-interface MessageTimeoutResult {
-  timeoutSeconds: number; // seconds before message becomes available again
-}
+) => Promise<void> | void;
 ```
 
 ## Limits

package/dist/index.d.mts

@@ -1,95 +1,33 @@
-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.mjs';
-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.mjs';
+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_.mjs';
+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_.mjs';
 
-/**
- * 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
-     * @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
-     */
+    receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T>, transport: Transport<T>): Promise<ReceiveMessageByIdResponse<T>>;
     deleteMessage(options: DeleteMessageOptions): Promise<DeleteMessageResponse>;
+    changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
     /**
-     * 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
+     * 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
      */
-    changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
+    changeVisibilityAlt(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
 }
 
 /**
@@ -252,8 +190,6 @@ 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;
 }
 
 /**
@@ -317,7 +253,7 @@ interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOp
  */
 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
+ * 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
@@ -327,20 +263,6 @@ declare function receive<T = unknown>(topicName: string, consumerGroup: string,
  */
 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 };

package/dist/index.d.ts

@@ -1,95 +1,33 @@
-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-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';
 
-/**
- * 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
-     * @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
-     */
+    receiveMessageById<T = unknown>(options: ReceiveMessageByIdOptions<T>, transport: Transport<T>): Promise<ReceiveMessageByIdResponse<T>>;
     deleteMessage(options: DeleteMessageOptions): Promise<DeleteMessageResponse>;
+    changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
     /**
-     * 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
+     * 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
      */
-    changeVisibility(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
+    changeVisibilityAlt(options: ChangeVisibilityOptions): Promise<ChangeVisibilityResponse>;
 }
 
 /**
@@ -252,8 +190,6 @@ 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;
 }
 
 /**
@@ -317,7 +253,7 @@ interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOp
  */
 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
+ * 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
@@ -327,20 +263,6 @@ declare function receive<T = unknown>(topicName: string, consumerGroup: string,
  */
 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 };