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

package/dist/index.mjs

@@ -137,6 +137,9 @@ var InvalidLimitError = class extends Error {
 };
 
 // src/client.ts
+function isDebugEnabled() {
+  return process.env.VERCEL_QUEUE_DEBUG === "1" || process.env.VERCEL_QUEUE_DEBUG === "true";
+}
 async function consumeStream(stream) {
   const reader = stream.getReader();
   try {
@@ -148,6 +151,31 @@ async function consumeStream(stream) {
     reader.releaseLock();
   }
 }
+function parseRetryAfter(headers) {
+  const retryAfterHeader = headers.get("Retry-After");
+  if (retryAfterHeader) {
+    const parsed = parseInt(retryAfterHeader, 10);
+    return Number.isNaN(parsed) ? void 0 : parsed;
+  }
+  return void 0;
+}
+function throwCommonHttpError(status, statusText, errorText, operation, badRequestDefault = "Invalid parameters") {
+  if (status === 400) {
+    throw new BadRequestError(errorText || badRequestDefault);
+  }
+  if (status === 401) {
+    throw new UnauthorizedError(errorText || void 0);
+  }
+  if (status === 403) {
+    throw new ForbiddenError(errorText || void 0);
+  }
+  if (status >= 500) {
+    throw new InternalServerError(
+      errorText || `Server error: ${status} ${statusText}`
+    );
+  }
+  throw new Error(`Failed to ${operation}: ${status} ${statusText}`);
+}
 function parseQueueHeaders(headers) {
   const messageId = headers.get("Vqs-Message-Id");
   const deliveryCountStr = headers.get("Vqs-Delivery-Count") || "0";
@@ -158,7 +186,7 @@ function parseQueueHeaders(headers) {
     return null;
   }
   const deliveryCount = parseInt(deliveryCountStr, 10);
-  if (isNaN(deliveryCount)) {
+  if (Number.isNaN(deliveryCount)) {
     return null;
   }
   return {
@@ -172,24 +200,22 @@ function parseQueueHeaders(headers) {
 var QueueClient = class {
   baseUrl;
   basePath;
-  customHeaders = {};
+  customHeaders;
+  providedToken;
   /**
    * Create a new Vercel Queue Service client
-   * @param options Client configuration options
+   * @param options QueueClient configuration options
    */
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || process.env.VERCEL_QUEUE_BASE_URL || "https://vercel-queue.com";
     this.basePath = options.basePath || process.env.VERCEL_QUEUE_BASE_PATH || "/api/v2/messages";
-    const VERCEL_QUEUE_HEADER_PREFIX = "VERCEL_QUEUE_HEADER_";
-    this.customHeaders = Object.fromEntries(
-      Object.entries(process.env).filter(([key]) => key.startsWith(VERCEL_QUEUE_HEADER_PREFIX)).map(([key, value]) => [
-        // This allows headers to use dashes independent of shell used
-        key.replace(VERCEL_QUEUE_HEADER_PREFIX, "").replaceAll("__", "-"),
-        value || ""
-      ])
-    );
+    this.customHeaders = options.headers || {};
+    this.providedToken = options.token;
   }
   async getToken() {
+    if (this.providedToken) {
+      return this.providedToken;
+    }
     const token = await getVercelOidcToken();
     if (!token) {
       throw new Error(
@@ -198,6 +224,45 @@ var QueueClient = class {
     }
     return token;
   }
+  /**
+   * Internal fetch wrapper that automatically handles debug logging
+   * when VERCEL_QUEUE_DEBUG is enabled
+   */
+  async fetch(url, init) {
+    const method = init.method || "GET";
+    if (isDebugEnabled()) {
+      const logData = {
+        method,
+        url,
+        headers: init.headers
+      };
+      const body = init.body;
+      if (body !== void 0 && body !== null) {
+        if (body instanceof ArrayBuffer) {
+          logData.bodySize = body.byteLength;
+        } else if (body instanceof Uint8Array) {
+          logData.bodySize = body.byteLength;
+        } else if (typeof body === "string") {
+          logData.bodySize = body.length;
+        } else {
+          logData.bodyType = typeof body;
+        }
+      }
+      console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
+    }
+    const response = await fetch(url, init);
+    if (isDebugEnabled()) {
+      const logData = {
+        method,
+        url,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+      };
+      console.debug("[VQS Debug] Response:", JSON.stringify(logData, null, 2));
+    }
+    return response;
+  }
   /**
    * Send a message to a queue
    * @param options Send message options
@@ -227,32 +292,21 @@ var QueueClient = class {
       headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
     }
     const body = transport.serialize(payload);
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
+    const response = await this.fetch(`${this.baseUrl}${this.basePath}`, {
       method: "POST",
       body,
       headers
     });
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 409) {
         throw new Error("Duplicate idempotency key detected");
       }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
-        );
-      }
-      throw new Error(
-        `Failed to send message: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "send message"
       );
     }
     const responseData = await response.json();
@@ -292,7 +346,7 @@ var QueueClient = class {
     if (limit !== void 0) {
       headers.set("Vqs-Limit", limit.toString());
     }
-    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
+    const response = await this.fetch(`${this.baseUrl}${this.basePath}`, {
       method: "GET",
       headers
     });
@@ -300,32 +354,18 @@ var QueueClient = class {
       throw new QueueEmptyError(queueName, consumerGroup);
     }
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 423) {
-        const retryAfterHeader = response.headers.get("Retry-After");
-        let retryAfter;
-        if (retryAfterHeader) {
-          const parsed = parseInt(retryAfterHeader, 10);
-          retryAfter = isNaN(parsed) ? void 0 : parsed;
-        }
-        throw new MessageLockedError("next message", retryAfter);
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+        throw new MessageLockedError(
+          "next message",
+          parseRetryAfter(response.headers)
         );
       }
-      throw new Error(
-        `Failed to receive messages: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive messages"
       );
     }
     for await (const multipartMessage of parseMultipartStream(response)) {
@@ -374,7 +414,7 @@ var QueueClient = class {
     if (skipPayload) {
       headers.set("Vqs-Skip-Payload", "1");
     }
-    const response = await fetch(
+    const response = await this.fetch(
       `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "GET",
@@ -382,38 +422,24 @@ var QueueClient = class {
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        const errorText = await response.text();
-        throw new BadRequestError(errorText || "Invalid parameters");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
         throw new MessageNotFoundError(messageId);
       }
-      if (response.status === 423) {
-        const retryAfterHeader = response.headers.get("Retry-After");
-        let retryAfter;
-        if (retryAfterHeader) {
-          const parsed = parseInt(retryAfterHeader, 10);
-          retryAfter = isNaN(parsed) ? void 0 : parsed;
-        }
-        throw new MessageLockedError(messageId, retryAfter);
-      }
       if (response.status === 409) {
         throw new MessageNotAvailableError(messageId);
       }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+      if (response.status === 423) {
+        throw new MessageLockedError(
+          messageId,
+          parseRetryAfter(response.headers)
         );
       }
-      throw new Error(
-        `Failed to receive message by ID: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "receive message by ID"
       );
     }
     if (skipPayload && response.status === 204) {
@@ -483,7 +509,7 @@ var QueueClient = class {
    */
   async deleteMessage(options) {
     const { queueName, consumerGroup, messageId, ticket } = options;
-    const response = await fetch(
+    const response = await this.fetch(
       `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "DELETE",
@@ -497,31 +523,22 @@ var QueueClient = class {
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        throw new BadRequestError("Missing or invalid ticket");
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
         throw new MessageNotFoundError(messageId);
       }
       if (response.status === 409) {
         throw new MessageNotAvailableError(
           messageId,
-          "Invalid ticket, message not in correct state, or already processed"
-        );
-      }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
+          errorText || "Invalid ticket, message not in correct state, or already processed"
         );
       }
-      throw new Error(
-        `Failed to delete message: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "delete message",
+        "Missing or invalid ticket"
       );
     }
     return { deleted: true };
@@ -545,7 +562,7 @@ var QueueClient = class {
       ticket,
       visibilityTimeoutSeconds
     } = options;
-    const response = await fetch(
+    const response = await this.fetch(
       `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "PATCH",
@@ -560,165 +577,28 @@ var QueueClient = class {
       }
     );
     if (!response.ok) {
-      if (response.status === 400) {
-        throw new BadRequestError(
-          "Missing ticket or invalid visibility timeout"
-        );
-      }
-      if (response.status === 401) {
-        throw new UnauthorizedError();
-      }
-      if (response.status === 403) {
-        throw new ForbiddenError();
-      }
+      const errorText = await response.text();
       if (response.status === 404) {
         throw new MessageNotFoundError(messageId);
       }
       if (response.status === 409) {
         throw new MessageNotAvailableError(
           messageId,
-          "Invalid ticket, message not in correct state, or already processed"
+          errorText || "Invalid ticket, message not in correct state, or already processed"
         );
       }
-      if (response.status >= 500) {
-        throw new InternalServerError(
-          `Server error: ${response.status} ${response.statusText}`
-        );
-      }
-      throw new Error(
-        `Failed to change visibility: ${response.status} ${response.statusText}`
+      throwCommonHttpError(
+        response.status,
+        response.statusText,
+        errorText,
+        "change visibility",
+        "Missing ticket or invalid visibility timeout"
       );
     }
     return { updated: true };
   }
 };
 
-// src/callback.ts
-function validateWildcardPattern(pattern) {
-  const firstIndex = pattern.indexOf("*");
-  const lastIndex = pattern.lastIndexOf("*");
-  if (firstIndex !== lastIndex) {
-    return false;
-  }
-  if (firstIndex === -1) {
-    return false;
-  }
-  if (firstIndex !== pattern.length - 1) {
-    return false;
-  }
-  return true;
-}
-function matchesWildcardPattern(topicName, pattern) {
-  const prefix = pattern.slice(0, -1);
-  return topicName.startsWith(prefix);
-}
-function findTopicHandler(queueName, handlers) {
-  const exactHandler = handlers[queueName];
-  if (exactHandler) {
-    return exactHandler;
-  }
-  for (const pattern in handlers) {
-    if (pattern.includes("*") && matchesWildcardPattern(queueName, pattern)) {
-      return handlers[pattern];
-    }
-  }
-  return null;
-}
-async function parseCallback(request) {
-  const contentType = request.headers.get("content-type");
-  if (!contentType || !contentType.includes("application/cloudevents+json")) {
-    throw new Error(
-      "Invalid content type: expected 'application/cloudevents+json'"
-    );
-  }
-  let cloudEvent;
-  try {
-    cloudEvent = await request.json();
-  } catch (error) {
-    throw new Error("Failed to parse CloudEvent from request body");
-  }
-  if (!cloudEvent.type || !cloudEvent.source || !cloudEvent.id || typeof cloudEvent.data !== "object" || cloudEvent.data == null) {
-    throw new Error("Invalid CloudEvent: missing required fields");
-  }
-  if (cloudEvent.type !== "com.vercel.queue.v1beta") {
-    throw new Error(
-      `Invalid CloudEvent type: expected 'com.vercel.queue.v1beta', got '${cloudEvent.type}'`
-    );
-  }
-  const missingFields = [];
-  if (!("queueName" in cloudEvent.data)) missingFields.push("queueName");
-  if (!("consumerGroup" in cloudEvent.data))
-    missingFields.push("consumerGroup");
-  if (!("messageId" in cloudEvent.data)) missingFields.push("messageId");
-  if (missingFields.length > 0) {
-    throw new Error(
-      `Missing required CloudEvent data fields: ${missingFields.join(", ")}`
-    );
-  }
-  const { messageId, queueName, consumerGroup } = cloudEvent.data;
-  return {
-    queueName,
-    consumerGroup,
-    messageId
-  };
-}
-function handleCallback(handlers) {
-  for (const topicPattern in handlers) {
-    if (topicPattern.includes("*")) {
-      if (!validateWildcardPattern(topicPattern)) {
-        throw new Error(
-          `Invalid wildcard pattern "${topicPattern}": * may only appear once and must be at the end of the topic name`
-        );
-      }
-    }
-  }
-  const routeHandler = async (request) => {
-    try {
-      const { queueName, consumerGroup, messageId } = await parseCallback(request);
-      const topicHandler = findTopicHandler(queueName, handlers);
-      if (!topicHandler) {
-        const availableTopics = Object.keys(handlers).join(", ");
-        return Response.json(
-          {
-            error: `No handler found for topic: ${queueName}`,
-            availableTopics
-          },
-          { status: 404 }
-        );
-      }
-      const consumerGroupHandler = topicHandler[consumerGroup];
-      if (!consumerGroupHandler) {
-        const availableGroups = Object.keys(topicHandler).join(", ");
-        return Response.json(
-          {
-            error: `No handler found for consumer group "${consumerGroup}" in topic "${queueName}".`,
-            availableGroups
-          },
-          { status: 404 }
-        );
-      }
-      const client = new QueueClient();
-      const topic = new Topic(client, queueName);
-      const cg = topic.consumerGroup(consumerGroup);
-      await cg.consume(consumerGroupHandler, { messageId });
-      return Response.json({ status: "success" });
-    } catch (error) {
-      console.error("Queue callback error:", error);
-      if (error instanceof Error && (error.message.includes("Missing required CloudEvent data fields") || error.message.includes("Invalid CloudEvent") || error.message.includes("Invalid CloudEvent type") || error.message.includes("Invalid content type") || error.message.includes("Failed to parse CloudEvent"))) {
-        return Response.json({ error: error.message }, { status: 400 });
-      }
-      return Response.json(
-        { error: "Failed to process queue message" },
-        { status: 500 }
-      );
-    }
-  };
-  if (isDevMode()) {
-    registerDevRouteHandler(routeHandler, handlers);
-  }
-  return routeHandler;
-}
-
 // src/dev.ts
 var GLOBAL_KEY = Symbol.for("@vercel/queue.devHandlers");
 function getDevHandlerState() {
@@ -1183,10 +1063,138 @@ var Topic = class {
   }
 };
 
+// src/callback.ts
+function validateWildcardPattern(pattern) {
+  const firstIndex = pattern.indexOf("*");
+  const lastIndex = pattern.lastIndexOf("*");
+  if (firstIndex !== lastIndex) {
+    return false;
+  }
+  if (firstIndex === -1) {
+    return false;
+  }
+  if (firstIndex !== pattern.length - 1) {
+    return false;
+  }
+  return true;
+}
+function matchesWildcardPattern(topicName, pattern) {
+  const prefix = pattern.slice(0, -1);
+  return topicName.startsWith(prefix);
+}
+function findTopicHandler(queueName, handlers) {
+  const exactHandler = handlers[queueName];
+  if (exactHandler) {
+    return exactHandler;
+  }
+  for (const pattern in handlers) {
+    if (pattern.includes("*") && matchesWildcardPattern(queueName, pattern)) {
+      return handlers[pattern];
+    }
+  }
+  return null;
+}
+async function parseCallback(request) {
+  const contentType = request.headers.get("content-type");
+  if (!contentType || !contentType.includes("application/cloudevents+json")) {
+    throw new Error(
+      "Invalid content type: expected 'application/cloudevents+json'"
+    );
+  }
+  let cloudEvent;
+  try {
+    cloudEvent = await request.json();
+  } catch (error) {
+    throw new Error("Failed to parse CloudEvent from request body");
+  }
+  if (!cloudEvent.type || !cloudEvent.source || !cloudEvent.id || typeof cloudEvent.data !== "object" || cloudEvent.data == null) {
+    throw new Error("Invalid CloudEvent: missing required fields");
+  }
+  if (cloudEvent.type !== "com.vercel.queue.v1beta") {
+    throw new Error(
+      `Invalid CloudEvent type: expected 'com.vercel.queue.v1beta', got '${cloudEvent.type}'`
+    );
+  }
+  const missingFields = [];
+  if (!("queueName" in cloudEvent.data)) missingFields.push("queueName");
+  if (!("consumerGroup" in cloudEvent.data))
+    missingFields.push("consumerGroup");
+  if (!("messageId" in cloudEvent.data)) missingFields.push("messageId");
+  if (missingFields.length > 0) {
+    throw new Error(
+      `Missing required CloudEvent data fields: ${missingFields.join(", ")}`
+    );
+  }
+  const { messageId, queueName, consumerGroup } = cloudEvent.data;
+  return {
+    queueName,
+    consumerGroup,
+    messageId
+  };
+}
+function createCallbackHandler(handlers, client) {
+  for (const topicPattern in handlers) {
+    if (topicPattern.includes("*")) {
+      if (!validateWildcardPattern(topicPattern)) {
+        throw new Error(
+          `Invalid wildcard pattern "${topicPattern}": * may only appear once and must be at the end of the topic name`
+        );
+      }
+    }
+  }
+  const routeHandler = async (request) => {
+    try {
+      const { queueName, consumerGroup, messageId } = await parseCallback(request);
+      const topicHandler = findTopicHandler(queueName, handlers);
+      if (!topicHandler) {
+        const availableTopics = Object.keys(handlers).join(", ");
+        return Response.json(
+          {
+            error: `No handler found for topic: ${queueName}`,
+            availableTopics
+          },
+          { status: 404 }
+        );
+      }
+      const consumerGroupHandler = topicHandler[consumerGroup];
+      if (!consumerGroupHandler) {
+        const availableGroups = Object.keys(topicHandler).join(", ");
+        return Response.json(
+          {
+            error: `No handler found for consumer group "${consumerGroup}" in topic "${queueName}".`,
+            availableGroups
+          },
+          { status: 404 }
+        );
+      }
+      const topic = new Topic(client, queueName);
+      const cg = topic.consumerGroup(consumerGroup);
+      await cg.consume(consumerGroupHandler, { messageId });
+      return Response.json({ status: "success" });
+    } catch (error) {
+      console.error("Queue callback error:", error);
+      if (error instanceof Error && (error.message.includes("Missing required CloudEvent data fields") || error.message.includes("Invalid CloudEvent") || error.message.includes("Invalid CloudEvent type") || error.message.includes("Invalid content type") || error.message.includes("Failed to parse CloudEvent"))) {
+        return Response.json({ error: error.message }, { status: 400 });
+      }
+      return Response.json(
+        { error: "Failed to process queue message" },
+        { status: 500 }
+      );
+    }
+  };
+  if (isDevMode()) {
+    registerDevRouteHandler(routeHandler, handlers);
+  }
+  return routeHandler;
+}
+function handleCallback(handlers, client) {
+  return createCallbackHandler(handlers, client || new QueueClient());
+}
+
 // src/factory.ts
 async function send(topicName, payload, options) {
   const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
+  const client = options?.client || new QueueClient();
   const result = await client.sendMessage(
     {
       queueName: topicName,
@@ -1204,9 +1212,14 @@ async function send(topicName, payload, options) {
 }
 async function receive(topicName, consumerGroup, handler, options) {
   const transport = options?.transport || new JsonTransport();
-  const client = new QueueClient();
+  const client = options?.client || new QueueClient();
   const topic = new Topic(client, topicName, transport);
-  const { messageId, skipPayload, ...consumerGroupOptions } = options || {};
+  const {
+    messageId,
+    skipPayload,
+    client: _,
+    ...consumerGroupOptions
+  } = options || {};
   const consumer = topic.consumerGroup(consumerGroup, consumerGroupOptions);
   if (messageId) {
     if (skipPayload) {
@@ -1221,9 +1234,58 @@ async function receive(topicName, consumerGroup, handler, options) {
     return consumer.consume(handler);
   }
 }
+
+// src/queue-client.ts
+var Client = class {
+  client;
+  /**
+   * Create a new Client
+   * @param options QueueClient configuration options
+   */
+  constructor(options = {}) {
+    this.client = new QueueClient(options);
+  }
+  /**
+   * Send a message to a topic
+   * @param topicName Name of the topic to send to
+   * @param payload The data to send
+   * @param options Optional publish options and transport
+   * @returns Promise with the message ID
+   * @throws {BadRequestError} When request parameters are invalid
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied (environment mismatch)
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async send(topicName, payload, options) {
+    return send(topicName, payload, {
+      ...options,
+      client: this.client
+    });
+  }
+  /**
+   * Create a callback handler for processing queue messages
+   * Returns a Next.js route handler function that routes messages to appropriate handlers
+   * @param handlers Object with topic-specific handlers organized by consumer groups
+   * @returns A Next.js route handler function
+   *
+   * @example
+   * ```typescript
+   * export const POST = client.handleCallback({
+   *   "user-events": {
+   *     "welcome": (user, metadata) => console.log("Welcoming user", user),
+   *     "analytics": (user, metadata) => console.log("Tracking user", user),
+   *   },
+   * });
+   * ```
+   */
+  handleCallback(handlers) {
+    return handleCallback(handlers, this.client);
+  }
+};
 export {
   BadRequestError,
   BufferTransport,
+  Client,
   ForbiddenError,
   InternalServerError,
   InvalidLimitError,