feat: methods and use cases

Author: g-saracca

docs/useCases.md

@@ -16,6 +16,7 @@ The different use cases currently available in the package are classified below,
     - [List All Collection Items](#list-all-collection-items)
     - [List My Data Collection Items](#list-my-data-collection-items)
     - [Get Collection Featured Items](#get-collection-featured-items)
+    - [Get Collection Dataset Templates](#get-collection-dataset-templates)
   - [Collections write use cases](#collections-write-use-cases)
     - [Create a Collection](#create-a-collection)
     - [Update a Collection](#update-a-collection)
@@ -321,6 +322,26 @@ The `collectionIdOrAlias` is a generic collection identifier, which can be eithe
 
 If no collection identifier is specified, the default collection identifier; `:root` will be used. If you want to search for a different collection, you must add the collection identifier as a parameter in the use case call.
 
+#### Get Collection Dataset Templates
+
+Returns a [CollectionDatasetTemplate](../src/collections/domain/models/CollectionDatasetTemplate.ts) array containing the dataset templates of the requested collection, given the collection identifier or alias.
+
+##### Example call:
+
+```typescript
+import { getCollectionDatasetTemplates } from '@iqss/dataverse-client-javascript'
+
+const collectionIdOrAlias = 12345
+
+getCollectionDatasetTemplates
+  .execute(collectionIdOrAlias)
+  .then((datasetTemplates: CollectionDatasetTemplate[]) => {
+    /* ... */
+  })
+```
+
+_See [use case](../src/collections/domain/useCases/GetCollectionDatasetTemplates.ts)_ definition.
+
 ### Collections Write Use Cases
 
 #### Create a Collection

src/collections/domain/models/CollectionDatasetTemplate.ts

@@ -0,0 +1,28 @@
+import { DatasetLicense, DatasetMetadataFieldValue, TermsOfUse } from '../../../datasets'
+
+export interface CollectionDatasetTemplate {
+  id: number
+  name: string
+  alias: string
+  isDefault: boolean
+  usageCount: number
+  createTime: string
+  createDate: string
+  // 👇 From Edit Template Metadata
+  datasetFields: DatasetFields
+  instructions: DatasetTemplateInstruction[]
+  // 👇 From Edit Template Terms
+  termsOfUse: TermsOfUse
+  license?: DatasetLicense // This license property is going to be present if not custom terms are added in the UI
+}
+
+type DatasetFields = Record<string, DatasetFieldInfo>
+interface DatasetFieldInfo {
+  displayName: string
+  name: string
+  fields: DatasetMetadataFieldValue[]
+}
+export interface DatasetTemplateInstruction {
+  instructionField: string
+  instructionText: string
+}

src/collections/domain/repositories/ICollectionsRepository.ts

@@ -10,6 +10,7 @@ import { CollectionUserPermissions } from '../models/CollectionUserPermissions'
 import { PublicationStatus } from '../../../core/domain/models/PublicationStatus'
 import { CollectionItemType } from '../../../collections/domain/models/CollectionItemType'
 import { CollectionLinks } from '../models/CollectionLinks'
+import { CollectionDatasetTemplate } from '../models/CollectionDatasetTemplate'
 
 export interface ICollectionsRepository {
   getCollection(collectionIdOrAlias: number | string): Promise<Collection>
@@ -60,5 +61,7 @@ export interface ICollectionsRepository {
     linkingCollectionIdOrAlias: number | string
   ): Promise<void>
   getCollectionLinks(collectionIdOrAlias: number | string): Promise<CollectionLinks>
-  getDatasetTemplates(collectionIdOrAlias: number | string): Promise<unknown>
+  getCollectionDatasetTemplates(
+    collectionIdOrAlias: number | string
+  ): Promise<CollectionDatasetTemplate[]>
 }

src/collections/domain/useCases/GetCollectionDatasetTemplates.ts

@@ -0,0 +1,25 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ICollectionsRepository } from '../repositories/ICollectionsRepository'
+import { ROOT_COLLECTION_ID } from '../models/Collection'
+import { CollectionDatasetTemplate } from '../models/CollectionDatasetTemplate'
+
+export class GetCollectionDatasetTemplates implements UseCase<CollectionDatasetTemplate[]> {
+  private collectionsRepository: ICollectionsRepository
+
+  constructor(collectionsRepository: ICollectionsRepository) {
+    this.collectionsRepository = collectionsRepository
+  }
+
+  /**
+   * Returns a CollectionDatasetTemplate array containing the dataset templates of the requested collection, given the collection identifier or alias.
+   *
+   * @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<CollectionDatasetTemplate[]>}
+   */
+  async execute(
+    collectionIdOrAlias: number | string = ROOT_COLLECTION_ID
+  ): Promise<CollectionDatasetTemplate[]> {
+    return await this.collectionsRepository.getCollectionDatasetTemplates(collectionIdOrAlias)
+  }
+}

src/collections/index.ts

@@ -15,6 +15,7 @@ import { DeleteCollectionFeaturedItem } from './domain/useCases/DeleteCollection
 import { LinkCollection } from './domain/useCases/LinkCollection'
 import { UnlinkCollection } from './domain/useCases/UnlinkCollection'
 import { GetCollectionLinks } from './domain/useCases/GetCollectionLinks'
+import { GetCollectionDatasetTemplates } from './domain/useCases/GetCollectionDatasetTemplates'
 
 const collectionsRepository = new CollectionsRepository()
 
@@ -34,6 +35,7 @@ const deleteCollectionFeaturedItem = new DeleteCollectionFeaturedItem(collection
 const linkCollection = new LinkCollection(collectionsRepository)
 const unlinkCollection = new UnlinkCollection(collectionsRepository)
 const getCollectionLinks = new GetCollectionLinks(collectionsRepository)
+const getCollectionDatasetTemplates = new GetCollectionDatasetTemplates(collectionsRepository)
 
 export {
   getCollection,
@@ -51,7 +53,8 @@ export {
   deleteCollectionFeaturedItem,
   linkCollection,
   unlinkCollection,
-  getCollectionLinks
+  getCollectionLinks,
+  getCollectionDatasetTemplates
 }
 export { Collection, CollectionInputLevel } from './domain/models/Collection'
 export { CollectionFacet } from './domain/models/CollectionFacet'

src/collections/infra/repositories/CollectionsRepository.ts

@@ -1,3 +1,4 @@
+import { AxiosResponse } from 'axios'
 import { ApiRepository } from '../../../core/infra/repositories/ApiRepository'
 import { ICollectionsRepository } from '../../domain/repositories/ICollectionsRepository'
 import {
@@ -38,6 +39,9 @@ import { ApiConstants } from '../../../core/infra/repositories/ApiConstants'
 import { PublicationStatus } from '../../../core/domain/models/PublicationStatus'
 import { ReadError } from '../../../core/domain/repositories/ReadError'
 import { CollectionLinks } from '../../domain/models/CollectionLinks'
+import { CollectionDatasetTemplatePayload } from './transformers/CollectionDatasetTemplatePayload'
+import { transformCollectionDatasetTemplatePayloadToCollectionDatasetTemplate } from './transformers/collectionDatasetTemplateTransformer'
+import { CollectionDatasetTemplate } from '../../domain/models/CollectionDatasetTemplate'
 
 export interface NewCollectionRequestPayload {
   alias: string
@@ -489,9 +493,13 @@ export class CollectionsRepository extends ApiRepository implements ICollections
       })
   }
 
-  public async getDatasetTemplates(collectionIdOrAlias: number | string): Promise<unknown> {
+  public async getCollectionDatasetTemplates(
+    collectionIdOrAlias: number | string
+  ): Promise<CollectionDatasetTemplate[]> {
     return this.doGet(`/${this.collectionsResourceName}/${collectionIdOrAlias}/templates`, true)
-      .then((response) => response.data.data)
+      .then((response: AxiosResponse<{ data: CollectionDatasetTemplatePayload[] }>) =>
+        transformCollectionDatasetTemplatePayloadToCollectionDatasetTemplate(response.data.data)
+      )
       .catch((error) => {
         throw error
       })

src/collections/infra/repositories/transformers/CollectionDatasetTemplatePayload.ts

@@ -1,72 +1,64 @@
-// TODO:ME - Adding custom terms makes the get dataset templates endpoint throw internal server error
+import { MetadataFieldPayload } from '../../../../datasets/infra/repositories/transformers/DatasetPayload'
 
 export interface CollectionDatasetTemplatePayload {
   id: number
   name: string
+  dataverseAlias: string
   isDefault: boolean
   usageCount: number
   createTime: string
   createDate: string
-  termsOfUseAndAccess: TermsOfUseAndAccess
-  datasetFields: DatasetFields
+  // 👇 From Edit Template Metadata
+  datasetFields: DatasetFieldsPayload
   instructions: Instruction[]
-  dataverseAlias: string
+  // 👇 From Edit Template Terms
+  termsOfUseAndAccess: {
+    id: number
+    fileAccessRequest: boolean
+    // This license property is going to be present if not custom terms are added in the UI
+    license?: {
+      id: number
+      name: string
+      shortDescription: string
+      uri: string
+      iconUrl?: string
+      active: boolean
+      isDefault: boolean
+      sortOrder: number
+      rightsIdentifier: string
+      rightsIdentifierScheme?: string
+      schemeUri: string
+      languageCode: string
+    }
+    // Below fields are going to be present if are added in "Restricted Files + Terms of Access"
+    termsOfAccess?: string // This is terms of access for restricted files in the JSF UI
+    dataAccessPlace?: string
+    originalArchive?: string
+    availabilityStatus?: string
+    sizeOfCollection?: string
+    studyCompletion?: string
+    contactForAccess?: string
+    // Below fields are going to be present if custom terms are added in the UI, they will be mapped and grouped under customTerms
+    termsOfUse?: string
+    confidentialityDeclaration?: string
+    specialPermissions?: string
+    restrictions?: string
+    citationRequirements?: string
+    depositorRequirements?: string
+    conditions?: string
+    disclaimer?: string
+  }
 }
 
-export interface TermsOfUseAndAccess {
-  id: number
-  license: License
-  // Below fields are going to be present if are added in "Restricted Files + Terms of Access"
-  termsOfAccess?: string // This is terms of access for restricted files in the JSF UI
-  dataAccessPlace?: string
-  originalArchive?: string
-  availabilityStatus?: string
-  sizeOfCollection?: string
-  studyCompletion?: string
-  // Below fields are going to be present if custom terms are added in the JSF UI
-  termsOfUse?: string
-  confidentialityDeclaration?: string
-  specialPermissions?: string
-  restrictions?: string
-  citationRequirements?: string
-  depositorRequirements?: string
-  conditions?: string
-  disclaimer?: string
-}
+type DatasetFieldsPayload = Record<string, DatasetFieldInfoPayload>
 
-export interface License {
-  id: number
-  name: string
-  shortDescription: string
-  uri: string
-  iconUrl: string
-  active: boolean
-  isDefault: boolean
-  sortOrder: number
-  rightsIdentifier: string
-  rightsIdentifierScheme: string
-  schemeUri: string
-  languageCode: string
-}
-
-export interface DatasetFields {
-  citation: Citation
-}
-
-export interface Citation {
+interface DatasetFieldInfoPayload {
   displayName: string
   name: string
-  fields: Field[]
-}
-
-export interface Field {
-  typeName: string
-  multiple: boolean
-  typeClass: string
-  value: string
+  fields: MetadataFieldPayload[]
 }
 
-export interface Instruction {
+interface Instruction {
   instructionField: string
   instructionText: string
 }

src/collections/infra/repositories/transformers/collectionDatasetTemplateTransformer.ts

@@ -0,0 +1,53 @@
+import { CollectionDatasetTemplate } from '../../../domain/models/CollectionDatasetTemplate'
+import { CollectionDatasetTemplatePayload } from './CollectionDatasetTemplatePayload'
+
+export const transformCollectionDatasetTemplatePayloadToCollectionDatasetTemplate = (
+  collectionDatasetTemplatePayload: CollectionDatasetTemplatePayload[]
+): CollectionDatasetTemplate[] => {
+  return collectionDatasetTemplatePayload.map((payload) => {
+    const collectionDatasetTemplate: CollectionDatasetTemplate = {
+      id: payload.id,
+      name: payload.name,
+      alias: payload.dataverseAlias,
+      isDefault: payload.isDefault,
+      usageCount: payload.usageCount,
+      createTime: payload.createTime,
+      createDate: payload.createDate,
+      datasetFields: payload.datasetFields as unknown as CollectionDatasetTemplate['datasetFields'],
+      instructions: payload.instructions.map((instruction) => ({
+        instructionField: instruction.instructionField,
+        instructionText: instruction.instructionText
+      })),
+      termsOfUse: {
+        termsOfAccess: {
+          fileAccessRequest: payload.termsOfUseAndAccess.fileAccessRequest,
+          termsOfAccessForRestrictedFiles: payload.termsOfUseAndAccess.termsOfAccess,
+          dataAccessPlace: payload.termsOfUseAndAccess.dataAccessPlace,
+          originalArchive: payload.termsOfUseAndAccess.originalArchive,
+          availabilityStatus: payload.termsOfUseAndAccess.availabilityStatus,
+          contactForAccess: payload.termsOfUseAndAccess.contactForAccess,
+          sizeOfCollection: payload.termsOfUseAndAccess.sizeOfCollection,
+          studyCompletion: payload.termsOfUseAndAccess.studyCompletion
+        }
+      }
+    }
+
+    if (payload.termsOfUseAndAccess.license) {
+      collectionDatasetTemplate.license = payload.termsOfUseAndAccess.license
+    } else {
+      collectionDatasetTemplate.termsOfUse.customTerms = {
+        termsOfUse: payload.termsOfUseAndAccess.termsOfUse as string,
+        confidentialityDeclaration: payload.termsOfUseAndAccess
+          .confidentialityDeclaration as string,
+        specialPermissions: payload.termsOfUseAndAccess.specialPermissions as string,
+        restrictions: payload.termsOfUseAndAccess.restrictions as string,
+        citationRequirements: payload.termsOfUseAndAccess.citationRequirements as string,
+        depositorRequirements: payload.termsOfUseAndAccess.depositorRequirements as string,
+        conditions: payload.termsOfUseAndAccess.conditions as string,
+        disclaimer: payload.termsOfUseAndAccess.disclaimer as string
+      }
+    }
+
+    return collectionDatasetTemplate
+  })
+}