PreviewURL use cases and extension on dataset and file use cases

[ChengShi-1]

What this PR does / why we need it:

• Datasets/Files: Added optional Preview URL (previewUrlToken) support to getDataset, getDatasetFiles, getDatasetFileCounts, getDatasetFilesTotalDownloadSize, getFile, and getFileAndDataset
• Datasets: Added createPreviewUrl, getPreviewUrl, and deletePreviewUrl use cases

Which issue(s) this PR closes:

• Closes Extend Dataset and File use cases: add privateUrlToken #470

Related Dataverse PRs:

• Depends on #

Special notes for your reviewer:

• toApiQueryParams is needed because the internal query object uses previewUrlToken, but the actual Dataverse API expects that token as query param key. Thus, I mapped key to previewUrlToken for better clarification.

Suggestions on how to test this:

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

Changlog updated

Additional documentation:

[Copilot]

Pull request overview

This PR extends the datasets and files read APIs to support Dataverse “Preview URL” access via an optional previewUrlToken (mapped to the Dataverse key query param), and adds a full Preview URL lifecycle (create/get/delete) to the datasets API surface.

Changes:

• Add optional previewUrlToken support to dataset/file read use cases and repository methods, including mapping to key query param and adjusting auth requirements.
• Add Preview URL lifecycle support (createPreviewUrl, getPreviewUrl, deletePreviewUrl) including a new PreviewUrl model and response transformer.
• Update unit/integration tests, docs, changelog, and test TypeScript config to cover new behavior.

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tsconfig.tests.json	Adds Jest/Node types for test compilation.
package.json	Bumps @types/jest version.
package-lock.json	Locks updated @types/jest version metadata.
src/files/domain/repositories/IFilesRepository.ts	Extends repository read methods with optional previewUrlToken.
src/files/infra/repositories/FilesRepository.ts	Maps previewUrlToken to key query param and adjusts auth behavior for preview access.
src/files/domain/useCases/GetFile.ts	Adds optional previewUrlToken passthrough to repository.
src/files/domain/useCases/GetFileAndDataset.ts	Adds optional previewUrlToken passthrough to repository.
src/files/domain/useCases/GetDatasetFiles.ts	Adds optional previewUrlToken passthrough to repository.
src/files/domain/useCases/GetDatasetFileCounts.ts	Adds optional previewUrlToken passthrough to repository.
src/files/domain/useCases/GetDatasetFilesTotalDownloadSize.ts	Adds optional previewUrlToken passthrough to repository.
src/datasets/domain/models/PreviewUrl.ts	Introduces PreviewUrl response model.
src/datasets/domain/repositories/IDatasetsRepository.ts	Adds preview URL lifecycle methods and extends getDataset with previewUrlToken.
src/datasets/infra/repositories/transformers/datasetTransformers.ts	Adds transformer for Preview URL API responses.
src/datasets/infra/repositories/DatasetsRepository.ts	Implements preview URL lifecycle methods and supports previewUrlToken on getDataset.
src/datasets/domain/useCases/previewUrl/CreatePreviewUrl.ts	Adds create-preview-url use case wrapper.
src/datasets/domain/useCases/previewUrl/GetPreviewUrl.ts	Adds get-preview-url use case wrapper.
src/datasets/domain/useCases/previewUrl/DeletePreviewUrl.ts	Adds delete-preview-url use case wrapper.
src/datasets/domain/useCases/GetDataset.ts	Adds optional previewUrlToken passthrough to repository.
src/datasets/index.ts	Exposes Preview URL use cases and model from the datasets package entrypoint.
docs/useCases.md	Documents Preview URL lifecycle and previewUrlToken usage across affected use cases.
CHANGELOG.md	Records Preview URL token support and new Preview URL use cases.
test/unit/files/GetFile.test.ts	Updates invocation to include new optional param and adds forwarding test.
test/unit/files/GetFileAndDataset.test.ts	Updates invocation to include new optional param and adds forwarding test.
test/unit/files/GetDatasetFiles.test.ts	Adds forwarding test for previewUrlToken.
test/unit/files/GetDatasetFileCounts.test.ts	Adds forwarding test for previewUrlToken.
test/unit/files/GetDatasetFilesTotalDownloadSize.test.ts	Updates invocation signature and adds forwarding test for previewUrlToken.
test/unit/files/FilesRepository.test.ts	Verifies previewUrlToken is sent as key for relevant file/dataset endpoints.
test/unit/datasets/GetDataset.test.ts	Adds forwarding test for previewUrlToken on getDataset.
test/unit/datasets/DatasetsRepository.test.ts	Verifies previewUrlToken is sent as key on dataset version fetch; adds Preview URL lifecycle tests.
test/unit/datasets/CreatePreviewUrl.test.ts	Adds unit tests for create-preview-url use case.
test/unit/datasets/GetPreviewUrl.test.ts	Adds unit tests for get-preview-url use case.
test/unit/datasets/DeletePreviewUrl.test.ts	Adds unit tests for delete-preview-url use case.
test/integration/files/FilesRepository.test.ts	Adds integration coverage for unauthenticated access via preview URL token.
test/integration/datasets/DatasetsRepository.test.ts	Adds integration coverage for Preview URL lifecycle and preview-token access patterns.

---

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

[ekraffmiller]

We discussed in the frontend meeting that APIs that use the key param currently don't support anonymous preview tokens. More work needs to be done in the backend to support these use cases. See: IQSS/dataverse#12631

[ekraffmiller]

@ChengShi-1 maybe we could put this PR on hold, while waiting for the API updates?