nuxt-convex-module 0.12.3 → 0.14.0

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

@@ -1,6 +1,6 @@
-import { computed, effectScope, hasInjectionContext, inject, shallowRef } from "vue";
-import { authClient } from "#convex/auth-client";
-import { BetterAuthTokenStoreKey, createBetterAuthTokenStore, PENDING_AUTH_VERSION, seedInitialToken } from "./token-store.js";
+import { computed, effectScope, hasInjectionContext, inject, shallowRef, triggerRef, watch } from "vue";
+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() {
   if (!import.meta.server) return browserStore;
@@ -16,64 +16,163 @@ 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(() => 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;
-    return data?.session?.id ?? data?.user?.id ?? null;
+    const id = data?.session?.id ?? data?.user?.id ?? null;
+    return id === null && session.value.isPending ? void 0 : id;
   });
-  const currentAuthVersion = () => authVersion.value ?? (session.value.isPending ? PENDING_AUTH_VERSION : null);
+  const currentAuthVersion = () => authVersion.value === void 0 ? PENDING_AUTH_VERSION : authVersion.value;
+  const holdsAnotherSessionsToken = computed(() => {
+    const data = session.value.data;
+    if (!data || !cachedToken.value || store.cachedTokenVersion !== PENDING_AUTH_VERSION) return false;
+    if (store.initialTokenSessionId && data.session?.id) return store.initialTokenSessionId !== data.session.id;
+    const subject = readTokenClaims(cachedToken.value)?.sub;
+    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) {
-      cachedToken.value = null;
-      store.cachedTokenVersion = null;
-      store.pendingToken = null;
-      store.pendingTokenVersion = null;
+      if (await signedInSince(forceRefreshToken)) return fetchAccessToken({ forceRefreshToken });
+      clearToken(store);
       return null;
     }
-    if (cachedToken.value && !forceRefreshToken && store.cachedTokenVersion === version) {
-      return cachedToken.value;
+    if (store.cachedTokenVersion === PENDING_AUTH_VERSION && store.initialTokenSessionId === version) {
+      store.cachedTokenVersion = version;
     }
-    if (!forceRefreshToken && store.pendingToken && store.pendingTokenVersion === version) {
-      return store.pendingToken;
+    if (!forceRefreshToken) {
+      if (store.pendingToken && store.pendingTokenVersion === version) {
+        return store.pendingToken;
+      }
+      if (cachedToken.value && store.cachedTokenVersion === version) {
+        return cachedToken.value;
+      }
     }
+    const afterFailure = () => {
+      if (cachedToken.value && !holdsAnotherSessionsToken.value && (store.cachedTokenVersion === version || store.cachedTokenVersion === PENDING_AUTH_VERSION)) {
+        return cachedToken.value;
+      }
+      if (isLatest()) {
+        cachedToken.value = null;
+        store.cachedTokenVersion = version;
+      }
+      return null;
+    };
     store.pendingTokenVersion = version;
-    const pending = store.pendingToken = client.convex.token({ fetchOptions: { throw: false } }).then(({ data }) => {
+    const isLatest = () => store.pendingToken === pending;
+    const pending = store.pendingToken = loadAuthClient().then((client2) => client2.convex.token({ fetchOptions: { throw: false } })).then(({ data, error }) => {
+      if (error && error.status !== 401) {
+        return afterFailure();
+      }
       const token = data?.token || null;
-      cachedToken.value = token;
-      store.cachedTokenVersion = version;
+      if (isLatest()) {
+        store.cachedTokenVersion = version;
+        cachedToken.value = token;
+        triggerRef(cachedToken);
+      }
       return token;
-    }).catch(() => {
-      cachedToken.value = null;
-      store.cachedTokenVersion = version;
-      return null;
-    }).finally(() => {
-      store.pendingToken = null;
-      store.pendingTokenVersion = null;
+    }).catch(afterFailure).finally(() => {
+      if (isLatest()) {
+        store.pendingToken = null;
+        store.pendingTokenVersion = null;
+      }
     });
     return pending;
   };
   return {
-    isLoading: computed(() => session.value.isPending && !cachedToken.value),
+    isLoading: computed(() => session.value.isPending && !isServerTokenActive() || holdsAnotherSessionsToken.value),
     // PARITY: D-03
-    // Diverges from upstream's `Boolean(session?.session) || cachedToken !== null`:
-    // a settled signed-out session must read unauthenticated immediately (Vue has
-    // no re-render to run upstream's cache-clearing effect first), and Better Auth
-    // session data without a nested `session` still counts as signed in.
+    // Diverges from upstream's `Boolean(session?.session) || isSsrTokenActive`:
+    // Better Auth session data without a nested `session` still counts as
+    // signed in.
     isAuthenticated: computed(
-      () => !!session.value.data || session.value.isPending && cachedToken.value !== null
+      () => !!session.value.data || isServerTokenActive()
     ),
     fetchAccessToken,
     // PARITY: A-06 — Vue-only service extensions.
@@ -86,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/composables/use-async-paginated-query.d.ts

@@ -32,7 +32,7 @@ export interface AsyncPaginatedQueryData<Item> {
     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. */
+    /** The live subscription's error, or the SSR fetch error until the live query has a page; `null` when none. Never thrown. */
     error: ComputedRef<Error | null>;
     /**
      * Fetch `numItems` more rows. Takes effect once the live subscription has

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

@@ -70,9 +70,11 @@ export function useAsyncPaginatedQuery(query, args, options) {
     return "LoadingFirstPage";
   });
   const isLoading = computed(() => status.value === "LoadingFirstPage" || status.value === "LoadingMore");
-  const error = computed(
-    () => liveState.value?.error ?? clientError.value ?? asyncData.error.value ?? null
-  );
+  const error = computed(() => {
+    const liveError = liveState.value?.error ?? clientError.value;
+    if (liveError) return liveError;
+    return liveHasPage.value ? null : asyncData.error.value ?? null;
+  });
   const loadMore = (numItems) => {
     live?.loadMore(numItems);
   };

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

@@ -66,7 +66,10 @@ export interface AsyncQueryReturn<T> extends PromiseLike<AsyncQueryData<T>> {
      * nothing has loaded (or while skipped).
      */
     data: ComputedRef<T | undefined>;
-    /** The initial-fetch or live-subscription error, `null` when none. */
+    /**
+     * The initial-fetch or live-subscription error, `null` when none. A failed
+     * initial fetch stops counting once the live subscription has a value.
+     */
     error: ComputedRef<Error | null>;
     /**
      * Initial-fetch status. Live pushes don't churn it: once data exists it

package/dist/runtime/nuxt/composables/use-async-query.js

@@ -75,9 +75,12 @@ export function useAsyncQuery(query, args, options = {}) {
   const data = computed(
     () => liveValue.value !== void 0 ? liveValue.value : payloadValue.value
   );
-  const error = computed(
-    () => liveError.value ?? asyncData.error.value ?? null
-  );
+  const error = computed(() => {
+    if (liveError.value) {
+      return liveError.value;
+    }
+    return liveValue.value !== void 0 ? null : asyncData.error.value ?? null;
+  });
   const status = computed(() => {
     if (liveError.value) {
       return "error";

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

@@ -37,7 +37,8 @@ export declare function convexResourceSrc(url?: string, siteUrl?: string): strin
  *
  * For each directive we keep any value the user already set and *append* the
  * Convex origins, so consumers extend (add their own third parties) rather than
- * fight the defaults, and the Convex origins are always present. A user who sets
+ * fight the defaults, and the Convex origins are always present. That covers a
+ * directive the user left to `default-src`, whose places carry over. A user who sets
  * `contentSecurityPolicy: false` (CSP disabled) is left untouched, as is a rule
  * set with nothing to add (no Convex URL).
  */

package/dist/runtime/nuxt/csp.js

@@ -39,8 +39,14 @@ export function applyConvexSecurityDefaults(rules, connectSrc, resourceSrc) {
   tightenDirective(csp, "media-src", ["'self'"], resourceSrc);
 }
 function tightenDirective(csp, name, baseline, additions) {
-  if (additions.length === 0) return;
-  const current = csp[name];
-  const existing = Array.isArray(current) ? current : typeof current === "string" ? current.split(/\s+/).filter(Boolean) : baseline;
+  if (additions.length === 0 || csp[name] === false) return;
+  const existing = sourcesOf(csp[name]) ?? [...baseline, ...inheritedSources(csp)];
   csp[name] = uniq([...existing, ...additions]);
 }
+function sourcesOf(value) {
+  if (Array.isArray(value)) return value;
+  return typeof value === "string" ? value.split(/\s+/).filter(Boolean) : void 0;
+}
+function inheritedSources(csp) {
+  return (sourcesOf(csp["default-src"]) ?? []).filter((source) => source === "'self'" || !source.startsWith("'"));
+}

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/auth/index.d.ts

@@ -66,7 +66,8 @@ export interface ConvexAuthProviderOptions {
          * Alternative re-authentication trigger for providers that hand out a
          * stable fetcher function: when this value changes, auth state transitions
          * back to loading, `clearAuth` runs, and `fetchAccessToken` is called
-         * again against the new auth context.
+         * again against the new auth context. `undefined` means the provider does
+         * not know the context yet, so the first value it learns is no change.
          */
         authVersion?: MaybeRefOrGetter<unknown>;
     };

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

@@ -1,4 +1,4 @@
-import { computed, effectScope, inject, provide, ref, toValue, unref, watch, watchEffect } from "vue";
+import { computed, effectScope, inject, nextTick, provide, ref, toValue, unref, watch } from "vue";
 export const ConvexAuthStateKey = Symbol("ConvexAuthState");
 export function useConvexAuth() {
   const authContext = inject(ConvexAuthStateKey);
@@ -9,6 +9,27 @@ export function useConvexAuth() {
   }
   return authContext;
 }
+const pendingClears = /* @__PURE__ */ new WeakMap();
+function clearAuthLast(client, ended) {
+  const pending = pendingClears.get(client);
+  if (pending) {
+    if (pending.start === ended) {
+      pending.start = null;
+    }
+    return;
+  }
+  const clear = { start: null };
+  pendingClears.set(client, clear);
+  void nextTick(() => {
+    pendingClears.delete(client);
+    try {
+      client.clearAuth();
+    } catch {
+      return;
+    }
+    clear.start?.();
+  });
+}
 export function provideConvexAuth(options) {
   const authState = createConvexAuthState(options);
   provide(ConvexAuthStateKey, authState);
@@ -43,16 +64,37 @@ export function createConvexAuthState(options, scope) {
       },
       { immediate: true }
     );
-    watchEffect((onCleanup) => {
-      if (import.meta.server) {
-        return;
+    const authContext = ref(0);
+    watch(
+      () => toValue(authVersion),
+      (_version, previous) => {
+        if (previous !== void 0) authContext.value++;
       }
-      let isThisEffectRelevant = true;
-      void toValue(authProviderLoading);
-      void toValue(authVersion);
-      const fetchToken = unref(fetchAccessToken);
-      if (toValue(authProviderAuthenticated)) {
-        client.setAuth(
+    );
+    watch(
+      [
+        // The loading flag is here only so auth re-registers when it flips,
+        // mirroring upstream's effect deps. It must not gate `setAuth`: a
+        // provider may report a cached session (authenticated) while still
+        // revalidating (loading), and upstream authenticates the client
+        // immediately in that window.
+        () => toValue(authProviderLoading),
+        authContext,
+        // Unwrapping here tracks the ref, so a new fetcher identity
+        // re-registers auth: upstream's effect re-running when
+        // `fetchAccessToken` changes between renders.
+        () => unref(fetchAccessToken),
+        () => toValue(authProviderAuthenticated)
+      ],
+      ([, , fetchToken, authenticated], _previous, onCleanup) => {
+        if (import.meta.server) {
+          return;
+        }
+        if (!authenticated) {
+          return;
+        }
+        let isThisEffectRelevant = true;
+        const start = () => client.setAuth(
           fetchToken,
           (convexReportsIsAuthenticated) => {
             if (isThisEffectRelevant) {
@@ -67,14 +109,21 @@ export function createConvexAuthState(options, scope) {
             }
           }
         );
+        const pending = pendingClears.get(client);
+        if (pending) {
+          pending.start = start;
+        } else {
+          start();
+        }
         onCleanup(() => {
           isThisEffectRelevant = false;
-          client.clearAuth();
           isConvexAuthenticated.value = null;
           isRefreshing.value = false;
+          clearAuthLast(client, start);
         });
-      }
-    });
+      },
+      { immediate: true }
+    );
   };
   if (scope) {
     scope.run(register);

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">