@vercel/queue 0.1.0 → 0.1.1

package/README.md

@@ -19,20 +19,20 @@ npm install @vercel/queue
 
 ## Quick Start
 
-**1. Create a shared queue client:**
+**1. Link your Vercel project and pull credentials:**
 
-```typescript
-// lib/queue.ts
-import { QueueClient } from "@vercel/queue";
+The SDK authenticates via OIDC. Link your project if you haven't already, then pull to get fresh tokens:
 
-const queue = new QueueClient();
-export const { send, handleCallback } = queue;
+```bash
+npm i -g vercel
+vc link   # if you haven't already
+vc env pull
 ```
 
 **2. Send a message anywhere in your app:**
 
 ```typescript
-import { send } from "@/lib/queue";
+import { send } from "@vercel/queue";
 
 await send("my-topic", { message: "Hello world" });
 ```
@@ -41,7 +41,7 @@ await send("my-topic", { message: "Hello world" });
 
 ```typescript
 // app/api/queue/my-topic/route.ts
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
 
 export const POST = handleCallback(async (message, metadata) => {
   console.log("Processing:", message);
@@ -60,28 +60,26 @@ export const POST = handleCallback(async (message, metadata) => {
 }
 ```
 
-**5. Link your project for local development:**
+That's it. The top-level `send` and `handleCallback` use an auto-configured default client. The region is auto-detected from `VERCEL_REGION` (set automatically on Vercel). If the region can't be detected (e.g. local dev), it falls back to `iad1`.
 
-```bash
-npm i -g vercel
-vc link
-vc env pull
-```
+To target a specific region for sending, pass the `region` option:
 
-That's it. `new QueueClient()` auto-detects the region from `VERCEL_REGION` (set automatically on Vercel). If the region can't be detected (e.g. local dev), it falls back to `iad1`.
+```typescript
+await send("my-topic", payload, { region: "sfo1" });
+```
 
 ## Local Development
 
-**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically via local HTTP requests. This means your local dev environment behaves identically to production — no surprising behavior differences.
+**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, then invokes your registered `handleCallback` handlers directly in-process using the same code path as production. Your handlers are called with the exact same lifecycle (receive, visibility extension, ack) as in production.
+
+Works with Next.js (Turbopack and webpack), Nuxt, SvelteKit, and any framework that runs server-side JavaScript. The SDK automatically discovers handlers from your `vercel.json` configuration and loads route modules on demand — no manual setup required beyond `vercel.json`.
 
-> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks (Next.js, etc.) set this automatically during `npm run dev`.
+> **Note:** Local dev mode is enabled when `NODE_ENV=development`. Most frameworks set this automatically during `npm run dev`.
 
 ## Publishing Messages
 
 ```typescript
-import { QueueClient } from "@vercel/queue";
-
-const { send } = new QueueClient();
+import { send } from "@vercel/queue";
 
 // Simple send
 await send("my-topic", { message: "Hello world" });
@@ -94,6 +92,7 @@ await send(
     idempotencyKey: "unique-key", // Prevent duplicate messages
     retentionSeconds: 3600, // 1 hour TTL (default: 24h)
     delaySeconds: 60, // Delay delivery by 1 minute
+    region: "sfo1", // Optional — target a specific region
   },
 );
 ```
@@ -102,7 +101,7 @@ Example usage in an API route:
 
 ```typescript
 // app/api/send-message/route.ts
-import { send } from "@/lib/queue";
+import { send } from "@vercel/queue";
 
 export async function POST(request: Request) {
   const body = await request.json();
@@ -127,7 +126,7 @@ Returns `(Request) => Promise<Response>`. For frameworks that export Web API rou
 
 ```typescript
 // app/api/queue/my-topic/route.ts
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
 
 export const POST = handleCallback(async (message, metadata) => {
   // metadata: { messageId, deliveryCount, createdAt, expiresAt?, topicName, consumerGroup, region }
@@ -136,11 +135,37 @@ export const POST = handleCallback(async (message, metadata) => {
 });
 ```
 
+**Nuxt:**
+
+```typescript
+// server/api/queue.ts
+import { handleCallback } from "@vercel/queue";
+
+const handler = handleCallback(async (message, metadata) => {
+  await processMessage(message);
+});
+
+export default defineEventHandler(async (event) => {
+  return handler(toWebRequest(event));
+});
+```
+
+**SvelteKit:**
+
+```typescript
+// src/routes/api/queue/+server.ts
+import { handleCallback } from "@vercel/queue";
+
+export const POST = handleCallback(async (message, metadata) => {
+  await processMessage(message);
+});
+```
+
 **Hono:**
 
 ```typescript
 import { Hono } from "hono";
-import { handleCallback } from "@/lib/queue";
+import { handleCallback } from "@vercel/queue";
 
 const app = new Hono();
 app.post(
@@ -154,7 +179,26 @@ export default app;
 
 #### Connect-style — `handleNodeCallback`
 
-Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Express, Next.js Pages Router, etc.).
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Vercel Node.js functions, Express, Next.js Pages Router, etc.). Requires a `QueueClient` instance:
+
+```typescript
+// lib/queue.ts
+import { QueueClient } from "@vercel/queue";
+
+const queue = new QueueClient();
+export const { handleNodeCallback } = queue;
+```
+
+**Vercel Node.js Functions (plain `api/` directory):**
+
+```typescript
+// api/queue.ts
+import { handleNodeCallback } from "./lib/queue";
+
+export default handleNodeCallback(async (message, metadata) => {
+  await processMessage(message);
+});
+```
 
 **Next.js Pages Router:**
 
@@ -228,6 +272,8 @@ When a handler throws, the message is not acknowledged and becomes available for
 For finer control over retry timing, pass a `retry` option:
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -246,6 +292,8 @@ When `retry` returns `{ afterSeconds: N }`, the message is rescheduled for redel
 **Exponential backoff** uses `metadata.deliveryCount` (starts at 1, increments each delivery):
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -263,6 +311,8 @@ export const POST = handleCallback(
 **Conditional retry** — only retry transient errors:
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -280,6 +330,8 @@ export const POST = handleCallback(
 **Acknowledging poison messages** — stop retrying messages that can never succeed:
 
 ```typescript
+import { handleCallback } from "@vercel/queue";
+
 export const POST = handleCallback(
   async (message, metadata) => {
     await processMessage(message);
@@ -298,6 +350,8 @@ The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `
 
 ## Custom Client Configuration
 
+For most use cases, the top-level `send` and `handleCallback` functions are all you need. For advanced configuration (custom transports, explicit tokens, deployment pinning), create a `QueueClient` instance directly.
+
 ### QueueClient (push mode)
 
 For push-based workflows where Vercel delivers messages to your route handlers:
@@ -445,8 +499,8 @@ import {
   ForbiddenError,
   InternalServerError,
   UnauthorizedError,
+  send,
 } from "@vercel/queue";
-import { send } from "@/lib/queue";
 
 try {
   await send("my-topic", payload);
@@ -549,9 +603,49 @@ All error types:
 
 ## API Reference
 
+### Top-level `send(topicName, payload, options?)`
+
+The simplest way to send a message. Uses an auto-configured default client that detects the region from `VERCEL_REGION`, falling back to `"iad1"` with a console warning on first use.
+
+```typescript
+import { send } from "@vercel/queue";
+
+const { messageId } = await send("my-topic", payload, {
+  idempotencyKey: "unique-key", // Dedup window: min(retention, 24h)
+  retentionSeconds: 3600, // Message TTL (default: 86400)
+  delaySeconds: 60, // Delay before visible (default: 0)
+  headers: { "X-Custom": "val" }, // Custom headers
+  region: "sfo1", // Optional — target a specific region
+});
+```
+
+Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
+
+### Top-level `handleCallback(handler, options?)`
+
+The simplest way to handle incoming queue messages. Uses the same auto-configured default client as `send`.
+
+```typescript
+import { handleCallback } from "@vercel/queue";
+
+export const POST = handleCallback(
+  async (message, metadata) => {
+    await processMessage(message);
+  },
+  {
+    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
+    retry: (error, metadata) => {
+      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
+    },
+  },
+);
+```
+
+Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers. Vercel only. The region for follow-up API calls is determined automatically from the `ce-vqsregion` header in the incoming event.
+
 ### `QueueClient`
 
-Push-based client for workflows where Vercel delivers messages to your route handlers. Region is auto-detected from `VERCEL_REGION` (set automatically on Vercel), falling back to `"iad1"` with a console warning.
+Push-based client for workflows where Vercel delivers messages to your route handlers. Use this when you need custom configuration (transport, token, headers, deployment pinning). Region is auto-detected from `VERCEL_REGION` (set automatically on Vercel), falling back to `"iad1"` with a console warning.
 
 ```typescript
 import { QueueClient } from "@vercel/queue";
@@ -585,21 +679,6 @@ const queue = new PollingQueueClient({
 const { send, receive } = queue;
 ```
 
-### `send(topicName, payload, options?)`
-
-Available on both `QueueClient` and `PollingQueueClient`.
-
-Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
-
-```typescript
-const { messageId } = await send("my-topic", payload, {
-  idempotencyKey: "unique-key", // Dedup window: min(retention, 24h)
-  retentionSeconds: 3600, // Message TTL (default: 86400)
-  delaySeconds: 60, // Delay before visible (default: 0)
-  headers: { "X-Custom": "val" }, // Custom headers
-});
-```
-
 ### `receive(topicName, consumerGroup, handler, options?)`
 
 Available on `PollingQueueClient` only.
@@ -626,26 +705,6 @@ const result = await receive("my-topic", "my-group", handler, {
 });
 ```
 
-### `handleCallback(handler, options?)`
-
-Available on `QueueClient` only. Vercel only.
-
-Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
-
-```typescript
-export const POST = handleCallback(
-  async (message, metadata) => {
-    await processMessage(message);
-  },
-  {
-    visibilityTimeoutSeconds: 300, // Lock duration (default: 300)
-    retry: (error, metadata) => {
-      // Optional: return { afterSeconds: N } to reschedule, { acknowledge: true } to ack, or undefined to propagate
-    },
-  },
-);
-```
-
 ### `handleNodeCallback(handler, options?)`
 
 Available on `QueueClient` only. Vercel only.
@@ -653,6 +712,11 @@ Available on `QueueClient` only. Vercel only.
 Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
 ```typescript
+import { QueueClient } from "@vercel/queue";
+
+const queue = new QueueClient();
+const { handleNodeCallback } = queue;
+
 // pages/api/queue/my-topic.ts
 export default handleNodeCallback(
   async (message, metadata) => {

package/dist/index.d.mts

@@ -519,6 +519,9 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
 /**
  * Queue client for push-based (callback) workflows.
  *
@@ -577,12 +580,12 @@ declare class QueueClient {
      * @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
+     * @returns A route handler that accepts either `Request` or `{ request: Request }`
      */
     handleCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
         visibilityTimeoutSeconds?: number;
         retry?: RetryHandler;
-    }) => ((request: Request) => Promise<Response>);
+    }) => ((requestOrEvent: CallbackRequestInput$1) => 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.
@@ -680,6 +683,58 @@ declare class PollingQueueClient {
     receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
 }
 
+type CallbackRequestInput = Request | {
+    request: Request;
+};
+/**
+ * Send a message to a topic using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { send } from "@vercel/queue";
+ * await send("my-topic", { hello: "world" });
+ * ```
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param payload - The data to send (serialized via JsonTransport)
+ * @param options - Optional send options. Pass `region` to route to a specific region.
+ * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+ *   the message for deferred processing
+ */
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions & {
+    region?: VercelRegion;
+}): Promise<SendResult>;
+/**
+ * Create a Web API route handler for processing queue callback messages
+ * using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ * The callback region is determined automatically from the incoming
+ * `ce-vqsregion` header in the v2beta event — no manual configuration needed.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { handleCallback } from "@vercel/queue";
+ * export const POST = handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * });
+ * ```
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Optional configuration (visibilityTimeoutSeconds, retry)
+ * @returns A route handler that accepts either `Request` or `{ request: Request }`
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options?: {
+    visibilityTimeoutSeconds?: number;
+    retry?: RetryHandler;
+}): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -753,4 +808,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-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, PollingQueueClient, type PollingQueueClientOptions, 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 };
+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, PollingQueueClient, type PollingQueueClientOptions, 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, handleCallback, parseCallback, parseRawCallback, send };

package/dist/index.d.ts

@@ -519,6 +519,9 @@ declare class ConsumerRegistryNotConfiguredError extends Error {
     constructor(message?: string);
 }
 
+type CallbackRequestInput$1 = Request | {
+    request: Request;
+};
 /**
  * Queue client for push-based (callback) workflows.
  *
@@ -577,12 +580,12 @@ declare class QueueClient {
      * @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
+     * @returns A route handler that accepts either `Request` or `{ request: Request }`
      */
     handleCallback: <T = unknown>(handler: MessageHandler<T>, options?: {
         visibilityTimeoutSeconds?: number;
         retry?: RetryHandler;
-    }) => ((request: Request) => Promise<Response>);
+    }) => ((requestOrEvent: CallbackRequestInput$1) => 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.
@@ -680,6 +683,58 @@ declare class PollingQueueClient {
     receive: <T = unknown>(topicName: string, consumerGroup: string, handler: MessageHandler<T>, options?: ReceiveOptions) => Promise<ReceiveResult>;
 }
 
+type CallbackRequestInput = Request | {
+    request: Request;
+};
+/**
+ * Send a message to a topic using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { send } from "@vercel/queue";
+ * await send("my-topic", { hello: "world" });
+ * ```
+ *
+ * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+ * @param payload - The data to send (serialized via JsonTransport)
+ * @param options - Optional send options. Pass `region` to route to a specific region.
+ * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+ *   the message for deferred processing
+ */
+declare function send<T = unknown>(topicName: string, payload: T, options?: SendOptions & {
+    region?: VercelRegion;
+}): Promise<SendResult>;
+/**
+ * Create a Web API route handler for processing queue callback messages
+ * using the default auto-configured client.
+ *
+ * The default client auto-detects the region from `VERCEL_REGION`,
+ * falling back to `"iad1"` with a console warning on first use.
+ * The callback region is determined automatically from the incoming
+ * `ce-vqsregion` header in the v2beta event — no manual configuration needed.
+ *
+ * This is an arrow function–free alternative to destructuring from a
+ * {@link QueueClient} instance — import and use directly:
+ * ```typescript
+ * import { handleCallback } from "@vercel/queue";
+ * export const POST = handleCallback(async (message, metadata) => {
+ *   console.log("Processing:", message);
+ * });
+ * ```
+ *
+ * @param handler - Function to process the message payload and metadata
+ * @param options - Optional configuration (visibilityTimeoutSeconds, retry)
+ * @returns A route handler that accepts either `Request` or `{ request: Request }`
+ */
+declare function handleCallback<T = unknown>(handler: MessageHandler<T>, options?: {
+    visibilityTimeoutSeconds?: number;
+    retry?: RetryHandler;
+}): (requestOrEvent: CallbackRequestInput) => Promise<Response>;
+
 /**
  * Core queue callback utilities for handling incoming webhook payloads
  * from Vercel triggers using the CloudEvent specification.
@@ -753,4 +808,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-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, PollingQueueClient, type PollingQueueClientOptions, 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 };
+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, PollingQueueClient, type PollingQueueClientOptions, 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, handleCallback, parseCallback, parseRawCallback, send };