@oxyhq/core 1.11.11 → 1.11.13

package/src/mixins/OxyServices.contacts.ts

@@ -0,0 +1,73 @@
+/**
+ * Contact Discovery Mixin
+ *
+ * Privacy-preserving discovery of which address-book contacts are on Oxy.
+ *
+ * The client hashes emails and phones locally before calling the API.
+ * The server responds with only Oxy user IDs and the hashes that matched,
+ * so the consumer can map each match back to the local contact that
+ * produced it.
+ *
+ * Hashing rules (must match the server `utils/contactHash.ts` exactly):
+ *   - SHA-256, hex-encoded, lowercase
+ *   - Email: `value.trim().toLowerCase()` then digest
+ *   - Phone: trim → keep a single leading "+" → strip non-digits → prepend "+"
+ *     if missing → digest
+ *
+ * Mobile clients can compute these digests with `expo-crypto`'s
+ * `digestStringAsync(SHA256, value, { encoding: HEX })`. Web clients should
+ * use `SubtleCrypto.digest('SHA-256', ...)`.
+ */
+
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/** A single match returned by `POST /contacts/discover`. */
+export interface ContactDiscoveryMatch {
+  /** Oxy user ID (MongoDB ObjectId hex string). */
+  userId: string;
+  /** The hashed identifier from the request that matched this user. */
+  hashedIdentifier: string;
+  /** Whether the match came from the email index or phone index. */
+  matchType: 'email' | 'phone';
+}
+
+/** Response shape of `POST /contacts/discover`. */
+export interface ContactDiscoveryResponse {
+  matches: ContactDiscoveryMatch[];
+}
+
+export function OxyServicesContactsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Discover which of the caller's contacts are on Oxy.
+     *
+     * @param hashedEmails - SHA-256 hex digests of normalized emails.
+     * @param hashedPhones - SHA-256 hex digests of normalized phone numbers.
+     * @returns Matches mapping each hashed identifier to the Oxy user ID it
+     *   resolved to. Empty arrays are valid for either parameter, but at
+     *   least one must be non-empty.
+     *
+     * The server enforces a 200-hash cap per channel per request — callers
+     * should batch larger address books client-side.
+     */
+    async discoverContacts(
+      hashedEmails: string[],
+      hashedPhones: string[],
+    ): Promise<ContactDiscoveryResponse> {
+      try {
+        return await this.makeRequest<ContactDiscoveryResponse>(
+          'POST',
+          '/contacts/discover',
+          { hashedEmails, hashedPhones },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.features.ts

@@ -412,17 +412,7 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
             }
         }
 
-        // ==================
-        // ACCOUNT
-        // ==================
-
-        /**
-         * Delete user account (requires password confirmation)
-         */
-        async deleteAccount(password: string): Promise<void> {
-            return this.withAuthRetry(async () => {
-                await this.makeRequest('DELETE', '/account', { password }, { cache: false });
-            }, 'deleteAccount');
-        }
+        // Account deletion lives in OxyServices.user mixin — it requires
+        // an identity-key signature (not just a password) and hits DELETE /users/me.
     };
 }

package/src/mixins/OxyServices.fedcm.ts

@@ -372,10 +372,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
               {
                 configURL: options.configURL,
                 clientId: options.clientId,
-                // Send nonce at both levels for backward compatibility
-                nonce: options.nonce, // For older browsers
+                // Older browsers read `nonce` at the top level; Chrome 145+
+                // expects it inside `params`. Send both for full coverage.
+                nonce: options.nonce,
                 params: {
-                  nonce: options.nonce, // For Chrome 145+
+                  nonce: options.nonce,
                 },
                 ...(options.loginHint && { loginHint: options.loginHint }),
               },

package/src/mixins/OxyServices.language.ts

@@ -4,6 +4,7 @@
 import { normalizeLanguageCode, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils';
 import type { LanguageMetadata } from '../utils/languageUtils';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { loadAsyncStorage } from '../utils/platformCrypto';
 import { isDev } from '../shared/utils/debugUtils';
 
 export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base: T) {
@@ -23,10 +24,11 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
       
       if (isReactNative) {
         try {
-          // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
-          const moduleName = '@react-native-async-storage/async-storage';
-          const asyncStorageModule = await import(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/mixins/OxyServices.redirect.ts

@@ -177,12 +177,16 @@ export function OxyServicesRedirectAuthMixin<T extends typeof OxyServicesBase>(B
     this.storeTokens(accessToken, sessionId);
     this.httpService.setTokens(accessToken);
 
-    // Build session response (minimal - we'll fetch full user data separately)
+    // Build session response (minimal — full user data is fetched separately
+    // by the caller via getCurrentUser() once tokens are stored).
     const session: SessionLoginResponse = {
       sessionId,
       deviceId: '', // Not available in redirect flow
       expiresAt: expiresAt || new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-      user: {} as any, // Will be fetched separately
+      // Placeholder user — caller MUST fetch real user data via getCurrentUser()
+      // before exposing this session to the application. The empty id signals
+      // that the user payload has not yet been populated.
+      user: { id: '', username: '' },
     };
 
     // Clean up URL (remove auth parameters)

package/src/mixins/OxyServices.security.ts

@@ -24,19 +24,29 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
       eventType?: SecurityEventType
     ): Promise<SecurityActivityResponse> {
       try {
-        const params: any = {};
+        const params: Record<string, unknown> = {};
         if (limit !== undefined) params.limit = limit;
         if (offset !== undefined) params.offset = offset;
         if (eventType) params.eventType = eventType;
 
-        const response = await this.makeRequest<SecurityActivityResponse>(
-          'GET',
-          '/security/activity',
-          params,
-          { cache: false }
-        );
+        // The API responds with the standard paginated envelope:
+        //   { data: SecurityActivity[], pagination: { total, limit, offset, hasMore } }
+        // SecurityActivityResponse is the flattened shape consumers expect.
+        const raw = await this.makeRequest<{
+          data: SecurityActivity[];
+          pagination: { total: number; limit: number; offset: number; hasMore: boolean };
+        }>('GET', '/security/activity', params, { cache: false });
+
+        const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+        const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
 
-        return response;
+        return {
+          data: raw.data ?? [],
+          total: raw.pagination?.total ?? raw.data?.length ?? 0,
+          limit: raw.pagination?.limit ?? requestedLimit,
+          offset: raw.pagination?.offset ?? requestedOffset,
+          hasMore: raw.pagination?.hasMore ?? false,
+        };
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.user.ts

@@ -1,9 +1,11 @@
 /**
  * User Management Methods Mixin
  */
-import type { User, Notification, SearchProfilesResponse, PaginationInfo } from '../models/interfaces';
+import type { User, Notification, SearchProfilesResponse, PaginationInfo, PrivacySettings } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
+import { KeyManager } from '../crypto/keyManager';
+import { SignatureService } from '../crypto/signatureService';
 
 export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -24,6 +26,24 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Lightweight username lookup for login flows.
+     * Returns minimal public info: exists, color, avatar, displayName.
+     * Faster than getProfileByUsername — no stats, no formatting.
+     */
+    async lookupUsername(username: string): Promise<{
+      exists: boolean;
+      username: string;
+      color: string | null;
+      avatar: string | null;
+      displayName: string;
+    }> {
+      return await this.makeRequest('GET', `/auth/lookup/${encodeURIComponent(username)}`, undefined, {
+        cache: true,
+        cacheTTL: 60 * 1000, // 1 minute cache
+      });
+    }
+
     /**
      * Search user profiles
      */
@@ -33,7 +53,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const searchParams = buildSearchParams(params);
         const paramsObj = Object.fromEntries(searchParams.entries());
 
-        const response = await this.makeRequest<SearchProfilesResponse | User[]>(
+        const response = await this.makeRequest<SearchProfilesResponse>(
           'GET',
           '/profiles/search',
           paramsObj,
@@ -43,43 +63,26 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           }
         );
 
-        // New API shape: { data: User[], pagination: {...} }
-        const isSearchProfilesResponse = (payload: unknown): payload is SearchProfilesResponse =>
-          typeof payload === 'object' &&
-          payload !== null &&
-          Array.isArray((payload as SearchProfilesResponse).data);
-
-        if (isSearchProfilesResponse(response)) {
-          const typedResponse = response;
-          const paginationInfo: PaginationInfo = typedResponse.pagination ?? {
-            total: typedResponse.data.length,
-            limit: pagination?.limit ?? typedResponse.data.length,
-            offset: pagination?.offset ?? 0,
-            hasMore: typedResponse.data.length === (pagination?.limit ?? typedResponse.data.length) &&
-              (pagination?.limit ?? typedResponse.data.length) > 0,
-          };
-
-          return {
-            data: typedResponse.data,
-            pagination: paginationInfo,
-          };
+        if (
+          typeof response !== 'object' ||
+          response === null ||
+          !Array.isArray(response.data)
+        ) {
+          throw new Error('Unexpected search response format');
         }
 
-        // Legacy API shape: returns raw User[]
-        if (Array.isArray(response)) {
-          const fallbackLimit = pagination?.limit ?? response.length;
-          const fallbackPagination: PaginationInfo = {
-            total: response.length,
-            limit: fallbackLimit,
-            offset: pagination?.offset ?? 0,
-            hasMore: fallbackLimit > 0 && response.length === fallbackLimit,
-          };
-
-          return { data: response, pagination: fallbackPagination };
-        }
+        const paginationInfo: PaginationInfo = response.pagination ?? {
+          total: response.data.length,
+          limit: pagination?.limit ?? response.data.length,
+          offset: pagination?.offset ?? 0,
+          hasMore: response.data.length === (pagination?.limit ?? response.data.length) &&
+            (pagination?.limit ?? response.data.length) > 0,
+        };
 
-        // If response is unexpected, throw an error
-        throw new Error('Unexpected search response format');
+        return {
+          data: response.data,
+          pagination: paginationInfo,
+        };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -188,12 +191,33 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Update user profile
-     * TanStack Query handles offline queuing automatically
+     * Update user profile.
+     *
+     * Invalidates the SDK-side response cache for every endpoint that
+     * returns the current user (`GET /users/me`, `GET /session/user/*`,
+     * `GET /users/<id>`, `GET /profiles/username/*`) so the next read
+     * doesn't return a stale snapshot. Without this, a follow-up
+     * `getUserBySession` call inside the 2-minute cache window can return
+     * the pre-update user — most visibly during onboarding, where it
+     * causes the username step to flicker back as if nothing was saved.
+     *
+     * TanStack Query handles offline queuing automatically.
      */
-    async updateProfile(updates: Record<string, any>): Promise<User> {
+    async updateProfile(updates: Partial<User>): Promise<User> {
       try {
-        return await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false });
+        const result = await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false });
+
+        // Bust every cached representation of the current user. We use a
+        // prefix sweep rather than an enumeration because the SDK never
+        // tracks the set of active session IDs centrally.
+        this.clearCacheByPrefix('GET:/session/user/');
+        this.clearCacheByPrefix('GET:/users/me');
+        this.clearCacheByPrefix('GET:/profiles/username/');
+        if (result?.id) {
+          this.clearCacheEntry(`GET:/users/${result.id}`);
+        }
+
+        return result;
       } catch (error) {
         const errorAny = error as any;
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -219,10 +243,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * Get privacy settings for a user
      * @param userId - The user ID (defaults to current user)
      */
-    async getPrivacySettings(userId?: string): Promise<any> {
+    async getPrivacySettings(userId?: string): Promise<PrivacySettings> {
       try {
         const id = userId || (await this.getCurrentUser()).id;
-        return await this.makeRequest<any>('GET', `/privacy/${id}/privacy`, undefined, {
+        return await this.makeRequest<PrivacySettings>('GET', `/privacy/${id}/privacy`, undefined, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
         });
@@ -236,10 +260,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * @param settings - Partial privacy settings object
      * @param userId - The user ID (defaults to current user)
      */
-    async updatePrivacySettings(settings: Record<string, any>, userId?: string): Promise<any> {
+    async updatePrivacySettings(settings: Partial<PrivacySettings>, userId?: string): Promise<PrivacySettings> {
       try {
         const id = userId || (await this.getCurrentUser()).id;
-        return await this.makeRequest<any>('PATCH', `/privacy/${id}/privacy`, settings, {
+        return await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
       } catch (error) {
@@ -281,14 +305,31 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Delete account permanently
-     * @param password - User password for confirmation
-     * @param confirmText - Confirmation text (usually username)
+     * Delete account permanently.
+     *
+     * Signs `delete:{publicKey}:{timestamp}` with the locally-stored identity
+     * private key and submits the signature alongside the confirmation text
+     * (must equal the user's username). The signature is the cryptographic
+     * proof of ownership — only the device holding the private key can issue
+     * a valid signature, so no password is required.
+     *
+     * @param confirmText - Must equal the user's username (verified server-side)
+     * @throws If no identity is stored on this device, or signing fails
      */
-    async deleteAccount(password: string, confirmText: string): Promise<{ message: string }> {
+    async deleteAccount(confirmText: string): Promise<{ message: string }> {
       try {
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+          throw new Error('No identity found on this device. Account deletion requires the device that holds your identity key.');
+        }
+
+        const timestamp = Date.now();
+        const message = `delete:${publicKey}:${timestamp}`;
+        const signature = await SignatureService.sign(message);
+
         return await this.makeRequest<{ message: string }>('DELETE', '/users/me', {
-          password,
+          signature,
+          timestamp,
           confirmText,
         }, { cache: false });
       } catch (error) {

package/src/mixins/OxyServices.utility.ts

@@ -7,6 +7,7 @@
 import { jwtDecode } from 'jwt-decode';
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { loadNodeCrypto } from '../utils/platformCrypto';
 import { CACHE_TIMES } from './mixinHelpers';
 
 interface JwtPayload {
@@ -297,9 +298,15 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               return res.status(403).json(error);
             }
 
-            // Verify JWT signature (not just decode)
+            // Verify JWT signature (not just decode).
+            // This middleware only runs on a Node Express server, but the file
+            // is bundled by Metro/Vite for RN/web consumers. `loadNodeCrypto`
+            // is per-platform: the RN variant throws (and is never called
+            // because service-token middleware is only mounted by Node hosts),
+            // so Metro never bundles a reference to Node's built-in.
             try {
-              const { createHmac } = await import('crypto');
+              const nodeCrypto = await loadNodeCrypto();
+              const { createHmac, timingSafeEqual } = nodeCrypto;
               const [headerB64, payloadB64, signatureB64] = token.split('.');
               if (!headerB64 || !payloadB64 || !signatureB64) {
                 throw new Error('Invalid token structure');
@@ -314,7 +321,6 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               // Timing-safe comparison
               const sigBuf = Buffer.from(signatureB64);
               const expectedBuf = Buffer.from(expectedSig);
-              const { timingSafeEqual } = await import('crypto');
               if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
                 throw new Error('Invalid signature');
               }
@@ -339,8 +345,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               return res.status(401).json(error);
             }
 
-            // Check expiration
-            if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+            // Check expiration — reject tokens at exact expiry second (use <=)
+            if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
               if (optional) {
                 req.userId = null;
                 req.user = null;
@@ -400,7 +406,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           }
 
           // Check token expiration locally first (fast path)
-          if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+          // Reject tokens at exact expiry second (use <=)
+          if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
             if (optional) {
               req.userId = null;
               req.user = null;
@@ -578,8 +585,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return next(new Error('Invalid token payload'));
           }
 
-          // Check expiration
-          if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+          // Check expiration — reject tokens at exact expiry second (use <=)
+          if (decoded.exp && decoded.exp <= Math.floor(Date.now() / 1000)) {
             return next(new Error('Token expired'));
           }
 
@@ -597,13 +604,15 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             }
           }
 
-          // Attach user data to socket
+          // Attach user data to socket. We expose BOTH `socket.data.userId`
+          // (the official Socket.IO data slot) and `socket.user` because
+          // every consumer in this ecosystem (Mention, Allo, api/server.ts)
+          // reads from `socket.user.id`.
           socket.data = socket.data || {};
           socket.data.userId = userId;
           socket.data.sessionId = decoded.sessionId || null;
           socket.data.token = token;
 
-          // Also set on socket.user for backward compatibility
           socket.user = { id: userId, userId, sessionId: decoded.sessionId };
 
           if (debug) {

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
  */