@digilogiclabs/saas-factory-auth 0.2.0 → 0.3.2

package/dist/index.d.mts

@@ -1,8 +1,174 @@
-import { User } from '@supabase/supabase-js';
+import * as _supabase_auth_js from '@supabase/auth-js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode } from 'react';
 import * as zustand from 'zustand';
-import * as _supabase_auth_helpers_nextjs from '@supabase/auth-helpers-nextjs';
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * Common user interface that abstracts user data across different authentication providers
+ */
+interface CommonUser {
+    /** Unique user identifier */
+    id: string;
+    /** User's email address */
+    email: string | undefined;
+    /** User's display name */
+    displayName?: string | null;
+    /** URL to user's profile photo */
+    photoURL?: string | null;
+    /** User roles for authorization */
+    roles?: string[];
+    /** Provider-specific metadata */
+    metadata: Record<string, any>;
+}
+/**
+ * Authentication session interface that wraps user data
+ */
+interface AuthSession {
+    /** Current authenticated user */
+    user: CommonUser | null;
+    /** Session expiration timestamp (optional) */
+    expiresAt?: number;
+    /** Access token (optional, provider-specific) */
+    accessToken?: string;
+}
+/**
+ * Authentication error types for better error handling
+ */
+declare enum AuthErrorType {
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    EMAIL_ALREADY_EXISTS = "EMAIL_ALREADY_EXISTS",
+    WEAK_PASSWORD = "WEAK_PASSWORD",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    PROVIDER_ERROR = "PROVIDER_ERROR",
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+}
+/**
+ * Custom authentication error class
+ */
+declare class AuthError extends Error {
+    readonly type: AuthErrorType;
+    readonly originalError?: any | undefined;
+    readonly context?: Record<string, any> | undefined;
+    readonly timestamp: Date;
+    readonly code: string;
+    constructor(type: AuthErrorType, message: string, originalError?: any | undefined, context?: Record<string, any> | undefined);
+    /**
+     * Convert error to JSON for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        type: AuthErrorType;
+        code: string;
+        message: string;
+        timestamp: string;
+        context: Record<string, any> | undefined;
+        originalError: {
+            name: any;
+            message: any;
+            code: any;
+        } | undefined;
+    };
+    /**
+     * Check if error is of a specific type
+     */
+    isType(type: AuthErrorType): boolean;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Authentication state change events
+ */
+declare enum AuthEvent {
+    SIGNED_IN = "SIGNED_IN",
+    SIGNED_OUT = "SIGNED_OUT",
+    TOKEN_REFRESHED = "TOKEN_REFRESHED",
+    USER_UPDATED = "USER_UPDATED"
+}
+/**
+ * OAuth provider types
+ */
+type OAuthProvider = 'google' | 'github' | 'facebook' | 'twitter' | 'discord' | 'apple';
+/**
+ * Authentication provider interface that abstracts authentication operations
+ * across different backends (Supabase, Firebase, etc.)
+ */
+interface IAuthProvider {
+    /**
+     * Sign in with email and password
+     * @param email User's email address
+     * @param password User's password (required for email/password authentication)
+     * @returns Promise resolving to the authenticated user or null
+     * @throws AuthError when authentication fails
+     */
+    signIn(email: string, password?: string): Promise<CommonUser | null>;
+    /**
+     * Sign up with email and password
+     * @param email User's email address
+     * @param password User's password (required for email/password authentication)
+     * @returns Promise resolving to the created user or null
+     * @throws AuthError when sign up fails
+     */
+    signUp(email: string, password?: string): Promise<CommonUser | null>;
+    /**
+     * Sign in with OAuth provider
+     * @param provider OAuth provider name
+     * @param redirectTo Optional redirect URL after authentication
+     * @returns Promise that resolves when OAuth flow is initiated
+     * @throws AuthError when OAuth flow fails to initiate
+     */
+    signInWithOAuth(provider: OAuthProvider, redirectTo?: string): Promise<void>;
+    /**
+     * Sign in with magic link (passwordless authentication)
+     * @param email User's email address
+     * @param redirectTo Optional redirect URL after email verification
+     * @returns Promise that resolves when magic link is sent
+     * @throws AuthError when magic link sending fails
+     */
+    signInWithMagicLink(email: string, redirectTo?: string): Promise<void>;
+    /**
+     * Sign out the current user
+     * @returns Promise that resolves when sign out is complete
+     * @throws AuthError when sign out fails
+     */
+    signOut(): Promise<void>;
+    /**
+     * Send password reset email
+     * @param email User's email address
+     * @returns Promise that resolves when reset email is sent
+     * @throws AuthError when password reset fails
+     */
+    resetPassword(email: string): Promise<void>;
+    /**
+     * Get the current authenticated user
+     * @returns Promise resolving to the current user or null if not authenticated
+     * @throws AuthError when user retrieval fails
+     */
+    getUser(): Promise<CommonUser | null>;
+    /**
+     * Listen for authentication state changes
+     * @param callback Function called when auth state changes
+     * @returns Object containing subscription data for cleanup
+     */
+    onAuthStateChange(callback: (event: AuthEvent, session: AuthSession | null) => void): {
+        data: {
+            subscription: any;
+        } | {
+            unsubscribe: () => void;
+        };
+    };
+    /**
+     * Validate provider configuration
+     * @returns Promise that resolves if configuration is valid
+     * @throws AuthError when configuration is invalid
+     */
+    validateConfiguration?(): Promise<void>;
+}
 
 type AuthMode = 'signIn' | 'signUp' | 'resetPassword' | 'magicLink';
 interface UserRole {
@@ -26,78 +192,438 @@ interface AuthFormProps {
     onSuccess?: () => void;
     onError?: (error: Error) => void;
     redirectTo?: string;
-    providers?: string[];
+    providers?: OAuthProvider[];
     allowMagicLink?: boolean;
 }
 interface AuthState {
-    user: User | null;
+    user: CommonUser | null;
     loading: boolean;
     error: Error | null;
 }
 interface AuthStore extends AuthState {
-    signIn: (email: string, password: string) => Promise<void>;
-    signUp: (email: string, password: string) => Promise<void>;
-    signInWithOAuth: (provider: string, redirectTo?: string) => Promise<void>;
+    signIn: (email: string, password?: string) => Promise<void>;
+    signUp: (email: string, password?: string) => Promise<void>;
+    signInWithOAuth: (provider: OAuthProvider, redirectTo?: string) => Promise<void>;
     signInWithMagicLink: (email: string, redirectTo?: string) => Promise<void>;
     signOut: () => Promise<void>;
     resetPassword: (email: string) => Promise<void>;
-    updateUser: (user: User | null) => void;
+    getUser: () => Promise<CommonUser | null>;
+    onAuthStateChange: (callback: (event: any, session: any) => void) => any;
+    updateUser: (user: CommonUser | null) => void;
     setLoading: (loading: boolean) => void;
     setError: (error: Error | null) => void;
 }
 
-declare const useAuth: () => AuthStore;
+interface IAuthStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare class WebAuthStorage implements IAuthStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare class NativeAuthStorage implements IAuthStorage {
+    private AsyncStorage;
+    constructor();
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare const createAuthStorage: () => IAuthStorage;
 
-declare const AuthProvider: ({ children }: {
-    children: ReactNode;
-}) => react_jsx_runtime.JSX.Element;
-declare const useAuthContext: () => AuthStore;
-
-declare const useAuthStore: zustand.UseBoundStore<zustand.StoreApi<AuthStore>>;
-
-type Database = {
-    public: {
-        Tables: {
-            profiles: {
-                Row: {
-                    id: string;
-                    updated_at: string;
-                    username: string;
-                    full_name: string;
-                    avatar_url: string;
-                    website: string;
-                };
-                Insert: {
-                    id: string;
-                    updated_at?: string;
-                    username: string;
-                    full_name?: string;
-                    avatar_url?: string;
-                    website?: string;
-                };
-                Update: {
-                    id?: string;
-                    updated_at?: string;
-                    username?: string;
-                    full_name?: string;
-                    avatar_url?: string;
-                    website?: string;
-                };
-            };
-        };
-        Views: {
-            [_ in never]: never;
-        };
-        Functions: {
-            [_ in never]: never;
+/**
+ * Supported authentication provider types
+ */
+type AuthProviderType = 'supabase' | 'firebase';
+/**
+ * Configuration interface for provider factory
+ */
+interface AuthProviderConfig {
+    /** Provider type to use */
+    type: AuthProviderType;
+    /** Whether to validate configuration on creation */
+    validateConfig?: boolean;
+    /** Whether to use singleton pattern */
+    useSingleton?: boolean;
+    /** Custom storage implementation (optional) */
+    storage?: IAuthStorage;
+}
+/**
+ * Factory class for creating authentication providers with improved patterns
+ */
+declare class AuthProviderFactory {
+    private static instances;
+    /**
+     * Gets provider based on environment variables (auto-detection)
+     * @param config Optional configuration overrides
+     * @returns Authentication provider instance
+     */
+    static getProviderFromEnvironment(config?: Partial<AuthProviderConfig>): Promise<IAuthProvider>;
+    /**
+     * Gets provider instance with configuration
+     * @param config Provider configuration
+     * @returns Authentication provider instance
+     */
+    static getProvider(config: AuthProviderConfig): Promise<IAuthProvider>;
+    /**
+     * Creates a new provider instance without caching
+     * @param type Provider type
+     * @param storage Optional custom storage implementation
+     * @returns Authentication provider instance
+     */
+    static createProvider(type: AuthProviderType, storage?: IAuthStorage): IAuthProvider;
+    /**
+     * Detects provider type from environment variables
+     * @returns Detected provider type
+     */
+    private static detectProviderFromEnvironment;
+    /**
+     * Gets explicit provider from environment variables (platform-agnostic)
+     */
+    private static getExplicitProvider;
+    /**
+     * Validates if a string is a valid provider type
+     * @param type String to validate
+     * @returns True if valid provider type
+     */
+    private static isValidProviderType;
+    /**
+     * Gets list of supported provider types
+     * @returns Array of supported provider types
+     */
+    static getSupportedProviders(): AuthProviderType[];
+    /**
+     * Checks if a provider type is supported
+     * @param type Provider type to check
+     * @returns True if supported
+     */
+    static isProviderSupported(type: string): type is AuthProviderType;
+    /**
+     * Clears singleton instances (useful for testing)
+     */
+    static clearInstances(): void;
+    /**
+     * Gets current singleton instances (useful for debugging)
+     * @returns Map of current instances
+     */
+    static getInstances(): Map<AuthProviderType, IAuthProvider>;
+}
+
+/**
+ * Supabase authentication provider implementation
+ */
+declare class SupabaseAuthProvider implements IAuthProvider {
+    private client;
+    private storage;
+    constructor(storage: IAuthStorage);
+    /**
+     * Validates Supabase configuration
+     */
+    validateConfiguration(): Promise<void>;
+    signIn(email: string, password?: string): Promise<CommonUser | null>;
+    signUp(email: string, password?: string): Promise<CommonUser | null>;
+    signInWithOAuth(provider: OAuthProvider, redirectTo?: string): Promise<void>;
+    signInWithMagicLink(email: string, redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getUser(): Promise<CommonUser | null>;
+    onAuthStateChange(callback: (event: AuthEvent, session: AuthSession | null) => void): {
+        data: {
+            subscription: any;
+        } | {
+            unsubscribe: () => void;
         };
-        Enums: {
-            [_ in never]: never;
+    };
+}
+
+/**
+ * Firebase authentication provider implementation
+ */
+declare class FirebaseAuthProvider implements IAuthProvider {
+    private app;
+    private auth;
+    private storage;
+    constructor(storage: IAuthStorage);
+    /**
+     * Validates Firebase configuration
+     */
+    validateConfiguration(): Promise<void>;
+    signIn(email: string, password?: string): Promise<CommonUser | null>;
+    signUp(email: string, password?: string): Promise<CommonUser | null>;
+    signInWithOAuth(provider: OAuthProvider, redirectTo?: string): Promise<void>;
+    signInWithMagicLink(email: string, redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getUser(): Promise<CommonUser | null>;
+    onAuthStateChange(callback: (event: AuthEvent, session: AuthSession | null) => void): {
+        data: {
+            subscription: any;
+        } | {
+            unsubscribe: () => void;
         };
     };
+}
+
+declare const useAuth: () => {
+    signIn: (email: string, password?: string) => Promise<void>;
+    signUp: (email: string, password?: string) => Promise<void>;
+    signInWithOAuth: (provider: OAuthProvider, redirectTo?: string) => Promise<void>;
+    signInWithMagicLink: (email: string, redirectTo?: string) => Promise<void>;
+    signOut: () => Promise<void>;
+    resetPassword: (email: string) => Promise<void>;
+    getUser: () => Promise<CommonUser | null>;
+    onAuthStateChange: (callback: (event: any, session: any) => void) => any;
+    updateUser: (user: CommonUser | null) => void;
+    setLoading: (loading: boolean) => void;
+    setError: (error: Error | null) => void;
+    user: CommonUser | null;
+    loading: boolean;
+    error: Error | null;
 };
 
-declare const createClient: () => _supabase_auth_helpers_nextjs.SupabaseClient<Database, "public", any>;
-declare const supabase: _supabase_auth_helpers_nextjs.SupabaseClient<Database, "public", any>;
+interface UseAuthFormOptions {
+    onSuccess?: () => void;
+    onError?: (error: AuthError) => void;
+    redirectUrl?: string;
+}
+interface AuthFormState {
+    email: string;
+    password: string;
+    confirmPassword: string;
+    loading: boolean;
+    error: string | null;
+    message: string | null;
+}
+interface AuthFormActions {
+    setEmail: (email: string) => void;
+    setPassword: (password: string) => void;
+    setConfirmPassword: (password: string) => void;
+    handleSignIn: () => Promise<void>;
+    handleSignUp: () => Promise<void>;
+    handleOAuthSignIn: (provider: OAuthProvider) => Promise<void>;
+    handlePasswordReset: () => Promise<void>;
+    handleMagicLink: () => Promise<void>;
+    clearError: () => void;
+    clearMessage: () => void;
+}
+declare const useAuthForm: (options?: UseAuthFormOptions) => AuthFormState & AuthFormActions;
+
+interface UseProtectedRouteOptions {
+    redirectTo?: string;
+    requiredRoles?: string[];
+    onUnauthorized?: () => void;
+    onUnauthenticated?: () => void;
+}
+declare const useProtectedRoute: (options?: UseProtectedRouteOptions) => {
+    user: CommonUser | null | undefined;
+    loading: boolean | undefined;
+    isAuthenticated: boolean;
+};
+
+declare function useRBAC(): {
+    checkPermission: (permission: string) => boolean;
+    hasRole: (role: string) => boolean;
+};
+
+declare function use2FA(): {
+    setup2FA: () => Promise<{
+        id: string;
+        type: "totp";
+        totp: {
+            qr_code: string;
+            secret: string;
+            uri: string;
+        };
+        friendly_name?: string;
+    }>;
+    verify2FA: (factorId: string, challengeId: string, code: string) => Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in: number;
+        refresh_token: string;
+        user: _supabase_auth_js.User;
+    }>;
+    unenroll2FA: (factorId: string) => Promise<{
+        id: string;
+    }>;
+    loading: boolean;
+    error: Error | null;
+};
+
+declare function useRedirectUrl(defaultUrl?: string): string;
+
+declare const AuthContext: react.Context<AuthStore | null>;
+interface AuthProviderProps {
+    children: ReactNode;
+    providerType?: AuthProviderType;
+    storage?: IAuthStorage;
+}
+declare const AuthProvider: ({ children, providerType, storage }: AuthProviderProps) => react_jsx_runtime.JSX.Element;
+
+interface AuthStoreProps {
+    authProvider: IAuthProvider;
+}
+declare const createAuthStore: ({ authProvider }: AuthStoreProps) => zustand.UseBoundStore<zustand.StoreApi<AuthStore>>;
+
+declare const defaultAuthConfig: AuthConfig;
+
+declare function validatePassword(password: string, config: AuthConfig['passwordRequirements']): boolean;
+
+/**
+ * Validation utilities for authentication inputs
+ */
+declare class ValidationUtils {
+    /**
+     * Validate email address format
+     */
+    static validateEmail(email: string): void;
+    /**
+     * Validate password strength
+     */
+    static validatePassword(password: string, requirements?: {
+        minLength?: number;
+        requireNumbers?: boolean;
+        requireSpecialChars?: boolean;
+        requireUppercase?: boolean;
+    }): void;
+    /**
+     * Validate OAuth provider
+     */
+    static validateOAuthProvider(provider: string): void;
+    /**
+     * Validate URL format
+     */
+    static validateUrl(url: string, fieldName?: string): void;
+    /**
+     * Validate required string field
+     */
+    static validateRequiredString(value: any, fieldName: string): void;
+    /**
+     * Sanitize email input
+     */
+    static sanitizeEmail(email: string): string;
+    /**
+     * Check if error is a validation error
+     */
+    static isValidationError(error: any): error is AuthError;
+}
+/**
+ * Decorator for validating method parameters
+ */
+declare function validateParams(validations: Record<string, (value: any) => void>): (target: any, propertyName: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * Performance optimization utilities for authentication operations
+ */
+/**
+ * Simple memoization utility for caching function results
+ */
+declare function memoize<T extends (...args: any[]) => any>(fn: T, keyGenerator?: (...args: Parameters<T>) => string): T;
+/**
+ * Debounce utility for rate-limiting function calls
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle utility for limiting function call frequency
+ */
+declare function throttle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Retry utility with exponential backoff
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number, maxDelay?: number): Promise<T>;
+/**
+ * Simple LRU cache implementation
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    clear(): void;
+    size(): number;
+}
+/**
+ * Performance monitoring utility
+ */
+declare class PerformanceMonitor {
+    private static timers;
+    static start(label: string): void;
+    static end(label: string): number;
+    static measure<T>(label: string, fn: () => T): T;
+    static measureAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Health check result interface
+ */
+interface HealthCheckResult {
+    status: 'healthy' | 'warning' | 'error';
+    message: string;
+    details?: Record<string, any>;
+    timestamp: Date;
+}
+/**
+ * Comprehensive health check results
+ */
+interface SystemHealthCheck {
+    overall: 'healthy' | 'warning' | 'error';
+    checks: {
+        configuration: HealthCheckResult;
+        provider: HealthCheckResult;
+        storage: HealthCheckResult;
+        network?: HealthCheckResult;
+    };
+    timestamp: Date;
+}
+/**
+ * Health check utilities for authentication system
+ */
+declare class HealthChecker {
+    /**
+     * Perform comprehensive system health check
+     */
+    static performHealthCheck(): Promise<SystemHealthCheck>;
+    /**
+     * Check configuration validity
+     */
+    static checkConfiguration(): Promise<HealthCheckResult>;
+    /**
+     * Check provider initialization
+     */
+    static checkProvider(): Promise<HealthCheckResult>;
+    /**
+     * Check storage functionality
+     */
+    static checkStorage(): Promise<HealthCheckResult>;
+    /**
+     * Check network connectivity to authentication services
+     */
+    static checkNetworkConnectivity(): Promise<HealthCheckResult>;
+    /**
+     * Generate health check report
+     */
+    static generateReport(healthCheck: SystemHealthCheck): string;
+    /**
+     * Quick health check for monitoring
+     */
+    static quickCheck(): Promise<boolean>;
+}
+
+declare function withAuth(middleware: (request: NextRequest) => Promise<NextResponse> | NextResponse, options?: {
+    publicRoutes?: string[];
+    loginRoute?: string;
+}): (req: NextRequest) => Promise<NextResponse<unknown>>;
+
+declare function handleEmailVerification(token: string): Promise<{
+    success: boolean;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: unknown;
+}>;
 
-export { type AuthConfig, type AuthFormProps, type AuthMode, AuthProvider, type AuthState, type AuthStore, type UserRole, createClient, supabase, useAuth, useAuthContext, useAuthStore };
+export { type AuthConfig, AuthContext, AuthError, AuthErrorType, AuthEvent, type AuthFormActions, type AuthFormProps, type AuthFormState, type AuthMode, AuthProvider, type AuthProviderConfig, AuthProviderFactory, type AuthProviderType, type AuthSession, type AuthState, type AuthStore, type CommonUser, FirebaseAuthProvider, type HealthCheckResult, HealthChecker, type IAuthProvider, type IAuthStorage, LRUCache, NativeAuthStorage, type OAuthProvider, PerformanceMonitor, SupabaseAuthProvider, type SystemHealthCheck, type UseAuthFormOptions, type UseProtectedRouteOptions, type UserRole, ValidationUtils, WebAuthStorage, createAuthStorage, createAuthStore, debounce, defaultAuthConfig, handleEmailVerification, memoize, retryWithBackoff, throttle, use2FA, useAuth, useAuthForm, useProtectedRoute, useRBAC, useRedirectUrl, validateParams, validatePassword, withAuth };