@vercel/queue 0.1.1 → 0.1.3

package/README.md

@@ -62,15 +62,17 @@ export const POST = handleCallback(async (message, metadata) => {
 
 That's it. The top-level `send` and `handleCallback` use an auto-configured default client. The region is auto-detected from `VERCEL_REGION` (set automatically on Vercel). If the region can't be detected (e.g. local dev), it falls back to `iad1`.
 
-To target a specific region for sending, pass the `region` option:
+To target a specific region for sending with the top-level `send`, pass the `region` option:
 
 ```typescript
 await send("my-topic", payload, { region: "sfo1" });
 ```
 
+> **Note:** The `region` option is only available on the top-level `send()` convenience export. When using a `QueueClient` instance, the region is set once in the constructor via `new QueueClient({ region: "sfo1" })` and applies to all operations on that client.
+
 ## Local Development
 
-**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, then invokes your registered `handleCallback` handlers directly in-process using the same code path as production. Your handlers are called with the exact same lifecycle (receive, visibility extension, ack) as in production.
+**Queues just work locally.** When you `send()` messages in development mode, the library sends them to the real Vercel Queue Service, then invokes your registered `handleCallback` handlers directly in-process using the same code path as production. Your handlers are called with the same lifecycle (receive, visibility extension, ack) as in production. If a handler throws, the message is re-delivered after the configured retry delay (from `retryAfterSeconds` in `vercel.json` or the `retry` callback's `afterSeconds`), with an incrementing `deliveryCount`, matching production retry semantics.
 
 Works with Next.js (Turbopack and webpack), Nuxt, SvelteKit, and any framework that runs server-side JavaScript. The SDK automatically discovers handlers from your `vercel.json` configuration and loads route modules on demand — no manual setup required beyond `vercel.json`.
 
@@ -92,7 +94,7 @@ await send(
     idempotencyKey: "unique-key", // Prevent duplicate messages
     retentionSeconds: 3600, // 1 hour TTL (default: 24h)
     delaySeconds: 60, // Delay delivery by 1 minute
-    region: "sfo1", // Optional — target a specific region
+    region: "sfo1", // Top-level send() only — not available on QueueClient.send()
   },
 );
 ```
@@ -128,11 +130,16 @@ Returns `(Request) => Promise<Response>`. For frameworks that export Web API rou
 // app/api/queue/my-topic/route.ts
 import { handleCallback } from "@vercel/queue";
 
-export const POST = handleCallback(async (message, metadata) => {
-  // metadata: { messageId, deliveryCount, createdAt, expiresAt?, topicName, consumerGroup, region }
-  await processMessage(message);
-  // Throwing an error will automatically retry the message
-});
+export const POST = handleCallback(
+  async (message, metadata) => {
+    // metadata: { messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, region }
+    await processMessage(message);
+    // Throwing an error will automatically retry the message
+  },
+  {
+    visibilityTimeoutSeconds: 600, // Lock duration while processing (default: 300)
+  },
+);
 ```
 
 **Nuxt:**
@@ -179,7 +186,7 @@ export default app;
 
 #### Connect-style — `handleNodeCallback`
 
-Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Vercel Node.js functions, Express, Next.js Pages Router, etc.). Requires a `QueueClient` instance:
+Returns `(req, res) => Promise<void>`. For frameworks that export Connect-style handlers (Vercel Node.js functions, Express, Next.js Pages Router, etc.). **`handleNodeCallback` is not a top-level export** — it is only available via a `QueueClient` instance:
 
 ```typescript
 // lib/queue.ts
@@ -269,7 +276,7 @@ Multiple route files for the same topic create separate consumer groups — each
 
 When a handler throws, the message is not acknowledged and becomes available for redelivery after the `retryAfterSeconds` interval configured in `vercel.json`. Retries continue until the handler succeeds or the message expires (default: 24 hours).
 
-For finer control over retry timing, pass a `retry` option:
+For finer control over retry timing, pass a `retry` option. You can also set `visibilityTimeoutSeconds` to control how long the message is locked during processing (default: 300):
 
 ```typescript
 import { handleCallback } from "@vercel/queue";
@@ -279,6 +286,7 @@ export const POST = handleCallback(
     await processMessage(message);
   },
   {
+    visibilityTimeoutSeconds: 600, // Lock duration while processing (default: 300)
     retry: (error, metadata) => {
       if (error instanceof RateLimitError) return { afterSeconds: 60 };
       // Return undefined to let the error propagate normally
@@ -553,7 +561,7 @@ All error types:
 | Limit                       | Value                 | Notes                               |
 | --------------------------- | --------------------- | ----------------------------------- |
 | Message throughput          | 10,000+ msg/sec/topic | Scales horizontally                 |
-| Payload size                | 1 GB                  | Smaller messages have lower latency |
+| Payload size                | 100 MB                | Smaller messages have lower latency |
 | Number of topics            | Unlimited             | No hard limit                       |
 | Consumer groups per message | ~4,000                | Per-message limit                   |
 | Messages per queue          | Unlimited             | No hard limit                       |
@@ -615,10 +623,12 @@ const { messageId } = await send("my-topic", payload, {
   retentionSeconds: 3600, // Message TTL (default: 86400)
   delaySeconds: 60, // Delay before visible (default: 0)
   headers: { "X-Custom": "val" }, // Custom headers
-  region: "sfo1", // Optional — target a specific region
+  region: "sfo1", // Override the auto-detected region for this send
 });
 ```
 
+The `region` option is exclusive to the top-level `send()`. It creates a one-off client targeting the given region. When using `QueueClient`, the region is set once in the constructor and applies to all operations.
+
 Returns `{ messageId: string | null }`. `messageId` is `null` when the server accepted the message for deferred processing (e.g. during a server-side outage).
 
 ### Top-level `handleCallback(handler, options?)`
@@ -707,7 +717,7 @@ const result = await receive("my-topic", "my-group", handler, {
 
 ### `handleNodeCallback(handler, options?)`
 
-Available on `QueueClient` only. Vercel only.
+Available on `QueueClient` instances only (not a top-level export). Vercel only.
 
 Returns `(req, res) => Promise<void>` — for frameworks that export Connect-style handlers.
 
@@ -740,7 +750,7 @@ interface MessageMetadata {
   messageId: string;
   deliveryCount: number;
   createdAt: Date;
-  expiresAt?: Date;
+  expiresAt: Date;
   topicName: string;
   consumerGroup: string;
   region: string;

package/dist/index.d.mts

@@ -289,7 +289,8 @@ interface Message<T = unknown> {
     createdAt: Date;
     /**
      * Timestamp when the message expires.
-     * Only present for messages delivered via the v2beta binary callback path.
+     * Present in v2beta binary callback (`ce-vqsexpiresat` header) and
+     * V3 multipart/NDJSON responses (`Vqs-Expires-At` header / `expiresAt` field).
      */
     expiresAt?: Date;
     /**
@@ -311,7 +312,7 @@ interface MessageMetadata {
     messageId: string;
     deliveryCount: number;
     createdAt: Date;
-    expiresAt?: Date;
+    expiresAt: Date;
     topicName: string;
     consumerGroup: string;
     /** Vercel region the client is targeting. */

package/dist/index.d.ts

@@ -289,7 +289,8 @@ interface Message<T = unknown> {
     createdAt: Date;
     /**
      * Timestamp when the message expires.
-     * Only present for messages delivered via the v2beta binary callback path.
+     * Present in v2beta binary callback (`ce-vqsexpiresat` header) and
+     * V3 multipart/NDJSON responses (`Vqs-Expires-At` header / `expiresAt` field).
      */
     expiresAt?: Date;
     /**
@@ -311,7 +312,7 @@ interface MessageMetadata {
     messageId: string;
     deliveryCount: number;
     createdAt: Date;
-    expiresAt?: Date;
+    expiresAt: Date;
     topicName: string;
     consumerGroup: string;
     /** Vercel region the client is targeting. */

package/dist/index.js

@@ -138,6 +138,8 @@ var import_mixpart = require("mixpart");
 var fs = __toESM(require("fs"));
 var net = __toESM(require("net"));
 var path = __toESM(require("path"));
+var import_minimatch = require("minimatch");
+var import_picocolors = __toESM(require("picocolors"));
 
 // src/types.ts
 var MessageNotFoundError = class extends Error {
@@ -400,11 +402,12 @@ var ConsumerGroup = class {
       message.receiptHandle,
       options
     );
+    const DEFAULT_RETENTION_MS = 864e5;
     const metadata = {
       messageId: message.messageId,
       deliveryCount: message.deliveryCount,
       createdAt: message.createdAt,
-      expiresAt: message.expiresAt,
+      expiresAt: message.expiresAt ?? new Date(message.createdAt.getTime() + DEFAULT_RETENTION_MS),
       topicName: this.topicName,
       consumerGroup: this.consumerGroupName,
       region: this.client.getRegion()
@@ -558,7 +561,9 @@ var Topic = class {
       invokeDevHandlers(
         this.topicName,
         result.messageId,
-        this.client.getRegion()
+        this.client.getRegion(),
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };
@@ -765,12 +770,30 @@ async function handleCallback(handler, request, options) {
 
 // src/dev.ts
 var import_meta = {};
+var PREFIX = import_picocolors.default.cyan("[queue]");
+var OK = import_picocolors.default.green("\u2713");
+var FAIL = import_picocolors.default.red("\u2717");
+var RETRY = import_picocolors.default.yellow("\u21BB");
 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");
+  let result = "";
+  for (const char of filePath) {
+    if (char === "_") {
+      result += "__";
+    } else if (char === "/") {
+      result += "_S";
+    } else if (char === ".") {
+      result += "_D";
+    } else if (/[A-Za-z0-9-]/.test(char)) {
+      result += char;
+    } else {
+      result += "_" + char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0");
+    }
+  }
+  return result;
 }
 function getDevRouteMappings() {
   const g = globalThis;
@@ -795,21 +818,22 @@ function getDevRouteMappings() {
         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.`
+            `${PREFIX} 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)
+          consumer: filePathToConsumerGroup(filePath),
+          retryAfterSeconds: trigger.retryAfterSeconds
         });
       }
     }
     g[ROUTE_MAPPINGS_KEY] = mappings.length > 0 ? mappings : null;
     return g[ROUTE_MAPPINGS_KEY];
   } catch (error) {
-    console.warn("[Dev Mode] Failed to read vercel.json:", error);
+    console.warn(`${PREFIX} Failed to read vercel.json:`, error);
     g[ROUTE_MAPPINGS_KEY] = null;
     return null;
   }
@@ -824,6 +848,20 @@ function findMatchingRoutes(topicName) {
     return mapping.topic === topicName;
   });
 }
+function findRetryAfterSeconds(topicName, consumerGroup) {
+  const routes = findMatchingRoutes(topicName);
+  const route = routes.find((r) => r.consumer === consumerGroup);
+  return route?.retryAfterSeconds;
+}
+function stripSrcPrefix(filePath) {
+  if (/^src\/(app|pages|server)\//.test(filePath)) {
+    return filePath.slice(4);
+  }
+  return null;
+}
+function matchesFunctionsPattern(sourceFile, pattern) {
+  return sourceFile === pattern || (0, import_minimatch.minimatch)(sourceFile, pattern);
+}
 function findMappingsForFile(absolutePath) {
   const mappings = getDevRouteMappings();
   if (!mappings) return [];
@@ -835,7 +873,10 @@ function findMappingsForFile(absolutePath) {
     return [];
   }
   const normalized = relative2.replace(/\\/g, "/");
-  return mappings.filter((m) => m.filePath === normalized);
+  const stripped = stripSrcPrefix(normalized);
+  return mappings.filter(
+    (m) => matchesFunctionsPattern(normalized, m.filePath) || stripped !== null && matchesFunctionsPattern(stripped, m.filePath)
+  );
 }
 function parseFrameFilePath(line) {
   let match = line.match(/\((.+?):\d+:\d+\)/);
@@ -929,7 +970,7 @@ 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."
+      `${PREFIX} Could not determine caller file path for handler registration.`
     );
     return;
   }
@@ -941,6 +982,9 @@ function registerDevHandler(handler, client, options, _testCallerPath) {
   );
   if (!registered) {
     const allMappings = getDevRouteMappings();
+    if (allMappings && allMappings.length > 0) {
+      return;
+    }
     const cwd = process.cwd();
     let relative2;
     try {
@@ -948,19 +992,8 @@ function registerDevHandler(handler, client, options, _testCallerPath) {
     } 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.
+      `${PREFIX} handleCallback() in ${relative2} has no matching experimentalTriggers in vercel.json. This handler won't receive messages.
 
 Add a trigger to vercel.json:
   "${relative2}": {
@@ -1084,7 +1117,7 @@ async function invokeWithRetry(handler, request, options) {
   }
 }
 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)$/, "");
+  let urlPath = filePath.replace(/^src\/app\//, "/").replace(/^src\/pages\//, "/").replace(/^src\/server\//, "/").replace(/^src\/routes\//, "/").replace(/^app\//, "/").replace(/^pages\//, "/").replace(/^server\//, "/").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;
   }
@@ -1177,7 +1210,7 @@ function buildNoHandlerWarning(topicName, routes, diagnostics) {
 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.
+  return `${PREFIX} 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.");
@@ -1187,18 +1220,106 @@ function isHandlerRegistered(topicName, consumerGroup) {
     (h) => h.consumerGroup === consumerGroup
   );
 }
-function invokeDevHandlers(topicName, messageId, region, delaySeconds) {
+var DEV_REDELIVERY_MAX_DELAY_S = 10;
+var DEV_REDELIVERY_DEFAULT_DELAY_S = 2;
+var DEV_REDELIVERY_MAX_ATTEMPTS = 10;
+var DEFAULT_RETENTION_S = 86400;
+function scheduleDevRedelivery(ctx, delayS) {
+  const cappedDelay = Math.min(Math.max(delayS, 0), DEV_REDELIVERY_MAX_DELAY_S);
+  console.log(
+    `${PREFIX} ${RETRY} Scheduling re-delivery in ${cappedDelay}s: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+  );
+  setTimeout(async () => {
+    const nextDeliveryCount = ctx.deliveryCount + 1;
+    const expiresAt = new Date(
+      ctx.createdAt.getTime() + ctx.retentionSeconds * 1e3
+    );
+    if (Date.now() >= expiresAt.getTime()) {
+      console.log(
+        `${PREFIX} Message expired, stopping retries: topic="${ctx.topicName}" messageId="${ctx.messageId}"`
+      );
+      return;
+    }
+    if (nextDeliveryCount > DEV_REDELIVERY_MAX_ATTEMPTS) {
+      console.log(
+        `${PREFIX} Max re-deliveries (${DEV_REDELIVERY_MAX_ATTEMPTS}) reached: topic="${ctx.topicName}" messageId="${ctx.messageId}"`
+      );
+      return;
+    }
+    const metadata = {
+      messageId: ctx.messageId,
+      deliveryCount: nextDeliveryCount,
+      createdAt: ctx.createdAt,
+      expiresAt,
+      topicName: ctx.topicName,
+      consumerGroup: ctx.consumerGroup,
+      region: ctx.region
+    };
+    console.log(
+      `${PREFIX} Re-delivering: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}" deliveryCount=${nextDeliveryCount}`
+    );
+    let succeeded = true;
+    let nextRetryAfterS = null;
+    let nextAcknowledged = false;
+    try {
+      await ctx.handler(ctx.payload, metadata);
+    } catch (error) {
+      succeeded = false;
+      if (ctx.retry) {
+        let directive;
+        try {
+          directive = ctx.retry(error, metadata);
+        } catch (retryErr) {
+          console.warn(`${PREFIX} retry handler threw:`, retryErr);
+        }
+        if (directive && "afterSeconds" in directive) {
+          nextRetryAfterS = directive.afterSeconds;
+        } else if (directive && "acknowledge" in directive) {
+          nextAcknowledged = true;
+        }
+      }
+      if (!nextAcknowledged) {
+        console.error(
+          `${PREFIX} ${FAIL} Handler error on re-delivery: topic="${ctx.topicName}" messageId="${ctx.messageId}"`,
+          error
+        );
+      }
+    }
+    if (succeeded) {
+      console.log(
+        `${PREFIX} ${OK} Message processed on re-delivery: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+      );
+    } else if (nextAcknowledged) {
+      console.log(
+        `${PREFIX} ${OK} Message acknowledged (will not retry): topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+      );
+    } else {
+      const nextDelay = nextRetryAfterS ?? ctx.defaultRetryDelayS;
+      scheduleDevRedelivery(
+        { ...ctx, deliveryCount: nextDeliveryCount },
+        nextDelay
+      );
+    }
+  }, cappedDelay * 1e3);
+}
+function invokeDevHandlers(topicName, messageId, region, delaySeconds, retentionSeconds) {
   if (delaySeconds && delaySeconds > 0) {
     console.log(
-      `[Dev Mode] Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
+      `${PREFIX} Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
     );
     setTimeout(() => {
-      invokeDevHandlers(topicName, messageId, region);
+      invokeDevHandlers(
+        topicName,
+        messageId,
+        region,
+        void 0,
+        retentionSeconds
+      );
     }, delaySeconds * 1e3);
     return;
   }
   console.log(
-    `[Dev Mode] Message sent: topic="${topicName}" messageId="${messageId}"`
+    `${PREFIX} Message sent: topic="${topicName}" messageId="${messageId}"`
   );
   (async () => {
     let handlers = lookupHandlers(topicName);
@@ -1225,7 +1346,7 @@ function invokeDevHandlers(topicName, messageId, region, delaySeconds) {
         );
       } else {
         console.warn(
-          `[Dev Mode] No registered handler for topic "${topicName}".
+          `${PREFIX} No registered handler for topic "${topicName}".
 Ensure vercel.json has a matching experimentalTriggers entry and the route file calls handleCallback().`
         );
       }
@@ -1233,9 +1354,36 @@ Ensure vercel.json has a matching experimentalTriggers entry and the route file
     }
     const consumerGroups = handlers.map((h) => h.consumerGroup);
     console.log(
-      `[Dev Mode] Invoking handlers for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
+      `${PREFIX} Invoking handlers for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
     );
+    const effectiveRetention = retentionSeconds ?? DEFAULT_RETENTION_S;
     for (const entry of handlers) {
+      let capturedPayload;
+      let capturedCreatedAt = /* @__PURE__ */ new Date();
+      let capturedDeliveryCount = 1;
+      let handlerSucceeded = true;
+      let retryAfterS = null;
+      let retryAcknowledged = false;
+      const wrappedHandler = async (message, metadata) => {
+        capturedPayload = message;
+        capturedCreatedAt = metadata.createdAt;
+        capturedDeliveryCount = metadata.deliveryCount;
+        try {
+          await entry.handler(message, metadata);
+        } catch (error) {
+          handlerSucceeded = false;
+          throw error;
+        }
+      };
+      const wrappedRetry = entry.options?.retry ? (error, metadata) => {
+        const directive = entry.options.retry(error, metadata);
+        if (directive && "afterSeconds" in directive) {
+          retryAfterS = directive.afterSeconds;
+        } else if (directive && "acknowledge" in directive) {
+          retryAcknowledged = true;
+        }
+        return directive;
+      } : void 0;
       const request = {
         queueName: topicName,
         consumerGroup: entry.consumerGroup,
@@ -1245,18 +1393,47 @@ Ensure vercel.json has a matching experimentalTriggers entry and the route file
       const callbackOptions = {
         client: entry.client,
         visibilityTimeoutSeconds: entry.options?.visibilityTimeoutSeconds,
-        retry: entry.options?.retry
+        retry: wrappedRetry
       };
+      const consumerDefaultDelay = Math.min(
+        findRetryAfterSeconds(topicName, entry.consumerGroup) ?? DEV_REDELIVERY_DEFAULT_DELAY_S,
+        DEV_REDELIVERY_MAX_DELAY_S
+      );
+      const buildRedeliveryCtx = () => ({
+        handler: entry.handler,
+        retry: entry.options?.retry,
+        payload: capturedPayload,
+        topicName,
+        consumerGroup: entry.consumerGroup,
+        messageId,
+        region,
+        createdAt: capturedCreatedAt,
+        retentionSeconds: effectiveRetention,
+        deliveryCount: capturedDeliveryCount,
+        defaultRetryDelayS: consumerDefaultDelay
+      });
       try {
-        await invokeWithRetry(entry.handler, request, callbackOptions);
-        console.log(
-          `[Dev Mode] \u2713 Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
-        );
+        await invokeWithRetry(wrappedHandler, request, callbackOptions);
+        if (handlerSucceeded) {
+          console.log(
+            `${PREFIX} ${OK} Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+          );
+        } else if (retryAcknowledged) {
+          console.log(
+            `${PREFIX} ${OK} Message acknowledged (will not retry): topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+          );
+        } else if (retryAfterS !== null) {
+          const devDelay = Math.min(retryAfterS, DEV_REDELIVERY_MAX_DELAY_S);
+          scheduleDevRedelivery(buildRedeliveryCtx(), devDelay);
+        }
       } catch (error) {
         console.error(
-          `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
+          `${PREFIX} ${FAIL} Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
           error
         );
+        if (!handlerSucceeded) {
+          scheduleDevRedelivery(buildRedeliveryCtx(), consumerDefaultDelay);
+        }
       }
     }
   })();
@@ -1268,6 +1445,10 @@ function clearDevState() {
 }
 if (process.env.NODE_ENV === "test" || process.env.VITEST) {
   globalThis.__clearDevState = clearDevState;
+  globalThis.__filePathToConsumerGroup = filePathToConsumerGroup;
+  globalThis.__filePathToUrlPath = filePathToUrlPath;
+  globalThis.__matchesFunctionsPattern = matchesFunctionsPattern;
+  globalThis.__stripSrcPrefix = stripSrcPrefix;
 }
 
 // src/oidc.ts
@@ -1311,6 +1492,7 @@ function parseQueueHeaders(headers) {
   const timestamp = headers.get("Vqs-Timestamp");
   const contentType = headers.get("Content-Type") || "application/octet-stream";
   const receiptHandle = headers.get("Vqs-Receipt-Handle");
+  const expiresAtStr = headers.get("Vqs-Expires-At");
   if (!messageId || !timestamp || !receiptHandle) {
     return null;
   }
@@ -1322,6 +1504,7 @@ function parseQueueHeaders(headers) {
     messageId,
     deliveryCount,
     createdAt: new Date(timestamp),
+    expiresAt: expiresAtStr ? new Date(expiresAtStr) : void 0,
     contentType,
     receiptHandle
   };
@@ -1405,13 +1588,25 @@ var ApiClient = class _ApiClient {
     if (this.providedToken) {
       return this.providedToken;
     }
-    const token = await (0, import_oidc.getVercelOidcToken)();
-    if (!token) {
+    try {
+      return await (0, import_oidc.getVercelOidcToken)();
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
       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'"
+        isDevMode() ? `Failed to get OIDC token for local development.
+
+To fix this, pull your environment variables with Vercel CLI:
+  \`vercel env pull\`
+
+Cause: ${cause}` : `Failed to get OIDC token. This usually means the function is running outside of a Vercel Function environment.
+
+To fix this, either:
+  - Deploy to Vercel (OIDC tokens are provisioned automatically)
+  - Provide a token explicitly: \`new QueueClient({ token: '...' })\`
+
+Cause: ${cause}`
       );
     }
-    return token;
   }
   buildUrl(queueName, ...pathSegments) {
     const encodedQueue = encodeURIComponent(queueName);
@@ -1442,7 +1637,7 @@ var ApiClient = class _ApiClient {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.1.1"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.1.3"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -1817,9 +2012,11 @@ 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" })`
-  );
+  if (!isDevMode()) {
+    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 {
@@ -1857,7 +2054,8 @@ var QueueClient = class {
         topicName,
         result.messageId,
         api.getRegion(),
-        options?.delaySeconds
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };