feat: export metadata use case

Author: ChengShi-1

CHANGELOG.md

@@ -14,6 +14,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Guestbooks: Added optional `includeStats` support to `getGuestbooksByCollectionId`, returning `usageCount` and `responseCount` when requested.
 - 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, `ExportedDatasetMetadata` response type, and `DatasetMetadataExportVersion` enum to support exporting dataset metadata by numeric id or persistent id through Dataverse endpoint `GET /datasets/export`.
 - 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

@@ -46,6 +46,8 @@ The different use cases currently available in the package are classified below,
     - [Get a Dataset](#get-a-dataset)
     - [Get Dataset By Private URL Token](#get-dataset-by-private-url-token)
     - [Get Dataset Citation Text](#get-dataset-citation-text)
+    - [Get Dataset Citation In Other Formats](#get-dataset-citation-in-other-formats)
+    - [Export Dataset Metadata](#export-dataset-metadata)
     - [Get Dataset Citation Text By Private URL Token](#get-dataset-citation-text-by-private-url-token)
     - [Get Dataset Locks](#get-dataset-locks)
     - [Get Dataset Summary Field Names](#get-dataset-summary-field-names)
@@ -1053,6 +1055,35 @@ 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`.
 
+#### Export Dataset Metadata
+
+Exports dataset metadata in a specified metadata export format.
+
+##### Example call:
+
+```typescript
+import {
+  exportDatasetMetadata,
+  DatasetMetadataExportVersion,
+  ExportedDatasetMetadata
+} from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+const exporter = 'ddi'
+
+exportDatasetMetadata
+  .execute(datasetId, exporter, DatasetMetadataExportVersion.DRAFT)
+  .then((metadata: ExportedDatasetMetadata) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/ExportDatasetMetadata.ts) implementation_.
+
 #### Get Dataset Citation Text By Private URL Token
 
 Returns the Dataset citation text, given an associated Private URL Token.

src/datasets/domain/models/ExportedDatasetMetadata.ts

@@ -0,0 +1,9 @@
+export type ExportedDatasetMetadata = {
+  content: string
+  contentType: string
+}
+
+export enum DatasetMetadataExportVersion {
+  LATEST_PUBLISHED = ':latest-published',
+  DRAFT = ':draft'
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -19,6 +19,8 @@ import { DatasetTypeDTO } from '../dtos/DatasetTypeDTO'
 import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { DatasetUploadLimits } from '../models/DatasetUploadLimits'
 import { DatasetReview } from '../models/DatasetReview'
+import { ExportedDatasetMetadata } from '../models/ExportedDatasetMetadata'
+import { DatasetMetadataExportVersion } from '../models/ExportedDatasetMetadata'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -86,6 +88,11 @@ export interface IDatasetsRepository {
     format: CitationFormat,
     includeDeaccessioned?: boolean
   ): Promise<FormattedCitation>
+  exportDatasetMetadata(
+    datasetId: number | string,
+    exporter: string,
+    version?: DatasetMetadataExportVersion
+  ): Promise<ExportedDatasetMetadata>
   getDatasetAvailableDatasetTypes(): Promise<DatasetType[]>
   getDatasetAvailableDatasetType(datasetTypeId: number | string): Promise<DatasetType>
   addDatasetType(datasetType: DatasetTypeDTO): Promise<DatasetType>

src/datasets/domain/useCases/ExportDatasetMetadata.ts

@@ -0,0 +1,28 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { DatasetMetadataExportVersion } from '../models/ExportedDatasetMetadata'
+import { ExportedDatasetMetadata } from '../models/ExportedDatasetMetadata'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+
+export class ExportDatasetMetadata implements UseCase<ExportedDatasetMetadata> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Exports dataset metadata in the specified metadata export format.
+   *
+   * @param {number | string} datasetId - The dataset identifier, which can be a string for persistent identifiers or a number for numeric identifiers.
+   * @param {string} exporter - The metadata exporter format name.
+   * @param {DatasetMetadataExportVersion} [version] - The dataset version to export. If omitted, Dataverse defaults to :latest-published.
+   * @returns {Promise<ExportedDatasetMetadata>} The exported metadata content and content type.
+   */
+  async execute(
+    datasetId: number | string,
+    exporter: string,
+    version?: DatasetMetadataExportVersion
+  ): Promise<ExportedDatasetMetadata> {
+    return await this.datasetsRepository.exportDatasetMetadata(datasetId, exporter, version)
+  }
+}

src/datasets/index.ts

@@ -36,6 +36,7 @@ import { UpdateDatasetLicense } from './domain/useCases/UpdateDatasetLicense'
 import { GetDatasetStorageDriver } from './domain/useCases/GetDatasetStorageDriver'
 import { GetDatasetUploadLimits } from './domain/useCases/GetDatasetUploadLimits'
 import { GetDatasetReviews } from './domain/useCases/GetDatasetReviews'
+import { ExportDatasetMetadata } from './domain/useCases/ExportDatasetMetadata'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -88,6 +89,7 @@ const updateDatasetLicense = new UpdateDatasetLicense(datasetsRepository)
 const getDatasetStorageDriver = new GetDatasetStorageDriver(datasetsRepository)
 const getDatasetUploadLimits = new GetDatasetUploadLimits(datasetsRepository)
 const getDatasetReviews = new GetDatasetReviews(datasetsRepository)
+const exportDatasetMetadata = new ExportDatasetMetadata(datasetsRepository)
 
 export {
   getDataset,
@@ -121,9 +123,14 @@ export {
   updateDatasetLicense,
   getDatasetStorageDriver,
   getDatasetUploadLimits,
-  getDatasetReviews
+  getDatasetReviews,
+  exportDatasetMetadata
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
+export {
+  DatasetMetadataExportVersion,
+  ExportedDatasetMetadata
+} from './domain/models/ExportedDatasetMetadata'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'
 export { DatasetLock, DatasetLockType } from './domain/models/DatasetLock'
 export {

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -26,13 +26,16 @@ import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } fr
 import { FormattedCitation } from '../../domain/models/FormattedCitation'
 import { DatasetType } from '../../domain/models/DatasetType'
 import { TermsOfAccess } from '../../domain/models/Dataset'
+import { DatasetNotNumberedVersion } from '../../domain/models/DatasetNotNumberedVersion'
 import { transformTermsOfAccessToUpdatePayload } from './transformers/termsOfAccessTransformers'
 import { DatasetLicenseUpdateRequest } from '../../domain/dtos/DatasetLicenseUpdateRequest'
 import { DatasetTypeDTO } from '../../domain/dtos/DatasetTypeDTO'
 import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { DatasetUploadLimits } from '../../domain/models/DatasetUploadLimits'
 import { DatasetReview } from '../../domain/models/DatasetReview'
 import { transformDatasetReviewsResponseToDatasetReviews } from './transformers/datasetReviewTransformers'
+import { ExportedDatasetMetadata } from '../../domain/models/ExportedDatasetMetadata'
+import { DatasetMetadataExportVersion } from '../../domain/models/ExportedDatasetMetadata'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -133,6 +136,39 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
     }
   }
 
+  public async exportDatasetMetadata(
+    datasetId: number | string,
+    exporter: string,
+    version?: DatasetMetadataExportVersion
+  ): Promise<ExportedDatasetMetadata> {
+    const persistentId =
+      typeof datasetId === 'number'
+        ? (
+            await this.getDataset(
+              datasetId,
+              version ?? DatasetNotNumberedVersion.LATEST_PUBLISHED,
+              false,
+              false
+            )
+          ).persistentId
+        : datasetId
+
+    const response = await this.doGet('/datasets/export', true, {
+      exporter,
+      persistentId,
+      ...(version && { version })
+    })
+
+    const contentType = response.headers['content-type']
+    const content =
+      typeof response.data === 'string' ? response.data : JSON.stringify(response.data)
+
+    return {
+      content,
+      contentType
+    }
+  }
+
   public async getPrivateUrlDatasetCitation(token: string): Promise<string> {
     return this.doGet(
       this.buildApiEndpoint(this.datasetsResourceName, `privateUrlDatasetVersion/${token}/citation`)

test/integration/datasets/DatasetsRepository.test.ts

@@ -35,7 +35,8 @@ import {
   updateTermsOfAccess,
   DatasetLicenseUpdateRequest,
   getDatasetReviews,
-  DatasetReview
+  DatasetReview,
+  DatasetMetadataExportVersion
 } from '../../../src/datasets'
 import { ApiConfig, WriteError } from '../../../src'
 import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig'
@@ -772,6 +773,43 @@ describe('DatasetsRepository', () => {
     })
   })
 
+  describe('exportDatasetMetadata', () => {
+    let draftDatasetIds: CreatedDatasetIdentifiers
+    let publishedDatasetIds: CreatedDatasetIdentifiers
+
+    beforeAll(async () => {
+      draftDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+      publishedDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+      await publishDatasetViaApi(publishedDatasetIds.numericId)
+      await waitForNoLocks(publishedDatasetIds.numericId, 10)
+    })
+
+    afterAll(async () => {
+      await deleteUnpublishedDatasetViaApi(draftDatasetIds.numericId)
+      await deletePublishedDatasetViaApi(publishedDatasetIds.persistentId)
+    })
+
+    test('should export latest published dataset metadata in DDI format by default', async () => {
+      const metadata = await sut.exportDatasetMetadata(publishedDatasetIds.persistentId, 'ddi')
+
+      expect(typeof metadata.content).toBe('string')
+      expect(metadata.content.length).toBeGreaterThan(0)
+      expect(metadata.contentType).toMatch(/xml/)
+    })
+
+    test('should export draft dataset metadata in DDI format', async () => {
+      const metadata = await sut.exportDatasetMetadata(
+        draftDatasetIds.numericId,
+        'ddi',
+        DatasetMetadataExportVersion.DRAFT
+      )
+
+      expect(typeof metadata.content).toBe('string')
+      expect(metadata.content.length).toBeGreaterThan(0)
+      expect(metadata.contentType).toMatch(/xml/)
+    })
+  })
+
   describe('getDatasetVersionDiff', () => {
     let testDatasetIds: CreatedDatasetIdentifiers
 

test/unit/datasets/ExportDatasetMetadata.test.ts

@@ -0,0 +1,46 @@
+import { ExportDatasetMetadata } from '../../../src/datasets/domain/useCases/ExportDatasetMetadata'
+import { IDatasetsRepository } from '../../../src/datasets/domain/repositories/IDatasetsRepository'
+import { ReadError } from '../../../src/core/domain/repositories/ReadError'
+import { ExportedDatasetMetadata } from '../../../src/datasets/domain/models/ExportedDatasetMetadata'
+import { DatasetMetadataExportVersion } from '../../../src/datasets/domain/models/ExportedDatasetMetadata'
+
+describe('ExportDatasetMetadata.execute', () => {
+  const testDatasetId = 1
+  const testExporter = 'ddi'
+
+  test('should return exported dataset metadata on repository success', async () => {
+    const expectedMetadata: ExportedDatasetMetadata = {
+      content: '<codeBook></codeBook>',
+      contentType: 'application/xml'
+    }
+
+    const datasetsRepositoryStub: IDatasetsRepository = {
+      exportDatasetMetadata: jest.fn().mockResolvedValue(expectedMetadata)
+    } as unknown as IDatasetsRepository
+
+    const sut = new ExportDatasetMetadata(datasetsRepositoryStub)
+
+    const actual = await sut.execute(
+      testDatasetId,
+      testExporter,
+      DatasetMetadataExportVersion.DRAFT
+    )
+
+    expect(actual).toEqual(expectedMetadata)
+    expect(datasetsRepositoryStub.exportDatasetMetadata).toHaveBeenCalledWith(
+      testDatasetId,
+      testExporter,
+      DatasetMetadataExportVersion.DRAFT
+    )
+  })
+
+  test('should throw ReadError on repository failure', async () => {
+    const datasetsRepositoryStub: IDatasetsRepository = {
+      exportDatasetMetadata: jest.fn().mockRejectedValue(new ReadError())
+    } as unknown as IDatasetsRepository
+
+    const sut = new ExportDatasetMetadata(datasetsRepositoryStub)
+
+    await expect(sut.execute(testDatasetId, testExporter)).rejects.toThrow(ReadError)
+  })
+})