Merge branch 'develop' into updateTermsOfAccess

Author: ChengShi-1

CHANGELOG.md

@@ -9,11 +9,14 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 ### Added
 
 - New Use Case: [Get Collections For Linking Use Case](./docs/useCases.md#get-collections-for-linking).
+- New Use Case: [Create a Dataset Template](./docs/useCases.md#create-a-dataset-template) under Collections.
 
 - New Use Case: [Update Terms of Access](./docs/useCases.md#update-terms-of-access).
 
 ### Changed
 
+- Add pagination query parameters to Dataset Version Summeries and File Version Summaries use cases
+
 ### Fixed
 
 ### Removed

docs/useCases.md

@@ -25,6 +25,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)
+    - [Create a Dataset Template](#create-a-dataset-template)
 - [Datasets](#Datasets)
   - [Datasets read use cases](#datasets-read-use-cases)
     - [Get a Dataset](#get-a-dataset)
@@ -567,6 +568,41 @@ deleteCollectionFeaturedItem.execute(featuredItemId)
 
 _See [use case](../src/collections/domain/useCases/DeleteCollectionFeaturedItem.ts)_ definition.
 
+#### Create a Dataset Template
+
+Creates a dataset template for a given Dataverse collection id or alias.
+
+##### Example call:
+
+```typescript
+import { createDatasetTemplate } from '@iqss/dataverse-client-javascript'
+import { TemplateCreateDTO } from '@iqss/dataverse-client-javascript'
+
+const collectionAlias = ':root'
+const template: TemplateCreateDTO = {
+  name: 'Dataverse template',
+  isDefault: true,
+  fields: [
+    {
+      typeName: 'author',
+      typeClass: 'compound',
+      multiple: true,
+      value: [
+        {
+          authorName: { typeName: 'authorName', value: 'Belicheck, Bill' },
+          authorAffiliation: { typeName: 'authorIdentifierScheme', value: 'ORCID' }
+        }
+      ]
+    }
+  ],
+  instructions: [{ instructionField: 'author', instructionText: 'The author data' }]
+}
+
+await createDatasetTemplate.execute(template, collectionAlias)
+```
+
+_See [use case](../src/collections/domain/useCases/CreateDatasetTemplate.ts) implementation_.
+
 ## Datasets
 
 ### Datasets Read Use Cases
@@ -836,7 +872,7 @@ The `DatasetPreviewSubset`returned instance contains a property called `totalDat
 
 #### Get Dataset Versions Summaries
 
-Returns an array of [DatasetVersionSummaryInfo](../src/datasets/domain/models/DatasetVersionSummaryInfo.ts) that contains information about what changed in every specific version.
+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.
 
 ##### Example call:
 
@@ -849,7 +885,7 @@ const datasetId = 'doi:10.77777/FK2/AAAAAA'
 
 getDatasetVersionsSummaries
   .execute(datasetId)
-  .then((datasetVersionsSummaries: DatasetVersionSummaryInfo[]) => {
+  .then((datasetVersionsSummaries: DatasetVersionSummarySubset) => {
     /* ... */
   })
 
@@ -858,7 +894,9 @@ getDatasetVersionsSummaries
 
 _See [use case](../src/datasets/domain/useCases/GetDatasetVersionsSummaries.ts) implementation_.
 
-The `datasetId` parameter can be a string, for persistent identifiers, or a number, for numeric identifiers.
+- 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.
 
 #### Get Dataset Linked Collections
 
@@ -1996,7 +2034,7 @@ The `fileId` parameter can be a string, for persistent identifiers, or a number,
 
 #### Get File Version Summaries
 
-Get the file versions summaries, return a list of summaries for each version
+Get the file versions summaries, return a total count of versions and a list of summaries for each version
 
 ##### Example call:
 
@@ -2007,7 +2045,7 @@ import { getFileVersionSummaries } from '@iqss/dataverse-client-javascript'
 
 const fileId = 1
 
-getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionSummaryInfo[]) => {
+getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionSummarySubset) => {
   /* ... */
 })
 
@@ -2016,6 +2054,9 @@ getFileVersionSummaries.execute(fileId).then((fileVersionSummaries: fileVersionS
 
 _See [use case](../src/files/domain/useCases/GetFileVersionSummaries.ts) implementation_.
 
+- **limit**: (number) Limit for pagination.
+- **offset**: (number) Offset for pagination.
+
 ## Metadata Blocks
 
 ### Metadata Blocks read use cases

src/collections/domain/dtos/CreateDatasetTemplateDTO.ts

@@ -0,0 +1,45 @@
+import { MetadataFieldTypeClass } from '../../../metadataBlocks/domain/models/MetadataBlock'
+
+export interface CreateDatasetTemplateDTO {
+  name: string
+  isDefault?: boolean
+  fields?: TemplateFieldDTO[]
+  instructions?: TemplateInstructionDTO[]
+}
+
+export interface TemplateFieldDTO {
+  typeName: string
+  multiple: boolean
+  typeClass?: MetadataFieldTypeClass
+  value?: TemplateFieldValueDTO[]
+}
+
+export interface TemplateFieldValueDTO {
+  [key: string]:
+    | TemplateFieldValuePrimitiveDTO
+    | TemplateFieldValueCompoundDTO
+    | TemplateFieldValueControlledVocabularyDTO
+}
+
+export interface TemplateFieldValuePrimitiveDTO {
+  typeName: string
+  typeClass: MetadataFieldTypeClass.Primitive
+  value: string | string[]
+}
+
+export interface TemplateFieldValueCompoundDTO {
+  typeName: string
+  typeClass: MetadataFieldTypeClass.Compound
+  value: TemplateFieldValueDTO[]
+}
+
+export interface TemplateFieldValueControlledVocabularyDTO {
+  typeName: string
+  typeClass: MetadataFieldTypeClass.ControlledVocabulary
+  value: string
+}
+
+export interface TemplateInstructionDTO {
+  instructionField: string
+  instructionText: string
+}

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -12,6 +12,7 @@ import { CollectionItemType } from '../../../collections/domain/models/Collectio
 import { CollectionLinks } from '../models/CollectionLinks'
 import { CollectionSummary } from '../models/CollectionSummary'
 import { LinkingObjectType } from '../useCases/GetCollectionsForLinking'
+import { CreateDatasetTemplateDTO } from '../dtos/CreateDatasetTemplateDTO'
 
 export interface ICollectionsRepository {
   getCollection(collectionIdOrAlias: number | string): Promise<Collection>
@@ -68,4 +69,8 @@ export interface ICollectionsRepository {
     searchTerm: string,
     alreadyLinked: boolean
   ): Promise<CollectionSummary[]>
+  createDatasetTemplate(
+    collectionIdOrAlias: number | string,
+    template: CreateDatasetTemplateDTO
+  ): Promise<void>
 }

src/collections/domain/useCases/CreateDatasetTemplate.ts

@@ -0,0 +1,27 @@
+import { ROOT_COLLECTION_ID } from '../models/Collection'
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+import { CreateDatasetTemplateDTO } from '../dtos/CreateDatasetTemplateDTO'
+
+export class CreateDatasetTemplate implements UseCase<void> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Creates a Dataset Template in the specified collection.
+   *
+   * @param {CreateDatasetTemplateDTO} template - Template definition payload.
+   * @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'.
+   * @returns {Promise<void>}
+   */
+  async execute(
+    template: CreateDatasetTemplateDTO,
+    collectionIdOrAlias: number | string = ROOT_COLLECTION_ID
+  ): Promise<void> {
+    return await this.collectionsRepository.createDatasetTemplate(collectionIdOrAlias, template)
+  }
+}

src/collections/index.ts

@@ -16,6 +16,7 @@ import { LinkCollection } from './domain/useCases/LinkCollection'
 import { UnlinkCollection } from './domain/useCases/UnlinkCollection'
 import { GetCollectionLinks } from './domain/useCases/GetCollectionLinks'
 import { GetCollectionsForLinking } from './domain/useCases/GetCollectionsForLinking'
+import { CreateDatasetTemplate } from './domain/useCases/CreateDatasetTemplate'
 
 const collectionsRepository = new CollectionsRepository()
 
@@ -36,6 +37,7 @@ const linkCollection = new LinkCollection(collectionsRepository)
 const unlinkCollection = new UnlinkCollection(collectionsRepository)
 const getCollectionLinks = new GetCollectionLinks(collectionsRepository)
 const getCollectionsForLinking = new GetCollectionsForLinking(collectionsRepository)
+const createDatasetTemplate = new CreateDatasetTemplate(collectionsRepository)
 
 export {
   getCollection,
@@ -54,7 +56,8 @@ export {
   linkCollection,
   unlinkCollection,
   getCollectionLinks,
-  getCollectionsForLinking
+  getCollectionsForLinking,
+  createDatasetTemplate
 }
 export { Collection, CollectionInputLevel } from './domain/models/Collection'
 export { CollectionFacet } from './domain/models/CollectionFacet'

src/collections/infra/repositories/CollectionsRepository.ts

@@ -40,6 +40,7 @@ import { ReadError } from '../../../core/domain/repositories/ReadError'
 import { CollectionLinks } from '../../domain/models/CollectionLinks'
 import { CollectionSummary } from '../../domain/models/CollectionSummary'
 import { LinkingObjectType } from '../../domain/useCases/GetCollectionsForLinking'
+import { CreateDatasetTemplateDTO } from '../../domain/dtos/CreateDatasetTemplateDTO'
 
 export interface NewCollectionRequestPayload {
   alias: string
@@ -528,4 +529,18 @@ export class CollectionsRepository extends ApiRepository implements ICollections
         throw error
       })
   }
+
+  public async createDatasetTemplate(
+    collectionIdOrAlias: number | string,
+    template: CreateDatasetTemplateDTO
+  ): Promise<void> {
+    return this.doPost(
+      `/${this.collectionsResourceName}/${collectionIdOrAlias}/templates`,
+      template
+    )
+      .then(() => undefined)
+      .catch((error) => {
+        throw error
+      })
+  }
 }

src/datasets/domain/models/DatasetVersionSummaryInfo.ts

@@ -6,6 +6,11 @@ export interface DatasetVersionSummaryInfo {
   publishedOn?: string
 }
 
+export interface DatasetVersionSummarySubset {
+  summaries: DatasetVersionSummaryInfo[]
+  totalCount: number
+}
+
 export type DatasetVersionSummary = {
   [key: string]:
     | SummaryUpdates

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -8,7 +8,7 @@ import { DatasetDeaccessionDTO } from '../dtos/DatasetDeaccessionDTO'
 import { MetadataBlock } from '../../../metadataBlocks'
 import { DatasetVersionDiff } from '../models/DatasetVersionDiff'
 import { DatasetDownloadCount } from '../models/DatasetDownloadCount'
-import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
 import { DatasetLinkedCollection } from '../models/DatasetLinkedCollection'
 import { CitationFormat } from '../models/CitationFormat'
 import { FormattedCitation } from '../models/FormattedCitation'
@@ -67,7 +67,11 @@ export interface IDatasetsRepository {
     datasetId: number | string,
     includeMDC?: boolean
   ): Promise<DatasetDownloadCount>
-  getDatasetVersionsSummaries(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]>
+  getDatasetVersionsSummaries(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<DatasetVersionSummarySubset>
   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/useCases/GetDatasetVersionsSummaries.ts

@@ -1,8 +1,8 @@
 import { UseCase } from '../../../core/domain/useCases/UseCase'
-import { DatasetVersionSummaryInfo } from '../models/DatasetVersionSummaryInfo'
+import { DatasetVersionSummarySubset } from '../models/DatasetVersionSummaryInfo'
 import { IDatasetsRepository } from '../repositories/IDatasetsRepository'
 
-export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummaryInfo[]> {
+export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummarySubset> {
   private datasetsRepository: IDatasetsRepository
 
   constructor(datasetsRepository: IDatasetsRepository) {
@@ -14,9 +14,15 @@ export class GetDatasetVersionsSummaries implements UseCase<DatasetVersionSummar
    * Draft versions will only be available to users who have permission to view unpublished drafts.
    *
    * @param {number | string} [datasetId] - The dataset identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
-   * @returns {Promise<DatasetVersionSummaryInfo[]>} - An array of DatasetVersionSummaryInfo.
+   * @param {number} [limit] - Limit for pagination (optional).
+   * @param {number} [offset] - Offset for pagination (optional).
+   * @returns {Promise<DatasetVersionSummarySubset>} - A DatasetVersionSummarySubset containing the summaries and total count.
    */
-  async execute(datasetId: number | string): Promise<DatasetVersionSummaryInfo[]> {
-    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId)
+  async execute(
+    datasetId: number | string,
+    limit?: number,
+    offset?: number
+  ): Promise<DatasetVersionSummarySubset> {
+    return await this.datasetsRepository.getDatasetVersionsSummaries(datasetId, limit, offset)
   }
 }