@oxy.so/services 11.2.0-oxy-one.2 → 11.2.0-oxy-one.4

package/src/ui/types/navigation.ts

@@ -9,181 +9,181 @@ import type { WebAuthMode } from '../oauth/types';
 import type { ProductAnalytics } from '../analytics/productAnalytics';
 
 export interface StepController {
-    canGoBack: () => boolean;
-    goBack: () => void;
+  canGoBack: () => boolean;
+  goBack: () => void;
 }
 
 export interface BaseScreenProps {
-    // Navigation props
-    navigate?: (screen: RouteName, props?: Record<string, unknown>) => void;
-    goBack?: () => void;
-    /** Whether the host surface can navigate back — a deeper frame OR a prior step. */
-    canGoBack?: () => boolean;
-    onClose?: () => void;
-    onAuthenticated?: (payload?: unknown) => void;
-    /**
-     * Dismiss THIS surface, resolving the `present()` promise that opened it
-     * with `result`. Injected by the surface host (the P1 surface stack). Picker
-     * and crop screens use it to hand a typed result back to the awaiting
-     * `surfaces.present(...)` call instead of an untyped `onSelect`/`onConfirm`
-     * callback prop.
-     */
-    dismiss?: (result?: unknown) => void;
-    
-    // Theme props
-    theme?: 'light' | 'dark' | string;
-    
-    // Step-based screen props
-    initialStep?: number;
-    stepControllerRef?: RefObject<StepController | null>;
-    onStepChange?: (currentStep: number, totalSteps: number) => void;
-    
-    // Screen identification
-    currentScreen?: RouteName;
-    
-    // Scroll control
-    scrollTo?: (y: number, animated?: boolean) => void;
-    
-    // Form props (for sign in/up flows)
-    username?: string;
-    email?: string;
-    password?: string;
-    confirmPassword?: string;
-    userProfile?: unknown;
-    
-    // Note: OxyContext values (user, sessions, login, etc.) should be accessed via useOxy() hook
-    // This keeps props minimal and follows React best practices
-    
-    // Allow additional props for screen-specific data
-    [key: string]: unknown;
+  // Navigation props
+  navigate?: (screen: RouteName, props?: Record<string, unknown>) => void;
+  goBack?: () => void;
+  /** Whether the host surface can navigate back — a deeper frame OR a prior step. */
+  canGoBack?: () => boolean;
+  onClose?: () => void;
+  onAuthenticated?: (payload?: unknown) => void;
+  /**
+   * Dismiss THIS surface, resolving the `present()` promise that opened it
+   * with `result`. Injected by the surface host (the P1 surface stack). Picker
+   * and crop screens use it to hand a typed result back to the awaiting
+   * `surfaces.present(...)` call instead of an untyped `onSelect`/`onConfirm`
+   * callback prop.
+   */
+  dismiss?: (result?: unknown) => void;
+
+  // Theme props
+  theme?: 'light' | 'dark' | string;
+
+  // Step-based screen props
+  initialStep?: number;
+  stepControllerRef?: RefObject<StepController | null>;
+  onStepChange?: (currentStep: number, totalSteps: number) => void;
+
+  // Screen identification
+  currentScreen?: RouteName;
+
+  // Scroll control
+  scrollTo?: (y: number, animated?: boolean) => void;
+
+  // Form props (for sign in/up flows)
+  username?: string;
+  email?: string;
+  password?: string;
+  confirmPassword?: string;
+  userProfile?: unknown;
+
+  // Note: OxyContext values (user, sessions, login, etc.) should be accessed via useOxy() hook
+  // This keeps props minimal and follows React best practices
+
+  // Allow additional props for screen-specific data
+  [key: string]: unknown;
 }
 
 export interface OxyProviderProps {
-    oxyServices?: unknown;
-    children?: ReactNode;
-    onAuthStateChange?: (user: unknown) => void;
-    /** Optional, non-blocking product analytics sink. Receives no profile data. */
-    productAnalytics?: ProductAnalytics;
-    storageKeyPrefix?: string;
-    /**
-     * The app's Oxy OAuth client id / ApplicationCredential publicKey.
-     * Required for the cross-app device sign-in flow: the QR / approval-window
-     * sign-in registers a device-flow session via `POST /auth/session/create`,
-     * which now identifies the requesting app by this real registered
-     * client id. The central Oxy auth experience resolves and renders the
-     * consent identity from it server-side. Without it the device sign-in
-     * flow cannot start.
-     */
-    clientId?: string;
-    baseURL?: string;
-    authWebUrl?: string;
-    authRedirectUri?: string;
-    /**
-     * Authorize endpoint override for web "Sign in with Oxy". Defaults to the
-     * production Oxy IdP (`https://auth.oxy.so/authorize`) when unset. Set this
-     * from an env var (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo
-     * `EXPO_PUBLIC_OXY_AUTHORIZE_URL`) so a local/staging deployment targets its
-     * own IdP instead of production.
-     */
-    authorizeBaseUrl?: string;
-    /**
-     * Who owns this app's session.
-     *
-     * - `'account'` (default) — the device's ACTIVE account. Every ordinary Oxy
-     *   app: any app sharing the device's `DeviceSession` can switch the active
-     *   account and this one follows, sign-in surfaces and the account switcher
-     *   are available, and `accounts` lists the account graph.
-     * - `'identity'` — the owner of this device's PRIMARY identity key, for as
-     *   long as that key exists. The provider pins its authenticated user AND
-     *   its bearer to the account that key authenticates as, so an account
-     *   switch made by any sibling app changes the shared device state but never
-     *   this app's user or token. Built for the identity vault (Commons).
-     *
-     * In `'identity'` mode the account-graph surfaces are disabled at the source
-     * rather than hidden in the UI: `accounts` stays empty and is never fetched,
-     * `switchToAccount` / `switchSession` reject with `IdentityBoundSessionError`,
-     * `accountDialogController` is `null` and `openAccountDialog()` does nothing,
-     * and the web OAuth cold-boot lane (the authorization-code return leg) is
-     * skipped — it commits whichever account the IdP resolves, which is not
-     * necessarily the local key's owner.
-     *
-     * Read once at mount, like `baseURL` / `oxyServices`: changing it on a
-     * mounted provider does not re-bind the session.
-     * @default 'account'
-     */
-    sessionMode?: SessionMode;
-    /**
-     * How a WEB third-party "Sign in with Oxy" hands the user to the IdP.
-     *
-     * - `'popup'` (default) — a small `auth.oxy.so` window opened from the
-     *   user's click. The app stays MOUNTED and becomes authenticated without a
-     *   reload; the IdP delivers only the authorization code + `state` back to
-     *   the opener via `postMessage` (never a token, device secret, or PKCE
-     *   verifier). A blocked popup falls back to the redirect automatically.
-     * - `'redirect'` — a full-page navigation to `auth.oxy.so`, which returns to
-     *   the registered `redirect_uri` with `?code=`. The tab unmounts and
-     *   remounts, so route and unsaved state are lost.
-     *
-     * Either way the navigation only ever happens from a real user gesture: the
-     * SDK never bounces the top-level window on its own (#691 phase 7b).
-     *
-     * Native is unaffected — it always uses an in-app auth session.
-     * @default 'popup'
-     */
-    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
-     * sign-in banner while signed out; `hard` blocks the app behind the signed-out
-     * wall until the user signs in. For finer control, mount `RequireOxyAuth`
-     * yourself around a specific subtree instead.
-     * @default 'off'
-     */
-    requireAuth?: 'off' | 'soft' | 'hard';
-    /**
-     * When true, provisions a non-rotating background credential for native code
-     * (Android widgets) that runs without a JS runtime. Android-only today; inert
-     * on web and iOS.
-     * @default false
-     */
-    backgroundSession?: boolean;
-    /**
-     * Wires the app's OWN i18n library to Oxy's resolved language, so the
-     * account (or, signed out, the device/guest locale) drives the app's
-     * translated UI directly — no app-local effect or "sync" component to
-     * remember to mount. Oxy decides WHICH language; the app keeps owning its
-     * own translation catalogs and library (i18next, FormatJS, or anything
-     * else) and is told through `onChange` when to switch.
-     *
-     * Omitted entirely (the default) when an app has no i18n of its own, or
-     * manages it independently of the account/device locale.
-     */
-    language?: OxyLanguageConfig;
+  oxyServices?: unknown;
+  children?: ReactNode;
+  onAuthStateChange?: (user: unknown) => void;
+  /** Optional, non-blocking product analytics sink. Receives no profile data. */
+  productAnalytics?: ProductAnalytics;
+  storageKeyPrefix?: string;
+  /**
+   * The app's Oxy OAuth client id / ApplicationCredential publicKey.
+   * Required for the cross-app device sign-in flow: the QR / approval-window
+   * sign-in registers a device-flow session via `POST /auth/session/create`,
+   * which now identifies the requesting app by this real registered
+   * client id. The central Oxy auth experience resolves and renders the
+   * consent identity from it server-side. Without it the device sign-in
+   * flow cannot start.
+   */
+  clientId?: string;
+  baseURL?: string;
+  authWebUrl?: string;
+  authRedirectUri?: string;
+  /**
+   * Authorize endpoint override for web "Sign in with Oxy". Defaults to the
+   * production Oxy IdP (`https://auth.oxy.so/authorize`) when unset. Set this
+   * from an env var (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo
+   * `EXPO_PUBLIC_OXY_AUTHORIZE_URL`) so a local/staging deployment targets its
+   * own IdP instead of production.
+   */
+  authorizeBaseUrl?: string;
+  /**
+   * Who owns this app's session.
+   *
+   * - `'account'` (default) — the device's ACTIVE account. Every ordinary Oxy
+   *   app: any app sharing the device's `DeviceSession` can switch the active
+   *   account and this one follows, sign-in surfaces and the account switcher
+   *   are available, and `accounts` lists the account graph.
+   * - `'identity'` — the owner of this device's PRIMARY identity key, for as
+   *   long as that key exists. The provider pins its authenticated user AND
+   *   its bearer to the account that key authenticates as, so an account
+   *   switch made by any sibling app changes the shared device state but never
+   *   this app's user or token. Built for the identity vault (Commons).
+   *
+   * In `'identity'` mode the account-graph surfaces are disabled at the source
+   * rather than hidden in the UI: `accounts` stays empty and is never fetched,
+   * `switchToAccount` / `switchSession` reject with `IdentityBoundSessionError`,
+   * `accountDialogController` is `null` and `openAccountDialog()` does nothing,
+   * and the web OAuth cold-boot lane (the authorization-code return leg) is
+   * skipped — it commits whichever account the IdP resolves, which is not
+   * necessarily the local key's owner.
+   *
+   * Read once at mount, like `baseURL` / `oxyServices`: changing it on a
+   * mounted provider does not re-bind the session.
+   * @default 'account'
+   */
+  sessionMode?: SessionMode;
+  /**
+   * How a WEB third-party "Sign in with Oxy" hands the user to the IdP.
+   *
+   * - `'popup'` (default) — a small `auth.oxy.so` window opened from the
+   *   user's click. The app stays MOUNTED and becomes authenticated without a
+   *   reload; the IdP delivers only the authorization code + `state` back to
+   *   the opener via `postMessage` (never a token, device secret, or PKCE
+   *   verifier). A blocked popup falls back to the redirect automatically.
+   * - `'redirect'` — a full-page navigation to `auth.oxy.so`, which returns to
+   *   the registered `redirect_uri` with `?code=`. The tab unmounts and
+   *   remounts, so route and unsaved state are lost.
+   *
+   * Either way the navigation only ever happens from a real user gesture: the
+   * SDK never bounces the top-level window on its own (#691 phase 7b).
+   *
+   * Native is unaffected — it always uses an in-app auth session.
+   * @default 'popup'
+   */
+  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
+   * sign-in banner while signed out; `hard` blocks the app behind the signed-out
+   * wall until the user signs in. For finer control, mount `RequireOxyAuth`
+   * yourself around a specific subtree instead.
+   * @default 'off'
+   */
+  requireAuth?: 'off' | 'soft' | 'hard';
+  /**
+   * When true, provisions a non-rotating background credential for native code
+   * (Android widgets) that runs without a JS runtime. Android-only today; inert
+   * on web and iOS.
+   * @default false
+   */
+  backgroundSession?: boolean;
+  /**
+   * Wires the app's OWN i18n library to Oxy's resolved language, so the
+   * account (or, signed out, the device/guest locale) drives the app's
+   * translated UI directly — no app-local effect or "sync" component to
+   * remember to mount. Oxy decides WHICH language; the app keeps owning its
+   * own translation catalogs and library (i18next, FormatJS, or anything
+   * else) and is told through `onChange` when to switch.
+   *
+   * Omitted entirely (the default) when an app has no i18n of its own, or
+   * manages it independently of the account/device locale.
+   */
+  language?: OxyLanguageConfig;
 }
 
 export interface OxyLanguageConfig {
-    /** The exact locales this app ships a translation catalog for. */
-    supportedLocales: readonly string[];
-    /**
-     * Used when Oxy's resolved language matches none of `supportedLocales`,
-     * not even by base language (Oxy's account-locale catalog is broader
-     * than any one app's translations).
-     */
-    fallbackLocale: string;
-    /**
-     * Called whenever the resolved locale changes, coerced to the closest
-     * one in `supportedLocales`. May return a promise; a rejection is
-     * reported to `onError` instead of throwing into the app tree.
-     */
-    onChange: (locale: string) => void | Promise<void>;
-    onError?: (error: unknown, locale: string) => void;
+  /** The exact locales this app ships a translation catalog for. */
+  supportedLocales: readonly string[];
+  /**
+   * Used when Oxy's resolved language matches none of `supportedLocales`,
+   * not even by base language (Oxy's account-locale catalog is broader
+   * than any one app's translations).
+   */
+  fallbackLocale: string;
+  /**
+   * Called whenever the resolved locale changes, coerced to the closest
+   * one in `supportedLocales`. May return a promise; a rejection is
+   * reported to `onError` instead of throwing into the app tree.
+   */
+  onChange: (locale: string) => void | Promise<void>;
+  onError?: (error: unknown, locale: string) => void;
 }

package/src/ui/types/surfaceScreen.ts

@@ -30,7 +30,10 @@ export interface SurfaceScreenProps<K extends RouteName> {
   /** Dismiss THIS surface, resolving its `present()` promise with `result`. */
   dismiss: (result?: SurfaceResult<K>) => void;
   /** Present a NEW surface on top of the stack (DEPTH); resolves with its result. */
-  present: <T extends RouteName>(route: T, props?: SurfaceProps<T>) => Promise<SurfaceResult<T> | undefined>;
+  present: <T extends RouteName>(
+    route: T,
+    props?: SurfaceProps<T>,
+  ) => Promise<SurfaceResult<T> | undefined>;
   /** The current wizard step of this frame. */
   step: number;
   /** Set the current wizard step. */

package/src/ui/utils/__tests__/deviceSessionTitle.test.ts

@@ -15,7 +15,7 @@ describe('deviceSessionTitle', () => {
     expect(title).not.toContain('undefined');
   });
 
-  it("names another session by its account, which the response does carry", () => {
+  it('names another session by its account, which the response does carry', () => {
     const user = { id: 'u2', username: 'bob', name: { displayName: 'Bob' } } as unknown as User;
     expect(deviceSessionTitle({ isCurrent: false, user } as never, t)).toBe('Bob');
   });
@@ -25,7 +25,9 @@ describe('deviceSessionTitle', () => {
   });
 
   it('keeps a real device name, marking the current one', () => {
-    expect(deviceSessionTitle({ deviceName: 'Pixel 8a', isCurrent: true }, t)).toBe('Pixel 8a (This device)');
+    expect(deviceSessionTitle({ deviceName: 'Pixel 8a', isCurrent: true }, t)).toBe(
+      'Pixel 8a (This device)',
+    );
     expect(deviceSessionTitle({ deviceName: 'Pixel 8a', isCurrent: false }, t)).toBe('Pixel 8a');
   });
 });

package/src/ui/utils/accountDeletionHandoff.ts

@@ -54,7 +54,11 @@ export async function runAccountDeletionHandoff(
     holdsIdentity = await hasIdentity();
   } catch (error) {
     // A locked or unreadable keystore is not proof the identity is elsewhere.
-    logger.warn('Identity read failed before account deletion', { component: 'accountDeletionHandoff' }, error);
+    logger.warn(
+      'Identity read failed before account deletion',
+      { component: 'accountDeletionHandoff' },
+      error,
+    );
     toast.error(
       text(
         'deleteAccount.handoff.identityUnreadable',
@@ -88,7 +92,11 @@ export async function runAccountDeletionHandoff(
       try {
         await openURL(COMMONS_DELETE_ACCOUNT_URL);
       } catch (error) {
-        logger.warn('Opening Commons delete-account failed', { component: 'accountDeletionHandoff' }, error);
+        logger.warn(
+          'Opening Commons delete-account failed',
+          { component: 'accountDeletionHandoff' },
+          error,
+        );
         toast.error(
           text(
             'deleteAccount.handoff.commonsOpenFailed',
@@ -101,7 +109,10 @@ export async function runAccountDeletionHandoff(
   }
 
   await surfaces.confirm({
-    title: text('deleteAccount.handoff.elsewhereTitle', 'Delete your account where your identity is'),
+    title: text(
+      'deleteAccount.handoff.elsewhereTitle',
+      'Delete your account where your identity is',
+    ),
     description: text(
       'deleteAccount.handoff.elsewhereMessage',
       "Deleting your account needs your identity key, and it isn't on this device. Open Oxy Commons on the device that holds it and go to Settings > Delete account.",

package/src/ui/utils/avatarUtils.ts

@@ -3,11 +3,12 @@ import type { OxyServices, User } from '@oxy.so/core';
 import type { UserProfileUpdate } from '@oxy.so/contracts';
 import { useAuthStore } from '../stores/authStore';
 import type { QueryClient } from '@tanstack/react-query';
-import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from '../hooks/queries/queryKeys';
 import {
-  clearedFieldsFromProfileUpdate,
-  upsertCachedUser,
-} from '../hooks/queries/userCache';
+  queryKeys,
+  invalidateUserQueries,
+  invalidateAccountQueries,
+} from '../hooks/queries/queryKeys';
+import { clearedFieldsFromProfileUpdate, upsertCachedUser } from '../hooks/queries/userCache';
 
 /**
  * Updates user profile with avatar and handles all side effects (cache writes,
@@ -25,13 +26,13 @@ export async function updateProfileWithAvatar(
   oxyServices: OxyServices,
   activeSessionId: string | null,
   queryClient: QueryClient,
-  syncSession?: () => Promise<User>
+  syncSession?: () => Promise<User>,
 ): Promise<User> {
   const data = await authenticatedApiCall<User>(
     oxyServices,
     activeSessionId,
     () => oxyServices.users.updateMe(updates),
-    syncSession
+    syncSession,
   );
 
   // Update cache with server response

package/src/ui/utils/clipboard.native.ts

@@ -2,11 +2,22 @@
  * Put text on the clipboard on iOS and Android, through `expo-clipboard`.
  * React Native's own `Clipboard` is deprecated and gone from newer releases.
  *
- * `expo-clipboard` is an OPTIONAL peer, loaded with `import()` so an app
- * without it (or with the JS but not the native module, before a rebuild)
- * still bundles and boots: the copy rejects here and the caller says nothing
- * was copied. A static import would instead fail the Metro build or throw
- * while the root barrel evaluates.
+ * `expo-clipboard` is an OPTIONAL peer, so an app without it (or with the JS but
+ * not the native module, before a rebuild) must still bundle and boot: the copy
+ * rejects here and the caller says nothing was copied.
+ *
+ * Metro resolves a dynamic `import()` at BUILD time, like a static import, so
+ * being dynamic is not what makes it optional. Metro marks a dependency optional
+ * (writing `null` into the dependency map instead of failing the bundle) only
+ * when the `import()`/`require()` of a string literal sits in a statement whose
+ * NEAREST enclosing block is a `try` block, or ends in a promise chain with a
+ * rejection handler (`isOptionalDependency` in metro's `collectDependencies`).
+ * This file used to `await import('expo-clipboard')` outside any `try`, and
+ * every Android or iOS bundle of an app without `expo-clipboard` failed with
+ * `Unable to resolve module expo-clipboard`, though nothing in that app ever
+ * copied anything. Keep the `import()` a direct statement of the `try` below:
+ * one `if` block of nesting inside the `try` loses the optionality again.
+ * `optionalPeerLoads.test.ts` holds every optional peer to that shape.
  *
  * Only this NATIVE fork names the package; the default fork (`clipboard.ts`,
  * which `tsc`, Vite and SSR resolve) names nothing, so a consumer's type graph
@@ -15,6 +26,12 @@
  * about. `clipboardIsolation.test.ts` keeps it that way.
  */
 export async function copyText(text: string): Promise<void> {
-  const clipboard = await import('expo-clipboard');
+  let clipboard: typeof import('expo-clipboard');
+  try {
+    clipboard = await import('expo-clipboard');
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`clipboard unavailable: expo-clipboard could not be loaded (${reason})`);
+  }
   await clipboard.setStringAsync(text);
 }

package/src/ui/utils/commonsStoreLinks.ts

@@ -33,6 +33,7 @@ const DEFAULT_COMMONS_LANDING_URL = 'https://oxy.so/commons';
  */
 export function getCommonsAcquisitionUrl(platformOS: 'ios' | 'android' | string): string {
   const links = getCommonsStoreLinks();
-  const storeUrl = platformOS === 'ios' ? links.ios : platformOS === 'android' ? links.android : undefined;
+  const storeUrl =
+    platformOS === 'ios' ? links.ios : platformOS === 'android' ? links.android : undefined;
   return storeUrl ?? process.env.EXPO_PUBLIC_COMMONS_LANDING_URL ?? DEFAULT_COMMONS_LANDING_URL;
 }

package/src/ui/utils/errorHandlers.ts

@@ -91,7 +91,10 @@ export const isTimeoutOrNetworkError = (error: unknown): boolean => {
   }
 
   const message = extractErrorMessage(error, '').toLowerCase();
-  const errorCode = isObject(error) && 'code' in (error as object) ? (error as Record<string, unknown>).code : undefined;
+  const errorCode =
+    isObject(error) && 'code' in (error as object)
+      ? (error as Record<string, unknown>).code
+      : undefined;
 
   // Check for timeout/cancelled messages
   if (
@@ -172,16 +175,10 @@ export const extractErrorMessage = (
  */
 export const handleAuthError = (
   error: unknown,
-  {
-    defaultMessage,
-    code,
-    status,
-    onError,
-    setAuthError,
-    logger,
-  }: HandleAuthErrorOptions,
+  { defaultMessage, code, status, onError, setAuthError, logger }: HandleAuthErrorOptions,
 ): string => {
-  const resolvedStatus = status ?? getResponseStatus(error) ?? (isInvalidSessionError(error) ? 401 : 500);
+  const resolvedStatus =
+    status ?? getResponseStatus(error) ?? (isInvalidSessionError(error) ? 401 : 500);
   const message = extractErrorMessage(error, defaultMessage);
 
   if (logger) {
@@ -198,5 +195,3 @@ export const handleAuthError = (
 
   return message;
 };
-
-