@oxyhq/core 1.11.24 → 2.1.0

package/src/mixins/__tests__/popup.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Popup mixin regression tests.
+ *
+ * Locks in the §6c fix: cross-domain sign-in popups (auth.oxy.so) were being
+ * blocked by Chrome on consumer apps (mention.earth, homiio.com, alia.onl)
+ * because the caller chain awaited FedCM / silent SSO BEFORE
+ * `signInWithPopup` reached `window.open`. The transient user-activation
+ * had been consumed by the first `await`, so the popup-blocker killed the
+ * subsequent `window.open` call.
+ *
+ * The fix exposes two new affordances on the popup mixin:
+ *   1. `openBlankPopup(width?, height?)` — a public, synchronous helper that
+ *      callers invoke from the raw user-gesture handler BEFORE any await, so
+ *      the popup is opened while the activation is still live.
+ *   2. `signInWithPopup({ popup })` — accepts the pre-opened window handle
+ *      and navigates IT to the auth URL instead of issuing a fresh
+ *      `window.open` (which would now be blocked).
+ *
+ * Backward compat: callers that omit `popup` keep the legacy behaviour (the
+ * mixin opens its own popup via `openCenteredPopup`). The browser globals
+ * are stubbed so the platform-agnostic mixin can run under the node test
+ * env.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+const ORIGIN = 'https://mention.earth';
+
+interface MockPopup {
+  closed: boolean;
+  close: jest.Mock;
+  location: {
+    href: string;
+    replace: jest.Mock;
+  };
+}
+
+function createMockPopup(overrides: Partial<MockPopup> = {}): MockPopup {
+  return {
+    closed: false,
+    close: jest.fn(),
+    location: {
+      href: '',
+      replace: jest.fn(function (this: { href: string }, url: string) {
+        this.href = url;
+      }),
+    },
+    ...overrides,
+  };
+}
+
+function installBrowserGlobals(options: {
+  windowOpen?: jest.Mock;
+  postMessageDispatcher?: { current: ((event: { origin: string; data: unknown }) => void) | null };
+} = {}): void {
+  const store = new Map<string, string>();
+  const sessionStorageStub = {
+    getItem: (k: string) => (store.has(k) ? (store.get(k) as string) : null),
+    setItem: (k: string, v: string) => { store.set(k, v); },
+    removeItem: (k: string) => { store.delete(k); },
+  };
+  const messageHandlers: Array<(event: { origin: string; data: unknown }) => void> = [];
+  const win = {
+    location: { origin: ORIGIN, hostname: 'mention.earth' },
+    screenX: 0,
+    screenY: 0,
+    outerWidth: 1280,
+    outerHeight: 800,
+    sessionStorage: sessionStorageStub,
+    open: options.windowOpen ?? jest.fn(() => null),
+    addEventListener: (event: string, handler: (e: { origin: string; data: unknown }) => void) => {
+      if (event === 'message') {
+        messageHandlers.push(handler);
+        if (options.postMessageDispatcher) {
+          options.postMessageDispatcher.current = handler;
+        }
+      }
+    },
+    removeEventListener: (event: string, handler: (e: { origin: string; data: unknown }) => void) => {
+      if (event === 'message') {
+        const idx = messageHandlers.indexOf(handler);
+        if (idx >= 0) messageHandlers.splice(idx, 1);
+      }
+    },
+  };
+  (globalThis as unknown as { window: unknown }).window = win;
+  (globalThis as unknown as { sessionStorage: unknown }).sessionStorage = sessionStorageStub;
+  // `crypto.randomUUID` already exists in node 20+ test env — leave it.
+}
+
+function clearBrowserGlobals(): void {
+  for (const key of ['window', 'sessionStorage'] as const) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+}
+
+describe('OxyServices popup mixin — pre-opened popup option', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('navigates a pre-opened popup to the auth URL instead of opening a new one', async () => {
+    const windowOpen = jest.fn();
+    installBrowserGlobals({ windowOpen });
+    const popup = createMockPopup();
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Resolve `signInWithPopup` as soon as the popup is navigated — we only
+    // care about the open path, not the full postMessage round-trip.
+    let dispatchedAuthUrl: string | null = null;
+    popup.location.replace.mockImplementation(function (this: MockPopup['location'], url: string) {
+      this.href = url;
+      dispatchedAuthUrl = url;
+    });
+
+    // Fire the auth-success message immediately after navigation. We do this
+    // by intercepting `addEventListener` above.
+    const messagePromise = new Promise<void>((resolve) => {
+      // Patch addEventListener to capture the handler and dispatch a fake
+      // success message on the next microtask.
+      const origAdd = (globalThis as unknown as { window: { addEventListener: typeof window.addEventListener } }).window.addEventListener;
+      (globalThis as unknown as { window: { addEventListener: typeof window.addEventListener } }).window.addEventListener =
+        (event: string, handler: EventListenerOrEventListenerObject) => {
+          origAdd(event, handler);
+          if (event === 'message') {
+            queueMicrotask(() => {
+              // We need the state from the URL the popup was navigated to.
+              const url = new URL(dispatchedAuthUrl ?? '');
+              const state = url.searchParams.get('state') ?? '';
+              (handler as (e: { origin: string; data: unknown }) => void)({
+                origin: 'https://auth.oxy.so',
+                data: {
+                  type: 'oxy_auth_response',
+                  state,
+                  session: {
+                    sessionId: 'sess_pre_opened',
+                    deviceId: 'dev_pre',
+                    expiresAt: new Date(Date.now() + 60000).toISOString(),
+                    accessToken: 'access_pre',
+                    user: { id: 'user_pre', username: 'tester' },
+                  },
+                },
+              });
+              resolve();
+            });
+          }
+        };
+    });
+
+    const session = await oxy.signInWithPopup({ popup: popup as unknown as Window });
+    await messagePromise;
+
+    // The pre-opened popup was navigated — `window.open` was NEVER called.
+    expect(windowOpen).not.toHaveBeenCalled();
+    expect(popup.location.replace).toHaveBeenCalledTimes(1);
+    expect(popup.location.replace).toHaveBeenCalledWith(expect.stringContaining('https://auth.oxy.so/login'));
+    expect(session.sessionId).toBe('sess_pre_opened');
+  });
+
+  it('throws a "window was closed" (cancelled) error — NOT "popup blocked" — when the pre-opened handle is already closed', async () => {
+    const windowOpen = jest.fn();
+    installBrowserGlobals({ windowOpen });
+    const popup = createMockPopup({ closed: true });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // The popup DID open (the blocker allowed it) and the user closed it.
+    // The error must communicate a cancel, never a blocker rejection —
+    // consumers map "blocked" to "please allow popups" UX guidance, which
+    // would be wrong here.
+    await expect(
+      oxy.signInWithPopup({ popup: popup as unknown as Window })
+    ).rejects.toThrow(/Sign-in window was closed/);
+    await expect(
+      oxy.signInWithPopup({ popup: popup as unknown as Window })
+    ).rejects.not.toThrow(/Popup blocked/);
+
+    // Did not attempt to open a fresh popup either.
+    expect(windowOpen).not.toHaveBeenCalled();
+    expect(popup.location.replace).not.toHaveBeenCalled();
+  });
+
+  it('falls back to assigning `location.href` when `location.replace` throws (sandboxed environments)', async () => {
+    const windowOpen = jest.fn();
+    installBrowserGlobals({ windowOpen });
+
+    // Some sandboxed / cross-origin-locked environments make `location.replace`
+    // throw. The mixin must recover with a plain `href` assignment so the
+    // popup still gets navigated. This is the only path that exercises the
+    // catch-and-log branch in OxyServices.popup.ts.
+    const popup: MockPopup = {
+      closed: false,
+      close: jest.fn(),
+      location: {
+        href: '',
+        replace: jest.fn(() => {
+          throw new Error('SecurityError: replace blocked by sandbox');
+        }),
+      },
+    };
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Drive `signInWithPopup` only until the navigation happens, then abort
+    // via `closed = true` so the poll loop's cancel path resolves the promise.
+    const promise = oxy.signInWithPopup({ popup: popup as unknown as Window });
+    // Let the synchronous popup-navigation path run.
+    await Promise.resolve();
+    popup.closed = true;
+
+    await expect(promise).rejects.toThrow(/cancelled|timeout/i);
+
+    // `replace` was attempted (and threw); the fallback wrote to `href`.
+    expect(popup.location.replace).toHaveBeenCalledTimes(1);
+    expect(popup.location.href).toMatch(/^https:\/\/auth\.oxy\.so\/login/);
+    // No fresh popup was opened.
+    expect(windowOpen).not.toHaveBeenCalled();
+  });
+
+  it('falls back to opening its own popup when `popup` option is omitted (classic behaviour)', async () => {
+    const fallbackPopup = createMockPopup();
+    const windowOpen = jest.fn(() => fallbackPopup);
+    installBrowserGlobals({ windowOpen });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    // Don't actually wait for the full flow; intercept after `window.open`
+    // is called and abort.
+    const promise = oxy.signInWithPopup();
+    // Allow the synchronous `window.open` path to run.
+    await Promise.resolve();
+    fallbackPopup.closed = true; // trigger "Authentication cancelled by user"
+
+    await expect(promise).rejects.toThrow(/cancelled|timeout/i);
+
+    expect(windowOpen).toHaveBeenCalledTimes(1);
+    // The first arg is the auth URL (not 'about:blank').
+    expect((windowOpen.mock.calls[0] as unknown[])[0]).toMatch(/^https:\/\/auth\.oxy\.so\/login/);
+  });
+
+  it('throws "popup blocked" when the legacy path is used and `window.open` returns null', async () => {
+    const windowOpen = jest.fn(() => null);
+    installBrowserGlobals({ windowOpen });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    await expect(oxy.signInWithPopup()).rejects.toThrow(/Popup blocked/);
+    expect(windowOpen).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('OxyServices popup mixin — openBlankPopup helper', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('opens about:blank synchronously and returns the window handle', () => {
+    const fakePopup = createMockPopup();
+    const windowOpen = jest.fn(() => fakePopup);
+    installBrowserGlobals({ windowOpen });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const popup = oxy.openBlankPopup();
+
+    expect(windowOpen).toHaveBeenCalledTimes(1);
+    const args = windowOpen.mock.calls[0] as unknown[];
+    expect(args[0]).toBe('about:blank');
+    expect(args[1]).toBe('Oxy Sign In');
+    // Features string should include the default width/height.
+    expect(typeof args[2]).toBe('string');
+    expect(args[2] as string).toContain('width=500');
+    expect(args[2] as string).toContain('height=700');
+    expect(popup).toBe(fakePopup);
+  });
+
+  it('returns null when the browser blocks the popup', () => {
+    const windowOpen = jest.fn(() => null);
+    installBrowserGlobals({ windowOpen });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const popup = oxy.openBlankPopup();
+
+    expect(popup).toBeNull();
+  });
+
+  it('honors caller-supplied dimensions', () => {
+    const fakePopup = createMockPopup();
+    const windowOpen = jest.fn(() => fakePopup);
+    installBrowserGlobals({ windowOpen });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.openBlankPopup(640, 480);
+
+    const args = windowOpen.mock.calls[0] as unknown[];
+    expect(args[2] as string).toContain('width=640');
+    expect(args[2] as string).toContain('height=480');
+  });
+
+  it('returns null in non-browser environments', () => {
+    // No browser globals installed.
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.openBlankPopup()).toBeNull();
+  });
+});

package/src/mixins/__tests__/sessionBaseUrl.test.ts

@@ -0,0 +1,61 @@
+/**
+ * `OxyServices.getSessionBaseUrl()` resolution tests.
+ *
+ * Per the 2026 session architecture (docs/SESSION-ARCHITECTURE.md), every app
+ * keeps its OWN first-party session on its OWN domain. `getSessionBaseUrl()`
+ * is the configurable base URL the SDK's first-party session/refresh calls will
+ * target in a later phase:
+ *   - non-`oxy.so` apps point `sessionBaseUrl` at their own same-site backend
+ *     (e.g. `https://api.mention.earth`);
+ *   - `*.oxy.so` apps leave it unset so it falls back to `baseURL`
+ *     (`https://api.oxy.so`) — their behavior is unchanged.
+ *
+ * This phase is additive: the getter only surfaces configuration. It must NOT
+ * mutate token/auth state and must NOT alter `getBaseURL()`.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+describe('OxyServices.getSessionBaseUrl', () => {
+  it('falls back to baseURL when sessionBaseUrl is not configured', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    expect(oxy.getSessionBaseUrl()).toBe('https://api.oxy.so');
+    // Must equal the API base URL exactly — no divergence for *.oxy.so apps.
+    expect(oxy.getSessionBaseUrl()).toBe(oxy.getBaseURL());
+  });
+
+  it('returns the configured sessionBaseUrl when provided', () => {
+    const oxy = new OxyServices({
+      baseURL: 'https://api.oxy.so',
+      sessionBaseUrl: 'https://api.mention.earth',
+    });
+
+    expect(oxy.getSessionBaseUrl()).toBe('https://api.mention.earth');
+  });
+
+  it('does not change the API base URL when sessionBaseUrl differs', () => {
+    const oxy = new OxyServices({
+      baseURL: 'https://api.oxy.so',
+      sessionBaseUrl: 'https://api.mention.earth',
+    });
+
+    // getBaseURL (the HTTP client's request base) is independent of the
+    // session base — only the latter is overridden by config.
+    expect(oxy.getBaseURL()).toBe('https://api.oxy.so');
+    expect(oxy.getSessionBaseUrl()).not.toBe(oxy.getBaseURL());
+  });
+
+  it('is a pure read — it does not touch token/auth state', () => {
+    const oxy = new OxyServices({
+      baseURL: 'https://api.oxy.so',
+      sessionBaseUrl: 'https://api.mention.earth',
+    });
+
+    expect(oxy.hasValidToken()).toBe(false);
+    // Resolving the session base must not plant or clear any token.
+    oxy.getSessionBaseUrl();
+    expect(oxy.hasValidToken()).toBe(false);
+    expect(oxy.getAccessToken()).toBeNull();
+  });
+});

package/src/models/interfaces.ts

@@ -1,6 +1,20 @@
 export interface OxyConfig {
   baseURL: string;
   cloudURL?: string;
+  /**
+   * Base URL the SDK's first-party session/refresh calls target.
+   *
+   * Per the 2026 session architecture (docs/SESSION-ARCHITECTURE.md), every app
+   * keeps its OWN first-party session on its OWN domain. For non-`oxy.so` apps
+   * this is the app's own same-site backend (e.g. `https://api.mention.earth`),
+   * whose session bridge forwards the user's refresh credential to
+   * `api.oxy.so`. For `*.oxy.so` apps this is omitted and falls back to
+   * `baseURL` (`https://api.oxy.so`), so their behavior is unchanged.
+   *
+   * Resolve via {@link OxyServices.getSessionBaseUrl}; when unset it returns
+   * `baseURL`. This is purely additive — no refresh/auth logic reads it yet.
+   */
+  sessionBaseUrl?: string;
   authWebUrl?: string;
   authRedirectUri?: string;
   // Performance & caching options
@@ -110,9 +124,43 @@ export interface User {
   // Managed account fields
   isManagedAccount?: boolean;
   managedBy?: string;
+  // User-controlled notification preferences. All channels default to on; users
+  // opt out per-channel. Updated via `PUT /users/me`.
+  notificationPreferences?: NotificationPreferences;
+  // General app-wide user preferences. Updated via `PUT /users/me`.
+  userPreferences?: UserPreferences;
   [key: string]: unknown;
 }
 
+/**
+ * User-controlled notification channels. Persisted on the User document.
+ */
+export interface NotificationPreferences {
+  /** Push notifications on registered devices. */
+  pushEnabled?: boolean;
+  /** Periodic email digest of activity. */
+  emailDigest?: boolean;
+  /** Security/account alerts (sign-ins, recovery, key changes). */
+  securityAlerts?: boolean;
+  /** Marketing / product update emails. */
+  marketingEmails?: boolean;
+}
+
+/**
+ * General per-user preferences applied across all Oxy apps for the user.
+ * Persisted on the User document.
+ */
+export interface UserPreferences {
+  /** BCP-47 language tag, e.g. "en-US", "es-ES". Empty string = follow device. */
+  language?: string;
+  /** Theme mode preference. */
+  theme?: 'light' | 'dark' | 'system';
+  /** Mirror of OS reduce-motion preference, persisted server-side. */
+  reduceMotion?: boolean;
+  /** IANA timezone, e.g. "Europe/Madrid". Empty string = follow device. */
+  timezone?: string;
+}
+
 export interface LoginResponse {
   accessToken?: string;
   refreshToken?: string;
@@ -590,3 +638,71 @@ export interface UpdateDeviceNameResponse {
   message: string;
   deviceName: string;
 }
+
+// ---------------------------------------------------------------------------
+// Multi-account "refresh-all" (Google-style)
+// ---------------------------------------------------------------------------
+// Wire shape of `POST /auth/refresh-all`. The server rotates every device-local
+// `oxy_rt_${authuser}` cookie in parallel and returns one entry per VALID
+// account, sorted by `authuser` ascending. Slot-level errors are silently
+// omitted; the response is `{ accounts: [] }` in the worst case (no signed-in
+// accounts, all cookies expired, or origin not allowlisted).
+
+/**
+ * Minimal user shape included in a `RefreshAllAccount` entry. The server
+ * projects a small whitelist (`username name avatar email color`) so the
+ * client can render the account chooser without an extra `/users/me` round
+ * trip per account.
+ *
+ * `avatar` and `color` are `string | null` because they are stored as nullable
+ * fields in the user document.
+ */
+export interface RefreshAllAccountUser {
+  id: string;
+  username: string;
+  name?: string;
+  avatar?: string | null;
+  email?: string;
+  color?: string | null;
+}
+
+/**
+ * One rotated account entry returned by `POST /auth/refresh-all`. `authuser` is
+ * the device-local slot index (0..N-1) the cookie was bound to. The legacy
+ * un-suffixed `oxy_rt` cookie yields `authuser: null` server-side, but the SDK
+ * normalises that to `0` before exposing it (the chooser always operates on
+ * numeric indices).
+ *
+ * `user` is `null` only on the SDK-side synthesised legacy fallback (when the
+ * server is too old to support `/auth/refresh-all` and we wrap a
+ * `/auth/refresh` response — that endpoint does not project a user shape).
+ * On the modern path every accepted entry carries a non-null user.
+ */
+export interface RefreshAllAccount {
+  authuser: number;
+  accessToken: string;
+  expiresAt: string;
+  sessionId: string;
+  user: RefreshAllAccountUser | null;
+}
+
+/**
+ * Wire shape of `POST /auth/refresh-all`. Always 200 with a (possibly empty)
+ * accounts array — 401 means "no accounts signed in on this device" and is
+ * normalised to `{ accounts: [] }` at the SDK layer.
+ */
+export interface RefreshAllResponse {
+  accounts: RefreshAllAccount[];
+}
+
+/**
+ * Wire shape of `POST /auth/refresh` (single-account refresh, optionally
+ * targeting a specific `?authuser=N` slot). The server includes `authuser` in
+ * the response when an indexed slot was rotated; the legacy slot yields
+ * `authuser: null`.
+ */
+export interface RefreshCookieResponse {
+  accessToken: string;
+  expiresAt: string;
+  authuser: number | null;
+}

package/src/models/session.ts

@@ -5,6 +5,14 @@ export interface ClientSession {
   lastActive: string;
   userId?: string;
   isCurrent?: boolean;
+  /**
+   * Web-only: the device-local refresh-cookie slot index (0..N) that backs
+   * this session. Populated from `POST /auth/refresh-all` and from login /
+   * signup / fedcm-exchange responses. Required for per-session web token
+   * refresh via `refreshTokenViaCookie({ authuser })` without a bearer token.
+   * Absent on native (RN uses the bearer-protected session id directly).
+   */
+  authuser?: number;
 }
 
 export interface StorageKeys {