@payez/next-mvp 3.0.0

package/src/templates/instrumentation.ts

@@ -0,0 +1,41 @@
+/**
+ * Next.js Instrumentation Hook Template
+ *
+ * Copy this file to your project root as `instrumentation.ts`
+ *
+ * This runs once when the server starts up (before any requests are handled).
+ * It initializes the broker handshake to fetch OAuth providers and secrets from IDP.
+ *
+ * REQUIRED: Your next.config.js must have `output: 'standalone'` for this to work.
+ */
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    // Only run on Node.js runtime (not Edge)
+    console.log('\n');
+    console.log('╔══════════════════════════════════════════════════════════════╗');
+    console.log('║            PayEz Next MVP - Server Startup                   ║');
+    console.log('╚══════════════════════════════════════════════════════════════╝');
+    console.log('');
+
+    try {
+      // Dynamically import at runtime to ensure server environment
+      const { logStartupStatus, ensureInitialized } = await import(
+        '@payez/next-mvp/lib/startup-init'
+      );
+
+      // Log startup status
+      logStartupStatus();
+
+      // Perform initialization (fetch client config from IDP including OAuth providers)
+      await ensureInitialized();
+
+      console.log('');
+      console.log('Server startup initialization complete!');
+      console.log('');
+    } catch (error) {
+      console.error('Server startup initialization failed:', error);
+      console.error('Will retry initialization on first request.');
+    }
+  }
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,39 @@
+/**
+ * Theme Provider for @payez/next-mvp
+ *
+ * Provides theme configuration to all child components via React Context.
+ * Consumer apps wrap their app with this provider and pass custom theme config.
+ */
+
+'use client';
+
+import React, { createContext, useContext } from 'react';
+import { ThemeConfig } from './types';
+import { defaultTheme } from './default';
+import { mergeDeep } from './utils';
+
+const ThemeContext = createContext<ThemeConfig>(defaultTheme);
+
+export interface ThemeProviderProps {
+  children: React.ReactNode;
+  theme?: Partial<ThemeConfig>;
+}
+
+export function ThemeProvider({ children, theme }: ThemeProviderProps) {
+  // Deep merge consumer theme with defaults
+  const mergedTheme = mergeDeep(defaultTheme, theme || {});
+
+  return (
+    <ThemeContext.Provider value={mergedTheme}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within ThemeProvider');
+  }
+  return context;
+}

package/src/theme/default.ts

@@ -0,0 +1,33 @@
+/**
+ * Default Theme Configuration for @payez/next-mvp
+ *
+ * This is the fallback theme when no custom theme is provided.
+ * It provides sensible defaults that match the current unbranded styling.
+ */
+
+import { ThemeConfig } from './types';
+
+export const defaultTheme: ThemeConfig = {
+  branding: {
+    logo: {
+      light: "/logo.svg",
+      dark: "/logo.svg",
+      alt: "Logo",
+      height: "h-10",
+      width: "w-auto",
+    },
+    appName: "App",
+  },
+  colors: {
+    primary: "#3b82f6",      // blue-500
+    background: "bg-gray-50",
+    card: "bg-white",
+    muted: "text-gray-600",
+    border: "border-gray-200",
+  },
+  layout: {
+    maxWidth: "max-w-4xl",
+    padding: "p-6",
+    spacing: "space-y-6",
+  },
+};

package/src/theme/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Theme Module for @payez/next-mvp
+ *
+ * Main export for the theme system. Provides:
+ * - ThemeProvider component
+ * - Theme hooks (useTheme, useBranding, useColors, etc.)
+ * - TypeScript types for theme configuration
+ * - Default theme
+ */
+
+export { ThemeProvider } from './ThemeProvider';
+export type { ThemeProviderProps } from './ThemeProvider';
+
+export {
+  useTheme,
+  useBranding,
+  useColors,
+  useTypography,
+  useLayout,
+  useComponentTheme,
+} from './useTheme';
+
+export type {
+  ThemeConfig,
+  LoginPageTheme,
+  ProfilePageTheme,
+  RecoveryPageTheme,
+} from './types';
+
+export { defaultTheme } from './default';
+export { mergeDeep } from './utils';

package/src/theme/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Theme Configuration Types for @payez/next-mvp
+ *
+ * These types define the shape of theme configurations that consumers
+ * can provide to customize branding, colors, typography, and layout.
+ */
+
+export interface ThemeConfig {
+  // Branding
+  branding: {
+    logo: {
+      light: string;        // Path to logo for light backgrounds
+      dark: string;         // Path to logo for dark backgrounds
+      alt: string;          // Alt text
+      height?: string;      // Default: "h-10"
+      width?: string;       // Default: "w-auto"
+    };
+    appName: string;        // "Nexus", "CryptAply", etc.
+    tagline?: string;       // Optional tagline
+  };
+
+  // Colors (Tailwind classes or hex)
+  colors: {
+    primary: string;        // Primary brand color
+    secondary?: string;     // Secondary brand color
+    accent?: string;        // Accent color
+    background: string;     // Page background
+    card: string;          // Card background
+    muted: string;         // Muted text/elements
+    border: string;        // Border color
+  };
+
+  // Typography
+  typography?: {
+    fontFamily?: string;   // Font family
+    headingWeight?: string; // "font-bold", etc.
+    bodyWeight?: string;   // "font-normal", etc.
+  };
+
+  // Layout
+  layout?: {
+    maxWidth?: string;     // "max-w-4xl", etc.
+    padding?: string;      // "p-6", etc.
+    spacing?: string;      // "space-y-6", etc.
+  };
+
+  // Component-specific overrides
+  components?: {
+    loginPage?: Partial<LoginPageTheme>;
+    profilePage?: Partial<ProfilePageTheme>;
+    recoveryPage?: Partial<RecoveryPageTheme>;
+  };
+}
+
+export interface LoginPageTheme {
+  cardBackground: string;
+  gradient: string;
+  buttonColor: string;
+  showLogo: boolean;
+}
+
+export interface ProfilePageTheme {
+  layout: "centered" | "full-width";
+  showAvatar: boolean;
+}
+
+export interface RecoveryPageTheme {
+  layout: "centered" | "full-width";
+}

package/src/theme/useTheme.ts

@@ -0,0 +1,57 @@
+/**
+ * Theme Hooks for @payez/next-mvp
+ *
+ * Convenience hooks for accessing specific parts of the theme configuration.
+ * These hooks can only be used within components wrapped by ThemeProvider.
+ */
+
+'use client';
+
+import { useTheme as useThemeContext } from './ThemeProvider';
+
+/**
+ * Access the full theme configuration
+ */
+export function useTheme() {
+  return useThemeContext();
+}
+
+/**
+ * Access branding configuration (logo, app name, tagline)
+ */
+export function useBranding() {
+  const theme = useThemeContext();
+  return theme.branding;
+}
+
+/**
+ * Access color configuration
+ */
+export function useColors() {
+  const theme = useThemeContext();
+  return theme.colors;
+}
+
+/**
+ * Access typography configuration
+ */
+export function useTypography() {
+  const theme = useThemeContext();
+  return theme.typography;
+}
+
+/**
+ * Access layout configuration
+ */
+export function useLayout() {
+  const theme = useThemeContext();
+  return theme.layout;
+}
+
+/**
+ * Access component-specific theme overrides
+ */
+export function useComponentTheme() {
+  const theme = useThemeContext();
+  return theme.components;
+}

package/src/theme/utils.ts

@@ -0,0 +1,40 @@
+/**
+ * Theme Utility Functions
+ *
+ * Provides helper functions for theme management, including deep merging
+ * of theme configurations.
+ */
+
+/**
+ * Deep merge two objects, with the second object taking precedence
+ * @param target - Base object
+ * @param source - Object to merge in (takes precedence)
+ * @returns Merged object
+ */
+export function mergeDeep<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+  const output: any = { ...target };
+
+  if (isObject(target) && isObject(source)) {
+    Object.keys(source).forEach((key) => {
+      const sourceValue = (source as any)[key];
+      const targetValue = (target as any)[key];
+
+      if (isObject(sourceValue) && isObject(targetValue)) {
+        // Recursively merge nested objects
+        output[key] = mergeDeep(targetValue, sourceValue);
+      } else if (sourceValue !== undefined) {
+        // Use source value if it's defined
+        output[key] = sourceValue;
+      }
+    });
+  }
+
+  return output as T;
+}
+
+/**
+ * Check if a value is a plain object
+ */
+function isObject(item: any): item is Record<string, any> {
+  return item && typeof item === 'object' && !Array.isArray(item);
+}

package/src/types/api.ts

@@ -0,0 +1,13 @@
+export interface ApiResponse<T = any> { success: boolean; data?: T; error?: ApiError; meta?: ApiMeta; timestamp: string; requestId: string; }
+export interface ApiError { code: string; message: string; details?: Record<string, any>; field?: string; resolution?: string; supportContact?: string; remainingAttempts?: number; }
+export interface ApiMeta { version: string; responseTime: number; operation?: string; rateLimit?: { limit: number; remaining: number; resetAt: string; }; pagination?: { page: number; pageSize: number; total: number; totalPages: number; }; cached?: boolean; filters?: Record<string, any>; aggregation?: Record<string, any>; resourceId?: string | number; }
+export interface ApiRequestContext { requestId: string; startTime: number; userAgent?: string; ipAddress?: string; userId?: string; sessionId?: string; endpoint: string; method: string; params?: Record<string, string>; headers?: Record<string, string>; }
+export interface ApiValidationError { field: string; message: string; code: string; value?: any; }
+export interface ApiAuthContext { accessToken: string | null; tokenType: string; refreshToken: string | null; userId?: string; roles?: string[]; sessionId?: string; expiresAt?: number; }
+export interface ApiHandlerConfig { requireAuth?: boolean; requiredRoles?: readonly string[]; rateLimit?: { windowMs: number; maxRequests: number; }; validation?: { body?: any; query?: any; params?: any; }; timeout?: number; retries?: number; cacheTtl?: number; tokenRefreshBuffer?: number; }
+export interface ApiMiddleware { name: string; execute: (context: ApiRequestContext, config: ApiHandlerConfig) => Promise<void>; }
+export enum ApiErrorCode { UNAUTHORIZED='UNAUTHORIZED', FORBIDDEN='FORBIDDEN', TOKEN_EXPIRED='TOKEN_EXPIRED', INVALID_TOKEN='INVALID_TOKEN', INVALID_SESSION='INVALID_SESSION', INVALID_2FA_TOKEN='INVALID_2FA_TOKEN', INSUFFICIENT_PERMISSIONS='INSUFFICIENT_PERMISSIONS', RATE_LIMIT_EXCEEDED='RATE_LIMIT_EXCEEDED', TOO_MANY_REQUESTS='TOO_MANY_REQUESTS', VALIDATION_ERROR='VALIDATION_ERROR', INVALID_REQUEST='INVALID_REQUEST', MISSING_REQUIRED_FIELD='MISSING_REQUIRED_FIELD', INVALID_FORMAT='INVALID_FORMAT', RESOURCE_NOT_FOUND='RESOURCE_NOT_FOUND', NOT_FOUND='NOT_FOUND', RESOURCE_CONFLICT='RESOURCE_CONFLICT', CONFLICT='CONFLICT', BUSINESS_RULE_VIOLATION='BUSINESS_RULE_VIOLATION', NOT_IMPLEMENTED='NOT_IMPLEMENTED', INTERNAL_ERROR='INTERNAL_ERROR', INTERNAL_SERVER_ERROR='INTERNAL_SERVER_ERROR', SERVICE_UNAVAILABLE='SERVICE_UNAVAILABLE', TIMEOUT='TIMEOUT', CIRCUIT_BREAKER_OPEN='CIRCUIT_BREAKER_OPEN', UPSTREAM_SERVICE_ERROR='UPSTREAM_SERVICE_ERROR', NETWORK_ERROR='NETWORK_ERROR', CONNECTION_ERROR='CONNECTION_ERROR', UNKNOWN_ERROR='UNKNOWN_ERROR' }
+export const ApiErrorMessages: Record<ApiErrorCode, string> = { [ApiErrorCode.UNAUTHORIZED]:'Authentication required',[ApiErrorCode.FORBIDDEN]:'Access denied',[ApiErrorCode.TOKEN_EXPIRED]:'Authentication token has expired',[ApiErrorCode.INVALID_TOKEN]:'Invalid authentication token',[ApiErrorCode.INVALID_SESSION]:'Invalid session - please log in again',[ApiErrorCode.INVALID_2FA_TOKEN]:'Invalid or expired 2FA verification token',[ApiErrorCode.INSUFFICIENT_PERMISSIONS]:'Insufficient permissions for this resource',[ApiErrorCode.RATE_LIMIT_EXCEEDED]:'Rate limit exceeded',[ApiErrorCode.TOO_MANY_REQUESTS]:'Too many requests',[ApiErrorCode.VALIDATION_ERROR]:'Request validation failed',[ApiErrorCode.INVALID_REQUEST]:'Invalid request format',[ApiErrorCode.MISSING_REQUIRED_FIELD]:'Required field is missing',[ApiErrorCode.INVALID_FORMAT]:'Invalid data format',[ApiErrorCode.RESOURCE_NOT_FOUND]:'Resource not found',[ApiErrorCode.NOT_FOUND]:'Not found',[ApiErrorCode.RESOURCE_CONFLICT]:'Resource conflict',[ApiErrorCode.CONFLICT]:'Conflict',[ApiErrorCode.BUSINESS_RULE_VIOLATION]:'Business rule violation',[ApiErrorCode.NOT_IMPLEMENTED]:'Feature not yet implemented',[ApiErrorCode.INTERNAL_ERROR]:'Internal error occurred',[ApiErrorCode.INTERNAL_SERVER_ERROR]:'Internal server error',[ApiErrorCode.SERVICE_UNAVAILABLE]:'Service temporarily unavailable',[ApiErrorCode.TIMEOUT]:'Request timeout',[ApiErrorCode.CIRCUIT_BREAKER_OPEN]:'Service circuit breaker is open',[ApiErrorCode.UPSTREAM_SERVICE_ERROR]:'Upstream service error',[ApiErrorCode.NETWORK_ERROR]:'Network error',[ApiErrorCode.CONNECTION_ERROR]:'Connection error',[ApiErrorCode.UNKNOWN_ERROR]:'An unknown error occurred' };
+export type ApiSuccessResponse<T> = ApiResponse<T> & { success: true; data: T; message: string; operation_code: string; };
+export type ApiErrorResponse = ApiResponse<never> & { success: false; error: ApiError };
+export class ApiResponseBuilder { private context: ApiRequestContext; private config: ApiHandlerConfig; constructor(context: ApiRequestContext, config: ApiHandlerConfig = {}) { this.context = context; this.config = config; } success<T>(data: T, meta?: Partial<ApiMeta>): ApiSuccessResponse<T> { return { success: true, data, message: meta?.operation ? `${meta.operation.replace(/-/g, ' ')} completed successfully` : 'Operation completed successfully', operation_code: meta?.operation || 'unknown-operation', meta: { version:'1.0', responseTime: Date.now() - this.context.startTime, ...meta }, timestamp: new Date().toISOString(), requestId: this.context.requestId }; } error(code: ApiErrorCode, message?: string, details?: Record<string, any>, field?: string): ApiErrorResponse { const errorMessage = message || ApiErrorMessages[code]; const enhancedDetails = { ...details, ...(this.context.endpoint && { endpoint: this.context.endpoint }), ...(this.context.method && { method: this.context.method }), timestamp: new Date().toISOString() }; return { success: false, error: { code, message: errorMessage, details: enhancedDetails, field, resolution: this.getResolution(code), supportContact: process.env.SUPPORT_CONTACT }, meta: { version: '1.0', responseTime: Date.now() - this.context.startTime }, timestamp: new Date().toISOString(), requestId: this.context.requestId }; } private getResolution(code: ApiErrorCode): string | undefined { const resolutions: Partial<Record<ApiErrorCode, string>> = { [ApiErrorCode.RATE_LIMIT_EXCEEDED]:'Please try again later',[ApiErrorCode.TOKEN_EXPIRED]:'Please refresh your session',[ApiErrorCode.UNAUTHORIZED]:'Please log in again',[ApiErrorCode.SERVICE_UNAVAILABLE]:'Please try again in a few minutes',[ApiErrorCode.CIRCUIT_BREAKER_OPEN]:'Service is temporarily unavailable. Please try again later.' }; return resolutions[code]; }}

package/src/types/auth.d.ts

@@ -0,0 +1,15 @@
+export type Session = import('next-auth').Session;
+export type JWT = import('next-auth/jwt').JWT;
+export type TwoFactorMethod = 'none' | 'sms' | 'authenticator' | 'passkey';
+
+export interface User {
+  id: string; email: string; name?: string | null; roles: string[]; twoFactorMethod?: TwoFactorMethod; requiresTwoFactor: boolean; accessToken?: string; refreshToken?: string; tokenType?: string;
+  authenticationMethods?: string[]; authenticationLevel?: string;
+}
+
+export interface JwtPayload { [key: string]: unknown; sub: string; email: string; name?: string; roles?: string[]; exp: number; iat: number; aud: string; iss: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
+export interface JwtPayloadWithRoles extends JwtPayload { roles: string[]; requiresTwoFactor: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
+
+export interface AuthorizeCredentials { email?: string; password?: string; token?: string; twoFactorCode?: string; twoFactorMethod?: TwoFactorMethod; }
+
+export interface ApiResponse { access_token?: string; refresh_token?: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; user_id?: string; email?: string; name?: string; roles?: string[]; error?: string; message?: string; result?: { access_token?: string; refresh_token?: string; name?: string; error?: string; id?: string; email?: string; roles?: string[]; user?: { email?: string; name?: string; roles?: string[]; id?: string; twoFactorMethod?: TwoFactorMethod | null; requiresTwoFactor?: boolean; accessToken?: string; refreshToken?: string; tokenType?: string; }; }; }

package/src/types/auth.ts

@@ -0,0 +1,22 @@
+import { JwtPayload } from 'jwt-decode';
+
+export type AuthMode = 'traditional' | 'federated';
+export type FederatedProvider = 'google' | 'microsoft' | 'facebook' | 'github' | 'apple';
+
+export interface AuthConfig {
+  mode: AuthMode;
+  providers: FederatedProvider[];
+  enableRecovery: boolean;
+  enableEmailSignup: boolean;
+  allowPasswordReset: boolean;
+}
+
+export interface JwtPayloadWithRoles extends JwtPayload {
+    role?: string | string[];
+    roles?: string[];
+    amr?: string[];
+    acr?: string;
+    mfa_time?: number;
+    mfa_expires?: number;
+    mfa_validity_hours?: number;
+}

package/src/types/logging.ts

@@ -0,0 +1,11 @@
+export interface LoggingConfig {
+  logLevel: LogLevel;
+  console: { enabled: boolean; colors: boolean; };
+  graylog: { enabled: boolean; host: string; port: number; facility: string; staticMeta: { service: string; application: string; version: string; [key: string]: any; }; };
+  components: { [key: string]: { enabled: boolean; prefix: string; }; };
+  levels: { [key: string]: number; };
+}
+export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'debug';
+export interface ComponentLoggerConfig { enabled: boolean; prefix: string; }
+export interface Logger { error: (message: string, meta?: any) => void; warn: (message: string, meta?: any) => void; info: (message: string, meta?: any) => void; http: (message: string, meta?: any) => void; debug: (message: string, meta?: any) => void; }
+export interface ComponentLogger extends Logger {}

package/src/types/next-auth.d.ts

@@ -0,0 +1,15 @@
+import { DefaultSession } from 'next-auth';
+
+declare module 'next-auth' {
+  interface Session extends DefaultSession {
+    accessToken?: string;
+    refreshToken?: string;
+    accessTokenExpires?: number;
+    error?: string;
+    user: {
+      id: string;
+      requiresTwoFactor?: boolean;
+      twoFactorSessionVerified?: boolean;
+    } & DefaultSession['user'];
+  }
+}

package/src/types/recovery.ts

@@ -0,0 +1,54 @@
+export type RecoveryStep = 'initiate' | 'select-method' | 'verify-code' | 'set-password' | 'complete';
+
+export interface RecoverySession {
+  recoveryToken: string;
+  email: string;
+  maskedEmail?: string;
+  maskedPhone?: string;
+  hasAuthenticator?: boolean;
+  availableMethods: Array<'email' | 'sms' | 'authenticator'>;
+  expiresAt: string;
+}
+
+export interface PasswordResetToken {
+  token: string;
+  expiresAt: string;
+}
+
+export interface RecoveryError {
+  code: string;
+  message: string;
+  attemptsRemaining?: number;
+}
+
+export interface RecoveryInitiateResponse {
+  success: boolean;
+  data: {
+    recovery_session_token?: string;
+    masked_email?: string;
+    masked_phone?: string;
+    has_authenticator?: boolean;
+    available_methods?: Array<'email' | 'sms' | 'authenticator'>;
+    expires_at?: string;
+    message?: string;
+  };
+}
+
+export interface SendCodeResponse {
+  success: boolean;
+  data: {
+    method: string;
+    masked_destination: string;
+    code_length: number;
+    expires_in: number;
+  };
+}
+
+export interface VerifyCodeResponse {
+  success: boolean;
+  data?: {
+    password_reset_token: string;
+    expires_at: string;
+  };
+  error?: RecoveryError;
+}

package/src/types/security.ts

@@ -0,0 +1 @@
+export type TwoFactorMethod = 'email' | 'sms' | 'authenticator';