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

package/dist/{types-Dw29Fr9y.d.mts → types-BHtRP_i_.d.mts}

@@ -87,7 +87,7 @@ interface QueueClientOptions {
     /**
      * Base path for API endpoints
      * Can also be set via VERCEL_QUEUE_BASE_PATH environment variable
-     * @default "/api/v2/messages"
+     * @default "/api/v3/topic"
      */
     basePath?: string;
     /**
@@ -99,6 +99,21 @@ interface QueueClientOptions {
      * Custom headers to include in all requests
      */
     headers?: Record<string, string>;
+    /**
+     * Default deployment ID to include in requests
+     * If not provided, defaults to VERCEL_DEPLOYMENT_ID environment variable
+     */
+    deploymentId?: string;
+    /**
+     * Whether to pin messages to the current deployment when publishing.
+     * When true, sends VERCEL_DEPLOYMENT_ID from environment, ensuring
+     * messages are routed to consumers on the same deployment.
+     * Only affects send/publish operations - consume operations always
+     * send deployment ID in production to identify the processing deployment.
+     * Ignored in development mode (deployment ID is never sent locally).
+     * @default true
+     */
+    pinToDeployment?: boolean;
 }
 /**
  * Shared options for publishing messages
@@ -117,10 +132,11 @@ interface PublishOptions {
      */
     retentionSeconds?: number;
     /**
-     * Explicit deployment identifier to include in the `Vqs-Deployment-Id` header
-     * If provided, this takes precedence over any value from the environment
+     * Delay delivery of the message by this many seconds
+     * @min 0
+     * @max retentionSeconds
      */
-    deploymentId?: string;
+    delaySeconds?: number;
 }
 interface SendMessageOptions<T = unknown> extends PublishOptions {
     /**
@@ -162,9 +178,9 @@ interface Message<T = unknown> {
      */
     contentType: string;
     /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
+     * Receipt handle for this message delivery (required for delete/patch operations)
      */
-    ticket: string;
+    receiptHandle: string;
 }
 interface ReceiveMessagesOptions<T = unknown> {
     /**
@@ -177,15 +193,19 @@ interface ReceiveMessagesOptions<T = unknown> {
     consumerGroup: string;
     /**
      * Time in seconds that messages will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * @default 30
      */
     visibilityTimeoutSeconds?: number;
     /**
      * Maximum number of messages to retrieve
-     * @default 10
+     * @default 1
      * @max 10
      */
     limit?: number;
+    /**
+     * Maximum concurrent in-flight messages
+     */
+    maxConcurrency?: number;
 }
 interface DeleteMessageOptions {
     /**
@@ -197,13 +217,9 @@ interface DeleteMessageOptions {
      */
     consumerGroup: string;
     /**
-     * The message ID to delete
+     * Receipt handle received from the message
      */
-    messageId: string;
-    /**
-     * Ticket received from the message
-     */
-    ticket: string;
+    receiptHandle: string;
 }
 interface DeleteMessageResponse {
     /**
@@ -221,13 +237,9 @@ interface ChangeVisibilityOptions {
      */
     consumerGroup: string;
     /**
-     * The message ID to update
-     */
-    messageId: string;
-    /**
-     * Ticket received from the message
+     * Receipt handle received from the message
      */
-    ticket: string;
+    receiptHandle: string;
     /**
      * New visibility timeout in seconds
      */
@@ -237,21 +249,8 @@ interface ChangeVisibilityResponse {
     /**
      * Whether the visibility was successfully updated
      */
-    updated: boolean;
-}
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
-    /**
-     * Time in seconds before the message becomes visible again
-     */
-    timeoutSeconds: number;
+    success: boolean;
 }
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
 /**
  * Message metadata provided to handlers
  */
@@ -265,7 +264,7 @@ interface MessageMetadata {
 /**
  * Message handler function type
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
 /**
  * Options for creating a ConsumerGroup instance
  */
@@ -301,18 +300,16 @@ interface ReceiveMessageByIdOptions<T = unknown> {
     messageId: string;
     /**
      * Time in seconds that the message will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * @default 30
      */
     visibilityTimeoutSeconds?: number;
     /**
-     * Skip payload content and only return message metadata
-     * When true, the server returns a 204 status with headers containing message metadata
-     * @default false
+     * Maximum concurrent in-flight messages
      */
-    skipPayload?: boolean;
+    maxConcurrency?: number;
 }
-interface ReceiveMessageByIdResponse<T = unknown, TSkipPayload extends boolean = false> {
-    message: TSkipPayload extends true ? Message<void> : Message<T>;
+interface ReceiveMessageByIdResponse<T = unknown> {
+    message: Message<T>;
 }
 /**
  * Error thrown when a message is not found (404)
@@ -376,5 +373,39 @@ declare class InternalServerError extends Error {
 declare class InvalidLimitError extends Error {
     constructor(limit: number, min?: number, max?: number);
 }
+/**
+ * Error thrown when a message has already been processed (410)
+ */
+declare class MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when concurrency limit is exceeded (429)
+ */
+declare class ConcurrencyLimitError extends Error {
+    readonly currentInflight?: number;
+    readonly maxConcurrency?: number;
+    constructor(message?: string, currentInflight?: number, maxConcurrency?: number);
+}
+/**
+ * Error thrown when a duplicate idempotency key is detected (409)
+ */
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: string);
+}
+/**
+ * Error thrown when consumer discovery fails (502)
+ */
+declare class ConsumerDiscoveryError extends Error {
+    readonly deploymentId?: string;
+    constructor(message: string, deploymentId?: string);
+}
+/**
+ * Error thrown when consumer registry is not configured (503)
+ */
+declare class ConsumerRegistryNotConfiguredError extends Error {
+    constructor(message?: string);
+}
 
-export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, InvalidLimitError as j, MessageCorruptedError as k, MessageLockedError as l, MessageNotAvailableError as m, MessageNotFoundError as n, QueueEmptyError as o, type MessageHandlerResult as p, type MessageMetadata as q, type MessageTimeoutResult as r };
+export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, ConcurrencyLimitError as j, ConsumerDiscoveryError as k, ConsumerRegistryNotConfiguredError as l, DuplicateMessageError as m, InvalidLimitError as n, MessageAlreadyProcessedError as o, MessageCorruptedError as p, MessageLockedError as q, MessageNotAvailableError as r, MessageNotFoundError as s, QueueEmptyError as t, type MessageMetadata as u };

package/dist/{types-Dw29Fr9y.d.ts → types-BHtRP_i_.d.ts}

@@ -87,7 +87,7 @@ interface QueueClientOptions {
     /**
      * Base path for API endpoints
      * Can also be set via VERCEL_QUEUE_BASE_PATH environment variable
-     * @default "/api/v2/messages"
+     * @default "/api/v3/topic"
      */
     basePath?: string;
     /**
@@ -99,6 +99,21 @@ interface QueueClientOptions {
      * Custom headers to include in all requests
      */
     headers?: Record<string, string>;
+    /**
+     * Default deployment ID to include in requests
+     * If not provided, defaults to VERCEL_DEPLOYMENT_ID environment variable
+     */
+    deploymentId?: string;
+    /**
+     * Whether to pin messages to the current deployment when publishing.
+     * When true, sends VERCEL_DEPLOYMENT_ID from environment, ensuring
+     * messages are routed to consumers on the same deployment.
+     * Only affects send/publish operations - consume operations always
+     * send deployment ID in production to identify the processing deployment.
+     * Ignored in development mode (deployment ID is never sent locally).
+     * @default true
+     */
+    pinToDeployment?: boolean;
 }
 /**
  * Shared options for publishing messages
@@ -117,10 +132,11 @@ interface PublishOptions {
      */
     retentionSeconds?: number;
     /**
-     * Explicit deployment identifier to include in the `Vqs-Deployment-Id` header
-     * If provided, this takes precedence over any value from the environment
+     * Delay delivery of the message by this many seconds
+     * @min 0
+     * @max retentionSeconds
      */
-    deploymentId?: string;
+    delaySeconds?: number;
 }
 interface SendMessageOptions<T = unknown> extends PublishOptions {
     /**
@@ -162,9 +178,9 @@ interface Message<T = unknown> {
      */
     contentType: string;
     /**
-     * Unique ticket for this message delivery (required for delete/patch operations)
+     * Receipt handle for this message delivery (required for delete/patch operations)
      */
-    ticket: string;
+    receiptHandle: string;
 }
 interface ReceiveMessagesOptions<T = unknown> {
     /**
@@ -177,15 +193,19 @@ interface ReceiveMessagesOptions<T = unknown> {
     consumerGroup: string;
     /**
      * Time in seconds that messages will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * @default 30
      */
     visibilityTimeoutSeconds?: number;
     /**
      * Maximum number of messages to retrieve
-     * @default 10
+     * @default 1
      * @max 10
      */
     limit?: number;
+    /**
+     * Maximum concurrent in-flight messages
+     */
+    maxConcurrency?: number;
 }
 interface DeleteMessageOptions {
     /**
@@ -197,13 +217,9 @@ interface DeleteMessageOptions {
      */
     consumerGroup: string;
     /**
-     * The message ID to delete
+     * Receipt handle received from the message
      */
-    messageId: string;
-    /**
-     * Ticket received from the message
-     */
-    ticket: string;
+    receiptHandle: string;
 }
 interface DeleteMessageResponse {
     /**
@@ -221,13 +237,9 @@ interface ChangeVisibilityOptions {
      */
     consumerGroup: string;
     /**
-     * The message ID to update
-     */
-    messageId: string;
-    /**
-     * Ticket received from the message
+     * Receipt handle received from the message
      */
-    ticket: string;
+    receiptHandle: string;
     /**
      * New visibility timeout in seconds
      */
@@ -237,21 +249,8 @@ interface ChangeVisibilityResponse {
     /**
      * Whether the visibility was successfully updated
      */
-    updated: boolean;
-}
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
-    /**
-     * Time in seconds before the message becomes visible again
-     */
-    timeoutSeconds: number;
+    success: boolean;
 }
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
 /**
  * Message metadata provided to handlers
  */
@@ -265,7 +264,7 @@ interface MessageMetadata {
 /**
  * Message handler function type
  */
-type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<MessageHandlerResult> | MessageHandlerResult;
+type MessageHandler<T = unknown> = (message: T, metadata: MessageMetadata) => Promise<void> | void;
 /**
  * Options for creating a ConsumerGroup instance
  */
@@ -301,18 +300,16 @@ interface ReceiveMessageByIdOptions<T = unknown> {
     messageId: string;
     /**
      * Time in seconds that the message will be invisible to other consumers
-     * @default 900 (15 minutes)
+     * @default 30
      */
     visibilityTimeoutSeconds?: number;
     /**
-     * Skip payload content and only return message metadata
-     * When true, the server returns a 204 status with headers containing message metadata
-     * @default false
+     * Maximum concurrent in-flight messages
      */
-    skipPayload?: boolean;
+    maxConcurrency?: number;
 }
-interface ReceiveMessageByIdResponse<T = unknown, TSkipPayload extends boolean = false> {
-    message: TSkipPayload extends true ? Message<void> : Message<T>;
+interface ReceiveMessageByIdResponse<T = unknown> {
+    message: Message<T>;
 }
 /**
  * Error thrown when a message is not found (404)
@@ -376,5 +373,39 @@ declare class InternalServerError extends Error {
 declare class InvalidLimitError extends Error {
     constructor(limit: number, min?: number, max?: number);
 }
+/**
+ * Error thrown when a message has already been processed (410)
+ */
+declare class MessageAlreadyProcessedError extends Error {
+    constructor(messageId: string);
+}
+/**
+ * Error thrown when concurrency limit is exceeded (429)
+ */
+declare class ConcurrencyLimitError extends Error {
+    readonly currentInflight?: number;
+    readonly maxConcurrency?: number;
+    constructor(message?: string, currentInflight?: number, maxConcurrency?: number);
+}
+/**
+ * Error thrown when a duplicate idempotency key is detected (409)
+ */
+declare class DuplicateMessageError extends Error {
+    readonly idempotencyKey?: string;
+    constructor(message: string, idempotencyKey?: string);
+}
+/**
+ * Error thrown when consumer discovery fails (502)
+ */
+declare class ConsumerDiscoveryError extends Error {
+    readonly deploymentId?: string;
+    constructor(message: string, deploymentId?: string);
+}
+/**
+ * Error thrown when consumer registry is not configured (503)
+ */
+declare class ConsumerRegistryNotConfiguredError extends Error {
+    constructor(message?: string);
+}
 
-export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, InvalidLimitError as j, MessageCorruptedError as k, MessageLockedError as l, MessageNotAvailableError as m, MessageNotFoundError as n, QueueEmptyError as o, type MessageHandlerResult as p, type MessageMetadata as q, type MessageTimeoutResult as r };
+export { BufferTransport as B, type ChangeVisibilityOptions as C, type DeleteMessageOptions as D, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type Message as M, type PublishOptions as P, type QueueClientOptions as Q, type ReceiveMessagesOptions as R, type SendMessageOptions as S, type Transport as T, UnauthorizedError as U, type SendMessageResponse as a, type ReceiveMessageByIdOptions as b, type ReceiveMessageByIdResponse as c, type DeleteMessageResponse as d, type ChangeVisibilityResponse as e, type MessageHandler as f, type ConsumerGroupOptions as g, StreamTransport as h, BadRequestError as i, ConcurrencyLimitError as j, ConsumerDiscoveryError as k, ConsumerRegistryNotConfiguredError as l, DuplicateMessageError as m, InvalidLimitError as n, MessageAlreadyProcessedError as o, MessageCorruptedError as p, MessageLockedError as q, MessageNotAvailableError as r, MessageNotFoundError as s, QueueEmptyError as t, type MessageMetadata as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/queue",
-  "version": "0.0.0-alpha.33",
+  "version": "0.0.0-alpha.34",
   "publishConfig": {
     "access": "public"
   },
@@ -8,9 +8,6 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "bin": {
-    "vercel-queue-local-init": "./bin/local-discover.js"
-  },
   "exports": {
     ".": {
       "import": {
@@ -34,8 +31,7 @@
     }
   },
   "files": [
-    "dist",
-    "bin"
+    "dist"
   ],
   "engines": {
     "node": ">=20.0.0"

package/bin/local-discover.js

@@ -1,196 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Standalone CLI script to discover queue handlers in development mode
- * This script is self-contained and doesn't import from the main package
- */
-
-const fs = require("fs");
-const path = require("path");
-
-function showHelp() {
-  console.log(`
-@vercel/queue local-init - Initialize queue handlers in local development
-
-USAGE:
-  npx vercel-queue-local-init [options]
-
-OPTIONS:
-  --port <number>        Port number for Next.js dev server (default: 3000)
-  --config <path>        Path to vercel.json file (default: ./vercel.json)
-  --help, -h             Show this help message
-
-EXAMPLES:
-  npx vercel-queue-local-init
-  npx vercel-queue-local-init --port 3001
-  npx vercel-queue-local-init --config ./my-vercel.json
-`);
-}
-
-/**
- * Read vercel.json and extract function endpoints with queue triggers
- */
-function readVercelConfig(configPath = "./vercel.json") {
-  try {
-    const fullPath = path.resolve(configPath);
-    const configContent = fs.readFileSync(fullPath, "utf-8");
-    const config = JSON.parse(configContent);
-
-    const routes = [];
-
-    // Extract routes from functions with queue triggers
-    if (config.functions) {
-      for (const [functionPath, functionConfig] of Object.entries(
-        config.functions,
-      )) {
-        if (
-          functionConfig &&
-          typeof functionConfig === "object" &&
-          "experimentalTriggers" in functionConfig
-        ) {
-          const triggers = functionConfig.experimentalTriggers;
-          if (Array.isArray(triggers)) {
-            // Check if any trigger is a queue trigger
-            const hasQueueTrigger = triggers.some(
-              (trigger) =>
-                trigger &&
-                typeof trigger === "object" &&
-                trigger.type === "queue/v1beta",
-            );
-
-            if (hasQueueTrigger) {
-              // Convert file path to API route
-              // Examples:
-              // app/api/vm/queue/route.ts -> /api/vm/queue
-              // app/(dashboard)/api/queue/route.ts -> /api/queue
-              // app/(auth)/login/route.ts -> /login
-              // src/app/api/queue/route.ts -> /api/queue
-              // src/app/(admin)/settings/route.ts -> /settings
-              // pages/api/queue.ts -> /api/queue
-              // src/pages/api/queue.ts -> /api/queue
-              // app/queue/route.ts -> /queue
-              // src/app/webhooks/route.ts -> /webhooks
-              let apiPath = functionPath;
-
-              // Handle src/ prefix
-              if (apiPath.startsWith("src/")) {
-                apiPath = apiPath.replace("src/", "");
-              }
-
-              // Convert Next.js file paths to HTTP routes
-              if (apiPath.startsWith("app/")) {
-                // App Router: app/api/queue/route.ts -> /api/queue
-                // App Router: app/queue/route.ts -> /queue
-                apiPath = apiPath.replace("app/", "/");
-              } else if (apiPath.startsWith("pages/api/")) {
-                // Pages Router: pages/api/queue.ts -> /api/queue
-                apiPath = apiPath.replace("pages/api/", "/api/");
-              } else if (apiPath.startsWith("pages/")) {
-                // Pages Router: pages/queue.ts -> /queue
-                apiPath = apiPath.replace("pages/", "/");
-              } else {
-                // Fallback: assume it's a root-level route
-                apiPath = "/" + apiPath;
-              }
-
-              // Remove Next.js route groups (folders wrapped in parentheses)
-              // Route groups like (dashboard), (auth), (admin) are used for organization
-              // but don't affect the URL structure
-              apiPath = apiPath.replace(/\/\([^)]+\)/g, "");
-
-              // Remove file extensions and Next.js-specific suffixes
-              apiPath = apiPath.replace(
-                /\/(route|index)\.(ts|js|tsx|jsx)$/,
-                "",
-              );
-              apiPath = apiPath.replace(/\.(ts|js|tsx|jsx)$/, "");
-
-              routes.push(apiPath);
-            }
-          }
-        }
-      }
-    }
-
-    return routes;
-  } catch (error) {
-    // vercel.json might not exist or be malformed
-    return [];
-  }
-}
-
-/**
- * Make OPTIONS requests to trigger Next.js lazy loading
- */
-async function discoverQueueHandlers(options = {}) {
-  const baseUrl = options.baseUrl || "http://localhost:3000";
-  const configPath = options.configPath || "./vercel.json";
-
-  let routes = options.routes || [];
-
-  // Auto-discover from vercel.json
-  if (routes.length === 0) {
-    const configRoutes = readVercelConfig(configPath);
-    if (configRoutes.length > 0) {
-      routes = configRoutes;
-      console.log(
-        `[Dev Mode] Found ${configRoutes.length} queue endpoints in vercel.json`,
-      );
-    } else {
-      console.error("[Dev Mode] No queue endpoints found in vercel.json");
-      process.exit(1);
-    }
-  }
-
-  console.log(
-    "[Dev Mode] Making OPTIONS requests to trigger module loading...",
-  );
-
-  for (const route of routes) {
-    try {
-      // Make an OPTIONS request to trigger module loading without processing
-      const response = await fetch(`${baseUrl}${route}`, {
-        method: "OPTIONS",
-        // Add a header to identify this as a discovery request
-        headers: { "x-queue-discovery": "true" },
-      });
-
-      // Any response means the route exists and module was loaded
-      console.log(`[Dev Mode] ✓ ${route} (${response.status})`);
-    } catch (error) {
-      // Ignore errors - route might not exist or server not running
-      console.log(`[Dev Mode] ✗ ${route} (server may not be running)`);
-    }
-  }
-
-  console.log("[Dev Mode] Module loading complete.");
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const options = {};
-
-  // Parse simple command line arguments
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--help" || arg === "-h") {
-      showHelp();
-      return;
-    } else if (arg === "--port" && args[i + 1]) {
-      options.baseUrl = `http://localhost:${args[i + 1]}`;
-      i++;
-    } else if (arg === "--config" && args[i + 1]) {
-      options.configPath = args[i + 1];
-      i++;
-    }
-  }
-
-  try {
-    await discoverQueueHandlers(options);
-  } catch (error) {
-    console.error("Failed to discover queue handlers:", error.message);
-    process.exit(1);
-  }
-}
-
-main();