use-convex 1.1.0 → 1.3.0

package/README.md

@@ -88,13 +88,20 @@ prewarmQuery(api.tasks.list, {})
 Browser-only live map (no SSR). Each value is `data | undefined` (loading) | `Error`. Combine with `useConvexQuery` when you need an SSR snapshot for known queries.
 
 ```ts
-const results = useConvexQueries(() => ({
-  tasks: { query: api.tasks.list, args: {} },
-  files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
-}))
+const results = useConvexQueries(
+  () => ({
+    tasks: { query: api.tasks.list, args: {} },
+    files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
+    // Per-entry gate (overrides the options bag when set):
+    // admin: { query: api.admin.stats, args: {}, authenticated: true },
+  }),
+  { authenticated: true }, // wait for Convex auth before any subscribe
+)
 // results.value.tasks
 ```
 
+`'skip'` still wins for missing ids / feature flags. Prefer `{ authenticated: true }` over wrapping every private entry yourself.
+
 ### Pagination
 
 ```ts
@@ -193,10 +200,34 @@ convex: {
   auth: {
     provider: 'convex-auth',
     // cookie defaults to 'convex_jwt'
+    // storageNamespace: 'myapp',       // optional; default = deployment URL
+    // storage: 'localStorage',         // or 'inMemory' (verifier uses a short-lived cookie)
+    // shouldHandleCode: true,          // set false to ignore ?code=
   },
 }
 ```
 
+For non-default OAuth / callback flows (JS router `replaceURL`, function `shouldHandleCode`, custom `TokenStorage`), call `configureConvexAuth` from a client plugin that runs before the auth plugin:
+
+```ts
+// plugins/convex-auth-options.client.ts
+export default defineNuxtPlugin({
+  name: 'convex-auth-options',
+  enforce: 'pre',
+  setup() {
+    const route = useRoute()
+    configureConvexAuth({
+      replaceURL: (url) => navigateTo(url, { replace: true }),
+      shouldHandleCode: () => route.path === '/auth/callback',
+      // storage: window.sessionStorage, // may be async; signIn waits before redirect
+      // storageNamespace: 'myapp',
+    })
+  },
+})
+```
+
+`storage: 'inMemory'` keeps JWTs in memory. The OAuth verifier is a short-lived cookie so the `?code=` callback still works after the IdP redirect. Custom storage may return Promises; `signIn` waits for writes before navigating.
+
 ```vue
 <script setup lang="ts">
 const { signIn, signOut } = useAuth()
@@ -318,7 +349,7 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
-`fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. `getConvexToken(event)` reads the cookie without throwing.
+`fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. Pass `{ adminToken }` (deploy key / admin key) for privileged server tooling — same as Next.js `fetchQuery` (user `token` is ignored when `adminToken` is set). `getConvexToken(event)` reads the cookie without throwing.
 
 ## Config
 
@@ -332,6 +363,9 @@ convex: {
     cookie: 'convex_jwt',
     httpOnly: false,
     presentCookie: 'convex_auth_present',
+    storage: 'localStorage', // or 'inMemory'
+    // storageNamespace: 'myapp',
+    // shouldHandleCode: true,
   },
 }
 ```

package/dist/module.d.mts

@@ -7,11 +7,13 @@ export { OptimisticUpdate, UseConvexMutationOptions } from '../dist/runtime/comp
 export { ConvexFileUploadExtraArgs, ConvexFileUploadMeta, UseConvexFileUploadOptions } from '../dist/runtime/composables/useConvexFileUpload.js';
 export { ConvexR2UploadApi, ConvexR2UploadProgress } from '../dist/runtime/composables/useConvexR2Upload.js';
 export { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, PaginationStatus, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js';
-export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry } from '../dist/runtime/composables/useConvexQueries.js';
+export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry, UseConvexQueriesOptions } from '../dist/runtime/composables/useConvexQueries.js';
 export { ConvexFetchOptions } from '../dist/runtime/server/fetch.js';
+export { ConvexRef } from '../dist/runtime/utils/functionReference.js';
 export { ConvexAuthContext, ConvexNuxtContext } from '../dist/runtime/utils/context.js';
 export { ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js';
 export { ConvexGate } from '../dist/runtime/composables/useConvexGate.js';
+export { ConvexAuthClientOptions, ConvexAuthStorageMode, ConvexAuthTokenStorage, configureConvexAuth } from '../dist/runtime/utils/authClientOptions.js';
 
 interface ModuleAuthOptions {
     /**
@@ -58,6 +60,24 @@ interface ModuleAuthOptions {
      * @default 'convex_auth_present'
      */
     presentCookie?: string;
+    /**
+     * Namespace for local token keys (React `storageNamespace` parity).
+     * Non-alphanumeric characters are stripped. Defaults to the deployment URL.
+     */
+    storageNamespace?: string;
+    /**
+     * Client token storage. `'localStorage'` (default) or `'inMemory'`.
+     * For a custom TokenStorage or `replaceURL` / function `shouldHandleCode`,
+     * call `configureConvexAuth` from a client plugin with `enforce: 'pre'`.
+     * Ignored when `httpOnly` is enabled.
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'inMemory';
+    /**
+     * When `false`, do not consume `?code=` OAuth callbacks.
+     * For a function gate, use `configureConvexAuth({ shouldHandleCode })`.
+     */
+    shouldHandleCode?: boolean;
 }
 interface ModuleOptions {
     /**

package/dist/module.mjs

@@ -3,6 +3,7 @@ import { defu } from 'defu';
 import { resolveAuthCookieName } from '../dist/runtime/utils/authStorage.js';
 import { suggestedCloudUrlFromMismatch } from '../dist/runtime/utils/convexDashboard.js';
 import { warnStaleLocalConvexUrl } from '../dist/runtime/utils/errors.js';
+export { configureConvexAuth } from '../dist/runtime/utils/authClientOptions.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -185,6 +186,10 @@ const module$1 = defineNuxtModule({
         {
           name: "signOut",
           from: resolver.resolve("./runtime/composables/useAuth")
+        },
+        {
+          name: "configureConvexAuth",
+          from: resolver.resolve("./runtime/utils/authClientOptions")
         }
       ] : []
     ]);

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

@@ -1,4 +1,5 @@
-import type { FunctionArgs, FunctionReference } from 'convex/server';
+import type { FunctionArgs } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Start a live subscription early so the first `useConvexQuery` / screen
  * paint can reuse warm client state (React `prewarmQuery` parity).
@@ -6,4 +7,4 @@ import type { FunctionArgs, FunctionReference } from 'convex/server';
  * Returns an unsubscribe function. When called during Vue `setup`, the
  * subscription is also cleaned up with the current effect scope.
  */
-export declare function prewarmQuery<Query extends FunctionReference<'query'>>(query: Query, args?: FunctionArgs<Query>): () => void;
+export declare function prewarmQuery<Query extends ConvexRef<'query'>>(query: Query, args?: FunctionArgs<Query>): () => void;

package/dist/runtime/composables/useAuth.js

@@ -6,16 +6,21 @@ 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 { getConvexAuthClientOptions, setConvexAuthModuleDefaults } from "../utils/authClientOptions.js";
 import {
   flattenSignInParams,
   isHttpOnlyAuth,
   JWT_STORAGE_KEY,
-  readLocal,
+  readLocalAsync,
+  readStored,
+  readVerifier,
+  readVerifierAsync,
   REFRESH_TOKEN_STORAGE_KEY,
   shouldConsumeOAuthCode,
   storageKey,
   VERIFIER_STORAGE_KEY,
-  writeLocal
+  writeLocalAsync,
+  writeVerifier
 } from "../utils/authStorage.js";
 import { tryUseConvexContext } from "../utils/context.js";
 import { parseOAuthRedirect } from "../utils/oauthRedirect.js";
@@ -61,8 +66,8 @@ export async function signIn(provider, params) {
   session.error.value = null;
   try {
     const flatParams = flattenSignInParams(params);
-    const existingVerifier = readLocal(session.verifierKey.value) ?? void 0;
-    writeLocal(session.verifierKey.value, null);
+    const existingVerifier = await readVerifierAsync(session.verifierKey.value) ?? void 0;
+    await writeVerifier(session.verifierKey.value, null);
     const result = await callSignIn(convexUrl, {
       provider,
       params: flatParams,
@@ -71,9 +76,9 @@ export async function signIn(provider, params) {
     if (result.redirect !== void 0) {
       const url = parseOAuthRedirect(result.redirect);
       if (result.verifier) {
-        writeLocal(session.verifierKey.value, result.verifier);
+        await writeVerifier(session.verifierKey.value, result.verifier);
       }
-      if (import.meta.client) {
+      if (inBrowser()) {
         window.location.href = url.toString();
       }
       return { signingIn: false, redirect: url };
@@ -98,7 +103,7 @@ export async function signOut() {
   session.error.value = null;
   try {
     if (convexUrl) {
-      const token = readLocal(session.jwtKey.value);
+      const token = await readLocalAsync(session.jwtKey.value);
       const http = new ConvexHttpClient(convexUrl);
       if (token) {
         http.setAuth(token);
@@ -140,12 +145,23 @@ export function hydrateAuthFromStorage() {
     });
     return;
   }
-  const token = readLocal(session.jwtKey.value);
-  session.hasSession.value = token !== null;
-  session.isLoading.value = false;
-  if (token) {
-    setJwtCookie(token);
+  const stored = readStored(session.jwtKey.value);
+  const applyToken = (token) => {
+    session.hasSession.value = token !== null;
+    session.isLoading.value = false;
+    if (token) {
+      setJwtCookie(token);
+    }
+  };
+  if (stored instanceof Promise) {
+    session.isLoading.value = true;
+    void stored.then(applyToken).catch(() => {
+      session.hasSession.value = false;
+      session.isLoading.value = false;
+    });
+    return;
   }
+  applyToken(stored);
 }
 export async function getAuthToken({
   forceRefreshToken
@@ -175,31 +191,37 @@ export async function getAuthToken({
     });
   }
   if (!forceRefreshToken) {
-    return readLocal(session.jwtKey.value);
+    return await readLocalAsync(session.jwtKey.value);
   }
   return withRefreshMutex(session.refreshKey.value, async () => {
-    const refreshToken = readLocal(session.refreshKey.value);
+    const refreshToken = await readLocalAsync(session.refreshKey.value);
     if (!refreshToken) {
-      persistTokens(session, null);
+      await persistTokens(session, null);
       return null;
     }
     try {
       const result = await callSignInWithRetry(convexUrl, { refreshToken });
       const tokens = result.tokens ?? null;
       if (!tokens) {
-        persistTokens(session, null);
+        await persistTokens(session, null);
         return null;
       }
-      persistTokens(session, tokens);
+      await persistTokens(session, tokens);
       return tokens.token;
     } catch {
-      persistTokens(session, null);
+      await persistTokens(session, null);
       return null;
     }
   });
 }
+function inBrowser() {
+  if (import.meta.client) {
+    return true;
+  }
+  return import.meta.client !== false && typeof window !== "undefined";
+}
 export function hasPendingOAuthCallback() {
-  if (!import.meta.client) {
+  if (!inBrowser()) {
     return false;
   }
   const session = useAuthSession();
@@ -207,11 +229,25 @@ export function hasPendingOAuthCallback() {
     return false;
   }
   const code = new URLSearchParams(window.location.search).get("code");
-  const verifier = readLocal(session.verifierKey.value);
-  return shouldConsumeOAuthCode({ code, verifier });
+  if (!code) {
+    return false;
+  }
+  const gate = getConvexAuthClientOptions().shouldHandleCode;
+  if (gate === false || typeof gate === "function" && !gate()) {
+    return false;
+  }
+  const verifier = readVerifier(session.verifierKey.value);
+  if (verifier instanceof Promise) {
+    return true;
+  }
+  return shouldConsumeOAuthCode({
+    code,
+    verifier,
+    shouldHandleCode: gate
+  });
 }
 export async function consumeOAuthCodeFromUrl() {
-  if (!import.meta.client) {
+  if (!inBrowser()) {
     return false;
   }
   const session = useAuthSession();
@@ -219,18 +255,36 @@ export async function consumeOAuthCodeFromUrl() {
     return false;
   }
   const code = new URLSearchParams(window.location.search).get("code");
-  const verifier = readLocal(session.verifierKey.value);
-  if (!shouldConsumeOAuthCode({ code, verifier })) {
+  const verifier = await readVerifierAsync(session.verifierKey.value);
+  const gate = getConvexAuthClientOptions().shouldHandleCode;
+  if (!shouldConsumeOAuthCode({
+    code,
+    verifier,
+    shouldHandleCode: gate
+  })) {
     return false;
   }
   const url = new URL(window.location.href);
   url.searchParams.delete("code");
-  window.history.replaceState({}, "", url.pathname + url.search + url.hash);
+  const relativeUrl = url.pathname + url.search + url.hash;
+  const replaceURL = getConvexAuthClientOptions().replaceURL;
+  try {
+    if (replaceURL) {
+      await replaceURL(relativeUrl);
+    } else {
+      window.history.replaceState({}, "", relativeUrl);
+    }
+  } catch (cause) {
+    session.error.value = cause instanceof Error ? cause.message : "OAuth callback failed";
+    session.isLoading.value = false;
+    session.pending.value = false;
+    return false;
+  }
   session.pending.value = true;
   session.error.value = null;
   session.isLoading.value = true;
   try {
-    writeLocal(session.verifierKey.value, null);
+    await writeVerifier(session.verifierKey.value, null);
     const result = await callSignInWithRetry(session.convexUrl, {
       params: { code },
       verifier
@@ -257,19 +311,28 @@ function useAuthSession() {
   const config = useRuntimeConfig();
   const convexConfig = config.public.convex;
   const convexUrl = convexConfig?.url;
-  const httpOnly = isHttpOnlyAuth(convexConfig?.auth);
+  const authConfig = convexConfig?.auth;
+  const httpOnly = isHttpOnlyAuth(authConfig);
+  if (authConfig?.provider === "convex-auth") {
+    setConvexAuthModuleDefaults({
+      storageNamespace: authConfig.storageNamespace,
+      storage: authConfig.storage,
+      shouldHandleCode: authConfig.shouldHandleCode
+    });
+  }
   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 namespace = getConvexAuthClientOptions().storageNamespace ?? authConfig?.storageNamespace ?? convexUrl;
   const jwtKey = computed(
-    () => convexUrl ? storageKey(JWT_STORAGE_KEY, convexUrl) : JWT_STORAGE_KEY
+    () => namespace ? storageKey(JWT_STORAGE_KEY, namespace) : JWT_STORAGE_KEY
   );
   const refreshKey = computed(
-    () => convexUrl ? storageKey(REFRESH_TOKEN_STORAGE_KEY, convexUrl) : REFRESH_TOKEN_STORAGE_KEY
+    () => namespace ? storageKey(REFRESH_TOKEN_STORAGE_KEY, namespace) : REFRESH_TOKEN_STORAGE_KEY
   );
   const verifierKey = computed(
-    () => convexUrl ? storageKey(VERIFIER_STORAGE_KEY, convexUrl) : VERIFIER_STORAGE_KEY
+    () => namespace ? storageKey(VERIFIER_STORAGE_KEY, namespace) : VERIFIER_STORAGE_KEY
   );
   return {
     convexUrl,
@@ -353,8 +416,8 @@ async function persistTokens(session, tokens) {
   if (session.httpOnly) {
     if (tokens === null) {
       await writeHttpOnlySession(null);
-      writeLocal(session.jwtKey.value, null);
-      writeLocal(session.refreshKey.value, null);
+      await writeLocalAsync(session.jwtKey.value, null);
+      await writeLocalAsync(session.refreshKey.value, null);
       session.hasSession.value = false;
       session.isLoading.value = false;
       return;
@@ -365,15 +428,15 @@ async function persistTokens(session, tokens) {
     return;
   }
   if (tokens === null) {
-    writeLocal(session.jwtKey.value, null);
-    writeLocal(session.refreshKey.value, null);
+    await writeLocalAsync(session.jwtKey.value, null);
+    await writeLocalAsync(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);
+  await writeLocalAsync(session.jwtKey.value, tokens.token);
+  await writeLocalAsync(session.refreshKey.value, tokens.refreshToken);
   session.hasSession.value = true;
   session.isLoading.value = false;
   nextTick(() => {

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

@@ -1,12 +1,13 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import { type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Browser action helper. Returns `{ run, error, pending }`.
  *
  * Safe to call during SSR setup — the ConvexClient is only touched when
  * `run()` runs in the browser.
  */
-export declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): {
+export declare function useConvexAction<Action extends ConvexRef<'action'>>(action: Action): {
     run: (args?: MaybeRefOrGetter<FunctionArgs<Action>>) => Promise<FunctionReturnType<Action>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

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

@@ -1,4 +1,5 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /** Built-in fields the composable always passes into `saveFile`. */
 export type ConvexFileUploadMeta = {
     storageId: string;
@@ -6,8 +7,8 @@ export type ConvexFileUploadMeta = {
     contentType: string;
     size: number;
 };
-export type ConvexFileUploadExtraArgs<SaveFile extends FunctionReference<'mutation'>> = Omit<FunctionArgs<SaveFile>, 'storageId' | 'name' | 'contentType' | 'size'>;
-export interface UseConvexFileUploadOptions<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>> {
+export type ConvexFileUploadExtraArgs<SaveFile extends ConvexRef<'mutation'>> = Omit<FunctionArgs<SaveFile>, 'storageId' | 'name' | 'contentType' | 'size'>;
+export interface UseConvexFileUploadOptions<GenerateUploadUrl extends ConvexRef<'mutation'>, SaveFile extends ConvexRef<'mutation'>> {
     /**
      * Mutation that returns a short-lived Convex upload URL
      * (`ctx.storage.generateUploadUrl()`). Must enforce auth itself.
@@ -35,7 +36,7 @@ export declare function postFileToUploadUrl(uploadUrl: string, file: File, onPro
  * in the browser. Your Convex mutations must enforce auth; never expose an
  * unauthenticated `generateUploadUrl`.
  */
-export declare function useConvexFileUpload<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>>(options: UseConvexFileUploadOptions<GenerateUploadUrl, SaveFile>): {
+export declare function useConvexFileUpload<GenerateUploadUrl extends ConvexRef<'mutation'>, SaveFile extends ConvexRef<'mutation'>>(options: UseConvexFileUploadOptions<GenerateUploadUrl, SaveFile>): {
     upload: (file: File, extra?: ConvexFileUploadExtraArgs<SaveFile> extends Record<string, never> ? undefined : ConvexFileUploadExtraArgs<SaveFile>) => Promise<FunctionReturnType<SaveFile>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

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

@@ -1,8 +1,9 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import type { OptimisticUpdate } from 'convex/browser';
 import { type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 export type { OptimisticUpdate };
-export interface UseConvexMutationOptions<Mutation extends FunctionReference<'mutation'>> {
+export interface UseConvexMutationOptions<Mutation extends ConvexRef<'mutation'>> {
     /**
      * Local query update applied while the mutation is in flight.
      * Passed through to `ConvexClient.mutation` → `BaseConvexClient`.
@@ -18,7 +19,7 @@ export interface UseConvexMutationOptions<Mutation extends FunctionReference<'mu
  * Pass `{ optimisticUpdate }` to apply temporary local query results while
  * the mutation is in flight (same contract as React `withOptimisticUpdate`).
  */
-export declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<Mutation>): {
+export declare function useConvexMutation<Mutation extends ConvexRef<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<Mutation>): {
     mutate: (args?: MaybeRefOrGetter<FunctionArgs<Mutation>>) => Promise<FunctionReturnType<Mutation>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

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

@@ -1,4 +1,4 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType, PaginationOptions, PaginationResult } from 'convex/server';
+import type { FunctionArgs, FunctionReference, FunctionReference_future, FunctionReturnType, PaginationOptions, PaginationResult } from 'convex/server';
 import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
 /**
  * A query usable with {@link useConvexPaginatedQuery}.
@@ -6,6 +6,8 @@ import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
  */
 export type PaginatedQueryReference = FunctionReference<'query', 'public', {
     paginationOpts: PaginationOptions;
+}, PaginationResult<unknown>> | FunctionReference_future<'query', 'public', {
+    paginationOpts: PaginationOptions;
 }, PaginationResult<unknown>>;
 export type PaginatedQueryArgs<Query extends PaginatedQueryReference> = Omit<FunctionArgs<Query>, 'paginationOpts'>;
 export type PaginatedQueryItem<Query extends PaginatedQueryReference> = FunctionReturnType<Query>['page'][number];

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

@@ -1,32 +1,62 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 /** One entry in a {@link useConvexQueries} request map. */
-export type ConvexQueryRequestEntry<Query extends FunctionReference<'query'> = FunctionReference<'query'>> = {
+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> = {
     [K in keyof Request]: Request[K] extends {
         query: infer Query;
         args: infer _Args;
-    } ? Query extends FunctionReference<'query'> ? FunctionReturnType<Query> | undefined | Error : undefined : undefined;
+    } ? 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 }
   );

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

@@ -1,6 +1,7 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
-export type ConvexQueryArgs<Query extends FunctionReference<'query'>> = FunctionArgs<Query> | 'skip';
+export type ConvexQueryArgs<Query extends ConvexRef<'query'>> = FunctionArgs<Query> | 'skip';
 export interface UseConvexQueryOptions {
     /**
      * Explicit Nuxt payload/cache key.
@@ -53,4 +54,4 @@ export interface UseConvexQueryReturn<T> {
  * 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>>>;
+export declare function useConvexQuery<Query extends ConvexRef<'query'>>(query: Query, args?: MaybeRefOrGetter<ConvexQueryArgs<Query>>, options?: UseConvexQueryOptions): Promise<UseConvexQueryReturn<FunctionReturnType<Query>>>;

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

@@ -1,11 +1,12 @@
-import type { FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Subset of `@convex-dev/r2` `clientApi()` exports needed for client uploads.
  * Pass `api.example` (or any module that re-exports these two mutations).
  */
 export type ConvexR2UploadApi = {
-    generateUploadUrl: FunctionReference<'mutation'>;
-    syncMetadata: FunctionReference<'mutation'>;
+    generateUploadUrl: ConvexRef<'mutation'>;
+    syncMetadata: ConvexRef<'mutation'>;
 };
 export type ConvexR2UploadProgress = {
     loaded: number;

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

@@ -7,6 +7,7 @@ import {
   hydrateAuthFromStorage,
   useAuthProviderState
 } from "./composables/useAuth.js";
+import { setConvexAuthModuleDefaults } from "./utils/authClientOptions.js";
 import { tryUseConvexContext } from "./utils/context.js";
 export default defineNuxtPlugin({
   name: "convex-nuxt-auth",
@@ -20,6 +21,14 @@ export default defineNuxtPlugin({
     if (!tryUseConvexContext()) {
       return;
     }
+    const auth = convexConfig.auth;
+    if (auth?.provider === "convex-auth") {
+      setConvexAuthModuleDefaults({
+        storageNamespace: auth.storageNamespace,
+        storage: auth.storage,
+        shouldHandleCode: auth.shouldHandleCode
+      });
+    }
     const pendingOAuth = hasPendingOAuthCallback();
     if (!pendingOAuth) {
       hydrateAuthFromStorage();
@@ -31,7 +40,7 @@ export default defineNuxtPlugin({
       isAuthenticated: hasSession
     });
     if (pendingOAuth) {
-      void consumeOAuthCodeFromUrl().then((ok) => {
+      void consumeOAuthCodeFromUrl().catch(() => false).then((ok) => {
         if (!ok) {
           hydrateAuthFromStorage();
         }

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

@@ -1,5 +1,6 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import type { H3Event } from 'h3';
+import type { ConvexRef } from '../utils/functionReference.js';
 export interface ConvexFetchOptions {
     /**
      * Deployment URL. Defaults to `NUXT_PUBLIC_CONVEX_URL` / runtimeConfig.
@@ -8,8 +9,15 @@ export interface ConvexFetchOptions {
     /**
      * JWT for this call. Prefer per-request tokens — never put JWTs in public config.
      * When omitted and `event` is passed, falls back to `convex.auth.cookie` if set.
+     * Ignored when {@link adminToken} is set (admin auth clears user JWT).
      */
     token?: string;
+    /**
+     * Deploy / admin key for privileged server tooling (Next.js `fetchQuery`
+     * parity). Calls `ConvexHttpClient.setAdminAuth`. Never put this in public
+     * runtime config — pass per request from a server secret.
+     */
+    adminToken?: string;
     /**
      * Nitro/H3 event. Used to resolve runtimeConfig and the optional auth cookie.
      */
@@ -30,12 +38,12 @@ export declare function resolveToken(options: ConvexFetchOptions): string | unde
  * })
  * ```
  */
-export declare function fetchQuery<Query extends FunctionReference<'query'>>(query: Query, args?: FunctionArgs<Query>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Query>>;
+export declare function fetchQuery<Query extends ConvexRef<'query'>>(query: Query, args?: FunctionArgs<Query>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Query>>;
 /**
  * One-shot mutation via ConvexHttpClient. Use in Nitro routes / server middleware.
  */
-export declare function fetchMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, args?: FunctionArgs<Mutation>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Mutation>>;
+export declare function fetchMutation<Mutation extends ConvexRef<'mutation'>>(mutation: Mutation, args?: FunctionArgs<Mutation>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Mutation>>;
 /**
  * One-shot action via ConvexHttpClient. Use in Nitro routes / server middleware.
  */
-export declare function fetchAction<Action extends FunctionReference<'action'>>(action: Action, args?: FunctionArgs<Action>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Action>>;
+export declare function fetchAction<Action extends ConvexRef<'action'>>(action: Action, args?: FunctionArgs<Action>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Action>>;

package/dist/runtime/server/fetch.js

@@ -32,9 +32,11 @@ export function resolveToken(options) {
   });
 }
 function setupClient(options = {}) {
+  const token = options.adminToken ? void 0 : resolveToken(options);
   return createHttpClient(resolveUrl(options), {
-    token: resolveToken(options),
-    skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck
+    ...token ? { token } : {},
+    ...options.adminToken ? { adminToken: options.adminToken } : {},
+    ...options.skipConvexDeploymentUrlCheck !== void 0 ? { skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck } : {}
   });
 }
 export async function fetchQuery(query, args, options) {

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

@@ -0,0 +1,61 @@
+/**
+ * Runtime Convex Auth client knobs (React `ConvexAuthProvider` parity).
+ *
+ * Serializable defaults also live on `convex.auth` module options
+ * (`storageNamespace`, `storage: 'localStorage' | 'inMemory'`,
+ * `shouldHandleCode: boolean`). Call {@link configureConvexAuth} from a
+ * client plugin (`enforce: 'pre'`) for `replaceURL`, function
+ * `shouldHandleCode`, or a custom {@link ConvexAuthTokenStorage}.
+ */
+export type ConvexAuthTokenStorage = {
+    getItem: (key: string) => string | undefined | null | Promise<string | undefined | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+};
+export type ConvexAuthStorageMode = 'localStorage' | 'inMemory';
+export type ConvexAuthClientOptions = {
+    /**
+     * When `false` (or a function returning false), ignore `?code=` OAuth
+     * callbacks. Defaults to handling the code when a verifier is stored.
+     */
+    shouldHandleCode?: boolean | (() => boolean);
+    /**
+     * Replace the URL after stripping `?code=` (JS routers). Defaults to
+     * `history.replaceState`.
+     */
+    replaceURL?: (relativeUrl: string) => void | Promise<void>;
+    /**
+     * Token storage. `'localStorage'` (default), `'inMemory'`, or a custom
+     * {@link ConvexAuthTokenStorage} (e.g. `sessionStorage`, Secure Store).
+     */
+    storage?: ConvexAuthStorageMode | ConvexAuthTokenStorage;
+    /**
+     * Namespace for storage keys (non-alphanumeric chars stripped). Defaults
+     * to the Convex deployment URL.
+     */
+    storageNamespace?: string;
+};
+/** Serializable subset safe for `runtimeConfig.public.convex.auth`. */
+export type ConvexAuthModuleClientOptions = {
+    shouldHandleCode?: boolean;
+    storage?: ConvexAuthStorageMode;
+    storageNamespace?: string;
+};
+/**
+ * Set runtime Convex Auth knobs. Merge is shallow — later calls override
+ * earlier keys. Prefer calling from a client plugin with `enforce: 'pre'`
+ * so options land before the auth plugin consumes OAuth codes.
+ */
+export declare function configureConvexAuth(options: ConvexAuthClientOptions): void;
+/** @internal */
+export declare function setConvexAuthModuleDefaults(options: ConvexAuthModuleClientOptions): void;
+/** Merged module defaults + {@link configureConvexAuth} overrides. */
+export declare function getConvexAuthClientOptions(): ConvexAuthClientOptions;
+/** @internal */
+export declare function resetConvexAuthClientOptionsForTests(): void;
+/** @internal */
+export declare function createInMemoryTokenStorage(): ConvexAuthTokenStorage;
+/** @internal */
+export declare function resetInMemoryTokenStorageForTests(): void;
+/** Resolve the active token storage from merged auth options. */
+export declare function resolveAuthTokenStorage(options?: ConvexAuthClientOptions): ConvexAuthTokenStorage;

package/dist/runtime/utils/authClientOptions.js

@@ -0,0 +1,73 @@
+let runtimeOverrides = {};
+let moduleDefaults = {};
+export function configureConvexAuth(options) {
+  runtimeOverrides = { ...runtimeOverrides, ...options };
+}
+export function setConvexAuthModuleDefaults(options) {
+  moduleDefaults = { ...options };
+}
+export function getConvexAuthClientOptions() {
+  return {
+    ...moduleDefaults,
+    ...runtimeOverrides
+  };
+}
+export function resetConvexAuthClientOptionsForTests() {
+  runtimeOverrides = {};
+  moduleDefaults = {};
+}
+const inMemory = /* @__PURE__ */ new Map();
+export function createInMemoryTokenStorage() {
+  return {
+    getItem: (key) => inMemory.get(key) ?? null,
+    setItem: (key, value) => {
+      inMemory.set(key, value);
+    },
+    removeItem: (key) => {
+      inMemory.delete(key);
+    }
+  };
+}
+export function resetInMemoryTokenStorageForTests() {
+  inMemory.clear();
+}
+const localStorageAdapter = {
+  getItem: (key) => {
+    if (typeof window === "undefined") {
+      return null;
+    }
+    try {
+      return window.localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  setItem: (key, value) => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    try {
+      window.localStorage.setItem(key, value);
+    } catch {
+    }
+  },
+  removeItem: (key) => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+    }
+  }
+};
+export function resolveAuthTokenStorage(options = getConvexAuthClientOptions()) {
+  const storage = options.storage;
+  if (storage === "inMemory") {
+    return createInMemoryTokenStorage();
+  }
+  if (storage && typeof storage === "object") {
+    return storage;
+  }
+  return localStorageAdapter;
+}

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

@@ -1,6 +1,7 @@
 /**
  * Convex Auth client storage helpers (mirrors @convex-dev/auth/react).
  */
+import { type ConvexAuthStorageMode, type ConvexAuthTokenStorage } from './authClientOptions.js';
 export declare const JWT_STORAGE_KEY = "__convexAuthJWT";
 export declare const REFRESH_TOKEN_STORAGE_KEY = "__convexAuthRefreshToken";
 export declare const VERIFIER_STORAGE_KEY = "__convexAuthOAuthVerifier";
@@ -24,9 +25,26 @@ export type ConvexAuthConfig = {
     httpOnly?: boolean;
     /** Readable presence cookie when `httpOnly` is set (UI only). */
     presentCookie?: string;
+    /**
+     * Namespace for local token keys (React `storageNamespace` parity).
+     * Non-alphanumeric characters are stripped. Defaults to the deployment URL.
+     */
+    storageNamespace?: string;
+    /**
+     * Client token storage mode. Use {@link configureConvexAuth} for a custom
+     * {@link ConvexAuthTokenStorage}. Ignored when `httpOnly` is enabled.
+     * @default 'localStorage'
+     */
+    storage?: ConvexAuthStorageMode;
+    /**
+     * When `false`, do not consume `?code=` OAuth callbacks. For a function
+     * gate, call {@link configureConvexAuth} with `shouldHandleCode`.
+     */
+    shouldHandleCode?: boolean;
 };
-export declare function storageNamespace(url: string): string;
-export declare function storageKey(base: string, url: string): string;
+export type { ConvexAuthTokenStorage, ConvexAuthStorageMode };
+export declare function storageNamespace(urlOrNamespace: string): string;
+export declare function storageKey(base: string, urlOrNamespace: string): string;
 /**
  * Flatten FormData (or pass through a plain record) the same way the React
  * Convex Auth client does before calling `auth:signIn`.
@@ -43,13 +61,36 @@ export declare function resolveAuthRefreshCookieName(auth?: ConvexAuthConfig): s
 export declare function isHttpOnlyAuth(auth?: ConvexAuthConfig): boolean;
 /** Empty / missing cookies are not a session. */
 export declare function cookieValueToSsrToken(value: string | null | undefined): string | undefined;
+/**
+ * Read a stored value.
+ * Sync storage returns `string | null`. Async {@link ConvexAuthTokenStorage}
+ * returns a Promise — callers that can wait should use {@link readLocalAsync}.
+ */
+export declare function readStored(key: string): string | null | Promise<string | null>;
+/** Sync read. Returns null when storage is async (use {@link readLocalAsync}). */
 export declare function readLocal(key: string): string | null;
+export declare function readLocalAsync(key: string): Promise<string | null>;
 export declare function writeLocal(key: string, value: string | null): void;
+export declare function writeLocalAsync(key: string, value: string | null): Promise<void>;
+/**
+ * `storage: 'inMemory'` cannot survive the IdP redirect, so the OAuth
+ * verifier is kept in a short-lived cookie (Next.js in-memory parity).
+ * JWTs stay in memory. Other storage modes keep the verifier with the tokens.
+ */
+export declare function readVerifier(key: string): string | null | Promise<string | null>;
+export declare function readVerifierAsync(key: string): Promise<string | null>;
+export declare function writeVerifier(key: string, value: string | null): Promise<void>;
+/** @internal */
+export declare function readBrowserCookie(name: string): string | null;
+/** @internal */
+export declare function writeBrowserCookie(name: string, value: string | null, maxAgeSeconds: number): void;
 /**
  * Whether the current URL's `?code=` should be treated as an OAuth callback.
- * Only true when we previously stored a verifier (we started the flow).
+ * Requires a stored verifier (we started the flow). Honors
+ * `shouldHandleCode` from module options / {@link configureConvexAuth}.
  */
 export declare function shouldConsumeOAuthCode(options: {
     code: string | null;
     verifier: string | null;
+    shouldHandleCode?: boolean | (() => boolean);
 }): boolean;

package/dist/runtime/utils/authStorage.js

@@ -1,3 +1,7 @@
+import {
+  getConvexAuthClientOptions,
+  resolveAuthTokenStorage
+} from "./authClientOptions.js";
 export const JWT_STORAGE_KEY = "__convexAuthJWT";
 export const REFRESH_TOKEN_STORAGE_KEY = "__convexAuthRefreshToken";
 export const VERIFIER_STORAGE_KEY = "__convexAuthOAuthVerifier";
@@ -6,11 +10,11 @@ export const DEFAULT_CONVEX_AUTH_COOKIE = "convex_jwt";
 export const DEFAULT_AUTH_PRESENT_COOKIE = "convex_auth_present";
 export const HTTPONLY_JWT_COOKIE = "__convexAuthJWT";
 export const HTTPONLY_REFRESH_COOKIE = "__convexAuthRefreshToken";
-export function storageNamespace(url) {
-  return url.replace(/[^a-z0-9]/gi, "");
+export function storageNamespace(urlOrNamespace) {
+  return urlOrNamespace.replace(/[^a-z0-9]/gi, "");
 }
-export function storageKey(base, url) {
-  return `${base}_${storageNamespace(url)}`;
+export function storageKey(base, urlOrNamespace) {
+  return `${base}_${storageNamespace(urlOrNamespace)}`;
 }
 export function flattenSignInParams(params) {
   if (params === void 0) {
@@ -57,29 +61,96 @@ export function isHttpOnlyAuth(auth) {
 export function cookieValueToSsrToken(value) {
   return value || void 0;
 }
-export function readLocal(key) {
-  if (typeof window === "undefined") {
-    return null;
+const OAUTH_VERIFIER_MAX_AGE_SECONDS = 60 * 10;
+function activeStorage() {
+  return resolveAuthTokenStorage(getConvexAuthClientOptions());
+}
+function authStorageIsInMemory() {
+  return getConvexAuthClientOptions().storage === "inMemory";
+}
+export function readStored(key) {
+  const value = activeStorage().getItem(key);
+  if (value instanceof Promise) {
+    return value.then((stored) => stored ?? null);
   }
-  try {
-    return window.localStorage.getItem(key);
-  } catch {
+  return value ?? null;
+}
+export function readLocal(key) {
+  const value = readStored(key);
+  if (value instanceof Promise) {
     return null;
   }
+  return value;
+}
+export async function readLocalAsync(key) {
+  return await readStored(key);
 }
 export function writeLocal(key, value) {
-  if (typeof window === "undefined") {
+  void writeLocalAsync(key, value);
+}
+export async function writeLocalAsync(key, value) {
+  const storage = activeStorage();
+  if (value === null) {
+    await storage.removeItem(key);
+  } else {
+    await storage.setItem(key, value);
+  }
+}
+export function readVerifier(key) {
+  if (authStorageIsInMemory()) {
+    return readBrowserCookie(key);
+  }
+  return readStored(key);
+}
+export async function readVerifierAsync(key) {
+  return await readVerifier(key);
+}
+export async function writeVerifier(key, value) {
+  if (authStorageIsInMemory()) {
+    writeBrowserCookie(key, value, OAUTH_VERIFIER_MAX_AGE_SECONDS);
     return;
   }
+  await writeLocalAsync(key, value);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function readBrowserCookie(name) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const match = document.cookie.match(new RegExp(`(?:^|; )${escapeRegExp(name)}=([^;]*)`));
+  const raw = match?.[1];
+  if (!raw) {
+    return null;
+  }
   try {
-    if (value === null) {
-      window.localStorage.removeItem(key);
-    } else {
-      window.localStorage.setItem(key, value);
-    }
+    return decodeURIComponent(raw);
   } catch {
+    return raw;
+  }
+}
+export function writeBrowserCookie(name, value, maxAgeSeconds) {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const secure = typeof location !== "undefined" && location.protocol === "https:" ? "; Secure" : "";
+  if (value === null) {
+    document.cookie = `${name}=; Max-Age=0; Path=/; SameSite=Lax${secure}`;
+    return;
   }
+  document.cookie = `${name}=${encodeURIComponent(value)}; Max-Age=${maxAgeSeconds}; Path=/; SameSite=Lax${secure}`;
 }
 export function shouldConsumeOAuthCode(options) {
-  return options.code !== null && options.verifier !== null;
+  if (options.code === null || options.verifier === null) {
+    return false;
+  }
+  const gate = options.shouldHandleCode ?? getConvexAuthClientOptions().shouldHandleCode;
+  if (gate === void 0) {
+    return true;
+  }
+  if (typeof gate === "function") {
+    return gate();
+  }
+  return gate;
 }

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

@@ -1,5 +1,6 @@
 import type { AuthTokenFetcher, ConvexClient, ConvexHttpClient } from 'convex/browser';
 import type { ComputedRef, InjectionKey, Ref } from 'vue';
+import type { CreateHttpClientOptions } from './http.js';
 export interface ConvexAuthContext {
     /**
      * Whether useConvexAuth({ fetchToken }) has been called.
@@ -37,9 +38,7 @@ export interface ConvexNuxtContext {
      * Create a fresh HttpClient for one-shot fetches (SSR / Nitro / refresh).
      * Prefer a new client per call — HttpClient is stateful.
      */
-    createHttpClient: (options?: {
-        token?: string;
-    }) => ConvexHttpClient;
+    createHttpClient: (options?: CreateHttpClientOptions) => ConvexHttpClient;
 }
 export declare const convexNuxtKey: InjectionKey<ConvexNuxtContext>;
 export declare function createAuthContext(): ConvexAuthContext;

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

@@ -0,0 +1,10 @@
+import type { FunctionReference, FunctionReference_future, FunctionType } from 'convex/server';
+/**
+ * Function reference accepted by use-convex client APIs.
+ *
+ * Convex 1.46+ introduced {@link FunctionReference_future} for stricter
+ * callback argument checking. Generated `api` refs remain plain
+ * {@link FunctionReference}; library surfaces accept either kind so callers
+ * can pass both (same contract as Convex React hooks).
+ */
+export type ConvexRef<Type extends FunctionType> = FunctionReference<Type> | FunctionReference_future<Type>;

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

@@ -1,6 +1,13 @@
 import { ConvexHttpClient } from 'convex/browser';
 export interface CreateHttpClientOptions {
     token?: string;
+    /**
+     * Deploy / admin key for privileged HttpClient calls (Next.js
+     * `fetchQuery(..., { adminToken })` parity). Uses `Authorization: Convex …`
+     * and clears any user JWT. Prefer per-request secrets — never put this in
+     * public runtime config.
+     */
+    adminToken?: string;
     skipConvexDeploymentUrlCheck?: boolean;
 }
 /**

package/dist/runtime/utils/http.js

@@ -2,9 +2,12 @@ import { ConvexHttpClient } from "convex/browser";
 export function createHttpClient(url, options = {}) {
   const client = new ConvexHttpClient(url, {
     skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck,
-    ...options.token ? { auth: options.token } : {}
+    ...options.token && !options.adminToken ? { auth: options.token } : {}
   });
-  if (options.token) {
+  if (options.adminToken) {
+    ;
+    client.setAdminAuth(options.adminToken);
+  } else if (options.token) {
     client.setAuth(options.token);
   }
   ;

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

@@ -1,8 +1,8 @@
-import type { FunctionReference } from 'convex/server';
+import type { ConvexRef } from './functionReference.js';
 /**
  * Stable Nuxt payload / useAsyncData key for a Convex query.
  *
  * `'skip'` means "don't fetch" — it must not change the key, otherwise
  * auth-gated queries lose the SSR payload on the client.
  */
-export declare function convexQueryKey(query: FunctionReference<'query'>, args: unknown, explicitKey?: string): string;
+export declare function convexQueryKey(query: ConvexRef<'query'>, args: unknown, explicitKey?: string): string;

package/dist/types.d.mts

@@ -18,16 +18,20 @@ export { type ConvexR2UploadApi, type ConvexR2UploadProgress } from '../dist/run
 
 export { type PaginatedQueryArgs, type PaginatedQueryItem, type PaginatedQueryReference, type PaginationStatus, type UseConvexPaginatedQueryOptions, type UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js'
 
-export { type ConvexQueriesRequest, type ConvexQueriesResult, type ConvexQueryRequestEntry } from '../dist/runtime/composables/useConvexQueries.js'
+export { type ConvexQueriesRequest, type ConvexQueriesResult, type ConvexQueryRequestEntry, type UseConvexQueriesOptions } from '../dist/runtime/composables/useConvexQueries.js'
 
 export { type ConvexFetchOptions } from '../dist/runtime/server/fetch.js'
 
+export { type ConvexRef } from '../dist/runtime/utils/functionReference.js'
+
 export { type ConvexAuthContext, type ConvexNuxtContext } from '../dist/runtime/utils/context.js'
 
 export { type ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js'
 
 export { type ConvexGate } from '../dist/runtime/composables/useConvexGate.js'
 
+export { type ConvexAuthClientOptions, type ConvexAuthStorageMode, type ConvexAuthTokenStorage, type configureConvexAuth } from '../dist/runtime/utils/authClientOptions.js'
+
 export { default } from './module.mjs'
 
 export { type ModuleAuthOptions, type ModuleOptions, type ModulePublicRuntimeConfig } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-convex",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "First-class Convex integration for Nuxt",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,7 @@
     "@nuxt/schema": "^4.0.0",
     "@nuxt/test-utils": "^3.23.0",
     "@types/node": "^26.5.0",
-    "convex": "^1.45.0",
+    "convex": "^1.46.0",
     "convex-test": "^0.0.56",
     "happy-dom": "^20.14.0",
     "nitropack": "^2.13.0",
@@ -63,7 +63,7 @@
     "vue-tsc": "^3.0.0"
   },
   "peerDependencies": {
-    "convex": "^1.21.0",
+    "convex": "^1.46.0",
     "nuxt": "^4.0.0",
     "vue": "^3.5.0"
   },