feat: update get citation in other format

Author: ChengShi-1

docs/useCases.md

@@ -564,6 +564,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: CitationResponse) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_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.

src/datasets/domain/models/CitationFormats.ts

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

src/datasets/domain/models/CitationResponse.ts

@@ -0,0 +1,7 @@
+import { CitationFormats } from './CitationFormats'
+
+export type CitationResponse = {
+  content: string
+  format: CitationFormats
+  contentType: string
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -10,6 +10,8 @@ import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
 import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
+import { CitationFormats } from '../models/CitationFormats'
+import { CitationResponse } from '../models/CitationResponse'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -65,4 +67,10 @@ export interface IDatasetsRepository {
   linkDataset(datasetId: number, collectionAlias: string): Promise<void>
   unlinkDataset(datasetId: number, collectionAlias: string): Promise<void>
   getDatasetLinkedCollections(datasetId: number | string): Promise<DatasetLinkedCollection[]>
+  getDatasetCitationInOtherFormats(
+    datasetId: number,
+    datasetVersionId: string,
+    format: CitationFormats,
+    includeDeaccessioned?: boolean
+  ): Promise<CitationResponse>
 }

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 { CitationResponse } from '../models/CitationResponse'
+import { CitationFormats } from '../models/CitationFormats'
+
+export class GetDatasetCitationInOtherFormats implements UseCase<CitationResponse> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns the dataset citation in the specified format.
+   *
+   * @param {number} 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 {CitationFormats} 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<CitationResponse>} The citation content, format, and content type.
+   */
+  async execute(
+    datasetId: number,
+    datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST,
+    format: CitationFormats,
+    includeDeaccessioned = false
+  ): Promise<CitationResponse> {
+    return await this.datasetsRepository.getDatasetCitationInOtherFormats(
+      datasetId,
+      datasetVersionId,
+      format,
+      includeDeaccessioned
+    )
+  }
+}

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -21,7 +21,9 @@ import { transformDatasetVersionDiffResponseToDatasetVersionDiff } from './trans
 import { DatasetDownloadCount } from '../../domain/models/DatasetDownloadCount'
 import { DatasetVersionSummaryInfo } from '../../domain/models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../../domain/models/DatasetLinkedCollection'
+import { CitationFormats } from '../../domain/models/CitationFormats'
 import { transformDatasetLinkedCollectionsResponseToDatasetLinkedCollection } from './transformers/datasetLinkedCollectionsTransformers'
+import { CitationResponse } from '../../domain/models/CitationResponse'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -95,6 +97,34 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
       })
   }
 
+  public async getDatasetCitationInOtherFormats(
+    datasetId: number,
+    datasetVersionId: string | 'LATEST' = 'LATEST',
+    format: CitationFormats,
+    includeDeaccessioned = false
+  ): Promise<CitationResponse> {
+    const endpoint = this.buildApiEndpoint(
+      this.datasetsResourceName,
+      `versions/${datasetVersionId}/citation/${format}`,
+      datasetId
+    )
+
+    const queryParams = { includeDeaccessioned }
+
+    try {
+      const response = await this.doGet(endpoint, true, queryParams)
+
+      return {
+        content: response.data,
+        format,
+        contentType: response.headers['content-type'] ?? 'text/plain'
+      }
+    } catch (error) {
+      console.error(`[DatasetsRepository] Error fetching citation:`, error)
+      throw error
+    }
+  }
+
   public async getPrivateUrlDatasetCitation(token: string): Promise<string> {
     return this.doGet(
       this.buildApiEndpoint(this.datasetsResourceName, `privateUrlDatasetVersion/${token}/citation`)

test/integration/datasets/DatasetsRepository.test.ts

@@ -51,6 +51,7 @@ import {
 import { FilesRepository } from '../../../src/files/infra/repositories/FilesRepository'
 import { DirectUploadClient } from '../../../src/files/infra/clients/DirectUploadClient'
 import { createTestFileUploadDestination } from '../../testHelpers/files/fileUploadDestinationHelper'
+import { CitationFormats } from '../../../src/datasets/domain/models/CitationFormats'
 
 const TEST_DIFF_DATASET_DTO: DatasetDTO = {
   license: {
@@ -492,6 +493,108 @@ describe('DatasetsRepository', () => {
     })
   })
 
+  describe('getDatasetCitationInOtherFormats', () => {
+    let testDatasetIds: CreatedDatasetIdentifiers
+
+    beforeAll(async () => {
+      testDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+    })
+
+    afterAll(async () => {
+      await deletePublishedDatasetViaApi(testDatasetIds.persistentId)
+    })
+
+    test('should return citation in BibTeX format', async () => {
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.BibTeX
+      )
+
+      expect(typeof citation.content).toBe('string')
+      expect(citation.format).toBe(CitationFormats.BibTeX)
+      expect(citation.contentType).toMatch(/text\/plain/)
+    })
+
+    test('should return citation in RIS format', async () => {
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.RIS
+      )
+
+      expect(typeof citation.content).toBe('string')
+      expect(citation.format).toBe(CitationFormats.RIS)
+      expect(citation.contentType).toMatch(/text\/plain/)
+    })
+
+    test('should return citation in CSLJson format', async () => {
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.CSLJson
+      )
+
+      expect(typeof citation.content).toBe('object')
+      expect(citation.format).toBe(CitationFormats.CSLJson)
+      expect(citation.contentType).toMatch(/application\/json/)
+    })
+
+    test('should return citation in EndNote format', async () => {
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.EndNote
+      )
+
+      expect(typeof citation.content).toBe('string')
+      expect(citation.format).toBe(CitationFormats.EndNote)
+      expect(citation.contentType).toMatch('text/xml;charset=UTF-8')
+    })
+
+    test('should return citation in Internal format', async () => {
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.Internal
+      )
+
+      expect(typeof citation.content).toBe('string')
+      expect(citation.format).toBe(CitationFormats.Internal)
+      expect(citation.contentType).toMatch(/text\/html/)
+    })
+
+    test('should return error when dataset does not exist', async () => {
+      const nonExistentId = 9999999
+      const expectedError = new ReadError(`[404] Dataset with ID ${nonExistentId} not found.`)
+
+      await expect(
+        sut.getDatasetCitationInOtherFormats(
+          nonExistentId,
+          DatasetNotNumberedVersion.LATEST,
+          CitationFormats.RIS
+        )
+      ).rejects.toThrow(expectedError)
+    })
+
+    test('should return citation for deaccessioned dataset when includeDeaccessioned = true', async () => {
+      await publishDatasetViaApi(testDatasetIds.numericId)
+      await waitForNoLocks(testDatasetIds.numericId, 10)
+      await deaccessionDatasetViaApi(testDatasetIds.numericId, '1.0')
+
+      const citation = await sut.getDatasetCitationInOtherFormats(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        CitationFormats.RIS,
+        true
+      )
+
+      expect(typeof citation.content).toBe('string')
+      expect(citation.format).toBe(CitationFormats.RIS)
+      expect(citation.contentType).toMatch(/text\/plain/)
+    })
+  })
+
   describe('getDatasetVersionDiff', () => {
     let testDatasetIds: CreatedDatasetIdentifiers
 

test/unit/datasets/GetDatasetCitationInOtherFormats.test.ts

@@ -0,0 +1,39 @@
+import { GetDatasetCitationInOtherFormats } from '../../../src/datasets/domain/useCases/GetDatasetCitationInOtherFormats'
+import { IDatasetsRepository } from '../../../src/datasets/domain/repositories/IDatasetsRepository'
+import { ReadError } from '../../../src/core/domain/repositories/ReadError'
+import { CitationFormats } from '../../../src/datasets/domain/models/CitationFormats'
+import { DatasetNotNumberedVersion } from '../../../src/datasets/domain/models/DatasetNotNumberedVersion'
+import { CitationResponse } from '../../../src/datasets/domain/models/CitationResponse'
+
+describe('GetDatasetCitationInOtherFormats.execute', () => {
+  const testDatasetId = 1
+  const testFormat: CitationFormats = CitationFormats.BibTeX
+  const testVersion: DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST
+
+  test('should return citation response on repository success', async () => {
+    const expectedCitation: CitationResponse = {
+      content: '@data{example, ...}',
+      format: CitationFormats.BibTeX,
+      contentType: 'text/plain'
+    }
+
+    const datasetsRepositoryStub: IDatasetsRepository = {
+      getDatasetCitationInOtherFormats: jest.fn().mockResolvedValue(expectedCitation)
+    } as unknown as IDatasetsRepository
+
+    const sut = new GetDatasetCitationInOtherFormats(datasetsRepositoryStub)
+
+    const actual = await sut.execute(testDatasetId, testVersion, testFormat as CitationFormats)
+    expect(actual).toEqual(expectedCitation)
+  })
+
+  test('should throw ReadError on repository failure', async () => {
+    const datasetsRepositoryStub: IDatasetsRepository = {
+      getDatasetCitationInOtherFormats: jest.fn().mockRejectedValue(new ReadError())
+    } as unknown as IDatasetsRepository
+
+    const sut = new GetDatasetCitationInOtherFormats(datasetsRepositoryStub)
+
+    await expect(sut.execute(testDatasetId, testVersion, testFormat)).rejects.toThrow(ReadError)
+  })
+})