Merge branch 'develop' into 334-create-use-cases-for-get-notifications-and-delete-notifications

Author: ChengShi-1

docs/useCases.md

@@ -36,12 +36,15 @@ The different use cases currently available in the package are classified below,
     - [Get Differences between Two Dataset Versions](#get-differences-between-two-dataset-versions)
     - [List All Datasets](#list-all-datasets)
     - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
+    - [Get Dataset Linked Collections](#get-dataset-linked-collections)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
     - [Publish a Dataset](#publish-a-dataset)
     - [Deaccession a Dataset](#deaccession-a-dataset)
     - [Delete a Draft Dataset](#delete-a-draft-dataset)
+    - [Link a Dataset](#link-a-dataset)
+    - [Unlink a Dataset](#unlink-a-dataset)
 - [Files](#Files)
   - [Files read use cases](#files-read-use-cases)
     - [Get a File](#get-a-file)
@@ -88,6 +91,8 @@ The different use cases currently available in the package are classified below,
 - [Notifications](#Notifications)
   - [Get All Notifications by User](#get-all-notifications-by-user)
   - [Delete Notification](#delete-notification)
+- [Search](#Search)
+  - [Get Search Services](#get-search-services)
 
 ## Collections
 
@@ -225,6 +230,8 @@ This use case supports the following optional parameters depending on the search
 - **limit**: (number) Limit for pagination.
 - **offset**: (number) Offset for pagination.
 - **collectionSearchCriteria**: ([CollectionSearchCriteria](../src/collections/domain/models/CollectionSearchCriteria.ts)) Supports filtering the collection items by different properties.
+- **searchServiceName**: The search service name on which to execute the search (Optional).
+- **showTypeCounts**: If true, the response will include the count per object type (Optional).
 
 #### List My Data Collection Items
 
@@ -560,6 +567,37 @@ The `datasetId` parameter can be a string, for persistent identifiers, or a numb
 
 There is an optional third parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is `false`.
 
+#### Get Dataset Citation In Other Formats
+
+Retrieves the citation for a dataset in a specified bibliographic format.
+
+##### Example call:
+
+```typescript
+import { getDatasetCitationInOtherFormats } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 2
+const datasetVersionId = '1.0'
+
+getDatasetCitationInOtherFormats
+  .execute(datasetId, datasetVersionId, format)
+  .then((citationText: FormattedCitation) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetCitationInOtherFormats.ts) implementation_.
+
+Supported formats include 'EndNote' (XML), 'RIS' (plain text), 'BibTeX' (plain text), 'CSLJson' (JSON), and 'Internal' (HTML). The response contains the raw citation content in the requested format, the format type, and the content type (MIME type).
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
+There is an optional third parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is `false`.
+
 #### Get Dataset Citation Text By Private URL Token
 
 Returns the Dataset citation text, given an associated Private URL Token.
@@ -738,6 +776,30 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts)
 
 The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
 
+#### Get Dataset Linked Collections
+
+Returns an array of [DatasetLinkedCollection](../src/datasets/domain/models/DatasetLinkedCollection.ts) that contains the collections linked to a dataset.
+
+##### Example call:
+
+```typescript
+import { getDatasetLinkedCollections } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetLinkedCollections
+  .execute(datasetId)
+  .then((datasetLinkedCollections: DatasetLinkedCollection[]) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetLinkedCollections.ts) implementation_.
+
 ### Datasets Write Use Cases
 
 #### Create a Dataset
@@ -947,6 +1009,48 @@ The `datasetId` parameter is a number for numeric identifiers or string for pers
 
 If you try to delete a dataset without draft version, you will get a not found error.
 
+#### Link a Dataset
+
+Creates a link between a Dataset and a Collection.
+
+##### Example call:
+
+```typescript
+import { linkDataset } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 1
+const collectionAlias = 'collection-alias'
+
+linkDataset.execute(datasetId, collectionAlias)
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/LinkDataset.ts) implementation_.
+
+#### Unlink a Dataset
+
+Removes a link between a Dataset and a Collection.
+
+##### Example call:
+
+```typescript
+import { unlinkDataset } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 1
+const collectionAlias = 'collection-alias'
+
+unlinkDataset.execute(datasetId, collectionAlias)
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/UnlinkDataset.ts) implementation_.
+
 #### Get Download Count of a Dataset
 
 Total number of downloads requested for a dataset, given a dataset numeric identifier,
@@ -2038,3 +2142,25 @@ deleteNotification.execute(notificationId: number).then(() => {
 ```
 
 _See [use case](../src/notifications/domain/useCases/DeleteNotification.ts) implementation_.
+
+## Search
+
+#### Get Search Services
+
+Returns all [Search Services](../src/search/domain/models/SearchService.ts) available in the installation.
+
+##### Example call:
+
+```typescript
+import { getSearchServices } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+getSearchServices.execute().then((searchServices: SearchService[]) => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/search/domain/useCases/GetSearchServices.ts) implementation_.

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -27,6 +27,7 @@ export interface ICollectionsRepository {
     limit?: number,
     offset?: number,
     collectionSearchCriteria?: CollectionSearchCriteria,
+    searchServiceName?: string,
     showTypeCounts?: boolean
   ): Promise<CollectionItemSubset>
   getMyDataCollectionItems(

src/collections/domain/useCases/GetCollectionItems.ts

@@ -18,6 +18,7 @@ export class GetCollectionItems implements UseCase<CollectionItemSubset> {
    * @param {number} [limit] - Limit for pagination (optional).
    * @param {number} [offset] - Offset for pagination (optional).
    * @param {CollectionSearchCriteria} [collectionSearchCriteria] - Supports filtering the collection items by different properties (optional).
+   * @param {string} [searchServiceName] - The search service name on which to execute the search (optional).
    * @param {boolean} [showTypeCounts] - If true, the response will include the count per object type (optional).
    * @returns {Promise<CollectionItemSubset>}
    */
@@ -26,13 +27,15 @@ export class GetCollectionItems implements UseCase<CollectionItemSubset> {
     limit?: number,
     offset?: number,
     collectionSearchCriteria?: CollectionSearchCriteria,
+    searchServiceName?: string,
     showTypeCounts = false
   ): Promise<CollectionItemSubset> {
     return await this.collectionsRepository.getCollectionItems(
       collectionId,
       limit,
       offset,
       collectionSearchCriteria,
+      searchServiceName,
       showTypeCounts
     )
   }

src/collections/infra/repositories/CollectionsRepository.ts

@@ -75,7 +75,8 @@ export enum GetCollectionItemsQueryParams {
   START = 'start',
   TYPE = 'type',
   FILTERQUERY = 'fq',
-  SHOW_TYPE_COUNTS = 'show_type_counts'
+  SHOW_TYPE_COUNTS = 'show_type_counts',
+  SEARCH_SERVICE_NAME = 'search_service'
 }
 
 export enum GetMyDataCollectionItemsQueryParams {
@@ -168,6 +169,7 @@ export class CollectionsRepository extends ApiRepository implements ICollections
     limit?: number,
     offset?: number,
     collectionSearchCriteria?: CollectionSearchCriteria,
+    searchServiceName?: string,
     showTypeCounts?: boolean
   ): Promise<CollectionItemSubset> {
     const queryParams = new URLSearchParams({
@@ -193,6 +195,10 @@ export class CollectionsRepository extends ApiRepository implements ICollections
       queryParams.set(GetCollectionItemsQueryParams.SHOW_TYPE_COUNTS, 'true')
     }
 
+    if (searchServiceName) {
+      queryParams.set(GetCollectionItemsQueryParams.SEARCH_SERVICE_NAME, searchServiceName)
+    }
+
     if (collectionSearchCriteria) {
       this.applyCollectionSearchCriteriaToQueryParams(queryParams, collectionSearchCriteria)
     }

src/datasets/domain/models/CitationFormat.ts

@@ -0,0 +1,7 @@
+export enum CitationFormat {
+  Internal = 'Internal',
+  EndNote = 'EndNote',
+  RIS = 'RIS',
+  BibTeX = 'BibTeX',
+  CSLJson = 'CSL'
+}

src/datasets/domain/models/DatasetLinkedCollection.ts

@@ -0,0 +1,5 @@
+export interface DatasetLinkedCollection {
+  id: number
+  alias: string
+  displayName: string
+}

src/datasets/domain/models/FormattedCitation.ts

@@ -0,0 +1,4 @@
+export type FormattedCitation = {
+  content: string
+  contentType: string
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -9,6 +9,9 @@ import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
 import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
+import { CitationFormat } from '../models/CitationFormat'
+import { FormattedCitation } from '../models/FormattedCitation'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -61,4 +64,13 @@ export interface IDatasetsRepository {
   ): Promise<DatasetDownloadCount>
   getDatasetVersionsSummaries(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]>
   deleteDatasetDraft(datasetId: number | string): Promise<void>
+  linkDataset(datasetId: number, collectionAlias: string): Promise<void>
+  unlinkDataset(datasetId: number, collectionAlias: string): Promise<void>
+  getDatasetLinkedCollections(datasetId: number | string): Promise<DatasetLinkedCollection[]>
+  getDatasetCitationInOtherFormats(
+    datasetId: number | string,
+    datasetVersionId: string,
+    format: CitationFormat,
+    includeDeaccessioned?: boolean
+  ): Promise<FormattedCitation>
 }

src/datasets/domain/useCases/GetDatasetCitationInOtherFormats.ts

@@ -0,0 +1,36 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+import { DatasetNotNumberedVersion } from '../models/DatasetNotNumberedVersion'
+import { FormattedCitation } from '../models/FormattedCitation'
+import { CitationFormat } from '../models/CitationFormat'
+
+export class GetDatasetCitationInOtherFormats implements UseCase<FormattedCitation> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns the dataset citation in the specified format.
+   *
+   * @param {number | string} datasetId - The dataset identifier.
+   * @param {string | DatasetNotNumberedVersion} [datasetVersionId=DatasetNotNumberedVersion.LATEST] - The dataset version identifier, which can be a version-specific string (e.g., '1.0') or a DatasetNotNumberedVersion enum value. Defaults to LATEST.
+   * @param {CitationFormat} format - The citation format to return. One of: 'EndNote', 'RIS', 'BibTeX', 'CSLJson', 'Internal'.
+   * @param {boolean} [includeDeaccessioned=false] - Whether to include deaccessioned versions in the search. Defaults to false.
+   * @returns {Promise<FormattedCitation>} The citation content, format, and content type.
+   */
+  async execute(
+    datasetId: number | string,
+    datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST,
+    format: CitationFormat,
+    includeDeaccessioned = false
+  ): Promise<FormattedCitation> {
+    return await this.datasetsRepository.getDatasetCitationInOtherFormats(
+      datasetId,
+      datasetVersionId,
+      format,
+      includeDeaccessioned
+    )
+  }
+}

src/datasets/domain/useCases/GetDatasetLinkedCollections.ts

@@ -0,0 +1,21 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetLinkedCollections implements UseCase<DatasetLinkedCollection[]> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a list of collections linked to a dataset.
+   *
+   * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @returns {Promise<DatasetLinkedCollection[]>}
+   */
+  async execute(datasetId: number | string): Promise<DatasetLinkedCollection[]> {
+    return await this.datasetsRepository.getDatasetLinkedCollections(datasetId)
+  }
+}