nuxt-convex-module 0.13.0 → 0.14.0

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

@@ -1,4 +1,4 @@
-import { authClient } from "#convex/auth-client";
+import { loadAuthClient, onAuthClient } from "./auth-client-loader.js";
 const normalizePathname = (path) => {
   const slashed = path.startsWith("/") ? path : `/${path}`;
   let end = slashed.length;
@@ -12,41 +12,58 @@ export async function consumeCrossDomainOneTimeToken(options = {}) {
   }
   const url = new URL(window.location.href);
   const token = url.searchParams.get("ott");
-  if (token) {
-    const authClientWithCrossDomain = authClient;
-    url.searchParams.delete("ott");
-    window.history.replaceState({}, "", url);
-    if (!authClientWithCrossDomain.crossDomain) {
-      return;
-    }
-    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).`
-      );
-      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
-      });
-      const session = result.data?.session;
-      if (session) {
-        await authClient.getSession({
-          fetchOptions: {
-            headers: {
-              Authorization: `Bearer ${session.token}`
-            }
+  if (!token) return;
+  url.searchParams.delete("ott");
+  window.history.replaceState({}, "", url);
+  const authClient = await loadAuthClient().catch(() => loadAuthClient()).catch((error) => {
+    console.warn("[nuxt-convex-module] Failed to load the Better Auth client:", error);
+  });
+  if (!authClient) {
+    onAuthClient((client) => void exchangeKeptToken(client, token, url, options));
+    return;
+  }
+  await exchangeOneTimeToken(authClient, token, url, options);
+}
+async function exchangeKeptToken(authClient, token, url, options) {
+  const current = await Promise.resolve().then(() => authClient.getSession()).catch(() => void 0);
+  if (!current || current.error || current.data?.session) {
+    if (!current?.data?.session) console.warn("[nuxt-convex-module] Failed to consume cross-domain one-time token:", current?.error ?? "the session lookup failed");
+    return;
+  }
+  await exchangeOneTimeToken(authClient, token, url, options);
+}
+async function exchangeOneTimeToken(authClient, token, url, options) {
+  const authClientWithCrossDomain = authClient;
+  if (!authClientWithCrossDomain?.crossDomain) {
+    return;
+  }
+  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).`
+    );
+    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
+    });
+    const session = result.data?.session;
+    if (session) {
+      await authClientWithCrossDomain.getSession({
+        fetchOptions: {
+          headers: {
+            Authorization: `Bearer ${session.token}`
           }
-        });
-        await authClientWithCrossDomain.updateSession();
-      }
-    } catch (error) {
-      console.warn("[nuxt-convex-module] Failed to consume cross-domain one-time token:", error);
+        }
+      });
+      await authClientWithCrossDomain.updateSession();
     }
+  } catch (error) {
+    console.warn("[nuxt-convex-module] Failed to consume cross-domain one-time token:", error);
   }
 }

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

@@ -6,6 +6,7 @@
  */
 export { useBetterAuth, type UseBetterAuthReturn, type BetterAuthSession, type BetterAuthUser } from './use-better-auth.js';
 export { authClient, type AuthClient } from '#convex/auth-client';
+export { loadAuthClient } from './auth-client-loader.js';
 export { usePreloadedAuthQuery } from './hydration.js';
 export { consumeCrossDomainOneTimeToken, type AuthClientWithCrossDomain, type ConsumeCrossDomainOneTimeTokenOptions } from './cross-domain.js';
 export { resolveAuthRedirect } from './redirect.js';

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

@@ -1,5 +1,6 @@
 export { useBetterAuth } from "./use-better-auth.js";
 export { authClient } from "#convex/auth-client";
+export { loadAuthClient } from "./auth-client-loader.js";
 export { usePreloadedAuthQuery } from "./hydration.js";
 export { consumeCrossDomainOneTimeToken } from "./cross-domain.js";
 export { resolveAuthRedirect } from "./redirect.js";

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

@@ -2,18 +2,37 @@ import { defineNuxtPlugin, useRuntimeConfig, useState } from "#app";
 import { ConvexVueClient, ConvexClientKey } from "../../vue/client.js";
 import { ConvexAuthStateKey, createScopedConvexAuthState } from "../../vue/auth/index.js";
 import { CONVEX_INITIAL_TOKEN_KEY } from "../../nuxt/config.js";
-import { useBetterAuth } from "./use-better-auth.js";
+import { settleSessionWithoutClient, useBetterAuth } from "./use-better-auth.js";
+import { deferAuthClient } from "./auth-client-loader.js";
+import { NO_SESSION_KEY } from "./token-store.js";
 import { consumeCrossDomainOneTimeToken } from "./cross-domain.js";
+function holdsCrossDomainSession() {
+  return [() => localStorage, () => sessionStorage].some((open) => {
+    try {
+      const storage = open();
+      for (let index = 0; index < storage.length; index++) {
+        const key = storage.key(index);
+        if (key?.endsWith("_cookie") && storage.getItem(key)?.includes("session_token")) return true;
+      }
+    } catch {
+    }
+    return false;
+  });
+}
 export default defineNuxtPlugin({
   name: "nuxt-convex-module:better-auth:client",
   async setup(nuxtApp) {
-    const { url, crossDomainCallbackRoute } = useRuntimeConfig().public.convex;
+    const { url, crossDomainCallbackRoute, deferAuthClient: mayDefer } = useRuntimeConfig().public.convex;
     if (!url) {
       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);
+    if (mayDefer !== false && useState(NO_SESSION_KEY, () => false).value && !new URL(window.location.href).searchParams.has("ott") && !holdsCrossDomainSession()) {
+      deferAuthClient();
+      nuxtApp.hook("app:suspense:resolve", settleSessionWithoutClient);
+    }
     await consumeCrossDomainOneTimeToken({
       callbackRoute: crossDomainCallbackRoute || void 0
     });

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

@@ -1,10 +1,11 @@
 import { computed } from "vue";
-import { defineNuxtPlugin, useRuntimeConfig, useState, useRequestEvent, useResponseHeader } from "#app";
+import { defineNuxtPlugin, useRuntimeConfig, useState, useRequestEvent, useRequestHeaders, useResponseHeader } from "#app";
 import { ConvexVueClient, ConvexClientKey } from "../../vue/client.js";
 import { CONVEX_INITIAL_TOKEN_KEY, closeAfterRender } from "../../nuxt/config.js";
 import { convexAuth } from "../nuxt/server.js";
 import { ConvexAuthStateKey } from "../../vue/auth/index.js";
-import { BetterAuthTokenStoreKey, createBetterAuthTokenStore, seedInitialToken } from "./token-store.js";
+import { CACHING_HEADERS, isSharedRender, NO_SESSION_CONTEXT_KEY } from "../nuxt/shared-render.js";
+import { BetterAuthTokenStoreKey, createBetterAuthTokenStore, hasSessionCookie, NO_SESSION_KEY, seedInitialToken } from "./token-store.js";
 export async function prefetchAuthToken(event, initialToken, cacheControl) {
   try {
     const token = await convexAuth(event).getToken();
@@ -12,10 +13,20 @@ export async function prefetchAuthToken(event, initialToken, cacheControl) {
     if (token && event) {
       cacheControl.value = "private, no-store";
     }
+    return true;
   } catch (error) {
     console.warn("[nuxt-convex-module] Failed to prefetch auth token for SSR:", error);
+    return false;
   }
 }
+function renderContext(event) {
+  const context = event.context;
+  return {
+    routeRules: context._nitro?.routeRules,
+    cache: context.cache,
+    headers: Object.fromEntries(CACHING_HEADERS.map((name) => [name, event.node?.res?.getHeader?.(name)]))
+  };
+}
 export default defineNuxtPlugin({
   name: "nuxt-convex-module:better-auth:server",
   async setup(nuxtApp) {
@@ -36,8 +47,17 @@ export default defineNuxtPlugin({
     nuxtApp.vueApp.provide(ConvexAuthStateKey, ssrAuthState);
     const event = useRequestEvent();
     if (event && !import.meta.prerender) {
-      await prefetchAuthToken(event, initialToken, useResponseHeader("Cache-Control"));
+      const cacheControl = useResponseHeader("Cache-Control");
+      const noSession = useState(NO_SESSION_KEY, () => false);
+      const { cookie } = useRequestHeaders(["cookie"]);
+      const answered = await prefetchAuthToken(event, initialToken, cacheControl);
       seedInitialToken(tokenStore, initialToken.value);
+      noSession.value = answered && !initialToken.value && !hasSessionCookie(cookie) && !isSharedRender(renderContext(event));
+      nuxtApp.hooks.hook("app:rendered", () => {
+        if (noSession.value && isSharedRender(renderContext(event))) noSession.value = false;
+        const context = event.context;
+        context[NO_SESSION_CONTEXT_KEY] = noSession.value;
+      });
     }
   }
 });

package/dist/runtime/better-auth/vue/token-store.js

@@ -10,6 +10,10 @@ export function createBetterAuthTokenStore() {
   };
 }
 export const BetterAuthTokenStoreKey = Symbol("BetterAuthTokenStore");
+export const NO_SESSION_KEY = "convex:betterAuth:noSession";
+export function hasSessionCookie(cookie) {
+  return !!cookie && cookie.split(";").some((pair) => pair.split("=", 1)[0].trim().endsWith("session_token"));
+}
 export const PENDING_AUTH_VERSION = "__pending__";
 export function readTokenClaims(token) {
   try {

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

@@ -1,6 +1,6 @@
 import type { AuthTokenFetcher } from 'convex/browser';
 import { type ComputedRef } from 'vue';
-import { type AuthClient } from '#convex/auth-client';
+import type { AuthClient } from '#convex/auth-client';
 export type BetterAuthSession = AuthClient['useSession'] extends {
     (): infer R;
     (useFetch: any): any;
@@ -49,3 +49,9 @@ export interface UseBetterAuthReturn {
  * @public
  */
 export declare function useBetterAuth(initialToken?: string | null): UseBetterAuthReturn;
+/**
+ * Forget what the Better Auth integration keeps for the app's lifetime: the
+ * browser's token cache and its session subscription. Published from
+ * `nuxt-convex-module/testing`; call it between tests that sign in.
+ */
+export declare function resetBetterAuthState(): void;

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

@@ -1,5 +1,5 @@
 import { computed, effectScope, hasInjectionContext, inject, shallowRef, triggerRef, watch } from "vue";
-import { authClient } from "#convex/auth-client";
+import { __resetAuthClientLoaderForTests, isAuthClientDeferred, lazyAuthClient, loadAuthClient, loadedAuthClient, onAuthClient, retryAuthClientLoad } from "./auth-client-loader.js";
 import { BetterAuthTokenStoreKey, clearToken, createBetterAuthTokenStore, PENDING_AUTH_VERSION, readTokenClaims, seedInitialToken } from "./token-store.js";
 const browserStore = createBetterAuthTokenStore();
 function useTokenStore() {
@@ -16,23 +16,85 @@ const serverSession = () => shallowRef({
 });
 let browserSession;
 let browserSessionScope;
+let settledWithoutClient = false;
+const clientAnswered = shallowRef(false);
+const pendingSessionState = () => {
+  const refetch = async (...args) => {
+    await loadAuthClient();
+    const next = browserSession.value.refetch;
+    if (next === refetch) return;
+    return next(...args);
+  };
+  return { data: null, error: null, isPending: true, isRefetching: false, refetch };
+};
 const useClientSession = () => {
   if (import.meta.server) return serverSession();
   browserSessionScope ??= effectScope(true);
-  return browserSession ??= browserSessionScope.run(() => {
-    const session = authClient.useSession();
+  const scope = browserSessionScope;
+  return browserSession ??= scope.run(() => {
+    const session = shallowRef(pendingSessionState());
+    onAuthClient((client) => scope.active && scope.run(() => {
+      watch(client.useSession(), (state) => {
+        if (settledWithoutClient && state.isPending) {
+          if (session.value.refetch !== state.refetch) session.value = { ...session.value, refetch: state.refetch };
+          return;
+        }
+        settledWithoutClient = false;
+        session.value = state;
+        if (!state.isPending) clientAnswered.value = true;
+      }, { immediate: true, flush: "sync" });
+    }));
+    if (!isAuthClientDeferred()) void loadAtStartup();
     watch(session, ({ data, isPending }) => {
       if (!data && !isPending) clearToken(browserStore);
     }, { flush: "sync" });
     return session;
   });
 };
+async function loadAtStartup() {
+  try {
+    await loadAuthClient().catch(() => loadAuthClient());
+  } catch (error) {
+    console.warn("[nuxt-convex-module] Failed to load the Better Auth client:", error);
+    if (!coveredByServerToken()) settle(error);
+    retryAuthClientLoad();
+  }
+}
+function coveredByServerToken() {
+  return Boolean(browserStore.cachedToken.value) && browserStore.cachedTokenVersion === PENDING_AUTH_VERSION;
+}
+export async function clientSessionSettled() {
+  useClientSession();
+  try {
+    await loadAuthClient().catch(() => loadAuthClient());
+  } catch {
+    if (!coveredByServerToken()) settle();
+    return;
+  }
+  if (clientAnswered.value) return;
+  await new Promise((resolve) => {
+    const stop = watch(clientAnswered, (answered) => {
+      if (!answered) return;
+      stop();
+      resolve();
+    });
+  });
+}
+function settle(error = null) {
+  const session = useClientSession();
+  if (loadedAuthClient() || !session.value.isPending) return;
+  settledWithoutClient = true;
+  session.value = { ...session.value, isPending: false, error };
+}
+export function settleSessionWithoutClient() {
+  settle();
+}
 export function useBetterAuth(initialToken) {
   const store = useTokenStore();
   seedInitialToken(store, initialToken);
   const { cachedToken } = store;
   const session = useClientSession();
-  const client = authClient;
+  const client = loadedAuthClient() ?? lazyAuthClient;
   const authVersion = computed(() => {
     const data = session.value.data;
     const id = data?.session?.id ?? data?.user?.id ?? null;
@@ -47,11 +109,17 @@ export function useBetterAuth(initialToken) {
     return !!data.user?.id && subject !== void 0 && subject !== data.user.id;
   });
   const isServerTokenActive = () => session.value.isPending && cachedToken.value !== null && store.cachedTokenVersion === PENDING_AUTH_VERSION;
+  const signedInSince = async (forceRefreshToken) => {
+    if (!forceRefreshToken || import.meta.server || clientAnswered.value) return false;
+    await clientSessionSettled();
+    return currentAuthVersion() !== null;
+  };
   const fetchAccessToken = async ({
     forceRefreshToken = false
   } = {}) => {
     const version = currentAuthVersion();
     if (version === null) {
+      if (await signedInSince(forceRefreshToken)) return fetchAccessToken({ forceRefreshToken });
       clearToken(store);
       return null;
     }
@@ -78,7 +146,7 @@ export function useBetterAuth(initialToken) {
     };
     store.pendingTokenVersion = version;
     const isLatest = () => store.pendingToken === pending;
-    const pending = store.pendingToken = client.convex.token({ fetchOptions: { throw: false } }).then(({ data, error }) => {
+    const pending = store.pendingToken = loadAuthClient().then((client2) => client2.convex.token({ fetchOptions: { throw: false } })).then(({ data, error }) => {
       if (error && error.status !== 401) {
         return afterFailure();
       }
@@ -117,10 +185,14 @@ export function useBetterAuth(initialToken) {
     authVersion
   };
 }
-export function __resetUseBetterAuthForTests() {
+export function resetBetterAuthState() {
   Object.assign(browserStore, createBetterAuthTokenStore(), { cachedToken: browserStore.cachedToken });
   browserStore.cachedToken.value = null;
   browserSessionScope?.stop();
   browserSessionScope = void 0;
   browserSession = void 0;
+  settledWithoutClient = false;
+  clientAnswered.value = false;
+  __resetAuthClientLoaderForTests();
 }
+export const __resetUseBetterAuthForTests = resetBetterAuthState;

package/dist/runtime/nuxt/function-name.d.ts

@@ -0,0 +1,9 @@
+import { getFunctionName } from 'convex/server';
+declare const SOURCE_PREFIX: {
+    readonly query: "Q";
+    readonly mutation: "M";
+    readonly action: "A";
+};
+/** `call`, with the function's name put in front of the message of the error it rejects with. */
+export declare function withFunctionName<T>(source: keyof typeof SOURCE_PREFIX, reference: Parameters<typeof getFunctionName>[0], call: Promise<T>): Promise<T>;
+export {};

package/dist/runtime/nuxt/function-name.js

@@ -0,0 +1,38 @@
+import { getFunctionName } from "convex/server";
+const SOURCE_PREFIX = { query: "Q", mutation: "M", action: "A" };
+const unnamed = /* @__PURE__ */ new WeakMap();
+export async function withFunctionName(source, reference, call) {
+  try {
+    return await call;
+  } catch (error) {
+    if (error instanceof Error && !error.message.startsWith("[CONVEX ")) name(error, `[CONVEX ${SOURCE_PREFIX[source]}(${getFunctionName(reference)})] `);
+    throw error;
+  }
+}
+function name(error, prefix) {
+  const original = error.message;
+  const stack = error.stack;
+  try {
+    error.message = `${prefix}${original}`;
+  } catch {
+    return;
+  }
+  if (error.message !== `${prefix}${original}`) return;
+  unnamed.set(error, { message: original, stack });
+  const header = `${error.name}: ${original}`;
+  if (original && stack?.startsWith(header)) error.stack = `${error.name}: ${error.message}${stack.slice(header.length)}`;
+}
+export function withoutFunctionName(error, read) {
+  const before = error instanceof Error ? unnamed.get(error) : void 0;
+  if (!before) return read(error);
+  const named = error;
+  const { message, stack } = named;
+  named.message = before.message;
+  named.stack = before.stack;
+  try {
+    return read(error);
+  } finally {
+    named.message = message;
+    named.stack = stack;
+  }
+}

package/dist/runtime/nuxt/index.js

@@ -2,6 +2,7 @@ import { ConvexHttpClient } from "convex/browser";
 import { getFunctionName } from "convex/server";
 import { convexToJson, jsonToConvex } from "convex/values";
 import { getConvexRuntimeConfig } from "./config.js";
+import { withFunctionName } from "./function-name.js";
 export async function preloadQuery(query, ...args) {
   const value = await fetchQuery(query, ...args);
   const preloaded = {
@@ -17,17 +18,17 @@ export function preloadedQueryResult(preloaded) {
 export async function fetchQuery(query, ...args) {
   const [fnArgs, options] = args;
   const client = setupClient(options ?? {});
-  return client.query(query, fnArgs || {});
+  return withFunctionName("query", query, client.query(query, fnArgs || {}));
 }
 export async function fetchMutation(mutation, ...args) {
   const [fnArgs, options] = args;
   const client = setupClient(options ?? {});
-  return client.mutation(mutation, fnArgs || {});
+  return withFunctionName("mutation", mutation, client.mutation(mutation, fnArgs || {}));
 }
 export async function fetchAction(action, ...args) {
   const [fnArgs, options] = args;
   const client = setupClient(options ?? {});
-  return client.action(action, fnArgs || {});
+  return withFunctionName("action", action, client.action(action, fnArgs || {}));
 }
 function setupClient(options) {
   if ("url" in options && options.url === void 0) {

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

@@ -0,0 +1,21 @@
+/**
+ * Helpers for an app's own tests, kept off the runtime entries.
+ *
+ * The module keeps some state for the app's lifetime, as upstream's provider
+ * keeps it for the provider's: a test that signs in leaves it behind for the
+ * next. Reset it here instead of reaching into the module's files by path.
+ *
+ * Load it where the app's runtime loads, in `@nuxt/test-utils`' `nuxt`
+ * environment: it imports `#convex/auth-client`, the alias the module (or
+ * your test config) registers.
+ *
+ * ```ts
+ * import { afterEach } from 'vitest'
+ * import { resetBetterAuthState } from 'nuxt-convex-module/testing'
+ *
+ * afterEach(() => resetBetterAuthState())
+ * ```
+ *
+ * @module testing
+ */
+export { resetBetterAuthState } from '../better-auth/vue/use-better-auth.js';

package/dist/runtime/nuxt/testing.js

@@ -0,0 +1 @@
+export { resetBetterAuthState } from "../better-auth/vue/use-better-auth.js";

package/dist/runtime/vue/composables/use-upload-queue.d.ts

@@ -6,6 +6,13 @@ import { type GenerateUploadUrl, type StorageId } from './use-upload.js';
  * @public
  */
 export type UploadItemStatus = 'pending' | 'uploading' | 'success' | 'error';
+/**
+ * Which step an `uploading` item is on: its `prepare` hook, the transfer, or
+ * its `after` hook. `null` outside `uploading`.
+ *
+ * @public
+ */
+export type UploadItemStage = 'prepare' | 'upload' | 'after';
 /**
  * A single entry in the queue managed by {@link useUploadQueue}.
  *
@@ -20,10 +27,27 @@ export interface UploadQueueItem {
     status: UploadItemStatus;
     /** Upload progress for this item, from `0` to `1`. */
     progress: number;
-    /** The storage id once the upload succeeds, or `null`. */
+    /**
+     * The storage id once the file is stored, or `null`. An item that failed
+     * after that keeps it (see `after` and `onItemSuccess`).
+     */
     storageId: StorageId | null;
     /** The error if this item failed, or `null`. */
     error: Error | null;
+    /**
+     * Whether the error is a refusal rather than a failure: the app said no
+     * (`isRefusal`; by default a `ConvexError`), so the same file would be
+     * turned away again. `false` while the item has no error.
+     */
+    refused: boolean;
+    /** The step an `uploading` item is on, or `null`. */
+    stage: UploadItemStage | null;
+    /**
+     * What `prepare` returned, which is what gets sent; `null` until it runs,
+     * or without a `prepare` hook (the file itself is sent). Kept for a retry
+     * and for a preview.
+     */
+    prepared: Blob | null;
 }
 /**
  * Options for {@link useUploadQueue}.
@@ -33,9 +57,39 @@ export interface UploadQueueItem {
 export interface UseUploadQueueOptions {
     /** Maximum number of uploads to run at once. Defaults to `3`. */
     concurrency?: number;
-    /** Called when an individual item finishes uploading. */
+    /**
+     * Turn a queued file into what is sent, before an upload URL is asked
+     * for: resize, re-encode, strip metadata. Throw to turn the file away; the
+     * item ends `error`, refused when `isRefusal` says so. Runs once per
+     * item: a retry reuses what it returned.
+     */
+    prepare?: (file: Blob, item: UploadQueueItem, signal: AbortSignal) => Blob | Promise<Blob>;
+    /**
+     * Runs once the file is stored, before the item counts as a success:
+     * attach the storage id to a document, run a check on it. The item stays
+     * `uploading` (stage `'after'`) until it settles. A throw ends the item
+     * `error`; a retry then runs only this hook again, with the same storage
+     * id, unless the throw was a refusal, which sends the file again. After a
+     * refusal `item.storageId` still holds the stored file while the item is
+     * in error, so `onItemError` can delete it; the queue never deletes files,
+     * and a retry forgets it before uploading again.
+     */
+    after?: (storageId: StorageId, item: UploadQueueItem, signal: AbortSignal) => void | Promise<void>;
+    /**
+     * Whether an error is a refusal (the app turned the file away) rather than
+     * a failure (the network, the deployment, an abort). Defaults to: the
+     * error is a `ConvexError`, which a Convex function throws on purpose.
+     * An aborted item is never refused, and neither is an error this check
+     * throws on.
+     */
+    isRefusal?: (error: Error, item: UploadQueueItem) => boolean;
+    /**
+     * Called when an individual item finishes uploading (after `after`). A
+     * throw ends the item `error` with its storage id kept; a retry then runs
+     * only this callback again, never `after` a second time.
+     */
     onItemSuccess?: (storageId: StorageId, item: UploadQueueItem) => void | Promise<void>;
-    /** Called when an individual item fails. */
+    /** Called when an individual item fails or is refused (`item.refused` says which). */
     onItemError?: (error: Error, item: UploadQueueItem) => void;
     /** Called once every queued item has settled (succeeded or failed). */
     onComplete?: (items: UploadQueueItem[]) => void;
@@ -66,6 +120,14 @@ export interface VueUploadQueue {
     remove: (id: string) => void;
     /** Abort everything and empty the queue. */
     clear: () => void;
+    /**
+     * Queue an errored item again, or every errored item without an id. It
+     * picks up where it stopped: `onItemSuccess` alone when `after` already
+     * finished, `after` alone when the file is stored, the transfer when
+     * `prepare` already ran. Whether a refused item is worth
+     * retrying is the app's call; nothing here stops it.
+     */
+    retry: (id?: string) => void;
 }
 /**
  * Upload many files to Convex file storage with bounded concurrency and
@@ -76,6 +138,11 @@ export interface VueUploadQueue {
  * a multi-file `<input>`) and the queue uploads up to `concurrency` at a time,
  * exposing per-item and aggregate progress.
  *
+ * Options `prepare` and `after` add the app's own steps on either side of
+ * the transfer (shrink a photo first; attach it once stored), and a failed
+ * item says whether the app `refused` it or it failed, so the UI can show a
+ * reason for one and {@link VueUploadQueue.retry} the other.
+ *
  * @example
  * ```vue
  * <script setup lang="ts">