@payez/next-mvp 3.0.0

package/dist/hooks/usePasswordValidation.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Password Validation Hook for @payez/next-mvp
+ *
+ * Provides real-time password validation against IDP password policy.
+ * Uses debounced API calls to validate password strength.
+ */
+'use client';
+/**
+ * Password Validation Hook for @payez/next-mvp
+ *
+ * Provides real-time password validation against IDP password policy.
+ * Uses debounced API calls to validate password strength.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePasswordValidation = usePasswordValidation;
+const react_1 = require("react");
+function usePasswordValidation(options = {}) {
+    const { debounceMs = 300 } = options;
+    const [isValid, setIsValid] = (0, react_1.useState)(false);
+    const [score, setScore] = (0, react_1.useState)(0);
+    const [failedRequirements, setFailedRequirements] = (0, react_1.useState)([]);
+    const [tip, setTip] = (0, react_1.useState)(undefined);
+    const [policy, setPolicy] = (0, react_1.useState)(undefined);
+    const [isValidating, setIsValidating] = (0, react_1.useState)(false);
+    const debounceTimerRef = (0, react_1.useRef)(null);
+    const abortControllerRef = (0, react_1.useRef)(null);
+    const validatePassword = (0, react_1.useCallback)(async (password) => {
+        // Cancel any pending request
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        // Don't validate empty passwords
+        if (!password || password.length === 0) {
+            setIsValid(false);
+            setScore(0);
+            setFailedRequirements([]);
+            setTip(undefined);
+            return;
+        }
+        setIsValidating(true);
+        abortControllerRef.current = new AbortController();
+        try {
+            const response = await fetch('/api/account/validate-password', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ password }),
+                signal: abortControllerRef.current.signal,
+            });
+            const data = await response.json();
+            setIsValid(data.is_valid);
+            setScore(data.score);
+            setFailedRequirements(data.failed_requirements || []);
+            setTip(data.tip);
+            if (data.policy) {
+                setPolicy(data.policy);
+            }
+        }
+        catch (err) {
+            if (err.name !== 'AbortError') {
+                console.error('[usePasswordValidation] Error:', err);
+                // On error, assume invalid but don't block user
+                setIsValid(false);
+                setScore(0);
+                setFailedRequirements(['Unable to validate password']);
+            }
+        }
+        finally {
+            setIsValidating(false);
+        }
+    }, []);
+    const setPassword = (0, react_1.useCallback)((password) => {
+        // Clear any pending debounce
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        // Debounce the validation
+        debounceTimerRef.current = setTimeout(() => {
+            validatePassword(password);
+        }, debounceMs);
+    }, [debounceMs, validatePassword]);
+    // Cleanup on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+            if (abortControllerRef.current) {
+                abortControllerRef.current.abort();
+            }
+        };
+    }, []);
+    return {
+        setPassword,
+        isValid,
+        score,
+        failedRequirements,
+        tip,
+        policy,
+        isValidating,
+    };
+}

package/dist/hooks/useProfile.d.ts

@@ -0,0 +1,15 @@
+export type ProfileResponse = {
+    email: string;
+    user_id?: string;
+    first_name?: string;
+    last_name?: string;
+    full_name?: string;
+    phone_number?: string;
+    email_confirmed?: boolean;
+    phone_confirmed?: boolean;
+    two_factor_enabled?: boolean;
+    roles?: string[];
+    contact_information?: Record<string, any>;
+    [key: string]: any;
+};
+export declare function useProfile(): import("@tanstack/react-query").UseQueryResult<ProfileResponse, Error>;

package/dist/hooks/useProfile.js

@@ -0,0 +1,59 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useProfile = useProfile;
+/**
+ * ⚠️ WARNING: This hook cannot be used directly from the @payez/next-mvp package!
+ *
+ * @deprecated Import this hook from your local app instead
+ *
+ * **Why?** This hook depends on useAuth, which requires SessionProvider context that cannot cross package boundaries.
+ *
+ * **Solution:** Create a local version in your app (e.g., src/hooks/useProfile.ts):
+ *
+ * @example
+ * ```typescript
+ * // src/hooks/useProfile.ts (YOUR APP)
+ * 'use client';
+ * import { useQuery } from '@tanstack/react-query';
+ * import { useAuth } from './useAuth'; // Your local useAuth
+ * import { isApiSuccess } from '@payez/next-mvp/lib/standardized-client-api';
+ *
+ * export function useProfile() {
+ *   const { isAuthenticated, apiCall } = useAuth();
+ *   return useQuery({
+ *     queryKey: ['account', 'profile'],
+ *     enabled: isAuthenticated,
+ *     queryFn: async () => {
+ *       const result = await apiCall('/api/account/profile', 'GET');
+ *       if (isApiSuccess(result)) return result.data;
+ *       throw new Error(result.message);
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/payez/next-mvp/blob/main/docs/centralized-auth-api-pattern.md#usage-patterns Complete documentation}
+ */
+const react_query_1 = require("@tanstack/react-query");
+const useAuth_1 = require("./useAuth");
+const standardized_client_api_1 = require("../lib/standardized-client-api");
+function useProfile() {
+    const { isAuthenticated, apiCall } = (0, useAuth_1.useAuth)();
+    return (0, react_query_1.useQuery)({
+        queryKey: ['account', 'profile'],
+        enabled: isAuthenticated,
+        queryFn: async () => {
+            const result = await apiCall('/api/account/profile', 'GET');
+            if ((0, standardized_client_api_1.isApiSuccess)(result)) {
+                return result.data;
+            }
+            // If API returned standardized error
+            if ((0, standardized_client_api_1.isApiError)(result)) {
+                throw new Error(result.message || 'Failed to load profile');
+            }
+            throw new Error('Failed to load profile');
+        },
+        staleTime: 5 * 60 * 1000,
+    });
+}

package/dist/hooks/usePublicAuthSettings.d.ts

@@ -0,0 +1,56 @@
+/**
+ * usePublicAuthSettings Hook
+ *
+ * Fetches public auth settings for pre-login pages (signup, login).
+ * Does NOT require authentication - settings are fetched via API.
+ */
+import type { FederatedProvider } from '../types/auth';
+export interface PublicAuthSettings {
+    enabledProviders: FederatedProvider[];
+    allowPublicRegistration: boolean;
+    allowSocialLogin: boolean;
+    enablePasswordReset: boolean;
+    require2FA: boolean;
+    allowed2FAMethods: string[];
+}
+export interface UsePublicAuthSettingsResult {
+    settings: PublicAuthSettings | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Hook to fetch public auth settings for login/signup pages.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { settings, isLoading } = usePublicAuthSettings();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <>
+ *       {settings?.allowSocialLogin && (
+ *         <FederatedAuthSection providers={settings.enabledProviders} />
+ *       )}
+ *       {settings?.allowPublicRegistration && (
+ *         <EmailSignupForm />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePublicAuthSettings(): UsePublicAuthSettingsResult;
+/**
+ * Hook to check if social login is enabled.
+ */
+export declare function useSocialLoginEnabled(): boolean;
+/**
+ * Hook to check if public registration is enabled.
+ */
+export declare function usePublicRegistrationEnabled(): boolean;
+/**
+ * Hook to check if password reset is enabled.
+ */
+export declare function usePasswordResetEnabled(): boolean;

package/dist/hooks/usePublicAuthSettings.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * usePublicAuthSettings Hook
+ *
+ * Fetches public auth settings for pre-login pages (signup, login).
+ * Does NOT require authentication - settings are fetched via API.
+ */
+'use client';
+/**
+ * usePublicAuthSettings Hook
+ *
+ * Fetches public auth settings for pre-login pages (signup, login).
+ * Does NOT require authentication - settings are fetched via API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePublicAuthSettings = usePublicAuthSettings;
+exports.useSocialLoginEnabled = useSocialLoginEnabled;
+exports.usePublicRegistrationEnabled = usePublicRegistrationEnabled;
+exports.usePasswordResetEnabled = usePasswordResetEnabled;
+const react_1 = require("react");
+// Map provider strings to FederatedProvider type
+const PROVIDER_MAP = {
+    'google': 'google',
+    'apple': 'apple',
+    'facebook': 'facebook',
+    'github': 'github',
+    'microsoft': 'microsoft',
+    'azure-ad': 'microsoft',
+};
+const DEFAULT_SETTINGS = {
+    enabledProviders: [],
+    allowPublicRegistration: true,
+    allowSocialLogin: false,
+    enablePasswordReset: true,
+    require2FA: true,
+    allowed2FAMethods: ['email', 'sms'],
+};
+/**
+ * Hook to fetch public auth settings for login/signup pages.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { settings, isLoading } = usePublicAuthSettings();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <>
+ *       {settings?.allowSocialLogin && (
+ *         <FederatedAuthSection providers={settings.enabledProviders} />
+ *       )}
+ *       {settings?.allowPublicRegistration && (
+ *         <EmailSignupForm />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+function usePublicAuthSettings() {
+    const [settings, setSettings] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let mounted = true;
+        async function fetchSettings() {
+            try {
+                const response = await fetch('/api/auth/settings');
+                if (!mounted)
+                    return;
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch auth settings: ${response.status}`);
+                }
+                const data = await response.json();
+                if (data.success && data.data) {
+                    // Map provider strings to FederatedProvider type
+                    const providers = (data.data.enabledProviders || [])
+                        .map((p) => PROVIDER_MAP[p.toLowerCase()])
+                        .filter((p) => p !== undefined);
+                    setSettings({
+                        ...data.data,
+                        enabledProviders: providers,
+                    });
+                }
+                else {
+                    setSettings(DEFAULT_SETTINGS);
+                }
+                setError(null);
+            }
+            catch (err) {
+                if (!mounted)
+                    return;
+                console.warn('[usePublicAuthSettings] Failed to fetch settings:', err);
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setSettings(DEFAULT_SETTINGS);
+            }
+            finally {
+                if (mounted) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        fetchSettings();
+        return () => {
+            mounted = false;
+        };
+    }, []);
+    return { settings, isLoading, error };
+}
+/**
+ * Hook to check if social login is enabled.
+ */
+function useSocialLoginEnabled() {
+    const { settings } = usePublicAuthSettings();
+    return settings?.allowSocialLogin ?? false;
+}
+/**
+ * Hook to check if public registration is enabled.
+ */
+function usePublicRegistrationEnabled() {
+    const { settings } = usePublicAuthSettings();
+    return settings?.allowPublicRegistration ?? true;
+}
+/**
+ * Hook to check if password reset is enabled.
+ */
+function usePasswordResetEnabled() {
+    const { settings } = usePublicAuthSettings();
+    return settings?.enablePasswordReset ?? true;
+}

package/dist/hooks/useSessionExpiration.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Hook to detect and handle stale/expired sessions during 2FA flow
+ *
+ * Use this in verify-code pages to automatically redirect to login
+ * when the provisional bearer token has expired.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionExpiration } from '@payez/next-mvp/hooks/useSessionExpiration';
+ *
+ * function VerifyCodePage() {
+ *   const { data: session } = useSession();
+ *   const router = useRouter();
+ *   const searchParams = useSearchParams();
+ *   const [error, setError] = useState<string | null>(null);
+ *
+ *   const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
+ *
+ *   // Automatically handles session expiration
+ *   const sessionValid = useSessionExpiration({
+ *     session,
+ *     router,
+ *     callbackUrl,
+ *     onExpired: (message) => setError(message)
+ *   });
+ *
+ *   if (!sessionValid) return null; // Will redirect
+ *   // ... rest of component
+ * }
+ * ```
+ */
+import type { Session } from 'next-auth';
+export interface UseSessionExpirationOptions {
+    /** NextAuth session object */
+    session: Session | null | undefined;
+    /** Next.js router for navigation */
+    router: {
+        push: (url: string) => void;
+    };
+    /** URL to redirect to after login */
+    callbackUrl?: string;
+    /** Callback when session expires - use to set error state */
+    onExpired?: (message: string) => void;
+    /** Delay before redirect in milliseconds (default: 1500) */
+    redirectDelay?: number;
+    /** Custom redirect URL (default: /account-auth/login) */
+    loginUrl?: string;
+}
+/**
+ * Detects stale sessions and redirects to login
+ *
+ * Returns:
+ * - `true` if session is valid (has accessToken)
+ * - `false` if session is loading (no session yet)
+ * - `null` if session is stale (will trigger redirect)
+ */
+export declare function useSessionExpiration({ session, router, callbackUrl, onExpired, redirectDelay, loginUrl }: UseSessionExpirationOptions): boolean | null;

package/dist/hooks/useSessionExpiration.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Hook to detect and handle stale/expired sessions during 2FA flow
+ *
+ * Use this in verify-code pages to automatically redirect to login
+ * when the provisional bearer token has expired.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionExpiration } from '@payez/next-mvp/hooks/useSessionExpiration';
+ *
+ * function VerifyCodePage() {
+ *   const { data: session } = useSession();
+ *   const router = useRouter();
+ *   const searchParams = useSearchParams();
+ *   const [error, setError] = useState<string | null>(null);
+ *
+ *   const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
+ *
+ *   // Automatically handles session expiration
+ *   const sessionValid = useSessionExpiration({
+ *     session,
+ *     router,
+ *     callbackUrl,
+ *     onExpired: (message) => setError(message)
+ *   });
+ *
+ *   if (!sessionValid) return null; // Will redirect
+ *   // ... rest of component
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSessionExpiration = useSessionExpiration;
+const react_1 = require("react");
+const react_2 = require("next-auth/react");
+/**
+ * Detects stale sessions and redirects to login
+ *
+ * Returns:
+ * - `true` if session is valid (has accessToken)
+ * - `false` if session is loading (no session yet)
+ * - `null` if session is stale (will trigger redirect)
+ */
+function useSessionExpiration({ session, router, callbackUrl = '/dashboard', onExpired, redirectDelay = 1500, loginUrl = '/account-auth/login' }) {
+    (0, react_1.useEffect)(() => {
+        // If session exists but no accessToken, the token is stale/expired
+        if (session && !session.accessToken) {
+            const message = 'Your session has expired. Redirecting to login...';
+            if (onExpired) {
+                onExpired(message);
+            }
+            setTimeout(async () => {
+                // Clear the session before redirecting
+                await (0, react_2.signOut)({ redirect: false });
+                const params = new URLSearchParams({
+                    callbackUrl,
+                    error: 'SessionExpired'
+                });
+                router.push(`${loginUrl}?${params.toString()}`);
+            }, redirectDelay);
+        }
+    }, [session, router, callbackUrl, onExpired, redirectDelay, loginUrl]);
+    // Return session validity state
+    if (session && !session.accessToken) {
+        return null; // Stale session - will redirect
+    }
+    if (session?.accessToken) {
+        return true; // Valid session
+    }
+    return false; // No session yet - loading
+}

package/dist/hooks/useViabilitySession.d.ts

@@ -0,0 +1,75 @@
+/**
+ * useViabilitySession - Redis-backed session state hook
+ *
+ * This hook provides the REAL session state by consulting Redis via /api/session/viability
+ * instead of relying on the potentially stale NextAuth JWT cookie.
+ *
+ * Redis is the single source of truth. This hook:
+ * 1. Polls /api/session/viability to get actual session state from Redis
+ * 2. Returns consistent auth state across all components
+ * 3. Triggers callback when session state changes unexpectedly
+ *
+ * Usage:
+ * ```tsx
+ * const { isAuthenticated, isLoading } = useViabilitySession();
+ * ```
+ */
+export interface ViabilityState {
+    /** Whether the user is authenticated according to Redis */
+    isAuthenticated: boolean;
+    /** Whether the viability check is in progress */
+    isLoading: boolean;
+    /** Whether 2FA is required for this client */
+    requires2FA: boolean;
+    /** Whether 2FA has been completed for this session */
+    twoFactorComplete: boolean;
+    /** Whether the access token has expired (refresh may be needed) */
+    accessTokenExpired: boolean;
+    /** Whether a refresh token is available */
+    hasRefreshToken: boolean;
+    /** Error message if viability check failed */
+    error: string | null;
+    /** Timestamp of last successful viability check */
+    lastChecked: number | null;
+    /** Force a viability check now */
+    refresh: () => void;
+}
+export interface UseViabilitySessionOptions {
+    /** Polling interval in milliseconds (default: 30000 = 30 seconds) */
+    pollInterval?: number;
+    /** Whether to poll automatically (default: true) */
+    enablePolling?: boolean;
+    /** Callback when session becomes invalid */
+    onSessionInvalid?: () => void;
+}
+declare global {
+    interface Window {
+        __viabilitySessionState?: {
+            isAuthenticated: boolean;
+            isLoading: boolean;
+            requires2FA: boolean;
+            twoFactorComplete: boolean;
+            accessTokenExpired: boolean;
+            hasRefreshToken: boolean;
+            error: string | null;
+            lastChecked: number | null;
+            checkInProgress: boolean;
+            prevAuth: boolean | null;
+            intervalId: ReturnType<typeof setInterval> | null;
+            listeners: Set<() => void>;
+            onSessionInvalidCallbacks: Set<() => void>;
+        };
+    }
+}
+/**
+ * Hook that provides Redis-backed session state
+ */
+export declare function useViabilitySession(options?: UseViabilitySessionOptions): ViabilityState;
+/**
+ * Simplified hook that just returns authentication status
+ * Use this in components that only need to know if user is logged in
+ */
+export declare function useIsAuthenticated(): {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+};