wyatt-packages/packages/wyatt_authentication_bloc/doc/api/index.md

# wyatt_authentication_bloc - Dart API docs


<!--
 * Copyright (C) 2023 WYATT GROUP
 * Please see the AUTHORS file for details.

 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * any later version.

 * This program is distributed in the hope that it will be useful, 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
-->
<h1 id="flutter---authentication-bloc">Flutter - Authentication BLoC</h1><p align="left">
  <a href="https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/wyatt_analysis"><img src="https://img.shields.io/badge/Style-Wyatt%20Analysis-blue.svg?style=flat-square" alt="Style: Wyatt Analysis"></a>
  <img src="https://img.shields.io/badge/SDK-Flutter-blue?style=flat-square" alt="SDK: Flutter">
</p>
<p>Authentication Bloc for Flutter.</p>
<h2 id="features">Features</h2>
<ul>
<li>🧐 Wyatt Architecture</li>
<li>🧱 Entities
<ul>
<li>Account -&gt; Contains account information from provider.</li>
<li>Session -&gt; Contains account and associated data retrieved from an external source.</li>
<li>AuthenticationChangeEvent -&gt; Describes an event in authentication change (sign in, sign up, sign out, etc...)</li>
<li>SessionWrapper -&gt; Contains latest authentication change event and session.</li>
</ul>
</li>
<li>🔑 Powerful and secured authentication repository</li>
<li>🔥 Multiple data sources
<ul>
<li>Mock</li>
<li>Firebase</li>
</ul>
</li>
<li>🧊 Cubits, why make it complicated when you can make it simple?
<ul>
<li>Goes to the essential.</li>
</ul>
</li>
<li>📐 Consistent
<ul>
<li>Every class have same naming convention</li>
</ul>
</li>
<li>🧪 Tested</li>
<li>📚 Documented: <a href="./doc/api/index.md">available here</a></li>
</ul>
<h2 id="getting-started">Getting started</h2>
<p>Simply add <code>wyatt_authentication_bloc</code> in <code>pubspec.yaml</code> , then</p>
<pre class="language-dart"><code class="language-dart">import 'package:wyatt_authentication_bloc/wyatt_authentication_bloc.dart';
</code></pre>
<h3 id="data-source">Data source</h3>
<p>The first step is to provide a data source.</p>
<pre class="language-dart"><code class="language-dart">getIt.registerLazySingleton&lt;AuthenticationRemoteDataSource&lt;int&gt;&gt;(
    () =&gt; AuthenticationFirebaseDataSourceImpl&lt;int&gt;(
        firebaseAuth: FirebaseAuth.instance,
        googleSignIn:
            GoogleSignIn(clientId: DefaultFirebaseOptions.ios.iosClientId)),
);
</code></pre>
<blockquote>
<p>Here we use GetIt (see example project)</p>
</blockquote>
<h3 id="repository">Repository</h3>
<p>Then you can configure your repository.</p>
<pre class="language-dart"><code class="language-dart">final AuthenticationRepository&lt;int&gt; authenticationRepository = AuthenticationRepositoryImpl(
    authenticationRemoteDataSource:
        getIt&lt;AuthenticationRemoteDataSource&lt;int&gt;&gt;(),
    customPasswordValidator: const CustomPassword.pure(),
    extraSignUpInputs: [
        FormInput(
        AuthFormField.confirmPassword,
        const ConfirmedPassword.pure(),
        metadata: const FormInputMetadata&lt;void&gt;(export: false),
        ),
    ],
);
</code></pre>
<blockquote>
<p>Here we pass some extra inputs for the sign up, and a custom password validator.</p>
</blockquote>
<h3 id="cubits">Cubits</h3>
<p>It is necessary to implement each cubit. Don't panic, most of the work is already done 😊 you just have to customize the logic of these.</p>
<p>In each of these cubits it is necessary to overload the various callbacks.</p>
<blockquote>
<p>Here the associated data <code>Data</code> is a <code>int</code></p>
</blockquote>
<h4 id="authentication">Authentication</h4>
<p>In the authentication are managed, the refresh, the deletion of account or the disconnection.</p>
<pre class="language-dart"><code class="language-dart">class ExampleAuthenticationCubit extends AuthenticationCubit&lt;int&gt; {
  ExampleAuthenticationCubit({required super.authenticationRepository});

  @override
  FutureOrResult&lt;int?&gt; onReauthenticate(Result&lt;Account, AppException&gt; result) async {
    // TODO
  }

  @override
  FutureOrResult&lt;int?&gt; onRefresh(Result&lt;Account, AppException&gt; result) {
    // TODO
  }

  @override
  FutureOrResult&lt;int?&gt; onSignInFromCache(SessionWrapper&lt;int&gt; wrapper) {
    // TODO
  }

  @override
  FutureOrResult&lt;void&gt; onSignOut() {
    // TODO
  }

  @override
  FutureOrResult&lt;void&gt; onDelete() {
    // TODO
  }
}
</code></pre>
<h4 id="sign-up">Sign Up</h4>
<pre class="language-dart"><code class="language-dart">class ExampleSignUpCubit extends SignUpCubit&lt;int&gt; {
  ExampleSignUpCubit({
    required super.authenticationRepository,
  });

  @override
  FutureOrResult&lt;int?&gt; onSignUpWithEmailAndPassword(Result&lt;Account, AppException&gt; result, WyattForm form) async {
    // TODO
  }
}

</code></pre>
<h4 id="sign-in">Sign In</h4>
<pre class="language-dart"><code class="language-dart">class ExampleSignInCubit extends SignInCubit&lt;int&gt; {
  ExampleSignInCubit({
    required super.authenticationRepository,
  });

  @override
  FutureOrResult&lt;int?&gt; onSignInWithEmailAndPassword(Result&lt;Account, AppException&gt; result, WyattForm form) {
    // TODO
  }

  @override
  FutureOrResult&lt;int?&gt; onSignInAnonymously(Result&lt;Account, AppException&gt; result, WyattForm form) {
    // TODO
  }

  @override
  FutureOrResult&lt;int?&gt; onSignInWithGoogle(Result&lt;Account, AppException&gt; result, WyattForm form) {
    // TODO
  }
}
</code></pre>
<p>After setting up all these cubits you can provide them in the application. And that's it!</p>
<pre class="language-dart"><code class="language-dart">BlocProvider&lt;SignUpCubit&lt;int&gt;&gt;(
    create: (_) =&gt; ExampleSignUpCubit(
        authenticationRepository: authenticationRepository,
    ),
),
BlocProvider&lt;SignInCubit&lt;int&gt;&gt;(
    create: (_) =&gt; ExampleSignInCubit(
        authenticationRepository: authenticationRepository,
    ),
),
</code></pre>
<h3 id="widgets">Widgets</h3>
<p>Widgets are provided to make your life easier. Starting with the <code>AuthenticationBuilder</code> which allows you to build according to the authentication state.</p>
<pre class="language-dart"><code class="language-dart">AuthenticationBuilder&lt;int&gt;(
    authenticated: (context, sessionWrapper) =&gt; Text(
        'Logged as ${sessionWrapper.session?.account.email} | GeneratedId is ${sessionWrapper.session?.data}'),
    unauthenticated: (context) =&gt;
        const Text('Not logged (unauthenticated)'),
    unknown: (context) =&gt; const Text('Not logged (unknown)'),
),
</code></pre>
<p>A <code>BuildContext</code> extension is also available to access certain attributes more quickly.</p>
<pre class="language-dart"><code class="language-dart">Text('Home | ${context.account&lt;AuthenticationCubit&lt;int&gt;, int&gt;()?.email}'),
</code></pre>
<p>Listeners are used to listen to the status of the sign in and sign up forms.</p>
<pre class="language-dart"><code class="language-dart">return SignInListener&lt;int&gt;(
    onError: (context, status, errorMessage) =&gt; ScaffoldMessenger.of(context)
    ..hideCurrentSnackBar()
    ..showSnackBar(
        SnackBar(content: Text(errorMessage ?? 'Sign In Failure')),
    ),
    child: ...
);
</code></pre>


## Libraries

##### [wyatt_authentication_bloc](wyatt_authentication_bloc/wyatt_authentication_bloc-library.md)
An authentication library for BLoC.