Merge origin/develop: union tree-listing additions with exportDatasetMetadata and setDefaultContributorRole; drop duplicated DatasetNotNumberedVersion import

Author: ErykKul

AGENTS.md

@@ -14,8 +14,10 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - 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/...`.

CHANGELOG.md

@@ -29,6 +29,7 @@ The different use cases currently available in the package are classified below,
     - [Update Collection Featured Items](#update-collection-featured-items)
     - [Delete Collection Featured Items](#delete-collection-featured-items)
     - [Delete a Collection Featured Item](#delete-a-collection-featured-item)
+    - [Set Default Contributor Role](#set-default-contributor-role)
 - [Templates](#Templates)
   - [Templates read use cases](#templates-read-use-cases)
     - [Get a Template](#get-a-template)
@@ -46,6 +47,8 @@ The different use cases currently available in the package are classified below,
     - [Get a Dataset](#get-a-dataset)
     - [Get Dataset By Private URL Token](#get-dataset-by-private-url-token)
     - [Get Dataset Citation Text](#get-dataset-citation-text)
+    - [Get Dataset Citation In Other Formats](#get-dataset-citation-in-other-formats)
+    - [Export Dataset Metadata](#export-dataset-metadata)
     - [Get Dataset Citation Text By Private URL Token](#get-dataset-citation-text-by-private-url-token)
     - [Get Dataset Locks](#get-dataset-locks)
     - [Get Dataset Summary Field Names](#get-dataset-summary-field-names)
@@ -732,6 +735,27 @@ deleteCollectionFeaturedItem.execute(featuredItemId)
 
 _See [use case](../src/collections/domain/useCases/DeleteCollectionFeaturedItem.ts)_ definition.
 
+#### Set Default Contributor Role
+
+Sets the default contributor role of a collection, given a collection identifier and a role alias.
+
+##### Example call:
+
+```typescript
+import { setDefaultContributorRole } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const collectionIdOrAlias = 12345
+const roleAlias = 'curator'
+
+setDefaultContributorRole.execute(collectionIdOrAlias, roleAlias)
+
+/* ... */
+```
+
+_See [use case](../src/collections/domain/useCases/SetDefaultContributorRole.ts)_ definition.
+
 ## Templates
 
 ### Templates Read Use Cases
@@ -1055,6 +1079,37 @@ The `datasetId` parameter can be a string, for persistent identifiers, or a numb
 
 There is an optional third parameter called `includeDeaccessioned`, which indicates whether to consider deaccessioned versions or not in the dataset search. If not set, the default value is `false`.
 
+#### Export Dataset Metadata
+
+Exports dataset metadata in a specified metadata export format.
+
+##### Example call:
+
+```typescript
+import {
+  exportDatasetMetadata,
+  DatasetNotNumberedVersion,
+  ExportedDatasetMetadata
+} from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+const exporter = 'ddi'
+
+exportDatasetMetadata
+  .execute(datasetId, exporter, DatasetNotNumberedVersion.DRAFT)
+  .then((metadata: ExportedDatasetMetadata) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/ExportDatasetMetadata.ts) implementation_.
+
+The `datasetId` parameter can be a string for persistent identifiers or a number for numeric identifiers. The optional `version` parameter accepts `DatasetNotNumberedVersion.LATEST_PUBLISHED` or `DatasetNotNumberedVersion.DRAFT`. If not set, Dataverse defaults to `DatasetNotNumberedVersion.LATEST_PUBLISHED`. Draft exports require configured authentication with access to the draft.
+
 #### Get Dataset Citation Text By Private URL Token
 
 Returns the Dataset citation text, given an associated Private URL Token.

docs/useCases.md

@@ -14,6 +14,7 @@ import { CollectionSummary } from '../models/CollectionSummary'
 import { AllowedStorageDrivers } from '../models/AllowedStorageDrivers'
 import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { LinkingObjectType } from '../useCases/GetCollectionsForLinking'
+import { RoleAlias } from '../../../roles/domain/models/RoleAlias'
 
 export interface ICollectionsRepository {
   getCollection(collectionIdOrAlias: number | string): Promise<Collection>
@@ -39,6 +40,10 @@ export interface ICollectionsRepository {
   getCollectionUserPermissions(
     collectionIdOrAlias: number | string
   ): Promise<CollectionUserPermissions>
+  setDefaultContributorRole(
+    collectionIdOrAlias: number | string,
+    roleAlias: RoleAlias | string
+  ): Promise<void>
   getCollectionItems(
     collectionId?: string,
     limit?: number,

package-lock.json

@@ -0,0 +1,30 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+import { ROOT_COLLECTION_ID } from '../models/Collection'
+import { RoleAlias } from '../../../roles/domain/models/RoleAlias'
+
+export class SetDefaultContributorRole implements UseCase<void> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Sets the default Role that is assigned to contributors in the given collection.
+   *
+   * @param {number | string} [collectionIdOrAlias = ':root'] - A generic collection identifier, which can be either a string (for queries by CollectionAlias), or a number (for queries by CollectionId)
+   * If this parameter is not set, the default value is: ':root'
+   * @param {RoleAlias | string} [roleAlias] - The alias of the role to be assigned
+   * @returns {Promise<void>}
+   */
+  async execute(
+    collectionIdOrAlias: number | string = ROOT_COLLECTION_ID,
+    roleAlias: RoleAlias | string
+  ): Promise<void> {
+    return await this.collectionsRepository.setDefaultContributorRole(
+      collectionIdOrAlias,
+      roleAlias
+    )
+  }
+}

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -20,6 +20,7 @@ import { GetCollectionsForLinking } from './domain/useCases/GetCollectionsForLin
 import { SetCollectionStorageDriver } from './domain/useCases/SetCollectionStorageDriver'
 import { DeleteCollectionStorageDriver } from './domain/useCases/DeleteCollectionStorageDriver'
 import { GetAllowedCollectionStorageDrivers } from './domain/useCases/GetAllowedCollectionStorageDrivers'
+import { SetDefaultContributorRole } from './domain/useCases/SetDefaultContributorRole'
 
 const collectionsRepository = new CollectionsRepository()
 
@@ -46,6 +47,7 @@ const deleteCollectionStorageDriver = new DeleteCollectionStorageDriver(collecti
 const getAllowedCollectionStorageDrivers = new GetAllowedCollectionStorageDrivers(
   collectionsRepository
 )
+const setDefaultContributorRole = new SetDefaultContributorRole(collectionsRepository)
 
 export {
   getCollection,
@@ -68,7 +70,8 @@ export {
   getCollectionsForLinking,
   setCollectionStorageDriver,
   deleteCollectionStorageDriver,
-  getAllowedCollectionStorageDrivers
+  getAllowedCollectionStorageDrivers,
+  setDefaultContributorRole
 }
 export { Collection, CollectionInputLevel, CollectionTheme } from './domain/models/Collection'
 export { CollectionFacet } from './domain/models/CollectionFacet'

src/collections/domain/useCases/SetDefaultContributorRole.ts

@@ -42,6 +42,7 @@ import { CollectionSummary } from '../../domain/models/CollectionSummary'
 import { AllowedStorageDrivers } from '../../domain/models/AllowedStorageDrivers'
 import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { LinkingObjectType } from '../../domain/useCases/GetCollectionsForLinking'
+import { RoleAlias } from '../../../roles/domain/models/RoleAlias'
 
 export interface NewCollectionRequestPayload {
   alias: string
@@ -225,6 +226,20 @@ export class CollectionsRepository extends ApiRepository implements ICollections
       })
   }
 
+  public async setDefaultContributorRole(
+    collectionIdOrAlias: number | string,
+    roleAlias: RoleAlias | string
+  ): Promise<void> {
+    return this.doPut(
+      `/${this.collectionsResourceName}/${collectionIdOrAlias}/defaultContributorRole/${roleAlias}`,
+      {}
+    )
+      .then(() => undefined)
+      .catch((error) => {
+        throw error
+      })
+  }
+
   public async getCollectionItems(
     collectionId?: string,
     limit?: number,

src/collections/index.ts

@@ -0,0 +1,4 @@
+export type ExportedDatasetMetadata = {
+  content: string
+  contentType: string
+}

src/collections/infra/repositories/CollectionsRepository.ts

@@ -20,6 +20,8 @@ import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { DatasetUploadLimits } from '../models/DatasetUploadLimits'
 import { DatasetReview } from '../models/DatasetReview'
 import { FileTreePage, FileTreeInclude, FileTreeOrder } from '../models/FileTreePage'
+import { ExportedDatasetMetadata } from '../models/ExportedDatasetMetadata'
+import { DatasetNotNumberedVersion } from '../models/DatasetNotNumberedVersion'
 
 export interface ListDatasetTreeNodeParams {
   datasetId: number | string
@@ -99,6 +101,11 @@ export interface IDatasetsRepository {
     format: CitationFormat,
     includeDeaccessioned?: boolean
   ): Promise<FormattedCitation>
+  exportDatasetMetadata(
+    datasetId: number | string,
+    exporter: string,
+    version?: DatasetNotNumberedVersion.LATEST_PUBLISHED | DatasetNotNumberedVersion.DRAFT
+  ): Promise<ExportedDatasetMetadata>
   getDatasetAvailableDatasetTypes(): Promise<DatasetType[]>
   getDatasetAvailableDatasetType(datasetTypeId: number | string): Promise<DatasetType>
   addDatasetType(datasetType: DatasetTypeDTO): Promise<DatasetType>