@oxy.so/core 1.1.1 → 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/cache.d.ts

@@ -118,10 +118,7 @@ export declare function createCache<T>(ttl?: number): TTLCache<T>;
  * @param cache Cache instance to register
  */
 export declare function registerCacheForCleanup(cache: TTLCache<any>): void;
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export declare function unregisterCacheFromCleanup(cache: TTLCache<any>): void;
 /**
  * Stop all cleanup intervals (useful for testing)

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.1",
+  "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__/cacheLifecycle.test.ts

@@ -0,0 +1,65 @@
+import { TTLCache, registerCacheForCleanup, unregisterCacheFromCleanup, stopAllCleanupIntervals } from '../cache';
+
+afterEach(() => { stopAllCleanupIntervals(); jest.useRealTimers(); });
+
+test('empty registration is inert and first data starts one shared cleanup timer', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  const b = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('a', 'value');
+  b.set('b', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  jest.advanceTimersByTime(11);
+  expect(a.get('a')).toBeNull();
+  expect(b.has('b')).toBe(false);
+  jest.advanceTimersByTime(60_000);
+  expect(jest.getTimerCount()).toBe(0);
+});
+test('periodic cleanup expires unread entries and clear restarts lazily without losing registration', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  a.set('expired', 'value');
+  jest.advanceTimersByTime(60_000);
+  expect(a.size()).toBe(0);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('again', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  a.clear();
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('after-clear', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+});
+test('unregister and stop preserve entries but prevent writes restarting automatic cleanup', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(100_000);
+  const b = new TTLCache<string>(100_000);
+  a.set('a', 'value');
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  b.set('b', 'value');
+  unregisterCacheFromCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  b.delete('b');
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('unregistered', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  registerCacheForCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  stopAllCleanupIntervals();
+  a.set('stopped', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  expect(a.get('a')).toBe('value');
+});
+test('server barrel imports and client construction start no background timers', () => {
+  jest.useFakeTimers();
+  jest.isolateModules(() => {
+    const server = require('../../server');
+    expect(typeof server.createEcosystemTraffic).toBe('function');
+    expect(jest.getTimerCount()).toBe(0);
+    require('../cache').stopAllCleanupIntervals();
+  });
+});

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/cache.ts

@@ -104,6 +104,7 @@ export class TTLCache<T> {
     const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
     const expiresAt = now + effectiveTTL;
     this.cache.set(key, { data, timestamp: now, expiresAt });
+    if (!cleanupInterval && activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -112,7 +113,9 @@ export class TTLCache<T> {
    * @returns true if entry was deleted, false if not found
    */
   delete(key: string): boolean {
-    return this.cache.delete(key);
+    const deleted = this.cache.delete(key);
+    if (activeCaches.has(this)) updateCleanupInterval();
+    return deleted;
   }
 
   /**
@@ -122,6 +125,7 @@ export class TTLCache<T> {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
+    if (activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -232,31 +236,29 @@ const activeCaches = new Set<TTLCache<any>>();
  */
 export function registerCacheForCleanup(cache: TTLCache<any>): void {
   activeCaches.add(cache);
+  updateCleanupInterval();
+}
 
-  // Start cleanup interval if not already running
-  if (!cleanupInterval) {
-    cleanupInterval = setInterval(() => {
-      for (const cache of activeCaches) {
-        cache.cleanup();
-      }
-    }, 60000); // Every minute
-    // Never block process/worker exit on a housekeeping timer.
-    cleanupInterval.unref?.();
+/** Empty registered caches need no timer; importing a client must stay inert. */
+function updateCleanupInterval(): void {
+  const hasEntries = [...activeCaches].some(cache => cache.size() > 0);
+  if (!hasEntries) {
+    if (cleanupInterval) clearInterval(cleanupInterval);
+    cleanupInterval = null;
+    return;
   }
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    for (const cache of activeCaches) cache.cleanup();
+    updateCleanupInterval();
+  }, 60_000);
+  cleanupInterval.unref?.();
 }
 
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
   activeCaches.delete(cache);
-
-  // Stop cleanup interval if no caches are registered
-  if (activeCaches.size === 0 && cleanupInterval) {
-    clearInterval(cleanupInterval);
-    cleanupInterval = null;
-  }
+  updateCleanupInterval();
 }
 
 /**

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