@oxy.so/services 1.0.0

package/src/ui/hooks/useProfileEditing.ts

@@ -0,0 +1,168 @@
+import { useCallback } from 'react';
+import { useUpdateProfile } from './mutations/useAccountMutations';
+import { useAuthStore } from '../stores/authStore';
+import type { UserProfileUpdate } from '@oxy.so/contracts';
+
+interface ProfileLocation {
+    id: string;
+    name: string;
+    label?: string;
+    coordinates?: { lat: number; lon: number };
+}
+
+interface ProfileLinkMetadata {
+    url: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    id: string;
+}
+
+export interface ProfileUpdateData {
+    firstName?: string;
+    lastName?: string;
+    username?: string;
+    email?: string;
+    bio?: string;
+    locations?: ProfileLocation[];
+    links?: string[];
+    linksMetadata?: ProfileLinkMetadata[];
+    avatar?: string;
+    phone?: string;
+    address?: string;
+    birthday?: string;
+}
+
+type ProfileFieldValue = string | ProfileLocation[] | ProfileLinkMetadata[];
+
+function isProfileLocationArray(value: ProfileFieldValue): value is ProfileLocation[] {
+    return Array.isArray(value) && value.every((item) => typeof item === 'object' && item !== null && 'name' in item);
+}
+
+function isProfileLinkMetadataArray(value: ProfileFieldValue): value is ProfileLinkMetadata[] {
+    return Array.isArray(value) && value.every((item) => typeof item === 'object' && item !== null && 'url' in item);
+}
+
+/**
+ * Hook for managing profile editing operations
+ * Provides functions to update profile fields and handle saving
+ */
+export const useProfileEditing = () => {
+    const updateProfileMutation = useUpdateProfile();
+
+    /**
+     * Save profile updates to the server using TanStack Query
+     */
+    const saveProfile = useCallback(async (updates: ProfileUpdateData) => {
+        // Prepare update object
+        const updateData: UserProfileUpdate = {};
+
+        if (updates.username !== undefined) {
+            updateData.username = updates.username;
+        }
+        if (updates.email !== undefined) {
+            updateData.email = updates.email;
+        }
+        if (updates.bio !== undefined) {
+            updateData.bio = updates.bio;
+        }
+        if (updates.locations !== undefined) {
+            updateData.locations = updates.locations;
+        }
+        if (updates.links !== undefined) {
+            updateData.links = updates.links;
+        }
+        if (updates.linksMetadata !== undefined) {
+            updateData.linksMetadata = updates.linksMetadata;
+        }
+        if (updates.avatar !== undefined) {
+            updateData.avatar = updates.avatar;
+        }
+        if (updates.phone !== undefined) {
+            updateData.phone = updates.phone;
+        }
+        if (updates.address !== undefined) {
+            updateData.address = updates.address;
+        }
+        if (updates.birthday !== undefined) {
+            updateData.birthday = updates.birthday;
+        }
+
+        // Handle name field
+        if (updates.firstName !== undefined || updates.lastName !== undefined) {
+            const currentUser = useAuthStore.getState().user;
+            const currentName = currentUser?.name;
+            updateData.name = {
+                first: updates.firstName ?? (typeof currentName === 'object' ? currentName?.first : '') ?? '',
+                last: updates.lastName ?? (typeof currentName === 'object' ? currentName?.last : '') ?? '',
+            };
+        }
+
+        try {
+            await updateProfileMutation.mutateAsync(updateData);
+            return true;
+        } catch (error: unknown) {
+            // Error toast is handled by the mutation
+            return false;
+        }
+    }, [updateProfileMutation]);
+
+    /**
+     * Update a single profile field
+     */
+    const updateField = useCallback(async (field: string, value: ProfileFieldValue) => {
+        const updates: ProfileUpdateData = {};
+        
+        switch (field) {
+            case 'firstName':
+                if (typeof value !== 'string') return false;
+                updates.firstName = value;
+                break;
+            case 'username':
+                if (typeof value !== 'string') return false;
+                updates.username = value;
+                break;
+            case 'email':
+                if (typeof value !== 'string') return false;
+                updates.email = value;
+                break;
+            case 'bio':
+                if (typeof value !== 'string') return false;
+                updates.bio = value;
+                break;
+            case 'phone':
+                if (typeof value !== 'string') return false;
+                updates.phone = value;
+                break;
+            case 'address':
+                if (typeof value !== 'string') return false;
+                updates.address = value;
+                break;
+            case 'birthday':
+                if (typeof value !== 'string') return false;
+                updates.birthday = value;
+                break;
+            case 'location':
+                if (!isProfileLocationArray(value)) return false;
+                updates.locations = value;
+                break;
+            case 'links':
+                if (!isProfileLinkMetadataArray(value)) return false;
+                updates.linksMetadata = value;
+                updates.links = value.map((link) => link.url);
+                break;
+            default:
+                return false;
+        }
+
+        return await saveProfile(updates);
+    }, [saveProfile]);
+
+    return {
+        saveProfile,
+        updateField,
+        isSaving: updateProfileMutation.isPending,
+    };
+};
+
+

package/src/ui/hooks/useQueryClient.ts

@@ -0,0 +1,17 @@
+import { useQueryClient as useTanStackQueryClient } from '@tanstack/react-query';
+import type { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Custom hook to access the QueryClient
+ * Provides type safety and ensures client is available
+ */
+export const useQueryClient = (): QueryClient => {
+  const queryClient = useTanStackQueryClient();
+  
+  if (!queryClient) {
+    throw new Error('QueryClient is not available. Make sure OxyProvider is wrapping your app.');
+  }
+  
+  return queryClient;
+};
+

package/src/ui/hooks/useReduceMotion.ts

@@ -0,0 +1,58 @@
+/**
+ * useReduceMotion
+ *
+ * Reactive boolean reflecting the OS "reduce motion" accessibility preference.
+ * Wraps `AccessibilityInfo` as an external store via `useSyncExternalStore` — the
+ * effect-free, React-Compiler-safe way to read an external mutable source. The
+ * initial value is read asynchronously once (the platform API is a Promise) and
+ * cached module-side; subsequent changes arrive via the `reduceMotionChanged`
+ * event. Mirrors the `useOnlineStatus` pattern.
+ *
+ * Consumers use it to pin entrance/stagger animations off under reduce-motion.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+let cachedReduceMotion = false;
+let initialized = false;
+const listeners = new Set<() => void>();
+
+const notifyAll = (): void => {
+    for (const listener of listeners) listener();
+};
+
+const setCached = (value: boolean): void => {
+    if (cachedReduceMotion === value) return;
+    cachedReduceMotion = value;
+    notifyAll();
+};
+
+const subscribeReduceMotion = (notify: () => void): (() => void) => {
+    // Populate the cache the first time anyone subscribes (the platform read is
+    // async, so it cannot be a synchronous `getSnapshot`).
+    if (!initialized) {
+        initialized = true;
+        AccessibilityInfo.isReduceMotionEnabled()
+            .then(setCached)
+            .catch(() => {
+                // No preference available — the `false` default stands.
+            });
+    }
+    listeners.add(notify);
+    const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setCached);
+    return () => {
+        listeners.delete(notify);
+        sub.remove();
+    };
+};
+
+const getSnapshot = (): boolean => cachedReduceMotion;
+
+// SSR/web-first paint: assume motion is allowed (no reduce) until the async read
+// resolves — matches the prior default.
+const getServerSnapshot = (): boolean => false;
+
+export function useReduceMotion(): boolean {
+    return useSyncExternalStore(subscribeReduceMotion, getSnapshot, getServerSnapshot);
+}

package/src/ui/hooks/useResolvedFileUrls.ts

@@ -0,0 +1,170 @@
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { FileMetadata } from '@oxy.so/core';
+
+/**
+ * The variant-aware batch resolver contract (`@oxy.so/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.
+ */
+export interface AssetUrlBatchResolver {
+  getFileDownloadUrls(
+    requests: Array<{ fileId: string; variant?: string }>,
+    options?: { expiresIn?: number; context?: string },
+  ): Promise<Record<string, string>>;
+}
+
+/**
+ * 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. */
+export const ASSET_DOWNLOAD_URLS_QUERY_KEY = 'assetDownloadUrls' as const;
+
+/**
+ * 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
+ * `@oxy.so/core`'s `avatarUtils.updateAvatarVisibility`.
+ */
+export function isOptimisticFile(file: Pick<FileMetadata, 'id' | 'metadata'>): boolean {
+  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: FileMetadata): string | undefined {
+  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: FileMetadata): string | undefined {
+  const uri = (file.metadata as Record<string, unknown> | undefined)?.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).
+ */
+export function fileThumbSource(
+  file: FileMetadata,
+  resolved: ReadonlyMap<string, string>,
+): string | undefined {
+  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".
+ */
+export function useResolvedFileUrls(
+  oxyServices: AssetUrlBatchResolver,
+  files: FileMetadata[],
+  /** Active viewer account id — media tokens are minted per user; must be in the query key. */
+  viewerId?: string | null,
+): ReadonlyMap<string, string> {
+  const viewerKey = viewerId ?? '';
+  const requests = useMemo(() => {
+    const list: Array<{ fileId: string; variant?: string }> = [];
+    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 = useMemo(
+    () => requests.map((r) => `${r.fileId}:${r.variant ?? ''}`).sort().join('|'),
+    [requests],
+  );
+
+  const query = 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 (): Promise<Record<string, string>> => {
+      const merged: Record<string, string> = {};
+      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 useMemo(() => {
+    const map = new Map<string, string>();
+    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]);
+}

package/src/ui/hooks/useSessionManagement.ts

@@ -0,0 +1,228 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { isDev, type ApiError, type User } from '@oxy.so/core';
+import type { ClientSession } from '@oxy.so/core';
+import { fetchSessionsWithFallback } from '../utils/sessionHelpers';
+import { getStorageKeys, type StorageInterface } from '../utils/storageHelpers';
+import { handleAuthError, isInvalidSessionError } from '../utils/errorHandlers';
+import type { OxyServices } from '@oxy.so/core';
+import type { QueryClient } from '@tanstack/react-query';
+import { clearQueryCache } from './queryClient';
+import { isWebBrowser } from '../utils/isWebBrowser';
+import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
+import type { OxyRuntime } from '../runtime';
+
+export interface UseSessionManagementOptions {
+  oxyServices: OxyServices;
+  /** The one owner of `sessions` / `activeSessionId` / the signed-in account. */
+  runtime: OxyRuntime;
+  storage: StorageInterface | null;
+  storageKeyPrefix?: string;
+  onAuthStateChange?: (user: User | null) => void;
+  onError?: (error: ApiError) => void;
+  setAuthError?: (message: string | null) => void;
+  logger?: (message: string, error?: unknown) => void;
+  queryClient?: QueryClient | null;
+}
+
+export interface UseSessionManagementResult {
+  /** Persist the projected session-id list. Handed to the runtime as its projection sink. */
+  saveSessionIds: (sessionIds: string[]) => void;
+  saveActiveSessionId: (sessionId: string) => Promise<void>;
+  /**
+   * The legacy `validateSession`-keyed switch. Reachable from exactly ONE
+   * caller: `performSignIn`'s same-user duplicate-session dedup. The switch a
+   * consumer sees on the context is the `SessionClient` one in `OxyContext`.
+   */
+  switchSession: (sessionId: string) => Promise<User>;
+  /** Tear down the local session: runtime projection, caches, storage, tokens. */
+  clearSessionState: () => Promise<void>;
+  storageKeys: ReturnType<typeof getStorageKeys>;
+}
+
+const DEFAULT_SAVE_ERROR_MESSAGE = 'Failed to save session data';
+const CLEAR_STORAGE_ERROR = 'Failed to clear storage';
+
+/**
+ * Session persistence and the one legacy switch left, over the runtime.
+ *
+ * This hook used to hold its OWN `sessions` / `activeSessionId` React state
+ * plus six refs mirroring them so its callbacks could avoid widening their
+ * dependency arrays. That made it a second owner of facts `SessionClient`
+ * already had, reconciled only by whichever `useEffect` ran last. Both are gone:
+ * the runtime owns them, this hook writes through it, and the refs mirrored
+ * nothing once there was nothing local to mirror.
+ *
+ * `refreshSessions`, `trackRemovedSession` and `isRefreshInFlight` are deleted
+ * outright — every one of them was dropped unread at the single call site.
+ */
+export const useSessionManagement = ({
+  oxyServices,
+  runtime,
+  storage,
+  storageKeyPrefix,
+  onAuthStateChange,
+  onError,
+  setAuthError,
+  logger,
+  queryClient,
+}: UseSessionManagementOptions): UseSessionManagementResult => {
+  const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
+  const runtimeRef = useRef(runtime);
+  runtimeRef.current = runtime;
+
+  const saveSessionIds = useCallback(
+    (sessionIds: string[]): void => {
+      if (!storage) return;
+      const uniqueIds = Array.from(new Set(sessionIds));
+      storage.setItem(storageKeys.sessionIds, JSON.stringify(uniqueIds)).catch((error: unknown) => {
+        if (logger) {
+          logger(DEFAULT_SAVE_ERROR_MESSAGE, error);
+        } else if (isDev()) {
+          console.warn('Failed to save session IDs:', error);
+        }
+      });
+    },
+    [logger, storage, storageKeys.sessionIds],
+  );
+
+  const saveActiveSessionId = useCallback(
+    async (sessionId: string): Promise<void> => {
+      if (!storage) return;
+      try {
+        await storage.setItem(storageKeys.activeSessionId, sessionId);
+      } catch (error) {
+        handleAuthError(error, {
+          defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
+          code: 'SESSION_PERSISTENCE_ERROR',
+          onError,
+          setAuthError,
+          logger,
+        });
+      }
+    },
+    [logger, onError, setAuthError, storage, storageKeys.activeSessionId],
+  );
+
+  const clearSessionStorage = useCallback(async (): Promise<void> => {
+    if (!storage) return;
+    try {
+      await storage.removeItem(storageKeys.activeSessionId);
+      await storage.removeItem(storageKeys.sessionIds);
+    } catch (error) {
+      handleAuthError(error, {
+        defaultMessage: CLEAR_STORAGE_ERROR,
+        code: 'STORAGE_ERROR',
+        onError,
+        setAuthError,
+        logger,
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId, storageKeys.sessionIds]);
+
+  const clearSessionState = useCallback(async (): Promise<void> => {
+    runtimeRef.current.clearSession();
+    resetSessionScopedStores();
+
+    // Clear the access token on the client instance. Without this the token
+    // store retained the stale bearer until the next 401, leaving the instance
+    // "logged in" at the HTTP layer and — via the provider's token 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();
+
+    if (queryClient) {
+      queryClient.clear();
+    }
+
+    if (storage) {
+      try {
+        await clearQueryCache(storage);
+      } catch (error) {
+        if (logger) {
+          logger('Failed to clear persisted query cache', error);
+        }
+      }
+    }
+
+    await clearSessionStorage();
+    onAuthStateChange?.(null);
+  }, [clearSessionStorage, onAuthStateChange, oxyServices, queryClient, storage, logger]);
+
+  const switchSession = useCallback(
+    async (sessionId: string): Promise<User> => {
+      try {
+        // On web the bearer must already be in memory (planted by
+        // `claimSessionByToken`, a cold-boot restore step, or a prior
+        // `SessionClient` sync) before validating — there is no client-side
+        // refresh-cookie slot to fall back on. The native path arrives here only
+        // after a bearer has been planted too.
+        if (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 as User;
+        const activeRuntime = runtimeRef.current;
+        activeRuntime.batch(() => {
+          activeRuntime.setTokenReady(true);
+          activeRuntime.setActiveSessionId(sessionId);
+          activeRuntime.setAccount(user);
+        });
+        await saveActiveSessionId(sessionId);
+        onAuthStateChange?.(user);
+
+        try {
+          const deviceSessions = await fetchSessionsWithFallback(oxyServices, sessionId, {
+            fallbackUserId: user.id,
+            logger,
+          });
+          activeRuntime.mergeSessions(deviceSessions, { merge: true });
+        } catch (error) {
+          if (isDev()) {
+            console.warn('Failed to synchronize sessions after switch:', error);
+          }
+        }
+
+        return user;
+      } catch (error) {
+        const invalidSession = 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.
+          const remaining: ClientSession[] = runtimeRef.current
+            .getSnapshot()
+            .sessions.filter((session) => session.sessionId !== sessionId);
+          runtimeRef.current.mergeSessions(remaining, { merge: false });
+        }
+
+        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');
+      }
+    },
+    [logger, onAuthStateChange, onError, oxyServices, saveActiveSessionId, setAuthError],
+  );
+
+  return {
+    saveSessionIds,
+    saveActiveSessionId,
+    switchSession,
+    clearSessionState,
+    storageKeys,
+  };
+};