Merge remote-tracking branch 'origin/develop' into feature/configurable-uploads

# Conflicts:
#	CHANGELOG.md
#	test/functional/collections/UpdateCollectionFeaturedItems.test.ts
#	test/testHelpers/html/htmlNormalizer.ts
#	test/unit/testHelpers/htmlNormalizer.test.ts

Author: ErykKul

CHANGELOG.md

@@ -8,16 +8,6 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Added
 
-- Guestbooks: Added `editGuestbook` use case.
-- Guestbooks: Added `getGuestbookResponsesByGuestbookId` use case and repository support for retrieving paginated guestbook responses with total count 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.
-- Files: Added `getFileCitationByFormat` use case, repository method, and `FileCitationFormat` enum to support Dataverse file citation exports in `EndNote`, `RIS`, `BibTeX`, `CSL`, and `Internal` formats.
-- Datasets: Added `getDatasetReviews` use case and repository method to support Dataverse endpoint `GET /datasets/{identifier}/reviews`, for retrieving review datasets associated with a dataset by persistent id or numeric id.
-- 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`.
-- Collections: Added `setDefaultContributorRole` use case.
 - Datasets: `listDatasetTreeNode` use case and repository method backing `GET /datasets/{id}/versions/{versionId}/tree` for paginated, lazy listing of folders/files inside a dataset version. Returns `FileTreePage` with folder-first ordering, opaque keyset cursors, and per-file `downloadUrl`. The per-file `access` marker is one of `retentionExpired`, `restricted`, `embargoed`, or `public` (resolved in that order), and folder `counts` carry the matching mutually exclusive `restricted`/`embargoed`/`retentionExpired` buckets.
 - Datasets: `iterateDatasetTreeNode` async generator that walks the cursor chain so callers can consume one folder's children without driving pagination by hand.
 - Core: re-export `DataverseApiAuthMechanism` from the public surface so consumers of the standalone reusable bundles (e.g. `dv-tree-view`, `dv-uploader`) can import it without reaching into `core/...`.
@@ -32,6 +22,27 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Removed
 
+## [v2.3.0] -- 2026-10-08
+
+### Added
+
+- Datasets: Added optional `templateId` support to `createDataset` requests and `getDataset` responses.
+- Guestbooks: Added `editGuestbook` use case.
+- Guestbooks: Added `getGuestbookResponsesByGuestbookId` use case and repository support for retrieving paginated guestbook responses with total count 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.
+- Files: Added `getFileCitationByFormat` use case, repository method, and `FileCitationFormat` enum to support Dataverse file citation exports in `EndNote`, `RIS`, `BibTeX`, `CSL`, and `Internal` formats.
+- Datasets: Added `getDatasetReviews` use case and repository method to support Dataverse endpoint `GET /datasets/{identifier}/reviews`, for retrieving review datasets associated with a dataset by persistent id or numeric id.
+- 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`.
+- Datasets: Added `getDatasetVersions` use case.
+- 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`.
+- Collections: Added `setDefaultContributorRole` use case.
+
+### Changed
+
+- Files: Added an optional dataset `version` parameter to `getFileCitationByFormat` for version-specific file citation exports.
+
 ## [v2.2.0] -- 2026-04-24
 
 ### Added
@@ -59,7 +70,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Changed
 
-- Add pagination query parameters to Dataset Version Summaries and File Version Summaries use cases.
+- Add pagination query parameters to Dataset Version Summeries and File Version Summaries use cases.
 - Templates: Rename `CreateDatasetTemplateDTO` to `CreateTemplateDTO`.
 - Templates: Rename `createDatasetTemplate` repository method to `createTemplate`.
 - Templates: Rename `getDatasetTemplates` repository method to `getTemplatesByCollectionId`.

docs/useCases.md

@@ -55,6 +55,7 @@ The different use cases currently available in the package are classified below,
     - [Get User Permissions on a Dataset](#get-user-permissions-on-a-dataset)
     - [Get Differences between Two Dataset Versions](#get-differences-between-two-dataset-versions)
     - [List All Datasets](#list-all-datasets)
+    - [Get Dataset Versions](#get-dataset-versions)
     - [Get Dataset Versions Summaries](#get-dataset-versions-summaries)
     - [Get Dataset Linked Collections](#get-dataset-linked-collections)
     - [Get Dataset Available Categories](#get-dataset-available-categories)
@@ -999,6 +1000,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`.
 
+When the dataset is associated with a template, the returned `Dataset` includes the optional `templateId` field containing that template's numeric identifier.
+
 #### Get Dataset By Private URL Token
 
 Returns a [Dataset](../src/datasets/domain/models/Dataset.ts) instance, given an associated Private URL Token.
@@ -1286,6 +1289,34 @@ Note that `collectionId` is an optional parameter to filter datasets by collecti
 
 The `DatasetPreviewSubset`returned instance contains a property called `totalDatasetCount` which is necessary for pagination.
 
+#### Get Dataset Versions
+
+Returns an array of [Dataset](../src/datasets/domain/models/Dataset.ts) that contains information about every specific version.
+
+##### Example call:
+
+```typescript
+import { getDatasetVersions } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+getDatasetVersions.execute(datasetId).then((datasetVersions: DatasetVersionSubset) => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/GetDatasetVersions.ts) implementation_.
+
+- The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+- **limit**: (number) Limit for pagination.
+- **offset**: (number) Offset for pagination.
+- **excludeMetadataBlocks**: (boolean) Exclude metadata blocks (default: false).
+- Note that the **excludeFiles** parameter, which is available on Dataverse's "List Versions of a Dataset" API, is not available here. The list of files can be retrieved using the separate use case [List Files in a Dataset](#list-files-in-a-dataset).
+
 #### Get Dataset Versions Summaries
 
 Returns the total count of versions and an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.
@@ -1451,7 +1482,7 @@ createDataset.execute(datasetDTO).then((newDatasetIds: CreatedDatasetIdentifiers
 
 _See [use case](../src/datasets/domain/useCases/CreateDataset.ts) implementation_.
 
-The above example creates the new dataset in the root collection since no collection identifier is specified. If you want to create the dataset in a different collection, you must add the collection identifier as a second parameter in the use case call. If you want the dataset type to be anything other than dataset, first [check available dataset types](#get-dataset-available-dataset-types) and then add the name of the dataset type as the third parameter.
+The above example creates the new dataset in the root collection since no collection identifier is specified. If you want to create the dataset in a different collection, you must add the collection identifier as a second parameter in the use case call. If you want the dataset type to be anything other than dataset, first [check available dataset types](#get-dataset-available-dataset-types) and then add the name of the dataset type as the third parameter. To create from an applicable metadata template, set its numeric identifier as `datasetDTO.templateId`; the SDK sends it as the top-level `templateId` field in the request body.
 
 The use case returns a [CreatedDatasetIdentifiers](../src/datasets/domain/models/CreatedDatasetIdentifiers.ts) object, which includes the persistent and numeric identifiers of the created dataset.
 
@@ -2093,9 +2124,11 @@ import { FileCitationFormat, getFileCitationByFormat } from '@iqss/dataverse-cli
 
 const fileId = 3
 
-getFileCitationByFormat.execute(fileId, FileCitationFormat.BIBTEX).then((citationText: string) => {
-  /* ... */
-})
+getFileCitationByFormat
+  .execute(fileId, FileCitationFormat.BIBTEX, '1.0')
+  .then((citationText: string) => {
+    /* ... */
+  })
 
 /* ... */
 ```
@@ -2104,6 +2137,8 @@ _See [use case](../src/files/domain/useCases/GetFileCitationByFormat.ts) impleme
 
 The `fileId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
 
+The optional third parameter, `version`, selects the **dataset version** whose file metadata is used in the citation. It accepts a numbered version such as `1.0`, or `DatasetNotNumberedVersion.DRAFT`, `LATEST`, or `LATEST_PUBLISHED` (`:draft`, `:latest`, `:latest-published`). When omitted, no version query parameter is sent, it will return the `:latest`.
+
 The `format` parameter must be one of the available [FileCitationFormat](../src/files/domain/models/FileCitationFormat.ts) enum values: `FileCitationFormat.ENDNOTE`, `FileCitationFormat.RIS`, `FileCitationFormat.BIBTEX`, `FileCitationFormat.CSL`, or `FileCitationFormat.INTERNAL`.
 
 #### Get File Counts in a Dataset

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqss/dataverse-client-javascript",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Dataverse API wrapper package for JavaScript/TypeScript-based applications",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,6 +43,7 @@
   "homepage": "https://github.com/IQSS/dataverse-client-javascript#readme",
   "devDependencies": {
     "@types/jest": "^29.5.12",
+    "@types/jsdom": "^20.0.1",
     "@typescript-eslint/eslint-plugin": "5.51.0",
     "@typescript-eslint/parser": "5.51.0",
     "@web-std/file": "3.0.3",
@@ -56,6 +57,7 @@
     "husky": "9.1.7",
     "jest": "^29.4.3",
     "jest-environment-jsdom": "29.7.0",
+    "jsdom": "^20.0.3",
     "prettier": "2.8.4",
     "testcontainers": "^10.11.0",
     "ts-jest": "^29.0.5",

package.json

@@ -142,7 +142,7 @@ export class AccessRepository extends ApiRepository implements IAccessRepository
     return fetchHeaders
   }
 
-  private async parseResponseBody(response: Response): Promise<any> {
+  private async parseResponseBody(response: Response): Promise<FetchResponseBody | string> {
     const contentType = response.headers.get('content-type') ?? ''
 
     if (contentType.includes('application/json')) {
@@ -158,7 +158,7 @@ export class AccessRepository extends ApiRepository implements IAccessRepository
     }
   }
 
-  private buildFetchErrorMessage(status: number, responseData: any): string {
+  private buildFetchErrorMessage(status: number, responseData: FetchResponseBody | string): string {
     const message =
       typeof responseData === 'string'
         ? responseData
@@ -167,8 +167,8 @@ export class AccessRepository extends ApiRepository implements IAccessRepository
     return `[${status}] ${message}`
   }
 
-  private getSignedUrlOrThrow(responseData: any): string {
-    const signedUrl = responseData?.data?.signedUrl
+  private getSignedUrlOrThrow(responseData: FetchResponseBody | string): string {
+    const signedUrl = typeof responseData === 'string' ? undefined : responseData?.data?.signedUrl
 
     if (typeof signedUrl !== 'string' || signedUrl.length === 0) {
       throw new WriteError('Missing signedUrl in access download response.')
@@ -177,3 +177,11 @@ export class AccessRepository extends ApiRepository implements IAccessRepository
     return signedUrl
   }
 }
+
+interface FetchResponseBody {
+  message?: string
+  data?: {
+    message?: string
+    signedUrl?: unknown
+  }
+}

src/access/infra/repositories/AccessRepository.ts

@@ -2,6 +2,7 @@ import { DatasetLicense } from '../models/Dataset'
 
 export interface DatasetDTO {
   license?: DatasetLicense
+  templateId?: number
   metadataBlockValues: DatasetMetadataBlockValuesDTO[]
 }
 

src/datasets/domain/dtos/DatasetDTO.ts

@@ -13,6 +13,7 @@ export interface Dataset {
   publicationDate?: string
   citationDate?: string
   guestbookId?: number
+  templateId?: number
   metadataBlocks: DatasetMetadataBlocks
   isPartOf: DvObjectOwnerNode
   datasetType?: string

src/datasets/domain/models/Dataset.ts

@@ -0,0 +1,5 @@
+import { Dataset, DatasetMetadataBlocks } from './Dataset'
+
+export interface DatasetVersionSubset {
+  versions: Array<Omit<Dataset, 'metadataBlocks'> & { metadataBlocks?: DatasetMetadataBlocks }>
+}

src/datasets/domain/models/DatasetVersionSubset.ts

@@ -9,6 +9,7 @@ import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
 import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSubset } from '../models/DatasetVersionSubset'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
@@ -90,6 +91,13 @@ export interface IDatasetsRepository {
     limit?: number,
     offset?: number
   ): Promise<DatasetVersionSummarySubset>
+  getDatasetVersions(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number,
+    excludeMetadataBlocks?: boolean,
+    keepRawFields?: boolean
+  ): Promise<DatasetVersionSubset>
   deleteDatasetDraft(datasetId: number | string): Promise<void>
   linkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>
   unlinkDataset(datasetId: number | string, collectionIdOrAlias: number | string): Promise<void>

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -18,7 +18,7 @@ export class CreateDataset extends DatasetWriteUseCase<CreatedDatasetIdentifiers
   /**
    * Creates a new Dataset in a collection, given a DatasetDTO object and an optional collection identifier, which defaults to :root.
    *
-   * @param {DatasetDTO} [newDataset] - DatasetDTO object including the new dataset metadata field values for each metadata block.
+   * @param {DatasetDTO} [newDataset] - DatasetDTO object including the new dataset metadata field values for each metadata block and, optionally, the template ID to apply.
    * @param {string} [collectionId] - Specifies the collection identifier where the new dataset should be created (optional, defaults to :root).
    * @param {string} [datasetType] - Specifies the dataset type (optional, when omitted, defaults to "dataset").
    * @returns {Promise<CreatedDatasetIdentifiers>}