@oxyhq/core 3.4.12 → 3.4.14

package/dist/types/index.d.ts

@@ -34,7 +34,8 @@ 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 { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull } from './utils/userIdentity';
+export { getCanonicalUserHandle, getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
+export type { CanonicalUserHandleInput } from './utils/userIdentity';
 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/server/auth.d.ts

@@ -27,7 +27,7 @@ export interface OxyAuthRequest extends Request {
     user?: OxyRequestUser | null;
     originalUser?: OxyRequestUser | null;
     actingAs?: OxyActingAsContext;
-    accessToken?: string | null;
+    accessToken?: string;
     sessionId?: string | null;
     serviceApp?: OxyServiceAppContext;
     serviceActingAs?: OxyServiceActingAsContext;

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

@@ -2,6 +2,16 @@ 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;
+}
 export declare function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null;
 export declare function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & {
     id: string;
@@ -9,4 +19,5 @@ export declare function normalizeUserIdentity<T extends UserIdentityInput>(user:
 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.12",
+  "version": "3.4.14",
   "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,5 @@
 import { OxyServices } from '../OxyServices';
-import { getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentity';
+import { getCanonicalUserHandle, getNormalizedUserId, normalizeUserIdentity } from '../utils/userIdentity';
 
 interface FetchCall {
   url: string;
@@ -71,3 +71,48 @@ describe('user identity normalization', () => {
     expect(validation.user.username).toBe('nate');
   });
 });
+
+describe('getCanonicalUserHandle', () => {
+  it('normalizes local usernames without route prefixes', () => {
+    expect(getCanonicalUserHandle({ username: ' nate ' })).toBe('nate');
+    expect(getCanonicalUserHandle({ username: '@nate' })).toBe('nate');
+  });
+
+  it('builds federated handles from username and instance', () => {
+    expect(getCanonicalUserHandle({
+      username: 'joannastern',
+      isFederated: true,
+      instance: 'threads.net',
+    })).toBe('joannastern@threads.net');
+  });
+
+  it('does not append an instance twice', () => {
+    expect(getCanonicalUserHandle({
+      username: '@joannastern@threads.net',
+      type: 'federated',
+      instance: 'threads.net',
+    })).toBe('joannastern@threads.net');
+  });
+
+  it('uses federation domain as the federated instance source', () => {
+    expect(getCanonicalUserHandle({
+      username: 'alice',
+      isFederated: true,
+      federation: { domain: '@example.social' },
+    })).toBe('alice@example.social');
+  });
+
+  it('does not use instance for local users', () => {
+    expect(getCanonicalUserHandle({
+      username: 'alice',
+      instance: 'example.social',
+    })).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();
+  });
+});

package/src/index.ts

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

package/src/server/auth.ts

@@ -32,7 +32,7 @@ export interface OxyAuthRequest extends Request {
   user?: OxyRequestUser | null;
   originalUser?: OxyRequestUser | null;
   actingAs?: OxyActingAsContext;
-  accessToken?: string | null;
+  accessToken?: string;
   sessionId?: string | null;
   serviceApp?: OxyServiceAppContext;
   serviceActingAs?: OxyServiceActingAsContext;

package/src/utils/userIdentity.ts

@@ -3,6 +3,17 @@ 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();
@@ -27,6 +38,12 @@ 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;
+}
+
 export function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null {
   if (!user) {
     return null;
@@ -49,3 +66,17 @@ 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;
+}