@oxyhq/core 3.4.15 → 3.4.17

package/dist/types/mixins/OxyServices.user.d.ts

@@ -2,6 +2,7 @@
  * User Management Methods Mixin
  */
 import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
+import type { UserNameResponse, UserProfileUpdate } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
 export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T): {
@@ -12,7 +13,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         getProfileByUsername(username: string): Promise<User>;
         /**
          * Lightweight username lookup for login flows.
-         * Returns minimal public info: exists, color, avatar, displayName.
+         * Returns minimal public info: exists, color, avatar, name.displayName.
          * Faster than getProfileByUsername — no stats, no formatting.
          */
         lookupUsername(username: string): Promise<{
@@ -20,7 +21,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             username: string;
             color: string | null;
             avatar: string | null;
-            displayName: string;
+            name: UserNameResponse;
         }>;
         /**
          * Search user profiles
@@ -62,11 +63,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         }): Promise<Array<{
             id: string;
             username: string;
-            name?: {
-                first?: string;
-                last?: string;
-                full?: string;
-            };
+            name: UserNameResponse;
             description?: string;
             isFederated?: boolean;
             isAgent?: boolean;
@@ -111,7 +108,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          *
          * TanStack Query handles offline queuing automatically.
          */
-        updateProfile(updates: Partial<User>): Promise<User>;
+        updateProfile(updates: UserProfileUpdate): Promise<User>;
         /**
          * Get privacy settings for a user
          * @param userId - The user ID (defaults to current user)

package/dist/types/models/interfaces.d.ts

@@ -81,26 +81,27 @@ export interface User {
     publicKey: string;
     username: string;
     email?: string;
-    avatar?: string;
-    color?: string;
+    avatar?: string | null;
+    color?: string | null;
     privacySettings?: PrivacySettings;
     /**
-     * Structured human name. The canonical wire shape ({@link UserNameResponse}):
-     * `{ first?, last?, full? }` where `full` is a Mongoose virtual (present only
-     * when the query materialised virtuals). The single source of truth lives in
-     * `@oxyhq/contracts` — do NOT re-declare a bare `string` here.
+     * Structured human name. `name.displayName` is the canonical display string
+     * resolved by the API; consumers render it directly instead of recomposing
+     * names from `first` / `last` / `full` / `username`.
      */
-    name?: UserNameResponse;
+    name: UserNameResponse;
     bio?: string;
     location?: string;
     website?: string;
     createdAt?: string;
     updatedAt?: string;
-    links?: Array<{
+    links?: string[];
+    linksMetadata?: Array<{
+        url: string;
         title?: string;
         description?: string;
         image?: string;
-        link: string;
+        id?: string;
     }>;
     _count?: {
         followers?: number;
@@ -539,7 +540,7 @@ export interface RefreshAllAccountUser {
      * string. The server projects `name` verbatim from the user document. The
      * single source of truth is `@oxyhq/contracts`.
      */
-    name?: UserNameResponse;
+    name: UserNameResponse;
     avatar?: string | null;
     email?: string;
     color?: string | null;

package/dist/types/models/session.d.ts

@@ -1,3 +1,4 @@
+import type { UserNameResponse } from '@oxyhq/contracts';
 export interface ClientSession {
     sessionId: string;
     deviceId: string;
@@ -21,6 +22,7 @@ export interface StorageKeys {
 export interface MinimalUserData {
     id: string;
     username: string;
+    name: UserNameResponse;
     avatar?: string;
 }
 export interface SessionLoginResponse {

package/dist/types/utils/accountUtils.d.ts

@@ -27,18 +27,13 @@ export interface QuickAccount {
 /** Minimal user shape accepted by display-name helpers. Avoids importing the full User type. */
 export interface DisplayNameUserShape {
     name?: string | {
+        displayName?: string;
         first?: string;
         last?: string;
         full?: string;
         [key: string]: unknown;
     };
-    /**
-     * Pre-resolved display name as emitted by the server's `displayName` virtual
-     * (raw `/users/me` responses). NOTE: the server virtual resolves to
-     * `username || truncatedPublicKey || 'Anonymous'` — it does NOT compose the
-     * structured `name`. It is therefore preferred only AFTER a real structured
-     * name, so a first-name-only account never collapses to its username/key.
-     */
+    /** Pre-normalized account-row display name, not the API User DTO field. */
     displayName?: string;
     username?: string;
     publicKey?: string;
@@ -52,16 +47,13 @@ export declare const formatPublicKeyHandle: (publicKey: string) => string;
  * Resolve a friendly display name for a user.
  *
  * Order of preference:
- *  1. `name.full`, or composed `name.first name.last` (FIRST-NAME-ONLY SAFE —
- *     a user with only a first name resolves to that first name, never to the
- *     lowercase username; this is the exact drift bug the auth app hit).
- *  2. `name` (when stored as a plain string)
- *  3. `displayName` (server `displayName` virtual — `username || truncatedKey`).
- *     Placed AFTER the structured name on purpose: the server virtual ignores
- *     `name`, so preferring it first would re-introduce the first-only bug.
- *  4. `username`
- *  5. `Account 0x12345678…` (derived from publicKey, when present)
- *  6. Translated fallback (e.g. "Unnamed")
+ *  1. `name.displayName` from the API user contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when passed as a plain string by local non-DTO call sites.
+ *  4. pre-normalized account-row `displayName`.
+ *  5. `username`
+ *  6. `Account 0x12345678…` (derived from publicKey, when present)
+ *  7. 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.
@@ -89,6 +81,7 @@ export declare const buildAccountsArray: (accounts: Record<string, QuickAccount>
  */
 export declare const createQuickAccount: (sessionId: string, userData: {
     name?: string | {
+        displayName?: string;
         full?: string;
         first?: string;
         last?: string;
@@ -99,7 +92,7 @@ export declare const createQuickAccount: (sessionId: string, userData: {
     _id?: {
         toString(): string;
     } | string;
-    avatar?: string;
+    avatar?: string | null;
 }, existingAccount?: QuickAccount, getFileDownloadUrl?: (fileId: string, variant: string) => string) => QuickAccount;
 /**
  * Merge a fresh `/auth/refresh-all` snapshot into an existing QuickAccount

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.15",
+  "version": "3.4.17",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -97,7 +97,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.1.0",
+    "@oxyhq/contracts": "^0.1.1",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/AuthManager.ts

@@ -497,7 +497,7 @@ export class AuthManager {
       this.oxyServices.httpService.setTokens(session.accessToken);
     }
 
-    if (session.user && typeof (session.user as any).id === 'string' && (session.user as any).id.length > 0) {
+    if (session.user && typeof session.user.id === 'string' && session.user.id.length > 0) {
       this.currentUser = session.user;
     }
 
@@ -514,6 +514,7 @@ export class AuthManager {
         user: {
           id: session.user.id,
           username: session.user.username,
+          name: session.user.name,
           avatar: session.user.avatar ?? null,
         },
         accessToken: session.accessToken,
@@ -758,6 +759,7 @@ export class AuthManager {
     return {
       id: account.user.id,
       username: account.user.username,
+      name: account.user.name,
       avatar: account.user.avatar ?? undefined,
     };
   }
@@ -806,6 +808,7 @@ export class AuthManager {
       this.currentUser = {
         id: hydrated.id,
         username: hydrated.username,
+        name: hydrated.name,
         avatar: hydrated.avatar ?? undefined,
       };
       this.notifyListeners();
@@ -1022,6 +1025,7 @@ export class AuthManager {
       ? {
           id: updated.user.id,
           username: updated.user.username,
+          name: updated.user.name,
           avatar: updated.user.avatar ?? undefined,
         }
       : null;
@@ -1083,6 +1087,7 @@ export class AuthManager {
           ? {
               id: next.user.id,
               username: next.user.username,
+              name: next.user.name,
               avatar: next.user.avatar ?? undefined,
             }
           : null;

package/src/mixins/OxyServices.auth.ts

@@ -684,7 +684,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           continue;
         }
         const userId = e.user.id ?? e.user._id;
-        if (!userId || !e.user.username) {
+        if (!userId || !e.user.username || !e.user.name?.displayName) {
           continue;
         }
         if (typeof e.authuser !== 'number') {

package/src/mixins/OxyServices.sso.ts

@@ -25,6 +25,7 @@
 
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
+import type { UserNameResponse } from '@oxyhq/contracts';
 import { createDebugLogger } from '../shared/utils/debugUtils';
 
 const debug = createDebugLogger('SSO');
@@ -40,6 +41,7 @@ interface SsoExchangeWireResponse {
     id?: string;
     _id?: string;
     username?: string;
+    name?: UserNameResponse;
     avatar?: string;
   };
   expiresAt?: string;
@@ -140,13 +142,14 @@ export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
       }
 
       const userId = payload.user?.id ?? payload.user?._id;
-      if (!userId || typeof payload.user?.username !== 'string') {
+      if (!userId || typeof payload.user?.username !== 'string' || typeof payload.user.name?.displayName !== 'string') {
         throw this.handleError(new Error('SSO exchange returned an invalid user'));
       }
 
       const user: MinimalUserData = {
         id: userId,
         username: payload.user.username,
+        name: payload.user.name,
         avatar: payload.user.avatar,
       };
 

package/src/mixins/OxyServices.user.ts

@@ -10,6 +10,7 @@ import type {
   PaginationInfo,
   PrivacySettings,
 } from '../models/interfaces';
+import type { UserNameResponse, UserProfileUpdate } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
 import { KeyManager } from '../crypto/keyManager';
@@ -38,7 +39,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
     /**
      * Lightweight username lookup for login flows.
-     * Returns minimal public info: exists, color, avatar, displayName.
+     * Returns minimal public info: exists, color, avatar, name.displayName.
      * Faster than getProfileByUsername — no stats, no formatting.
      */
     async lookupUsername(username: string): Promise<{
@@ -46,7 +47,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       username: string;
       color: string | null;
       avatar: string | null;
-      displayName: string;
+      name: UserNameResponse;
     }> {
       return await this.makeRequest('GET', `/auth/lookup/${encodeURIComponent(username)}`, undefined, {
         cache: true,
@@ -150,7 +151,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }): Promise<Array<{
       id: string;
       username: string;
-      name?: { first?: string; last?: string; full?: string };
+      name: UserNameResponse;
       description?: string;
       isFederated?: boolean;
       isAgent?: boolean;
@@ -225,7 +226,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      *
      * TanStack Query handles offline queuing automatically.
      */
-    async updateProfile(updates: Partial<User>): Promise<User> {
+    async updateProfile(updates: UserProfileUpdate): Promise<User> {
       try {
         const result = normalizeUserIdentity(
           await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false }),

package/src/models/interfaces.ts

@@ -89,28 +89,29 @@ export interface User {
   username: string;
   email?: string;
   // Avatar file id (asset id)
-  avatar?: string;
+  avatar?: string | null;
   // Named color preset (e.g. 'teal', 'blue', 'purple')
-  color?: string;
+  color?: string | null;
   // Privacy and security settings
   privacySettings?: PrivacySettings;
   /**
-   * Structured human name. The canonical wire shape ({@link UserNameResponse}):
-   * `{ first?, last?, full? }` where `full` is a Mongoose virtual (present only
-   * when the query materialised virtuals). The single source of truth lives in
-   * `@oxyhq/contracts` — do NOT re-declare a bare `string` here.
+   * Structured human name. `name.displayName` is the canonical display string
+   * resolved by the API; consumers render it directly instead of recomposing
+   * names from `first` / `last` / `full` / `username`.
    */
-  name?: UserNameResponse;
+  name: UserNameResponse;
   bio?: string;
   location?: string;
   website?: string;
   createdAt?: string;
   updatedAt?: string;
-  links?: Array<{
+  links?: string[];
+  linksMetadata?: Array<{
+    url: string;
     title?: string;
     description?: string;
     image?: string;
-    link: string;
+    id?: string;
   }>;
   // Social counts
   _count?: {
@@ -651,7 +652,7 @@ export interface RefreshAllAccountUser {
    * string. The server projects `name` verbatim from the user document. The
    * single source of truth is `@oxyhq/contracts`.
    */
-  name?: UserNameResponse;
+  name: UserNameResponse;
   avatar?: string | null;
   email?: string;
   color?: string | null;

package/src/models/session.ts

@@ -1,3 +1,5 @@
+import type { UserNameResponse } from '@oxyhq/contracts';
+
 export interface ClientSession {
   sessionId: string;
   deviceId: string;
@@ -23,6 +25,7 @@ export interface StorageKeys {
 export interface MinimalUserData {
   id: string;
   username: string;
+  name: UserNameResponse;
   avatar?: string; // file id
 }
 

package/src/utils/__tests__/accountUtils.test.ts

@@ -4,16 +4,16 @@ import {
     formatPublicKeyHandle,
 } from '../accountUtils';
 
-/**
- * Regression coverage for the auth-app display-name drift (Phase 1 of the
- * contract-centralisation refactor).
- *
- * The auth app previously required BOTH `name.first` AND `name.last` to compose
- * a display name, falling back to the lowercase `username` for first-name-only
- * accounts. The canonical resolver in core MUST be first-name-only safe: a user
- * with only a first name resolves to that first name, never to the username.
- */
 describe('getAccountDisplayName', () => {
+    it('prefers the API name.displayName when present', () => {
+        expect(
+            getAccountDisplayName({
+                name: { first: 'Nate', displayName: 'Nate Isern' },
+                username: 'nateus',
+            }),
+        ).toBe('Nate Isern');
+    });
+
     it('returns first name for first-name-only accounts (NOT the username)', () => {
         const result = getAccountDisplayName({
             name: { first: 'Nate' },
@@ -50,20 +50,7 @@ describe('getAccountDisplayName', () => {
         ).toBe('Nathaniel Isern');
     });
 
-    it('uses the structured name over a server displayName virtual', () => {
-        // Server `displayName` virtual = `username || truncatedKey`; it ignores
-        // the structured name. A real name must win so a first-only account is
-        // never collapsed to its username.
-        expect(
-            getAccountDisplayName({
-                name: { first: 'Nate' },
-                displayName: 'nateus',
-                username: 'nateus',
-            }),
-        ).toBe('Nate');
-    });
-
-    it('uses displayName when there is no structured name', () => {
+    it('uses pre-normalized account-row displayName when there is no structured name', () => {
         expect(
             getAccountDisplayName({
                 displayName: 'Cool Display',

package/src/utils/accountUtils.ts

@@ -30,14 +30,14 @@ export interface QuickAccount {
 
 /** 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 };
-    /**
-     * Pre-resolved display name as emitted by the server's `displayName` virtual
-     * (raw `/users/me` responses). NOTE: the server virtual resolves to
-     * `username || truncatedPublicKey || 'Anonymous'` — it does NOT compose the
-     * structured `name`. It is therefore preferred only AFTER a real structured
-     * name, so a first-name-only account never collapses to its username/key.
-     */
+    name?: string | {
+        displayName?: string;
+        first?: string;
+        last?: string;
+        full?: string;
+        [key: string]: unknown;
+    };
+    /** Pre-normalized account-row display name, not the API User DTO field. */
     displayName?: string;
     username?: string;
     publicKey?: string;
@@ -57,16 +57,13 @@ export const formatPublicKeyHandle = (publicKey: string): string => {
  * Resolve a friendly display name for a user.
  *
  * Order of preference:
- *  1. `name.full`, or composed `name.first name.last` (FIRST-NAME-ONLY SAFE —
- *     a user with only a first name resolves to that first name, never to the
- *     lowercase username; this is the exact drift bug the auth app hit).
- *  2. `name` (when stored as a plain string)
- *  3. `displayName` (server `displayName` virtual — `username || truncatedKey`).
- *     Placed AFTER the structured name on purpose: the server virtual ignores
- *     `name`, so preferring it first would re-introduce the first-only bug.
- *  4. `username`
- *  5. `Account 0x12345678…` (derived from publicKey, when present)
- *  6. Translated fallback (e.g. "Unnamed")
+ *  1. `name.displayName` from the API user contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when passed as a plain string by local non-DTO call sites.
+ *  4. pre-normalized account-row `displayName`.
+ *  5. `username`
+ *  6. `Account 0x12345678…` (derived from publicKey, when present)
+ *  7. 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.
@@ -80,6 +77,9 @@ export const getAccountDisplayName = (
     const { name, displayName, username, publicKey } = user;
 
     if (name && typeof name === 'object') {
+        if (typeof name.displayName === 'string' && name.displayName.trim()) {
+            return name.displayName.trim();
+        }
         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() : '';
@@ -146,12 +146,12 @@ export const buildAccountsArray = (
 export const createQuickAccount = (
     sessionId: string,
     userData: {
-        name?: string | { full?: string; first?: string; last?: string };
+        name?: string | { displayName?: string; full?: string; first?: string; last?: string };
         username?: string;
         publicKey?: string;
         id?: string;
         _id?: { toString(): string } | string;
-        avatar?: string;
+        avatar?: string | null;
     },
     existingAccount?: QuickAccount,
     getFileDownloadUrl?: (fileId: string, variant: string) => string
@@ -161,10 +161,11 @@ export const createQuickAccount = (
 
     // Preserve existing avatarUrl if avatar hasn't changed (prevents image reload)
     let avatarUrl: string | undefined;
-    if (existingAccount && existingAccount.avatar === userData.avatar && existingAccount.avatarUrl) {
+    const avatar = userData.avatar ?? undefined;
+    if (existingAccount && existingAccount.avatar === avatar && existingAccount.avatarUrl) {
         avatarUrl = existingAccount.avatarUrl;
-    } else if (userData.avatar && getFileDownloadUrl) {
-        avatarUrl = getFileDownloadUrl(userData.avatar, 'thumb');
+    } else if (avatar && getFileDownloadUrl) {
+        avatarUrl = getFileDownloadUrl(avatar, 'thumb');
     }
 
     return {
@@ -172,7 +173,7 @@ export const createQuickAccount = (
         userId,
         username: userData.username || '',
         displayName,
-        avatar: userData.avatar,
+        avatar,
         avatarUrl,
     };
 };

package/src/utils/asyncUtils.ts

@@ -277,4 +277,4 @@ export async function retryOnError<T>(
     const errorCode = error?.code || error?.status || error?.message;
     return retryableErrors.includes(errorCode);
   });
-} 
+}