@oxy.so/services 13.6.0 → 13.7.0

package/src/ui/components/OxyProvider.tsx

@@ -20,19 +20,10 @@ import { isNetConnectivityOnline } from '../utils/netConnectivity';
 import { KeyboardBoundary } from './KeyboardBoundary';
 import { SafeAreaRoot } from './SafeAreaRoot';
 import { ProductAnalyticsObserver } from '../analytics/productAnalytics';
-import { LanguageBridge } from './LanguageBridge';
+import { AccountLanguageBoundary } from './AccountLanguageBoundary';
 import { BloomLocaleBridge } from './BloomLocaleBridge';
-import { useOxy } from '../context/oxyRuntimeContext';
-import { useCurrentUser } from '../hooks/queries/useAccountQueries';
 import { SupervisionStateObserver } from '../hooks/queries/useSupervision';
 
-/** Hydrate owner preferences after the bearer is ready, including on cold boot. */
-function AccountProfileObserver() {
-  const { canUsePrivateApi } = useOxy();
-  useCurrentUser({ enabled: canUsePrivateApi });
-  return null;
-}
-
 const bootStyles = StyleSheet.create({
   providerRoot: {
     flex: 1,
@@ -114,6 +105,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
   requireAuth = 'off',
   backgroundSession = false,
   language,
+  campaignAttribution = false,
 }) => {
   const support = useMemo(
     () => ({ onAskAlia, documentationUrl, aliaAvatar, oxyOneArtwork }),
@@ -279,26 +271,28 @@ const OxyProvider: FC<OxyProviderProps> = ({
         sessionMode={sessionMode}
         webAuthMode={webAuthMode}
         backgroundSession={backgroundSession}
+        legacyLanguageKeys={language?.legacyStorageKeys}
+        captureCampaignAttribution={campaignAttribution}
         platformStorage={platformStorage}
         accountQueries={accountQueries}
         onAuthStateChange={onAuthStateChange as OxyRuntimeProviderProps['onAuthStateChange']}
       >
-        <AccountProfileObserver />
         <SupervisionStateObserver />
         {productAnalytics ? <ProductAnalyticsObserver analytics={productAnalytics} /> : null}
-        {language ? <LanguageBridge {...language} /> : null}
-        <BloomLocaleBridge>
-          <OxySupportContext.Provider value={support}>
-            <SurfaceProvider>
-              {requireAuth === 'off' ? (
-                children
-              ) : (
-                <RequireOxyAuth prompt={requireAuth}>{children}</RequireOxyAuth>
-              )}
-            </SurfaceProvider>
-          </OxySupportContext.Provider>
-          <ToastOutlet />
-        </BloomLocaleBridge>
+        <AccountLanguageBoundary language={language}>
+          <BloomLocaleBridge>
+            <OxySupportContext.Provider value={support}>
+              <SurfaceProvider>
+                {requireAuth === 'off' ? (
+                  children
+                ) : (
+                  <RequireOxyAuth prompt={requireAuth}>{children}</RequireOxyAuth>
+                )}
+              </SurfaceProvider>
+            </OxySupportContext.Provider>
+            <ToastOutlet />
+          </BloomLocaleBridge>
+        </AccountLanguageBoundary>
       </OxyRuntimeProvider>
     </QueryClientProvider>
   );

package/src/ui/components/__tests__/AccountLanguageBoundary.test.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { render, waitFor } from '@testing-library/react';
+import { AccountLanguageBoundary } from '../AccountLanguageBoundary';
+
+let mockCurrentLanguage = 'en-US';
+let mockCanUsePrivateApi = true;
+const mockUser = { id: 'account', publicKey: '', username: 'ada', name: {} };
+let mockQuery: {
+  data?: typeof mockUser & { languages?: string[] };
+  dataUpdatedAt: number;
+  isError: boolean;
+  fetchStatus?: 'fetching' | 'paused' | 'idle';
+};
+jest.mock('../../context/oxyRuntimeContext', () => ({
+  useOxy: () => ({
+    canUsePrivateApi: mockCanUsePrivateApi,
+    user: mockUser,
+    currentLanguage: mockCurrentLanguage,
+    isLanguageReady: true,
+    isAuthResolved: true,
+  }),
+}));
+jest.mock('../../hooks/queries/useAccountQueries', () => ({ useCurrentUser: () => mockQuery }));
+
+it('waits for the owner preference query and its runtime projection before painting the account app', async () => {
+  mockQuery = { data: mockUser, dataUpdatedAt: 0, isError: false };
+  const onChange = jest.fn();
+  const config = { supportedLocales: ['en-US', 'es-ES'], fallbackLocale: 'en-US', onChange };
+  const screen = render(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  expect(screen.queryByText('App')).toBeNull();
+  mockQuery = { data: { ...mockUser, languages: ['es-ES'] }, dataUpdatedAt: 123, isError: false };
+  screen.rerender(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  expect(screen.queryByText('App')).toBeNull();
+  expect(onChange).not.toHaveBeenCalled();
+  mockCurrentLanguage = 'es-ES';
+  screen.rerender(
+    <AccountLanguageBoundary language={config}>
+      <span>App</span>
+    </AccountLanguageBoundary>,
+  );
+  await waitFor(() => expect(screen.getByText('App')).toBeTruthy());
+  expect(onChange.mock.calls).toEqual([['es-ES']]);
+});
+
+it.each(['paused', 'disabled', 'error'] as const)(
+  'renders the resolved fallback when the account query is %s, then adopts its preference without remounting',
+  async (unavailable) => {
+    mockCurrentLanguage = 'en-US';
+    mockCanUsePrivateApi = unavailable !== 'disabled';
+    mockQuery = {
+      data: mockUser,
+      dataUpdatedAt: 0,
+      isError: unavailable === 'error',
+      fetchStatus: unavailable === 'paused' ? 'paused' : 'idle',
+    };
+    const onChange = jest.fn();
+    const config = { supportedLocales: ['en-US', 'es-ES'], fallbackLocale: 'en-US', onChange };
+    const view = () => (
+      <AccountLanguageBoundary language={config}>
+        <input aria-label="Draft" defaultValue="Kept" />
+      </AccountLanguageBoundary>
+    );
+    const screen = render(view());
+    await waitFor(() => expect(screen.getByLabelText('Draft')).toBeTruthy());
+    const draft = screen.getByLabelText('Draft');
+    expect(onChange.mock.calls).toEqual([['en-US']]);
+    mockCanUsePrivateApi = true;
+    mockQuery = {
+      data: { ...mockUser, languages: ['es-ES'] },
+      dataUpdatedAt: 123,
+      isError: false,
+      fetchStatus: 'idle',
+    };
+    mockCurrentLanguage = 'es-ES';
+    screen.rerender(view());
+    await waitFor(() => expect(onChange.mock.calls).toEqual([['en-US'], ['es-ES']]));
+    expect(screen.getByLabelText('Draft')).toBe(draft);
+  },
+);

package/src/ui/components/__tests__/LanguageBridge.test.tsx

@@ -1,91 +1,111 @@
 import React from 'react';
-import { render } from '@testing-library/react';
+import { act, render, waitFor } from '@testing-library/react';
 import { LanguageBridge } from '../LanguageBridge';
 
-/**
- * `OxyProvider`'s language config prop, realized: the one place Oxy's
- * resolved language reaches a host app's own i18n library. `useOxy` is mocked here —
- * it is the SDK's own well-tested context — so these tests exercise exactly
- * what this component adds: coercion to the caller's catalog, and calling
- * back only when the RESOLVED locale actually changes.
- */
-
 let mockCurrentLanguage = 'en-US';
+let mockLanguageReady = true;
+let mockAuthResolved = true;
 jest.mock('../../context/oxyRuntimeContext', () => ({
-  useOxy: () => ({ currentLanguage: mockCurrentLanguage }),
+  useOxy: () => ({
+    currentLanguage: mockCurrentLanguage,
+    isLanguageReady: mockLanguageReady,
+    isAuthResolved: mockAuthResolved,
+  }),
 }));
-
 const HOST_CATALOG = ['en-US', 'es-ES', 'fr-FR'] as const;
-
 beforeEach(() => {
   mockCurrentLanguage = 'en-US';
+  mockLanguageReady = true;
+  mockAuthResolved = true;
 });
 
-it('resolves and reports the account language on mount', () => {
-  mockCurrentLanguage = 'es-ES';
+it.each([
+  ['es-ES', 'es-ES'],
+  ['es-MX', 'es-ES'],
+  ['ja-JP', 'en-US'],
+])('resolves %s to the host catalog %s', async (locale, expected) => {
+  mockCurrentLanguage = locale;
   const onChange = jest.fn();
   render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+    <LanguageBridge config={{ supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange }}>
+      <span>App</span>
+    </LanguageBridge>,
   );
-
-  expect(onChange).toHaveBeenCalledWith('es-ES');
+  await waitFor(() => expect(onChange).toHaveBeenCalledWith(expected));
 });
 
-it('coerces a locale the host never shipped a catalog for, by base language', () => {
-  mockCurrentLanguage = 'es-MX';
-  const onChange = jest.fn();
-  render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+it('does not paint any app text before saved preferences, account restoration and catalog loading finish', async () => {
+  mockLanguageReady = false;
+  mockAuthResolved = false;
+  let finishCatalog: (() => void) | undefined;
+  const onChange = jest.fn(
+    () =>
+      new Promise<void>((resolve) => {
+        finishCatalog = resolve;
+      }),
   );
-
-  expect(onChange).toHaveBeenCalledWith('es-ES');
-});
-
-it('falls back to the caller default when nothing matches, even by base', () => {
-  mockCurrentLanguage = 'ja-JP';
-  const onChange = jest.fn();
-  render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
-  );
-
-  expect(onChange).toHaveBeenCalledWith('en-US');
+  const config = { supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange };
+  const children = <span>Translated app</span>;
+  const screen = render(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  expect(screen.queryByText('Translated app')).toBeNull();
+  expect(onChange).not.toHaveBeenCalled();
+  mockLanguageReady = true;
+  mockCurrentLanguage = 'es-ES';
+  screen.rerender(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  expect(onChange).not.toHaveBeenCalled();
+  mockAuthResolved = true;
+  screen.rerender(<LanguageBridge config={config}>{children}</LanguageBridge>);
+  await waitFor(() => expect(onChange).toHaveBeenCalledWith('es-ES'));
+  expect(screen.queryByText('Translated app')).toBeNull();
+  await act(async () => finishCatalog?.());
+  expect(screen.getByText('Translated app')).toBeTruthy();
 });
 
-it('calls back again only when the RESOLVED locale changes', () => {
+it('keeps route state mounted across a language change and ignores callback identity changes', async () => {
+  let mounts = 0;
+  function Page() {
+    React.useEffect(() => {
+      mounts += 1;
+    }, []);
+    return <span>App</span>;
+  }
   const onChange = jest.fn();
-  const { rerender } = render(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+  const config = { supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange };
+  const screen = render(
+    <LanguageBridge config={config}>
+      <Page />
+    </LanguageBridge>,
   );
-  expect(onChange).toHaveBeenCalledTimes(1);
-
-  // Same resolved locale, brand-new callback identity (the common case for an
-  // inline arrow function) — must not re-fire.
-  rerender(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={() => {}} />,
+  await waitFor(() => expect(mounts).toBe(1));
+  screen.rerender(
+    <LanguageBridge config={{ ...config, onChange: jest.fn() }}>
+      <Page />
+    </LanguageBridge>,
   );
   expect(onChange).toHaveBeenCalledTimes(1);
-
   mockCurrentLanguage = 'fr-FR';
-  rerender(
-    <LanguageBridge supportedLocales={HOST_CATALOG} fallbackLocale="en-US" onChange={onChange} />,
+  screen.rerender(
+    <LanguageBridge config={config}>
+      <Page />
+    </LanguageBridge>,
   );
-  expect(onChange).toHaveBeenCalledTimes(2);
-  expect(onChange).toHaveBeenLastCalledWith('fr-FR');
+  await waitFor(() => expect(onChange).toHaveBeenLastCalledWith('fr-FR'));
+  expect(mounts).toBe(1);
 });
 
-it('reports a rejected onChange to onError instead of throwing', async () => {
-  const failure = new Error('catalog failed to load');
-  const onChange = jest.fn().mockRejectedValue(failure);
+it('reports a failed catalog and initializes the fallback before showing children', async () => {
+  mockCurrentLanguage = 'es-ES';
+  const failure = new Error('catalog unavailable');
+  const onChange = jest.fn().mockRejectedValueOnce(failure).mockResolvedValueOnce(undefined);
   const onError = jest.fn();
-  render(
+  const screen = render(
     <LanguageBridge
-      supportedLocales={HOST_CATALOG}
-      fallbackLocale="en-US"
-      onChange={onChange}
-      onError={onError}
-    />,
+      config={{ supportedLocales: HOST_CATALOG, fallbackLocale: 'en-US', onChange, onError }}
+    >
+      <span>App</span>
+    </LanguageBridge>,
   );
-
-  await new Promise((resolve) => setTimeout(resolve, 0));
-  expect(onError).toHaveBeenCalledWith(failure, 'en-US');
+  await waitFor(() => expect(screen.getByText('App')).toBeTruthy());
+  expect(onError).toHaveBeenCalledWith(failure, 'es-ES');
+  expect(onChange.mock.calls.map(([locale]) => locale)).toEqual(['es-ES', 'en-US']);
 });

package/src/ui/components/signIn/OxySignUpPanel.tsx

@@ -67,7 +67,13 @@ export const OxySignUpPanel: React.FC<OxySignUpPanelProps> = ({
   host = 'page',
 }) => {
   const { t } = useI18n();
-  const { oxyServices, handleWebSession, accountDialogController } = useOxy();
+  const {
+    oxyServices,
+    handleWebSession,
+    accountDialogController,
+    currentLanguage,
+    campaignAttribution,
+  } = useOxy();
   const snapshot = useAccountDialogSnapshot(accountDialogController);
   const flowOwner = host === 'dialog' ? accountDialogController : null;
   const [saved] = useState(() => readSignInFlow<SavedSignUpFlow>(flowOwner, SIGN_UP_FLOW_KEY));
@@ -139,6 +145,8 @@ export const OxySignUpPanel: React.FC<OxySignUpPanelProps> = ({
         username: username.trim(),
         email,
         emailTicket: ticket,
+        languages: [currentLanguage],
+        ...(campaignAttribution ? { campaignAttribution } : {}),
       });
       await handleWebSession(session);
       writeSignInFlow(flowOwner, SIGN_UP_FLOW_KEY, undefined);

package/src/ui/context/OxyContext.tsx

@@ -62,6 +62,7 @@ import {
 import { createTokenLossRecovery, TOKEN_RECOVERY_BACKOFF_MS } from '../session/tokenLossRecovery';
 import { createCachedBootStore, type CachedBootStore } from '../session/cachedBoot';
 import { bindAuthStoreToRuntime } from '../stores/authStore';
+import { useEntryLink } from '../hooks/useEntryLink';
 import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
 import { useAuthOperations, clearPersistedAuthSafe } from './hooks/useAuthOperations';
@@ -153,6 +154,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   sessionMode = 'account',
   webAuthMode = 'popup',
   backgroundSession = false,
+  legacyLanguageKeys,
+  captureCampaignAttribution = false,
   platformStorage,
   accountQueries,
   onAuthStateChange,
@@ -415,8 +418,10 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .catch((err) => {
         // Nothing persisted can be restored; the account cache still has to
         // become ready, or RequireOxyAuth would wait forever.
-        accountQueryPersistence.setStorage(createMemoryStorage());
+        const memoryStorage = createMemoryStorage();
+        accountQueryPersistence.setStorage(memoryStorage);
         if (mounted) {
+          setStorage(memoryStorage);
           logger('Failed to initialize storage', err);
           onError?.({
             message: 'Failed to initialize storage',
@@ -430,8 +435,15 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     };
   }, [accountQueryPersistence, logger, onError, platformStorage, runtime, storageReady]);
 
+  const entryLink = useEntryLink({
+    storage,
+    storageKey: `${storageKeyPrefix}_campaign_attribution`,
+    captureCampaign: captureCampaignAttribution,
+    onError: logger,
+  });
   const {
     currentLanguage,
+    isLanguageReady,
     languages: currentLanguages,
     metadata: currentLanguageMetadata,
     languageName: currentLanguageName,
@@ -441,6 +453,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   } = useLanguageManagement({
     storage,
     languageKey: storageKeys.language,
+    entryUrl: entryLink.url,
+    entryLinkReady: entryLink.ready,
+    legacyLanguageKeys,
     user,
     onError,
     logger,
@@ -1751,6 +1766,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       webAuthMode,
       error,
       currentLanguage,
+      isLanguageReady: isLanguageReady && entryLink.campaignReady,
+      campaignAttribution: entryLink.campaignAttribution,
       currentLanguages,
       currentLanguageMetadata,
       currentLanguageName,
@@ -1808,6 +1825,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       webAuthMode,
       error,
       currentLanguage,
+      isLanguageReady,
+      entryLink.campaignReady,
+      entryLink.campaignAttribution,
       currentLanguages,
       currentLanguageMetadata,
       currentLanguageName,

package/src/ui/context/oxyContextTypes.ts

@@ -1,3 +1,4 @@
+import type { CampaignAttribution } from '@oxy.so/contracts';
 import type {
   StartNativeOAuthSignInOptions,
   NativeOAuthSignInResult,
@@ -85,6 +86,8 @@ export interface OxyContextState {
   error: string | null;
   /** Active UI locale (`language-REGION`): the account's primary locale when signed in, else the guest/device locale. */
   currentLanguage: string;
+  isLanguageReady: boolean;
+  campaignAttribution?: CampaignAttribution;
   /** Ordered account locales (primary first) when signed in, or the single guest override when signed out. */
   currentLanguages: string[];
   currentLanguageMetadata: ReturnType<typeof useLanguageManagement>['metadata'];
@@ -180,6 +183,8 @@ export interface OxyContextState {
 }
 
 export interface OxyRuntimeProviderProps {
+  legacyLanguageKeys?: readonly string[];
+  captureCampaignAttribution?: boolean;
   children: ReactNode;
   oxyServices?: OxyServices;
   baseURL?: string;

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