@digitaldefiance/express-suite-react-components 2.9.37 → 2.9.38

package/src/hooks/useBackupCodes.ts

@@ -0,0 +1,105 @@
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSuiteConfig } from '../contexts';
+import { createAuthenticatedApiClient } from '../services';
+
+export interface UseBackupCodesOptions {
+  initialCodeCount?: number | null;
+}
+
+export interface UseBackupCodesResult {
+  backupCodesRemaining: number | null;
+  isLoading: boolean;
+  error: Error | null;
+  generateBackupCodes: (
+    password?: string,
+    mnemonic?: string
+  ) => Promise<{
+    message: string;
+    backupCodes: string[];
+  }>;
+  refreshCodeCount: () => Promise<void>;
+}
+
+export const useBackupCodes = (
+  options: UseBackupCodesOptions = {}
+): UseBackupCodesResult => {
+  const { baseUrl } = useSuiteConfig();
+  const [backupCodesRemaining, setBackupCodesRemaining] = useState<
+    number | null
+  >(options.initialCodeCount ?? null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const requestedOnMountRef = useRef(false);
+  const api = useMemo(() => createAuthenticatedApiClient(baseUrl), [baseUrl]);
+
+  const refreshCodeCount = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await api.get<{ codeCount: number }>('/user/backup-codes');
+      if (result?.data?.codeCount !== undefined) {
+        setBackupCodesRemaining(result.data.codeCount);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.BackupCodes_FailedToFetch
+            )
+      );
+      setBackupCodesRemaining(0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [api]);
+
+  useEffect(() => {
+    if (requestedOnMountRef.current) return;
+    if (backupCodesRemaining !== null) return;
+
+    requestedOnMountRef.current = true;
+    refreshCodeCount();
+  }, [backupCodesRemaining, refreshCodeCount]);
+
+  const generateBackupCodes = async (password?: string, mnemonic?: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await api.post<{ message: string; backupCodes: string[] }>(
+        '/user/backup-codes',
+        {
+          ...(password ? { password } : {}),
+          ...(mnemonic ? { mnemonic } : {}),
+        }
+      );
+      return {
+        message: result.data.message,
+        backupCodes: result.data.backupCodes,
+      };
+    } catch (err) {
+      const error =
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.BackupCodes_FailedToGenerate
+            );
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return {
+    backupCodesRemaining,
+    isLoading,
+    error,
+    generateBackupCodes,
+    refreshCodeCount,
+  };
+};

package/src/hooks/useEmailVerification.ts

@@ -0,0 +1,49 @@
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { useMemo, useState } from 'react';
+import { useSuiteConfig } from '../contexts';
+import { createAuthenticatedApiClient } from '../services';
+
+export interface UseEmailVerificationResult {
+  isVerifying: boolean;
+  error: Error | null;
+  verifyEmail: (
+    token: string
+  ) => Promise<{ success: boolean; message?: string }>;
+}
+
+export const useEmailVerification = (): UseEmailVerificationResult => {
+  const { baseUrl } = useSuiteConfig();
+  const api = useMemo(() => createAuthenticatedApiClient(baseUrl), [baseUrl]);
+  const [isVerifying, setIsVerifying] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const verifyEmail = async (verificationToken: string) => {
+    setIsVerifying(true);
+    setError(null);
+    try {
+      const result = await api.post<{ message: string }>('/verify-email', {
+        token: verificationToken,
+      });
+      return { success: true, message: result.data.message };
+    } catch (err: unknown) {
+      const axiosError = err as { response?: { data?: { message?: string } } };
+      const errorMessage =
+        axiosError.response?.data?.message ||
+        getSuiteCoreTranslation(SuiteCoreStringKey.Error_VerificationFailed);
+      const error = new Error(errorMessage);
+      setError(error);
+      return { success: false, message: errorMessage };
+    } finally {
+      setIsVerifying(false);
+    }
+  };
+
+  return {
+    isVerifying,
+    error,
+    verifyEmail,
+  };
+};

package/src/hooks/useExpiringValue.ts

@@ -0,0 +1,78 @@
+import { useCallback, useState } from 'react';
+
+export interface TimerInfo {
+  timeout: NodeJS.Timeout;
+  startTime: number;
+  durationMs: number;
+}
+
+export interface ExpiringValueReturn<T> {
+  value: T | undefined;
+  setValue: (newValue: T, durationSeconds?: number, saveToStorage?: boolean) => () => void;
+  clearValue: () => void;
+  getRemainingTime: () => number;
+  isActive: boolean;
+}
+
+export function useExpiringValue<T>(
+  defaultDurationSeconds: number,
+  localStorageKey?: string
+): ExpiringValueReturn<T> {
+  const [value, _setValue] = useState<T | undefined>(undefined);
+  const [timer, setTimer] = useState<TimerInfo | undefined>(undefined);
+  const [durationSeconds, _setDurationSeconds] = useState<number>(() => {
+    if (localStorageKey) {
+      const stored = localStorage.getItem(localStorageKey);
+      return stored ? parseInt(stored, 10) : defaultDurationSeconds;
+    }
+    return defaultDurationSeconds;
+  });
+
+  const getRemainingTime = useCallback((): number => {
+    if (!timer) return 0;
+    const elapsed = Date.now() - timer.startTime;
+    const remaining = Math.max(0, timer.durationMs - elapsed);
+    return Math.ceil(remaining / 1000);
+  }, [timer]);
+
+  const setValue = useCallback((newValue: T, customDurationSeconds?: number, saveToStorage?: boolean) => {
+    const finalDurationSeconds = customDurationSeconds ?? durationSeconds;
+    
+    if (saveToStorage && customDurationSeconds !== undefined && localStorageKey) {
+      _setDurationSeconds(customDurationSeconds);
+      localStorage.setItem(localStorageKey, customDurationSeconds.toString());
+    }
+    
+    _setValue(newValue);
+    
+    if (timer) {
+      clearTimeout(timer.timeout);
+    }
+    
+    const startTime = Date.now();
+    const durationMs = finalDurationSeconds * 1000;
+    const timeout = setTimeout(() => {
+      _setValue(undefined);
+      setTimer(undefined);
+    }, durationMs);
+    
+    setTimer({ timeout, startTime, durationMs });
+    
+    return () => {
+      clearTimeout(timeout);
+      setTimer(undefined);
+    };
+  }, [durationSeconds, timer, localStorageKey]);
+
+  const clearValue = useCallback(() => {
+    if (timer) {
+      clearTimeout(timer.timeout);
+      setTimer(undefined);
+    }
+    _setValue(undefined);
+  }, [timer]);
+
+  const isActive = Boolean(timer && value !== undefined);
+
+  return { value, setValue, clearValue, getRemainingTime, isActive };
+}

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,18 @@
+import { useCallback, useState } from 'react';
+import { LocalStorageManager } from '@digitaldefiance/suite-core-lib';
+
+export function useLocalStorage<T>(
+  key: string,
+  defaultValue: T
+): [T, (value: T) => void] {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    return LocalStorageManager.getValue(key, defaultValue);
+  });
+
+  const setValue = useCallback((value: T) => {
+    setStoredValue(value);
+    LocalStorageManager.setValue(key, value);
+  }, [key]);
+
+  return [storedValue, setValue];
+}

package/src/hooks/useUserSettings.ts

@@ -0,0 +1,269 @@
+import { EmailString } from '@digitaldefiance/ecies-lib';
+import {
+  CurrencyCode,
+  DefaultCurrencyCode,
+  DefaultLanguageCode,
+  DefaultTimezone,
+  Timezone,
+} from '@digitaldefiance/i18n-lib';
+import {
+  dehydrateUserSettings,
+  getSuiteCoreTranslation,
+  IUserSettings,
+  IUserSettingsDTO,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { useCallback, useEffect, useState } from 'react';
+import { useAuth, useI18n, useTheme } from '../contexts';
+
+const defaultUserSettings: Partial<IUserSettings> = {
+  darkMode: false,
+  currency: new CurrencyCode(DefaultCurrencyCode),
+  timezone: new Timezone(DefaultTimezone),
+  siteLanguage: DefaultLanguageCode,
+  directChallenge: false,
+} as const;
+
+export interface UseUserSettingsOptions {
+  authenticatedApi: {
+    post: <T = unknown>(
+      url: string,
+      data: Record<string, unknown>
+    ) => Promise<{ data: T }>;
+  };
+  isAuthenticated: boolean;
+}
+
+export interface UseUserSettingsResult {
+  currentLanguage: string;
+  changeLanguage: (languageCode: string) => Promise<void>;
+  userSettings: IUserSettings | undefined;
+  setUserSettingAndUpdateSettings: (
+    setting?: Partial<IUserSettings>
+  ) => Promise<void>;
+  toggleColorMode: () => Promise<void>;
+}
+
+/**
+ * Hook for managing user settings state and synchronization.
+ * Used by AuthProvider to handle user settings logic.
+ */
+export const useUserSettings = ({
+  authenticatedApi,
+  isAuthenticated,
+}: UseUserSettingsOptions): UseUserSettingsResult => {
+  const { setColorMode: themeSetPaletteMode, mode: currentThemeMode } =
+    useTheme();
+  const { currentLanguage, changeLanguage } = useI18n();
+  const [userSettings, setUserSettings] = useState<IUserSettings | undefined>(
+    undefined
+  );
+
+  const setUserSettingAndUpdateSettings = useCallback(
+    async (setting?: Partial<IUserSettings>) => {
+      if (setting) {
+        // Merge settings with defaults and existing settings
+        const merged = {
+          ...defaultUserSettings,
+          ...(userSettings ? userSettings : {}),
+          ...setting,
+        };
+
+        // TypeScript requires all IUserSettings fields, but during initialization
+        // some fields like email may not be set yet. We'll use Partial until
+        // all required fields are available.
+        setUserSettings(merged as IUserSettings);
+
+        if (setting.darkMode !== undefined) {
+          themeSetPaletteMode(setting.darkMode ? 'dark' : 'light');
+        }
+        if (
+          setting.siteLanguage !== undefined &&
+          setting.siteLanguage !== currentLanguage
+        ) {
+          changeLanguage(setting.siteLanguage);
+        }
+
+        // Send to server if authenticated and we have complete settings (including email)
+        if (isAuthenticated && merged.email) {
+          const dehydratedSettings = dehydrateUserSettings(
+            merged as IUserSettings
+          );
+          await authenticatedApi.post(
+            '/user/settings',
+            dehydratedSettings as unknown as Record<string, unknown>
+          );
+        }
+      } else {
+        setUserSettings(undefined);
+        themeSetPaletteMode('light');
+      }
+    },
+    [
+      isAuthenticated,
+      userSettings,
+      currentLanguage,
+      changeLanguage,
+      themeSetPaletteMode,
+      authenticatedApi,
+    ]
+  );
+
+  const changeLanguageSetting = useCallback(
+    async (languageCode: string) => {
+      await setUserSettingAndUpdateSettings({ siteLanguage: languageCode });
+    },
+    [setUserSettingAndUpdateSettings]
+  );
+
+  const toggleColorMode = useCallback(async () => {
+    // When not authenticated, read from the current theme mode
+    // When authenticated, read from userSettings (synced with server)
+    const currentDarkMode = isAuthenticated
+      ? userSettings?.darkMode ?? false
+      : currentThemeMode === 'dark';
+    await setUserSettingAndUpdateSettings({ darkMode: !currentDarkMode });
+  }, [
+    isAuthenticated,
+    userSettings?.darkMode,
+    currentThemeMode,
+    setUserSettingAndUpdateSettings,
+  ]);
+
+  return {
+    changeLanguage: changeLanguageSetting,
+    currentLanguage,
+    userSettings,
+    setUserSettingAndUpdateSettings,
+    toggleColorMode,
+  };
+};
+
+// Public-facing hook for components
+export interface UserSettingsValues extends IUserSettingsDTO {
+  [key: string]: string | boolean;
+}
+
+export interface UseUserSettingsPublicResult {
+  settings: UserSettingsValues | null;
+  isLoading: boolean;
+  error: Error | null;
+  updateSettings: (values: UserSettingsValues) => Promise<
+    | {
+        success: boolean;
+        message: string;
+      }
+    | {
+        error: string;
+        errorType?: string;
+        field?: string;
+        errors?: Array<{ path: string; msg: string }>;
+      }
+  >;
+  refreshSettings: () => Promise<void>;
+}
+
+/**
+ * Public hook for components to manage user settings.
+ * Provides a simpler API for fetching and updating settings.
+ */
+export const useUserSettingsPublic = (): UseUserSettingsPublicResult => {
+  const { userData, setUserSetting, userSettings } = useAuth();
+  const [settings, setSettings] = useState<UserSettingsValues | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refreshSettings = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      if (userSettings) {
+        const dehydratedSettings = dehydrateUserSettings(userSettings);
+        setSettings(dehydratedSettings as UserSettingsValues);
+      } else if (userData) {
+        const fallback = {
+          email: userData.email || '',
+          timezone: userData.timezone || 'UTC',
+          siteLanguage: userData.siteLanguage || 'en-US',
+          currency: userData.currency || 'USD',
+          darkMode: userData.darkMode || false,
+          directChallenge: userData.directChallenge || false,
+        };
+        setSettings(fallback);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.Settings_RetrieveFailure
+            )
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userSettings, userData]);
+
+  useEffect(() => {
+    refreshSettings();
+  }, [refreshSettings]);
+
+  const updateSettings = useCallback(
+    async (values: UserSettingsValues) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        await setUserSetting({
+          darkMode: values.darkMode,
+          currency: new CurrencyCode(values.currency),
+          timezone: new Timezone(values.timezone),
+          siteLanguage: values.siteLanguage,
+          email: new EmailString(values.email),
+          directChallenge: values.directChallenge,
+        });
+
+        setSettings(values);
+
+        return {
+          success: true,
+          message: getSuiteCoreTranslation(
+            SuiteCoreStringKey.Settings_SaveSuccess
+          ),
+        };
+      } catch (err: unknown) {
+        const axiosError = err as {
+          response?: {
+            data?: {
+              message?: string;
+              errorType?: string;
+              field?: string;
+              errors?: Array<{ path: string; msg: string }>;
+            };
+          };
+        };
+        const errorMessage =
+          axiosError.response?.data?.message ||
+          getSuiteCoreTranslation(SuiteCoreStringKey.Settings_UpdateFailed);
+        setError(err instanceof Error ? err : new Error(errorMessage));
+        return {
+          error: errorMessage,
+          errorType: axiosError.response?.data?.errorType,
+          field: axiosError.response?.data?.field,
+          errors: axiosError.response?.data?.errors,
+        };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [setUserSetting]
+  );
+
+  return {
+    settings,
+    isLoading,
+    error,
+    updateSettings,
+    refreshSettings,
+  };
+};

package/src/{index.d.ts → index.ts}

@@ -1,3 +1,4 @@
+// Export all components
 export * from './auth';
 export * from './components';
 export * from './contexts';
@@ -6,4 +7,3 @@ export * from './interfaces';
 export * from './services';
 export * from './types';
 export * from './wrappers';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/IAppConfig.ts

@@ -0,0 +1,5 @@
+export interface IAppConfig {
+  hostname: string;
+  siteTitle: string;
+  server: string;
+}

package/src/interfaces/IMenuConfig.ts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+import { IMenuOption } from './IMenuOption';
+import { createMenuType } from '../types';
+
+export interface IMenuConfig {
+  menuType: ReturnType<typeof createMenuType>;
+  menuIcon: ReactElement;
+  priority?: number;
+  options: IMenuOption[];
+  isUserMenu?: boolean;
+}

package/src/interfaces/IMenuOption.ts

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { To } from 'react-router-dom';
+import { MenuType } from '../types/MenuType';
+
+export interface IMenuOption {
+  /**
+   * Unique identifier for the menu option
+   */
+  id: string;
+  /**
+   * Text to display for the menu option
+   */
+  label: string;
+  /**
+   * Where the menu option should be displayed
+   */
+  includeOnMenus: MenuType[];
+  /**
+   * Display order for the menu option. Lower numbers are displayed first.
+   */
+  index: number;
+  /**
+   * Whether the menu option is a divider
+   */
+  divider?: boolean;
+  /**
+   * Icon to display for the menu option
+   */
+  icon?: ReactNode;
+  /**
+   * Link to navigate to when the menu option is clicked
+   * Mutually exclusive with `action`
+   * Can be a string, a react-router To object, or an object with pathname and optional state
+   */
+  link?: To | { pathname: string; state?: unknown };
+  /**
+   * Function to execute when the menu option is clicked
+   * Mutually exclusive with `link`
+   * @returns void
+   */
+  action?: () => void;
+  /**
+   * Whether the menu option requires authentication
+   * true = requires authentication
+   * false = requires unauthenticated
+   * undefined = always show
+   */
+  requiresAuth: boolean | undefined;
+  /**
+   * Custom filter function to determine if the menu option should be displayed
+   * @param option - The menu option to filter
+   * @returns boolean
+   */
+  filter?: (option: IMenuOption) => boolean;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,3 @@
+export * from './IAppConfig';
+export * from './IMenuOption';
+export * from './IMenuConfig';

package/src/services/__mocks__/authService.ts

@@ -0,0 +1,14 @@
+import { jest } from '@jest/globals';
+
+export const mockAuthService = {
+  verifyToken: jest.fn(),
+  directLogin: jest.fn(),
+  emailChallengeLogin: jest.fn(),
+  refreshToken: jest.fn(),
+  register: jest.fn(),
+  requestEmailLogin: jest.fn(),
+  backupCodeLogin: jest.fn(),
+  changePassword: jest.fn(),
+};
+
+export const createAuthService = jest.fn(() => mockAuthService);

package/src/services/api.ts

@@ -0,0 +1,13 @@
+import axios from 'axios';
+
+export function createApiClient(baseURL: string) {
+  const api = axios.create({ baseURL });
+
+  api.interceptors.request.use((config) => {
+    const languageCode = localStorage.getItem('languageCode') ?? 'en-US';
+    config.headers['Accept-Language'] = languageCode;
+    return config;
+  });
+
+  return api;
+}