nuxt-convex-module 0.0.0

package/dist/runtime/better-auth/vue/use-auth.d.ts

@@ -0,0 +1,92 @@
+import type { AuthTokenFetcher } from 'convex/browser';
+import { type ComputedRef } from 'vue';
+import { type AuthClient } from '#convex/auth-client';
+declare const useClientSession: () => Readonly<import("vue").Ref<{
+    readonly data: {
+        readonly user: {
+            readonly id: string;
+            readonly createdAt: Date;
+            readonly updatedAt: Date;
+            readonly email: string;
+            readonly emailVerified: boolean;
+            readonly name: string;
+            readonly image?: string | null | undefined;
+            readonly userId?: string | null | undefined;
+        };
+        readonly session: {
+            readonly id: string;
+            readonly createdAt: Date;
+            readonly updatedAt: Date;
+            readonly userId: string;
+            readonly expiresAt: Date;
+            readonly token: string;
+            readonly ipAddress?: string | null | undefined;
+            readonly userAgent?: string | null | undefined;
+        };
+    } | null;
+    readonly isPending: boolean;
+    readonly isRefetching: boolean;
+    readonly error: import("better-auth/client").BetterFetchError | null;
+    readonly refetch: (queryParams?: {
+        query?: import("better-auth").SessionQueryParams;
+    } | undefined) => Promise<void>;
+}, {
+    readonly data: {
+        readonly user: {
+            readonly id: string;
+            readonly createdAt: Date;
+            readonly updatedAt: Date;
+            readonly email: string;
+            readonly emailVerified: boolean;
+            readonly name: string;
+            readonly image?: string | null | undefined;
+            readonly userId?: string | null | undefined;
+        };
+        readonly session: {
+            readonly id: string;
+            readonly createdAt: Date;
+            readonly updatedAt: Date;
+            readonly userId: string;
+            readonly expiresAt: Date;
+            readonly token: string;
+            readonly ipAddress?: string | null | undefined;
+            readonly userAgent?: string | null | undefined;
+        };
+    } | null;
+    readonly isPending: boolean;
+    readonly isRefetching: boolean;
+    readonly error: import("better-auth/client").BetterFetchError | null;
+    readonly refetch: (queryParams?: {
+        query?: import("better-auth").SessionQueryParams;
+    } | undefined) => Promise<void>;
+}>>;
+export type AuthSession = ReturnType<typeof useClientSession>;
+/** The signed-in user (loose — exact fields depend on your auth schema). */
+export type AuthUser = {
+    id: string;
+    email: string;
+    name: string;
+} & Record<string, unknown>;
+export interface UseAuthService {
+    isLoading: ComputedRef<boolean>;
+    isAuthenticated: ComputedRef<boolean>;
+    fetchAccessToken: AuthTokenFetcher;
+    client: AuthClient;
+    session: AuthSession;
+    /** The current user, or `null` when signed out / still loading. */
+    user: ComputedRef<AuthUser | null>;
+    authVersion: ComputedRef<string | null>;
+}
+/**
+ * Unified Better Auth service for the Vue/Nuxt runtime.
+ *
+ * Returns the full Better Auth client, the reactive session wrapper, and the
+ * Convex-compatible auth state used by the packaged auth plugin.
+ *
+ * @param initialToken - Optional preloaded token, used once per app lifetime
+ *   to avoid a round-trip on initial load (e.g. from SSR).
+ */
+export declare function useAuth(initialToken?: string | null): UseAuthService;
+/** Reset module-level token cache — intended for tests only. */
+export declare function __resetUseAuthForTests(): void;
+export {};

package/dist/runtime/better-auth/vue/use-auth.js

@@ -0,0 +1,82 @@
+import { computed, ref } from "vue";
+import { authClient } from "#convex/auth-client";
+const cachedToken = ref(null);
+let cachedTokenVersion = null;
+let pendingToken = null;
+let pendingTokenVersion = null;
+let initialTokenUsed = false;
+const PENDING_AUTH_VERSION = "__pending__";
+const useClientSession = () => authClient.useSession();
+export function useAuth(initialToken) {
+  if (!initialTokenUsed && initialToken) {
+    cachedToken.value = initialToken;
+    cachedTokenVersion = PENDING_AUTH_VERSION;
+    initialTokenUsed = true;
+  }
+  const session = useClientSession();
+  const client = authClient;
+  const authVersion = computed(() => {
+    const data = session.value.data;
+    return data?.session?.id ?? data?.user?.id ?? null;
+  });
+  const currentAuthVersion = () => authVersion.value ?? (session.value.isPending ? PENDING_AUTH_VERSION : null);
+  const fetchAccessToken = async ({
+    forceRefreshToken = false
+  } = {}) => {
+    const version = currentAuthVersion();
+    if (version === null) {
+      cachedToken.value = null;
+      cachedTokenVersion = null;
+      pendingToken = null;
+      pendingTokenVersion = null;
+      return null;
+    }
+    if (cachedToken.value && !forceRefreshToken && cachedTokenVersion === version) {
+      return cachedToken.value;
+    }
+    if (!forceRefreshToken && pendingToken && pendingTokenVersion === version) {
+      return pendingToken;
+    }
+    pendingTokenVersion = version;
+    pendingToken = client.convex.token({ fetchOptions: { throw: false } }).then(({ data }) => {
+      const token = data?.token || null;
+      cachedToken.value = token;
+      cachedTokenVersion = version;
+      return token;
+    }).catch(() => {
+      cachedToken.value = null;
+      cachedTokenVersion = version;
+      return null;
+    }).finally(() => {
+      pendingToken = null;
+      pendingTokenVersion = null;
+    });
+    return pendingToken;
+  };
+  return {
+    isLoading: computed(() => session.value.isPending && !cachedToken.value),
+    // Diverges from upstream's `Boolean(session?.session) || cachedToken !== null`:
+    // a settled signed-out session must read unauthenticated immediately (Vue has
+    // no re-render to run upstream's cache-clearing effect first), and Better Auth
+    // session data without a nested `session` still counts as signed in.
+    isAuthenticated: computed(
+      () => !!session.value.data || session.value.isPending && cachedToken.value !== null
+    ),
+    fetchAccessToken,
+    // Vue-only service extensions (documented in PARITY.md).
+    client,
+    session,
+    user: computed(() => {
+      const data = session.value.data;
+      return data?.user ?? null;
+    }),
+    authVersion
+  };
+}
+export function __resetUseAuthForTests() {
+  cachedToken.value = null;
+  cachedTokenVersion = null;
+  pendingToken = null;
+  pendingTokenVersion = null;
+  initialTokenUsed = false;
+}

package/dist/runtime/clerk/vue/index.d.ts

@@ -0,0 +1,81 @@
+import { type ComputedRef, type PropType } from 'vue';
+import { type ConvexAuthState, type IConvexVueClient } from '../../vue/auth/index.js';
+export type UseAuth = () => {
+    isLoaded: ComputedRef<boolean>;
+    isSignedIn: ComputedRef<boolean | undefined>;
+    getToken: ComputedRef<(options: {
+        template?: 'convex';
+        skipCache?: boolean;
+    }) => Promise<string | null>>;
+    orgId: ComputedRef<string | undefined | null>;
+    orgRole: ComputedRef<string | undefined | null>;
+    sessionId: ComputedRef<string | undefined | null>;
+    sessionClaims: ComputedRef<Record<string, unknown> | undefined | null>;
+};
+/**
+ * Options for {@link provideConvexAuthFromClerk} / `<ConvexProviderWithClerk>`.
+ */
+export interface ConvexProviderWithClerkOptions {
+    /** Convex client to authenticate. Defaults to the provided {@link useConvex} client. */
+    client?: IConvexVueClient;
+    /** Clerk's `useAuth` composable. Defaults to `useAuth` from `@clerk/vue`. */
+    useAuth?: UseAuth;
+}
+/**
+ * A composable which provides a {@link ConvexVueClient}
+ * authenticated with Clerk, exposing the reactive auth state to descendants
+ * via {@link useConvexAuth} — the Vue translation of wrapping the app in
+ * `convex/react-clerk`'s `<ConvexProviderWithClerk>`.
+ *
+ * Call it in a top-level component's `setup`. The app must be wrapped by a
+ * configured `clerkPlugin`, from `@clerk/vue`, `@clerk/nuxt` or
+ * another Vue-based Clerk client library and have the corresponding
+ * `useAuth` composable passed in (it defaults to `useAuth` from `@clerk/vue`).
+ *
+ * See [Convex Clerk](https://docs.convex.dev/auth/clerk) on how to set up
+ * Convex with Clerk.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { provideConvexAuthFromClerk } from 'nuxt-convex-module/clerk/client'
+ * provideConvexAuthFromClerk()
+ * </script>
+ * ```
+ *
+ * @public
+ */
+export declare function provideConvexAuthFromClerk(options?: ConvexProviderWithClerkOptions): ConvexAuthState;
+/**
+ * A wrapper Vue component which provides a {@link ConvexVueClient}
+ * authenticated with Clerk — the component form of
+ * {@link provideConvexAuthFromClerk}, kept as a drop-in parity port of
+ * `convex/react-clerk`'s `<ConvexProviderWithClerk>`. Renders its default
+ * slot once Convex auth is wired.
+ *
+ * @public
+ */
+export declare const ConvexProviderWithClerk: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    client: {
+        type: PropType<IConvexVueClient>;
+        default: undefined;
+    };
+    useAuth: {
+        type: PropType<UseAuth>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    client: {
+        type: PropType<IConvexVueClient>;
+        default: undefined;
+    };
+    useAuth: {
+        type: PropType<UseAuth>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    client: IConvexVueClient;
+    useAuth: UseAuth;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/runtime/clerk/vue/index.js

@@ -0,0 +1,49 @@
+import { useAuth as useClerkAuth } from "@clerk/vue";
+import { defineComponent, toValue } from "vue";
+import { provideConvexAuth } from "../../vue/auth/index.js";
+import { useConvexOrThrow } from "../../vue/client.js";
+export function provideConvexAuthFromClerk(options = {}) {
+  const client = options.client ?? useConvexOrThrow("provideConvexAuthFromClerk");
+  const useAuth = options.useAuth ?? useClerkAuth;
+  return provideConvexAuth({ client, useAuth: () => useAuthFromClerk(useAuth) });
+}
+export const ConvexProviderWithClerk = defineComponent({
+  name: "ConvexProviderWithClerk",
+  props: {
+    client: { type: Object, default: void 0 },
+    useAuth: { type: Function, default: void 0 }
+  },
+  setup(props, { slots }) {
+    provideConvexAuthFromClerk({ client: props.client, useAuth: props.useAuth });
+    return () => slots.default?.();
+  }
+});
+function useAuthFromClerk(useAuth) {
+  const { isLoaded, isSignedIn, getToken, orgId, orgRole, sessionId, sessionClaims } = useAuth();
+  const fetchAccessToken = async ({ forceRefreshToken }) => {
+    try {
+      if (toValue(sessionClaims)?.aud === "convex") {
+        return await toValue(getToken)({
+          skipCache: forceRefreshToken
+        });
+      } else {
+        return await toValue(getToken)({
+          template: "convex",
+          skipCache: forceRefreshToken
+        });
+      }
+    } catch {
+      return null;
+    }
+  };
+  return {
+    isLoading: () => !toValue(isLoaded),
+    isAuthenticated: () => toValue(isSignedIn) ?? false,
+    fetchAccessToken,
+    // The `authVersion` key triggers setAuth() whenever these change — the Vue
+    // translation of upstream rebuilding `fetchAccessToken` with dependencies
+    // `[orgId, orgRole, sessionId]`. Anything else from the JWT Clerk wants to
+    // be reactive goes here too.
+    authVersion: () => `${toValue(orgId) ?? ""}:${toValue(orgRole) ?? ""}:${toValue(sessionId) ?? ""}`
+  };
+}

package/dist/runtime/devtools/bridge.d.ts

@@ -0,0 +1,12 @@
+import type { ConvexVueClient } from '../vue/client.js';
+import type { ConvexDevtoolsBridgeHost } from './types.js';
+/**
+ * Attach dev-only DevTools instrumentation to a {@link ConvexVueClient}.
+ *
+ * Observes the client from the outside — wrapping its subscription map,
+ * instance-patching `transition`/`close`, trapping `cachedSync` assignment for
+ * lazy connection-state wiring, and tee-ing the logger — and exposes plain-JSON
+ * snapshots plus change events for the DevTools iframe. Never touches the
+ * `sync` getter (which would open the WebSocket).
+ */
+export declare function createConvexDevtoolsBridge(client: ConvexVueClient): ConvexDevtoolsBridgeHost;

package/dist/runtime/devtools/bridge.js

@@ -0,0 +1,191 @@
+import { convexToJson } from "convex/values";
+const MAX_LOG_ENTRIES = 300;
+function parseQueryToken(token) {
+  try {
+    const parsed = JSON.parse(token);
+    return {
+      udfPath: parsed.udfPath ?? token,
+      args: parsed.args ?? {},
+      paginated: parsed.type === "paginated"
+    };
+  } catch {
+    return { udfPath: token, args: void 0, paginated: false };
+  }
+}
+function toPlainJson(value) {
+  if (value === void 0) return void 0;
+  try {
+    return convexToJson(value);
+  } catch {
+    return String(value);
+  }
+}
+function renderLogArg(arg) {
+  if (typeof arg === "string") return arg;
+  if (arg instanceof Error) return arg.stack ?? String(arg);
+  try {
+    return JSON.stringify(arg);
+  } catch {
+    return String(arg);
+  }
+}
+function serializeConnectionState(state) {
+  return {
+    isWebSocketConnected: state.isWebSocketConnected,
+    hasInflightRequests: state.hasInflightRequests,
+    hasEverConnected: state.hasEverConnected,
+    connectionCount: state.connectionCount,
+    connectionRetries: state.connectionRetries,
+    inflightMutations: state.inflightMutations,
+    inflightActions: state.inflightActions,
+    timeOfOldestInflightRequest: state.timeOfOldestInflightRequest?.getTime() ?? null
+  };
+}
+export function createConvexDevtoolsBridge(client) {
+  const internals = client;
+  const listeners = internals.listeners;
+  const handlers = /* @__PURE__ */ new Map();
+  const emit = (event, payload) => {
+    for (const handler of handlers.get(event) ?? []) {
+      handler(payload);
+    }
+  };
+  let closed = false;
+  const queryStats = /* @__PURE__ */ new Map();
+  const logs = [];
+  let auth = { available: false };
+  const computeQueries = () => {
+    const sync = internals.cachedSync;
+    return Array.from(listeners.entries(), ([token, callbacks]) => {
+      const { udfPath, args, paginated } = parseQueryToken(token);
+      const stats = queryStats.get(token);
+      const snapshot = {
+        token,
+        udfPath,
+        args,
+        paginated,
+        listenerCount: callbacks.size,
+        updates: stats?.updates ?? 0,
+        lastUpdatedAt: stats?.lastUpdatedAt ?? null
+      };
+      try {
+        snapshot.result = toPlainJson(sync?.localQueryResultByToken?.(token));
+      } catch (error) {
+        snapshot.errorMessage = error instanceof Error ? error.message : String(error);
+      }
+      const queryLogs = sync?.optimisticQueryResults?.queryLogs?.(token);
+      if (queryLogs?.length) snapshot.logs = queryLogs;
+      return snapshot;
+    });
+  };
+  let queriesEmitScheduled = false;
+  const scheduleQueriesEmit = () => {
+    if (queriesEmitScheduled || closed) return;
+    queriesEmitScheduled = true;
+    queueMicrotask(() => {
+      queriesEmitScheduled = false;
+      if (!closed) emit("queries", computeQueries());
+    });
+  };
+  const originalSet = listeners.set.bind(listeners);
+  listeners.set = (key, value) => {
+    const result = originalSet(key, value);
+    scheduleQueriesEmit();
+    return result;
+  };
+  const originalDelete = listeners.delete.bind(listeners);
+  listeners.delete = (key) => {
+    const result = originalDelete(key);
+    queryStats.delete(key);
+    scheduleQueriesEmit();
+    return result;
+  };
+  const originalTransition = internals.transition.bind(client);
+  internals.transition = (updatedQueries) => {
+    originalTransition(updatedQueries);
+    const now = Date.now();
+    for (const token of updatedQueries) {
+      const stats = queryStats.get(token) ?? { updates: 0, lastUpdatedAt: now };
+      stats.updates += 1;
+      stats.lastUpdatedAt = now;
+      queryStats.set(token, stats);
+    }
+    scheduleQueriesEmit();
+  };
+  const computeConnection = () => {
+    if (closed) return { status: "closed" };
+    const sync = internals.cachedSync;
+    if (!sync) return { status: "idle" };
+    return { status: "active", state: serializeConnectionState(sync.connectionState()) };
+  };
+  let unsubscribeConnection;
+  const onSyncCreated = (sync) => {
+    if (unsubscribeConnection || closed) return;
+    unsubscribeConnection = sync.subscribeToConnectionState((state) => {
+      if (!closed) emit("connection", { status: "active", state: serializeConnectionState(state) });
+    });
+    emit("connection", computeConnection());
+  };
+  let cachedSyncValue = internals.cachedSync;
+  Object.defineProperty(client, "cachedSync", {
+    configurable: true,
+    get: () => cachedSyncValue,
+    set: (value) => {
+      cachedSyncValue = value;
+      if (value) onSyncCreated(value);
+    }
+  });
+  if (cachedSyncValue) onSyncCreated(cachedSyncValue);
+  const originalClose = client.close.bind(client);
+  client.close = async () => {
+    closed = true;
+    unsubscribeConnection?.();
+    unsubscribeConnection = void 0;
+    emit("connection", { status: "closed" });
+    await originalClose();
+  };
+  const logger = client.logger;
+  const levels = [
+    ["logVerbose", "verbose"],
+    ["log", "log"],
+    ["warn", "warn"],
+    ["error", "error"]
+  ];
+  for (const [method, level] of levels) {
+    const original = logger[method].bind(logger);
+    logger[method] = (...args) => {
+      original(...args);
+      if (closed) return;
+      const entry = { level, args: args.map(renderLogArg), timestamp: Date.now() };
+      logs.push(entry);
+      if (logs.length > MAX_LOG_ENTRIES) logs.splice(0, logs.length - MAX_LOG_ENTRIES);
+      emit("log", entry);
+    };
+  }
+  return {
+    version: 1,
+    getSnapshot() {
+      return {
+        connection: computeConnection(),
+        queries: computeQueries(),
+        auth,
+        logs: [...logs]
+      };
+    },
+    on(event, callback) {
+      let set = handlers.get(event);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        handlers.set(event, set);
+      }
+      set.add(callback);
+      return () => {
+        set.delete(callback);
+      };
+    },
+    setAuth(snapshot) {
+      auth = snapshot;
+      if (!closed) emit("auth", snapshot);
+    }
+  };
+}

package/dist/runtime/devtools/plugin.client.d.ts

@@ -0,0 +1,8 @@
+import type { ConvexDevtoolsBridge } from './types.js';
+declare global {
+    interface Window {
+        __NUXT_CONVEX_DEVTOOLS__?: ConvexDevtoolsBridge;
+    }
+}
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/devtools/plugin.client.js

@@ -0,0 +1,34 @@
+import { defineNuxtPlugin } from "#app";
+import { inject, watchEffect } from "vue";
+import { ConvexClientKey } from "../vue/client.js";
+import { ConvexAuthStateKey } from "../vue/auth/index.js";
+import { createConvexDevtoolsBridge } from "./bridge.js";
+export default defineNuxtPlugin({
+  name: "nuxt-convex-module:devtools",
+  setup(nuxtApp) {
+    const attach = () => {
+      const client = nuxtApp.vueApp.runWithContext(() => inject(ConvexClientKey, void 0));
+      if (!client) return false;
+      const bridge = createConvexDevtoolsBridge(client);
+      const auth = nuxtApp.vueApp.runWithContext(() => inject(ConvexAuthStateKey, void 0));
+      if (auth) {
+        watchEffect(() => {
+          bridge.setAuth({
+            available: true,
+            isLoading: auth.isLoading.value,
+            isAuthenticated: auth.isAuthenticated.value,
+            isRefreshing: auth.isRefreshing.value
+          });
+        });
+      }
+      nuxtApp.provide("convexDevtools", bridge);
+      window.__NUXT_CONVEX_DEVTOOLS__ = bridge;
+      return true;
+    };
+    if (!attach()) {
+      nuxtApp.hook("app:mounted", () => {
+        attach();
+      });
+    }
+  }
+});

package/dist/runtime/devtools/types.d.ts

@@ -0,0 +1,78 @@
+/** Serialized `ConnectionState` (Date → epoch ms) plus the client lifecycle. */
+export interface DevtoolsConnectionSnapshot {
+    /**
+     * `idle` — the underlying sync client (and its WebSocket) has not been
+     * created yet; `active` — it exists; `closed` — the client was closed.
+     */
+    status: 'idle' | 'active' | 'closed';
+    state?: {
+        isWebSocketConnected: boolean;
+        hasInflightRequests: boolean;
+        hasEverConnected: boolean;
+        connectionCount: number;
+        connectionRetries: number;
+        inflightMutations: number;
+        inflightActions: number;
+        timeOfOldestInflightRequest: number | null;
+    };
+}
+/** One active query subscription on the client. */
+export interface DevtoolsQuerySnapshot {
+    /** The client's internal query token (stable identity for the panel). */
+    token: string;
+    udfPath: string;
+    /** Query args, JSON-serialized (`convexToJson` shape). */
+    args: unknown;
+    /** Whether this is a paginated-query page subscription. */
+    paginated: boolean;
+    /** Number of Vue-layer listeners sharing this subscription. */
+    listenerCount: number;
+    /** Server transitions observed for this token since the bridge attached. */
+    updates: number;
+    /** Epoch ms of the last observed transition, if any. */
+    lastUpdatedAt: number | null;
+    /** Current local result, JSON-serialized — absent while loading. */
+    result?: unknown;
+    /** Set instead of `result` when the query errored. */
+    errorMessage?: string;
+    /** Server-side log lines from this query's execution, if any. */
+    logs?: string[];
+}
+export interface DevtoolsAuthSnapshot {
+    /** False when no app-level auth state is observable (e.g. Clerk/Auth0). */
+    available: boolean;
+    isLoading?: boolean;
+    isAuthenticated?: boolean;
+    isRefreshing?: boolean;
+}
+export interface DevtoolsLogEntry {
+    level: 'verbose' | 'log' | 'warn' | 'error';
+    /** Log arguments, each rendered to a string. */
+    args: string[];
+    /** Epoch ms. */
+    timestamp: number;
+}
+export interface DevtoolsSnapshot {
+    connection: DevtoolsConnectionSnapshot;
+    queries: DevtoolsQuerySnapshot[];
+    auth: DevtoolsAuthSnapshot;
+    logs: DevtoolsLogEntry[];
+}
+export interface BridgeEvents {
+    connection: (connection: DevtoolsConnectionSnapshot) => void;
+    queries: (queries: DevtoolsQuerySnapshot[]) => void;
+    auth: (auth: DevtoolsAuthSnapshot) => void;
+    log: (entry: DevtoolsLogEntry) => void;
+}
+/** The surface the DevTools iframe consumes via `$convexDevtools`. */
+export interface ConvexDevtoolsBridge {
+    version: 1;
+    getSnapshot(): DevtoolsSnapshot;
+    /** Subscribe to an event; returns an unsubscribe function. */
+    on<E extends keyof BridgeEvents>(event: E, callback: BridgeEvents[E]): () => void;
+}
+/** Host-side extras the plugin uses; not part of the iframe contract. */
+export interface ConvexDevtoolsBridgeHost extends ConvexDevtoolsBridge {
+    /** Push the app-level auth state into the bridge (plugin-side). */
+    setAuth(auth: DevtoolsAuthSnapshot): void;
+}