@oxy.so/services 1.0.0

package/src/ui/hooks/useFollowTarget.ts

@@ -0,0 +1,223 @@
+/**
+ * `useFollowTarget` — the one hook every application uses to follow anything.
+ *
+ * Wraps the `/v2/follows` SDK methods with the store above, an optimistic
+ * update, and a rollback. Nothing in here knows what kind of thing it is
+ * following, which is the property that lets an application the SDK has never
+ * heard of use it without a release of this package.
+ *
+ * ## Optimism, and its one limit
+ *
+ * A follow flips the button immediately and rolls back if the server refuses,
+ * because the round trip is long enough to feel like a bug otherwise. But an
+ * optimistic follow has no relationship id until the server answers, and every
+ * other operation addresses the relationship — so those stay disabled for the
+ * width of one request rather than being sent with a guessed id.
+ */
+
+import { useCallback, useEffect } from 'react';
+import type { FollowStatus } from '@oxy.so/contracts';
+import { useOxy } from '../context/OxyContext';
+import {
+  isCompleteFollowStatus,
+  isFollowedGlobally,
+  UNKNOWN_FOLLOW_STATUS,
+  useFollowTargetStore,
+  withApplicationMode,
+} from '../stores/followTargetStore';
+
+export interface UseFollowTargetResult {
+  status: FollowStatus;
+  /**
+   * Whether the user follows this at all — NOT `effectiveState`, which reports
+   * `not_following` for a follow merely switched off in this application.
+   */
+  isFollowing: boolean;
+  /** True until the first read settles. Distinct from "not following". */
+  isUnknown: boolean;
+  isPending: boolean;
+  error: string | undefined;
+  /**
+   * Every mutation resolves to whether the server ACCEPTED it.
+   *
+   * They never reject — a refusal becomes `error` in the store, so the button
+   * can render it — which means a caller that only awaits them cannot tell a
+   * write that happened from one that did not. Returning the outcome is what
+   * lets a caller mirror the change somewhere else without mirroring failures
+   * too.
+   */
+  follow: (options?: { expiresIn?: number }) => Promise<boolean>;
+  unfollow: () => Promise<boolean>;
+  /** Stop acting on this follow HERE, without giving it up everywhere. */
+  disableHere: () => Promise<boolean>;
+  enableHere: () => Promise<boolean>;
+  refresh: () => Promise<void>;
+}
+
+export function useFollowTarget(
+  targetId: string | undefined,
+  options?: { initialStatus?: FollowStatus }
+): UseFollowTargetResult {
+  const { oxyServices, canUsePrivateApi } = useOxy();
+
+  const status = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.statuses[targetId] : undefined), [targetId])
+  );
+  const isPending = useFollowTargetStore(
+    useCallback((s) => (targetId ? (s.pending[targetId] ?? false) : false), [targetId])
+  );
+  const error = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.errors[targetId] : undefined), [targetId])
+  );
+
+  const initialStatus = options?.initialStatus;
+
+  // A caller that already knows the status — a follow list, a feed payload —
+  // seeds it rather than making this hook re-ask once per rendered row.
+  useEffect(() => {
+    if (!targetId || !initialStatus) return;
+    const store = useFollowTargetStore.getState();
+    if (!store.statuses[targetId]) store.setStatus(targetId, initialStatus);
+  }, [targetId, initialStatus]);
+
+  const refresh = useCallback(async () => {
+    // Gated on `canUsePrivateApi`, not on `isAuthenticated`: during the session
+    // cold boot the second is true well before the first, and a read sent in
+    // that window 401s and would leave the button stuck reporting an error the
+    // user cannot act on.
+    if (!targetId || !canUsePrivateApi) return;
+    try {
+      const next = await oxyServices.getFollowTargetStatus(targetId);
+      useFollowTargetStore.getState().setStatus(targetId, next);
+      useFollowTargetStore.getState().setError(targetId, undefined);
+    } catch (e) {
+      const store = useFollowTargetStore.getState();
+      const message = e instanceof Error ? e.message : 'Could not read follow status';
+      // Leave `isUnknown` false so the button stays interactive and can retry.
+      // A failed read is not the same as "never asked" — disabling forever would
+      // strand the user with no affordance when the network blips.
+      if (!store.statuses[targetId]) {
+        store.setStatus(targetId, UNKNOWN_FOLLOW_STATUS);
+      }
+      store.setError(targetId, message);
+    }
+  }, [targetId, canUsePrivateApi, oxyServices]);
+
+  useEffect(() => {
+    if (!targetId || !canUsePrivateApi) return;
+    const existing = useFollowTargetStore.getState().statuses[targetId];
+    if (existing && isCompleteFollowStatus(existing)) return;
+    void refresh();
+  }, [targetId, canUsePrivateApi, refresh]);
+
+  /**
+   * Run a mutation optimistically: show `optimistic` at once, keep the previous
+   * value, and put it back if the server refuses. Every mutation below goes
+   * through this so the rollback cannot be forgotten in one of them.
+   */
+  const mutate = useCallback(
+    async (
+      optimistic: FollowStatus,
+      run: () => Promise<FollowStatus | undefined>,
+      failureMessage: string
+    ): Promise<boolean> => {
+      if (!targetId) return false;
+      const store = useFollowTargetStore.getState();
+      const previous = store.statuses[targetId];
+      store.setStatus(targetId, optimistic);
+      store.setPending(targetId, true);
+      store.setError(targetId, undefined);
+      try {
+        const settled = await run();
+        if (settled) useFollowTargetStore.getState().setStatus(targetId, settled);
+        return true;
+      } catch (e) {
+        const s = useFollowTargetStore.getState();
+        // Back to what was true, not to a guess. Clearing the entry instead
+        // would make the next render ask again and flash the wrong state.
+        if (previous) s.setStatus(targetId, previous);
+        s.setError(targetId, e instanceof Error ? e.message : failureMessage);
+        return false;
+      } finally {
+        useFollowTargetStore.getState().setPending(targetId, false);
+      }
+    },
+    [targetId]
+  );
+
+  const current = status ?? UNKNOWN_FOLLOW_STATUS;
+
+  const follow = useCallback(
+    async (opts?: { expiresIn?: number }) => {
+      if (!targetId) return false;
+      return mutate(
+        {
+          ...withApplicationMode({ ...current, globalState: 'active' }, current.applicationMode),
+          ...(opts?.expiresIn
+            ? { expiresAt: new Date(Date.now() + opts.expiresIn * 1000).toISOString() }
+            : {}),
+        },
+        // The server returns the whole resulting status, so store it rather
+        // than reconstructing one: `effectiveState`'s derivation lives there,
+        // and a client recomputing it is a second implementation of one rule.
+        async () => (await oxyServices.followTarget(targetId, opts)).status,
+        'Could not follow'
+      );
+    },
+    [targetId, current, mutate, oxyServices]
+  );
+
+  const unfollow = useCallback(async () => {
+    const relationshipId = current.relationshipId;
+    if (!targetId || !relationshipId) return false;
+    return mutate(
+      { ...UNKNOWN_FOLLOW_STATUS },
+      async () => {
+        await oxyServices.unfollowTarget(relationshipId);
+        return { ...UNKNOWN_FOLLOW_STATUS };
+      },
+      'Could not unfollow'
+    );
+  }, [targetId, current.relationshipId, mutate, oxyServices]);
+
+  const disableHere = useCallback(async () => {
+    const relationshipId = current.relationshipId;
+    if (!targetId || !relationshipId) return false;
+    const optimistic = withApplicationMode(current, 'disabled');
+    return mutate(
+      optimistic,
+      async () => {
+        await oxyServices.setFollowApplicationMode(relationshipId, 'disabled');
+        return optimistic;
+      },
+      'Could not change this app’s setting for this follow'
+    );
+  }, [targetId, current, mutate, oxyServices]);
+
+  const enableHere = useCallback(async () => {
+    const relationshipId = current.relationshipId;
+    if (!targetId || !relationshipId) return false;
+    const optimistic = withApplicationMode(current, 'inherit');
+    return mutate(
+      optimistic,
+      async () => {
+        await oxyServices.restoreFollowInheritance(relationshipId);
+        return optimistic;
+      },
+      'Could not change this app’s setting for this follow'
+    );
+  }, [targetId, current, mutate, oxyServices]);
+
+  return {
+    status: current,
+    isFollowing: isFollowedGlobally(current),
+    isUnknown: status === undefined,
+    isPending,
+    error,
+    follow,
+    unfollow,
+    disableHere,
+    enableHere,
+    refresh,
+  };
+}

package/src/ui/hooks/useI18n.ts

@@ -0,0 +1,32 @@
+import { useMemo } from 'react';
+import { useOptionalOxy } from '../context/OxyContext';
+import { translate } from '@oxy.so/core';
+
+/**
+ * The locale `@oxy.so/core`'s translator falls back to. Mirrors its own
+ * `FALLBACK`, so a surface rendered without a provider reads the same strings
+ * an unrecognised locale would.
+ */
+const FALLBACK_LOCALE = 'en-US';
+
+/**
+ * Display copy for SDK surfaces.
+ *
+ * This is the ONE hook that reads the runtime optionally. The locale is display
+ * metadata, not session state — ADR 0004 lists it among the things that come off
+ * the central value entirely — and purely presentational surfaces
+ * (`OxyConsentScreen`, `OxySignInRequestSurface`) are rendered outside a
+ * provider on purpose: `packages/auth`'s production-bundle probe builds the real
+ * Vite bundle and renders the surface standalone to prove every element beneath
+ * it links. Throwing there would report a linkage failure that is not one.
+ *
+ * Anything that reads or mutates session state uses `useOxy()`, which throws.
+ */
+export function useI18n() {
+  const oxy = useOptionalOxy();
+  const currentLanguage = oxy?.currentLanguage ?? FALLBACK_LOCALE;
+  const t = useMemo(() => {
+    return (key: string, vars?: Record<string, string | number>) => translate(currentLanguage, key, vars);
+  }, [currentLanguage]);
+  return { t, locale: currentLanguage };
+}

package/src/ui/hooks/useLanguageManagement.ts

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { ApiError, User, SupportedLanguage } from '@oxy.so/core';
+import {
+  FALLBACK_LOCALE,
+  SUPPORTED_LANGUAGES,
+  getBaseLanguage,
+  getLanguageMetadata,
+  getLanguageName,
+  getNativeLanguageName,
+  getPrimaryLanguage,
+  getUserLanguages,
+  normalizeLocale,
+} from '@oxy.so/core';
+import type { StorageInterface } from '../utils/storageHelpers';
+import { extractErrorMessage } from '../utils/errorHandlers';
+
+export interface UseLanguageManagementOptions {
+  storage: StorageInterface | null;
+  languageKey: string;
+  /**
+   * The active account, when signed in. When present, the account's primary
+   * locale (`languages[0]`) is authoritative for the app's UI locale; when
+   * `null` the device locale (or a locally-chosen guest override) is used.
+   */
+  user: User | null;
+  onError?: (error: ApiError) => void;
+  logger?: (message: string, error?: unknown) => void;
+}
+
+export interface UseLanguageManagementResult {
+  /**
+   * The active UI locale (a canonical `language-REGION` tag). Derived, never
+   * stored: the account's primary locale when signed in, otherwise the
+   * locally-chosen guest override, otherwise the device locale.
+   */
+  currentLanguage: string;
+  /**
+   * The ordered account locales (primary first) when signed in, or the single
+   * guest override when signed out. Empty only before the guest override loads
+   * and no device locale resolves.
+   */
+  languages: string[];
+  metadata: SupportedLanguage | null;
+  languageName: string;
+  nativeLanguageName: string;
+  /**
+   * Persist a single locally-owned locale (guest / device override) and mark it
+   * primary. For signed-in accounts, locale changes are written to the account
+   * (`updateProfile({ languages })`) instead — the derived `currentLanguage`
+   * then follows the refreshed `user`.
+   */
+  setLanguage: (locale: string) => Promise<void>;
+  hydrateLanguage: () => Promise<void>;
+}
+
+/**
+ * Append `locale` to an ordered locale list if not already present. Canonical
+ * order is preserved; the new locale lands last (non-primary).
+ */
+export function addLocale(languages: readonly string[], locale: string): string[] {
+  const canonical = normalizeLocale(locale);
+  if (!canonical) return [...languages];
+  if (languages.includes(canonical)) return [...languages];
+  return [...languages, canonical];
+}
+
+/**
+ * Remove `locale` from an ordered locale list. The list's new first element
+ * becomes the primary locale.
+ */
+export function removeLocale(languages: readonly string[], locale: string): string[] {
+  const canonical = normalizeLocale(locale);
+  if (!canonical) return [...languages];
+  return languages.filter((entry) => entry !== canonical);
+}
+
+/**
+ * Move `locale` to the front of an ordered locale list, making it primary.
+ * Adds it if it was not already present.
+ */
+export function setPrimaryLocale(languages: readonly string[], locale: string): string[] {
+  const canonical = normalizeLocale(locale);
+  if (!canonical) return [...languages];
+  return [canonical, ...languages.filter((entry) => entry !== canonical)];
+}
+
+/**
+ * Resolve the device/browser locale, mapped to a supported catalog locale.
+ *
+ * Reads the platform's ordered locale preferences (`navigator.languages` /
+ * `navigator.language` on web, `Intl.DateTimeFormat().resolvedOptions().locale`
+ * on Hermes) and returns the first that resolves to a supported locale —
+ * either exactly or by base-language match (`fr-BE` → `fr-FR`). Falls back to
+ * {@link FALLBACK_LOCALE} when nothing resolves. Pure and side-effect free.
+ */
+function resolveDeviceLocale(): string {
+  const candidates: string[] = [];
+
+  if (typeof navigator !== 'undefined') {
+    const nav = navigator as Navigator & { languages?: readonly string[] };
+    if (Array.isArray(nav.languages)) {
+      candidates.push(...nav.languages);
+    }
+    if (typeof nav.language === 'string') {
+      candidates.push(nav.language);
+    }
+  }
+
+  try {
+    const intlLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (intlLocale) {
+      candidates.push(intlLocale);
+    }
+  } catch {
+    // Intl is unavailable or incomplete on this runtime — fall through to the
+    // navigator-provided candidates (or the fallback locale below).
+  }
+
+  for (const candidate of candidates) {
+    const exact = normalizeLocale(candidate);
+    if (exact) return exact;
+    const base = getBaseLanguage(candidate);
+    const byBase = SUPPORTED_LANGUAGES.find((entry) => entry.language === base);
+    if (byBase) return byBase.code;
+  }
+
+  return FALLBACK_LOCALE;
+}
+
+/**
+ * Resolve and manage the app's active UI locale.
+ *
+ * The active locale is DERIVED, not stored:
+ *  - Signed in  → the account's primary locale (`getPrimaryLanguage(user)`),
+ *    falling back to {@link FALLBACK_LOCALE}. This is what makes every Oxy app
+ *    follow the account's language automatically.
+ *  - Signed out → a locally-chosen guest override if one exists, otherwise the
+ *    device locale.
+ *
+ * The only external system this hook synchronizes with is local storage (the
+ * guest override), which is loaded once on mount.
+ */
+export const useLanguageManagement = ({
+  storage,
+  languageKey,
+  user,
+  onError,
+  logger,
+}: UseLanguageManagementOptions): UseLanguageManagementResult => {
+  // The device locale is fixed for the lifetime of the runtime.
+  const deviceLanguage = useMemo(resolveDeviceLocale, []);
+
+  // The locally-owned guest override (a single locale). `null` until loaded
+  // from storage or explicitly set; the derived locale falls back to the device
+  // locale while it is `null`.
+  const [guestLanguage, setGuestLanguage] = useState<string | null>(null);
+
+  const loadLanguageFromStorage = useCallback(async (): Promise<void> => {
+    if (!storage) {
+      return;
+    }
+
+    try {
+      const savedLanguageRaw = await storage.getItem(languageKey);
+      const normalized = savedLanguageRaw ? normalizeLocale(savedLanguageRaw) : undefined;
+      if (normalized) {
+        setGuestLanguage(normalized);
+      }
+    } catch (error) {
+      const message = extractErrorMessage(error, 'Failed to load language preference');
+      onError?.({
+        message,
+        code: 'LANGUAGE_LOAD_ERROR',
+        status: 500,
+      });
+      if (logger) {
+        logger(message, error);
+      } else if (__DEV__) {
+        console.warn('Failed to load language preference:', error);
+      }
+    }
+  }, [languageKey, logger, onError, storage]);
+
+  useEffect(() => {
+    loadLanguageFromStorage().catch((error) => {
+      if (logger) {
+        logger('Unexpected error loading language', error);
+      }
+    });
+  }, [loadLanguageFromStorage, logger]);
+
+  const setLanguage = useCallback(
+    async (locale: string): Promise<void> => {
+      if (!storage) {
+        throw new Error('Storage not initialized');
+      }
+
+      const normalized = normalizeLocale(locale);
+      if (!normalized) {
+        throw new Error(`Unsupported locale: ${locale}`);
+      }
+
+      try {
+        await storage.setItem(languageKey, normalized);
+        setGuestLanguage(normalized);
+      } catch (error) {
+        const message = extractErrorMessage(error, 'Failed to save language preference');
+        onError?.({
+          message,
+          code: 'LANGUAGE_SAVE_ERROR',
+          status: 500,
+        });
+        if (logger) {
+          logger(message, error);
+        } else if (__DEV__) {
+          console.warn('Failed to save language preference:', error);
+        }
+        throw error instanceof Error ? error : new Error(message);
+      }
+    },
+    [languageKey, logger, onError, storage],
+  );
+
+  const languages = useMemo<string[]>(() => {
+    if (user) {
+      return getUserLanguages(user);
+    }
+    return guestLanguage ? [guestLanguage] : [];
+  }, [user, guestLanguage]);
+
+  const currentLanguage = useMemo<string>(() => {
+    if (user) {
+      return getPrimaryLanguage(user) ?? FALLBACK_LOCALE;
+    }
+    return guestLanguage ?? deviceLanguage;
+  }, [user, guestLanguage, deviceLanguage]);
+
+  const metadata = useMemo(() => getLanguageMetadata(currentLanguage), [currentLanguage]);
+  const languageName = useMemo(() => getLanguageName(currentLanguage), [currentLanguage]);
+  const nativeLanguageName = useMemo(
+    () => getNativeLanguageName(currentLanguage),
+    [currentLanguage],
+  );
+
+  return {
+    currentLanguage,
+    languages,
+    metadata,
+    languageName,
+    nativeLanguageName,
+    setLanguage,
+    hydrateLanguage: loadLanguageFromStorage,
+  };
+};

package/src/ui/hooks/useMutationStatus.ts

@@ -0,0 +1,111 @@
+/**
+ * useMutationStatus
+ *
+ * Aggregates counts of in-flight, paused (offline), and errored mutations
+ * from the TanStack Query mutation cache. Useful for showing a global
+ * "Syncing..." indicator in the app shell.
+ */
+
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import { useQueryClient, type Mutation, type QueryClient } from '@tanstack/react-query';
+
+export interface MutationStatus {
+  /** Mutations currently running (status === 'pending', not paused). */
+  pending: number;
+  /** Mutations paused waiting for the network to come back. */
+  paused: number;
+  /** Mutations that failed and have not been retried. */
+  erroring: number;
+  /** Total of `pending + paused + erroring`. */
+  total: number;
+  /** True if any mutation is paused (i.e. waiting for connectivity). */
+  isOffline: boolean;
+  /** True if any work is in flight or pending sync. */
+  isSyncing: boolean;
+}
+
+function computeStatus(queryClient: QueryClient): MutationStatus {
+  const mutations: Mutation[] = queryClient.getMutationCache().getAll();
+  let pending = 0;
+  let paused = 0;
+  let erroring = 0;
+
+  for (const m of mutations) {
+    const { status, isPaused } = m.state;
+    if (isPaused) {
+      paused += 1;
+      continue;
+    }
+    if (status === 'pending') {
+      pending += 1;
+      continue;
+    }
+    if (status === 'error') {
+      erroring += 1;
+    }
+  }
+
+  const total = pending + paused + erroring;
+  return {
+    pending,
+    paused,
+    erroring,
+    total,
+    isOffline: paused > 0,
+    isSyncing: pending > 0 || paused > 0,
+  };
+}
+
+const EMPTY_SNAPSHOT: MutationStatus = {
+  pending: 0,
+  paused: 0,
+  erroring: 0,
+  total: 0,
+  isOffline: false,
+  isSyncing: false,
+};
+
+function snapshotsEqual(a: MutationStatus, b: MutationStatus): boolean {
+  return (
+    a.pending === b.pending &&
+    a.paused === b.paused &&
+    a.erroring === b.erroring &&
+    a.total === b.total &&
+    a.isOffline === b.isOffline &&
+    a.isSyncing === b.isSyncing
+  );
+}
+
+export function useMutationStatus(): MutationStatus {
+  const queryClient = useQueryClient();
+
+  // Cache the last returned snapshot so `useSyncExternalStore`'s tearing
+  // check sees the same reference between renders unless the underlying
+  // mutation cache actually changed. Without this React 19 enters an
+  // infinite render loop because every call to `computeStatus` returns
+  // a fresh object literal.
+  const cachedRef = useRef<MutationStatus>(EMPTY_SNAPSHOT);
+
+  const subscribe = useCallback(
+    (notify: () => void): (() => void) => {
+      const cache = queryClient.getMutationCache();
+      return cache.subscribe(() => {
+        notify();
+      });
+    },
+    [queryClient],
+  );
+
+  const getSnapshot = useCallback((): MutationStatus => {
+    const next = computeStatus(queryClient);
+    if (snapshotsEqual(cachedRef.current, next)) {
+      return cachedRef.current;
+    }
+    cachedRef.current = next;
+    return next;
+  }, [queryClient]);
+
+  const getServerSnapshot = useCallback((): MutationStatus => EMPTY_SNAPSHOT, []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/ui/hooks/useOnlineStatus.ts

@@ -0,0 +1,30 @@
+/**
+ * useOnlineStatus
+ *
+ * Reactive boolean reflecting TanStack Query's `onlineManager` state.
+ * Mirrors browser `online`/`offline` events on web and NetInfo reachability
+ * updates on native (both wired up in `OxyProvider`, aligned with Bloom's
+ * `ConnectionStatusToasts` semantics).
+ *
+ * Use this for surfacing offline UI — an OfflineBanner, a disabled "Sync"
+ * button, an inline "queued" badge on pending writes, etc. For pending /
+ * paused mutation counts use `useMutationStatus()` instead.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { onlineManager } from '@tanstack/react-query';
+
+const getOnlineSnapshot = (): boolean => onlineManager.isOnline();
+
+const subscribeOnline = (notify: () => void): (() => void) => {
+  return onlineManager.subscribe(() => {
+    notify();
+  });
+};
+
+// SSR: assume online so SSR-rendered markup doesn't show offline banners.
+const getServerSnapshot = (): boolean => true;
+
+export function useOnlineStatus(): boolean {
+  return useSyncExternalStore(subscribeOnline, getOnlineSnapshot, getServerSnapshot);
+}

package/src/ui/hooks/useOxyEvent.ts

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+
+import { useOxy } from '../context/OxyContext';
+
+/**
+ * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`)
+ * for the lifetime of the component. Payloads arrive as `unknown` — callers
+ * validate shape. Handler identity may change between renders; the latest one
+ * is always invoked.
+ */
+export function useOxyEvent(event: string, handler: (payload: unknown) => void): void {
+  const { sessionClient } = useOxy();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    if (!sessionClient) return;
+    return sessionClient.onServerEvent(event, (payload) => {
+      handlerRef.current(payload);
+    });
+  }, [sessionClient, event]);
+}