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

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

@@ -50,7 +50,7 @@ declare class BufferTransport implements Transport<Buffer> {
  *
  * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
  * processing the message to prevent resource leaks, especially in error cases.
- * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
+ * ConsumerGroup handles this automatically, but direct Client usage requires manual cleanup.
  *
  * Example usage:
  * ```typescript
@@ -77,6 +77,44 @@ declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
  * Vercel Queue Service client types
  */
 
+interface QueueClientOptions {
+    /**
+     * Base URL for the Vercel Queue Service API
+     * Can also be set via VERCEL_QUEUE_BASE_URL environment variable
+     * @default "https://vercel-queue.com"
+     */
+    baseUrl?: string;
+    /**
+     * Base path for API endpoints
+     * Can also be set via VERCEL_QUEUE_BASE_PATH environment variable
+     * @default "/api/v3/topic"
+     */
+    basePath?: string;
+    /**
+     * Authentication token for the Vercel Queue Service API
+     * If not provided, the client will attempt to get a token via OIDC
+     */
+    token?: string;
+    /**
+     * 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
  */
@@ -94,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 {
     /**
@@ -139,23 +178,79 @@ 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;
 }
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
+interface ReceiveMessagesOptions<T = unknown> {
+    /**
+     * The queue name to receive messages from
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
     /**
-     * Time in seconds before the message becomes visible again
+     * Time in seconds that messages will be invisible to other consumers
+     * @default 30
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum number of messages to retrieve
+     * @default 1
+     * @max 10
+     */
+    limit?: number;
+    /**
+     * Maximum concurrent in-flight messages
      */
-    timeoutSeconds: number;
+    maxConcurrency?: number;
+}
+interface DeleteMessageOptions {
+    /**
+     * The queue name the message belongs to
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received from the message
+     */
+    receiptHandle: string;
+}
+interface DeleteMessageResponse {
+    /**
+     * Whether the message was successfully deleted
+     */
+    deleted: boolean;
+}
+interface ChangeVisibilityOptions {
+    /**
+     * The queue name the message belongs to
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received from the message
+     */
+    receiptHandle: string;
+    /**
+     * New visibility timeout in seconds
+     */
+    visibilityTimeoutSeconds: number;
+}
+interface ChangeVisibilityResponse {
+    /**
+     * Whether the visibility was successfully updated
+     */
+    success: boolean;
 }
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
 /**
  * Message metadata provided to handlers
  */
@@ -169,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
  */
@@ -190,6 +285,32 @@ interface ConsumerGroupOptions<T = unknown> {
      */
     refreshInterval?: number;
 }
+interface ReceiveMessageByIdOptions<T = unknown> {
+    /**
+     * The queue name to receive the message from
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * The message ID to retrieve
+     */
+    messageId: string;
+    /**
+     * Time in seconds that the message will be invisible to other consumers
+     * @default 30
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum concurrent in-flight messages
+     */
+    maxConcurrency?: number;
+}
+interface ReceiveMessageByIdResponse<T = unknown> {
+    message: Message<T>;
+}
 /**
  * Error thrown when a message is not found (404)
  */
@@ -252,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 ConsumerGroupOptions as C, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type MessageHandler as M, type PublishOptions as P, QueueEmptyError as Q, StreamTransport as S, type Transport as T, UnauthorizedError as U, BadRequestError as a, InvalidLimitError as b, MessageCorruptedError as c, MessageLockedError as d, MessageNotAvailableError as e, MessageNotFoundError as f, type Message as g, type MessageHandlerResult as h, type MessageMetadata as i, type MessageTimeoutResult as j, type SendMessageOptions as k, type SendMessageResponse as l };
+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-JvOenjfT.d.ts → types-BHtRP_i_.d.ts}

@@ -50,7 +50,7 @@ declare class BufferTransport implements Transport<Buffer> {
  *
  * IMPORTANT: When using StreamTransport, you must call finalize(payload) when done
  * processing the message to prevent resource leaks, especially in error cases.
- * ConsumerGroup handles this automatically, but direct QueueClient usage requires manual cleanup.
+ * ConsumerGroup handles this automatically, but direct Client usage requires manual cleanup.
  *
  * Example usage:
  * ```typescript
@@ -77,6 +77,44 @@ declare class StreamTransport implements Transport<ReadableStream<Uint8Array>> {
  * Vercel Queue Service client types
  */
 
+interface QueueClientOptions {
+    /**
+     * Base URL for the Vercel Queue Service API
+     * Can also be set via VERCEL_QUEUE_BASE_URL environment variable
+     * @default "https://vercel-queue.com"
+     */
+    baseUrl?: string;
+    /**
+     * Base path for API endpoints
+     * Can also be set via VERCEL_QUEUE_BASE_PATH environment variable
+     * @default "/api/v3/topic"
+     */
+    basePath?: string;
+    /**
+     * Authentication token for the Vercel Queue Service API
+     * If not provided, the client will attempt to get a token via OIDC
+     */
+    token?: string;
+    /**
+     * 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
  */
@@ -94,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 {
     /**
@@ -139,23 +178,79 @@ 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;
 }
-/**
- * Result indicating the message should be timed out for retry later
- */
-interface MessageTimeoutResult {
+interface ReceiveMessagesOptions<T = unknown> {
+    /**
+     * The queue name to receive messages from
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
     /**
-     * Time in seconds before the message becomes visible again
+     * Time in seconds that messages will be invisible to other consumers
+     * @default 30
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum number of messages to retrieve
+     * @default 1
+     * @max 10
+     */
+    limit?: number;
+    /**
+     * Maximum concurrent in-flight messages
      */
-    timeoutSeconds: number;
+    maxConcurrency?: number;
+}
+interface DeleteMessageOptions {
+    /**
+     * The queue name the message belongs to
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received from the message
+     */
+    receiptHandle: string;
+}
+interface DeleteMessageResponse {
+    /**
+     * Whether the message was successfully deleted
+     */
+    deleted: boolean;
+}
+interface ChangeVisibilityOptions {
+    /**
+     * The queue name the message belongs to
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * Receipt handle received from the message
+     */
+    receiptHandle: string;
+    /**
+     * New visibility timeout in seconds
+     */
+    visibilityTimeoutSeconds: number;
+}
+interface ChangeVisibilityResponse {
+    /**
+     * Whether the visibility was successfully updated
+     */
+    success: boolean;
 }
-/**
- * Result returned by message handlers
- */
-type MessageHandlerResult = void | MessageTimeoutResult;
 /**
  * Message metadata provided to handlers
  */
@@ -169,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
  */
@@ -190,6 +285,32 @@ interface ConsumerGroupOptions<T = unknown> {
      */
     refreshInterval?: number;
 }
+interface ReceiveMessageByIdOptions<T = unknown> {
+    /**
+     * The queue name to receive the message from
+     */
+    queueName: string;
+    /**
+     * Consumer group name
+     */
+    consumerGroup: string;
+    /**
+     * The message ID to retrieve
+     */
+    messageId: string;
+    /**
+     * Time in seconds that the message will be invisible to other consumers
+     * @default 30
+     */
+    visibilityTimeoutSeconds?: number;
+    /**
+     * Maximum concurrent in-flight messages
+     */
+    maxConcurrency?: number;
+}
+interface ReceiveMessageByIdResponse<T = unknown> {
+    message: Message<T>;
+}
 /**
  * Error thrown when a message is not found (404)
  */
@@ -252,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 ConsumerGroupOptions as C, ForbiddenError as F, InternalServerError as I, JsonTransport as J, type MessageHandler as M, type PublishOptions as P, QueueEmptyError as Q, StreamTransport as S, type Transport as T, UnauthorizedError as U, BadRequestError as a, InvalidLimitError as b, MessageCorruptedError as c, MessageLockedError as d, MessageNotAvailableError as e, MessageNotFoundError as f, type Message as g, type MessageHandlerResult as h, type MessageMetadata as i, type MessageTimeoutResult as j, type SendMessageOptions as k, type SendMessageResponse as l };
+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.32",
+  "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"