Extend get guestbooks use case with stats and Download responses

[ChengShi-1]

What this PR does / why we need it:

• Get Guestbooks By Collection Id: Added optional includeStats and includeInherited support to getGuestbooksByCollectionId.
• write use cases of downloading all responses of a collection or download responses of a guestbook

Which issue(s) this PR closes:

• Closes Add usage and response counts to get guestbooks use case #448

Related Dataverse PRs:

• Depends on #Get Guestbook list API: add param to return inherited guestbooks dataverse#12326 and Add usage and response counts to get guestbooks use case #448

Special notes for your reviewer:

Test failed about storage drive, so I also copy pastes a CollectionHelper.ts from this PR. waiting to be merged
https://github.com/IQSS/dataverse-client-javascript/pull/431/changes#diff-edac108c1a43d5773116d19797d04ecdf890fc97b5cf83ce2d56d38b9a7aca18

Suggestions on how to test this:

Is there a release notes or changelog update needed for this change?:

Additional documentation:

[Copilot]

Pull request overview

Adds optional guestbook usage/response statistics support to the “get guestbooks by collection” flow, aligning the client with the Dataverse API enhancement needed for the Manage Guestbooks UI.

Changes:

• Extended getGuestbooksByCollectionId to accept an optional includeStats flag and send it as a query parameter when enabled.
• Updated the Guestbook domain model to optionally expose usageCount and responseCount.
• Added/updated unit + integration tests, plus documentation and changelog entries.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/unit/guestbooks/GuestbooksRepository.test.ts	New unit coverage for repository query param behavior and error handling.
test/unit/guestbooks/GetGuestbooksByCollectionId.test.ts	Adds unit coverage for the use case passing includeStats.
test/integration/guestbooks/GuestbooksRepository.test.ts	Adds integration coverage for listing stats and verifying count changes via assignment + guest response submission.
src/guestbooks/infra/repositories/GuestbooksRepository.ts	Adds includeStats param and forwards it as query params when true.
src/guestbooks/domain/useCases/GetGuestbooksByCollectionId.ts	Extends use case API to accept includeStats.
src/guestbooks/domain/repositories/IGuestbooksRepository.ts	Updates repository interface to include optional includeStats.
src/guestbooks/domain/models/Guestbook.ts	Adds optional usageCount and responseCount fields.
docs/useCases.md	Documents the new includeStats parameter and updates example usage.
CHANGELOG.md	Adds an Unreleased entry describing the new includeStats support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ekraffmiller]

Hi @ChengShi-1 I left some comments on the PR, hope it's not too confusing! After going back on forth between the use cases and the API, I think there is actually one more change we need in the API - which I describe in my comment in GetGuestbookResponsesOfAGuestbook. I'm happy to discuss more about it.

[ekraffmiller]

The API for getting the responses for a guestbook in JSON form is, for example:
curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/guestbooks/$ID/responses?limit10&offset=0"
So we need to add parameters for limit and offset.
Another thing I noticed though, is that this API doesn't allow us to pass a dataverseId, so it's going to return all guestbook responses regardless of collection. So unfortunately I think we to ask for another change to the API - to be able to pass guestbookId and collectionId and get all the responses for a guestbook within a specific collection, returned in JSON format.

[ChengShi-1]

I created an issue in dataverse for the api missing IQSS/dataverse#12451

[ekraffmiller]

I don't think this use case is needed, we only need to download the csv version of the responses, we don't need an array of JSON for displaying.

[ekraffmiller]

Looks good! just need to update the return type of GetGuestbookResponsesByGuestbookId to support pagination.

[ekraffmiller]

The API will return pagination info as well, so the return type should be GustbookSubset, containing the array of Guestbook items, and the total count, similar to how we handle pagination for other objects

[ChengShi-1]

Added. Thanks for catching this😃

[ekraffmiller]

thanks for the updates, looks good!