@payez/next-mvp 3.0.0

package/src/logging/components/AdminAnalyticsLayout.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { ReactNode } from 'react';
+import { TimeRange } from '../types';
+
+interface AdminAnalyticsLayoutProps {
+  title: string;
+  timeRange: TimeRange;
+  onTimeRangeChange: (range: TimeRange) => void;
+  children: ReactNode;
+}
+
+export function AdminAnalyticsLayout({
+  title,
+  timeRange,
+  onTimeRangeChange,
+  children,
+}: AdminAnalyticsLayoutProps) {
+  const timeRanges: TimeRange[] = ['1h', '24h', '7d', '30d'];
+
+  return (
+    <div className="p-6">
+      {/* Header */}
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl font-bold">{title}</h1>
+
+        {/* Time range selector */}
+        <div className="flex gap-2">
+          {timeRanges.map(range => (
+            <button
+              key={range}
+              onClick={() => onTimeRangeChange(range)}
+              className={`px-3 py-1 rounded text-sm font-medium transition-colors ${
+                timeRange === range
+                  ? 'bg-blue-600 text-white'
+                  : 'bg-gray-200 text-gray-700 hover:bg-gray-300'
+              }`}
+            >
+              {range}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Content */}
+      <div>{children}</div>
+    </div>
+  );
+}

package/src/logging/components/AuditLogViewer.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { AuditLogEntry, AuditLogQuery } from '../types';
+import { queryAuditLog } from '../api/audit-log';
+
+interface AuditLogViewerProps {
+  query?: Partial<AuditLogQuery>;
+  className?: string;
+}
+
+export function AuditLogViewer({ query = {}, className }: AuditLogViewerProps) {
+  const [logs, setLogs] = useState<AuditLogEntry[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [page, setPage] = useState(1);
+  const [totalPages, setTotalPages] = useState(1);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function fetchLogs() {
+      try {
+        setLoading(true);
+        const result = await queryAuditLog({
+          ...query,
+          page,
+          pageSize: 20,
+        });
+
+        if (mounted) {
+          setLogs(result.data);
+          setTotalPages(result.pagination?.totalPages || 1);
+          setError(null);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : 'Failed to fetch audit logs');
+        }
+      } finally {
+        if (mounted) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchLogs();
+
+    return () => {
+      mounted = false;
+    };
+  }, [query, page]);
+
+  if (loading) return <div className={className}>Loading audit logs...</div>;
+  if (error) return <div className={className}>Error: {error}</div>;
+
+  return (
+    <div className={className}>
+      <h3 className="text-lg font-semibold mb-4">Audit Log</h3>
+
+      {/* Logs table */}
+      <div className="overflow-x-auto">
+        <table className="min-w-full divide-y divide-gray-200">
+          <thead className="bg-gray-50">
+            <tr>
+              <th className="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">
+                Timestamp
+              </th>
+              <th className="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">
+                Category
+              </th>
+              <th className="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">
+                Action
+              </th>
+              <th className="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">
+                User ID
+              </th>
+              <th className="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">
+                Details
+              </th>
+            </tr>
+          </thead>
+          <tbody className="bg-white divide-y divide-gray-200">
+            {logs.map(log => (
+              <tr key={log.id} className="hover:bg-gray-50">
+                <td className="px-4 py-2 text-sm text-gray-900 font-mono">
+                  {log.timestamp ? new Date(log.timestamp).toLocaleString() : '-'}
+                </td>
+                <td className="px-4 py-2 text-sm text-gray-900">{log.category}</td>
+                <td className="px-4 py-2 text-sm text-gray-900 font-mono">{log.action}</td>
+                <td className="px-4 py-2 text-sm text-gray-900">{log.userId || '-'}</td>
+                <td className="px-4 py-2 text-sm text-gray-500">
+                  {log.details ? JSON.stringify(log.details).slice(0, 50) : '-'}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination */}
+      {totalPages > 1 && (
+        <div className="flex justify-center gap-2 mt-4">
+          <button
+            onClick={() => setPage(p => Math.max(1, p - 1))}
+            disabled={page === 1}
+            className="px-3 py-1 rounded bg-gray-200 text-gray-700 disabled:opacity-50"
+          >
+            Previous
+          </button>
+          <span className="px-3 py-1">
+            Page {page} of {totalPages}
+          </span>
+          <button
+            onClick={() => setPage(p => Math.min(totalPages, p + 1))}
+            disabled={page === totalPages}
+            className="px-3 py-1 rounded bg-gray-200 text-gray-700 disabled:opacity-50"
+          >
+            Next
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/logging/components/ErrorMetricsCard.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { useErrorMetrics } from '../hooks/useErrorMetrics';
+import { TimeRange } from '../types';
+
+interface ErrorMetricsCardProps {
+  timeRange?: TimeRange;
+  className?: string;
+}
+
+export function ErrorMetricsCard({ timeRange = '24h', className }: ErrorMetricsCardProps) {
+  const { data, loading, error } = useErrorMetrics(timeRange);
+
+  if (loading) return <div className={className}>Loading error metrics...</div>;
+  if (error) return <div className={className}>Error: {error}</div>;
+  if (!data) return null;
+
+  return (
+    <div className={className}>
+      <h3 className="text-lg font-semibold mb-4">
+        Error Metrics
+        <span className="text-sm text-gray-500 ml-2">
+          ({new Date(data.periodStart).toLocaleDateString()} - {new Date(data.periodEnd).toLocaleDateString()})
+        </span>
+      </h3>
+
+      {/* Total errors */}
+      <div className="mb-4">
+        <span className="text-3xl font-bold">{data.totalErrors}</span>
+        <span className="text-gray-600 ml-2">total errors</span>
+      </div>
+
+      {/* Top failing routes */}
+      {data.topFailingRoutes && data.topFailingRoutes.length > 0 && (
+        <div className="mb-4">
+          <h4 className="font-medium mb-2">Top Failing Routes</h4>
+          <ul className="space-y-1">
+            {data.topFailingRoutes.slice(0, 5).map((route, idx) => (
+              <li key={idx} className="flex justify-between text-sm">
+                <span className="font-mono">{route.route}</span>
+                <span className="text-red-600">{route.count} errors</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Errors by level */}
+      <div className="mb-4">
+        <h4 className="font-medium mb-2">By Severity</h4>
+        <div className="flex gap-4">
+          <div className="text-sm">
+            <span className="font-medium">Error:</span>
+            <span className="ml-1">{data.errorCount}</span>
+          </div>
+          <div className="text-sm">
+            <span className="font-medium">Warn:</span>
+            <span className="ml-1">{data.warnCount}</span>
+          </div>
+          <div className="text-sm">
+            <span className="font-medium">Fatal:</span>
+            <span className="ml-1">{data.fatalCount}</span>
+          </div>
+        </div>
+      </div>
+
+      {/* By category */}
+      {data.byCategory && data.byCategory.length > 0 && (
+        <div className="mb-4">
+          <h4 className="font-medium mb-2">By Category</h4>
+          <div className="flex flex-wrap gap-2">
+            {data.byCategory.map((cat, idx) => (
+              <div key={idx} className="text-sm bg-gray-100 px-2 py-1 rounded">
+                <span className="font-medium">{cat.category}:</span>
+                <span className="ml-1">{cat.count}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Top error codes */}
+      {data.topErrorCodes && data.topErrorCodes.length > 0 && (
+        <div>
+          <h4 className="font-medium mb-2">Top Error Codes</h4>
+          <ul className="space-y-1">
+            {data.topErrorCodes.slice(0, 5).map((code, idx) => (
+              <li key={idx} className="flex justify-between text-sm">
+                <span className="font-mono">{code.errorCode}</span>
+                <span className="text-orange-600">{code.count}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/logging/components/HealthMetricsCard.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { useHealthMetrics } from '../hooks/useHealthMetrics';
+import { TimeRange } from '../types';
+
+interface HealthMetricsCardProps {
+  timeRange?: TimeRange;
+  className?: string;
+}
+
+export function HealthMetricsCard({ timeRange = '1h', className }: HealthMetricsCardProps) {
+  const { data, loading, error } = useHealthMetrics(timeRange);
+
+  if (loading) return <div className={className}>Loading health metrics...</div>;
+  if (error) return <div className={className}>Error: {error}</div>;
+  if (!data) return null;
+
+  return (
+    <div className={className}>
+      <h3 className="text-lg font-semibold mb-4">System Health ({data.timeRange})</h3>
+
+      {/* API health overview */}
+      <div className="grid grid-cols-2 gap-4 mb-4">
+        <div>
+          <div className="text-2xl font-bold">{data.apiHealth.avgResponseTimeMs}ms</div>
+          <div className="text-sm text-gray-600">Avg Response Time</div>
+        </div>
+        <div>
+          <div className="text-2xl font-bold">{data.apiHealth.requestCount}</div>
+          <div className="text-sm text-gray-600">Total Requests</div>
+        </div>
+        <div>
+          <div className="text-2xl font-bold">{data.apiHealth.p95ResponseTimeMs}ms</div>
+          <div className="text-sm text-gray-600">P95 Response Time</div>
+        </div>
+        <div>
+          <div className="text-2xl font-bold">
+            {(data.apiHealth.errorRate * 100).toFixed(2)}%
+          </div>
+          <div className="text-sm text-gray-600">Error Rate</div>
+        </div>
+      </div>
+
+      {/* Slowest endpoints */}
+      {data.endpointBreakdown.length > 0 && (
+        <div className="mb-4">
+          <h4 className="font-medium mb-2">Slowest Endpoints</h4>
+          <ul className="space-y-1">
+            {data.endpointBreakdown
+              .sort((a, b) => b.avgDurationMs - a.avgDurationMs)
+              .slice(0, 5)
+              .map((ep, i) => (
+                <li key={i} className="flex justify-between text-sm">
+                  <span className="font-mono">{ep.endpoint}</span>
+                  <span className="text-orange-600">{ep.avgDurationMs}ms</span>
+                </li>
+              ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Rate limit hits */}
+      {data.rateLimitHits > 0 && (
+        <div className="text-sm text-yellow-600">
+          ⚠️ {data.rateLimitHits} rate limit hits
+        </div>
+      )}
+    </div>
+  );
+}

package/src/logging/hooks/useAdminAnalytics.ts

@@ -0,0 +1,22 @@
+import { TimeRange } from '../types';
+import { useErrorMetrics } from './useErrorMetrics';
+import { useHealthMetrics } from './useHealthMetrics';
+import { useAuditLog } from './useAuditLog';
+
+/**
+ * Combined hook for admin analytics
+ * Fetches both error and health metrics
+ */
+export function useAdminAnalytics(timeRange: TimeRange = '24h') {
+  const errorMetrics = useErrorMetrics(timeRange);
+  const healthMetrics = useHealthMetrics(timeRange);
+  const auditLog = useAuditLog();
+
+  return {
+    errorMetrics,
+    healthMetrics,
+    auditLog,
+    loading: errorMetrics.loading || healthMetrics.loading,
+    error: errorMetrics.error || healthMetrics.error,
+  };
+}

package/src/logging/hooks/useAuditLog.ts

@@ -0,0 +1,24 @@
+import { useState } from 'react';
+import { AuditLogEntry } from '../types';
+import { writeAuditLog } from '../api/audit-log';
+
+export function useAuditLog() {
+  const [writing, setWriting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function log(entry: Omit<AuditLogEntry, 'id' | 'timestamp'>) {
+    try {
+      setWriting(true);
+      setError(null);
+      await writeAuditLog(entry);
+    } catch (err) {
+      const errMessage = err instanceof Error ? err.message : 'Failed to write audit log';
+      setError(errMessage);
+      throw err;
+    } finally {
+      setWriting(false);
+    }
+  }
+
+  return { log, writing, error };
+}

package/src/logging/hooks/useErrorMetrics.ts

@@ -0,0 +1,40 @@
+import { useState, useEffect } from 'react';
+import { ErrorMetrics, TimeRange } from '../types';
+import { getErrorMetrics } from '../api/admin-analytics';
+
+export function useErrorMetrics(timeRange: TimeRange = '24h') {
+  const [data, setData] = useState<ErrorMetrics | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function fetchData() {
+      try {
+        setLoading(true);
+        const result = await getErrorMetrics(timeRange);
+        if (mounted) {
+          setData(result.data);
+          setError(null);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : 'Failed to fetch error metrics');
+        }
+      } finally {
+        if (mounted) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchData();
+
+    return () => {
+      mounted = false;
+    };
+  }, [timeRange]);
+
+  return { data, loading, error };
+}

package/src/logging/hooks/useHealthMetrics.ts

@@ -0,0 +1,44 @@
+import { useState, useEffect } from 'react';
+import { HealthMetrics, TimeRange } from '../types';
+import { getHealthMetrics } from '../api/admin-analytics';
+
+export function useHealthMetrics(timeRange: TimeRange = '1h') {
+  const [data, setData] = useState<HealthMetrics | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function fetchData() {
+      try {
+        setLoading(true);
+        const result = await getHealthMetrics(timeRange);
+        if (mounted) {
+          setData(result.data);
+          setError(null);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : 'Failed to fetch health metrics');
+        }
+      } finally {
+        if (mounted) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchData();
+
+    // Auto-refresh health metrics every minute
+    const interval = setInterval(fetchData, 60000);
+
+    return () => {
+      mounted = false;
+      clearInterval(interval);
+    };
+  }, [timeRange]);
+
+  return { data, loading, error };
+}

package/src/logging/index.ts

@@ -0,0 +1,18 @@
+// Components
+export { ErrorMetricsCard } from './components/ErrorMetricsCard';
+export { HealthMetricsCard } from './components/HealthMetricsCard';
+export { AuditLogViewer } from './components/AuditLogViewer';
+export { AdminAnalyticsLayout } from './components/AdminAnalyticsLayout';
+
+// Hooks
+export { useErrorMetrics } from './hooks/useErrorMetrics';
+export { useHealthMetrics } from './hooks/useHealthMetrics';
+export { useAuditLog } from './hooks/useAuditLog';
+export { useAdminAnalytics } from './hooks/useAdminAnalytics';
+
+// Types
+export * from './types';
+
+// API (for advanced use cases)
+export * from './api/admin-analytics';
+export * from './api/audit-log';

package/src/logging/types/analytics.ts

@@ -0,0 +1,81 @@
+// Universal analytics types that work for ANY app
+
+export interface ErrorMetrics {
+  totalErrors: number;
+  errorCount: number;
+  warnCount: number;
+  fatalCount: number;
+  topFailingRoutes: RouteError[];
+  byCategory: CategoryCount[];
+  topErrorCodes?: TopErrorCode[];
+  hourlyTrend?: HourlyTrendPoint[];
+  periodStart: string;
+  periodEnd: string;
+}
+
+export interface RouteError {
+  route: string;
+  count: number;
+  percentage: number;
+}
+
+export interface LevelCount {
+  level: 'error' | 'warn' | 'fatal';
+  count: number;
+}
+
+export interface CategoryCount {
+  category: string; // Generic: 'api', 'auth', 'billing', etc.
+  count: number;
+}
+
+export interface TopErrorCode {
+  errorCode: string;
+  count: number;
+}
+
+export interface HourlyTrendPoint {
+  hour: string;
+  count: number;
+}
+
+export interface ErrorDetail {
+  timestamp: string;
+  level: string;
+  message: string;
+  path: string;
+  userId?: number;
+  errorCode?: string;
+}
+
+export interface HealthMetrics {
+  timeRange: string;
+  apiHealth: {
+    avgResponseTimeMs: number;
+    p95ResponseTimeMs: number;
+    p99ResponseTimeMs: number;
+    requestCount: number;
+    errorRate: number;
+  };
+  endpointBreakdown: EndpointHealth[];
+  rateLimitHits: number;
+  slowRequests: SlowRequest[];
+}
+
+export interface EndpointHealth {
+  endpoint: string;
+  avgDurationMs: number;
+  p95DurationMs: number;
+  requestCount: number;
+  errorRate: number;
+}
+
+export interface SlowRequest {
+  timestamp: string;
+  path: string;
+  durationMs: number;
+  userId?: number;
+}
+
+// Time range options
+export type TimeRange = '1h' | '24h' | '7d' | '30d';

package/src/logging/types/audit.ts

@@ -0,0 +1,31 @@
+export interface AuditLogEntry {
+  id?: number;
+  category: string;
+  action: string;
+  userId?: number;
+  adminUserId?: number;
+  details?: Record<string, any>;
+  ipAddress?: string;
+  userAgent?: string;
+  timestamp?: string;
+}
+
+export interface AuditLogQuery {
+  category?: string;
+  userId?: number;
+  startDate?: string;
+  endDate?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+export interface AuditLogResponse {
+  success: boolean;
+  data: AuditLogEntry[];
+  pagination?: {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+  };
+}

package/src/logging/types/index.ts

@@ -0,0 +1,3 @@
+// Re-export all types
+export * from './analytics';
+export * from './audit';

package/src/middleware/auth-decision.ts

@@ -0,0 +1,43 @@
+/**
+ * Auth Decision Engine (lifted)
+ */
+import { NextRequest } from 'next/server';
+
+export interface AuthContext {
+  pathname: string;
+  isPublicRoute: boolean;
+  isLoginPage: boolean;
+  searchParams: URLSearchParams;
+  sessionPointer: { exists: boolean; sessionToken?: string; expired?: boolean; hasRefreshToken?: boolean; };
+  sessionStatus: { exists: boolean | null; forceInvalid: boolean | null; requires2FA: boolean; twoFactorComplete: boolean; };
+  circuitBreakerOpen: boolean;
+}
+
+export type AuthAction = 
+  | { type: 'allow' }
+  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
+  | { type: 'service_error'; reason: string };
+
+export function makeAuthDecision(context: AuthContext): AuthAction {
+  const { pathname, isPublicRoute, isLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = context;
+  // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops
+  const safeCallbackUrl = pathname.startsWith('/account-auth/') ? '/' : pathname;
+  if (isPublicRoute && !isLoginPage) return { type: 'allow' };
+  if (circuitBreakerOpen) { if (isLoginPage) return { type: 'allow' }; return { type: 'redirect', location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen', reason: 'CircuitBreakerOpen', clearCookies: true }; }
+  if (!sessionPointer.exists) { if (isLoginPage) return { type: 'allow' }; if (pathname === '/') { const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login'; return { type: 'redirect', location: unauthUrl, reason: 'unauthenticated_root_redirect' }; } return { type: 'redirect', location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`, reason: 'no_session_pointer' }; }
+  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) return { type: 'service_error', reason: 'redis_unavailable' };
+  if (sessionStatus.forceInvalid) { if (isLoginPage) return { type: 'allow' }; return { type: 'redirect', location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=force_invalidated`, reason: 'force_invalidated' }; }
+  if (!sessionStatus.exists) { if (isLoginPage) return { type: 'allow' }; return { type: 'redirect', location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=stale_session`, reason: 'stale_session' }; }
+  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+    if (pathname === '/account-auth/verify-code') return { type: 'allow' };
+    if (isLoginPage) { const callbackUrl = searchParams.get('callbackUrl') || '/'; const safeCallbackUrl2 = callbackUrl.startsWith('/account-auth/') ? '/' : callbackUrl; return { type: 'redirect', location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl2)}`, reason: '2fa_required_login_redirect' }; }
+    return { type: 'allow' };
+  }
+  if (sessionPointer.expired) { if (isLoginPage) return { type: 'allow' }; return { type: 'redirect', location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&error=SessionExpired`, reason: 'token_expired' }; }
+  if (pathname === '/') return { type: 'redirect', location: '/', reason: 'authenticated_root_redirect' };
+  if (isLoginPage) { const callbackUrl = searchParams.get('callbackUrl') || '/'; const safeCallbackUrl = callbackUrl.startsWith('/account-auth/') ? '/' : callbackUrl; return { type: 'redirect', location: safeCallbackUrl, reason: 'already_authenticated' }; }
+  return { type: 'allow' };
+}
+
+export function isLoginPage(pathname: string): boolean { return pathname === '/account-auth/login'; }
+export function getCallbackUrl(pathname: string, searchParams: URLSearchParams): string { if (pathname.startsWith('/account-auth/')) return '/'; const existingCallback = searchParams.get('callbackUrl'); if (existingCallback && !existingCallback.startsWith('/account-auth/')) return existingCallback; return pathname; }