fix: change dataverseId to collectionId, and update GetGuestbookResponsesById

Author: ChengShi-1

CHANGELOG.md

@@ -8,7 +8,8 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Added
 
-- Guestbooks: Added `downloadGuestbookResponsesByDataverseId` and `downloadGuestbookResponsesOfAGuestbook` use cases and repository support for exporting guestbook responses as raw CSV content.
+- Guestbooks: Added `getGuestbookResponsesByGuestbookId` use case and repository support for retrieving paginated guestbook responses as structured JSON.
+- Guestbooks: Added `downloadGuestbookResponsesByCollectionId` and `downloadGuestbookResponsesOfAGuestbook` use cases and repository support for exporting guestbook responses as raw CSV content.
 - Guestbooks: Added optional `includeStats` support to `getGuestbooksByCollectionId`, returning `usageCount` and `responseCount` when requested.
 
 ### Changed

docs/useCases.md

@@ -130,6 +130,9 @@ The different use cases currently available in the package are classified below,
   - [Guestbooks read use cases](#guestbooks-read-use-cases)
     - [Get a Guestbook](#get-a-guestbook)
     - [Get Guestbooks By Collection Id](#get-guestbooks-by-collection-id)
+    - [Get Guestbook Responses Byg Guestbook Id](#get-guestbook-responses-byg-guestbook-id)
+    - [Download Guestbook Responses By Collection Id](#download-guestbook-responses-by-collection-id)
+    - [Download Guestbook Responses Of A Guestbook](#download-guestbook-responses-of-a-guestbook)
   - [Guestbooks write use cases](#guestbooks-write-use-cases)
     - [Create a Guestbook](#create-a-guestbook)
     - [Set Guestbook Enabled](#set-guestbook-enabled)
@@ -2951,38 +2954,62 @@ getGuestbooksByCollectionId
 
 _See [use case](../src/guestbooks/domain/useCases/GetGuestbooksByCollectionId.ts) implementation_.
 
-#### Download Guestbook Responses By Dataverse Id
+#### Get Guestbook Responses Byg Guestbook Id
 
-Downloads all guestbook responses for a dataverse collection and returns the raw response body, typically CSV content.
+Returns paginated [GuestbookResponse](../src/guestbooks/domain/models/GuestbookResponse.ts) entries for a guestbook.
 
 ##### Example call:
 
 ```typescript
-import { downloadGuestbookResponsesByDataverseId } from '@iqss/dataverse-client-javascript'
+import { getGuestbookResponsesByGuestbookId } from '@iqss/dataverse-client-javascript'
 
-const dataverseId = 'root'
+const guestbookId = 123
+const limit = 10
+const offset = 0
 
-downloadGuestbookResponsesByDataverseId.execute(dataverseId).then((csvResponse: string) => {
-  /* ... */
-})
+getGuestbookResponsesByGuestbookId
+  .execute(guestbookId, limit, offset)
+  .then((guestbookResponses: GuestbookResponse[]) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/guestbooks/domain/useCases/getGuestbookResponsesByGuestbookId.ts) implementation_.
+
+#### Download Guestbook Responses By Collection Id
+
+Downloads all guestbook responses for a collection and returns the raw response body, typically CSV content.
+
+##### Example call:
+
+```typescript
+import { downloadGuestbookResponsesByCollectionId } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 'root'
+
+downloadGuestbookResponsesByCollectionId
+  .execute(collectionIdOrAlias)
+  .then((csvResponse: string) => {
+    /* ... */
+  })
 ```
 
-_See [use case](../src/guestbooks/domain/useCases/DownloadGuestbookResponsesByDataverseId.ts) implementation_.
+_See [use case](../src/guestbooks/domain/useCases/DownloadGuestbookResponsesByCollectionId.ts) implementation_.
 
 #### Download Guestbook Responses Of A Guestbook
 
-Downloads guestbook responses for one guestbook in a dataverse collection and returns the raw response body, typically CSV content.
+Downloads guestbook responses for one guestbook in a collection and returns the raw response body, typically CSV content.
 
 ##### Example call:
 
 ```typescript
 import { downloadGuestbookResponsesOfAGuestbook } from '@iqss/dataverse-client-javascript'
 
-const dataverseId = 'root'
+const collectionIdOrAlias = 'root'
 const guestbookId = 123
 
 downloadGuestbookResponsesOfAGuestbook
-  .execute(dataverseId, guestbookId)
+  .execute(collectionIdOrAlias, guestbookId)
   .then((csvResponse: string) => {
     /* ... */
   })

src/guestbooks/domain/dtos/GuestbookResponsesDTO.ts

@@ -0,0 +1,13 @@
+import { Guestbook } from '../models/Guestbook'
+import { GuestbookResponse } from '../models/GuestbookResponse'
+
+export interface GuestbookResponsesDTO {
+  guestbook: Guestbook
+  responses: GuestbookResponse[]
+  pagination?: GuestbookResponsesPaginationDTO
+}
+
+export interface GuestbookResponsesPaginationDTO {
+  next?: string
+  totalResponses: number
+}

src/guestbooks/domain/models/GuestbookResponse.ts

@@ -1,5 +1,27 @@
 export interface GuestbookResponse {
-  [key: string]: unknown
-  guestbookId?: number
-  dataverseId?: number
+  id: number
+  dataset: string
+  datasetPid: string
+  date: string
+  type: EventType
+  fileName?: string
+  fileId?: number
+  filePid?: string
+  userName: string
+  email?: string
+  institution?: string
+  position?: string
+  customQuestions?: GuestbookResponseCustomQuestion[]
+}
+
+export interface GuestbookResponseCustomQuestion {
+  question: string
+  response: string
+}
+
+export enum EventType {
+  ACCESS_REQUEST = 'AccessRequest',
+  DOWNLOAD = 'Download',
+  SUBSET = 'Subset',
+  EXPLORE = 'Explore'
 }

src/guestbooks/domain/repositories/IGuestbooksRepository.ts

@@ -13,12 +13,13 @@ export interface IGuestbooksRepository {
     includeStats?: boolean,
     includeInherited?: boolean
   ): Promise<Guestbook[]>
-  getGuestbookResponsesByDataverseId(
-    dataverseId: number | string,
-    guestbookId?: number
+  getGuestbookResponsesByGuestbookId(
+    guestbookId: number,
+    limit?: number,
+    offset?: number
   ): Promise<GuestbookResponse[]>
-  downloadGuestbookResponsesByDataverseId(
-    dataverseId: number | string,
+  downloadGuestbookResponsesByCollectionId(
+    collectionIdOrAlias: number | string,
     guestbookId?: number
   ): Promise<string>
   setGuestbookEnabled(

…wnloadGuestbookResponsesByDataverseId.ts …nloadGuestbookResponsesByCollectionId.tssrc/guestbooks/domain/useCases/DownloadGuestbookResponsesByDataverseId.ts renamed to src/guestbooks/domain/useCases/DownloadGuestbookResponsesByCollectionId.ts src/guestbooks/domain/useCases/DownloadGuestbookResponsesByDataverseId.ts renamed to src/guestbooks/domain/useCases/DownloadGuestbookResponsesByCollectionId.ts

@@ -1,20 +1,22 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
 import { IGuestbooksRepository } from '../repositories/IGuestbooksRepository'
 
-export class DownloadGuestbookResponsesByDataverseId implements UseCase<string> {
+export class DownloadGuestbookResponsesByCollectionId implements UseCase<string> {
   constructor(private readonly guestbooksRepository: IGuestbooksRepository) {}
 
   /**
-   * Downloads all guestbook responses for a dataverse collection.
+   * Downloads all guestbook responses for a collection.
    *
-   * The dataverse can be identified by either its alias/identifier or numeric database id.
+   * The collection can be identified by either its alias/identifier or numeric database id.
    * The returned string is the raw response body from the Dataverse API, which is typically
    * saved by callers as a CSV file or printed directly.
    *
-   * @param {number | string} dataverseId - Dataverse alias/identifier or numeric database id.
+   * @param {number | string} collectionIdOrAlias - Collection alias/identifier or numeric database id.
    * @returns {Promise<string>} Raw response body returned by the Dataverse API.
    */
-  async execute(dataverseId: number | string): Promise<string> {
-    return await this.guestbooksRepository.downloadGuestbookResponsesByDataverseId(dataverseId)
+  async execute(collectionIdOrAlias: number | string): Promise<string> {
+    return await this.guestbooksRepository.downloadGuestbookResponsesByCollectionId(
+      collectionIdOrAlias
+    )
   }
 }

src/guestbooks/domain/useCases/DownloadGuestbookResponsesOfAGuestbook.ts

@@ -5,19 +5,19 @@ export class DownloadGuestbookResponsesOfAGuestbook implements UseCase<string> {
   constructor(private readonly guestbooksRepository: IGuestbooksRepository) {}
 
   /**
-   * Downloads guestbook responses for one guestbook in a dataverse collection.
+   * Downloads guestbook responses for one guestbook in a collection.
    *
-   * The dataverse can be identified by either its alias/identifier or numeric database id.
+   * The collection can be identified by either its alias/identifier or numeric database id.
    * The returned string is the raw response body from the Dataverse API, which is typically
    * saved by callers as a CSV file or printed directly.
    *
-   * @param {number | string} dataverseId - Dataverse alias/identifier or numeric database id.
+   * @param {number | string} collectionIdOrAlias - Collection alias/identifier or numeric database id.
    * @param {number} guestbookId - Guestbook identifier to restrict the export.
    * @returns {Promise<string>} Raw response body returned by the Dataverse API.
    */
-  async execute(dataverseId: number | string, guestbookId: number): Promise<string> {
-    return await this.guestbooksRepository.downloadGuestbookResponsesByDataverseId(
-      dataverseId,
+  async execute(collectionIdOrAlias: number | string, guestbookId: number): Promise<string> {
+    return await this.guestbooksRepository.downloadGuestbookResponsesByCollectionId(
+      collectionIdOrAlias,
       guestbookId
     )
   }

src/guestbooks/domain/useCases/GetGuestbookResponsesByDataverseId.ts

@@ -0,0 +1,23 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { GuestbookResponse } from '../models/GuestbookResponse'
+import { IGuestbooksRepository } from '../repositories/IGuestbooksRepository'
+
+export class GetGuestbookResponsesByGuestbookId implements UseCase<GuestbookResponse[]> {
+  constructor(private readonly guestbooksRepository: IGuestbooksRepository) {}
+
+  /**
+   * Returns guestbook responses for one guestbook.
+   *
+   * @param {number} guestbookId - Guestbook identifier.
+   * @param {number} limit - Maximum number of responses to return.
+   * @param {number} offset - Number of responses to skip.
+   * @returns {Promise<GuestbookResponse[]>}
+   */
+  async execute(guestbookId: number, limit = 10, offset = 0): Promise<GuestbookResponse[]> {
+    return await this.guestbooksRepository.getGuestbookResponsesByGuestbookId(
+      guestbookId,
+      limit,
+      offset
+    )
+  }
+}