@upstash/qstash 2.10.1 → 2.11.1

package/index.js

@@ -314,6 +314,9 @@ var formatWorkflowError = (error) => {
 
 // src/client/utils.ts
 var DEFAULT_BULK_COUNT = 100;
+function serializeLabel(label) {
+  return Array.isArray(label) ? label.join(",") : label;
+}
 var isIgnoredHeader = (header) => {
   const lowerCaseHeader = header.toLowerCase();
   return lowerCaseHeader.startsWith("content-type") || lowerCaseHeader.startsWith("upstash-");
@@ -398,7 +401,7 @@ function processHeaders(request) {
     headers.set("Upstash-Flow-Control-Value", controlValue.join(", "));
   }
   if (request.label !== void 0) {
-    headers.set("Upstash-Label", request.label);
+    headers.set("Upstash-Label", serializeLabel(request.label));
   }
   if (request.redact !== void 0) {
     const redactParts = [];
@@ -490,17 +493,23 @@ function normalizeCursor(response) {
   const cursor = response.cursor;
   return { ...response, cursor: cursor || void 0 };
 }
+function _processGlobal() {
+  const proc = globalThis["process"];
+  return proc;
+}
 function getRuntime() {
-  if (typeof process === "object" && typeof process.versions == "object" && process.versions.bun)
-    return `bun@${process.versions.bun}`;
+  const proc = _processGlobal();
+  if (proc?.versions?.bun)
+    return `bun@${proc.versions.bun}`;
   if (typeof EdgeRuntime === "string")
     return "edge-light";
-  else if (typeof process === "object" && typeof process.version === "string")
-    return `node@${process.version}`;
+  if (typeof proc?.version === "string")
+    return `node@${proc.version}`;
   return "";
 }
 function getSafeEnvironment() {
-  return typeof process === "undefined" ? {} : process.env;
+  const proc = _processGlobal();
+  return proc?.env ?? {};
 }
 
 // src/client/multi-region/utils.ts
@@ -544,12 +553,453 @@ function normalizeRegionHeader(region) {
   return void 0;
 }
 
+// src/dev-server/constants.ts
+var DEFAULT_DEV_PORT = 8080;
+var DEV_CREDENTIALS = {
+  token: "eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=",
+  currentSigningKey: "sig_7kYjw48mhY7kAjqNGcy6cr29RJ6r",
+  nextSigningKey: "sig_5ZB6DVzB1wjE8S6rZ7eenA8Pdnhs"
+};
+var GITHUB_RELEASES_URL = "https://api.github.com/repos/upstash/qstash-cli/releases/latest";
+var BINARY_URL_BASE = "https://artifacts.upstash.com/qstash/versions";
+var CONSOLE_URL = "https://console.upstash.com/qstash/local-mode-user";
+var DEV_PREFIX = "\x1B[2m[QStash Dev]\x1B[0m";
+var CLI_PREFIX = "\x1B[2m[QStash CLI]\x1B[0m";
+var _n = (m) => `node:${m}`;
+var importHttp = () => import(
+  /* webpackIgnore: true */
+  _n("http")
+);
+var importHttps = () => import(
+  /* webpackIgnore: true */
+  _n("https")
+);
+var importFs = () => import(
+  /* webpackIgnore: true */
+  _n("fs")
+);
+var importChildProcess = () => import(
+  /* webpackIgnore: true */
+  _n("child_process")
+);
+var importOs = () => import(
+  /* webpackIgnore: true */
+  _n("os")
+);
+
+// src/dev-server/http.ts
+var HTTP_OK = 200;
+var HTTP_MULTI_CHOICE = 300;
+var nativeGet = async (url, headers, timeoutMs) => {
+  const parsedUrl = new URL(url);
+  const httpModule = parsedUrl.protocol === "https:" ? await importHttps() : await importHttp();
+  return new Promise((resolve, reject) => {
+    const request = httpModule.get(url, { headers }, (response) => {
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => {
+        const statusCode = response.statusCode ?? 0;
+        resolve({
+          ok: statusCode >= HTTP_OK && statusCode < HTTP_MULTI_CHOICE,
+          statusCode,
+          body: Buffer.concat(chunks)
+        });
+      });
+      response.on("error", reject);
+    });
+    if (timeoutMs) {
+      request.setTimeout(timeoutMs, () => {
+        request.destroy(new Error("Request timed out"));
+      });
+    }
+    request.on("error", reject);
+  });
+};
+
+// src/dev-server/health.ts
+var HEALTH_CHECK_TIMEOUT_MS = 2e3;
+var isDevServerRunning = async (baseUrl) => {
+  try {
+    const { ok: ok4, body } = await nativeGet(
+      `${baseUrl}/v2/keys`,
+      { Authorization: `Bearer ${DEV_CREDENTIALS.token}` },
+      HEALTH_CHECK_TIMEOUT_MS
+    );
+    if (!ok4)
+      return false;
+    const data = JSON.parse(body.toString());
+    return data.current === DEV_CREDENTIALS.currentSigningKey && data.next === DEV_CREDENTIALS.nextSigningKey;
+  } catch {
+    return false;
+  }
+};
+var _didLogUnreachable = false;
+var checkDevServerReachable = async (baseUrl, runtime) => {
+  if (await pingEdge(baseUrl))
+    return;
+  if (!_didLogUnreachable) {
+    console.error(unreachableMessage(baseUrl, runtime));
+    _didLogUnreachable = true;
+  }
+  throw new Error(`${DEV_PREFIX} dev server unreachable at ${baseUrl}`);
+};
+var pingEdge = async (baseUrl) => {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, HEALTH_CHECK_TIMEOUT_MS);
+    const response = await fetch(`${baseUrl}/v2/keys`, {
+      headers: { Authorization: `Bearer ${DEV_CREDENTIALS.token}` },
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+var unreachableMessage = (baseUrl, runtime) => {
+  const port = new URL(baseUrl).port;
+  const manualStartCmd = `npx @upstash/qstash-cli dev --port ${port}`;
+  const header = `
+${DEV_PREFIX} The dev server is not running at ${baseUrl}.
+
+`;
+  if (runtime === "cloudflare-workers") {
+    return header + `Cloudflare Workers cannot start the dev server automatically.
+Start it manually before running wrangler dev:
+
+  ${manualStartCmd}
+`;
+  }
+  return header + `Edge runtimes cannot start the dev server automatically.
+Either:
+  1. Add the instrumentation hook to start it with your app:
+
+     // instrumentation.ts
+     import { registerQStashDev } from "@upstash/qstash/nextjs";
+     export async function register() { await registerQStashDev(); }
+
+  2. Or start it manually:
+
+     ${manualStartCmd}
+`;
+};
+
+// src/dev-server/binary.ts
+var ensureBinary = async () => {
+  const fs = await importFs();
+  const os = await importOs();
+  const cacheDirectory = await findCacheDirectory();
+  const isWindows = os.platform() === "win32";
+  const binaryName = isWindows ? "qstash.exe" : "qstash";
+  const binaryPath = `${cacheDirectory}/${binaryName}`;
+  const versionFile = `${cacheDirectory}/.version`;
+  let version;
+  try {
+    version = await fetchLatestVersion();
+  } catch (error) {
+    if (fs.existsSync(binaryPath)) {
+      const cachedVersion = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, "utf8").trim() : "unknown";
+      console.log(`${DEV_PREFIX} Offline, using local v${cachedVersion}`);
+      return binaryPath;
+    }
+    throw error;
+  }
+  return downloadBinary(version, cacheDirectory);
+};
+var fetchLatestVersion = async () => {
+  const { ok: ok4, statusCode, body } = await nativeGet(GITHUB_RELEASES_URL, {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "upstash-qstash-js"
+  });
+  if (!ok4) {
+    throw new Error(`[QStash Dev] Failed to fetch latest version: HTTP ${statusCode}`);
+  }
+  const data = JSON.parse(body.toString());
+  return data.tag_name.replace(/^v/, "");
+};
+var findCacheDirectory = async () => {
+  const fs = await importFs();
+  const os = await importOs();
+  const home = os.homedir();
+  const platform = os.platform();
+  let base;
+  if (platform === "darwin") {
+    base = `${home}/Library/Caches/upstash`;
+  } else if (platform === "win32") {
+    base = `${process.env.LOCALAPPDATA ?? `${home}/AppData/Local`}/upstash`;
+  } else {
+    base = `${home}/.cache/upstash`;
+  }
+  const cacheDirectory = `${base}/qstash-dev`;
+  await fs.promises.mkdir(cacheDirectory, { recursive: true });
+  return cacheDirectory;
+};
+var downloadBinary = async (version, cacheDirectory) => {
+  const fs = await importFs();
+  const childProcess = await importChildProcess();
+  const os = await importOs();
+  const osPlatform = os.platform();
+  const isWindows = osPlatform === "win32";
+  const platform = isWindows ? "windows" : osPlatform === "darwin" ? "darwin" : "linux";
+  const arch = os.arch() === "arm64" ? "arm64" : "amd64";
+  const archiveName = `qstash-server_${version}_${platform}_${arch}`;
+  const binaryName = isWindows ? "qstash.exe" : "qstash";
+  const binaryPath = `${cacheDirectory}/${binaryName}`;
+  const versionFile = `${cacheDirectory}/.version`;
+  if (fs.existsSync(binaryPath) && fs.existsSync(versionFile)) {
+    const cachedVersion = fs.readFileSync(versionFile, "utf8").trim();
+    if (cachedVersion === version) {
+      return binaryPath;
+    }
+  }
+  await fs.promises.rm(cacheDirectory, { recursive: true, force: true });
+  await fs.promises.mkdir(cacheDirectory, { recursive: true });
+  const extension = isWindows ? "zip" : "tar.gz";
+  const archiveUrl = `${BINARY_URL_BASE}/${version}/${archiveName}.${extension}`;
+  console.log(`${DEV_PREFIX} Downloading dev server v${version}...`);
+  const { ok: ok4, statusCode, body } = await nativeGet(archiveUrl);
+  if (!ok4) {
+    throw new Error(`[QStash Dev] Failed to download binary: HTTP ${statusCode}`);
+  }
+  const archivePath = `${cacheDirectory}/${archiveName}.${extension}`;
+  await fs.promises.writeFile(archivePath, new Uint8Array(body));
+  childProcess.execFileSync("tar", ["-xf", archivePath, "-C", cacheDirectory], {
+    stdio: "pipe"
+  });
+  if (!isWindows) {
+    const EXECUTABLE_PERMISSION = 493;
+    await fs.promises.chmod(binaryPath, EXECUTABLE_PERMISSION);
+  }
+  await fs.promises.writeFile(versionFile, version);
+  await fs.promises.unlink(archivePath).catch(() => {
+  });
+  return binaryPath;
+};
+
+// src/dev-server/process.ts
+var STARTUP_TIMEOUT_MS = 3e4;
+var _proc = () => {
+  return globalThis["process"] ?? {};
+};
+var spawnServer = async (binaryPath, port, onUnexpectedExit) => {
+  const childProcess = await importChildProcess();
+  const child = await new Promise((resolve, reject) => {
+    const child2 = childProcess.spawn(binaryPath, ["dev", "--port", String(port)], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const timeout = setTimeout(() => {
+      child2.kill();
+      reject(new Error("[QStash Dev] Server failed to start within 30 seconds"));
+    }, STARTUP_TIMEOUT_MS);
+    let startupOutput = "";
+    let started = false;
+    const bufferLine = (line) => {
+      if (!started)
+        startupOutput += `${line}
+`;
+    };
+    forwardWithPrefix(child2.stdout, _proc().stdout, (line) => {
+      bufferLine(line);
+      if (!started && /runn+ing( at|\.)/i.test(line)) {
+        clearTimeout(timeout);
+        started = true;
+        resolve(child2);
+      }
+    });
+    forwardWithPrefix(child2.stderr, _proc().stderr, bufferLine);
+    child2.on("error", (error) => {
+      clearTimeout(timeout);
+      reject(new Error(`[QStash Dev] Failed to start server: ${error.message}`));
+    });
+    child2.on("close", (code, _signal) => {
+      if (started) {
+        onUnexpectedExit?.();
+        return;
+      }
+      clearTimeout(timeout);
+      reject(new Error(formatStartupError(code, startupOutput)));
+    });
+  });
+  registerCleanup(child);
+  child.unref?.();
+  child.stdout?.unref?.();
+  child.stderr?.unref?.();
+};
+var formatStartupError = (code, startupOutput) => {
+  const cleaned = startupOutput.replaceAll(/\u001B\[[\d;]*m/g, "").replaceAll(/^\d{1,2}:\d{2}(AM|PM)\s+\w{3}\s+/gm, "").trim();
+  if (/address already in use/i.test(cleaned)) {
+    const match = /:(\d+)\s*$/.exec(cleaned);
+    const portHint = match ? ` on port ${match[1]}` : "";
+    return `[QStash Dev] Port already in use${portHint}. Set QSTASH_DEV_PORT to use a different port, or stop the process holding it.`;
+  }
+  const codeSuffix = code ? ` with code ${code}` : "";
+  const detail = cleaned ? `: ${cleaned}` : "";
+  return `[QStash Dev] Server exited unexpectedly${codeSuffix}${detail}`;
+};
+var forwardWithPrefix = (source, destination, onLine) => {
+  if (!source)
+    return;
+  let buffer = "";
+  const flushLine = (line) => {
+    destination?.write(`${CLI_PREFIX} ${line}
+`);
+    onLine(line);
+  };
+  source.on("data", (data) => {
+    buffer += data.toString();
+    let newlineIndex = buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      flushLine(buffer.slice(0, newlineIndex));
+      buffer = buffer.slice(newlineIndex + 1);
+      newlineIndex = buffer.indexOf("\n");
+    }
+  });
+  source.on("end", () => {
+    if (buffer.length > 0) {
+      flushLine(buffer);
+      buffer = "";
+    }
+  });
+  source.on("error", () => {
+  });
+};
+var currentChild;
+var processHandlersRegistered = false;
+var killCurrentChild = () => {
+  if (!currentChild)
+    return;
+  try {
+    currentChild.kill("SIGTERM");
+  } catch {
+  }
+  currentChild = void 0;
+};
+var registerCleanup = (child) => {
+  currentChild = child;
+  if (!processHandlersRegistered) {
+    processHandlersRegistered = true;
+    const proc = _proc();
+    proc.on?.("exit", killCurrentChild);
+    proc.on?.("SIGINT", () => {
+      killCurrentChild();
+      proc.exit?.(0);
+    });
+    proc.on?.("SIGTERM", () => {
+      killCurrentChild();
+      proc.exit?.(0);
+    });
+  }
+};
+
+// src/dev-server/index.ts
+var _processGlobal2 = () => {
+  const proc = globalThis["process"];
+  return proc;
+};
+var devServerPromise;
+var ensureDevelopmentServer = (env, devMode) => {
+  if (!shouldUseDevelopmentMode(devMode, env))
+    return Promise.resolve();
+  const procEnv = _processGlobal2()?.env;
+  if (procEnv?.NEXT_PHASE === "phase-production-build")
+    return Promise.resolve();
+  if (procEnv?.NODE_ENV === "production")
+    return Promise.resolve();
+  const runtime = getRuntime2();
+  if (runtime !== "nodejs") {
+    return checkDevServerReachable(getDevUrl(env), runtime);
+  }
+  if (!devServerPromise) {
+    devServerPromise = startPipeline(env).catch((error) => {
+      devServerPromise = void 0;
+      throw error;
+    });
+  }
+  return devServerPromise;
+};
+var startPipeline = async (env) => {
+  const baseUrl = getDevUrl(env);
+  const port = new URL(baseUrl).port;
+  const consoleLink = `\x1B[36m${CONSOLE_URL}?port=${port}\x1B[0m`;
+  if (await isDevServerRunning(baseUrl)) {
+    console.log(
+      `${DEV_PREFIX} Server already running at ${baseUrl}
+${DEV_PREFIX} Console: ${consoleLink}`
+    );
+    return;
+  }
+  const binaryPath = await ensureBinary();
+  await spawnServer(binaryPath, port, () => {
+    devServerPromise = void 0;
+  });
+};
+var shouldUseDevelopmentMode = (devMode, env) => {
+  if (devMode !== void 0)
+    return devMode;
+  const value = env?.QSTASH_DEV ?? getProcessEnvironment("QSTASH_DEV");
+  if (value === void 0 || value === "" || value === "false" || value === "0")
+    return false;
+  if (value === "true" || value === "1")
+    return true;
+  throw new Error(`[QStash Dev] Invalid value for QSTASH_DEV in environment: ${value}`);
+};
+var getDevelopmentCredentials = (env) => {
+  return {
+    ...DEV_CREDENTIALS,
+    baseUrl: getDevUrl(env)
+  };
+};
+var getDevUrl = (env) => {
+  const portString = env?.QSTASH_DEV_PORT ?? getProcessEnvironment("QSTASH_DEV_PORT");
+  let port = DEFAULT_DEV_PORT;
+  if (portString) {
+    const parsed = Number.parseInt(portString, 10);
+    if (!Number.isNaN(parsed) && parsed > 0) {
+      port = parsed;
+    }
+  }
+  return `http://127.0.0.1:${port}`;
+};
+var getRuntime2 = () => {
+  if (typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers") {
+    return "cloudflare-workers";
+  }
+  const proc = _processGlobal2();
+  if (!proc) {
+    return "browser";
+  }
+  if (!proc.release?.name) {
+    return "edge";
+  }
+  return "nodejs";
+};
+var getProcessEnvironment = (key) => {
+  const proc = _processGlobal2();
+  return proc?.env ? proc.env[key] : void 0;
+};
+
 // src/client/multi-region/incoming.ts
 var getReceiverSigningKeys = ({
   environment,
   regionFromHeader,
-  config
+  config,
+  devMode
 }) => {
+  if (shouldUseDevelopmentMode(devMode, environment)) {
+    if (config?.currentSigningKey || config?.nextSigningKey) {
+      console.warn(
+        `${DEV_PREFIX} Dev mode is active. Ignoring signing keys from config. Set devMode: false to use your own keys.`
+      );
+    }
+    const developmentCreds = getDevelopmentCredentials(environment);
+    return {
+      currentSigningKey: developmentCreds.currentSigningKey,
+      nextSigningKey: developmentCreds.nextSigningKey
+    };
+  }
   if (config?.currentSigningKey && config.nextSigningKey) {
     return {
       currentSigningKey: config.currentSigningKey,
@@ -594,8 +1044,21 @@ var getClientCredentials = (clientCredentialConfig) => {
 };
 var resolveCredentials = ({
   environment,
-  config
+  config,
+  devMode
 }) => {
+  if (shouldUseDevelopmentMode(devMode, environment)) {
+    if (config?.baseUrl || config?.token) {
+      console.warn(
+        `${DEV_PREFIX} Dev mode is active. Ignoring baseUrl/token from config. Set devMode: false to use your own credentials.`
+      );
+    }
+    const developmentCreds = getDevelopmentCredentials(environment);
+    return {
+      baseUrl: developmentCreds.baseUrl,
+      token: developmentCreds.token
+    };
+  }
   if (config?.baseUrl && config.token) {
     return {
       baseUrl: config.baseUrl,
@@ -648,9 +1111,11 @@ var SignatureError = class extends Error {
 var Receiver = class {
   currentSigningKey;
   nextSigningKey;
+  devMode;
   constructor(config) {
     this.currentSigningKey = config?.currentSigningKey;
     this.nextSigningKey = config?.nextSigningKey;
+    this.devMode = config?.devMode;
   }
   /**
    * Verify the signature of a request.
@@ -669,7 +1134,8 @@ var Receiver = class {
       config: {
         currentSigningKey: this.currentSigningKey,
         nextSigningKey: this.nextSigningKey
-      }
+      },
+      devMode: this.devMode
     });
     if (!signingKeys) {
       throw new Error(
@@ -935,12 +1401,14 @@ var HttpClient = class {
   baseUrl;
   authorization;
   options;
+  devMode;
   retry;
   headers;
   telemetryHeaders;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.authorization = config.authorization;
+    this.devMode = config.devMode;
     this.retry = // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     typeof config.retry === "boolean" && !config.retry ? {
       attempts: 1,
@@ -953,6 +1421,7 @@ var HttpClient = class {
     this.telemetryHeaders = config.telemetryHeaders;
   }
   async request(request) {
+    await ensureDevelopmentServer(void 0, this.devMode);
     const { response } = await this.requestWithBackoff(request);
     if (request.parseResponseAsJson === false) {
       return void 0;
@@ -960,6 +1429,7 @@ var HttpClient = class {
     return await response.json();
   }
   async *requestStream(request) {
+    await ensureDevelopmentServer(void 0, this.devMode);
     const { response } = await this.requestWithBackoff(request);
     if (!response.body) {
       throw new Error("No response body");
@@ -1713,7 +2183,7 @@ var Workflow = class {
 };
 
 // version.ts
-var VERSION = "2.10.1";
+var VERSION = "2.11.1";
 
 // src/client/client.ts
 var Client = class {
@@ -1721,7 +2191,14 @@ var Client = class {
   token;
   constructor(config) {
     const environment = getSafeEnvironment();
-    const { baseUrl, token } = getClientCredentials({ environment, config });
+    const { baseUrl, token } = getClientCredentials({
+      environment,
+      config,
+      devMode: config?.devMode
+    });
+    if (shouldUseDevelopmentMode(config?.devMode, environment)) {
+      void ensureDevelopmentServer(environment, config?.devMode);
+    }
     const enableTelemetry = environment.UPSTASH_DISABLE_TELEMETRY ? false : config?.enableTelemetry ?? true;
     const isCloudflare = typeof caches !== "undefined" && "default" in caches;
     const telemetryHeaders = new Headers(
@@ -1738,7 +2215,8 @@ var Client = class {
       //@ts-expect-error caused by undici and bunjs type overlap
       headers: prefixHeaders(new Headers(config?.headers ?? {})),
       //@ts-expect-error caused by undici and bunjs type overlap
-      telemetryHeaders
+      telemetryHeaders,
+      devMode: config?.devMode
     });
     this.token = token;
   }

package/index.mjs

@@ -1,6 +1,6 @@
 import {
   resend
-} from "./chunk-Z37KJCW7.mjs";
+} from "./chunk-ATX5KA4T.mjs";
 import {
   Chat,
   Client,
@@ -24,7 +24,7 @@ import {
   openai,
   setupAnalytics,
   upstash
-} from "./chunk-35B33QW3.mjs";
+} from "./chunk-T3Z5YUS4.mjs";
 export {
   Chat,
   Client,

package/nextjs.d.mts

@@ -1,6 +1,6 @@
 import { NextApiHandler } from 'next';
 import { NextRequest, NextFetchEvent } from 'next/server';
-import { ae as RouteFunction, af as WorkflowServeOptions } from './client-CsM1dTnz.mjs';
+import { ae as RouteFunction, af as WorkflowServeOptions } from './client-BHOXiX0H.mjs';
 import 'neverthrow';
 
 type VerifySignatureConfig = {
@@ -18,6 +18,17 @@ type VerifySignatureConfig = {
      * @default 0
      */
     clockTolerance?: number;
+    /**
+     * Use the local dev server signing keys. Pair this with
+     * `new Client({ devMode: true })` for end-to-end local development.
+     *
+     * - `true`: use dev server signing keys
+     * - `false`: never use dev server signing keys (ignores QSTASH_DEV env var)
+     * - `undefined`: check QSTASH_DEV env var
+     *
+     * @default undefined
+     */
+    devMode?: boolean;
 };
 declare function verifySignature(handler: NextApiHandler, config?: VerifySignatureConfig): NextApiHandler;
 declare function verifySignatureEdge(handler: (request: NextRequest, nfe?: NextFetchEvent) => Response | Promise<Response>, config?: VerifySignatureConfig): (request: NextRequest, nfe: NextFetchEvent) => Promise<Response>;
@@ -43,5 +54,25 @@ declare const serve: <TInitialPayload = unknown>(routeFunction: RouteFunction<TI
  * Migration Guide: https://upstash.com/docs/workflow/migration
  */
 declare const servePagesRouter: <TInitialPayload = unknown>(routeFunction: RouteFunction<TInitialPayload>, options?: Omit<WorkflowServeOptions<Response, TInitialPayload>, "onStepFinish">) => NextApiHandler;
+/**
+ * Start the QStash dev server early during Next.js initialization.
+ *
+ * Call this inside your `instrumentation.ts` `register()` function so
+ * the dev server is ready before any request — including edge routes
+ * that cannot start it themselves.
+ *
+ * No-op in production, during `next build`, or in edge runtime.
+ *
+ * @example
+ * ```ts
+ * // instrumentation.ts
+ * import { registerQStashDev } from "@upstash/qstash/nextjs";
+ *
+ * export function register() {
+ *   registerQStashDev();
+ * }
+ * ```
+ */
+declare function registerQStashDev(): Promise<void>;
 
-export { type VerifySignatureConfig, serve, servePagesRouter, verifySignature, verifySignatureAppRouter, verifySignatureEdge };
+export { type VerifySignatureConfig, registerQStashDev, serve, servePagesRouter, verifySignature, verifySignatureAppRouter, verifySignatureEdge };