Flutter GB Account Basic

A utility package that helps implementing common account management actions using a Clean Architecture approach with BLoC.

---

✨ Features

This package provides a robust foundation for handling user account operations, organizing them into logical domains:

🔐 Password Management

• Request Password Reset: Send a reset link/code to email.
• Submit Password Reset: Complete the "Forgot Password" flow.
• Change Password: Update password for authenticated users.

✅ Account Verification

• Resend Verification Code: Send a new code to email/phone.
• Submit Verification Code: Verify the user account.

👤 Profile Management

• Update Account Info: Modify generic user information.
• Update Profile Picture: Upload and set a new avatar.
• Update Username: Change the display name/username.

📧 Email Management

• Request Email Change: Initiate email update flow.
• Confirm/Cancel: Validate the new email or cancel the request.

🛡️ Navigation Guards

• AccountVerificationGuard: Automatically protect routes that require verified users.

---

🛠️ Installation

Add the following packages to your pubspec.yaml:

dependencies:
  flutter_gb_account_basic: ^9.0.0
  
  # Dependencies required by the package
  flutter_gb_authentication_basic: ^5.0.0
  flutter_gb_stack_base: ^4.0.0
  flutter_bloc: ^8.1.6
  
dev_dependencies:
  build_runner: 
  freezed: 

---

⚙️ Configuration & Setup

1. Configure Dependency Injection

You need to register the package's dependencies using the provided configuration function. This is typically done in your app's main initialization logic or dependency injection setup (e.g., using get_it).

import 'package:flutter_gb_account_basic/flutter_gb_account_basic.dart';
import 'package:flutter_gb_stack_base/flutter_gb_stack_base.dart';
import 'package:get_it/get_it.dart';

Future<void> initAccountModule() async {
  // Define your configuration
  final accountConfig = AccountBasicConfig(
    // 1. Password Reset Configuration
    requestPasswordResetApiEndpoint: () => Uri.parse('https://api.yoursite.com/auth/forgot-password'),
    submitPasswordResetApiEndpoint: (email, code) => Uri.parse('https://api.yoursite.com/auth/reset-password'),
    
    // 2. Verification Configuration
    resendVerificationCodeApiEndpoint: (data) => Uri.parse('https://api.yoursite.com/auth/resend-verification'),
    submitVerificationCodeApiEndpoint: (code, data) => Uri.parse('https://api.yoursite.com/auth/verify-account'),
    
    // 3. User Info Updates
    updateUserInfoApiEndpoint: (data) => Uri.parse('https://api.yoursite.com/user/${data.user.id}'),
    updateUserProfilePictureApiEndpoint: (data) => Uri.parse('https://api.yoursite.com/user/${data.user.id}/avatar'),
    
    // 4. Email Change
    resendChangeEmailCodeApiEndpoint: (data) => Uri.parse('https://api.yoursite.com/user/email/resend-code'),
    
    // ... add other endpoints as needed
  );

  // Initialize the module
  await configureAccountBasicInjection(
    AppEnvironment.dev, // Or AppEnvironment.prod
    accountConfig,
  );
}

Tip

The AccountBasicConfig allows for extensive customization, including optional HTTP methods, custom request mappers, and response parsers.

---

🚀 Usage

Using the BLoC

You can access the AccountBasicBloc to dispatch events for various account actions. The BLoC includes helper methods to make this even easier:

// Using helper method (Recommended)
context.read<AccountBasicBloc>().requestPasswordReset('[e-mail]');

// Equivalent to dispatching the event manually
context.read<AccountBasicBloc>().add(
  AccountBasicEvent.requestPasswordReset(email: '[e-mail]'),
);

Common Helper Methods:

Method	Description
submitChangePassword(...)	Change current user's password
submitPasswordReset(...)	Complete forgot password flow
resendVerificationCode(...)	Resend verification email/SMS
submitVerificationCode(...)	Verify account with code
updateAccountInfo(...)	Update user profile details
updateProfilePicture(...)	Upload new avatar
requestEmailChange(...)	Start email change process

Handling Results with Listener

Use the AccountBasicBlocListener to handle success or failure notifications. This is perfect for showing Snackbars or navigating.

AccountBasicBlocListener(
  onPasswordResetRequestResult: (context, result) {
    result.fold(
      (failure) => ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Error: ${failure.message}')),
      ),
      (_) => ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Reset email sent!')),
      ),
    );
  },
  // ... other callbacks
  child: YourWidget(),
)

Route Protection

Use AccountVerificationGuard with AutoRoute to ensure users are verified before accessing specific pages.

// In your AppRouter
AutoRoute(
  page: ProtectedPage,
  guards: [
    AccountVerificationGuard(
      authBloc: GetIt.I<AuthenticationBasicBloc>(),
      onNotVerified: (router) {
        router.push(VerificationRoute());
      },
      onFailure: (router, failure) {
        // Handle failure
      }
    ),
  ],
);

Libraries

application/application

application/bloc/account_basic_bloc/account_basic_bloc

application/bloc/account_verification_page_bloc/account_verification_page_bloc

application/bloc/bloc

application/bloc/password_reset_screen_bloc/password_reset_screen_bloc

config/account_basic_config

config/config

dependency_injection

domain/domain

domain/entities/custom_verification_code_payload

domain/entities/entities

domain/services/account_basic_service

domain/services/services

flutter_gb_account_basic

infrastructure/infrastructure

infrastructure/models/models

infrastructure/services/account_basic_service_impl

infrastructure/services/services

presentation/containers/account_basic_builder_container

presentation/containers/account_basic_listener_container

presentation/containers/account_basic_provider_container

presentation/containers/containers

presentation/guards/account_verification_guard

presentation/guards/guards

presentation/presentation

utils/failure

utils/logger

utils/utils