@oxy.so/services 8.1.1 → 8.3.0

package/src/ui/context/OxyContext.tsx

@@ -7,6 +7,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import { Linking, Platform } from 'react-native';
 import { OxyServices } from '@oxy.so/core';
@@ -43,7 +44,7 @@ import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
 import { useAuthOperations, clearPersistedAuthSafe } from './hooks/useAuthOperations';
 import { useDeviceManagement } from '../hooks/useDeviceManagement';
-import { getStorageKeys, createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
+import { getStorageKeys, createMemoryStorage, createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
 import type { RouteName } from '../navigation/routes';
 import { showBottomSheet as globalShowBottomSheet } from '../navigation/bottomSheetManager';
 import {
@@ -54,6 +55,7 @@ import {
 } from '../navigation/surfaces';
 import { useQueryClient, onlineManager } from '@tanstack/react-query';
 import { clearQueryCache } from '../hooks/queryClient';
+import { createAccountQueryPersistence, type AccountQueryPersistence } from '../hooks/accountQueryPersistence';
 import { useAvatarPicker } from '../hooks/useAvatarPicker';
 import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
 import { ASSET_DOWNLOAD_URLS_QUERY_KEY } from '../hooks/useResolvedFileUrls';
@@ -94,6 +96,8 @@ export type { LogoutResult, OxyContextState, OxyRuntimeProviderProps } from './o
 
 const OxyRuntimeContext = createContext<OxyContextState | null>(null);
 
+const subscribeNever = (): (() => void) => () => undefined;
+
 type OxyAuthActionsContextState = Pick<
   OxyContextState,
   | 'signIn'
@@ -135,6 +139,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   webAuthMode = 'popup',
   backgroundSession = false,
   platformStorage,
+  accountQueries,
   onAuthStateChange,
   onError,
 }) => {
@@ -283,6 +288,24 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   // Local display/bookkeeping storage (session id list, language). Distinct
   // from `authStore` (the durable credential blob). Exposed as an awaitable so
   // a persistence write is never dropped because it raced storage init.
+  const queryClient = useQueryClient();
+
+  // The app's per-account offline cache (`accountQueries`). Built once, like the
+  // runtime. `handleSubjectChange` activates it BEFORE anyone is woken, so a
+  // consumer of the new account never reads the previous account's rows.
+  const accountQueryPersistenceRef = useRef<AccountQueryPersistence | null | undefined>(undefined);
+  if (accountQueryPersistenceRef.current === undefined) {
+    accountQueryPersistenceRef.current = accountQueries
+      ? createAccountQueryPersistence(queryClient, accountQueries)
+      : null;
+  }
+  const accountQueryPersistence = accountQueryPersistenceRef.current;
+  const isAccountCacheReady = useSyncExternalStore(
+    accountQueryPersistence ? accountQueryPersistence.subscribe : subscribeNever,
+    () => accountQueryPersistence?.isReady() ?? true,
+    () => accountQueryPersistence?.isReady() ?? true,
+  );
+
   const storageRef = useRef<StorageInterface | null>(null);
   const [storage, setStorage] = useState<StorageInterface | null>(null);
   const buildStorageDeferred = () => {
@@ -313,12 +336,16 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .then((storageInstance) => {
         storageRef.current = storageInstance;
         storageReady.resolve(storageInstance);
+        accountQueryPersistence?.setStorage(storageInstance);
         if (mounted) {
           setStorage(storageInstance);
           runtime.setStorageReady(true);
         }
       })
       .catch((err) => {
+        // Nothing persisted can be restored; the account cache still has to
+        // become ready, or RequireOxyAuth would wait forever.
+        accountQueryPersistence?.setStorage(createMemoryStorage());
         if (mounted) {
           logger('Failed to initialize storage', err);
           onError?.({ message: 'Failed to initialize storage', code: 'STORAGE_INIT_ERROR', status: 500 });
@@ -327,7 +354,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     return () => {
       mounted = false;
     };
-  }, [logger, onError, platformStorage, runtime, storageReady]);
+  }, [accountQueryPersistence, logger, onError, platformStorage, runtime, storageReady]);
 
   const {
     currentLanguage,
@@ -344,8 +371,6 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     logger,
   });
 
-  const queryClient = useQueryClient();
-
   const {
     saveSessionIds,
     switchSession,
@@ -1207,6 +1232,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   // buy a refetch storm at first paint.
   const handleSubjectChange = useCallback(
     ({ previous, next }: SubjectTransition): void => {
+      // Every transition, the first sign-in included: the account cache is
+      // keyed by the subject, and a sign-out deletes the signed-out one's.
+      accountQueryPersistence?.activate(next);
       if (previous === null) {
         return;
       }
@@ -1224,7 +1252,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       queryClient.invalidateQueries();
       void refreshAccounts();
     },
-    [queryClient, refreshAccounts],
+    [accountQueryPersistence, queryClient, refreshAccounts],
   );
   subjectChangeRef.current = handleSubjectChange;
 
@@ -1256,6 +1284,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       isPrivateApiPending,
       isAuthResolved: authResolved,
       isStorageReady: snapshot.storageReady,
+      isAccountCacheReady,
       sessionMode: isIdentityBound ? 'identity' : 'account',
       webAuthMode,
       error,
@@ -1310,6 +1339,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       isPrivateApiPending,
       authResolved,
       snapshot.storageReady,
+      isAccountCacheReady,
       isIdentityBound,
       webAuthMode,
       error,

package/src/ui/context/oxyContextTypes.ts

@@ -12,6 +12,7 @@ import type {
 } from '../oauth/explicitOAuthConsent';
 import type { WebAuthMode, WebOAuthSignInResult } from '../oauth/types';
 import type { StorageInterface } from '../utils/storageHelpers';
+import type { AccountQueriesConfig } from '../hooks/accountQueryPersistence';
 
 /**
  * The outcome of `logout()`. It never rejects: a caller reads this instead.
@@ -48,6 +49,12 @@ export interface OxyContextState {
    */
   isAuthResolved: boolean;
   isStorageReady: boolean;
+  /**
+   * Whether the signed-in account's persisted `accountQueries` cache has been
+   * restored. Always `true` signed out or when the app declared none.
+   * `RequireOxyAuth` waits on it.
+   */
+  isAccountCacheReady: boolean;
   /**
    * Who owns this provider's session (see `OxyProviderProps.sessionMode`).
    *
@@ -200,6 +207,8 @@ export interface OxyRuntimeProviderProps {
   onError?: (error: ApiError) => void;
   /** Storage instance owned by the public provider; internal composition seam. */
   platformStorage?: StorageInterface | null;
+  /** See `OxyProviderProps.accountQueries`. Read once, at mount. */
+  accountQueries?: AccountQueriesConfig;
 }
 
 /** Internal commit input — session plus zero-cookie device credential. */

package/src/ui/hooks/accountQueryPersistence.ts

@@ -0,0 +1,201 @@
+/**
+ * Offline persistence for an app's PRIVATE, per-account queries.
+ *
+ * The SDK's own persister (`attachQueryPersistence`) keeps account-agnostic
+ * data. An app's mail, library or drafts belong to one account, and every app
+ * that wanted them to survive a restart had to scope a persister to the session
+ * itself. The SDK owns the session, so it owns this too:
+ *
+ * - Storage is keyed by the account (`oxy_account_queries:<accountId>`), so a
+ *   restore can only ever hydrate the account that is signed in.
+ * - The buster is the build (`getOxyBuildId`), so no cache written by an older
+ *   bundle, in an older shape, is ever served.
+ * - On a subject change the declared roots, memory-only ones included, and the
+ *   account's paused mutations are dropped
+ *   from memory synchronously, before anyone is woken, and the new account's
+ *   blob is restored. `isReady()` is false until that restore settles, and
+ *   `RequireOxyAuth` waits on it, so another account's rows never render.
+ * - On sign-out the signed-out account's blob is deleted.
+ */
+
+import { hashKey, type Mutation, type Query, type QueryClient, type QueryKey } from '@tanstack/react-query';
+import { persistQueryClient } from '@tanstack/react-query-persist-client';
+import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
+import type { StorageInterface } from '../utils/storageHelpers';
+import { getOxyBuildId } from '../utils/buildId';
+
+/** An app's declaration of which data is private to the signed-in account. */
+export interface AccountQueriesConfig {
+  /**
+   * Query-key roots (`queryKey[0]`) whose data belongs to the signed-in account
+   * and survives a restart.
+   */
+  roots: readonly string[];
+  /**
+   * Roots that belong to the account too, but must not be written to disk
+   * (signed URLs, AI output, search results): dropped on a switch, never persisted.
+   */
+  memoryOnlyRoots?: readonly string[];
+  /**
+   * Mutation keys whose PAUSED (offline) instances replay after a restart for
+   * the same account. Register their `mutationFn` with `setMutationDefaults`.
+   */
+  mutationKeys?: readonly QueryKey[];
+}
+
+export const ACCOUNT_QUERY_CACHE_KEY = 'oxy_account_queries';
+const ACCOUNT_QUERY_CACHE_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
+const ACCOUNT_QUERY_PERSIST_THROTTLE_MS = 1_000;
+
+export interface AccountQueryPersistence {
+  /** Storage became available (it initializes asynchronously). */
+  setStorage(storage: StorageInterface): void;
+  /** The signed-in account changed. `null` is a sign-out. Synchronous in-memory reset. */
+  activate(accountId: string | null): void;
+  /** True once the active account's cache is restored (always true signed out). */
+  isReady(): boolean;
+  subscribe(listener: () => void): () => void;
+  /** Whether a mutation is account-scoped (so the SDK's own persister skips it). */
+  ownsMutation(mutation: Mutation): boolean;
+  dispose(): void;
+}
+
+function storageKeyFor(accountId: string): string {
+  return `${ACCOUNT_QUERY_CACHE_KEY}:${encodeURIComponent(accountId)}`;
+}
+
+export function createAccountQueryPersistence(
+  queryClient: QueryClient,
+  config: AccountQueriesConfig,
+): AccountQueryPersistence {
+  const persistedRoots = new Set(config.roots);
+  const accountRoots = new Set([...config.roots, ...(config.memoryOnlyRoots ?? [])]);
+  const mutationHashes = new Set((config.mutationKeys ?? []).map((key) => hashKey(key)));
+  const listeners = new Set<() => void>();
+
+  let storage: StorageInterface | null = null;
+  let accountId: string | null = null;
+  let restoredFor: string | null = null;
+  let generation = 0;
+  let unsubscribePersist: (() => void) | null = null;
+  // The in-flight restore. A new account waits for it, so a late restore can
+  // never hydrate the previous account's rows after the switch.
+  let restoring: Promise<void> = Promise.resolve();
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  const rootOf = (query: Query): string | null => {
+    const head = query.queryKey[0];
+    return typeof head === 'string' ? head : null;
+  };
+  const ownsQuery = (query: Query): boolean => accountRoots.has(rootOf(query) ?? '');
+  const persistsQuery = (query: Query): boolean => persistedRoots.has(rootOf(query) ?? '');
+
+  const ownsMutation = (mutation: Mutation): boolean => {
+    const key = mutation.options.mutationKey;
+    return key !== undefined && mutationHashes.has(hashKey(key));
+  };
+
+  const dropScopedData = () => {
+    queryClient.removeQueries({ predicate: ownsQuery });
+    const mutations = queryClient.getMutationCache();
+    for (const mutation of mutations.getAll()) {
+      if (ownsMutation(mutation)) mutations.remove(mutation);
+    }
+  };
+
+  const persisterFor = (id: string, target: StorageInterface) =>
+    createAsyncStoragePersister({
+      storage: {
+        getItem: (key) => target.getItem(key),
+        setItem: (key, value) => target.setItem(key, value),
+        removeItem: (key) => target.removeItem(key),
+      },
+      key: storageKeyFor(id),
+      throttleTime: ACCOUNT_QUERY_PERSIST_THROTTLE_MS,
+    });
+
+  const start = () => {
+    const id = accountId;
+    const target = storage;
+    if (!id || !target || unsubscribePersist) return;
+    const current = generation;
+    const [unsubscribe, restored] = persistQueryClient({
+      queryClient,
+      persister: persisterFor(id, target),
+      maxAge: ACCOUNT_QUERY_CACHE_MAX_AGE,
+      buster: getOxyBuildId(),
+      dehydrateOptions: {
+        shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
+        shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
+      },
+    });
+    unsubscribePersist = unsubscribe;
+    restoring = restored.catch(() => undefined).then(() => {
+      if (current !== generation) return;
+      restoredFor = id;
+      notify();
+    });
+  };
+
+  const stop = () => {
+    unsubscribePersist?.();
+    unsubscribePersist = null;
+  };
+
+  return {
+    setStorage(next) {
+      if (storage) return;
+      storage = next;
+      const current = generation;
+      void restoring.then(() => {
+        if (current === generation) start();
+      });
+    },
+
+    activate(next) {
+      if (next === accountId) return;
+      const previous = accountId;
+      generation += 1;
+      const current = generation;
+      stop();
+      dropScopedData();
+      accountId = next;
+      restoredFor = null;
+      notify();
+
+      if (next === null && previous !== null && storage) {
+        void persisterFor(previous, storage).removeClient();
+      }
+
+      void restoring.then(() => {
+        if (current !== generation) return;
+        // A restore that was already in flight may have hydrated the previous
+        // account's rows; drop them again before this account's restore.
+        dropScopedData();
+        start();
+      });
+    },
+
+    isReady() {
+      return accountId === null || restoredFor === accountId;
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    ownsMutation,
+
+    dispose() {
+      generation += 1;
+      stop();
+      listeners.clear();
+    },
+  };
+}

package/src/ui/hooks/queryClient.ts

@@ -24,7 +24,7 @@
  *   when introducing reads that should survive restart.
  */
 
-import { QueryClient, onlineManager, type Query, type Mutation } from '@tanstack/react-query';
+import { QueryClient, hashKey, onlineManager, type Query, type Mutation, type QueryKey } from '@tanstack/react-query';
 import {
   persistQueryClient,
   type PersistedClient,
@@ -32,6 +32,7 @@ import {
 import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
 import { isDev } from '@oxy.so/core';
 import type { StorageInterface } from '../utils/storageHelpers';
+import { getOxyBuildId } from '../utils/buildId';
 
 const QUERY_CACHE_KEY = 'oxy_query_cache_v3';
 const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -106,13 +107,6 @@ function shouldDehydrateQuery(query: Query): boolean {
   return PERSISTED_QUERY_PREFIXES.includes(head);
 }
 
-/**
- * Persist every mutation regardless of status — paused mutations are
- * exactly the ones that must survive restart to replay when online.
- */
-function shouldDehydrateMutation(_mutation: Mutation): boolean {
-  return true;
-}
 
 /**
  * Create a QueryClient with offline-first defaults.
@@ -191,6 +185,12 @@ export interface AttachPersistenceResult {
 export const attachQueryPersistence = (
   queryClient: QueryClient,
   storage: StorageInterface | null | undefined,
+  /**
+   * Mutation keys the app declared account-scoped (`accountQueries`). Those are
+   * persisted per account by `createAccountQueryPersistence`, never here, so a
+   * paused mutation cannot replay twice or under another account.
+   */
+  accountMutationKeys: readonly QueryKey[] = [],
 ): AttachPersistenceResult => {
   if (!storage) {
     return {
@@ -205,10 +205,19 @@ export const attachQueryPersistence = (
     throttleTime: QUERY_PERSIST_THROTTLE_MS,
   });
 
+  // Persist every other mutation regardless of status: paused mutations are
+  // exactly the ones that must survive restart to replay when online.
+  const accountScoped = new Set(accountMutationKeys.map((key) => hashKey(key)));
+  const shouldDehydrateMutation = (mutation: Mutation): boolean => {
+    const key = mutation.options.mutationKey;
+    return key === undefined || !accountScoped.has(hashKey(key));
+  };
+
   const [unsubscribe, restored] = persistQueryClient({
     queryClient,
     persister,
     maxAge: QUERY_CACHE_MAX_AGE,
+    buster: getOxyBuildId(),
     dehydrateOptions: {
       shouldDehydrateQuery,
       shouldDehydrateMutation,

package/src/ui/index.ts

@@ -24,6 +24,8 @@ export { LogoIcon } from './components/logo/LogoIcon';
 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 { 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

@@ -1,5 +1,6 @@
 import type { ReactNode, RefObject } from 'react';
 import type { QueryClient } from '@tanstack/react-query';
+import type { AccountQueriesConfig } from '../hooks/accountQueryPersistence';
 import type { RouteName } from '../navigation/routes';
 import type { User } from '@oxy.so/core';
 import type { ClientSession } from '@oxy.so/core';
@@ -131,6 +132,14 @@ export interface OxyProviderProps {
      */
     webAuthMode?: WebAuthMode;
     queryClient?: QueryClient;
+    /**
+     * The app's private, per-account data, persisted offline by the SDK: stored
+     * per account, discarded by every new build, dropped from memory on an
+     * 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`.
+     */
+    accountQueries?: AccountQueriesConfig;
     /**
      * Convenience: wrap the whole app subtree in `<RequireOxyAuth prompt=...>`.
      * `off` (default) renders children unconditionally; `soft` adds a dismissible

package/src/ui/utils/buildId.ts

@@ -0,0 +1,18 @@
+/**
+ * The identity of the JS bundle that is running, used as the buster for every
+ * persisted query cache the SDK owns.
+ *
+ * A persisted cache is restored and served before any refetch (offline-first),
+ * so data written by an older build reaches components in whatever shape that
+ * build used. Busting on the build means no app ever has to remember to bump a
+ * version when a query's shape changes: a new build simply starts from the
+ * network. Inbox shipped exactly that crash when a hand-kept buster was missed.
+ *
+ * `@oxy.so/app-preset`'s Babel config replaces `process.env.OXY_BUILD_ID` with
+ * the commit at bundle time, node_modules included. An app that does not use
+ * the preset gets a constant, which behaves like a buster that is never bumped.
+ */
+export function getOxyBuildId(): string {
+  const buildId = typeof process === 'undefined' ? undefined : process.env.OXY_BUILD_ID;
+  return buildId || 'unversioned';
+}