feat: update restrict extension

Author: ChengShi-1

docs/useCases.md

@@ -1376,7 +1376,7 @@ 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.
+Restrict or unrestrict an existing file, given a [RestrictFileDTO](../src/users/domain/dtos/RestrictFileDTO.ts)
 
 ##### Example call:
 
@@ -1386,15 +1386,23 @@ import { restrictFile } from '@iqss/dataverse-client-javascript'
 /* ... */
 
 const fileId = 12345
+const restrictFileDTO = {
+  restrict: true,
+  enableAccessRequest: boolean,
+  termsOfAccess: string
+}
 
-restrictFile.execute(fileId, true)
+restrictFile.execute(fileId, restrictFileDTO)
 
 /* ... */
 ```
 
 _See [use case](../src/files/domain/useCases/RestrictFile.ts) implementation_.
 
 The `fileId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+If restrict is false then enableAccessRequest and termsOfAccess are ignored
+If restrict is true and enableAccessRequest is false then termsOfAccess is required.
+The enableAccessRequest and termsOfAccess are applied to the Draft version of the Dataset and affect all of the restricted files in said Draft version.
 
 ## Metadata Blocks
 

src/files/domain/dtos/RestrictFileDTO.ts

@@ -0,0 +1,5 @@
+export interface RestrictFileDTO {
+  restrict: boolean
+  enableAccessRequest?: boolean
+  termsOfAccess?: string
+}

src/files/domain/repositories/IFilesRepository.ts

@@ -9,6 +9,7 @@ import { Dataset } from '../../../datasets'
 import { FileUploadDestination } from '../models/FileUploadDestination'
 import { UploadedFileDTO } from '../dtos/UploadedFileDTO'
 import { UpdateFileMetadataDTO } from '../dtos/UpdateFileMetadataDTO'
+import { RestrictFileDTO } from '../dtos/RestrictFileDTO'
 
 export interface IFilesRepository {
   getDatasetFiles(
@@ -65,7 +66,8 @@ export interface IFilesRepository {
 
   replaceFile(fileId: number | string, uploadedFileDTO: UploadedFileDTO): Promise<number>
 
-  restrictFile(fileId: number | string, restrict: boolean): Promise<undefined>
+  restrictFile(fileId: number | string, restrictFileDTO: RestrictFileDTO): Promise<string>
+
   updateFileMetadata(
     fileId: number | string,
     updateFileMetadataDTO: UpdateFileMetadataDTO

src/files/domain/useCases/RestrictFile.ts

@@ -1,18 +1,20 @@
 import { IFilesRepository } from '../repositories/IFilesRepository'
 import { UseCase } from '../../../core/domain/useCases/UseCase'
-
-export class RestrictFile implements UseCase<void> {
+import { RestrictFileDTO } from '../dtos/RestrictFileDTO'
+// https://github.com/IQSS/dataverse/pull/11349/files
+export class RestrictFile implements UseCase<string> {
   constructor(private readonly filesRepository: IFilesRepository) {}
 
   /**
    * Restrict or unrestrict an existing file.
    * More detailed information about the file restriction behavior can be found in https://guides.dataverse.org/en/latest/api/native-api.html#restrict-files
    *
    * @param {number | string} [fileId] - The File identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
-   * @param {boolean} [restrict] - A boolean value that indicates whether the file should be restricted or unrestricted.
+   * @param {RestrictFileDTO} [restrictFileDTO] - The DTO containing the file restriction information.
    * @returns {Promise<void>} -This method does not return anything upon successful completion.
    */
-  async execute(fileId: number | string, restrict: boolean): Promise<void> {
-    return await this.filesRepository.restrictFile(fileId, restrict)
+
+  async execute(fileId: number | string, restrictFileDTO: RestrictFileDTO): Promise<string> {
+    return await this.filesRepository.restrictFile(fileId, restrictFileDTO)
   }
 }

src/files/infra/repositories/FilesRepository.ts

@@ -21,6 +21,7 @@ import { transformUploadDestinationsResponseToUploadDestination } from './transf
 import { UploadedFileDTO } from '../../domain/dtos/UploadedFileDTO'
 import { UpdateFileMetadataDTO } from '../../domain/dtos/UpdateFileMetadataDTO'
 import { ApiConstants } from '../../../core/infra/repositories/ApiConstants'
+import { RestrictFileDTO } from '../../domain/dtos/RestrictFileDTO'
 
 export interface GetFilesQueryParams {
   includeDeaccessioned: boolean
@@ -346,9 +347,18 @@ export class FilesRepository extends ApiRepository implements IFilesRepository {
       })
   }
 
-  public async restrictFile(fileId: number | string, restrict: boolean): Promise<undefined> {
-    return this.doPut(this.buildApiEndpoint(this.filesResourceName, 'restrict', fileId), restrict)
-      .then(() => undefined)
+  public async restrictFile(
+    fileId: number | string,
+    restrictFileDTO: RestrictFileDTO
+  ): Promise<string> {
+    return this.doPut(
+      this.buildApiEndpoint(this.filesResourceName, 'restrict', fileId),
+      restrictFileDTO
+    )
+      .then((response) => {
+        console.log('test', response.data.data.message)
+        return response.data.data.message
+      })
       .catch((error) => {
         throw error
       })

test/functional/files/RestrictFile.test.ts

@@ -58,32 +58,36 @@ describe('execute', () => {
     try {
       const datasetFiles = await getDatasetFiles.execute(testDatasetIds.numericId)
 
-      await restrictFile.execute(datasetFiles.files[0].id, true)
+      await restrictFile.execute(datasetFiles.files[0].id, { restrict: true })
     } catch (error) {
-      throw new Error('File should be deleted')
+      throw new Error('File should be restricted')
     } finally {
       const datasetFilesAfterRestriction = await getDatasetFiles.execute(testDatasetIds.numericId)
-
       expect(datasetFilesAfterRestriction.files[0].restricted).toEqual(true)
-
       // Unrestrict the file for the next test
-      await restrictFile.execute(datasetFilesAfterRestriction.files[0].id, false)
+      await restrictFile.execute(datasetFilesAfterRestriction.files[0].id, { restrict: false })
     }
   })
 
   test('should succesfully unrestrict a file', async () => {
     try {
       const datasetFiles = await getDatasetFiles.execute(testDatasetIds.numericId)
-
-      await restrictFile.execute(datasetFiles.files[0].id, true)
-
-      await restrictFile.execute(datasetFiles.files[0].id, false)
+      await restrictFile.execute(datasetFiles.files[0].id, { restrict: true })
     } catch (error) {
-      throw new Error('File should be deleted')
+      throw new Error('File should be restricted')
     } finally {
       const datasetFilesAfterRestriction = await getDatasetFiles.execute(testDatasetIds.numericId)
+      expect(datasetFilesAfterRestriction.files[0].restricted).toEqual(true)
+    }
 
-      expect(datasetFilesAfterRestriction.files[0].restricted).toEqual(false)
+    try {
+      const datasetFilesAfterRestriction = await getDatasetFiles.execute(testDatasetIds.numericId)
+      await restrictFile.execute(datasetFilesAfterRestriction.files[0].id, { restrict: false })
+    } catch (error) {
+      throw new Error('File should be unrestricted')
+    } finally {
+      const datasetFilesAfterUnrestriction = await getDatasetFiles.execute(testDatasetIds.numericId)
+      expect(datasetFilesAfterUnrestriction.files[0].restricted).toEqual(false)
     }
   })
 
@@ -93,7 +97,7 @@ describe('execute', () => {
     const nonExistentFileId = 5
 
     try {
-      await restrictFile.execute(nonExistentFileId, true)
+      await restrictFile.execute(nonExistentFileId, { restrict: true })
       throw new Error('Use case should throw an error')
     } catch (error) {
       writeError = error as WriteError
@@ -105,4 +109,22 @@ describe('execute', () => {
       )
     }
   })
+
+  test('should throw an error when the terms of use is empty while enableAccess is false', async () => {
+    let caughtError: unknown
+    try {
+      const datasetFiles = await getDatasetFiles.execute(testDatasetIds.numericId)
+      await restrictFile.execute(datasetFiles.files[0].id, {
+        restrict: true,
+        enableAccessRequest: false
+      })
+    } catch (error) {
+      caughtError = error
+    }
+
+    expect(caughtError).toBeInstanceOf(WriteError)
+    expect((caughtError as WriteError).message).toEqual(
+      'There was an error when writing the resource. Reason was: [409] Terms of Use and Access are invalid. You must enable request access or add terms of access in datasets with restricted files.'
+    )
+  })
 })

test/integration/files/FilesRepository.test.ts

@@ -41,6 +41,7 @@ import {
   deleteCollectionViaApi,
   setStorageDriverViaApi
 } from '../../testHelpers/collections/collectionHelper'
+import { RestrictFileDTO } from '../../../src/files/domain/dtos/RestrictFileDTO'
 
 describe('FilesRepository', () => {
   const sut: FilesRepository = new FilesRepository()
@@ -766,13 +767,23 @@ describe('FilesRepository', () => {
   describe('restrictFile', () => {
     let restrictFileDatasetIds: CreatedDatasetIdentifiers
     const testTextFile1Name = 'test-file-1.txt'
+    const restrictFileDTO: RestrictFileDTO = {
+      restrict: true,
+      enableAccessRequest: true,
+      termsOfAccess: 'This file is restricted for testing purposes'
+    }
+
+    const unrestrictFileDTO: RestrictFileDTO = {
+      restrict: false,
+      termsOfAccess: 'This file is restricted for testing purposes'
+    }
 
     const setFileToRestricted = async (fileId: number) => {
-      await sut.restrictFile(fileId, true)
+      await sut.restrictFile(fileId, restrictFileDTO)
     }
 
     const setFileToUnrestricted = async (fileId: number) => {
-      await sut.restrictFile(fileId, false)
+      await sut.restrictFile(fileId, unrestrictFileDTO)
     }
 
     beforeEach(async () => {

test/unit/files/RestrictFile.test.ts

@@ -1,15 +1,22 @@
 import { WriteError } from '../../../src'
+import { RestrictFileDTO } from '../../../src/files/domain/dtos/RestrictFileDTO'
 import { IFilesRepository } from '../../../src/files/domain/repositories/IFilesRepository'
 import { RestrictFile } from '../../../src/files/domain/useCases/RestrictFile'
 
 describe('execute', () => {
+  const restrictFileDTO: RestrictFileDTO = {
+    restrict: true,
+    enableAccessRequest: true,
+    termsOfAccess: 'This file is restricted for testing purposes'
+  }
+
   test('should return undefined when repository call is successful', async () => {
     const filesRepositoryStub: IFilesRepository = {} as IFilesRepository
     filesRepositoryStub.restrictFile = jest.fn().mockResolvedValue(undefined)
 
     const sut = new RestrictFile(filesRepositoryStub)
 
-    const actual = await sut.execute(1, true)
+    const actual = await sut.execute(1, restrictFileDTO)
 
     expect(actual).toEqual(undefined)
   })
@@ -20,6 +27,6 @@ describe('execute', () => {
 
     const sut = new RestrictFile(filesRepositoryStub)
 
-    await expect(sut.execute(1, true)).rejects.toThrow(WriteError)
+    await expect(sut.execute(1, restrictFileDTO)).rejects.toThrow(WriteError)
   })
 })