@oxyhq/services 23.0.2 → 23.0.3

package/lib/commonjs/ui/hooks/useResolvedFileUrls.js

@@ -0,0 +1,163 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ASSET_DOWNLOAD_URLS_QUERY_KEY = void 0;
+exports.fileThumbSource = fileThumbSource;
+exports.isOptimisticFile = isOptimisticFile;
+exports.useResolvedFileUrls = useResolvedFileUrls;
+var _react = require("react");
+var _reactQuery = require("@tanstack/react-query");
+/**
+ * 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.
+ */
+
+/**
+ * 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. */
+const ASSET_DOWNLOAD_URLS_QUERY_KEY = exports.ASSET_DOWNLOAD_URLS_QUERY_KEY = 'assetDownloadUrls';
+
+/**
+ * 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`.
+ */
+function isOptimisticFile(file) {
+  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) {
+  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) {
+  const uri = file.metadata?.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).
+ */
+function fileThumbSource(file, resolved) {
+  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".
+ */
+function useResolvedFileUrls(oxyServices, files, /** Active viewer account id — media tokens are minted per user; must be in the query key. */
+viewerId) {
+  const viewerKey = viewerId ?? '';
+  const requests = (0, _react.useMemo)(() => {
+    const list = [];
+    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 = (0, _react.useMemo)(() => requests.map(r => `${r.fileId}:${r.variant ?? ''}`).sort().join('|'), [requests]);
+  const query = (0, _reactQuery.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 () => {
+      const merged = {};
+      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 (0, _react.useMemo)(() => {
+    const map = new Map();
+    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]);
+}
+//# sourceMappingURL=useResolvedFileUrls.js.map

package/lib/commonjs/ui/hooks/useResolvedFileUrls.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_reactQuery","ASSET_URL_TTL_SECONDS","ASSET_URL_STALE_MS","ASSET_URL_GC_MS","BATCH_CAP","ASSET_DOWNLOAD_URLS_QUERY_KEY","exports","isOptimisticFile","file","id","startsWith","metadata","uploading","thumbVariantFor","contentType","undefined","localPreviewUri","uri","length","fileThumbSource","resolved","get","useResolvedFileUrls","oxyServices","files","viewerId","viewerKey","requests","useMemo","list","variant","push","fileId","signature","map","r","sort","join","query","useQuery","queryKey","enabled","staleTime","gcTime","placeholderData","previousData","previousQuery","prevViewer","queryFn","merged","i","chunk","slice","urls","getFileDownloadUrls","expiresIn","Object","assign","Map","data","url","entries","set"],"sourceRoot":"../../../../src","sources":["ui/hooks/useResolvedFileUrls.ts"],"mappings":";;;;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,WAAA,GAAAD,OAAA;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,MAAME,qBAAqB,GAAG,GAAG,CAAC,CAAC;AACnC;AACA;AACA;AACA;AACA,MAAMC,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AAC1C,MAAMC,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;AACtC;AACA,MAAMC,SAAS,GAAG,GAAG;;AAErB;AACO,MAAMC,6BAA6B,GAAAC,OAAA,CAAAD,6BAAA,GAAG,mBAA4B;;AAEzE;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,gBAAgBA,CAACC,IAA2C,EAAW;EACrF,IAAI,OAAOA,IAAI,CAACC,EAAE,KAAK,QAAQ,IAAID,IAAI,CAACC,EAAE,CAACC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI;EAC3E,OAAOF,IAAI,CAACG,QAAQ,EAAEC,SAAS,KAAK,IAAI;AAC1C;;AAEA;AACA,SAASC,eAAeA,CAACL,IAAkB,EAAsB;EAC/D,IAAIA,IAAI,CAACM,WAAW,CAACJ,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,QAAQ;EAC1D,IAAIF,IAAI,CAACM,WAAW,CAACJ,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,OAAO;EACzD,OAAOK,SAAS;AAClB;;AAEA;AACA;AACA;AACA;AACA,SAASC,eAAeA,CAACR,IAAkB,EAAsB;EAC/D,MAAMS,GAAG,GAAIT,IAAI,CAACG,QAAQ,EAA0CK,eAAe;EACnF,OAAO,OAAOC,GAAG,KAAK,QAAQ,IAAIA,GAAG,CAACC,MAAM,GAAG,CAAC,GAAGD,GAAG,GAAGF,SAAS;AACpE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASI,eAAeA,CAC7BX,IAAkB,EAClBY,QAAqC,EACjB;EACpB,IAAIb,gBAAgB,CAACC,IAAI,CAAC,EAAE;IAC1B,OAAOQ,eAAe,CAACR,IAAI,CAAC;EAC9B;EACA,OAAOY,QAAQ,CAACC,GAAG,CAACb,IAAI,CAACC,EAAE,CAAC;AAC9B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASa,mBAAmBA,CACjCC,WAAkC,EAClCC,KAAqB,EACrB;AACAC,QAAwB,EACK;EAC7B,MAAMC,SAAS,GAAGD,QAAQ,IAAI,EAAE;EAChC,MAAME,QAAQ,GAAG,IAAAC,cAAO,EAAC,MAAM;IAC7B,MAAMC,IAAiD,GAAG,EAAE;IAC5D,KAAK,MAAMrB,IAAI,IAAIgB,KAAK,EAAE;MACxB,IAAIjB,gBAAgB,CAACC,IAAI,CAAC,EAAE;MAC5B,MAAMsB,OAAO,GAAGjB,eAAe,CAACL,IAAI,CAAC;MACrC,IAAI,CAACsB,OAAO,EAAE;MACdD,IAAI,CAACE,IAAI,CAAC;QAAEC,MAAM,EAAExB,IAAI,CAACC,EAAE;QAAEqB;MAAQ,CAAC,CAAC;IACzC;IACA,OAAOD,IAAI;EACb,CAAC,EAAE,CAACL,KAAK,CAAC,CAAC;;EAEX;EACA;EACA;EACA,MAAMS,SAAS,GAAG,IAAAL,cAAO,EACvB,MAAMD,QAAQ,CAACO,GAAG,CAAEC,CAAC,IAAK,GAAGA,CAAC,CAACH,MAAM,IAAIG,CAAC,CAACL,OAAO,IAAI,EAAE,EAAE,CAAC,CAACM,IAAI,CAAC,CAAC,CAACC,IAAI,CAAC,GAAG,CAAC,EAC5E,CAACV,QAAQ,CACX,CAAC;EAED,MAAMW,KAAK,GAAG,IAAAC,oBAAQ,EAAC;IACrBC,QAAQ,EAAE,CAACnC,6BAA6B,EAAEqB,SAAS,EAAEO,SAAS,CAAC;IAC/DQ,OAAO,EAAEd,QAAQ,CAACT,MAAM,GAAG,CAAC,IAAIQ,SAAS,CAACR,MAAM,GAAG,CAAC;IACpDwB,SAAS,EAAExC,kBAAkB;IAC7ByC,MAAM,EAAExC,eAAe;IACvB;IACA;IACA;IACAyC,eAAe,EAAEA,CAACC,YAAY,EAAEC,aAAa,KAAK;MAChD,IAAI,CAACD,YAAY,IAAI,CAACC,aAAa,EAAE,OAAO/B,SAAS;MACrD,MAAMgC,UAAU,GAAGD,aAAa,CAACN,QAAQ,CAAC,CAAC,CAAC;MAC5C,IAAIO,UAAU,KAAKrB,SAAS,EAAE,OAAOX,SAAS;MAC9C,OAAO8B,YAAY;IACrB,CAAC;IACDG,OAAO,EAAE,MAAAA,CAAA,KAA6C;MACpD,MAAMC,MAA8B,GAAG,CAAC,CAAC;MACzC,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGvB,QAAQ,CAACT,MAAM,EAAEgC,CAAC,IAAI9C,SAAS,EAAE;QACnD,MAAM+C,KAAK,GAAGxB,QAAQ,CAACyB,KAAK,CAACF,CAAC,EAAEA,CAAC,GAAG9C,SAAS,CAAC;QAC9C,MAAMiD,IAAI,GAAG,MAAM9B,WAAW,CAAC+B,mBAAmB,CAACH,KAAK,EAAE;UACxDI,SAAS,EAAEtD;QACb,CAAC,CAAC;QACFuD,MAAM,CAACC,MAAM,CAACR,MAAM,EAAEI,IAAI,CAAC;MAC7B;MACA,OAAOJ,MAAM;IACf;EACF,CAAC,CAAC;EAEF,OAAO,IAAArB,cAAO,EAAC,MAAM;IACnB,MAAMM,GAAG,GAAG,IAAIwB,GAAG,CAAiB,CAAC;IACrC,MAAMC,IAAI,GAAGrB,KAAK,CAACqB,IAAI;IACvB,IAAIA,IAAI,EAAE;MACR,KAAK,MAAM,CAAClD,EAAE,EAAEmD,GAAG,CAAC,IAAIJ,MAAM,CAACK,OAAO,CAACF,IAAI,CAAC,EAAE;QAC5C,IAAI,OAAOC,GAAG,KAAK,QAAQ,IAAIA,GAAG,CAAC1C,MAAM,GAAG,CAAC,EAAEgB,GAAG,CAAC4B,GAAG,CAACrD,EAAE,EAAEmD,GAAG,CAAC;MACjE;IACF;IACA,OAAO1B,GAAG;EACZ,CAAC,EAAE,CAACI,KAAK,CAACqB,IAAI,CAAC,CAAC;AAClB","ignoreList":[]}

package/lib/commonjs/ui/hooks/useSessionManagement.js

@@ -0,0 +1,290 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useSessionManagement = void 0;
+var _react = require("react");
+var _core = require("@oxyhq/core");
+var _sessionHelpers = require("../utils/sessionHelpers.js");
+var _storageHelpers = require("../utils/storageHelpers.js");
+var _errorHandlers = require("../utils/errorHandlers.js");
+var _queryClient = require("./queryClient.js");
+var _isWebBrowser = require("../utils/isWebBrowser.js");
+var _resetSessionScopedStores = require("../stores/resetSessionScopedStores.js");
+const DEFAULT_SAVE_ERROR_MESSAGE = 'Failed to save session data';
+const CLEAR_STORAGE_ERROR = 'Failed to clear storage';
+
+/**
+ * Manage session state, persistence, and high-level multi-session operations.
+ *
+ * @param options - Session management configuration
+ */
+const useSessionManagement = ({
+  oxyServices,
+  storage,
+  storageKeyPrefix,
+  loginSuccess,
+  logoutStore,
+  onAuthStateChange,
+  onError,
+  setAuthError,
+  logger,
+  setTokenReady,
+  queryClient
+}) => {
+  const [sessions, setSessions] = (0, _react.useState)([]);
+  const [activeSessionId, setActiveSessionId] = (0, _react.useState)(null);
+
+  // Refs to avoid recreating callbacks when sessions/activeSessionId change
+  const sessionsRef = (0, _react.useRef)(sessions);
+  sessionsRef.current = sessions;
+  const activeSessionIdRef = (0, _react.useRef)(activeSessionId);
+  activeSessionIdRef.current = activeSessionId;
+  const refreshInFlightRef = (0, _react.useRef)(null);
+  const removedSessionsRef = (0, _react.useRef)(new Set());
+  const lastRefreshRef = (0, _react.useRef)(0);
+  const storageKeys = (0, _react.useMemo)(() => (0, _storageHelpers.getStorageKeys)(storageKeyPrefix), [storageKeyPrefix]);
+  const saveSessionIds = (0, _react.useCallback)(async sessionIds => {
+    if (!storage) return;
+    try {
+      const uniqueIds = Array.from(new Set(sessionIds));
+      await storage.setItem(storageKeys.sessionIds, JSON.stringify(uniqueIds));
+    } catch (error) {
+      if (logger) {
+        logger(DEFAULT_SAVE_ERROR_MESSAGE, error);
+      } else if ((0, _core.isDev)()) {
+        console.warn('Failed to save session IDs:', error);
+      }
+    }
+  }, [logger, storage, storageKeys.sessionIds]);
+  const updateSessions = (0, _react.useCallback)((incoming, options = {}) => {
+    setSessions(prevSessions => {
+      const processed = options.merge ? (0, _core.mergeSessions)(prevSessions, incoming, activeSessionIdRef.current, false) : (0, _core.normalizeAndSortSessions)(incoming, activeSessionIdRef.current, false);
+      if (storage) {
+        void saveSessionIds([...processed.map(session => session.sessionId), ...(options.preserveSessionIds ?? [])]);
+      }
+      if ((0, _core.sessionsArraysEqual)(prevSessions, processed)) {
+        return prevSessions;
+      }
+      return processed;
+    });
+  }, [saveSessionIds, storage]);
+  const saveActiveSessionId = (0, _react.useCallback)(async sessionId => {
+    if (!storage) return;
+    try {
+      await storage.setItem(storageKeys.activeSessionId, sessionId);
+    } catch (error) {
+      (0, _errorHandlers.handleAuthError)(error, {
+        defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
+        code: 'SESSION_PERSISTENCE_ERROR',
+        onError,
+        setAuthError,
+        logger
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId]);
+  const removeActiveSessionId = (0, _react.useCallback)(async () => {
+    if (!storage) return;
+    try {
+      await storage.removeItem(storageKeys.activeSessionId);
+    } catch (error) {
+      (0, _errorHandlers.handleAuthError)(error, {
+        defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
+        code: 'SESSION_PERSISTENCE_ERROR',
+        onError,
+        setAuthError,
+        logger
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId]);
+  const clearSessionStorage = (0, _react.useCallback)(async () => {
+    if (!storage) return;
+    try {
+      await storage.removeItem(storageKeys.activeSessionId);
+      await storage.removeItem(storageKeys.sessionIds);
+      // Note: Identity sync state ('oxy_identity_synced') is managed by accounts app
+    } catch (error) {
+      (0, _errorHandlers.handleAuthError)(error, {
+        defaultMessage: CLEAR_STORAGE_ERROR,
+        code: 'STORAGE_ERROR',
+        onError,
+        setAuthError,
+        logger
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId, storageKeys.sessionIds]);
+  const clearSessionState = (0, _react.useCallback)(async () => {
+    setSessions([]);
+    setActiveSessionId(null);
+    logoutStore();
+    (0, _resetSessionScopedStores.resetSessionScopedStores)();
+
+    // Clear the access token on the client instance. Without this the
+    // TokenStore retained the stale bearer until the next 401, leaving the
+    // instance "logged in" at the HTTP layer and — via OxyProvider's
+    // token-change mirror — leaking that stale token onto the shared
+    // `oxyClient` singleton after sign-out. Clearing here fires
+    // `onTokensChanged(null)`, propagating the logged-out state everywhere.
+    oxyServices.clearTokens();
+
+    // Clear TanStack Query cache (in-memory)
+    if (queryClient) {
+      queryClient.clear();
+    }
+
+    // Clear persisted query cache
+    if (storage) {
+      try {
+        await (0, _queryClient.clearQueryCache)(storage);
+      } catch (error) {
+        if (logger) {
+          logger('Failed to clear persisted query cache', error);
+        }
+      }
+    }
+    await clearSessionStorage();
+    onAuthStateChange?.(null);
+  }, [clearSessionStorage, logoutStore, onAuthStateChange, oxyServices, queryClient, storage, logger]);
+  const activateSession = (0, _react.useCallback)(async (sessionId, user) => {
+    setTokenReady?.(true);
+    setActiveSessionId(sessionId);
+    loginSuccess(user);
+    await saveActiveSessionId(sessionId);
+    onAuthStateChange?.(user);
+  }, [loginSuccess, onAuthStateChange, saveActiveSessionId, setTokenReady]);
+  const removalTimerIdsRef = (0, _react.useRef)(new Set());
+  const trackRemovedSession = (0, _react.useCallback)(sessionId => {
+    removedSessionsRef.current.add(sessionId);
+    const timerId = setTimeout(() => {
+      removedSessionsRef.current.delete(sessionId);
+      removalTimerIdsRef.current.delete(timerId);
+    }, 5000);
+    removalTimerIdsRef.current.add(timerId);
+  }, []);
+  (0, _react.useEffect)(() => {
+    return () => {
+      removalTimerIdsRef.current.forEach(clearTimeout);
+    };
+  }, []);
+  const switchSession = (0, _react.useCallback)(async sessionId => {
+    try {
+      // On web, the bearer must already be in memory (planted by
+      // `claimSessionByToken`, a cold-boot silent-restore step, or a prior
+      // `SessionClient` sync) before validating — there is no client-side
+      // `oxy_rt` refresh-cookie slot to fall back on; the device account SET
+      // is server-authoritative via `SessionClient` now. The native path
+      // arrives here only after a bearer has been planted by
+      // `claimSessionByToken` or secure shared-session restore.
+      if ((0, _isWebBrowser.isWebBrowser)() && !oxyServices.getAccessToken()) {
+        throw new Error('Session is invalid or expired');
+      }
+      const validation = await oxyServices.validateSession(sessionId, {
+        useHeaderValidation: true
+      });
+      if (!validation?.valid) {
+        throw new Error('Session is invalid or expired');
+      }
+      if (!validation.user) {
+        throw new Error('User data not available from session validation');
+      }
+      const user = validation.user;
+      await activateSession(sessionId, user);
+      try {
+        const deviceSessions = await (0, _sessionHelpers.fetchSessionsWithFallback)(oxyServices, sessionId, {
+          fallbackUserId: user.id,
+          logger
+        });
+        updateSessions(deviceSessions, {
+          merge: true
+        });
+      } catch (error) {
+        if ((0, _core.isDev)()) {
+          console.warn('Failed to synchronize sessions after switch:', error);
+        }
+      }
+      return user;
+    } catch (error) {
+      const invalidSession = (0, _errorHandlers.isInvalidSessionError)(error);
+      if (invalidSession) {
+        // Server authority (`SessionClient` bootstrap/sync) reconciles which
+        // account is actually active — just drop the invalid session from
+        // the local view rather than guessing at a replacement.
+        updateSessions(sessionsRef.current.filter(session => session.sessionId !== sessionId), {
+          merge: false
+        });
+      }
+      (0, _errorHandlers.handleAuthError)(error, {
+        defaultMessage: 'Failed to switch session',
+        code: invalidSession ? 'INVALID_SESSION' : 'SESSION_SWITCH_ERROR',
+        onError,
+        setAuthError,
+        logger
+      });
+      throw error instanceof Error ? error : new Error('Failed to switch session');
+    }
+  }, [activateSession, logger, onError, oxyServices, setAuthError, updateSessions]);
+  const refreshSessions = (0, _react.useCallback)(async activeUserId => {
+    // Capture the active session id once so the async closure below uses a
+    // narrowed, non-null local instead of re-reading the ref (which the
+    // compiler cannot prove stays non-null across awaits).
+    const activeSessionId = activeSessionIdRef.current;
+    if (!activeSessionId) return;
+    if (refreshInFlightRef.current) {
+      await refreshInFlightRef.current;
+      return;
+    }
+    const now = Date.now();
+    if (now - lastRefreshRef.current < 500) {
+      return;
+    }
+    lastRefreshRef.current = now;
+    const refreshPromise = (async () => {
+      try {
+        const deviceSessions = await (0, _sessionHelpers.fetchSessionsWithFallback)(oxyServices, activeSessionId, {
+          fallbackUserId: activeUserId,
+          logger
+        });
+        updateSessions(deviceSessions, {
+          merge: true
+        });
+      } catch (error) {
+        if ((0, _errorHandlers.isInvalidSessionError)(error)) {
+          // Server authority (`SessionClient` bootstrap/sync) reconciles
+          // which account is actually active — just clear local state
+          // rather than guessing at a replacement session.
+          await clearSessionState();
+          return;
+        }
+        (0, _errorHandlers.handleAuthError)(error, {
+          defaultMessage: 'Failed to refresh sessions',
+          code: 'SESSION_REFRESH_ERROR',
+          onError,
+          setAuthError,
+          logger
+        });
+      } finally {
+        refreshInFlightRef.current = null;
+        lastRefreshRef.current = Date.now();
+      }
+    })();
+    refreshInFlightRef.current = refreshPromise;
+    await refreshPromise;
+  }, [clearSessionState, logger, onError, oxyServices, setAuthError, updateSessions]);
+  const isRefreshInFlight = Boolean(refreshInFlightRef.current);
+  return {
+    sessions,
+    activeSessionId,
+    setActiveSessionId,
+    updateSessions,
+    switchSession,
+    refreshSessions,
+    clearSessionState,
+    saveActiveSessionId,
+    trackRemovedSession,
+    storageKeys,
+    isRefreshInFlight
+  };
+};
+exports.useSessionManagement = useSessionManagement;
+//# sourceMappingURL=useSessionManagement.js.map

package/lib/commonjs/ui/hooks/useSessionManagement.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_core","_sessionHelpers","_storageHelpers","_errorHandlers","_queryClient","_isWebBrowser","_resetSessionScopedStores","DEFAULT_SAVE_ERROR_MESSAGE","CLEAR_STORAGE_ERROR","useSessionManagement","oxyServices","storage","storageKeyPrefix","loginSuccess","logoutStore","onAuthStateChange","onError","setAuthError","logger","setTokenReady","queryClient","sessions","setSessions","useState","activeSessionId","setActiveSessionId","sessionsRef","useRef","current","activeSessionIdRef","refreshInFlightRef","removedSessionsRef","Set","lastRefreshRef","storageKeys","useMemo","getStorageKeys","saveSessionIds","useCallback","sessionIds","uniqueIds","Array","from","setItem","JSON","stringify","error","isDev","console","warn","updateSessions","incoming","options","prevSessions","processed","merge","mergeSessions","normalizeAndSortSessions","map","session","sessionId","preserveSessionIds","sessionsArraysEqual","saveActiveSessionId","handleAuthError","defaultMessage","code","removeActiveSessionId","removeItem","clearSessionStorage","clearSessionState","resetSessionScopedStores","clearTokens","clear","clearQueryCache","activateSession","user","removalTimerIdsRef","trackRemovedSession","add","timerId","setTimeout","delete","useEffect","forEach","clearTimeout","switchSession","isWebBrowser","getAccessToken","Error","validation","validateSession","useHeaderValidation","valid","deviceSessions","fetchSessionsWithFallback","fallbackUserId","id","invalidSession","isInvalidSessionError","filter","refreshSessions","activeUserId","now","Date","refreshPromise","isRefreshInFlight","Boolean","exports"],"sourceRoot":"../../../../src","sources":["ui/hooks/useSessionManagement.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/ui/hooks/useSettingToggle.js

@@ -0,0 +1,132 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+exports.useSettingToggle = useSettingToggle;
+exports.useSettingToggles = useSettingToggles;
+var _react = require("react");
+var _bloom = require("@oxyhq/bloom");
+/**
+ * Hook for handling boolean toggle settings with optimistic updates.
+ * Automatically reverts to the previous value if the save fails.
+ *
+ * @example
+ * const { value, toggle, isSaving } = useSettingToggle({
+ *   initialValue: user.notificationsEnabled,
+ *   onSave: (value) => api.updateNotifications(value),
+ *   errorMessage: 'Failed to update notifications',
+ * });
+ *
+ * <Switch value={value} onValueChange={toggle} disabled={isSaving} />
+ */
+function useSettingToggle(options) {
+  const {
+    initialValue,
+    onSave,
+    successMessage,
+    errorMessage = 'Failed to save setting',
+    revertOnError = true,
+    showSuccessToast = false
+  } = options;
+  const [value, setValue] = (0, _react.useState)(initialValue);
+  const [isSaving, setIsSaving] = (0, _react.useState)(false);
+
+  // Update value when initialValue changes (e.g., from server)
+  (0, _react.useEffect)(() => {
+    setValue(initialValue);
+  }, [initialValue]);
+  const toggle = (0, _react.useCallback)(async () => {
+    const previousValue = value;
+    const newValue = !value;
+
+    // Optimistic update
+    setValue(newValue);
+    setIsSaving(true);
+    try {
+      await onSave(newValue);
+      if (showSuccessToast && successMessage) {
+        _bloom.toast.success(successMessage);
+      }
+    } catch (err) {
+      // Revert on error
+      if (revertOnError) {
+        setValue(previousValue);
+      }
+      _bloom.toast.error(errorMessage || (err instanceof Error ? err.message : null) || 'An error occurred');
+    } finally {
+      setIsSaving(false);
+    }
+  }, [value, onSave, successMessage, errorMessage, revertOnError, showSuccessToast]);
+  return {
+    value,
+    isSaving,
+    toggle,
+    setValue
+  };
+}
+
+/**
+ * Hook for managing multiple toggle settings at once.
+ * Useful when you have several related boolean settings.
+ */
+function useSettingToggles(options) {
+  const {
+    initialValues,
+    onSave,
+    errorMessage = 'Failed to save setting',
+    revertOnError = true
+  } = options;
+  const [values, setValues] = (0, _react.useState)(initialValues);
+  const [savingKeys, setSavingKeys] = (0, _react.useState)(new Set());
+
+  // Update values when initialValues change
+  (0, _react.useEffect)(() => {
+    setValues(initialValues);
+  }, [initialValues]);
+  const toggle = (0, _react.useCallback)(async key => {
+    const previousValue = values[key];
+    const newValue = !previousValue;
+
+    // Optimistic update
+    setValues(prev => ({
+      ...prev,
+      [key]: newValue
+    }));
+    setSavingKeys(prev => new Set(prev).add(key));
+    try {
+      await onSave(key, newValue);
+    } catch (err) {
+      // Revert on error
+      if (revertOnError) {
+        setValues(prev => ({
+          ...prev,
+          [key]: previousValue
+        }));
+      }
+      const message = typeof errorMessage === 'function' ? errorMessage(key) : errorMessage;
+      _bloom.toast.error(message || (err instanceof Error ? err.message : null) || 'An error occurred');
+    } finally {
+      setSavingKeys(prev => {
+        const next = new Set(prev);
+        next.delete(key);
+        return next;
+      });
+    }
+  }, [values, onSave, errorMessage, revertOnError]);
+  const setValuesExternal = (0, _react.useCallback)(newValues => {
+    setValues(prev => ({
+      ...prev,
+      ...newValues
+    }));
+  }, []);
+  return {
+    values,
+    savingKeys,
+    toggle,
+    setValues: setValuesExternal
+  };
+}
+var _default = exports.default = useSettingToggle;
+//# sourceMappingURL=useSettingToggle.js.map

package/lib/commonjs/ui/hooks/useSettingToggle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_bloom","useSettingToggle","options","initialValue","onSave","successMessage","errorMessage","revertOnError","showSuccessToast","value","setValue","useState","isSaving","setIsSaving","useEffect","toggle","useCallback","previousValue","newValue","toast","success","err","error","Error","message","useSettingToggles","initialValues","values","setValues","savingKeys","setSavingKeys","Set","key","prev","add","next","delete","setValuesExternal","newValues","_default","exports","default"],"sourceRoot":"../../../../src","sources":["ui/hooks/useSettingToggle.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/ui/hooks/useStorage.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useStorage = void 0;
+var _react = require("react");
+var _storageHelpers = require("../utils/storageHelpers.js");
+/**
+ * Simple React hook that initializes platform-appropriate storage.
+ * Returns storage instance once ready, or null if initialization failed.
+ */
+const useStorage = ({
+  onError,
+  logger
+} = {}) => {
+  const [storage, setStorage] = (0, _react.useState)(null);
+  const initRef = (0, _react.useRef)(null);
+  (0, _react.useEffect)(() => {
+    // Prevent multiple initializations
+    if (initRef.current) return;
+    initRef.current = (async () => {
+      try {
+        const storageInstance = await (0, _storageHelpers.createPlatformStorage)();
+        setStorage(storageInstance);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Failed to initialize storage';
+        if (logger) {
+          logger(message, err);
+        }
+        onError?.({
+          message,
+          code: 'STORAGE_INIT_ERROR',
+          status: 500
+        });
+      }
+    })();
+  }, [logger, onError]);
+  return {
+    storage,
+    isReady: storage !== null
+  };
+};
+exports.useStorage = useStorage;
+//# sourceMappingURL=useStorage.js.map