* Added a boolean linkWithExistingUser to link the new credentials with an existing signed-in user, instead of creating a new one.

* Added onError callback for general purpose errors by the library
* Updated example app
* Updated version

Author: rithik-dev

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [1.0.6] - 16/07/2022
+
+* Added a boolean linkWithExistingUser to link the new credentials with an existing signed-in user, instead of creating a new one.
+* Added onError callback for general purpose errors by the library
+
 ## [1.0.5+1] - 11/07/2022
 
 * Fixed files formatting

README.md

@@ -112,6 +112,8 @@ FirebasePhoneAuthHandler(
     phoneNumber: "+919876543210",
     // If true, the user is signed out before the onLoginSuccess callback is fired when the OTP is verified successfully.
     signOutOnSuccessfulVerification: false,
+    
+    linkWithExistingUser: false,
     builder: (context, controller) {
       return SizedBox.shrink();
     },
@@ -122,6 +124,7 @@ FirebasePhoneAuthHandler(
     onLoginFailed: (authException) {
       debugPrint("An error occurred: ${authException.message}");
     },
+    onError: (error) {},
 ),
 ```
 
@@ -289,7 +292,8 @@ class _VerifyPhoneNumberScreenState extends State<VerifyPhoneNumberScreen>
     return SafeArea(
       child: FirebasePhoneAuthHandler(
         phoneNumber: widget.phoneNumber,
-        signOutOnSuccessfulVerification: false,
+        signOutOnSuccessfulVerification: false, // default
+        linkWithExistingUser: false,  // default
         autoRetrievalTimeOutDuration: const Duration(seconds: 60),
         otpExpirationDuration: const Duration(seconds: 60),
         onCodeSent: () {
@@ -321,6 +325,9 @@ class _VerifyPhoneNumberScreenState extends State<VerifyPhoneNumberScreen>
           log(VerifyPhoneNumberScreen.id, error: authException.message);
           // handle error further if needed
         },
+        onError: (error) {
+          showSnackBar('An error occurred!');
+        },
         builder: (context, controller) {
           return Scaffold(
             appBar: AppBar(

example/lib/screens/verify_phone_number_screen.dart

@@ -67,6 +67,7 @@ class _VerifyPhoneNumberScreenState extends State<VerifyPhoneNumberScreen>
       child: FirebasePhoneAuthHandler(
         phoneNumber: widget.phoneNumber,
         signOutOnSuccessfulVerification: false,
+        linkWithExistingUser: false,
         autoRetrievalTimeOutDuration: const Duration(seconds: 60),
         otpExpirationDuration: const Duration(seconds: 60),
         onCodeSent: () {
@@ -98,6 +99,9 @@ class _VerifyPhoneNumberScreenState extends State<VerifyPhoneNumberScreen>
           log(VerifyPhoneNumberScreen.id, error: authException.message);
           // handle error further if needed
         },
+        onError: (error) {
+          showSnackBar('An error occurred!');
+        },
         builder: (context, controller) {
           return Scaffold(
             appBar: AppBar(

example/pubspec.lock

@@ -105,7 +105,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "1.0.5+1"
+    version: "1.0.6"
   flutter:
     dependency: "direct main"
     description: flutter

lib/src/auth_controller.dart

@@ -57,22 +57,32 @@ class FirebasePhoneAuthController extends ChangeNotifier {
   /// {@macro onLoginFailed}
   OnLoginFailed? _onLoginFailed;
 
+  /// {@macro onError}
+  OnError? _onError;
+
+  /// {@macro linkWithExistingUser}
+  late bool _linkWithExistingUser;
+
   /// Set callbacks and other data. (only for internal use)
   void _setData({
     required String phoneNumber,
     required OnLoginSuccess? onLoginSuccess,
     required OnLoginFailed? onLoginFailed,
+    required OnError? onError,
     required VoidCallback? onCodeSent,
     required bool signOutOnSuccessfulVerification,
-    RecaptchaVerifier? recaptchaVerifierForWeb,
-    Duration autoRetrievalTimeOutDuration = kAutoRetrievalTimeOutDuration,
-    Duration otpExpirationDuration = kAutoRetrievalTimeOutDuration,
+    required RecaptchaVerifier? recaptchaVerifierForWeb,
+    required Duration autoRetrievalTimeOutDuration,
+    required Duration otpExpirationDuration,
+    required bool linkWithExistingUser,
   }) {
     _phoneNumber = phoneNumber;
     _signOutOnSuccessfulVerification = signOutOnSuccessfulVerification;
     _onLoginSuccess = onLoginSuccess;
-    _onCodeSent = onCodeSent;
     _onLoginFailed = onLoginFailed;
+    _onError = onError;
+    _onCodeSent = onCodeSent;
+    _linkWithExistingUser = linkWithExistingUser;
     _autoRetrievalTimeOutDuration = autoRetrievalTimeOutDuration;
     _otpExpirationDuration = otpExpirationDuration;
     if (kIsWeb) _recaptchaVerifierForWeb = recaptchaVerifierForWeb;
@@ -149,6 +159,7 @@ class FirebasePhoneAuthController extends ChangeNotifier {
       _onLoginFailed?.call(e);
       return false;
     } catch (e) {
+      _onError?.call(e);
       return false;
     }
   }
@@ -213,6 +224,7 @@ class FirebasePhoneAuthController extends ChangeNotifier {
       _onLoginFailed?.call(e);
       return false;
     } catch (e) {
+      _onError?.call(e);
       return false;
     }
   }
@@ -242,14 +254,24 @@ class FirebasePhoneAuthController extends ChangeNotifier {
 
     // Not on web.
     try {
-      final authResult = await _auth.signInWithCredential(authCredential!);
+      late final UserCredential authResult;
+
+      if (_linkWithExistingUser) {
+        authResult = await _auth.currentUser!.linkWithCredential(
+          authCredential!,
+        );
+      } else {
+        authResult = await _auth.signInWithCredential(authCredential!);
+      }
+
       if (_signOutOnSuccessfulVerification) await signOut();
       _onLoginSuccess?.call(authResult, autoVerified);
       return true;
     } on FirebaseAuthException catch (e) {
       _onLoginFailed?.call(e);
       return false;
     } catch (e) {
+      _onError?.call(e);
       return false;
     }
   }
@@ -297,12 +319,14 @@ class FirebasePhoneAuthController extends ChangeNotifier {
     _webConfirmationResult = null;
     _onLoginSuccess = null;
     _onLoginFailed = null;
+    _onError = null;
     _onCodeSent = null;
     _signOutOnSuccessfulVerification = false;
     _forceResendingToken = null;
     _otpExpirationTimer?.cancel();
     _otpExpirationTimer = null;
     _phoneNumber = null;
+    _linkWithExistingUser = false;
     _autoRetrievalTimeOutDuration = kAutoRetrievalTimeOutDuration;
     _otpExpirationDuration = kAutoRetrievalTimeOutDuration;
     _verificationId = null;

lib/src/auth_handler.dart

@@ -14,10 +14,12 @@ class FirebasePhoneAuthHandler extends StatefulWidget {
     Key? key,
     required this.phoneNumber,
     required this.builder,
-    this.onLoginFailed,
     this.onLoginSuccess,
+    this.onLoginFailed,
+    this.onError,
     this.onCodeSent,
     this.signOutOnSuccessfulVerification = false,
+    this.linkWithExistingUser = false,
     this.autoRetrievalTimeOutDuration =
         FirebasePhoneAuthController.kAutoRetrievalTimeOutDuration,
     this.otpExpirationDuration =
@@ -56,6 +58,21 @@ class FirebasePhoneAuthHandler extends StatefulWidget {
   /// {@endtemplate}
   final VoidCallback? onCodeSent;
 
+  /// {@template linkWithExistingUser}
+  ///
+  /// If true, links the generated credentials to an existing signed in user,
+  /// and not creating new session.
+  ///
+  /// Internally, if true, this calls the linkWithCredential method instead of
+  /// signInWithCredential.
+  ///
+  /// Make sure a user is signed in already, else an error is thrown.
+  ///
+  /// Defaults to false
+  ///
+  /// {@endtemplate}
+  final bool linkWithExistingUser;
+
   /// {@template onLoginSuccess}
   ///
   /// This callback is triggered when the phone number is verified and the user is
@@ -78,6 +95,15 @@ class FirebasePhoneAuthHandler extends StatefulWidget {
   /// {@endtemplate}
   final OnLoginFailed? onLoginFailed;
 
+  /// {@template onError}
+  ///
+  /// Called when a general error occurs.
+  ///
+  /// If the error is a [FirebaseAuthException], then [onLoginFailed] is called.
+  ///
+  /// {@endtemplate}
+  final OnError? onError;
+
   /// {@template autoRetrievalTimeOutDuration}
   ///
   /// The maximum amount of time you are willing to wait for SMS
@@ -161,9 +187,11 @@ class _FirebasePhoneAuthHandlerState extends State<FirebasePhoneAuthHandler> {
         phoneNumber: widget.phoneNumber,
         onLoginSuccess: widget.onLoginSuccess,
         onLoginFailed: widget.onLoginFailed,
+        onError: widget.onError,
         autoRetrievalTimeOutDuration: widget.autoRetrievalTimeOutDuration,
         otpExpirationDuration: widget.otpExpirationDuration,
         onCodeSent: widget.onCodeSent,
+        linkWithExistingUser: widget.linkWithExistingUser,
         signOutOnSuccessfulVerification: widget.signOutOnSuccessfulVerification,
         recaptchaVerifierForWeb: captcha,
       );

lib/src/type_definitions.dart

@@ -4,3 +4,4 @@ import 'package:firebase_auth/firebase_auth.dart';
 
 typedef OnLoginSuccess = FutureOr<void> Function(UserCredential, bool);
 typedef OnLoginFailed = FutureOr<void> Function(FirebaseAuthException);
+typedef OnError = FutureOr<void> Function(Object);

pubspec.yaml

@@ -1,6 +1,6 @@
 name: firebase_phone_auth_handler
 description: An easy-to-use firebase phone authentication package to easily send and verify OTP's with auto-fetch OTP support via SMS. Supports web out of the box.
-version: 1.0.5+1
+version: 1.0.6
 homepage: https://github.com/rithik-dev/firebase_phone_auth_handler
 
 environment: