use-convex 0.0.2 → 1.1.0

package/dist/runtime/server/authCookies.js

@@ -1,10 +1,4 @@
-import {
-  deleteCookie,
-  getCookie,
-  getRequestHeader,
-  setCookie
-} from "h3";
-import { useRuntimeConfig } from "nitropack/runtime";
+import { deleteCookie, getCookie, getRequestHeader, setCookie } from "h3";
 import {
   AUTH_JWT_COOKIE_MAX_AGE,
   isHttpOnlyAuth,
@@ -12,32 +6,18 @@ import {
   resolveAuthPresentCookieName,
   resolveAuthRefreshCookieName
 } from "../utils/authStorage.js";
+import { readConvexConfig } from "./convexConfig.js";
 function readAuthConfig(event) {
-  try {
-    const config = useRuntimeConfig(event);
-    return config.public?.convex?.auth;
-  } catch {
-    return void 0;
-  }
+  return readConvexConfig(event)?.auth;
 }
 function isLocalHost(event) {
   const host = getRequestHeader(event, "host") ?? "";
   return host.startsWith("localhost") || host.startsWith("127.0.0.1") || host.startsWith("[::1]");
 }
-function httpOnlyCookieOptions(event) {
-  const local = isLocalHost(event);
-  return {
-    httpOnly: true,
-    secure: !local,
-    sameSite: "lax",
-    path: "/",
-    maxAge: AUTH_JWT_COOKIE_MAX_AGE
-  };
-}
-function readableCookieOptions(event) {
+function cookieOptions(event, httpOnly) {
   const local = isLocalHost(event);
   return {
-    httpOnly: false,
+    httpOnly,
     secure: !local,
     sameSite: "lax",
     path: "/",
@@ -47,15 +27,13 @@ function readableCookieOptions(event) {
 export function setAuthCookies(event, tokens) {
   const auth = readAuthConfig(event);
   if (!isHttpOnlyAuth(auth)) {
-    throw new Error(
-      "[convex-nuxt] setAuthCookies requires convex.auth.httpOnly: true"
-    );
+    throw new Error("[use-convex] setAuthCookies requires convex.auth.httpOnly: true");
   }
   const jwtName = resolveAuthCookieName(auth);
   const refreshName = resolveAuthRefreshCookieName(auth);
   const presentName = resolveAuthPresentCookieName(auth);
-  const httpOpts = httpOnlyCookieOptions(event);
-  const presentOpts = readableCookieOptions(event);
+  const httpOpts = cookieOptions(event, true);
+  const presentOpts = cookieOptions(event, false);
   if (!tokens.token) {
     deleteCookie(event, jwtName, httpOpts);
     deleteCookie(event, refreshName, httpOpts);

package/dist/runtime/server/convexConfig.d.ts

@@ -0,0 +1,12 @@
+import type { H3Event } from 'h3';
+export interface ConvexPublicConfig {
+    url?: string;
+    auth?: {
+        provider?: string;
+        cookie?: string;
+        httpOnly?: boolean;
+        presentCookie?: string;
+    };
+}
+/** Read `runtimeConfig.public.convex`, or `undefined` outside a Nitro request. */
+export declare function readConvexConfig(event?: H3Event): ConvexPublicConfig | undefined;

package/dist/runtime/server/convexConfig.js

@@ -0,0 +1,9 @@
+import { useRuntimeConfig } from "nitropack/runtime";
+export function readConvexConfig(event) {
+  try {
+    const config = useRuntimeConfig(event);
+    return config.public?.convex;
+  } catch {
+    return void 0;
+  }
+}

package/dist/runtime/server/fetch.d.ts

@@ -1,7 +1,5 @@
 import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
 import type { H3Event } from 'h3';
-import { resolveFetchToken } from '../utils/fetchToken.js';
-export { resolveFetchToken };
 export interface ConvexFetchOptions {
     /**
      * Deployment URL. Defaults to `NUXT_PUBLIC_CONVEX_URL` / runtimeConfig.
@@ -18,9 +16,9 @@ export interface ConvexFetchOptions {
     event?: H3Event;
     skipConvexDeploymentUrlCheck?: boolean;
 }
-/** @internal Exported for unit tests. */
+/** @internal */
 export declare function resolveUrl(options: ConvexFetchOptions): string;
-/** @internal Exported for unit tests. */
+/** @internal */
 export declare function resolveToken(options: ConvexFetchOptions): string | undefined;
 /**
  * One-shot query via ConvexHttpClient. Use in Nitro routes / server middleware.

package/dist/runtime/server/fetch.js

@@ -1,17 +1,9 @@
 import { getCookie } from "h3";
-import { useRuntimeConfig } from "nitropack/runtime";
 import { createHttpClient } from "../utils/http.js";
 import { resolveAuthCookieName } from "../utils/authStorage.js";
 import { resolveFetchToken } from "../utils/fetchToken.js";
-export { resolveFetchToken };
-function readConvexConfig(event) {
-  try {
-    const config = useRuntimeConfig(event);
-    return config.public?.convex;
-  } catch {
-    return void 0;
-  }
-}
+import { missingConvexUrlError } from "../utils/errors.js";
+import { readConvexConfig } from "./convexConfig.js";
 export function resolveUrl(options) {
   if (options.url) {
     return options.url;
@@ -24,9 +16,7 @@ export function resolveUrl(options) {
   if (fromEnv) {
     return fromEnv;
   }
-  throw new Error(
-    "[convex-nuxt] No Convex URL. Pass { url } or set NUXT_PUBLIC_CONVEX_URL."
-  );
+  throw missingConvexUrlError("fetchQuery/Mutation/Action");
 }
 export function resolveToken(options) {
   if (options.token !== void 0) {

package/dist/runtime/server/routes/__convex_devtools.get.d.ts

@@ -1,6 +1,10 @@
 /**
- * Minimal DevTools iframe — shows public Convex runtime config.
- * Connection state is available in-app via `useConvexConnectionState()`.
+ * DevTools iframe — embeds Convex dashboard (cloud) + public config tips.
+ * Live auth/connection: `window.__CONVEX_NUXT__` (devtools client plugin).
+ *
+ * Auto-login uses CONVEX_DEPLOY_KEY via postMessage to dashboard-embedded.
+ * Without a key, the embed shows Convex's credential form; Open dashboard
+ * still deep-links to dashboard.convex.dev (existing session).
  */
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, string>;
 export default _default;

package/dist/runtime/server/routes/__convex_devtools.get.js

@@ -1,32 +1,200 @@
 import { defineEventHandler } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
+import { buildDevtoolsDashboardPayload } from "../../utils/convexDashboard.js";
 export default defineEventHandler((event) => {
   const config = useRuntimeConfig(event);
   const convex = config.public?.convex ?? {};
-  const body = JSON.stringify(
-    {
-      url: convex.url ?? null,
-      server: convex.server ?? true,
-      auth: convex.auth ?? null,
-      tip: "useConvexConnectionState() for live WebSocket status in the app"
-    },
-    null,
-    2
-  );
+  const devtools = config.convexDevtools;
+  const url = typeof convex.url === "string" && convex.url.trim() || typeof devtools?.url === "string" && devtools.url.trim() || process.env.NUXT_PUBLIC_CONVEX_URL?.trim() || process.env.CONVEX_URL?.trim() || null;
+  const hasUrl = Boolean(url);
+  const summary = {
+    url,
+    server: convex.server ?? true,
+    auth: convex.auth ? {
+      provider: convex.auth.provider ?? null,
+      cookie: convex.auth.cookie ?? null,
+      httpOnly: convex.auth.httpOnly ?? false,
+      presentCookie: convex.auth.presentCookie ?? null
+    } : null
+  };
+  const tips = [
+    hasUrl ? "Deployment URL is set." : "No URL \u2014 set convex.url or NUXT_PUBLIC_CONVEX_URL.",
+    "Set CONVEX_DEPLOY_KEY for dashboard auto-login in this tab (dev only).",
+    "In the app console: window.__CONVEX_NUXT__.connection (WebSocket).",
+    "In the app console: window.__CONVEX_NUXT__.auth (gate flags).",
+    "Gate private live queries with { authenticated: true }.",
+    "SSR off globally: convex.server: false \u2014 or per call { server: false }."
+  ];
+  const dashboard = buildDevtoolsDashboardPayload({
+    url,
+    convexDeployment: devtools?.deployment || process.env.CONVEX_DEPLOYMENT,
+    deployKey: devtools?.deployKey || process.env.CONVEX_DEPLOY_KEY
+  });
+  const configJson = JSON.stringify({ config: summary, tips }).replace(/</g, "\\u003c");
+  const dashboardJson = JSON.stringify({
+    deploymentUrl: dashboard.deploymentUrl,
+    deploymentName: dashboard.deploymentName,
+    adminKey: dashboard.adminKey,
+    embed: dashboard.embed,
+    embedSrc: dashboard.embedSrc,
+    embedOrigin: dashboard.embedOrigin
+  }).replace(/</g, "\\u003c");
+  const openHref = dashboard.openDashboardUrl ? escapeHtml(dashboard.openDashboardUrl) : null;
+  const urlLabel = dashboard.deploymentUrl ? escapeHtml(dashboard.deploymentUrl) : "No deployment URL";
+  const statusLabel = !dashboard.embed ? "Hosted embed needs a *.convex.cloud URL" : dashboard.adminKey ? "Auto-login via CONVEX_DEPLOY_KEY" : "Paste credentials in the embed, or Open dashboard";
+  const embedBlock = dashboard.embed ? `<div id="embed-wrap" class="embed${dashboard.adminKey ? " pending" : ""}">
+  <iframe
+    id="convex-dashboard"
+    title="Convex dashboard"
+    src="${escapeHtml(dashboard.embedSrc)}"
+    allow="clipboard-write"
+  ></iframe>
+</div>` : `<div class="notice">
+  <p>The hosted Convex dashboard embed only works with Convex Cloud URLs (<code>*.convex.cloud</code>).</p>
+  <p>Local / self-hosted deployments: use the CLI dashboard or Open dashboard when a name is known.</p>
+</div>`;
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
-  <title>Convex \xB7 Nuxt DevTools</title>
+  <title>use-convex \xB7 DevTools</title>
   <style>
-    body { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; margin: 1rem; color: #e5e7eb; background: #0b1220; }
-    h1 { font-size: 0.95rem; font-weight: 600; margin: 0 0 0.75rem; color: #93c5fd; }
-    pre { margin: 0; white-space: pre-wrap; word-break: break-word; font-size: 0.8rem; line-height: 1.45; }
+    * { box-sizing: border-box; }
+    html, body {
+      height: 100%;
+      margin: 0;
+    }
+    body {
+      display: flex;
+      flex-direction: column;
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      color: #e5e7eb;
+      background: #0b1220;
+    }
+    header {
+      flex: 0 0 auto;
+      padding: 0.65rem 0.85rem;
+      border-bottom: 1px solid #1f2937;
+      background: #0f172a;
+    }
+    .row {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: baseline;
+      gap: 0.5rem 0.85rem;
+    }
+    h1 {
+      font-size: 0.9rem;
+      font-weight: 600;
+      margin: 0;
+      color: #93c5fd;
+    }
+    .url {
+      font-size: 0.7rem;
+      color: #9ca3af;
+      word-break: break-all;
+    }
+    .status {
+      font-size: 0.7rem;
+      color: #a5b4fc;
+    }
+    a.open {
+      font-size: 0.75rem;
+      color: #67e8f9;
+      text-decoration: none;
+    }
+    a.open:hover { text-decoration: underline; }
+    details {
+      margin-top: 0.45rem;
+    }
+    summary {
+      cursor: pointer;
+      font-size: 0.7rem;
+      color: #9ca3af;
+      user-select: none;
+    }
+    pre {
+      margin: 0.4rem 0 0;
+      white-space: pre-wrap;
+      word-break: break-word;
+      font-size: 0.72rem;
+      line-height: 1.4;
+      max-height: 12rem;
+      overflow: auto;
+    }
+    .embed {
+      flex: 1 1 auto;
+      min-height: 0;
+      position: relative;
+    }
+    .embed.pending iframe { visibility: hidden; }
+    iframe {
+      display: block;
+      width: 100%;
+      height: 100%;
+      border: 0;
+      background: #111827;
+    }
+    .notice {
+      flex: 1 1 auto;
+      padding: 1rem 0.85rem;
+      font-size: 0.8rem;
+      color: #9ca3af;
+      line-height: 1.5;
+    }
+    .notice code { color: #93c5fd; }
   </style>
 </head>
 <body>
-  <h1>use-convex</h1>
-  <pre>${body.replace(/</g, "&lt;")}</pre>
+  <header>
+    <div class="row">
+      <h1>use-convex</h1>
+      <span class="url">${urlLabel}</span>
+      ${openHref ? `<a class="open" href="${openHref}" target="_blank" rel="noopener noreferrer">Open dashboard \u2197</a>` : ""}
+    </div>
+    <p class="status">${escapeHtml(statusLabel)}</p>
+    <details>
+      <summary>Module config &amp; tips</summary>
+      <pre id="config-pre"></pre>
+    </details>
+  </header>
+  ${embedBlock}
+  <script>
+    (function () {
+      var config = ${configJson};
+      var dash = ${dashboardJson};
+      var pre = document.getElementById('config-pre');
+      if (pre) pre.textContent = JSON.stringify(config, null, 2);
+
+      if (!dash.embed || !dash.adminKey) return;
+
+      var iframe = document.getElementById('convex-dashboard');
+      var wrap = document.getElementById('embed-wrap');
+      if (!iframe || !iframe.contentWindow) return;
+
+      function reveal() {
+        if (wrap) wrap.classList.remove('pending');
+      }
+
+      window.addEventListener('message', function (event) {
+        if (event.origin !== dash.embedOrigin) return;
+        if (!event.data || event.data.type !== 'dashboard-credentials-request') return;
+        iframe.contentWindow.postMessage(
+          {
+            type: 'dashboard-credentials',
+            adminKey: dash.adminKey,
+            deploymentUrl: dash.deploymentUrl,
+            deploymentName: dash.deploymentName,
+          },
+          dash.embedOrigin,
+        );
+        reveal();
+      });
+    })();
+  <\/script>
 </body>
 </html>`;
 });
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/dist/runtime/server/sameOrigin.js

@@ -1,8 +1,4 @@
-import {
-  createError,
-  getRequestHeader,
-  getRequestProtocol
-} from "h3";
+import { createError, getRequestHeader, getRequestProtocol } from "h3";
 export function assertSameOrigin(event) {
   const secFetchSite = getRequestHeader(event, "sec-fetch-site");
   if (secFetchSite === "same-origin" || secFetchSite === "none") {

package/dist/runtime/utils/authCookie.d.ts

@@ -1,6 +1,4 @@
 import { type ComputedRef } from 'vue';
-import { AUTH_JWT_COOKIE_MAX_AGE } from './authStorage.js';
-export { AUTH_JWT_COOKIE_MAX_AGE };
 /**
  * Shared JWT cookie for SSR snapshots. Same name + options as persistTokens
  * so plugin reads and sign-in/out writes share one Nuxt cookie ref.

package/dist/runtime/utils/authCookie.js

@@ -7,7 +7,6 @@ import {
   resolveAuthCookieName,
   resolveAuthPresentCookieName
 } from "./authStorage.js";
-export { AUTH_JWT_COOKIE_MAX_AGE };
 function cookieOptions(httpOnly) {
   return {
     sameSite: "lax",

package/dist/runtime/utils/authState.js

@@ -1,10 +1,5 @@
 export function resolveConvexAuthState(flags) {
-  const {
-    authProviderLoading,
-    authProviderAuthenticated,
-    isConvexAuthenticated,
-    isRefreshing
-  } = flags;
+  const { authProviderLoading, authProviderAuthenticated, isConvexAuthenticated, isRefreshing } = flags;
   if (authProviderLoading) {
     return {
       isLoading: true,

package/dist/runtime/utils/authStorage.js

@@ -7,7 +7,7 @@ export const DEFAULT_AUTH_PRESENT_COOKIE = "convex_auth_present";
 export const HTTPONLY_JWT_COOKIE = "__convexAuthJWT";
 export const HTTPONLY_REFRESH_COOKIE = "__convexAuthRefreshToken";
 export function storageNamespace(url) {
-  return url.replace(/[^a-zA-Z0-9]/g, "");
+  return url.replace(/[^a-z0-9]/gi, "");
 }
 export function storageKey(base, url) {
   return `${base}_${storageNamespace(url)}`;

package/dist/runtime/utils/context.js

@@ -1,5 +1,6 @@
 import { inject, ref } from "vue";
 import { useNuxtApp } from "nuxt/app";
+import { missingConvexUrlError } from "./errors.js";
 export const convexNuxtKey = Symbol("convex-nuxt");
 export function createAuthContext() {
   return {
@@ -33,8 +34,8 @@ export function tryUseConvexContext() {
 export function useConvexContext() {
   const ctx = tryUseConvexContext();
   if (!ctx) {
-    throw new Error(
-      "[convex-nuxt] Convex plugin did not start \u2014 set convex.url or NUXT_PUBLIC_CONVEX_URL (the module no-ops when the URL is empty)."
+    throw missingConvexUrlError(
+      "Convex plugin did not start (the module no-ops when the URL is empty)"
     );
   }
   return ctx;

package/dist/runtime/utils/convexDashboard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Helpers for linking / embedding the Convex dashboard from Nuxt DevTools.
+ * Pure — no Nitro / Nuxt imports so unit tests stay lightweight.
+ */
+export declare const DASHBOARD_EMBED_ORIGIN = "https://dashboard-embedded.convex.dev";
+export declare const DASHBOARD_EMBED_DATA_URL = "https://dashboard-embedded.convex.dev/data";
+export declare const DASHBOARD_HOST = "https://dashboard.convex.dev";
+/**
+ * Strip CLI prefixes like `dev:happy-animal-123` → `happy-animal-123`.
+ */
+export declare function deploymentNameFromEnv(value: string | undefined | null): string | null;
+/**
+ * Derive deployment name from a cloud URL host: `happy-animal-123.convex.cloud`.
+ */
+export declare function deploymentNameFromUrl(url: string | undefined | null): string | null;
+export declare function resolveDeploymentName(options: {
+    url?: string | null;
+    convexDeployment?: string | null;
+}): string | null;
+/** True when the URL looks like Convex Cloud (embeddable hosted dashboard). */
+export declare function isConvexCloudUrl(url: string | undefined | null): boolean;
+/** True for a loopback Convex backend (`npx convex dev --local`). */
+export declare function isLocalConvexUrl(url: string | undefined | null): boolean;
+/**
+ * When CONVEX_DEPLOYMENT is a cloud `dev:`/`prod:` name but the app URL is
+ * still loopback (CLI: "Can't safely modify .env.local"), return the cloud URL.
+ */
+export declare function suggestedCloudUrlFromMismatch(url: string | undefined | null, convexDeployment: string | undefined | null): string | null;
+export declare function dashboardDeepLink(deploymentName: string | null): string | null;
+export interface DevtoolsDashboardPayload {
+    deploymentUrl: string | null;
+    deploymentName: string | null;
+    /** Present only when CONVEX_DEPLOY_KEY is set (dev server only). */
+    adminKey: string | null;
+    embed: boolean;
+    openDashboardUrl: string | null;
+    embedSrc: string;
+    embedOrigin: string;
+}
+export declare function buildDevtoolsDashboardPayload(options: {
+    url?: string | null;
+    convexDeployment?: string | null;
+    deployKey?: string | null;
+}): DevtoolsDashboardPayload;

package/dist/runtime/utils/convexDashboard.js

@@ -0,0 +1,77 @@
+export const DASHBOARD_EMBED_ORIGIN = "https://dashboard-embedded.convex.dev";
+export const DASHBOARD_EMBED_DATA_URL = `${DASHBOARD_EMBED_ORIGIN}/data`;
+export const DASHBOARD_HOST = "https://dashboard.convex.dev";
+export function deploymentNameFromEnv(value) {
+  if (!value) return null;
+  const trimmed = value.split("#")[0]?.trim() ?? "";
+  if (!trimmed) return null;
+  const colon = trimmed.indexOf(":");
+  if (colon >= 0 && colon < trimmed.length - 1) {
+    return trimmed.slice(colon + 1);
+  }
+  return trimmed;
+}
+export function deploymentNameFromUrl(url) {
+  if (!url) return null;
+  try {
+    const { hostname } = new URL(url);
+    if (hostname.endsWith(".convex.cloud")) {
+      const name = hostname.slice(0, -".convex.cloud".length);
+      return name || null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+export function resolveDeploymentName(options) {
+  return deploymentNameFromUrl(options.url) ?? deploymentNameFromEnv(options.convexDeployment) ?? null;
+}
+export function isConvexCloudUrl(url) {
+  if (!url) return false;
+  try {
+    const { hostname } = new URL(url);
+    return hostname.endsWith(".convex.cloud");
+  } catch {
+    return false;
+  }
+}
+export function isLocalConvexUrl(url) {
+  if (!url) return false;
+  try {
+    const { hostname } = new URL(url);
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]";
+  } catch {
+    return false;
+  }
+}
+export function suggestedCloudUrlFromMismatch(url, convexDeployment) {
+  if (!isLocalConvexUrl(url)) return null;
+  const trimmed = convexDeployment?.split("#")[0]?.trim() ?? "";
+  if (!/^(dev|prod):/.test(trimmed)) return null;
+  const name = deploymentNameFromEnv(trimmed);
+  if (!name) return null;
+  return `https://${name}.convex.cloud`;
+}
+export function dashboardDeepLink(deploymentName) {
+  if (!deploymentName) return null;
+  return `${DASHBOARD_HOST}/d/${encodeURIComponent(deploymentName)}`;
+}
+export function buildDevtoolsDashboardPayload(options) {
+  const deploymentUrl = options.url?.trim() || null;
+  const deploymentName = resolveDeploymentName({
+    url: deploymentUrl,
+    convexDeployment: options.convexDeployment
+  });
+  const adminKey = options.deployKey?.trim() || null;
+  const embed = isConvexCloudUrl(deploymentUrl);
+  return {
+    deploymentUrl,
+    deploymentName,
+    adminKey: embed && adminKey ? adminKey : null,
+    embed,
+    openDashboardUrl: dashboardDeepLink(deploymentName),
+    embedSrc: DASHBOARD_EMBED_DATA_URL,
+    embedOrigin: DASHBOARD_EMBED_ORIGIN
+  };
+}

package/dist/runtime/utils/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Consistent, actionable errors for consumers of `use-convex`.
+ *
+ * Branding uses `[use-convex]` (package name). Older `[use-convex]` strings
+ * are migrated here so setup failures point to the same fix.
+ */
+export declare const USE_CONVEX_PREFIX = "[use-convex]";
+/** Missing deployment URL — the most common first-run failure. */
+export declare const MISSING_URL_HINT = "Set convex.url in nuxt.config or NUXT_PUBLIC_CONVEX_URL (runtimeConfig.public.convex.url).";
+export declare function useConvexError(message: string): Error;
+export declare function missingConvexUrlError(context?: string): Error;
+export declare function warnMissingConvexUrl(scope: 'client' | 'server'): void;
+export declare function unreachableConvexUrlError(convexUrl: string): Error;
+export declare function warnStaleLocalConvexUrl(localUrl: string, cloudUrl: string): void;

package/dist/runtime/utils/errors.js

@@ -0,0 +1,25 @@
+export const USE_CONVEX_PREFIX = "[use-convex]";
+export const MISSING_URL_HINT = "Set convex.url in nuxt.config or NUXT_PUBLIC_CONVEX_URL (runtimeConfig.public.convex.url).";
+export function useConvexError(message) {
+  const text = message.startsWith(USE_CONVEX_PREFIX) ? message : `${USE_CONVEX_PREFIX} ${message}`;
+  return new Error(text);
+}
+export function missingConvexUrlError(context) {
+  const where = context ? `${context}: ` : "";
+  return useConvexError(`${where}No Convex URL. ${MISSING_URL_HINT}`);
+}
+export function warnMissingConvexUrl(scope) {
+  console.warn(
+    `${USE_CONVEX_PREFIX} No Convex URL on ${scope}. ${MISSING_URL_HINT} The module no-ops until a URL is set.`
+  );
+}
+export function unreachableConvexUrlError(convexUrl) {
+  return useConvexError(
+    `Could not reach Convex at ${convexUrl}. If you switched from a local to a cloud deployment, set CONVEX_URL and NUXT_PUBLIC_CONVEX_URL in .env.local to the URL printed by \`npx convex dev\` and restart Nuxt. If you use a local backend, keep \`npx convex dev\` running.`
+  );
+}
+export function warnStaleLocalConvexUrl(localUrl, cloudUrl) {
+  console.warn(
+    `${USE_CONVEX_PREFIX} Convex URL is ${localUrl} but CONVEX_DEPLOYMENT is a cloud deployment. The Convex CLI could not update .env.local \u2014 set CONVEX_URL and NUXT_PUBLIC_CONVEX_URL to ${cloudUrl} and restart Nuxt.`
+  );
+}

package/dist/runtime/utils/oauthRedirect.js

@@ -1,12 +1,13 @@
+import { useConvexError } from "./errors.js";
 export function parseOAuthRedirect(redirect) {
   let url;
   try {
     url = new URL(redirect);
   } catch {
-    throw new Error("Invalid OAuth redirect URL");
+    throw useConvexError("Invalid OAuth redirect URL");
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("OAuth redirect must be http(s)");
+    throw useConvexError("OAuth redirect must be http(s)");
   }
   return url;
 }