docs: Add CatalystDataGatewayRepository docs (#388)

* test: Fix tests after cat-gateway update.

* docs: Add `CatalystDataGatewayRepository` usage examples.

* docs: Move docs from README to code comment.

* test: Update `CatalystDataGatewayRepository` tests.

* test: Use Fake instead of Mock.

* chore: Fix Markdown errors.

* chore: Explicit use of `HttpStatus` codes.

catalyst_voices/packages/catalyst_voices_repositories/README.md

@@ -1,23 +1 @@
 # Catalyst Voices Repositories
-
-## Catalyst Data Gateway Repository
-
-### Tests
-
-When extending the `CatalystDataGatewayRepository` it is necessary to generate
-proper mocks to have them available in tests.
-To do that we need to run
-
-```sh
-flutter pub run build_runner build --delete-conflicting-outputs
-```
-
- or
-
- ```sh
-dart run build_runner build --delete-conflicting-outputs
-```
-
-in the Catalyst Voices Repositories package root.
-The decorator `@GenerateNiceMocks` provided by mockito is used to indicate the
-repository to generate the mocks for.

catalyst_voices/packages/catalyst_voices_repositories/lib/src/catalyst_data_gateway_repository.dart

@@ -6,11 +6,53 @@ import 'package:catalyst_voices_services/generated/catalyst_gateway/cat_gateway_
 import 'package:chopper/chopper.dart';
 import 'package:result_type/result_type.dart';
 
-interface class CatalystDataGatewayRepository {
+// The [CatalystDataGatewayRepository] provides a structured interface to
+// interact with the `catalyst-gateway` backend API.
+// Network communication and error handling is abstracted allowing the
+// integration of API calls in an easy way.
+// All methods return `Future` objects to allow async execution.
+//
+// The repository uses, under the hood, the [CatGatewayApi] directly generated
+// from backend OpenAPI specification.
+//
+// To use the repository is necessary to initialize it by specifying the API 
+// base URL:
+// 
+// ```dart
+// final repository = CatalystDataGatewayRepository(Uri.parse('https://example.org/api'));
+// ```
+//
+// Once initialized it is possible, for example, to check the health status of
+// the service:
+//
+// ```dart
+// final health_status = await repository.getHealthLive();
+// ```
+// 
+// fetch staked ADA by stake address:
+//
+// ```dart
+// final stake_info = await repository.getCardanoStakedAdaStakeAddress(
+//   // cspell: disable-next-line
+//   stakeAddress:'stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw',
+// );
+// ```
+//
+// or get the sync state:
+//
+// ```dart
+// final sync_state = await repository.getCardanoSyncState();
+// ```
+
+final class CatalystDataGatewayRepository {
   final CatGatewayApi _catGatewayApi;
 
-  CatalystDataGatewayRepository(Uri baseUrl)
-    : _catGatewayApi = CatGatewayApi.create(baseUrl: baseUrl);
+  CatalystDataGatewayRepository(
+    Uri baseUrl,
+    {CatGatewayApi? catGatewayApiInstance,}
+  )
+    : _catGatewayApi = catGatewayApiInstance ?? 
+      CatGatewayApi.create(baseUrl: baseUrl);
 
   Future<Result<void, NetworkErrors>> getHealthStarted() async {
     try {
@@ -42,13 +84,13 @@ interface class CatalystDataGatewayRepository {
   Future<Result<StakeInfo, NetworkErrors>> getCardanoStakedAdaStakeAddress({
     required String stakeAddress,
     enums.Network network = enums.Network.mainnet,
-    DateTime? dateTime,
+    int? slotNumber,
   }) async {
     try {
       final stakeInfo = await _catGatewayApi.apiCardanoStakedAdaStakeAddressGet(
         stakeAddress: stakeAddress,
         network: network,
-        dateTime: dateTime,
+        slotNumber: slotNumber,
       );
       return Success(stakeInfo.bodyOrThrow);
     } on ChopperHttpException catch (error) {

catalyst_voices/packages/catalyst_voices_repositories/pubspec.yaml

@@ -15,6 +15,7 @@ dependencies:
   chopper: ^7.2.0
   flutter:
     sdk: flutter
+  http: ^1.2.1
   result_type: ^0.2.0
   rxdart: ^0.27.7