@oxyhq/core 9.2.4 → 10.1.0

package/src/mixins/OxyServices.language.ts

@@ -1,12 +1,25 @@
 /**
  * Language Methods Mixin
  */
-import { normalizeLanguageCode, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils';
-import type { LanguageMetadata } from '../utils/languageUtils';
+import { normalizeLocale, getPrimaryLanguage, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils';
+import type { SupportedLanguage } from '../utils/languageUtils';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadAsyncStorage } from '@oxyhq/protocol';
 import { isDev } from '../shared/utils/debugUtils';
 
+/**
+ * Cross-mixin surface consumed by the language methods. `getCurrentUser` is
+ * provided by the user mixin at runtime — both live on the composed
+ * `OxyServices` instance — but it is not visible on `OxyServicesBase` at the
+ * type level. We narrow `this` through this interface (mirroring the
+ * `OxyAuthInstance` pattern in `OxyServices.utility.ts`) instead of casting to
+ * `any`. Only the fields this mixin reads are declared, keeping it decoupled
+ * from the full `User` shape.
+ */
+interface LanguageMixinCrossAccess {
+  getCurrentUser(): Promise<{ languages?: string[] }>;
+}
+
 export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -62,29 +75,30 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * Get the current language from storage or user profile
+     * Get the current locale from the user profile or local storage.
      * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
-     * @returns The current language code (e.g., 'en-US') or null if not set
+     * @returns The current BCP-47 locale (e.g., 'en-US') or null if not set
      */
-    async getCurrentLanguage(storageKeyPrefix: string = 'oxy_session'): Promise<string | null> {
+    async getCurrentLanguage(storageKeyPrefix = 'oxy_session'): Promise<string | null> {
       try {
-        // First try to get from user profile if authenticated
+        // First try the authenticated user's primary account locale.
         try {
-          const user = await (this as any).getCurrentUser();
-          const userLanguage = (user as Record<string, unknown>)?.language as string | undefined;
-          if (userLanguage) {
-            return normalizeLanguageCode(userLanguage) || userLanguage;
+          const user = await (this as unknown as LanguageMixinCrossAccess).getCurrentUser();
+          const primary = getPrimaryLanguage(user);
+          if (primary) {
+            return primary;
           }
-        } catch (e) {
-          // User not authenticated or error, continue to storage
+        } catch {
+          // Not authenticated or the profile fetch failed — fall through to the
+          // locally stored preference below.
         }
 
-        // Fall back to storage
+        // Fall back to the locally stored locale preference.
         const storage = await this.getStorage();
         const storageKey = `${storageKeyPrefix}_language`;
         const storedLanguage = await storage.getItem(storageKey);
         if (storedLanguage) {
-          return normalizeLanguageCode(storedLanguage) || storedLanguage;
+          return normalizeLocale(storedLanguage) ?? storedLanguage;
         }
 
         return null;
@@ -101,7 +115,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
      * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
      * @returns Language metadata object or null if not set
      */
-    async getCurrentLanguageMetadata(storageKeyPrefix: string = 'oxy_session'): Promise<LanguageMetadata | null> {
+    async getCurrentLanguageMetadata(storageKeyPrefix = 'oxy_session'): Promise<SupportedLanguage | null> {
       const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
       return getLanguageMetadata(languageCode);
     }
@@ -111,7 +125,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
      * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
      * @returns Language name or null if not set
      */
-    async getCurrentLanguageName(storageKeyPrefix: string = 'oxy_session'): Promise<string | null> {
+    async getCurrentLanguageName(storageKeyPrefix = 'oxy_session'): Promise<string | null> {
       const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
       if (!languageCode) return null;
       return getLanguageName(languageCode);
@@ -122,7 +136,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
      * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
      * @returns Native language name or null if not set
      */
-    async getCurrentNativeLanguageName(storageKeyPrefix: string = 'oxy_session'): Promise<string | null> {
+    async getCurrentNativeLanguageName(storageKeyPrefix = 'oxy_session'): Promise<string | null> {
       const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
       if (!languageCode) return null;
       return getNativeLanguageName(languageCode);

package/src/mixins/OxyServices.privacy.ts

@@ -82,6 +82,9 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
           cache: false,
         });
         this.clearCacheEntry('GET:/privacy/blocked');
+        // The block changed the viewer's graph (`blockedIds`) — bust the cached
+        // consolidated `GET /users/me/graph` so the next read reflects it.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -105,6 +108,9 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
           cache: false,
         });
         this.clearCacheEntry('GET:/privacy/blocked');
+        // Symmetric to blockUser: the unblock changed the viewer's `blockedIds`,
+        // so bust the consolidated `GET /users/me/graph` cache.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/OxyServices.security.ts

@@ -57,7 +57,7 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
      * @param limit - Number of recent events to fetch (default: 10)
      * @returns Array of recent security activities
      */
-    async getRecentSecurityActivity(limit: number = 10): Promise<SecurityActivity[]> {
+    async getRecentSecurityActivity(limit = 10): Promise<SecurityActivity[]> {
       try {
         const response = await this.getSecurityActivity(limit, 0);
         return response.data || [];

package/src/mixins/OxyServices.user.ts

@@ -49,6 +49,23 @@ export interface BulkFollowResult {
   followedCount: number;
 }
 
+/**
+ * The authenticated viewer's OWN social graph, ids-only — the response of
+ * `GET /users/me/graph`. Consolidates the accounts the viewer follows, the
+ * subset who follow back (mutuals), and the accounts the viewer has blocked
+ * into one payload so a consumer can fetch its whole viewer graph in a single
+ * round trip instead of three. Each list is server-bounded; bare ids only (no
+ * hydrated DTOs) because the consumer hydrates/ranks itself.
+ */
+export interface ViewerGraph {
+  /** Accounts the viewer follows (most-recent first, bounded). */
+  followingIds: string[];
+  /** Accounts the viewer follows that ALSO follow the viewer back (bounded). */
+  mutualIds: string[];
+  /** Accounts the viewer has blocked (bounded). */
+  blockedIds: string[];
+}
+
 /** Per-user outcome returned by `POST /users/unfollow/bulk`. */
 export interface BulkUnfollowEntry {
   /** The user ID that was processed. */
@@ -666,6 +683,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       try {
         const result = await this.makeRequest<{ success: boolean; message: string }>('POST', `/users/${userId}/follow`, undefined, { cache: false });
         this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+        // The follow changed the viewer's graph — bust the cached consolidated
+        // `GET /users/me/graph` so the next read reflects the new following/
+        // mutual set instead of the stale pre-write snapshot.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -690,6 +711,8 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         for (const id of userIds) {
           this.clearCacheEntry(`GET:/users/${id}/follow-status`);
         }
+        // The batch changed the viewer's graph — bust the consolidated cache.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -714,6 +737,8 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         for (const id of userIds) {
           this.clearCacheEntry(`GET:/users/${id}/follow-status`);
         }
+        // The batch changed the viewer's graph — bust the consolidated cache.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -728,6 +753,8 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const result = await this.makeRequest<{ success: boolean; message: string }>('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
         // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
         this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+        // The unfollow changed the viewer's graph — bust the consolidated cache.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -872,6 +899,36 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Get the authenticated VIEWER's OWN social graph — the accounts they follow,
+     * the subset who follow back (mutuals), and the accounts they have blocked —
+     * as ONE ids-only payload. The viewer is derived server-side from the SDK's
+     * auth token (never a param).
+     *
+     * Consolidates what were three separate round trips (`getUserFollowing` /
+     * `getMutualUserIds` / `getBlockedUsers`) into a single request so a consumer
+     * can prime its whole viewer graph at once. Mirrors {@link getMutualUserIds}'s
+     * caching posture (2-minute identity-scoped cache); the follow/unfollow/block/
+     * unblock write methods bust this entry so a local mutation is reflected
+     * immediately. An anonymous caller resolves to empty lists.
+     */
+    async getViewerGraph(): Promise<ViewerGraph> {
+      try {
+        const response = await this.makeRequest<{ data: ViewerGraph }>('GET', '/users/me/graph', undefined, {
+          cache: true,
+          cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+        });
+        const graph = response.data;
+        return {
+          followingIds: graph?.followingIds || [],
+          mutualIds: graph?.mutualIds || [],
+          blockedIds: graph?.blockedIds || [],
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Get notifications
      */

package/src/models/interfaces.ts

@@ -103,6 +103,12 @@ export interface User {
    */
   name: UserNameResponse;
   bio?: string;
+  /**
+   * Longer public profile text. Emitted alongside `bio` by every user DTO the
+   * API produces (single profile, `getUsersByIds`, follower/following/mutual
+   * lists, profile search) — the two are separate fields on the User document.
+   */
+  description?: string;
   phone?: string;
   address?: string;
   birthday?: string;
@@ -144,6 +150,14 @@ export interface User {
   managedBy?: string;
   /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
   organizationCategory?: OrganizationCategory;
+  /**
+   * The account's languages as full BCP-47 locales (`language-REGION`, e.g.
+   * `en-US`, `es-MX`, `pt-BR`), ordered with the PRIMARY (UI) locale first.
+   * `languages[0]` is the primary locale — there is no singular `language`
+   * field. Resolve via `getUserLanguages` / `getPrimaryLanguage`, which
+   * normalize, validate against the supported catalog, and de-duplicate.
+   */
+  languages?: string[];
   // User-controlled notification preferences. All channels default to on; users
   // opt out per-channel. Updated via `PUT /users/me`.
   notificationPreferences?: NotificationPreferences;

package/src/server/safeFetch.ts

@@ -183,7 +183,7 @@ function ipv6ToGroups(ip: string): number[] | null {
     const groups: number[] = [];
     for (const part of segment.split(':')) {
       if (!/^[0-9a-fA-F]{1,4}$/.test(part)) return null;
-      groups.push(parseInt(part, 16));
+      groups.push(Number.parseInt(part, 16));
     }
     return groups;
   };
@@ -234,8 +234,8 @@ function extractEmbeddedIpv4(ip: string): string | null {
   // Hex form "::ffff:0102:0304" → 1.2.3.4
   const hexMapped = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
   if (hexMapped) {
-    const hi = parseInt(hexMapped[1], 16);
-    const lo = parseInt(hexMapped[2], 16);
+    const hi = Number.parseInt(hexMapped[1], 16);
+    const lo = Number.parseInt(hexMapped[2], 16);
     return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
   }
   return null;

package/src/session/SessionClient.ts

@@ -374,7 +374,7 @@ export class SessionClient {
       transports: ['websocket'],
       autoConnect: true,
       reconnection: true,
-      reconnectionAttempts: Infinity,
+      reconnectionAttempts: Number.POSITIVE_INFINITY,
       reconnectionDelay: 1000,
       reconnectionDelayMax: 10000,
       auth: (cb: (data: Record<string, string>) => void) => {

package/src/session/accountDialogController.ts

@@ -37,7 +37,7 @@ import {
   normalizeOAuthRedirectUri,
   persistOAuthHandshake,
 } from '../utils/oauthPkce';
-import { SessionClient } from './SessionClient';
+import type { SessionClient } from './SessionClient';
 import {
   projectSwitchableAccounts,
   switchableAccountIds,

package/src/shared/utils/colorUtils.ts

@@ -20,12 +20,12 @@
  * darkenColor('FF0000', 0.3);  // Also works without #
  * ```
  */
-export const darkenColor = (color: string, factor: number = 0.6): string => {
+export const darkenColor = (color: string, factor = 0.6): string => {
   const hex = color.replace('#', '');
 
-  const r = parseInt(hex.substring(0, 2), 16);
-  const g = parseInt(hex.substring(2, 4), 16);
-  const b = parseInt(hex.substring(4, 6), 16);
+  const r = Number.parseInt(hex.substring(0, 2), 16);
+  const g = Number.parseInt(hex.substring(2, 4), 16);
+  const b = Number.parseInt(hex.substring(4, 6), 16);
 
   const newR = Math.max(0, Math.round(r * (1 - factor)));
   const newG = Math.max(0, Math.round(g * (1 - factor)));
@@ -46,12 +46,12 @@ export const darkenColor = (color: string, factor: number = 0.6): string => {
  * lightenColor('#0000FF', 0.5); // Returns a lighter blue
  * ```
  */
-export const lightenColor = (color: string, factor: number = 0.3): string => {
+export const lightenColor = (color: string, factor = 0.3): string => {
   const hex = color.replace('#', '');
 
-  const r = parseInt(hex.substring(0, 2), 16);
-  const g = parseInt(hex.substring(2, 4), 16);
-  const b = parseInt(hex.substring(4, 6), 16);
+  const r = Number.parseInt(hex.substring(0, 2), 16);
+  const g = Number.parseInt(hex.substring(2, 4), 16);
+  const b = Number.parseInt(hex.substring(4, 6), 16);
 
   const newR = Math.min(255, Math.round(r + (255 - r) * factor));
   const newG = Math.min(255, Math.round(g + (255 - g) * factor));
@@ -75,9 +75,9 @@ export const hexToRgb = (hex: string): { r: number; g: number; b: number } | nul
   const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
   return result
     ? {
-        r: parseInt(result[1], 16),
-        g: parseInt(result[2], 16),
-        b: parseInt(result[3], 16),
+        r: Number.parseInt(result[1], 16),
+        g: Number.parseInt(result[2], 16),
+        b: Number.parseInt(result[3], 16),
       }
     : null;
 };

package/src/shared/utils/errorUtils.ts

@@ -57,7 +57,7 @@ export const getErrorStatus = (error: unknown): number | undefined => {
  * @param fallback - Fallback message if none found
  * @returns The error message
  */
-export const getErrorMessage = (error: unknown, fallback: string = 'An unknown error occurred'): string => {
+export const getErrorMessage = (error: unknown, fallback = 'An unknown error occurred'): string => {
   if (!error) return fallback;
 
   if (typeof error === 'string') return error;

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

@@ -0,0 +1,219 @@
+import {
+  SUPPORTED_LANGUAGES,
+  getBaseLanguage,
+  normalizeLocale,
+  isSupportedLocale,
+  getLanguageMetadata,
+  getLanguageName,
+  getNativeLanguageName,
+  isRTLLocale,
+  getUserLanguages,
+  getPrimaryLanguage,
+} from '../languageUtils';
+
+describe('getBaseLanguage', () => {
+  it('extracts the base subtag from a full locale, lowercased', () => {
+    expect(getBaseLanguage('es-ES')).toBe('es');
+    expect(getBaseLanguage('EN-us')).toBe('en');
+  });
+
+  it('is tolerant of a bare base subtag', () => {
+    expect(getBaseLanguage('es')).toBe('es');
+    expect(getBaseLanguage('ES')).toBe('es');
+  });
+
+  it('ignores script/variant subtags', () => {
+    expect(getBaseLanguage('zh-Hant-TW')).toBe('zh');
+  });
+
+  it('trims surrounding whitespace and handles empty input', () => {
+    expect(getBaseLanguage('  fr-FR ')).toBe('fr');
+    expect(getBaseLanguage('')).toBe('');
+  });
+});
+
+describe('normalizeLocale', () => {
+  it('canonicalizes case: lowercase base, uppercase region', () => {
+    expect(normalizeLocale('es-es')).toBe('es-ES');
+    expect(normalizeLocale('EN-us')).toBe('en-US');
+    expect(normalizeLocale('PT-br')).toBe('pt-BR');
+  });
+
+  it('returns already-canonical supported locales unchanged', () => {
+    expect(normalizeLocale('es-MX')).toBe('es-MX');
+    expect(normalizeLocale('zh-TW')).toBe('zh-TW');
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(normalizeLocale('  fr-CA  ')).toBe('fr-CA');
+  });
+
+  it('collapses extra subtags to language-REGION', () => {
+    expect(normalizeLocale('zh-Hant-TW')).toBe('zh-TW');
+  });
+
+  it('returns undefined for a bare base subtag (no region)', () => {
+    expect(normalizeLocale('es')).toBeUndefined();
+    expect(normalizeLocale('en')).toBeUndefined();
+  });
+
+  it('returns undefined for unsupported locales', () => {
+    expect(normalizeLocale('xx-ZZ')).toBeUndefined();
+    expect(normalizeLocale('es-ZZ')).toBeUndefined();
+  });
+
+  it('returns undefined for empty or whitespace input', () => {
+    expect(normalizeLocale('')).toBeUndefined();
+    expect(normalizeLocale('   ')).toBeUndefined();
+  });
+});
+
+describe('isSupportedLocale', () => {
+  it('is true for supported locales in any case', () => {
+    expect(isSupportedLocale('es-ES')).toBe(true);
+    expect(isSupportedLocale('es-es')).toBe(true);
+  });
+
+  it('is false for bare subtags and unknown locales', () => {
+    expect(isSupportedLocale('es')).toBe(false);
+    expect(isSupportedLocale('xx-ZZ')).toBe(false);
+    expect(isSupportedLocale('')).toBe(false);
+  });
+});
+
+describe('getLanguageMetadata', () => {
+  it('resolves a supported locale to its catalog entry', () => {
+    const entry = getLanguageMetadata('es-mx');
+    expect(entry).not.toBeNull();
+    expect(entry?.code).toBe('es-MX');
+    expect(entry?.language).toBe('es');
+    expect(entry?.region).toBe('MX');
+  });
+
+  it('returns null for bare, unknown, or empty codes', () => {
+    expect(getLanguageMetadata('es')).toBeNull();
+    expect(getLanguageMetadata('xx-ZZ')).toBeNull();
+    expect(getLanguageMetadata('')).toBeNull();
+    expect(getLanguageMetadata(null)).toBeNull();
+    expect(getLanguageMetadata(undefined)).toBeNull();
+  });
+});
+
+describe('getLanguageName / getNativeLanguageName', () => {
+  it('returns the English and native display names for a supported locale', () => {
+    expect(getLanguageName('es-ES')).toBe('Spanish (Spain)');
+    expect(getNativeLanguageName('es-ES')).toBe('Español (España)');
+  });
+
+  it('falls back to the input tag for unsupported locales', () => {
+    expect(getLanguageName('xx-ZZ')).toBe('xx-ZZ');
+    expect(getNativeLanguageName('xx-ZZ')).toBe('xx-ZZ');
+  });
+
+  it('falls back to the fallback locale for empty input', () => {
+    expect(getLanguageName('')).toBe('en-US');
+    expect(getNativeLanguageName(null)).toBe('en-US');
+  });
+});
+
+describe('isRTLLocale', () => {
+  it('is true for right-to-left locales and their base subtags', () => {
+    expect(isRTLLocale('ar-SA')).toBe(true);
+    expect(isRTLLocale('he-IL')).toBe(true);
+    expect(isRTLLocale('fa')).toBe(true);
+    expect(isRTLLocale('ur-PK')).toBe(true);
+  });
+
+  it('is false for left-to-right locales and empty input', () => {
+    expect(isRTLLocale('en-US')).toBe(false);
+    expect(isRTLLocale('es-ES')).toBe(false);
+    expect(isRTLLocale(null)).toBe(false);
+    expect(isRTLLocale(undefined)).toBe(false);
+  });
+});
+
+describe('getUserLanguages', () => {
+  it('normalizes and validates the plural array, preserving order', () => {
+    expect(getUserLanguages({ languages: ['es-es', 'EN-us', 'pt-BR'] })).toEqual([
+      'es-ES',
+      'en-US',
+      'pt-BR',
+    ]);
+  });
+
+  it('drops unsupported locales and bare subtags', () => {
+    expect(getUserLanguages({ languages: ['es-ES', 'xx-ZZ', 'en'] })).toEqual(['es-ES']);
+  });
+
+  it('de-duplicates after normalization, keeping first-seen order', () => {
+    expect(getUserLanguages({ languages: ['es-ES', 'es-es', 'en-US', 'ES-es'] })).toEqual([
+      'es-ES',
+      'en-US',
+    ]);
+  });
+
+  it('ignores non-string junk entries without throwing', () => {
+    const languages = ['es-ES', 42, null, undefined, {}, 'en-US'] as unknown as string[];
+    expect(getUserLanguages({ languages })).toEqual(['es-ES', 'en-US']);
+  });
+
+  it('returns an empty array when languages is absent, empty, or non-array', () => {
+    expect(getUserLanguages({})).toEqual([]);
+    expect(getUserLanguages({ languages: [] })).toEqual([]);
+    expect(getUserLanguages({ languages: undefined })).toEqual([]);
+    expect(getUserLanguages(null)).toEqual([]);
+    expect(getUserLanguages(undefined)).toEqual([]);
+  });
+
+  it('ignores any stray singular language field (removed from User)', () => {
+    const strayLanguage: { language: string; languages?: string[] } = { language: 'es-ES' };
+    expect(getUserLanguages(strayLanguage)).toEqual([]);
+  });
+});
+
+describe('getPrimaryLanguage', () => {
+  it('returns the first normalized locale from the plural array', () => {
+    expect(getPrimaryLanguage({ languages: ['es-es', 'en-US'] })).toBe('es-ES');
+  });
+
+  it('skips leading unsupported entries', () => {
+    expect(getPrimaryLanguage({ languages: ['xx-ZZ', 'pt-br'] })).toBe('pt-BR');
+  });
+
+  it('returns undefined when the user has no supported locale', () => {
+    expect(getPrimaryLanguage({})).toBeUndefined();
+    expect(getPrimaryLanguage({ languages: ['xx-ZZ'] })).toBeUndefined();
+    expect(getPrimaryLanguage(null)).toBeUndefined();
+  });
+});
+
+describe('SUPPORTED_LANGUAGES catalog integrity', () => {
+  it('is non-empty', () => {
+    expect(SUPPORTED_LANGUAGES.length).toBeGreaterThan(0);
+  });
+
+  it('has no duplicate codes', () => {
+    const codes = SUPPORTED_LANGUAGES.map((entry) => entry.code);
+    expect(new Set(codes).size).toBe(codes.length);
+  });
+
+  it('every entry is internally consistent', () => {
+    for (const entry of SUPPORTED_LANGUAGES) {
+      // code is canonical language-REGION derived from its subtags
+      expect(entry.code).toBe(`${entry.language}-${entry.region}`);
+      // base subtag is lowercase, region is uppercase
+      expect(entry.language).toBe(entry.language.toLowerCase());
+      expect(entry.region).toBe(entry.region.toUpperCase());
+      // parsing the code recovers the subtags
+      expect(getBaseLanguage(entry.code)).toBe(entry.language);
+      // the code round-trips through normalization
+      expect(normalizeLocale(entry.code)).toBe(entry.code);
+      expect(isSupportedLocale(entry.code)).toBe(true);
+      // display names are present
+      expect(entry.name.length).toBeGreaterThan(0);
+      expect(entry.nativeName.length).toBeGreaterThan(0);
+      // rtl flag agrees with the RTL detector
+      expect(isRTLLocale(entry.code)).toBe(entry.rtl === true);
+    }
+  });
+});