@oxyhq/core 3.4.14 → 3.4.16

package/dist/types/index.d.ts

@@ -34,8 +34,9 @@ export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServic
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
-export { getCanonicalUserHandle, getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
-export type { CanonicalUserHandleInput } from './utils/userIdentity';
+export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
+export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';
+export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
 export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';

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

@@ -80,6 +80,8 @@ export interface User {
     id: string;
     publicKey: string;
     username: string;
+    /** Canonical display name resolved by the API. */
+    displayName: string;
     email?: string;
     avatar?: string;
     color?: string;

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

@@ -32,13 +32,7 @@ export interface DisplayNameUserShape {
         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.
-     */
+    /** Canonical display name resolved by the API. */
     displayName?: string;
     username?: string;
     publicKey?: string;
@@ -52,13 +46,9 @@ 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.
+ *  1. `displayName` from the API contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when stored as a plain string.
  *  4. `username`
  *  5. `Account 0x12345678…` (derived from publicKey, when present)
  *  6. Translated fallback (e.g. "Unnamed")

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

@@ -0,0 +1,26 @@
+export interface UserHandleInput {
+    username?: string | null;
+    handle?: string | null;
+    instance?: string | null;
+    isFederated?: boolean | null;
+    type?: string | null;
+    federation?: {
+        domain?: string | null;
+    } | null;
+}
+export type CanonicalUserHandleInput = UserHandleInput;
+/**
+ * Returns the normalized profile handle used by Oxy consumers for display and
+ * profile routing.
+ *
+ * Local users resolve to `username`. Federated users resolve to
+ * `username@instance` when the username does not already include an instance.
+ * Route-like values are rejected so callers do not accidentally turn paths or
+ * query strings into profile destinations.
+ */
+export declare function getNormalizedUserHandle(user: UserHandleInput | null | undefined): string | null;
+/**
+ * Compatibility alias for the first public name shipped with this helper.
+ * Prefer {@link getNormalizedUserHandle} in new code.
+ */
+export declare function getCanonicalUserHandle(user: CanonicalUserHandleInput | null | undefined): string | null;

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

@@ -2,22 +2,20 @@ interface UserIdentityInput {
     id?: unknown;
     _id?: unknown;
 }
-export interface CanonicalUserHandleInput {
-    username?: string | null;
-    handle?: string | null;
-    instance?: string | null;
-    isFederated?: boolean | null;
-    type?: string | null;
-    federation?: {
-        domain?: string | null;
-    } | null;
-}
+/**
+ * Returns the stable SDK user id from API payloads that may use either `id` or
+ * Mongo-style `_id`.
+ */
 export declare function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null;
+/**
+ * Normalizes a user payload to always expose `id`. Throws when the payload does
+ * not contain a usable id, because SDK callers should never receive anonymous
+ * user objects from authenticated identity endpoints.
+ */
 export declare function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & {
     id: string;
 };
 export declare function normalizeUserIdentityOrNull<T extends UserIdentityInput>(user: T | null | undefined): (T & {
     id: string;
 }) | null;
-export declare function getCanonicalUserHandle(user: CanonicalUserHandleInput | null | undefined): string | null;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.14",
+  "version": "3.4.16",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/__tests__/userIdentity.test.ts

@@ -1,5 +1,6 @@
 import { OxyServices } from '../OxyServices';
-import { getCanonicalUserHandle, getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentity';
+import { getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentity';
+import { getCanonicalUserHandle, getNormalizedUserHandle } from '../utils/userHandle';
 
 interface FetchCall {
   url: string;
@@ -72,14 +73,18 @@ describe('user identity normalization', () => {
   });
 });
 
-describe('getCanonicalUserHandle', () => {
+describe('getNormalizedUserHandle', () => {
   it('normalizes local usernames without route prefixes', () => {
-    expect(getCanonicalUserHandle({ username: ' nate ' })).toBe('nate');
-    expect(getCanonicalUserHandle({ username: '@nate' })).toBe('nate');
+    expect(getNormalizedUserHandle({ username: ' nate ' })).toBe('nate');
+    expect(getNormalizedUserHandle({ username: '@nate' })).toBe('nate');
+  });
+
+  it('falls back to handle when username is missing', () => {
+    expect(getNormalizedUserHandle({ handle: '@nate' })).toBe('nate');
   });
 
   it('builds federated handles from username and instance', () => {
-    expect(getCanonicalUserHandle({
+    expect(getNormalizedUserHandle({
       username: 'joannastern',
       isFederated: true,
       instance: 'threads.net',
@@ -87,7 +92,7 @@ describe('getCanonicalUserHandle', () => {
   });
 
   it('does not append an instance twice', () => {
-    expect(getCanonicalUserHandle({
+    expect(getNormalizedUserHandle({
       username: '@joannastern@threads.net',
       type: 'federated',
       instance: 'threads.net',
@@ -95,7 +100,7 @@ describe('getCanonicalUserHandle', () => {
   });
 
   it('uses federation domain as the federated instance source', () => {
-    expect(getCanonicalUserHandle({
+    expect(getNormalizedUserHandle({
       username: 'alice',
       isFederated: true,
       federation: { domain: '@example.social' },
@@ -103,16 +108,36 @@ describe('getCanonicalUserHandle', () => {
   });
 
   it('does not use instance for local users', () => {
-    expect(getCanonicalUserHandle({
+    expect(getNormalizedUserHandle({
       username: 'alice',
       instance: 'example.social',
     })).toBe('alice');
   });
 
+  it('keeps case while normalizing whitespace', () => {
+    expect(getNormalizedUserHandle({
+      username: ' Alice ',
+      isFederated: true,
+      instance: ' Example.Social ',
+    })).toBe('Alice@Example.Social');
+  });
+
+  it('does not turn an invalid instance into a federated suffix', () => {
+    expect(getNormalizedUserHandle({
+      username: 'alice',
+      isFederated: true,
+      instance: 'example.social/users/alice',
+    })).toBe('alice');
+  });
+
   it('rejects empty and route-like values', () => {
-    expect(getCanonicalUserHandle({ username: '' })).toBeNull();
-    expect(getCanonicalUserHandle({ username: 'alice/about' })).toBeNull();
-    expect(getCanonicalUserHandle({ username: 'alice?tab=posts' })).toBeNull();
-    expect(getCanonicalUserHandle({ username: 'alice#posts' })).toBeNull();
+    expect(getNormalizedUserHandle({ username: '' })).toBeNull();
+    expect(getNormalizedUserHandle({ username: 'alice/about' })).toBeNull();
+    expect(getNormalizedUserHandle({ username: 'alice?tab=posts' })).toBeNull();
+    expect(getNormalizedUserHandle({ username: 'alice#posts' })).toBeNull();
+  });
+
+  it('keeps the compatibility alias wired to the normalized implementation', () => {
+    expect(getCanonicalUserHandle({ username: '@nate' })).toBe('nate');
   });
 });

package/src/index.ts

@@ -62,13 +62,20 @@ export type {
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
+
+// ---------------------------------------------------------------------------
+// User identity and handles
+// ---------------------------------------------------------------------------
 export {
-    getCanonicalUserHandle,
     getNormalizedUserId,
     normalizeUserIdentity,
     normalizeUserIdentityOrNull,
 } from './utils/userIdentity';
-export type { CanonicalUserHandleInput } from './utils/userIdentity';
+export {
+    getCanonicalUserHandle,
+    getNormalizedUserHandle,
+} from './utils/userHandle';
+export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
 
 // ---------------------------------------------------------------------------
 // Applications (multi-user apps: membership, roles, credentials)

package/src/models/interfaces.ts

@@ -87,6 +87,8 @@ export interface User {
   id: string;
   publicKey: string;
   username: string;
+  /** Canonical display name resolved by the API. */
+  displayName: string;
   email?: string;
   // Avatar file id (asset id)
   avatar?: string;

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

@@ -4,16 +4,17 @@ 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 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,19 +51,6 @@ 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', () => {
         expect(
             getAccountDisplayName({

package/src/utils/accountUtils.ts

@@ -31,13 +31,7 @@ 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.
-     */
+    /** Canonical display name resolved by the API. */
     displayName?: string;
     username?: string;
     publicKey?: string;
@@ -57,13 +51,9 @@ 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.
+ *  1. `displayName` from the API contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when stored as a plain string.
  *  4. `username`
  *  5. `Account 0x12345678…` (derived from publicKey, when present)
  *  6. Translated fallback (e.g. "Unnamed")
@@ -79,6 +69,8 @@ export const getAccountDisplayName = (
 
     const { name, displayName, username, publicKey } = user;
 
+    if (typeof displayName === 'string' && displayName.trim()) return displayName.trim();
+
     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() : '';
@@ -89,8 +81,6 @@ export const getAccountDisplayName = (
         return name.trim();
     }
 
-    if (typeof displayName === 'string' && displayName.trim()) return displayName.trim();
-
     if (typeof username === 'string' && username.trim()) return username.trim();
 
     if (typeof publicKey === 'string' && publicKey.length > 0) {

package/src/utils/asyncUtils.ts

@@ -2,7 +2,6 @@
  * Async utilities for common asynchronous patterns and error handling
  */
 
-import { TTLCache, registerCacheForCleanup } from './cache';
 import { logger } from './loggerUtils';
 
 /**
@@ -278,4 +277,4 @@ export async function retryOnError<T>(
     const errorCode = error?.code || error?.status || error?.message;
     return retryableErrors.includes(errorCode);
   });
-} 
+}

package/src/utils/userHandle.ts

@@ -0,0 +1,49 @@
+export interface UserHandleInput {
+  username?: string | null;
+  handle?: string | null;
+  instance?: string | null;
+  isFederated?: boolean | null;
+  type?: string | null;
+  federation?: {
+    domain?: string | null;
+  } | null;
+}
+
+export type CanonicalUserHandleInput = UserHandleInput;
+
+function normalizeHandlePart(value?: string | null): string | null {
+  const trimmed = value?.trim().replace(/^@+/, '');
+  if (!trimmed || /[/?#]/.test(trimmed)) return null;
+  return trimmed;
+}
+
+/**
+ * Returns the normalized profile handle used by Oxy consumers for display and
+ * profile routing.
+ *
+ * Local users resolve to `username`. Federated users resolve to
+ * `username@instance` when the username does not already include an instance.
+ * Route-like values are rejected so callers do not accidentally turn paths or
+ * query strings into profile destinations.
+ */
+export function getNormalizedUserHandle(user: UserHandleInput | null | undefined): string | null {
+  const username = normalizeHandlePart(user?.username ?? user?.handle);
+  if (!username) return null;
+
+  const isFederated = user?.isFederated === true || user?.type === 'federated';
+  const instance = normalizeHandlePart(user?.instance ?? user?.federation?.domain);
+
+  if (isFederated && instance && !username.includes('@')) {
+    return `${username}@${instance}`;
+  }
+
+  return username;
+}
+
+/**
+ * Compatibility alias for the first public name shipped with this helper.
+ * Prefer {@link getNormalizedUserHandle} in new code.
+ */
+export function getCanonicalUserHandle(user: CanonicalUserHandleInput | null | undefined): string | null {
+  return getNormalizedUserHandle(user);
+}

package/src/utils/userIdentity.ts

@@ -3,17 +3,6 @@ interface UserIdentityInput {
   _id?: unknown;
 }
 
-export interface CanonicalUserHandleInput {
-  username?: string | null;
-  handle?: string | null;
-  instance?: string | null;
-  isFederated?: boolean | null;
-  type?: string | null;
-  federation?: {
-    domain?: string | null;
-  } | null;
-}
-
 function stringifyIdentity(value: unknown): string | null {
   if (typeof value === 'string') {
     const trimmed = value.trim();
@@ -38,12 +27,10 @@ function stringifyIdentity(value: unknown): string | null {
   return null;
 }
 
-function normalizeHandle(value?: string | null): string | null {
-  const trimmed = value?.trim().replace(/^@+/, '');
-  if (!trimmed || /[/?#]/.test(trimmed)) return null;
-  return trimmed;
-}
-
+/**
+ * Returns the stable SDK user id from API payloads that may use either `id` or
+ * Mongo-style `_id`.
+ */
 export function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null {
   if (!user) {
     return null;
@@ -52,6 +39,11 @@ export function getNormalizedUserId(user: UserIdentityInput | null | undefined):
   return stringifyIdentity(user.id) ?? stringifyIdentity(user._id);
 }
 
+/**
+ * Normalizes a user payload to always expose `id`. Throws when the payload does
+ * not contain a usable id, because SDK callers should never receive anonymous
+ * user objects from authenticated identity endpoints.
+ */
 export function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & { id: string } {
   const id = getNormalizedUserId(user);
   if (!id) {
@@ -66,17 +58,3 @@ export function normalizeUserIdentityOrNull<T extends UserIdentityInput>(
 ): (T & { id: string }) | null {
   return user ? normalizeUserIdentity(user) : null;
 }
-
-export function getCanonicalUserHandle(user: CanonicalUserHandleInput | null | undefined): string | null {
-  const username = normalizeHandle(user?.username ?? user?.handle);
-  if (!username) return null;
-
-  const isFederated = user?.isFederated === true || user?.type === 'federated';
-  const instance = normalizeHandle(user?.instance ?? user?.federation?.domain);
-
-  if (isFederated && instance && !username.includes('@')) {
-    return `${username}@${instance}`;
-  }
-
-  return username;
-}