@oxy.so/services 1.0.0

package/src/ui/utils/userUtils.ts

@@ -0,0 +1,69 @@
+/**
+ * User display name and date formatting utilities.
+ *
+ * Display-name helpers follow the API contract: prefer `name.displayName` when
+ * present, otherwise fall back to the normalized handle via
+ * `getNormalizedUserHandle`.
+ */
+
+import { getNormalizedUserHandle, type DisplayNameUserShape } from '@oxy.so/core';
+
+/**
+ * Formats a date string to a readable format (e.g., "Feb 21, 2025")
+ */
+export const formatDate = (dateString: string | undefined | null | Date): string => {
+  if (!dateString) return '';
+
+  try {
+    const date = dateString instanceof Date ? dateString : new Date(dateString);
+    if (Number.isNaN(date.getTime())) return '';
+
+    return date.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  } catch {
+    return '';
+  }
+};
+
+function readDisplayName(user: DisplayNameUserShape | null | undefined): string {
+  const name = user?.name;
+  if (!name || typeof name !== 'object') return '';
+  return typeof name.displayName === 'string' ? name.displayName.trim() : '';
+}
+
+/**
+ * Gets a display name from user data.
+ *
+ * Prefers API `name.displayName`, then the normalized handle.
+ */
+export const getDisplayName = (
+  user: DisplayNameUserShape | null | undefined,
+): string => {
+  const displayName = readDisplayName(user);
+  if (displayName) return displayName;
+  return getNormalizedUserHandle(user) ?? '';
+};
+
+/**
+ * Gets a short display name (first token) for compact UI.
+ */
+export const getShortDisplayName = (
+  user: DisplayNameUserShape | null | undefined,
+): string => {
+  const displayName = readDisplayName(user);
+  if (displayName) {
+    const firstToken = displayName.split(/\s+/).find(Boolean);
+    if (firstToken) return firstToken;
+  }
+
+  const handle = getNormalizedUserHandle(user);
+  if (handle) {
+    const firstToken = handle.split(/\s+/).find(Boolean);
+    return firstToken ?? handle;
+  }
+
+  return '';
+};

package/src/utils/hookUtils.ts

@@ -0,0 +1,423 @@
+/**
+ * React hook utilities for common patterns and state management
+ */
+
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+
+// Platform detection for SSR/Node.js/React Native safety
+const isBrowser = typeof window !== 'undefined';
+const hasLocalStorage = isBrowser && typeof window.localStorage !== 'undefined';
+const hasSessionStorage = isBrowser && typeof window.sessionStorage !== 'undefined';
+const hasNavigator = typeof navigator !== 'undefined';
+
+/**
+ * Hook for managing async operations with loading, error, and data states
+ */
+export function useAsync<T>(
+  asyncFn: () => Promise<T>,
+  deps: React.DependencyList = []
+) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: asyncFn is intentionally excluded — this is a mount-only pattern where the callback identity should not cause re-creation
+  const execute = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await asyncFn();
+      setData(result);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setLoading(false);
+    }
+  }, deps);
+
+  return { data, loading, error, execute };
+}
+
+/**
+ * Hook for managing async operations that execute on mount
+ */
+export function useAsyncEffect<T>(
+  asyncFn: () => Promise<T>,
+  deps: React.DependencyList = []
+) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: asyncFn is intentionally excluded — this is a mount-only pattern where the callback identity should not trigger re-execution
+  useEffect(() => {
+    let mounted = true;
+
+    const execute = async () => {
+      try {
+        const result = await asyncFn();
+        if (mounted) {
+          setData(result);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (mounted) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setError(error);
+          setLoading(false);
+        }
+      }
+    };
+
+    execute();
+
+    return () => {
+      mounted = false;
+    };
+  }, deps);
+
+  return { data, loading, error };
+}
+
+/**
+ * Hook for debounced values
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+/**
+ * Hook for throttled values
+ */
+export function useThrottle<T>(value: T, delay: number): T {
+  const [throttledValue, setThrottledValue] = useState<T>(value);
+  const lastRun = useRef(Date.now());
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      if (Date.now() - lastRun.current >= delay) {
+        setThrottledValue(value);
+        lastRun.current = Date.now();
+      }
+    }, delay - (Date.now() - lastRun.current));
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return throttledValue;
+}
+
+/**
+ * Hook for previous value
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T | undefined>(undefined);
+  
+  useEffect(() => {
+    ref.current = value;
+  });
+  
+  return ref.current;
+}
+
+/**
+ * Hook for boolean state with toggle
+ */
+export function useToggle(initialValue = false) {
+  const [value, setValue] = useState(initialValue);
+  
+  const toggle = useCallback(() => setValue(v => !v), []);
+  const setTrue = useCallback(() => setValue(true), []);
+  const setFalse = useCallback(() => setValue(false), []);
+  
+  return { value, toggle, setTrue, setFalse, setValue };
+}
+
+/**
+ * Hook for counter state
+ */
+export function useCounter(initialValue = 0) {
+  const [count, setCount] = useState(initialValue);
+  
+  const increment = useCallback(() => setCount(c => c + 1), []);
+  const decrement = useCallback(() => setCount(c => c - 1), []);
+  const reset = useCallback(() => setCount(initialValue), [initialValue]);
+  const setValue = useCallback((value: number) => setCount(value), []);
+  
+  return { count, increment, decrement, reset, setValue };
+}
+
+/**
+ * Hook for local storage (platform-safe)
+ */
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (!hasLocalStorage) return initialValue;
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch {
+      // Silently fail and return initial value
+      return initialValue;
+    }
+  });
+
+  const setValue = useCallback((value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      if (hasLocalStorage) {
+        window.localStorage.setItem(key, JSON.stringify(valueToStore));
+      }
+    } catch {
+      // Silently fail - storage might be full or blocked
+    }
+  }, [key, storedValue]);
+
+  return [storedValue, setValue] as const;
+}
+
+/**
+ * Hook for session storage (platform-safe)
+ */
+export function useSessionStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (!hasSessionStorage) return initialValue;
+    try {
+      const item = window.sessionStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch {
+      // Silently fail and return initial value
+      return initialValue;
+    }
+  });
+
+  const setValue = useCallback((value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      if (hasSessionStorage) {
+        window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
+      }
+    } catch {
+      // Silently fail - storage might be full or blocked
+    }
+  }, [key, storedValue]);
+
+  return [storedValue, setValue] as const;
+}
+
+/**
+ * Hook for window size (platform-safe)
+ */
+export function useWindowSize() {
+  const [windowSize, setWindowSize] = useState({
+    width: isBrowser ? window.innerWidth : 0,
+    height: isBrowser ? window.innerHeight : 0,
+  });
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const handleResize = () => {
+      setWindowSize({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    };
+
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  }, []);
+
+  return windowSize;
+}
+
+/**
+ * Hook for scroll position (platform-safe)
+ */
+export function useScrollPosition() {
+  const [scrollPosition, setScrollPosition] = useState(0);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const handleScroll = () => {
+      setScrollPosition(window.pageYOffset);
+    };
+
+    window.addEventListener('scroll', handleScroll);
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, []);
+
+  return scrollPosition;
+}
+
+/**
+ * Hook for online/offline status (platform-safe)
+ */
+export function useOnlineStatus() {
+  const [isOnline, setIsOnline] = useState(hasNavigator ? navigator.onLine : true);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const handleOnline = () => setIsOnline(true);
+    const handleOffline = () => setIsOnline(false);
+
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+    };
+  }, []);
+
+  return isOnline;
+}
+
+/**
+ * Hook for media queries (platform-safe)
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const media = window.matchMedia(query);
+    if (media.matches !== matches) {
+      setMatches(media.matches);
+    }
+
+    const listener = () => setMatches(media.matches);
+    media.addEventListener('change', listener);
+
+    return () => media.removeEventListener('change', listener);
+  }, [matches, query]);
+
+  return matches;
+}
+
+/**
+ * Hook for keyboard events (platform-safe)
+ */
+export function useKeyPress(targetKey: string): boolean {
+  const [keyPressed, setKeyPressed] = useState(false);
+
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const downHandler = ({ key }: KeyboardEvent) => {
+      if (key === targetKey) {
+        setKeyPressed(true);
+      }
+    };
+
+    const upHandler = ({ key }: KeyboardEvent) => {
+      if (key === targetKey) {
+        setKeyPressed(false);
+      }
+    };
+
+    window.addEventListener('keydown', downHandler);
+    window.addEventListener('keyup', upHandler);
+
+    return () => {
+      window.removeEventListener('keydown', downHandler);
+      window.removeEventListener('keyup', upHandler);
+    };
+  }, [targetKey]);
+
+  return keyPressed;
+}
+
+/**
+ * Hook for click outside detection (platform-safe)
+ */
+export function useClickOutside(ref: React.RefObject<HTMLElement>, handler: () => void) {
+  useEffect(() => {
+    if (!isBrowser) return;
+
+    const listener = (event: MouseEvent | TouchEvent) => {
+      if (!ref.current || ref.current.contains(event.target as Node)) {
+        return;
+      }
+      handler();
+    };
+
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [ref, handler]);
+}
+
+/**
+ * Hook for form validation
+ */
+export function useFormValidation<T extends Record<string, unknown>>(
+  initialValues: T,
+  validationSchema: (values: T) => Partial<Record<keyof T, string>>
+) {
+  const [values, setValues] = useState<T>(initialValues);
+  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
+  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
+
+  const validate = useCallback((valuesToValidate: T) => {
+    return validationSchema(valuesToValidate);
+  }, [validationSchema]);
+
+  const setValue = useCallback((field: keyof T, value: T[keyof T]) => {
+    setValues(prev => ({ ...prev, [field]: value }));
+    if (touched[field]) {
+      const newErrors = validate({ ...values, [field]: value });
+      setErrors(prev => ({ ...prev, [field]: newErrors[field] }));
+    }
+  }, [values, touched, validate]);
+
+  const setTouchedField = useCallback((field: keyof T) => {
+    setTouched(prev => ({ ...prev, [field]: true }));
+    const newErrors = validate(values);
+    setErrors(prev => ({ ...prev, [field]: newErrors[field] }));
+  }, [values, validate]);
+
+  const isValid = useMemo(() => {
+    const validationErrors = validate(values);
+    return Object.keys(validationErrors).length === 0;
+  }, [values, validate]);
+
+  return {
+    values,
+    errors,
+    touched,
+    isValid,
+    setValue,
+    setTouchedField,
+    setValues,
+    setErrors,
+    setTouched
+  };
+} 

package/src/webauthn/passkeyClient.native.ts

@@ -0,0 +1,26 @@
+/**
+ * Passkey / WebAuthn ceremony client — NATIVE implementation.
+ *
+ * React Native has no browser WebAuthn API, and Oxy's native passkey story is
+ * Commons (shared-keychain / QR handoff), NOT `navigator.credentials`. So this
+ * variant imports NOTHING browser-specific and mirrors the clean default:
+ * unsupported, and the ceremony helpers throw if a caller skipped the gate.
+ */
+
+const WEBAUTHN_WEB_ONLY_MESSAGE =
+  'WebAuthn is web-only; native uses Commons. Passkeys are not available on this platform.';
+
+/** Always `false` on native — there is no browser WebAuthn API. */
+export function isPasskeySupported(): boolean {
+  return false;
+}
+
+/** Not available on native — throws. Guard with {@link isPasskeySupported} first. */
+export async function runRegistrationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}
+
+/** Not available on native — throws. Guard with {@link isPasskeySupported} first. */
+export async function runAuthenticationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}

package/src/webauthn/passkeyClient.ts

@@ -0,0 +1,31 @@
+/**
+ * Passkey / WebAuthn ceremony client — clean default (non-web) implementation.
+ *
+ * This is the base module TypeScript resolves for TYPES and any bundler that
+ * does not pick a platform variant. It intentionally imports NOTHING browser-
+ * specific (no `@simplewebauthn/browser`) so it stays safe for Metro, native
+ * builds, and SSR. The real ceremony lives in `passkeyClient.web.ts`; native
+ * passkeys are Commons' job, so there is no WebAuthn ceremony here.
+ *
+ * `isPasskeySupported()` returns `false` (no relying-party origin / no browser
+ * WebAuthn API), and the ceremony helpers throw a clear error so a caller that
+ * skipped the support gate fails loudly instead of silently.
+ */
+
+const WEBAUTHN_WEB_ONLY_MESSAGE =
+  'WebAuthn is web-only; native uses Commons. Passkeys are not available on this platform.';
+
+/** Always `false` off the web — there is no relying-party origin or WebAuthn API. */
+export function isPasskeySupported(): boolean {
+  return false;
+}
+
+/** Not available off the web — throws. Guard with {@link isPasskeySupported} first. */
+export async function runRegistrationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}
+
+/** Not available off the web — throws. Guard with {@link isPasskeySupported} first. */
+export async function runAuthenticationCeremony(_optionsJSON: unknown): Promise<unknown> {
+  throw new Error(WEBAUTHN_WEB_ONLY_MESSAGE);
+}

package/src/webauthn/passkeyClient.web.ts

@@ -0,0 +1,56 @@
+/**
+ * Passkey / WebAuthn ceremony client — WEB implementation.
+ *
+ * The browser half of the passkey flow: it drives `navigator.credentials`
+ * through `@simplewebauthn/browser`, turning the OPAQUE options the server
+ * emitted (`OxyServices.webauthn{Register,Login}Options`) into the opaque
+ * response the matching `verify` endpoint consumes. Oxy never owns those wire
+ * shapes — `@simplewebauthn/browser` does — so options flow in as `unknown` and
+ * the single cast at this boundary hands them to the library's own types.
+ *
+ * This file is selected ONLY on web (react-native-web / Vite RNW): the sibling
+ * `passkeyClient.native.ts` + the clean default `passkeyClient.ts` deliberately
+ * do NOT import `@simplewebauthn/browser` (a browser-only dependency), per the
+ * platform-split rule. Native passkeys are Commons' job — there is no WebAuthn
+ * ceremony off the web.
+ */
+
+import {
+  startRegistration,
+  startAuthentication,
+  type PublicKeyCredentialCreationOptionsJSON,
+  type PublicKeyCredentialRequestOptionsJSON,
+  type RegistrationResponseJSON,
+  type AuthenticationResponseJSON,
+} from '@simplewebauthn/browser';
+
+/**
+ * True iff this browser can run a WebAuthn ceremony (exposes the
+ * `PublicKeyCredential` global). Gate all passkey UI/entrypoints on this so an
+ * unsupported browser fails loudly rather than throwing mid-ceremony.
+ */
+export function isPasskeySupported(): boolean {
+  return typeof window !== 'undefined' && typeof window.PublicKeyCredential !== 'undefined';
+}
+
+/**
+ * Run the WebAuthn REGISTRATION ceremony (`navigator.credentials.create`) from
+ * the server's opaque creation options, returning the opaque attestation
+ * response for `OxyServices.webauthnRegisterVerify`.
+ */
+export async function runRegistrationCeremony(
+  optionsJSON: unknown,
+): Promise<RegistrationResponseJSON> {
+  return startRegistration({ optionsJSON: optionsJSON as PublicKeyCredentialCreationOptionsJSON });
+}
+
+/**
+ * Run the WebAuthn AUTHENTICATION ceremony (`navigator.credentials.get`) from
+ * the server's opaque request options, returning the opaque assertion response
+ * for `OxyServices.webauthnLoginVerify`.
+ */
+export async function runAuthenticationCeremony(
+  optionsJSON: unknown,
+): Promise<AuthenticationResponseJSON> {
+  return startAuthentication({ optionsJSON: optionsJSON as PublicKeyCredentialRequestOptionsJSON });
+}