nuxt-convex-module 0.0.1 → 0.9.1

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

@@ -4,12 +4,12 @@ import { type ConvexAuthState, type IConvexVueClient } from '../../vue/auth/inde
  * Options for {@link provideConvexAuthFromAuth0} / `<ConvexProviderWithAuth0>`.
  */
 export interface ConvexProviderWithAuth0Options {
-    /** Convex client to authenticate. Defaults to the provided {@link useConvex} client. */
+    /** Convex client to authenticate. Defaults to the client `useConvex()` returns. */
     client?: IConvexVueClient;
 }
 /**
  * The composable form of {@link ConvexProviderWithAuth0} — provides a
- * {@link ConvexVueClient} authenticated with Auth0.
+ * {@link client!ConvexVueClient | ConvexVueClient} authenticated with Auth0.
  *
  * It must be called in an app wrapped by a configured Auth0 plugin from
  * `@auth0/auth0-vue`.
@@ -29,7 +29,7 @@ export interface ConvexProviderWithAuth0Options {
  */
 export declare function provideConvexAuthFromAuth0(options?: ConvexProviderWithAuth0Options): ConvexAuthState;
 /**
- * A wrapper Vue component which provides a {@link ConvexVueClient}
+ * A wrapper Vue component which provides a {@link client!ConvexVueClient | ConvexVueClient}
  * authenticated with Auth0 — the component form of
  * {@link provideConvexAuthFromAuth0}. Renders its default slot once Convex
  * auth is wired.

package/dist/runtime/better-auth/nuxt/middleware.d.ts

@@ -12,11 +12,5 @@
  * </script>
  * ```
  */
-interface GuardedRoute {
-    path: string;
-    fullPath: string;
-}
-/** Exported for unit tests — `import.meta.server` is compile-time. @internal */
-export declare function serverGuard(to: GuardedRoute, loginPath: string): Promise<string | false | void | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | import("vue-router").NavigationFailure>;
 declare const _default: import("nuxt/app").RouteMiddleware;
 export default _default;

package/dist/runtime/better-auth/nuxt/middleware.js

@@ -1,15 +1,14 @@
 import { defineNuxtRouteMiddleware, navigateTo, useNuxtApp, useRequestEvent, useRuntimeConfig } from "#app";
 import { watch } from "vue";
-import { useAuth } from "../vue/use-auth.js";
+import { useBetterAuth } from "../vue/use-better-auth.js";
 import { convexAuth } from "./server.js";
 function loginTarget(to, loginPath) {
   return { path: loginPath, query: { redirect: to.fullPath } };
 }
 export async function serverGuard(to, loginPath) {
-  const event = useRequestEvent();
-  if (!event) return;
   const nuxtApp = useNuxtApp();
-  const authed = await convexAuth(event).isAuthenticated();
+  const event = useRequestEvent();
+  const authed = event ? await convexAuth(event).isAuthenticated() : false;
   if (!authed && to.path !== loginPath) {
     return nuxtApp.runWithContext(() => navigateTo(loginTarget(to, loginPath)));
   }
@@ -33,7 +32,7 @@ export default defineNuxtRouteMiddleware(async (to) => {
   if (import.meta.server) {
     return serverGuard(to, loginPath);
   }
-  const { session } = useAuth();
+  const { session } = useBetterAuth();
   if (session.value.isPending) {
     await waitForSession(() => session.value.isPending);
   }

package/dist/runtime/better-auth/nuxt/proxy.d.ts

@@ -1,6 +1,22 @@
 /**
- * Proxy all /api/auth/* requests to the Convex site URL.
- * This keeps auth cookies on the same origin (no CORS issues).
+ * Proxy all `${convex.authRoute}/**` requests (default `/api/auth/**`) to the
+ * Convex site URL. This keeps auth cookies on the same origin (no CORS issues).
+ *
+ * The site URL is `convexAuth`'s to resolve: the private `runtimeConfig.convex.siteUrl`,
+ * then the public one, then the environment — so a container built without it and
+ * started with `NUXT_PUBLIC_CONVEX_SITE_URL` works. Reading only the private key here
+ * used to fail every auth request in exactly that deployment.
+ *
+ * The method list matches the nuxt-security route rule the module registers on this
+ * route; enforcing it here too keeps the proxy closed to `PUT`/`DELETE` probes when
+ * nuxt-security is not installed.
+ *
+ * The path check: h3 routes the request's raw path, and the handler forwards the
+ * URL-normalised one. `/api/auth/../../x` (or its `%2e%2e` spelling) matches this
+ * route and normalises to `/x`, which the proxy would send to the site origin —
+ * any HTTP action on the deployment, reached through the app's origin with the
+ * app's cookies attached. Next.js normalises before routing, so upstream's
+ * handler never sees such a path; Nitro does not, so it is refused here.
  */
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response>>;
 export default _default;

package/dist/runtime/better-auth/nuxt/proxy.js

@@ -1,11 +1,11 @@
-import { defineEventHandler } from "h3";
-import { useRuntimeConfig } from "#imports";
+import { assertMethod, createError, defineEventHandler, toWebRequest } from "h3";
 import { convexAuth } from "./server.js";
 export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig();
-  const siteUrl = config.convex.siteUrl;
-  if (!siteUrl) {
-    throw new Error("[nuxt-convex-module] NUXT_PUBLIC_CONVEX_SITE_URL is not configured. Auth proxy cannot forward requests.");
+  assertMethod(event, ["GET", "HEAD", "POST", "OPTIONS"]);
+  const routed = event.path.split("?")[0];
+  const forwarded = new URL(toWebRequest(event).url).pathname;
+  if (forwarded !== routed) {
+    throw createError({ statusCode: 400, statusMessage: "Bad Request" });
   }
-  return convexAuth(event, { convexSiteUrl: siteUrl }).handler();
+  return convexAuth(event).handler();
 });

package/dist/runtime/better-auth/nuxt/server.d.ts

@@ -1,11 +1,9 @@
 /**
  * Server-side Better Auth + Convex integration for Nuxt.
  *
- * Provides {@link convexAuth} for Nuxt server handlers.
- *
- * It accepts the H3
- * {@link H3Event} that is available in every Nuxt server route, API handler
- * and server middleware.
+ * Provides {@link convexAuth} for Nuxt server handlers: it takes the H3
+ * `H3Event` every Nuxt server route, API handler and server middleware
+ * receives, and returns a request-scoped, authenticated Convex client.
  *
  * @module better-auth/server
  */
@@ -30,7 +28,9 @@ export type ConvexAuthOptions = GetTokenOptions & {
      */
     convexUrl?: string;
     /**
-     * Override the Convex site URL. Defaults to `NUXT_PUBLIC_CONVEX_SITE_URL`.
+     * Override the Convex site URL. Defaults to `runtimeConfig.convex.siteUrl`,
+     * then `runtimeConfig.public.convex.siteUrl`, then the
+     * `NUXT_PUBLIC_CONVEX_SITE_URL` process variable.
      */
     convexSiteUrl?: string;
 };

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

@@ -43,6 +43,7 @@ type EmptyObject = Record<string, never>;
  * @param props.isAuthError - Function to check if the error is auth related.
  *
  * @public
+ * @experimental May change in a minor release — see STABILITY.md.
  */
 export declare const AuthBoundary: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /**

package/dist/runtime/better-auth/vue/cross-domain.js

@@ -21,10 +21,15 @@ export async function consumeCrossDomainOneTimeToken(options = {}) {
     }
     if (options.callbackRoute && normalizePathname(url.pathname) !== normalizePathname(options.callbackRoute)) {
       console.warn(
-        `[nuxt-convex-module] ignoring cross-domain one-time token on "${url.pathname}" \u2014 consumption is restricted to "${options.callbackRoute}" (convex.betterAuth.crossDomainCallbackRoute).`
+        `[nuxt-convex-module] Ignoring cross-domain one-time token on "${url.pathname}" \u2014 consumption is restricted to "${options.callbackRoute}" (convex.betterAuth.crossDomainCallbackRoute).`
       );
       return;
     }
+    if (import.meta.dev && !options.callbackRoute) {
+      console.warn(
+        `[nuxt-convex-module] Exchanged a cross-domain one-time token on "${url.pathname}" with no \`convex.betterAuth.crossDomainCallbackRoute\` set \u2014 any page can complete sign-in. Restrict it to your callback route.`
+      );
+    }
     try {
       const result = await authClientWithCrossDomain.crossDomain.oneTimeToken.verify({
         token
@@ -41,7 +46,7 @@ export async function consumeCrossDomainOneTimeToken(options = {}) {
         await authClientWithCrossDomain.updateSession();
       }
     } catch (error) {
-      console.warn("[nuxt-convex-module] failed to consume cross-domain one-time token", error);
+      console.warn("[nuxt-convex-module] Failed to consume cross-domain one-time token:", error);
     }
   }
 }

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

@@ -2,7 +2,7 @@ import type { FunctionReference } from 'convex/server';
 import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
 import { type Preloaded } from '../../vue/hydration.js';
 /**
- * Auth-aware version of {@link usePreloadedQuery} for payloads returned by
+ * Auth-aware version of {@link client!usePreloadedQuery | usePreloadedQuery} for payloads returned by
  * `convexAuth(event).preloadAuthQuery(...)`.
  *
  * A Vue/Nuxt port of `@convex-dev/better-auth`'s `usePreloadedAuthQuery`

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

@@ -4,7 +4,7 @@
  *
  * @module better-auth/client
  */
-export { useAuth, type UseAuthService, type AuthSession, type AuthUser } from './use-auth.js';
+export { useBetterAuth, type UseBetterAuthReturn, type BetterAuthSession, type BetterAuthUser } from './use-better-auth.js';
 export { authClient, type AuthClient } from '#convex/auth-client';
 export { usePreloadedAuthQuery } from './hydration.js';
 export { consumeCrossDomainOneTimeToken, type ConsumeCrossDomainOneTimeTokenOptions } from './cross-domain.js';

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

@@ -1,4 +1,4 @@
-export { useAuth } from "./use-auth.js";
+export { useBetterAuth } from "./use-better-auth.js";
 export { authClient } from "#convex/auth-client";
 export { usePreloadedAuthQuery } from "./hydration.js";
 export { consumeCrossDomainOneTimeToken } from "./cross-domain.js";

package/dist/runtime/better-auth/vue/plugin.client.d.ts

@@ -1,6 +1,2 @@
-import { ConvexVueClient } from '../../vue/client.js';
-type ConvexNuxtInjection = {
-    convex?: ConvexVueClient;
-};
-declare const _default: import("nuxt/app").Plugin<ConvexNuxtInjection> & import("nuxt/app").ObjectPlugin<ConvexNuxtInjection>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/better-auth/vue/plugin.client.js

@@ -1,32 +1,28 @@
 import { defineNuxtPlugin, useRuntimeConfig, useState } from "#app";
 import { ConvexVueClient, ConvexClientKey } from "../../vue/client.js";
 import { ConvexAuthStateKey, createScopedConvexAuthState } from "../../vue/auth/index.js";
-import { useAuth } from "./use-auth.js";
+import { CONVEX_INITIAL_TOKEN_KEY } from "../../nuxt/config.js";
+import { useBetterAuth } from "./use-better-auth.js";
 import { consumeCrossDomainOneTimeToken } from "./cross-domain.js";
 export default defineNuxtPlugin({
   name: "nuxt-convex-module:better-auth:client",
   async setup(nuxtApp) {
     const { url, crossDomainCallbackRoute } = useRuntimeConfig().public.convex;
     if (!url) {
-      console.warn("[nuxt-convex-module] No Convex URL configured for client plugin.");
-      return { provide: {} };
+      console.warn("[nuxt-convex-module] No Convex deployment URL configured \u2014 client and auth not created. Set NUXT_PUBLIC_CONVEX_URL or `convex.url` in nuxt.config.");
+      return;
     }
     const client = new ConvexVueClient(url);
     nuxtApp.vueApp.provide(ConvexClientKey, client);
     await consumeCrossDomainOneTimeToken({
       callbackRoute: crossDomainCallbackRoute || void 0
     });
-    const initialToken = useState("convex:initialToken", () => null);
+    const initialToken = useState(CONVEX_INITIAL_TOKEN_KEY, () => null);
     const { state, scope } = createScopedConvexAuthState({
       client,
-      useAuth: () => useAuth(initialToken.value)
+      useAuth: () => useBetterAuth(initialToken.value)
     });
     nuxtApp.vueApp.provide(ConvexAuthStateKey, state);
     void scope;
-    return {
-      provide: {
-        convex: client
-      }
-    };
   }
 });

package/dist/runtime/better-auth/vue/plugin.server.d.ts

@@ -1,24 +1,13 @@
-import { useState, useRequestEvent } from '#app';
-import { ConvexVueClient } from '../../vue/client.js';
-type ConvexNuxtInjection = {
-    convex?: ConvexVueClient;
-};
-/**
- * Prefetch the Convex JWT for SSR and stash it in `initialToken`.
- *
- * Exported for unit testing.
- */
-export declare function prefetchAuthToken(event: ReturnType<typeof useRequestEvent>, initialToken: ReturnType<typeof useState<string | null>>): Promise<void>;
 /**
  * Server-side Better Auth bootstrap.
  *
  * Mirrors the Next.js parity layer that calls `getToken()` from the root
  * server layout and passes it as `initialToken` to `ConvexBetterAuthProvider`.
  *
- * The token is stashed into a Nuxt `useState('convex:initialToken')` so the
- * client plugin can hand it to `useAuth(initialToken)` before the first
- * Convex `setAuth` call — avoiding an extra Better Auth round-trip on first
- * paint.
+ * The token is stashed into a Nuxt `useState` (`CONVEX_INITIAL_TOKEN_KEY`) so
+ * the client plugin can hand it to `useBetterAuth(initialToken)` before the
+ * first Convex `setAuth` call — avoiding an extra Better Auth round-trip on
+ * first paint.
  */
-declare const _default: import("nuxt/app").Plugin<ConvexNuxtInjection> & import("nuxt/app").ObjectPlugin<ConvexNuxtInjection>;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/better-auth/vue/plugin.server.js

@@ -2,11 +2,9 @@ import { computed } from "vue";
 import { setResponseHeader } from "h3";
 import { defineNuxtPlugin, useRuntimeConfig, useState, useRequestEvent } from "#app";
 import { ConvexVueClient, ConvexClientKey } from "../../vue/client.js";
+import { CONVEX_INITIAL_TOKEN_KEY } from "../../nuxt/config.js";
 import { convexAuth } from "../nuxt/server.js";
 import { ConvexAuthStateKey } from "../../vue/auth/index.js";
-function buildProvide(ssrClient) {
-  return ssrClient ? { provide: { convex: ssrClient } } : { provide: {} };
-}
 export async function prefetchAuthToken(event, initialToken) {
   try {
     const token = await convexAuth(event).getToken();
@@ -21,7 +19,7 @@ export async function prefetchAuthToken(event, initialToken) {
 export default defineNuxtPlugin({
   name: "nuxt-convex-module:better-auth:server",
   async setup(nuxtApp) {
-    const initialToken = useState("convex:initialToken", () => null);
+    const initialToken = useState(CONVEX_INITIAL_TOKEN_KEY, () => null);
     const url = useRuntimeConfig().public.convex.url;
     const ssrClient = url ? new ConvexVueClient(url) : void 0;
     if (ssrClient) {
@@ -34,9 +32,8 @@ export default defineNuxtPlugin({
     };
     nuxtApp.vueApp.provide(ConvexAuthStateKey, ssrAuthState);
     const event = useRequestEvent();
-    if (event) {
+    if (event && !import.meta.prerender) {
       await prefetchAuthToken(event, initialToken);
     }
-    return buildProvide(ssrClient);
   }
 });

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

@@ -1,15 +1,3 @@
-/**
- * Safe handling of the `?redirect=` destination the `auth` route middleware
- * attaches when it sends an unauthenticated visitor to the login page.
- *
- * The middleware only ever writes a router path there, but the query is part
- * of a URL anyone can craft: a link to `/login?redirect=https://evil.example`
- * turns a login page that navigates to `route.query.redirect` verbatim into an
- * open redirect — a phishing primitive that borrows the app's own domain, and
- * one that carries whatever the app appends to the destination.
- *
- * @module better-auth/redirect
- */
 /**
  * Validate a post-sign-in redirect destination, returning `fallback` unless it
  * is a same-origin path.
@@ -21,10 +9,10 @@
  * ```vue
  * <script setup lang="ts">
  * const route = useRoute()
- * const { signIn } = useAuth()
+ * const { client } = useBetterAuth()
  *
  * async function onSubmit() {
- *   await signIn.email({ email, password })
+ *   await client.signIn.email({ email, password })
  *   // '/dashboard' survives; 'https://evil.example' becomes '/'.
  *   await navigateTo(resolveAuthRedirect(route.query.redirect))
  * }

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

@@ -27,7 +27,9 @@ declare const useClientSession: () => Readonly<import("vue").Ref<{
     readonly isPending: boolean;
     readonly isRefetching: boolean;
     readonly error: import("better-auth/client").BetterFetchError | null;
-    readonly refetch: (queryParams?: {
+    readonly refetch: (queryParams
+    /** The Better Auth client from `#convex/auth-client` — sign-in, sign-out and every plugin flow live here. */
+    ?: {
         query?: import("better-auth").SessionQueryParams;
     } | undefined) => Promise<void>;
 }, {
@@ -56,37 +58,55 @@ declare const useClientSession: () => Readonly<import("vue").Ref<{
     readonly isPending: boolean;
     readonly isRefetching: boolean;
     readonly error: import("better-auth/client").BetterFetchError | null;
-    readonly refetch: (queryParams?: {
+    readonly refetch: (queryParams
+    /** The Better Auth client from `#convex/auth-client` — sign-in, sign-out and every plugin flow live here. */
+    ?: {
         query?: import("better-auth").SessionQueryParams;
     } | undefined) => Promise<void>;
 }>>;
-export type AuthSession = ReturnType<typeof useClientSession>;
+export type BetterAuthSession = ReturnType<typeof useClientSession>;
 /** The signed-in user (loose — exact fields depend on your auth schema). */
-export type AuthUser = {
+export type BetterAuthUser = {
     id: string;
     email: string;
     name: string;
 } & Record<string, unknown>;
-export interface UseAuthService {
+/** What `useBetterAuth()` returns. */
+export interface UseBetterAuthReturn {
+    /** `true` until the session is known and no prefetched token covers the gap. */
     isLoading: ComputedRef<boolean>;
+    /** `true` when Better Auth reports a session, or a token is cached while it reloads. */
     isAuthenticated: ComputedRef<boolean>;
+    /** Convex's token fetcher: the Better Auth JWT for the current session, or `null`. */
     fetchAccessToken: AuthTokenFetcher;
+    /** The Better Auth client from `#convex/auth-client` — sign-in, sign-out and every plugin flow live here. */
     client: AuthClient;
-    session: AuthSession;
+    /** Better Auth's own `useSession()` ref: `{ data, isPending, error }`. */
+    session: BetterAuthSession;
     /** The current user, or `null` when signed out / still loading. */
-    user: ComputedRef<AuthUser | null>;
+    user: ComputedRef<BetterAuthUser | null>;
+    /** The session id (or user id); changes when the signed-in identity changes. */
     authVersion: ComputedRef<string | null>;
 }
 /**
- * Unified Better Auth service for the Vue/Nuxt runtime.
+ * The Better Auth service for the Vue/Nuxt runtime.
  *
  * Returns the full Better Auth client, the reactive session wrapper, and the
  * Convex-compatible auth state used by the packaged auth plugin.
  *
  * @param initialToken - Optional preloaded token, used once per app lifetime
  *   to avoid a round-trip on initial load (e.g. from SSR).
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * const { user, client, isAuthenticated } = useBetterAuth()
+ *
+ * const signOut = () => client.signOut()
+ * </script>
+ * ```
+ *
+ * @public
  */
-export declare function useAuth(initialToken?: string | null): UseAuthService;
-/** Reset module-level token cache — intended for tests only. */
-export declare function __resetUseAuthForTests(): void;
+export declare function useBetterAuth(initialToken?: string | null): UseBetterAuthReturn;
 export {};

package/dist/runtime/better-auth/vue/{use-auth.js → use-better-auth.js}

@@ -7,7 +7,7 @@ let pendingTokenVersion = null;
 let initialTokenUsed = false;
 const PENDING_AUTH_VERSION = "__pending__";
 const useClientSession = () => authClient.useSession();
-export function useAuth(initialToken) {
+export function useBetterAuth(initialToken) {
   if (!initialTokenUsed && initialToken) {
     cachedToken.value = initialToken;
     cachedTokenVersion = PENDING_AUTH_VERSION;
@@ -74,7 +74,7 @@ export function useAuth(initialToken) {
     authVersion
   };
 }
-export function __resetUseAuthForTests() {
+export function __resetUseBetterAuthForTests() {
   cachedToken.value = null;
   cachedTokenVersion = null;
   pendingToken = null;

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

@@ -16,15 +16,15 @@ export type UseAuth = () => {
  * Options for {@link provideConvexAuthFromClerk} / `<ConvexProviderWithClerk>`.
  */
 export interface ConvexProviderWithClerkOptions {
-    /** Convex client to authenticate. Defaults to the provided {@link useConvex} client. */
+    /** Convex client to authenticate. Defaults to the client `useConvex()` returns. */
     client?: IConvexVueClient;
     /** Clerk's `useAuth` composable. Defaults to `useAuth` from `@clerk/vue`. */
     useAuth?: UseAuth;
 }
 /**
- * A composable which provides a {@link ConvexVueClient}
+ * A composable which provides a {@link client!ConvexVueClient | ConvexVueClient}
  * authenticated with Clerk, exposing the reactive auth state to descendants
- * via {@link useConvexAuth} — the Vue translation of wrapping the app in
+ * via {@link client!useConvexAuth | useConvexAuth} — the Vue translation of wrapping the app in
  * `convex/react-clerk`'s `<ConvexProviderWithClerk>`.
  *
  * Call it in a top-level component's `setup`. The app must be wrapped by a
@@ -47,7 +47,7 @@ export interface ConvexProviderWithClerkOptions {
  */
 export declare function provideConvexAuthFromClerk(options?: ConvexProviderWithClerkOptions): ConvexAuthState;
 /**
- * A wrapper Vue component which provides a {@link ConvexVueClient}
+ * A wrapper Vue component which provides a {@link client!ConvexVueClient | ConvexVueClient}
  * authenticated with Clerk — the component form of
  * {@link provideConvexAuthFromClerk}, kept as a drop-in parity port of
  * `convex/react-clerk`'s `<ConvexProviderWithClerk>`. Renders its default

package/dist/runtime/nuxt/app.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Composables that need the Nuxt app context (`#app`) — the half of the
+ * package that runs in a Nuxt app but not in plain Vue.
+ *
+ * This module contains {@link useAsyncQuery} and its paginated form
+ * {@link useAsyncPaginatedQuery}: server-rendered Convex data that upgrades
+ * to a live subscription after hydration.
+ *
+ * ## Usage
+ *
+ * **Default — auto-imported.** In any page, component or composable, call it
+ * with no import; its types are auto-imported too:
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * import { api } from '#convex/api'
+ *
+ * const { data: messages, status } = useAsyncQuery(api.messages.list, {})
+ * // `AsyncQueryStatus`, `AsyncQueryReturn`, … resolve without an import as well:
+ * const label = (s: AsyncQueryStatus) => s === 'pending' ? 'Loading…' : ''
+ * </script>
+ * ```
+ *
+ * **Explicit import — this subpath.** For a project that turns auto-imports
+ * off, a file outside the app's auto-import scope, or an editor that wants
+ * the import spelled out:
+ *
+ * ```ts
+ * import { useAsyncQuery } from 'nuxt-convex-module/app'
+ * ```
+ *
+ * **Types.** From `#imports` (Nuxt's auto-import barrel) or from this subpath,
+ * whichever your file already uses:
+ *
+ * ```ts
+ * import type { AsyncQueryReturn } from '#imports'
+ * import type { AsyncQueryReturn } from 'nuxt-convex-module/app'
+ *
+ * const messages: AsyncQueryReturn<Doc<'messages'>[]> = useAsyncQuery(api.messages.list, {})
+ * ```
+ *
+ * Before 1.0 the composable was auto-imported but reachable from no subpath,
+ * so neither the explicit form nor the types could be written at all.
+ *
+ * @module app
+ */
+export { useAsyncQuery, useConvexAsyncQuery, type AsyncQueryData, type AsyncQueryOptions, type AsyncQueryReturn, type AsyncQueryStatus, } from './composables/use-async-query.js';
+export { useAsyncPaginatedQuery, useConvexAsyncPaginatedQuery, type AsyncPaginatedQueryData, type AsyncPaginatedQueryOptions, type AsyncPaginatedQueryReturn, } from './composables/use-async-paginated-query.js';

package/dist/runtime/nuxt/app.js

@@ -0,0 +1,8 @@
+export {
+  useAsyncQuery,
+  useConvexAsyncQuery
+} from "./composables/use-async-query.js";
+export {
+  useAsyncPaginatedQuery,
+  useConvexAsyncPaginatedQuery
+} from "./composables/use-async-paginated-query.js";

package/dist/runtime/nuxt/composables/use-async-paginated-query.d.ts

@@ -0,0 +1,88 @@
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import { type PaginatedQueryArgs, type PaginatedQueryItem, type PaginatedQueryReference, type PaginationStatus } from '../../vue/composables/use-paginated-query.js';
+import { type AsyncQueryOptions } from './use-async-query.js';
+/**
+ * Options for {@link useAsyncPaginatedQuery}: `usePaginatedQuery`'s
+ * `initialNumItems` plus the SSR options of {@link AsyncQueryOptions}.
+ *
+ * @public
+ */
+export interface AsyncPaginatedQueryOptions extends Pick<AsyncQueryOptions, 'key' | 'server' | 'lazy' | 'token'> {
+    /** How many items the first page holds — on the server and on the client. */
+    initialNumItems: number;
+}
+/**
+ * The reactive half of {@link AsyncPaginatedQueryReturn}: `usePaginatedQuery`'s
+ * fields plus the `error` and `refresh` of the Nuxt data contract.
+ *
+ * @public
+ */
+export interface AsyncPaginatedQueryData<Item> {
+    /**
+     * The rows: the server-rendered first page until the live subscription
+     * delivers its own, then every loaded page, live. The server page is
+     * shown for the initial args only — after an args change the list is
+     * empty until the new first page arrives.
+     */
+    results: ComputedRef<Item[]>;
+    /**
+     * `usePaginatedQuery`'s status. Before the live subscription has its first
+     * page it is derived from the server page: `'CanLoadMore'` or `'Exhausted'`.
+     */
+    status: ComputedRef<PaginationStatus>;
+    /** `true` while no page — server or live — is available yet, or more rows are loading. */
+    isLoading: ComputedRef<boolean>;
+    /** The SSR fetch error or the live subscription's, `null` when none. Never thrown. */
+    error: ComputedRef<Error | null>;
+    /**
+     * Fetch `numItems` more rows. Takes effect once the live subscription has
+     * its first page (`status` no longer derived from the server page).
+     */
+    loadMore: (numItems: number) => void;
+    /** Re-run the server-side first-page fetch (client-side it is a no-op — the subscription is live). */
+    refresh: (opts?: {
+        dedupe?: 'cancel' | 'defer';
+    }) => Promise<void>;
+}
+/**
+ * Result of {@link useAsyncPaginatedQuery}: awaitable like `useAsyncData`, and
+ * the refs of {@link AsyncPaginatedQueryData}.
+ *
+ * @public
+ */
+export interface AsyncPaginatedQueryReturn<Item> extends PromiseLike<AsyncPaginatedQueryData<Item>>, AsyncPaginatedQueryData<Item> {
+}
+/**
+ * A paginated Convex query the Nuxt way: the first page is fetched during SSR
+ * and hydrated from the payload, then {@link usePaginatedQuery} takes over on
+ * the client — live rows and `loadMore`, no loading flash for the first page.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { api } from '#convex/api'
+ *
+ * const { results, status, loadMore } = useAsyncPaginatedQuery(
+ *   api.messages.list,
+ *   {},
+ *   { initialNumItems: 20 },
+ * )
+ * </script>
+ * ```
+ *
+ * The payload entry is keyed on the query name, the *initial* args and
+ * `initialNumItems` (override with `options.key`). Client-side navigation does
+ * not fetch a page over HTTP: the subscription opens straight away, and the
+ * server page only matters for the first paint.
+ *
+ * @param query - a `FunctionReference` for the public paginated query.
+ * @param args - the query's arguments without `paginationOpts`, or `'skip'`.
+ *   Accepts a ref, computed, or getter.
+ * @param options - {@link AsyncPaginatedQueryOptions}.
+ * @returns An awaitable {@link AsyncPaginatedQueryReturn}.
+ *
+ * @public
+ */
+export declare function useAsyncPaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: AsyncPaginatedQueryOptions): AsyncPaginatedQueryReturn<PaginatedQueryItem<Query>>;
+/** @public */
+export declare const useConvexAsyncPaginatedQuery: typeof useAsyncPaginatedQuery;