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

package/dist/index.d.ts

@@ -1,158 +1,650 @@
-import { M as MessageHandler, C as ConsumerGroupOptions, Q as QueueClient, P as PublishOptions } from './callback-lq_sorrn.js';
-export { g as BadRequestError, B as BufferTransport, a as CLOUD_EVENT_TYPE_V1BETA, b as CLOUD_EVENT_TYPE_V2BETA, i as ConsumerDiscoveryError, j as ConsumerRegistryNotConfiguredError, D as DuplicateMessageError, F as ForbiddenError, H as HandleCallbackOptions, I as InternalServerError, k as InvalidLimitError, J as JsonTransport, s as Message, l as MessageAlreadyProcessedError, m as MessageCorruptedError, n as MessageLockedError, t as MessageMetadata, o as MessageNotAvailableError, q as MessageNotFoundError, d as ParsedCallbackRequest, e as ParsedCallbackV1, f as ParsedCallbackV2, u as QueueClientOptions, r as QueueEmptyError, v as SendMessageOptions, w as SendMessageResponse, S as StreamTransport, T as Transport, U as UnauthorizedError, h as handleCallback, p as parseCallback, c as parseRawCallback } from './callback-lq_sorrn.js';
-
 /**
- * Options for consuming a specific message by ID.
+ * 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 ConsumeByIdOptions {
-    /** The specific message ID to consume */
-    messageId: string;
+interface Transport<T = unknown> {
+    /**
+     * 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.
+     * Called when receiving messages from the queue.
+     */
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
+    /**
+     * 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.
+     * Sent as the Content-Type header when publishing messages.
+     */
+    contentType: string;
 }
 /**
- * Options for consuming messages from the queue.
+ * 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" });
+ * ```
  */
-interface ConsumeBatchOptions {
+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];
     /**
-     * Maximum number of messages to retrieve in a single request.
-     * @default 1
-     * @minimum 1
-     * @maximum 10
+     * 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
      */
-    limit?: number;
+    constructor(options?: {
+        replacer?: Parameters<typeof JSON.stringify>[1];
+        reviver?: Parameters<typeof JSON.parse>[1];
+    });
+    serialize(value: T): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<T>;
 }
-
 /**
- * Options for the send function.
+ * 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);
+ * ```
  */
-interface SendOptions extends PublishOptions {
-    /**
-     * QueueClient instance to use for sending the message.
-     * Configure transport on the client if you need custom serialization.
-     * If not provided, a default client is created with OIDC authentication and JsonTransport.
-     */
-    client?: QueueClient;
+declare class BufferTransport implements Transport<Buffer> {
+    readonly contentType = "application/octet-stream";
+    serialize(value: Buffer): Buffer;
+    deserialize(stream: ReadableStream<Uint8Array>): Promise<Buffer>;
 }
 /**
- * Send a message to a topic.
+ * Pass-through stream serializer/deserializer.
  *
- * Uses the default QueueClient with automatic OIDC token detection, or a provided client.
+ * Ideal for large files and real-time streams. Does not buffer data in memory.
  *
- * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
- * @param payload - The data to send
- * @param options - Optional send options
- * @param options.idempotencyKey - 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)
- * @param options.client - Custom QueueClient instance (configure transport on the client)
- * @returns Promise with the generated messageId
- * @throws {DuplicateMessageError} When idempotency key was already used
- * @throws {BadRequestError} When parameters are invalid
- * @throws {UnauthorizedError} When authentication fails
- * @throws {ForbiddenError} When access is denied
- * @throws {InternalServerError} When server encounters an error
+ * **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
  * ```typescript
- * // Basic usage (OIDC auth, JSON serialization)
- * await send("my-topic", { hello: "world" });
- *
- * // With options
- * await send("my-topic", payload, {
- *   idempotencyKey: "unique-key",
- *   retentionSeconds: 3600,      // 1 hour TTL
- *   delaySeconds: 60,            // Delay 1 minute
- * });
+ * const queue = new QueueClient({ region: "iad1", transport: new StreamTransport() });
+ *
+ * // Sending a stream
+ * await queue.send("large-file", myReadableStream);
  *
- * // Using custom client with custom transport
- * const client = new QueueClient({
- *   token: "my-token",
- *   transport: new BufferTransport(),
+ * // Receiving - cleanup handled automatically
+ * await queue.receive("large-file", "processor", async (stream, meta) => {
+ *   const reader = stream.getReader();
+ *   // Process chunks...
  * });
- * await send("my-topic", myBuffer, { client });
  * ```
  */
-declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions): Promise<{
-    messageId: string;
-}>;
+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>;
+}
+
+/**
+ * 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 {
+    /**
+     * 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;
+    /**
+     * 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;
+}
 /**
- * Base options shared by all receive variants.
+ * Options for sending messages.
  */
-interface ReceiveBaseOptions extends ConsumerGroupOptions {
+interface SendOptions {
+    /**
+     * Unique key to prevent duplicate message submissions.
+     * Deduplication window: `min(message retention, 24 hours)`.
+     */
+    idempotencyKey?: string;
     /**
-     * QueueClient instance to use for receiving the message.
-     * Configure transport on the client if you need custom deserialization.
-     * If not provided, a default client is created with OIDC authentication and JsonTransport.
+     * Message retention time in seconds. After this period, the message expires.
+     * @default 86400 (24 hours)
+     * @minimum 60 (1 minute)
+     * @maximum 86400 (24 hours)
      */
-    client?: QueueClient;
+    retentionSeconds?: number;
+    /**
+     * 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)
+     */
+    delaySeconds?: number;
+    /**
+     * Custom headers to include with this message.
+     * These headers are passed through to the VQS server.
+     */
+    headers?: Record<string, 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> {
+    /**
+     * Unique message identifier. Used for receive-by-ID operations.
+     */
+    messageId: string;
+    /**
+     * 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.
+     * Starts at 1 for the first delivery, increments on each retry.
+     */
+    deliveryCount: number;
+    /**
+     * Timestamp when the message was created/published.
+     */
+    createdAt: Date;
+    /**
+     * Timestamp when the message expires.
+     * Only present for messages delivered via the v2beta binary callback path.
+     */
+    expiresAt?: Date;
+    /**
+     * MIME type of the message content.
+     * Set by the transport's `contentType` property during publish.
+     */
+    contentType: string;
+    /**
+     * Receipt handle (lease token) for this message delivery.
+     * Required for acknowledge and visibility extension operations.
+     * Valid only until the visibility timeout expires.
+     */
+    receiptHandle: string;
+}
+/**
+ * Message metadata provided to handlers
+ */
+interface MessageMetadata {
+    messageId: string;
+    deliveryCount: number;
+    createdAt: Date;
+    expiresAt?: Date;
+    topicName: string;
+    consumerGroup: string;
+    /** Vercel region the client is targeting. */
+    region: string;
+}
+/**
+ * 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 ReceiveByIdOptions = ReceiveBaseOptions & ConsumeByIdOptions;
+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 receiving messages from the queue with an optional batch limit.
  */
-type ReceiveBatchOptions = ReceiveBaseOptions & ConsumeBatchOptions;
+interface ReceiveBatchOptions {
+    /**
+     * Maximum number of messages to retrieve in a single request.
+     * @default 1
+     * @minimum 1
+     * @maximum 10
+     */
+    limit?: number;
+    /**
+     * 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 the receive function. Either receive by message ID or receive
+ * 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;
 /**
- * Receive messages from a topic.
- *
- * Shorthand for creating a topic and consumer group. Each message is automatically:
- * - Locked with the configured visibility timeout
- * - Kept alive via periodic visibility extensions during processing
- * - Deleted upon successful handler completion
- *
- * When the queue is empty, the handler is called with `null` for both
- * message and metadata, allowing graceful handling without exceptions.
+ * Error thrown when a message does not exist or has expired.
+ */
+declare class MessageNotFoundError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * 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 message data is corrupted or can't be parsed
+ */
+declare class MessageCorruptedError extends Error {
+    constructor(messageId: string, reason: string);
+}
+/**
+ * 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 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.
+ * This typically means the token is missing, invalid, or expired.
+ */
+declare class UnauthorizedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 when request parameters are invalid.
+ */
+declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the server encounters an unexpected error.
+ */
+declare class InternalServerError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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);
+}
+/**
+ * Error thrown when attempting to process a message that has already been successfully processed.
+ */
+declare class MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when a duplicate idempotency key is detected.
+ * The message was already sent within the deduplication window.
+ */
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: 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);
+}
+/**
+ * Error thrown when the consumer registry is not configured for the project.
+ */
+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>);
+}
+
+/**
+ * Core queue callback utilities for handling incoming webhook payloads
+ * from Vercel triggers using the CloudEvent specification.
  *
- * @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.
- *                  Receives (null, null) when queue is empty.
- * @param options - Optional receive options
- * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
- * @param options.limit - Maximum messages to retrieve (default: 1, min: 1, max: 10)
- * @param options.client - Custom QueueClient instance (configure transport on the client)
- * @returns Promise that resolves when all messages are processed and deleted,
- *          or when the handler returns after receiving null (empty queue)
+ * 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";
+/**
+ * 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;
+    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;
+/**
+ * Parse a callback from a pre-parsed body and headers.
  *
- * @example
- * ```typescript
- * // Basic usage (OIDC auth, JSON deserialization)
- * await receive("my-topic", "my-group", async (payload, metadata) => {
- *   console.log("Received:", payload);
- * });
+ * For frameworks like Next.js Pages Router where the body has already been
+ * parsed, use this instead of {@link parseCallback}.
  *
- * // Batch processing - fetch up to 10 messages in one request
- * await receive("my-topic", "my-group", handler, { limit: 10 });
+ * 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)
  *
- * // Using custom client with custom transport
- * const client = new QueueClient({
- *   transport: new BufferTransport(),
- * });
- * await receive("my-topic", "my-group", handler, { client });
- * ```
+ * @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 receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveBatchOptions): Promise<void>;
+declare function parseRawCallback(body: unknown, headers: Record<string, string | string[] | undefined>): ParsedCallbackRequest;
 /**
- * Receive a specific message by its ID.
+ * Parse and validate a CloudEvent callback from a Web API `Request` object.
  *
- * Used for targeted message processing, typically from webhook callbacks.
+ * 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)
  *
- * @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 the message payload and metadata
- * @param options - Receive options with messageId
- * @param options.messageId - Specific message ID to consume
- * @returns Promise that resolves when the message is processed and deleted
- * @throws {MessageNotFoundError} When message doesn't exist
- * @throws {MessageNotAvailableError} When message in wrong state
- * @throws {MessageAlreadyProcessedError} When already processed
+ * For frameworks that pre-parse the body (e.g. Next.js Pages Router),
+ * use {@link parseRawCallback} instead.
  */
-declare function receive<T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options: ReceiveByIdOptions): Promise<void>;
+declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { MessageHandler, PublishOptions, QueueClient, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type SendOptions, 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 };