@spidy092/auth-client 3.0.9 → 3.1.0

package/dist/index.cjs

@@ -30,8 +30,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthProvider: () => AuthProvider,
+  PREFERENCE_DEFAULTS: () => PREFERENCE_DEFAULTS,
+  PreferencesProvider: () => PreferencesProvider,
+  applyPreferences: () => applyPreferences,
   auth: () => auth,
+  formatUserDate: () => formatUserDate,
+  formatUserNumber: () => formatUserNumber,
+  formatUserRelativeTime: () => formatUserRelativeTime,
+  getPreferences: () => getPreferences,
+  normalizePreferences: () => normalizePreferences,
+  resolveTheme: () => resolveTheme,
+  startPreferenceSync: () => startPreferenceSync,
+  subscribePreferences: () => subscribePreferences,
+  updatePreferences: () => updatePreferences,
   useAuth: () => useAuth,
+  usePreferences: () => usePreferences,
   useSessionMonitor: () => useSessionMonitor
 });
 module.exports = __toCommonJS(index_exports);
@@ -266,8 +279,8 @@ function setConfig(customConfig = {}) {
     // ✅ Auto-detect router mode
     isRouter: customConfig.isRouter || customConfig.clientKey === "account-ui"
   };
+  enableRefreshTokenPersistence(config.persistRefreshToken);
   if (config.persistRefreshToken) {
-    enableRefreshTokenPersistence(true);
     console.log("\u{1F4E6} Refresh token persistence ENABLED (localStorage on HTTPS)");
   }
   console.log(`\u{1F527} Auth Client Mode: ${config.isRouter ? "ROUTER" : "CLIENT"}`, {
@@ -283,6 +296,82 @@ function isRouterMode() {
   return config.isRouter;
 }
 
+// diagnostics.js
+var STORAGE_KEY = "auth_diagnostic_context";
+var LOGIN_LOCK_KEY = "auth_login_lock";
+var randomId = () => {
+  var _a;
+  if ((_a = globalThis.crypto) == null ? void 0 : _a.randomUUID) return globalThis.crypto.randomUUID();
+  return `auth-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+};
+var fingerprint = async (value) => {
+  var _a;
+  if (!value || !((_a = globalThis.crypto) == null ? void 0 : _a.subtle)) return null;
+  const bytes = new TextEncoder().encode(String(value));
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].slice(0, 6).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+function getDiagnosticContext() {
+  try {
+    const existing = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || "null");
+    if (existing == null ? void 0 : existing.correlationId) return existing;
+  } catch {
+  }
+  const context = { correlationId: randomId(), startedAt: Date.now() };
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(context));
+  } catch {
+  }
+  return context;
+}
+function resetDiagnosticContext() {
+  const context = { correlationId: randomId(), startedAt: Date.now() };
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(context));
+  } catch {
+  }
+  return context;
+}
+function diagnosticHeaders() {
+  const { correlationId } = getDiagnosticContext();
+  return { "X-Correlation-ID": correlationId, "X-Request-ID": correlationId };
+}
+function acquireLoginLock(clientKey, redirectUri, ttlMs = 5e3) {
+  const now = Date.now();
+  const signature = `${clientKey}|${redirectUri}`;
+  try {
+    const current = JSON.parse(sessionStorage.getItem(LOGIN_LOCK_KEY) || "null");
+    if ((current == null ? void 0 : current.signature) === signature && now - current.createdAt < ttlMs) return false;
+    sessionStorage.setItem(LOGIN_LOCK_KEY, JSON.stringify({ signature, createdAt: now }));
+  } catch {
+  }
+  return true;
+}
+function clearLoginLock() {
+  try {
+    sessionStorage.removeItem(LOGIN_LOCK_KEY);
+  } catch {
+  }
+}
+async function emitAuthDiagnostic(event, outcome, reasonCode, details = {}) {
+  const context = getDiagnosticContext();
+  const safe = {
+    eventType: "auth_client_diagnostic",
+    event,
+    outcome,
+    reasonCode,
+    correlationId: context.correlationId,
+    elapsedMs: Date.now() - context.startedAt,
+    clientKey: details.clientKey || null,
+    status: details.status || null,
+    stateFingerprint: await fingerprint(details.state),
+    online: typeof navigator === "undefined" ? null : navigator.onLine
+  };
+  const method = outcome === "FAILURE" ? "error" : outcome === "WARNING" ? "warn" : "info";
+  console[method]("[auth-client]", safe);
+  return safe;
+}
+
 // core.js
 var callbackProcessed = false;
 function login(clientKeyArg, redirectUriArg) {
@@ -295,14 +384,16 @@ function login(clientKeyArg, redirectUriArg) {
   } = getConfig();
   const clientKey = clientKeyArg || defaultClientKey;
   const redirectUri = redirectUriArg || defaultRedirectUri;
-  console.log("\u{1F504} Smart Login initiated:", {
-    mode: isRouterMode() ? "ROUTER" : "CLIENT",
-    clientKey,
-    redirectUri
-  });
   if (!clientKey || !redirectUri) {
+    emitAuthDiagnostic("LOGIN_REJECTED", "FAILURE", "CLIENT_CONFIG_MISSING", { clientKey });
     throw new Error("Missing clientKey or redirectUri");
   }
+  if (!acquireLoginLock(clientKey, redirectUri)) {
+    emitAuthDiagnostic("LOGIN_DUPLICATE_SUPPRESSED", "WARNING", "LOGIN_ALREADY_IN_PROGRESS", { clientKey });
+    return false;
+  }
+  resetDiagnosticContext();
+  emitAuthDiagnostic("LOGIN_INITIATED", "PENDING", "NONE", { clientKey });
   sessionStorage.setItem("originalApp", clientKey);
   sessionStorage.setItem("returnUrl", redirectUri);
   if (isRouterMode()) {
@@ -317,13 +408,9 @@ function routerLogin(clientKey, redirectUri) {
   if (redirectUri) {
     params.append("redirect_uri", redirectUri);
   }
+  params.append("correlation_id", getDiagnosticContext().correlationId);
   const query = params.toString();
   const backendLoginUrl = `${authBaseUrl}/login/${clientKey}${query ? `?${query}` : ""}`;
-  console.log("\u{1F3ED} Router Login: Direct backend authentication", {
-    clientKey,
-    redirectUri,
-    backendUrl: backendLoginUrl
-  });
   window.location.href = backendLoginUrl;
 }
 function clientLogin(clientKey, redirectUri) {
@@ -335,11 +422,6 @@ function clientLogin(clientKey, redirectUri) {
     params.append("redirect_uri", redirectUri);
   }
   const centralizedLoginUrl = `${accountUiUrl}/login?${params.toString()}`;
-  console.log("\u{1F504} Client Login: Redirecting to centralized login", {
-    clientKey,
-    redirectUri,
-    centralizedUrl: centralizedLoginUrl
-  });
   window.location.href = centralizedLoginUrl;
 }
 async function logout(options = {}) {
@@ -362,6 +444,7 @@ async function logout(options = {}) {
       method: "POST",
       credentials: "include",
       headers: {
+        ...diagnosticHeaders(),
         "Authorization": token ? `Bearer ${token}` : "",
         "Content-Type": "application/json"
       },
@@ -407,11 +490,19 @@ function handleCallback() {
     callbackProcessed = false;
   }
   callbackProcessed = true;
+  clearLoginLock();
   sessionStorage.removeItem("originalApp");
   sessionStorage.removeItem("returnUrl");
   if (error) {
     const errorDescription = params.get("error_description") || error;
-    throw new Error(`Authentication failed: ${errorDescription}`);
+    const authError = new Error(`Authentication failed: ${errorDescription}`);
+    authError.code = error;
+    authError.correlationId = getDiagnosticContext().correlationId;
+    emitAuthDiagnostic("CALLBACK_REJECTED", "FAILURE", error.toUpperCase(), {
+      clientKey: getConfig().clientKey,
+      state: params.get("state")
+    });
+    throw authError;
   }
   if (accessToken2) {
     setToken(accessToken2);
@@ -434,9 +525,19 @@ function handleCallback() {
     url.searchParams.delete("error_description");
     window.history.replaceState({}, "", url);
     console.log("\u2705 Callback processed successfully, token stored");
+    emitAuthDiagnostic("CALLBACK_COMPLETED", "SUCCESS", "NONE", {
+      clientKey: getConfig().clientKey,
+      state: params.get("state")
+    });
     return accessToken2;
   }
-  throw new Error("No access token found in callback URL");
+  emitAuthDiagnostic("CALLBACK_REJECTED", "FAILURE", "ACCESS_TOKEN_MISSING", {
+    clientKey: getConfig().clientKey,
+    state: params.get("state")
+  });
+  const missingTokenError = new Error("No access token found in callback URL");
+  missingTokenError.code = "ACCESS_TOKEN_MISSING";
+  throw missingTokenError;
 }
 function resetCallbackState() {
   callbackProcessed = false;
@@ -451,7 +552,7 @@ async function refreshToken() {
   }
   refreshInProgress = true;
   refreshPromise = (async () => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     try {
       const storedRefreshToken = getRefreshToken();
       console.log("\u{1F504} Refreshing token:", {
@@ -464,6 +565,7 @@ async function refreshToken() {
         credentials: "include",
         // ✅ Include httpOnly cookies (for HTTPS)
         headers: {
+          ...diagnosticHeaders(),
           "Content-Type": "application/json"
         }
       };
@@ -474,8 +576,19 @@ async function refreshToken() {
       const response = await fetch(`${authBaseUrl}/refresh/${clientKey}`, requestOptions);
       if (!response.ok) {
         const errorText = await response.text();
-        console.error("\u274C Token refresh failed:", response.status, errorText);
-        throw new Error(`Refresh failed: ${response.status}`);
+        let serverCode = null;
+        try {
+          serverCode = ((_a = JSON.parse(errorText)) == null ? void 0 : _a.error) || ((_b = JSON.parse(errorText)) == null ? void 0 : _b.code);
+        } catch {
+        }
+        emitAuthDiagnostic("TOKEN_REFRESH_REJECTED", "FAILURE", serverCode || `HTTP_${response.status}`, {
+          clientKey,
+          status: response.status
+        });
+        const refreshError = new Error(`Refresh failed: ${response.status}`);
+        refreshError.code = serverCode || `HTTP_${response.status}`;
+        refreshError.status = response.status;
+        throw refreshError;
       }
       const data = await response.json();
       const { access_token, refresh_token: new_refresh_token } = data;
@@ -488,10 +601,11 @@ async function refreshToken() {
         console.log("\u{1F504} New refresh token stored from rotation");
       }
       console.log("\u2705 Token refresh successful, listeners notified");
+      emitAuthDiagnostic("TOKEN_REFRESH_COMPLETED", "SUCCESS", "NONE", { clientKey });
       return access_token;
     } catch (err) {
       console.error("\u274C Token refresh error:", err);
-      const isAuthRejection = ((_a = err.message) == null ? void 0 : _a.includes("401")) || ((_b = err.message) == null ? void 0 : _b.includes("403")) || ((_c = err.message) == null ? void 0 : _c.includes("invalid_grant")) || ((_d = err.message) == null ? void 0 : _d.includes("Refresh failed: 4"));
+      const isAuthRejection = ((_c = err.message) == null ? void 0 : _c.includes("401")) || ((_d = err.message) == null ? void 0 : _d.includes("403")) || ((_e = err.message) == null ? void 0 : _e.includes("invalid_grant")) || ((_f = err.message) == null ? void 0 : _f.includes("Refresh failed: 4"));
       if (isAuthRejection) {
         clearToken();
         clearRefreshToken();
@@ -514,6 +628,7 @@ async function validateCurrentSession() {
     const response = await fetch(`${authBaseUrl}/account/validate-session`, {
       method: "GET",
       headers: {
+        ...diagnosticHeaders(),
         "Authorization": `Bearer ${token}`,
         "Content-Type": "application/json"
       },
@@ -766,6 +881,7 @@ api.interceptors.request.use((config2) => {
   if ((runtimeConfig == null ? void 0 : runtimeConfig.clientKey) && !config2.headers["X-Client-Key"]) {
     config2.headers["X-Client-Key"] = runtimeConfig.clientKey;
   }
+  Object.assign(config2.headers, diagnosticHeaders());
   const token = getToken();
   if (token) {
     config2.headers.Authorization = `Bearer ${token}`;
@@ -784,6 +900,10 @@ api.interceptors.response.use(
       return Promise.reject(error);
     }
     config2._retry = true;
+    emitAuthDiagnostic("API_401_REFRESH_STARTED", "PENDING", "HTTP_401", {
+      clientKey: getConfig().clientKey,
+      status: 401
+    });
     if (!refreshPromise2) {
       refreshPromise2 = refreshToken().then((newToken) => {
         refreshPromise2 = null;
@@ -843,6 +963,208 @@ function isAuthenticated() {
   return !!token && !isTokenExpired(token, 10);
 }
 
+// preferences.js
+var PREFERENCE_DEFAULTS = Object.freeze({
+  theme: "system",
+  colorScheme: "blue",
+  density: "comfortable",
+  reducedMotion: false,
+  language: "en",
+  timezone: "Etc/UTC",
+  dateFormat: "MM/DD/YYYY",
+  timeFormat: "12h",
+  highContrast: false,
+  largeText: false
+});
+var ALLOWED = {
+  theme: /* @__PURE__ */ new Set(["light", "dark", "system"]),
+  density: /* @__PURE__ */ new Set(["compact", "comfortable", "spacious"]),
+  timeFormat: /* @__PURE__ */ new Set(["12h", "24h"])
+};
+var listeners2 = /* @__PURE__ */ new Set();
+var cachedPreferences = null;
+var pendingRequest = null;
+var syncCleanup = null;
+function extractResponseData(response) {
+  var _a;
+  return ((_a = response == null ? void 0 : response.data) == null ? void 0 : _a.data) ?? (response == null ? void 0 : response.data) ?? response ?? {};
+}
+function normalizePreferences(value = {}) {
+  const next = { ...PREFERENCE_DEFAULTS };
+  for (const key of Object.keys(PREFERENCE_DEFAULTS)) {
+    if (!Object.hasOwn(value, key)) continue;
+    const candidate = value[key];
+    if (ALLOWED[key] && !ALLOWED[key].has(candidate)) continue;
+    if (typeof PREFERENCE_DEFAULTS[key] !== typeof candidate) continue;
+    next[key] = candidate;
+  }
+  return next;
+}
+function resolveTheme(theme, matchMedia2 = globalThis.matchMedia) {
+  if (theme === "dark" || theme === "light") return theme;
+  return typeof matchMedia2 === "function" && matchMedia2("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function announce(preferences2) {
+  cachedPreferences = normalizePreferences(preferences2);
+  listeners2.forEach((listener) => listener(cachedPreferences));
+  return cachedPreferences;
+}
+async function getPreferences({ force = false } = {}) {
+  if (cachedPreferences && !force) return cachedPreferences;
+  if (pendingRequest) return pendingRequest;
+  pendingRequest = api_default.get("/account/preferences").then((response) => announce(extractResponseData(response))).finally(() => {
+    pendingRequest = null;
+  });
+  return pendingRequest;
+}
+async function updatePreferences(patch) {
+  const allowedPatch = {};
+  for (const key of Object.keys(PREFERENCE_DEFAULTS)) {
+    if (Object.hasOwn(patch, key)) allowedPatch[key] = patch[key];
+  }
+  const candidate = normalizePreferences({ ...cachedPreferences || PREFERENCE_DEFAULTS, ...allowedPatch });
+  const response = await api_default.put("/account/preferences", allowedPatch);
+  const saved = extractResponseData(response);
+  return announce(Object.keys(saved).length ? saved : candidate);
+}
+function subscribePreferences(listener) {
+  listeners2.add(listener);
+  if (cachedPreferences) listener(cachedPreferences);
+  return () => listeners2.delete(listener);
+}
+function clearPreferenceCache() {
+  cachedPreferences = null;
+  pendingRequest = null;
+}
+function applyPreferences(preferences2, documentRef = globalThis.document) {
+  var _a, _b, _c;
+  if (!(documentRef == null ? void 0 : documentRef.documentElement)) return;
+  const value = normalizePreferences(preferences2);
+  const root = documentRef.documentElement;
+  const resolvedTheme = resolveTheme(value.theme, (_b = (_a = documentRef.defaultView) == null ? void 0 : _a.matchMedia) == null ? void 0 : _b.bind(documentRef.defaultView));
+  root.dataset.theme = resolvedTheme;
+  root.dataset.themePreference = value.theme;
+  root.dataset.colorScheme = value.colorScheme;
+  root.dataset.density = value.density;
+  root.lang = value.language;
+  root.style.colorScheme = resolvedTheme;
+  root.style.setProperty("--user-accent-color", {
+    blue: "#1976d2",
+    green: "#2e7d32",
+    purple: "#7b1fa2",
+    orange: "#c65d00",
+    red: "#c62828"
+  }[value.colorScheme] || "#1976d2");
+  root.classList.toggle("user-reduced-motion", value.reducedMotion);
+  root.classList.toggle("user-high-contrast", value.highContrast);
+  root.classList.toggle("user-large-text", value.largeText);
+  const styleId = "sso-user-preference-styles";
+  if (!documentRef.getElementById(styleId)) {
+    const style = documentRef.createElement("style");
+    style.id = styleId;
+    style.textContent = `
+      html.user-large-text { font-size: 112.5%; }
+      html.user-high-contrast { filter: contrast(1.15); }
+      html[data-density="compact"] { --user-density-padding: 6px; }
+      html[data-density="comfortable"] { --user-density-padding: 10px; }
+      html[data-density="spacious"] { --user-density-padding: 14px; }
+      html[data-density] .MuiListItem-root { padding-top: var(--user-density-padding); padding-bottom: var(--user-density-padding); }
+      html.user-reduced-motion *, html.user-reduced-motion *::before, html.user-reduced-motion *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        scroll-behavior: auto !important;
+        transition-duration: 0.01ms !important;
+      }
+    `;
+    (_c = documentRef.head) == null ? void 0 : _c.appendChild(style);
+  }
+}
+function startPreferenceSync({ refreshOnFocus = true } = {}) {
+  var _a, _b;
+  if (syncCleanup || typeof globalThis.addEventListener !== "function") return syncCleanup || (() => {
+  });
+  const refresh = () => {
+    if (!globalThis.document || globalThis.document.visibilityState === "visible") {
+      getPreferences({ force: true }).catch(() => {
+      });
+    }
+  };
+  const onVisibility = () => refresh();
+  (_b = (_a = globalThis.document) == null ? void 0 : _a.addEventListener) == null ? void 0 : _b.call(_a, "visibilitychange", onVisibility);
+  if (refreshOnFocus) globalThis.addEventListener("focus", refresh);
+  syncCleanup = () => {
+    var _a2, _b2;
+    (_b2 = (_a2 = globalThis.document) == null ? void 0 : _a2.removeEventListener) == null ? void 0 : _b2.call(_a2, "visibilitychange", onVisibility);
+    if (refreshOnFocus) globalThis.removeEventListener("focus", refresh);
+    syncCleanup = null;
+  };
+  return syncCleanup;
+}
+function localeFor(language) {
+  const supported = Intl.DateTimeFormat.supportedLocalesOf([language]);
+  return supported[0] || "en";
+}
+function fixedOffset(value) {
+  const match = /^UTC([+-])(\d{2}):(\d{2})$/.exec(value || "");
+  if (!match) return null;
+  const minutes = Number(match[2]) * 60 + Number(match[3]);
+  return (match[1] === "-" ? -1 : 1) * minutes;
+}
+function formatUserDate(input, preferences2 = cachedPreferences || PREFERENCE_DEFAULTS, options = {}) {
+  const value = normalizePreferences(preferences2);
+  const date = input instanceof Date ? input : new Date(input);
+  const offset = fixedOffset(value.timezone);
+  const adjusted = offset === null ? date : new Date(date.getTime() + offset * 6e4);
+  const timeZone = offset === null ? value.timezone : "UTC";
+  const hasExplicitParts = ["year", "month", "day", "weekday", "hour", "minute", "second", "dateStyle", "timeStyle"].some((key) => options[key] !== void 0);
+  const dateOptions = hasExplicitParts ? options : { year: "numeric", month: "2-digit", day: "2-digit" };
+  const formatter = new Intl.DateTimeFormat(localeFor(value.language), {
+    ...dateOptions,
+    timeZone,
+    ...dateOptions.hour || dateOptions.timeStyle ? { hour12: value.timeFormat === "12h" } : {}
+  });
+  if (!hasExplicitParts) {
+    const parts = Object.fromEntries(formatter.formatToParts(adjusted).map((part) => [part.type, part.value]));
+    if (value.dateFormat === "DD/MM/YYYY") return `${parts.day}/${parts.month}/${parts.year}`;
+    if (value.dateFormat === "YYYY-MM-DD") return `${parts.year}-${parts.month}-${parts.day}`;
+    return `${parts.month}/${parts.day}/${parts.year}`;
+  }
+  return formatter.format(adjusted);
+}
+function formatUserNumber(input, preferences2 = cachedPreferences || PREFERENCE_DEFAULTS, options = {}) {
+  const value = normalizePreferences(preferences2);
+  return new Intl.NumberFormat(localeFor(value.language), options).format(input);
+}
+function formatUserRelativeTime(input, preferences2 = cachedPreferences || PREFERENCE_DEFAULTS, now = /* @__PURE__ */ new Date()) {
+  const value = normalizePreferences(preferences2);
+  const deltaSeconds = (new Date(input).getTime() - now.getTime()) / 1e3;
+  const units = [
+    ["year", 31536e3],
+    ["month", 2592e3],
+    ["week", 604800],
+    ["day", 86400],
+    ["hour", 3600],
+    ["minute", 60],
+    ["second", 1]
+  ];
+  const [unit, seconds] = units.find(([, size]) => Math.abs(deltaSeconds) >= size) || units.at(-1);
+  return new Intl.RelativeTimeFormat(localeFor(value.language), { numeric: "auto" }).format(Math.round(deltaSeconds / seconds), unit);
+}
+var preferences = {
+  defaults: PREFERENCE_DEFAULTS,
+  get: getPreferences,
+  update: updatePreferences,
+  subscribe: subscribePreferences,
+  clearCache: clearPreferenceCache,
+  apply: applyPreferences,
+  startSync: startPreferenceSync,
+  formatDate: formatUserDate,
+  formatNumber: formatUserNumber,
+  formatRelativeTime: formatUserRelativeTime,
+  normalize: normalizePreferences,
+  resolveTheme
+};
+
 // react/AuthProvider.jsx
 var import_react = __toESM(require("react"), 1);
 var AuthContext = (0, import_react.createContext)();
@@ -906,7 +1228,8 @@ function AuthProvider({ children, onSessionExpired }) {
       console.log("\u{1F4E5} Profile response status:", res.status);
       if (!res.ok) throw new Error("Failed to fetch user");
       return res.json();
-    }).then((userData) => {
+    }).then((responseBody) => {
+      const userData = (responseBody == null ? void 0 : responseBody.data) ?? responseBody;
       console.log("\u2705 Profile fetched successfully:", userData.email);
       setUser(userData);
       setSessionValid(true);
@@ -1053,6 +1376,62 @@ var useSessionMonitor = (options = {}) => {
   };
 };
 
+// react/PreferencesProvider.jsx
+var import_react4 = __toESM(require("react"), 1);
+var PreferencesContext = (0, import_react4.createContext)(null);
+function PreferencesProvider({ children, initialPreferences, applyToDocument = true }) {
+  const [preferences2, setPreferences] = (0, import_react4.useState)(() => ({
+    ...PREFERENCE_DEFAULTS,
+    ...initialPreferences
+  }));
+  const [loading, setLoading] = (0, import_react4.useState)(true);
+  const [error, setError] = (0, import_react4.useState)(null);
+  (0, import_react4.useEffect)(() => {
+    const unsubscribe = subscribePreferences((next) => {
+      setPreferences(next);
+      setLoading(false);
+      setError(null);
+    });
+    const stopSync = startPreferenceSync();
+    getPreferences().catch((nextError) => {
+      setError(nextError);
+      setLoading(false);
+    });
+    return () => {
+      unsubscribe();
+      stopSync();
+    };
+  }, []);
+  (0, import_react4.useEffect)(() => {
+    if (applyToDocument) applyPreferences(preferences2);
+  }, [applyToDocument, preferences2]);
+  (0, import_react4.useEffect)(() => {
+    var _a;
+    if (preferences2.theme !== "system" || typeof matchMedia !== "function") return void 0;
+    const media = matchMedia("(prefers-color-scheme: dark)");
+    const applySystemTheme = () => applyPreferences(preferences2);
+    (_a = media.addEventListener) == null ? void 0 : _a.call(media, "change", applySystemTheme);
+    return () => {
+      var _a2;
+      return (_a2 = media.removeEventListener) == null ? void 0 : _a2.call(media, "change", applySystemTheme);
+    };
+  }, [preferences2]);
+  const value = (0, import_react4.useMemo)(() => ({
+    preferences: preferences2,
+    resolvedTheme: resolveTheme(preferences2.theme),
+    loading,
+    error,
+    refresh: () => getPreferences({ force: true }),
+    update: updatePreferences
+  }), [error, loading, preferences2]);
+  return /* @__PURE__ */ import_react4.default.createElement(PreferencesContext.Provider, { value }, children);
+}
+function usePreferences() {
+  const context = (0, import_react4.useContext)(PreferencesContext);
+  if (!context) throw new Error("usePreferences must be used within a PreferencesProvider");
+  return context;
+}
+
 // index.js
 var auth = {
   // 🔧 Config
@@ -1083,6 +1462,10 @@ var auth = {
   // ✅ Debug function
   // 🌐 Authenticated API client
   api: api_default,
+  preferences,
+  // 🔎 Safe authentication diagnostics
+  getDiagnosticContext,
+  emitAuthDiagnostic,
   // 🧪 Utilities
   decodeToken,
   isTokenExpired,
@@ -1130,8 +1513,21 @@ var auth = {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthProvider,
+  PREFERENCE_DEFAULTS,
+  PreferencesProvider,
+  applyPreferences,
   auth,
+  formatUserDate,
+  formatUserNumber,
+  formatUserRelativeTime,
+  getPreferences,
+  normalizePreferences,
+  resolveTheme,
+  startPreferenceSync,
+  subscribePreferences,
+  updatePreferences,
   useAuth,
+  usePreferences,
   useSessionMonitor
 });
 //# sourceMappingURL=index.cjs.map