Add use case for getting dataset versions

CHANGELOG.md

@@ -15,6 +15,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Files: Added `getFileCitationByFormat` use case, repository method, and `FileCitationFormat` enum to support Dataverse file citation exports in `EndNote`, `RIS`, `BibTeX`, `CSL`, and `Internal` formats.
 - Datasets: Added `getDatasetReviews` use case and repository method to support Dataverse endpoint `GET /datasets/{identifier}/reviews`, for retrieving review datasets associated with a dataset by persistent id or numeric id.
 - Datasets: Added `exportDatasetMetadata` use case, repository method, and `ExportedDatasetMetadata` response type to support exporting dataset metadata by numeric id or persistent id through Dataverse endpoint `GET /datasets/export`.
+- Datasets: Added `getDatasetVersions` use case.
 - Collections: Added `allowedDatasetTypes` field to the [Collection](./src/collections/domain/models/Collection.ts) model. This field is optional and only populated the feature is enabled on the installation and configured on the collection.
 - Collections: Added theme information when retrieving a collection using `getCollection`.
 

docs/useCases.md

@@ -54,6 +54,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](#get-dataset-versions)
     - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
     - [Get Dataset Linked Collections](#get-dataset-linked-collections)
     - [Get Dataset Available Categories](#get-dataset-available-categories)
@@ -1262,6 +1263,36 @@ 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
+
+Returns the total count of versions and an array of [DatasetVersion](../src/datasets/domain/models/DatasetVersion.ts) that contains information about every specific version.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersions } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetVersions
+  .execute(datasetId)
+  .then((datasetVersions: DatasetVersionSubset) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersions.ts) implementation_.
+
+- The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+- **limit**: (number) Limit for pagination.
+- **offset**: (number) Offset for pagination.
+- **excludeMetadataBlocks**: (boolean) Exclude metadata blocks (default: false).
+- Note that the **excludeFiles** parameter, which is available on Dataverse's "List Versions of a Dataset" API, is not available here. The list of files can be retrieved using the separate use case [List Files in a Dataset](#list-files-in-a-dataset).
+
 #### Get Dataset Versions Summaries
 
 Returns the total count of versions and an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.

src/datasets/domain/models/DatasetVersion.ts

@@ -0,0 +1,28 @@
+import { DatasetLicense, DatasetMetadataBlocks, DatasetVersionState } from "./Dataset";
+import { FilePayload } from "../../../files/infra/repositories/transformers/FilePayload";
+
+export interface DatasetVersion {
+  id: number
+  datasetId: number
+  datasetPersistentId: string
+  alternativePersistentId?: string
+  datasetType: string
+  storageIdentifier: string
+  versionNumber?: number
+  versionMinorNumber?: number
+  internalVersionNumber: number
+  versionState: DatasetVersionState
+  latestVersionPublishingState: DatasetVersionState
+  lastUpdateTime: string
+  releaseTime?: string
+  createTime: string
+  publicationDate: string
+  citationDate: string
+  license: DatasetLicense
+  fileAccessRequest: boolean
+  metadataBlocks?: DatasetMetadataBlocks
+}
+
+export interface DatasetVersionSubset {
+  versions: DatasetVersion[]
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -9,6 +9,7 @@ import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
 import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSubset } from '../models/DatasetVersion'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
@@ -77,6 +78,12 @@ export interface IDatasetsRepository {
     limit?: number,
     offset?: number
   ): Promise<DatasetVersionSummarySubset>
+  getDatasetVersions(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean
+  ): Promise<DatasetVersionSubset>
   deleteDatasetDraft(datasetId: number | string): Promise<void>
   linkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>
   unlinkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>

src/datasets/domain/useCases/GetDatasetVersions.ts

@@ -0,0 +1,30 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetVersionSubset } from '../models/DatasetVersion'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class GetDatasetVersions implements UseCase<DatasetVersionSubset> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns a list of versions for a given dataset including (optionally) metadata blocks and files.
+   * 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).
+   * @param {number} [limit] - Limit for pagination (optional).
+   * @param {number} [offset] - Offset for pagination (optional).
+   * @param {boolean} [excludeMetadataBlocks] - Exclude metadata blocks (optional, default: false).
+   * @returns {Promise<DatasetVersionSubset>} - A DatasetVersionSubset containing the versions and total count.
+   */
+  async execute(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean
+  ): Promise<DatasetVersionSubset> {
+    return await this.datasetsRepository.getDatasetVersions(datasetId, limit, offset, excludeMetadataBlocks)
+  }
+}

src/datasets/index.ts

@@ -19,6 +19,7 @@ import { GetDatasetVersionDiff } from './domain/useCases/GetDatasetVersionDiff'
 import { DeaccessionDataset } from './domain/useCases/DeaccessionDataset'
 import { GetDatasetDownloadCount } from './domain/useCases/GetDatasetDownloadCount'
 import { GetDatasetVersionsSummaries } from './domain/useCases/GetDatasetVersionsSummaries'
+import { GetDatasetVersions } from './domain/useCases/GetDatasetVersions'
 import { DeleteDatasetDraft } from './domain/useCases/DeleteDatasetDraft'
 import { LinkDataset } from './domain/useCases/LinkDataset'
 import { UnlinkDataset } from './domain/useCases/UnlinkDataset'
@@ -70,6 +71,7 @@ const updateDataset = new UpdateDataset(
 const deaccessionDataset = new DeaccessionDataset(datasetsRepository)
 const getDatasetDownloadCount = new GetDatasetDownloadCount(datasetsRepository)
 const getDatasetVersionsSummaries = new GetDatasetVersionsSummaries(datasetsRepository)
+const getDatasetVersions = new GetDatasetVersions(datasetsRepository)
 const deleteDatasetDraft = new DeleteDatasetDraft(datasetsRepository)
 const linkDataset = new LinkDataset(datasetsRepository)
 const unlinkDataset = new UnlinkDataset(datasetsRepository)
@@ -107,6 +109,7 @@ export {
   deaccessionDataset,
   getDatasetDownloadCount,
   getDatasetVersionsSummaries,
+  getDatasetVersions,
   deleteDatasetDraft,
   linkDataset,
   unlinkDataset,
@@ -143,6 +146,7 @@ export {
   TermsOfUse
 } from './domain/models/Dataset'
 export { DatasetPreview } from './domain/models/DatasetPreview'
+export { DatasetVersion } from './domain/models/DatasetVersion'
 export { DatasetVersionDiff } from './domain/models/DatasetVersionDiff'
 export { DatasetPreviewSubset } from './domain/models/DatasetPreviewSubset'
 export {

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -20,6 +20,7 @@ import { DatasetVersionDiff } from '../../domain/models/DatasetVersionDiff'
 import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './transformers/datasetVersionDiffTransformers'
 import { DatasetDownloadCount } from '../../domain/models/DatasetDownloadCount'
 import { DatasetVersionSummarySubset } from '../../domain/models/DatasetVersionSummaryInfo'
+import { DatasetVersionSubset } from '../../domain/models/DatasetVersion'
 import { DatasetLinkedCollection } from '../../domain/models/DatasetLinkedCollection'
 import { CitationFormat } from '../../domain/models/CitationFormat'
 import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } from './transformers/datasetLinkedCollectionsTransformers'
@@ -372,6 +373,39 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
       })
   }
 
+  public async getDatasetVersions(
+    datasetId: string | number,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean
+  ): Promise<DatasetVersionSubset> {
+    const queryParams = new URLSearchParams()
+
+    if (limit) {
+      queryParams.set('limit', limit.toString())
+    }
+
+    if (offset) {
+      queryParams.set('offset', offset.toString())
+    }
+
+    if (excludeMetadataBlocks !== undefined) {
+      queryParams.set('excludeMetadataBlocks', excludeMetadataBlocks.toString())
+    }
+
+    return this.doGet(
+      this.buildApiEndpoint(this.datasetsResourceName, 'versions', datasetId),
+      true,
+      queryParams
+    )
+      .then((response) => ({
+        versions: response.data.data
+      }))
+      .catch((error) => {
+        throw error
+      })
+  }
+
   public async deleteDatasetDraft(datasetId: string | number): Promise<void> {
     return this.doDelete(
       this.buildApiEndpoint(this.datasetsResourceName, 'versions/:draft', datasetId)