@oxyhq/core 1.11.12 → 1.11.14

package/src/mixins/index.ts

@@ -25,9 +25,53 @@ import { OxyServicesUtilityMixin } from './OxyServices.utility';
 import { OxyServicesFeaturesMixin } from './OxyServices.features';
 import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
+import { OxyServicesContactsMixin } from './OxyServices.contacts';
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type MixinFunction = (Base: any) => any;
+/**
+ * Instance shape of every mixin in the pipeline, intersected. The runtime
+ * `composeOxyServices()` produces a class whose instances expose all of
+ * these methods; we surface that to TypeScript via this intersection so the
+ * `extends` site in `OxyServices.ts` can avoid an `as any` cast.
+ *
+ * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
+ * are visible without a cast.
+ */
+type AllMixinInstances =
+  & InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+
+/**
+ * Constructor type for the fully composed mixin pipeline. Each mixin returns
+ * a new constructor that augments its input; reducing across the pipeline
+ * yields an instance with every mixin's methods.
+ */
+export type ComposedOxyServicesConstructor = new (config: import('../OxyServices.base').OxyConfig) => AllMixinInstances;
+
+/**
+ * A mixin function: takes a constructor and returns an augmented constructor.
+ * Each individual mixin uses a `<T extends typeof OxyServicesBase>` generic
+ * to preserve its specific augmentations, but those refinements are
+ * intentionally collapsed across the `reduce` call below.
+ */
+type MixinFunction = (Base: new (...args: unknown[]) => OxyServicesBase) => new (...args: unknown[]) => OxyServicesBase;
 
 /**
  * Mixin pipeline - applied in order from first to last.
@@ -70,6 +114,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesFeaturesMixin,
     OxyServicesTopicsMixin,
     OxyServicesManagedAccountsMixin,
+    OxyServicesContactsMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
@@ -79,15 +124,21 @@ const MIXIN_PIPELINE: MixinFunction[] = [
  * Composes all OxyServices mixins using a pipeline pattern.
  *
  * This is equivalent to the nested calls but more readable and maintainable.
- * Adding a new mixin: just add it to MIXIN_PIPELINE at the appropriate position.
+ * Adding a new mixin: add it to MIXIN_PIPELINE at the appropriate position
+ * AND extend `AllMixinInstances` so its methods are visible to consumers.
+ *
+ * The cast through `unknown` carries the runtime augmentation chain into the
+ * static type system. `Array.reduce` cannot track each mixin's generic
+ * refinement, so we assert the final shape exposed by all mixins together.
  *
- * @returns The fully composed OxyServices class with all mixins applied
+ * @returns The fully composed OxyServices constructor with all mixins applied
  */
-export function composeOxyServices() {
-    return MIXIN_PIPELINE.reduce(
+export function composeOxyServices(): ComposedOxyServicesConstructor {
+    const composed = MIXIN_PIPELINE.reduce(
         (Base, mixin) => mixin(Base),
-        OxyServicesBase as unknown as ReturnType<MixinFunction>
+        OxyServicesBase as unknown as new (...args: unknown[]) => OxyServicesBase
     );
+    return composed as unknown as ComposedOxyServicesConstructor;
 }
 
 // Export the pipeline for testing/debugging

package/src/models/interfaces.ts

@@ -23,6 +23,41 @@ export interface OxyConfig {
   onRequestError?: (url: string, method: string, error: Error) => void;
 }
 
+/**
+ * Privacy settings for a user account.
+ *
+ * All fields are optional because:
+ *  - Updates are dot-path partial PATCHes — clients send only changed keys.
+ *  - The server may return a partial subdocument depending on the API
+ *    build (older builds returned only the field that changed).
+ *  - User accounts created before a new toggle was introduced won't
+ *    have that key persisted yet.
+ *
+ * Mirrors `IPrivacySettings` from `packages/api/src/types/privacy.types.ts`,
+ * but with every field marked optional.
+ */
+export interface PrivacySettings {
+  isPrivateAccount?: boolean;
+  hideOnlineStatus?: boolean;
+  hideLastSeen?: boolean;
+  profileVisibility?: boolean;
+  loginAlerts?: boolean;
+  blockScreenshots?: boolean;
+  login?: boolean;
+  biometricLogin?: boolean;
+  showActivity?: boolean;
+  allowTagging?: boolean;
+  allowMentions?: boolean;
+  hideReadReceipts?: boolean;
+  allowDirectMessages?: boolean;
+  dataSharing?: boolean;
+  locationSharing?: boolean;
+  analyticsSharing?: boolean;
+  sensitiveContent?: boolean;
+  autoFilter?: boolean;
+  muteKeywords?: boolean;
+}
+
 export interface User {
   id: string;
   publicKey: string;
@@ -33,9 +68,7 @@ export interface User {
   // Named color preset (e.g. 'teal', 'blue', 'purple')
   color?: string;
   // Privacy and security settings
-  privacySettings?: {
-    [key: string]: unknown;
-  };
+  privacySettings?: PrivacySettings;
   name?: {
     first?: string;
     last?: string;
@@ -289,6 +322,35 @@ export interface FileDeleteResponse {
   fileId: string;
 }
 
+/**
+ * React Native file descriptor accepted by FormData.
+ *
+ * On React Native, the multipart upload reads the file from disk via the URI
+ * during the network request — no in-JS Blob construction is required (and
+ * doing so would fail on Hermes since RN's BlobManager cannot wrap an
+ * ArrayBuffer/ArrayBufferView).
+ *
+ * This shape matches what `expo-document-picker` and `expo-image-picker`
+ * return for selected assets, and is what `OxyServices.assetUpload` accepts
+ * on native platforms.
+ */
+export interface RNFileDescriptor {
+  uri: string;
+  type?: string;
+  name?: string;
+  size?: number;
+}
+
+/**
+ * Asset upload input — accepted by `OxyServices.assetUpload` and `uploadRawFile`.
+ *
+ * - `File` / `Blob`: standard web browser path. `assetUpload` appends the
+ *   Blob to FormData directly.
+ * - {@link RNFileDescriptor}: React Native path. FormData reads the file from
+ *   disk via the URI during the multipart request.
+ */
+export type AssetUploadInput = File | Blob | RNFileDescriptor;
+
 /**
  * Central Asset Service interfaces
  */

package/src/utils/accountUtils.ts

@@ -3,6 +3,8 @@
  * Used by both @oxyhq/services (React Native) and @oxyhq/auth (Web) account stores.
  */
 
+import { translate } from '../i18n';
+
 export interface QuickAccount {
     sessionId: string;
     userId?: string;
@@ -12,6 +14,83 @@ export interface QuickAccount {
     avatarUrl?: string;
 }
 
+/** Minimal user shape accepted by display-name helpers. Avoids importing the full User type. */
+export interface DisplayNameUserShape {
+    name?: string | { first?: string; last?: string; full?: string; [key: string]: unknown };
+    username?: string;
+    publicKey?: string;
+}
+
+/**
+ * Truncate a long public key for display, e.g. `0x12345678…`.
+ * Falls back to the raw key if it's too short to truncate.
+ */
+export const formatPublicKeyHandle = (publicKey: string): string => {
+    const cleaned = publicKey.startsWith('0x') ? publicKey.slice(2) : publicKey;
+    if (cleaned.length <= 8) return `0x${cleaned}`;
+    return `0x${cleaned.slice(0, 8)}…`;
+};
+
+/**
+ * Resolve a friendly display name for a user.
+ *
+ * Order of preference:
+ *  1. `name.full`, or composed `name.first name.last`
+ *  2. `name` (when stored as a plain string)
+ *  3. `username`
+ *  4. `Account 0x12345678…` (derived from publicKey, when present)
+ *  5. Translated fallback (e.g. "Unnamed")
+ *
+ * The translation key `common.unnamed` is used for the final fallback. If the
+ * caller does not pass a locale, the default English translation is used.
+ */
+export const getAccountDisplayName = (
+    user: DisplayNameUserShape | null | undefined,
+    locale?: string,
+): string => {
+    if (!user) return translate(locale, 'common.unnamed');
+
+    const { name, username, publicKey } = user;
+
+    if (name && typeof name === 'object') {
+        if (typeof name.full === 'string' && name.full.trim()) return name.full.trim();
+        const first = typeof name.first === 'string' ? name.first.trim() : '';
+        const last = typeof name.last === 'string' ? name.last.trim() : '';
+        const composed = [first, last].filter(Boolean).join(' ').trim();
+        if (composed) return composed;
+    } else if (typeof name === 'string' && name.trim()) {
+        return name.trim();
+    }
+
+    if (typeof username === 'string' && username.trim()) return username.trim();
+
+    if (typeof publicKey === 'string' && publicKey.length > 0) {
+        return translate(locale, 'common.accountFallback', {
+            handle: formatPublicKeyHandle(publicKey),
+        });
+    }
+
+    return translate(locale, 'common.unnamed');
+};
+
+/**
+ * Resolve a `@handle` style identifier for a user.
+ *
+ * Returns the bare username when present (without the `@`), otherwise a
+ * truncated public-key handle (`0x12345678…`), or `undefined` when neither is
+ * available — callers can decide whether to hide the line entirely.
+ */
+export const getAccountFallbackHandle = (
+    user: DisplayNameUserShape | null | undefined,
+): string | undefined => {
+    if (!user) return undefined;
+    if (typeof user.username === 'string' && user.username.trim()) return user.username.trim();
+    if (typeof user.publicKey === 'string' && user.publicKey.length > 0) {
+        return formatPublicKeyHandle(user.publicKey);
+    }
+    return undefined;
+};
+
 /**
  * Build an ordered array of QuickAccounts from a map and order list.
  */
@@ -38,8 +117,9 @@ export const buildAccountsArray = (
 export const createQuickAccount = (
     sessionId: string,
     userData: {
-        name?: { full?: string; first?: string };
+        name?: string | { full?: string; first?: string; last?: string };
         username?: string;
+        publicKey?: string;
         id?: string;
         _id?: { toString(): string } | string;
         avatar?: string;
@@ -47,7 +127,7 @@ export const createQuickAccount = (
     existingAccount?: QuickAccount,
     getFileDownloadUrl?: (fileId: string, variant: string) => string
 ): QuickAccount => {
-    const displayName = userData.name?.full || userData.name?.first || userData.username || 'Account';
+    const displayName = getAccountDisplayName(userData);
     const userId = userData.id || (typeof userData._id === 'string' ? userData._id : userData._id?.toString());
 
     // Preserve existing avatarUrl if avatar hasn't changed (prevents image reload)

package/src/utils/deviceManager.ts

@@ -1,3 +1,5 @@
+import { loadAsyncStorage } from './platformCrypto';
+
 export interface DeviceFingerprint {
   userAgent: string;
   platform: string;
@@ -42,10 +44,11 @@ export class DeviceManager {
   }> {
     if (this.isReactNative()) {
       try {
-        // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
-        const moduleName = '@react-native-async-storage/async-storage';
-        const asyncStorageModule = await import(/* @vite-ignore */ moduleName);
-        const storage = asyncStorageModule.default as unknown as { getItem: (key: string) => Promise<string | null>; setItem: (key: string, value: string) => Promise<void>; removeItem: (key: string) => Promise<void> };
+        // `loadAsyncStorage` is per-platform: the RN variant statically imports
+        // @react-native-async-storage/async-storage, the default variant throws
+        // (never called outside RN because of the `isReactNative()` gate above).
+        const asyncStorageModule = await loadAsyncStorage();
+        const storage = asyncStorageModule.default;
         return {
           getItem: storage.getItem.bind(storage),
           setItem: storage.setItem.bind(storage),

package/src/utils/languageUtils.ts

@@ -154,7 +154,7 @@ export function getNativeLanguageName(languageCode: string | null | undefined):
 export function normalizeLanguageCode(lang?: string | null): string {
   if (!lang) return FALLBACK_LANGUAGE;
   if (lang.includes('-')) return lang;
-  
+
   const map: Record<string, string> = {
     en: 'en-US',
     es: 'es-ES',
@@ -168,7 +168,28 @@ export function normalizeLanguageCode(lang?: string | null): string {
     zh: 'zh-CN',
     ar: 'ar-SA',
   };
-  
+
   return map[lang] || lang;
 }
 
+/**
+ * RTL language detection.
+ *
+ * Returns `true` when the given BCP-47 tag or bare language code is one
+ * of the right-to-left scripts we ship UI for. Apps use this to drive
+ * `I18nManager.allowRTL(true)` / `forceRTL(...)` on React Native and the
+ * `<html dir="rtl">` attribute on web.
+ *
+ * Includes Arabic (`ar`), Hebrew (`he` / legacy `iw`), Persian (`fa`),
+ * Urdu (`ur`) plus their common region variants. Unknown tags are
+ * treated as LTR.
+ */
+const RTL_LANGUAGE_BASES = new Set(['ar', 'he', 'iw', 'fa', 'ur']);
+
+export function isRTLLocale(locale?: string | null): boolean {
+  if (!locale) return false;
+  const base = locale.toLowerCase().split('-')[0];
+  if (!base) return false;
+  return RTL_LANGUAGE_BASES.has(base);
+}
+

package/src/utils/platformCrypto.native.ts

@@ -0,0 +1,101 @@
+/**
+ * Platform Crypto / Storage — React Native Variant
+ *
+ * Companion to `./platformCrypto.ts`. See the doc-comment at the top of that
+ * file for the full design.
+ *
+ * Metro auto-selects this file in any non-web build (`preferNativePlatform`
+ * is `true` for iOS / Android, so `*.native.js` shadows `*.js` during
+ * source-extension resolution inside `node_modules/@oxyhq/core/dist/`). On
+ * iOS / Android `<base>.ios.js` / `<base>.android.js` would shadow this file
+ * if they existed, but they don't — `.native.js` is the shared RN variant.
+ *
+ *   - The default variant references Node's `'crypto'` and would crash Metro
+ *     if bundled into an RN app.
+ *   - This variant references the RN-only modules (`expo-crypto`,
+ *     `expo-secure-store`, `@react-native-async-storage/async-storage`)
+ *     as static imports, so Metro and Hermes both resolve and parse them
+ *     cleanly.
+ *
+ * Both variants expose the same surface; importers don't care which one
+ * they got.
+ *
+ * # Why static imports?
+ *
+ * Every RN consumer of `@oxyhq/core` already lists or transitively pulls
+ * in `expo-crypto`, `expo-secure-store`, and
+ * `@react-native-async-storage/async-storage` (they're stable Expo modules
+ * present in `services`, `accounts`, `inbox`, and `test-app`). A static
+ * import is what Metro wants to see anyway, and Hermes parses it like any
+ * other ES module — no `Function`-constructor parser exotic-mode involved.
+ *
+ * This is also clearer to debug: Metro fails up-front with a normal
+ * unresolved-module error if a consumer is missing a peer dep, instead of
+ * a confusing runtime throw the first time a code path that needs the
+ * module is exercised.
+ */
+
+import * as ExpoCrypto from 'expo-crypto';
+import * as SecureStore from 'expo-secure-store';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// ---------------------------------------------------------------------------
+// Node `crypto` — never available in RN.
+// ---------------------------------------------------------------------------
+
+export async function loadNodeCrypto(): Promise<typeof import('crypto')> {
+  // Unreachable in practice: every caller gates with `isNodeJS()` before
+  // invoking this. If it somehow does fire, throw immediately with a clear
+  // diagnostic rather than letting Metro / Hermes attempt to find a
+  // non-existent module at runtime.
+  throw new Error(
+    "[oxy.platformCrypto] Node's built-in 'crypto' module is not available " +
+      'in a React Native runtime. Use the RN-specific helpers ' +
+      '(loadExpoCrypto, getRandomBytesRN) or the Web Crypto API (`globalThis.crypto`).',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// expo-crypto — RN cryptographic primitives.
+// ---------------------------------------------------------------------------
+
+export async function loadExpoCrypto(): Promise<typeof import('expo-crypto')> {
+  return ExpoCrypto;
+}
+
+// ---------------------------------------------------------------------------
+// expo-secure-store — RN keychain / keystore.
+// ---------------------------------------------------------------------------
+
+export async function loadSecureStore(): Promise<typeof import('expo-secure-store')> {
+  return SecureStore;
+}
+
+// ---------------------------------------------------------------------------
+// @react-native-async-storage/async-storage — RN persistent KV storage.
+// ---------------------------------------------------------------------------
+
+type AsyncStorageLike = {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+};
+
+export async function loadAsyncStorage(): Promise<{ default: AsyncStorageLike }> {
+  // Mirror the shape callers historically used (`module.default.<method>`)
+  // so the call sites don't have to know whether the underlying module
+  // ships ESM or CJS-with-default.
+  const storage = AsyncStorage as unknown as AsyncStorageLike;
+  return {
+    default: storage,
+  };
+}
+
+/**
+ * Synchronous random-bytes via `expo-crypto.getRandomBytes`. Available
+ * synchronously because `expo-crypto` is statically imported by this file
+ * — no async initialization race.
+ */
+export function getRandomBytesRN(byteCount: number): Uint8Array {
+  return ExpoCrypto.getRandomBytes(byteCount);
+}

package/src/utils/platformCrypto.ts

@@ -0,0 +1,145 @@
+/**
+ * Platform Crypto / Storage — Default Variant (Node.js, Browser, generic bundlers)
+ *
+ * Provides lazy access to platform-specific crypto and storage modules.
+ *
+ * # Variants
+ *
+ * This module ships in two physical variants on disk, selected per consumer
+ * by the bundler / runtime:
+ *
+ * - `platformCrypto.js`           — this file. Used by Node.js, Vite, webpack,
+ *                                   Rollup, esbuild, and anything that does
+ *                                   not match Metro's `*.native.js`
+ *                                   source-extension preference.
+ * - `platformCrypto.native.js`    — sibling file. Picked up automatically by
+ *                                   Metro's resolver (which prefers
+ *                                   `*.<platform>.js` and `*.native.js` over
+ *                                   plain `*.js` when `preferNativePlatform`
+ *                                   is true — Expo sets this for all non-web
+ *                                   builds).
+ *
+ * The `package.json#exports` map also declares a `"react-native"` condition
+ * pointing at the same `dist/esm/index.js` entry — that entry transitively
+ * imports `./platformCrypto`, and Metro's per-file source-extension lookup
+ * substitutes the `.native.js` sibling automatically inside `dist/`. This
+ * means consumers never have to add resolver shims; Metro Just Works.
+ *
+ * Both variants expose the EXACT same public API; importers don't need to know
+ * which one they got. The variant difference is purely about which underlying
+ * native modules each one references:
+ *
+ *   ┌──────────────────┬───────────────────────┬───────────────────────────────┐
+ *   │ Function         │ Default variant       │ React Native variant          │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadNodeCrypto   │ `await import('crypto')` (Node built-in)              │
+ *   │                  │                       │ throws — Node crypto is not   │
+ *   │                  │                       │ available on Hermes/RN        │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadExpoCrypto   │ throws — expo-crypto  │ static `import 'expo-crypto'` │
+ *   │                  │ is not part of a      │                               │
+ *   │                  │ Node/Vite bundle      │                               │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadSecureStore  │ throws (web/Node have │ static `import 'expo-secure-` │
+ *   │                  │ their own storage)    │ store'                        │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadAsyncStorage │ throws (web/Node have │ static `import '@react-       │
+ *   │                  │ their own storage)    │ native-async-storage/...'     │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ getRandomBytesRN │ throws (RN-only)      │ direct call into expo-crypto  │
+ *   └──────────────────┴───────────────────────┴───────────────────────────────┘
+ *
+ * Crucially, the default variant references ONLY Node's `'crypto'`. It never
+ * mentions `expo-*` or `@react-native-async-storage/*` — so Vite, webpack,
+ * esbuild, Rollup, and Node itself can bundle / require it without ever
+ * attempting to resolve those RN-only packages.
+ *
+ * The React Native variant references ONLY the RN packages. It never
+ * mentions `'crypto'` — so Metro and Hermes have nothing to choke on.
+ *
+ * # Why not a single file with dynamic import?
+ *
+ * A previous iteration used a "bundler-opaque" `new Function('s', 'return
+ * import(s)')` trick so a single file could service every platform. It
+ * bundled cleanly on Metro but Hermes refused to PARSE the resulting
+ * `import()` expression inside a Function-constructor body
+ * (`SyntaxError: Invalid expression encountered` at the `(` of `import(`).
+ * The platform-extension split is the only approach that lets each runtime
+ * see a file containing only specifiers it can understand — no tricks, no
+ * runtime parsing risks.
+ */
+
+import { isReactNative } from './platform';
+
+// ---------------------------------------------------------------------------
+// Node `crypto` — Node built-in
+//
+// `await import('crypto')` here is a real, static-from-tsc's-perspective
+// dynamic import. Node ESM, Vite, webpack, and esbuild all resolve it fine.
+// Metro never sees this file because the `.react-native.js` sibling shadows
+// it, so Metro never tries to resolve `'crypto'`.
+// ---------------------------------------------------------------------------
+
+let cachedNodeCrypto: typeof import('crypto') | null = null;
+
+export async function loadNodeCrypto(): Promise<typeof import('crypto')> {
+  if (cachedNodeCrypto) {
+    return cachedNodeCrypto;
+  }
+  cachedNodeCrypto = await import('node:crypto');
+  return cachedNodeCrypto;
+}
+
+// ---------------------------------------------------------------------------
+// RN-only modules — never called from this variant.
+//
+// These throw a clear error if anything ever reaches them outside RN. In
+// practice every caller gates with `isReactNative()` before calling, so
+// these are belt-and-braces.
+// ---------------------------------------------------------------------------
+
+function notReactNativeError(module: string): Error {
+  return new Error(
+    `[oxy.platformCrypto] Tried to load '${module}' outside React Native. This module is only available in a React Native runtime; bundling routed this consumer to the default (Node/web) variant. This indicates a missing platform gate (\`isReactNative()\`) in the calling code.`,
+  );
+}
+
+export async function loadExpoCrypto(): Promise<typeof import('expo-crypto')> {
+  if (isReactNative()) {
+    // Should be unreachable: when running on RN, Metro / the `react-native`
+    // exports condition serves the sibling variant. If we got here, the
+    // package-exports map is misconfigured for this host. Throw with a
+    // helpful diagnostic rather than fall back to a broken dynamic import.
+    throw new Error(
+      '[oxy.platformCrypto] React Native runtime resolved the default ' +
+        '(non-RN) variant of @oxyhq/core/utils/platformCrypto. Check the ' +
+        "consumer's bundler resolution — Metro should pick the sibling " +
+        '.react-native.js file via package exports.',
+    );
+  }
+  throw notReactNativeError('expo-crypto');
+}
+
+export async function loadSecureStore(): Promise<typeof import('expo-secure-store')> {
+  throw notReactNativeError('expo-secure-store');
+}
+
+export async function loadAsyncStorage(): Promise<{
+  default: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+  };
+}> {
+  throw notReactNativeError('@react-native-async-storage/async-storage');
+}
+
+/**
+ * Synchronous random-bytes via `expo-crypto.getRandomBytes`. Only available
+ * in the React Native variant. The default variant throws because Node and
+ * browsers have their own native CSPRNGs (`crypto.randomBytes` and
+ * `crypto.getRandomValues` respectively) — callers should use those.
+ */
+export function getRandomBytesRN(_byteCount: number): Uint8Array {
+  throw notReactNativeError('expo-crypto.getRandomBytes (sync)');
+}