PreviewURL use cases and extension on dataset and file use cases

CHANGELOG.md

@@ -17,6 +17,8 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Datasets: Added `exportDatasetMetadata` use case, repository method, and `ExportedDatasetMetadata` response type to support exporting dataset metadata by numeric id or persistent id through Dataverse endpoint `GET /datasets/export`.
 - Collections: Added `allowedDatasetTypes` field to the [Collection](./src/collections/domain/models/Collection.ts) model. This field is optional and only populated the feature is enabled on the installation and configured on the collection.
 - Collections: Added theme information when retrieving a collection using `getCollection`.
+- Datasets/Files: Added optional Preview URL (`previewUrlToken`) support to `getDataset`, `getDatasetFiles`, `getDatasetFileCounts`, `getDatasetFilesTotalDownloadSize`, `getFile`, and `getFileAndDataset`.
+- Datasets: Added `createPreviewUrl`, `getPreviewUrl`, and `deletePreviewUrl` use cases and repository methods to support Dataverse endpoint `/datasets/{id}/previewUrl`.
 
 ### Changed
 

docs/useCases.md

@@ -62,6 +62,7 @@ The different use cases currently available in the package are classified below,
     - [Get Dataset Available Dataset Types](#get-dataset-available-dataset-types)
     - [Get Dataset Available Dataset Type](#get-dataset-available-dataset-type)
     - [Get Dataset Upload Limits](#get-dataset-upload-limits)
+    - [Get Preview URL for a Dataset](#get-preview-url-for-a-dataset)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
@@ -75,6 +76,8 @@ The different use cases currently available in the package are classified below,
     - [Link Dataset Type with Metadata Blocks](#link-dataset-type-with-metadata-blocks)
     - [Set Available Licenses For Dataset Type](#set-available-licenses-for-dataset-type)
     - [Delete a Dataset Type](#delete-a-dataset-type)
+    - [Create a Preview URL for a Dataset](#create-a-preview-url-for-a-dataset)
+    - [Delete a Preview URL from a Dataset](#delete-a-preview-url-from-a-dataset)
 - [Files](#Files)
   - [Files read use cases](#files-read-use-cases)
     - [Get a File](#get-a-file)
@@ -975,6 +978,8 @@ There is an optional third parameter called `includeDeaccessioned`, which indica
 
 There is an optional fourth parameter called `keepRawFields`, which indicates whether or not to keep the metadata fields as they are and avoid the transformation to Markdown. The default value is `false`.
 
+There is an optional fifth parameter called `previewUrlToken`, which allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to access an unpublished dataset without needing to log in. When provided, it takes priority over any other credentials that may be configured, so the Preview URL grants access on its own.
+
 #### Get Dataset By Private URL Token
 
 Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given an associated Private URL Token.
@@ -1890,6 +1895,80 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetUploadLimits.ts) imple
 
 If the backend does not define any quota limits for the dataset, the returned object can be empty (`{}`).
 
+#### Get Preview URL for a Dataset
+
+Returns a [PreviewUrl](../src/datasets/domain/models/PreviewUrl.ts) instance (`token`, `link`, and `isAnonymizedAccess`) for the given dataset's existing Preview URL, if one has been created.
+
+##### Example call:
+
+```typescript
+import { getPreviewUrl } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getPreviewUrl.execute(datasetId).then((previewUrl: PreviewUrl) => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/previewUrl/GetPreviewUrl.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
+#### Create a Preview URL for a Dataset
+
+Creates a Preview URL for the given dataset, returning a [PreviewUrl](../src/datasets/domain/models/PreviewUrl.ts) instance.
+
+##### Example call:
+
+```typescript
+import { createPreviewUrl } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+createPreviewUrl.execute(datasetId).then((previewUrl: PreviewUrl) => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/previewUrl/CreatePreviewUrl.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
+There is an optional second parameter called `anonymizedAccess`. If set to `true`, and Anonymized Access has been enabled on the installation, the created Preview URL will only allow an anonymized view of the dataset.
+
+#### Delete a Preview URL from a Dataset
+
+Deletes the Preview URL for the given dataset, if one exists.
+
+##### Example call:
+
+```typescript
+import { deletePreviewUrl } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+deletePreviewUrl.execute(datasetId).then(() => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/previewUrl/DeletePreviewUrl.ts) implementation_.
+
+The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+
 ## Files
 
 ### Files read use cases
@@ -1923,6 +2002,8 @@ The optional `datasetVersionId` parameter can correspond to a numeric version id
 
 There is an optional third parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the file search. If not set, the default value is `false`.
 
+There is an optional fourth parameter called `previewUrlToken`, which allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to access a file in an unpublished dataset without needing to log in.
+
 #### Get a File and its Dataset
 
 Returns a tuple of [FileModel](../src/files/domain/models/FileModel.ts) and [Dataset](../src/datasets/domain/models/Dataset.ts) objects (`[FileModel, Dataset]`), given the search parameters to identify the file.
@@ -1954,6 +2035,8 @@ The optional `datasetVersionId` parameter can correspond to a numeric version id
 
 There is an optional third parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the file search. If not set, the default value is `false`.
 
+There is an optional fourth parameter called `previewUrlToken`, which allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to access a file in an unpublished dataset without needing to log in.
+
 #### Get File Citation Text
 
 Returns the File citation text.
@@ -2041,6 +2124,8 @@ There is an optional third parameter called `includeDeaccessioned`, which indica
 
 An optional fourth parameter `fileSearchCriteria` receives a [FileSearchCriteria](../src/files/domain/models/FileCriteria.ts) object to retrieve counts only for files that match the specified criteria.
 
+An optional fifth parameter called `previewUrlToken` allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to access file counts in an unpublished dataset without needing to log in.
+
 ##### Example call using optional parameters:
 
 ```typescript
@@ -2147,6 +2232,8 @@ An optional fourth parameter called `fileSearchCriteria` receives a [FileSearchC
 
 An optional fifth parameter called `includeDeaccessioned` indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is `false`.
 
+An optional sixth parameter called `previewUrlToken` allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to get the download size for an unpublished dataset without needing to log in.
+
 ##### Example call using optional parameters:
 
 ```typescript
@@ -2233,6 +2320,7 @@ This use case supports the following optional parameters depending on the search
 - **offset**: (number) Offset for pagination.
 - **fileSearchCriteria**: ([FileSearchCriteria](../src/files/domain/models/FileCriteria.ts)) Supports filtering the files by different file properties.
 - **fileOrderCriteria**: ([FileOrderCriteria](../src/files/domain/models/FileCriteria.ts)) Supports ordering the results according to different criteria. If not set, the defalt value is `FileOrderCriteria.NAME_AZ`.
+- **previewUrlToken**: (string) Allows a reviewer using a [Preview URL](#get-preview-url-for-a-dataset) to list the files of an unpublished dataset without needing to log in.
 
 ##### Example call using optional parameters:
 

package.json

@@ -42,7 +42,7 @@
   },
   "homepage": "https://github.com/IQSS/dataverse-client-javascript#readme",
   "devDependencies": {
-    "@types/jest": "^29.5.12",
+    "@types/jest": "^29.5.14",
     "@typescript-eslint/eslint-plugin": "5.51.0",
     "@typescript-eslint/parser": "5.51.0",
     "@web-std/file": "3.0.3",

src/datasets/domain/models/PreviewUrl.ts

@@ -0,0 +1,5 @@
+export interface PreviewUrl {
+  token: string
+  link: string
+  isAnonymizedAccess: boolean
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -21,13 +21,15 @@ import { DatasetUploadLimits } from '../models/DatasetUploadLimits'
 import { DatasetReview } from '../models/DatasetReview'
 import { ExportedDatasetMetadata } from '../models/ExportedDatasetMetadata'
 import { DatasetNotNumberedVersion } from '../models/DatasetNotNumberedVersion'
+import { PreviewUrl } from '../models/PreviewUrl'
 
 export interface IDatasetsRepository {
   getDataset(
     datasetId: number | string,
     datasetVersionId: string,
     includeDeaccessioned: boolean,
-    keepRawFields: boolean
+    keepRawFields: boolean,
+    previewUrlToken?: string
   ): Promise<Dataset>
   getDatasetLocks(datasetId: number | string): Promise<DatasetLock[]>
   getDatasetCitation(
@@ -36,6 +38,9 @@ export interface IDatasetsRepository {
     includeDeaccessioned: boolean
   ): Promise<string>
   getPrivateUrlDataset(token: string, keepRawFields: boolean): Promise<Dataset>
+  createPreviewUrl(datasetId: number | string, anonymizedAccess?: boolean): Promise<PreviewUrl>
+  getPreviewUrl(datasetId: number | string): Promise<PreviewUrl>
+  deletePreviewUrl(datasetId: number | string): Promise<void>
   getAllDatasetPreviews(
     limit?: number,
     offset?: number,

src/datasets/domain/useCases/GetDataset.ts

@@ -17,19 +17,22 @@ export class GetDataset implements UseCase<Dataset> {
    * @param {string | DatasetNotNumberedVersion} [datasetVersionId=DatasetNotNumberedVersion.LATEST] - The dataset version identifier, which can be a version-specific numeric string (for example, 1.0) or a DatasetNotNumberedVersion enum value. If this parameter is not set, the default value is: DatasetNotNumberedVersion.LATEST
    * @param {boolean} [includeDeaccessioned=false] - Indicates whether to consider deaccessioned versions in the dataset search or not. The default value is false
    * @param {boolean} [keepRawFields=false] - Indicates whether or not the use case should keep the metadata fields as they are and avoid the transformation to markdown. The default value is false.
+   * @param {string} [previewUrlToken] - The token identifying a Preview URL, allowing a reviewer without credentials to access an unpublished dataset (optional).
    * @returns {Promise<Dataset>}
    */
   async execute(
     datasetId: number | string,
     datasetVersionId: string | DatasetNotNumberedVersion = DatasetNotNumberedVersion.LATEST,
     includeDeaccessioned = false,
-    keepRawFields = false
+    keepRawFields = false,
+    previewUrlToken?: string
   ): Promise<Dataset> {
     return await this.datasetsRepository.getDataset(
       datasetId,
       datasetVersionId,
       includeDeaccessioned,
-      keepRawFields
+      keepRawFields,
+      previewUrlToken
     )
   }
 }

src/datasets/domain/useCases/previewUrl/CreatePreviewUrl.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '../../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../../repositories/IDatasetsRepository'
+import { PreviewUrl } from '../../models/PreviewUrl'
+
+export class CreatePreviewUrl implements UseCase<PreviewUrl> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Creates a Preview URL for the given dataset, allowing a reviewer without credentials to access its latest (unpublished) version. Requires permission to manage the dataset's permissions.
+   *
+   * @param {number | string} datasetId - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @param {boolean} [anonymizedAccess] - If true, and Anonymized Access is enabled on the installation, the Preview URL will only allow an anonymized view of the dataset (optional).
+   * @returns {Promise<PreviewUrl>}
+   */
+  async execute(datasetId: number | string, anonymizedAccess?: boolean): Promise<PreviewUrl> {
+    return await this.datasetsRepository.createPreviewUrl(datasetId, anonymizedAccess)
+  }
+}

src/datasets/domain/useCases/previewUrl/DeletePreviewUrl.ts

@@ -0,0 +1,20 @@
+import { UseCase } from '../../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../../repositories/IDatasetsRepository'
+
+export class DeletePreviewUrl implements UseCase<void> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Deletes the Preview URL for the given dataset, if one exists.
+   *
+   * @param {number | string} datasetId - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @returns {Promise<void>}
+   */
+  async execute(datasetId: number | string): Promise<void> {
+    return await this.datasetsRepository.deletePreviewUrl(datasetId)
+  }
+}

src/datasets/domain/useCases/previewUrl/GetPreviewUrl.ts

@@ -0,0 +1,21 @@
+import { UseCase } from '../../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository } from '../../repositories/IDatasetsRepository'
+import { PreviewUrl } from '../../models/PreviewUrl'
+
+export class GetPreviewUrl implements UseCase<PreviewUrl> {
+  private datasetsRepository: IDatasetsRepository
+
+  constructor(datasetsRepository: IDatasetsRepository) {
+    this.datasetsRepository = datasetsRepository
+  }
+
+  /**
+   * Returns the existing Preview URL for the given dataset, if one has been created.
+   *
+   * @param {number | string} datasetId - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
+   * @returns {Promise<PreviewUrl>}
+   */
+  async execute(datasetId: number | string): Promise<PreviewUrl> {
+    return await this.datasetsRepository.getPreviewUrl(datasetId)
+  }
+}

src/datasets/index.ts

@@ -5,6 +5,9 @@ import { CreateDataset } from './domain/useCases/CreateDataset'
 import { GetDatasetLocks } from './domain/useCases/GetDatasetLocks'
 import { GetDatasetCitation } from './domain/useCases/GetDatasetCitation'
 import { GetPrivateUrlDataset } from './domain/useCases/GetPrivateUrlDataset'
+import { CreatePreviewUrl } from './domain/useCases/previewUrl/CreatePreviewUrl'
+import { GetPreviewUrl } from './domain/useCases/previewUrl/GetPreviewUrl'
+import { DeletePreviewUrl } from './domain/useCases/previewUrl/DeletePreviewUrl'
 import { GetAllDatasetPreviews } from './domain/useCases/GetAllDatasetPreviews'
 import { MetadataFieldValidator } from './domain/useCases/validators/MetadataFieldValidator'
 import { GetDatasetUserPermissions } from './domain/useCases/GetDatasetUserPermissions'
@@ -44,6 +47,9 @@ const getDataset = new GetDataset(datasetsRepository)
 const getDatasetLocks = new GetDatasetLocks(datasetsRepository)
 const getDatasetCitation = new GetDatasetCitation(datasetsRepository)
 const getPrivateUrlDataset = new GetPrivateUrlDataset(datasetsRepository)
+const createPreviewUrl = new CreatePreviewUrl(datasetsRepository)
+const getPreviewUrl = new GetPreviewUrl(datasetsRepository)
+const deletePreviewUrl = new DeletePreviewUrl(datasetsRepository)
 const getAllDatasetPreviews = new GetAllDatasetPreviews(datasetsRepository)
 const getDatasetUserPermissions = new GetDatasetUserPermissions(datasetsRepository)
 const getDatasetSummaryFieldNames = new GetDatasetSummaryFieldNames(datasetsRepository)
@@ -96,6 +102,9 @@ export {
   getDatasetLocks,
   getDatasetCitation,
   getPrivateUrlDataset,
+  createPreviewUrl,
+  getPreviewUrl,
+  deletePreviewUrl,
   getAllDatasetPreviews,
   getDatasetUserPermissions,
   getDatasetSummaryFieldNames,
@@ -130,6 +139,7 @@ export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVer
 export { ExportedDatasetMetadata } from './domain/models/ExportedDatasetMetadata'
 export { DatasetUserPermissions } from './domain/models/DatasetUserPermissions'
 export { DatasetLock, DatasetLockType } from './domain/models/DatasetLock'
+export { PreviewUrl } from './domain/models/PreviewUrl'
 export {
   Dataset,
   DatasetLicense,