@oxy.so/services 13.1.0 → 13.3.0

package/src/ui/hooks/useFileDownloadUrl.ts

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import type { OxyServices } from '@oxy.so/core';
+import { useOptionalOxy } from '../context/oxyRuntimeContext';
 
 export interface UseFileDownloadUrlOptions {
   variant?: string;
@@ -12,72 +13,81 @@ export interface UseFileDownloadUrlResult {
   error: Error | null;
 }
 
+interface Settled {
+  request: string;
+  url: string | null;
+  error: Error | null;
+}
+
+function isAbsoluteUrl(ref: string): boolean {
+  return ref.startsWith('http://') || ref.startsWith('https://');
+}
+
 /**
- * Hook to resolve a file's download URL asynchronously.
+ * Resolve a file's download URL for the current caller.
  *
- * 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.
+ * A URL `assets.url` already resolved is answered in the FIRST render from
+ * core's identity-scoped cache (`assets.cachedUrl`): no request, no loading
+ * frame. Only a miss resolves asynchronously, through `assets.url`, which
+ * returns a scoped media-token stream URL for a private asset. There is no
+ * public-CDN fallback: `assets.publicUrl` 404s for private uploads. A
+ * reference that is already an absolute `http(s)` URL is returned unchanged.
+ *
+ * For a synchronous, render-only answer (an image resolver, a list row) use
+ * `oxyServices.assets.renderUrl`, which reads the same cache.
  */
 export const useFileDownloadUrl = (
   oxyServices: OxyServices | null | undefined,
   fileId: string | null | undefined,
   options?: UseFileDownloadUrlOptions,
 ): UseFileDownloadUrlResult => {
-  const [url, setUrl] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
   const variant = options?.variant;
   const expiresIn = options?.expiresIn;
+  // A resolved URL can carry the viewer's scoped media token, so the viewer is
+  // part of what was asked: an account switch never shows the previous one's.
+  const viewerId = useOptionalOxy()?.user?.id ?? '';
+  const request = fileId ? `${viewerId}|${fileId}|${variant ?? ''}|${expiresIn ?? ''}` : null;
+  const immediate = !fileId
+    ? null
+    : isAbsoluteUrl(fileId)
+      ? fileId
+      : (oxyServices?.assets.cachedUrl(fileId, variant, expiresIn) ?? null);
+  const needsResolve = !!fileId && !!oxyServices && immediate === null;
 
-  useEffect(() => {
-    if (!fileId) {
-      setUrl(null);
-      setLoading(false);
-      setError(null);
-      return;
-    }
-
-    if (!oxyServices) {
-      setUrl(null);
-      setLoading(false);
-      setError(new Error('OxyServices instance not configured for useFileDownloadUrl'));
-      return;
-    }
+  const [settled, setSettled] = useState<Settled | null>(null);
 
+  useEffect(() => {
+    if (!needsResolve || !fileId || !oxyServices || !request) return;
     let cancelled = false;
-    const instance = oxyServices;
-    const targetFileId = fileId;
-
-    const load = async () => {
-      setLoading(true);
-      setError(null);
-
-      try {
-        const resolvedUrl = await instance.assets.url(targetFileId, variant, expiresIn);
-
+    oxyServices.assets.url(fileId, variant, expiresIn).then(
+      (url) => {
+        if (!cancelled) setSettled({ request, url: url || null, error: null });
+      },
+      (err: unknown) => {
         if (!cancelled) {
-          setUrl(resolvedUrl || null);
+          setSettled({
+            request,
+            url: null,
+            error: err instanceof Error ? err : new Error(String(err)),
+          });
         }
-      } catch (err: unknown) {
-        if (!cancelled) {
-          setUrl(null);
-          setError(err instanceof Error ? err : new Error(String(err)));
-        }
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    };
-
-    load();
-
+      },
+    );
     return () => {
       cancelled = true;
     };
-  }, [fileId, oxyServices, variant, expiresIn]);
+  }, [needsResolve, fileId, oxyServices, variant, expiresIn, request]);
 
-  return { url, loading, error };
+  if (!fileId) return { url: null, loading: false, error: null };
+  if (immediate !== null) return { url: immediate, loading: false, error: null };
+  if (!oxyServices) {
+    return {
+      url: null,
+      loading: false,
+      error: new Error('OxyServices instance not configured for useFileDownloadUrl'),
+    };
+  }
+  // A result settled for another file, variant or expiry is never shown.
+  if (settled?.request !== request) return { url: null, loading: true, error: null };
+  return { url: settled.url, loading: false, error: settled.error };
 };

package/src/ui/index.ts

@@ -34,7 +34,7 @@ export { LogoText } from './components/logo/LogoText';
 export { RequireOxyAuth } from './components/RequireOxyAuth';
 export type { RequireOxyAuthProps, RequireOxyAuthPrompt } from './components/RequireOxyAuth';
 // `OxyProvider`'s `accountQueries`: the app's per-account offline cache.
-export type { AccountQueriesConfig } from './hooks/accountQueryPersistence';
+export type { AccountQueriesConfig, AccountQueryMeta } from './hooks/accountQueryPersistence';
 export { default as FollowButton } from './components/FollowButton';
 export { default as PeableButton } from './components/PeableButton';
 export type { PeableButtonProps } from './components/PeableButton';

package/src/ui/types/navigation.ts

@@ -150,6 +150,8 @@ export interface OxyProviderProps {
    * account switch and deleted on sign-out. `RequireOxyAuth` waits for the
    * signed-in account's cache to restore, so another account's rows never
    * render. Works with the SDK's client or one passed as `queryClient`.
+   * A single query opts in with `meta: { persist: 'account' }` and needs no
+   * declaration here (`AccountQueryMeta`).
    */
   accountQueries?: AccountQueriesConfig;
   /**