use-convex 1.2.0 → 2.0.0

package/dist/runtime/composables/useAuth.js

@@ -1,413 +1,84 @@
-import { ConvexHttpClient } from "convex/browser";
-import { makeFunctionReference } from "convex/server";
-import { computed, nextTick } from "vue";
-import { useRuntimeConfig, useState } from "nuxt/app";
+import { computed, ref, shallowRef } from "vue";
+import { useConvexContext } from "../utils/context.js";
 import { useConvexAuth } from "./useConvexAuth.js";
-import { missingConvexUrlError, unreachableConvexUrlError } from "../utils/errors.js";
-import { withRefreshMutex } from "../utils/authMutex.js";
-import { useAuthJwtCookie, useAuthPresentCookie } from "../utils/authCookie.js";
 import {
-  flattenSignInParams,
-  isHttpOnlyAuth,
-  JWT_STORAGE_KEY,
-  readLocal,
-  REFRESH_TOKEN_STORAGE_KEY,
-  shouldConsumeOAuthCode,
-  storageKey,
-  VERIFIER_STORAGE_KEY,
-  writeLocal
-} from "../utils/authStorage.js";
-import { tryUseConvexContext } from "../utils/context.js";
-import { parseOAuthRedirect } from "../utils/oauthRedirect.js";
-const authSignIn = makeFunctionReference("auth:signIn");
-const authSignOut = makeFunctionReference("auth:signOut");
-const RETRY_BACKOFF = [500, 2e3];
-const RETRY_JITTER = 100;
+  OAUTH_ACTIONS_KEY,
+  OAUTH_FLOW_ERROR_KEY,
+  OAUTH_SETUP_ID
+} from "../auth/oauth.js";
+function useBinding(name) {
+  const ctx = useConvexContext();
+  if (!import.meta.server && !ctx.convexAuth) {
+    throw new Error(
+      `[use-convex] ${name} requires \`convex.auth.provider: 'convex-auth'\` in nuxt.config.`
+    );
+  }
+  return ctx.convexAuth ?? null;
+}
+function requireBinding(name) {
+  const binding = useConvexContext().convexAuth;
+  if (!binding) {
+    throw new Error(`[use-convex] ${name} is browser-only and requires Convex Auth.`);
+  }
+  return binding;
+}
 export function useAuth() {
-  const session = useAuthSession();
-  if (!tryUseConvexContext()) {
-    return {
-      isLoading: computed(() => session.isLoading.value),
-      isAuthenticated: computed(() => false),
-      isRefreshing: computed(() => false),
-      hasSsrSession: computed(() => false),
-      showAuthedUi: computed(() => false),
-      error: session.error,
-      pending: session.pending,
-      signIn,
-      signOut
-    };
-  }
-  const convexAuth = useConvexAuth();
+  const binding = useBinding("useAuth");
+  const auth = useConvexAuth();
   return {
-    isLoading: convexAuth.isLoading,
-    isAuthenticated: convexAuth.isAuthenticated,
-    isRefreshing: convexAuth.isRefreshing,
-    hasSsrSession: convexAuth.hasSsrSession,
-    showAuthedUi: convexAuth.showAuthedUi,
-    error: session.error,
-    pending: session.pending,
-    signIn,
-    signOut
+    ...auth,
+    token: computed(() => binding?.state.value.token ?? null),
+    setSession: (session) => requireBinding("setSession").setSession(session),
+    signOut: () => signOut()
   };
 }
-export async function signIn(provider, params) {
-  const session = useAuthSession();
-  const convexUrl = session.convexUrl;
-  if (!convexUrl) {
-    throw missingConvexUrlError("signIn");
-  }
-  session.pending.value = true;
-  session.error.value = null;
-  try {
-    const flatParams = flattenSignInParams(params);
-    const existingVerifier = readLocal(session.verifierKey.value) ?? void 0;
-    writeLocal(session.verifierKey.value, null);
-    const result = await callSignIn(convexUrl, {
-      provider,
-      params: flatParams,
-      verifier: existingVerifier
-    });
-    if (result.redirect !== void 0) {
-      const url = parseOAuthRedirect(result.redirect);
-      if (result.verifier) {
-        writeLocal(session.verifierKey.value, result.verifier);
-      }
-      if (import.meta.client) {
-        window.location.href = url.toString();
-      }
-      return { signingIn: false, redirect: url };
-    }
-    if (result.tokens !== void 0) {
-      await persistTokens(session, result.tokens);
-      return { signingIn: result.tokens !== null };
-    }
-    return { signingIn: false };
-  } catch (cause) {
-    const message = isNetworkError(cause) && convexUrl ? unreachableConvexUrlError(convexUrl).message : cause instanceof Error ? cause.message : "Authentication failed";
-    session.error.value = message;
-    throw cause;
-  } finally {
-    session.pending.value = false;
-  }
-}
 export async function signOut() {
-  const session = useAuthSession();
-  const convexUrl = session.convexUrl;
-  session.pending.value = true;
-  session.error.value = null;
-  try {
-    if (convexUrl) {
-      const token = readLocal(session.jwtKey.value);
-      const http = new ConvexHttpClient(convexUrl);
-      if (token) {
-        http.setAuth(token);
-      }
-      try {
-        await http.action(authSignOut, {});
-      } catch {
-      }
-    }
-    await persistTokens(session, null);
-  } finally {
-    session.pending.value = false;
-  }
-}
-export function hydrateAuthFromStorage() {
-  const session = useAuthSession();
-  if (!session.convexUrl) {
-    session.isLoading.value = false;
-    session.hasSession.value = false;
-    return;
-  }
-  if (session.httpOnly) {
-    const present = useAuthPresentCookie();
-    if (present?.value === "1") {
-      session.hasSession.value = true;
-      session.isLoading.value = false;
-      return;
-    }
-    session.isLoading.value = true;
-    void fetchAuthSession().then((result) => {
-      session.hasSession.value = result.hasSession;
-      session.isLoading.value = false;
-      if (result.hasSession) {
-        const marker = useAuthPresentCookie();
-        if (marker) {
-          marker.value = "1";
-        }
-      }
-    });
-    return;
-  }
-  const token = readLocal(session.jwtKey.value);
-  session.hasSession.value = token !== null;
-  session.isLoading.value = false;
-  if (token) {
-    setJwtCookie(token);
-  }
-}
-export async function getAuthToken({
-  forceRefreshToken
-}) {
-  const session = useAuthSession();
-  const convexUrl = session.convexUrl;
-  if (!convexUrl) {
-    return null;
-  }
-  if (session.httpOnly) {
-    return withRefreshMutex(session.refreshKey.value, async () => {
-      if (!forceRefreshToken) {
-        const current = await fetchAuthSessionToken();
-        if (current.token) {
-          session.hasSession.value = true;
-          return current.token;
-        }
-      }
-      const refreshed = await refreshAuthSession();
-      if (!refreshed) {
-        await clearAuthSession();
-        session.hasSession.value = false;
-        return null;
-      }
-      session.hasSession.value = true;
-      return refreshed;
-    });
-  }
-  if (!forceRefreshToken) {
-    return readLocal(session.jwtKey.value);
-  }
-  return withRefreshMutex(session.refreshKey.value, async () => {
-    const refreshToken = readLocal(session.refreshKey.value);
-    if (!refreshToken) {
-      persistTokens(session, null);
-      return null;
+  await requireBinding("signOut").signOut();
+}
+export function useConvexSignIn(fn, options = {}) {
+  useBinding("useConvexSignIn");
+  const ctx = useConvexContext();
+  const pending = ref(false);
+  const run = async (args) => {
+    const binding = ctx.convexAuth;
+    if (!binding) {
+      throw new Error("[use-convex] useConvexSignIn().run is browser-only.");
     }
+    pending.value = true;
     try {
-      const result = await callSignInWithRetry(convexUrl, { refreshToken });
-      const tokens = result.tokens ?? null;
-      if (!tokens) {
-        persistTokens(session, null);
-        return null;
+      const call = options.kind === "action" ? binding.signInApi.action : binding.signInApi.mutation;
+      const result = await call(fn, args);
+      if (result?.status === "complete" && result.tokens) {
+        await binding.setSession(result.tokens);
       }
-      persistTokens(session, tokens);
-      return tokens.token;
-    } catch {
-      persistTokens(session, null);
-      return null;
+      return result;
+    } catch (cause) {
+      return { status: "error", userError: { error: "OTHER_ERROR", cause } };
+    } finally {
+      pending.value = false;
     }
-  });
-}
-export function hasPendingOAuthCallback() {
-  if (!import.meta.client) {
-    return false;
-  }
-  const session = useAuthSession();
-  if (!session.convexUrl) {
-    return false;
-  }
-  const code = new URLSearchParams(window.location.search).get("code");
-  const verifier = readLocal(session.verifierKey.value);
-  return shouldConsumeOAuthCode({ code, verifier });
-}
-export async function consumeOAuthCodeFromUrl() {
-  if (!import.meta.client) {
-    return false;
-  }
-  const session = useAuthSession();
-  if (!session.convexUrl) {
-    return false;
-  }
-  const code = new URLSearchParams(window.location.search).get("code");
-  const verifier = readLocal(session.verifierKey.value);
-  if (!shouldConsumeOAuthCode({ code, verifier })) {
-    return false;
-  }
-  const url = new URL(window.location.href);
-  url.searchParams.delete("code");
-  window.history.replaceState({}, "", url.pathname + url.search + url.hash);
-  session.pending.value = true;
-  session.error.value = null;
-  session.isLoading.value = true;
-  try {
-    writeLocal(session.verifierKey.value, null);
-    const result = await callSignInWithRetry(session.convexUrl, {
-      params: { code },
-      verifier
-    });
-    await persistTokens(session, result.tokens ?? null);
-    return result.tokens != null;
-  } catch (cause) {
-    const message = cause instanceof Error ? cause.message : "OAuth callback failed";
-    session.error.value = message;
-    await persistTokens(session, null);
-    return false;
-  } finally {
-    session.pending.value = false;
-  }
-}
-export function useAuthProviderState() {
-  const session = useAuthSession();
-  return {
-    isLoading: computed(() => session.isLoading.value),
-    hasSession: computed(() => session.hasSession.value)
-  };
-}
-function useAuthSession() {
-  const config = useRuntimeConfig();
-  const convexConfig = config.public.convex;
-  const convexUrl = convexConfig?.url;
-  const httpOnly = isHttpOnlyAuth(convexConfig?.auth);
-  const isLoading = useState("convex-auth-loading", () => true);
-  const hasSession = useState("convex-auth-has-session", () => false);
-  const error = useState("convex-auth-error", () => null);
-  const pending = useState("convex-auth-pending", () => false);
-  const jwtKey = computed(
-    () => convexUrl ? storageKey(JWT_STORAGE_KEY, convexUrl) : JWT_STORAGE_KEY
-  );
-  const refreshKey = computed(
-    () => convexUrl ? storageKey(REFRESH_TOKEN_STORAGE_KEY, convexUrl) : REFRESH_TOKEN_STORAGE_KEY
-  );
-  const verifierKey = computed(
-    () => convexUrl ? storageKey(VERIFIER_STORAGE_KEY, convexUrl) : VERIFIER_STORAGE_KEY
-  );
-  return {
-    convexUrl,
-    httpOnly,
-    jwtKey,
-    refreshKey,
-    verifierKey,
-    isLoading,
-    hasSession,
-    error,
-    pending
   };
-}
-function setJwtCookie(token) {
-  const cookie = useAuthJwtCookie();
-  if (!cookie) {
-    return;
-  }
-  cookie.value = token;
-}
-function setPresentCookie(value) {
-  const cookie = useAuthPresentCookie();
-  if (!cookie) {
-    return;
-  }
-  cookie.value = value;
-}
-const AUTH_SESSION_PATH = "/api/convex/auth/session";
-async function fetchAuthSession() {
-  try {
-    return await $fetch(AUTH_SESSION_PATH, {
-      method: "GET"
-    });
-  } catch {
-    return { hasSession: false };
-  }
-}
-async function fetchAuthSessionToken() {
-  try {
-    return await $fetch(AUTH_SESSION_PATH, {
-      method: "POST",
-      body: { getToken: true }
-    });
-  } catch {
-    return { hasSession: false, token: null };
-  }
-}
-async function refreshAuthSession() {
-  try {
-    const result = await $fetch(AUTH_SESSION_PATH, {
-      method: "POST",
-      body: { refresh: true }
-    });
-    return result.token;
-  } catch {
-    return null;
-  }
-}
-async function clearAuthSession() {
-  try {
-    await $fetch(AUTH_SESSION_PATH, { method: "DELETE" });
-  } catch {
-  }
-  setPresentCookie(null);
-}
-async function writeHttpOnlySession(tokens) {
-  if (tokens === null) {
-    await clearAuthSession();
-    return;
-  }
-  await $fetch(AUTH_SESSION_PATH, {
-    method: "POST",
-    body: {
-      token: tokens.token,
-      refreshToken: tokens.refreshToken
-    }
-  });
-  setPresentCookie("1");
-}
-async function persistTokens(session, tokens) {
-  if (session.httpOnly) {
-    if (tokens === null) {
-      await writeHttpOnlySession(null);
-      writeLocal(session.jwtKey.value, null);
-      writeLocal(session.refreshKey.value, null);
-      session.hasSession.value = false;
-      session.isLoading.value = false;
-      return;
+  return { run, pending };
+}
+export function useOAuth() {
+  const binding = useBinding("useOAuth");
+  if (!binding) {
+    return { flowError: shallowRef(null) };
+  }
+  const value = binding.ambientValue(OAUTH_SETUP_ID, OAUTH_FLOW_ERROR_KEY);
+  return { flowError: computed(() => value.value ?? null) };
+}
+export function useOAuthSignIn(refs) {
+  const binding = useBinding("useOAuthSignIn");
+  const actions = binding?.ambientValue(OAUTH_SETUP_ID, OAUTH_ACTIONS_KEY);
+  const signIn = (async (options) => {
+    const current = actions?.value;
+    if (!current) {
+      throw new Error(
+        "[use-convex] OAuth is not registered. Include convexOAuth() in configureConvexAuth({ ambientSignIns })."
+      );
     }
-    session.hasSession.value = true;
-    session.isLoading.value = false;
-    await writeHttpOnlySession(tokens);
-    return;
-  }
-  if (tokens === null) {
-    writeLocal(session.jwtKey.value, null);
-    writeLocal(session.refreshKey.value, null);
-    setJwtCookie(null);
-    session.hasSession.value = false;
-    session.isLoading.value = false;
-    return;
-  }
-  writeLocal(session.jwtKey.value, tokens.token);
-  writeLocal(session.refreshKey.value, tokens.refreshToken);
-  session.hasSession.value = true;
-  session.isLoading.value = false;
-  nextTick(() => {
-    setJwtCookie(tokens.token);
+    return await current.signIn(refs, options);
   });
-}
-async function callSignIn(convexUrl, args) {
-  const http = new ConvexHttpClient(convexUrl);
-  return await http.action(authSignIn, args);
-}
-async function callSignInWithRetry(convexUrl, args) {
-  let lastError;
-  let retry = 0;
-  while (retry < RETRY_BACKOFF.length) {
-    try {
-      return await callSignIn(convexUrl, args);
-    } catch (e) {
-      lastError = e;
-      if (!isNetworkError(e)) {
-        break;
-      }
-      const wait = RETRY_BACKOFF[retry] + RETRY_JITTER * Math.random();
-      retry++;
-      await new Promise((resolve) => setTimeout(resolve, wait));
-    }
-  }
-  throw lastError;
-}
-function isNetworkError(error) {
-  if (error instanceof TypeError) {
-    return true;
-  }
-  if (error instanceof Error && /network|fetch|Failed to fetch/i.test(error.message)) {
-    return true;
-  }
-  return false;
+  return { signIn };
 }

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

@@ -4,8 +4,8 @@ import { type ComputedRef } from 'vue';
  * Current JWT for authenticated HTTP calls (React `@convex-dev/auth`
  * `useAuthToken` parity).
  *
- * Prefers `ConvexClient.getAuth()`, then the configured `fetchToken`
- * (Convex Auth / BYO). Returns `null` when signed out or unavailable.
+ * Uses the Convex Auth client token when Convex Auth is enabled; otherwise
+ * `ConvexClient.getAuth()`, then the configured BYO `fetchToken`. Returns `null` when signed out or unavailable.
  */
 export declare function useAuthToken(): ComputedRef<string | null>;
 /**

package/dist/runtime/composables/useAuthToken.js

@@ -9,6 +9,10 @@ export function useAuthToken() {
     return computed(() => null);
   }
   const auth = useConvexAuth();
+  const binding = ctx.convexAuth;
+  if (binding) {
+    return computed(() => binding.state.value.token);
+  }
   const refresh = async () => {
     if (!ctx.client) {
       token.value = null;

package/dist/runtime/composables/useConvexAuth.js

@@ -61,7 +61,7 @@ export function useConvexAuth(setup) {
       );
     };
     watch(
-      () => [toValue(setup.isLoading) ?? false, toValue(setup.isAuthenticated) ?? true],
+      [() => toValue(setup.isLoading) ?? false, () => toValue(setup.isAuthenticated) ?? true],
       syncFromProvider,
       { immediate: true }
     );

package/dist/runtime/composables/useConvexPaginatedQuery.js

@@ -1,3 +1,4 @@
+import { sessionKeyFromToken } from "../utils/authStorage.js";
 import { convexToJson, jsonToConvex } from "convex/values";
 import { useAsyncData, useRuntimeConfig } from "nuxt/app";
 import {
@@ -60,7 +61,11 @@ export async function useConvexPaginatedQuery(query, args = {}, options) {
       server,
       watch: [
         () => toValue(args),
-        () => options.token ?? ctx.ssrToken.value,
+        // Session identity (JWT iss + sub), not the raw token: Convex Auth
+        // rotates the access token every minute without changing session,
+        // but switching accounts must re-run the snapshot (`live: false`
+        // and BYO cookies included).
+        () => sessionKeyFromToken(options.token ?? ctx.ssrToken.value),
         () => requireAuth && ctx.auth.isAuthenticated.value && !!(options.token ?? ctx.ssrToken.value)
       ]
     }

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

@@ -5,10 +5,16 @@ import type { ConvexRef } from '../utils/functionReference.js';
 export type ConvexQueryRequestEntry<Query extends ConvexRef<'query'> = ConvexRef<'query'>> = {
     query: Query;
     args: FunctionArgs<Query>;
+    /**
+     * Skip this entry until Convex confirms auth (`isAuthenticated`).
+     * Overrides the top-level {@link UseConvexQueriesOptions.authenticated}
+     * flag when set.
+     */
+    authenticated?: boolean;
 };
 /**
  * Request map for {@link useConvexQueries}.
- * Values are `{ query, args }` or `'skip'`.
+ * Values are `{ query, args, authenticated? }` or `'skip'`.
  */
 export type ConvexQueriesRequest = Record<string, ConvexQueryRequestEntry | 'skip'>;
 export type ConvexQueriesResult<Request extends ConvexQueriesRequest> = {
@@ -17,17 +23,40 @@ export type ConvexQueriesResult<Request extends ConvexQueriesRequest> = {
         args: infer _Args;
     } ? Query extends ConvexRef<'query'> ? FunctionReturnType<Query> | undefined | Error : undefined : undefined;
 };
+export interface UseConvexQueriesOptions {
+    /**
+     * Skip every entry until Convex confirms auth (`isAuthenticated`).
+     * Prefer this over wrapping each value in `'skip'`. Per-entry
+     * `authenticated` overrides this when set.
+     *
+     * @default false
+     */
+    authenticated?: boolean;
+}
 /**
  * Subscribe to a dynamic map of Convex queries (React `useQueries` parity).
  *
- * Pass a reactive object whose values are `{ query, args }` or `'skip'`.
- * Returns a computed map of the same keys → result | `undefined` (loading) |
- * `Error`.
+ * Pass a reactive object whose values are `{ query, args, authenticated? }`
+ * or `'skip'`. Returns a computed map of the same keys → result |
+ * `undefined` (loading) | `Error`.
  *
  * Browser-only live subscriptions. During SSR every entry is `undefined`
  * (combine with `useConvexQuery` when you need SSR for known queries).
  *
- * Unchanged keys (same function name + args) keep their existing subscription
- * so deep reactive churn does not tear down WebSocket watches.
+ * Unchanged keys (same function name + args + auth-skip) keep their
+ * existing subscription so deep reactive churn does not tear down
+ * WebSocket watches.
+ *
+ * @example
+ * ```ts
+ * // Gate the whole map until Convex confirms auth
+ * const results = useConvexQueries(
+ *   () => ({
+ *     tasks: { query: api.tasks.list, args: {} },
+ *     files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
+ *   }),
+ *   { authenticated: true },
+ * )
+ * ```
  */
-export declare function useConvexQueries<Request extends ConvexQueriesRequest>(queries: MaybeRefOrGetter<Request>): ComputedRef<ConvexQueriesResult<Request>>;
+export declare function useConvexQueries<Request extends ConvexQueriesRequest>(queries: MaybeRefOrGetter<Request>, options?: UseConvexQueriesOptions): ComputedRef<ConvexQueriesResult<Request>>;

package/dist/runtime/composables/useConvexQueries.js

@@ -7,13 +7,18 @@ import {
   toValue,
   watch
 } from "vue";
+import { resolveAuthGatedArgs } from "../utils/authGate.js";
 import { useConvexContext } from "../utils/context.js";
-function subscriptionSignature(query, args) {
-  return `${getFunctionName(query)}:${JSON.stringify(convexToJson(args))}`;
+function subscriptionSignature(query, args, authSkipped) {
+  return `${getFunctionName(query)}:${JSON.stringify(convexToJson(args))}:authSkip=${authSkipped}`;
 }
-export function useConvexQueries(queries) {
+function entryRequiresAuth(entry, defaultAuthenticated) {
+  return entry.authenticated ?? defaultAuthenticated;
+}
+export function useConvexQueries(queries, options = {}) {
   const ctx = useConvexContext();
   const results = shallowRef({});
+  const defaultAuthenticated = options.authenticated ?? false;
   if (import.meta.server || !ctx.client) {
     return computed(() => results.value);
   }
@@ -29,9 +34,10 @@ export function useConvexQueries(queries) {
       results.value = rest;
     }
   };
-  const sync = (request) => {
+  const sync = (request, isAuthenticated) => {
     const nextKeys = new Set(Object.keys(request));
-    for (const key of unsubscribers.keys()) {
+    const known = /* @__PURE__ */ new Set([...unsubscribers.keys(), ...signatures.keys()]);
+    for (const key of known) {
       if (!nextKeys.has(key)) {
         dropKey(key);
       }
@@ -41,15 +47,33 @@ export function useConvexQueries(queries) {
         dropKey(key);
         continue;
       }
-      const { query, args } = entry;
-      const signature = subscriptionSignature(query, args);
-      if (signatures.get(key) === signature && unsubscribers.has(key)) {
+      const requireAuth = entryRequiresAuth(entry, defaultAuthenticated);
+      const effectiveArgs = resolveAuthGatedArgs(entry.args, {
+        authenticated: requireAuth,
+        isAuthenticated
+      });
+      const authSkipped = effectiveArgs === "skip";
+      const signature = subscriptionSignature(
+        entry.query,
+        entry.args,
+        authSkipped
+      );
+      if (signatures.get(key) === signature && (unsubscribers.has(key) || authSkipped)) {
         continue;
       }
       unsubscribers.get(key)?.();
+      unsubscribers.delete(key);
+      if (authSkipped) {
+        signatures.set(key, signature);
+        if (key in results.value) {
+          const { [key]: _, ...rest } = results.value;
+          results.value = rest;
+        }
+        continue;
+      }
       const unsubscribe = client.onUpdate(
-        query,
-        args,
+        entry.query,
+        effectiveArgs,
         (value) => {
           results.value = { ...results.value, [key]: value };
         },
@@ -65,9 +89,9 @@ export function useConvexQueries(queries) {
     }
   };
   watch(
-    () => toValue(queries),
-    (request) => {
-      sync(request);
+    () => [toValue(queries), ctx.auth.isAuthenticated.value],
+    ([request, isAuthenticated]) => {
+      sync(request, isAuthenticated);
     },
     { immediate: true, deep: true }
   );