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

package/dist/index.mjs

@@ -1,128 +1,79 @@
-// 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";
-
-// src/local.ts
-import { spawn } from "child_process";
-function isLocalhostWithPort(url) {
+// src/transports.ts
+async function streamToBuffer(stream) {
+  let totalLength = 0;
+  const reader = stream.getReader();
+  const chunks = [];
   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 };
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalLength += value.length;
+    }
+  } finally {
+    reader.releaseLock();
   }
+  return Buffer.concat(chunks, totalLength);
 }
-function isSupportedPlatform() {
-  const platform = process.platform;
-  return platform === "darwin" || platform === "linux";
-}
-function processDevelopmentCallbacks(callbacks) {
-  const isDevelopment = process.env.NODE_ENV === "development";
-  if (!isDevelopment) {
-    return [];
+var JsonTransport = class {
+  contentType = "application/json";
+  replacer;
+  reviver;
+  constructor(options = {}) {
+    this.replacer = options.replacer;
+    this.reviver = options.reviver;
   }
-  if (!isSupportedPlatform()) {
-    const hasLocalhostCallbacks = Object.values(callbacks).some((config) => {
-      const { isLocalhost } = isLocalhostWithPort(config.url);
-      return isLocalhost;
-    });
-    if (hasLocalhostCallbacks) {
-      console.warn(
-        `Queue 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 [];
+  serialize(value) {
+    return Buffer.from(JSON.stringify(value, this.replacer), "utf8");
   }
-  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(
-        `Queue 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(
-      `Queue: fireAndForgetWaitForHttpReady is not supported on ${process.platform}. This function requires bash, nc, and curl which are available on macOS and Linux only.`
-    );
-    return;
+  async deserialize(stream) {
+    const buffer = await streamToBuffer(stream);
+    return JSON.parse(buffer.toString("utf8"), this.reviver);
   }
-  let headerArgs = "";
-  if (headers) {
-    const headerArray = [];
-    headers.forEach((value, key) => {
-      headerArray.push(`-H '${key}: ${value}'`);
-    });
-    headerArgs = headerArray.join(" ");
+};
+var BufferTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    return await streamToBuffer(stream);
+  }
+};
+var StreamTransport = class {
+  contentType = "application/octet-stream";
+  serialize(value) {
+    return value;
+  }
+  async deserialize(stream) {
+    return stream;
   }
-  const bashScript = `
-    # Wait for any initial boot time
-    sleep ${initialDelaySeconds}
+  async finalize(payload) {
+    const reader = payload.getReader();
+    try {
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
 
-    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 = spawn("bash", ["-c", bashScript], {
-    stdio: "ignore",
-    detached: true
-  });
-  childProcess.unref();
+// src/client.ts
+import { parseMultipartStream } from "mixpart";
+
+// src/oidc.ts
+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) {
+    return null;
+  }
+  return token;
 }
 
 // src/types.ts
@@ -140,16 +91,6 @@ var MessageNotAvailableError = class extends Error {
     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}`);
@@ -191,16 +132,6 @@ var BadRequestError = class extends Error {
     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);
@@ -213,12 +144,6 @@ var InvalidLimitError = class extends Error {
     this.name = "InvalidLimitError";
   }
 };
-var InvalidCallbackError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidCallbackError";
-  }
-};
 
 // src/client.ts
 async function consumeStream(stream) {
@@ -248,40 +173,33 @@ function parseQueueHeaders(headers) {
   return {
     messageId,
     deliveryCount,
-    timestamp,
+    createdAt: new Date(timestamp),
     contentType,
     ticket
   };
 }
-var QueueClient = class _QueueClient {
+var QueueClient = class {
   baseUrl;
+  basePath;
   token;
   /**
    * 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) {
-    this.baseUrl = options.baseUrl || "https://vqs.vercel.sh";
-    this.token = options.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
-   */
-  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."
-      );
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl || "https://vercel-queue.com";
+    this.basePath = options.basePath || "/api/v2/messages";
+    if (options.token) {
+      this.token = options.token;
+    } else {
+      const token = getVercelOidcToken();
+      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;
     }
-    return new _QueueClient({
-      token,
-      baseUrl
-    });
   }
   /**
    * Send a message to a queue
@@ -294,40 +212,23 @@ 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 } = options;
     const headers = new Headers({
       Authorization: `Bearer ${this.token}`,
       "Vqs-Queue-Name": queueName,
       "Content-Type": transport.contentType
     });
+    if (process.env.VERCEL_DEPLOYMENT_ID) {
+      headers.set("Vqs-Deployment-Id", process.env.VERCEL_DEPLOYMENT_ID);
+    }
     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`, {
+    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
       method: "POST",
       headers,
       body
@@ -356,9 +257,6 @@ var QueueClient = class _QueueClient {
       );
     }
     const responseData = await response.json();
-    if (localhostCallbacks.length > 0) {
-      fireLocalhostCallbacks(localhostCallbacks, queueName, responseData);
-    }
     return responseData;
   }
   /**
@@ -368,7 +266,7 @@ var QueueClient = class _QueueClient {
    * @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 {MessageLockedError} When messages are temporarily locked (423)
    * @throws {BadRequestError} When request parameters are invalid
    * @throws {UnauthorizedError} When authentication fails
    * @throws {ForbiddenError} When access is denied (environment mismatch)
@@ -394,7 +292,7 @@ var QueueClient = class _QueueClient {
     if (limit !== void 0) {
       headers.set("Vqs-Limit", limit.toString());
     }
-    const response = await fetch(`${this.baseUrl}/api/v2/messages`, {
+    const response = await fetch(`${this.baseUrl}${this.basePath}`, {
       method: "GET",
       headers
     });
@@ -419,7 +317,7 @@ var QueueClient = class _QueueClient {
           const parsed = parseInt(retryAfterHeader, 10);
           retryAfter = isNaN(parsed) ? void 0 : parsed;
         }
-        throw new MessageLockedError("next message in FIFO queue", retryAfter);
+        throw new MessageLockedError("next message", retryAfter);
       }
       if (response.status >= 500) {
         throw new InternalServerError(
@@ -476,7 +374,7 @@ var QueueClient = class _QueueClient {
       headers.set("Vqs-Skip-Payload", "1");
     }
     const response = await fetch(
-      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "GET",
         headers
@@ -505,37 +403,7 @@ 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"
-        );
-      }
       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) {
@@ -615,7 +483,7 @@ var QueueClient = class _QueueClient {
   async deleteMessage(options) {
     const { queueName, consumerGroup, messageId, ticket } = options;
     const response = await fetch(
-      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "DELETE",
         headers: new Headers({
@@ -676,7 +544,7 @@ var QueueClient = class _QueueClient {
       visibilityTimeoutSeconds
     } = options;
     const response = await fetch(
-      `${this.baseUrl}/api/v2/messages/${encodeURIComponent(messageId)}`,
+      `${this.baseUrl}${this.basePath}/${encodeURIComponent(messageId)}`,
       {
         method: "PATCH",
         headers: new Headers({
@@ -722,81 +590,336 @@ var QueueClient = class _QueueClient {
   }
 };
 
-// src/transports.ts
-var JsonTransport = class {
-  contentType = "application/json";
-  serialize(value) {
-    return Buffer.from(JSON.stringify(value), "utf8");
+// src/callback.ts
+function validateWildcardPattern(pattern) {
+  const firstIndex = pattern.indexOf("*");
+  const lastIndex = pattern.lastIndexOf("*");
+  if (firstIndex !== lastIndex) {
+    return false;
   }
-  async deserialize(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
+  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`
+        );
       }
-    } 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;
+  }
+  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 }
+      );
     }
-    return JSON.parse(Buffer.from(buffer).toString("utf8"));
+  };
+  if (isDevMode()) {
+    registerDevRouteHandler(routeHandler, handlers);
   }
-};
-var BufferTransport = class {
-  contentType = "application/octet-stream";
-  serialize(value) {
-    return value;
+  return routeHandler;
+}
+
+// src/dev.ts
+var devRouteHandlers = /* @__PURE__ */ new Map();
+var wildcardRouteHandlers = /* @__PURE__ */ new Map();
+var routeHandlerKeys = /* @__PURE__ */ new WeakMap();
+function cleanupDeadRefs(key, refs) {
+  const aliveRefs = refs.filter((ref) => ref.deref() !== void 0);
+  if (aliveRefs.length === 0) {
+    wildcardRouteHandlers.delete(key);
+  } else if (aliveRefs.length < refs.length) {
+    wildcardRouteHandlers.set(key, aliveRefs);
   }
-  async deserialize(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
+}
+function isDevMode() {
+  return process.env.NODE_ENV === "development";
+}
+function registerDevRouteHandler(routeHandler, handlers) {
+  const existingKeys = routeHandlerKeys.get(routeHandler);
+  if (existingKeys) {
+    const newKeys = /* @__PURE__ */ new Set();
+    for (const topicName in handlers) {
+      for (const consumerGroup in handlers[topicName]) {
+        newKeys.add(`${topicName}:${consumerGroup}`);
       }
-    } 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;
+    for (const key of existingKeys) {
+      if (!newKeys.has(key)) {
+        const [topicPattern] = key.split(":");
+        if (topicPattern.includes("*")) {
+          const refs = wildcardRouteHandlers.get(key);
+          if (refs) {
+            const filteredRefs = refs.filter(
+              (ref) => ref.deref() !== routeHandler
+            );
+            if (filteredRefs.length === 0) {
+              wildcardRouteHandlers.delete(key);
+            } else {
+              wildcardRouteHandlers.set(key, filteredRefs);
+            }
+          }
+        } else {
+          devRouteHandlers.delete(key);
+        }
+      }
     }
-    return Buffer.from(buffer);
   }
-};
-var StreamTransport = class {
-  contentType = "application/octet-stream";
-  serialize(value) {
-    return value;
+  const keys = /* @__PURE__ */ new Set();
+  for (const topicName in handlers) {
+    for (const consumerGroup in handlers[topicName]) {
+      const key = `${topicName}:${consumerGroup}`;
+      keys.add(key);
+      if (topicName.includes("*")) {
+        const weakRef = new WeakRef(routeHandler);
+        const existing = wildcardRouteHandlers.get(key) || [];
+        cleanupDeadRefs(key, existing);
+        const cleanedRefs = wildcardRouteHandlers.get(key) || [];
+        cleanedRefs.push(weakRef);
+        wildcardRouteHandlers.set(key, cleanedRefs);
+      } else {
+        devRouteHandlers.set(key, {
+          routeHandler,
+          topicPattern: topicName
+        });
+      }
+    }
   }
-  async deserialize(stream) {
-    return stream;
+  routeHandlerKeys.set(routeHandler, keys);
+}
+function findRouteHandlersForTopic(topicName) {
+  const handlersMap = /* @__PURE__ */ new Map();
+  for (const [
+    key,
+    { routeHandler, topicPattern }
+  ] of devRouteHandlers.entries()) {
+    const [_, consumerGroup] = key.split(":");
+    if (topicPattern === topicName) {
+      if (!handlersMap.has(routeHandler)) {
+        handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
+      }
+      handlersMap.get(routeHandler).add(consumerGroup);
+    }
   }
-  async finalize(payload) {
-    const reader = payload.getReader();
-    try {
-      while (true) {
-        const { done } = await reader.read();
-        if (done) break;
+  for (const [key, refs] of wildcardRouteHandlers.entries()) {
+    const [pattern, consumerGroup] = key.split(":");
+    if (matchesWildcardPattern(topicName, pattern)) {
+      cleanupDeadRefs(key, refs);
+      const cleanedRefs = wildcardRouteHandlers.get(key) || [];
+      for (const ref of cleanedRefs) {
+        const routeHandler = ref.deref();
+        if (routeHandler) {
+          if (!handlersMap.has(routeHandler)) {
+            handlersMap.set(routeHandler, /* @__PURE__ */ new Set());
+          }
+          handlersMap.get(routeHandler).add(consumerGroup);
+        }
       }
-    } finally {
-      reader.releaseLock();
     }
   }
-};
+  return handlersMap;
+}
+function createMockCloudEventRequest(topicName, consumerGroup, messageId) {
+  const cloudEvent = {
+    type: "com.vercel.queue.v1beta",
+    source: `/topic/${topicName}/consumer/${consumerGroup}`,
+    id: messageId,
+    datacontenttype: "application/json",
+    data: {
+      messageId,
+      queueName: topicName,
+      consumerGroup
+    },
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    specversion: "1.0"
+  };
+  return new Request("https://localhost/api/queue/callback", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/cloudevents+json"
+    },
+    body: JSON.stringify(cloudEvent)
+  });
+}
+var DEV_CALLBACK_DELAY = 1e3;
+function scheduleDevTimeout(topicName, messageId, timeoutSeconds) {
+  console.log(
+    `[Dev Mode] Message ${messageId} timed out for ${timeoutSeconds}s, will re-trigger`
+  );
+  setTimeout(
+    () => {
+      console.log(
+        `[Dev Mode] Re-triggering callback for timed-out message ${messageId}`
+      );
+      triggerDevCallbacks(topicName, messageId);
+    },
+    timeoutSeconds * 1e3 + DEV_CALLBACK_DELAY
+  );
+}
+function triggerDevCallbacks(topicName, messageId) {
+  const handlersMap = findRouteHandlersForTopic(topicName);
+  if (handlersMap.size === 0) {
+    return;
+  }
+  const consumerGroups = Array.from(
+    new Set(
+      Array.from(handlersMap.values()).flatMap((groups) => Array.from(groups))
+    )
+  );
+  console.log(
+    `[Dev Mode] Triggering local callbacks for topic "${topicName}" \u2192 consumers: ${consumerGroups.join(", ")}`
+  );
+  setTimeout(async () => {
+    for (const [routeHandler, consumerGroups2] of handlersMap.entries()) {
+      for (const consumerGroup of consumerGroups2) {
+        try {
+          const request = createMockCloudEventRequest(
+            topicName,
+            consumerGroup,
+            messageId
+          );
+          const response = await routeHandler(request);
+          if (response.ok) {
+            try {
+              const responseData = await response.json();
+              if (responseData.status === "success") {
+                console.log(
+                  `[Dev Mode] Message processed for ${topicName}/${consumerGroup}`
+                );
+              }
+            } catch (jsonError) {
+              console.error(
+                `[Dev Mode] Failed to parse success response for ${topicName}/${consumerGroup}:`,
+                jsonError
+              );
+            }
+          } else {
+            try {
+              const errorData = await response.json();
+              console.error(
+                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
+                errorData.error || response.statusText
+              );
+            } catch (jsonError) {
+              console.error(
+                `[Dev Mode] Failed to process message for ${topicName}/${consumerGroup}:`,
+                response.statusText
+              );
+            }
+          }
+        } catch (error) {
+          console.error(
+            `[Dev Mode] Error triggering callback for ${topicName}/${consumerGroup}:`,
+            error
+          );
+        }
+      }
+    }
+  }, DEV_CALLBACK_DELAY);
+}
+function clearDevHandlers() {
+  devRouteHandlers.clear();
+  wildcardRouteHandlers.clear();
+}
+if (process.env.NODE_ENV === "test" || process.env.VITEST) {
+  globalThis.__clearDevHandlers = clearDevHandlers;
+}
 
 // src/consumer-group.ts
 var ConsumerGroup = class {
@@ -897,7 +1020,13 @@ var ConsumerGroup = class {
       message.ticket
     );
     try {
-      const result = await handler(message);
+      const result = await handler(message.payload, {
+        messageId: message.messageId,
+        deliveryCount: message.deliveryCount,
+        createdAt: message.createdAt,
+        topicName: this.topicName,
+        consumerGroup: this.consumerGroupName
+      });
       await stopExtension();
       if (result && "timeoutSeconds" in result) {
         await this.client.changeVisibility({
@@ -907,6 +1036,13 @@ var ConsumerGroup = class {
           ticket: message.ticket,
           visibilityTimeoutSeconds: result.timeoutSeconds
         });
+        if (isDevMode()) {
+          scheduleDevTimeout(
+            this.topicName,
+            message.messageId,
+            result.timeoutSeconds
+          );
+        }
       } else {
         await this.client.deleteMessage({
           queueName: this.topicName,
@@ -927,219 +1063,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
    */
@@ -1186,11 +1161,13 @@ var Topic = class {
         queueName: this.topicName,
         payload,
         idempotencyKey: options?.idempotencyKey,
-        retentionSeconds: options?.retentionSeconds,
-        callbacks: options?.callbacks
+        retentionSeconds: options?.retentionSeconds
       },
       this.transport
     );
+    if (isDevMode()) {
+      triggerDevCallbacks(this.topicName, result.messageId);
+    }
     return { messageId: result.messageId };
   }
   /**
@@ -1226,53 +1203,59 @@ var Topic = class {
 };
 
 // src/factory.ts
-function createTopic(client, topicName, transport) {
-  return new Topic(client, topicName, transport);
+async function send(topicName, payload, options) {
+  const transport = options?.transport || new JsonTransport();
+  const client = new QueueClient();
+  const result = await client.sendMessage(
+    {
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds
+    },
+    transport
+  );
+  if (isDevMode()) {
+    triggerDevCallbacks(topicName, result.messageId);
+  }
+  return { messageId: result.messageId };
 }
-
-// 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 queue callback headers: ${missingHeaders.join(", ")}`
-    );
+async function receive(topicName, consumerGroup, handler, options) {
+  const transport = options?.transport || new JsonTransport();
+  const client = new QueueClient();
+  const topic = new Topic(client, 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);
   }
-  return {
-    messageId,
-    queueName,
-    consumerGroup
-  };
 }
 export {
   BadRequestError,
   BufferTransport,
-  ConsumerGroup,
-  FailedDependencyError,
-  FifoOrderingViolationError,
   ForbiddenError,
   InternalServerError,
-  InvalidCallbackError,
   InvalidLimitError,
   JsonTransport,
   MessageCorruptedError,
   MessageLockedError,
   MessageNotAvailableError,
   MessageNotFoundError,
-  QueueClient,
   QueueEmptyError,
   StreamTransport,
-  Topic,
   UnauthorizedError,
-  createTopic,
-  getVercelOidcToken,
-  parseCallbackRequest
+  handleCallback,
+  parseCallback,
+  receive,
+  send
 };
 //# sourceMappingURL=index.mjs.map