Skip to main content

brix 1.1.0 copy "brix: ^1.1.0" to clipboard
brix: ^1.1.0 copied to clipboard

Ready-made login, signup, email code, password reset and account logic for Flutter apps. Pure Dart, any backend, any state management.

brix #

Ready-made app logic you would otherwise write again in every Flutter app: login, signup, email codes, password reset, profile, change password, delete account, app start and logout.

  • Any backend. You write one small adapter for your API (REST, Firebase, Supabase, …).
  • Any state library. Pure Dart – no Flutter, no GetX / Bloc / Riverpod inside. A thin wrapper connects it to yours (brix_getx for GetX).
  • Your own UI. brix has no screens; it tells your screens what to show and where to go.
  • Safe defaults. Passwords are never trimmed or logged, double taps are ignored, a failed logout on the server still logs out locally.
  • Updates do not break your app. New calls arrive with default bodies, new values work with a default switch case.

Install #

dart pub add brix
Import What you get
package:brix/auth.dart login, signup, email code, forgot / reset password, password rules
package:brix/account.dart app start + logout, profile, change password, delete account (includes auth)
package:brix/core.dart Result, Failure, Json, BrixFlow
package:brix/testing.dart fakes for your tests

How it works #

You write four small classes once. Every flow uses them:

You write What it does
AuthProvider calls your backend (login, logout required; signup, codes, reset optional)
AuthSessionStore keeps the session between launches (use secure storage for tokens)
AuthNavigator opens your screens (toHome, toLogin required)
AuthFeedback shows errors, warnings and success messages your way

A flow holds a small immutable state (isSubmitting, …) and tells you when it changes (flow.changes). Show a loader from it; call the flow's methods from your buttons.

Every backend call returns a Result: Success(data, message: …) or Failed(failure). A Failure says what kind of problem it was – ValidationFailure, UnauthorizedFailure, ServerFailure, NetworkFailure, UnsupportedFailure, UnknownFailure – and carries the backend's messages.

1. The backend: AuthProvider #

import 'package:brix/auth.dart';

class MyAuthProvider extends AuthProvider<SignupBody, User> {
  MyAuthProvider(this.api);

  final MyApi api;

  /// What your backend does: code after signup? reset by code or link?
  @override
  AuthCapabilities get capabilities => const AuthCapabilities(
    otpAfterSignup: true,
    resetMode: ResetMode.otp,
    otpLength: 6,
  );

  @override
  Future<Result<AuthSession<User>>> login({
    required String identifier,
    required String password,
  }) async {
    final response = await api.post('auth/login', {
      'email': identifier,
      'password': password, // brix never changes a password – send it as is
    });
    if (response.statusCode == 401) {
      return Failed(ValidationFailure(messages: [response.message]));
    }
    return Success(
      AuthSession(accessToken: response.token, user: User.fromJson(response.data)),
      message: response.message,
    );
  }

  @override
  Future<Result<void>> logout() async {
    await api.post('auth/logout', {});
    return const Success(null);
  }

  // Optional – override only what your backend has:
  // register, verifyOtp, resendOtp, forgotPassword, resetPassword.

  /// Errors your API client throws (no connection, timeouts).
  @override
  Failure mapError(Object error, StackTrace stackTrace) => switch (error) {
    SocketException() => NetworkFailure(),
    _ => super.mapError(error, stackTrace),
  };
}

2. Storage, screens and alerts #

class MySessionStore extends AuthSessionStore<User> {
  @override
  Future<void> saveSession(AuthSession<User> session) async {
    // Write the token to secure storage, the user wherever you like.
  }

  @override
  Future<AuthSession<User>?> readSession() async {
    // Read it back; null when nobody is logged in.
  }

  @override
  Future<void> clearSession() async {
    // Delete the token and the user.
  }

  // Optional: savePendingIdentifier (code screen after a restart) and
  // saveRememberedCredentials ("remember me").
}

class MyNavigator extends AuthNavigator {
  @override
  Future<void> toHome() async => router.go('/home');

  @override
  Future<void> toLogin({String? identifier}) async =>
      router.go('/login', extra: identifier); // fill the email when given

  // Optional, when your capabilities need them:
  // toSignup, toOtp, toForgotPassword, toResetPassword, back.
}

class MyFeedback extends AuthFeedback {
  @override
  void failure(Failure failure) => showError(failure.displayMessage);

  @override
  void warning(AuthWarning warning) => showWarning(warning.message);

  @override
  void success(String? message) {
    if (message != null) showSnackbar(message);
  }
}

Do not wait for a new screen to close inside a navigator method (e.g. do not return Navigator.push's future) – the flow would stay busy.

3. Login #

final login = LoginFlow<User>(
  provider: MyAuthProvider(api),
  store: MySessionStore(),
  navigator: MyNavigator(),
  feedback: MyFeedback(),
  onLoggedIn: (session) => currentUser = session.user, // optional
);

// Fill the form from "remember me".
final saved = await login.loadRemembered(); // email + password, or null

// Button: double taps are ignored; email trimmed, password sent as typed.
await login.submit(identifier: email, password: password, rememberMe: true);

// Loader.
login.changes.listen((state) => setLoading(state.isSubmitting));

// Screen closed.
login.dispose();

Success: the session is saved, "remember me" saved or cleared, the backend's message shown, home opened. Failure: the error is shown, nothing saved.

4. Signup and the email code #

final signup = SignupFlow<SignupBody, User>(
  provider: provider,
  store: store,
  navigator: navigator,
  feedback: feedback,
  passwordPolicy: const PasswordPolicy(), // 8+, capital, small, number, special
);

// Your own checks (terms accepted, …) run before this.
await signup.submit(
  request: SignupBody(name: name, email: email, password: password),
  identifier: email,
  password: password,
);
// otpAfterSignup → email kept as "pending", code screen opened.
// otherwise      → login opened with the email filled.

Code screen:

final otp = OtpVerificationFlow<User>(
  provider: provider,
  store: store,
  navigator: navigator,
  feedback: feedback,
  resendCooldown: const Duration(seconds: 30),
);

await otp.start(); // reads the pending email (also after an app restart)

otp.state.maskedIdentifier; // "ad•••@mail.com"
otp.state.resendIn;         // time left before "resend" works
otp.state.failedAttempts;   // went up → clear your code boxes

await otp.verify('123456'); // right → login with the email filled
await otp.resend();
await otp.changeIdentifier(); // wrong email → back to signup

5. Forgot and reset password #

final forgot = ForgotPasswordFlow(
  provider: provider,
  navigator: navigator,
  feedback: feedback,
);
await forgot.submit(identifier: email);
// ResetMode.otp  → reset screen opened (code + new password)
// ResetMode.link → message shown, login opened

final reset = ResetPasswordFlow(
  provider: provider,
  navigator: navigator,
  feedback: feedback,
  identifier: email,
  store: store, // optional: updates a remembered password
);
await reset.start();
await reset.submit(code: '123456', newPassword: 'New@Pass1');
// → login with the email filled

6. App start and logout #

final session = SessionFlow<User>(
  auth: provider,
  store: store,
  navigator: navigator,
  feedback: feedback,
  account: accountProvider, // optional: refresh the user on start
);

await session.start();
// waiting signup code → code screen; saved session → home;
// rejected session (401) → login; nothing saved → login.

await session.logout(); // server logout, then always local logout

7. Account: profile, change password, delete #

Write an AccountProvider with only the calls you have:

class MyAccountProvider extends AccountProvider<User, ProfileBody> {
  @override
  AccountDeletionMode get deletionMode => AccountDeletionMode.code;

  @override
  Future<Result<User>> currentUser() async { /* GET profile */ }

  @override
  Future<Result<void>> updateProfile(ProfileBody update) async { /* PATCH */ }

  @override
  Future<Result<void>> uploadAvatar(AvatarUpload avatar) async {
    // avatar.path on mobile, avatar.bytes on web
  }

  @override
  Future<Result<void>> changePassword({
    required String currentPassword,
    required String newPassword,
  }) async { /* … */ }

  @override
  Future<Result<void>> requestAccountDeletion({required String identifier}) async {
    // email a code
  }

  @override
  Future<Result<void>> deleteAccount({
    required String identifier,
    String? code,
    String? password,
  }) async { /* … */ }
}
// Profile
final profile = ProfileFlow<User, ProfileBody>(account: account, feedback: feedback);
await profile.load();                         // state.user, state.isLoading
await profile.save(ProfileBody(name: 'Ada')); // saved, then reloaded
await profile.uploadAvatar(AvatarUpload(fileName: 'me.jpg', path: file.path));

// Change password (stays logged in)
final change = ChangePasswordFlow(
  account: account,
  store: store,
  navigator: navigator,
  feedback: feedback,
);
await change.submit(currentPassword: old, newPassword: newer);

// Delete account with an emailed code
final delete = DeleteAccountFlow(
  account: account,
  store: store,
  navigator: navigator,
  feedback: feedback,
  identifier: user.email,
);
await delete.requestDeletion(); // code sent
await delete.confirm('123456'); // deleted, everything cleared, login opened

Reading JSON safely #

Json reads decoded JSON from any backend (REST, Firebase, Supabase, …) into your models without crashes:

factory User.fromJson(Json json) => User(
  id: json.string('id'),
  name: json.string('profile.firstName'),   // paths for nested values
  age: json.integer('age'),                 // 31, 31.0 and "31" all work
  isActive: json.boolean('active'),         // true, "true", 1
  createdAt: json.dateOrNull('createdAt'),  // ISO text or epoch milliseconds
  roles: json.list('roles', Role.fromJson),
);

final user = User.fromJson(Json(jsonDecode(body)));

A missing key or a wrong type gives the fallback ('', 0, false, empty list) or null for the …OrNull readers – never an exception. See them while developing:

Json.onProblem = (path, problem) => debugPrint('JSON $path: $problem');
// JSON roles[0].level: expected a whole number, got String "high"

With your state library #

Every flow has state (now) and changes (a stream of new states). Connect it to whatever your app uses, and dispose() it when the screen closes.

GetX – ready-made controllers in brix_getx.

Riverpod

final loginFlowProvider = Provider.autoDispose<LoginFlow<User>>((ref) {
  final flow = LoginFlow<User>(provider: api, store: store, navigator: nav, feedback: alerts);
  ref.onDispose(flow.dispose);
  return flow;
});

final loginStateProvider = StreamProvider.autoDispose<AuthFormState>(
  (ref) => ref.watch(loginFlowProvider).changes,
);

// Widget
final busy = ref.watch(loginStateProvider).value?.isSubmitting ?? false;
onPressed: busy ? null : () => ref.read(loginFlowProvider).submit(identifier: email, password: password),

Bloc

class LoginCubit extends Cubit<AuthFormState> {
  LoginCubit(this.flow) : super(flow.state) {
    _subscription = flow.changes.listen(emit);
  }

  final LoginFlow<User> flow;
  late final StreamSubscription<AuthFormState> _subscription;

  Future<void> login(String email, String password) =>
      flow.submit(identifier: email, password: password);

  @override
  Future<void> close() async {
    await _subscription.cancel();
    await flow.dispose();
    return super.close();
  }
}

Provider

class LoginNotifier extends ChangeNotifier {
  LoginNotifier(this.flow) {
    _subscription = flow.changes.listen((_) => notifyListeners());
  }

  final LoginFlow<User> flow;
  late final StreamSubscription<AuthFormState> _subscription;

  bool get isSubmitting => flow.state.isSubmitting;

  Future<void> login(String email, String password) =>
      flow.submit(identifier: email, password: password);

  @override
  void dispose() {
    _subscription.cancel();
    flow.dispose();
    super.dispose();
  }
}

setState

class _LoginScreenState extends State<LoginScreen> {
  late final flow = LoginFlow<User>(provider: api, store: store, navigator: nav, feedback: alerts);

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<AuthFormState>(
      stream: flow.changes,
      initialData: flow.state,
      builder: (context, snapshot) => FilledButton(
        onPressed: snapshot.data!.isSubmitting
            ? null
            : () => flow.submit(identifier: email, password: password),
        child: const Text('Log in'),
      ),
    );
  }

  @override
  void dispose() {
    flow.dispose();
    super.dispose();
  }
}

The same works for every flow (signup, code, reset, profile, …) – only the state type changes.

Texts #

Backend messages always come first. When the backend sends none, brix has a plain English text, so you need no own text for the basics – and you can always show your own:

@override
void failure(Failure failure) => showError(switch (failure) {
  NetworkFailure() => 'You are offline.', // your wording, if you want
  _ => failure.displayMessage,             // backend message, else brix's text
});

@override
void warning(AuthWarning warning) => showWarning(switch (warning) {
  AuthWarning.otpIncomplete => 'Please enter all 6 digits.',
  _ => warning.message, // also for warnings added in later versions
});

Password checklist: for (final rule in policy.rules) Text(rule.labelFor(policy)) → "At least 8 characters", "One capital letter (A-Z)", … and policy.unmetRules(password) for the ticks.

Form errors per field arrive in failure.fieldErrors – show them under the field:

TextFormField(decoration: InputDecoration(errorText: failure?.fieldError('email')))

Your own checks and errors use the same types: const AuthWarning('termsNotAccepted', 'Accept the terms first.'), or a Failure subclass that overrides defaultMessage.

Updates never break your app #

  • AuthWarning, PasswordRule and OtpPurpose are classes, not enums: always switch with a default case (_ =>), and values added later just work.
  • New provider, store and navigator methods arrive with a default body, so your classes keep compiling.

Testing #

import 'package:brix/testing.dart';

final provider = FakeAuthProvider<void, String>()
  ..loginResult = Failed(ValidationFailure(messages: ['Wrong password']));
final navigator = RecordingAuthNavigator();
final feedback = RecordingAuthFeedback();

final flow = LoginFlow<String>(
  provider: provider,
  store: InMemoryAuthSessionStore(),
  navigator: navigator,
  feedback: feedback,
);
await flow.submit(identifier: 'a@b.com', password: 'x');

expect(feedback.failures.single.messages, ['Wrong password']);
expect(navigator.visits, isEmpty);

Example #

example/main.dart – a login in plain Dart (dart run example/main.dart). A full Flutter app: brix_getx example.

License #

MIT

2
likes
0
points
1.19k
downloads

Publisher

unverified uploader

Weekly Downloads

Ready-made login, signup, email code, password reset and account logic for Flutter apps. Pure Dart, any backend, any state management.

Repository (GitHub)
View/report issues

Topics

#authentication #login #otp #architecture #state-management

License

unknown (license)

Dependencies

meta

More

Packages that depend on brix