@vercel/queue 0.0.0-alpha.33 → 0.0.0-alpha.35

package/README.md

@@ -18,11 +18,6 @@ A TypeScript client library for interacting with the Vercel Queue Service API, d
 npm install @vercel/queue
 ```
 
-The package includes:
-
-- **Main Library**: Queue client and utilities for production and development
-- **CLI Tool**: `npx vercel-queue-local-init` for local development handler initialization
-
 ## Quick Start
 
 For local development, you'll need to set up your Vercel project:
@@ -42,15 +37,7 @@ vc env pull
 
 **Queues just work locally.** After you have setup your Vercel project, when you `send()` messages in development mode, they automatically trigger your handlers locally - no external queue infrastructure needed.
 
-### Next.js Lazy Loading
-
-For Next.js API routes (or others that are lazy-loaded), run this simple command to initialize handlers:
-
-```bash
-npx vercel-queue-local-init
-```
-
-That's it! The script reads your `vercel.json`, finds your queue handlers, and triggers Next.js to load them.
+The library reads your `vercel.json` configuration, discovers your queue handlers, and triggers them automatically when messages are sent.
 
 ### Example Workflow
 
@@ -58,22 +45,9 @@ That's it! The script reads your `vercel.json`, finds your queue handlers, and t
 # Start your dev server
 npm run dev
 
-# Initialize handlers (only needed for frameworks that lazy load routes in dev)
-npx vercel-queue-local-init
-
 # Send messages - they process locally automatically!
 ```
 
-### CLI Options
-
-```bash
-# Custom port
-npx vercel-queue-local-init --port 3001
-
-# Different config file
-npx vercel-queue-local-init --config ./my-vercel.json
-```
-
 ### TypeScript Configuration
 
 Update your `tsconfig.json` to use `"bundler"` module resolution for proper package export resolution:
@@ -107,6 +81,7 @@ await send(
   {
     idempotencyKey: "unique-key", // Optional: prevent duplicate messages
     retentionSeconds: 3600, // Optional: override retention time (defaults to 24 hours)
+    delaySeconds: 60, // Optional: delay message delivery by N seconds
   },
 );
 ```
@@ -146,7 +121,7 @@ export const POST = handleCallback({
   // Single topic with one consumer
   "my-topic": {
     "my-consumer": async (message, metadata) => {
-      // metadata includes: { messageId, deliveryCount, createdAt }
+      // metadata includes: { messageId, deliveryCount, createdAt, topicName, consumerGroup }
       console.log("Processing message:", message);
 
       // If this throws an error, the message will be automatically retried
@@ -157,23 +132,10 @@ export const POST = handleCallback({
   // Multiple consumers for different purposes
   "order-events": {
     fulfillment: async (order, metadata) => {
-      // By default, errors will trigger automatic retries
-      // But you can control retry timing if needed:
-      if (!isSystemReady()) {
-        // Override default retry with a 5 minute delay
-        return { timeoutSeconds: 300 };
-      }
-
       await processOrder(order);
     },
     analytics: async (order, metadata) => {
-      try {
-        await trackOrder(order);
-      } catch (error) {
-        // Optional: Custom exponential backoff instead of default retry timing
-        const timeoutSeconds = Math.pow(2, metadata.deliveryCount) * 60;
-        return { timeoutSeconds };
-      }
+      await trackOrder(order);
     },
   },
 });
@@ -198,9 +160,6 @@ export default handleCallback({
   },
   "order-events": {
     fulfillment: async (order, metadata) => {
-      if (!isSystemReady()) {
-        return { timeoutSeconds: 300 };
-      }
       await processOrder(order);
     },
     analytics: async (order, metadata) => {
@@ -290,6 +249,47 @@ Configure which topics and consumers your API route handles.
 
 ## Advanced Features
 
+### Client Class
+
+For custom configuration (tokens, headers, etc.), use the `Client` class:
+
+```typescript
+import { Client } from "@vercel/queue";
+
+const client = new Client({
+  token: "my-token", // Optional: custom auth token
+  headers: { "X-Custom": "header" }, // Optional: custom headers
+  pinToDeployment: false, // Optional: disable deployment pinning (default: true)
+});
+
+// Send a message
+await client.send("my-topic", { hello: "world" });
+
+// Handle callbacks using the same client
+export const POST = client.handleCallback({
+  "my-topic": {
+    "my-group": async (msg, meta) => console.log(msg),
+  },
+});
+```
+
+### Parsing Callback Requests
+
+For custom webhook handling, use `parseCallback` to extract queue information from CloudEvent requests:
+
+```typescript
+import { parseCallback } from "@vercel/queue";
+
+export async function POST(request: Request) {
+  const { queueName, consumerGroup, messageId } = await parseCallback(request);
+
+  // Use the parsed information for custom processing...
+  await myWorkflow.handleWebhook(queueName, consumerGroup, messageId);
+
+  return Response.json({ status: "success" });
+}
+```
+
 ### Serialization (Transport) System
 
 The queue client supports customizable serialization through the `Transport` interface:
@@ -314,36 +314,51 @@ await send(
   { data: "example" },
   { transport: new JsonTransport() },
 );
+
+// JsonTransport with custom serialization
+const transport = new JsonTransport({
+  replacer: (key, value) => (key === "password" ? undefined : value),
+  reviver: (key, value) => (key === "date" ? new Date(value) : value),
+});
+await send("json-topic", { data: "example" }, { transport });
 ```
 
 ### Transport Selection Guide
 
-| Use Case             | Recommended Transport | Memory Usage | Performance |
-| -------------------- | --------------------- | ------------ | ----------- |
-| Small JSON objects   | JsonTransport         | Low          | High        |
-| Binary files < 100MB | BufferTransport       | Medium       | High        |
-| Large files > 100MB  | StreamTransport       | Very Low     | Medium      |
-| Real-time streams    | StreamTransport       | Very Low     | High        |
+| Use Case           | Recommended Transport | Memory Usage | Performance |
+| ------------------ | --------------------- | ------------ | ----------- |
+| Small JSON objects | JsonTransport         | Low          | High        |
+| Binary data        | BufferTransport       | Medium       | High        |
+| Large payloads     | StreamTransport       | Very Low     | Medium      |
+| Real-time streams  | StreamTransport       | Very Low     | High        |
 
 ## Error Handling
 
 The queue client provides specific error types:
 
-- **`QueueEmptyError`**: No messages available (204)
-- **`MessageLockedError`**: Message temporarily locked (423)
-- **`MessageNotFoundError`**: Message doesn't exist (404)
-- **`MessageNotAvailableError`**: Message exists but unavailable (409)
-- **`MessageCorruptedError`**: Message data corrupted
-- **`BadRequestError`**: Invalid parameters (400)
-- **`UnauthorizedError`**: Authentication failure (401)
-- **`ForbiddenError`**: Access denied (403)
-- **`InternalServerError`**: Server errors (500+)
+- **`QueueEmptyError`**: No messages available in the queue
+- **`MessageLockedError`**: Message is being processed by another consumer
+- **`MessageNotFoundError`**: Message doesn't exist or has expired
+- **`MessageNotAvailableError`**: Message exists but cannot be claimed
+- **`MessageAlreadyProcessedError`**: Message was already successfully processed
+- **`MessageCorruptedError`**: Message data could not be parsed
+- **`BadRequestError`**: Invalid request parameters
+- **`UnauthorizedError`**: Authentication failed (invalid or missing token)
+- **`ForbiddenError`**: Access denied (wrong environment or project)
+- **`DuplicateMessageError`**: Idempotency key was already used
+- **`ConcurrencyLimitError`**: Too many in-flight messages
+- **`ConsumerDiscoveryError`**: Could not reach the consumer deployment
+- **`ConsumerRegistryNotConfiguredError`**: Project not configured for queues
+- **`InternalServerError`**: Unexpected server error
+- **`InvalidLimitError`**: Batch limit outside valid range (1-10)
 
 Example error handling:
 
 ```typescript
 import {
   BadRequestError,
+  ConcurrencyLimitError,
+  DuplicateMessageError,
   ForbiddenError,
   InternalServerError,
   UnauthorizedError,
@@ -358,59 +373,131 @@ try {
     console.log("Environment mismatch - check configuration");
   } else if (error instanceof BadRequestError) {
     console.log("Invalid parameters:", error.message);
+  } else if (error instanceof DuplicateMessageError) {
+    console.log("Duplicate message:", error.idempotencyKey);
+  } else if (error instanceof ConcurrencyLimitError) {
+    console.log(
+      "Rate limited:",
+      error.currentInflight,
+      "/",
+      error.maxConcurrency,
+    );
   } else if (error instanceof InternalServerError) {
     console.log("Server error - retry with backoff");
   }
 }
 ```
 
+## Environment Variables
+
+The following environment variables can be used to configure the queue client:
+
+| Variable                 | Description                          | Default                    |
+| ------------------------ | ------------------------------------ | -------------------------- |
+| `VERCEL_QUEUE_BASE_URL`  | Override the queue service URL       | `https://vercel-queue.com` |
+| `VERCEL_QUEUE_BASE_PATH` | Override the API base path           | `/api/v3/topic`            |
+| `VERCEL_QUEUE_DEBUG`     | Enable debug logging (`1` or `true`) | -                          |
+| `VERCEL_DEPLOYMENT_ID`   | Deployment ID (auto-set by Vercel)   | -                          |
+
 ## Advanced Usage
 
 ### Direct Message Processing
 
-> **Note**: The `receive` function is not intended for use in Vercel deployments. It's designed for use in the Vercel Sandbox environment or alternative server setups where you need direct message processing control.
+> **Note**: The `receive` function is for advanced use cases where you need direct message processing control outside of Vercel's automatic triggering.
 
 ```typescript
+import { receive } from "@vercel/queue";
+
 // Process next available message
 await receive<T>(topicName, consumerGroup, handler);
 
 // Process specific message by ID
 await receive<T>(topicName, consumerGroup, handler, {
-  messageId: "message-id"
+  messageId: "message-id",
 });
 
 // Process message with options
 await receive<T>(topicName, consumerGroup, handler, {
-  messageId?: string; // Process specific message by ID
-  skipPayload?: boolean; // Skip payload download (requires messageId)
-  transport?: Transport<T>; // Custom transport (defaults to JsonTransport)
-  visibilityTimeoutSeconds?: number; // Message visibility timeout
-  refreshInterval?: number; // Refresh interval for long-running operations
+  messageId: "message-id", // Optional: process specific message by ID
+  transport: new JsonTransport(), // Optional: custom transport (defaults to JsonTransport)
+  visibilityTimeoutSeconds: 30, // Optional: message visibility timeout
+  visibilityRefreshInterval: 10, // Optional: how often to refresh the lock
 });
 
 // Handler function signature
 type MessageHandler<T = unknown> = (
   message: T,
-  metadata: MessageMetadata
-) => Promise<MessageHandlerResult> | MessageHandlerResult;
-
-// Handler result types
-type MessageHandlerResult = void | MessageTimeoutResult;
-
-interface MessageTimeoutResult {
-  timeoutSeconds: number; // seconds before message becomes available again
+  metadata: MessageMetadata,
+) => Promise<void> | void;
+
+// MessageMetadata type
+interface MessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  createdAt: Date;
+  topicName: string;
+  consumerGroup: string;
 }
 ```
 
-## Limits
+## Service Limits & Constraints
+
+### Throughput & Storage
+
+| Limit                       | Value                 | Notes                               |
+| --------------------------- | --------------------- | ----------------------------------- |
+| Message throughput          | 10,000s msg/sec/topic | Scales horizontally                 |
+| Payload size                | 1 GB                  | Smaller messages have lower latency |
+| Number of topics            | Unlimited             | No hard limit                       |
+| Consumer groups per message | ~4,000                | Per-message limit                   |
+| Messages per queue          | Unlimited             | No hard limit                       |
+
+### Parameter Constraints
+
+#### Publishing Messages
+
+| Parameter          | Default      | Min | Max         | Notes                               |
+| ------------------ | ------------ | --- | ----------- | ----------------------------------- |
+| `retentionSeconds` | 86,400 (24h) | 60  | 86,400      | Message TTL                         |
+| `delaySeconds`     | 0            | 0   | ≤ retention | Cannot exceed retention             |
+| `idempotencyKey`   | —            | —   | —           | Dedup window: `min(retention, 24h)` |
 
-- **Message Throughput**: Each topic can handle up to 1,000 messages per second
-- **Payload Size**: Maximum payload size is 4.5MB (this limit will be increased soon)
-- **Number of Topics**: No limit on the number of topics you can create
+#### Receiving Messages
 
-### Scaling Beyond Limits
+| Parameter                  | Default   | Min | Max    | Notes                       |
+| -------------------------- | --------- | --- | ------ | --------------------------- |
+| `visibilityTimeoutSeconds` | 30        | 0   | 3,600  | 0 = immediate re-visibility |
+| `limit`                    | 1         | 1   | 10     | Messages per request        |
+| `maxConcurrency`           | unlimited | 1   | 10,000 | In-flight message limit     |
 
-If you need more than 1,000 messages per second, you can create multiple topics (e.g., user-specific or shard-based topics) and handle them with a single consumer using wildcards in your `vercel.json`:
+#### Visibility Extension
+
+| Constraint                 | Value                              |
+| -------------------------- | ---------------------------------- |
+| `visibilityTimeoutSeconds` | 0 - 3,600 seconds                  |
+| Cannot extend beyond       | Message's original expiration time |
+| Receipt handle             | Must match the receive operation   |
+
+### Identifier Formats
+
+| Identifier       | Pattern          | Example                          |
+| ---------------- | ---------------- | -------------------------------- |
+| Topic/Queue name | `[A-Za-z0-9_-]+` | `my-queue`, `task_queue_v2`      |
+| Consumer group   | `[A-Za-z0-9_-]+` | `worker-1`, `analytics_consumer` |
+| Message ID       | Opaque string    | `0-1`, `3-7K9mNpQrS`             |
+| Receipt handle   | Opaque string    | Used for delete/visibility ops   |
+
+### Content-Type Handling
+
+| Scenario                        | Result                     |
+| ------------------------------- | -------------------------- |
+| Client provides `Content-Type`  | Used as-is                 |
+| No header, magic bytes detected | Auto-detected MIME type    |
+| No header, detection fails      | `application/octet-stream` |
+
+### Wildcard Topics
+
+Topic patterns support wildcards for flexible routing:
 
 ```json
 {
@@ -428,11 +515,125 @@ If you need more than 1,000 messages per second, you can create multiple topics
 }
 ```
 
-This allows you to:
+**Wildcard Rules:**
+
+- `*` may only appear **once** in the pattern
+- `*` must be at the **end** of the topic name
+- Valid: `user-*`, `orders-*`
+- Invalid: `*-events`, `user-*-data`
+
+## API Reference
+
+### Client Configuration
+
+```typescript
+import { Client } from "@vercel/queue";
+
+const client = new Client({
+  // Base URL for the queue service
+  // Default: "https://vercel-queue.com"
+  // Env: VERCEL_QUEUE_BASE_URL
+  baseUrl: "https://vercel-queue.com",
+
+  // API path prefix
+  // Default: "/api/v3/topic"
+  // Env: VERCEL_QUEUE_BASE_PATH
+  basePath: "/api/v3/topic",
+
+  // Auth token (auto-fetched via OIDC if not provided)
+  token: "my-token",
+
+  // Custom headers for all requests
+  headers: { "X-Custom": "value" },
+
+  // Deployment ID for message routing
+  // Default: process.env.VERCEL_DEPLOYMENT_ID
+  deploymentId: "dpl_xxx",
+
+  // Pin messages to current deployment when publishing
+  // Default: true
+  pinToDeployment: true,
+});
+```
+
+### Send Options
+
+```typescript
+await send("my-topic", payload, {
+  // Deduplication key
+  // Dedup window: min(retentionSeconds, 24 hours)
+  idempotencyKey: "unique-key",
+
+  // Message TTL in seconds
+  // Default: 86400, Min: 60, Max: 86400
+  retentionSeconds: 3600,
+
+  // Delay before message becomes visible
+  // Default: 0, Min: 0, Max: retentionSeconds
+  delaySeconds: 60,
+
+  // Custom serializer (default: JsonTransport)
+  transport: new JsonTransport(),
+});
+```
+
+### Receive Options
+
+```typescript
+await receive("my-topic", "my-consumer", handler, {
+  // Specific message ID to consume (optional)
+  messageId: "0-1",
+
+  // Message lock duration in seconds
+  // Default: 30, Min: 0, Max: 3600
+  visibilityTimeoutSeconds: 60,
 
-- Create topics like `user-1`, `user-2`, etc.
-- Process messages from all user topics with a single handler
-- Each topic gets its own 1,000 messages per second quota
+  // How often to refresh the lock during processing
+  // Default: visibilityTimeoutSeconds / 3
+  visibilityRefreshInterval: 15,
+
+  // Custom deserializer (default: JsonTransport)
+  transport: new JsonTransport(),
+});
+```
+
+### Receive Options (Advanced)
+
+```typescript
+await receive("my-topic", "my-consumer", handler, {
+  // Payload deserializer
+  // Default: JsonTransport
+  transport: new JsonTransport(),
+
+  // Message lock duration
+  // Default: 30, Min: 0, Max: 3600
+  visibilityTimeoutSeconds: 60,
+
+  // How often to refresh the lock during processing
+  // Default: visibilityTimeoutSeconds / 3
+  visibilityRefreshInterval: 20,
+});
+```
+
+### handleCallback Options
+
+```typescript
+export const POST = handleCallback(
+  {
+    "my-topic": {
+      "my-consumer": async (message, metadata) => {
+        await processMessage(message);
+      },
+    },
+  },
+  {
+    // Message lock duration for long-running handlers
+    // Default: 30, Min: 0, Max: 3600
+    // visibilityRefreshInterval defaults to visibilityTimeoutSeconds / 3
+    visibilityTimeoutSeconds: 300, // 5 minutes
+  },
+);
+```
 
 ## License