Merge pull request #294 from IQSS/283-implement-my-data-use-case

Implement GetMyDataCollectionItems use case

Author: ofahimIQSS

docs/useCases.md

@@ -14,6 +14,7 @@ The different use cases currently available in the package are classified below,
     - [Get Collection Facets](#get-collection-facets)
     - [Get User Permissions on a Collection](#get-user-permissions-on-a-collection)
     - [List All Collection Items](#list-all-collection-items)
+    - [List My Data Collection Items](#list-my-data-collection-items)
     - [Get Collection Featured Items](#get-collection-featured-items)
   - [Collections write use cases](#collections-write-use-cases)
     - [Create a Collection](#create-a-collection)
@@ -215,6 +216,62 @@ This use case supports the following optional parameters depending on the search
 - **offset**: (number) Offset for pagination.
 - **collectionSearchCriteria**: ([CollectionSearchCriteria](../src/collections/domain/models/CollectionSearchCriteria.ts)) Supports filtering the collection items by different properties.
 
+#### List My Data Collection Items
+
+Returns an instance of [CollectionItemSubset](../src/collections/domain/models/CollectionItemSubset.ts) that contains reduced information for each collection item for which the calling user has a role.
+
+##### Example call:
+
+```typescript
+import { getMyDataCollectionItems } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const roleIds = [1, 2]
+const collectionItemTypes = [CollectionItemType.DATASET, CollectionItemType.FILE]
+const publishingStatuses = [
+  PublicationStatus.Published,
+  PublicationStatus.Draft,
+  PublicationStatus.Unpublished
+]
+const limit = 10
+const selectedPage = 1
+const searchText = 'search text'
+const otherUserName = 'otherUserName'
+
+getMyDataCollectionItems
+  .execute(
+    roleIds,
+    collectionItemTypes,
+    publishingStatuses,
+    limit,
+    selectedPage,
+    searchText,
+    otherUserName
+  )
+  .then((subset: CollectionItemSubset) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/collections/domain/useCases/GetMyDataCollectionItems.ts) implementation_.
+This use case requires the following parameters:
+
+- **roleIds** is an array of user role identifiers to filter the results. At least one roleId must be specified.
+- **collectionItemTypes** is an array of collection item types to filter the results. At least one collectionItemType must be specified.
+- **publishingStatuses** is an array of publishing statuses to filter the results. At least one publishingStatus must be specified.
+
+This use case supports the following optional parameters depending on the search goals:
+
+- **limit**: (number) Limit of items per page for pagination. (default is 10)
+- **selectedPage**: (number) the page of results to be returned. (default is 1)
+- **searchText** is an optional string to filter the results by.
+- **otherUserName** is an optional string to return the collection items of another user. If not set, the calling user will be used. _Only superusers can use this parameter_.
+
+The `CollectionItemSubset`returned instance contains a property called `totalItemCount` which is necessary for pagination.
+
 #### Get Collection Featured Items
 
 Returns a [CollectionFeaturedItem](../src/collections/domain/models/CollectionFeaturedItem.ts) array containing the featured items of the requested collection, given the collection identifier or alias.

src/collections/domain/models/CollectionItemSubset.ts

@@ -15,13 +15,13 @@ export interface CollectionItemsFacet {
   labels: CollectionItemsFacetLabel[]
 }
 
-interface CollectionItemsFacetLabel {
+export interface CollectionItemsFacetLabel {
   name: string
   count: number
 }
 
 interface CountPerObjectType {
-  dataverses: number
+  collections: number
   datasets: number
   files: number
 }

src/collections/domain/models/CollectionPreview.ts

@@ -12,4 +12,5 @@ export interface CollectionPreview {
   publicationStatuses: PublicationStatus[]
   releaseOrCreateDate: Date
   imageUrl?: string
+  userRoles?: string[]
 }

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -6,6 +6,8 @@ import { CollectionFeaturedItem } from '../models/CollectionFeaturedItem'
 import { CollectionItemSubset } from '../models/CollectionItemSubset'
 import { CollectionSearchCriteria } from '../models/CollectionSearchCriteria'
 import { CollectionUserPermissions } from '../models/CollectionUserPermissions'
+import { PublicationStatus } from '../../../../src/core/domain/models/PublicationStatus'
+import { CollectionItemType } from '../../../../src/collections/domain/models/CollectionItemType'
 
 export interface ICollectionsRepository {
   getCollection(collectionIdOrAlias: number | string): Promise<Collection>
@@ -25,6 +27,15 @@ export interface ICollectionsRepository {
     offset?: number,
     collectionSearchCriteria?: CollectionSearchCriteria
   ): Promise<CollectionItemSubset>
+  getMyDataCollectionItems(
+    roleIds: number[],
+    collectionItemTypes: CollectionItemType[],
+    publicationStatuses: PublicationStatus[],
+    limit?: number,
+    selectedPage?: number,
+    searchText?: string,
+    otherUserName?: string
+  ): Promise<CollectionItemSubset>
   updateCollection(
     collectionIdOrAlias: number | string,
     updatedCollection: CollectionDTO

src/collections/domain/useCases/GetMyDataCollectionItems.ts

@@ -0,0 +1,45 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { CollectionItemSubset } from '../models/CollectionItemSubset'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+import { CollectionItemType } from '../../../../src/collections/domain/models/CollectionItemType'
+import { PublicationStatus } from '../../../../src/core/domain/models/PublicationStatus'
+
+export class GetMyDataCollectionItems implements UseCase<CollectionItemSubset> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Returns an instance of  MyDataCollectionItemSubset that contains the items for which the user has the specified role or roles
+   *
+   * @param {number[]} [roleIds] - the ids of the roles to filter the items by.
+   * @param {CollectionItemType[]} [collectionItemTypes] - the types of items to filter by.
+   * @param {PublicationStatus[]} [publicationStatuses] - the publication statuses to filter by.
+   * @param {number} [limit] - Limit number of items to return for pagination (optional).
+   * @param {number} [selectedPage] - Offset (starting point) for pagination (optional).
+   * @param {string} [searchText] - filter by searching for this text in the results (optional).
+   * @param {string} [otherUserName] - filter by searching for this text in the results (optional).
+   * * @returns {Promise<CollectionItemSubset>}
+   */
+  async execute(
+    roleIds: number[],
+    collectionItemTypes: CollectionItemType[],
+    publicationStatuses: PublicationStatus[],
+    limit?: number,
+    selectedPage?: number,
+    searchText?: string,
+    otherUserName?: string
+  ): Promise<CollectionItemSubset> {
+    return this.collectionsRepository.getMyDataCollectionItems(
+      roleIds,
+      collectionItemTypes,
+      publicationStatuses,
+      limit,
+      selectedPage,
+      searchText,
+      otherUserName
+    )
+  }
+}

src/collections/index.ts

@@ -10,6 +10,7 @@ import { CollectionsRepository } from './infra/repositories/CollectionsRepositor
 import { UpdateCollectionFeaturedItems } from './domain/useCases/UpdateCollectionFeaturedItems'
 import { DeleteCollectionFeaturedItems } from './domain/useCases/DeleteCollectionFeaturedItems'
 import { DeleteCollection } from './domain/useCases/DeleteCollection'
+import { GetMyDataCollectionItems } from './domain/useCases/GetMyDataCollectionItems'
 
 const collectionsRepository = new CollectionsRepository()
 
@@ -18,6 +19,7 @@ const createCollection = new CreateCollection(collectionsRepository)
 const getCollectionFacets = new GetCollectionFacets(collectionsRepository)
 const getCollectionUserPermissions = new GetCollectionUserPermissions(collectionsRepository)
 const getCollectionItems = new GetCollectionItems(collectionsRepository)
+const getMyDataCollectionItems = new GetMyDataCollectionItems(collectionsRepository)
 const publishCollection = new PublishCollection(collectionsRepository)
 const updateCollection = new UpdateCollection(collectionsRepository)
 const getCollectionFeaturedItems = new GetCollectionFeaturedItems(collectionsRepository)
@@ -31,6 +33,7 @@ export {
   getCollectionFacets,
   getCollectionUserPermissions,
   getCollectionItems,
+  getMyDataCollectionItems,
   publishCollection,
   updateCollection,
   getCollectionFeaturedItems,

src/collections/infra/repositories/CollectionsRepository.ts

@@ -3,7 +3,8 @@ import { ICollectionsRepository } from '../../domain/repositories/ICollectionsRe
 import {
   transformCollectionFacetsResponseToCollectionFacets,
   transformCollectionItemsResponseToCollectionItemSubset,
-  transformCollectionResponseToCollection
+  transformCollectionResponseToCollection,
+  transformMyDataResponseToCollectionItemSubset
 } from './transformers/collectionTransformers'
 import { Collection, ROOT_COLLECTION_ID } from '../../domain/models/Collection'
 import { CollectionDTO } from '../../domain/dtos/CollectionDTO'
@@ -21,6 +22,8 @@ import { CollectionFeaturedItem } from '../../domain/models/CollectionFeaturedIt
 import { transformCollectionFeaturedItemsPayloadToCollectionFeaturedItems } from './transformers/collectionFeaturedItemsTransformer'
 import { CollectionFeaturedItemsDTO } from '../../domain/dtos/CollectionFeaturedItemsDTO'
 import { ApiConstants } from '../../../core/infra/repositories/ApiConstants'
+import { PublicationStatus } from '../../../../src/core/domain/models/PublicationStatus'
+import { ReadError } from '../../../core/domain/repositories/ReadError'
 
 export interface NewCollectionRequestPayload {
   alias: string
@@ -63,6 +66,16 @@ export enum GetCollectionItemsQueryParams {
   SHOW_TYPE_COUNTS = 'show_type_counts'
 }
 
+export enum GetMyDataCollectionItemsQueryParams {
+  SEARCH_TEXT = 'mydata_search_term',
+  PER_PAGE = 'per_page',
+  SELECTED_PAGE = 'selected_page',
+  ROLE_ID = 'role_ids',
+  TYPE = 'dvobject_types',
+  PUBLISHED_STATES = 'published_states',
+  USER_IDENTIFIER = 'userIdentifier'
+}
+
 export class CollectionsRepository extends ApiRepository implements ICollectionsRepository {
   private readonly collectionsResourceName: string = 'dataverses'
 
@@ -188,6 +201,76 @@ export class CollectionsRepository extends ApiRepository implements ICollections
       })
   }
 
+  public async getMyDataCollectionItems(
+    roleIds: number[],
+    collectionItemTypes: CollectionItemType[],
+    publicationStatuses: PublicationStatus[],
+    limit?: number,
+    selectedPage?: number,
+    searchText?: string,
+    userIdentifier?: string
+  ): Promise<CollectionItemSubset> {
+    const queryParams = new URLSearchParams()
+
+    if (limit) {
+      queryParams.set(GetMyDataCollectionItemsQueryParams.PER_PAGE, limit.toString())
+    }
+
+    if (selectedPage) {
+      queryParams.set(GetMyDataCollectionItemsQueryParams.SELECTED_PAGE, selectedPage.toString())
+    }
+
+    if (searchText) {
+      queryParams.set(
+        GetMyDataCollectionItemsQueryParams.SEARCH_TEXT,
+        encodeURIComponent(searchText)
+      )
+    }
+
+    roleIds.forEach((roleId) => {
+      queryParams.append(GetMyDataCollectionItemsQueryParams.ROLE_ID, roleId.toString())
+    })
+    if (userIdentifier) {
+      queryParams.set(GetMyDataCollectionItemsQueryParams.USER_IDENTIFIER, userIdentifier)
+    }
+
+    collectionItemTypes.forEach((itemType) => {
+      let mappedItemType: string
+
+      switch (itemType) {
+        case CollectionItemType.COLLECTION:
+          mappedItemType = 'Dataverse'
+          break
+        case CollectionItemType.DATASET:
+          mappedItemType = 'Dataset'
+          break
+        case CollectionItemType.FILE:
+          mappedItemType = 'DataFile'
+          break
+      }
+      queryParams.append(GetMyDataCollectionItemsQueryParams.TYPE, mappedItemType)
+    })
+
+    publicationStatuses.forEach((publicationStatus) => {
+      queryParams.append(
+        GetMyDataCollectionItemsQueryParams.PUBLISHED_STATES,
+        publicationStatus.toString()
+      )
+    })
+    const result = await this.doGet('/mydata/retrieve', true, queryParams)
+      .then((response) => {
+        if (response.data.success !== true) {
+          throw new ReadError(response.data.error_message)
+        }
+        return transformMyDataResponseToCollectionItemSubset(response)
+      })
+      .catch((error) => {
+        throw error
+      })
+
+    return result
+  }
+
   private createCreateOrUpdateRequestBody(
     collectionDTO: CollectionDTO
   ): NewCollectionRequestPayload {

src/collections/infra/repositories/transformers/MyDataCollectionPreviewPayload.ts

@@ -0,0 +1,14 @@
+export interface MyDataCollectionPreviewPayload {
+  name: string
+  parentDataverseName: string
+  identifier: string
+  parentDataverseIdentifier: string
+  url: string
+  image_url: string
+  description: string
+  type?: string
+  publicationStatuses: string[]
+  affiliation: string
+  published_at: string
+  user_roles: string[]
+}

src/collections/infra/repositories/transformers/MyDataCountPerObjectTypePayload.ts

@@ -0,0 +1,5 @@
+export interface MyDataCountPerObjectTypePayload {
+  dataverses_count: number
+  datasets_count: number
+  files_count: number
+}

src/collections/infra/repositories/transformers/MyDataPublicationStatusCountsPayload.ts

@@ -0,0 +1,7 @@
+export interface MyDataPublicationStatusCountsPayload {
+  deaccessioned_count: number
+  draft_count: number
+  in_review_count: number
+  published_count: number
+  unpublished_count: number
+}