@oxyhq/core 1.11.24 → 2.1.0

package/dist/esm/mixins/OxyServices.popup.js

@@ -77,7 +77,37 @@ export function OxyServicesPopupAuthMixin(Base) {
                     clientId: window.location.origin,
                     redirectUri: `${this.resolveAuthUrl()}/auth/callback`,
                 });
-                const popup = this.openCenteredPopup(authUrl, 'Oxy Sign In', width, height);
+                // If the caller pre-opened a popup on the raw user gesture (recommended
+                // path — see `openBlankPopup` and `PopupAuthOptions.popup`), navigate it
+                // to the auth URL instead of issuing a fresh `window.open` (which would
+                // be blocked once any prior `await` has consumed the user activation).
+                let popup;
+                const preOpened = options.popup ?? null;
+                if (preOpened) {
+                    if (preOpened.closed) {
+                        // The pre-opened popup is gone — distinguish a user cancel (they
+                        // closed the blank window before sign-in could navigate it) from a
+                        // blocker rejection. Lumping these together as "Popup blocked" is
+                        // misleading: the popup was NOT blocked, it was opened successfully
+                        // and then dismissed.
+                        throw new OxyAuthenticationError('Sign-in window was closed before authentication could start.');
+                    }
+                    try {
+                        preOpened.location.replace(authUrl);
+                    }
+                    catch (replaceError) {
+                        // `location.replace` can throw in sandboxed / cross-origin-locked
+                        // environments. Fall back to `href` assignment, which is more
+                        // permissive. Logged at debug-level so consumers can correlate
+                        // unusual sign-in behaviour without producing noise in normal flows.
+                        debug.warn('location.replace failed, falling back to location.href', replaceError);
+                        preOpened.location.href = authUrl;
+                    }
+                    popup = preOpened;
+                }
+                else {
+                    popup = this.openCenteredPopup(authUrl, 'Oxy Sign In', width, height);
+                }
                 if (!popup) {
                     throw new OxyAuthenticationError('Popup blocked. Please allow popups for this site and try again.');
                 }
@@ -220,6 +250,36 @@ export function OxyServicesPopupAuthMixin(Base) {
                     document.body.removeChild(iframe);
                 }
             }
+            /**
+             * Open a blank, centered popup window SYNCHRONOUSLY.
+             *
+             * Use this in a click (or other user-gesture) handler BEFORE any `await`
+             * to capture the transient user-activation. Pass the returned handle into
+             * `signInWithPopup({ popup })` once the async portion of the flow runs.
+             *
+             * Returns `null` if the browser's popup blocker rejected the open.
+             *
+             * @example
+             * ```typescript
+             * const onSignInClick = () => {
+             *   const popup = oxyServices.openBlankPopup();
+             *   (async () => {
+             *     const silent = await oxyServices.silentSignInWithFedCM();
+             *     if (silent) { popup?.close(); return; }
+             *     await oxyServices.signInWithPopup({ popup });
+             *   })();
+             * };
+             * ```
+             */
+            openBlankPopup(width, height) {
+                if (typeof window === 'undefined') {
+                    return null;
+                }
+                const ctor = this.constructor;
+                const w = width ?? ctor.POPUP_WIDTH;
+                const h = height ?? ctor.POPUP_HEIGHT;
+                return this.openCenteredPopup('about:blank', 'Oxy Sign In', w, h);
+            }
             /**
              * Open a centered popup window
              *

package/dist/esm/mixins/OxyServices.user.js

@@ -215,6 +215,24 @@ export function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Update the authenticated user's notification preferences.
+         *
+         * Thin wrapper over `updateProfile` that constrains the patch to known
+         * notification channels — same persistence path, same cache invalidation,
+         * but type-safe at the call site.
+         */
+        async updateNotificationPreferences(preferences) {
+            return this.updateProfile({ notificationPreferences: preferences });
+        }
+        /**
+         * Update the authenticated user's general preferences (language, theme,
+         * reduce-motion, timezone). Persisted on the User document via
+         * `PUT /users/me` — same cache-invalidation behaviour as `updateProfile`.
+         */
+        async updateUserPreferences(preferences) {
+            return this.updateProfile({ userPreferences: preferences });
+        }
         /**
          * Request account verification
          */

package/dist/esm/utils/accountUtils.js

@@ -108,3 +108,64 @@ export const createQuickAccount = (sessionId, userData, existingAccount, getFile
         avatarUrl,
     };
 };
+/**
+ * Merge a fresh `/auth/refresh-all` snapshot into an existing QuickAccount
+ * list, preserving any cached fields (`avatarUrl`) for slots that didn't
+ * change. The fresh response is canonical: the resulting list contains EXACTLY
+ * the slots present in `fresh`, sorted by `authuser` ascending. Stale stored
+ * accounts that no longer appear in `fresh` are dropped (the server already
+ * authoritatively cleared the corresponding cookie).
+ *
+ * @param stored Previously persisted QuickAccount list (any order).
+ * @param fresh Server's authoritative refresh-all response.
+ * @returns Canonical merged list, sorted by `authuser` asc.
+ */
+export const mergeAccountsFromRefreshAll = (stored, fresh) => {
+    const storedByAuthuser = new Map();
+    if (stored) {
+        for (const account of stored) {
+            if (typeof account.authuser === 'number') {
+                storedByAuthuser.set(account.authuser, account);
+            }
+        }
+    }
+    const merged = fresh.map((entry) => {
+        const previous = storedByAuthuser.get(entry.authuser);
+        // `entry.user` is null on the SDK legacy-fallback path; preserve any
+        // previously cached identity for that slot rather than overwriting
+        // it with blanks, and let the AuthManager's getCurrentUser() hydration
+        // refresh it on the next snapshot.
+        const wireUser = entry.user;
+        const username = wireUser?.username ?? previous?.username ?? '';
+        const displayName = getAccountDisplayName({
+            name: wireUser?.name,
+            username,
+        });
+        const avatar = wireUser?.avatar ?? previous?.avatar ?? undefined;
+        const avatarUrl = previous && previous.avatar === avatar ? previous.avatarUrl : undefined;
+        return {
+            sessionId: entry.sessionId,
+            userId: wireUser?.id ?? previous?.userId,
+            username,
+            displayName,
+            avatar,
+            avatarUrl,
+            authuser: entry.authuser,
+            color: wireUser?.color ?? previous?.color ?? null,
+        };
+    });
+    merged.sort((a, b) => {
+        const aIdx = a.authuser ?? Number.POSITIVE_INFINITY;
+        const bIdx = b.authuser ?? Number.POSITIVE_INFINITY;
+        return aIdx - bIdx;
+    });
+    return merged;
+};
+/**
+ * Return the account's preferred Bloom color preset, or `null` if it has no
+ * preference. Centralises the `color ?? null` normalisation so consumers can
+ * drive per-account theming without duplicating the nullish-handling.
+ */
+export const getAccountColor = (account) => {
+    return account.color ?? null;
+};

package/dist/esm/utils/coldBoot.js

@@ -0,0 +1,68 @@
+/**
+ * coldBoot — a pure, ordered, short-circuit runner for "cold boot"
+ * authentication resolution.
+ *
+ * On a fresh page load / app launch the SDK may have several ways to recover an
+ * existing session (silent FedCM, a persisted refresh token, a cross-domain
+ * claim, an explicit popup flow, …). They must be attempted in a *deterministic
+ * order*, and the FIRST one that yields a session wins — every later step is
+ * skipped. This module encodes exactly that contract and nothing else.
+ *
+ * Design constraints (all enforced):
+ *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
+ *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
+ *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
+ *     web bundle, which is precisely why the FedCM silent-SSO guard had to live
+ *     in consumers rather than a core singleton).
+ *   - Architecture-agnostic: both candidate cross-domain SSO designs consume
+ *     this same primitive; it knows nothing about HOW a step resolves a session.
+ *
+ * A step is skipped (without running) when its `enabled` predicate returns
+ * false. Any thrown error — from either `enabled` or `run` — is reported via
+ * `onStepError` and treated as a non-fatal skip, so one broken recovery path
+ * can never prevent a later, healthy one from succeeding.
+ */
+/**
+ * Run the ordered cold-boot steps and resolve to the first recovered session,
+ * or `unauthenticated` if none recovers one.
+ *
+ * Semantics:
+ *   1. Iterate `steps` in order.
+ *   2. If a step has an `enabled` predicate, call it inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → treat as disabled → continue.
+ *      - returns false → continue (skip, `run` not called).
+ *   3. Otherwise await `step.run()` inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → continue.
+ *      - `{ kind: 'session' }` → return `{ kind: 'session', via: step.id, session }`.
+ *      - `{ kind: 'skip' }` → continue.
+ *   4. After the loop with no winner → `{ kind: 'unauthenticated' }`.
+ */
+export async function runColdBoot(options) {
+    const { steps, onStepError } = options;
+    for (const step of steps) {
+        if (step.enabled) {
+            let isEnabled;
+            try {
+                isEnabled = step.enabled();
+            }
+            catch (error) {
+                onStepError?.(step.id, error);
+                continue;
+            }
+            if (!isEnabled)
+                continue;
+        }
+        let result;
+        try {
+            result = await step.run();
+        }
+        catch (error) {
+            onStepError?.(step.id, error);
+            continue;
+        }
+        if (result.kind === 'session') {
+            return { kind: 'session', via: step.id, session: result.session };
+        }
+    }
+    return { kind: 'unauthenticated' };
+}

package/dist/esm/utils/fapiAutoDetect.js

@@ -0,0 +1,85 @@
+/**
+ * Auto-detect the FAPI (IdP) URL from the current browser hostname.
+ *
+ * This is the canonical cross-domain IdP-resolution primitive for the Oxy
+ * ecosystem. Both candidate cross-domain SSO designs derive `auth.<rp-apex>`
+ * through this helper; do not fork it.
+ *
+ * Clerk-style multi-domain SSO depends on the IdP being reachable on a
+ * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
+ * central Oxy IdP). That way every FedCM endpoint, the session cookie,
+ * and any popup/redirect target are same-site with the RP — the only way
+ * to get first-party cookies in Safari ITP and Firefox Total Cookie
+ * Protection.
+ *
+ * This helper computes `https://auth.<rp-apex>` from
+ * `window.location.hostname` so a consuming app doesn't have to pass
+ * `authWebUrl` explicitly. Returns `undefined` for environments where
+ * auto-detection would be wrong:
+ *
+ *   - SSR / non-browser (no `window`).
+ *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
+ *   - Hostnames with fewer than two labels.
+ *   - Hostnames whose trailing two labels form a known multi-part public
+ *     suffix (e.g. `co.uk`), where the naive `labels.slice(-2)` apex would be
+ *     an attacker-registrable suffix like `auth.co.uk` rather than the real
+ *     registrable domain.
+ *
+ * When the page is already loaded ON the IdP itself (`auth.<anything>`),
+ * the helper returns the current origin so the SDK keeps everything
+ * same-origin instead of hopping to a different IdP host.
+ *
+ * The IdP backend independently derives `iss`, `provider_urls`, and the
+ * `fedcm.json` icon URLs from the request host
+ * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
+ * is required for end-to-end FedCM correctness — no per-RP config.
+ */
+/**
+ * Known multi-part public suffixes where the registrable domain is the LAST
+ * THREE labels, not two. Deriving an apex from `labels.slice(-2)` against any
+ * of these would yield an attacker-registrable suffix (e.g. `auth.co.uk`),
+ * so we bail out instead.
+ *
+ * This is intentionally a small, explicit allow-list rather than the full
+ * Public Suffix List — it covers the suffixes the Oxy ecosystem's RPs use.
+ * Any multi-part-TLD RP MUST extend this set (or wire in a proper PSL check)
+ * before relying on this helper, otherwise auto-detection silently bails to
+ * `undefined` and the consumer must pass `authWebUrl` explicitly.
+ */
+const MULTIPART_TLDS = new Set([
+    'co.uk',
+    'com.au',
+    'co.jp',
+    'co.nz',
+    'com.br',
+    'co.za',
+    'com.mx',
+    'co.in',
+    'co.kr',
+    'com.sg',
+]);
+export function autoDetectAuthWebUrl(location = typeof window !== 'undefined' ? window.location : undefined) {
+    if (!location)
+        return undefined;
+    const { hostname, protocol } = location;
+    if (!hostname)
+        return undefined;
+    if (protocol !== 'https:' && protocol !== 'http:')
+        return undefined;
+    if (hostname === 'localhost' || hostname === '127.0.0.1')
+        return undefined;
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname))
+        return undefined;
+    if (hostname.startsWith('['))
+        return undefined;
+    if (hostname.startsWith('auth.')) {
+        return `${protocol}//${hostname}`;
+    }
+    const labels = hostname.split('.');
+    if (labels.length < 2)
+        return undefined;
+    if (MULTIPART_TLDS.has(labels.slice(-2).join('.')))
+        return undefined;
+    const apex = labels.slice(-2).join('.');
+    return `${protocol}//auth.${apex}`;
+}