@oxyhq/auth 2.0.4 → 2.0.6

package/dist/esm/hooks/queryClient.js

@@ -1,104 +1,147 @@
+/**
+ * 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 } from '@tanstack/react-query';
-const QUERY_CACHE_KEY = 'oxy_query_cache';
-const QUERY_CACHE_VERSION = '1';
+import { persistQueryClient, } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+const QUERY_CACHE_KEY = 'oxy_auth_query_cache_v2';
+const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000;
+const QUERY_PERSIST_THROTTLE_MS = 1000;
 /**
- * Custom persistence adapter for TanStack Query using our StorageInterface
+ * 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.
  */
-export const createPersistenceAdapter = (storage) => {
-    return {
-        persistClient: async (client) => {
-            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);
-                }
+const PERSISTED_QUERY_PREFIXES = [
+    'accounts',
+    'users',
+    'sessions',
+    'auth',
+];
+function shouldDehydrateQuery(query) {
+    if (query.state.status !== 'success')
+        return false;
+    const head = query.queryKey[0];
+    return typeof head === 'string' && PERSISTED_QUERY_PREFIXES.includes(head);
+}
+function shouldDehydrateMutation(_mutation) {
+    return true;
+}
+/**
+ * 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.
+ */
+function getBrowserLocalStorage() {
+    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) => ({
+    persistClient: async (client) => {
+        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;
+        }
+    },
+    restoreClient: async () => {
+        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);
             }
-            catch (error) {
-                if (process.env.NODE_ENV !== 'production') {
-                    console.warn('[QueryClient] Failed to restore cache:', error);
-                }
-                return undefined;
+            return undefined;
+        }
+    },
+    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);
             }
+        }
+    },
+});
+export const createQueryClient = () => new QueryClient({
+    defaultOptions: {
+        queries: {
+            staleTime: 5 * 60 * 1000,
+            gcTime: 30 * 60 * 1000,
+            retry: 3,
+            retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
+            refetchOnReconnect: true,
+            refetchOnWindowFocus: false,
+            networkMode: 'offlineFirst',
         },
-        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);
-                }
-            }
+        mutations: {
+            retry: 1,
+            networkMode: 'offlineFirst',
         },
-    };
-};
+    },
+});
 /**
- * Create a QueryClient with offline-first configuration
+ * 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 createQueryClient = (storage) => {
-    const client = 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
-                retry: 3,
-                retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
-                // Refetch on reconnect
-                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',
-            },
+export const attachQueryPersistence = (queryClient) => {
+    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,
         },
     });
-    // 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;
+    restored.catch((error) => {
+        if (process.env.NODE_ENV !== 'production') {
+            console.warn('[QueryClient] Failed to restore persisted cache', error);
+        }
+    });
+    return { unsubscribe, restored };
 };
-/**
- * Clear persisted query cache
- */
 export const clearQueryCache = async (storage) => {
-    const adapter = createPersistenceAdapter(storage);
-    await adapter.removeClient();
+    try {
+        await storage.removeItem(QUERY_CACHE_KEY);
+    }
+    catch (error) {
+        if (process.env.NODE_ENV !== 'production') {
+            console.warn('[QueryClient] Failed to remove cache', error);
+        }
+    }
 };

package/dist/esm/hooks/useFileDownloadUrl.js

@@ -1,38 +1,16 @@
 import { useEffect, useState } from 'react';
-import { OxyServices } from '@oxyhq/core';
-let oxyInstance = null;
-export const setOxyFileUrlInstance = (instance) => {
-    oxyInstance = instance;
-};
 /**
  * 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, fileIdOrOptions, maybeOptions) => {
-    // Support two call signatures:
-    // 1. useFileDownloadUrl(oxyServices, fileId, options)  — preferred
-    // 2. useFileDownloadUrl(fileId, options)               — legacy (uses singleton)
-    let services;
-    let fileId;
-    let options;
-    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 : undefined;
-    }
+export const useFileDownloadUrl = (oxyServices, fileId, options) => {
     const [url, setUrl] = useState(null);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
+    const variant = options?.variant;
+    const expiresIn = options?.expiresIn;
     useEffect(() => {
         if (!fileId) {
             setUrl(null);
@@ -40,25 +18,25 @@ export const useFileDownloadUrl = (fileIdOrServices, fileIdOrOptions, maybeOptio
             setError(null);
             return;
         }
-        if (!services) {
+        if (!oxyServices) {
             setUrl(null);
             setLoading(false);
             setError(new Error('OxyServices instance not configured for useFileDownloadUrl'));
             return;
         }
         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 = 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) {
                     setUrl(resolvedUrl || null);
@@ -68,8 +46,7 @@ export const useFileDownloadUrl = (fileIdOrServices, fileIdOrOptions, maybeOptio
                 // 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)));
@@ -78,7 +55,7 @@ export const useFileDownloadUrl = (fileIdOrServices, fileIdOrOptions, maybeOptio
                     }
                 }
                 catch {
-                    // ignore secondary failure
+                    // Secondary failure: surface the original error below.
                 }
                 if (!cancelled) {
                     setError(err instanceof Error ? err : new Error(String(err)));
@@ -94,6 +71,6 @@ export const useFileDownloadUrl = (fileIdOrServices, fileIdOrOptions, maybeOptio
         return () => {
             cancelled = true;
         };
-    }, [fileId, services, options?.variant, options?.expiresIn]);
+    }, [fileId, oxyServices, variant, expiresIn]);
     return { url, loading, error };
 };

package/dist/esm/hooks/useSessionSocket.js

@@ -24,7 +24,8 @@ function readTokenFromStorage() {
     try {
         return window.localStorage.getItem(LS_ACCESS_TOKEN_KEY);
     }
-    catch {
+    catch (err) {
+        console.warn('[oxy.session-socket] localStorage read failed:', err);
         return null;
     }
 }
@@ -37,12 +38,12 @@ async function getSocketIO() {
         return null;
     _ioLoadAttempted = true;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const mod = await import('socket.io-client');
-        _io = (mod.io ?? mod.default);
+        const mod = (await import('socket.io-client'));
+        _io = mod.io ?? mod.default ?? null;
         return _io;
     }
-    catch {
+    catch (err) {
+        console.warn('[oxy.session-socket] socket.io-client import failed:', err);
         debug.warn('socket.io-client is not installed. useSessionSocket will be disabled. Install it with: bun add socket.io-client');
         return null;
     }
@@ -109,7 +110,7 @@ export function useSessionSocket(options) {
             // If no token is available at all, we skip the initial connect and let
             // the storage listener or retry logic connect when a token appears.
             const token = resolveToken();
-            socketRef.current = ioFn(baseURL, {
+            const socket = ioFn(baseURL, {
                 transports: ['websocket'],
                 autoConnect: !!token, // don't auto-connect when there is no token
                 auth: (cb) => {
@@ -126,7 +127,7 @@ export function useSessionSocket(options) {
                     cb({ token: resolved });
                 },
             });
-            const socket = socketRef.current;
+            socketRef.current = socket;
             // Server auto-joins the user to `user:<userId>` room on connection
             const handleConnect = () => {
                 debug.log('Socket connected:', socket.id);
@@ -162,110 +163,94 @@ export function useSessionSocket(options) {
                 invalidateSessionQueries(queryClientRef.current);
                 return Promise.resolve();
             };
+            const triggerLocalSignOut = async (toastMessage, errorContext) => {
+                if (onRemoteSignOutRef.current) {
+                    onRemoteSignOutRef.current();
+                }
+                else {
+                    toast.info(toastMessage);
+                }
+                // Clear local state since the server has already removed the session.
+                // Await so storage cleanup completes before any subsequent navigation.
+                try {
+                    await clearSessionStateRef.current();
+                }
+                catch (error) {
+                    if (process.env.NODE_ENV !== 'production') {
+                        logger.error(`Failed to clear session state after ${errorContext}`, error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
+                    }
+                }
+            };
             const handleSessionUpdate = async (data) => {
                 debug.log('Received session_update:', data);
                 const currentActiveSessionId = activeSessionIdRef.current;
                 const deviceId = currentDeviceIdRef.current;
-                // Handle different event types
-                if (data.type === 'session_removed') {
-                    // Track removed session
-                    if (data.sessionId && onSessionRemovedRef.current) {
-                        onSessionRemovedRef.current(data.sessionId);
-                    }
-                    // If the removed sessionId matches the current activeSessionId, immediately clear state
-                    if (data.sessionId === currentActiveSessionId) {
-                        if (onRemoteSignOutRef.current) {
-                            onRemoteSignOutRef.current();
-                        }
-                        else {
-                            toast.info('You have been signed out remotely.');
+                // Strict whitelist. Every event type that may sign the user out must
+                // appear in the switch. Anything unknown falls through to `default`,
+                // which only logs in dev. This guards against future server-side event
+                // additions (e.g. `session_created` after a successful sign-in)
+                // accidentally triggering sign-out via a fallback branch that compares
+                // `data.sessionId === currentActiveSessionId` — that branch would match
+                // the user's NEW session id and trigger an instant remote sign-out
+                // toast on every login.
+                switch (data.type) {
+                    case 'session_removed': {
+                        if (data.sessionId && onSessionRemovedRef.current) {
+                            onSessionRemovedRef.current(data.sessionId);
                         }
-                        try {
-                            await clearSessionStateRef.current();
+                        if (data.sessionId && data.sessionId === currentActiveSessionId) {
+                            await triggerLocalSignOut('You have been signed out remotely.', 'session_removed');
                         }
-                        catch (error) {
-                            if (process.env.NODE_ENV !== 'production') {
-                                logger.error('Failed to clear session state after session_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
-                            }
+                        else {
+                            refreshSessions();
                         }
+                        break;
                     }
-                    else {
-                        refreshSessions();
-                    }
-                }
-                else if (data.type === 'device_removed') {
-                    // Track all removed sessions from this device
-                    if (data.sessionIds && onSessionRemovedRef.current) {
-                        for (const sessionId of data.sessionIds) {
-                            onSessionRemovedRef.current(sessionId);
+                    case 'device_removed': {
+                        if (data.sessionIds && onSessionRemovedRef.current) {
+                            for (const sessionId of data.sessionIds) {
+                                onSessionRemovedRef.current(sessionId);
+                            }
                         }
-                    }
-                    // If the removed deviceId matches the current device, immediately clear state
-                    if (data.deviceId && data.deviceId === deviceId) {
-                        if (onRemoteSignOutRef.current) {
-                            onRemoteSignOutRef.current();
+                        if (data.deviceId && deviceId && data.deviceId === deviceId) {
+                            await triggerLocalSignOut('This device has been removed. You have been signed out.', 'device_removed');
                         }
                         else {
-                            toast.info('This device has been removed. You have been signed out.');
-                        }
-                        try {
-                            await clearSessionStateRef.current();
-                        }
-                        catch (error) {
-                            if (process.env.NODE_ENV !== 'production') {
-                                logger.error('Failed to clear session state after device_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
-                            }
+                            refreshSessions();
                         }
+                        break;
                     }
-                    else {
-                        refreshSessions();
-                    }
-                }
-                else if (data.type === 'sessions_removed') {
-                    // Track all removed sessions
-                    if (data.sessionIds && onSessionRemovedRef.current) {
-                        for (const sessionId of data.sessionIds) {
-                            onSessionRemovedRef.current(sessionId);
+                    case 'sessions_removed': {
+                        if (data.sessionIds && onSessionRemovedRef.current) {
+                            for (const sessionId of data.sessionIds) {
+                                onSessionRemovedRef.current(sessionId);
+                            }
                         }
-                    }
-                    // If the current activeSessionId is in the removed sessionIds list, immediately clear state
-                    if (data.sessionIds && currentActiveSessionId && data.sessionIds.includes(currentActiveSessionId)) {
-                        if (onRemoteSignOutRef.current) {
-                            onRemoteSignOutRef.current();
+                        if (data.sessionIds &&
+                            currentActiveSessionId &&
+                            data.sessionIds.includes(currentActiveSessionId)) {
+                            await triggerLocalSignOut('You have been signed out remotely.', 'sessions_removed');
                         }
                         else {
-                            toast.info('You have been signed out remotely.');
-                        }
-                        try {
-                            await clearSessionStateRef.current();
-                        }
-                        catch (error) {
-                            if (process.env.NODE_ENV !== 'production') {
-                                logger.error('Failed to clear session state after sessions_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
-                            }
+                            refreshSessions();
                         }
+                        break;
                     }
-                    else {
+                    case 'session_created':
+                    case 'session_update': {
+                        // Lifecycle event for the current user. Just resync the sessions
+                        // list — never sign out.
                         refreshSessions();
+                        break;
                     }
-                }
-                else {
-                    // For other event types (e.g., session_created), refresh sessions
-                    refreshSessions();
-                    // If the current session was logged out (legacy behavior), handle it specially
-                    if (data.sessionId === currentActiveSessionId) {
-                        if (onRemoteSignOutRef.current) {
-                            onRemoteSignOutRef.current();
-                        }
-                        else {
-                            toast.info('You have been signed out remotely.');
-                        }
-                        try {
-                            await clearSessionStateRef.current();
-                        }
-                        catch (error) {
-                            debug.error('Failed to clear session state after session_update:', error);
+                    default: {
+                        if (process.env.NODE_ENV !== 'production') {
+                            logger.warn('Unknown session socket event type', {
+                                component: 'useSessionSocket',
+                                type: data.type,
+                            });
                         }
+                        break;
                     }
                 }
             };
@@ -293,12 +278,14 @@ export function useSessionSocket(options) {
             if (authRetryTimer) {
                 clearTimeout(authRetryTimer);
             }
-            if (socketRef.current) {
+            const currentSocket = socketRef.current;
+            if (currentSocket) {
                 // Remove cross-tab storage listener
-                if (typeof window !== 'undefined' && socketRef.current.__oxyStorageHandler) {
-                    window.removeEventListener('storage', socketRef.current.__oxyStorageHandler);
+                const storageHandler = currentSocket.__oxyStorageHandler;
+                if (typeof window !== 'undefined' && storageHandler) {
+                    window.removeEventListener('storage', storageHandler);
                 }
-                socketRef.current.disconnect();
+                currentSocket.disconnect();
                 socketRef.current = null;
             }
         };

package/dist/esm/index.js

@@ -30,15 +30,15 @@ export { useAssetStore, useAssets as useAssetsStore, useAsset, useUploadProgress
 export { useAccountStore, useAccounts, useAccountLoading, useAccountError, useAccountLoadingSession, } from './stores/accountStore';
 export { useFollowStore, } from './stores/followStore';
 // --- Query Hooks ---
-export { useUserProfile, useUserProfiles, useCurrentUser, useUserById, useUserByUsername, useUsersBySessions, usePrivacySettings, useSessions, useSession, useDeviceSessions, useUserDevices, useSecurityInfo, useSecurityActivity, useRecentSecurityActivity, } from './hooks/queries';
+export { useUserProfile, useUserProfiles, useCurrentUser, useUserById, useUserByUsername, useUsersBySessions, usePrivacySettings, useSessions, useSession, useDeviceSessions, useUserDevices, useSecurityInfo, useSecurityActivity, useRecentSecurityActivity, useAppData, useAppDataNamespace, appDataQueryKeys, isMissingAppDataEndpointError, } from './hooks/queries';
 // --- Mutation Hooks ---
-export { useUpdateProfile, useUploadAvatar, useUpdateAccountSettings, useUpdatePrivacySettings, useUploadFile, useSwitchSession, useLogoutSession, useLogoutAll, useUpdateDeviceName, useRemoveDevice, } from './hooks/mutations';
+export { useUpdateProfile, useUploadAvatar, useUpdateAccountSettings, useUpdatePrivacySettings, useUploadFile, useSwitchSession, useLogoutSession, useLogoutAll, useUpdateDeviceName, useRemoveDevice, useSetAppData, useDeleteAppData, } from './hooks/mutations';
 export { createProfileMutation, createGenericMutation, } from './hooks/mutations/mutationFactory';
 // --- Custom Hooks ---
 export { useWebSSO, isWebBrowser } from './hooks/useWebSSO';
 export { useSessionSocket } from './hooks/useSessionSocket';
 export { useAssets, setOxyAssetInstance } from './hooks/useAssets';
-export { useFileDownloadUrl, setOxyFileUrlInstance } from './hooks/useFileDownloadUrl';
+export { useFileDownloadUrl } from './hooks/useFileDownloadUrl';
 export { useFollow, useFollowerCounts } from './hooks/useFollow';
 export { useFileFiltering } from './hooks/useFileFiltering';
 // --- Error Handlers ---

package/dist/esm/utils/sessionHelpers.js

@@ -21,7 +21,9 @@ export const mapSessionsToClient = (sessions, fallbackDeviceId, fallbackUserId)
     }));
 };
 /**
- * Fetch device sessions with fallback to the legacy session endpoint when needed.
+ * Fetch device sessions, falling back to the per-user session endpoint
+ * if the device endpoint is unavailable (older API versions or disabled
+ * device-grouping feature flag).
  *
  * @param oxyServices - Oxy service instance
  * @param sessionId - Session identifier to fetch