Merge branch 'develop' into 269-get-dataset-download-count-use-case

Author: ChengShi-1

docs/useCases.md

@@ -33,6 +33,7 @@ The different use cases currently available in the package are classified below,
     - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset)
     - [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)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
@@ -577,7 +578,7 @@ const datasetId = 'doi:10.77777/FK2/AAAAAA'
 const oldVersion = '1.0'
 const newVersion = '2.0'
 
-lgetDatasetVersionDiff
+getDatasetVersionDiff
   .execute(datasetId, oldVersion, newVersion)
   .then((versionDiff: DatasetVersionDiff) => {
     /* ... */
@@ -622,6 +623,32 @@ Note that `collectionId` is an optional parameter to filter datasets by collecti
 
 The `DatasetPreviewSubset`returned instance contains a property called `totalDatasetCount` which is necessary for pagination.
 
+#### Get Dataset Versions Summaries
+
+Returns an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersionsSummaries } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetVersionsSummaries
+  .execute(datasetId)
+  .then((datasetVersionsSummaries: DatasetVersionSummaryInfo[]) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
 ### Datasets Write Use Cases
 
 #### Create a Dataset
@@ -1291,6 +1318,33 @@ The following error might arise from the `AddUploadedFileToDataset` use case:
 
 - AddUploadedFileToDatasetError: This error indicates that there was an error while adding the uploaded file to the dataset.
 
+#### Update File Metadata
+
+Updates Metadata of a File.
+
+###### Example call:
+
+```typescript
+import { updateFileMetadata } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const fileId: number | string = 123
+const updateFileMetadataDTO = {
+  description: 'My description bbb.',
+  categories: ['Data'],
+  restrict: false
+}
+
+await updateFileMetadata.execute(fileId, updateFileMetadataDTO).then((fileId) => {
+  console.log(`File updated successfully with file ID: ${fileId}`)
+})
+```
+
+_See [use case](../src/files/domain/useCases/UpdateFileMetadata.ts) implementation_.
+
+The `fileId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
 #### Delete a File
 
 Deletes a File.

jest.config.ts

@@ -9,7 +9,7 @@ const config: Config = {
   moduleFileExtensions: ['ts', 'js', 'json', 'node'],
   coveragePathIgnorePatterns: ['node_modules', 'testHelpers'],
   globalSetup: '<rootDir>/test/environment/setup.ts',
-  testTimeout: 25000,
+  testTimeout: 35000,
   coverageThreshold: {
     global: {
       branches: 90,

src/datasets/domain/models/DatasetVersionSummaryInfo.ts

@@ -0,0 +1,36 @@
+export interface DatasetVersionSummaryInfo {
+  id: number
+  versionNumber: string
+  summary?: DatasetVersionSummary | DatasetVersionSummaryStringValues
+  contributors: string
+  publishedOn?: string
+}
+
+export type DatasetVersionSummary = {
+  [key: string]: SummaryUpdates | SummaryUpdatesWithFields | FilesSummaryUpdates | boolean
+}
+
+interface SummaryUpdates {
+  added: number
+  deleted: number
+  changed: number
+}
+
+interface SummaryUpdatesWithFields {
+  [key: string]: SummaryUpdates
+}
+
+interface FilesSummaryUpdates {
+  added: number
+  removed: number
+  replaced: number
+  changedFileMetaData: number
+  changedVariableMetadata: number
+}
+
+export enum DatasetVersionSummaryStringValues {
+  firstPublished = 'firstPublished',
+  firstDraft = 'firstDraft',
+  versionDeaccessioned = 'versionDeaccessioned',
+  previousVersionDeaccessioned = 'previousVersionDeaccessioned'
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -8,6 +8,7 @@ import { DatasetDeaccessionDTO } from '../dtos/DatasetDeaccessionDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
+import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -53,4 +54,5 @@ export interface IDatasetsRepository {
     deaccessionDTO: DatasetDeaccessionDTO
   ): Promise<void>
   getDatasetDownloadCount(datasetId: number, includeMDC?: boolean): Promise<DatasetDownloadCount>
+  getDatasetVersionsSummaries(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]>
 }

src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummaryInfo[]> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a list of versions for a given dataset including a summary of differences between consecutive versions where available.
+   * Draft versions will only be available to users who have permission to view unpublished drafts.
+   *
+   * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @returns {Promise<DatasetVersionSummaryInfo[]>} - An array of DatasetVersionSummaryInfo.
+   */
+  async execute(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]> {
+    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId)
+  }
+}

src/datasets/index.ts

@@ -18,6 +18,7 @@ import { UpdateDataset } from './domain/useCases/UpdateDataset'
 import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 import { DeaccessionDataset } from './domain/useCases/DeaccessionDataset'
 import { GetDatasetDownloadCount } from './domain/useCases/GetDatasetDownloadCount'
+import { GetDatasetVersionsSummaries } from './domain/useCases/GetDatasetVersionsSummaries'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -50,6 +51,7 @@ const updateDataset = new UpdateDataset(
 )
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
 const getDatasetDownloadCount = new GetDatasetDownloadCount(datasetsRepository)
+const getDatasetVersionsSummaries = new GetDatasetVersionsSummaries(datasetsRepository)
 
 export {
   getDataset,
@@ -65,7 +67,8 @@ export {
   createDataset,
   updateDataset,
   deaccessionDataset,
-  getDatasetDownloadCount
+  getDatasetDownloadCount,
+  getDatasetVersionsSummaries
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'
@@ -95,3 +98,7 @@ export {
 export { DatasetDeaccessionDTO } from './domain/dtos/DatasetDeaccessionDTO'
 export { CreatedDatasetIdentifiers } from './domain/models/CreatedDatasetIdentifiers'
 export { VersionUpdateType } from './domain/models/Dataset'
+export {
+  DatasetVersionSummaryInfo,
+  DatasetVersionSummaryStringValues
+} from './domain/models/DatasetVersionSummaryInfo'

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -19,6 +19,7 @@ import { transformDatasetPreviewsResponseToDatasetPreviewSubset } from './transf
 import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
 import { DatasetDownloadCount } from '../../domain/models/DatasetDownloadCount'
+import { DatasetVersionSummaryInfo } from '../../domain/models/DatasetVersionSummaryInfo'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -253,4 +254,17 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
         throw error
       })
   }
+
+  public async getDatasetVersionsSummaries(
+    datasetId: string | number
+  ): Promise<DatasetVersionSummaryInfo[]> {
+    return this.doGet(
+      this.buildApiEndpoint(this.datasetsResourceName, 'versions/compareSummary', datasetId),
+      true
+    )
+      .then((response) => response.data.data)
+      .catch((error) => {
+        throw error
+      })
+  }
 }

src/files/domain/dtos/UpdateFileMetadataDTO.ts

@@ -0,0 +1,7 @@
+export interface UpdateFileMetadataDTO {
+  description?: string
+  prevFreeform?: string
+  categories?: string[]
+  dataFileTags?: string[]
+  restrict?: boolean
+}

src/files/domain/repositories/IFilesRepository.ts

@@ -8,6 +8,7 @@ import { FileModel } from '../models/FileModel'
 import { Dataset } from '../../../datasets'
 import { FileUploadDestination } from '../models/FileUploadDestination'
 import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
+import { UpdateFileMetadataDTO } from '../dtos/UpdateFileMetadataDTO'
 
 export interface IFilesRepository {
   getDatasetFiles(
@@ -65,4 +66,8 @@ export interface IFilesRepository {
   replaceFile(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<undefined>
 
   restrictFile(fileId: number | string, restrict: boolean): Promise<undefined>
+  updateFileMetadata(
+    fileId: number | string,
+    updateFileMetadataDTO: UpdateFileMetadataDTO
+  ): Promise<void>
 }

src/files/domain/useCases/UpdateFileMetadata.ts

@@ -0,0 +1,26 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IFilesRepository } from '../repositories/IFilesRepository'
+import { UpdateFileMetadataDTO } from '../dtos/UpdateFileMetadataDTO'
+
+export class UpdateFileMetadata implements UseCase<void> {
+  private filesRepository: IFilesRepository
+
+  constructor(filesRepository: IFilesRepository) {
+    this.filesRepository = filesRepository
+  }
+
+  /**
+   * Updates the metadata for a particular File.
+   * More detailed information about updating a file's metadata behavior can be found in https://guides.dataverse.org/en/latest/api/native-api.html#updating-file-metadata
+   *
+   * @param {number | string} [fileId] - The file identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @param {UpdateFileMetadataDTO} [updateFileMetadataDTO] - The DTO containing the metadata updates.
+   * @returns {Promise<void>}
+   */
+  async execute(
+    fileId: number | string,
+    updateFileMetadataDTO: UpdateFileMetadataDTO
+  ): Promise<void> {
+    await this.filesRepository.updateFileMetadata(fileId, updateFileMetadataDTO)
+  }
+}