@vercel/queue 0.0.0-alpha.4 → 0.0.0-alpha.40

package/dist/index.d.ts

@@ -1,37 +1,83 @@
 /**
- * Serializer/Deserializer interface for message payloads
+ * Serializer/Deserializer interface for message payloads.
+ *
+ * Built-in implementations:
+ * - `JsonTransport` - JSON serialization (default, buffers entire payload)
+ * - `BufferTransport` - Binary data (buffers entire payload)
+ * - `StreamTransport` - Pass-through streaming (no buffering, ideal for large payloads)
  */
 interface Transport<T = unknown> {
     /**
-     * Serialize a value to a buffer or stream for transmission
+     * Serialize a value to a buffer or stream for transmission.
+     * The result is sent as the request body with the `contentType` header.
      */
     serialize(value: T): Buffer | ReadableStream<Uint8Array>;
     /**
-     * Deserialize a readable stream back to the original value
+     * Deserialize a readable stream back to the original value.
+     * Called when receiving messages from the queue.
      */
     deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
     /**
-     * Optional cleanup method for deserialized payloads that may contain resources
-     * Should be called when the payload is no longer needed, especially in error cases
+     * Optional cleanup method for deserialized payloads that may contain resources.
+     * Called automatically by ConsumerGroup on error; manual cleanup required for direct client usage.
      * @param payload The deserialized payload to clean up
      */
     finalize?(payload: T): Promise<void>;
     /**
-     * MIME type for this serialization format
+     * MIME type for this serialization format.
+     * Sent as the Content-Type header when publishing messages.
      */
     contentType: string;
 }
 /**
- * Built-in JSON serializer/deserializer
- * This implementation reads the entire stream into memory for JSON parsing
+ * JSON serializer/deserializer (default transport).
+ *
+ * Ideal for structured data. Buffers the entire payload in memory for parsing.
+ *
+ * @example
+ * ```typescript
+ * // Default (JsonTransport is used automatically)
+ * const queue = new QueueClient({ region: process.env.QUEUE_REGION! });
+ * await queue.send("topic", { data: "example" });
+ *
+ * // With custom serialization
+ * const queue = new QueueClient({
+ *   region: process.env.QUEUE_REGION!,
+ *   transport: new JsonTransport({
+ *     replacer: (key, value) => key === "password" ? undefined : value,
+ *     reviver: (key, value) => key === "date" ? new Date(value) : value,
+ *   }),
+ * });
+ * await queue.send("topic", { data: "example" });
+ * ```
  */
 declare class JsonTransport<T = unknown> implements Transport<T> {
     readonly contentType = "application/json";
+    readonly replacer?: Parameters<typeof JSON.stringify>[1];
+    readonly reviver?: Parameters<typeof JSON.parse>[1];
+    /**
+     * 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?: {
+        replacer?: Parameters<typeof JSON.stringify>[1];
+        reviver?: Parameters<typeof JSON.parse>[1];
+    });
     serialize(value: T): Buffer;
     deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
 }
 /**
- * Built-in Buffer serializer/deserializer (reads entire stream into a Buffer)
+ * Binary data serializer/deserializer.
+ *
+ * Ideal for binary data that fits in memory. Buffers the entire payload.
+ *
+ * @example
+ * ```typescript
+ * const queue = new QueueClient({ region: "iad1", transport: new BufferTransport() });
+ * await queue.send("binary-topic", myBuffer);
+ * ```
  */
 declare class BufferTransport implements Transport<Buffer> {
     readonly contentType = "application/octet-stream";
@@ -39,31 +85,36 @@ declare class BufferTransport implements Transport<Buffer> {
     deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
 }
 /**
- * Stream serializer/deserializer (pass-through for streaming binary data)
- * This is ideal for large payloads that don't need to be buffered in memory
+ * Pass-through stream serializer/deserializer.
+ *
+ * Ideal for large files and real-time streams. Does not buffer data in memory.
  *
- * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
- * processing the message to prevent resource leaks, especially in error cases.
- * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
+ * **Important:** When using StreamTransport, you must call `finalize(payload)` when done
+ * processing to prevent resource leaks. ConsumerGroup handles this automatically;
+ * direct client usage requires manual cleanup.
  *
- * Example usage:
+ * @example
  * ```typescript
- * const transport = new StreamTransport();
- * try {
- *   for await (const message of client.receiveMessages(options, transport)) {
- *     // Process the stream...
- *     const reader = message.payload.getReader();
- *     // ... handle stream data
- *   }
- * } catch (error) {
- *   // Cleanup is handled automatically by ConsumerGroup
- *   // or manually: await transport.finalize(message.payload);
- * }
+ * const queue = new QueueClient({ region: "iad1", transport: new StreamTransport() });
+ *
+ * // Sending a stream
+ * await queue.send("large-file", myReadableStream);
+ *
+ * // Receiving - cleanup handled automatically
+ * await queue.receive("large-file", "processor", async (stream, meta) => {
+ *   const reader = stream.getReader();
+ *   // Process chunks...
+ * });
+ * ```
  */
 declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
     readonly contentType = "application/octet-stream";
     serialize(value: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
     deserialize(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Consume any remaining stream data to prevent resource leaks.
+     * Called automatically by ConsumerGroup; manual call required for direct client usage.
+     */
     finalize(payload: ReadableStream<Uint8Array>): Promise<void>;
 }
 
@@ -71,269 +122,276 @@ declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
  * Vercel Queue Service client types
  */
 
+/**
+ * Vercel region code. The 20 known codes match
+ * {@link https://dcs.vercel-infra.com/ | dcs.vercel-infra.com}.
+ * Arbitrary strings are also accepted for forward compatibility
+ * with regions added after this SDK version.
+ */
+type VercelRegion = "arn1" | "bom1" | "cdg1" | "cle1" | "cpt1" | "dub1" | "dxb1" | "fra1" | "gru1" | "hkg1" | "hnd1" | "iad1" | "icn1" | "kix1" | "lhr1" | "pdx1" | "sfo1" | "sin1" | "syd1" | "yul1" | (string & {});
+/**
+ * Resolves a region code to a base URL for the Vercel Queue Service API.
+ *
+ * Default: `` (region) => `https://${region}.vercel-queue.com` ``
+ */
+type BaseUrlResolver = (region: string) => string;
 interface QueueClientOptions {
     /**
-     * Base URL for the Vercel Queue Service API
-     * @default "https://vqs.vercel.sh"
+     * Vercel region code for API routing.
+     *
+     * Requests are sent to the regional endpoint resolved by
+     * {@link BaseUrlResolver} (default: `https://${region}.vercel-queue.com`).
+     *
+     * Use a `QUEUE_REGION` env var set to `${VERCEL_REGION}` in production
+     * and a fixed region (e.g. `"iad1"`) in development.
+     *
+     * @example
+     * ```ts
+     * new QueueClient({ region: process.env.QUEUE_REGION! })
+     * ```
+     */
+    region: VercelRegion;
+    /**
+     * Custom resolver that maps a region code to a base URL.
+     * @default (region) => `https://${region}.vercel-queue.com`
      */
-    baseUrl?: string;
+    resolveBaseUrl?: BaseUrlResolver;
     /**
-     * Vercel function OIDC token
-     * Can be obtained from x-vercel-oidc-token header in Vercel Serverless Functions
-     * If not provided, will automatically attempt to retrieve from Vercel Function environment
+     * Authentication token for the Vercel Queue Service API.
+     * If not provided, the client will attempt to get a token via OIDC
+     * when running in a Vercel Function environment.
      */
     token?: string;
-}
-/**
- * Callback configuration for a consumer group
- */
-interface CallbackConfig {
     /**
-     * Webhook URL to notify when messages are available
+     * Custom headers to include in all requests.
      */
-    url: string;
+    headers?: Record<string, string>;
     /**
-     * Delay in seconds before sending the first callback
+     * Deployment ID for message routing and lease validation.
+     *
+     * - `undefined` (default): auto-detect from `VERCEL_DEPLOYMENT_ID` env var;
+     *   sent messages are pinned to this deployment.
+     * - `null`: explicitly unpinned — no deployment ID is sent on any request.
+     * - `"dpl_xxx"`: explicit value used for both send pinning and consume identification.
+     *
+     * Ignored in development mode (deployment ID is never sent locally).
      */
-    delay?: number;
+    deploymentId?: string | null;
     /**
-     * Delay in seconds between retry attempts when the callback fails
+     * Serializer/deserializer for message payloads.
+     * Used for all send and receive operations.
+     * @default JsonTransport
      */
-    frequency?: number;
+    transport?: Transport;
 }
 /**
- * Shared options for publishing messages
+ * Options for sending messages.
  */
-interface PublishOptions {
+interface SendOptions {
     /**
-     * Unique key to prevent duplicate message submissions
-     * @default random UUID
+     * Unique key to prevent duplicate message submissions.
+     * Deduplication window: `min(message retention, 24 hours)`.
      */
     idempotencyKey?: string;
     /**
-     * Message retention time in seconds
+     * Message retention time in seconds. After this period, the message expires.
      * @default 86400 (24 hours)
-     * @min 60
-     * @max 86400
+     * @minimum 60 (1 minute)
+     * @maximum 86400 (24 hours)
      */
     retentionSeconds?: number;
     /**
-     * Callback configuration
-     * - If a single CallbackConfig is provided, it will use the "default" consumer group
-     * - If an object is provided, keys are consumer group names with their respective callback configs
+     * Delay delivery of the message by this many seconds.
+     * The message will not be visible to consumers until the delay has passed.
+     * @default 0
+     * @minimum 0
+     * @maximum Value of retentionSeconds (delay cannot exceed retention)
      */
-    callback?: Record<string, CallbackConfig> | CallbackConfig;
-}
-interface SendMessageOptions<T = unknown> extends PublishOptions {
+    delaySeconds?: number;
     /**
-     * The queue name to send the message to
+     * Custom headers to include with this message.
+     * These headers are passed through to the VQS server.
      */
-    queueName: string;
-    /**
-     * The message payload
-     */
-    payload: T;
+    headers?: Record<string, string>;
 }
-interface SendMessageResponse {
-    /**
-     * The generated message ID
-     */
-    messageId: string;
+/**
+ * Result returned by `send()`.
+ *
+ * `messageId` is `null` when the server accepted the message for deferred
+ * processing (e.g. during a server-side outage) and no ID is available yet.
+ */
+interface SendResult {
+    messageId: string | null;
 }
 interface Message<T = unknown> {
     /**
-     * The message ID
+     * Unique message identifier. Used for receive-by-ID operations.
      */
     messageId: string;
     /**
-     * The deserialized message payload
-     * Note: If using streaming transports, ensure proper cleanup by calling transport.finalize(payload)
-     * when done processing, especially in error cases
+     * The deserialized message payload.
+     * Note: If using StreamTransport, ensure proper cleanup by calling
+     * `transport.finalize(payload)` when done processing, especially in error cases.
      */
     payload: T;
     /**
-     * Number of times this message has been delivered
+     * Number of times this message has been delivered.
+     * Starts at 1 for the first delivery, increments on each retry.
      */
     deliveryCount: number;
     /**
-     * Timestamp when the message was created
-     */
-    timestamp: string;
-    /**
-     * MIME type of the message content
-     */
-    contentType: string;
-    /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
-     */
-    ticket: string;
-}
-interface ReceiveMessagesOptions<T = unknown> {
-    /**
-     * The queue name to receive messages from
+     * Timestamp when the message was created/published.
      */
-    queueName: string;
+    createdAt: Date;
     /**
-     * Consumer group name
+     * Timestamp when the message expires.
+     * Only present for messages delivered via the v2beta binary callback path.
      */
-    consumerGroup: string;
+    expiresAt?: Date;
     /**
-     * Time in seconds that messages will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * MIME type of the message content.
+     * Set by the transport's `contentType` property during publish.
      */
-    visibilityTimeoutSeconds?: number;
+    contentType: string;
     /**
-     * Maximum number of messages to retrieve
-     * @default 10
-     * @max 10
-     * @note FIFO queues must use limit=1
+     * Receipt handle (lease token) for this message delivery.
+     * Required for acknowledge and visibility extension operations.
+     * Valid only until the visibility timeout expires.
      */
-    limit?: number;
+    receiptHandle: string;
 }
-interface DeleteMessageOptions {
-    /**
-     * The queue name the message belongs to
-     */
-    queueName: string;
-    /**
-     * Consumer group name
-     */
-    consumerGroup: string;
-    /**
-     * The message ID to delete
-     */
+/**
+ * Message metadata provided to handlers
+ */
+interface MessageMetadata {
     messageId: string;
-    /**
-     * Ticket received from the message
-     */
-    ticket: string;
-}
-interface DeleteMessageResponse {
-    /**
-     * Whether the message was successfully deleted
-     */
-    deleted: boolean;
-}
-interface ChangeVisibilityOptions {
-    /**
-     * The queue name the message belongs to
-     */
-    queueName: string;
-    /**
-     * Consumer group name
-     */
+    deliveryCount: number;
+    createdAt: Date;
+    expiresAt?: Date;
+    topicName: string;
     consumerGroup: string;
-    /**
-     * The message ID to update
-     */
-    messageId: string;
-    /**
-     * Ticket received from the message
-     */
-    ticket: string;
-    /**
-     * New visibility timeout in seconds
-     */
-    visibilityTimeoutSeconds: number;
-}
-interface ChangeVisibilityResponse {
-    /**
-     * Whether the visibility was successfully updated
-     */
-    updated: boolean;
+    /** Vercel region the client is targeting. */
+    region: string;
 }
 /**
- * Result indicating the message should be timed out for retry later
+ * Instruction returned by a {@link RetryHandler} to control what happens
+ * to a message when the handler throws.
+ *
+ * - `{ afterSeconds: N }` — reschedule the message for redelivery after N seconds
+ * - `{ acknowledge: true }` — acknowledge the message so it is never retried
  */
-interface MessageTimeoutResult {
-    /**
-     * Time in seconds before the message becomes visible again
-     */
-    timeoutSeconds: number;
-}
+type RetryDirective = {
+    afterSeconds: number;
+} | {
+    acknowledge: true;
+};
 /**
- * Result returned by message handlers
+ * Called when the message handler throws an error.
+ * Return a {@link RetryDirective} to reschedule or acknowledge the message,
+ * or return `undefined` to let the error propagate normally.
  */
-type MessageHandlerResult = void | MessageTimeoutResult;
+type RetryHandler = (error: unknown, metadata: MessageMetadata) => RetryDirective | void | undefined;
 /**
- * Message metadata provided to handlers
+ * Message handler function type.
+ *
+ * Called once per message with the deserialized payload and metadata.
+ * Not called when the queue is empty — check the return value of `receive()` instead.
  */
-interface MessageMetadata {
-    messageId: string;
-    deliveryCount: number;
-    timestamp: string;
-}
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
 /**
- * Message handler function type
+ * Result returned by `receive()`. Use `ok` to check if messages were processed.
+ *
+ * @example
+ * ```typescript
+ * const result = await receive("topic", "group", handler);
+ * if (result.ok) {
+ *   // Messages were processed successfully
+ * } else if (result.reason === "empty") {
+ *   // Queue had no messages available
+ * }
+ * ```
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
+type ReceiveResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "not_found";
+    messageId: string;
+} | {
+    ok: false;
+    reason: "not_available";
+    messageId: string;
+} | {
+    ok: false;
+    reason: "already_processed";
+    messageId: string;
+};
 /**
- * Options for creating a ConsumerGroup instance
+ * Options for receiving a specific message by ID.
  */
-interface ConsumerGroupOptions<T = unknown> {
-    /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
-     */
-    transport?: Transport<T>;
+interface ReceiveByIdOptions {
+    /** The specific message ID to consume */
+    messageId: string;
     /**
-     * Time in seconds that messages will be invisible to other consumers
-     * @default 30
+     * Message lock duration in seconds.
+     * @default 300 (5 minutes)
+     * @minimum 30
+     * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
     /**
-     * How often to refresh the visibility timeout during processing (in seconds)
-     * @default 10
+     * Called when the handler throws. Return `{ afterSeconds: N }` to reschedule
+     * the message for redelivery after N seconds, or return `undefined`
+     * to let the error propagate normally.
      */
-    refreshInterval?: number;
+    retry?: RetryHandler;
 }
-interface ReceiveMessageByIdOptions<T = unknown> {
-    /**
-     * The queue name to receive the message from
-     */
-    queueName: string;
-    /**
-     * Consumer group name
-     */
-    consumerGroup: string;
+/**
+ * Options for receiving messages from the queue with an optional batch limit.
+ */
+interface ReceiveBatchOptions {
     /**
-     * The message ID to retrieve
+     * Maximum number of messages to retrieve in a single request.
+     * @default 1
+     * @minimum 1
+     * @maximum 10
      */
-    messageId: string;
+    limit?: number;
     /**
-     * Time in seconds that the message will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * Message lock duration in seconds.
+     * @default 300 (5 minutes)
+     * @minimum 30
+     * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
     /**
-     * Skip payload content and only return message metadata
-     * When true, the server returns a 204 status with headers containing message metadata
-     * @default false
+     * Called when the handler throws. Return `{ afterSeconds: N }` to reschedule
+     * the message for redelivery after N seconds, or return `undefined`
+     * to let the error propagate normally.
      */
-    skipPayload?: boolean;
-}
-interface ReceiveMessageByIdResponse<T = unknown, TSkipPayload extends boolean = false> {
-    message: TSkipPayload extends true ? Message<void> : Message<T>;
+    retry?: RetryHandler;
 }
 /**
- * Error thrown when a message is not found (404)
+ * Options for the receive method. Either receive by message ID or receive
+ * from the queue with an optional limit. These options are mutually exclusive.
+ */
+type ReceiveOptions = ReceiveByIdOptions | ReceiveBatchOptions;
+/**
+ * Error thrown when a message does not exist or has expired.
  */
 declare class MessageNotFoundError extends Error {
     constructor(messageId: string);
 }
 /**
- * Error thrown when a message is not available for processing (409)
- * This can happen when the message is in the wrong state, already claimed, etc.
+ * Error thrown when a message exists but cannot be processed.
+ * This can happen when the message is in the wrong state or already claimed by another consumer.
  */
 declare class MessageNotAvailableError extends Error {
     constructor(messageId: string, reason?: string);
 }
-/**
- * Error thrown when there's a FIFO ordering violation (409)
- */
-declare class FifoOrderingViolationError extends Error {
-    constructor(messageId: string, reason: string);
-}
 /**
  * Error thrown when message data is corrupted or can't be parsed
  */
@@ -341,458 +399,252 @@ declare class MessageCorruptedError extends Error {
     constructor(messageId: string, reason: string);
 }
 /**
- * Error thrown when there are no messages available in the queue (204)
+ * Error thrown when there are no messages available in the queue.
  */
 declare class QueueEmptyError extends Error {
     constructor(queueName: string, consumerGroup: string);
 }
 /**
- * Error thrown when a message is temporarily locked in a FIFO queue (423)
+ * Error thrown when a message is temporarily locked by another consumer.
+ * The message is currently being processed and cannot be claimed.
  */
 declare class MessageLockedError extends Error {
+    /** Suggested retry delay in seconds, if provided by the server. */
     readonly retryAfter?: number;
     constructor(messageId: string, retryAfter?: number);
 }
 /**
- * Error thrown when authentication fails (401)
+ * Error thrown when authentication fails.
+ * This typically means the token is missing, invalid, or expired.
  */
 declare class UnauthorizedError extends Error {
     constructor(message?: string);
 }
 /**
- * Error thrown when access is forbidden (403)
+ * Error thrown when access is forbidden.
+ * This typically means the queue belongs to a different environment or project.
  */
 declare class ForbiddenError extends Error {
     constructor(message?: string);
 }
 /**
- * Error thrown for bad requests (400)
+ * Error thrown when request parameters are invalid.
  */
 declare class BadRequestError extends Error {
     constructor(message: string);
 }
 /**
- * Error thrown when there's a failed dependency (424) - FIFO ordering violation in receive by ID
- */
-declare class FailedDependencyError extends Error {
-    constructor(messageId: string);
-}
-/**
- * Error thrown for internal server errors (500)
+ * Error thrown when the server encounters an unexpected error.
  */
 declare class InternalServerError extends Error {
     constructor(message?: string);
 }
 /**
- * Error thrown when batch limit parameter is invalid
+ * Error thrown when the batch limit parameter is outside the valid range.
+ * The limit must be between 1 and 10 (inclusive).
  */
 declare class InvalidLimitError extends Error {
     constructor(limit: number, min?: number, max?: number);
 }
 /**
- * Options extracted from a queue callback request
+ * Error thrown when attempting to process a message that has already been successfully processed.
  */
-interface CallbackMessageOptions {
-    /**
-     * The queue name extracted from Vqs-Queue-Name header
-     */
-    queueName: string;
-    /**
-     * The consumer group extracted from Vqs-Consumer-Group header
-     */
-    consumerGroup: string;
-    /**
-     * The message ID extracted from Vqs-Message-Id header
-     */
-    messageId: string;
+declare class MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
 }
 /**
- * Error thrown when queue callback headers are missing or invalid
+ * Error thrown when a duplicate idempotency key is detected.
+ * The message was already sent within the deduplication window.
  */
-declare class InvalidCallbackError extends Error {
-    constructor(message: string);
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: string);
 }
-
 /**
- * Client for interacting with the Vercel Queue Service API
+ * Error thrown when consumer discovery fails.
+ * This typically means the deployment could not be reached or is not configured correctly.
  */
-declare class QueueClient {
-    private baseUrl;
-    private token;
-    /**
-     * Internal default instance for use by createTopic and other convenience functions
-     * @internal
-     */
-    private static _defaultInstance;
-    /**
-     * Create a new Vercel Queue Service client
-     * @param options Client configuration options (optional - will auto-detect Vercel Function environment)
-     */
-    constructor(options?: QueueClientOptions);
-    /**
-     * Get the default client instance for internal use by convenience functions
-     * @internal
-     */
-    static _getDefaultInstance(): QueueClient;
-    /**
-     * Synchronously get OIDC token from environment
-     * Used internally by constructor - mirrors the logic from getVercelOidcToken but synchronously
-     */
-    private getVercelOidcTokenSync;
-    /**
-     * 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 FIFO queue has locked messages (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 {FailedDependencyError} When FIFO ordering is violated (424)
-     * @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>;
+declare class ConsumerDiscoveryError extends Error {
+    readonly deploymentId?: string;
+    constructor(message: string, deploymentId?: string);
 }
-
 /**
- * Options for the consume method
+ * Error thrown when the consumer registry is not configured for the project.
  */
-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;
+declare class ConsumerRegistryNotConfiguredError extends Error {
+    constructor(message?: string);
 }
-/**
- * A ConsumerGroup represents a named group of consumers that process messages from a topic
- */
-declare class ConsumerGroup<T = unknown> {
-    private client;
-    private topicName;
-    private consumerGroupName;
-    private visibilityTimeout;
-    private refreshInterval;
-    private transport;
+
+declare class QueueClient {
+    constructor(options: QueueClientOptions);
     /**
-     * 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
+     * Send a message to a topic.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * await send("my-topic", payload);
+     * ```
+     *
+     * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+     * @param payload - The data to send (serialized via the configured transport)
+     * @param options - Optional send options (idempotencyKey, retentionSeconds, delaySeconds, headers)
+     * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+     *   the message for deferred processing (no ID available yet)
      */
-    constructor(client: QueueClient, topicName: string, consumerGroupName: string, options?: ConsumerGroupOptions<T>);
+    send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
     /**
-     * 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.
+     * Receive and process messages from a topic.
      *
-     * The extension loop runs every `refreshInterval` seconds and updates the message's
-     * visibility timeout to `visibilityTimeout` seconds from the current time.
+     * Each message is automatically locked, kept alive via periodic visibility
+     * extensions during processing, and acknowledged upon successful handler completion.
+     * The handler is not called when the queue is empty — check `result.ok` instead.
      *
-     * @param messageId - The unique identifier of the message to extend visibility for
-     * @param ticket - The receipt ticket that proves ownership of the message
-     * @returns A function that when called will stop the extension loop
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { receive } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * const result = await receive("my-topic", "my-group", handler);
+     * if (!result.ok) console.log(result.reason);
+     * ```
      *
-     * @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
-     */
-    private startVisibilityExtension;
-    /**
-     * Process a single message with the given handler
-     * @param message The message to process
-     * @param handler Function to process the message
-     */
-    private processMessage;
-    /**
-     * Consume the next available message from the queue
-     * @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
-     */
-    consume(handler: MessageHandler<T>): Promise<void>;
-    /**
-     * Consume a specific message by its ID with full payload
-     * @param handler Function to process the message
-     * @param options Consume options with messageId specified
-     * @returns Promise that resolves when the message is processed
-     * @throws All the same errors as the underlying client methods
-     */
-    consume(handler: MessageHandler<T>, options: {
-        messageId: string;
-        skipPayload?: false | undefined;
-    }): Promise<void>;
-    /**
-     * Consume a specific message by its ID without downloading the payload (metadata only)
-     * @param handler Function to process the message metadata (payload will be void)
-     * @param options Consume 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
+     * @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 each message payload and metadata.
+     *                  Not called when the queue is empty.
+     * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
+     * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
      */
-    consume(handler: MessageHandler<void>, options: {
-        messageId: string;
-        skipPayload: true;
-    }): Promise<void>;
+    receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
     /**
-     * Get the consumer group name
-     */
-    get name(): string;
-    /**
-     * Get the topic name this consumer group is subscribed to
-     */
-    get topic(): string;
+     * Create a Web API route handler for processing queue callback messages.
+     *
+     * Parses incoming `Request` as a CloudEvent and invokes the handler.
+     * For use on Vercel — Vercel invokes this route when messages are available.
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * export const POST = handleCallback(handler);
+     * ```
+     *
+     * @param handler - Function to process the message payload and metadata
+     * @param options - Optional configuration
+     * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
+     * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
+     *   reschedule the message for redelivery after N seconds.
+     * @returns A `(request: Request) => Promise<Response>` route handler
+     */
+    handleCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
+        visibilityTimeoutSeconds?: number;
+        retry?: RetryHandler;
+    }) => ((request: Request) => Promise<Response>);
+    /**
+     * Create a Connect-style route handler for processing queue callback messages.
+     * For use on Vercel — Vercel invokes this route when messages are available.
+     *
+     * For frameworks using the `(req, res)` middleware pattern where `req.body`
+     * is pre-parsed (Next.js Pages Router, etc.).
+     *
+     * This is an arrow function property so it can be destructured:
+     * ```typescript
+     * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+     * app.post("/api/queue", handleNodeCallback(handler));
+     * ```
+     *
+     * @param handler - Function to process the message payload and metadata
+     * @param options - Optional configuration
+     * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
+     * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
+     *   reschedule the message for redelivery after N seconds.
+     * @returns A `(req, res) => Promise<void>` route handler
+     */
+    handleNodeCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
+        visibilityTimeoutSeconds?: number;
+        retry?: RetryHandler;
+    }) => ((req: {
+        method?: string;
+        headers: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    }, res: {
+        status(code: number): {
+            json(data: unknown): void;
+            end(): void;
+        };
+        end(): void;
+    }) => Promise<void>);
 }
 
 /**
- * A Topic represents a named channel for publishing messages in a pub/sub pattern
+ * Core queue callback utilities for handling incoming webhook payloads
+ * from Vercel triggers using the CloudEvent specification.
+ *
+ * This module provides the framework-agnostic core. For framework-specific
+ * wrappers, see `@vercel/queue/web` and `@vercel/queue/nextjs/pages`.
  */
-declare class Topic<T = unknown> {
-    private client;
-    private topicName;
-    private transport;
-    /**
-     * Create a new Topic instance
-     * @param client QueueClient instance to use for API calls
-     * @param topicName Name of the topic to work with
-     * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
-     */
-    constructor(client: QueueClient, topicName: string, transport?: Transport<T>);
-    /**
-     * Publish a message to the topic
-     * @param payload The data to publish
-     * @param options Optional publish options
-     * @returns An object containing 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
-     */
-    publish(payload: T, options?: PublishOptions): Promise<{
-        messageId: string;
-    }>;
-    /**
-     * Create a consumer group for this topic
-     * @param consumerGroupName Name of the consumer group
-     * @param options Optional configuration for the consumer group
-     * @returns A ConsumerGroup instance
-     */
-    consumerGroup<U = T>(consumerGroupName: string, options?: ConsumerGroupOptions<U>): ConsumerGroup<U>;
-    /**
-     * Get the topic name
-     */
-    get name(): string;
-    /**
-     * Get the transport used by this topic
-     */
-    get serializer(): Transport<T>;
-}
 
+declare const CLOUD_EVENT_TYPE_V1BETA = "com.vercel.queue.v1beta";
+declare const CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta";
 /**
- * Create a new Topic instance using the default QueueClient
- * For custom client configuration, use `new Topic(customClient, topicName, transport)` directly
- * @param topicName Name of the topic
- * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
- * @returns A Topic instance
+ * Routing-only callback: the SDK must fetch the message by ID.
+ * Produced by v1beta structured mode and v2beta large-body mode.
  */
-declare function createTopic<T = unknown>(topicName: string, transport?: Transport<T>): Topic<T>;
-/**
- * Options for the send function
- */
-interface SendOptions<T = unknown> extends PublishOptions {
-    /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
-     */
-    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<{
+type ParsedCallbackV1 = {
+    queueName: string;
+    consumerGroup: string;
     messageId: string;
-}>;
+    region?: string;
+};
 /**
- * Options for the receive function
+ * Full-message callback: payload and receipt handle are inlined,
+ * so the SDK can process directly without an extra fetch.
+ * Produced by v2beta small-body mode.
  */
-interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOptions {
-}
-/**
- * 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> & {
+type ParsedCallbackV2 = {
+    queueName: string;
+    consumerGroup: string;
     messageId: string;
-    skipPayload: true;
-}): Promise<void>;
-
-/**
- * Queue Callback utilities for handling incoming webhook payloads
- */
-
+    region?: string;
+    receiptHandle: string;
+    deliveryCount?: number;
+    createdAt?: string;
+    expiresAt?: string;
+    contentType?: string;
+    visibilityDeadline?: string;
+    rawBody?: ReadableStream<Uint8Array>;
+    parsedPayload?: unknown;
+};
+type ParsedCallbackRequest = ParsedCallbackV1 | ParsedCallbackV2;
 /**
- * Parse a queue callback request and extract the required information for receiveMessageById
+ * Parse a callback from a pre-parsed body and headers.
  *
- * @param request The incoming Request object from the queue callback
- * @returns CallbackMessageOptions that can be used with receiveMessageById
- * @throws {InvalidCallbackError} When required queue headers are missing or invalid
+ * For frameworks like Next.js Pages Router where the body has already been
+ * parsed, use this instead of {@link parseCallback}.
  *
- * @example
- * ```typescript
- * import { parseCallbackRequest } from '@vercel/queue';
+ * Detects the CloudEvent version from the `ce-type` header:
+ * - `com.vercel.queue.v2beta`: binary content mode (metadata in headers,
+ *   payload in body). For small messages, the body is attached as `parsedPayload`.
+ * - Otherwise: structured content mode (v1beta, entire CloudEvent in JSON body)
  *
- * // In your webhook handler
- * export async function POST(request: Request) {
- *   try {
- *     const callbackOptions = parseCallbackRequest(request);
- *
- *     // Use with receiveMessageById
- *     const message = await client.receiveMessageById({
- *       ...callbackOptions,
- *       visibilityTimeoutSeconds: 30
- *     }, transport);
- *
- *     // Process the message...
- *   } catch (error) {
- *     if (error instanceof InvalidCallbackError) {
- *       return new Response('Invalid callback', { status: 400 });
- *     }
- *     throw error;
- *   }
- * }
- * ```
+ * @param body - The framework-parsed request body. Type depends on Content-Type
+ *   and framework configuration:
+ *   - v1beta: parsed CloudEvent JSON object
+ *   - v2beta: the message payload as parsed by the framework (object, Buffer, or string)
+ * @param headers - HTTP headers
+ * @returns Parsed callback request with routing metadata and optional payload
  */
-declare function parseCallbackRequest(request: Request): CallbackMessageOptions;
-/**
- * Configuration object with handlers for different topics
- * Each topic can have either:
- * - A single handler function (uses 'default' consumer group)
- * - An object with handlers for specific consumer groups
- */
-type CallbackHandlers = {
-    [topicName: string]: MessageHandler | {
-        [consumerGroup: string]: MessageHandler;
-    };
-};
+declare function parseRawCallback(body: unknown, headers: Record<string, string | string[] | undefined>): ParsedCallbackRequest;
 /**
- * Simplified queue callback handler for NextJS route handlers
+ * Parse and validate a CloudEvent callback from a Web API `Request` object.
  *
- * @param handlers Object with topic-specific handlers
- * @returns A NextJS route handler function
+ * Detects the CloudEvent version from the `ce-type` header:
+ * - `com.vercel.queue.v2beta`: binary content mode (metadata in headers,
+ *   payload in body). For v2beta, the body is attached as `rawBody` (a
+ *   ReadableStream) rather than being parsed.
+ * - Otherwise: structured content mode (v1beta, entire CloudEvent in JSON body)
  *
- * @example
- * ```typescript
- * // Topic handler (uses 'default' consumer group)
- * export const POST = handleCallback({
- *   "new-users": (message, metadata) => {
- *     console.log(`New user event:`, message, metadata);
- *   }
- * });
- *
- * // Consumer group specific handlers
- * export const POST = handleCallback({
- *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing image", message),
- *     "resize": (message, metadata) => console.log("Resizing image", message),
- *   }
- * });
- * ```
+ * For frameworks that pre-parse the body (e.g. Next.js Pages Router),
+ * use {@link parseRawCallback} instead.
  */
-declare function handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
+declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, BufferTransport, type CallbackConfig, type CallbackMessageOptions, type ChangeVisibilityOptions, type ChangeVisibilityResponse, type ConsumeOptions, ConsumerGroup, type ConsumerGroupOptions, type DeleteMessageOptions, type DeleteMessageResponse, FailedDependencyError, FifoOrderingViolationError, ForbiddenError, InternalServerError, InvalidCallbackError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type PublishOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveMessageByIdOptions, type ReceiveMessageByIdResponse, type ReceiveMessagesOptions, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, Topic, type Transport, UnauthorizedError, createTopic, handleCallback, parseCallbackRequest, receive, send };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, parseCallback, parseRawCallback };