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

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

@@ -0,0 +1,134 @@
+import { hash } from "ohash";
+const functionNameSymbol = Symbol.for("functionName");
+const MAX_LOCAL_JWT_LENGTH = 65536;
+const MAX_DISPLAY_STRING_LENGTH = 4096;
+export const TOKEN_EXPIRY_SAFETY_BUFFER_MS = 3e4;
+function isPlainRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function defineSafeProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+}
+function readDisplayString(value) {
+  if (value === null) return null;
+  return typeof value === "string" && value.length <= MAX_DISPLAY_STRING_LENGTH ? value : void 0;
+}
+function copyNormalizedDisplayFields(target, input) {
+  for (const key of ["name", "email", "image", "createdAt", "updatedAt"]) {
+    const value = readDisplayString(input[key]);
+    if (value !== void 0) defineSafeProperty(target, key, value);
+  }
+  if (typeof input.emailVerified === "boolean") {
+    defineSafeProperty(target, "emailVerified", input.emailVerified);
+  }
+}
+function base64UrlDecode(str) {
+  if (str.length % 4 === 1) throw new Error("Invalid base64url length");
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = base64.length % 4;
+  if (padding > 0) {
+    base64 += "=".repeat(4 - padding);
+  }
+  let bytes;
+  if (typeof Buffer !== "undefined") {
+    bytes = Buffer.from(base64, "base64");
+  } else {
+    const binaryString = atob(base64);
+    bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+  }
+  let canonical;
+  if (typeof Buffer !== "undefined") {
+    canonical = Buffer.from(bytes).toString("base64url");
+  } else {
+    let binaryString = "";
+    for (const byte of bytes) binaryString += String.fromCharCode(byte);
+    canonical = btoa(binaryString).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
+  if (canonical !== str) throw new Error("Non-canonical base64url encoding");
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function isBase64UrlSegment(value) {
+  return value.length > 0 && /^[\w-]+$/.test(value);
+}
+export function decodeJwtPayload(token) {
+  try {
+    if (token.length === 0 || token.length > MAX_LOCAL_JWT_LENGTH) return null;
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const [header, payload, signature] = parts;
+    if (!header || !payload || !signature || !isBase64UrlSegment(header) || !isBase64UrlSegment(payload) || !isBase64UrlSegment(signature)) {
+      return null;
+    }
+    const decoded = base64UrlDecode(payload);
+    const parsed = JSON.parse(decoded);
+    return isPlainRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+export function getJwtTimeUntilExpiryMs(token, nowMs = Date.now()) {
+  const payload = decodeJwtPayload(token);
+  if (!payload) return null;
+  const exp = payload.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+  const expiryMs = exp * 1e3;
+  if (!Number.isFinite(expiryMs)) return null;
+  return expiryMs - nowMs;
+}
+export function isJwtUsable(token, nowMs = Date.now()) {
+  if (!token) return false;
+  const timeUntilExpiry = getJwtTimeUntilExpiryMs(token, nowMs);
+  return timeUntilExpiry !== null && timeUntilExpiry > TOKEN_EXPIRY_SAFETY_BUFFER_MS;
+}
+export function decodeUserFromJwt(token) {
+  const payload = decodeJwtPayload(token);
+  if (!payload) return null;
+  const subject = payload.sub;
+  if (typeof subject !== "string" || subject.length === 0 || subject.length > MAX_DISPLAY_STRING_LENGTH) {
+    return null;
+  }
+  const user = { id: subject };
+  copyNormalizedDisplayFields(user, payload);
+  return user;
+}
+export function computeQueryStatus(isSkipped, hasError, isPending, hasData) {
+  if (isSkipped) return "idle";
+  if (hasError) return "error";
+  if (isPending && !hasData) return "pending";
+  return "success";
+}
+export function getFunctionName(fn) {
+  if (!fn) return "unknown";
+  try {
+    const value = fn;
+    if (typeof value === "string") return value;
+    if (typeof value !== "object" && typeof value !== "function" || value === null) {
+      return "unknown";
+    }
+    const functionRef = value;
+    const symbolName = functionRef[functionNameSymbol];
+    if (typeof symbolName === "string") return symbolName;
+    if (typeof functionRef._path === "string") return functionRef._path;
+    if (typeof functionRef.functionPath === "string") return functionRef.functionPath;
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+export function hashArgs(args) {
+  return hash(args ?? {});
+}
+export function createConvexQueryKey(query, args, namespace = "convex") {
+  const fnName = getFunctionName(query);
+  return `${namespace}:${fnName}:${hashArgs(args)}`;
+}

package/dist/runtime/utils/identity-changed-error.d.ts

@@ -0,0 +1,4 @@
+import { ConvexCallError } from '../errors/index.js';
+export declare const IDENTITY_CHANGED: "IDENTITY_CHANGED";
+export declare function createIdentityChangedError(operation?: string): ConvexCallError;
+export declare function isIdentityChangedError(error: unknown): boolean;

package/dist/runtime/utils/identity-changed-error.js

@@ -0,0 +1,12 @@
+import { ConvexCallError } from "../errors/index.js";
+export const IDENTITY_CHANGED = "IDENTITY_CHANGED";
+export function createIdentityChangedError(operation) {
+  return new ConvexCallError({
+    kind: "authentication",
+    code: IDENTITY_CHANGED,
+    message: operation ? `Convex ${operation} rejected: the auth identity changed before it settled (${IDENTITY_CHANGED}).` : `Convex operation rejected: the auth identity changed (${IDENTITY_CHANGED}).`
+  });
+}
+export function isIdentityChangedError(error) {
+  return typeof error === "object" && error !== null && error.code === IDENTITY_CHANGED;
+}

package/dist/runtime/utils/identity-key.d.ts

@@ -0,0 +1,19 @@
+import type { ConvexUser } from './types.js';
+export type ConvexIdentityKey = 'anonymous' | `user:${string}`;
+export declare function isAuthenticatedIdentityKey(key: ConvexIdentityKey | null): key is `user:${string}`;
+/**
+ * The single stable-user-ID extraction function.
+ *
+ * `'anonymous'` covers every unauthenticated identity; `user:${string}` uses the
+ * Better Auth `user.id` at this Nuxt adapter boundary. It is never a JWT, token
+ * hash, role, or permission.
+ *
+ * Use this everywhere an identity-varying holder is keyed: SSR snapshots, client
+ * auth, cache keys, payload keys, subscription keys, and identity generation.
+ * There is deliberately exactly one implementation .
+ *
+ * @throws TypeError when a user is present but has no non-empty string `id`.
+ *   A token without a resolved user id is not a settled identity and must keep
+ *   auth-gated queries waiting; it must never produce `user:undefined`.
+ */
+export declare function getConvexIdentityKey(user: ConvexUser | null): ConvexIdentityKey;

package/dist/runtime/utils/identity-key.js

@@ -0,0 +1,10 @@
+export function isAuthenticatedIdentityKey(key) {
+  return typeof key === "string" && key.startsWith("user:");
+}
+export function getConvexIdentityKey(user) {
+  if (!user) return "anonymous";
+  if (typeof user.id !== "string" || user.id.length === 0) {
+    throw new TypeError("Authenticated Convex user is missing a stable Better Auth user id");
+  }
+  return `user:${user.id}`;
+}

package/dist/runtime/utils/integrated-auth-client.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Keep provider methods while removing transport and token-authority escape
+ * hatches owned by the Nuxt runtime.
+ */
+export type IntegratedAuthClient<Client extends object> = Omit<Client, '$fetch' | '$store' | 'hydrateSession' | 'convex'>;

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

@@ -0,0 +1,42 @@
+/**
+ * Semantic logger for better-convex-nuxt
+ *
+ * Levels:
+ * - false: No logs (production default)
+ * - 'info': Auth and upload events
+ * - 'debug': Auth/uploads plus timing and debug messages
+ *
+ * Output:
+ * - Server: ANSI-styled single-line logs for easy grep/scanning
+ * - Browser: CSS badges + collapsed groups for clean dev tools
+ */
+export type LogLevel = false | 'info' | 'debug';
+export interface AuthEvent {
+    phase: string;
+    outcome: 'success' | 'error' | 'skip' | 'miss';
+    details?: Record<string, unknown>;
+    error?: unknown;
+}
+export interface UploadEvent {
+    name: string;
+    event: 'success' | 'error';
+    filename?: string;
+    size?: number;
+    duration?: number;
+    error?: unknown;
+}
+export interface Logger {
+    auth(event: AuthEvent): void;
+    upload(event: UploadEvent): void;
+    debug(message: string, data?: unknown): void;
+    time(label: string): () => void;
+}
+/**
+ * Create a logger with the specified level.
+ * Automatically selects ANSI (server) or CSS (browser) styling.
+ */
+export declare function createLogger(level: LogLevel): Logger;
+/**
+ * Get log level from runtime config.
+ */
+export declare function getLogLevel(config: unknown): LogLevel;

package/dist/runtime/utils/logger.js

@@ -0,0 +1,190 @@
+import { sanitizeDiagnosticValue } from "./sanitize-diagnostic.js";
+const noopLogger = Object.freeze({
+  auth: () => {
+  },
+  upload: () => {
+  },
+  debug: () => {
+  },
+  time: () => () => {
+  }
+});
+const ANSI = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m"
+};
+const ICONS = {
+  success: "\u2714",
+  error: "\u2716",
+  warning: "\u26A0",
+  upload: "\u{1F4E4}"
+};
+const CSS = {
+  badge: "background: #6366f1; color: white; padding: 2px 6px; border-radius: 3px; font-weight: bold;",
+  success: "color: #22c55e; font-weight: bold;",
+  error: "color: #ef4444; font-weight: bold;",
+  warning: "color: #f59e0b; font-weight: bold;",
+  dim: "color: #9ca3af;",
+  name: "color: #3b82f6; font-weight: bold;"
+};
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function formatDuration(ms) {
+  return `${ms}ms`;
+}
+function formatDetails(details) {
+  return Object.entries(details).map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+}
+function createServerLogger(level) {
+  const isDebug = level === "debug";
+  const PREFIX = `${ANSI.cyan}[convex]${ANSI.reset}`;
+  return {
+    auth(event) {
+      const icon = event.outcome === "success" ? `${ANSI.green}${ICONS.success}${ANSI.reset}` : event.outcome === "error" ? `${ANSI.red}${ICONS.error}${ANSI.reset}` : `${ANSI.yellow}${ICONS.warning}${ANSI.reset}`;
+      let msg = `${PREFIX} ${icon} Auth:${event.phase}`;
+      if (event.details) {
+        msg += `  ${ANSI.dim}${formatDetails(event.details)}${ANSI.reset}`;
+      }
+      if (event.error) {
+        console.error(msg, "[Omitted]");
+      } else {
+        console.log(msg);
+      }
+    },
+    upload(event) {
+      const icon = event.event === "error" ? `${ANSI.red}${ICONS.error}${ANSI.reset}` : `${ANSI.green}${ICONS.upload}${ANSI.reset}`;
+      let msg = `${PREFIX} ${icon} ${event.name}`;
+      if (event.event === "success") {
+        msg += `  ${ANSI.green}success${ANSI.reset}`;
+        if (event.filename) {
+          msg += ` ${ANSI.dim}${event.filename}${ANSI.reset}`;
+        }
+        if (event.size !== void 0) {
+          msg += ` ${ANSI.dim}(${formatBytes(event.size)})${ANSI.reset}`;
+        }
+        if (event.duration !== void 0) {
+          msg += ` ${ANSI.dim}${formatDuration(event.duration)}${ANSI.reset}`;
+        }
+      } else {
+        msg += `  ${ANSI.red}error${ANSI.reset}`;
+        if (event.error) msg += ` ${ANSI.red}[Omitted]${ANSI.reset}`;
+      }
+      console.log(msg);
+    },
+    debug(message, data) {
+      if (!isDebug) return;
+      void data;
+      console.log(`${PREFIX} ${ANSI.dim}[debug]${ANSI.reset} ${message}`);
+    },
+    time(label) {
+      if (!isDebug) return () => {
+      };
+      const start = performance.now();
+      return () => {
+        const elapsed = Math.round(performance.now() - start);
+        console.log(`${PREFIX} ${ANSI.dim}[time]${ANSI.reset} ${label}: ${elapsed}ms`);
+      };
+    }
+  };
+}
+function createBrowserLogger(level) {
+  const isDebug = level === "debug";
+  return {
+    auth(event) {
+      const icon = event.outcome === "success" ? ICONS.success : event.outcome === "error" ? ICONS.error : ICONS.warning;
+      const iconStyle = event.outcome === "success" ? CSS.success : event.outcome === "error" ? CSS.error : CSS.warning;
+      const hasDetails = event.details && Object.keys(event.details).length > 0;
+      if (hasDetails || event.error) {
+        console.groupCollapsed(
+          `%cConvex%c Auth | %c${icon} ${event.phase}`,
+          CSS.badge,
+          "",
+          iconStyle
+        );
+        if (event.details) console.log(event.details);
+        if (event.error) console.error("[Omitted]");
+        console.groupEnd();
+      } else {
+        console.log(`%cConvex%c Auth | %c${icon} ${event.phase}`, CSS.badge, "", iconStyle);
+      }
+    },
+    upload(event) {
+      const icon = event.event === "error" ? ICONS.error : ICONS.upload;
+      let label = `%cConvex%c ${icon} %c${event.name}`;
+      const styles = [CSS.badge, "", CSS.name];
+      if (event.event === "success") {
+        if (event.filename) {
+          label += `%c ${event.filename}`;
+          styles.push(CSS.dim);
+        }
+        if (event.size !== void 0) {
+          label += `%c (${formatBytes(event.size)})`;
+          styles.push(CSS.dim);
+        }
+        if (event.duration !== void 0) {
+          label += `%c ${formatDuration(event.duration)}`;
+          styles.push(CSS.dim);
+        }
+      } else {
+        label += `%c Failed`;
+        styles.push(CSS.error);
+      }
+      if (event.error) {
+        console.groupCollapsed(label, ...styles);
+        console.error("Error:", "[Omitted]");
+        console.groupEnd();
+      } else {
+        console.log(label, ...styles);
+      }
+    },
+    debug(message, data) {
+      if (!isDebug) return;
+      void data;
+      console.log(`%cConvex%c [debug] ${message}`, CSS.badge, CSS.dim);
+    },
+    time(label) {
+      if (!isDebug) return () => {
+      };
+      const start = performance.now();
+      return () => {
+        const elapsed = Math.round(performance.now() - start);
+        console.log(`%cConvex%c [time] ${label}: ${elapsed}ms`, CSS.badge, CSS.dim);
+      };
+    }
+  };
+}
+export function createLogger(level) {
+  if (!level) return noopLogger;
+  const sink = !isBrowserRuntime() ? createServerLogger(level) : createBrowserLogger(level);
+  const sanitizeEvent = (event) => ({
+    ...event,
+    ...event.phase === void 0 ? {} : { phase: String(sanitizeDiagnosticValue(event.phase)) },
+    ...event.name === void 0 ? {} : { name: String(sanitizeDiagnosticValue(event.name)) },
+    ...event.filename === void 0 ? {} : { filename: String(sanitizeDiagnosticValue(event.filename)) },
+    ...event.details === void 0 ? {} : { details: sanitizeDiagnosticValue(event.details) },
+    // Error objects/messages often contain transport data and credentials.
+    // Callers must put a stable, reviewed code in `details` instead.
+    ...event.error === void 0 ? {} : { error: "[Omitted]" }
+  });
+  const safeLogger = {
+    auth: (event) => sink.auth(sanitizeEvent(event)),
+    upload: (event) => sink.upload(sanitizeEvent(event)),
+    debug: (message, data) => sink.debug(String(sanitizeDiagnosticValue(message)), data),
+    time: (label) => sink.time(String(sanitizeDiagnosticValue(label)))
+  };
+  return Object.freeze(safeLogger);
+}
+function isBrowserRuntime() {
+  return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+}
+export function getLogLevel(config) {
+  const logging = config && typeof config === "object" && "logging" in config ? config.logging : void 0;
+  return logging ?? false;
+}

package/dist/runtime/utils/mime-type.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MIME type matching utilities for file validation.
+ * Used by useConvexFileUpload for client-side file type validation.
+ */
+/**
+ * Check if a file type matches an allowed type pattern.
+ * Supports exact matches and wildcards (e.g., 'image/*').
+ *
+ * @param fileType - The MIME type of the file (e.g., 'image/jpeg')
+ * @param pattern - The pattern to match against (e.g., 'image/*' or 'image/jpeg')
+ * @returns true if the file type matches the pattern
+ *
+ * @example
+ * matchesMimeType('image/jpeg', 'image/jpeg')  // true (exact match)
+ * matchesMimeType('image/jpeg', 'image/*')     // true (wildcard)
+ * matchesMimeType('image/jpeg', 'video/*')     // false
+ * matchesMimeType('video/mp4', 'video/*')      // true
+ */
+export declare function matchesMimeType(fileType: string, pattern: string): boolean;
+/**
+ * Check if a file type is allowed by any of the allowed type patterns.
+ *
+ * @param fileType - The MIME type of the file (e.g., 'image/jpeg')
+ * @param allowedTypes - Array of allowed patterns (supports wildcards)
+ * @returns true if the file type matches any of the allowed patterns
+ *
+ * @example
+ * isFileTypeAllowed('image/jpeg', ['image/jpeg', 'image/png'])  // true
+ * isFileTypeAllowed('image/gif', ['image/*'])                   // true
+ * isFileTypeAllowed('video/mp4', ['image/*'])                   // false
+ * isFileTypeAllowed('application/pdf', ['image/*', 'application/pdf'])  // true
+ */
+export declare function isFileTypeAllowed(fileType: string, allowedTypes: readonly string[]): boolean;

package/dist/runtime/utils/mime-type.js

@@ -0,0 +1,10 @@
+export function matchesMimeType(fileType, pattern) {
+  if (pattern.endsWith("/*")) {
+    const category = pattern.slice(0, -2);
+    return fileType.startsWith(`${category}/`);
+  }
+  return fileType === pattern;
+}
+export function isFileTypeAllowed(fileType, allowedTypes) {
+  return allowedTypes.some((pattern) => matchesMimeType(fileType, pattern));
+}

package/dist/runtime/utils/query-execution-gate.d.ts

@@ -0,0 +1,47 @@
+import type { ConvexAuthMode, ConvexQueryAuthStatus } from './auth-status.js';
+import { type ConvexIdentityKey } from './identity-key.js';
+/**
+ * Canonical query execution gate ("Required execution-gate behavior").
+ *
+ * The gate is driven by the canonical auth status and the stable identity key
+ * published by the frozen {@link ClientIdentityPort} adapter — never by raw engine
+ * state and never by `isPending`. Background auth work must not idle an already
+ * usable identity, so `isPending` is deliberately absent from the input.
+ *
+ * Decision order (each step returns immediately):
+ *   1. Explicit `'skip'` resolves idle.
+ *   2. `none` executes without waiting and uses the `anonymous` cache dimension.
+ *   3. `disabled`: `required` resolves idle; `optional` executes anonymously
+ *      without waiting.
+ *   4. `loading`: `required` and `optional` wait for initial auth settlement.
+ *   5. `error`: `required` and `optional` surface the auth error without a
+ *      network request. They do not silently downgrade to anonymous.
+ *   6. `anonymous`: `required` resolves idle; `optional` executes anonymously.
+ *   7. `authenticated`: `required` and `optional` require a non-null matching
+ *      `user:<id>` key and execute with that identity.
+ */
+export interface QueryExecutionGateInput {
+    authStatus: ConvexQueryAuthStatus;
+    authMode: ConvexAuthMode;
+    identityKey: ConvexIdentityKey | null;
+    skipped: boolean;
+}
+/**
+ * The terminal query execution decision:
+ * - `execute` — the caller may issue its configured network request;
+ * - `idle`    — resolve idle with no request and no error;
+ * - `wait`    — wait for initial auth settlement, then re-evaluate;
+ * - `error`   — surface the settled auth error with no request.
+ */
+export type QueryExecutionOutcome = 'execute' | 'idle' | 'wait' | 'error';
+export interface QueryExecutionGate {
+    outcome: QueryExecutionOutcome;
+    /** The identity dimension for the cache / payload / subscription key. */
+    cacheIdentity: ConvexIdentityKey;
+}
+/**
+ * Pure gate. No side effects, no reactivity, no client access — it maps the
+ * canonical status + mode + identity key to a terminal decision so the same
+ * matrix is trivially unit-testable across all status/mode combinations.
+ */
+export declare function createQueryExecutionGate(input: QueryExecutionGateInput): QueryExecutionGate;

package/dist/runtime/utils/query-execution-gate.js

@@ -0,0 +1,63 @@
+import { isAuthenticatedIdentityKey } from "./identity-key.js";
+const IDLE = {
+  outcome: "idle"
+};
+export function createQueryExecutionGate(input) {
+  const { authStatus, authMode, identityKey, skipped } = input;
+  if (skipped) {
+    return {
+      ...IDLE,
+      cacheIdentity: identityDimension(authMode, identityKey)
+    };
+  }
+  if (authMode === "none") {
+    return {
+      outcome: "execute",
+      cacheIdentity: "anonymous"
+    };
+  }
+  if (authStatus === "disabled") {
+    if (authMode === "required") {
+      return { ...IDLE, cacheIdentity: "anonymous" };
+    }
+    return executeAnonymously();
+  }
+  if (authStatus === "loading") {
+    return {
+      outcome: "wait",
+      cacheIdentity: identityDimension(authMode, identityKey)
+    };
+  }
+  if (authStatus === "error") {
+    return {
+      outcome: "error",
+      cacheIdentity: identityDimension(authMode, identityKey)
+    };
+  }
+  if (authStatus === "anonymous") {
+    if (authMode === "required") {
+      return { ...IDLE, cacheIdentity: "anonymous" };
+    }
+    return executeAnonymously();
+  }
+  if (!isAuthenticatedIdentityKey(identityKey)) {
+    return {
+      outcome: "wait",
+      cacheIdentity: "anonymous"
+    };
+  }
+  return {
+    outcome: "execute",
+    cacheIdentity: identityKey
+  };
+}
+function executeAnonymously() {
+  return {
+    outcome: "execute",
+    cacheIdentity: "anonymous"
+  };
+}
+function identityDimension(authMode, identityKey) {
+  if (authMode === "none") return "anonymous";
+  return isAuthenticatedIdentityKey(identityKey) ? identityKey : "anonymous";
+}

package/dist/runtime/utils/query-execution.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Execute one request-scoped SSR query through Convex's official HTTP client.
+ * The client owns Convex value encoding, response decoding, and structured
+ * application-error reconstruction. The custom fetch owns only request bounds.
+ *
+ * @internal
+ */
+export declare function executeQueryHttp<T>(convexUrl: string, functionPath: string, args: Record<string, unknown>, authToken?: string, signal?: AbortSignal): Promise<T>;

package/dist/runtime/utils/query-execution.js

@@ -0,0 +1,19 @@
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { normalizeConvexError } from "../errors/index.js";
+import { createBoundedConvexFetch } from "./bounded-convex-fetch.js";
+export async function executeQueryHttp(convexUrl, functionPath, args, authToken, signal) {
+  const client = new ConvexHttpClient(convexUrl, {
+    fetch: createBoundedConvexFetch({ signal }),
+    logger: false
+  });
+  if (authToken) client.setAuth(authToken);
+  try {
+    return await client.query(
+      makeFunctionReference(functionPath),
+      args
+    );
+  } catch (error) {
+    throw normalizeConvexError(error);
+  }
+}

package/dist/runtime/utils/query-foundation.d.ts

@@ -0,0 +1,20 @@
+import type { ComputedRef } from 'vue';
+import { ConvexCallError } from '../errors/index.js';
+import { type ConvexQueryAuthStatus } from './auth-status.js';
+import type { ConvexIdentityKey } from './identity-key.js';
+/**
+ * Reactive canonical auth-identity inputs for query gating and isolation
+ * tagging (architecture invariant). This is the single place query composables read auth
+ * state; they never touch the auth engine directly.
+ *
+ * Derived from the SSR-seeded reactive state (`convex:pending` / `convex:identity` /
+ * `convex:authError`) so it is correct on both server and client, plus the
+ * Query isolation generations are owned by the attached Vue runtime; this Nuxt
+ * context only derives the server/client execution gate.
+ */
+export interface ConvexQueryAuthContext {
+    readonly status: ComputedRef<ConvexQueryAuthStatus>;
+    readonly identityKey: ComputedRef<ConvexIdentityKey | null>;
+    readonly error: ComputedRef<ConvexCallError | null>;
+}
+export declare function createConvexQueryAuthContext(): ConvexQueryAuthContext;

package/dist/runtime/utils/query-foundation.js

@@ -0,0 +1,39 @@
+import { computed } from "vue";
+import { useState } from "#imports";
+import { identityKeyOf } from "../auth/auth-identity.js";
+import { ConvexCallError } from "../errors/index.js";
+import { useConvexIdentityState } from "./auth-identity-state.js";
+import { useConvexAuthPendingState } from "./auth-pending-state.js";
+import { deriveConvexAuthStatus } from "./auth-status.js";
+import { getConvexRuntimeConfig } from "./runtime-config.js";
+export function createConvexQueryAuthContext() {
+  const authEnabled = getConvexRuntimeConfig().auth !== false;
+  const identity = useConvexIdentityState();
+  const pending = useConvexAuthPendingState();
+  const authError = useState("convex:authError", () => null);
+  const identityKey = computed(
+    () => authEnabled ? identityKeyOf(identity.value) : null
+  );
+  const error = computed(() => {
+    if (!authEnabled) return null;
+    return authError.value ? new ConvexCallError({
+      kind: "authentication",
+      message: authError.value
+    }) : null;
+  });
+  const status = computed(() => {
+    if (!authEnabled) return "disabled";
+    if (pending.value) return "loading";
+    return deriveConvexAuthStatus({
+      authEnabled: true,
+      settled: true,
+      identityKey: identityKey.value,
+      error: error.value
+    });
+  });
+  return {
+    status,
+    identityKey,
+    error
+  };
+}