use-convex 0.0.2

package/dist/runtime/composables/useConvexQueries.js

@@ -0,0 +1,84 @@
+import { getFunctionName } from "convex/server";
+import { convexToJson } from "convex/values";
+import {
+  computed,
+  onScopeDispose,
+  shallowRef,
+  toValue,
+  watch
+} from "vue";
+import { useConvexContext } from "../utils/context.js";
+function subscriptionSignature(query, args) {
+  return `${getFunctionName(query)}:${JSON.stringify(convexToJson(args))}`;
+}
+export function useConvexQueries(queries) {
+  const ctx = useConvexContext();
+  const results = shallowRef({});
+  if (import.meta.server || !ctx.client) {
+    return computed(
+      () => results.value
+    );
+  }
+  const client = ctx.client;
+  const unsubscribers = /* @__PURE__ */ new Map();
+  const signatures = /* @__PURE__ */ new Map();
+  const dropKey = (key) => {
+    unsubscribers.get(key)?.();
+    unsubscribers.delete(key);
+    signatures.delete(key);
+    if (key in results.value) {
+      const { [key]: _, ...rest } = results.value;
+      results.value = rest;
+    }
+  };
+  const sync = (request) => {
+    const nextKeys = new Set(Object.keys(request));
+    for (const key of unsubscribers.keys()) {
+      if (!nextKeys.has(key)) {
+        dropKey(key);
+      }
+    }
+    for (const [key, entry] of Object.entries(request)) {
+      if (entry === "skip") {
+        dropKey(key);
+        continue;
+      }
+      const { query, args } = entry;
+      const signature = subscriptionSignature(query, args);
+      if (signatures.get(key) === signature && unsubscribers.has(key)) {
+        continue;
+      }
+      unsubscribers.get(key)?.();
+      const unsubscribe = client.onUpdate(
+        query,
+        args,
+        (value) => {
+          results.value = { ...results.value, [key]: value };
+        },
+        (err) => {
+          results.value = { ...results.value, [key]: err };
+        }
+      );
+      unsubscribers.set(key, unsubscribe);
+      signatures.set(key, signature);
+      if (!(key in results.value)) {
+        results.value = { ...results.value, [key]: void 0 };
+      }
+    }
+  };
+  watch(
+    () => toValue(queries),
+    (request) => {
+      sync(request);
+    },
+    { immediate: true, deep: true }
+  );
+  onScopeDispose(() => {
+    for (const unsubscribe of unsubscribers.values()) {
+      unsubscribe();
+    }
+    unsubscribers.clear();
+    signatures.clear();
+  });
+  return computed(() => results.value);
+}

package/dist/runtime/composables/useConvexQuery.d.ts

@@ -0,0 +1,56 @@
+import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
+export type ConvexQueryArgs<Query extends FunctionReference<'query'>> = FunctionArgs<Query> | 'skip';
+export interface UseConvexQueryOptions {
+    /**
+     * Explicit Nuxt payload/cache key.
+     * Defaults to `convex:<functionName>:<argsJSON>`.
+     * `'skip'` does not change the key (same slot as empty args).
+     */
+    key?: string;
+    /**
+     * Run the HttpClient snapshot during SSR and transfer it through the Nuxt payload.
+     * Defaults to `convex.server` from module config (`true`).
+     */
+    server?: boolean;
+    /**
+     * Make the initial Nuxt request non-blocking during client navigation.
+     * @default false
+     */
+    lazy?: boolean;
+    /**
+     * Subscribe with ConvexClient on the browser after hydration.
+     * @default true
+     */
+    live?: boolean;
+    /**
+     * JWT for this request's HttpClient (SSR / one-shot refresh).
+     * Never put this in public runtime config.
+     */
+    token?: string;
+    /**
+     * Skip HttpClient fetch and live subscribe until Convex confirms auth
+     * (`isAuthenticated`). SSR still runs when the server plugin stamps auth
+     * from the JWT cookie; the client keeps the SSR payload via the overlay
+     * until `setAuth` confirms. Prefer this over manually wrapping args in
+     * `computed(() => isAuthenticated.value ? args : 'skip')`.
+     *
+     * @default false
+     */
+    authenticated?: boolean;
+}
+export interface UseConvexQueryReturn<T> {
+    data: Ref<T | null | undefined> | ComputedRef<T | null | undefined>;
+    error: Ref<Error | null | undefined> | ComputedRef<Error | null | undefined>;
+    pending: Ref<boolean> | ComputedRef<boolean>;
+    status: Ref<'pending' | 'success' | 'error' | string> | ComputedRef<'pending' | 'success' | 'error' | string>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Nuxt-native Convex query.
+ *
+ * Server + client both call `useAsyncData` so the Nuxt payload hydrates without
+ * a duplicate HTTP request. On the browser, a live `ConvexClient` subscription
+ * overlays the payload (`live ?? payload`), matching Next.js `usePreloadedQuery`.
+ */
+export declare function useConvexQuery<Query extends FunctionReference<'query'>>(query: Query, args?: MaybeRefOrGetter<ConvexQueryArgs<Query>>, options?: UseConvexQueryOptions): Promise<UseConvexQueryReturn<FunctionReturnType<Query>>>;

package/dist/runtime/composables/useConvexQuery.js

@@ -0,0 +1,147 @@
+import { convexToJson, jsonToConvex } from "convex/values";
+import { useAsyncData, useNuxtApp, useRuntimeConfig } from "nuxt/app";
+import {
+  computed,
+  onScopeDispose,
+  ref,
+  toValue,
+  watch
+} from "vue";
+import { resolveAuthGatedArgs } from "../utils/authGate.js";
+import { useConvexContext } from "../utils/context.js";
+import { resolveQueryOverlay } from "../utils/overlay.js";
+import { convexQueryKey } from "../utils/queryKey.js";
+export async function useConvexQuery(query, args = {}, options = {}) {
+  const runtimeConfig = useRuntimeConfig();
+  const defaultServer = runtimeConfig.public.convex?.server;
+  const server = options.server ?? defaultServer ?? true;
+  const live = options.live ?? true;
+  const requireAuth = options.authenticated ?? false;
+  const ctx = useConvexContext();
+  const resolveRawArgs = () => toValue(args);
+  const resolveEffectiveArgs = () => resolveAuthGatedArgs(resolveRawArgs(), {
+    authenticated: requireAuth,
+    isAuthenticated: ctx.auth.isAuthenticated.value
+  });
+  const key = computed(
+    () => convexQueryKey(query, resolveRawArgs(), options.key)
+  );
+  const asyncData = await useAsyncData(
+    key,
+    async () => {
+      const argsValue = resolveEffectiveArgs();
+      if (argsValue === "skip") {
+        return null;
+      }
+      const token = options.token ?? ctx.ssrToken.value;
+      if (requireAuth && import.meta.client && !token) {
+        const nuxtApp = useNuxtApp();
+        const cached = nuxtApp.payload.data[toValue(key)];
+        return cached ?? null;
+      }
+      const http = ctx.createHttpClient({ token });
+      const result = await http.query(
+        query,
+        argsValue ?? {}
+      );
+      return jsonToConvex(convexToJson(result));
+    },
+    {
+      server,
+      lazy: options.lazy ?? false,
+      watch: [
+        () => toValue(args),
+        // Re-run HttpClient snapshot when the SSR JWT cookie / token changes
+        // (e.g. after sign-in with live:false, or Refresh).
+        () => options.token ?? ctx.ssrToken.value,
+        // Re-run when auth confirms *and* a JWT is available for HttpClient
+        // (readable cookie / SSR). Avoids anonymous client refetches with HttpOnly.
+        () => requireAuth && ctx.auth.isAuthenticated.value && !!(options.token ?? ctx.ssrToken.value)
+      ]
+    }
+  );
+  const refresh = async () => {
+    if (requireAuth && import.meta.client && !(options.token ?? ctx.ssrToken.value)) {
+      return;
+    }
+    await asyncData.refresh();
+  };
+  if (import.meta.server || !live) {
+    return {
+      data: asyncData.data,
+      error: asyncData.error,
+      pending: computed(() => {
+        if (resolveEffectiveArgs() === "skip") {
+          return false;
+        }
+        return asyncData.pending.value;
+      }),
+      status: computed(() => {
+        if (resolveEffectiveArgs() === "skip") {
+          return "success";
+        }
+        return asyncData.status.value;
+      }),
+      refresh
+    };
+  }
+  const client = ctx.client;
+  if (!client) {
+    throw new Error("[convex-nuxt] ConvexClient is not available on the client.");
+  }
+  const liveReady = ref(false);
+  const liveData = ref();
+  const liveError = ref(null);
+  let cancel;
+  const subscribe = (argsValue) => {
+    cancel?.();
+    cancel = void 0;
+    liveReady.value = false;
+    liveError.value = null;
+    if (argsValue === "skip") {
+      liveData.value = void 0;
+      return;
+    }
+    cancel = client.onUpdate(
+      query,
+      argsValue ?? {},
+      (result) => {
+        liveData.value = result;
+        liveError.value = null;
+        liveReady.value = true;
+      },
+      (err) => {
+        liveError.value = err;
+        liveReady.value = true;
+      }
+    );
+  };
+  watch(
+    () => [resolveEffectiveArgs(), ctx.auth.isAuthenticated.value],
+    ([argsValue]) => {
+      subscribe(argsValue);
+    },
+    { immediate: true }
+  );
+  onScopeDispose(() => {
+    cancel?.();
+  });
+  const overlay = computed(
+    () => resolveQueryOverlay({
+      skipped: resolveEffectiveArgs() === "skip",
+      liveReady: liveReady.value,
+      liveData: liveData.value,
+      liveError: liveError.value,
+      payload: asyncData.data.value,
+      payloadError: asyncData.error.value ?? null,
+      payloadPending: asyncData.pending.value
+    })
+  );
+  return {
+    data: computed(() => overlay.value.data),
+    error: computed(() => overlay.value.error),
+    pending: computed(() => overlay.value.pending),
+    status: computed(() => overlay.value.status),
+    refresh
+  };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * First-party Convex Auth wiring (opt-in via `convex.auth.provider: 'convex-auth'`).
+ *
+ * Must stay synchronous through `useConvexAuth` / `inject` — awaiting first
+ * drops Vue setup context and caused the "plugin did not start" 500.
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

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

@@ -0,0 +1,41 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { useConvexAuth } from "./composables/useConvexAuth.js";
+import {
+  consumeOAuthCodeFromUrl,
+  getAuthToken,
+  hasPendingOAuthCallback,
+  hydrateAuthFromStorage,
+  useAuthProviderState
+} from "./composables/useAuth.js";
+import { tryUseConvexContext } from "./utils/context.js";
+export default defineNuxtPlugin({
+  name: "convex-nuxt-auth",
+  dependsOn: ["convex-nuxt-client"],
+  setup() {
+    const config = useRuntimeConfig();
+    const convexConfig = config.public.convex;
+    if (!convexConfig?.url) {
+      return;
+    }
+    if (!tryUseConvexContext()) {
+      return;
+    }
+    const pendingOAuth = hasPendingOAuthCallback();
+    if (!pendingOAuth) {
+      hydrateAuthFromStorage();
+    }
+    const { isLoading, hasSession } = useAuthProviderState();
+    useConvexAuth({
+      fetchToken: ({ forceRefreshToken }) => getAuthToken({ forceRefreshToken }),
+      isLoading,
+      isAuthenticated: hasSession
+    });
+    if (pendingOAuth) {
+      void consumeOAuthCodeFromUrl().then((ok) => {
+        if (!ok) {
+          hydrateAuthFromStorage();
+        }
+      });
+    }
+  }
+});

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

@@ -0,0 +1,7 @@
+import { type ConvexNuxtContext } from './utils/context.js';
+declare const _default: import("nuxt/app").Plugin<{
+    convex: ConvexNuxtContext;
+}> & import("nuxt/app").ObjectPlugin<{
+    convex: ConvexNuxtContext;
+}>;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,40 @@
+import { ConvexClient } from "convex/browser";
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { useSsrTokenRef } from "./utils/authCookie.js";
+import { createHttpClient } from "./utils/http.js";
+import {
+  convexNuxtKey,
+  createAuthContext
+} from "./utils/context.js";
+export default defineNuxtPlugin({
+  name: "convex-nuxt-client",
+  setup(nuxtApp) {
+    const config = useRuntimeConfig();
+    const convexConfig = config.public.convex;
+    const url = convexConfig?.url;
+    if (!url) {
+      if (import.meta.dev) {
+        console.warn(
+          "[convex-nuxt] No Convex URL configured. Set convex.url or NUXT_PUBLIC_CONVEX_URL."
+        );
+      }
+      return;
+    }
+    const client = new ConvexClient(url, convexConfig?.client ?? {});
+    const ssrToken = useSsrTokenRef();
+    const auth = createAuthContext();
+    const ctx = {
+      url,
+      client,
+      ssrToken,
+      auth,
+      createHttpClient: (options) => createHttpClient(url, options)
+    };
+    nuxtApp.vueApp.provide(convexNuxtKey, ctx);
+    return {
+      provide: {
+        convex: ctx
+      }
+    };
+  }
+});

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

@@ -0,0 +1,6 @@
+/**
+ * Expose connection state on `window.__CONVEX_NUXT__` in development for
+ * quick inspection alongside the DevTools iframe tab.
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

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

@@ -0,0 +1,16 @@
+import { defineNuxtPlugin } from "nuxt/app";
+import { useConvexConnectionState } from "./composables/useConvexConnectionState.js";
+import { tryUseConvexContext } from "./utils/context.js";
+export default defineNuxtPlugin({
+  name: "convex-nuxt-devtools",
+  setup() {
+    if (!import.meta.dev || !tryUseConvexContext()) {
+      return;
+    }
+    const connection = useConvexConnectionState();
+    if (typeof window !== "undefined") {
+      ;
+      window.__CONVEX_NUXT__ = { connection };
+    }
+  }
+});

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

@@ -0,0 +1,7 @@
+import { type ConvexNuxtContext } from './utils/context.js';
+declare const _default: import("nuxt/app").Plugin<{
+    convex: ConvexNuxtContext;
+}> & import("nuxt/app").ObjectPlugin<{
+    convex: ConvexNuxtContext;
+}>;
+export default _default;

package/dist/runtime/plugin.server.js

@@ -0,0 +1,44 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+import { useSsrTokenRef } from "./utils/authCookie.js";
+import { createHttpClient } from "./utils/http.js";
+import {
+  convexNuxtKey,
+  createAuthContext
+} from "./utils/context.js";
+export default defineNuxtPlugin({
+  name: "convex-nuxt-server",
+  setup(nuxtApp) {
+    const config = useRuntimeConfig();
+    const convexConfig = config.public.convex;
+    const url = convexConfig?.url;
+    if (!url) {
+      if (import.meta.dev) {
+        console.warn(
+          "[convex-nuxt] No Convex URL configured. Set convex.url or NUXT_PUBLIC_CONVEX_URL."
+        );
+      }
+      return;
+    }
+    const ssrToken = useSsrTokenRef();
+    const auth = createAuthContext();
+    if (ssrToken.value) {
+      auth.providerAuthenticated.value = true;
+      auth.isConvexAuthenticated.value = true;
+      auth.isLoading.value = false;
+      auth.isAuthenticated.value = true;
+    }
+    const ctx = {
+      url,
+      client: null,
+      ssrToken,
+      auth,
+      createHttpClient: (options) => createHttpClient(url, options)
+    };
+    nuxtApp.vueApp.provide(convexNuxtKey, ctx);
+    return {
+      provide: {
+        convex: ctx
+      }
+    };
+  }
+});

package/dist/runtime/server/api/convex/auth/session.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persist / read / refresh HttpOnly auth cookies.
+ *
+ * - GET → `{ hasSession }` only (no JWT in the response body)
+ * - POST `{ getToken: true }` → `{ hasSession, token }` for ConvexClient.setAuth
+ * - POST `{ refresh: true }` → refresh cookies, return `{ token }`
+ * - POST `{ token, refreshToken }` → set cookies
+ * - DELETE → clear cookies
+ *
+ * All methods require same-origin (fail-closed). Returning the JWT only via
+ * POST reduces accidental leakage via prefetch/logs; XSS can still obtain a
+ * token once ConvexClient needs it in memory — HttpOnly mitigates cookie theft,
+ * not XSS session theft.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    hasSession: boolean;
+    ok?: undefined;
+    token?: undefined;
+} | {
+    ok: boolean;
+    hasSession?: undefined;
+    token?: undefined;
+} | {
+    hasSession: boolean;
+    token: string | null;
+    ok?: undefined;
+} | {
+    token: null;
+    hasSession?: undefined;
+    ok?: undefined;
+} | {
+    token: string;
+    hasSession?: undefined;
+    ok?: undefined;
+}>>;
+export default _default;

package/dist/runtime/server/api/convex/auth/session.js

@@ -0,0 +1,95 @@
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  createError,
+  defineEventHandler,
+  readBody
+} from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import {
+  readHttpOnlyJwt,
+  readHttpOnlyRefresh,
+  setAuthCookies
+} from "../../../authCookies.js";
+import { isHttpOnlyAuth } from "../../../../utils/authStorage.js";
+import { assertSameOrigin } from "../../../sameOrigin.js";
+const authSignIn = makeFunctionReference("auth:signIn");
+function convexUrl(event) {
+  const config = useRuntimeConfig(event);
+  const url = config.public?.convex?.url ?? process.env.NUXT_PUBLIC_CONVEX_URL;
+  if (!url) {
+    throw createError({
+      statusCode: 500,
+      message: "Convex URL is not configured"
+    });
+  }
+  return url;
+}
+function requireHttpOnly(event) {
+  const config = useRuntimeConfig(event);
+  const auth = config.public?.convex?.auth;
+  if (!isHttpOnlyAuth(auth)) {
+    throw createError({
+      statusCode: 404,
+      message: "HttpOnly auth is not enabled"
+    });
+  }
+}
+export default defineEventHandler(async (event) => {
+  requireHttpOnly(event);
+  assertSameOrigin(event);
+  if (event.method === "GET") {
+    const token = readHttpOnlyJwt(event);
+    return {
+      hasSession: !!token
+    };
+  }
+  if (event.method === "DELETE") {
+    setAuthCookies(event, { token: null });
+    return { ok: true };
+  }
+  if (event.method === "POST") {
+    const body = await readBody(event);
+    if (body?.getToken) {
+      const token = readHttpOnlyJwt(event);
+      return {
+        hasSession: !!token,
+        token: token ?? null
+      };
+    }
+    if (body?.refresh) {
+      const refreshToken = readHttpOnlyRefresh(event);
+      if (!refreshToken) {
+        setAuthCookies(event, { token: null });
+        return { token: null };
+      }
+      const http = new ConvexHttpClient(convexUrl(event));
+      try {
+        const result = await http.action(authSignIn, { refreshToken });
+        const tokens = result.tokens ?? null;
+        if (!tokens) {
+          setAuthCookies(event, { token: null });
+          return { token: null };
+        }
+        setAuthCookies(event, {
+          token: tokens.token,
+          refreshToken: tokens.refreshToken
+        });
+        return { token: tokens.token };
+      } catch {
+        setAuthCookies(event, { token: null });
+        return { token: null };
+      }
+    }
+    if (!body?.token) {
+      setAuthCookies(event, { token: null });
+      return { ok: true };
+    }
+    setAuthCookies(event, {
+      token: body.token,
+      refreshToken: body.refreshToken ?? null
+    });
+    return { ok: true };
+  }
+  throw createError({ statusCode: 405, message: "Method not allowed" });
+});

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

@@ -0,0 +1,19 @@
+import type { H3Event } from 'h3';
+/**
+ * Read the Convex JWT from the configured auth cookie on this request.
+ * Returns `undefined` when the cookie is missing or auth cookies are disabled.
+ */
+export declare function getConvexToken(event: H3Event): string | undefined;
+/**
+ * Require a Convex JWT cookie on this Nitro request.
+ * Throws an H3 401 when the cookie is missing.
+ *
+ * @example
+ * ```ts
+ * export default defineEventHandler(async (event) => {
+ *   requireConvexAuth(event)
+ *   return await fetchQuery(api.tasks.list, {}, { event })
+ * })
+ * ```
+ */
+export declare function requireConvexAuth(event: H3Event): string;

package/dist/runtime/server/auth.js

@@ -0,0 +1,32 @@
+import { createError, getCookie } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { resolveAuthCookieName } from "../utils/authStorage.js";
+import { resolveFetchToken } from "../utils/fetchToken.js";
+function readConvexConfig(event) {
+  try {
+    const config = useRuntimeConfig(event);
+    return config.public?.convex;
+  } catch {
+    return void 0;
+  }
+}
+export function getConvexToken(event) {
+  const cookieName = resolveAuthCookieName(readConvexConfig(event)?.auth);
+  if (!cookieName) {
+    return void 0;
+  }
+  return resolveFetchToken({
+    cookieName,
+    cookieValue: getCookie(event, cookieName)
+  });
+}
+export function requireConvexAuth(event) {
+  const token = getConvexToken(event);
+  if (!token) {
+    throw createError({
+      statusCode: 401,
+      message: "Not authenticated \u2014 sign in so the Convex auth cookie is set."
+    });
+  }
+  return token;
+}

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

@@ -0,0 +1,9 @@
+import type { H3Event } from 'h3';
+export interface AuthCookieSet {
+    token: string | null;
+    refreshToken?: string | null;
+}
+/** Persist or clear HttpOnly auth cookies + readable presence marker. */
+export declare function setAuthCookies(event: H3Event, tokens: AuthCookieSet): void;
+export declare function readHttpOnlyJwt(event: H3Event): string | undefined;
+export declare function readHttpOnlyRefresh(event: H3Event): string | undefined;