@asgardeo/javascript 0.8.1 → 0.8.3

package/dist/models/config.d.ts

@@ -239,6 +239,16 @@ export interface ThemePreferences {
      */
     overrides?: RecursivePartial<ThemeConfig>;
 }
+/**
+ * The storage strategy to use for persisting the user's language selection.
+ *
+ * - `'cookie'`       — persists in `document.cookie` as a domain cookie (default).
+ *                      Useful for cross-subdomain scenarios where the auth portal and
+ *                      the application share a root domain.
+ * - `'localStorage'` — persists in `window.localStorage`.
+ * - `'none'`         — no persistence; the resolved language is held in React state only.
+ */
+export type I18nStorageStrategy = 'cookie' | 'localStorage' | 'none';
 export interface I18nPreferences {
     /**
      * Custom translations to override default ones.
@@ -246,6 +256,14 @@ export interface I18nPreferences {
     bundles?: {
         [key: string]: I18nBundle;
     };
+    /**
+     * The domain to use when setting the language cookie.
+     * Only applies when `storageStrategy` is `'cookie'`.
+     * Defaults to the root domain derived from `window.location.hostname`
+     * (e.g. `'app.example.com'` → `'example.com'`).
+     * Override this for eTLD+1 domains like `.co.uk` or custom cookie scoping.
+     */
+    cookieDomain?: string;
     /**
      * The fallback language to use if translations are not available in the specified language.
      * Defaults to 'en-US'.
@@ -253,9 +271,31 @@ export interface I18nPreferences {
     fallbackLanguage?: string;
     /**
      * The language to use for translations.
-     * Defaults to the browser's default language.
+     * When set, acts as a hard override and bypasses all other detection sources
+     * (URL param, stored preference, browser language).
      */
     language?: string;
+    /**
+     * The key used when reading/writing the language to the chosen storage.
+     * For `localStorage` this is the key name; for `cookie` this is the cookie name.
+     * @default 'asgardeo-i18n-language'
+     */
+    storageKey?: string;
+    /**
+     * The storage strategy to use for persisting the user's language selection.
+     * @default 'cookie'
+     */
+    storageStrategy?: I18nStorageStrategy;
+    /**
+     * The URL query-parameter name to inspect for a language override.
+     * Set to `false` to disable URL-parameter detection entirely.
+     * When a URL param is detected its value is immediately persisted to storage.
+     * @default 'lang'
+     * @example
+     * // With urlParam: 'locale', the URL ?locale=fr-FR will select French.
+     * // With urlParam: false, URL parameters are ignored.
+     */
+    urlParam?: string | false;
 }
 export interface Preferences {
     /**

package/dist/utils/v2/countryCodeToFlagEmoji.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Converts a two-letter ISO 3166-1 alpha-2 country code to a flag emoji using
+ * Unicode Regional Indicator Symbols (U+1F1E6–U+1F1FF).
+ *
+ * @param countryCode - Two-letter uppercase country code (e.g. "US", "GB")
+ * @returns Flag emoji string (e.g. "🇺🇸", "🇬🇧")
+ */
+export default function countryCodeToFlagEmoji(countryCode: string): string;

package/dist/utils/v2/resolveLocaleDisplayName.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Resolves a BCP 47 locale tag to a human-readable display name using the
+ * `Intl.DisplayNames` API.
+ *
+ * Falls back to the raw locale code if the runtime does not support
+ * `Intl.DisplayNames` or if resolution returns `undefined`.
+ *
+ * @param locale - BCP 47 locale tag to resolve (e.g. "en", "fr", "zh-Hant")
+ * @param displayLocale - Locale used for the display name language (defaults to "en")
+ * @returns Human-readable language name (e.g. "English", "French")
+ */
+export default function resolveLocaleDisplayName(locale: string, displayLocale: string): string;

package/dist/utils/v2/resolveLocaleEmoji.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Resolves a BCP 47 locale tag to a flag emoji.
+ *
+ * Resolution order:
+ * 1. Country subtag when present (e.g. `"en-US"` → 🇺🇸)
+ * 2. Language-to-country fallback map (e.g. `"en"` → 🇬🇧)
+ * 3. Globe emoji 🌐 for unrecognised codes
+ *
+ * @param locale - BCP 47 locale tag (e.g. "en", "en-US", "fr-CA")
+ * @returns Flag or globe emoji string
+ */
+declare function resolveLocaleEmoji(locale: string): string;
+export default resolveLocaleEmoji;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asgardeo/javascript",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Framework agnostic JavaScript SDK for Asgardeo.",
   "keywords": [
     "asgardeo",
@@ -47,7 +47,7 @@
   "dependencies": {
     "tslib": "2.8.1",
     "jose": "^5.2.0",
-    "@asgardeo/i18n": "0.4.2"
+    "@asgardeo/i18n": "0.4.3"
   },
   "publishConfig": {
     "access": "public"