@oxyhq/core 3.4.14 → 3.4.15

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/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.15",
   "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/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;
-}