fix: continuing error managment and documentation

lib/data/repositories/auth_repository.dart

@@ -2,6 +2,7 @@ import 'package:flutter/foundation.dart';
 import 'package:seshat/data/services/auth_client.dart';
 import 'package:seshat/utils/result.dart';
 
+/// Repository to manage authentification
 class AuthRepository extends ChangeNotifier {
   AuthRepository({required AuthClient authClient}) : _authClient = authClient;
 
@@ -9,6 +10,7 @@ class AuthRepository extends ChangeNotifier {
 
   bool? _isAuthenticated;
 
+  /// Checks the validity of the token if not already checked
   Future<bool> get isLoggedIn async {
     if (_isAuthenticated != null) {
       return _isAuthenticated!;
@@ -25,6 +27,7 @@ class AuthRepository extends ChangeNotifier {
     }
   }
 
+  /// Logs in the user
   Future<Result<void>> login(String username, String password) async {
     try {
       final result = await _authClient.login(username, password);
@@ -33,13 +36,14 @@ class AuthRepository extends ChangeNotifier {
           _isAuthenticated = true;
           return Result.ok(());
         case Error():
-          return Result.error(result.error);
+          return result;
       }
     } catch (e) {
       return Result.error(Exception(e));
     }
   }
 
+  /// Gets the API's remote version
   Future<Result<int>> getRemoteApiVersion() async {
     return await _authClient.getRemoteApiVersion();
   }

lib/data/repositories/bal_repository.dart

@@ -5,13 +5,19 @@ import 'package:seshat/domain/models/bal_stats.dart';
 import 'package:seshat/domain/models/enums.dart';
 import 'package:seshat/utils/result.dart';
 
+/// Repository to manage [Bal]
 class BalRepository {
   BalRepository({required ApiClient apiClient}) : _apiClient = apiClient;
 
   final ApiClient _apiClient;
-  List<Bal>? _bals;
-  Accounting? accounting;
 
+  /// [List<Bal>] of all the user's [Bal]
+  List<Bal>? _bals;
+
+  /// [Accounting] of [Bal], mapped by [Bal] id
+  final Map<int, Accounting?> _accountingMap = {};
+
+  /// Gets a list of all [Bal] from cache or remote
   Future<Result<List<Bal>>> getBals() async {
     if (_bals != null) {
       return Result.ok(_bals!);
@@ -26,6 +32,7 @@ class BalRepository {
     }
   }
 
+  /// Gets a list of all [Bal] from remote only
   Future<Result<List<Bal>>> _getBalsNoCache() async {
     final result = await _apiClient.getBals();
     switch (result) {
@@ -37,15 +44,16 @@ class BalRepository {
     }
   }
 
-  Future<Result<Bal>> balById(int id) async {
+  /// Gets a [Bal] by [balId], either from cache or remote
+  Future<Result<Bal>> balById(int balId) async {
     if (_bals == null) {
       await getBals();
     }
-    Bal? bal = _bals!.where((bal) => bal.id == id).firstOrNull;
+    Bal? bal = _bals!.where((bal) => bal.id == balId).firstOrNull;
     if (bal != null) {
       return Result.ok(bal);
     }
-    final result = await _apiClient.getBalById(id);
+    final result = await _apiClient.getBalById(balId);
     switch (result) {
       case Ok():
         return Result.ok(result.value);
@@ -54,11 +62,13 @@ class BalRepository {
     }
   }
 
+  /// Return wether or not a [Bal] is currently [BalState.ongoing]
   bool isABalOngoing() {
     return _bals?.where((bal) => bal.state == BalState.ongoing).isNotEmpty ??
         false;
   }
 
+  /// Gets the [Bal] that is [BalState.ongoing]
   Future<Bal?> ongoingBal() async {
     if (_bals == null) {
       await _getBalsNoCache();
@@ -66,12 +76,14 @@ class BalRepository {
     return _bals!.where((bal) => bal.state == BalState.ongoing).firstOrNull;
   }
 
+  /// Stops a [Bal] and refresh cache
   Future<Result<Bal>> stopBal(int id) async {
     final result = await _apiClient.stopBal(id);
     _getBalsNoCache();
     return result;
   }
 
+  /// Starts a [Bal] and refresh cache
   Future<Result<Bal>> startBal(int id) async {
     if (isABalOngoing()) {
       return Result.error(
@@ -83,52 +95,62 @@ class BalRepository {
     return result;
   }
 
+  /// Changes a [Bal]'s [name], [startTime] or [endTime]
   Future<Result<Bal>> editBal(
     int id,
     String name,
-    DateTime start,
-    DateTime end,
+    DateTime startTime,
+    DateTime endTime,
   ) async {
-    final result = await _apiClient.editBal(id, name, start, end);
+    final result = await _apiClient.editBal(id, name, startTime, endTime);
     await _getBalsNoCache();
     return result;
   }
 
-  Future<Result<void>> addBal(String name, DateTime start, DateTime end) async {
-    final result = await _apiClient.addBal(name, start, end);
+  /// Creates a [Bal] from its [name], [startTime] and [endTime]
+  Future<Result<void>> addBal(
+    String name,
+    DateTime startTime,
+    DateTime endTime,
+  ) async {
+    final result = await _apiClient.addBal(name, startTime, endTime);
     await _getBalsNoCache();
     return result;
   }
 
-  Future<Result<BalStats>> getBalStats(int id) async {
-    return _apiClient.getBalStats(id);
+  /// Gets a [BalStats] from its [balId]
+  Future<Result<BalStats>> getBalStats(int balId) async {
+    return _apiClient.getBalStats(balId);
   }
 
+  /// Get [Accounting] of a [Bal] from remote only
   Future<Result<Accounting>> getAccountingNoCache(int balId) async {
     final result = await _apiClient.getAccounting(balId);
     switch (result) {
       case Ok():
-        accounting = result.value;
+        _accountingMap[balId] = result.value;
         break;
       default:
     }
     return result;
   }
 
+  /// Get [Accounting] of a [Bal] from cache or remote
   Future<Result<Accounting>> getAccounting(int balId) async {
-    if (accounting != null) {
-      return Result.ok(accounting!);
+    if (_accountingMap[balId] != null) {
+      return Result.ok(_accountingMap[balId]!);
     }
     final result = await _apiClient.getAccounting(balId);
     switch (result) {
       case Ok():
-        accounting = result.value;
+        _accountingMap[balId] = result.value;
         break;
       default:
     }
     return result;
   }
 
+  /// Manages what returning (of type [ReturnType]) does to cache and notifies remote
   Future<Result<void>> returnToId(
     int balId,
     int ownerId,
@@ -139,26 +161,32 @@ class BalRepository {
       case Ok():
         switch (type) {
           case ReturnType.books:
-            final owner = accounting?.owners
+            final owner = _accountingMap[balId]?.owners
                 .where((el) => el.ownerId == ownerId)
                 .firstOrNull;
             if (owner?.owedMoney == 0) {
-              accounting?.owners.removeWhere((el) => el.ownerId == ownerId);
+              _accountingMap[balId]?.owners.removeWhere(
+                (el) => el.ownerId == ownerId,
+              );
             }
             owner?.owed = [];
             owner?.owedInstances = [];
             break;
           case ReturnType.money:
-            final owner = accounting?.owners
+            final owner = _accountingMap[balId]?.owners
                 .where((el) => el.ownerId == ownerId)
                 .firstOrNull;
             if (owner?.owed == null || owner!.owed.isEmpty) {
-              accounting?.owners.removeWhere((el) => el.ownerId == ownerId);
+              _accountingMap[balId]?.owners.removeWhere(
+                (el) => el.ownerId == ownerId,
+              );
             }
             owner?.owedMoney = 0;
             break;
           case ReturnType.all:
-            accounting?.owners.removeWhere((el) => el.ownerId == ownerId);
+            _accountingMap[balId]?.owners.removeWhere(
+              (el) => el.ownerId == ownerId,
+            );
             break;
         }
         break;

lib/data/repositories/book_instance_repository.dart

@@ -6,16 +6,19 @@ import 'package:seshat/domain/models/owner.dart';
 import 'package:seshat/domain/models/search_result.dart';
 import 'package:seshat/utils/result.dart';
 
+/// Repository to manage [BookInstance]
 class BookInstanceRepository {
   BookInstanceRepository({required ApiClient apiClient})
     : _apiClient = apiClient;
 
   final ApiClient _apiClient;
 
+  /// Gets a [List<BookInstance>] from an [ean]
   Future<Result<List<BookInstance>>> getByEan(int balId, int ean) async {
     return await _apiClient.getBookInstanceByEAN(balId, ean);
   }
 
+  /// Gets a [List<BookInstance>] from a [title] and [author]
   Future<Result<List<SearchResult>>> getBySearch(
     int balId,
     String title,
@@ -24,15 +27,17 @@ class BookInstanceRepository {
     return await _apiClient.getBookInstanceBySearch(balId, title, author);
   }
 
-  Future<Result<BookInstance>> sendBook(
+  /// Sends a new [BookInstance]'s [book], [owner], [bal] and [price]
+  Future<Result<BookInstance>> sendNewBookInstance(
     Book book,
     Owner owner,
     Bal bal,
     double price,
   ) async {
-    return await _apiClient.sendBook(book, owner, bal, price);
+    return await _apiClient.sendNewBookInstance(book, owner, bal, price);
   }
 
+  /// Sells a [List<BookInstance>]
   Future<Result<void>> sellBooks(List<BookInstance> books) async {
     Map<String, double?> res = {};
     for (BookInstance instance in books) {

lib/data/repositories/book_repository.dart

@@ -2,16 +2,19 @@ import 'package:seshat/data/services/api_client.dart';
 import 'package:seshat/domain/models/book.dart';
 import 'package:seshat/utils/result.dart';
 
+/// Repository to manage [Book]
 class BookRepository {
   BookRepository({required ApiClient apiClient}) : _apiClient = apiClient;
 
   final ApiClient _apiClient;
 
+  /// Gets a [Book] by its [ean]
   Future<Result<Book>> getBookByEAN(String ean) async {
     return await _apiClient.getBookByEAN(ean);
   }
 
-  Future<Result<Book>> getBookById(int id) async {
-    return await _apiClient.getBookById(id);
+  /// Gets a [Book] by its [bookId]
+  Future<Result<Book>> getBookById(int bookId) async {
+    return await _apiClient.getBookById(bookId);
   }
 }

lib/data/repositories/owner_repository.dart

@@ -5,6 +5,7 @@ import 'package:seshat/data/services/websocket_client.dart';
 import 'package:seshat/domain/models/owner.dart';
 import 'package:seshat/utils/result.dart';
 
+/// Repository to manage [Owner]
 class OwnerRepository {
   OwnerRepository({
     required ApiClient apiClient,
@@ -14,18 +15,25 @@ class OwnerRepository {
 
   final ApiClient _apiClient;
   final WebsocketClient _wsClient;
-  late final StreamSubscription sub;
-  List<Owner>? _cachedOwners;
-  Owner? _sectionOwner;
 
-  Future<Result<Owner>> get sectionOwner async {
-    if (_sectionOwner != null) {
-      return Result.ok(_sectionOwner!);
+  /// [StreamSubscription] to the [Stream<Owner>] for [_wsClient]
+  late final StreamSubscription sub;
+
+  /// [List<Owner>] of owners, updated by [_wsClient]
+  List<Owner>? _cachedOwners;
+
+  /// [Owner] of the current user
+  Owner? _ownerOfUser;
+
+  /// [Owner] of the current user
+  Future<Result<Owner>> get ownerOfUser async {
+    if (_ownerOfUser != null) {
+      return Result.ok(_ownerOfUser!);
     }
-    final result = await _apiClient.getSectionOwner();
+    final result = await _apiClient.getOwnerOfUser();
     switch (result) {
       case Ok():
-        _sectionOwner = result.value;
+        _ownerOfUser = result.value;
         break;
       default:
         break;
@@ -33,16 +41,17 @@ class OwnerRepository {
     return result;
   }
 
-  Future<Result<Owner>> getOwnerById(int id) async {
+  /// Gets an [Owner] from its [ownerId]
+  Future<Result<Owner>> getOwnerById(int ownerId) async {
     if (_cachedOwners != null) {
       final result1 = _cachedOwners!
-          .where((owner) => owner.id == id)
+          .where((owner) => owner.id == ownerId)
           .firstOrNull;
       if (result1 != null) {
         return Result.ok(result1);
       }
     }
-    return await _apiClient.getOwnerById(id);
+    return await _apiClient.getOwnerById(ownerId);
   }
 
   /// Adds an [Owner] to the database, and gets the resulting [Owner].