feat: feat: add use case to edit terms of access

Author: ChengShi-1

docs/useCases.md

@@ -1012,6 +1012,38 @@ The `versionUpdateType` parameter can be a [VersionUpdateType](../src/datasets/d
 - `VersionUpdateType.MAJOR`
 - `VersionUpdateType.UPDATE_CURRENT`
 
+#### Update Terms of Access
+
+Updates the Terms of Access for restricted files on a dataset.
+
+##### Example call:
+
+```typescript
+import { updateTermsOfAccess } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 3
+
+await updateTermsOfAccess.execute(datasetId, {
+  fileAccessRequest: true,
+  termsOfAccessForRestrictedFiles: 'Your terms of access for restricted files',
+  dataAccessPlace: 'Your data access place',
+  originalArchive: 'Your original archive',
+  availabilityStatus: 'Your availability status',
+  contactForAccess: 'Your contact for access',
+  sizeOfCollection: 'Your size of collection',
+  studyCompletion: 'Your study completion'
+})
+```
+
+_See [use case](../src/datasets/domain/useCases/UpdateTermsOfAccess.ts) implementation_.
+
+Notes:
+
+- If the dataset is already published, this action creates a DRAFT version containing the new terms.
+- Unspecified fields are treated as omissions: sending only `fileAccessRequest` will update that field and leave all other terms absent (undefined). In practice, the new values you send fully replace the previous set of terms — so if you omit a field, you are effectively clearing it unless you include its original value in the new input.
+
 #### Deaccession a Dataset
 
 Deaccession a Dataset, given its identifier, version, and deaccessionDatasetDTO to perform.

src/datasets/domain/models/Dataset.ts

@@ -51,6 +51,7 @@ export interface CustomTerms {
   conditions?: string
   disclaimer?: string
 }
+
 export interface TermsOfAccess {
   fileAccessRequest: boolean
   termsOfAccessForRestrictedFiles?: string

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -14,6 +14,7 @@ import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
 import { DatasetTemplate } from '../models/DatasetTemplate'
 import { DatasetType } from '../models/DatasetType'
+import { TermsOfAccess } from '../models/Dataset'
 
 export interface IDatasetsRepository {
   getDataset(
@@ -90,4 +91,5 @@ export interface IDatasetsRepository {
     licenses: string[]
   ): Promise<void>
   deleteDatasetType(datasetTypeId: number): Promise<void>
+  updateTermsOfAccess(datasetId: number | string, termsOfAccess: TermsOfAccess): Promise<void>
 }

src/datasets/domain/useCases/SetAvailableLicensesForDatasetType.ts

@@ -10,6 +10,10 @@ export class SetAvailableLicensesForDatasetType implements UseCase<void> {
 
   /**
    * Sets the available licenses for a given dataset type. This limits the license options when creating a dataset of this type.
+   *
+   * @param {number | string} [datasetTypeId] - The dataset type identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @param {string[]} licenses - The licenses to set for the dataset type.
+   * @returns {Promise<void>} - This method does not return anything upon successful completion.
    */
   async execute(datasetTypeId: number | string, licenses: string[]): Promise<void> {
     return await this.datasetsRepository.setAvailableLicensesForDatasetType(datasetTypeId, licenses)

src/datasets/domain/useCases/UpdateTermsOfAccess.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
+import { TermsOfAccess } from '../models/Dataset'
+
+export class UpdateTermsOfAccess implements UseCase<void> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Sets the terms of access for a given dataset.
+   *
+   * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @param {TermsOfAccess} termsOfAccess - The terms of access to set for the dataset.
+   * @returns {Promise<void>} - This method does not return anything upon successful completion.
+   */
+  async execute(datasetId: number | string, termsOfAccess: TermsOfAccess): Promise<void> {
+    return await this.datasetsRepository.updateTermsOfAccess(datasetId, termsOfAccess)
+  }
+}

src/datasets/index.ts

@@ -32,6 +32,7 @@ import { SetAvailableLicensesForDatasetType } from './domain/useCases/SetAvailab
 import { DeleteDatasetType } from './domain/useCases/DeleteDatasetType'
 import { GetDatasetCitationInOtherFormats } from './domain/useCases/GetDatasetCitationInOtherFormats'
 import { GetDatasetTemplates } from './domain/useCases/GetDatasetTemplates'
+import { UpdateTermsOfAccess } from './domain/useCases/UpdateTermsOfAccess'
 
 const datasetsRepository = new DatasetsRepository()
 
@@ -80,6 +81,7 @@ const setAvailableLicensesForDatasetType = new SetAvailableLicensesForDatasetTyp
 const deleteDatasetType = new DeleteDatasetType(datasetsRepository)
 const getDatasetCitationInOtherFormats = new GetDatasetCitationInOtherFormats(datasetsRepository)
 const getDatasetTemplates = new GetDatasetTemplates(datasetsRepository)
+const updateTermsOfAccess = new UpdateTermsOfAccess(datasetsRepository)
 
 export {
   getDataset,
@@ -104,6 +106,7 @@ export {
   getDatasetAvailableCategories,
   getDatasetCitationInOtherFormats,
   getDatasetTemplates,
+  updateTermsOfAccess,
   getDatasetAvailableDatasetTypes,
   getDatasetAvailableDatasetType,
   addDatasetType,

src/datasets/infra/repositories/DatasetsRepository.ts

@@ -29,6 +29,8 @@ import { DatasetTemplate } from '../../domain/models/DatasetTemplate'
 import { DatasetTemplatePayload } from './transformers/DatasetTemplatePayload'
 import { transformDatasetTemplatePayloadToDatasetTemplate } from './transformers/datasetTemplateTransformers'
 import { DatasetType } from '../../domain/models/DatasetType'
+import { TermsOfAccess } from '../../domain/models/Dataset'
+import { transformTermsOfAccessToUpdatePayload } from './transformers/termsOfAccessTransformers'
 
 export interface GetAllDatasetPreviewsQueryParams {
   per_page?: number
@@ -451,4 +453,20 @@ export class DatasetsRepository extends ApiRepository implements IDatasetsReposi
         throw error
       })
   }
+
+  public async updateTermsOfAccess(
+    datasetId: number | string,
+    termsOfAccess: TermsOfAccess
+  ): Promise<void> {
+    return this.doPut(
+      this.buildApiEndpoint(this.datasetsResourceName, 'access', datasetId),
+      transformTermsOfAccessToUpdatePayload(
+        termsOfAccess as TermsOfAccess & { termsOfAccess?: string }
+      )
+    )
+      .then(() => undefined)
+      .catch((error) => {
+        throw error
+      })
+  }
 }

src/datasets/infra/repositories/transformers/termsOfAccessTransformers.ts

@@ -0,0 +1,31 @@
+import { TermsOfAccess } from '../../../domain/models/Dataset'
+
+type TermsOfAccessInput = TermsOfAccess & { termsOfAccess?: string }
+
+export const transformTermsOfAccessToUpdatePayload = (terms: TermsOfAccessInput) => {
+  const {
+    fileAccessRequest,
+    dataAccessPlace,
+    originalArchive,
+    availabilityStatus,
+    contactForAccess,
+    sizeOfCollection,
+    studyCompletion
+  } = terms
+
+  const termsOfAccessForRestrictedFiles =
+    terms.termsOfAccess ?? terms.termsOfAccessForRestrictedFiles
+
+  return {
+    customTermsOfAccess: {
+      fileAccessRequest,
+      termsOfAccess: termsOfAccessForRestrictedFiles,
+      dataAccessPlace,
+      originalArchive,
+      availabilityStatus,
+      contactForAccess,
+      sizeOfCollection,
+      studyCompletion
+    }
+  }
+}

test/functional/datasets/UpdateTermsOfAccess.test.ts

@@ -0,0 +1,51 @@
+import { TestConstants } from '../../testHelpers/TestConstants'
+import {
+  ApiConfig,
+  DataverseApiAuthMechanism
+} from '../../../src/core/infra/repositories/ApiConfig'
+import {
+  createDataset,
+  DatasetNotNumberedVersion,
+  getDataset,
+  updateTermsOfAccess
+} from '../../../src/datasets'
+import { WriteError } from '../../../src'
+
+describe('UpdateTermsOfAccess (functional)', () => {
+  beforeAll(() => {
+    ApiConfig.init(
+      TestConstants.TEST_API_URL,
+      DataverseApiAuthMechanism.API_KEY,
+      process.env.TEST_API_KEY
+    )
+  })
+
+  test('should update terms of access with provided fields', async () => {
+    const ids = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+
+    await updateTermsOfAccess.execute(ids.numericId, {
+      fileAccessRequest: true,
+      termsOfAccessForRestrictedFiles: 'Your terms',
+      dataAccessPlace: 'Place'
+    })
+
+    const dataset = await getDataset.execute(
+      ids.numericId,
+      DatasetNotNumberedVersion.LATEST,
+      false,
+      false
+    )
+
+    expect(dataset.termsOfUse.termsOfAccess.fileAccessRequest).toBe(true)
+    expect(dataset.termsOfUse.termsOfAccess.termsOfAccessForRestrictedFiles).toBe('Your terms')
+    expect(dataset.termsOfUse.termsOfAccess.dataAccessPlace).toBe('Place')
+  })
+
+  test('should throw when dataset does not exist', async () => {
+    await expect(
+      updateTermsOfAccess.execute(999999, {
+        fileAccessRequest: false
+      })
+    ).rejects.toBeInstanceOf(WriteError)
+  })
+})

test/integration/datasets/DatasetsRepository.test.ts

@@ -27,7 +27,8 @@ import {
   addDatasetType,
   deleteDatasetType,
   linkDatasetTypeWithMetadataBlocks,
-  setAvailableLicensesForDatasetType
+  setAvailableLicensesForDatasetType,
+  updateTermsOfAccess
 } from '../../../src/datasets'
 import { ApiConfig, WriteError } from '../../../src'
 import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig'
@@ -36,7 +37,8 @@ import {
   Author,
   DatasetContact,
   DatasetDescription,
-  Publication
+  Publication,
+  TermsOfAccess
 } from '../../../src/datasets/domain/models/Dataset'
 import {
   createCollectionViaApi,
@@ -1850,4 +1852,143 @@ describe('DatasetsRepository', () => {
       })
     })
   })
+
+  describe('updateTermsOfAccess', () => {
+    let testDatasetIds: CreatedDatasetIdentifiers
+
+    console.log(
+      'authentication',
+      TestConstants.TEST_API_URL,
+      DataverseApiAuthMechanism.API_KEY,
+      process.env.TEST_API_KEY
+    )
+    beforeAll(async () => {
+      testDatasetIds = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+    })
+
+    test('should update the terms of access for a dataset', async () => {
+      const datasetBefore = await sut.getDataset(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        false,
+        false
+      )
+
+      const termsOfAccessBefore: TermsOfAccess = {
+        fileAccessRequest: true,
+        termsOfAccessForRestrictedFiles: undefined,
+        dataAccessPlace: undefined,
+        originalArchive: undefined,
+        availabilityStatus: undefined,
+        contactForAccess: undefined,
+        sizeOfCollection: undefined,
+        studyCompletion: undefined
+      }
+      expect(datasetBefore.termsOfUse.termsOfAccess).toEqual(termsOfAccessBefore)
+
+      const termsOfAccessAfter: TermsOfAccess = {
+        fileAccessRequest: false,
+        termsOfAccessForRestrictedFiles: 'Your terms of access for restricted files',
+        dataAccessPlace: 'Your data access place',
+        originalArchive: 'Your original archive',
+        availabilityStatus: 'Your availability status',
+        contactForAccess: 'Your contact for access',
+        sizeOfCollection: 'Your size of collection',
+        studyCompletion: 'Your study completion'
+      }
+
+      await updateTermsOfAccess.execute(testDatasetIds.numericId, termsOfAccessAfter)
+
+      const datasetAfter = await sut.getDataset(
+        testDatasetIds.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        false,
+        false
+      )
+
+      expect(datasetAfter.termsOfUse.termsOfAccess).toEqual(termsOfAccessAfter)
+    })
+
+    test('should throw error when dataset does not exist', async () => {
+      const nonExistentId = 999999
+      await expect(
+        updateTermsOfAccess.execute(nonExistentId, {
+          fileAccessRequest: true
+        })
+      ).rejects.toBeInstanceOf(WriteError)
+    })
+
+    test('should accept only fileAccessRequest field', async () => {
+      const ids = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+
+      await updateTermsOfAccess.execute(ids.numericId, {
+        fileAccessRequest: false
+      })
+
+      const dataset = await sut.getDataset(
+        ids.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        false,
+        false
+      )
+
+      expect(dataset.termsOfUse.termsOfAccess.fileAccessRequest).toBe(false)
+      expect(dataset.termsOfUse.termsOfAccess.dataAccessPlace).toBeUndefined()
+      expect(dataset.termsOfUse.termsOfAccess.originalArchive).toBeUndefined()
+      expect(dataset.termsOfUse.termsOfAccess.availabilityStatus).toBeUndefined()
+      expect(dataset.termsOfUse.termsOfAccess.contactForAccess).toBeUndefined()
+      expect(dataset.termsOfUse.termsOfAccess.sizeOfCollection).toBeUndefined()
+      expect(dataset.termsOfUse.termsOfAccess.studyCompletion).toBeUndefined()
+    })
+
+    test('should work when identifying dataset by persistent id', async () => {
+      const ids = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+
+      await updateTermsOfAccess.execute(ids.persistentId, {
+        termsOfAccessForRestrictedFiles: 'Persistent terms',
+        fileAccessRequest: false
+      })
+
+      const dataset = await sut.getDataset(
+        ids.persistentId,
+        DatasetNotNumberedVersion.LATEST,
+        false,
+        false
+      )
+
+      expect(dataset.persistentId).toBe(ids.persistentId)
+      expect(dataset.termsOfUse.termsOfAccess.fileAccessRequest).toBe(false)
+      expect(dataset.termsOfUse.termsOfAccess.termsOfAccessForRestrictedFiles).toBe(
+        'Persistent terms'
+      )
+    })
+
+    test('should update terms on a published dataset (creates a draft)', async () => {
+      const ids = await createDataset.execute(TestConstants.TEST_NEW_DATASET_DTO)
+
+      await publishDataset.execute(ids.numericId, VersionUpdateType.MAJOR)
+      await waitForNoLocks(ids.numericId, 10)
+
+      await updateTermsOfAccess.execute(ids.numericId, {
+        fileAccessRequest: true,
+        termsOfAccessForRestrictedFiles: 'Updated after publish'
+      })
+
+      await waitForNoLocks(ids.numericId, 10)
+
+      const dataset = await sut.getDataset(
+        ids.numericId,
+        DatasetNotNumberedVersion.LATEST,
+        false,
+        false
+      )
+
+      expect(dataset.versionInfo.state).toBe('DRAFT')
+      expect(dataset.termsOfUse.termsOfAccess.termsOfAccessForRestrictedFiles).toBe(
+        'Updated after publish'
+      )
+
+      await deletePublishedDatasetViaApi(ids.persistentId)
+    })
+  })
 })