@oxy.so/core 1.1.2 → 1.2.0

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.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,18 +115,18 @@
     }
   },
   "dependencies": {
-    "@oxy.so/telemetry": "^1.1.1",
+    "@oxy.so/telemetry": "workspace:^",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.1.1",
-    "@oxy.so/protocol": "^1.0.1",
+    "@oxy.so/contracts": "workspace:^",
+    "@oxy.so/protocol": "workspace:^",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
-    "express-rate-limit": "^8.6.0",
+    "express-rate-limit": "catalog:",
     "helmet": "^8.0.0",
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
-    "socket.io-client": "^4.8.1",
+    "socket.io-client": "catalog:",
     "tldts": "^7.4.10",
     "zod": "^3.25.64"
   },
@@ -151,19 +151,19 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "catalog:",
     "@react-native-async-storage/async-storage": "^2.2.0",
-    "@types/express": "^4.17.25",
+    "@types/express": "catalog:",
     "@types/invariant": "^2.2.34",
     "@types/node": "^20.19.43",
     "expo-crypto": "~56.0.3",
     "expo-secure-store": "~56.0.4",
-    "express": "^4.22.2",
-    "express-rate-limit": "^8.6.0",
+    "express": "catalog:",
+    "express-rate-limit": "catalog:",
     "jest": "^30.5.1",
     "regexpu-core": "^6.4.0",
-    "release-it": "^19.0.6",
+    "release-it": "catalog:",
     "typescript": "^5.9.2",
-    "helmet": "^8.3.0"
+    "helmet": "catalog:"
   }
 }

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;
+}