rn-swiftauth-sdk 1.0.2 → 1.0.3

package/README.md

@@ -237,63 +237,149 @@ const {
 
 ## Error Handling
 
-SwiftAuth maps Firebase errors to user-friendly messages:
+SwiftAuth provides a comprehensive error handling system with custom exceptions that map Firebase errors to user-friendly messages.
+
+### Custom Exception Classes
+
+All errors extend the base `AuthException` class and include:
+- `code`: Machine-readable error code
+- `message`: User-friendly error message
+- `timestamp`: When the error occurred
+- `originalError`: The underlying Firebase error (optional)
+- `toJSON()`: Serialize for logging/debugging
+
+### Supported Exceptions
+
+| Exception Class | Error Code | User Message |
+|-----------------|------------|--------------|
+| `InvalidCredentialsException` | `auth/invalid-credentials` | "Invalid email or password. Please check your credentials and try again." |
+| `UserNotFoundException` | `auth/user-not-found` | "No account found with this email. Please sign up first." |
+| `EmailAlreadyInUseException` | `auth/email-already-in-use` | "This email is already registered. Please sign in or use a different email." |
+| `WeakPasswordException` | `auth/weak-password` | "Password is too weak. Please use at least 6 characters with a mix of letters and numbers." |
+| `TokenExpiredException` | `auth/token-expired` | "Your session has expired. Please sign in again." |
+| `NetworkException` | `auth/network-error` | "Network error. Please check your internet connection and try again." |
+| `GoogleSignInCancelledException` | `auth/google-sign-in-cancelled` | "Google Sign-In was cancelled." |
+| `AppleSignInCancelledException` | `auth/apple-sign-in-cancelled` | "Apple Sign-In was cancelled." |
+| `AppleSignInNotSupportedException` | `auth/apple-sign-in-not-supported` | "Apple Sign-In is only available on iOS 13+ devices." |
+| `GooglePlayServicesUnavailableException` | `auth/google-play-services-unavailable` | "Google Play Services are not available. Please update Google Play Services." |
+| `ConfigurationException` | `auth/configuration-error` | Custom message based on configuration issue |
+| `UnknownAuthException` | `auth/unknown` | "An unexpected error occurred." |
+
+### Basic Error Display
+```typescript
+import { useAuth } from 'rn-swiftauth-sdk';
 
-| Error Code | User Message |
-|------------|--------------|
-| `auth/invalid-credentials` | "Invalid email or password." |
-| `auth/user-not-found` | "Invalid email or password." |
-| `auth/email-already-in-use` | "This email is already registered." |
-| `auth/weak-password` | "Password is too weak." |
-| `auth/network-request-failed` | "Network error. Please check your connection." |
+const LoginScreen = () => {
+  const { error, clearError } = useAuth();
 
-### Basic Usage
+  return (
+    <View>
+      {error && (
+        <View style={styles.errorContainer}>
+          <Text style={styles.errorText}>{error.message}</Text>
+          <Button title="Dismiss" onPress={clearError} />
+        </View>
+      )}
+    </View>
+  );
+};
+```
 
+### Handling Specific Exception Types
 ```typescript
-const { error } = useAuth();
+import { 
+  useAuth,
+  InvalidCredentialsException,
+  EmailAlreadyInUseException,
+  NetworkException 
+} from 'rn-swiftauth-sdk';
 
-if (error) {
-  return <Text style={{ color: 'red' }}>{error.message}</Text>;
-}
-```
+const SignUpScreen = () => {
+  const { signUpWithEmail } = useAuth();
 
-### Advanced: Raw Firebase Errors
+  const handleSignUp = async () => {
+    try {
+      await signUpWithEmail({ email, password });
+    } catch (error) {
+      if (error instanceof EmailAlreadyInUseException) {
+        Alert.alert(
+          "Account Exists",
+          "Would you like to sign in instead?",
+          [
+            { text: "Cancel", style: "cancel" },
+            { text: "Sign In", onPress: () => navigation.navigate('SignIn') }
+          ]
+        );
+      } else if (error instanceof NetworkException) {
+        Alert.alert("Connection Issue", "Please check your internet and try again.");
+      } else if (error instanceof InvalidCredentialsException) {
+        Alert.alert("Invalid Input", "Please check your email and password.");
+      } else {
+        Alert.alert("Error", error.message);
+      }
+    }
+  };
+
+  return <Button title="Sign Up" onPress={handleSignUp} />;
+};
+```
 
-For custom UI implementations, access raw Firebase errors:
+### Accessing Original Firebase Errors
 
-**Method 1: Try/Catch Block**
+For advanced use cases, access the raw Firebase error:
 ```typescript
-const { signInWithEmail } = useAuth();
+const { error } = useAuth();
 
-const handleLogin = async () => {
-  try {
-    await signInWithEmail({ email, password });
-  } catch (rawError: any) {
-    if (rawError.code === 'auth/requires-recent-login') {
-      showReauthModal();
-    } else if (rawError.code === 'auth/quota-exceeded') {
-      Alert.alert("System Overload", "Please try again later.");
+useEffect(() => {
+  if (error?.originalError) {
+    console.log('Firebase Error Code:', error.originalError.code);
+    console.log('Firebase Error Message:', error.originalError.message);
+    
+    // Custom handling for specific Firebase codes
+    if (error.originalError.code === 'auth/requires-recent-login') {
+      showReauthenticationPrompt();
     }
   }
-};
+}, [error]);
 ```
 
-**Method 2: Global State**
+### Error Logging for Debugging
 ```typescript
 const { error } = useAuth();
 
 useEffect(() => {
-  if (error?.originalError) {
-    const rawCode = (error.originalError as any).code;
-    console.log("Raw Firebase Code:", rawCode);
+  if (error) {
+    // Log full error details (includes timestamp, code, original error)
+    console.log('Auth Error:', JSON.stringify(error.toJSON(), null, 2));
     
-    if (rawCode === 'auth/invalid-email') {
-      setLocalizedMessage(t('errors.bad_email'));
-    }
+    // Send to error tracking service (e.g., Sentry)
+    logErrorToService(error.toJSON());
   }
 }, [error]);
 ```
 
+### Global Error Boundary
+```typescript
+import { useAuth } from 'rn-swiftauth-sdk';
+
+const ErrorBoundary = ({ children }) => {
+  const { error, clearError } = useAuth();
+
+  if (error) {
+    return (
+      <View style={styles.errorScreen}>
+        <Text style={styles.errorTitle}>Oops!</Text>
+        <Text style={styles.errorMessage}>{error.message}</Text>
+        <Text style={styles.errorCode}>Error Code: {error.code}</Text>
+        <Button title="Try Again" onPress={clearError} />
+      </View>
+    );
+  }
+
+  return <>{children}</>;
+};
+```
+
 ---
 
 ## Session Management
@@ -421,4 +507,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 - **Issues:** [GitHub Issues](https://github.com/allcodez/Auth-SDK_Stage8/issues)
 - **NPM Package:** [rn-swiftauth-sdk](https://www.npmjs.com/package/rn-swiftauth-sdk)
-- **Documentation:** [Full Docs](https://github.com/allcodez/Auth-SDK_Stage8)
+- **Documentation:** [Full Docs](https://github.com/allcodez/Auth-SDK_Stage8)

package/dist/core/AuthProvider.js

@@ -113,9 +113,11 @@ const AuthProvider = ({ config, children }) => {
                         if (tokenError.code === types_1.ProviderErrorCodes.USER_TOKEN_EXPIRED ||
                             tokenError.code === types_1.ProviderErrorCodes.NULL_USER) {
                             setStatus(types_1.AuthStatus.TOKEN_EXPIRED);
+                            setError((0, errors_1.mapFirebaseError)(tokenError));
                         }
                         else {
                             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
+                            setError((0, errors_1.mapFirebaseError)(tokenError));
                         }
                         setUser(null);
                     }
@@ -128,6 +130,7 @@ const AuthProvider = ({ config, children }) => {
             catch (err) {
                 console.error("Auth State Error:", err);
                 setStatus(types_1.AuthStatus.UNAUTHENTICATED);
+                setError((0, errors_1.mapFirebaseError)(err));
             }
             finally {
                 setIsDataLoading(false);
@@ -145,10 +148,10 @@ const AuthProvider = ({ config, children }) => {
             await FirebaseAuth.signInWithEmailAndPassword(firebaseAuthInstance, email, password);
         }
         catch (err) {
-            const mapped = (0, errors_1.mapFirebaseError)(err);
-            setError({ ...mapped, originalError: err });
+            const mappedException = (0, errors_1.mapFirebaseError)(err);
+            setError(mappedException);
             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
-            throw err;
+            throw mappedException;
         }
     };
     const signUpWithEmail = async ({ email, password }) => {
@@ -160,18 +163,19 @@ const AuthProvider = ({ config, children }) => {
             await FirebaseAuth.createUserWithEmailAndPassword(firebaseAuthInstance, email, password);
         }
         catch (err) {
-            const mapped = (0, errors_1.mapFirebaseError)(err);
-            setError({ ...mapped, originalError: err });
+            const mappedException = (0, errors_1.mapFirebaseError)(err);
+            setError(mappedException);
             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
-            throw err;
+            throw mappedException;
         }
     };
     const signInWithGoogle = async () => {
         if (!firebaseAuthInstance)
             throw new Error('Firebase not initialized');
         if (!config.enableGoogle || !config.googleWebClientId) {
-            setError({ code: types_1.AuthErrorCode.CONFIG_ERROR, message: 'Google Auth not configured. Missing googleWebClientId.' });
-            return;
+            const configError = new errors_1.ConfigurationException('Google Auth not configured. Missing googleWebClientId.');
+            setError(configError);
+            throw configError;
         }
         try {
             setError(null);
@@ -187,55 +191,29 @@ const AuthProvider = ({ config, children }) => {
         }
         catch (err) {
             console.error('Google Sign-In Error:', err);
-            let mappedError;
             if (err.code === types_1.ProviderErrorCodes.GOOGLE_CANCELLED) {
-                mappedError = {
-                    code: types_1.AuthErrorCode.GOOGLE_SIGN_IN_CANCELLED,
-                    message: 'Google Sign-In was cancelled',
-                    originalError: err
-                };
+                const cancelError = new errors_1.GoogleSignInCancelledException(err);
+                setError(cancelError);
                 setStatus(types_1.AuthStatus.UNAUTHENTICATED);
                 return;
             }
-            else if (err.code === types_1.ProviderErrorCodes.GOOGLE_IN_PROGRESS) {
-                mappedError = {
-                    code: types_1.AuthErrorCode.GOOGLE_SIGN_IN_IN_PROGRESS,
-                    message: 'Google Sign-In is already in progress',
-                    originalError: err
-                };
-            }
-            else if (err.code === types_1.ProviderErrorCodes.GOOGLE_PLAY_UNAVAILABLE) {
-                mappedError = {
-                    code: types_1.AuthErrorCode.GOOGLE_PLAY_SERVICES_NOT_AVAILABLE,
-                    message: 'Google Play Services are not available. Please update Google Play Services.',
-                    originalError: err
-                };
-            }
-            else {
-                mappedError = (0, errors_1.mapFirebaseError)(err);
-            }
-            setError({ ...mappedError, originalError: err });
+            const mappedException = (0, errors_1.mapFirebaseError)(err);
+            setError(mappedException);
             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
-            throw mappedError;
+            throw mappedException;
         }
     };
     const signInWithApple = async () => {
         if (!firebaseAuthInstance)
             throw new Error('Firebase not initialized');
         if (react_native_1.Platform.OS !== 'ios') {
-            const platformError = {
-                code: types_1.AuthErrorCode.APPLE_SIGN_IN_NOT_SUPPORTED,
-                message: 'Apple Sign-In is only available on iOS devices',
-            };
+            const platformError = new errors_1.AppleSignInNotSupportedException();
             setError(platformError);
             throw platformError;
         }
         const isAvailable = await AppleAuthentication.isAvailableAsync();
         if (!isAvailable) {
-            const availabilityError = {
-                code: types_1.AuthErrorCode.APPLE_SIGN_IN_NOT_SUPPORTED,
-                message: 'Apple Sign-In is not available on this device (requires iOS 13+)',
-            };
+            const availabilityError = new errors_1.AppleSignInNotSupportedException();
             setError(availabilityError);
             throw availabilityError;
         }
@@ -265,19 +243,15 @@ const AuthProvider = ({ config, children }) => {
         catch (err) {
             console.error('Apple Sign-In Error:', err);
             if (err.code === types_1.ProviderErrorCodes.APPLE_CANCELLED) {
-                const cancelError = {
-                    code: types_1.AuthErrorCode.APPLE_SIGN_IN_CANCELLED,
-                    message: 'Apple Sign-In was cancelled',
-                    originalError: err
-                };
+                const cancelError = new errors_1.AppleSignInCancelledException(err);
                 setError(cancelError);
                 setStatus(types_1.AuthStatus.UNAUTHENTICATED);
                 return;
             }
-            const mappedError = (0, errors_1.mapFirebaseError)(err);
-            setError({ ...mappedError, originalError: err });
+            const mappedException = (0, errors_1.mapFirebaseError)(err);
+            setError(mappedException);
             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
-            throw mappedError;
+            throw mappedException;
         }
     };
     const signOut = async () => {
@@ -297,6 +271,8 @@ const AuthProvider = ({ config, children }) => {
         }
         catch (err) {
             console.error('Sign out error:', err);
+            const signOutError = (0, errors_1.mapFirebaseError)(err);
+            setError(signOutError);
             setUser(null);
             setStatus(types_1.AuthStatus.UNAUTHENTICATED);
         }

package/dist/errors/errorMapper.d.ts

@@ -1,2 +1,10 @@
-import { AuthError } from '../types';
-export declare const mapFirebaseError: (error: any) => AuthError;
+import { AuthException } from './exceptions';
+export declare const mapFirebaseError: (error: any) => AuthException;
+/**
+ * Helper function to check if an error is a specific exception type
+ */
+export declare const isAuthException: (error: any, exceptionType: new (...args: any[]) => AuthException) => boolean;
+/**
+ * Helper to extract user-friendly message from any error
+ */
+export declare const getErrorMessage: (error: any) => string;

package/dist/errors/errorMapper.js

@@ -1,124 +1,86 @@
 "use strict";
+// swiftauth-sdk/src/errors/errorMapper.ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mapFirebaseError = void 0;
+exports.getErrorMessage = exports.isAuthException = exports.mapFirebaseError = void 0;
+const exceptions_1 = require("./exceptions");
 const types_1 = require("../types");
 const mapFirebaseError = (error) => {
-    // Default fallback
-    const fallbackError = {
-        code: types_1.AuthErrorCode.UNKNOWN,
-        message: 'An unexpected error occurred',
-        originalError: error,
-    };
-    // If it's not a Firebase error, return generic
+    // If it's already our custom exception, return it
+    if (error instanceof exceptions_1.AuthException) {
+        return error;
+    }
+    // If it's not a Firebase error or doesn't have a code, return generic
     if (!error || typeof error.code !== 'string') {
-        return {
-            ...fallbackError,
-            message: error?.message || fallbackError.message
-        };
+        return new exceptions_1.UnknownAuthException(error?.message || 'An unexpected error occurred', error);
     }
     const fbError = error;
+    // Map Firebase error codes to custom exceptions
     switch (fbError.code) {
-        // Email/Password Errors
+        // Invalid Credentials
         case 'auth/invalid-email':
-        case 'auth/user-not-found':
         case 'auth/wrong-password':
         case 'auth/invalid-credential':
-            return {
-                code: types_1.AuthErrorCode.INVALID_CREDENTIALS,
-                message: 'Invalid email or password.',
-                originalError: error
-            };
+        case 'auth/user-disabled':
+            return new exceptions_1.InvalidCredentialsException(error);
+        // User Not Found
+        case 'auth/user-not-found':
+            return new exceptions_1.UserNotFoundException(error);
+        // Email Already In Use
         case 'auth/email-already-in-use':
-            return {
-                code: types_1.AuthErrorCode.EMAIL_ALREADY_IN_USE,
-                message: 'This email is already registered.',
-                originalError: error
-            };
+        case 'auth/account-exists-with-different-credential':
+            return new exceptions_1.EmailAlreadyInUseException(error);
+        // Weak Password
         case 'auth/weak-password':
-            return {
-                code: types_1.AuthErrorCode.WEAK_PASSWORD,
-                message: 'Password is too weak. Please use a stronger password.',
-                originalError: error
-            };
+            return new exceptions_1.WeakPasswordException(error);
+        // Token Expired
+        case 'auth/id-token-expired':
+        case 'auth/user-token-expired':
+        case types_1.ProviderErrorCodes.USER_TOKEN_EXPIRED:
+            return new exceptions_1.TokenExpiredException(error);
+        // Network Error
         case 'auth/network-request-failed':
-            return {
-                code: types_1.AuthErrorCode.NETWORK_ERROR,
-                message: 'Network error. Please check your connection.',
-                originalError: error
-            };
+        case 'auth/timeout':
+            return new exceptions_1.NetworkException(error);
         // Google Sign-In Errors
+        case types_1.ProviderErrorCodes.GOOGLE_CANCELLED:
         case 'auth/popup-closed-by-user':
         case 'auth/cancelled-popup-request':
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: 'Sign-in was cancelled.',
-                originalError: error
-            };
-        case 'auth/account-exists-with-different-credential':
-            return {
-                code: types_1.AuthErrorCode.EMAIL_ALREADY_IN_USE,
-                message: 'An account already exists with this email using a different sign-in method.',
-                originalError: error
-            };
-        case 'auth/invalid-credential':
-            return {
-                code: types_1.AuthErrorCode.INVALID_CREDENTIALS,
-                message: 'The credential received is invalid. Please try again.',
-                originalError: error
-            };
-        case 'auth/operation-not-allowed':
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: 'This sign-in method is not enabled. Please contact support.',
-                originalError: error
-            };
-        case 'auth/user-disabled':
-            return {
-                code: types_1.AuthErrorCode.INVALID_CREDENTIALS,
-                message: 'This account has been disabled.',
-                originalError: error
-            };
+            return new exceptions_1.GoogleSignInCancelledException(error);
+        case types_1.ProviderErrorCodes.GOOGLE_PLAY_UNAVAILABLE:
+            return new exceptions_1.GooglePlayServicesUnavailableException(error);
         // Apple Sign-In Errors
-        case 'auth/invalid-verification-code':
-        case 'auth/invalid-verification-id':
-            return {
-                code: types_1.AuthErrorCode.INVALID_CREDENTIALS,
-                message: 'The verification code is invalid. Please try again.',
-                originalError: error
-            };
-        // Token Expiration
-        case 'auth/id-token-expired':
-        case 'auth/user-token-expired':
-            return {
-                code: types_1.AuthErrorCode.TOKEN_EXPIRED,
-                message: 'Your session has expired. Please sign in again.',
-                originalError: error
-            };
-        // OAuth-Specific Errors
+        case types_1.ProviderErrorCodes.APPLE_CANCELLED:
+            return new exceptions_1.AppleSignInCancelledException(error);
+        case types_1.ProviderErrorCodes.APPLE_NOT_SUPPORTED:
+            return new exceptions_1.AppleSignInNotSupportedException(error);
+        // Configuration Errors
+        case 'auth/operation-not-allowed':
+            return new exceptions_1.ConfigurationException('This sign-in method is not enabled. Please check your Firebase configuration.', error);
         case 'auth/unauthorized-domain':
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: 'This domain is not authorized for OAuth operations.',
-                originalError: error
-            };
+            return new exceptions_1.ConfigurationException('This domain is not authorized for OAuth operations.', error);
         case 'auth/invalid-oauth-provider':
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: 'The OAuth provider configuration is invalid.',
-                originalError: error
-            };
         case 'auth/invalid-oauth-client-id':
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: 'The OAuth client ID is invalid.',
-                originalError: error
-            };
+            return new exceptions_1.ConfigurationException('The OAuth configuration is invalid.', error);
+        // Default
         default:
-            return {
-                code: types_1.AuthErrorCode.UNKNOWN,
-                message: fbError.message || 'An unknown error occurred.',
-                originalError: error
-            };
+            return new exceptions_1.UnknownAuthException(fbError.message || 'An unknown error occurred.', error);
     }
 };
 exports.mapFirebaseError = mapFirebaseError;
+/**
+ * Helper function to check if an error is a specific exception type
+ */
+const isAuthException = (error, exceptionType) => {
+    return error instanceof exceptionType;
+};
+exports.isAuthException = isAuthException;
+/**
+ * Helper to extract user-friendly message from any error
+ */
+const getErrorMessage = (error) => {
+    if (error instanceof exceptions_1.AuthException) {
+        return error.message;
+    }
+    return error?.message || 'An unexpected error occurred';
+};
+exports.getErrorMessage = getErrorMessage;

package/dist/errors/exceptions.d.ts

@@ -0,0 +1,82 @@
+export declare class AuthException extends Error {
+    readonly code: string;
+    readonly originalError?: any;
+    readonly timestamp: Date;
+    constructor(message: string, code: string, originalError?: any);
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        timestamp: string;
+        originalError: any;
+    };
+}
+export declare class InvalidCredentialsException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when user account does not exist
+ */
+export declare class UserNotFoundException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when attempting to sign up with an email that's already registered
+ */
+export declare class EmailAlreadyInUseException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when password doesn't meet minimum security requirements
+ */
+export declare class WeakPasswordException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when user's authentication token has expired
+ */
+export declare class TokenExpiredException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when network connectivity issues occur
+ */
+export declare class NetworkException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when Google Sign-In is cancelled by user
+ */
+export declare class GoogleSignInCancelledException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when Apple Sign-In is cancelled by user
+ */
+export declare class AppleSignInCancelledException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when Apple Sign-In is not supported on the device
+ */
+export declare class AppleSignInNotSupportedException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown when Google Play Services are not available
+ */
+export declare class GooglePlayServicesUnavailableException extends AuthException {
+    constructor(originalError?: any);
+}
+/**
+ * Thrown for configuration errors
+ */
+export declare class ConfigurationException extends AuthException {
+    constructor(message: string, originalError?: any);
+}
+/**
+ * Generic unknown error
+ */
+export declare class UnknownAuthException extends AuthException {
+    constructor(message?: string, originalError?: any);
+}