@vercel/queue 0.0.0-alpha.2 → 0.0.0-alpha.4

package/dist/index.mjs

@@ -1,17 +1,3 @@
-// src/oidc.ts
-async function getVercelOidcToken() {
-  const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
-  const fromSymbol = globalThis;
-  const context = fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
-  const token = context.headers?.["x-vercel-oidc-token"] ?? process.env.VERCEL_OIDC_TOKEN;
-  if (!token) {
-    throw new Error(
-      `The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`
-    );
-  }
-  return token;
-}
-
 // src/client.ts
 import { parseMultipartStream } from "mixpart";
 
@@ -141,13 +127,9 @@ var MessageNotAvailableError = class extends Error {
   }
 };
 var FifoOrderingViolationError = class extends Error {
-  nextMessageId;
-  constructor(messageId, nextMessageId, reason) {
-    super(
-      `FIFO ordering violation for message ${messageId}: ${reason}. Process message ${nextMessageId} first.`
-    );
+  constructor(messageId, reason) {
+    super(`FIFO ordering violation for message ${messageId}: ${reason}`);
     this.name = "FifoOrderingViolationError";
-    this.nextMessageId = nextMessageId;
   }
 };
 var MessageCorruptedError = class extends Error {
@@ -192,13 +174,11 @@ var BadRequestError = class extends Error {
   }
 };
 var FailedDependencyError = class extends Error {
-  nextMessageId;
-  constructor(messageId, nextMessageId) {
+  constructor(messageId) {
     super(
-      `Failed dependency: FIFO ordering violation for message ${messageId}. Must process message ${nextMessageId} first.`
+      `Failed dependency: FIFO ordering violation for message ${messageId}`
     );
     this.name = "FailedDependencyError";
-    this.nextMessageId = nextMessageId;
   }
 };
 var InternalServerError = class extends Error {
@@ -256,32 +236,53 @@ function parseQueueHeaders(headers) {
 var QueueClient = class _QueueClient {
   baseUrl;
   token;
+  /**
+   * Internal default instance for use by createTopic and other convenience functions
+   * @internal
+   */
+  static _defaultInstance = null;
   /**
    * Create a new Vercel Queue Service client
-   * @param options Client configuration options
+   * @param options Client configuration options (optional - will auto-detect Vercel Function environment)
    */
-  constructor(options) {
+  constructor(options = {}) {
     this.baseUrl = options.baseUrl || "https://vqs.vercel.sh";
-    this.token = options.token;
+    if (options.token) {
+      this.token = options.token;
+    } else {
+      const token = this.getVercelOidcTokenSync();
+      if (!token) {
+        throw new Error(
+          "Failed to get OIDC token from Vercel Functions. Make sure you are running in a Vercel Function environment, or provide a token explicitly.\n\nTo set up your environment:\n1. Link your project: 'vercel link'\n2. Pull environment variables: 'vercel env pull'\n3. Run with environment: 'dotenv -e .env.local -- your-command'"
+        );
+      }
+      this.token = token;
+    }
   }
   /**
-   * Create a QueueClient automatically configured for Vercel Functions
-   * This method automatically retrieves the OIDC token from the Vercel Function environment
-   * Always creates a fresh instance since OIDC tokens expire after 15 minutes
-   * @param baseUrl Optional base URL override
-   * @returns Promise resolving to a new QueueClient instance
+   * Get the default client instance for internal use by convenience functions
+   * @internal
    */
-  static async fromVercelFunction(baseUrl) {
-    const token = await getVercelOidcToken();
-    if (!token) {
-      throw new Error(
-        "Failed to get OIDC token from Vercel Functions. Make sure you are running in a Vercel Function environment."
-      );
+  static _getDefaultInstance() {
+    if (!this._defaultInstance) {
+      this._defaultInstance = new _QueueClient();
+    }
+    return this._defaultInstance;
+  }
+  /**
+   * Synchronously get OIDC token from environment
+   * Used internally by constructor - mirrors the logic from getVercelOidcToken but synchronously
+   */
+  getVercelOidcTokenSync() {
+    try {
+      const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+      const fromSymbol = globalThis;
+      const context = fromSymbol[SYMBOL_FOR_REQ_CONTEXT]?.get?.() ?? {};
+      const token = context.headers?.["x-vercel-oidc-token"] ?? process.env.VERCEL_OIDC_TOKEN;
+      return token || null;
+    } catch {
+      return null;
     }
-    return new _QueueClient({
-      token,
-      baseUrl
-    });
   }
   /**
    * Send a message to a queue
@@ -294,7 +295,7 @@ var QueueClient = class _QueueClient {
    * @throws {InternalServerError} When server encounters an error
    */
   async sendMessage(options, transport) {
-    const { queueName, payload, idempotencyKey, retentionSeconds, callbacks } = options;
+    const { queueName, payload, idempotencyKey, retentionSeconds, callback } = options;
     const headers = new Headers({
       Authorization: `Bearer ${this.token}`,
       "Vqs-Queue-Name": queueName,
@@ -306,21 +307,29 @@ var QueueClient = class _QueueClient {
     if (retentionSeconds !== void 0) {
       headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
     }
+    let normalizedCallbacks;
+    if (callback) {
+      if ("url" in callback && typeof callback.url === "string") {
+        normalizedCallbacks = { default: callback };
+      } else {
+        normalizedCallbacks = callback;
+      }
+    }
     let localhostCallbacks = [];
-    if (callbacks) {
+    if (normalizedCallbacks) {
       const isDevelopment = process.env.NODE_ENV === "development";
       if (isDevelopment) {
-        localhostCallbacks = processDevelopmentCallbacks(callbacks);
+        localhostCallbacks = processDevelopmentCallbacks(normalizedCallbacks);
       } else {
-        const endpoints = Object.entries(callbacks).map(
+        const endpoints = Object.entries(normalizedCallbacks).map(
           ([group, config]) => `${group}=${Buffer.from(config.url).toString("base64")}`
         ).join(",");
         headers.set("Vqs-Callback-Url", endpoints);
-        const delays = Object.entries(callbacks).filter(([, config]) => config.delay !== void 0).map(([group, config]) => `${group}=${config.delay}`).join(",");
+        const delays = Object.entries(normalizedCallbacks).filter(([, config]) => config.delay !== void 0).map(([group, config]) => `${group}=${config.delay}`).join(",");
         if (delays) {
           headers.set("Vqs-Callback-Delay", delays);
         }
-        const frequencies = Object.entries(callbacks).filter(([, config]) => config.frequency !== void 0).map(([group, config]) => `${group}=${config.frequency}`).join(",");
+        const frequencies = Object.entries(normalizedCallbacks).filter(([, config]) => config.frequency !== void 0).map(([group, config]) => `${group}=${config.frequency}`).join(",");
         if (frequencies) {
           headers.set("Vqs-Callback-Frequency", frequencies);
         }
@@ -506,36 +515,9 @@ var QueueClient = class _QueueClient {
         throw new MessageLockedError(messageId, retryAfter);
       }
       if (response.status === 424) {
-        try {
-          const errorData = await response.json();
-          if (errorData.meta?.nextMessageId) {
-            throw new FailedDependencyError(
-              messageId,
-              errorData.meta.nextMessageId
-            );
-          }
-        } catch (parseError) {
-          if (parseError instanceof FailedDependencyError) {
-            throw parseError;
-          }
-        }
-        throw new MessageNotAvailableError(
-          messageId,
-          "FIFO ordering violation"
-        );
+        throw new FailedDependencyError(messageId);
       }
       if (response.status === 409) {
-        try {
-          const errorData = await response.json();
-          if (errorData.nextMessageId) {
-            throw new FifoOrderingViolationError(
-              messageId,
-              errorData.nextMessageId,
-              errorData.error
-            );
-          }
-        } catch (parseError) {
-        }
         throw new MessageNotAvailableError(messageId);
       }
       if (response.status >= 500) {
@@ -897,7 +879,11 @@ var ConsumerGroup = class {
       message.ticket
     );
     try {
-      const result = await handler(message);
+      const result = await handler(message.payload, {
+        messageId: message.messageId,
+        deliveryCount: message.deliveryCount,
+        timestamp: message.timestamp
+      });
       await stopExtension();
       if (result && "timeoutSeconds" in result) {
         await this.client.changeVisibility({
@@ -927,219 +913,58 @@ var ConsumerGroup = class {
       throw error;
     }
   }
-  /**
-   * Start continuous processing of messages from the topic
-   * @param signal AbortSignal to control when to stop processing
-   * @param handler Function to process each message
-   * @param options Processing options
-   * @returns Promise that resolves when processing stops (due to signal or error)
-   */
-  async subscribe(signal, handler, options = {}) {
-    const pollingInterval = options.pollingInterval || 1e3;
-    while (!signal.aborted) {
-      try {
-        for await (const message of this.client.receiveMessages(
+  async consume(handler, options) {
+    if (options?.messageId) {
+      if (options.skipPayload) {
+        const response = await this.client.receiveMessageById(
           {
             queueName: this.topicName,
             consumerGroup: this.consumerGroupName,
+            messageId: options.messageId,
             visibilityTimeoutSeconds: this.visibilityTimeout,
-            limit: 1
-            // Always process one message at a time
+            skipPayload: true
           },
           this.transport
-        )) {
-          if (signal.aborted) {
-            break;
-          }
-          try {
-            await this.processMessage(message, handler);
-          } catch (error) {
-            console.error("Error processing message:", error);
-          }
-        }
-        if (!signal.aborted) {
-          await new Promise((resolve) => {
-            const timeoutId = setTimeout(resolve, pollingInterval);
-            signal.addEventListener(
-              "abort",
-              () => {
-                clearTimeout(timeoutId);
-                resolve();
-              },
-              { once: true }
-            );
-          });
-        }
-      } catch (error) {
-        if (error instanceof QueueEmptyError) {
-          if (!signal.aborted) {
-            await new Promise((resolve) => {
-              const timeoutId = setTimeout(resolve, pollingInterval);
-              signal.addEventListener(
-                "abort",
-                () => {
-                  clearTimeout(timeoutId);
-                  resolve();
-                },
-                { once: true }
-              );
-            });
-          }
-          continue;
-        }
-        if (error instanceof MessageLockedError) {
-          const waitTime = error.retryAfter ? error.retryAfter * 1e3 : pollingInterval;
-          if (!signal.aborted) {
-            await new Promise((resolve) => {
-              const timeoutId = setTimeout(resolve, waitTime);
-              signal.addEventListener(
-                "abort",
-                () => {
-                  clearTimeout(timeoutId);
-                  resolve();
-                },
-                { once: true }
-              );
-            });
-          }
-          continue;
-        }
-        console.error("Error polling topic:", error);
-        throw error;
+        );
+        await this.processMessage(
+          response.message,
+          handler
+        );
+      } else {
+        const response = await this.client.receiveMessageById(
+          {
+            queueName: this.topicName,
+            consumerGroup: this.consumerGroupName,
+            messageId: options.messageId,
+            visibilityTimeoutSeconds: this.visibilityTimeout
+          },
+          this.transport
+        );
+        await this.processMessage(
+          response.message,
+          handler
+        );
+      }
+    } else {
+      let messageFound = false;
+      for await (const message of this.client.receiveMessages(
+        {
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          visibilityTimeoutSeconds: this.visibilityTimeout,
+          limit: 1
+        },
+        this.transport
+      )) {
+        messageFound = true;
+        await this.processMessage(message, handler);
+        break;
+      }
+      if (!messageFound) {
+        throw new Error("No messages available");
       }
     }
   }
-  /**
-   * Receive and process a specific message by its ID with full payload
-   * @param messageId The ID of the message to receive and process
-   * @param handler Function to process the message with full payload
-   * @returns Promise that resolves when the message is processed or rejects with specific errors
-   * @throws {MessageNotFoundError} When the message doesn't exist (404)
-   * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
-   * @throws {MessageLockedError} When the message is temporarily locked (423)
-   * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
-   * @throws {FailedDependencyError} When FIFO ordering is violated (424)
-   * @throws {MessageCorruptedError} When the message data is corrupted
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async receiveMessage(messageId, handler) {
-    const response = await this.client.receiveMessageById(
-      {
-        queueName: this.topicName,
-        consumerGroup: this.consumerGroupName,
-        messageId,
-        visibilityTimeoutSeconds: this.visibilityTimeout
-      },
-      this.transport
-    );
-    await this.processMessage(response.message, handler);
-  }
-  /**
-   * Receive and process the next available message from the queue
-   * @param handler Function to process the message
-   * @returns Promise that resolves when the message is processed or rejects with specific errors
-   * @throws {QueueEmptyError} When no messages are available in the queue (204)
-   * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async receiveNextMessage(handler) {
-    let messageFound = false;
-    for await (const message of this.client.receiveMessages(
-      {
-        queueName: this.topicName,
-        consumerGroup: this.consumerGroupName,
-        visibilityTimeoutSeconds: this.visibilityTimeout,
-        limit: 1
-      },
-      this.transport
-    )) {
-      messageFound = true;
-      await this.processMessage(message, handler);
-      break;
-    }
-    if (!messageFound) {
-      throw new Error("No messages available");
-    }
-  }
-  /**
-   * Receive and process multiple next available messages from the queue
-   * @param limit Number of messages to process (1-10)
-   * @param handler Function to process each message
-   * @returns Promise that resolves to an array of PromiseSettledResult (same as Promise.allSettled)
-   * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
-   * @throws {QueueEmptyError} When no messages are available in the queue (204)
-   * @throws {MessageLockedError} When the next message in a FIFO queue is locked (423)
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async receiveNextMessages(limit, handler) {
-    if (limit < 1 || limit > 10) {
-      throw new InvalidLimitError(limit);
-    }
-    const processingPromises = [];
-    let messageCount = 0;
-    for await (const message of this.client.receiveMessages(
-      {
-        queueName: this.topicName,
-        consumerGroup: this.consumerGroupName,
-        visibilityTimeoutSeconds: this.visibilityTimeout,
-        limit
-      },
-      this.transport
-    )) {
-      messageCount++;
-      const wrappedPromise = this.processMessage(message, handler).then(
-        (value) => ({
-          status: "fulfilled",
-          value
-        }),
-        (reason) => ({ status: "rejected", reason })
-      );
-      processingPromises.push(wrappedPromise);
-    }
-    if (messageCount === 0) {
-      throw new Error("No messages available");
-    }
-    const results = await Promise.all(processingPromises);
-    return results;
-  }
-  /**
-   * Handle a specific message by its ID without downloading the payload (metadata only)
-   * @param messageId The ID of the message to handle
-   * @param handler Function to process the message metadata (payload will be void)
-   * @returns Promise that resolves when the message is handled or rejects with specific errors
-   * @throws {MessageNotFoundError} When the message doesn't exist (404)
-   * @throws {MessageNotAvailableError} When the message exists but isn't available for processing (409)
-   * @throws {MessageLockedError} When the message is temporarily locked (423)
-   * @throws {FifoOrderingViolationError} When there's a FIFO ordering violation (409 with nextMessageId)
-   * @throws {FailedDependencyError} When FIFO ordering is violated (424)
-   * @throws {MessageCorruptedError} When the message data is corrupted
-   * @throws {BadRequestError} When request parameters are invalid
-   * @throws {UnauthorizedError} When authentication fails
-   * @throws {ForbiddenError} When access is denied
-   * @throws {InternalServerError} When server encounters an error
-   */
-  async handleMessage(messageId, handler) {
-    const response = await this.client.receiveMessageById(
-      {
-        queueName: this.topicName,
-        consumerGroup: this.consumerGroupName,
-        messageId,
-        visibilityTimeoutSeconds: this.visibilityTimeout,
-        skipPayload: true
-      },
-      this.transport
-    );
-    await this.processMessage(response.message, handler);
-  }
   /**
    * Get the consumer group name
    */
@@ -1187,7 +1012,7 @@ var Topic = class {
         payload,
         idempotencyKey: options?.idempotencyKey,
         retentionSeconds: options?.retentionSeconds,
-        callbacks: options?.callbacks
+        callback: options?.callback
       },
       this.transport
     );
@@ -1226,9 +1051,43 @@ var Topic = class {
 };
 
 // src/factory.ts
-function createTopic(client, topicName, transport) {
+function createTopic(topicName, transport) {
+  const client = QueueClient._getDefaultInstance();
   return new Topic(client, topicName, transport);
 }
+async function send(topicName, payload, options) {
+  const transport = options?.transport || new JsonTransport();
+  const client = QueueClient._getDefaultInstance();
+  const result = await client.sendMessage(
+    {
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds,
+      callback: options?.callback
+    },
+    transport
+  );
+  return { messageId: result.messageId };
+}
+async function receive(topicName, consumerGroup, handler, options) {
+  const transport = options?.transport || new JsonTransport();
+  const topic = createTopic(topicName, transport);
+  const { messageId, skipPayload, ...consumerGroupOptions } = options || {};
+  const consumer = topic.consumerGroup(consumerGroup, consumerGroupOptions);
+  if (messageId) {
+    if (skipPayload) {
+      return consumer.consume(handler, {
+        messageId,
+        skipPayload: true
+      });
+    } else {
+      return consumer.consume(handler, { messageId });
+    }
+  } else {
+    return consumer.consume(handler);
+  }
+}
 
 // src/callback.ts
 function parseCallbackRequest(request) {
@@ -1251,6 +1110,52 @@ function parseCallbackRequest(request) {
     consumerGroup
   };
 }
+function handleCallback(handlers) {
+  return async (request) => {
+    try {
+      const { queueName, consumerGroup, messageId } = parseCallbackRequest(request);
+      const topicHandler = handlers[queueName];
+      if (!topicHandler) {
+        throw new Error(`No handler found for topic: ${queueName}`);
+      }
+      let actualHandler;
+      if (typeof topicHandler === "function") {
+        if (consumerGroup !== "default") {
+          throw new Error(
+            `Topic "${queueName}" has a single handler but received consumer group "${consumerGroup}". Expected "default".`
+          );
+        }
+        actualHandler = topicHandler;
+      } else {
+        const consumerGroupHandler = topicHandler[consumerGroup];
+        if (!consumerGroupHandler) {
+          const availableGroups = Object.keys(topicHandler).join(", ");
+          throw new Error(
+            `No handler found for consumer group "${consumerGroup}" in topic "${queueName}". Available groups: ${availableGroups}`
+          );
+        }
+        actualHandler = consumerGroupHandler;
+      }
+      const client = new QueueClient();
+      const topic = new Topic(client, queueName);
+      const cg = topic.consumerGroup(consumerGroup);
+      await cg.consume(actualHandler, { messageId });
+      return Response.json({ status: "success" });
+    } catch (error) {
+      console.error("Callback error:", error);
+      if (error instanceof InvalidCallbackError) {
+        return Response.json(
+          { error: "Invalid callback request" },
+          { status: 400 }
+        );
+      }
+      return Response.json(
+        { error: "Failed to process callback" },
+        { status: 500 }
+      );
+    }
+  };
+}
 export {
   BadRequestError,
   BufferTransport,
@@ -1272,7 +1177,9 @@ export {
   Topic,
   UnauthorizedError,
   createTopic,
-  getVercelOidcToken,
-  parseCallbackRequest
+  handleCallback,
+  parseCallbackRequest,
+  receive,
+  send
 };
 //# sourceMappingURL=index.mjs.map