@payez/next-mvp 3.0.0

package/src/lib/types/api-responses.ts

@@ -0,0 +1,336 @@
+// ========================================================================================
+// BULLETPROOF API RESPONSE TYPES - ENFORCES STANDARDIZED FORMAT
+// ========================================================================================
+// These types ENFORCE the standardized response format from our Identity API
+// If the API doesn't return this exact structure, TypeScript will break the build
+// NO MORE data.data.data.data NONSENSE - EVER!
+// ========================================================================================
+
+/**
+ * BASE STANDARDIZED RESPONSE FORMAT
+ * This is THE ONLY acceptable response format from our APIs
+ */
+export interface StandardizedApiResponse<TData = unknown> {
+  /** REQUIRED: Operation success status */
+  success: true;
+  /** REQUIRED: The actual data payload */
+  data: TData;
+  /** REQUIRED: Human-readable success message */
+  message: string;
+  /** REQUIRED: Unique operation code for tracking */
+  operation_code: string;
+  /** Optional: Server timestamp */
+  timestamp?: string;
+  /** Optional: Request ID for tracing */
+  request_id?: string;
+}
+
+/**
+ * STANDARDIZED ERROR RESPONSE FORMAT
+ * This is THE ONLY acceptable error format from our APIs
+ */
+export interface StandardizedErrorResponse {
+  /** REQUIRED: Always false for errors */
+  success: false;
+  /** REQUIRED: Standard error code */
+  error_code: string;
+  /** REQUIRED: Human-readable error message */
+  message: string;
+  /** REQUIRED: Operation that failed */
+  operation: string;
+  /** Optional: Additional error details - can be any structure from IDP */
+  details?: unknown;
+  /** Optional: Validation errors */
+  validation_errors?: Record<string, string[]>;
+  /** Optional: Server timestamp */
+  timestamp?: string;
+  /** Optional: Request ID for tracing */
+  request_id?: string;
+}
+
+/**
+ * STANDARDIZED PAGINATED RESPONSE FORMAT
+ * For endpoints that return paged data
+ */
+export interface StandardizedPagedResponse<TData = unknown> {
+  /** REQUIRED: Always true for success */
+  success: true;
+  /** REQUIRED: Array of data items */
+  data: TData[];
+  /** REQUIRED: Human-readable success message */
+  message: string;
+  /** REQUIRED: Unique operation code */
+  operation_code: string;
+  /** REQUIRED: Pagination metadata */
+  pagination: {
+    /** Current page number (1-based) */
+    current_page: number;
+    /** Total number of pages */
+    total_pages: number;
+    /** Number of items per page */
+    page_size: number;
+    /** Total number of items across all pages */
+    total_items: number;
+    /** True if there are more pages after current */
+    has_next_page: boolean;
+    /** True if there are pages before current */
+    has_previous_page: boolean;
+  };
+  /** Optional: Server timestamp */
+  timestamp?: string;
+  /** Optional: Request ID for tracing */
+  request_id?: string;
+}
+
+/**
+ * VALIDATION ERROR RESPONSE FORMAT
+ * For input validation failures
+ */
+export interface StandardizedValidationResponse {
+  /** REQUIRED: Always false for validation errors */
+  success: false;
+  /** REQUIRED: Always 'VALIDATION_ERROR' */
+  error_code: 'VALIDATION_ERROR';
+  /** REQUIRED: Summary message */
+  message: string;
+  /** REQUIRED: Operation that failed */
+  operation: string;
+  /** REQUIRED: Field-specific validation errors */
+  payload: {
+    /** Field name mapped to array of error messages */
+    validation_errors: Record<string, string[]>;
+    /** The invalid value that caused the error */
+    invalid_value?: unknown;
+    /** The field that caused the primary error */
+    primary_field?: string;
+  };
+}
+
+// ========================================================================================
+// RESPONSE TYPE UNION - THE ONLY VALID API RESPONSES
+// ========================================================================================
+
+/** ALL POSSIBLE STANDARDIZED RESPONSES */
+export type StandardizedResponse<TData = unknown> = 
+  | StandardizedApiResponse<TData>
+  | StandardizedPagedResponse<TData>
+  | StandardizedErrorResponse
+  | StandardizedValidationResponse;
+
+// ========================================================================================
+// TYPE GUARDS FOR RUNTIME VALIDATION
+// ========================================================================================
+
+/**
+ * Type guard to check if response is a success response
+ * THROWS if response doesn't match standardized format
+ */
+export function isSuccessResponse<TData = unknown>(
+  response: unknown
+): response is StandardizedApiResponse<TData> {
+  if (!response || typeof response !== 'object') {
+    throw new Error('INVALID_API_RESPONSE: Response is not an object');
+  }
+
+  const r = response as any;
+
+  if (r.success !== true) {
+    return false; // This is an error response, not invalid format
+  }
+
+  // SUCCESS RESPONSE VALIDATION - BE STRICT!
+  if (!('data' in r)) {
+    throw new Error('INVALID_API_RESPONSE: Success response missing required "data" field');
+  }
+
+  if (!('message' in r) || typeof r.message !== 'string') {
+    throw new Error('INVALID_API_RESPONSE: Success response missing required "message" field');
+  }
+
+  if (!('operation_code' in r) || typeof r.operation_code !== 'string') {
+    throw new Error('INVALID_API_RESPONSE: Success response missing required "operation_code" field');
+  }
+
+  return true;
+}
+
+/**
+ * Type guard to check if response is a paged success response
+ * THROWS if response doesn't match standardized format
+ */
+export function isPagedResponse<TData = unknown>(
+  response: unknown
+): response is StandardizedPagedResponse<TData> {
+  if (!isSuccessResponse(response)) {
+    return false;
+  }
+
+  const r = response as any;
+
+  // Check if it has pagination metadata
+  if (!('pagination' in r) || typeof r.pagination !== 'object') {
+    return false;
+  }
+
+  const pagination = r.pagination;
+  const requiredPaginationFields = [
+    'current_page', 'total_pages', 'page_size', 'total_items', 
+    'has_next_page', 'has_previous_page'
+  ];
+
+  for (const field of requiredPaginationFields) {
+    if (!(field in pagination)) {
+      throw new Error(`INVALID_API_RESPONSE: Paged response missing required pagination.${field}`);
+    }
+  }
+
+  // Ensure data is an array for paged responses
+  if (!Array.isArray(r.data)) {
+    throw new Error('INVALID_API_RESPONSE: Paged response data must be an array');
+  }
+
+  return true;
+}
+
+/**
+ * Type guard to check if response is an error response
+ * THROWS if response doesn't match standardized format
+ */
+export function isErrorResponse(
+  response: unknown
+): response is StandardizedErrorResponse {
+  if (!response || typeof response !== 'object') {
+    throw new Error('INVALID_API_RESPONSE: Response is not an object');
+  }
+
+  const r = response as any;
+
+  if (r.success !== false) {
+    return false; // This is a success response, not invalid format
+  }
+
+  // ERROR RESPONSE VALIDATION - BE STRICT!
+  if (!('error_code' in r) || typeof r.error_code !== 'string') {
+    throw new Error('INVALID_API_RESPONSE: Error response missing required "error_code" field');
+  }
+
+  if (!('message' in r) || typeof r.message !== 'string') {
+    throw new Error('INVALID_API_RESPONSE: Error response missing required "message" field');
+  }
+
+  if (!('operation' in r) || typeof r.operation !== 'string') {
+    throw new Error('INVALID_API_RESPONSE: Error response missing required "operation" field');
+  }
+
+  return true;
+}
+
+/**
+ * Type guard to check if response is a validation error
+ * THROWS if response doesn't match standardized format
+ */
+export function isValidationErrorResponse(
+  response: unknown
+): response is StandardizedValidationResponse {
+  if (!isErrorResponse(response)) {
+    return false;
+  }
+
+  const r = response as any;
+  
+  if (r.error_code !== 'VALIDATION_ERROR') {
+    return false;
+  }
+
+  // VALIDATION ERROR RESPONSE VALIDATION - BE STRICT!
+  if (!('payload' in r) || typeof r.payload !== 'object') {
+    throw new Error('INVALID_API_RESPONSE: Validation error missing required "payload" field');
+  }
+
+  if (!('validation_errors' in r.payload) || typeof r.payload.validation_errors !== 'object') {
+    throw new Error('INVALID_API_RESPONSE: Validation error missing required "payload.validation_errors" field');
+  }
+
+  return true;
+}
+
+// ========================================================================================
+// RESPONSE VALIDATOR - ENFORCES COMPLIANCE AT RUNTIME
+// ========================================================================================
+
+/**
+ * VALIDATES AND NORMALIZES API RESPONSES
+ * This function BREAKS THE BUILD if responses don't match our standard
+ * NO EXCEPTIONS - ZERO TOLERANCE FOR BAD RESPONSES
+ */
+export function validateStandardizedResponse<TData = unknown>(
+  response: unknown,
+  endpoint?: string
+): StandardizedResponse<TData> {
+  const context = endpoint ? ` for endpoint: ${endpoint}` : '';
+  
+  try {
+    // First, basic object validation
+    if (!response || typeof response !== 'object') {
+      throw new Error(`CRITICAL_API_ERROR: Invalid response object${context}`);
+    }
+
+    const r = response as any;
+
+    // Check for success field (REQUIRED)
+    if (!('success' in r) || typeof r.success !== 'boolean') {
+      throw new Error(`CRITICAL_API_ERROR: Response missing required boolean "success" field${context}`);
+    }
+
+    // Route to appropriate validator based on success status
+    if (r.success === true) {
+      // Check if it's a paged response
+      if ('pagination' in r) {
+        if (isPagedResponse<TData>(response)) {
+          return response as StandardizedPagedResponse<TData>;
+        }
+      } else {
+        if (isSuccessResponse<TData>(response)) {
+          return response as StandardizedApiResponse<TData>;
+        }
+      }
+    } else if (r.success === false) {
+      // Check if it's a validation error
+      if (r.error_code === 'VALIDATION_ERROR') {
+        if (isValidationErrorResponse(response)) {
+          return response as StandardizedValidationResponse;
+        }
+      } else {
+        if (isErrorResponse(response)) {
+          return response as StandardizedErrorResponse;
+        }
+      }
+    }
+
+    // If we reach here, the response format is invalid
+    throw new Error(`CRITICAL_API_ERROR: Response format validation failed${context}. Response: ${JSON.stringify(response, null, 2)}`);
+
+  } catch (error) {
+    // Re-throw validation errors with context
+    const errorMessage = error instanceof Error ? error.message : 'Unknown validation error';
+    throw new Error(`${errorMessage}${context}`);
+  }
+}
+
+// ========================================================================================
+// CONVENIENCE TYPE EXTRACTORS
+// ========================================================================================
+
+/** Extract the data type from a standardized response */
+export type ExtractResponseData<T> = T extends StandardizedApiResponse<infer U> 
+  ? U 
+  : T extends StandardizedPagedResponse<infer U>
+  ? U[]
+  : never;
+
+/** Extract the error code from an error response */
+export type ExtractErrorCode<T> = T extends StandardizedErrorResponse 
+  ? T['error_code'] 
+  : T extends StandardizedValidationResponse 
+  ? T['error_code']
+  : never;

package/src/lib/user-agent-parser.ts

@@ -0,0 +1,252 @@
+/**
+ * =============================================================================
+ * USER AGENT PARSER
+ * =============================================================================
+ *
+ * Lightweight user agent parsing without external dependencies.
+ * Extracts device type, browser, and OS information from user agent strings.
+ *
+ * USAGE:
+ * ------
+ * import { parseUserAgent, DeviceInfo } from '@payez/next-mvp/lib/user-agent-parser';
+ *
+ * const info = parseUserAgent(request.headers.get('user-agent'));
+ * console.log(info.browser); // 'Chrome'
+ * console.log(info.deviceType); // 'desktop'
+ *
+ * =============================================================================
+ */
+
+// -----------------------------------------------------------------------------
+// TYPES
+// -----------------------------------------------------------------------------
+
+export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'unknown';
+
+export interface DeviceInfo {
+  deviceType: DeviceType;
+  browser: string;
+  browserVersion?: string;
+  os: string;
+  osVersion?: string;
+  isMobile: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+  isBot: boolean;
+  raw: string;
+}
+
+// -----------------------------------------------------------------------------
+// DETECTION PATTERNS
+// -----------------------------------------------------------------------------
+
+const MOBILE_KEYWORDS = [
+  'Mobile',
+  'Android',
+  'iPhone',
+  'iPod',
+  'BlackBerry',
+  'IEMobile',
+  'Opera Mini',
+  'Opera Mobi',
+  'Windows Phone',
+];
+
+const TABLET_KEYWORDS = [
+  'iPad',
+  'Tablet',
+  'PlayBook',
+  'Silk',
+  'Kindle',
+];
+
+const BOT_KEYWORDS = [
+  'bot',
+  'spider',
+  'crawler',
+  'slurp',
+  'googlebot',
+  'bingbot',
+  'yandex',
+  'baidu',
+  'duckduckbot',
+  'facebookexternalhit',
+  'twitterbot',
+  'linkedinbot',
+  'pinterest',
+  'semrush',
+  'ahref',
+];
+
+// Browser detection patterns (order matters - more specific first)
+const BROWSER_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
+  { name: 'Edge', pattern: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)*)/ },
+  { name: 'Opera', pattern: /(?:OPR|Opera)\/(\d+(?:\.\d+)*)/ },
+  { name: 'Samsung Browser', pattern: /SamsungBrowser\/(\d+(?:\.\d+)*)/ },
+  { name: 'UC Browser', pattern: /UCBrowser\/(\d+(?:\.\d+)*)/ },
+  { name: 'Firefox', pattern: /Firefox\/(\d+(?:\.\d+)*)/ },
+  { name: 'Chrome', pattern: /Chrome\/(\d+(?:\.\d+)*)/ },
+  { name: 'Safari', pattern: /Version\/(\d+(?:\.\d+)*).*Safari/ },
+  { name: 'Safari', pattern: /Safari\/(\d+(?:\.\d+)*)/ },
+  { name: 'IE', pattern: /(?:MSIE |rv:)(\d+(?:\.\d+)*)/ },
+];
+
+// OS detection patterns
+const OS_PATTERNS: Array<{ name: string; pattern: RegExp; versionPattern?: RegExp }> = [
+  { name: 'iOS', pattern: /iPhone|iPad|iPod/, versionPattern: /OS (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
+  { name: 'Android', pattern: /Android/, versionPattern: /Android (\d+(?:\.\d+)*)/ },
+  { name: 'Windows', pattern: /Windows/, versionPattern: /Windows NT (\d+(?:\.\d+)*)/ },
+  { name: 'macOS', pattern: /Mac OS X/, versionPattern: /Mac OS X (\d+[_\.]\d+(?:[_\.]\d+)?)/ },
+  { name: 'Linux', pattern: /Linux/, versionPattern: undefined },
+  { name: 'Chrome OS', pattern: /CrOS/, versionPattern: undefined },
+];
+
+// Windows NT version mapping
+const WINDOWS_VERSIONS: Record<string, string> = {
+  '10.0': '10/11',
+  '6.3': '8.1',
+  '6.2': '8',
+  '6.1': '7',
+  '6.0': 'Vista',
+  '5.1': 'XP',
+};
+
+// -----------------------------------------------------------------------------
+// PARSER FUNCTION
+// -----------------------------------------------------------------------------
+
+/**
+ * Parse a user agent string to extract device, browser, and OS information.
+ *
+ * @param userAgent - The user agent string from request headers
+ * @returns Parsed device information
+ */
+export function parseUserAgent(userAgent?: string | null): DeviceInfo {
+  const ua = userAgent || '';
+  const uaLower = ua.toLowerCase();
+
+  // Default result
+  const result: DeviceInfo = {
+    deviceType: 'unknown',
+    browser: 'Unknown',
+    os: 'Unknown',
+    isMobile: false,
+    isTablet: false,
+    isDesktop: false,
+    isBot: false,
+    raw: ua,
+  };
+
+  if (!ua) return result;
+
+  // Check for bots first
+  result.isBot = BOT_KEYWORDS.some(keyword => uaLower.includes(keyword));
+
+  // Detect device type
+  result.isTablet = TABLET_KEYWORDS.some(keyword => ua.includes(keyword));
+  result.isMobile = !result.isTablet && MOBILE_KEYWORDS.some(keyword => ua.includes(keyword));
+  result.isDesktop = !result.isMobile && !result.isTablet && !result.isBot;
+
+  if (result.isTablet) {
+    result.deviceType = 'tablet';
+  } else if (result.isMobile) {
+    result.deviceType = 'mobile';
+  } else if (result.isDesktop) {
+    result.deviceType = 'desktop';
+  }
+
+  // Detect browser
+  for (const { name, pattern } of BROWSER_PATTERNS) {
+    const match = ua.match(pattern);
+    if (match) {
+      result.browser = name;
+      result.browserVersion = match[1];
+      break;
+    }
+  }
+
+  // Detect OS
+  for (const { name, pattern, versionPattern } of OS_PATTERNS) {
+    if (pattern.test(ua)) {
+      result.os = name;
+      if (versionPattern) {
+        const versionMatch = ua.match(versionPattern);
+        if (versionMatch) {
+          let version = versionMatch[1].replace(/_/g, '.');
+
+          // Map Windows NT versions to friendly names
+          if (name === 'Windows' && WINDOWS_VERSIONS[version]) {
+            version = WINDOWS_VERSIONS[version];
+          }
+
+          result.osVersion = version;
+        }
+      }
+      break;
+    }
+  }
+
+  return result;
+}
+
+// -----------------------------------------------------------------------------
+// HELPER FUNCTIONS
+// -----------------------------------------------------------------------------
+
+/**
+ * Get a short, human-readable description of the device
+ */
+export function getDeviceDescription(info: DeviceInfo): string {
+  const parts: string[] = [];
+
+  if (info.browser !== 'Unknown') {
+    parts.push(info.browser);
+  }
+
+  if (info.os !== 'Unknown') {
+    let osDesc = info.os;
+    if (info.osVersion) {
+      osDesc += ` ${info.osVersion}`;
+    }
+    parts.push(osDesc);
+  }
+
+  if (parts.length === 0) {
+    if (info.isBot) return 'Bot';
+    return info.deviceType.charAt(0).toUpperCase() + info.deviceType.slice(1);
+  }
+
+  return parts.join(' / ');
+}
+
+/**
+ * Get device type icon (emoji)
+ */
+export function getDeviceIcon(deviceType: DeviceType): string {
+  switch (deviceType) {
+    case 'mobile':
+      return '📱';
+    case 'tablet':
+      return '📲';
+    case 'desktop':
+      return '💻';
+    default:
+      return '🔌';
+  }
+}
+
+/**
+ * Get browser icon (emoji)
+ */
+export function getBrowserIcon(browser: string): string {
+  const browserLower = browser.toLowerCase();
+
+  if (browserLower.includes('chrome')) return '🌐';
+  if (browserLower.includes('firefox')) return '🦊';
+  if (browserLower.includes('safari')) return '🧭';
+  if (browserLower.includes('edge')) return '🌐';
+  if (browserLower.includes('opera')) return '🔴';
+  if (browserLower.includes('ie') || browserLower.includes('internet explorer')) return '🌐';
+
+  return '🌐';
+}

package/src/logging/api/admin-analytics.ts

@@ -0,0 +1,51 @@
+import { ErrorMetrics, HealthMetrics, TimeRange } from '../types';
+
+const API_BASE = process.env.NEXT_PUBLIC_VIBE_API_URL || 'http://localhost:32786';
+
+/**
+ * Get admin token from app's auth implementation
+ * Apps should override this via their own auth logic
+ */
+function getAdminToken(): string {
+  if (typeof window !== 'undefined' && window.localStorage) {
+    return localStorage.getItem('admin_token') || '';
+  }
+  return '';
+}
+
+export async function getErrorMetrics(timeRange: TimeRange = '24h') {
+  // Convert timeRange to hours for backend API
+  const hoursMap: Record<TimeRange, number> = {
+    '1h': 1,
+    '24h': 24,
+    '7d': 168,
+    '30d': 720
+  };
+  const hours = hoursMap[timeRange];
+
+  const res = await fetch(`${API_BASE}/v1/admin/analytics/errors?hours=${hours}`, {
+    headers: {
+      Authorization: `Bearer ${getAdminToken()}`
+    }
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch error metrics: ${res.statusText}`);
+  }
+
+  return res.json();
+}
+
+export async function getHealthMetrics(timeRange: TimeRange = '1h') {
+  const res = await fetch(`${API_BASE}/v1/admin/analytics/health?timeRange=${timeRange}`, {
+    headers: {
+      Authorization: `Bearer ${getAdminToken()}`
+    }
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch health metrics: ${res.statusText}`);
+  }
+
+  return res.json();
+}

package/src/logging/api/audit-log.ts

@@ -0,0 +1,53 @@
+import { AuditLogEntry, AuditLogQuery, AuditLogResponse } from '../types';
+
+const API_BASE = process.env.NEXT_PUBLIC_VIBE_API_URL || 'http://localhost:32786';
+
+/**
+ * Get admin token from app's auth implementation
+ */
+function getAdminToken(): string {
+  if (typeof window !== 'undefined' && window.localStorage) {
+    return localStorage.getItem('admin_token') || '';
+  }
+  return '';
+}
+
+export async function writeAuditLog(entry: Omit<AuditLogEntry, 'id' | 'timestamp'>) {
+  const res = await fetch(`${API_BASE}/v1/audit`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${getAdminToken()}`
+    },
+    body: JSON.stringify(entry)
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to write audit log: ${res.statusText}`);
+  }
+
+  return res.json();
+}
+
+export async function queryAuditLog(query: AuditLogQuery): Promise<AuditLogResponse> {
+  const params = new URLSearchParams();
+
+  if (query.category) params.append('category', query.category);
+  if (query.userId) params.append('userId', query.userId.toString());
+  if (query.startDate) params.append('startDate', query.startDate);
+  if (query.endDate) params.append('endDate', query.endDate);
+  if (query.page) params.append('page', query.page.toString());
+  if (query.pageSize) params.append('pageSize', query.pageSize.toString());
+
+  const res = await fetch(`${API_BASE}/v1/audit?${params.toString()}`, {
+    headers: {
+      Authorization: `Bearer ${getAdminToken()}`
+    }
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to query audit log: ${res.statusText}`);
+  }
+
+  return res.json();
+}