@vercel/queue 0.0.2 → 0.1.1

package/dist/index.js

@@ -46,12 +46,15 @@ __export(index_exports, {
   MessageLockedError: () => MessageLockedError,
   MessageNotAvailableError: () => MessageNotAvailableError,
   MessageNotFoundError: () => MessageNotFoundError,
+  PollingQueueClient: () => PollingQueueClient,
   QueueClient: () => QueueClient,
   QueueEmptyError: () => QueueEmptyError,
   StreamTransport: () => StreamTransport,
   UnauthorizedError: () => UnauthorizedError,
+  handleCallback: () => handleCallback2,
   parseCallback: () => parseCallback,
-  parseRawCallback: () => parseRawCallback
+  parseRawCallback: () => parseRawCallback,
+  send: () => send
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -133,6 +136,7 @@ var import_mixpart = require("mixpart");
 
 // src/dev.ts
 var fs = __toESM(require("fs"));
+var net = __toESM(require("net"));
 var path = __toESM(require("path"));
 
 // src/types.ts
@@ -318,8 +322,8 @@ var ConsumerGroup = class {
         firstDelayMs = 0;
       }
     }
-    const lifecyclePromise = new Promise((resolve) => {
-      resolveLifecycle = resolve;
+    const lifecyclePromise = new Promise((resolve2) => {
+      resolveLifecycle = resolve2;
     });
     const safeResolve = () => {
       if (!isResolved) {
@@ -551,7 +555,7 @@ var Topic = class {
       headers: options?.headers
     });
     if (result.messageId && isDevMode()) {
-      triggerDevCallbacks(
+      invokeDevHandlers(
         this.topicName,
         result.messageId,
         this.client.getRegion()
@@ -760,14 +764,11 @@ async function handleCallback(handler, request, options) {
 }
 
 // src/dev.ts
-var ROUTE_MAPPINGS_KEY = Symbol.for("@vercel/queue.devRouteMappings");
-function filePathToUrlPath(filePath) {
-  let urlPath = filePath.replace(/^app\//, "/").replace(/^pages\//, "/").replace(/\/route\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
-  if (!urlPath.startsWith("/")) {
-    urlPath = "/" + urlPath;
-  }
-  return urlPath;
+var import_meta = {};
+function isDevMode() {
+  return process.env.NODE_ENV === "development";
 }
+var ROUTE_MAPPINGS_KEY = Symbol.for("@vercel/queue.devRouteMappings");
 function filePathToConsumerGroup(filePath) {
   return filePath.replace(/_/g, "__").replace(/\//g, "_S").replace(/\./g, "_D");
 }
@@ -791,13 +792,18 @@ function getDevRouteMappings() {
     for (const [filePath, config] of Object.entries(vercelJson.functions)) {
       if (!config.experimentalTriggers) continue;
       for (const trigger of config.experimentalTriggers) {
-        if (trigger.type?.startsWith("queue/") && trigger.topic) {
-          mappings.push({
-            urlPath: filePathToUrlPath(filePath),
-            topic: trigger.topic,
-            consumer: filePathToConsumerGroup(filePath)
-          });
+        if (!trigger.type?.startsWith("queue/") || !trigger.topic) continue;
+        if (trigger.type !== "queue/v2beta") {
+          console.warn(
+            `[Dev Mode] Unsupported trigger type "${trigger.type}" for topic "${trigger.topic}" in ${filePath}. Use "queue/v2beta" instead.`
+          );
+          continue;
         }
+        mappings.push({
+          filePath,
+          topic: trigger.topic,
+          consumer: filePathToConsumerGroup(filePath)
+        });
       }
     }
     g[ROUTE_MAPPINGS_KEY] = mappings.length > 0 ? mappings : null;
@@ -810,9 +816,7 @@ function getDevRouteMappings() {
 }
 function findMatchingRoutes(topicName) {
   const mappings = getDevRouteMappings();
-  if (!mappings) {
-    return [];
-  }
+  if (!mappings) return [];
   return mappings.filter((mapping) => {
     if (mapping.topic.includes("*")) {
       return matchesWildcardPattern(topicName, mapping.topic);
@@ -820,149 +824,450 @@ function findMatchingRoutes(topicName) {
     return mapping.topic === topicName;
   });
 }
-function isDevMode() {
-  return process.env.NODE_ENV === "development";
+function findMappingsForFile(absolutePath) {
+  const mappings = getDevRouteMappings();
+  if (!mappings) return [];
+  const cwd = process.cwd();
+  let relative2;
+  try {
+    relative2 = path.relative(cwd, absolutePath);
+  } catch {
+    return [];
+  }
+  const normalized = relative2.replace(/\\/g, "/");
+  return mappings.filter((m) => m.filePath === normalized);
+}
+function parseFrameFilePath(line) {
+  let match = line.match(/\((.+?):\d+:\d+\)/);
+  if (!match) match = line.match(/at\s+(.+?):\d+:\d+/);
+  if (!match) return null;
+  let filePath = match[1].trim();
+  if (filePath === "native" || filePath.startsWith("node:") || filePath.startsWith("internal")) {
+    return null;
+  }
+  if (filePath.startsWith("file://")) {
+    try {
+      filePath = new URL(filePath).pathname;
+    } catch {
+      return null;
+    }
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(filePath)) {
+    return null;
+  }
+  if (filePath.startsWith("./")) {
+    filePath = filePath.slice(2);
+  }
+  return filePath;
+}
+var _sdkPackageDir;
+function getSdkPackageDir() {
+  if (_sdkPackageDir) return _sdkPackageDir;
+  try {
+    const thisDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(new URL(import_meta.url).pathname);
+    _sdkPackageDir = path.resolve(thisDir, "..");
+  } catch {
+    _sdkPackageDir = "";
+  }
+  return _sdkPackageDir;
+}
+function extractCallerFilePath() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+  const lines = stack.split("\n").slice(1);
+  const pkgDir = getSdkPackageDir();
+  for (const line of lines) {
+    const fp = parseFrameFilePath(line);
+    if (!fp) continue;
+    const absolute = path.isAbsolute(fp) ? fp : path.resolve(process.cwd(), fp);
+    let realFp;
+    try {
+      realFp = fs.realpathSync(absolute);
+    } catch {
+      realFp = absolute;
+    }
+    if (pkgDir && realFp.startsWith(pkgDir)) continue;
+    return realFp;
+  }
+  return null;
+}
+var HANDLER_REGISTRY_KEY = Symbol.for("@vercel/queue.devHandlerRegistry");
+function getHandlerRegistry() {
+  const g = globalThis;
+  if (!g[HANDLER_REGISTRY_KEY]) {
+    g[HANDLER_REGISTRY_KEY] = /* @__PURE__ */ new Map();
+  }
+  return g[HANDLER_REGISTRY_KEY];
+}
+function registerHandlerForFile(filePath, handler, client, options) {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  const fileMappings = findMappingsForFile(absolutePath);
+  if (fileMappings.length === 0) return false;
+  const registry = getHandlerRegistry();
+  for (const mapping of fileMappings) {
+    const key = mapping.topic;
+    const existing = registry.get(key) ?? [];
+    const nextEntry = {
+      consumerGroup: mapping.consumer,
+      handler,
+      client,
+      options
+    };
+    const existingIndex = existing.findIndex(
+      (e) => e.consumerGroup === mapping.consumer
+    );
+    if (existingIndex >= 0) {
+      existing[existingIndex] = nextEntry;
+    } else {
+      existing.push(nextEntry);
+    }
+    registry.set(key, existing);
+  }
+  return true;
+}
+function registerDevHandler(handler, client, options, _testCallerPath) {
+  const callerPath = _testCallerPath ?? extractCallerFilePath();
+  if (!callerPath) {
+    console.warn(
+      "[Dev Mode] Could not determine caller file path for handler registration."
+    );
+    return;
+  }
+  const registered = registerHandlerForFile(
+    callerPath,
+    handler,
+    client,
+    options
+  );
+  if (!registered) {
+    const allMappings = getDevRouteMappings();
+    const cwd = process.cwd();
+    let relative2;
+    try {
+      relative2 = path.relative(cwd, callerPath).replace(/\\/g, "/");
+    } catch {
+      relative2 = callerPath;
+    }
+    if (allMappings && allMappings.length > 0) {
+      const configuredFiles = Array.from(
+        new Set(allMappings.map((m) => m.filePath))
+      );
+      console.warn(
+        `[Dev Mode] handleCallback() in ${relative2} does not match any queue route in vercel.json. This handler won't receive messages.
+Configured queue routes: [${configuredFiles.join(", ")}]
+If this path is a bundled chunk, keep handleCallback()/handleNodeCallback() at module scope and let dev-mode route priming load the mapped file.`
+      );
+      return;
+    }
+    console.warn(
+      `[Dev Mode] handleCallback() in ${relative2} has no matching experimentalTriggers in vercel.json. This handler won't receive messages.
+
+Add a trigger to vercel.json:
+  "${relative2}": {
+    "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "your-topic" }]
+  }`
+    );
+  }
+}
+function lookupHandlers(topicName) {
+  const registry = getHandlerRegistry();
+  const result = [];
+  for (const [pattern, handlers] of registry) {
+    const matches = pattern.includes("*") ? matchesWildcardPattern(topicName, pattern) : pattern === topicName;
+    if (matches) {
+      result.push(...handlers);
+    }
+  }
+  return result;
+}
+var DEV_RETRY_INITIAL_DELAY_MS = 50;
+var DEV_RETRY_MAX_WAIT_MS = 5e3;
+var DEV_RETRY_BACKOFF = 2;
+var PORT_CHECK_TIMEOUT_MS = 250;
+var PRIME_PORT_ENV_KEYS = [
+  "PORT",
+  "NEXT_PORT",
+  "NEXTJS_PORT",
+  "NUXT_PORT",
+  "NITRO_PORT",
+  "SVELTEKIT_PORT",
+  "VITE_PORT",
+  "DEV_PORT",
+  "npm_config_port"
+];
+var PRIME_URL_ENV_KEYS = [
+  "__NEXT_PRIVATE_ORIGIN",
+  "NUXT_PUBLIC_SITE_URL",
+  "URL"
+];
+function formatErrorReason(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
 }
-var DEV_VISIBILITY_POLL_INTERVAL = 50;
-var DEV_VISIBILITY_MAX_WAIT = 5e3;
-var DEV_VISIBILITY_BACKOFF_MULTIPLIER = 2;
-async function waitForMessageVisibility(topicName, consumerGroup, messageId, region) {
-  const client = new ApiClient({ region });
+function isMessageNotFoundError(error) {
+  if (error instanceof MessageNotFoundError) {
+    return true;
+  }
+  if (error instanceof Error && error.name === "MessageNotFoundError") {
+    return true;
+  }
+  return false;
+}
+function parsePort(value) {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) return null;
+  return parsed;
+}
+function parsePortFromUrl(value) {
+  if (!value) return null;
+  try {
+    const parsed = new URL(value).port;
+    return parsePort(parsed);
+  } catch {
+    return null;
+  }
+}
+function collectPrimePorts() {
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (port) => {
+    if (port && !seen.has(port)) {
+      seen.add(port);
+      result.push(port);
+    }
+  };
+  for (const key of PRIME_PORT_ENV_KEYS) {
+    add(parsePort(process.env[key]));
+  }
+  for (const key of PRIME_URL_ENV_KEYS) {
+    add(parsePortFromUrl(process.env[key]));
+  }
+  return result;
+}
+function isPortListening(port) {
+  return new Promise((resolve2) => {
+    const socket = net.connect({ host: "localhost", port });
+    let settled = false;
+    const finish = (listening) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve2(listening);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(PORT_CHECK_TIMEOUT_MS, () => finish(false));
+  });
+}
+async function invokeWithRetry(handler, request, options) {
   let elapsed = 0;
-  let interval = DEV_VISIBILITY_POLL_INTERVAL;
-  while (elapsed < DEV_VISIBILITY_MAX_WAIT) {
+  let delay = DEV_RETRY_INITIAL_DELAY_MS;
+  while (true) {
     try {
-      await client.receiveMessageById({
-        queueName: topicName,
-        consumerGroup,
-        messageId,
-        visibilityTimeoutSeconds: 0
-      });
-      return true;
+      await handleCallback(handler, request, options);
+      return;
     } catch (error) {
-      if (error instanceof MessageNotFoundError) {
-        await new Promise((resolve) => setTimeout(resolve, interval));
-        elapsed += interval;
-        interval = Math.min(
-          interval * DEV_VISIBILITY_BACKOFF_MULTIPLIER,
-          DEV_VISIBILITY_MAX_WAIT - elapsed
+      if (isMessageNotFoundError(error) && elapsed < DEV_RETRY_MAX_WAIT_MS) {
+        await new Promise((r) => setTimeout(r, delay));
+        elapsed += delay;
+        delay = Math.min(
+          delay * DEV_RETRY_BACKOFF,
+          DEV_RETRY_MAX_WAIT_MS - elapsed
         );
         continue;
       }
-      if (error instanceof MessageAlreadyProcessedError) {
-        console.log(
-          `[Dev Mode] Message already processed: topic="${topicName}" messageId="${messageId}"`
-        );
-        return false;
+      throw error;
+    }
+  }
+}
+function filePathToUrlPath(filePath) {
+  let urlPath = filePath.replace(/^app\//, "/").replace(/^pages\//, "/").replace(/^server\//, "/").replace(/^src\/routes\//, "/").replace(/\/route\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\/\+server\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
+  if (!urlPath.startsWith("/")) {
+    urlPath = "/" + urlPath;
+  }
+  return urlPath;
+}
+async function ensureHandlersLoaded(topicName, options = {}) {
+  const diagnostics = {
+    triedPorts: collectPrimePorts(),
+    listeningPorts: [],
+    unavailablePorts: [],
+    importFailures: [],
+    primeFailures: []
+  };
+  const matchingRoutes = findMatchingRoutes(topicName);
+  if (matchingRoutes.length === 0) return diagnostics;
+  const shouldRefreshRegistered = options.refreshRegistered === true;
+  for (const port of diagnostics.triedPorts) {
+    if (await isPortListening(port)) {
+      diagnostics.listeningPorts.push(port);
+    } else {
+      diagnostics.unavailablePorts.push(port);
+    }
+  }
+  for (const route of matchingRoutes) {
+    const alreadyRegistered = isHandlerRegistered(topicName, route.consumer);
+    if (alreadyRegistered && !shouldRefreshRegistered) {
+      continue;
+    }
+    if (!alreadyRegistered) {
+      const absolutePath = path.resolve(process.cwd(), route.filePath);
+      try {
+        await import(absolutePath);
+      } catch (error) {
+        diagnostics.importFailures.push({
+          filePath: route.filePath,
+          reason: formatErrorReason(error)
+        });
+      }
+      if (isHandlerRegistered(topicName, route.consumer)) continue;
+    }
+    for (const port of diagnostics.listeningPorts) {
+      const url = `http://localhost:${port}${filePathToUrlPath(route.filePath)}`;
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "x-vercel-queue-prime": "1",
+            "x-vercel-queue-prime-file": route.filePath
+          }
+        });
+        try {
+          await response.text();
+        } catch {
+        }
+        if (isHandlerRegistered(topicName, route.consumer)) {
+          break;
+        }
+        diagnostics.primeFailures.push({
+          filePath: route.filePath,
+          url,
+          reason: `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`.trim()
+        });
+      } catch (error) {
+        diagnostics.primeFailures.push({
+          filePath: route.filePath,
+          url,
+          reason: formatErrorReason(error)
+        });
       }
-      console.error(
-        `[Dev Mode] Error polling for message visibility: topic="${topicName}" messageId="${messageId}"`,
-        error
-      );
-      return false;
     }
   }
-  console.warn(
-    `[Dev Mode] Message visibility timeout after ${DEV_VISIBILITY_MAX_WAIT}ms: topic="${topicName}" messageId="${messageId}"`
+  return diagnostics;
+}
+function buildNoHandlerWarning(topicName, routes, diagnostics) {
+  const files = routes.map((r) => r.filePath);
+  const suggestedPort = diagnostics.listeningPorts[0] ?? diagnostics.triedPorts[0];
+  const suggestedUrls = suggestedPort ? routes.map(
+    (r) => `http://localhost:${suggestedPort}${filePathToUrlPath(r.filePath)}`
+  ) : [];
+  let portSummary;
+  if (diagnostics.triedPorts.length === 0) {
+    portSummary = "No local dev port detected from env. Set PORT (or NEXT_PORT/NUXT_PORT/VITE_PORT).";
+  } else if (diagnostics.listeningPorts.length === 0) {
+    portSummary = `Detected env ports: [${diagnostics.triedPorts.join(", ")}], but none are listening.`;
+  } else {
+    const unavailable = diagnostics.unavailablePorts.length > 0 ? ` Not listening: [${diagnostics.unavailablePorts.join(", ")}].` : "";
+    portSummary = `Detected env ports: [${diagnostics.triedPorts.join(", ")}]. Listening: [${diagnostics.listeningPorts.join(", ")}].` + unavailable;
+  }
+  const importSummary = diagnostics.importFailures.length > 0 ? `
+Import failures: ` + diagnostics.importFailures.slice(0, 2).map((f) => `${f.filePath} (${f.reason})`).join("; ") : "";
+  const primeSummary = diagnostics.primeFailures.length > 0 ? `
+Prime failures: ` + diagnostics.primeFailures.slice(0, 3).map((f) => `${f.url} (${f.reason})`).join("; ") : "";
+  return `[Dev Mode] No registered handler for topic "${topicName}". vercel.json maps this topic to [${files.join(", ")}] but auto-loading failed.
+${portSummary}${importSummary}${primeSummary}
+Ensure your dev server is running, set PORT if needed, and confirm mapped route files call handleCallback()/handleNodeCallback() at module scope.
+` + (suggestedUrls.length > 0 ? `Try opening: ${suggestedUrls.join(" or ")}` : "Set PORT (or NEXT_PORT/NUXT_PORT/VITE_PORT) and try sending again.");
+}
+function isHandlerRegistered(topicName, consumerGroup) {
+  return lookupHandlers(topicName).some(
+    (h) => h.consumerGroup === consumerGroup
   );
-  return false;
 }
-function triggerDevCallbacks(topicName, messageId, region, delaySeconds) {
+function invokeDevHandlers(topicName, messageId, region, delaySeconds) {
   if (delaySeconds && delaySeconds > 0) {
     console.log(
       `[Dev Mode] Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
     );
     setTimeout(() => {
-      triggerDevCallbacks(topicName, messageId, region);
+      invokeDevHandlers(topicName, messageId, region);
     }, delaySeconds * 1e3);
     return;
   }
   console.log(
     `[Dev Mode] Message sent: topic="${topicName}" messageId="${messageId}"`
   );
-  const matchingRoutes = findMatchingRoutes(topicName);
-  if (matchingRoutes.length === 0) {
-    console.log(
-      `[Dev Mode] No matching routes in vercel.json for topic "${topicName}"`
-    );
-    return;
-  }
-  const consumerGroups = matchingRoutes.map((r) => r.consumer);
-  console.log(
-    `[Dev Mode] Scheduling callbacks for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
-  );
   (async () => {
-    const firstRoute = matchingRoutes[0];
-    const isVisible = await waitForMessageVisibility(
-      topicName,
-      firstRoute.consumer,
-      messageId,
-      region
-    );
-    if (!isVisible) {
-      console.warn(
-        `[Dev Mode] Skipping callbacks - message not visible: topic="${topicName}" messageId="${messageId}"`
-      );
+    let handlers = lookupHandlers(topicName);
+    let diagnostics = null;
+    if (handlers.length > 0) {
+      await ensureHandlersLoaded(topicName, { refreshRegistered: true });
+      handlers = lookupHandlers(topicName);
+    } else {
+      diagnostics = await ensureHandlersLoaded(topicName);
+      handlers = lookupHandlers(topicName);
+    }
+    if (handlers.length === 0) {
+      const matchingRoutes = findMatchingRoutes(topicName);
+      if (matchingRoutes.length > 0) {
+        const safeDiagnostics = diagnostics ?? {
+          triedPorts: collectPrimePorts(),
+          listeningPorts: [],
+          unavailablePorts: [],
+          importFailures: [],
+          primeFailures: []
+        };
+        console.warn(
+          buildNoHandlerWarning(topicName, matchingRoutes, safeDiagnostics)
+        );
+      } else {
+        console.warn(
+          `[Dev Mode] No registered handler for topic "${topicName}".
+Ensure vercel.json has a matching experimentalTriggers entry and the route file calls handleCallback().`
+        );
+      }
       return;
     }
-    const port = process.env.PORT || 3e3;
-    const baseUrl = `http://localhost:${port}`;
-    for (const route of matchingRoutes) {
-      const url = `${baseUrl}${route.urlPath}`;
-      console.log(
-        `[Dev Mode] Invoking handler: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`
-      );
+    const consumerGroups = handlers.map((h) => h.consumerGroup);
+    console.log(
+      `[Dev Mode] Invoking handlers for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
+    );
+    for (const entry of handlers) {
+      const request = {
+        queueName: topicName,
+        consumerGroup: entry.consumerGroup,
+        messageId,
+        region
+      };
+      const callbackOptions = {
+        client: entry.client,
+        visibilityTimeoutSeconds: entry.options?.visibilityTimeoutSeconds,
+        retry: entry.options?.retry
+      };
       try {
-        const response = await fetch(url, {
-          method: "POST",
-          headers: {
-            "ce-type": CLOUD_EVENT_TYPE_V2BETA,
-            "ce-vqsqueuename": topicName,
-            "ce-vqsconsumergroup": route.consumer,
-            "ce-vqsmessageid": messageId,
-            "ce-vqsregion": region
-          }
-        });
-        if (response.ok) {
-          try {
-            const responseData = await response.json();
-            if (responseData.status === "success") {
-              console.log(
-                `[Dev Mode] \u2713 Message processed successfully: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}"`
-              );
-            }
-          } catch {
-            console.warn(
-              `[Dev Mode] Handler returned OK but response was not JSON: topic="${topicName}" consumer="${route.consumer}"`
-            );
-          }
-        } else {
-          try {
-            const errorData = await response.json();
-            console.error(
-              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" error="${errorData.error || response.statusText}"`
-            );
-          } catch {
-            console.error(
-              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" status=${response.status}`
-            );
-          }
-        }
+        await invokeWithRetry(entry.handler, request, callbackOptions);
+        console.log(
+          `[Dev Mode] \u2713 Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+        );
       } catch (error) {
         console.error(
-          `[Dev Mode] \u2717 HTTP request failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`,
+          `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
           error
         );
       }
     }
   })();
 }
-function clearDevRouteMappings() {
+function clearDevState() {
   const g = globalThis;
   delete g[ROUTE_MAPPINGS_KEY];
+  delete g[HANDLER_REGISTRY_KEY];
 }
 if (process.env.NODE_ENV === "test" || process.env.VITEST) {
-  globalThis.__clearDevRouteMappings = clearDevRouteMappings;
+  globalThis.__clearDevState = clearDevState;
 }
 
 // src/oidc.ts
@@ -1079,7 +1384,7 @@ var ApiClient = class _ApiClient {
       return;
     }
     throw new Error(
-      'No deployment ID available. VERCEL_DEPLOYMENT_ID is not set.\n\nThis usually means the code is running outside a Vercel deployment (e.g. during build or in a non-Vercel environment).\n\nTo fix this, create a new QueueClient with an explicit deploymentId:\n  new QueueClient({ region: "iad1", deploymentId: "dpl_xxx" })\nOr explicitly opt out of deployment pinning:\n  new QueueClient({ region: "iad1", deploymentId: null })'
+      'No deployment ID available. VERCEL_DEPLOYMENT_ID is not set.\n\nThis usually means the code is running outside a Vercel deployment (e.g. during build or in a non-Vercel environment).\n\nTo fix this, create a client with an explicit deploymentId:\n  new QueueClient({ deploymentId: "dpl_xxx" })\nOr explicitly opt out of deployment pinning:\n  new QueueClient({ deploymentId: null })'
     );
   }
   getSendDeploymentId() {
@@ -1137,7 +1442,7 @@ var ApiClient = class _ApiClient {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.0.2"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.1.1"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -1473,23 +1778,61 @@ var ApiClient = class _ApiClient {
 
 // src/client.ts
 var apiClients = /* @__PURE__ */ new WeakMap();
-function getApiClient(client) {
+var API_CLIENT_KEY = Symbol.for("@vercel/queue.apiClient");
+function setApi(client, api) {
+  apiClients.set(client, api);
+  Object.defineProperty(client, API_CLIENT_KEY, {
+    value: api,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+}
+function getApi(client) {
   const api = apiClients.get(client);
-  if (!api) {
-    throw new Error("QueueClient not initialized");
+  if (api) {
+    return api;
+  }
+  const apiFromSymbol = client[API_CLIENT_KEY];
+  if (typeof apiFromSymbol === "object" && apiFromSymbol !== null) {
+    const resolvedApi = apiFromSymbol;
+    apiClients.set(client, resolvedApi);
+    return resolvedApi;
   }
-  return api;
+  throw new Error(
+    "QueueClient not initialized. This may happen when multiple bundled copies of @vercel/queue are loaded in local dev."
+  );
+}
+function resolveCallbackRequest(input) {
+  if ("request" in input) {
+    return input.request;
+  }
+  return input;
+}
+function getApiClient(client) {
+  return getApi(client);
+}
+var DEFAULT_REGION = "iad1";
+function resolveRegion(region) {
+  if (region) return region;
+  const fromEnv = process.env.VERCEL_REGION;
+  if (fromEnv) return fromEnv;
+  console.warn(
+    `[QueueClient] Region not detected \u2014 defaulting to "${DEFAULT_REGION}". On Vercel this is set automatically via VERCEL_REGION. To silence this warning, pass region explicitly: new QueueClient({ region: "iad1" })`
+  );
+  return DEFAULT_REGION;
 }
 var QueueClient = class {
-  constructor(options) {
-    apiClients.set(this, new ApiClient(options));
+  constructor(options = {}) {
+    const region = resolveRegion(options.region);
+    setApi(this, new ApiClient({ ...options, region }));
   }
   /**
    * Send a message to a topic.
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { send } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { send } = new QueueClient();
    * await send("my-topic", payload);
    * ```
    *
@@ -1500,7 +1843,7 @@ var QueueClient = class {
    *   the message for deferred processing (no ID available yet)
    */
   send = async (topicName, payload, options) => {
-    const api = getApiClient(this);
+    const api = getApi(this);
     const result = await api.sendMessage({
       queueName: topicName,
       payload,
@@ -1510,7 +1853,7 @@ var QueueClient = class {
       headers: options?.headers
     });
     if (result.messageId && isDevMode()) {
-      triggerDevCallbacks(
+      invokeDevHandlers(
         topicName,
         result.messageId,
         api.getRegion(),
@@ -1519,75 +1862,6 @@ var QueueClient = class {
     }
     return { messageId: result.messageId };
   };
-  /**
-   * Receive and process messages from a topic.
-   *
-   * Each message is automatically locked, kept alive via periodic visibility
-   * extensions during processing, and acknowledged upon successful handler completion.
-   * The handler is not called when the queue is empty — check `result.ok` instead.
-   *
-   * This is an arrow function property so it can be destructured:
-   * ```typescript
-   * const { receive } = new QueueClient({ region: process.env.QUEUE_REGION! });
-   * const result = await receive("my-topic", "my-group", handler);
-   * if (!result.ok) console.log(result.reason);
-   * ```
-   *
-   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
-   * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
-   * @param handler - Function to process each message payload and metadata.
-   *                  Not called when the queue is empty.
-   * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
-   * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
-   */
-  receive = async (topicName, consumerGroup, handler, options) => {
-    const api = getApiClient(this);
-    const topic = new Topic(api, topicName);
-    const visibilityTimeoutSeconds = options && "visibilityTimeoutSeconds" in options ? options.visibilityTimeoutSeconds : void 0;
-    const consumer = topic.consumerGroup(
-      consumerGroup,
-      visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
-    );
-    try {
-      let count;
-      const retry = options?.retry;
-      if (options && "messageId" in options) {
-        count = await consumer.consume(handler, {
-          messageId: options.messageId,
-          retry
-        });
-      } else {
-        const limit = options && "limit" in options ? options.limit : void 0;
-        count = await consumer.consume(handler, {
-          ...limit !== void 0 ? { limit } : {},
-          retry
-        });
-      }
-      if (count === 0) {
-        return { ok: false, reason: "empty" };
-      }
-      return { ok: true };
-    } catch (error) {
-      if (options && "messageId" in options && error instanceof MessageNotFoundError) {
-        return { ok: false, reason: "not_found", messageId: options.messageId };
-      }
-      if (options && "messageId" in options && error instanceof MessageNotAvailableError) {
-        return {
-          ok: false,
-          reason: "not_available",
-          messageId: options.messageId
-        };
-      }
-      if (options && "messageId" in options && error instanceof MessageAlreadyProcessedError) {
-        return {
-          ok: false,
-          reason: "already_processed",
-          messageId: options.messageId
-        };
-      }
-      throw error;
-    }
-  };
   /**
    * Create a Web API route handler for processing queue callback messages.
    *
@@ -1596,7 +1870,7 @@ var QueueClient = class {
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { handleCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { handleCallback } = new QueueClient();
    * export const POST = handleCallback(handler);
    * ```
    *
@@ -1605,10 +1879,26 @@ var QueueClient = class {
    * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
    * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
    *   reschedule the message for redelivery after N seconds.
-   * @returns A `(request: Request) => Promise<Response>` route handler
+   * @returns A route handler that accepts either `Request` or `{ request: Request }`
    */
   handleCallback = (handler, options) => {
-    return async (request) => {
+    if (isDevMode()) {
+      registerDevHandler(handler, this, options);
+    }
+    return async (requestOrEvent) => {
+      const request = resolveCallbackRequest(requestOrEvent);
+      if (isDevMode() && request.headers.get("x-vercel-queue-prime") === "1") {
+        const primeFile = request.headers.get("x-vercel-queue-prime-file");
+        if (primeFile) {
+          registerDevHandler(
+            handler,
+            this,
+            options,
+            primeFile
+          );
+        }
+        return Response.json({ status: "primed" });
+      }
       try {
         const parsed = await parseCallback(request);
         await handleCallback(handler, parsed, {
@@ -1638,7 +1928,7 @@ var QueueClient = class {
    *
    * This is an arrow function property so it can be destructured:
    * ```typescript
-   * const { handleNodeCallback } = new QueueClient({ region: process.env.QUEUE_REGION! });
+   * const { handleNodeCallback } = new QueueClient();
    * app.post("/api/queue", handleNodeCallback(handler));
    * ```
    *
@@ -1650,11 +1940,29 @@ var QueueClient = class {
    * @returns A `(req, res) => Promise<void>` route handler
    */
   handleNodeCallback = (handler, options) => {
+    if (isDevMode()) {
+      registerDevHandler(handler, this, options);
+    }
     return async (req, res) => {
       if (req.method !== "POST") {
         res.status(200).end();
         return;
       }
+      const primeHeader = req.headers["x-vercel-queue-prime"];
+      if (isDevMode() && primeHeader === "1") {
+        const primeFileHeader = req.headers["x-vercel-queue-prime-file"];
+        const primeFile = Array.isArray(primeFileHeader) ? primeFileHeader[0] : primeFileHeader;
+        if (primeFile) {
+          registerDevHandler(
+            handler,
+            this,
+            options,
+            primeFile
+          );
+        }
+        res.status(200).json({ status: "primed" });
+        return;
+      }
       try {
         const parsed = parseRawCallback(req.body, req.headers);
         await handleCallback(handler, parsed, {
@@ -1674,6 +1982,126 @@ var QueueClient = class {
     };
   };
 };
+var PollingQueueClient = class {
+  constructor(options) {
+    setApi(this, new ApiClient(options));
+  }
+  /**
+   * Send a message to a topic.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { send } = new PollingQueueClient({ region: "iad1" });
+   * await send("my-topic", payload);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param payload - The data to send (serialized via the configured transport)
+   * @param options - Optional send options (idempotencyKey, retentionSeconds, delaySeconds, headers)
+   * @returns `{ messageId }` — `messageId` is `null` when the server accepted
+   *   the message for deferred processing (no ID available yet)
+   */
+  send = async (topicName, payload, options) => {
+    const api = getApi(this);
+    const result = await api.sendMessage({
+      queueName: topicName,
+      payload,
+      idempotencyKey: options?.idempotencyKey,
+      retentionSeconds: options?.retentionSeconds,
+      delaySeconds: options?.delaySeconds,
+      headers: options?.headers
+    });
+    return { messageId: result.messageId };
+  };
+  /**
+   * Receive and process messages from a topic.
+   *
+   * Each message is automatically locked, kept alive via periodic visibility
+   * extensions during processing, and acknowledged upon successful handler completion.
+   * The handler is not called when the queue is empty — check `result.ok` instead.
+   *
+   * This is an arrow function property so it can be destructured:
+   * ```typescript
+   * const { receive } = new PollingQueueClient({ region: "iad1" });
+   * const result = await receive("my-topic", "my-group", handler);
+   * if (!result.ok) console.log(result.reason);
+   * ```
+   *
+   * @param topicName - Name of the topic (pattern: `[A-Za-z0-9_-]+`)
+   * @param consumerGroup - Name of the consumer group (pattern: `[A-Za-z0-9_-]+`)
+   * @param handler - Function to process each message payload and metadata.
+   *                  Not called when the queue is empty.
+   * @param options - Optional receive options (visibilityTimeoutSeconds, limit, or messageId)
+   * @returns Discriminated result: `{ ok: true }` on success, `{ ok: false, reason }` otherwise
+   */
+  receive = async (topicName, consumerGroup, handler, options) => {
+    const api = getApi(this);
+    const topic = new Topic(api, topicName);
+    const visibilityTimeoutSeconds = options && "visibilityTimeoutSeconds" in options ? options.visibilityTimeoutSeconds : void 0;
+    const consumer = topic.consumerGroup(
+      consumerGroup,
+      visibilityTimeoutSeconds !== void 0 ? { visibilityTimeoutSeconds } : {}
+    );
+    try {
+      let count;
+      const retry = options?.retry;
+      if (options && "messageId" in options) {
+        count = await consumer.consume(handler, {
+          messageId: options.messageId,
+          retry
+        });
+      } else {
+        const limit = options && "limit" in options ? options.limit : void 0;
+        count = await consumer.consume(handler, {
+          ...limit !== void 0 ? { limit } : {},
+          retry
+        });
+      }
+      if (count === 0) {
+        return { ok: false, reason: "empty" };
+      }
+      return { ok: true };
+    } catch (error) {
+      if (options && "messageId" in options && error instanceof MessageNotFoundError) {
+        return { ok: false, reason: "not_found", messageId: options.messageId };
+      }
+      if (options && "messageId" in options && error instanceof MessageNotAvailableError) {
+        return {
+          ok: false,
+          reason: "not_available",
+          messageId: options.messageId
+        };
+      }
+      if (options && "messageId" in options && error instanceof MessageAlreadyProcessedError) {
+        return {
+          ok: false,
+          reason: "already_processed",
+          messageId: options.messageId
+        };
+      }
+      throw error;
+    }
+  };
+};
+
+// src/default-client.ts
+var _defaultClient;
+function getDefaultClient() {
+  if (!_defaultClient) {
+    _defaultClient = new QueueClient();
+  }
+  return _defaultClient;
+}
+function resolveClient(region) {
+  if (!region) return getDefaultClient();
+  return new QueueClient({ region });
+}
+async function send(topicName, payload, options) {
+  return resolveClient(options?.region).send(topicName, payload, options);
+}
+function handleCallback2(handler, options) {
+  return getDefaultClient().handleCallback(handler, options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BadRequestError,
@@ -1692,11 +2120,14 @@ var QueueClient = class {
   MessageLockedError,
   MessageNotAvailableError,
   MessageNotFoundError,
+  PollingQueueClient,
   QueueClient,
   QueueEmptyError,
   StreamTransport,
   UnauthorizedError,
+  handleCallback,
   parseCallback,
-  parseRawCallback
+  parseRawCallback,
+  send
 });
 //# sourceMappingURL=index.js.map