feat(cat-voices): Migrate document index to v2 endpoint (#3599)

* feat: Migrate document index to v2 endpoint

* Update catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/dio_cat_gateway_service.dart

Co-authored-by: Dominik Toton <[email protected]>

* Update catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/dio_cat_gateway_service.dart

Co-authored-by: Dominik Toton <[email protected]>

* chore: Simplify comments in API models

---------

Co-authored-by: Dominik Toton <[email protected]>

Author: bstolinski

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/dio_cat_gateway_service.dart

@@ -37,9 +37,9 @@ abstract interface class CatGatewayService {
 
   void close();
 
-  /// Post A Signed Document Index Query.
-  /// This endpoint produces a summary of signed documents that meet the criteria
-  /// defined in the request body.
+  /// Post A Signed Document Index Query for Newer Versions of v0.0.4.
+  /// Produces a summary of signed documents that meet the criteria
+  /// defined in the request body for new signed document versions of v0.0.4.
   ///
   /// It does not return the actual documents, just an index of the document identifiers
   /// which allows the documents to be retrieved by the `GET document` endpoint.
@@ -137,7 +137,7 @@ final class DioCatGatewayService implements CatGatewayService {
     int? page,
   }) {
     return _dio.post<dynamic, DocumentIndexList>(
-      '/v1/document/index',
+      '/v2/document/index',
       queryParameters: {
         'limit': ?limit,
         'page': ?page,

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/models/document_index_query_filter.dart

@@ -12,7 +12,7 @@ part 'document_index_query_filter.g.dart';
 /// which do not strictly match the metadata or payload fields included in the query
 /// itself.
 ///
-/// Used as request body for POST /api/v1/document/index
+/// Used as request body for POST /api/v2/document/index
 @JsonSerializable(createFactory: false, includeIfNull: false)
 final class DocumentIndexQueryFilter {
   /// ## Signed Document Type.
@@ -21,23 +21,26 @@ final class DocumentIndexQueryFilter {
   /// [Registered Document Types](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/)
   ///
   /// UUIDv4 Formatted 128bit value.
-  final String? type;
+  ///
+  /// Max items 10
+  final List<String>? type;
 
-  /// Document ID Selector
   /// ## Document ID
   ///
   /// Either an absolute single Document ID or a range of
   /// [Document IDs](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id)
-  final EqOrRangedId? id;
+  ///
+  /// Max items 10
+  final List<EqOrRangedId>? id;
 
-  /// Document Version Selector
   /// ## Document Version
   ///
   /// Either an absolute single Document Version or a range of
   /// [Document Versions](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#ver)
-  final EqOrRangedVer? ver;
+  ///
+  /// Max items 10
+  final List<EqOrRangedVer>? ver;
 
-  /// Document Reference
   /// ## Document Reference
   ///
   /// A [reference](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/meta/#ref-document-reference)
@@ -48,9 +51,10 @@ final class DocumentIndexQueryFilter {
   ///
   /// The kind of document that the reference refers to is defined by the
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/)
-  final IdAndVerRef? ref;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? ref;
 
-  /// Document Reference
   /// ## Document Template
   ///
   /// Documents that are created based on a template include the
@@ -64,9 +68,10 @@ final class DocumentIndexQueryFilter {
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/)
   /// however, it will always be a template type document that matches the document
   /// itself.
-  final IdAndVerRef? template;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? template;
 
-  /// Document Reference
   /// ## Document Reply
   ///
   /// This is a
@@ -80,9 +85,10 @@ final class DocumentIndexQueryFilter {
   ///
   /// The kind of document that the reference refers to is defined by the
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
-  final IdAndVerRef? reply;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? reply;
 
-  /// Document Reference
   /// ## Brand
   ///
   /// This is a
@@ -95,9 +101,10 @@ final class DocumentIndexQueryFilter {
   ///
   /// Whether a Document Type has a brand reference is defined by its
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
-  final IdAndVerRef? brand;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? brand;
 
-  /// Document Reference
   /// ## Campaign
   ///
   /// This is a
@@ -110,9 +117,10 @@ final class DocumentIndexQueryFilter {
   ///
   /// Whether a Document Type has a campaign reference is defined by its
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
-  final IdAndVerRef? campaign;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? campaign;
 
-  /// Document Reference
   /// ## Category
   ///
   /// This is a
@@ -125,7 +133,9 @@ final class DocumentIndexQueryFilter {
   ///
   /// Whether a Document Type has a category reference is defined by its
   /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
-  final IdAndVerRef? category;
+  ///
+  /// Max items 10
+  final List<IdAndVerRef>? category;
 
   const DocumentIndexQueryFilter({
     this.type,

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/models/document_reference.dart

@@ -7,16 +7,18 @@ part 'document_reference.g.dart';
 @JsonSerializable()
 final class DocumentReference {
   /// Signed Document ID
-  /// Document ID Reference
   final String id;
 
   /// Signed Document Version
-  /// Document Version
   final String ver;
 
+  /// Signed Document Locator
+  final String? cid;
+
   const DocumentReference({
     required this.id,
     required this.ver,
+    this.cid,
   });
 
   factory DocumentReference.fromJson(Json json) => _$DocumentReferenceFromJson(json);

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/models/indexed_document_version.dart

@@ -15,22 +15,22 @@ final class IndexedDocumentVersion {
   /// Document Type that matches the filter
   final String type;
 
-  /// Document Reference for filtered Documents.
   /// Document Reference that matches the filter
-  final DocumentReference? ref;
+  /// Max items 10
+  final List<DocumentReference>? ref;
 
-  /// Document Reference for filtered Documents.
   /// DDocument Reply Reference that matches the filter
-  final DocumentReference? reply;
+  /// Max items 10
+  final List<DocumentReference>? reply;
 
-  /// Document Reference for filtered Documents.
   /// Document Template Reference that matches the filter
-  final DocumentReference? template;
+  /// Max items 10
+  final List<DocumentReference>? template;
 
-  /// Document Reference for filtered Documents.
   /// Document Parameter Reference that matches the filter
+  /// Max items 10
   @JsonKey(name: 'doc_parameters')
-  final DocumentReference? parameters;
+  final List<DocumentReference>? parameters;
 
   IndexedDocumentVersion({
     required this.ver,

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/api/models/staked_txo_asset_info.dart

@@ -12,12 +12,10 @@ final class StakedTxoAssetInfo {
   final String policyHash;
 
   /// Cardano Native Asset Name
-  /// Token policies Asset Name.
   @JsonKey(name: 'asset_name')
   final String assetName;
 
   /// Cardano native Asset Value
-  /// Token Asset Value.
   final int amount;
 
   const StakedTxoAssetInfo({

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/document/source/document_data_remote_source.dart

@@ -1,10 +1,10 @@
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
 import 'package:catalyst_voices_repositories/catalyst_voices_repositories.dart';
-import 'package:catalyst_voices_repositories/src/api/models/current_page.dart';
 import 'package:catalyst_voices_repositories/src/api/models/document_index_list.dart';
 import 'package:catalyst_voices_repositories/src/api/models/document_index_query_filter.dart';
 import 'package:catalyst_voices_repositories/src/api/models/document_reference.dart';
 import 'package:catalyst_voices_repositories/src/api/models/eq_or_ranged_id.dart';
+import 'package:catalyst_voices_repositories/src/api/models/id_and_ver_ref.dart';
 import 'package:catalyst_voices_repositories/src/common/future_response_mapper.dart';
 import 'package:catalyst_voices_repositories/src/document/document_data_factory.dart';
 import 'package:collection/collection.dart';
@@ -49,7 +49,7 @@ final class CatGatewayDocumentDataSource implements DocumentDataRemoteSource {
     try {
       final index = await _api.gateway
           .documentIndex(
-            filter: DocumentIndexQueryFilter(id: EqOrRangedId.eq(id)),
+            filter: DocumentIndexQueryFilter(id: [EqOrRangedId.eq(id)]),
             limit: 1,
           )
           .successBodyOrThrow();
@@ -76,28 +76,15 @@ final class CatGatewayDocumentDataSource implements DocumentDataRemoteSource {
     var remaining = 0;
 
     do {
-      final response =
-          await _getDocumentIndexList(
-            page: page,
-            limit: maxPerPage,
-            campaign: campaign,
-          )
-          // TODO(damian-molinski): Remove this workaround when migrated to V2 endpoint.
-          // https://github.com/input-output-hk/catalyst-voices/issues/3199#issuecomment-3204803465
-          .onError<NotFoundException>(
-            (_, _) {
-              return DocumentIndexList(
-                docs: [],
-                page: CurrentPage(page: page, limit: maxPerPage, remaining: 0),
-              );
-            },
-          );
+      final response = await _getDocumentIndexList(
+        page: page,
+        limit: maxPerPage,
+        campaign: campaign,
+      );
 
       allRefs.addAll(response.refs);
 
-      // TODO(damian-molinski): Remove this workaround when migrated to V2 endpoint.
-      // https://github.com/input-output-hk/catalyst-voices/issues/3199#issuecomment-3204803465
-      remaining = response.docs.length < maxPerPage ? 0 : response.page.remaining;
+      remaining = response.page.remaining;
       page = response.page.page + 1;
     } while (remaining > 0);
 
@@ -115,16 +102,17 @@ final class CatGatewayDocumentDataSource implements DocumentDataRemoteSource {
     required int limit,
     required Campaign campaign,
   }) async {
-    // TODO(bstolinski): previously it was possible to use `inside` filter for categories.
-    // final categoriesIds = campaign.categories.map((e) => e.selfRef.id).toList();
-    // final categoryFilter = DocumentIndexQueryFilter(
-    //   parameters: IdRefOnly(id: IdSelectorDto.inside(categoriesIds)).toJson(),
-    // );
-    const filter = DocumentIndexQueryFilter();
+    assert(campaign.categories.length <= 10, 'Max 10 categories are allowed in the filter.');
+
+    final categoryFilter = campaign.categories
+        .take(10)
+        .map((e) => IdAndVerRef.idOnly(EqOrRangedId.eq(e.selfRef.id)))
+        .toList();
+    final documentFilter = DocumentIndexQueryFilter(category: categoryFilter);
 
     return _api.gateway
         .documentIndex(
-          filter: filter,
+          filter: documentFilter,
           limit: limit,
           page: page,
         )
@@ -155,24 +143,32 @@ extension on DocumentIndexList {
                       type: documentType,
                     ),
                     if (ver.ref case final ref?)
-                      TypedDocumentRef(
-                        ref: ref.toRef(),
-                        type: DocumentType.unknown,
+                      ...ref.map(
+                        (ref) => TypedDocumentRef(
+                          ref: ref.toRef(),
+                          type: DocumentType.unknown,
+                        ),
                       ),
                     if (ver.reply case final reply?)
-                      TypedDocumentRef(
-                        ref: reply.toRef(),
-                        type: DocumentType.unknown,
+                      ...reply.map(
+                        (reply) => TypedDocumentRef(
+                          ref: reply.toRef(),
+                          type: DocumentType.unknown,
+                        ),
                       ),
                     if (ver.parameters case final parameters?)
-                      TypedDocumentRef(
-                        ref: parameters.toRef(),
-                        type: DocumentType.categoryParametersDocument,
+                      ...parameters.map(
+                        (parameters) => TypedDocumentRef(
+                          ref: parameters.toRef(),
+                          type: DocumentType.categoryParametersDocument,
+                        ),
                       ),
                     if (ver.template case final template?)
-                      TypedDocumentRef(
-                        ref: template.toRef(),
-                        type: documentType.template ?? DocumentType.unknown,
+                      ...template.map(
+                        (template) => TypedDocumentRef(
+                          ref: template.toRef(),
+                          type: documentType.template ?? DocumentType.unknown,
+                        ),
                       ),
                   ];
                 })

catalyst_voices/packages/internal/catalyst_voices_repositories/test/src/document/source/document_data_remote_source_test.dart

@@ -105,10 +105,12 @@ void main() {
                 return IndexedDocumentVersion(
                   ver: e.version!,
                   type: DocumentType.proposalDocument.uuid,
-                  template: DocumentReference(
-                    id: templateRef.id,
-                    ver: templateRef.version!,
-                  ),
+                  template: [
+                    DocumentReference(
+                      id: templateRef.id,
+                      ver: templateRef.version!,
+                    ),
+                  ],
                 );
               }).toList(),
             ),
@@ -142,8 +144,8 @@ void main() {
 
 IndexedDocument _buildDocumentIndexList({
   int verCount = 2,
-  DocumentReference? template,
-  DocumentReference? ref,
+  List<DocumentReference>? template,
+  List<DocumentReference>? ref,
 }) {
   return IndexedDocument(
     id: DocumentRefFactory.randomUuidV7(),