@oxy.so/services 13.6.0 → 13.7.0

package/src/ui/hooks/useLanguageManagement.ts

@@ -12,11 +12,15 @@ import {
   normalizeLocale,
 } from '@oxy.so/core';
 import type { StorageInterface } from '../utils/storageHelpers';
+import { readEntryLink } from '../utils/entryLink';
 import { extractErrorMessage } from '../utils/errorHandlers';
 
 export interface UseLanguageManagementOptions {
   storage: StorageInterface | null;
   languageKey: string;
+  entryUrl?: string | null;
+  entryLinkReady?: boolean;
+  legacyLanguageKeys?: readonly string[];
   /**
    * The active account, when signed in. When present, the account's primary
    * locale (`languages[0]`) is authoritative for the app's UI locale; when
@@ -34,6 +38,7 @@ export interface UseLanguageManagementResult {
    * locally-chosen guest override, otherwise the device locale.
    */
   currentLanguage: string;
+  isLanguageReady: boolean;
   /**
    * The ordered account locales (primary first) when signed in, or the locally
    * persisted selection when signed out. Empty only before the guest override loads
@@ -145,6 +150,9 @@ function resolveDeviceLocale(): string {
 export const useLanguageManagement = ({
   storage,
   languageKey,
+  entryUrl = null,
+  entryLinkReady = true,
+  legacyLanguageKeys,
   user,
   onError,
   logger,
@@ -156,6 +164,8 @@ export const useLanguageManagement = ({
   // Until it loads, the UI uses the device locale.
   const [guestLanguages, setGuestLanguages] = useState<string[]>([]);
   const selectionVersion = useRef(0);
+  const [isLanguageReady, setLanguageReady] = useState(false);
+  const legacyKeysSignature = JSON.stringify(legacyLanguageKeys ?? []);
 
   const loadLanguageFromStorage = useCallback(async (): Promise<void> => {
     if (!storage) {
@@ -164,24 +174,45 @@ export const useLanguageManagement = ({
 
     const version = selectionVersion.current;
     try {
-      const savedLanguageRaw = await storage.getItem(languageKey);
-      // Migrate the former single locale without discarding existing preferences.
-      let stored: unknown = savedLanguageRaw;
-      if (savedLanguageRaw?.startsWith('[')) {
-        stored = JSON.parse(savedLanguageRaw);
+      function parseStored(raw: string | null): string[] {
+        let stored: unknown = raw;
+        if (raw?.startsWith('[') || raw?.startsWith('"')) {
+          try {
+            stored = JSON.parse(raw);
+          } catch {
+            return [];
+          }
+        }
+        const entries = Array.isArray(stored) ? stored : [stored];
+        return [
+          ...new Set(
+            entries.flatMap((entry) => {
+              const locale = typeof entry === 'string' ? normalizeLocale(entry) : undefined;
+              return locale ? [locale] : [];
+            }),
+          ),
+        ];
       }
-      const entries = Array.isArray(stored) ? stored : [stored];
-      const normalized = [
-        ...new Set(
-          entries.flatMap((entry) => {
-            const locale = typeof entry === 'string' ? normalizeLocale(entry) : undefined;
-            return locale ? [locale] : [];
-          }),
-        ),
-      ];
-      if (normalized.length && version === selectionVersion.current) {
-        setGuestLanguages(normalized);
+      let normalized = parseStored(await storage.getItem(languageKey));
+      let migratedKey: string | undefined;
+      const legacyKeys: string[] = JSON.parse(legacyKeysSignature);
+      if (!normalized.length) {
+        for (const key of legacyKeys) {
+          normalized = parseStored(await storage.getItem(key));
+          if (normalized.length) {
+            migratedKey = key;
+            break;
+          }
+        }
+      }
+      const linkedLanguage = readEntryLink(entryUrl).language;
+      const selected = linkedLanguage ? [linkedLanguage] : normalized;
+      if (version !== selectionVersion.current) return;
+      if (linkedLanguage || migratedKey) {
+        await storage.setItem(languageKey, JSON.stringify(selected));
+        if (migratedKey) await storage.removeItem(migratedKey);
       }
+      if (selected.length && version === selectionVersion.current) setGuestLanguages(selected);
     } catch (error) {
       const message = extractErrorMessage(error, 'Failed to load language preference');
       onError?.({
@@ -194,16 +225,19 @@ export const useLanguageManagement = ({
       } else if (__DEV__) {
         console.warn('Failed to load language preference:', error);
       }
+    } finally {
+      setLanguageReady(true);
     }
-  }, [languageKey, logger, onError, storage]);
+  }, [entryUrl, languageKey, legacyKeysSignature, logger, onError, storage]);
 
   useEffect(() => {
+    if (!entryLinkReady) return;
     loadLanguageFromStorage().catch((error) => {
       if (logger) {
         logger('Unexpected error loading language', error);
       }
     });
-  }, [loadLanguageFromStorage, logger]);
+  }, [entryLinkReady, loadLanguageFromStorage, logger]);
 
   const setLanguages = useCallback(
     async (locales: readonly string[]): Promise<void> => {
@@ -268,6 +302,7 @@ export const useLanguageManagement = ({
 
   return {
     currentLanguage,
+    isLanguageReady,
     languages,
     metadata,
     languageName,

package/src/ui/types/navigation.ts

@@ -182,9 +182,13 @@ export interface OxyProviderProps {
    * manages it independently of the account/device locale.
    */
   language?: OxyLanguageConfig;
+  /** Persist bounded first-touch link labels and attach them only to a new account. */
+  campaignAttribution?: boolean;
 }
 
 export interface OxyLanguageConfig {
+  /** Previous app-owned storage keys, migrated once without replacing a current SDK choice. */
+  legacyStorageKeys?: readonly string[];
   /** The exact locales this app ships a translation catalog for. */
   supportedLocales: readonly string[];
   /**

package/src/ui/utils/__tests__/entryLink.test.ts

@@ -0,0 +1,30 @@
+import { readEntryLink, readCampaignAttribution } from '../entryLink';
+
+it.each([
+  ['https://mention.earth/?lang=es', 'es-ES'],
+  ['mention://compose?lang=fr-BE', 'fr-FR'],
+  ['https://mention.earth/?lang=zz', undefined],
+  ['https://mention.earth/?lang=en&lang=es', undefined],
+  ['not a url', undefined],
+])('resolves supported entry locale %s', (url, expected) => {
+  expect(readEntryLink(url).language).toBe(expected);
+});
+
+it('captures only campaign fields without retaining the URL, a referrer or unrelated private query data', () => {
+  expect(
+    readEntryLink(
+      'https://mention.earth/write?utm_source=meta&utm_campaign=Spain&fbclid=click&email=private@example.test',
+    ),
+  ).toEqual({
+    language: undefined,
+    campaignAttribution: { utmSource: 'meta', utmCampaign: 'Spain', fbclid: 'click' },
+  });
+});
+
+it('drops empty, duplicate, overlong and control-character campaign values', () => {
+  const url = `mention://?utm_source=one&utm_source=two&utm_medium=&utm_campaign=${'x'.repeat(257)}&utm_content=bad%00value`;
+  expect(readEntryLink(url).campaignAttribution).toBeUndefined();
+  expect(
+    readCampaignAttribution({ fbclid: 'x'.repeat(1025), utmSource: ' meta ', private: 'secret' }),
+  ).toEqual({ utmSource: 'meta' });
+});

package/src/ui/utils/entryLink.ts

@@ -0,0 +1,61 @@
+import { SUPPORTED_LANGUAGES, normalizeLocale } from '@oxy.so/core';
+import {
+  CAMPAIGN_LABEL_MAX_LENGTH,
+  isLanguageTag,
+  hasCampaignControlCharacters,
+  CAMPAIGN_CLICK_ID_MAX_LENGTH,
+  type CampaignAttribution,
+} from '@oxy.so/contracts/client';
+
+const CAMPAIGN_PARAMETERS = {
+  utmSource: 'utm_source',
+  utmMedium: 'utm_medium',
+  utmCampaign: 'utm_campaign',
+  utmContent: 'utm_content',
+  utmTerm: 'utm_term',
+  fbclid: 'fbclid',
+} as const;
+
+export function readCampaignAttribution(value: unknown): CampaignAttribution | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const result: CampaignAttribution = {};
+  for (const field of Object.keys(CAMPAIGN_PARAMETERS) as (keyof CampaignAttribution)[]) {
+    const raw = Reflect.get(value, field);
+    if (typeof raw !== 'string') continue;
+    const normalized = raw.trim();
+    const limit = field === 'fbclid' ? CAMPAIGN_CLICK_ID_MAX_LENGTH : CAMPAIGN_LABEL_MAX_LENGTH;
+    if (!normalized || normalized.length > limit || hasCampaignControlCharacters(normalized))
+      continue;
+    result[field] = normalized;
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+
+/** Consumes only explicit locale/campaign parameters, never the URL or referrer itself. */
+export function readEntryLink(url: string | null): {
+  language?: string;
+  campaignAttribution?: CampaignAttribution;
+} {
+  if (!url) return {};
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return {};
+  }
+  const languages = parsed.searchParams.getAll('lang');
+  const requestedLanguage = languages.length === 1 ? languages[0] : undefined;
+  const language =
+    requestedLanguage && isLanguageTag(requestedLanguage)
+      ? (normalizeLocale(requestedLanguage) ??
+        SUPPORTED_LANGUAGES.find(
+          (candidate) => candidate.language === requestedLanguage.split('-')[0]?.toLowerCase(),
+        )?.code)
+      : undefined;
+  const fields: Record<string, string> = {};
+  for (const [field, query] of Object.entries(CAMPAIGN_PARAMETERS)) {
+    const values = parsed.searchParams.getAll(query);
+    if (values.length === 1) fields[field] = values[0];
+  }
+  return { language, campaignAttribution: readCampaignAttribution(fields) };
+}