Use Cases of Guestbooks

CHANGELOG.md

@@ -16,6 +16,11 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - New Use Case: [Get a Template](./docs/useCases.md#get-a-template) under Templates.
 - 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`).
+- Datasets/Guestbooks: Added `guestbookId` in `getDataset` responses.
+- 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

@@ -123,6 +123,26 @@ The different use cases currently available in the package are classified below,
     - [Get External Tools](#get-external-tools)
     - [Get Dataset External Tool Resolved](#get-dataset-external-tool-resolved)
     - [Get File External Tool Resolved](#get-file-external-tool-resolved)
+- [Guestbooks](#Guestbooks)
+  - [Guestbooks read use cases](#guestbooks-read-use-cases)
+    - [Get a Guestbook](#get-a-guestbook)
+    - [Get Guestbooks By Collection Id](#get-guestbooks-by-collection-id)
+  - [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)
+    - [Submit Guestbook For Dataset Download](#submit-guestbook-for-dataset-download)
+    - [Submit Guestbook For Dataset Version Download](#submit-guestbook-for-dataset-version-download)
 
 ## Collections
 
@@ -2767,3 +2787,312 @@ getFileExternalToolResolved
 ```
 
 _See [use case](../src/externalTools/domain/useCases/GetfileExternalToolResolved.ts) implementation_.
+
+## Guestbooks
+
+### Guestbooks Read Use Cases
+
+#### Get a Guestbook
+
+Returns a [Guestbook](../src/guestbooks/domain/models/Guestbook.ts) by its id.
+
+##### Example call:
+
+```typescript
+import { getGuestbook } from '@iqss/dataverse-client-javascript'
+
+const guestbookId = 123
+
+getGuestbook.execute(guestbookId).then((guestbook: Guestbook) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/guestbooks/domain/useCases/GetGuestbook.ts) implementation_.
+
+#### Get Guestbooks By Collection Id
+
+Returns all [Guestbook](../src/guestbooks/domain/models/Guestbook.ts) entries available for a collection.
+
+##### Example call:
+
+```typescript
+import { getGuestbooksByCollectionId } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 'root'
+
+getGuestbooksByCollectionId.execute(collectionIdOrAlias).then((guestbooks: Guestbook[]) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/guestbooks/domain/useCases/GetGuestbooksByCollectionId.ts) implementation_.
+
+### Guestbooks Write Use Cases
+
+#### Create a Guestbook
+
+Creates a guestbook on a collection using [CreateGuestbookDTO](../src/guestbooks/domain/dtos/CreateGuestbookDTO.ts).
+
+##### Example call:
+
+```typescript
+import { createGuestbook } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 'root'
+const guestbook: CreateGuestbookDTO = {
+  name: 'my test guestbook',
+  enabled: true,
+  emailRequired: true,
+  nameRequired: true,
+  institutionRequired: false,
+  positionRequired: false,
+  email: 'test@gmail.com',
+  institution: 'Harvard University',
+  position: 'Researcher',
+  customQuestions: [
+    {
+      question: 'Describe yourself',
+      required: false,
+      displayOrder: 1,
+      type: 'textarea',
+      hidden: false
+    }
+  ]
+}
+
+createGuestbook.execute(guestbook, collectionIdOrAlias).then(() => {
+  /* ... */
+})
+```
+
+_See [use case](../src/guestbooks/domain/useCases/CreateGuestbook.ts) implementation_.
+
+#### Set Guestbook Enabled
+
+Enables or disables a guestbook in a collection.
+
+##### Example call:
+
+```typescript
+import { setGuestbookEnabled } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 'root'
+const guestbookId = 123
+
+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.
+
+##### 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.
+
+##### 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.
+
+##### 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.
+
+##### Example call:
+
+```typescript
+import { getSignedDatasetVersionDownloadUrl } from '@iqss/dataverse-client-javascript'
+
+getSignedDatasetVersionDownloadUrl.execute(10, '1.0').then((signedUrl: string) => {
+  /* ... */
+})
+```
+
+_See [use case](../src/access/domain/useCases/GetSignedDatasetVersionDownloadUrl.ts) implementation_.
+
+### Access Write Use Cases
+
+#### Submit Guestbook For Datafile Download
+
+Submits guestbook answers for a datafile and returns a signed URL.
+
+##### Example call:
+
+```typescript
+import { submitGuestbookForDatafileDownload } from '@iqss/dataverse-client-javascript'
+
+submitGuestbookForDatafileDownload
+  .execute(10, {
+    guestbookResponse: {
+      answers: [
+        { id: 123, value: 'Good' },
+        { id: 124, value: ['Multi', 'Line'] }
+      ]
+    }
+  })
+  .then((signedUrl: string) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/access/domain/useCases/SubmitGuestbookForDatafileDownload.ts) implementation_.
+
+#### Submit Guestbook For Datafiles Download
+
+Submits guestbook answers for multiple files and returns a signed URL.
+
+##### Example call:
+
+```typescript
+import { submitGuestbookForDatafilesDownload } from '@iqss/dataverse-client-javascript'
+
+submitGuestbookForDatafilesDownload
+  .execute([10, 11], {
+    guestbookResponse: {
+      answers: [
+        { id: 123, value: 'Good' },
+        { id: 124, value: ['Multi', 'Line'] },
+        { id: 125, value: 'Yellow' }
+      ]
+    }
+  })
+  .then((signedUrl: string) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/access/domain/useCases/SubmitGuestbookForDatafilesDownload.ts) implementation_.
+
+#### Submit Guestbook For Dataset Download
+
+Submits guestbook answers for dataset download and returns a signed URL.
+
+##### Example call:
+
+```typescript
+import { submitGuestbookForDatasetDownload } from '@iqss/dataverse-client-javascript'
+
+submitGuestbookForDatasetDownload
+  .execute('doi:10.5072/FK2/XXXXXX', {
+    guestbookResponse: {
+      answers: [
+        { id: 123, value: 'Good' },
+        { id: 124, value: ['Multi', 'Line'] },
+        { id: 125, value: 'Yellow' }
+      ]
+    }
+  })
+  .then((signedUrl: string) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/access/domain/useCases/SubmitGuestbookForDatasetDownload.ts) implementation_.
+
+#### Submit Guestbook For Dataset Version Download
+
+Submits guestbook answers for a specific dataset version and returns a signed URL.
+
+##### Example call:
+
+```typescript
+import { submitGuestbookForDatasetVersionDownload } from '@iqss/dataverse-client-javascript'
+
+submitGuestbookForDatasetVersionDownload
+  .execute(10, ':latest', {
+    guestbookResponse: {
+      answers: [
+        { id: 123, value: 'Good' },
+        { id: 124, value: ['Multi', 'Line'] },
+        { id: 125, value: 'Yellow' }
+      ]
+    }
+  })
+  .then((signedUrl: string) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/access/domain/useCases/SubmitGuestbookForDatasetVersionDownload.ts) implementation_.

src/access/domain/dtos/GuestbookResponseDTO.ts

@@ -0,0 +1,10 @@
+export interface GuestbookAnswerDTO {
+  id: number | string
+  value: string | string[]
+}
+
+export interface GuestbookResponseDTO {
+  guestbookResponse: {
+    answers: GuestbookAnswerDTO[]
+  }
+}

src/access/domain/repositories/IAccessRepository.ts

@@ -0,0 +1,32 @@
+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
+  ): Promise<string>
+
+  submitGuestbookForDatafilesDownload(
+    fileIds: string | Array<number | string>,
+    guestbookResponse: GuestbookResponseDTO
+  ): Promise<string>
+
+  submitGuestbookForDatasetDownload(
+    datasetId: number | string,
+    guestbookResponse: GuestbookResponseDTO
+  ): Promise<string>
+
+  submitGuestbookForDatasetVersionDownload(
+    datasetId: number | string,
+    versionId: string,
+    guestbookResponse: GuestbookResponseDTO
+  ): Promise<string>
+}