@vercel/queue 0.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,1326 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BadRequestError: () => BadRequestError,
+  BufferTransport: () => BufferTransport,
+  ConsumerGroup: () => ConsumerGroup,
+  FailedDependencyError: () => FailedDependencyError,
+  FifoOrderingViolationError: () => FifoOrderingViolationError,
+  ForbiddenError: () => ForbiddenError,
+  InternalServerError: () => InternalServerError,
+  InvalidCallbackError: () => InvalidCallbackError,
+  InvalidLimitError: () => InvalidLimitError,
+  JsonTransport: () => JsonTransport,
+  MessageCorruptedError: () => MessageCorruptedError,
+  MessageLockedError: () => MessageLockedError,
+  MessageNotAvailableError: () => MessageNotAvailableError,
+  MessageNotFoundError: () => MessageNotFoundError,
+  QueueEmptyError: () => QueueEmptyError,
+  StreamTransport: () => StreamTransport,
+  Topic: () => Topic,
+  UnauthorizedError: () => UnauthorizedError,
+  VQSClient: () => VQSClient,
+  createTopic: () => createTopic,
+  getVercelOidcToken: () => getVercelOidcToken,
+  parseCallbackRequest: () => parseCallbackRequest
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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
+var import_mixpart = require("mixpart");
+
+// src/local.ts
+var import_node_child_process = require("child_process");
+function isLocalhostWithPort(url) {
+  try {
+    const parsedUrl = new URL(url);
+    const isLocalhost = parsedUrl.hostname === "localhost";
+    const port = parsedUrl.port ? parseInt(parsedUrl.port, 10) : 0;
+    return { isLocalhost, port };
+  } catch {
+    return { isLocalhost: false };
+  }
+}
+function isSupportedPlatform() {
+  const platform = process.platform;
+  return platform === "darwin" || platform === "linux";
+}
+function processDevelopmentCallbacks(callbacks) {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  if (!isDevelopment) {
+    return [];
+  }
+  if (!isSupportedPlatform()) {
+    const hasLocalhostCallbacks = Object.values(callbacks).some((config) => {
+      const { isLocalhost } = isLocalhostWithPort(config.url);
+      return isLocalhost;
+    });
+    if (hasLocalhostCallbacks) {
+      console.warn(
+        `VQS Development Mode: Localhost callbacks are not supported on ${process.platform}. Localhost callback handling requires bash, nc, and curl which are available on macOS and Linux only. Consider using a production callback URL or developing on a supported platform.`
+      );
+    }
+    return [];
+  }
+  const localhostCallbacks = [];
+  Object.entries(callbacks).forEach(([group, config]) => {
+    const { isLocalhost, port } = isLocalhostWithPort(config.url);
+    if (isLocalhost && port && port > 0) {
+      localhostCallbacks.push({ group, config, port });
+    } else {
+      console.warn(
+        `VQS Development Mode: Skipping non-localhost callback for group "${group}": ${config.url}. Only localhost callbacks with explicit ports are supported in development.`
+      );
+    }
+  });
+  return localhostCallbacks;
+}
+function fireLocalhostCallbacks(localhostCallbacks, queueName, responseData) {
+  localhostCallbacks.forEach(({ group, config, port }) => {
+    const callbackHeaders = new Headers();
+    callbackHeaders.set("Vqs-Message-Id", responseData.messageId);
+    callbackHeaders.set("Vqs-Queue-Name", queueName);
+    callbackHeaders.set("Vqs-Consumer-Group", group);
+    fireAndForgetWaitForHttpReady(
+      config.url,
+      port,
+      config.delay || 0,
+      3,
+      // Default retry frequency
+      callbackHeaders
+    );
+  });
+}
+function fireAndForgetWaitForHttpReady(url, port, initialDelaySeconds = 0, retryFrequencySeconds = 3, headers) {
+  if (!isSupportedPlatform()) {
+    console.warn(
+      `VQS: fireAndForgetWaitForHttpReady is not supported on ${process.platform}. This function requires bash, nc, and curl which are available on macOS and Linux only.`
+    );
+    return;
+  }
+  let headerArgs = "";
+  if (headers) {
+    const headerArray = [];
+    headers.forEach((value, key) => {
+      headerArray.push(`-H '${key}: ${value}'`);
+    });
+    headerArgs = headerArray.join(" ");
+  }
+  const bashScript = `
+    # Wait for any initial boot time
+    sleep ${initialDelaySeconds}
+
+    missed=0
+    while true; do
+      # 1) Check if TCP port is listening
+      if nc -z localhost ${port} 2>/dev/null; then
+        missed=0
+        # 2) If port is open, try HTTP POST check
+        if curl -sSL --fail -o /dev/null -X POST ${headerArgs} "${url}"; then
+          # Success: port is up AND HTTP returned 2xx (following redirects)
+          exit 0
+        fi
+      else
+        # Port was closed\u2014increment miss counter
+        ((missed+=1))
+        # If closed twice in a row, give up immediately
+        if [ "$missed" -ge 2 ]; then
+          exit 1
+        fi
+      fi
+      # Wait before next cycle
+      sleep ${retryFrequencySeconds}
+    done
+  `;
+  const childProcess = (0, import_node_child_process.spawn)("bash", ["-c", bashScript], {
+    stdio: "ignore",
+    detached: true
+  });
+  childProcess.unref();
+}
+
+// src/types.ts
+var MessageNotFoundError = class extends Error {
+  constructor(messageId) {
+    super(`Message ${messageId} not found`);
+    this.name = "MessageNotFoundError";
+  }
+};
+var MessageNotAvailableError = class extends Error {
+  constructor(messageId, reason) {
+    super(
+      `Message ${messageId} not available for processing${reason ? `: ${reason}` : ""}`
+    );
+    this.name = "MessageNotAvailableError";
+  }
+};
+var FifoOrderingViolationError = class extends Error {
+  nextMessageId;
+  constructor(messageId, nextMessageId, reason) {
+    super(
+      `FIFO ordering violation for message ${messageId}: ${reason}. Process message ${nextMessageId} first.`
+    );
+    this.name = "FifoOrderingViolationError";
+    this.nextMessageId = nextMessageId;
+  }
+};
+var MessageCorruptedError = class extends Error {
+  constructor(messageId, reason) {
+    super(`Message ${messageId} is corrupted: ${reason}`);
+    this.name = "MessageCorruptedError";
+  }
+};
+var QueueEmptyError = class extends Error {
+  constructor(queueName, consumerGroup) {
+    super(
+      `No messages available in queue "${queueName}" for consumer group "${consumerGroup}"`
+    );
+    this.name = "QueueEmptyError";
+  }
+};
+var MessageLockedError = class extends Error {
+  retryAfter;
+  constructor(messageId, retryAfter) {
+    const retryMessage = retryAfter ? ` Retry after ${retryAfter} seconds.` : " Try again later.";
+    super(`Message ${messageId} is temporarily locked.${retryMessage}`);
+    this.name = "MessageLockedError";
+    this.retryAfter = retryAfter;
+  }
+};
+var UnauthorizedError = class extends Error {
+  constructor(message = "Missing or invalid authentication token") {
+    super(message);
+    this.name = "UnauthorizedError";
+  }
+};
+var ForbiddenError = class extends Error {
+  constructor(message = "Queue environment doesn't match token environment") {
+    super(message);
+    this.name = "ForbiddenError";
+  }
+};
+var BadRequestError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BadRequestError";
+  }
+};
+var FailedDependencyError = class extends Error {
+  nextMessageId;
+  constructor(messageId, nextMessageId) {
+    super(
+      `Failed dependency: FIFO ordering violation for message ${messageId}. Must process message ${nextMessageId} first.`
+    );
+    this.name = "FailedDependencyError";
+    this.nextMessageId = nextMessageId;
+  }
+};
+var InternalServerError = class extends Error {
+  constructor(message = "Unexpected server error") {
+    super(message);
+    this.name = "InternalServerError";
+  }
+};
+var InvalidLimitError = class extends Error {
+  constructor(limit, min = 1, max = 10) {
+    super(`Invalid limit: ${limit}. Limit must be between ${min} and ${max}.`);
+    this.name = "InvalidLimitError";
+  }
+};
+var InvalidCallbackError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidCallbackError";
+  }
+};
+
+// src/client.ts
+async function consumeStream(stream) {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function parseVQSHeaders(headers) {
+  const messageId = headers.get("Vqs-Message-Id");
+  const deliveryCountStr = headers.get("Vqs-Delivery-Count") || "0";
+  const timestamp = headers.get("Vqs-Timestamp");
+  const contentType = headers.get("Content-Type") || "application/octet-stream";
+  const ticket = headers.get("Vqs-Ticket");
+  if (!messageId || !timestamp || !ticket) {
+    return null;
+  }
+  const deliveryCount = parseInt(deliveryCountStr, 10);
+  if (isNaN(deliveryCount)) {
+    return null;
+  }
+  return {
+    messageId,
+    deliveryCount,
+    timestamp,
+    contentType,
+    ticket
+  };
+}
+var VQSClient = class _VQSClient {
+  baseUrl;
+  token;
+  /**
+   * Create a new Vercel Queue Service client
+   * @param options Client configuration options
+   */
+  constructor(options) {
+    this.baseUrl = options.baseUrl || "https://vqs.vercel.sh";
+    this.token = options.token;
+  }
+  /**
+   * Create a VQSClient 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 VQSClient instance
+   */
+  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."
+      );
+    }
+    return new _VQSClient({
+      token,
+      baseUrl
+    });
+  }
+  /**
+   * Send a message to a queue
+   * @param options Send message options
+   * @param transport Serializer/deserializer for the payload
+   * @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 sendMessage(options, transport) {
+    const { queueName, payload, idempotencyKey, retentionSeconds, callbacks } = options;
+    const headers = new Headers({
+      Authorization: `Bearer ${this.token}`,
+      "Vqs-Queue-Name": queueName,
+      "Content-Type": transport.contentType
+    });
+    if (idempotencyKey) {
+      headers.set("Vqs-Idempotency-Key", idempotencyKey);
+    }
+    if (retentionSeconds !== void 0) {
+      headers.set("Vqs-Retention-Seconds", retentionSeconds.toString());
+    }
+    let localhostCallbacks = [];
+    if (callbacks) {
+      const isDevelopment = process.env.NODE_ENV === "development";
+      if (isDevelopment) {
+        localhostCallbacks = processDevelopmentCallbacks(callbacks);
+      } else {
+        const endpoints = Object.entries(callbacks).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(",");
+        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(",");
+        if (frequencies) {
+          headers.set("Vqs-Callback-Frequency", frequencies);
+        }
+      }
+    }
+    const body = transport.serialize(payload);
+    const response = await fetch(`${this.baseUrl}/api/v2/messages`, {
+      method: "POST",
+      headers,
+      body
+    });
+    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();
+      }
+      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}`
+      );
+    }
+    const responseData = await response.json();
+    if (localhostCallbacks.length > 0) {
+      fireLocalhostCallbacks(localhostCallbacks, queueName, responseData);
+    }
+    return responseData;
+  }
+  /**
+   * Receive messages from a queue
+   * @param options Receive messages options
+   * @param transport Serializer/deserializer for the payload
+   * @returns AsyncGenerator that yields messages as they arrive
+   * @throws {InvalidLimitError} When limit parameter is not between 1 and 10
+   * @throws {QueueEmptyError} When no messages are available (204)
+   * @throws {MessageLockedError} When FIFO queue has locked messages (423)
+   * @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 *receiveMessages(options, transport) {
+    const { queueName, consumerGroup, visibilityTimeoutSeconds, limit } = options;
+    if (limit !== void 0 && (limit < 1 || limit > 10)) {
+      throw new InvalidLimitError(limit);
+    }
+    const headers = new Headers({
+      Authorization: `Bearer ${this.token}`,
+      "Vqs-Queue-Name": queueName,
+      "Vqs-Consumer-Group": consumerGroup,
+      Accept: "multipart/mixed"
+    });
+    if (visibilityTimeoutSeconds !== void 0) {
+      headers.set(
+        "Vqs-Visibility-Timeout",
+        visibilityTimeoutSeconds.toString()
+      );
+    }
+    if (limit !== void 0) {
+      headers.set("Vqs-Limit", limit.toString());
+    }
+    const response = await fetch(`${this.baseUrl}/api/v2/messages`, {
+      method: "GET",
+      headers
+    });
+    if (response.status === 204) {
+      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();
+      }
+      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 in FIFO queue", retryAfter);
+      }
+      if (response.status >= 500) {
+        throw new InternalServerError(
+          `Server error: ${response.status} ${response.statusText}`
+        );
+      }
+      throw new Error(
+        `Failed to receive messages: ${response.status} ${response.statusText}`
+      );
+    }
+    for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
+      try {
+        const parsedHeaders = parseVQSHeaders(multipartMessage.headers);
+        if (!parsedHeaders) {
+          console.warn("Missing required VQS headers in multipart part");
+          await consumeStream(multipartMessage.payload);
+          continue;
+        }
+        const deserializedPayload = await transport.deserialize(
+          multipartMessage.payload
+        );
+        const message = {
+          ...parsedHeaders,
+          payload: deserializedPayload
+        };
+        yield message;
+      } catch (error) {
+        console.warn("Failed to process multipart message:", error);
+        await consumeStream(multipartMessage.payload);
+      }
+    }
+  }
+  async receiveMessageById(options, transport) {
+    const {
+      queueName,
+      consumerGroup,
+      messageId,
+      visibilityTimeoutSeconds,
+      skipPayload
+    } = options;
+    const headers = new Headers({
+      Authorization: `Bearer ${this.token}`,
+      "Vqs-Queue-Name": queueName,
+      "Vqs-Consumer-Group": consumerGroup,
+      Accept: "multipart/mixed"
+    });
+    if (visibilityTimeoutSeconds !== void 0) {
+      headers.set(
+        "Vqs-Visibility-Timeout",
+        visibilityTimeoutSeconds.toString()
+      );
+    }
+    if (skipPayload) {
+      headers.set("Vqs-Skip-Payload", "1");
+    }
+    const response = await fetch(
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      {
+        method: "GET",
+        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();
+      }
+      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 === 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"
+        );
+      }
+      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) {
+        throw new InternalServerError(
+          `Server error: ${response.status} ${response.statusText}`
+        );
+      }
+      throw new Error(
+        `Failed to receive message by ID: ${response.status} ${response.statusText}`
+      );
+    }
+    if (skipPayload && response.status === 204) {
+      const parsedHeaders = parseVQSHeaders(response.headers);
+      if (!parsedHeaders) {
+        throw new MessageCorruptedError(
+          messageId,
+          "Missing required VQS headers in 204 response"
+        );
+      }
+      const message = {
+        ...parsedHeaders,
+        payload: void 0
+      };
+      return { message };
+    }
+    if (!transport) {
+      throw new Error("Transport is required when skipPayload is not true");
+    }
+    try {
+      for await (const multipartMessage of (0, import_mixpart.parseMultipartStream)(response)) {
+        try {
+          const parsedHeaders = parseVQSHeaders(multipartMessage.headers);
+          if (!parsedHeaders) {
+            console.warn("Missing required VQS headers in multipart part");
+            await consumeStream(multipartMessage.payload);
+            continue;
+          }
+          const deserializedPayload = await transport.deserialize(
+            multipartMessage.payload
+          );
+          const message = {
+            ...parsedHeaders,
+            payload: deserializedPayload
+          };
+          return { message };
+        } catch (error) {
+          console.warn("Failed to deserialize message by ID:", error);
+          await consumeStream(multipartMessage.payload);
+          throw new MessageCorruptedError(
+            messageId,
+            `Failed to deserialize payload: ${error}`
+          );
+        }
+      }
+    } catch (error) {
+      if (error instanceof MessageCorruptedError) {
+        throw error;
+      }
+      throw new MessageCorruptedError(
+        messageId,
+        `Failed to parse multipart response: ${error}`
+      );
+    }
+    throw new MessageNotFoundError(messageId);
+  }
+  /**
+   * Delete a message (acknowledge processing)
+   * @param options Delete message options
+   * @returns Promise with delete status
+   * @throws {MessageNotFoundError} When the message doesn't exist (404)
+   * @throws {MessageNotAvailableError} When message can't be deleted (409)
+   * @throws {BadRequestError} When ticket is missing or invalid (400)
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied (environment mismatch)
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async deleteMessage(options) {
+    const { queueName, consumerGroup, messageId, ticket } = options;
+    const response = await fetch(
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      {
+        method: "DELETE",
+        headers: new Headers({
+          Authorization: `Bearer ${this.token}`,
+          "Vqs-Queue-Name": queueName,
+          "Vqs-Consumer-Group": consumerGroup,
+          "Vqs-Ticket": ticket
+        })
+      }
+    );
+    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();
+      }
+      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}`
+        );
+      }
+      throw new Error(
+        `Failed to delete message: ${response.status} ${response.statusText}`
+      );
+    }
+    return { deleted: true };
+  }
+  /**
+   * Change the visibility timeout of a message
+   * @param options Change visibility options
+   * @returns Promise with update status
+   * @throws {MessageNotFoundError} When the message doesn't exist (404)
+   * @throws {MessageNotAvailableError} When message can't be updated (409)
+   * @throws {BadRequestError} When ticket is missing or visibility timeout invalid (400)
+   * @throws {UnauthorizedError} When authentication fails
+   * @throws {ForbiddenError} When access is denied (environment mismatch)
+   * @throws {InternalServerError} When server encounters an error
+   */
+  async changeVisibility(options) {
+    const {
+      queueName,
+      consumerGroup,
+      messageId,
+      ticket,
+      visibilityTimeoutSeconds
+    } = options;
+    const response = await fetch(
+      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      {
+        method: "PATCH",
+        headers: new Headers({
+          Authorization: `Bearer ${this.token}`,
+          "Vqs-Queue-Name": queueName,
+          "Vqs-Consumer-Group": consumerGroup,
+          "Vqs-Ticket": ticket,
+          "Vqs-Visibility-Timeout": visibilityTimeoutSeconds.toString()
+        })
+      }
+    );
+    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();
+      }
+      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}`
+        );
+      }
+      throw new Error(
+        `Failed to change visibility: ${response.status} ${response.statusText}`
+      );
+    }
+    return { updated: true };
+  }
+};
+
+// src/transports.ts
+var JsonTransport = class {
+  contentType = "application/json";
+  serialize(value) {
+    return Buffer.from(JSON.stringify(value), "utf8");
+  }
+  async deserialize(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      buffer.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return JSON.parse(Buffer.from(buffer).toString("utf8"));
+  }
+};
+var BufferTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      buffer.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return Buffer.from(buffer);
+  }
+};
+var StreamTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    return stream;
+  }
+  async finalize(payload) {
+    const reader = payload.getReader();
+    try {
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+
+// src/consumer-group.ts
+var ConsumerGroup = class {
+  client;
+  topicName;
+  consumerGroupName;
+  visibilityTimeout;
+  refreshInterval;
+  transport;
+  /**
+   * Create a new ConsumerGroup instance
+   * @param client VQSClient instance to use for API calls
+   * @param topicName Name of the topic to consume from
+   * @param consumerGroupName Name of the consumer group
+   * @param options Optional configuration
+   */
+  constructor(client, topicName, consumerGroupName, options = {}) {
+    this.client = client;
+    this.topicName = topicName;
+    this.consumerGroupName = consumerGroupName;
+    this.visibilityTimeout = options.visibilityTimeoutSeconds || 30;
+    this.refreshInterval = options.refreshInterval || 10;
+    this.transport = options.transport || new JsonTransport();
+  }
+  /**
+   * Starts a background loop that periodically extends the visibility timeout for a message.
+   * This prevents the message from becoming visible to other consumers while it's being processed.
+   *
+   * The extension loop runs every `refreshInterval` seconds and updates the message's
+   * visibility timeout to `visibilityTimeout` seconds from the current time.
+   *
+   * @param messageId - The unique identifier of the message to extend visibility for
+   * @param ticket - The receipt ticket that proves ownership of the message
+   * @returns A function that when called will stop the extension loop
+   *
+   * @remarks
+   * - The first extension attempt occurs after `refreshInterval` seconds, not immediately
+   * - If an extension fails, the loop terminates with an error logged to console
+   * - The returned stop function is idempotent - calling it multiple times is safe
+   * - By default, the stop function returns immediately without waiting for in-flight
+   * - Pass `true` to the stop function to wait for any in-flight extension to complete
+   */
+  startVisibilityExtension(messageId, ticket) {
+    let isRunning = true;
+    let resolveLifecycle;
+    let timeoutId = null;
+    const lifecyclePromise = new Promise((resolve) => {
+      resolveLifecycle = resolve;
+    });
+    const extend = async () => {
+      if (!isRunning) {
+        resolveLifecycle();
+        return;
+      }
+      try {
+        await this.client.changeVisibility({
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          messageId,
+          ticket,
+          visibilityTimeoutSeconds: this.visibilityTimeout
+        });
+        if (isRunning) {
+          timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
+        } else {
+          resolveLifecycle();
+        }
+      } catch (error) {
+        console.error(
+          `Failed to extend visibility for message ${messageId}:`,
+          error
+        );
+        resolveLifecycle();
+      }
+    };
+    timeoutId = setTimeout(() => extend(), this.refreshInterval * 1e3);
+    return async (waitForCompletion = false) => {
+      isRunning = false;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      if (waitForCompletion) {
+        await lifecyclePromise;
+      } else {
+        resolveLifecycle();
+      }
+    };
+  }
+  /**
+   * Process a single message with the given handler
+   * @param message The message to process
+   * @param handler Function to process the message
+   */
+  async processMessage(message, handler) {
+    const stopExtension = this.startVisibilityExtension(
+      message.messageId,
+      message.ticket
+    );
+    try {
+      const result = await handler(message);
+      await stopExtension();
+      if (result && "timeoutSeconds" in result) {
+        await this.client.changeVisibility({
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          messageId: message.messageId,
+          ticket: message.ticket,
+          visibilityTimeoutSeconds: result.timeoutSeconds
+        });
+      } else {
+        await this.client.deleteMessage({
+          queueName: this.topicName,
+          consumerGroup: this.consumerGroupName,
+          messageId: message.messageId,
+          ticket: message.ticket
+        });
+      }
+    } catch (error) {
+      await stopExtension();
+      if (this.transport.finalize && message.payload !== void 0 && message.payload !== null) {
+        try {
+          await this.transport.finalize(message.payload);
+        } catch (finalizeError) {
+          console.warn("Failed to finalize message payload:", finalizeError);
+        }
+      }
+      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(
+          {
+            queueName: this.topicName,
+            consumerGroup: this.consumerGroupName,
+            visibilityTimeoutSeconds: this.visibilityTimeout,
+            limit: 1
+            // Always process one message at a time
+          },
+          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;
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  get name() {
+    return this.consumerGroupName;
+  }
+  /**
+   * Get the topic name this consumer group is subscribed to
+   */
+  get topic() {
+    return this.topicName;
+  }
+};
+
+// src/topic.ts
+var Topic = class {
+  client;
+  topicName;
+  transport;
+  /**
+   * Create a new Topic instance
+   * @param client VQSClient instance to use for API calls
+   * @param topicName Name of the topic to work with
+   * @param transport Optional serializer/deserializer for the payload (defaults to JSON)
+   */
+  constructor(client, topicName, transport) {
+    this.client = client;
+    this.topicName = topicName;
+    this.transport = transport || new JsonTransport();
+  }
+  /**
+   * Publish a message to the topic
+   * @param payload The data to publish
+   * @param options Optional publish options
+   * @returns An object containing 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 publish(payload, options) {
+    const result = await this.client.sendMessage(
+      {
+        queueName: this.topicName,
+        payload,
+        idempotencyKey: options?.idempotencyKey,
+        retentionSeconds: options?.retentionSeconds,
+        callbacks: options?.callbacks
+      },
+      this.transport
+    );
+    return { messageId: result.messageId };
+  }
+  /**
+   * Create a consumer group for this topic
+   * @param consumerGroupName Name of the consumer group
+   * @param options Optional configuration for the consumer group
+   * @returns A ConsumerGroup instance
+   */
+  consumerGroup(consumerGroupName, options) {
+    const consumerOptions = {
+      ...options,
+      transport: options?.transport || this.transport
+    };
+    return new ConsumerGroup(
+      this.client,
+      this.topicName,
+      consumerGroupName,
+      consumerOptions
+    );
+  }
+  /**
+   * Get the topic name
+   */
+  get name() {
+    return this.topicName;
+  }
+  /**
+   * Get the transport used by this topic
+   */
+  get serializer() {
+    return this.transport;
+  }
+};
+
+// src/factory.ts
+function createTopic(client, topicName, transport) {
+  return new Topic(client, topicName, transport);
+}
+
+// src/callback.ts
+function parseCallbackRequest(request) {
+  const headers = request.headers;
+  const messageId = headers.get("Vqs-Message-Id");
+  const queueName = headers.get("Vqs-Queue-Name");
+  const consumerGroup = headers.get("Vqs-Consumer-Group");
+  const missingHeaders = [];
+  if (!messageId) missingHeaders.push("Vqs-Message-Id");
+  if (!queueName) missingHeaders.push("Vqs-Queue-Name");
+  if (!consumerGroup) missingHeaders.push("Vqs-Consumer-Group");
+  if (missingHeaders.length > 0) {
+    throw new InvalidCallbackError(
+      `Missing required VQS callback headers: ${missingHeaders.join(", ")}`
+    );
+  }
+  return {
+    messageId,
+    queueName,
+    consumerGroup
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BadRequestError,
+  BufferTransport,
+  ConsumerGroup,
+  FailedDependencyError,
+  FifoOrderingViolationError,
+  ForbiddenError,
+  InternalServerError,
+  InvalidCallbackError,
+  InvalidLimitError,
+  JsonTransport,
+  MessageCorruptedError,
+  MessageLockedError,
+  MessageNotAvailableError,
+  MessageNotFoundError,
+  QueueEmptyError,
+  StreamTransport,
+  Topic,
+  UnauthorizedError,
+  VQSClient,
+  createTopic,
+  getVercelOidcToken,
+  parseCallbackRequest
+});
+//# sourceMappingURL=index.js.map