feat: update use cases of guestbook and access

Author: ChengShi-1

CHANGELOG.md

@@ -17,6 +17,8 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - New Use Case: [Delete a Template](./docs/useCases.md#delete-a-template) under Templates.
 - New Use Case: [Update Terms of Access](./docs/useCases.md#update-terms-of-access).
 - Guestbooks: Added use cases and repository support for guestbook creation, listing, and enabling/disabling.
+- Guestbooks: Added dataset-level guestbook assignment and removal support via `assignDatasetGuestbook` (`PUT /api/datasets/{identifier}/guestbook`) and `removeDatasetGuestbook` (`DELETE /api/datasets/{identifier}/guestbook`).
+- Access: Added signed-URL GET use cases for `access/datafile`, `access/datafiles`, `access/dataset`, and `access/dataset/{id}/versions/{versionId}` endpoints using `?signed=true` (authenticated users only).
 - Access: Added a dedicated `access` module for guestbook-at-request and download terms/guestbook submission endpoints.
 
 ### Changed

docs/useCases.md

@@ -130,7 +130,14 @@ The different use cases currently available in the package are classified below,
   - [Guestbooks write use cases](#guestbooks-write-use-cases)
     - [Create a Guestbook](#create-a-guestbook)
     - [Set Guestbook Enabled](#set-guestbook-enabled)
+    - [Assign Dataset Guestbook](#assign-dataset-guestbook)
+    - [Remove Dataset Guestbook](#remove-dataset-guestbook)
 - [Access](#Access)
+  - [Access read use cases](#access-read-use-cases)
+    - [Get Signed Datafile Download URL](#get-signed-datafile-download-url)
+    - [Get Signed Datafiles Download URL](#get-signed-datafiles-download-url)
+    - [Get Signed Dataset Download URL](#get-signed-dataset-download-url)
+    - [Get Signed Dataset Version Download URL](#get-signed-dataset-version-download-url)
   - [Access write use cases](#access-write-use-cases)
     - [Submit Guestbook For Datafile Download](#submit-guestbook-for-datafile-download)
     - [Submit Guestbook For Datafiles Download](#submit-guestbook-for-datafiles-download)
@@ -2840,6 +2847,9 @@ const guestbook: CreateGuestbookDTO = {
   nameRequired: true,
   institutionRequired: false,
   positionRequired: false,
+  email: 'test@gmail.com',
+  institution: 'Harvard University',
+  position: 'Researcher',
   customQuestions: [
     {
       question: 'Describe yourself',
@@ -2877,8 +2887,113 @@ setGuestbookEnabled.execute(collectionIdOrAlias, guestbookId, false).then(() =>
 
 _See [use case](../src/guestbooks/domain/useCases/SetGuestbookEnabled.ts) implementation_.
 
+#### Assign Dataset Guestbook
+
+Assigns a guestbook to a dataset using `PUT /api/datasets/{identifier}/guestbook`.
+
+##### Example call:
+
+```typescript
+import { assignDatasetGuestbook } from '@iqss/dataverse-client-javascript'
+
+const datasetIdOrPersistentId = 123
+const guestbookId = 456
+
+assignDatasetGuestbook.execute(datasetIdOrPersistentId, guestbookId).then(() => {
+  /* ... */
+})
+```
+
+_See [use case](../src/guestbooks/domain/useCases/AssignDatasetGuestbook.ts) implementation_.
+
+#### Remove Dataset Guestbook
+
+Removes the guestbook assignment for a dataset using `DELETE /api/datasets/{identifier}/guestbook`.
+
+##### Example call:
+
+```typescript
+import { removeDatasetGuestbook } from '@iqss/dataverse-client-javascript'
+
+const datasetIdOrPersistentId = 123
+
+removeDatasetGuestbook.execute(datasetIdOrPersistentId).then(() => {
+  /* ... */
+})
+```
+
+_See [use case](../src/guestbooks/domain/useCases/RemoveDatasetGuestbook.ts) implementation_.
+
 ## Access
 
+### Access Read Use Cases
+
+#### Get Signed Datafile Download URL
+
+Returns a signed URL for downloading a single datafile using `GET /api/access/datafile/{fileId:.+}?signed=true`.
+
+##### Example call:
+
+```typescript
+import { getSignedDatafileDownloadUrl } from '@iqss/dataverse-client-javascript'
+
+getSignedDatafileDownloadUrl.execute(10).then((signedUrl: string) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/access/domain/useCases/GetSignedDatafileDownloadUrl.ts) implementation_.
+
+#### Get Signed Datafiles Download URL
+
+Returns a signed URL for downloading multiple datafiles using `GET /api/access/datafiles/{fileIds}?signed=true`.
+
+##### Example call:
+
+```typescript
+import { getSignedDatafilesDownloadUrl } from '@iqss/dataverse-client-javascript'
+
+getSignedDatafilesDownloadUrl.execute([10, 11]).then((signedUrl: string) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/access/domain/useCases/GetSignedDatafilesDownloadUrl.ts) implementation_.
+
+#### Get Signed Dataset Download URL
+
+Returns a signed URL for downloading a dataset using `GET /api/access/dataset/{id}?signed=true`.
+
+##### Example call:
+
+```typescript
+import { getSignedDatasetDownloadUrl } from '@iqss/dataverse-client-javascript'
+
+getSignedDatasetDownloadUrl.execute(10).then((signedUrl: string) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/access/domain/useCases/GetSignedDatasetDownloadUrl.ts) implementation_.
+
+#### Get Signed Dataset Version Download URL
+
+Returns a signed URL for downloading a dataset version using `GET /api/access/dataset/{id}/versions/{versionId}?signed=true`.
+
+##### Example call:
+
+```typescript
+import { getSignedDatasetVersionDownloadUrl } from '@iqss/dataverse-client-javascript'
+
+getSignedDatasetVersionDownloadUrl.execute(10, '1.0').then((signedUrl: string) => {
+  /* ... */
+})
+```
+
+Signed URLs are only available to authenticated users. Guest users will receive an error when requesting `signed=true`.
+
+_See [use case](../src/access/domain/useCases/GetSignedDatasetVersionDownloadUrl.ts) implementation_.
+
 ### Access Write Use Cases
 
 #### Submit Guestbook For Datafile Download

src/access/domain/repositories/IAccessRepository.ts

@@ -1,6 +1,14 @@
 import { GuestbookResponseDTO } from '../dtos/GuestbookResponseDTO'
 
 export interface IAccessRepository {
+  getSignedDatafileDownloadUrl(fileId: number | string): Promise<string>
+
+  getSignedDatafilesDownloadUrl(fileIds: string | Array<number | string>): Promise<string>
+
+  getSignedDatasetDownloadUrl(datasetId: number | string): Promise<string>
+
+  getSignedDatasetVersionDownloadUrl(datasetId: number | string, versionId: string): Promise<string>
+
   submitGuestbookForDatafileDownload(
     fileId: number | string,
     guestbookResponse: GuestbookResponseDTO

src/access/domain/useCases/GetSignedDatafileDownloadUrl.ts

@@ -0,0 +1,16 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IAccessRepository } from '../repositories/IAccessRepository'
+
+export class GetSignedDatafileDownloadUrl implements UseCase<string> {
+  constructor(private readonly accessRepository: IAccessRepository) {}
+
+  /**
+   * Returns a signed URL for downloading a single datafile.
+   *
+   * @param {number | string} fileId - Datafile identifier (numeric id or persistent id).
+   * @returns {Promise<string>} - Signed URL for the download.
+   */
+  async execute(fileId: number | string): Promise<string> {
+    return await this.accessRepository.getSignedDatafileDownloadUrl(fileId)
+  }
+}

src/access/domain/useCases/GetSignedDatafilesDownloadUrl.ts

@@ -0,0 +1,16 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IAccessRepository } from '../repositories/IAccessRepository'
+
+export class GetSignedDatafilesDownloadUrl implements UseCase<string> {
+  constructor(private readonly accessRepository: IAccessRepository) {}
+
+  /**
+   * Returns a signed URL for downloading multiple datafiles.
+   *
+   * @param {string | Array<number | string>} fileIds - Comma-separated ids or array of datafile ids.
+   * @returns {Promise<string>} - Signed URL for the download.
+   */
+  async execute(fileIds: string | Array<number | string>): Promise<string> {
+    return await this.accessRepository.getSignedDatafilesDownloadUrl(fileIds)
+  }
+}

src/access/domain/useCases/GetSignedDatasetDownloadUrl.ts

@@ -0,0 +1,16 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IAccessRepository } from '../repositories/IAccessRepository'
+
+export class GetSignedDatasetDownloadUrl implements UseCase<string> {
+  constructor(private readonly accessRepository: IAccessRepository) {}
+
+  /**
+   * Returns a signed URL for downloading all files in a dataset.
+   *
+   * @param {number | string} datasetId - Dataset identifier (numeric id or persistent id).
+   * @returns {Promise<string>} - Signed URL for the download.
+   */
+  async execute(datasetId: number | string): Promise<string> {
+    return await this.accessRepository.getSignedDatasetDownloadUrl(datasetId)
+  }
+}

src/access/domain/useCases/GetSignedDatasetVersionDownloadUrl.ts

@@ -0,0 +1,17 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IAccessRepository } from '../repositories/IAccessRepository'
+
+export class GetSignedDatasetVersionDownloadUrl implements UseCase<string> {
+  constructor(private readonly accessRepository: IAccessRepository) {}
+
+  /**
+   * Returns a signed URL for downloading all files in a specific dataset version.
+   *
+   * @param {number | string} datasetId - Dataset identifier (numeric id or persistent id).
+   * @param {string} versionId - Dataset version id.
+   * @returns {Promise<string>} - Signed URL for the download.
+   */
+  async execute(datasetId: number | string, versionId: string): Promise<string> {
+    return await this.accessRepository.getSignedDatasetVersionDownloadUrl(datasetId, versionId)
+  }
+}

src/access/index.ts

@@ -1,11 +1,19 @@
 import { AccessRepository } from './infra/repositories/AccessRepository'
+import { GetSignedDatafileDownloadUrl } from './domain/useCases/GetSignedDatafileDownloadUrl'
+import { GetSignedDatafilesDownloadUrl } from './domain/useCases/GetSignedDatafilesDownloadUrl'
+import { GetSignedDatasetDownloadUrl } from './domain/useCases/GetSignedDatasetDownloadUrl'
+import { GetSignedDatasetVersionDownloadUrl } from './domain/useCases/GetSignedDatasetVersionDownloadUrl'
 import { SubmitGuestbookForDatafileDownload } from './domain/useCases/SubmitGuestbookForDatafileDownload'
 import { SubmitGuestbookForDatafilesDownload } from './domain/useCases/SubmitGuestbookForDatafilesDownload'
 import { SubmitGuestbookForDatasetDownload } from './domain/useCases/SubmitGuestbookForDatasetDownload'
 import { SubmitGuestbookForDatasetVersionDownload } from './domain/useCases/SubmitGuestbookForDatasetVersionDownload'
 
 const accessRepository = new AccessRepository()
 
+const getSignedDatafileDownloadUrl = new GetSignedDatafileDownloadUrl(accessRepository)
+const getSignedDatafilesDownloadUrl = new GetSignedDatafilesDownloadUrl(accessRepository)
+const getSignedDatasetDownloadUrl = new GetSignedDatasetDownloadUrl(accessRepository)
+const getSignedDatasetVersionDownloadUrl = new GetSignedDatasetVersionDownloadUrl(accessRepository)
 const submitGuestbookForDatafileDownload = new SubmitGuestbookForDatafileDownload(accessRepository)
 const submitGuestbookForDatafilesDownload = new SubmitGuestbookForDatafilesDownload(
   accessRepository
@@ -16,6 +24,10 @@ const submitGuestbookForDatasetVersionDownload = new SubmitGuestbookForDatasetVe
 )
 
 export {
+  getSignedDatafileDownloadUrl,
+  getSignedDatafilesDownloadUrl,
+  getSignedDatasetDownloadUrl,
+  getSignedDatasetVersionDownloadUrl,
   submitGuestbookForDatafileDownload,
   submitGuestbookForDatafilesDownload,
   submitGuestbookForDatasetDownload,

src/access/infra/repositories/AccessRepository.ts

@@ -5,6 +5,61 @@ import { IAccessRepository } from '../../domain/repositories/IAccessRepository'
 export class AccessRepository extends ApiRepository implements IAccessRepository {
   private readonly accessResourceName = 'access'
 
+  public async getSignedDatafileDownloadUrl(fileId: number | string): Promise<string> {
+    const endpoint = this.buildApiEndpoint(`${this.accessResourceName}/datafile`, undefined, fileId)
+    return this.doGet(endpoint, true, { signed: true })
+      .then((response) => response.data.data.signedUrl)
+      .catch((error) => {
+        throw error
+      })
+  }
+
+  public async getSignedDatafilesDownloadUrl(
+    fileIds: string | Array<number | string>
+  ): Promise<string> {
+    return this.doGet(
+      this.buildApiEndpoint(
+        this.accessResourceName,
+        `datafiles/${Array.isArray(fileIds) ? fileIds.join(',') : fileIds}`
+      ),
+      true,
+      { signed: true }
+    )
+      .then((response) => response.data.data.signedUrl)
+      .catch((error) => {
+        throw error
+      })
+  }
+
+  public async getSignedDatasetDownloadUrl(datasetId: number | string): Promise<string> {
+    const endpoint = this.buildApiEndpoint(
+      `${this.accessResourceName}/dataset`,
+      undefined,
+      datasetId
+    )
+    return this.doGet(endpoint, true, { signed: true })
+      .then((response) => response.data.data.signedUrl)
+      .catch((error) => {
+        throw error
+      })
+  }
+
+  public async getSignedDatasetVersionDownloadUrl(
+    datasetId: number | string,
+    versionId: string
+  ): Promise<string> {
+    const endpoint = this.buildApiEndpoint(
+      `${this.accessResourceName}/dataset`,
+      `versions/${versionId}`,
+      datasetId
+    )
+    return this.doGet(endpoint, true, { signed: true })
+      .then((response) => response.data.data.signedUrl)
+      .catch((error) => {
+        throw error
+      })
+  }
+
   public async submitGuestbookForDatafileDownload(
     fileId: number | string,
     guestbookResponse: GuestbookResponseDTO

src/guestbooks/domain/dtos/CreateGuestbookDTO.ts

@@ -21,5 +21,8 @@ export interface CreateGuestbookDTO {
   nameRequired: boolean
   institutionRequired: boolean
   positionRequired: boolean
+  email: string
+  institution: string
+  position: string
   customQuestions: CreateGuestbookCustomQuestionDTO[]
 }