@oxyhq/services 22.4.2 → 22.6.0

package/src/ui/hooks/queries/userCache.ts

@@ -0,0 +1,308 @@
+/**
+ * Canonical user-cache UPSERT for the Oxy React Query cache.
+ *
+ * The problem this solves: many places across an app write a user object into
+ * the React Query cache and REPLACE the existing entry — profile fetch, feed /
+ * post hydration, search, notifications, lists. Each of those sources carries a
+ * DIFFERENT (often sparse) slice of the user: a feed author has no viewer
+ * `relationship`, a search hit has no `createdAt`, a notification actor has no
+ * `_count`. A plain `setQueryData(key, sparseUser)` therefore STRIPS whatever
+ * fields the authoritative single-profile fetch had already stored — the
+ * "Follows you tag vanishes when the feed loads" / "counts flash to zero" class
+ * of bug.
+ *
+ * The fix (owned here, in the SDK): ONE canonical upsert that MERGES. It writes
+ * under BOTH keys the SDK's user hooks read from:
+ *   - by-id:       `queryKeys.users.detail(id)`             (read by `useUserById`)
+ *   - by-username: `queryKeys.users.byUsername(username, viewerId)` (viewer-scoped;
+ *                  read by `useUserByUsername`, carries the viewer `relationship`)
+ *
+ * Merge semantics (per key):
+ *   - No existing entry  -> seed the (normalized) incoming object and mark it
+ *     STALE (`updatedAt: 0`) so react-query refetches the full authoritative
+ *     profile (viewer-relative `relationship`, counts, `createdAt`, …). Instant
+ *     first paint, then the real fetch.
+ *   - Existing entry     -> `{ ...existing, ...pickMeaningful(incoming) }`: only
+ *     the DEFINED, non-empty fields of `incoming` win; every other field is kept
+ *     from `existing`. A sparse source can never NULL-out or STRIP a field the
+ *     authoritative fetch set. The entry's freshness is left untouched (never
+ *     marked stale — it is already managed).
+ *   - Nested objects (`name`, `_count`, `relationship`) merge field-by-field, so
+ *     a partial `name`/`_count`/`relationship` never replaces a fuller one.
+ *   - `relationship` is written ONLY under the viewer-scoped by-username key —
+ *     the viewer-independent by-id key never stores it (prevents one viewer's
+ *     follow state from leaking into every other viewer's identity cache).
+ *   - Anti-degradation: a good `username` / `name.displayName` / `avatar` is
+ *     never overwritten by a degraded/empty one (empty username, the
+ *     `'Unknown user'` ghost-author sentinel, `null` avatar).
+ *
+ * It is a cache write only — zero network, one `setQueryData` per key.
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+import type { UserNameResponse } from '@oxyhq/contracts';
+import { queryKeys } from './queryKeys';
+import { useAuthStore } from '../../stores/authStore';
+
+/**
+ * A user-shaped object that can be upserted into the cache. Intentionally
+ * permissive: it covers the SDK `User` PLUS the looser actor objects embedded on
+ * posts / notifications / lists, where `name` may be a plain string and the id
+ * may arrive as Mongo `_id`. Every field is optional — a sparse feed author is a
+ * valid `CacheableUser`. The index signature lets any additional `User` field
+ * pass through untouched (so the upsert never has to know the full DTO shape).
+ */
+export interface CacheableUser {
+  id?: string;
+  /** Some sources (post/notification actors) carry the id as Mongo `_id`. */
+  _id?: string;
+  username?: string;
+  /**
+   * Canonical structured name (`UserNameResponse`) OR a plain display string on
+   * the looser actor objects. Normalized to the object shape on write.
+   */
+  name?: string | UserNameResponse;
+  /** Avatar file id. `null`/`''` are treated as "no avatar" (never degrade). */
+  avatar?: string | null;
+  /** Social counts. A partial `_count` never replaces a fuller one. */
+  _count?: { followers?: number; following?: number } | null;
+  /**
+   * Viewer-relative follow relationship. Present ONLY on an authenticated
+   * single-profile fetch; `null`/absent for anon/self/bulk/feed. Never stripped
+   * from an existing entry by a source that lacks it.
+   */
+  relationship?: { isFollowing?: boolean; followsYou?: boolean } | null;
+  [key: string]: unknown;
+}
+
+/** The degraded display-name sentinel (ghost-author rule). */
+const DEGRADED_DISPLAY_NAME = 'Unknown user';
+
+/** A cache entry always carries a resolved string `id`. */
+type CachedUser = CacheableUser & { id: string; name?: UserNameResponse };
+
+/**
+ * Whether a value is "meaningful" — i.e. it should override an existing field.
+ * Drops `undefined` / `null` / empty-or-whitespace strings so a sparse source
+ * can never strip a field. `false`, `0` and other falsy-but-defined values ARE
+ * meaningful (a real `verified: false` or `_count.followers: 0`).
+ */
+function isMeaningful(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim() !== '';
+  return true;
+}
+
+/** A display name is meaningful only when non-empty AND not the degraded sentinel. */
+function isMeaningfulDisplayName(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '' && value !== DEGRADED_DISPLAY_NAME;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Normalize the polymorphic `name` (string | object | nullish) to the canonical object shape. */
+function normalizeName(name: CacheableUser['name']): UserNameResponse | undefined {
+  if (name === undefined || name === null) return undefined;
+  if (typeof name === 'string') {
+    const trimmed = name.trim();
+    return trimmed ? { displayName: trimmed } : undefined;
+  }
+  return name;
+}
+
+/**
+ * Coerce a user-shaped object to a cache entry: resolve the id from
+ * `id ?? _id ?? fallbackId` and normalize `name` to the canonical object shape
+ * (the polymorphic `string` name is dropped from the spread and re-set as an
+ * object so the cache never holds a bare-string name).
+ */
+function toCachedUser(user: CacheableUser, fallbackId: string): CachedUser {
+  const { name: rawName, ...rest } = user;
+  const id = String(user.id ?? user._id ?? fallbackId);
+  const name = normalizeName(rawName);
+  const normalized: CachedUser = { ...rest, id };
+  if (name !== undefined) normalized.name = name;
+  return normalized;
+}
+
+/**
+ * Normalize an incoming (possibly partial) user to a cache entry. Returns `null`
+ * when no id can be resolved (nothing to key on).
+ */
+function normalizeIncoming(user: CacheableUser): CachedUser | null {
+  const cached = toCachedUser(user, '');
+  return cached.id ? cached : null;
+}
+
+/** Merge two `name` objects field-by-field, with anti-degradation on `displayName`. */
+function mergeName(
+  existing: UserNameResponse | undefined,
+  incoming: UserNameResponse | undefined,
+): UserNameResponse | undefined {
+  if (incoming === undefined) return existing;
+  if (existing === undefined) return incoming;
+  const merged: UserNameResponse = { ...existing };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (key === 'displayName') continue;
+    if (isMeaningful(value)) merged[key] = value;
+  }
+  // Never let an empty / `'Unknown user'` displayName overwrite a real one.
+  if (isMeaningfulDisplayName(incoming.displayName)) {
+    merged.displayName = incoming.displayName;
+  }
+  return merged;
+}
+
+/** Merge `_count` field-by-field so a partial count never replaces a fuller one. */
+function mergeCount(
+  existing: CacheableUser['_count'],
+  incoming: CacheableUser['_count'],
+): CacheableUser['_count'] {
+  if (!isPlainObject(incoming)) return existing;
+  const merged: { followers?: number; following?: number } = { ...(isPlainObject(existing) ? existing : {}) };
+  if (typeof incoming.followers === 'number') merged.followers = incoming.followers;
+  if (typeof incoming.following === 'number') merged.following = incoming.following;
+  return merged;
+}
+
+/**
+ * Merge `relationship`. A source without a relationship (feed/list/notification,
+ * or an anon/self/bulk `null`) must NEVER strip an existing viewer relationship.
+ */
+function mergeRelationship(
+  existing: CacheableUser['relationship'],
+  incoming: CacheableUser['relationship'],
+): CacheableUser['relationship'] {
+  if (!isPlainObject(incoming)) return existing;
+  const merged: { isFollowing?: boolean; followsYou?: boolean } = {
+    ...(isPlainObject(existing) ? existing : {}),
+  };
+  if (typeof incoming.isFollowing === 'boolean') merged.isFollowing = incoming.isFollowing;
+  if (typeof incoming.followsYou === 'boolean') merged.followsYou = incoming.followsYou;
+  return merged;
+}
+
+/**
+ * Merge a (normalized) incoming user over an existing cache entry: keep every
+ * existing field, override only with the meaningful fields of `incoming`.
+ *
+ * When `includeRelationship` is false (the viewer-independent by-id key), the
+ * viewer-relative `relationship` field is never read, written, or preserved —
+ * only the by-username key carries it (`useUserByUsername`).
+ */
+function mergeUsers(
+  existing: CachedUser,
+  incoming: CachedUser,
+  options?: { includeRelationship?: boolean },
+): CachedUser {
+  const includeRelationship = options?.includeRelationship ?? true;
+  const merged: CachedUser = { ...existing };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (key === 'name' || key === '_count' || key === 'relationship') continue;
+    if (key === 'id') {
+      merged.id = incoming.id;
+      continue;
+    }
+    if (isMeaningful(value)) merged[key] = value;
+  }
+  const name = mergeName(existing.name, incoming.name);
+  if (name !== undefined) merged.name = name;
+  const count = mergeCount(existing._count, incoming._count);
+  if (count !== undefined) merged._count = count;
+  if (includeRelationship) {
+    const relationship = mergeRelationship(existing.relationship, incoming.relationship);
+    if (relationship !== undefined) merged.relationship = relationship;
+  } else {
+    delete merged.relationship;
+  }
+  return merged;
+}
+
+/** Merge-upsert a normalized user into one cache key (see module docs for semantics). */
+function upsertOneKey(
+  queryClient: QueryClient,
+  key: readonly unknown[],
+  incoming: CachedUser,
+  options: { includeRelationship: boolean },
+): void {
+  const mergeOpts = { includeRelationship: options.includeRelationship };
+  const existing = queryClient.getQueryData<CacheableUser>(key);
+  if (existing === undefined) {
+    // Cold slot: seed the full incoming object, STALE, so react-query refetches
+    // the full authoritative profile (relationship, counts, createdAt, …).
+    const seeded = mergeUsers({ id: incoming.id }, incoming, mergeOpts);
+    queryClient.setQueryData<CachedUser>(key, seeded, { updatedAt: 0 });
+    return;
+  }
+  // Existing entry: merge and leave its freshness lifecycle untouched. The
+  // existing entry is keyed by `incoming.id`, so use it as the fallback id.
+  const merged = mergeUsers(toCachedUser(existing, incoming.id), incoming, mergeOpts);
+  const dataUpdatedAt = queryClient.getQueryState(key)?.dataUpdatedAt ?? 0;
+  queryClient.setQueryData<CachedUser>(key, merged, { updatedAt: dataUpdatedAt });
+}
+
+/**
+ * Resolve the active viewer id. The by-username cache key is viewer-scoped; the
+ * seed must land on the exact key `useUserByUsername` reads. When a caller does
+ * not pass `viewerId`, read it from the auth store — the same store behind the
+ * hook's `useOxy().user?.id`, so seed and read stay in lockstep. An explicit
+ * empty string is honoured (anonymous scope).
+ */
+function resolveViewerId(viewerId?: string): string {
+  return viewerId ?? useAuthStore.getState().user?.id ?? '';
+}
+
+/**
+ * Merge-upsert a (possibly partial) user into the SDK's user query cache under
+ * both the by-id key and, when a username is present, the viewer-scoped
+ * by-username key.
+ *
+ * @param queryClient The app's React Query client.
+ * @param user        A `User`-shaped object (may be sparse).
+ * @param viewerId    The active viewer id for the by-username key. Defaults to
+ *                    the current auth-store user id.
+ */
+export function upsertCachedUser(
+  queryClient: QueryClient,
+  user: CacheableUser,
+  viewerId?: string,
+): void {
+  const incoming = normalizeIncoming(user);
+  if (!incoming) return;
+
+  // By-id identity entry (read by `useUserById`). Not viewer-scoped — never store
+  // the viewer-relative `relationship` here or one viewer's follow state leaks
+  // into every other viewer's by-id cache entry.
+  upsertOneKey(queryClient, queryKeys.users.detail(incoming.id), incoming, {
+    includeRelationship: false,
+  });
+
+  const username = incoming.username;
+  if (typeof username === 'string' && username.trim() !== '') {
+    // By-username entry (read by `useUserByUsername`). Viewer-scoped because the
+    // authenticated single-profile fetch embeds the viewer `relationship`. Build
+    // the key through the SAME helper the hook uses so username normalization
+    // (`trim().toLowerCase()`) matches byte-for-byte.
+    const key = queryKeys.users.byUsername(username, resolveViewerId(viewerId));
+    upsertOneKey(queryClient, key, incoming, { includeRelationship: true });
+  }
+}
+
+/**
+ * Batch merge-upsert many users at once (for a feed / list / search response).
+ * Resolves the viewer id once and upserts each user cumulatively — a user that
+ * appears twice merges both slices into the single cache entry.
+ */
+export function upsertCachedUsers(
+  queryClient: QueryClient,
+  users: readonly CacheableUser[] | null | undefined,
+  viewerId?: string,
+): void {
+  if (!Array.isArray(users) || users.length === 0) return;
+  const resolvedViewerId = resolveViewerId(viewerId);
+  for (const user of users) {
+    if (user) upsertCachedUser(queryClient, user, resolvedViewerId);
+  }
+}

package/src/ui/hooks/useAvatarPicker.ts

@@ -100,11 +100,19 @@ export function useAvatarPicker({
   );
 
   /**
-   * After the user picks a file in the FileManagement sheet, route to the
-   * crop screen with the file's download URL as the source image.
+   * After the user picks a file in the FileManagement sheet, resolve a working
+   * source URL and route to the crop screen.
+   *
+   * The picked file is usually PRIVATE, so the synchronous
+   * `getFileDownloadUrl` (public CDN origin) would 404 and the crop screen's
+   * `Image.getSize` would fail silently. We resolve the authenticated URL via
+   * `assetGetUrl` (which throws on failure — unlike `getFileDownloadUrlAsync`,
+   * which swallows errors and falls back to the broken public URL) so a
+   * failure surfaces a real user-facing error instead of a blank crop canvas.
+   * No variant is requested — cropping needs the original.
    */
   const handleFilePicked = useCallback(
-    (file: FileMetadata) => {
+    async (file: FileMetadata) => {
       if (!file.contentType?.startsWith('image/')) {
         toast.error(
           translate(currentLanguage ?? undefined, 'editProfile.toasts.selectImage') ||
@@ -113,10 +121,22 @@ export function useAvatarPicker({
         return;
       }
 
-      // Use the public download URL of the picked file as the crop source.
-      // The OxyServices file URL endpoints accept image variants, but for
-      // cropping we want the original — passing no variant returns it.
-      const sourceUri = oxyServices.getFileDownloadUrl(file.id);
+      let sourceUri: string;
+      try {
+        const resolved = await oxyServices.assetGetUrl(file.id);
+        if (!resolved?.url) {
+          throw new Error('No download URL returned for the selected image');
+        }
+        sourceUri = resolved.url;
+      } catch (e: unknown) {
+        const message = e instanceof Error ? e.message : undefined;
+        toast.error(
+          message ||
+            translate(currentLanguage ?? undefined, 'editProfile.toasts.cropMeasureFailed') ||
+            'Could not load the selected image',
+        );
+        return;
+      }
 
       showBottomSheet({
         screen: 'AvatarCrop',

package/src/ui/hooks/useFileDownloadUrl.ts

@@ -15,8 +15,9 @@ export interface UseFileDownloadUrlResult {
 /**
  * Hook to resolve a file's download URL asynchronously.
  *
- * Uses `getFileDownloadUrlAsync` first, falling back to the synchronous
- * `getFileDownloadUrl` if the async call fails.
+ * Uses `getFileDownloadUrlAsync`, which returns a scoped media-token stream URL
+ * for private assets. There is no sync CDN fallback — the synchronous
+ * `getFileDownloadUrl` is public-CDN-only and 404s for private uploads.
  */
 export const useFileDownloadUrl = (
   oxyServices: OxyServices | null | undefined,
@@ -54,35 +55,18 @@ export const useFileDownloadUrl = (
       setError(null);
 
       try {
-        let resolvedUrl: string | null = null;
-
-        if (typeof instance.getFileDownloadUrlAsync === 'function') {
-          resolvedUrl = await instance.getFileDownloadUrlAsync(targetFileId, variant, expiresIn);
+        if (typeof instance.getFileDownloadUrlAsync !== 'function') {
+          throw new Error('getFileDownloadUrlAsync is not available on this OxyServices instance');
         }
 
-        if (!resolvedUrl && typeof instance.getFileDownloadUrl === 'function') {
-          resolvedUrl = instance.getFileDownloadUrl(targetFileId, variant, expiresIn);
-        }
+        const resolvedUrl = await instance.getFileDownloadUrlAsync(targetFileId, variant, expiresIn);
 
         if (!cancelled) {
           setUrl(resolvedUrl || null);
         }
       } catch (err: unknown) {
-        // Fallback to sync URL on error where possible
-        try {
-          if (typeof instance.getFileDownloadUrl === 'function') {
-            const fallbackUrl = instance.getFileDownloadUrl(targetFileId, variant, expiresIn);
-            if (!cancelled) {
-              setUrl(fallbackUrl || null);
-              setError(err instanceof Error ? err : new Error(String(err)));
-            }
-            return;
-          }
-        } catch {
-          // Secondary failure: surface the original error below.
-        }
-
         if (!cancelled) {
+          setUrl(null);
           setError(err instanceof Error ? err : new Error(String(err)));
         }
       } finally {

package/src/ui/hooks/useResolvedFileUrls.ts

@@ -0,0 +1,170 @@
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { FileMetadata } from '@oxyhq/core';
+
+/**
+ * The variant-aware batch resolver contract (`@oxyhq/core`).
+ *
+ * `getFileDownloadUrls` takes a per-file `{ fileId, variant }` list and returns
+ * a map keyed by `fileId`; ids that are denied or missing are OMITTED (never an
+ * empty string), and PRIVATE assets resolve to a working scoped-media-token
+ * stream URL. Typed here rather than `Pick<OxyServices, …>` so this file states
+ * the exact contract it depends on.
+ */
+export interface AssetUrlBatchResolver {
+  getFileDownloadUrls(
+    requests: Array<{ fileId: string; variant?: string }>,
+    options?: { expiresIn?: number; context?: string },
+  ): Promise<Record<string, string>>;
+}
+
+/**
+ * Private-safe grid/thumbnail URL resolution.
+ *
+ * The synchronous `oxyServices.getFileDownloadUrl(id, variant)` always yields
+ * the public CDN origin (`cloud.oxy.so/<id>`), which 404s for PRIVATE assets —
+ * and uploads default to private. Thumbnails and previews therefore have to be
+ * resolved through the authenticated batch endpoint, which returns a working
+ * `/assets/:id/stream?…&mt=<scoped media token>` URL for private files.
+ *
+ * This hook resolves an ENTIRE page of files in ONE (chunked) batch request
+ * rather than N per-tile calls, and caches the result in React Query keyed by
+ * the (fileId, variant) set. `staleTime` is deliberately shorter than the
+ * server media-token TTL so a tile never renders a URL whose token has already
+ * expired.
+ *
+ * Optimistic (`temp-…` / `uploading`) entries are NEVER resolved here — an
+ * asset URL must never be built from an id the server does not yet know. Their
+ * preview comes from the locally-picked uri (see {@link fileThumbSource}).
+ */
+
+/** Server media-token lifetime we request for each resolved URL (seconds). */
+const ASSET_URL_TTL_SECONDS = 600; // 10 minutes
+/**
+ * Refresh window. Kept below {@link ASSET_URL_TTL_SECONDS} so React Query
+ * re-resolves in the background before a rendered URL's token can die.
+ */
+const ASSET_URL_STALE_MS = 5 * 60 * 1000; // 5 minutes
+const ASSET_URL_GC_MS = 30 * 60 * 1000;
+/** Server-side batch cap for `POST /assets/batch-access` — chunk beyond this. */
+const BATCH_CAP = 100;
+
+/** React Query prefix — scoped media URLs must never leak across accounts. */
+export const ASSET_DOWNLOAD_URLS_QUERY_KEY = 'assetDownloadUrls' as const;
+
+/**
+ * True when a file is an optimistic placeholder that has not been persisted by
+ * the server yet — either its id is still the client-minted `temp-…` id, or it
+ * carries the `uploading` flag. Mirrors the `temp-` id guard precedent in
+ * `@oxyhq/core`'s `avatarUtils.updateAvatarVisibility`.
+ */
+export function isOptimisticFile(file: Pick<FileMetadata, 'id' | 'metadata'>): boolean {
+  if (typeof file.id === 'string' && file.id.startsWith('temp-')) return true;
+  return file.metadata?.uploading === true;
+}
+
+/** Grid thumbnail variant for a file, or `undefined` when it needs no URL. */
+function thumbVariantFor(file: FileMetadata): string | undefined {
+  if (file.contentType.startsWith('video/')) return 'poster';
+  if (file.contentType.startsWith('image/')) return 'thumb';
+  return undefined;
+}
+
+/**
+ * Locally-picked preview uri stashed on an optimistic entry's metadata by the
+ * upload flow, if present.
+ */
+function localPreviewUri(file: FileMetadata): string | undefined {
+  const uri = (file.metadata as Record<string, unknown> | undefined)?.localPreviewUri;
+  return typeof uri === 'string' && uri.length > 0 ? uri : undefined;
+}
+
+/**
+ * Resolve the image source for a grid tile.
+ *
+ * - Optimistic entry → its locally-picked preview uri (never an asset URL).
+ * - Persisted entry → the private-safe URL from {@link useResolvedFileUrls},
+ *   or `undefined` while it is still resolving / was denied (tile shows a
+ *   placeholder instead of a guaranteed-404 CDN URL).
+ */
+export function fileThumbSource(
+  file: FileMetadata,
+  resolved: ReadonlyMap<string, string>,
+): string | undefined {
+  if (isOptimisticFile(file)) {
+    return localPreviewUri(file);
+  }
+  return resolved.get(file.id);
+}
+
+/**
+ * Batch-resolve private-safe thumbnail URLs for the given files.
+ *
+ * Only image/video, non-optimistic files are resolved (documents render an
+ * icon, optimistic entries render their local preview). Returns a stable
+ * `Map<fileId, url>`; missing entries mean "not resolved yet or access denied".
+ */
+export function useResolvedFileUrls(
+  oxyServices: AssetUrlBatchResolver,
+  files: FileMetadata[],
+  /** Active viewer account id — media tokens are minted per user; must be in the query key. */
+  viewerId?: string | null,
+): ReadonlyMap<string, string> {
+  const viewerKey = viewerId ?? '';
+  const requests = useMemo(() => {
+    const list: Array<{ fileId: string; variant?: string }> = [];
+    for (const file of files) {
+      if (isOptimisticFile(file)) continue;
+      const variant = thumbVariantFor(file);
+      if (!variant) continue;
+      list.push({ fileId: file.id, variant });
+    }
+    return list;
+  }, [files]);
+
+  // A content signature so the query key is stable across renders while the
+  // resolvable set is unchanged (the `files` array is a fresh reference every
+  // render). Sorted so ordering churn does not force a refetch.
+  const signature = useMemo(
+    () => requests.map((r) => `${r.fileId}:${r.variant ?? ''}`).sort().join('|'),
+    [requests],
+  );
+
+  const query = useQuery({
+    queryKey: [ASSET_DOWNLOAD_URLS_QUERY_KEY, viewerKey, signature],
+    enabled: requests.length > 0 && viewerKey.length > 0,
+    staleTime: ASSET_URL_STALE_MS,
+    gcTime: ASSET_URL_GC_MS,
+    // Keep previously-resolved URLs on screen while the SAME viewer's file set
+    // grows (pagination), but never carry another account's scoped media tokens
+    // across a switch — `keepPreviousData` alone would do that.
+    placeholderData: (previousData, previousQuery) => {
+      if (!previousData || !previousQuery) return undefined;
+      const prevViewer = previousQuery.queryKey[1];
+      if (prevViewer !== viewerKey) return undefined;
+      return previousData;
+    },
+    queryFn: async (): Promise<Record<string, string>> => {
+      const merged: Record<string, string> = {};
+      for (let i = 0; i < requests.length; i += BATCH_CAP) {
+        const chunk = requests.slice(i, i + BATCH_CAP);
+        const urls = await oxyServices.getFileDownloadUrls(chunk, {
+          expiresIn: ASSET_URL_TTL_SECONDS,
+        });
+        Object.assign(merged, urls);
+      }
+      return merged;
+    },
+  });
+
+  return useMemo(() => {
+    const map = new Map<string, string>();
+    const data = query.data;
+    if (data) {
+      for (const [id, url] of Object.entries(data)) {
+        if (typeof url === 'string' && url.length > 0) map.set(id, url);
+      }
+    }
+    return map;
+  }, [query.data]);
+}