@payez/next-mvp 4.8.1 → 4.8.3

package/src/edge/middleware.ts

@@ -1,42 +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, isPrefetchRequest } 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';
+/**
+ * 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, isPrefetchRequest } 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

@@ -1,117 +1,117 @@
-'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 { authClient } from '@payez/next-mvp/client/better-auth-client';
- * 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 { authClient } from '../client/better-auth-client';
-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: sessionData, isPending } = authClient.useSession();
-  const session = sessionData;
-  const status = isPending ? 'loading' : session ? 'authenticated' : 'unauthenticated';
-  const router = useRouter();
-
-  const isLoading = status === 'loading';
-  const isAuthenticated = status === 'authenticated' && !!(session as any)?.accessToken;
-
-  // Handle sign out with redirect
-  const handleSignOut = useCallback(async () => {
-    await authClient.signOut();
-    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 as any)?.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 as any).accessToken!);
-          case 'POST':
-            return await standardizedApi.post<T>(url, data, (session as any).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 as any)?.accessToken, handleSignOut]
-  );
-
-  return {
-    session: session as CustomSession | null,
-    status,
-    isLoading,
-    isAuthenticated,
-    apiCall
-  };
-}
+'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 { authClient } from '@payez/next-mvp/client/better-auth-client';
+ * 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 { authClient } from '../client/better-auth-client';
+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: sessionData, isPending } = authClient.useSession();
+  const session = sessionData;
+  const status = isPending ? 'loading' : session ? 'authenticated' : 'unauthenticated';
+  const router = useRouter();
+
+  const isLoading = status === 'loading';
+  const isAuthenticated = status === 'authenticated' && !!(session as any)?.accessToken;
+
+  // Handle sign out with redirect
+  const handleSignOut = useCallback(async () => {
+    await authClient.signOut();
+    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 as any)?.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 as any).accessToken!);
+          case 'POST':
+            return await standardizedApi.post<T>(url, data, (session as any).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 as any)?.accessToken, handleSignOut]
+  );
+
+  return {
+    session: session as CustomSession | null,
+    status,
+    isLoading,
+    isAuthenticated,
+    apiCall
+  };
+}

package/src/hooks/useAuthSettings.ts

@@ -1,109 +1,109 @@
-/**
- * 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 { authClient } from '../client/better-auth-client';
-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 } = authClient.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();
-    // 257255: DELIBERATELY LEFT FAIL-CLOSED, and flagged rather than silently kept.
-    // QAPert proved any hardcoded fallback is wrong in one environment (same client
-    // is require_2fa TRUE on AKS, FALSE on dev-93), so `?? true` is not correct - it
-    // is merely the SAFE direction: it demands more auth rather than less, and
-    // flipping it to false would be fail-OPEN. The genuinely correct answer is to
-    // propagate "unknown" to the caller, which is a breaking signature change
-    // (boolean -> boolean | null) and needs its own decision. Tracked on 257255.
-    return authSettings?.require2FA ?? true;
-}
-
-/**
- * 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();
-    // 257255 / v32(a) OFFER NOTHING YOU CANNOT CONFIRM.
-    // Was `?? ['email','sms']` - a fabricated method list rendered whenever the
-    // policy could not be read. On 2026-08-24 that told users to use email+sms
-    // while the database said emailcode+totp. An empty list is the honest answer;
-    // the caller must show "we could not load sign-in options" rather than guess.
-    return authSettings?.allowed2FAMethods ?? [];
-}
-
-/**
- * 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,
-    };
-}
+/**
+ * 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 { authClient } from '../client/better-auth-client';
+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 } = authClient.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();
+    // 257255: DELIBERATELY LEFT FAIL-CLOSED, and flagged rather than silently kept.
+    // QAPert proved any hardcoded fallback is wrong in one environment (same client
+    // is require_2fa TRUE on AKS, FALSE on dev-93), so `?? true` is not correct - it
+    // is merely the SAFE direction: it demands more auth rather than less, and
+    // flipping it to false would be fail-OPEN. The genuinely correct answer is to
+    // propagate "unknown" to the caller, which is a breaking signature change
+    // (boolean -> boolean | null) and needs its own decision. Tracked on 257255.
+    return authSettings?.require2FA ?? true;
+}
+
+/**
+ * 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();
+    // 257255 / v32(a) OFFER NOTHING YOU CANNOT CONFIRM.
+    // Was `?? ['email','sms']` - a fabricated method list rendered whenever the
+    // policy could not be read. On 2026-08-24 that told users to use email+sms
+    // while the database said emailcode+totp. An empty list is the honest answer;
+    // the caller must show "we could not load sign-in options" rather than guess.
+    return authSettings?.allowed2FAMethods ?? [];
+}
+
+/**
+ * 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,
+    };
+}