Use Cases of Download with Guestbooks by ChengShi-1 · Pull Request #429 · IQSS/dataverse-client-javascript

ChengShi-1 · 2026-02-19T20:07:53Z

What this PR does / why we need it:

Adds support for Guestbook-related access flows needed for signed downloads (signed=true) via the new Access API endpoints.
Add Guestbook use cases and repository methods for creating, retrieving, listing, and enabling/disabling guestbooks.

Which issue(s) this PR closes:

Closes Use Cases to support Download Terms of Use and Guestbook #424

Related Dataverse PRs:

Depends on #Feature Request: API to support Download Terms of Use and Guestbook dataverse#12110

Special notes for your reviewer:

I introduced an AccessRepository because these endpoints are grouped under /api/access/*. I’m open to feedback on architecture: we could move SubmitGuestbookForDatafileDownload use cases under guestbooks instead, if that is preferred.
For signed=false(which acts the same as when signed is omitted), the current frontend download flow is URL-based: it builds the download URL, the browser issues a direct GET to the backend, and the browser handles the file download automatically (see FileJSDataverseRepository.ts (line 329)). We put the browser-triggered download flow in the frontend UI repo, so this PR does not add use cases for path if signed=false.
However, the question is whether signed=false should now have use cases if it requires a guestbookResponse. If guestbook submission is required, this is no longer a pure browser-triggered download flow and we should likely model it explicitly with use case.
.env should be change back once the dataverse pr is ready

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

yes

Additional documentation:

…ingly

ChengShi-1 · 2026-02-19T20:40:14Z

Hi Ellen @ekraffmiller , this PR is ready for review. Please feel free to take a look. I’ve added two questions in the special notes for the reviewer that I’m unsure about.

Copilot

Pull request overview

Adds Guestbook management and Access (guestbook submission for signed downloads) capabilities to the client library, supporting SPA flows that require guestbook responses prior to generating signed download URLs.

Changes:

Introduces a new guestbooks module with repository + use cases to create, fetch, list, and enable/disable guestbooks.
Introduces a new access module with repository + use cases to submit guestbook responses for signed download URLs (datafile, datafiles, dataset, dataset version).
Adds unit/integration tests plus public documentation and changelog updates for the new APIs.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
test/unit/guestbooks/SetGuestbookEnabled.test.ts	Unit coverage for enabling/disabling a guestbook use case.
test/unit/guestbooks/GetGuestbooksByDataverseIdentifier.test.ts	Unit coverage for listing guestbooks for a collection.
test/unit/guestbooks/GetGuestbook.test.ts	Unit coverage for fetching a single guestbook.
test/unit/guestbooks/CreateGuestbook.test.ts	Unit coverage for guestbook creation use case.
test/unit/access/SubmitGuestbookDownloads.test.ts	Unit coverage for guestbook-submission download use cases returning signed URLs.
test/integration/guestbooks/GuestbooksRepository.test.ts	Integration coverage for guestbooks repository against a real API.
test/integration/access/AccessRepository.test.ts	Integration coverage for access repository signed-URL flows.
test/environment/.env	Updates Dataverse image registry/tag used by the test environment.
src/index.ts	Exposes `guestbooks` and `access` modules from the package root.
src/guestbooks/infra/repositories/GuestbooksRepository.ts	Implements Guestbooks API calls (create/get/list/enable).
src/guestbooks/index.ts	Exports guestbooks use case instances and DTO/model types.
src/guestbooks/domain/useCases/SetGuestbookEnabled.ts	Use case wrapper for enabling/disabling guestbooks.
src/guestbooks/domain/useCases/GetGuestbooksByCollectionId.ts	Use case wrapper for listing guestbooks in a collection.
src/guestbooks/domain/useCases/GetGuestbook.ts	Use case wrapper for fetching a guestbook by id.
src/guestbooks/domain/useCases/CreateGuestbook.ts	Use case wrapper for guestbook creation.
src/guestbooks/domain/repositories/IGuestbooksRepository.ts	Defines guestbooks repository interface.
src/guestbooks/domain/models/Guestbook.ts	Adds guestbook domain model types.
src/guestbooks/domain/dtos/CreateGuestbookDTO.ts	Adds DTOs for guestbook creation payloads.
src/access/infra/repositories/AccessRepository.ts	Implements `/access/*` guestbook-submission endpoints returning signed URLs.
src/access/index.ts	Exports access use case instances and DTO types.
src/access/domain/useCases/SubmitGuestbookForDatasetVersionDownload.ts	Use case wrapper for dataset-version signed download.
src/access/domain/useCases/SubmitGuestbookForDatasetDownload.ts	Use case wrapper for dataset signed download.
src/access/domain/useCases/SubmitGuestbookForDatafilesDownload.ts	Use case wrapper for multi-file signed download.
src/access/domain/useCases/SubmitGuestbookForDatafileDownload.ts	Use case wrapper for single-file signed download.
src/access/domain/repositories/IAccessRepository.ts	Defines access repository interface.
src/access/domain/dtos/GuestbookResponseDTO.ts	Defines DTO for guestbook response submission payload.
docs/useCases.md	Documents the new guestbooks/access use cases and example calls.
CHANGELOG.md	Announces the new guestbooks/access capabilities.

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

src/guestbooks/domain/useCases/GetGuestbooksByCollectionId.ts

src/guestbooks/domain/repositories/IGuestbooksRepository.ts

test/unit/guestbooks/GetGuestbooksByDataverseIdentifier.test.ts

docs/useCases.md

CHANGELOG.md

src/guestbooks/infra/repositories/GuestbooksRepository.ts

docs/useCases.md

Copilot · 2026-02-19T20:41:08Z

test/environment/.env

-DATAVERSE_IMAGE_REGISTRY=docker.io
-DATAVERSE_IMAGE_TAG=unstable
+DATAVERSE_IMAGE_REGISTRY=ghcr.io
+DATAVERSE_IMAGE_TAG=12001-api-support-termofuse-guestbook


This change pins integration tests to a specific Dataverse image tag (12001-api-support-termofuse-guestbook) and registry. Since this looks temporary (noted in the PR description), it will make tests fragile once that tag disappears. Consider reverting to the default tag/registry (or making the tag overridable via a separate local-only env file) before merging.

Suggested change

DATAVERSE_IMAGE_TAG=12001-api-support-termofuse-guestbook

DATAVERSE_IMAGE_TAG=latest

docs/useCases.md

ChengShi-1 · 2026-03-11T15:34:16Z

Hi @ekraffmiller , this PR is ready for review again.

ekraffmiller

Hi @ChengShi-1, looks good! I just have some comments about the Guestbook objects. Also, with the latest merge from Steve Winship, can you update the tests to use guestbook Id returned from the create response?

ekraffmiller · 2026-02-24T15:03:25Z

src/access/domain/dtos/GuestbookResponseDTO.ts

+export interface GuestbookResponseDTO {
+  guestbookResponse: {
+    answers: GuestbookAnswerDTO[]
+  }
+}


answers should also be an optional field

ekraffmiller · 2026-02-28T15:05:46Z

src/guestbooks/domain/dtos/CreateGuestbookDTO.ts

+  email: string
+  institution: string
+  position: string


These fields (email, institution, position) aren't needed, they will be sent in the guestbook response instead

Suggested change

email: string

institution: string

position: string

ekraffmiller · 2026-02-28T15:41:35Z

src/guestbooks/domain/models/Guestbook.ts

+  email: string
+  institution: string
+  position: string


These fields aren't needed in the Guestbook interface

Suggested change

email: string

institution: string

position: string

ekraffmiller · 2026-03-13T16:47:53Z

src/access/infra/repositories/AccessRepository.ts

+  }
+
+  public async submitGuestbookForDatafilesDownload(
+    fileIds: string | Array<number | string>,


As far as I can tell, the access API for multiple files only accepts numeric ids, not a persistentIds. So, can we narrow the types allowed for this function?

Suggested change

fileIds: string | Array<number | string>,

fileIds: Array<number>,

ekraffmiller · 2026-03-13T17:03:59Z

docs/useCases.md

+  email: 'test@gmail.com',
+  institution: 'Harvard University',
+  position: 'Researcher',


not needed

Suggested change

email: 'test@gmail.com',

institution: 'Harvard University',

position: 'Researcher',

ekraffmiller · 2026-03-13T17:05:18Z

docs/useCases.md

+const guestbookId = 123
+
+setGuestbookEnabled.execute(collectionIdOrAlias, guestbookId, false).then(() => {


add a const for enabled boolean

Suggested change

const guestbookId = 123

setGuestbookEnabled.execute(collectionIdOrAlias, guestbookId, false).then(() => {

const guestbookId = 123

const enabled=false

setGuestbookEnabled.execute(collectionIdOrAlias, guestbookId, enabled).then(() => {

ekraffmiller · 2026-03-13T17:43:48Z

test/integration/access/AccessRepository.test.ts

+    test('should return signed url for datafile download', async () => {
+      const actual = await sut.submitGuestbookForDatafileDownload(testFileId, guestbookResponse)
+
+      expect(actual).toEqual(expect.any(String))


can you update the tests to make sure the returned string is a URL?
for example, expect(() => new URL(actual)).not.toThrow()

…f-use-and-guestbook

…tbook' of https://github.com/IQSS/dataverse-client-javascript into 424-use-cases-to-support-download-terms-of-use-and-guestbook

ekraffmiller

changes look good, thanks!

…upport-download-terms-of-use-and-guestbook

feat: Add Guestbook and Access Repository, and their use cases accord…

c023fd5

…ingly

ChengShi-1 linked an issue Feb 19, 2026 that may be closed by this pull request

Use Cases to support Download Terms of Use and Guestbook #424

Closed

github-actions bot added FY26 Sprint 17 FY26 Sprint 17 (2026-02-11 - 2026-02-25) GREI Re-arch GREI re-architecture-related Project: HDV SPA Rollout SPA.Q1.2026.1 Download with terms of use and guestbook labels Feb 19, 2026

ChengShi-1 added the Size: 3 A percentage of a sprint. 2.1 hours. label Feb 19, 2026

ChengShi-1 added this to IQSS Dataverse Project Feb 19, 2026

ChengShi-1 added 2 commits February 19, 2026 15:14

use other image tag for test

1f61ab1

fix: test failing

812dd22

ChengShi-1 marked this pull request as ready for review February 19, 2026 20:32

Copilot AI review requested due to automatic review settings February 19, 2026 20:32

ChengShi-1 moved this to Ready for Review ⏩ in IQSS Dataverse Project Feb 19, 2026

Copilot started reviewing on behalf of ChengShi-1 February 19, 2026 20:32 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes

ChengShi-1 added 2 commits February 19, 2026 15:46

fix: copilot reviews

c3f76f8

fix: update collectionId to Uppercase

bba1993

ekraffmiller self-assigned this Feb 23, 2026

ekraffmiller moved this from Ready for Review ⏩ to In Review 🔎 in IQSS Dataverse Project Feb 23, 2026

ChengShi-1 moved this from In Review 🔎 to In Progress 💻 in IQSS Dataverse Project Feb 25, 2026

ChengShi-1 unassigned ekraffmiller Feb 25, 2026

scolapasta assigned ChengShi-1 Feb 25, 2026

cmbz added the FY26 Sprint 18 FY26 Sprint 18 (2026-02-25 - 2026-03-11) label Feb 26, 2026

feat: update use cases of guestbook and access

4dd5c4c

ChengShi-1 added Size: 10 A percentage of a sprint. 7 hours. and removed Size: 3 A percentage of a sprint. 2.1 hours. labels Feb 26, 2026

ChengShi-1 removed their assignment Feb 26, 2026

ChengShi-1 moved this from In Progress 💻 to Ready for Review ⏩ in IQSS Dataverse Project Feb 26, 2026

chore: update usecases.md

88fb521

ChengShi-1 moved this from In Progress 💻 to Ready for Review ⏩ in IQSS Dataverse Project Mar 11, 2026

ChengShi-1 changed the title ~~Use Cases of Guestbooks~~ Use Cases of Download with Guestbooks Mar 11, 2026

fix: update changelog and usecase md

63ce2d8

cmbz added this to the 6.11 milestone Mar 11, 2026

jp-tosca assigned jp-tosca and unassigned jp-tosca Mar 12, 2026

ekraffmiller moved this from Ready for Review ⏩ to In Review 🔎 in IQSS Dataverse Project Mar 13, 2026

ekraffmiller self-assigned this Mar 13, 2026

ChengShi-1 mentioned this pull request Mar 13, 2026

View guestbook and download file with guestbook IQSS/dataverse-frontend#926

Open

ekraffmiller reviewed Mar 16, 2026

View reviewed changes

ekraffmiller assigned ChengShi-1 and unassigned ekraffmiller Mar 16, 2026

ChengShi-1 and others added 7 commits March 17, 2026 09:45

fix: tests and createGuestbookDTO

92f65b3

fix: createGuestbook returns ID

26163fe

Merge branch 'develop' into 424-use-cases-to-support-download-terms-o…

d6e8ca8

…f-use-and-guestbook

fix: unit test

cbf44c0

Merge branch '424-use-cases-to-support-download-terms-of-use-and-gues…

bc7726b

…tbook' of https://github.com/IQSS/dataverse-client-javascript into 424-use-cases-to-support-download-terms-of-use-and-guestbook

fix: unit test

5f5cdd2

update env

199cf25

ChengShi-1 assigned ekraffmiller Mar 17, 2026

ekraffmiller approved these changes Mar 17, 2026

View reviewed changes

github-project-automation bot moved this from In Review 🔎 to Ready for QA ⏩ in IQSS Dataverse Project Mar 17, 2026

ChengShi-1 unassigned ekraffmiller and ChengShi-1 Mar 17, 2026

jp-tosca self-assigned this Mar 19, 2026

Merge remote-tracking branch 'origin/develop' into 424-use-cases-to-s…

b3bb1e5

…upport-download-terms-of-use-and-guestbook

jp-tosca merged commit 554dbe0 into develop Mar 20, 2026
5 checks passed

github-project-automation bot moved this from Ready for QA ⏩ to Merged 🚀 in IQSS Dataverse Project Mar 20, 2026

jp-tosca removed their assignment Mar 20, 2026

	DATAVERSE_IMAGE_TAG=12001-api-support-termofuse-guestbook
	DATAVERSE_IMAGE_TAG=latest

	fileIds: string \| Array<number \| string>,
	fileIds: Array<number>,

	email: 'test@gmail.com',
	institution: 'Harvard University',
	position: 'Researcher',

		const guestbookId = 123

		setGuestbookEnabled.execute(collectionIdOrAlias, guestbookId, false).then(() => {

Conversation

ChengShi-1 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it:

Which issue(s) this PR closes:

Related Dataverse PRs:

Special notes for your reviewer:

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

Additional documentation:

Uh oh!

ChengShi-1 commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ChengShi-1 commented Mar 11, 2026

Uh oh!

ekraffmiller left a comment

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

ekraffmiller left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ChengShi-1 commented Feb 19, 2026 •

edited

Loading