Merge branch 'develop' into edit-metadata-allow-empty-values

Author: g-saracca

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
@@ -1257,6 +1284,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.
@@ -1305,7 +1359,9 @@ const uploadedFileDTO: UploadedFileDTO = {
   mimeType: 'text/plain'
 }
 
-replaceFile.execute(fileId, uploadedFileDTO)
+replaceFile.execute(fileId, uploadedFileDTO).then((newFileId: number) => {
+  /* ... */
+})
 
 /* ... */
 ```
@@ -1316,6 +1372,8 @@ The `fileId` parameter can be a string, for persistent identifiers, or a number,
 
 The `uploadedFileDTO` parameter is a [UploadedFileDTO](../src/files/domain/dtos/UploadedFileDTO.ts) and includes properties related to the uploaded files. Some of these properties should be calculated from the uploaded File Blob objects and the resulting storage identifiers from the Upload File use case.
 
+The use case returns a number, which is the identifier of the new file.
+
 #### Restrict or Unrestrict a File
 
 Restrict or unrestrict an existing 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

@@ -7,6 +7,7 @@ import { DatasetDTO } from '../dtos/DatasetDTO'
 import { DatasetDeaccessionDTO } from '../dtos/DatasetDeaccessionDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
+import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -51,4 +52,5 @@ export interface IDatasetsRepository {
     datasetVersionId: string,
     deaccessionDTO: DatasetDeaccessionDTO
   ): Promise<void>
+  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

@@ -17,6 +17,7 @@ import { PublishDataset } from './domain/useCases/PublishDataset'
 import { UpdateDataset } from './domain/useCases/UpdateDataset'
 import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 import { DeaccessionDataset } from './domain/useCases/DeaccessionDataset'
+import { GetDatasetVersionsSummaries } from './domain/useCases/GetDatasetVersionsSummaries'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -48,6 +49,7 @@ const updateDataset = new UpdateDataset(
   datasetResourceValidator
 )
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
+const getDatasetVersionsSummaries = new GetDatasetVersionsSummaries(datasetsRepository)
 
 export {
   getDataset,
@@ -62,7 +64,8 @@ export {
   publishDataset,
   createDataset,
   updateDataset,
-  deaccessionDataset
+  deaccessionDataset,
+  getDatasetVersionsSummaries
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'
@@ -92,3 +95,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

@@ -18,6 +18,7 @@ import { transformDatasetLocksResponseToDatasetLocks } from './transformers/data
 import { transformDatasetPreviewsResponseToDatasetPreviewSubset } from './transformers/datasetPreviewsTransformers'
 import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
+import { DatasetVersionSummaryInfo } from '../../domain/models/DatasetVersionSummaryInfo'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -235,4 +236,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(
@@ -62,7 +63,11 @@ export interface IFilesRepository {
 
   deleteFile(fileId: number | string): Promise<undefined>
 
-  replaceFile(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<undefined>
+  replaceFile(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<number>
 
   restrictFile(fileId: number | string, restrict: boolean): Promise<undefined>
+  updateFileMetadata(
+    fileId: number | string,
+    updateFileMetadataDTO: UpdateFileMetadataDTO
+  ): Promise<void>
 }

src/files/domain/useCases/ReplaceFile.ts

@@ -2,7 +2,7 @@ import { UseCase } from '../../../core/domain/useCases/UseCase'
 import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
 import { IFilesRepository } from '../repositories/IFilesRepository'
 
-export class ReplaceFile implements UseCase<void> {
+export class ReplaceFile implements UseCase<number> {
   private filesRepository: IFilesRepository
 
   constructor(filesRepository: IFilesRepository) {
@@ -19,10 +19,10 @@ export class ReplaceFile implements UseCase<void> {
    *
    * @param {number | string} [fileId] - The File identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
    * @param {UploadedFileDTO} [uploadedFileDTO] - File DTO associated with the uploaded file.
-   * @returns {Promise<void>} A promise that resolves when the file has been successfully replaced.
+   * @returns {Promise<number>} A promise that resolves when the file has been successfully replaced and returns the new file identifier.
    * @throws {WriteError} - If there are errors while writing data.
    */
-  async execute(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<void> {
-    await this.filesRepository.replaceFile(fileId, uploadedFileDTO)
+  async execute(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<number> {
+    return await this.filesRepository.replaceFile(fileId, uploadedFileDTO)
   }
 }