@oxyhq/core 9.2.3 → 10.0.0

package/dist/esm/utils/languageUtils.js

@@ -1,179 +1,212 @@
 /**
- * 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.
+ */
+/**
+ * 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.
  */
-// Supported languages with their metadata
 export const SUPPORTED_LANGUAGES = [
-    {
-        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',
-    },
+    // 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 = 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) {
-    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) {
+    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) {
-    const metadata = getLanguageMetadata(languageCode);
-    return metadata?.name || languageCode || FALLBACK_LANGUAGE;
+export function normalizeLocale(input) {
+    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) {
-    const metadata = getLanguageMetadata(languageCode);
-    return metadata?.nativeName || languageCode || FALLBACK_LANGUAGE;
+export function isSupportedLocale(input) {
+    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) {
-    if (!lang)
-        return FALLBACK_LANGUAGE;
-    if (lang.includes('-'))
-        return lang;
-    const map = {
-        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) {
+    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) {
+    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) {
+    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']);
+/**
+ * Whether a locale (or bare base subtag) is written right-to-left. Unknown
+ * tags are treated as left-to-right.
+ */
 export function isRTLLocale(locale) {
     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) {
+    const source = user?.languages;
+    if (!Array.isArray(source))
+        return [];
+    const result = [];
+    const seen = new Set();
+    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) {
+    return getUserLanguages(user)[0];
 }

package/dist/esm/utils/platform.js

@@ -5,6 +5,13 @@
  * This allows core modules to be used in web/Node.js environments
  * without bundlers failing on react-native imports.
  */
+/**
+ * Typed view over `globalThis` for the RN-platform marker, avoiding an `any`
+ * cast at each access site.
+ */
+function rnPlatformGlobal() {
+    return globalThis;
+}
 /**
  * Detect the current platform without importing react-native
  *
@@ -17,7 +24,7 @@
 function detectPlatform() {
     // Check if React Native Platform is available globally (set by RN runtime)
     // This avoids static imports while still detecting RN environment
-    const rnPlatform = globalThis.__REACT_NATIVE_PLATFORM__;
+    const rnPlatform = rnPlatformGlobal().__REACT_NATIVE_PLATFORM__;
     if (rnPlatform) {
         return rnPlatform;
     }
@@ -81,7 +88,7 @@ export function isAndroid() {
  */
 export function setPlatformOS(os) {
     cachedPlatform = os;
-    globalThis.__REACT_NATIVE_PLATFORM__ = os;
+    rnPlatformGlobal().__REACT_NATIVE_PLATFORM__ = os;
 }
 /**
  * True only in a real web browser (a DOM is present), false on React Native