@oxyhq/core 9.2.4 → 10.1.0

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

@@ -0,0 +1,196 @@
+import { normalizeInlineText, normalizeMultilineText } from '../textNormalization';
+
+/**
+ * Whitespace characters are built from their code points rather than pasted as
+ * literals: an NBSP or a U+2028 in the source would be invisible to a reviewer
+ * and trivially "fixed" by an editor, silently gutting the test it anchors.
+ */
+const NBSP = String.fromCharCode(0x00a0); // no-break space
+const EN_QUAD = String.fromCharCode(0x2000); // U+2000 space block
+const IDEOGRAPHIC_SPACE = String.fromCharCode(0x3000); // CJK full-width space
+const NARROW_NBSP = String.fromCharCode(0x202f);
+const ZWNBSP = String.fromCharCode(0xfeff); // BOM when leading
+const LINE_SEPARATOR = String.fromCharCode(0x2028);
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);
+
+/** "é" as a base letter plus a combining acute accent (NFD form). */
+const DECOMPOSED_E_ACUTE = `e${String.fromCharCode(0x0301)}`;
+/** The precomposed "é" (NFC form) the two above must normalize into. */
+const COMPOSED_E_ACUTE = String.fromCharCode(0x00e9);
+
+describe('normalizeInlineText', () => {
+  it('flattens the indented multi-line <title> that caused the original bug', () => {
+    expect(normalizeInlineText('\n      Mi título\n    ')).toBe('Mi título');
+  });
+
+  it('collapses every whitespace form to a single space', () => {
+    expect(normalizeInlineText('a\tb\nc\r\nd  e')).toBe('a b c d e');
+  });
+
+  it('collapses Unicode spaces (NBSP, U+2000 block, ideographic, narrow NBSP)', () => {
+    expect(
+      normalizeInlineText(`a${NBSP}b${EN_QUAD}c${IDEOGRAPHIC_SPACE}d${NARROW_NBSP}e`)
+    ).toBe('a b c d e');
+  });
+
+  it('collapses the Unicode line and paragraph separators', () => {
+    expect(normalizeInlineText(`a${LINE_SEPARATOR}b${PARAGRAPH_SEPARATOR}c`)).toBe('a b c');
+  });
+
+  it('strips a leading BOM / zero-width no-break space', () => {
+    expect(normalizeInlineText(`${ZWNBSP}Título`)).toBe('Título');
+  });
+
+  it('handles CRLF line endings', () => {
+    expect(normalizeInlineText('News\r\n\r\nToday')).toBe('News Today');
+  });
+
+  it('returns an empty string for empty and whitespace-only input', () => {
+    expect(normalizeInlineText('')).toBe('');
+    expect(normalizeInlineText('   ')).toBe('');
+    expect(normalizeInlineText(`\n\t ${NBSP}\r\n`)).toBe('');
+  });
+
+  it('NFC-normalizes so decomposed accents are stored composed', () => {
+    const normalized = normalizeInlineText(`Ren${DECOMPOSED_E_ACUTE}e`);
+    expect(normalized).toBe(`Ren${COMPOSED_E_ACUTE}e`);
+    expect(normalized).toHaveLength(5);
+  });
+
+  it('leaves already-clean text untouched', () => {
+    expect(normalizeInlineText('Hacker News')).toBe('Hacker News');
+    expect(normalizeInlineText('Título en español — con guion')).toBe(
+      'Título en español — con guion'
+    );
+  });
+
+  it('does not truncate long values (length caps are a product rule)', () => {
+    const long = 'a'.repeat(500);
+    expect(normalizeInlineText(long)).toHaveLength(500);
+  });
+
+  it('does not strip markup or punctuation (that is the sanitizer\'s job)', () => {
+    expect(normalizeInlineText('  <b>Bold</b> & "quoted"  ')).toBe('<b>Bold</b> & "quoted"');
+  });
+
+  it('is idempotent', () => {
+    const inputs = [
+      '\n      Mi título\n    ',
+      `a${NBSP}${NBSP}b`,
+      'Hacker News',
+      '',
+      '   ',
+      `Ren${DECOMPOSED_E_ACUTE}e`,
+    ];
+    for (const input of inputs) {
+      const once = normalizeInlineText(input);
+      expect(normalizeInlineText(once)).toBe(once);
+    }
+  });
+});
+
+describe('normalizeMultilineText', () => {
+  it('preserves the author\'s paragraphs', () => {
+    const body = 'First paragraph.\n\nSecond paragraph.\nSame paragraph, next line.';
+    expect(normalizeMultilineText(body)).toBe(body);
+  });
+
+  it('collapses a blank line that contains spaces — the ordering bug', () => {
+    // The "blank" lines hold spaces, so they break the run of \n characters: a
+    // bare /\n{3,}/ collapse never sees them. Trailing horizontal whitespace
+    // must be stripped FIRST.
+    expect(normalizeMultilineText('a\n    \n    \nb')).toBe('a\n\nb');
+  });
+
+  it('collapses a blank line that contains tabs and NBSP', () => {
+    expect(normalizeMultilineText(`a\n\t\n${NBSP}${NBSP}\nb`)).toBe('a\n\nb');
+  });
+
+  it('strips trailing horizontal whitespace from every line', () => {
+    expect(normalizeMultilineText('one   \ntwo\t\nthree ')).toBe('one\ntwo\nthree');
+  });
+
+  it('collapses three or more newlines to a single blank line', () => {
+    expect(normalizeMultilineText('a\n\n\n\n\nb')).toBe('a\n\nb');
+  });
+
+  it('keeps exactly one blank line as-is', () => {
+    expect(normalizeMultilineText('a\n\nb')).toBe('a\n\nb');
+  });
+
+  it('collapses runs of horizontal whitespace to one space, keeping newlines', () => {
+    expect(normalizeMultilineText('hello    world\nsecond\t\tline')).toBe(
+      'hello world\nsecond line'
+    );
+  });
+
+  it('preserves a single-space indent (it is the author\'s, not markup noise)', () => {
+    expect(normalizeMultilineText('a\n b')).toBe('a\n b');
+  });
+
+  it('normalizes CRLF and lone CR to \\n', () => {
+    expect(normalizeMultilineText('a\r\nb\rc')).toBe('a\nb\nc');
+    expect(normalizeMultilineText('a\r\n\r\n\r\n\r\nb')).toBe('a\n\nb');
+  });
+
+  it('normalizes the Unicode line and paragraph separators to \\n', () => {
+    expect(normalizeMultilineText(`a${LINE_SEPARATOR}b${PARAGRAPH_SEPARATOR}c`)).toBe('a\nb\nc');
+  });
+
+  it('collapses Unicode spaces without touching line structure', () => {
+    expect(normalizeMultilineText(`a${NBSP}${NBSP}b\nc${IDEOGRAPHIC_SPACE}d`)).toBe('a b\nc d');
+  });
+
+  it('trims both ends, including leading and trailing blank lines', () => {
+    expect(normalizeMultilineText('\n\n  Hello\n\nWorld  \n\n  ')).toBe('Hello\n\nWorld');
+  });
+
+  it('returns an empty string for empty and whitespace-only input', () => {
+    expect(normalizeMultilineText('')).toBe('');
+    expect(normalizeMultilineText('   ')).toBe('');
+    expect(normalizeMultilineText(`\n\n \t${NBSP}\r\n  \n`)).toBe('');
+  });
+
+  it('NFC-normalizes so decomposed accents are stored composed', () => {
+    expect(normalizeMultilineText(`Caf${DECOMPOSED_E_ACUTE}\n\nabierto`)).toBe(
+      `Caf${COMPOSED_E_ACUTE}\n\nabierto`
+    );
+  });
+
+  it('leaves an already-clean body untouched', () => {
+    const body = 'Line one\nLine two\n\nNew paragraph.';
+    expect(normalizeMultilineText(body)).toBe(body);
+  });
+
+  it('cleans a realistic federated post body without losing its paragraphs', () => {
+    const federated = '  Hola a todos.\r\n   \r\n\r\nEsto  es  una   prueba.\t\r\nFin.   ';
+    expect(normalizeMultilineText(federated)).toBe(
+      'Hola a todos.\n\nEsto es una prueba.\nFin.'
+    );
+  });
+
+  it('is idempotent', () => {
+    const inputs = [
+      'a\n    \n    \nb',
+      'a\r\n\r\n\r\nb',
+      'First paragraph.\n\nSecond paragraph.',
+      `a${NBSP}b`,
+      'a\n b',
+      '',
+      '   ',
+      `Caf${DECOMPOSED_E_ACUTE}`,
+    ];
+    for (const input of inputs) {
+      const once = normalizeMultilineText(input);
+      expect(normalizeMultilineText(once)).toBe(once);
+    }
+  });
+});
+
+describe('choosing between the two helpers', () => {
+  it('inline flattens what multiline preserves', () => {
+    const body = 'Title\n\nSubtitle';
+    expect(normalizeInlineText(body)).toBe('Title Subtitle');
+    expect(normalizeMultilineText(body)).toBe('Title\n\nSubtitle');
+  });
+});

package/src/utils/avatarUtils.ts

@@ -17,7 +17,7 @@ export interface AssetVisibilityService {
 export async function updateAvatarVisibility(
   fileId: string | undefined,
   oxyServices: AssetVisibilityService,
-  contextName: string = 'AvatarUtils'
+  contextName = 'AvatarUtils'
 ): Promise<void> {
   if (!fileId || fileId.startsWith('temp-')) {
     return;

package/src/utils/languageUtils.ts

@@ -1,195 +1,256 @@
 /**
- * Language utilities for OxyServices
- * Provides access to supported languages and language metadata
+ * Locale utilities for OxyServices.
+ *
+ * The Oxy platform models account languages as full BCP-47 locales
+ * (`language-REGION`, e.g. `es-ES`, `es-MX`, `pt-BR`). Region is significant:
+ * "Spanish (Spain)" is a different locale than "Spanish (Mexico)". A user's
+ * account locales live on `User.languages` as an ordered list with the PRIMARY
+ * (UI) locale first — there is no singular `language` field.
+ *
+ * This module is the single source of truth for the supported-locale catalog
+ * and every locale operation the SDK exposes: parsing base subtags, canonical
+ * normalization, validation, metadata lookup, and resolving a user's locales.
+ * It is pure and side-effect free.
  */
 
-export interface LanguageMetadata {
-  id: string;
+import type { User } from '../models/interfaces';
+
+/**
+ * A supported BCP-47 locale in the Oxy catalog.
+ */
+export interface SupportedLanguage {
+  /** Canonical BCP-47 locale tag, `language-REGION` (e.g. `'es-ES'`). */
+  code: string;
+  /** ISO 639-1 base language subtag, lowercased (e.g. `'es'`). */
+  language: string;
+  /** ISO 3166-1 alpha-2 region subtag, uppercased (e.g. `'ES'`). */
+  region: string;
+  /** English display name, `'Language (Region)'` (e.g. `'Spanish (Spain)'`). */
   name: string;
+  /** Endonym — the name as written in the locale itself (e.g. `'Español (España)'`). */
   nativeName: string;
-  flag: string;
-  icon: string;
-  color: string;
+  /** `true` when the locale is written right-to-left. Omitted for LTR locales. */
+  rtl?: boolean;
 }
 
-// Supported languages with their metadata
-export const SUPPORTED_LANGUAGES: LanguageMetadata[] = [
-  {
-    id: 'en-US',
-    name: 'English',
-    nativeName: 'English',
-    flag: '🇺🇸',
-    icon: 'translate',
-    color: '#007AFF',
-  },
-  {
-    id: 'es-ES',
-    name: 'Spanish',
-    nativeName: 'Español',
-    flag: '🇪🇸',
-    icon: 'translate',
-    color: '#FF3B30',
-  },
-  {
-    id: 'ca-ES',
-    name: 'Catalan',
-    nativeName: 'Català',
-    flag: '🇪🇸',
-    icon: 'translate',
-    color: '#0CA678',
-  },
-  {
-    id: 'fr-FR',
-    name: 'French',
-    nativeName: 'Français',
-    flag: '🇫🇷',
-    icon: 'translate',
-    color: '#5856D6',
-  },
-  {
-    id: 'de-DE',
-    name: 'German',
-    nativeName: 'Deutsch',
-    flag: '🇩🇪',
-    icon: 'translate',
-    color: '#FF9500',
-  },
-  {
-    id: 'it-IT',
-    name: 'Italian',
-    nativeName: 'Italiano',
-    flag: '🇮🇹',
-    icon: 'translate',
-    color: '#34C759',
-  },
-  {
-    id: 'pt-PT',
-    name: 'Portuguese',
-    nativeName: 'Português',
-    flag: '🇵🇹',
-    icon: 'translate',
-    color: '#AF52DE',
-  },
-  {
-    id: 'ja-JP',
-    name: 'Japanese',
-    nativeName: '日本語',
-    flag: '🇯🇵',
-    icon: 'translate',
-    color: '#FF2D92',
-  },
-  {
-    id: 'ko-KR',
-    name: 'Korean',
-    nativeName: '한국어',
-    flag: '🇰🇷',
-    icon: 'translate',
-    color: '#32D74B',
-  },
-  {
-    id: 'zh-CN',
-    name: 'Chinese',
-    nativeName: '中文',
-    flag: '🇨🇳',
-    icon: 'translate',
-    color: '#FF9F0A',
-  },
-  {
-    id: 'ar-SA',
-    name: 'Arabic',
-    nativeName: 'العربية',
-    flag: '🇸🇦',
-    icon: 'translate',
-    color: '#30B0C7',
-  },
+/**
+ * The supported-locale catalog. Ordered by prominence for display; the order
+ * is not otherwise significant. Every entry is a full `language-REGION` tag,
+ * with the base subtag lowercased and the region uppercased.
+ */
+export const SUPPORTED_LANGUAGES: readonly SupportedLanguage[] = [
+  // English
+  { code: 'en-US', language: 'en', region: 'US', name: 'English (United States)', nativeName: 'English (United States)' },
+  { code: 'en-GB', language: 'en', region: 'GB', name: 'English (United Kingdom)', nativeName: 'English (United Kingdom)' },
+  { code: 'en-AU', language: 'en', region: 'AU', name: 'English (Australia)', nativeName: 'English (Australia)' },
+  { code: 'en-CA', language: 'en', region: 'CA', name: 'English (Canada)', nativeName: 'English (Canada)' },
+  { code: 'en-IN', language: 'en', region: 'IN', name: 'English (India)', nativeName: 'English (India)' },
+
+  // Spanish
+  { code: 'es-ES', language: 'es', region: 'ES', name: 'Spanish (Spain)', nativeName: 'Español (España)' },
+  { code: 'es-MX', language: 'es', region: 'MX', name: 'Spanish (Mexico)', nativeName: 'Español (México)' },
+  { code: 'es-US', language: 'es', region: 'US', name: 'Spanish (United States)', nativeName: 'Español (Estados Unidos)' },
+  { code: 'es-AR', language: 'es', region: 'AR', name: 'Spanish (Argentina)', nativeName: 'Español (Argentina)' },
+  { code: 'es-CO', language: 'es', region: 'CO', name: 'Spanish (Colombia)', nativeName: 'Español (Colombia)' },
+
+  // Portuguese
+  { code: 'pt-BR', language: 'pt', region: 'BR', name: 'Portuguese (Brazil)', nativeName: 'Português (Brasil)' },
+  { code: 'pt-PT', language: 'pt', region: 'PT', name: 'Portuguese (Portugal)', nativeName: 'Português (Portugal)' },
+
+  // French
+  { code: 'fr-FR', language: 'fr', region: 'FR', name: 'French (France)', nativeName: 'Français (France)' },
+  { code: 'fr-CA', language: 'fr', region: 'CA', name: 'French (Canada)', nativeName: 'Français (Canada)' },
+
+  // German
+  { code: 'de-DE', language: 'de', region: 'DE', name: 'German (Germany)', nativeName: 'Deutsch (Deutschland)' },
+  { code: 'de-AT', language: 'de', region: 'AT', name: 'German (Austria)', nativeName: 'Deutsch (Österreich)' },
+  { code: 'de-CH', language: 'de', region: 'CH', name: 'German (Switzerland)', nativeName: 'Deutsch (Schweiz)' },
+
+  // Italian
+  { code: 'it-IT', language: 'it', region: 'IT', name: 'Italian (Italy)', nativeName: 'Italiano (Italia)' },
+
+  // Dutch
+  { code: 'nl-NL', language: 'nl', region: 'NL', name: 'Dutch (Netherlands)', nativeName: 'Nederlands (Nederland)' },
+  { code: 'nl-BE', language: 'nl', region: 'BE', name: 'Dutch (Belgium)', nativeName: 'Nederlands (België)' },
+
+  // Nordic
+  { code: 'sv-SE', language: 'sv', region: 'SE', name: 'Swedish (Sweden)', nativeName: 'Svenska (Sverige)' },
+  { code: 'nb-NO', language: 'nb', region: 'NO', name: 'Norwegian Bokmål (Norway)', nativeName: 'Norsk bokmål (Norge)' },
+  { code: 'da-DK', language: 'da', region: 'DK', name: 'Danish (Denmark)', nativeName: 'Dansk (Danmark)' },
+  { code: 'fi-FI', language: 'fi', region: 'FI', name: 'Finnish (Finland)', nativeName: 'Suomi (Suomi)' },
+
+  // Central & Eastern Europe
+  { code: 'pl-PL', language: 'pl', region: 'PL', name: 'Polish (Poland)', nativeName: 'Polski (Polska)' },
+  { code: 'cs-CZ', language: 'cs', region: 'CZ', name: 'Czech (Czechia)', nativeName: 'Čeština (Česko)' },
+  { code: 'sk-SK', language: 'sk', region: 'SK', name: 'Slovak (Slovakia)', nativeName: 'Slovenčina (Slovensko)' },
+  { code: 'hu-HU', language: 'hu', region: 'HU', name: 'Hungarian (Hungary)', nativeName: 'Magyar (Magyarország)' },
+  { code: 'ro-RO', language: 'ro', region: 'RO', name: 'Romanian (Romania)', nativeName: 'Română (România)' },
+  { code: 'bg-BG', language: 'bg', region: 'BG', name: 'Bulgarian (Bulgaria)', nativeName: 'Български (България)' },
+  { code: 'hr-HR', language: 'hr', region: 'HR', name: 'Croatian (Croatia)', nativeName: 'Hrvatski (Hrvatska)' },
+  { code: 'sr-RS', language: 'sr', region: 'RS', name: 'Serbian (Serbia)', nativeName: 'Српски (Србија)' },
+  { code: 'sl-SI', language: 'sl', region: 'SI', name: 'Slovenian (Slovenia)', nativeName: 'Slovenščina (Slovenija)' },
+  { code: 'lt-LT', language: 'lt', region: 'LT', name: 'Lithuanian (Lithuania)', nativeName: 'Lietuvių (Lietuva)' },
+  { code: 'lv-LV', language: 'lv', region: 'LV', name: 'Latvian (Latvia)', nativeName: 'Latviešu (Latvija)' },
+  { code: 'et-EE', language: 'et', region: 'EE', name: 'Estonian (Estonia)', nativeName: 'Eesti (Eesti)' },
+  { code: 'uk-UA', language: 'uk', region: 'UA', name: 'Ukrainian (Ukraine)', nativeName: 'Українська (Україна)' },
+  { code: 'ru-RU', language: 'ru', region: 'RU', name: 'Russian (Russia)', nativeName: 'Русский (Россия)' },
+  { code: 'el-GR', language: 'el', region: 'GR', name: 'Greek (Greece)', nativeName: 'Ελληνικά (Ελλάδα)' },
+
+  // Turkish
+  { code: 'tr-TR', language: 'tr', region: 'TR', name: 'Turkish (Türkiye)', nativeName: 'Türkçe (Türkiye)' },
+
+  // Catalan
+  { code: 'ca-ES', language: 'ca', region: 'ES', name: 'Catalan (Spain)', nativeName: 'Català (Espanya)' },
+
+  // East, South & Southeast Asia
+  { code: 'ja-JP', language: 'ja', region: 'JP', name: 'Japanese (Japan)', nativeName: '日本語 (日本)' },
+  { code: 'ko-KR', language: 'ko', region: 'KR', name: 'Korean (South Korea)', nativeName: '한국어 (대한민국)' },
+  { code: 'zh-CN', language: 'zh', region: 'CN', name: 'Chinese (Simplified, China)', nativeName: '中文 (中国)' },
+  { code: 'zh-TW', language: 'zh', region: 'TW', name: 'Chinese (Traditional, Taiwan)', nativeName: '中文 (台灣)' },
+  { code: 'zh-HK', language: 'zh', region: 'HK', name: 'Chinese (Traditional, Hong Kong)', nativeName: '中文 (香港)' },
+  { code: 'hi-IN', language: 'hi', region: 'IN', name: 'Hindi (India)', nativeName: 'हिन्दी (भारत)' },
+  { code: 'bn-BD', language: 'bn', region: 'BD', name: 'Bengali (Bangladesh)', nativeName: 'বাংলা (বাংলাদেশ)' },
+  { code: 'id-ID', language: 'id', region: 'ID', name: 'Indonesian (Indonesia)', nativeName: 'Bahasa Indonesia (Indonesia)' },
+  { code: 'ms-MY', language: 'ms', region: 'MY', name: 'Malay (Malaysia)', nativeName: 'Bahasa Melayu (Malaysia)' },
+  { code: 'th-TH', language: 'th', region: 'TH', name: 'Thai (Thailand)', nativeName: 'ไทย (ประเทศไทย)' },
+  { code: 'vi-VN', language: 'vi', region: 'VN', name: 'Vietnamese (Vietnam)', nativeName: 'Tiếng Việt (Việt Nam)' },
+
+  // Right-to-left
+  { code: 'ar-SA', language: 'ar', region: 'SA', name: 'Arabic (Saudi Arabia)', nativeName: 'العربية (السعودية)', rtl: true },
+  { code: 'ar-EG', language: 'ar', region: 'EG', name: 'Arabic (Egypt)', nativeName: 'العربية (مصر)', rtl: true },
+  { code: 'he-IL', language: 'he', region: 'IL', name: 'Hebrew (Israel)', nativeName: 'עברית (ישראל)', rtl: true },
+  { code: 'fa-IR', language: 'fa', region: 'IR', name: 'Persian (Iran)', nativeName: 'فارسی (ایران)', rtl: true },
+  { code: 'ur-PK', language: 'ur', region: 'PK', name: 'Urdu (Pakistan)', nativeName: 'اردو (پاکستان)', rtl: true },
 ];
 
-const FALLBACK_LANGUAGE = 'en-US';
+/** Canonical fallback locale used when a display value cannot be resolved. */
+export const FALLBACK_LOCALE = 'en-US';
+
+/** O(1) lookup of a catalog entry by its canonical code. */
+const LOCALE_BY_CODE: ReadonlyMap<string, SupportedLanguage> = new Map(
+  SUPPORTED_LANGUAGES.map((entry) => [entry.code, entry]),
+);
 
 /**
- * Get language metadata by language code
- * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
- * @returns Language metadata or null if not found
+ * Extract the base language subtag from a locale, lowercased.
+ *
+ * Tolerant of bare base subtags and of extra subtags (script/variant):
+ * `'es-ES'` → `'es'`, `'es'` → `'es'`, `'zh-Hant-TW'` → `'zh'`. Returns an
+ * empty string for empty input.
  */
-export function getLanguageMetadata(languageCode: string | null | undefined): LanguageMetadata | null {
-  if (!languageCode) return null;
-  
-  // Direct match
-  const exactMatch = SUPPORTED_LANGUAGES.find(lang => lang.id === languageCode);
-  if (exactMatch) return exactMatch;
-  
-  // Try to match base language code (e.g., 'en' matches 'en-US')
-  const baseCode = languageCode.split('-')[0];
-  const baseMatch = SUPPORTED_LANGUAGES.find(lang => lang.id.startsWith(baseCode + '-'));
-  if (baseMatch) return baseMatch;
-  
-  return null;
+export function getBaseLanguage(locale: string): string {
+  return locale.trim().toLowerCase().split('-')[0] ?? '';
 }
 
 /**
- * Get language name by language code
- * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
- * @returns Language name (e.g., 'English') or the code if not found
+ * Normalize a locale string to its canonical `language-REGION` form when it is
+ * a supported locale, otherwise `undefined`.
+ *
+ * Canonicalization lowercases the base subtag and uppercases the region
+ * subtag (`'es-es'` → `'es-ES'`, `'EN-us'` → `'en-US'`) and validates the
+ * result against {@link SUPPORTED_LANGUAGES}. A bare base subtag (`'es'`) has
+ * no region and is therefore not a locale — it returns `undefined`.
  */
-export function getLanguageName(languageCode: string | null | undefined): string {
-  const metadata = getLanguageMetadata(languageCode);
-  return metadata?.name || languageCode || FALLBACK_LANGUAGE;
+export function normalizeLocale(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+
+  const parts = trimmed.split('-');
+  if (parts.length < 2) return undefined;
+
+  const base = parts[0]?.toLowerCase();
+  const region = parts[parts.length - 1]?.toUpperCase();
+  if (!base || !region) return undefined;
+
+  const canonical = `${base}-${region}`;
+  return LOCALE_BY_CODE.has(canonical) ? canonical : undefined;
 }
 
 /**
- * Get native language name by language code
- * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
- * @returns Native language name (e.g., 'Español') or the code if not found
+ * Whether `input` resolves to a supported BCP-47 locale.
  */
-export function getNativeLanguageName(languageCode: string | null | undefined): string {
-  const metadata = getLanguageMetadata(languageCode);
-  return metadata?.nativeName || languageCode || FALLBACK_LANGUAGE;
+export function isSupportedLocale(input: string): boolean {
+  return normalizeLocale(input) !== undefined;
 }
 
 /**
- * Normalize language code to BCP-47 format
- * @param lang - Language code (may be short like 'en' or full like 'en-US')
- * @returns Normalized BCP-47 language code
+ * Resolve catalog metadata for a locale.
+ *
+ * @param code - A locale tag (any case; e.g. `'es-ES'`, `'es-es'`).
+ * @returns The {@link SupportedLanguage} entry, or `null` when the tag is empty
+ *   or not a supported locale.
  */
-export function normalizeLanguageCode(lang?: string | null): string {
-  if (!lang) return FALLBACK_LANGUAGE;
-  if (lang.includes('-')) return lang;
-
-  const map: Record<string, string> = {
-    en: 'en-US',
-    es: 'es-ES',
-    ca: 'ca-ES',
-    fr: 'fr-FR',
-    de: 'de-DE',
-    it: 'it-IT',
-    pt: 'pt-PT',
-    ja: 'ja-JP',
-    ko: 'ko-KR',
-    zh: 'zh-CN',
-    ar: 'ar-SA',
-  };
-
-  return map[lang] || lang;
+export function getLanguageMetadata(code: string | null | undefined): SupportedLanguage | null {
+  if (!code) return null;
+  const canonical = normalizeLocale(code);
+  if (!canonical) return null;
+  return LOCALE_BY_CODE.get(canonical) ?? null;
 }
 
 /**
- * RTL language detection.
- *
- * Returns `true` when the given BCP-47 tag or bare language code is one
- * of the right-to-left scripts we ship UI for. Apps use this to drive
- * `I18nManager.allowRTL(true)` / `forceRTL(...)` on React Native and the
- * `<html dir="rtl">` attribute on web.
- *
- * Includes Arabic (`ar`), Hebrew (`he` / legacy `iw`), Persian (`fa`),
- * Urdu (`ur`) plus their common region variants. Unknown tags are
- * treated as LTR.
+ * English display name for a locale (e.g. `'Spanish (Spain)'`).
+ * Falls back to the input tag, then {@link FALLBACK_LOCALE}.
+ */
+export function getLanguageName(code: string | null | undefined): string {
+  return getLanguageMetadata(code)?.name || code || FALLBACK_LOCALE;
+}
+
+/**
+ * Native display name (endonym) for a locale (e.g. `'Español (España)'`).
+ * Falls back to the input tag, then {@link FALLBACK_LOCALE}.
+ */
+export function getNativeLanguageName(code: string | null | undefined): string {
+  return getLanguageMetadata(code)?.nativeName || code || FALLBACK_LOCALE;
+}
+
+/**
+ * Base language subtags whose scripts are written right-to-left. Used to drive
+ * `I18nManager.forceRTL(...)` on React Native and `<html dir="rtl">` on web.
+ * Includes Arabic (`ar`), Hebrew (`he` / legacy `iw`), Persian (`fa`), and
+ * Urdu (`ur`).
  */
-const RTL_LANGUAGE_BASES = new Set(['ar', 'he', 'iw', 'fa', 'ur']);
+const RTL_LANGUAGE_BASES: ReadonlySet<string> = new Set(['ar', 'he', 'iw', 'fa', 'ur']);
 
+/**
+ * Whether a locale (or bare base subtag) is written right-to-left. Unknown
+ * tags are treated as left-to-right.
+ */
 export function isRTLLocale(locale?: string | null): boolean {
   if (!locale) return false;
-  const base = locale.toLowerCase().split('-')[0];
-  if (!base) return false;
-  return RTL_LANGUAGE_BASES.has(base);
+  return RTL_LANGUAGE_BASES.has(getBaseLanguage(locale));
+}
+
+/**
+ * Resolve the ordered list of account locales for a user, primary first.
+ *
+ * Reads `user.languages` (the only source — there is no singular `language`
+ * field), then normalizes each entry to its canonical `language-REGION` form,
+ * drops non-string and unsupported entries, and de-duplicates while preserving
+ * first-seen order. Pure and side-effect free — never throws on bad input.
+ */
+export function getUserLanguages(user: Pick<User, 'languages'> | null | undefined): string[] {
+  const source = user?.languages;
+  if (!Array.isArray(source)) return [];
+
+  const result: string[] = [];
+  const seen = new Set<string>();
+
+  for (const entry of source) {
+    if (typeof entry !== 'string') continue;
+    const canonical = normalizeLocale(entry);
+    if (!canonical || seen.has(canonical)) continue;
+    seen.add(canonical);
+    result.push(canonical);
+  }
+
+  return result;
 }
 
+/**
+ * Resolve the single PRIMARY locale for a user (the first entry from
+ * {@link getUserLanguages}), or `undefined` when the user has no supported
+ * locale.
+ */
+export function getPrimaryLanguage(user: Pick<User, 'languages'> | null | undefined): string | undefined {
+  return getUserLanguages(user)[0];
+}