@vercel/queue 0.0.0-alpha.36 → 0.0.0-alpha.38

package/dist/{types-C7IKe67P.d.mts → callback-lq_sorrn.d.mts}

@@ -167,6 +167,12 @@ interface QueueClientOptions {
      * @default true
      */
     pinToDeployment?: boolean;
+    /**
+     * Serializer/deserializer for message payloads.
+     * Used for all send and receive operations.
+     * @default JsonTransport
+     */
+    transport?: Transport;
 }
 /**
  * Options for publishing messages to a topic.
@@ -273,13 +279,6 @@ interface ReceiveMessagesOptions<T = unknown> {
      * @maximum 10
      */
     limit?: number;
-    /**
-     * Maximum concurrent in-flight messages for this consumer group.
-     * When limit is reached, receive requests throw ConcurrencyLimitError.
-     * @default unlimited
-     * @minimum 1
-     */
-    maxConcurrency?: number;
 }
 interface DeleteMessageOptions {
     /**
@@ -340,32 +339,25 @@ interface MessageMetadata {
 }
 /**
  * Message handler function type
+ *
+ * When a message is available, both `message` and `metadata` are provided.
+ * When the queue is empty, both `message` and `metadata` are `null`.
+ * This allows handlers to gracefully handle the empty queue case without
+ * catching exceptions.
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
+type MessageHandler<T = unknown> = (message: T | null, metadata: MessageMetadata | null) => Promise<void> | void;
 /**
  * Options for creating a ConsumerGroup instance.
  */
 interface ConsumerGroupOptions<T = unknown> {
-    /**
-     * Serializer/deserializer for the payload.
-     * Built-in options: JsonTransport, BufferTransport, StreamTransport.
-     * @default JsonTransport
-     */
-    transport?: Transport<T>;
     /**
      * Time in seconds that messages will be invisible to other consumers after receipt.
      * The ConsumerGroup will automatically extend this timeout during processing.
-     * @default 30
-     * @minimum 0
+     * @default 300 (5 minutes)
+     * @minimum 30
      * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
-    /**
-     * How often (in seconds) to refresh the visibility timeout during message processing.
-     * Should be less than visibilityTimeoutSeconds to prevent message redelivery.
-     * @default Math.floor(visibilityTimeoutSeconds / 3)
-     */
-    visibilityRefreshInterval?: number;
 }
 interface ReceiveMessageByIdOptions<T = unknown> {
     /**
@@ -389,12 +381,6 @@ interface ReceiveMessageByIdOptions<T = unknown> {
      * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
-    /**
-     * Maximum concurrent in-flight messages for this consumer group.
-     * @default unlimited
-     * @minimum 1
-     */
-    maxConcurrency?: number;
 }
 interface ReceiveMessageByIdResponse<T = unknown> {
     message: Message<T>;
@@ -472,17 +458,6 @@ declare class InvalidLimitError extends Error {
 declare class MessageAlreadyProcessedError extends Error {
     constructor(messageId: string);
 }
-/**
- * Error thrown when the concurrency limit is exceeded.
- * This occurs when maxConcurrency is set and too many messages are already in-flight.
- */
-declare class ConcurrencyLimitError extends Error {
-    /** Current number of in-flight messages for this consumer group. */
-    readonly currentInflight?: number;
-    /** Maximum allowed concurrent messages (as configured). */
-    readonly maxConcurrency?: number;
-    constructor(message?: string, currentInflight?: number, maxConcurrency?: number);
-}
 /**
  * Error thrown when a duplicate idempotency key is detected.
  * The message was already sent within the deduplication window.
@@ -506,4 +481,238 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
-export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, ConcurrencyLimitError as j, ConsumerDiscoveryError as k, ConsumerRegistryNotConfiguredError as l, DuplicateMessageError as m, InvalidLimitError as n, MessageAlreadyProcessedError as o, MessageCorruptedError as p, MessageLockedError as q, MessageNotAvailableError as r, MessageNotFoundError as s, QueueEmptyError as t, type MessageMetadata as u };
+declare class QueueClient {
+    private baseUrl;
+    private basePath;
+    private customHeaders;
+    private providedToken?;
+    private defaultDeploymentId?;
+    private pinToDeployment;
+    private transport;
+    constructor(options?: QueueClientOptions);
+    getTransport(): Transport;
+    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)
+     * @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>): Promise<SendMessageResponse>;
+    /**
+     * Receive messages from a topic as an async generator.
+     *
+     * When the queue is empty, the generator completes without yielding any
+     * messages. Callers should handle the case where no messages are yielded.
+     *
+     * @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)
+     * @yields Message objects with payload, messageId, receiptHandle, etc.
+     *         Yields nothing if queue is empty.
+     * @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>): 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)
+     * @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>): 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>;
+}
+
+/**
+ * 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`.
+ */
+
+/**
+ * Options for configuring `handleCallback` behavior.
+ */
+interface HandleCallbackOptions {
+    /**
+     * QueueClient instance to use for processing messages.
+     * If not provided, a default client is created with OIDC authentication
+     * and JsonTransport.
+     */
+    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 300 (5 minutes)
+     * @minimum 30
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+}
+declare const CLOUD_EVENT_TYPE_V1BETA = "com.vercel.queue.v1beta";
+declare const CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta";
+/**
+ * Routing-only callback: the SDK must fetch the message by ID.
+ * Produced by v1beta structured mode and v2beta large-body mode.
+ */
+type ParsedCallbackV1 = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+};
+/**
+ * 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.
+ */
+type ParsedCallbackV2 = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+    receiptHandle: string;
+    deliveryCount?: number;
+    createdAt?: string;
+    contentType?: string;
+    visibilityDeadline?: string;
+    rawBody?: ReadableStream<Uint8Array>;
+    parsedPayload?: unknown;
+};
+type ParsedCallbackRequest = ParsedCallbackV1 | ParsedCallbackV2;
+/**
+ * Parse a callback from a pre-parsed body and headers.
+ *
+ * For frameworks like Next.js Pages Router where the body has already been
+ * parsed, use this instead of {@link parseCallback}.
+ *
+ * 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)
+ *
+ * @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 parseRawCallback(body: unknown, headers: Record<string, string | string[] | undefined>): ParsedCallbackRequest;
+/**
+ * Parse and validate a CloudEvent callback from a Web API `Request` object.
+ *
+ * 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)
+ *
+ * For frameworks that pre-parse the body (e.g. Next.js Pages Router),
+ * use {@link parseRawCallback} instead.
+ */
+declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
+/**
+ * Core queue callback handler. Processes the message using the provided handler.
+ *
+ * This is the framework-agnostic core — it takes already-parsed request data
+ * and throws on errors. Framework-specific wrappers (in `@vercel/queue/web`
+ * and `@vercel/queue/nextjs/pages`) compose around this function to handle
+ * request parsing and response formatting.
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param request - A {@link ParsedCallbackV1} (routing metadata only, message
+ *   fetched by ID) or {@link ParsedCallbackV2} (full message inlined, no fetch).
+ * @param options - Optional configuration (client, visibilityTimeoutSeconds)
+ * @throws {Error} If binary mode request has a receipt handle but no payload
+ * @throws {Error} If message processing fails
+ *
+ * @example
+ * ```typescript
+ * import { handleCallback, parseRawCallback } from "@vercel/queue";
+ *
+ * const parsed = parseRawCallback(body, headers);
+ * await handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * }, parsed);
+ * ```
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, request: ParsedCallbackRequest, options?: HandleCallbackOptions): Promise<void>;
+
+export { BufferTransport as B, type ConsumerGroupOptions as C, DuplicateMessageError as D, ForbiddenError as F, type HandleCallbackOptions as H, InternalServerError as I, JsonTransport as J, type MessageHandler as M, type PublishOptions as P, QueueClient as Q, StreamTransport as S, type Transport as T, UnauthorizedError as U, CLOUD_EVENT_TYPE_V1BETA as a, CLOUD_EVENT_TYPE_V2BETA as b, parseRawCallback as c, type ParsedCallbackRequest as d, type ParsedCallbackV1 as e, type ParsedCallbackV2 as f, BadRequestError as g, handleCallback as h, ConsumerDiscoveryError as i, ConsumerRegistryNotConfiguredError as j, InvalidLimitError as k, MessageAlreadyProcessedError as l, MessageCorruptedError as m, MessageLockedError as n, MessageNotAvailableError as o, parseCallback as p, MessageNotFoundError as q, QueueEmptyError as r, type Message as s, type MessageMetadata as t, type QueueClientOptions as u, type SendMessageOptions as v, type SendMessageResponse as w };

package/dist/{types-C7IKe67P.d.ts → callback-lq_sorrn.d.ts}

@@ -167,6 +167,12 @@ interface QueueClientOptions {
      * @default true
      */
     pinToDeployment?: boolean;
+    /**
+     * Serializer/deserializer for message payloads.
+     * Used for all send and receive operations.
+     * @default JsonTransport
+     */
+    transport?: Transport;
 }
 /**
  * Options for publishing messages to a topic.
@@ -273,13 +279,6 @@ interface ReceiveMessagesOptions<T = unknown> {
      * @maximum 10
      */
     limit?: number;
-    /**
-     * Maximum concurrent in-flight messages for this consumer group.
-     * When limit is reached, receive requests throw ConcurrencyLimitError.
-     * @default unlimited
-     * @minimum 1
-     */
-    maxConcurrency?: number;
 }
 interface DeleteMessageOptions {
     /**
@@ -340,32 +339,25 @@ interface MessageMetadata {
 }
 /**
  * Message handler function type
+ *
+ * When a message is available, both `message` and `metadata` are provided.
+ * When the queue is empty, both `message` and `metadata` are `null`.
+ * This allows handlers to gracefully handle the empty queue case without
+ * catching exceptions.
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
+type MessageHandler<T = unknown> = (message: T | null, metadata: MessageMetadata | null) => Promise<void> | void;
 /**
  * Options for creating a ConsumerGroup instance.
  */
 interface ConsumerGroupOptions<T = unknown> {
-    /**
-     * Serializer/deserializer for the payload.
-     * Built-in options: JsonTransport, BufferTransport, StreamTransport.
-     * @default JsonTransport
-     */
-    transport?: Transport<T>;
     /**
      * Time in seconds that messages will be invisible to other consumers after receipt.
      * The ConsumerGroup will automatically extend this timeout during processing.
-     * @default 30
-     * @minimum 0
+     * @default 300 (5 minutes)
+     * @minimum 30
      * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
-    /**
-     * How often (in seconds) to refresh the visibility timeout during message processing.
-     * Should be less than visibilityTimeoutSeconds to prevent message redelivery.
-     * @default Math.floor(visibilityTimeoutSeconds / 3)
-     */
-    visibilityRefreshInterval?: number;
 }
 interface ReceiveMessageByIdOptions<T = unknown> {
     /**
@@ -389,12 +381,6 @@ interface ReceiveMessageByIdOptions<T = unknown> {
      * @maximum 3600 (1 hour)
      */
     visibilityTimeoutSeconds?: number;
-    /**
-     * Maximum concurrent in-flight messages for this consumer group.
-     * @default unlimited
-     * @minimum 1
-     */
-    maxConcurrency?: number;
 }
 interface ReceiveMessageByIdResponse<T = unknown> {
     message: Message<T>;
@@ -472,17 +458,6 @@ declare class InvalidLimitError extends Error {
 declare class MessageAlreadyProcessedError extends Error {
     constructor(messageId: string);
 }
-/**
- * Error thrown when the concurrency limit is exceeded.
- * This occurs when maxConcurrency is set and too many messages are already in-flight.
- */
-declare class ConcurrencyLimitError extends Error {
-    /** Current number of in-flight messages for this consumer group. */
-    readonly currentInflight?: number;
-    /** Maximum allowed concurrent messages (as configured). */
-    readonly maxConcurrency?: number;
-    constructor(message?: string, currentInflight?: number, maxConcurrency?: number);
-}
 /**
  * Error thrown when a duplicate idempotency key is detected.
  * The message was already sent within the deduplication window.
@@ -506,4 +481,238 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
-export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, ConcurrencyLimitError as j, ConsumerDiscoveryError as k, ConsumerRegistryNotConfiguredError as l, DuplicateMessageError as m, InvalidLimitError as n, MessageAlreadyProcessedError as o, MessageCorruptedError as p, MessageLockedError as q, MessageNotAvailableError as r, MessageNotFoundError as s, QueueEmptyError as t, type MessageMetadata as u };
+declare class QueueClient {
+    private baseUrl;
+    private basePath;
+    private customHeaders;
+    private providedToken?;
+    private defaultDeploymentId?;
+    private pinToDeployment;
+    private transport;
+    constructor(options?: QueueClientOptions);
+    getTransport(): Transport;
+    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)
+     * @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>): Promise<SendMessageResponse>;
+    /**
+     * Receive messages from a topic as an async generator.
+     *
+     * When the queue is empty, the generator completes without yielding any
+     * messages. Callers should handle the case where no messages are yielded.
+     *
+     * @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)
+     * @yields Message objects with payload, messageId, receiptHandle, etc.
+     *         Yields nothing if queue is empty.
+     * @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>): 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)
+     * @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>): 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>;
+}
+
+/**
+ * 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`.
+ */
+
+/**
+ * Options for configuring `handleCallback` behavior.
+ */
+interface HandleCallbackOptions {
+    /**
+     * QueueClient instance to use for processing messages.
+     * If not provided, a default client is created with OIDC authentication
+     * and JsonTransport.
+     */
+    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 300 (5 minutes)
+     * @minimum 30
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+}
+declare const CLOUD_EVENT_TYPE_V1BETA = "com.vercel.queue.v1beta";
+declare const CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta";
+/**
+ * Routing-only callback: the SDK must fetch the message by ID.
+ * Produced by v1beta structured mode and v2beta large-body mode.
+ */
+type ParsedCallbackV1 = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+};
+/**
+ * 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.
+ */
+type ParsedCallbackV2 = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+    receiptHandle: string;
+    deliveryCount?: number;
+    createdAt?: string;
+    contentType?: string;
+    visibilityDeadline?: string;
+    rawBody?: ReadableStream<Uint8Array>;
+    parsedPayload?: unknown;
+};
+type ParsedCallbackRequest = ParsedCallbackV1 | ParsedCallbackV2;
+/**
+ * Parse a callback from a pre-parsed body and headers.
+ *
+ * For frameworks like Next.js Pages Router where the body has already been
+ * parsed, use this instead of {@link parseCallback}.
+ *
+ * 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)
+ *
+ * @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 parseRawCallback(body: unknown, headers: Record<string, string | string[] | undefined>): ParsedCallbackRequest;
+/**
+ * Parse and validate a CloudEvent callback from a Web API `Request` object.
+ *
+ * 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)
+ *
+ * For frameworks that pre-parse the body (e.g. Next.js Pages Router),
+ * use {@link parseRawCallback} instead.
+ */
+declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
+/**
+ * Core queue callback handler. Processes the message using the provided handler.
+ *
+ * This is the framework-agnostic core — it takes already-parsed request data
+ * and throws on errors. Framework-specific wrappers (in `@vercel/queue/web`
+ * and `@vercel/queue/nextjs/pages`) compose around this function to handle
+ * request parsing and response formatting.
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param request - A {@link ParsedCallbackV1} (routing metadata only, message
+ *   fetched by ID) or {@link ParsedCallbackV2} (full message inlined, no fetch).
+ * @param options - Optional configuration (client, visibilityTimeoutSeconds)
+ * @throws {Error} If binary mode request has a receipt handle but no payload
+ * @throws {Error} If message processing fails
+ *
+ * @example
+ * ```typescript
+ * import { handleCallback, parseRawCallback } from "@vercel/queue";
+ *
+ * const parsed = parseRawCallback(body, headers);
+ * await handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * }, parsed);
+ * ```
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, request: ParsedCallbackRequest, options?: HandleCallbackOptions): Promise<void>;
+
+export { BufferTransport as B, type ConsumerGroupOptions as C, DuplicateMessageError as D, ForbiddenError as F, type HandleCallbackOptions as H, InternalServerError as I, JsonTransport as J, type MessageHandler as M, type PublishOptions as P, QueueClient as Q, StreamTransport as S, type Transport as T, UnauthorizedError as U, CLOUD_EVENT_TYPE_V1BETA as a, CLOUD_EVENT_TYPE_V2BETA as b, parseRawCallback as c, type ParsedCallbackRequest as d, type ParsedCallbackV1 as e, type ParsedCallbackV2 as f, BadRequestError as g, handleCallback as h, ConsumerDiscoveryError as i, ConsumerRegistryNotConfiguredError as j, InvalidLimitError as k, MessageAlreadyProcessedError as l, MessageCorruptedError as m, MessageLockedError as n, MessageNotAvailableError as o, parseCallback as p, MessageNotFoundError as q, QueueEmptyError as r, type Message as s, type MessageMetadata as t, type QueueClientOptions as u, type SendMessageOptions as v, type SendMessageResponse as w };