@lupinum/better-convex-nuxt 0.8.0-beta.40

package/dist/runtime/utils/auth-route-protection.js

@@ -0,0 +1,58 @@
+const LOCAL_URL_BASE = "https://better-convex-nuxt.invalid";
+function hasUnsafePathCharacter(value) {
+  for (const character of value) {
+    const codeUnit = character.charCodeAt(0);
+    if (character === "\\" || codeUnit <= 31 || codeUnit === 127) return true;
+  }
+  return false;
+}
+export function normalizeLocalRedirectPath(value) {
+  if (!value.startsWith("/") || value.startsWith("//") || hasUnsafePathCharacter(value)) {
+    return null;
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  if (decoded.startsWith("//") || hasUnsafePathCharacter(decoded)) {
+    return null;
+  }
+  const parsed = new URL(value, LOCAL_URL_BASE);
+  if (parsed.origin !== LOCAL_URL_BASE || parsed.pathname.startsWith("//")) {
+    return null;
+  }
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+export function resolveRouteProtectionDecision(input) {
+  const { meta, defaultRedirectTo, preserveReturnTo, currentPath } = input;
+  const currentFullPath = input.currentFullPath ?? currentPath;
+  if (meta === void 0 || meta === false) return null;
+  const redirectBase = typeof meta === "object" && meta !== null && meta.redirectTo ? meta.redirectTo : defaultRedirectTo;
+  if (!redirectBase) return null;
+  if (typeof redirectBase !== "string") {
+    if ("path" in redirectBase && typeof redirectBase.path === "string") {
+      const path = normalizeLocalRedirectPath(redirectBase.path);
+      if (!path) return null;
+      return { redirectTo: { ...redirectBase, path } };
+    }
+    return { redirectTo: redirectBase };
+  }
+  const redirectPath = normalizeLocalRedirectPath(redirectBase);
+  if (!redirectPath) return null;
+  const redirectPathOnly = redirectPath.split(/[?#]/)[0] || redirectPath;
+  if (currentPath === redirectPathOnly) return null;
+  if (!preserveReturnTo) {
+    return { redirectTo: redirectPath };
+  }
+  const returnTo = normalizeLocalRedirectPath(currentFullPath) ?? normalizeLocalRedirectPath(currentPath) ?? "/";
+  const hashIndex = redirectPath.indexOf("#");
+  const redirectWithoutHash = hashIndex === -1 ? redirectPath : redirectPath.slice(0, hashIndex);
+  const hash = hashIndex === -1 ? "" : redirectPath.slice(hashIndex);
+  const hasQuery = redirectWithoutHash.includes("?");
+  const separator = hasQuery ? "&" : "?";
+  return {
+    redirectTo: `${redirectWithoutHash}${separator}redirect=${encodeURIComponent(returnTo)}${hash}`
+  };
+}

package/dist/runtime/utils/auth-status.d.ts

@@ -0,0 +1,47 @@
+import type { ConvexCallError } from '../errors/index.js';
+import { type ConvexIdentityKey } from './identity-key.js';
+/**
+ * Per-query authentication mode .
+ *
+ * | Mode       | Initial auth loading | Settled authenticated | Settled anonymous   |
+ * | ---------- | -------------------- | --------------------- | ------------------- |
+ * | `required` | Wait                 | Execute with identity | Stay idle           |
+ * | `optional` | Wait                 | Execute with identity | Execute anonymously |
+ * | `none`     | Do not wait          | Execute anonymously   | Execute anonymously |
+ *
+ * The fixed default is `optional`. There is no `auto` mode and no per-build
+ * default override; auth policy must not change invisibly between applications.
+ */
+export type ConvexAuthMode = 'required' | 'optional' | 'none';
+/**
+ * Current usable identity . Orthogonal to `isPending`, which tracks
+ * auth work in flight. A background refresh keeps `status === 'authenticated'`
+ * while `isPending === true`.
+ */
+export type ConvexAuthStatus = 'loading' | 'anonymous' | 'authenticated' | 'error';
+/** Internal query gate state for a build that intentionally has no auth graph. */
+export type ConvexQueryAuthStatus = ConvexAuthStatus | 'disabled';
+/**
+ * The two-dimensional inputs to status derivation. `settled` is the initial
+ * auth-settlement signal; `error` is non-null only when initial resolution
+ * failed without a usable identity (see {@link ConvexCallError} placeholder).
+ */
+export interface ConvexAuthStatusInput {
+    authEnabled: boolean;
+    settled: boolean;
+    identityKey: ConvexIdentityKey | null;
+    error: ConvexCallError | null;
+}
+/**
+ * Derive the canonical status in the exact precedence locked by public and
+ * architecture invariant: `disabled` → `loading` → `authenticated` → `error` → `anonymous`.
+ *
+ * `authenticated` outranks `error` so a failed background refresh over a still
+ * usable identity keeps `authenticated`. `error` outranks `anonymous` so a
+ * failed initial resolution surfaces the error instead of silently downgrading
+ * to anonymous execution.
+ */
+export declare function deriveConvexAuthStatus(input: ConvexAuthStatusInput & {
+    authEnabled: true;
+}): ConvexAuthStatus;
+export declare function deriveConvexAuthStatus(input: ConvexAuthStatusInput): ConvexQueryAuthStatus;

package/dist/runtime/utils/auth-status.js

@@ -0,0 +1,8 @@
+import { isAuthenticatedIdentityKey } from "./identity-key.js";
+export function deriveConvexAuthStatus(input) {
+  if (!input.authEnabled) return "disabled";
+  if (!input.settled) return "loading";
+  if (isAuthenticatedIdentityKey(input.identityKey)) return "authenticated";
+  if (input.error) return "error";
+  return "anonymous";
+}

package/dist/runtime/utils/bounded-convex-fetch.d.ts

@@ -0,0 +1,18 @@
+export declare const CONVEX_HTTP_QUERY_TIMEOUT_MS = 8000;
+export declare const CONVEX_HTTP_MUTATION_TIMEOUT_MS = 15000;
+export declare const CONVEX_HTTP_ACTION_TIMEOUT_MS = 60000;
+export declare const CONVEX_HTTP_MAX_RESPONSE_BYTES: number;
+interface BoundedConvexFetchOptions {
+    fetchImpl?: typeof fetch;
+    maxResponseBytes?: number;
+    signal?: AbortSignal;
+    /** Test-only fixed deadline override; production derives it from the endpoint. */
+    timeoutMs?: number;
+}
+/**
+ * One bounded Convex HTTP transport for SSR queries and request-scoped public
+ * server calls. Convex owns value/protocol encoding; this boundary owns abort,
+ * operation deadlines, opaque non-UDF failures, and response bytes.
+ */
+export declare function createBoundedConvexFetch(options?: BoundedConvexFetchOptions): typeof fetch;
+export {};

package/dist/runtime/utils/bounded-convex-fetch.js

@@ -0,0 +1,152 @@
+import { ConvexCallError } from "../errors/index.js";
+export const CONVEX_HTTP_QUERY_TIMEOUT_MS = 8e3;
+export const CONVEX_HTTP_MUTATION_TIMEOUT_MS = 15e3;
+export const CONVEX_HTTP_ACTION_TIMEOUT_MS = 6e4;
+export const CONVEX_HTTP_MAX_RESPONSE_BYTES = 1024 * 1024;
+const CONVEX_UDF_FAILED_STATUS = 560;
+const CONVEX_HTTP_UPSTREAM_FAILURE_MESSAGE = "The request to Convex failed before a usable response was received.";
+function operationTimeoutMs(input) {
+  let pathname;
+  try {
+    pathname = new URL(input instanceof Request ? input.url : String(input)).pathname;
+  } catch {
+    return CONVEX_HTTP_QUERY_TIMEOUT_MS;
+  }
+  if (pathname.endsWith("/api/action")) return CONVEX_HTTP_ACTION_TIMEOUT_MS;
+  if (pathname.endsWith("/api/mutation")) return CONVEX_HTTP_MUTATION_TIMEOUT_MS;
+  return CONVEX_HTTP_QUERY_TIMEOUT_MS;
+}
+function transportError(message, status) {
+  return new ConvexCallError({ kind: "transport", message, status });
+}
+function boundedResponse(response, maximum, signal, cleanup) {
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    const length = Number(declared);
+    if (!Number.isSafeInteger(length) || length < 0 || length > maximum) {
+      cleanup();
+      void response.body?.cancel().catch(() => {
+      });
+      throw transportError("Convex HTTP response exceeded the size limit", response.status);
+    }
+  }
+  if (!response.body) {
+    cleanup();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let total = 0;
+  let finished = false;
+  let bodyController;
+  const abortBody = () => {
+    if (finished) return;
+    const reason = signal.reason instanceof ConvexCallError ? signal.reason : transportError("Convex HTTP request was aborted");
+    void reader.cancel(reason).catch(() => {
+    });
+    finish();
+    bodyController?.error(reason);
+  };
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    signal.removeEventListener("abort", abortBody);
+    cleanup();
+    reader.releaseLock();
+  };
+  const body = new ReadableStream({
+    start(controller) {
+      bodyController = controller;
+      signal.addEventListener("abort", abortBody, { once: true });
+      if (signal.aborted) abortBody();
+    },
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          finish();
+          controller.close();
+          return;
+        }
+        total += next.value.byteLength;
+        if (total > maximum) {
+          const error = transportError(
+            "Convex HTTP response exceeded the size limit",
+            response.status
+          );
+          await reader.cancel(error);
+          finish();
+          controller.error(error);
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        finish();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try {
+        await reader.cancel(reason);
+      } finally {
+        finish();
+      }
+    }
+  });
+  return new Response(body, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText
+  });
+}
+export function createBoundedConvexFetch(options = {}) {
+  const {
+    fetchImpl = fetch,
+    maxResponseBytes = CONVEX_HTTP_MAX_RESPONSE_BYTES,
+    signal: parentSignal,
+    timeoutMs: fixedTimeoutMs
+  } = options;
+  if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes <= 0) {
+    throw new TypeError("CONVEX_HTTP_RESPONSE_LIMIT_INVALID");
+  }
+  if (fixedTimeoutMs !== void 0 && (!Number.isFinite(fixedTimeoutMs) || fixedTimeoutMs <= 0)) {
+    throw new TypeError("CONVEX_HTTP_TIMEOUT_INVALID");
+  }
+  return async (input, init) => {
+    const timeoutMs = fixedTimeoutMs ?? operationTimeoutMs(input);
+    const controller = new AbortController();
+    const abortFromParent = () => controller.abort(parentSignal?.reason);
+    if (parentSignal?.aborted) abortFromParent();
+    else parentSignal?.addEventListener("abort", abortFromParent, { once: true });
+    const timeout = setTimeout(
+      () => controller.abort(transportError("Convex HTTP request timed out")),
+      timeoutMs
+    );
+    const cleanup = () => {
+      clearTimeout(timeout);
+      parentSignal?.removeEventListener("abort", abortFromParent);
+    };
+    try {
+      const response = await fetchImpl(input, {
+        ...init,
+        cache: "no-store",
+        signal: controller.signal
+      });
+      if (!response.ok && response.status !== CONVEX_UDF_FAILED_STATUS) {
+        cleanup();
+        void response.body?.cancel().catch(() => {
+        });
+        throw transportError(CONVEX_HTTP_UPSTREAM_FAILURE_MESSAGE, response.status);
+      }
+      return boundedResponse(response, maxResponseBytes, controller.signal, cleanup);
+    } catch (error) {
+      cleanup();
+      if (error instanceof ConvexCallError) throw error;
+      if (controller.signal.aborted) {
+        throw transportError(
+          parentSignal?.aborted ? "Convex HTTP request was aborted" : "Convex HTTP request timed out"
+        );
+      }
+      throw transportError("Convex HTTP request could not complete");
+    }
+  };
+}

package/dist/runtime/utils/callable-devtools.d.ts

@@ -0,0 +1,17 @@
+import type { DevtoolsSink } from '../devtools/sink.js';
+import type { ConvexCallError } from '../errors/index.js';
+interface CallableDevtoolsEvent {
+    sink: DevtoolsSink;
+    id: string;
+}
+export declare function createCallableDevtoolsEvents<Args, Result>(input: {
+    operation: 'mutation' | 'action';
+    fnName: string;
+    hasOptimisticUpdate: boolean;
+    getSink: () => DevtoolsSink | null;
+}): {
+    startEvent(args: Args, startedAt: number): CallableDevtoolsEvent | undefined;
+    finishEvent(event: unknown, result: Result, startedAt: number): void;
+    failEvent(event: unknown, error: ConvexCallError, startedAt: number): void;
+};
+export {};

package/dist/runtime/utils/callable-devtools.js

@@ -0,0 +1,49 @@
+export function createCallableDevtoolsEvents(input) {
+  return {
+    startEvent(args, startedAt) {
+      try {
+        const sink = input.getSink();
+        if (!sink) return void 0;
+        const id = sink.registerMutation({
+          name: input.fnName,
+          type: input.operation,
+          args,
+          state: input.operation === "mutation" && input.hasOptimisticUpdate ? "optimistic" : "pending",
+          hasOptimisticUpdate: input.hasOptimisticUpdate,
+          startedAt
+        });
+        return id ? { sink, id } : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    finishEvent(rawEvent, result, startedAt) {
+      const event = rawEvent;
+      if (!event) return;
+      try {
+        const settledAt = Date.now();
+        event.sink.updateMutation(event.id, {
+          state: "success",
+          result,
+          settledAt,
+          duration: settledAt - startedAt
+        });
+      } catch {
+      }
+    },
+    failEvent(rawEvent, error, startedAt) {
+      const event = rawEvent;
+      if (!event) return;
+      try {
+        const settledAt = Date.now();
+        event.sink.updateMutation(event.id, {
+          state: "error",
+          error: error.message,
+          settledAt,
+          duration: settledAt - startedAt
+        });
+      } catch {
+      }
+    }
+  };
+}

package/dist/runtime/utils/callable-observer.d.ts

@@ -0,0 +1,2 @@
+/** Private cross-package key shared by the exact-version Nuxt and Vue runtimes. */
+export declare const CALLABLE_OBSERVER_KEY: unique symbol;

package/dist/runtime/utils/callable-observer.js

@@ -0,0 +1 @@
+export const CALLABLE_OBSERVER_KEY = Symbol.for("better-convex.callable-observer");

package/dist/runtime/utils/composable-scope.d.ts

@@ -0,0 +1,2 @@
+export type ConvexScopeComposableName = 'useConvexQuery' | 'useConvexPaginatedQuery' | 'useConvexFileUpload';
+export declare function assertConvexComposableScope(composable: ConvexScopeComposableName, isClient: boolean, scope: unknown): void;

package/dist/runtime/utils/composable-scope.js

@@ -0,0 +1,8 @@
+export function assertConvexComposableScope(composable, isClient, scope) {
+  if (!isClient || scope) {
+    return;
+  }
+  throw new Error(
+    `[${composable}] Must be called within component setup/effect scope. For middleware/plugins use useConvex() (client) or serverConvex() (server).`
+  );
+}

package/dist/runtime/utils/config-defaults.d.ts

@@ -0,0 +1,8 @@
+import type { LogLevel } from './logger.js';
+export declare const CONVEX_MODULE_DEFAULTS: Readonly<{
+    logging: LogLevel | false;
+    authProxy: Readonly<{
+        maxRequestBodyBytes: 1048576;
+        maxResponseBodyBytes: 1048576;
+    }>;
+}>;

package/dist/runtime/utils/config-defaults.js

@@ -0,0 +1,8 @@
+const DEFAULT_AUTH_PROXY_BODY_LIMIT_BYTES = 1048576;
+export const CONVEX_MODULE_DEFAULTS = Object.freeze({
+  logging: false,
+  authProxy: Object.freeze({
+    maxRequestBodyBytes: DEFAULT_AUTH_PROXY_BODY_LIMIT_BYTES,
+    maxResponseBodyBytes: DEFAULT_AUTH_PROXY_BODY_LIMIT_BYTES
+  })
+});

package/dist/runtime/utils/convex-cache.d.ts

@@ -0,0 +1,68 @@
+import type { ConvexAuthMode } from './auth-status.js';
+import type { ConvexIdentityKey } from './identity-key.js';
+/**
+ * Append the auth/identity dimension to an identity-blind base key produced by
+ * `createConvexQueryKey`. `none` is a static, identity-independent suffix so a
+ * public query is shared across sign-in/out; every other mode is partitioned by
+ * the concrete `ConvexIdentityKey`.
+ */
+export declare function withAuthDimension(baseKey: string, authMode: ConvexAuthMode, identityKey: ConvexIdentityKey): string;
+/**
+ * A protected SSR payload may seed a browser controller only when the canonical
+ * browser identity already names the same principal. The auth adapter seeds an
+ * unsettled first generation from SSR provenance, so an anonymous snapshot is a
+ * real mismatch here rather than a reason to expose protected data speculatively.
+ */
+export declare function matchesConvexHydrationIdentity(authMode: ConvexAuthMode, payloadIdentity: ConvexIdentityKey, browserIdentity: {
+    readonly identityKey: ConvexIdentityKey | null;
+} | undefined): boolean;
+/**
+ * Read the `:auth:<mode>` segment of a payload key, or `null` when the key is
+ * not a mode-tagged Convex payload key (e.g. an `idle` key or a non-Convex key).
+ */
+export declare function readAuthMode(key: string): ConvexAuthMode | null;
+/**
+ * Sign-out / identity-change purge (architecture invariant). Scans only the two Convex
+ * payload namespaces on the Nuxt payload/state and removes keys whose `:auth:`
+ * mode segment is `required` or `optional`; `none` keys are retained and keys
+ * outside these namespaces are never touched. No registry or count is consulted.
+ *
+ * This is the app-global hygiene complement to each composable clearing its own
+ * identity-owned state on an identity change; identity-partitioned keys already
+ * guarantee a new identity never reads the previous identity's payload.
+ */
+export declare function purgeConvexIdentityPayloadKeys(nuxtApp: {
+    payload?: {
+        data?: Record<string, unknown>;
+        state?: Record<string, unknown>;
+    };
+}): string[];
+/**
+ * Remove identity-bound query errors while retaining anonymous-query errors.
+ * Error state is stored under one Nuxt useState key rather than as individual
+ * payload keys, so it needs the same auth-mode filtering explicitly.
+ */
+export declare function retainAnonymousConvexQueryErrors<T>(errors: Readonly<Record<string, T>>): Record<string, T>;
+export interface FetchAuthTokenOptions {
+    /** Auth transport mode for this query. */
+    auth: ConvexAuthMode;
+    /** Cookie header from the request. */
+    cookieHeader: string;
+    /** Cached token state (must be obtained at setup time via useState). */
+    cachedToken: {
+        value: string | null;
+    };
+}
+/**
+ * Resolve the SSR auth token for a query.
+ *
+ * Performs NO cookie -> JWT exchange. `plugin.server.ts` runs before any route
+ * component's setup and already exchanged the session cookie once, writing the
+ * result into the canonical `useState('convex:identity')`. SSR queries reuse that single
+ * per-request exchange. `none` never attaches a token.
+ *
+ * The `cachedToken` must be obtained at component setup time via
+ * the canonical identity state; calling `useState` inside an async function loses
+ * Vue context.
+ */
+export declare function fetchAuthToken(options: FetchAuthTokenOptions): string | undefined;

package/dist/runtime/utils/convex-cache.js

@@ -0,0 +1,47 @@
+import { getBetterAuthSessionToken } from "./shared-helpers.js";
+const AUTH_SEGMENT = ":auth:";
+export function withAuthDimension(baseKey, authMode, identityKey) {
+  if (authMode === "none") return `${baseKey}${AUTH_SEGMENT}none`;
+  return `${baseKey}${AUTH_SEGMENT}${authMode}:${identityKey}`;
+}
+export function matchesConvexHydrationIdentity(authMode, payloadIdentity, browserIdentity) {
+  return authMode === "none" || browserIdentity?.identityKey === payloadIdentity;
+}
+function isConvexPayloadKey(key) {
+  return key.startsWith("convex:") || key.startsWith("convex-paginated:");
+}
+export function readAuthMode(key) {
+  const idx = key.indexOf(AUTH_SEGMENT);
+  if (idx < 0) return null;
+  const rest = key.slice(idx + AUTH_SEGMENT.length);
+  const mode = rest.split(":", 1)[0];
+  if (mode === "required" || mode === "optional" || mode === "none") return mode;
+  return null;
+}
+export function purgeConvexIdentityPayloadKeys(nuxtApp) {
+  const purged = [];
+  const scan = (bag) => {
+    if (!bag) return;
+    for (const key of Object.keys(bag)) {
+      const libKey = key.startsWith("$s") ? key.slice(2) : key;
+      if (!isConvexPayloadKey(libKey)) continue;
+      const mode = readAuthMode(libKey);
+      if (mode === "required" || mode === "optional") {
+        Reflect.deleteProperty(bag, key);
+        purged.push(key);
+      }
+    }
+  };
+  scan(nuxtApp.payload?.data);
+  scan(nuxtApp.payload?.state);
+  return purged;
+}
+export function retainAnonymousConvexQueryErrors(errors) {
+  return Object.fromEntries(Object.entries(errors).filter(([key]) => readAuthMode(key) === "none"));
+}
+export function fetchAuthToken(options) {
+  const { auth, cookieHeader, cachedToken } = options;
+  if (auth === "none") return void 0;
+  if (!getBetterAuthSessionToken(cookieHeader)) return void 0;
+  return cachedToken.value ?? void 0;
+}

package/dist/runtime/utils/convex-config.d.ts

@@ -0,0 +1,16 @@
+export type SiteUrlResolutionSource = 'explicit' | 'derived' | 'missing' | 'invalid-derived';
+export interface ResolveConvexSiteUrlInput {
+    url?: string | null;
+    siteUrl?: string | null;
+}
+export interface ResolveConvexSiteUrlResult {
+    siteUrl?: string;
+    source: SiteUrlResolutionSource;
+}
+/**
+ * Derive the Convex HTTP Actions host from the Convex deployment URL.
+ * Example: https://foo.convex.cloud -> https://foo.convex.site
+ */
+export declare function deriveConvexSiteUrl(url?: string | null): string | undefined;
+export declare function resolveConvexSiteUrl(input: ResolveConvexSiteUrlInput): ResolveConvexSiteUrlResult;
+export declare function getSiteUrlResolutionHint(url?: string | null): string;

package/dist/runtime/utils/convex-config.js

@@ -0,0 +1,50 @@
+export function deriveConvexSiteUrl(url) {
+  if (!url) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return void 0;
+  }
+  if (parsed.hostname.endsWith(".convex.cloud")) {
+    parsed.hostname = parsed.hostname.replace(/\.convex\.cloud$/, ".convex.site");
+    parsed.pathname = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, "");
+  }
+  const isLocalConvexDevHost = parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost";
+  if (isLocalConvexDevHost && parsed.port === "3210") {
+    parsed.port = "3211";
+    parsed.pathname = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, "");
+  }
+  return void 0;
+}
+export function resolveConvexSiteUrl(input) {
+  if (input.siteUrl) {
+    return { siteUrl: input.siteUrl, source: "explicit" };
+  }
+  if (!input.url) {
+    return { siteUrl: void 0, source: "missing" };
+  }
+  const derived = deriveConvexSiteUrl(input.url);
+  if (derived) {
+    return { siteUrl: derived, source: "derived" };
+  }
+  return { siteUrl: void 0, source: "invalid-derived" };
+}
+export function getSiteUrlResolutionHint(url) {
+  if (!url) {
+    return "Set `convex.url` (or `NUXT_PUBLIC_CONVEX_URL` / `CONVEX_URL`) first, or provide `convex.siteUrl` (or `NUXT_PUBLIC_CONVEX_SITE_URL` / `CONVEX_SITE_URL`) explicitly.";
+  }
+  if (url.includes("localhost") || url.includes("127.0.0.1")) {
+    return "For local Convex dev, use `convex.url` = `http://127.0.0.1:3210` (or `http://localhost:3210`), or set `convex.siteUrl` explicitly.";
+  }
+  if (!url.includes(".convex.cloud")) {
+    return "Could not derive `siteUrl` from `convex.url` because this is not a `.convex.cloud` URL. Set `convex.siteUrl` explicitly for your custom HTTP Actions domain.";
+  }
+  return "Set `convex.siteUrl` explicitly to your Convex HTTP Actions host (for example `https://your-app.convex.site`).";
+}

package/dist/runtime/utils/convex-shared.d.ts

@@ -0,0 +1,67 @@
+import type { FunctionArgs, FunctionReference } from 'convex/server';
+import type { ConvexCallStatus, ConvexUser } from './types.js';
+/** Milliseconds before `exp` at which a locally retained token is unusable. */
+export declare const TOKEN_EXPIRY_SAFETY_BUFFER_MS = 30000;
+/**
+ * Decode JWT payload without verification.
+ * Returns the parsed payload object or null if decoding fails.
+ *
+ * @param token - The JWT token string
+ * @returns The decoded payload object or null
+ */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+/**
+ * Returns milliseconds until JWT expiry, or null when `exp` is missing/invalid.
+ * Negative values mean the token is already expired.
+ */
+export declare function getJwtTimeUntilExpiryMs(token: string, nowMs?: number): number | null;
+/**
+ * A locally retained token must have a finite `exp` beyond the safety window.
+ * This is a lifecycle guard, not JWT verification: Convex still verifies the
+ * signature, algorithm, key, issuer, audience, subject, and temporal claims.
+ */
+export declare function isJwtUsable(token: string | null, nowMs?: number): token is string;
+/**
+ * Decode user info from JWT payload.
+ * Extracts standard user fields from the JWT claims.
+ *
+ * @param token - The JWT token string
+ * @returns The decoded user or null if decoding fails
+ */
+export declare function decodeUserFromJwt(token: string): ConvexUser | null;
+/**
+ * Status computation logic for queries.
+ *
+ * Priority order:
+ * 1. Skip -> idle (always)
+ * 2. Error -> error (takes precedence over pending)
+ * 3. Pending without data -> pending
+ * 4. Everything else -> success (including pending with data for background refresh)
+ */
+export declare function computeQueryStatus(isSkipped: boolean, hasError: boolean, isPending: boolean, hasData: boolean): ConvexCallStatus;
+/**
+ * Get the function name from a Convex function reference.
+ * Works with queries, mutations, and actions.
+ */
+export declare function getFunctionName(fn: FunctionReference<'query'> | FunctionReference<'mutation'> | FunctionReference<'action'>): string;
+/**
+ * Generate a stable hash for any value using ohash.
+ * Used for cache key generation and argument comparison.
+ *
+ * Benefits over custom stableStringify:
+ * - Handles circular references gracefully
+ * - Faster execution (optimized C++ implementation)
+ * - Shorter, URL-safe output
+ * - Handles Symbols, Functions, and edge cases
+ */
+export declare function hashArgs(args: unknown): string;
+/**
+ * Build the identity-blind base key for a query and arguments. This is the
+ * `convex:<functionName>:<argsHash>` (or
+ * `convex-paginated:<functionName>:<argsHash>`) prefix; the auth/identity
+ * dimension is appended separately by {@link withAuthDimension} so the same base
+ * can be partitioned per identity.
+ *
+ * The base key is internal; public keys include the auth dimension.
+ */
+export declare function createConvexQueryKey<Query extends FunctionReference<'query'>>(query: Query, args?: FunctionArgs<Query>, namespace?: 'convex' | 'convex-paginated'): string;