@payez/next-mvp 3.0.0

package/dist/hooks/useViabilitySession.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * 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();
+ * ```
+ */
+'use client';
+/**
+ * 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();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useViabilitySession = useViabilitySession;
+exports.useIsAuthenticated = useIsAuthenticated;
+const react_1 = require("react");
+const react_2 = require("next-auth/react");
+function getGlobalState() {
+    if (typeof window === 'undefined') {
+        // SSR - return default state
+        return {
+            isAuthenticated: false,
+            isLoading: true,
+            requires2FA: false,
+            twoFactorComplete: false,
+            accessTokenExpired: false,
+            hasRefreshToken: false,
+            error: null,
+            lastChecked: null,
+            checkInProgress: false,
+            prevAuth: null,
+            intervalId: null,
+            listeners: new Set(),
+            onSessionInvalidCallbacks: new Set()
+        };
+    }
+    // Initialize global state on window if not present
+    if (!window.__viabilitySessionState) {
+        window.__viabilitySessionState = {
+            isAuthenticated: false,
+            isLoading: true,
+            requires2FA: false,
+            twoFactorComplete: false,
+            accessTokenExpired: false,
+            hasRefreshToken: false,
+            error: null,
+            lastChecked: null,
+            checkInProgress: false,
+            prevAuth: null,
+            intervalId: null,
+            listeners: new Set(),
+            onSessionInvalidCallbacks: new Set()
+        };
+    }
+    return window.__viabilitySessionState;
+}
+async function doViabilityCheck() {
+    const state = getGlobalState();
+    // Prevent concurrent checks
+    if (state.checkInProgress)
+        return;
+    state.checkInProgress = true;
+    try {
+        const response = await fetch('/api/session/viability', {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json',
+                'Cache-Control': 'no-store'
+            },
+            credentials: 'include'
+        });
+        if (!response.ok) {
+            state.isLoading = false;
+            state.error = `Viability check failed: ${response.status}`;
+            state.lastChecked = Date.now();
+            notifyListeners();
+            return;
+        }
+        const data = await response.json();
+        // Detect auth state change
+        if (state.prevAuth !== null && state.prevAuth !== data.authenticated) {
+            console.log('[useViabilitySession] Auth state changed:', {
+                was: state.prevAuth,
+                now: data.authenticated
+            });
+            if (!data.authenticated) {
+                // Notify all callbacks
+                state.onSessionInvalidCallbacks.forEach(cb => {
+                    try {
+                        cb();
+                    }
+                    catch (e) {
+                        console.error('[useViabilitySession] onSessionInvalid error:', e);
+                    }
+                });
+            }
+        }
+        state.prevAuth = data.authenticated;
+        state.isAuthenticated = data.authenticated;
+        state.isLoading = false;
+        state.requires2FA = data.requires2FA ?? false;
+        state.twoFactorComplete = data.twoFactorComplete ?? false;
+        state.accessTokenExpired = data.accessTokenExpired ?? false;
+        state.hasRefreshToken = data.hasRefreshToken ?? false;
+        state.error = null;
+        state.lastChecked = Date.now();
+        notifyListeners();
+    }
+    catch (error) {
+        console.error('[useViabilitySession] Error checking viability:', error);
+        const state = getGlobalState();
+        state.isLoading = false;
+        state.error = error instanceof Error ? error.message : 'Unknown error';
+        state.lastChecked = Date.now();
+        notifyListeners();
+    }
+    finally {
+        getGlobalState().checkInProgress = false;
+    }
+}
+function notifyListeners() {
+    const state = getGlobalState();
+    state.listeners.forEach(listener => {
+        try {
+            listener();
+        }
+        catch (e) { /* ignore */ }
+    });
+}
+function startPolling(interval) {
+    const state = getGlobalState();
+    if (state.intervalId !== null)
+        return; // Already polling
+    state.intervalId = setInterval(() => {
+        doViabilityCheck();
+    }, interval);
+}
+function stopPolling() {
+    const state = getGlobalState();
+    if (state.intervalId !== null) {
+        clearInterval(state.intervalId);
+        state.intervalId = null;
+    }
+}
+/**
+ * Hook that provides Redis-backed session state
+ */
+function useViabilitySession(options = {}) {
+    const { pollInterval = 30000, enablePolling = true, onSessionInvalid } = options;
+    const { status: nextAuthStatus } = (0, react_2.useSession)();
+    const [, forceUpdate] = (0, react_1.useState)(0);
+    const mountedRef = (0, react_1.useRef)(true);
+    const initializedRef = (0, react_1.useRef)(false);
+    // Register this component's onSessionInvalid callback
+    (0, react_1.useEffect)(() => {
+        if (onSessionInvalid) {
+            const state = getGlobalState();
+            state.onSessionInvalidCallbacks.add(onSessionInvalid);
+            return () => {
+                state.onSessionInvalidCallbacks.delete(onSessionInvalid);
+            };
+        }
+    }, [onSessionInvalid]);
+    // Subscribe to global state changes
+    (0, react_1.useEffect)(() => {
+        mountedRef.current = true;
+        const listener = () => {
+            if (mountedRef.current) {
+                forceUpdate(n => n + 1);
+            }
+        };
+        const state = getGlobalState();
+        state.listeners.add(listener);
+        return () => {
+            mountedRef.current = false;
+            state.listeners.delete(listener);
+        };
+    }, []);
+    // Initial check when NextAuth status is determined - only once!
+    (0, react_1.useEffect)(() => {
+        if (nextAuthStatus === 'loading') {
+            return;
+        }
+        const state = getGlobalState();
+        // Only do initial check once globally
+        if (!initializedRef.current && state.lastChecked === null) {
+            initializedRef.current = true;
+            doViabilityCheck();
+        }
+    }, [nextAuthStatus]);
+    // Manage polling - only one interval for all hook instances
+    (0, react_1.useEffect)(() => {
+        if (!enablePolling || nextAuthStatus === 'loading') {
+            return;
+        }
+        // Start polling if not already started
+        startPolling(pollInterval);
+        // Cleanup: only stop if this is the last listener
+        return () => {
+            const state = getGlobalState();
+            // Small delay to allow other components to register
+            setTimeout(() => {
+                if (state.listeners.size === 0) {
+                    stopPolling();
+                }
+            }, 100);
+        };
+    }, [enablePolling, pollInterval, nextAuthStatus]);
+    // Check viability on focus (user returns to tab) - with debounce
+    (0, react_1.useEffect)(() => {
+        const handleFocus = () => {
+            const state = getGlobalState();
+            // Debounce: only check if last check was > 10 seconds ago
+            if (state.lastChecked !== null &&
+                Date.now() - state.lastChecked > 10000) {
+                doViabilityCheck();
+            }
+        };
+        window.addEventListener('focus', handleFocus);
+        return () => window.removeEventListener('focus', handleFocus);
+    }, []);
+    // Return current state
+    const state = getGlobalState();
+    return {
+        isAuthenticated: state.isAuthenticated,
+        isLoading: state.isLoading,
+        requires2FA: state.requires2FA,
+        twoFactorComplete: state.twoFactorComplete,
+        accessTokenExpired: state.accessTokenExpired,
+        hasRefreshToken: state.hasRefreshToken,
+        error: state.error,
+        lastChecked: state.lastChecked,
+        refresh: doViabilityCheck
+    };
+}
+/**
+ * Simplified hook that just returns authentication status
+ * Use this in components that only need to know if user is logged in
+ */
+function useIsAuthenticated() {
+    const { isAuthenticated, isLoading } = useViabilitySession({
+        pollInterval: 60000, // Less frequent polling for simple status
+        enablePolling: true
+    });
+    return { isAuthenticated, isLoading };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { fetchWithAuth } from './client/fetch-with-auth';
+export { useAnonSession } from './client/useAnonSession';
+export type { AnonPreferences, AnonMetrics, AnonSession, UseAnonSessionReturn } from './client/useAnonSession';
+export { AuthProvider, useAuthConfig, useAuthMode, useFederatedProviders, useFederatedAuthEnabled, useTraditionalAuthEnabled } from './client/AuthContext';
+export type { AuthConfig } from './types/auth';
+export { makeAuthDecision } from './auth/auth-decision';
+export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+export { createMvpMiddleware } from './middleware/create-middleware';
+export { UserAvatarMenu } from './components/account';
+export type { UserAvatarMenuProps } from './components/account';
+export { ErrorMetricsCard, HealthMetricsCard, AuditLogViewer, AdminAnalyticsLayout, useErrorMetrics, useHealthMetrics, useAuditLog, useAdminAnalytics, getErrorMetrics, getHealthMetrics, writeAuditLog, queryAuditLog, } from './logging';
+export type { ErrorMetrics, HealthMetrics, AuditLogEntry, AuditLogQuery, AuditLogResponse, TimeRange, RouteError, LevelCount, CategoryCount, ErrorDetail, EndpointHealth, SlowRequest, } from './logging';

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+// Type augmentation for NextAuth - included via ambient module declaration
+// Note: Type declarations are picked up automatically via tsconfig.json, no explicit import needed
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
+// NOTE: Server-only exports are NOT exported from the root to prevent bundling Node.js modules in client code.
+// Server-side code should import from subpath exports:
+// - Session management: import { sessionStore } from '@payez/next-mvp/lib/session-store'
+// - Redis client: import { redis } from '@payez/next-mvp/lib/redis'
+// - Token expiry: import { computeTokenExpiries } from '@payez/next-mvp/lib/token-expiry'
+// - Refresh validation: import { validateRefreshToken } from '@payez/next-mvp/lib/refresh-token-validator'
+// - Auth options: import { authOptions } from '@payez/next-mvp/auth/auth-options'
+// - Auth handler: import { createAuthHandler } from '@payez/next-mvp/api/auth-handler'
+// Client-safe exports only
+// Client-side utilities
+var fetch_with_auth_1 = require("./client/fetch-with-auth");
+Object.defineProperty(exports, "fetchWithAuth", { enumerable: true, get: function () { return fetch_with_auth_1.fetchWithAuth; } });
+// Anonymous session hook (for pre-login preferences like theme)
+var useAnonSession_1 = require("./client/useAnonSession");
+Object.defineProperty(exports, "useAnonSession", { enumerable: true, get: function () { return useAnonSession_1.useAnonSession; } });
+// Authentication Context and Hooks
+var AuthContext_1 = require("./client/AuthContext");
+Object.defineProperty(exports, "AuthProvider", { enumerable: true, get: function () { return AuthContext_1.AuthProvider; } });
+Object.defineProperty(exports, "useAuthConfig", { enumerable: true, get: function () { return AuthContext_1.useAuthConfig; } });
+Object.defineProperty(exports, "useAuthMode", { enumerable: true, get: function () { return AuthContext_1.useAuthMode; } });
+Object.defineProperty(exports, "useFederatedProviders", { enumerable: true, get: function () { return AuthContext_1.useFederatedProviders; } });
+Object.defineProperty(exports, "useFederatedAuthEnabled", { enumerable: true, get: function () { return AuthContext_1.useFederatedAuthEnabled; } });
+Object.defineProperty(exports, "useTraditionalAuthEnabled", { enumerable: true, get: function () { return AuthContext_1.useTraditionalAuthEnabled; } });
+// Route configuration (client-safe)
+var auth_decision_1 = require("./auth/auth-decision");
+Object.defineProperty(exports, "makeAuthDecision", { enumerable: true, get: function () { return auth_decision_1.makeAuthDecision; } });
+var route_config_1 = require("./auth/route-config");
+Object.defineProperty(exports, "isUnauthenticatedRoute", { enumerable: true, get: function () { return route_config_1.isUnauthenticatedRoute; } });
+Object.defineProperty(exports, "configurePublicRoutes", { enumerable: true, get: function () { return route_config_1.configurePublicRoutes; } });
+Object.defineProperty(exports, "getRouteConfig", { enumerable: true, get: function () { return route_config_1.getRouteConfig; } });
+var create_middleware_1 = require("./middleware/create-middleware");
+Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
+// Account Components
+var account_1 = require("./components/account");
+Object.defineProperty(exports, "UserAvatarMenu", { enumerable: true, get: function () { return account_1.UserAvatarMenu; } });
+// Admin Logging & Analytics (client-side components and hooks)
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "ErrorMetricsCard", { enumerable: true, get: function () { return logging_1.ErrorMetricsCard; } });
+Object.defineProperty(exports, "HealthMetricsCard", { enumerable: true, get: function () { return logging_1.HealthMetricsCard; } });
+Object.defineProperty(exports, "AuditLogViewer", { enumerable: true, get: function () { return logging_1.AuditLogViewer; } });
+Object.defineProperty(exports, "AdminAnalyticsLayout", { enumerable: true, get: function () { return logging_1.AdminAnalyticsLayout; } });
+Object.defineProperty(exports, "useErrorMetrics", { enumerable: true, get: function () { return logging_1.useErrorMetrics; } });
+Object.defineProperty(exports, "useHealthMetrics", { enumerable: true, get: function () { return logging_1.useHealthMetrics; } });
+Object.defineProperty(exports, "useAuditLog", { enumerable: true, get: function () { return logging_1.useAuditLog; } });
+Object.defineProperty(exports, "useAdminAnalytics", { enumerable: true, get: function () { return logging_1.useAdminAnalytics; } });
+Object.defineProperty(exports, "getErrorMetrics", { enumerable: true, get: function () { return logging_1.getErrorMetrics; } });
+Object.defineProperty(exports, "getHealthMetrics", { enumerable: true, get: function () { return logging_1.getHealthMetrics; } });
+Object.defineProperty(exports, "writeAuditLog", { enumerable: true, get: function () { return logging_1.writeAuditLog; } });
+Object.defineProperty(exports, "queryAuditLog", { enumerable: true, get: function () { return logging_1.queryAuditLog; } });

package/dist/lib/anon-session.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Anonymous Session Store for `@payez/next-mvp`
+ *
+ * Provides Redis-backed anonymous sessions for tracking user preferences
+ * before they log in. When a user logs in, their anonymous session can be
+ * merged into their authenticated session.
+ *
+ * Key features:
+ * - Generates a unique visitor ID on first visit
+ * - Stores preferences (theme, locale, etc.) in Redis
+ * - Tracks usage metrics (resume count for free tier, etc.)
+ * - Provides merge functionality when user authenticates
+ */
+export declare const ANON_COOKIE_NAME: string;
+export interface AnonSessionPreferences {
+    theme?: string;
+    locale?: string;
+    [key: string]: any;
+}
+export interface AnonSessionMetrics {
+    resumeGenerationCount?: number;
+    firstVisit?: number;
+    lastVisit?: number;
+    visitCount?: number;
+    [key: string]: any;
+}
+export interface AnonSessionData {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    preferences: AnonSessionPreferences;
+    metrics: AnonSessionMetrics;
+}
+/**
+ * Generates a new anonymous session ID
+ */
+export declare function generateAnonId(): string;
+/**
+ * Creates a new anonymous session in Redis
+ */
+export declare function createAnonSession(anonId?: string): Promise<AnonSessionData>;
+/**
+ * Retrieves an anonymous session from Redis
+ */
+export declare function getAnonSession(anonId: string): Promise<AnonSessionData | null>;
+/**
+ * Gets or creates an anonymous session
+ */
+export declare function getOrCreateAnonSession(anonId?: string): Promise<AnonSessionData>;
+/**
+ * Saves an anonymous session to Redis
+ */
+export declare function saveAnonSession(session: AnonSessionData): Promise<void>;
+/**
+ * Updates preferences in an anonymous session
+ */
+export declare function updateAnonPreferences(anonId: string, preferences: Partial<AnonSessionPreferences>): Promise<AnonSessionData | null>;
+/**
+ * Updates metrics in an anonymous session
+ */
+export declare function updateAnonMetrics(anonId: string, metrics: Partial<AnonSessionMetrics>): Promise<AnonSessionData | null>;
+/**
+ * Increments a numeric metric
+ */
+export declare function incrementAnonMetric(anonId: string, metricName: string, amount?: number): Promise<number>;
+/**
+ * Deletes an anonymous session
+ */
+export declare function deleteAnonSession(anonId: string): Promise<void>;
+/**
+ * Merges anonymous session data into user profile data
+ * Call this when a user logs in to preserve their pre-login preferences
+ */
+export declare function mergeAnonSessionToUser(anonId: string, userId: string, mergeCallback?: (anonData: AnonSessionData, userId: string) => Promise<void>): Promise<AnonSessionData | null>;

package/dist/lib/anon-session.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Anonymous Session Store for `@payez/next-mvp`
+ *
+ * Provides Redis-backed anonymous sessions for tracking user preferences
+ * before they log in. When a user logs in, their anonymous session can be
+ * merged into their authenticated session.
+ *
+ * Key features:
+ * - Generates a unique visitor ID on first visit
+ * - Stores preferences (theme, locale, etc.) in Redis
+ * - Tracks usage metrics (resume count for free tier, etc.)
+ * - Provides merge functionality when user authenticates
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANON_COOKIE_NAME = void 0;
+exports.generateAnonId = generateAnonId;
+exports.createAnonSession = createAnonSession;
+exports.getAnonSession = getAnonSession;
+exports.getOrCreateAnonSession = getOrCreateAnonSession;
+exports.saveAnonSession = saveAnonSession;
+exports.updateAnonPreferences = updateAnonPreferences;
+exports.updateAnonMetrics = updateAnonMetrics;
+exports.incrementAnonMetric = incrementAnonMetric;
+exports.deleteAnonSession = deleteAnonSession;
+exports.mergeAnonSessionToUser = mergeAnonSessionToUser;
+const redis_1 = __importDefault(require("./redis"));
+const crypto_1 = require("crypto");
+const app_slug_1 = require("./app-slug");
+// Use app-slug prefixes for multi-app isolation
+const getAnonKey = (id) => `${(0, app_slug_1.getAnonPrefix)()}${id}`;
+const ANON_SESSION_TTL = 90 * 24 * 60 * 60; // 90 days in seconds
+// Export dynamic cookie name getter for external use
+exports.ANON_COOKIE_NAME = (0, app_slug_1.getAnonCookieName)();
+/**
+ * Generates a new anonymous session ID
+ */
+function generateAnonId() {
+    return (0, crypto_1.randomBytes)(16).toString('hex');
+}
+// getAnonKey is defined above using app-slug prefix
+/**
+ * Creates a new anonymous session in Redis
+ */
+async function createAnonSession(anonId) {
+    const id = anonId || generateAnonId();
+    const now = Date.now();
+    const session = {
+        id,
+        createdAt: now,
+        updatedAt: now,
+        preferences: {},
+        metrics: {
+            firstVisit: now,
+            lastVisit: now,
+            visitCount: 1,
+        },
+    };
+    const key = getAnonKey(id);
+    await redis_1.default.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
+    return session;
+}
+/**
+ * Retrieves an anonymous session from Redis
+ */
+async function getAnonSession(anonId) {
+    if (!anonId)
+        return null;
+    const key = getAnonKey(anonId);
+    const json = await redis_1.default.get(key);
+    if (!json)
+        return null;
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets or creates an anonymous session
+ */
+async function getOrCreateAnonSession(anonId) {
+    if (anonId) {
+        const existing = await getAnonSession(anonId);
+        if (existing) {
+            // Update last visit
+            existing.updatedAt = Date.now();
+            existing.metrics.lastVisit = Date.now();
+            existing.metrics.visitCount = (existing.metrics.visitCount || 0) + 1;
+            await saveAnonSession(existing);
+            return existing;
+        }
+    }
+    // Create new session
+    return createAnonSession(anonId);
+}
+/**
+ * Saves an anonymous session to Redis
+ */
+async function saveAnonSession(session) {
+    session.updatedAt = Date.now();
+    const key = getAnonKey(session.id);
+    await redis_1.default.setex(key, ANON_SESSION_TTL, JSON.stringify(session));
+}
+/**
+ * Updates preferences in an anonymous session
+ */
+async function updateAnonPreferences(anonId, preferences) {
+    const session = await getAnonSession(anonId);
+    if (!session)
+        return null;
+    session.preferences = { ...session.preferences, ...preferences };
+    await saveAnonSession(session);
+    return session;
+}
+/**
+ * Updates metrics in an anonymous session
+ */
+async function updateAnonMetrics(anonId, metrics) {
+    const session = await getAnonSession(anonId);
+    if (!session)
+        return null;
+    session.metrics = { ...session.metrics, ...metrics };
+    await saveAnonSession(session);
+    return session;
+}
+/**
+ * Increments a numeric metric
+ */
+async function incrementAnonMetric(anonId, metricName, amount = 1) {
+    const session = await getAnonSession(anonId);
+    if (!session)
+        return 0;
+    const currentValue = session.metrics[metricName] || 0;
+    const newValue = currentValue + amount;
+    session.metrics[metricName] = newValue;
+    await saveAnonSession(session);
+    return newValue;
+}
+/**
+ * Deletes an anonymous session
+ */
+async function deleteAnonSession(anonId) {
+    if (!anonId)
+        return;
+    const key = getAnonKey(anonId);
+    await redis_1.default.del(key);
+}
+/**
+ * Merges anonymous session data into user profile data
+ * Call this when a user logs in to preserve their pre-login preferences
+ */
+async function mergeAnonSessionToUser(anonId, userId, mergeCallback) {
+    const anonSession = await getAnonSession(anonId);
+    if (!anonSession)
+        return null;
+    // If a merge callback is provided, use it to persist data to user profile
+    if (mergeCallback) {
+        await mergeCallback(anonSession, userId);
+    }
+    // Optionally delete the anonymous session after merge
+    // await deleteAnonSession(anonId);
+    return anonSession;
+}
+// ANON_COOKIE_NAME is already exported at the top of the file