@oxy.so/core 1.1.2 → 1.2.1

package/dist/types/index.d.ts

@@ -76,7 +76,7 @@ export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferenc
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';
-export { SUPPORTED_LANGUAGES, FALLBACK_LOCALE, getBaseLanguage, normalizeLocale, isSupportedLocale, getLanguageMetadata, getLanguageName, getNativeLanguageName, isRTLLocale, getUserLanguages, getPrimaryLanguage, } from './utils/languageUtils';
+export { SUPPORTED_LANGUAGES, FALLBACK_LOCALE, getBaseLanguage, normalizeLocale, isSupportedLocale, getLanguageMetadata, getLanguageName, getNativeLanguageName, isRTLLocale, getUserLanguages, getPrimaryLanguage, coerceToSupportedLocale, } from './utils/languageUtils';
 export type { SupportedLanguage } from './utils/languageUtils';
 export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, isWebBrowser, } from './utils/platform';
 export type { PlatformOS } from './utils/platform';

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

@@ -98,3 +98,16 @@ export declare function getUserLanguages(user: Pick<User, 'languages'> | null |
  * locale.
  */
 export declare function getPrimaryLanguage(user: Pick<User, 'languages'> | null | undefined): string | undefined;
+/**
+ * Coerce a locale down to one from a CALLER-provided catalog: an exact
+ * canonical match wins, else the closest entry sharing the same base
+ * language (an `es-MX` account reads a host app's `es-ES` catalog), else
+ * `fallback`.
+ *
+ * A host app's own shipped translation catalog is rarely {@link SUPPORTED_LANGUAGES}
+ * itself — Oxy's account-locale catalog is broader than any one app's
+ * translated strings — so this is the one place that gap is bridged. Every Oxy
+ * app was independently re-deriving this exact algorithm against its own
+ * catalog before it moved here.
+ */
+export declare function coerceToSupportedLocale(locale: string | null | undefined, supportedLocales: readonly string[], fallback: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -428,6 +428,7 @@ export {
     isRTLLocale,
     getUserLanguages,
     getPrimaryLanguage,
+    coerceToSupportedLocale,
 } from './utils/languageUtils';
 export type { SupportedLanguage } from './utils/languageUtils';
 

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

@@ -9,6 +9,7 @@ import {
   isRTLLocale,
   getUserLanguages,
   getPrimaryLanguage,
+  coerceToSupportedLocale,
 } from '../languageUtils';
 
 describe('getBaseLanguage', () => {
@@ -187,6 +188,30 @@ describe('getPrimaryLanguage', () => {
   });
 });
 
+describe('coerceToSupportedLocale', () => {
+  const hostCatalog = ['en-US', 'es-ES', 'fr-FR'] as const;
+
+  it('returns an exact canonical match from the host catalog', () => {
+    expect(coerceToSupportedLocale('es-es', hostCatalog, 'en-US')).toBe('es-ES');
+  });
+
+  it('falls back to the closest entry sharing the same base language', () => {
+    // `es-MX` is a real Oxy locale, but this host never shipped a Mexican
+    // Spanish catalog — its Spanish (Spain) one is the closest match.
+    expect(coerceToSupportedLocale('es-MX', hostCatalog, 'en-US')).toBe('es-ES');
+  });
+
+  it('falls back to the caller default when no base language matches', () => {
+    expect(coerceToSupportedLocale('ja-JP', hostCatalog, 'en-US')).toBe('en-US');
+  });
+
+  it('falls back to the caller default for empty or unresolved input', () => {
+    expect(coerceToSupportedLocale(undefined, hostCatalog, 'en-US')).toBe('en-US');
+    expect(coerceToSupportedLocale(null, hostCatalog, 'en-US')).toBe('en-US');
+    expect(coerceToSupportedLocale('', hostCatalog, 'en-US')).toBe('en-US');
+  });
+});
+
 describe('SUPPORTED_LANGUAGES catalog integrity', () => {
   it('is non-empty', () => {
     expect(SUPPORTED_LANGUAGES.length).toBeGreaterThan(0);

package/src/utils/languageUtils.ts

@@ -254,3 +254,32 @@ export function getUserLanguages(user: Pick<User, 'languages'> | null | undefine
 export function getPrimaryLanguage(user: Pick<User, 'languages'> | null | undefined): string | undefined {
   return getUserLanguages(user)[0];
 }
+
+/**
+ * Coerce a locale down to one from a CALLER-provided catalog: an exact
+ * canonical match wins, else the closest entry sharing the same base
+ * language (an `es-MX` account reads a host app's `es-ES` catalog), else
+ * `fallback`.
+ *
+ * A host app's own shipped translation catalog is rarely {@link SUPPORTED_LANGUAGES}
+ * itself — Oxy's account-locale catalog is broader than any one app's
+ * translated strings — so this is the one place that gap is bridged. Every Oxy
+ * app was independently re-deriving this exact algorithm against its own
+ * catalog before it moved here.
+ */
+export function coerceToSupportedLocale(
+  locale: string | null | undefined,
+  supportedLocales: readonly string[],
+  fallback: string,
+): string {
+  if (locale) {
+    const canonical = normalizeLocale(locale);
+    if (canonical && supportedLocales.includes(canonical)) {
+      return canonical;
+    }
+    const base = getBaseLanguage(locale);
+    const byBase = supportedLocales.find((entry) => getBaseLanguage(entry) === base);
+    if (byBase) return byBase;
+  }
+  return fallback;
+}