@oxy.so/services 13.5.0 → 13.7.0

package/src/ui/hooks/useEntryLink.ts

@@ -0,0 +1,103 @@
+import { useEffect, useRef, useState } from 'react';
+import { Linking, Platform } from 'react-native';
+import type { CampaignAttribution } from '@oxy.so/contracts';
+import type { StorageInterface } from '../utils/storageHelpers';
+import { readCampaignAttribution, readEntryLink } from '../utils/entryLink';
+
+/** One receiver for initial and warm native links and web entry parameters. */
+export function useEntryLink({
+  storage,
+  storageKey,
+  captureCampaign,
+  onError,
+}: {
+  storage: StorageInterface | null;
+  storageKey: string;
+  captureCampaign: boolean;
+  onError: (message: string, error?: unknown) => void;
+}) {
+  const [entry, setEntry] = useState<{
+    url: string | null | undefined;
+    ready: boolean;
+    firstCampaign?: CampaignAttribution;
+  }>({ url: undefined, ready: false });
+  const [campaignAttribution, setCampaignAttribution] = useState<CampaignAttribution>();
+  const [campaignReady, setCampaignReady] = useState(false);
+  const captures = useRef(Promise.resolve());
+
+  useEffect(() => {
+    let active = true;
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      setEntry((current) => ({
+        ...current,
+        url,
+        firstCampaign: current.firstCampaign ?? readEntryLink(url).campaignAttribution,
+      }));
+    });
+    const initialUrl =
+      Platform.OS === 'web' && typeof window !== 'undefined'
+        ? Promise.resolve(window.location.href)
+        : Linking.getInitialURL();
+    initialUrl
+      .then((initial) => {
+        if (active)
+          setEntry((current) => ({
+            url: current.url === undefined ? initial : current.url,
+            ready: true,
+            firstCampaign:
+              readEntryLink(initial ?? null).campaignAttribution ?? current.firstCampaign,
+          }));
+      })
+      .catch((error: unknown) => {
+        onError('Failed to read the initial entry link', error);
+        if (active) setEntry((current) => ({ ...current, url: current.url ?? null, ready: true }));
+      });
+    return () => {
+      active = false;
+      subscription.remove();
+    };
+  }, [onError]);
+
+  useEffect(() => {
+    if (!storage || !entry.ready) return;
+    let active = true;
+    async function capture() {
+      if (!captureCampaign) {
+        if (active) setCampaignReady(true);
+        return;
+      }
+      let stored: CampaignAttribution | undefined;
+      const raw = await storage?.getItem(storageKey);
+      if (raw) {
+        try {
+          stored = readCampaignAttribution(JSON.parse(raw));
+        } catch {
+          onError('Stored campaign attribution is malformed');
+        }
+      }
+      const selected = stored ?? entry.firstCampaign;
+      if (selected && !stored) await storage?.setItem(storageKey, JSON.stringify(selected));
+      if (active) {
+        setCampaignAttribution(selected);
+        setCampaignReady(true);
+      }
+    }
+    captures.current = captures.current.then(capture).catch((error: unknown) => {
+      onError('Failed to persist campaign attribution', error);
+      if (active) {
+        setCampaignAttribution(entry.firstCampaign);
+        setCampaignReady(true);
+      }
+    });
+    return () => {
+      active = false;
+    };
+  }, [captureCampaign, entry.ready, entry.firstCampaign, onError, storage, storageKey]);
+
+  return {
+    url: entry.url,
+    ready: entry.ready,
+    campaignAttribution,
+    campaignReady: !captureCampaign || campaignReady,
+  };
+}

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/screens/AccountMembersScreen.tsx

@@ -111,7 +111,14 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
   );
   const memberProfilesQuery = useQuery({
     queryKey: ['users', 'by-ids', memberUserIds],
-    queryFn: () => oxyServices.users.getMany(memberUserIds),
+    // `lookupMany`, not `getMany`: a chunk that failed is unknown, not absent.
+    // Failing the query lets React Query retry it, where a resolved empty
+    // answer would be cached as "no handle" for the whole stale window.
+    queryFn: async () => {
+      const lookup = await oxyServices.users.lookupMany(memberUserIds);
+      if (lookup.failed.length > 0) throw lookup.error ?? new Error('Member profiles unavailable');
+      return lookup.found;
+    },
     enabled: canUsePrivateApi && memberUserIds.length > 0,
   });
   const memberLabelByUserId = useMemo(() => {

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