@vercel/queue 0.0.2 → 0.1.1

package/README.md

@@ -4,9 +4,9 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 
 ## Features
 
-- **Simple API**: `send` and `receive` are all you need
+- **Simple API**: `send` and `handleCallback` are all you need for push-based workflows
 - **Automatic Triggering on Vercel**: Vercel invokes your route handlers when messages are ready
-- **Works Anywhere**: `send` and `receive` work in any Node.js environment
+- **Works Anywhere**: `send` and `receive` work in any Node.js environment, including self-hosted and non-Vercel platforms
 - **Type Safety**: Full TypeScript generics support
 - **Customizable Serialization**: Built-in JSON, Buffer, and Stream transports
 - **Local Dev Mode**: Messages sent locally trigger your handlers automatically
@@ -19,48 +19,36 @@ npm install @vercel/queue
 
 ## Quick Start
 
-Set up your region via environment variables. If your framework supports `.env` files (Next.js, Vite, Nuxt, etc.):
+**1. Link your Vercel project and pull credentials:**
 
-```bash
-# .env.production (on Vercel, inherits the platform's region)
-QUEUE_REGION=${VERCEL_REGION}
-
-# .env.development (fixed region for local dev — iad1 is recommended)
-QUEUE_REGION=iad1
-```
-
-Otherwise, set `QUEUE_REGION` in your environment directly (e.g. via your hosting provider's dashboard or a `dotenv` setup).
-
-Create a shared queue client:
-
-```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({ region: process.env.QUEUE_REGION! });
-export const { send, receive, handleCallback, handleNodeCallback } = queue;
+```bash
+npm i -g vercel
+vc link   # if you haven't already
+vc env pull
 ```
 
-Send a message anywhere in your app:
+**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" });
 ```
 
-Handle incoming messages with a route handler:
+**3. Handle incoming messages with a route handler:**
 
 ```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);
 });
 ```
 
-Configure your `vercel.json`:
+**4. Configure `vercel.json`:**
 
 ```json
 {
@@ -72,28 +60,26 @@ Configure your `vercel.json`:
 }
 ```
 
-### Project Setup
+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`.
 
-For local development, link your Vercel project:
+To target a specific region for sending, pass the `region` option:
 
-```bash
-npm i -g vercel
-vc link
-vc env pull
+```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({ region: process.env.QUEUE_REGION! });
+import { send } from "@vercel/queue";
 
 // Simple send
 await send("my-topic", { message: "Hello world" });
@@ -106,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
   },
 );
 ```
@@ -114,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();
@@ -139,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 }
@@ -148,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(
@@ -166,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:**
 
@@ -240,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);
@@ -258,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);
@@ -275,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);
@@ -292,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);
@@ -310,40 +350,56 @@ The `retry` option is available on `handleCallback`, `handleNodeCallback`, and `
 
 ## Custom Client Configuration
 
-All configuration lives on the `QueueClient`:
+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:
 
 ```typescript
 import { QueueClient, BufferTransport } from "@vercel/queue";
 
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
+  region: "iad1", // Optional — auto-detected from VERCEL_REGION, falls back to "iad1"
   token: "my-token", // Auth token (default: OIDC auto-detection)
   transport: new BufferTransport(), // Serialization (default: JsonTransport)
   headers: { "X-Custom": "header" }, // Custom headers on all requests
   deploymentId: null, // null = unpinned, omit = auto from env, or explicit string
 });
 
-// Use directly
-await queue.send("my-topic", myBuffer);
+export const { send, handleCallback, handleNodeCallback } = queue;
+```
+
+### PollingQueueClient (poll mode)
 
-// Or destructure
-export const { send, receive, handleCallback, handleNodeCallback } = queue;
+For manual polling workflows where you call `receive` to poll for messages. Works anywhere — on Vercel, self-hosted, or any Node.js environment:
+
+```typescript
+import { PollingQueueClient, BufferTransport } from "@vercel/queue";
+
+const queue = new PollingQueueClient({
+  region: "iad1", // Required — messages must be received from a fixed region
+  token: "my-token",
+  transport: new BufferTransport(),
+  headers: { "X-Custom": "header" },
+  deploymentId: null,
+});
+
+export const { send, receive } = queue;
 ```
 
-The client sends requests to `https://${region}.vercel-queue.com`. When `handleCallback` receives a message, it reads the `ce-vqsregion` header and routes follow-up API calls to the correct regional endpoint.
+Both clients send requests to `https://${region}.vercel-queue.com`. When `handleCallback` receives a message, it reads the `ce-vqsregion` header and routes follow-up API calls to the correct regional endpoint.
 
 To customize the URL scheme, provide a `resolveBaseUrl` that returns a `URL`:
 
 ```typescript
 // Custom domain
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   resolveBaseUrl: (region) => new URL(`https://${region}.my-proxy.example`),
 });
 
 // Custom domain with a base path (e.g. reverse proxy prefix)
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   resolveBaseUrl: (region) =>
     new URL(`https://my-proxy.example/queues/${region}`),
   // → requests go to https://my-proxy.example/queues/<region>/api/v3/…
@@ -372,7 +428,6 @@ import {
 
 // JSON 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),
@@ -381,14 +436,12 @@ const queue = new QueueClient({
 
 // Binary data
 const binQueue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   transport: new BufferTransport(),
 });
 await binQueue.send("binary-topic", myBuffer);
 
 // Streaming for large payloads
 const streamQueue = new QueueClient({
-  region: process.env.QUEUE_REGION!,
   transport: new StreamTransport(),
 });
 await streamQueue.send("large-file", myReadableStream);
@@ -396,30 +449,25 @@ await streamQueue.send("large-file", myReadableStream);
 
 ## Manual Receive
 
-Use `receive` to pull and process messages directly. This is an advanced alternative to `handleCallback` that works in any Node.js environment, both on and off Vercel.
+Use `PollingQueueClient` to poll for and process messages directly. This is an advanced alternative to `handleCallback` that works in any Node.js environment, both on and off Vercel.
 
 ### Region considerations
 
-Messages can only be received from the region they were sent to. When using `receive`, use a **fixed region** (e.g. `"iad1"`) for both sending and receiving — do not use `VERCEL_REGION` (or `QUEUE_REGION=${VERCEL_REGION}`), because Vercel may route requests to different regions due to failover or load balancing, distributing your messages across regions unpredictably.
-
-```bash
-# .env.production — fixed region for manual receive workflows
-QUEUE_REGION=iad1
-
-# .env.development
-QUEUE_REGION=iad1
-```
+Messages can only be received from the region they were sent to. When using `receive`, use a **fixed region** (e.g. `"iad1"`) for both sending and receiving — do not use `VERCEL_REGION`, because Vercel may route requests to different regions due to failover or load balancing, distributing your messages across regions unpredictably.
 
 A single region is still highly available — Vercel deploys across 3+ availability zones within each region. If you need multi-region availability, you are responsible for designing your own HA strategy (e.g. sending to multiple regions and receiving from each).
 
-For most use cases on Vercel, `handleCallback` is the recommended approach — the platform handles region routing automatically and the SDK routes follow-up calls to the correct region via the `ce-vqsregion` header.
+For most use cases on Vercel, `handleCallback` via `QueueClient` is the recommended approach — the platform handles region routing automatically and the SDK routes follow-up calls to the correct region via the `ce-vqsregion` header.
 
 ### Usage
 
 ```typescript
-import { QueueClient } from "@vercel/queue";
+import { PollingQueueClient } from "@vercel/queue";
 
-const { receive } = new QueueClient({ region: "iad1" });
+const { send, receive } = new PollingQueueClient({ region: "iad1" });
+
+// Send a message
+await send("my-topic", { message: "Hello world" });
 
 // Process next available message
 const result = await receive(
@@ -451,8 +499,8 @@ import {
   ForbiddenError,
   InternalServerError,
   UnauthorizedError,
+  send,
 } from "@vercel/queue";
-import { send } from "@/lib/queue";
 
 try {
   await send("my-topic", payload);
@@ -492,12 +540,11 @@ All error types:
 
 ## Environment Variables
 
-| Variable               | Description                                     | Default |
-| ---------------------- | ----------------------------------------------- | ------- |
-| `QUEUE_REGION`         | Region code for the queue client (user-defined) | -       |
-| `VERCEL_REGION`        | Current region (auto-set by Vercel)             | -       |
-| `VERCEL_QUEUE_DEBUG`   | Enable debug logging (`1` or `true`)            | -       |
-| `VERCEL_DEPLOYMENT_ID` | Deployment ID (auto-set by Vercel)              | -       |
+| Variable               | Description                          | Default |
+| ---------------------- | ------------------------------------ | ------- |
+| `VERCEL_REGION`        | Current region (auto-set by Vercel)  | -       |
+| `VERCEL_QUEUE_DEBUG`   | Enable debug logging (`1` or `true`) | -       |
+| `VERCEL_DEPLOYMENT_ID` | Deployment ID (auto-set by Vercel)   | -       |
 
 ## Service Limits & Constraints
 
@@ -556,13 +603,55 @@ 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. 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";
 
 const queue = new QueueClient({
-  region: process.env.QUEUE_REGION!, // Required — see Quick Start for env setup
+  region: "iad1", // Optional — auto-detected from VERCEL_REGION, falls back to "iad1"
   resolveBaseUrl: (r) => new URL(`https://${r}.vercel-queue.com`), // Default resolver
   token: "my-token", // Auto-fetched via OIDC if omitted
   headers: { "X-Custom": "value" },
@@ -571,24 +660,29 @@ const queue = new QueueClient({
 });
 
 // Methods (arrow functions — safe to destructure)
-const { send, receive, handleCallback, handleNodeCallback } = queue;
+const { send, handleCallback, handleNodeCallback } = queue;
 ```
 
-### `send(topicName, payload, options?)`
+### `PollingQueueClient`
 
-Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
+Poll-based client for manually receiving messages. Works in any Node.js environment, including self-hosted and non-Vercel platforms. Region is required to ensure send and receive target the same endpoint.
 
 ```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
+import { PollingQueueClient } from "@vercel/queue";
+
+const queue = new PollingQueueClient({
+  region: "iad1", // Required — use a fixed region for polling
+  // ... same options as QueueClient (except region is required)
 });
+
+// Methods (arrow functions — safe to destructure)
+const { send, receive } = queue;
 ```
 
 ### `receive(topicName, consumerGroup, handler, options?)`
 
+Available on `PollingQueueClient` only.
+
 Returns a discriminated result: `{ ok: true }` on success, or `{ ok: false, reason }` when no message was processed. The handler is never called when the queue is empty.
 
 For receive-by-id, operational errors are returned instead of thrown:
@@ -611,29 +705,18 @@ const result = await receive("my-topic", "my-group", handler, {
 });
 ```
 
-### `handleCallback(handler, options?)`
+### `handleNodeCallback(handler, options?)`
 
-Vercel only. Returns `(request: Request) => Promise<Response>` — for frameworks that export Web API route handlers.
+Available on `QueueClient` only. Vercel only.
 
-```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
-    },
-  },
-);
-```
+Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
-### `handleNodeCallback(handler, options?)`
+```typescript
+import { QueueClient } from "@vercel/queue";
 
-Vercel only. Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
+const queue = new QueueClient();
+const { handleNodeCallback } = queue;
 
-```typescript
 // pages/api/queue/my-topic.ts
 export default handleNodeCallback(
   async (message, metadata) => {