@oxyhq/auth 2.0.4 → 2.0.6

package/src/hooks/queries/useAppData.ts

@@ -0,0 +1,105 @@
+/**
+ * App-Data Query Hooks
+ *
+ * Read side of the `/users/me/app-data/...` per-user JSON KV store. Gated on
+ * `isAuthenticated` — when signed out the query stays `enabled: false` and
+ * `data` is `null`, so consumers can fall back to localStorage without ever
+ * issuing a doomed request.
+ *
+ * Errors from the network (404 because the endpoint isn't deployed yet,
+ * 401 because the session lapsed, etc.) are not user-facing here. Hooks
+ * return `data: null` on error so the calling component renders the
+ * "nothing yet" state and the consuming app can quietly fall back to local
+ * persistence. Mutations still propagate errors so write attempts surface
+ * a toast — only reads are silent.
+ */
+
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { authenticatedApiCall } from '@oxyhq/core';
+import { useWebOxy } from '../../WebOxyProvider';
+import { appDataQueryKeys, isMissingAppDataEndpointError } from './appDataQueryKeys';
+
+interface AppDataQueryOptions {
+  /** Disable the query without unmounting the component. */
+  enabled?: boolean;
+  /** Override the default 1-minute stale time. */
+  staleTime?: number;
+  /** Override the default 30-minute gc time. */
+  gcTime?: number;
+}
+
+/**
+ * Read a single per-user JSON value.
+ *
+ * @param namespace - kebab/snake-case identifier (e.g. `"academy"`).
+ * @param key       - kebab/snake-case identifier (e.g. course slug).
+ * @param options   - optional `enabled`/`staleTime`/`gcTime` overrides.
+ *
+ * @returns A `useQuery` result with `data` of type `T | null`. The query
+ *   stays disabled when the user is signed out; when enabled but the server
+ *   has no stored value, `data` is `null`. Reads that fail because the
+ *   endpoint isn't reachable also resolve to `null` so the consumer can
+ *   fall back to local persistence.
+ */
+export const useAppData = <T = unknown>(
+  namespace: string,
+  key: string,
+  options?: AppDataQueryOptions,
+): UseQueryResult<T | null, Error> => {
+  const { oxyServices, activeSessionId, isAuthenticated } = useWebOxy();
+
+  return useQuery<T | null, Error>({
+    queryKey: appDataQueryKeys.value(namespace, key),
+    queryFn: async () => {
+      try {
+        return await authenticatedApiCall(oxyServices, activeSessionId, () =>
+          oxyServices.getAppData<T>(namespace, key),
+        );
+      } catch (error) {
+        // Endpoint not deployed yet, no network, etc. — return null so the
+        // consumer falls back to localStorage rather than rendering a broken
+        // UI state. Authentication errors still bubble up so the auth retry
+        // pipeline can surface them at the provider level.
+        if (isMissingAppDataEndpointError(error)) {
+          return null;
+        }
+        throw error;
+      }
+    },
+    enabled: (options?.enabled !== false) && isAuthenticated,
+    staleTime: options?.staleTime ?? 60 * 1000,
+    gcTime: options?.gcTime ?? 30 * 60 * 1000,
+  });
+};
+
+/**
+ * Read every value in a namespace.
+ *
+ * @returns A `useQuery` result with `data` as a `Record<string, T>`. Empty
+ *   object when the namespace contains nothing (or when fetching failed).
+ */
+export const useAppDataNamespace = <T = unknown>(
+  namespace: string,
+  options?: AppDataQueryOptions,
+): UseQueryResult<Record<string, T>, Error> => {
+  const { oxyServices, activeSessionId, isAuthenticated } = useWebOxy();
+
+  return useQuery<Record<string, T>, Error>({
+    queryKey: appDataQueryKeys.namespace(namespace),
+    queryFn: async () => {
+      try {
+        return await authenticatedApiCall(oxyServices, activeSessionId, () =>
+          oxyServices.listAppData<T>(namespace),
+        );
+      } catch (error) {
+        if (isMissingAppDataEndpointError(error)) {
+          return {};
+        }
+        throw error;
+      }
+    },
+    enabled: (options?.enabled !== false) && isAuthenticated,
+    staleTime: options?.staleTime ?? 60 * 1000,
+    gcTime: options?.gcTime ?? 30 * 60 * 1000,
+  });
+};

package/src/hooks/queryClient.ts

@@ -1,112 +1,169 @@
-import { QueryClient } from '@tanstack/react-query';
+/**
+ * Web QueryClient with offline-first defaults + localStorage persistence.
+ *
+ * Mirrors the persistence behaviour in `@oxyhq/services/queryClient` so
+ * web auth apps (FedCM, popup, redirect flows) survive a page reload with
+ * cached identity + paused mutations intact.
+ *
+ * Persistence is opt-in via `attachQueryPersistence(...)` so SSR callers
+ * (Next.js getServerSideProps, Vite SSR, tests) can create a stateless
+ * client without touching `window`.
+ */
+
+import { QueryClient, type Mutation, type Query } from '@tanstack/react-query';
+import {
+  persistQueryClient,
+  type PersistedClient,
+} from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
 import type { StorageInterface } from '../utils/storageHelpers';
 
-const QUERY_CACHE_KEY = 'oxy_query_cache';
-const QUERY_CACHE_VERSION = '1';
+const QUERY_CACHE_KEY = 'oxy_auth_query_cache_v2';
+const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000;
+const QUERY_PERSIST_THROTTLE_MS = 1_000;
+
+/**
+ * Query-key prefixes whose data is safe to restore across reloads.
+ * Web auth surfaces are session/profile heavy — lists and history are not
+ * persisted to keep the localStorage footprint small.
+ */
+const PERSISTED_QUERY_PREFIXES: ReadonlyArray<string> = [
+  'accounts',
+  'users',
+  'sessions',
+  'auth',
+];
+
+function shouldDehydrateQuery(query: Query): boolean {
+  if (query.state.status !== 'success') return false;
+  const head = query.queryKey[0];
+  return typeof head === 'string' && PERSISTED_QUERY_PREFIXES.includes(head);
+}
+
+function shouldDehydrateMutation(_mutation: Mutation): boolean {
+  return true;
+}
 
 /**
- * Custom persistence adapter for TanStack Query using our StorageInterface
+ * Best-effort detection — works in browsers, Node SSR, and React Server
+ * Components. `localStorage` is gated behind `window` because Node and edge
+ * runtimes may polyfill `globalThis.localStorage` inconsistently.
  */
-export const createPersistenceAdapter = (storage: StorageInterface) => {
-  return {
-    persistClient: async (client: any) => {
-      try {
-        const serialized = JSON.stringify({
-          clientState: client,
-          timestamp: Date.now(),
-          version: QUERY_CACHE_VERSION,
-        });
-        await storage.setItem(QUERY_CACHE_KEY, serialized);
-      } catch (error) {
-        if (process.env.NODE_ENV !== 'production') {
-          console.warn('[QueryClient] Failed to persist cache:', error);
-        }
+function getBrowserLocalStorage(): Storage | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    if (!window.localStorage) return null;
+    return window.localStorage;
+  } catch {
+    // Access blocked (Safari Private Mode, sandboxed iframe, etc.)
+    return null;
+  }
+}
+
+export const createPersistenceAdapter = (storage: StorageInterface) => ({
+  persistClient: async (client: unknown): Promise<void> => {
+    try {
+      await storage.setItem(QUERY_CACHE_KEY, JSON.stringify(client));
+    } catch (error) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[QueryClient] Failed to persist cache', error);
       }
-    },
-    restoreClient: async () => {
-      try {
-        const cached = await storage.getItem(QUERY_CACHE_KEY);
-        if (!cached) return undefined;
-
-        const parsed = JSON.parse(cached);
-        
-        // Check version compatibility
-        if (parsed.version !== QUERY_CACHE_VERSION) {
-          // Clear old cache on version mismatch
-          await storage.removeItem(QUERY_CACHE_KEY);
-          return undefined;
-        }
-
-        // Check if cache is too old (30 days)
-        const maxAge = 30 * 24 * 60 * 60 * 1000;
-        if (parsed.timestamp && Date.now() - parsed.timestamp > maxAge) {
-          await storage.removeItem(QUERY_CACHE_KEY);
-          return undefined;
-        }
-
-        return parsed.clientState;
-      } catch (error) {
-        if (process.env.NODE_ENV !== 'production') {
-          console.warn('[QueryClient] Failed to restore cache:', error);
-        }
-        return undefined;
+    }
+  },
+  restoreClient: async (): Promise<unknown> => {
+    try {
+      const cached = await storage.getItem(QUERY_CACHE_KEY);
+      return cached ? JSON.parse(cached) : undefined;
+    } catch (error) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[QueryClient] Failed to restore cache', error);
       }
-    },
-    removeClient: async () => {
-      try {
-        await storage.removeItem(QUERY_CACHE_KEY);
-      } catch (error) {
-        if (process.env.NODE_ENV !== 'production') {
-          console.warn('[QueryClient] Failed to remove cache:', error);
-        }
+      return undefined;
+    }
+  },
+  removeClient: async (): Promise<void> => {
+    try {
+      await storage.removeItem(QUERY_CACHE_KEY);
+    } catch (error) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[QueryClient] Failed to remove cache', error);
       }
-    },
-  };
-};
+    }
+  },
+});
 
-/**
- * Create a QueryClient with offline-first configuration
- */
-export const createQueryClient = (storage?: StorageInterface | null): QueryClient => {
-  const client = new QueryClient({
+export const createQueryClient = (): QueryClient =>
+  new QueryClient({
     defaultOptions: {
       queries: {
-        // Data is fresh for 5 minutes
         staleTime: 5 * 60 * 1000,
-        // Keep unused data in cache for 10 minutes
-        gcTime: 10 * 60 * 1000,
-        // Retry 3 times with exponential backoff
+        gcTime: 30 * 60 * 1000,
         retry: 3,
-        retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
-        // Refetch on reconnect
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
         refetchOnReconnect: true,
-        // Don't refetch on window focus (better for mobile)
         refetchOnWindowFocus: false,
-        // Offline-first: use cache when offline
         networkMode: 'offlineFirst',
       },
       mutations: {
-        // Retry once for mutations
         retry: 1,
-        // Offline-first: queue mutations when offline
         networkMode: 'offlineFirst',
       },
     },
   });
 
-  // Note: Persistence is handled by TanStack Query's built-in persistence
-  // For now, we rely on the query client's default behavior with networkMode: 'offlineFirst'
-  // The cache will be available in memory and queries will use cached data when offline
-  // Full persistence to AsyncStorage can be added later with @tanstack/react-query-persist-client if needed
-
-  return client;
-};
+export interface AttachPersistenceResult {
+  restored: Promise<void>;
+  unsubscribe: () => void;
+}
 
 /**
- * Clear persisted query cache
+ * Wire `persistQueryClient` to browser `localStorage` (or a no-op when not
+ * in a browser). Returns the restore promise so consumers can `await` it
+ * before exposing the client to <Suspense> boundaries.
  */
-export const clearQueryCache = async (storage: StorageInterface): Promise<void> => {
-  const adapter = createPersistenceAdapter(storage);
-  await adapter.removeClient();
+export const attachQueryPersistence = (
+  queryClient: QueryClient,
+): AttachPersistenceResult => {
+  const localStorage = getBrowserLocalStorage();
+  if (!localStorage) {
+    return { restored: Promise.resolve(), unsubscribe: () => {} };
+  }
+
+  const persister = createSyncStoragePersister({
+    storage: localStorage,
+    key: QUERY_CACHE_KEY,
+    throttleTime: QUERY_PERSIST_THROTTLE_MS,
+  });
+
+  const [unsubscribe, restored] = persistQueryClient({
+    queryClient,
+    persister,
+    maxAge: QUERY_CACHE_MAX_AGE,
+    dehydrateOptions: {
+      shouldDehydrateQuery,
+      shouldDehydrateMutation,
+    },
+  });
+
+  restored.catch((error) => {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('[QueryClient] Failed to restore persisted cache', error);
+    }
+  });
+
+  return { unsubscribe, restored };
+};
+
+export const clearQueryCache = async (
+  storage: StorageInterface,
+): Promise<void> => {
+  try {
+    await storage.removeItem(QUERY_CACHE_KEY);
+  } catch (error) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('[QueryClient] Failed to remove cache', error);
+    }
+  }
 };
 
+export type { PersistedClient };

package/src/hooks/useFileDownloadUrl.ts

@@ -1,11 +1,5 @@
 import { useEffect, useState } from 'react';
-import { OxyServices } from '@oxyhq/core';
-
-let oxyInstance: OxyServices | null = null;
-
-export const setOxyFileUrlInstance = (instance: OxyServices) => {
-  oxyInstance = instance;
-};
+import type { OxyServices } from '@oxyhq/core';
 
 export interface UseFileDownloadUrlOptions {
   variant?: string;
@@ -21,38 +15,21 @@ export interface UseFileDownloadUrlResult {
 /**
  * Hook to resolve a file's download URL asynchronously.
  *
- * Prefers the provided `oxyServices` instance, falls back to the module-level
- * singleton set via `setOxyFileUrlInstance`.
- *
  * Uses `getFileDownloadUrlAsync` first, falling back to the synchronous
  * `getFileDownloadUrl` if the async call fails.
  */
 export const useFileDownloadUrl = (
-  fileIdOrServices?: string | OxyServices | null,
-  fileIdOrOptions?: string | UseFileDownloadUrlOptions | null,
-  maybeOptions?: UseFileDownloadUrlOptions
+  oxyServices: OxyServices | null | undefined,
+  fileId: string | null | undefined,
+  options?: UseFileDownloadUrlOptions,
 ): UseFileDownloadUrlResult => {
-  // Support two call signatures:
-  // 1. useFileDownloadUrl(oxyServices, fileId, options)  — preferred
-  // 2. useFileDownloadUrl(fileId, options)               — legacy (uses singleton)
-  let services: OxyServices | null;
-  let fileId: string | null | undefined;
-  let options: UseFileDownloadUrlOptions | undefined;
-
-  if (fileIdOrServices instanceof OxyServices) {
-    services = fileIdOrServices;
-    fileId = typeof fileIdOrOptions === 'string' ? fileIdOrOptions : null;
-    options = maybeOptions;
-  } else {
-    services = oxyInstance;
-    fileId = typeof fileIdOrServices === 'string' ? fileIdOrServices : null;
-    options = typeof fileIdOrOptions === 'object' && fileIdOrOptions !== null ? fileIdOrOptions as UseFileDownloadUrlOptions : undefined;
-  }
-
   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;
+
   useEffect(() => {
     if (!fileId) {
       setUrl(null);
@@ -61,7 +38,7 @@ export const useFileDownloadUrl = (
       return;
     }
 
-    if (!services) {
+    if (!oxyServices) {
       setUrl(null);
       setLoading(false);
       setError(new Error('OxyServices instance not configured for useFileDownloadUrl'));
@@ -69,22 +46,22 @@ export const useFileDownloadUrl = (
     }
 
     let cancelled = false;
-    const instance = services;
+    const instance = oxyServices;
+    const targetFileId = fileId;
 
     const load = async () => {
       setLoading(true);
       setError(null);
 
       try {
-        const { variant, expiresIn } = options || {};
         let resolvedUrl: string | null = null;
 
         if (typeof instance.getFileDownloadUrlAsync === 'function') {
-          resolvedUrl = await instance.getFileDownloadUrlAsync(fileId!, variant, expiresIn);
+          resolvedUrl = await instance.getFileDownloadUrlAsync(targetFileId, variant, expiresIn);
         }
 
         if (!resolvedUrl && typeof instance.getFileDownloadUrl === 'function') {
-          resolvedUrl = instance.getFileDownloadUrl(fileId!, variant, expiresIn);
+          resolvedUrl = instance.getFileDownloadUrl(targetFileId, variant, expiresIn);
         }
 
         if (!cancelled) {
@@ -94,8 +71,7 @@ export const useFileDownloadUrl = (
         // Fallback to sync URL on error where possible
         try {
           if (typeof instance.getFileDownloadUrl === 'function') {
-            const { variant, expiresIn } = options || {};
-            const fallbackUrl = instance.getFileDownloadUrl(fileId!, variant, expiresIn);
+            const fallbackUrl = instance.getFileDownloadUrl(targetFileId, variant, expiresIn);
             if (!cancelled) {
               setUrl(fallbackUrl || null);
               setError(err instanceof Error ? err : new Error(String(err)));
@@ -103,7 +79,7 @@ export const useFileDownloadUrl = (
             return;
           }
         } catch {
-          // ignore secondary failure
+          // Secondary failure: surface the original error below.
         }
 
         if (!cancelled) {
@@ -121,7 +97,7 @@ export const useFileDownloadUrl = (
     return () => {
       cancelled = true;
     };
-  }, [fileId, services, options?.variant, options?.expiresIn]);
+  }, [fileId, oxyServices, variant, expiresIn]);
 
   return { url, loading, error };
 };