@payez/next-mvp 3.0.0

package/src/edge/middleware.ts

@@ -0,0 +1,42 @@
+/**
+ * Edge Runtime Compatible Exports
+ *
+ * This module exports only Edge Runtime compatible code for use in Next.js middleware.
+ * Client-side utilities that depend on browser APIs or server-only code are excluded.
+ */
+
+// Authentication middleware and configuration (Edge Runtime compatible)
+export { makeAuthDecision } from '../auth/auth-decision';
+export {
+  isUnauthenticatedRoute,
+  configurePublicRoutes,
+  getRouteConfig,
+  configure2FABypassRoutes,
+  should2FABypass,
+  get2FABypassConfig
+} from '../auth/route-config';
+export type { UnauthenticatedRouteConfig, ProtectedRouteConfig } from '../auth/route-config';
+export { createMvpMiddleware } from '../middleware/create-middleware';
+export type {
+  MvpMiddlewareOptions,
+  CircuitBreakerProvider,
+  MiddlewareLogger,
+  AuthContext,
+  AuthAction,
+  SessionPointer,
+  SessionStatus
+} from '../middleware/create-middleware';
+
+// Two-Factor Authentication Presets (Edge Runtime compatible)
+export {
+  TwoFactorPresets,
+  AMRValues,
+  ACRLevels,
+  validateAMR,
+  validateACR,
+  checkTwoFactorRequirements
+} from '../middleware/twofa-presets';
+export type { TwoFactorRequirements, RouteConfig } from '../middleware/twofa-presets';
+
+// Internal API URL utilities for Edge Runtime
+export { getInternalApiUrl } from './internal-api-url';

package/src/hooks/useAuth.ts

@@ -0,0 +1,115 @@
+'use client';
+
+/**
+ * ⚠️ WARNING: This hook cannot be used directly from the @payez/next-mvp package!
+ *
+ * @deprecated Import this hook from your local app instead
+ *
+ * **Why?** React Context (SessionProvider) cannot cross package boundaries in file:// linked packages.
+ *
+ * **Solution:** Create a local version in your app (e.g., src/hooks/useAuth.ts) that imports standardizedApi:
+ *
+ * @example
+ * ```typescript
+ * // src/hooks/useAuth.ts (YOUR APP)
+ * 'use client';
+ * import { useSession } from 'next-auth/react';
+ * import { standardizedApi } from '@payez/next-mvp/lib/standardized-client-api';
+ *
+ * export function useAuth() {
+ *   const { data: session } = useSession(); // Works in your app context
+ *   // ... implementation
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/payez/next-mvp/blob/main/docs/centralized-auth-api-pattern.md#why-local-hooks-for-auth Complete documentation}
+ */
+
+import { useSession, signOut } from 'next-auth/react';
+import { useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import { standardizedApi, ApiResult } from '../lib/standardized-client-api';
+
+// Custom session type matching NextAuth structure
+export interface CustomSession {
+  user: {
+    id: string;
+    email: string;
+    roles?: string[];
+    twoFactorMethod?: string;
+    twoFactorSessionVerified?: boolean;
+    requiresTwoFactor?: boolean;
+  };
+  accessToken?: string;
+  refreshToken?: string;
+  expires: string;
+  error?: string;
+}
+
+export interface UseAuthResult {
+  session: CustomSession | null;
+  status: 'loading' | 'authenticated' | 'unauthenticated';
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  // API helper that automatically includes the auth token
+  apiCall: <T>(url: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', data?: any) => Promise<ApiResult<T>>;
+}
+
+export function useAuth(): UseAuthResult {
+  const { data: session, status } = useSession();
+  const router = useRouter();
+
+  const isLoading = status === 'loading';
+  const isAuthenticated = status === 'authenticated' && !!session?.accessToken;
+
+  // Handle sign out with redirect
+  const handleSignOut = useCallback(async () => {
+    await signOut({ redirect: false });
+    router.push('/account-auth/login?error=SessionExpired');
+  }, [router]);
+
+  // API helper that automatically includes the auth token and uses standardized API
+  const apiCall = useCallback(
+    async <T>(url: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'GET', data?: any): Promise<ApiResult<T>> => {
+      if (!session?.accessToken) {
+        console.error('[useAuth] No access token available');
+        throw new Error('Not authenticated');
+      }
+
+      try {
+        // Use standardized API which handles token refresh and validates response format
+        switch (method) {
+          case 'GET':
+            return await standardizedApi.get<T>(url, session.accessToken!);
+          case 'POST':
+            return await standardizedApi.post<T>(url, data, session.accessToken!);
+          case 'PUT':
+            return await standardizedApi.put<T>(url, data);
+          case 'DELETE':
+            return await standardizedApi.delete<T>(url);
+          default:
+            throw new Error(`Unsupported method: ${method}`);
+        }
+      } catch (error) {
+        console.error('[useAuth] API call failed:', error);
+
+        // standardizedApi handles token refresh internally, but if we still get auth errors, sign out
+        if (error instanceof Error && error.message.includes('Authentication failed')) {
+          console.warn('[useAuth] Authentication failed, signing out...');
+          await handleSignOut();
+        }
+
+        throw error;
+      }
+    },
+    [session?.accessToken, handleSignOut]
+  );
+
+  return {
+    session: session as CustomSession | null,
+    status,
+    isLoading,
+    isAuthenticated,
+    apiCall
+  };
+}

package/src/hooks/useAuthSettings.ts

@@ -0,0 +1,97 @@
+/**
+ * useAuthSettings Hook
+ *
+ * Client-side hook to access auth settings from the IDP config.
+ * Settings are passed through the session from server-side config.
+ */
+
+'use client';
+
+import { useSession } from 'next-auth/react';
+import type { AuthSettings } from '../lib/idp-client-config';
+
+/**
+ * Extended session type that may include authSettings
+ */
+interface SessionWithAuthSettings {
+    authSettings?: AuthSettings;
+}
+
+/**
+ * Hook to access auth settings from the session.
+ *
+ * Auth settings are populated from IDP config on the server side
+ * and included in the session for client-side access.
+ *
+ * @returns AuthSettings or null if not available
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const authSettings = useAuthSettings();
+ *
+ *   if (authSettings?.require2FA) {
+ *     return <TwoFactorPrompt />;
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+export function useAuthSettings(): AuthSettings | null {
+    const { data: session } = useSession();
+
+    if (!session) {
+        return null;
+    }
+
+    // Auth settings are included in the session from server-side config
+    const sessionWithSettings = session as unknown as SessionWithAuthSettings;
+    return sessionWithSettings.authSettings || null;
+}
+
+/**
+ * Hook to check if 2FA is required based on auth settings.
+ *
+ * @returns boolean indicating if 2FA is required
+ */
+export function useRequires2FA(): boolean {
+    const authSettings = useAuthSettings();
+    return authSettings?.require2FA ?? true; // Default to true for security
+}
+
+/**
+ * Hook to get allowed 2FA methods.
+ *
+ * @returns Array of allowed 2FA method strings (e.g., ['email', 'sms', 'totp'])
+ */
+export function useAllowed2FAMethods(): string[] {
+    const authSettings = useAuthSettings();
+    return authSettings?.allowed2FAMethods ?? ['email', 'sms'];
+}
+
+/**
+ * Hook to get session timeout settings.
+ *
+ * @returns Object with session and idle timeout minutes
+ */
+export function useSessionTimeouts(): { sessionTimeoutMinutes: number; idleTimeoutMinutes: number } {
+    const authSettings = useAuthSettings();
+    return {
+        sessionTimeoutMinutes: authSettings?.sessionTimeoutMinutes ?? 60,
+        idleTimeoutMinutes: authSettings?.idleTimeoutMinutes ?? 15,
+    };
+}
+
+/**
+ * Hook to check if remember me is allowed.
+ *
+ * @returns Object with allowRememberMe flag and rememberMeDays
+ */
+export function useRememberMeSettings(): { allowRememberMe: boolean; rememberMeDays: number } {
+    const authSettings = useAuthSettings();
+    return {
+        allowRememberMe: authSettings?.allowRememberMe ?? true,
+        rememberMeDays: authSettings?.rememberMeDays ?? 30,
+    };
+}

package/src/hooks/useAvailableProviders.ts

@@ -0,0 +1,118 @@
+/**
+ * useAvailableProviders Hook
+ *
+ * Fetches the list of OAuth providers actually configured in NextAuth.
+ * This ensures UI only shows buttons for providers that are enabled in IDP.
+ */
+
+'use client';
+
+import { useState, useEffect } from 'react';
+import { getProviders, LiteralUnion, ClientSafeProvider } from 'next-auth/react';
+import { BuiltInProviderType } from 'next-auth/providers/index';
+import type { FederatedProvider } from '../types/auth';
+
+// Map NextAuth provider IDs to our FederatedProvider type
+const PROVIDER_MAP: Record<string, FederatedProvider> = {
+    'google': 'google',
+    'apple': 'apple',
+    'facebook': 'facebook',
+    'github': 'github',
+    'azure-ad': 'microsoft',
+    'microsoft-entra-id': 'microsoft',
+};
+
+// Providers we support in UI (excludes credentials)
+const OAUTH_PROVIDERS = ['google', 'apple', 'facebook', 'github', 'azure-ad', 'microsoft-entra-id'];
+
+export interface UseAvailableProvidersResult {
+    providers: FederatedProvider[];
+    isLoading: boolean;
+    error: Error | null;
+    rawProviders: Record<LiteralUnion<BuiltInProviderType>, ClientSafeProvider> | null;
+}
+
+/**
+ * Hook to get available OAuth providers from NextAuth.
+ *
+ * Returns only the providers that are actually configured in auth-options,
+ * which reflects what's enabled in IDP config.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { providers, isLoading } = useAvailableProviders();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <FederatedAuthSection
+ *       providers={providers}
+ *       onProviderClick={handleClick}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useAvailableProviders(): UseAvailableProvidersResult {
+    const [providers, setProviders] = useState<FederatedProvider[]>([]);
+    const [rawProviders, setRawProviders] = useState<Record<LiteralUnion<BuiltInProviderType>, ClientSafeProvider> | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    useEffect(() => {
+        let mounted = true;
+
+        async function fetchProviders() {
+            try {
+                const result = await getProviders();
+
+                if (!mounted) return;
+
+                setRawProviders(result);
+
+                if (result) {
+                    // Filter to OAuth providers only (exclude credentials)
+                    // Map to our FederatedProvider type
+                    const oauthProviders = Object.keys(result)
+                        .filter(id => OAUTH_PROVIDERS.includes(id))
+                        .map(id => PROVIDER_MAP[id])
+                        .filter((p): p is FederatedProvider => p !== undefined);
+
+                    setProviders(oauthProviders);
+                } else {
+                    setProviders([]);
+                }
+
+                setError(null);
+            } catch (err) {
+                if (!mounted) return;
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setProviders([]);
+            } finally {
+                if (mounted) {
+                    setIsLoading(false);
+                }
+            }
+        }
+
+        fetchProviders();
+
+        return () => {
+            mounted = false;
+        };
+    }, []);
+
+    return { providers, isLoading, error, rawProviders };
+}
+
+/**
+ * Check if a specific provider is available.
+ *
+ * @param provider The provider to check
+ * @returns boolean indicating if provider is configured
+ */
+export function useIsProviderAvailable(provider: FederatedProvider): boolean {
+    const { providers } = useAvailableProviders();
+    return providers.includes(provider);
+}

package/src/hooks/usePasswordValidation.ts

@@ -0,0 +1,127 @@
+/**
+ * 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';
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+interface PasswordPolicy {
+  min_length?: number;
+  require_uppercase?: boolean;
+  require_lowercase?: boolean;
+  require_digit?: boolean;
+  require_special?: boolean;
+  min_strength_score?: number;
+}
+
+interface ValidationResult {
+  is_valid: boolean;
+  score: number;
+  failed_requirements: string[];
+  tip?: string;
+  policy?: PasswordPolicy;
+}
+
+interface UsePasswordValidationOptions {
+  debounceMs?: number;
+}
+
+export function usePasswordValidation(options: UsePasswordValidationOptions = {}) {
+  const { debounceMs = 300 } = options;
+
+  const [isValid, setIsValid] = useState(false);
+  const [score, setScore] = useState(0);
+  const [failedRequirements, setFailedRequirements] = useState<string[]>([]);
+  const [tip, setTip] = useState<string | undefined>(undefined);
+  const [policy, setPolicy] = useState<PasswordPolicy | undefined>(undefined);
+  const [isValidating, setIsValidating] = useState(false);
+
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  const validatePassword = useCallback(async (password: string) => {
+    // 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: ValidationResult = 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: any) {
+      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 = useCallback((password: string) => {
+    // Clear any pending debounce
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current);
+    }
+
+    // Debounce the validation
+    debounceTimerRef.current = setTimeout(() => {
+      validatePassword(password);
+    }, debounceMs);
+  }, [debounceMs, validatePassword]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+    };
+  }, []);
+
+  return {
+    setPassword,
+    isValid,
+    score,
+    failedRequirements,
+    tip,
+    policy,
+    isValidating,
+  };
+}

package/src/hooks/useProfile.ts

@@ -0,0 +1,75 @@
+'use client';
+
+/**
+ * ⚠️ 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}
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import { useAuth } from './useAuth';
+import { isApiSuccess, isApiError } from '../lib/standardized-client-api';
+
+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 function useProfile() {
+  const { isAuthenticated, apiCall } = useAuth();
+
+  return useQuery<ProfileResponse, Error>({
+    queryKey: ['account', 'profile'],
+    enabled: isAuthenticated,
+    queryFn: async () => {
+      const result = await apiCall<ProfileResponse>('/api/account/profile', 'GET');
+      if (isApiSuccess(result)) {
+        return result.data;
+      }
+      // If API returned standardized error
+      if (isApiError(result)) {
+        throw new Error(result.message || 'Failed to load profile');
+      }
+      throw new Error('Failed to load profile');
+    },
+    staleTime: 5 * 60 * 1000,
+  });
+}