@oxyhq/services 23.2.0 → 24.0.0

package/src/ui/session/useBackgroundSessionSync.ts

@@ -0,0 +1,93 @@
+/**
+ * Keeps the native background credential in step with the session, so an app
+ * enables background authentication with one prop and writes no session code of
+ * its own.
+ *
+ * See `./backgroundSession` for what the credential is and why it is separate
+ * from the rotating device secret.
+ */
+import { useEffect } from 'react';
+import { AppState } from 'react-native';
+import type { OxyServices } from '@oxyhq/core';
+import {
+  clearBackgroundSession,
+  isBackgroundSessionSupported,
+  syncBackgroundSession,
+} from './backgroundSession';
+
+export interface UseBackgroundSessionSyncInput {
+  /** `OxyProviderProps.backgroundSession`. */
+  enabled: boolean;
+  oxyServices: OxyServices;
+  /** The signed-in account, or `null` when signed out. */
+  userId: string | null;
+  /** Whether a bearer is available yet — provisioning needs one. */
+  canUsePrivateApi: boolean;
+}
+
+/**
+ * An effect is the right shape here, unusually for this codebase: the work is a
+ * side effect on native storage, and it has to react both to an identity change
+ * (a value) and to the app being foregrounded (a subscription). There is no
+ * derived-state or React Query formulation of "write a credential to the
+ * keystore when the user changes or the app comes back".
+ *
+ * Re-runs on identity change, which is what makes sign-out and account switching
+ * work: `syncBackgroundSession` clears a credential belonging to anyone other
+ * than `userId` before it does any network work.
+ */
+export function useBackgroundSessionSync({
+  enabled,
+  oxyServices,
+  userId,
+  canUsePrivateApi,
+}: UseBackgroundSessionSyncInput): void {
+  useEffect(() => {
+    if (!isBackgroundSessionSupported()) {
+      return;
+    }
+
+    if (!enabled) {
+      // An app that turns the feature OFF must not leave a live credential at
+      // rest for the rest of its 30-day lifetime. The cost is one local store
+      // open per launch on Android apps that never use the feature, which is
+      // accepted deliberately: correct revocation is worth more than skipping a
+      // memoized keystore open.
+      void clearBackgroundSession();
+      return;
+    }
+
+    // A run that is superseded (unmount, or another identity change) must not
+    // write the credential it was about to write.
+    let current = true;
+    // Deliberately NOT caught. `syncBackgroundSession` already handles every
+    // runtime failure internally and throws for exactly one thing: an installed
+    // `@oxyhq/core` too old to provision. That is a dependency mistake which must
+    // surface, so it is allowed to reject — adding a `.catch()` here would put it
+    // back behind the silence it was moved out of.
+    const run = () => {
+      void syncBackgroundSession({
+        oxyServices,
+        userId,
+        canUsePrivateApi,
+        isCurrent: () => current,
+      });
+    };
+
+    run();
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        run();
+      }
+    });
+
+    return () => {
+      current = false;
+      subscription.remove();
+      // Deliberately NOT clearing here. Unmount is the app closing, which is
+      // precisely when the credential has to survive — clearing on teardown
+      // would defeat the entire feature. Revocation happens on sign-out (via a
+      // `userId` of null), on the server, or when the credential expires.
+    };
+  }, [enabled, oxyServices, userId, canUsePrivateApi]);
+}

package/src/ui/types/navigation.ts

@@ -136,4 +136,11 @@ export interface OxyProviderProps {
      * @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;
 }

package/src/ui/utils/userUtils.ts

@@ -1,13 +1,15 @@
 /**
  * User display name and date formatting utilities.
  *
- * The display-name helpers are thin wrappers around the canonical
- * `getAccountDisplayName` in `@oxyhq/core`, which handles all the edge cases
- * (missing username, missing name, fallback to truncated `publicKey`, i18n).
+ * Display-name helpers follow the API contract: prefer `name.displayName` when
+ * present, otherwise fall back to the normalized handle. The legacy
+ * `getAccountDisplayName` chain is only used as a last resort for local
+ * account-switcher surfaces without a handle.
  */
 
 import {
   getAccountDisplayName as coreGetAccountDisplayName,
+  getNormalizedUserHandle,
   type DisplayNameUserShape,
 } from '@oxyhq/core';
 
@@ -31,44 +33,56 @@ export const formatDate = (dateString: string | undefined | null | Date): string
   }
 };
 
+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 full name → composed first+last → username → `Account 0x12345678…`
- * (derived from publicKey) → translated "Unnamed".
- *
- * @param user - User-like object with optional name/username/publicKey
- * @param locale - Optional locale for the final fallback label
+ * Prefers API `name.displayName`, then the normalized handle, then the local
+ * account-switcher fallback chain.
  */
 export const getDisplayName = (
   user: DisplayNameUserShape | null | undefined,
   locale?: string,
-): string => coreGetAccountDisplayName(user, locale);
+): string => {
+  const displayName = readDisplayName(user);
+  if (displayName) return displayName;
+
+  const handle = getNormalizedUserHandle(user);
+  if (handle) return handle;
+
+  return coreGetAccountDisplayName(user, locale);
+};
 
 /**
- * Gets a short display name (first name or username).
- *
- * Used for compact UI (e.g. greetings). Falls back to the full display name
- * helper, which also handles publicKey-only accounts.
+ * Gets a short display name (first token) for compact UI.
  */
 export const getShortDisplayName = (
   user: DisplayNameUserShape | null | undefined,
   locale?: string,
 ): string => {
-  if (!user) return coreGetAccountDisplayName(user, locale);
+  const displayName = readDisplayName(user);
+  if (displayName) {
+    const firstToken = displayName.split(/\s+/).find(Boolean);
+    if (firstToken) return firstToken;
+  }
 
-  const name = user.name;
+  const name = user?.name;
   if (name && typeof name === 'object') {
     const first = typeof name.first === 'string' ? name.first.trim() : '';
-    if (first) return first;
+    if (first) return first.split(/\s+/)[0] ?? first;
     const full = typeof name.full === 'string' ? name.full.trim() : '';
-    if (full) return full.split(' ')[0];
+    if (full) return full.split(/\s+/)[0] ?? full;
   } else if (typeof name === 'string' && name.trim()) {
-    return name.trim().split(' ')[0];
+    return name.trim().split(/\s+/)[0] ?? name.trim();
   }
 
-  if (typeof user.username === 'string' && user.username.trim()) return user.username.trim();
+  const handle = getNormalizedUserHandle(user);
+  if (handle) return handle;
 
-  // Defer to the canonical helper for publicKey/unnamed fallbacks.
   return coreGetAccountDisplayName(user, locale);
 };