@vercel/queue 0.0.0-alpha.9 → 0.0.1

package/dist/index.d.mts

@@ -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>;
 }
 
@@ -72,120 +123,271 @@ declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
  */
 
 /**
- * Shared options for publishing messages
+ * 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.
  */
-interface PublishOptions {
+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 {
+    /**
+     * 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`
+     */
+    resolveBaseUrl?: BaseUrlResolver;
     /**
-     * Unique key to prevent duplicate message submissions
-     * @default random UUID
+     * 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;
+    /**
+     * Custom headers to include in all requests.
+     */
+    headers?: Record<string, string>;
+    /**
+     * 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).
+     */
+    deploymentId?: string | null;
+    /**
+     * Serializer/deserializer for message payloads.
+     * Used for all send and receive operations.
+     * @default JsonTransport
+     */
+    transport?: Transport;
+}
+/**
+ * Options for sending messages.
+ */
+interface SendOptions {
+    /**
+     * 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;
-}
-interface SendMessageOptions<T = unknown> extends PublishOptions {
     /**
-     * The queue name to send the message to
+     * 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)
      */
-    queueName: string;
+    delaySeconds?: number;
     /**
-     * The message payload
+     * Custom headers to include with this message.
+     * These headers are passed through to the VQS server.
      */
-    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 when the message was created/published.
      */
-    timestamp: string;
+    createdAt: Date;
     /**
-     * MIME type of the message content
+     * Timestamp when the message expires.
+     * Only present for messages delivered via the v2beta binary callback path.
      */
-    contentType: string;
+    expiresAt?: Date;
     /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
+     * MIME type of the message content.
+     * Set by the transport's `contentType` property during publish.
      */
-    ticket: string;
-}
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
+    contentType: string;
     /**
-     * Time in seconds before the message becomes visible again
+     * Receipt handle (lease token) for this message delivery.
+     * Required for acknowledge and visibility extension operations.
+     * Valid only until the visibility timeout expires.
      */
-    timeoutSeconds: number;
+    receiptHandle: string;
 }
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
 /**
  * Message metadata provided to handlers
  */
 interface MessageMetadata {
     messageId: string;
     deliveryCount: number;
-    timestamp: string;
+    createdAt: Date;
+    expiresAt?: Date;
+    topicName: string;
+    consumerGroup: string;
+    /** Vercel region the client is targeting. */
+    region: string;
 }
 /**
- * Message handler function type
+ * 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
+ */
+type RetryDirective = {
+    afterSeconds: number;
+} | {
+    acknowledge: true;
+};
+/**
+ * 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 RetryHandler = (error: unknown, metadata: MessageMetadata) => RetryDirective | void | undefined;
+/**
+ * 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.
+ */
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
+/**
+ * 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 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 receiving a specific message by ID.
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
+interface ReceiveByIdOptions {
+    /** The specific message ID to consume */
+    messageId: string;
+    /**
+     * Message lock duration in seconds.
+     * @default 300 (5 minutes)
+     * @minimum 30
+     * @maximum 3600 (1 hour)
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * 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.
+     */
+    retry?: RetryHandler;
+}
 /**
- * Options for creating a ConsumerGroup instance
+ * Options for receiving messages from the queue with an optional batch limit.
  */
-interface ConsumerGroupOptions<T = unknown> {
+interface ReceiveBatchOptions {
     /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
+     * Maximum number of messages to retrieve in a single request.
+     * @default 1
+     * @minimum 1
+     * @maximum 10
      */
-    transport?: Transport<T>;
+    limit?: number;
     /**
-     * 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;
 }
 /**
- * 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);
@@ -197,166 +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 (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 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 for the consume method
+ * Error thrown when attempting to process a message that has already been successfully processed.
  */
-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 MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
 }
-
 /**
- * Options for the send function
+ * Error thrown when a duplicate idempotency key is detected.
+ * The message was already sent within the deduplication window.
  */
-interface SendOptions<T = unknown> extends PublishOptions {
-    /**
-     * Serializer/deserializer for the payload
-     * @default JsonTransport instance
-     */
-    transport?: Transport<T>;
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: string);
 }
 /**
- * Send a message to a topic (shorthand for topic creation and publishing)
- * Uses the default QueueClient with automatic OIDC token detection
- * @param topicName Name of the topic to send to
- * @param payload The data to send
- * @param options Optional send options including transport and publish settings
- * @returns Promise with the message ID
- * @throws {BadRequestError} When request parameters are invalid
- * @throws {UnauthorizedError} When authentication fails
- * @throws {ForbiddenError} When access is denied (environment mismatch)
- * @throws {InternalServerError} When server encounters an error
- */
-declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions<T>): Promise<{
-    messageId: string;
-}>;
+ * Error thrown when consumer discovery fails.
+ * This typically means the deployment could not be reached or is not configured correctly.
+ */
+declare class ConsumerDiscoveryError extends Error {
+    readonly deploymentId?: string;
+    constructor(message: string, deploymentId?: string);
+}
 /**
- * Options for the receive function
+ * Error thrown when the consumer registry is not configured for the project.
  */
-interface ReceiveOptions<T = unknown> extends ConsumerGroupOptions<T>, ConsumeOptions {
+declare class ConsumerRegistryNotConfiguredError extends Error {
+    constructor(message?: string);
+}
+
+declare class QueueClient {
+    constructor(options: QueueClientOptions);
+    /**
+     * 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)
+     */
+    send: <T = unknown>(topicName: string, payload: T, options?: SendOptions) => Promise<SendResult>;
+    /**
+     * Receive and process messages from a topic.
+     *
+     * 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.
+     *
+     * 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);
+     * ```
+     *
+     * @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
+     */
+    receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
+    /**
+     * 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>);
 }
+
 /**
- * Receive a message from a topic (shorthand for topic and consumer group creation)
- * Uses the default QueueClient with automatic OIDC token detection
- * @param topicName Name of the topic to receive from
- * @param consumerGroup Name of the consumer group
- * @param handler Function to process the message
- * @returns Promise that resolves when the message is processed
- * @throws All the same errors as the underlying client methods
- */
-declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions<T>): Promise<void>;
-/**
- * Receive a specific message by its ID with full payload
- * @param topicName Name of the topic to receive from
- * @param consumerGroup Name of the consumer group
- * @param handler Function to process the message
- * @param options Receive options with messageId specified
- * @returns Promise that resolves when the message is processed
- * @throws All the same errors as the underlying client methods
- */
-declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options: ReceiveOptions<T> & {
-    messageId: string;
-    skipPayload?: false | undefined;
-}): Promise<void>;
-/**
- * Receive a specific message by its ID without downloading the payload (metadata only)
- * @param topicName Name of the topic to receive from
- * @param consumerGroup Name of the consumer group
- * @param handler Function to process the message metadata (payload will be void)
- * @param options Receive options with messageId and skipPayload specified
- * @returns Promise that resolves when the message is processed
- * @throws All the same errors as the underlying client methods
- */
-declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<void>, options: ReceiveOptions<T> & {
-    messageId: string;
-    skipPayload: true;
-}): Promise<void>;
+ * 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 const CLOUD_EVENT_TYPE_V1BETA = "com.vercel.queue.v1beta";
+declare const CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta";
 /**
- * Configuration object with handlers for different topics and consumer groups
+ * Routing-only callback: the SDK must fetch the message by ID.
+ * Produced by v1beta structured mode and v2beta large-body mode.
  */
-type CallbackHandlers = {
-    [topicName: string]: {
-        [consumerGroup: string]: MessageHandler;
-    };
+type ParsedCallbackV1 = {
+    queueName: string;
+    consumerGroup: string;
+    messageId: string;
+    region?: 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;
+    region?: string;
+    receiptHandle: string;
+    deliveryCount?: number;
+    createdAt?: string;
+    expiresAt?: string;
+    contentType?: string;
+    visibilityDeadline?: string;
+    rawBody?: ReadableStream<Uint8Array>;
+    parsedPayload?: unknown;
 };
+type ParsedCallbackRequest = ParsedCallbackV1 | ParsedCallbackV2;
 /**
- * Simplified queue callback handler for Next.js route handlers
+ * Parse a callback from a pre-parsed body and headers.
  *
- * Automatically extracts queue information from CloudEvent format
- * and routes to the appropriate handler based on topic and consumer group.
+ * For frameworks like Next.js Pages Router where the body has already been
+ * parsed, use this instead of {@link parseCallback}.
  *
- * @param handlers Object with topic-specific handlers organized by consumer groups
- * @returns A Next.js 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 small messages, the body is attached as `parsedPayload`.
+ * - Otherwise: structured content mode (v1beta, entire CloudEvent in JSON body)
  *
- * @example
- * ```typescript
- * // Single topic with multiple consumer groups
- * export const POST = handleCallback({
- *   "image-processing": {
- *     "compress": (message, metadata) => console.log("Compressing image", message),
- *     "resize": (message, metadata) => console.log("Resizing image", message),
- *   }
- * });
+ * @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.
  *
- * // Multiple topics with consumer groups
- * export const POST = handleCallback({
- *   "user-events": {
- *     "welcome": (user, metadata) => console.log("Welcoming user", user),
- *     "analytics": (user, metadata) => console.log("Tracking user", user),
- *   },
- *   "order-events": {
- *     "fulfillment": (order, metadata) => console.log("Fulfilling order", order),
- *     "notifications": (order, metadata) => console.log("Notifying order", order),
- *   }
- * });
- * ```
+ * 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 handleCallback(handlers: CallbackHandlers): (request: Request) => Promise<Response>;
+declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, BufferTransport, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageCorruptedError, type MessageHandler, type MessageHandlerResult, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type MessageTimeoutResult, type PublishOptions, QueueEmptyError, type ReceiveOptions, type SendMessageOptions, type SendMessageResponse, type SendOptions, StreamTransport, type Transport, UnauthorizedError, handleCallback, 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 };