Merge pull request #232 from IQSS/231-implement-use-case-for-sending-information-to-contacts

implement use case for sending information to contacts

Author: ofahimIQSS

docs/useCases.md

@@ -68,6 +68,8 @@ The different use cases currently available in the package are classified below,
   - [Get Dataverse Backend Version](#get-dataverse-backend-version)
   - [Get Maximum Embargo Duration In Months](#get-maximum-embargo-duration-in-months)
   - [Get ZIP Download Limit](#get-zip-download-limit)
+- [Contact](#Contact)
+  - [Send Feedback to Object Contacts](#send-feedback-to-object-contacts)
 
 ## Collections
 
@@ -1499,3 +1501,40 @@ getZipDownloadLimit.execute().then((downloadLimit: number) => {
 ```
 
 _See [use case](../src/info/domain/useCases/GetZipDownloadLimit.ts) implementation_.
+
+## Contact
+
+#### Send Feedback to Object Contacts
+
+Returns a [Contact](../src/contactInfo/domain/models/Contact.ts) object, which contains contact return information, showing fromEmail, subject, body.
+
+##### Example call:
+
+```typescript
+import { submitContactInfo } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const contactDTO: ContactDTO = {
+  targedId: 1
+  subject: 'Data Question',
+  body: 'Please help me understand your data. Thank you!',
+  fromEmail: '[email protected]'
+}
+
+submitContactInfo.execute(contactDTO)
+
+/* ... */
+```
+
+_See [use case](../src/info/domain/useCases/submitContactInfo.ts) implementation_.
+
+The above example would submit feedback to all contacts of a object where the object targetId = 1.
+
+In ContactDTO, it takes the following information:
+
+- **targetId**: the numeric identifier of the collection, dataset, or datafile. Persistent ids and collection aliases are not supported. (Optional)
+- **identifier**: the alias of a collection or the persistence id of a dataset or datafile. (Optional)
+- **subject**: the email subject line.
+- **body**: the email body to send.
+- **fromEmail**: the email to list in the reply-to field.

src/contactInfo/domain/dtos/ContactDTO.ts

@@ -0,0 +1,7 @@
+export interface ContactDTO {
+  targetId?: number
+  identifier?: string
+  subject: string
+  body: string
+  fromEmail: string
+}

src/contactInfo/domain/models/Contact.ts

@@ -0,0 +1,5 @@
+export interface Contact {
+  fromEmail: string
+  body: string
+  subject: string
+}

src/contactInfo/domain/repositories/IContactRepository.ts

@@ -0,0 +1,6 @@
+import { Contact } from '../models/Contact'
+import { ContactDTO } from '../dtos/ContactDTO'
+
+export interface IContactRepository {
+  submitContactInfo(contactDTO: ContactDTO): Promise<Contact[]>
+}

src/contactInfo/domain/useCases/SubmitContactInfo.ts

@@ -0,0 +1,23 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ContactDTO } from '../dtos/ContactDTO'
+import { Contact } from '../models/Contact'
+import { IContactRepository } from '../repositories/IContactRepository'
+
+export class SubmitContactInfo implements UseCase<Contact[]> {
+  private contactRepository: IContactRepository
+
+  constructor(contactRepository: IContactRepository) {
+    this.contactRepository = contactRepository
+  }
+
+  /**
+   * Submits contact information and returns a Contact model containing the submitted data.
+   *
+   * @param {ContactDTO} contactDTO - The contact information to be submitted.
+   * @returns {Promise<Contact[]>} A promise resolving to a list of contact.
+   */
+
+  async execute(contactDTO: ContactDTO): Promise<Contact[]> {
+    return await this.contactRepository.submitContactInfo(contactDTO)
+  }
+}

src/contactInfo/index.ts

@@ -0,0 +1,9 @@
+import { SubmitContactInfo } from './domain/useCases/SubmitContactInfo'
+import { ContactRepository } from './infra/repositories/ContactRepository'
+
+const contactRepository = new ContactRepository()
+const submitContactInfo = new SubmitContactInfo(contactRepository)
+
+export { submitContactInfo }
+export { Contact } from './domain/models/Contact'
+export { ContactDTO } from './domain/dtos/ContactDTO'

src/contactInfo/infra/repositories/ContactRepository.ts

@@ -0,0 +1,23 @@
+import { ApiRepository } from '../../../core/infra/repositories/ApiRepository'
+import { Contact } from '../../domain/models/Contact'
+import { IContactRepository } from '../../domain/repositories/IContactRepository'
+import { ContactDTO } from '../../domain/dtos/ContactDTO'
+
+export class ContactRepository extends ApiRepository implements IContactRepository {
+  public async submitContactInfo(contactDTO: ContactDTO): Promise<Contact[]> {
+    return this.doPost(`/sendfeedback`, contactDTO)
+      .then((response) => {
+        const responseData = response.data
+        const contact: Contact[] = responseData.data.map((item: Contact) => ({
+          fromEmail: item.fromEmail,
+          subject: item.subject,
+          body: item.body
+        }))
+
+        return contact
+      })
+      .catch((error) => {
+        throw error
+      })
+  }
+}

src/index.ts

@@ -6,3 +6,4 @@ export * from './datasets'
 export * from './collections'
 export * from './metadataBlocks'
 export * from './files'
+export * from './contactInfo'

test/functional/contact/SubmitContactInfo.test.ts

@@ -0,0 +1,80 @@
+import { ApiConfig, submitContactInfo, ContactDTO, WriteError, Contact } from '../../../src'
+import { TestConstants } from '../../testHelpers/TestConstants'
+import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig'
+
+describe('submitContactInfo', () => {
+  beforeAll(async () => {
+    ApiConfig.init(
+      TestConstants.TEST_API_URL,
+      DataverseApiAuthMechanism.API_KEY,
+      process.env.TEST_API_KEY
+    )
+  })
+
+  test('should return Contact result successfully with targetId', async () => {
+    const contactDTO: ContactDTO = {
+      targetId: 1,
+      subject: 'Data Question',
+      body: 'Please help me understand your data. Thank you!',
+      fromEmail: '[email protected]'
+    }
+
+    let contactInfo: Contact[] = []
+    try {
+      contactInfo = await submitContactInfo.execute(contactDTO)
+    } catch (error) {
+      throw new Error('Contact info should be submitted')
+    } finally {
+      expect(contactInfo).toBeDefined()
+      expect(contactInfo[0].fromEmail).toEqual('[email protected]')
+      expect(contactInfo[0].subject).toEqual(expect.any(String))
+      expect(contactInfo[0].body).toEqual(expect.any(String))
+    }
+  })
+
+  test('should return a Contact when targetId is not provided', async () => {
+    const contactDTO: ContactDTO = {
+      subject: 'General Inquiry',
+      body: 'I have a general question.',
+      fromEmail: '[email protected]'
+    }
+
+    let contactInfo: Contact[] = []
+    try {
+      contactInfo = await submitContactInfo.execute(contactDTO)
+    } catch (error) {
+      throw new Error('Contact info should be submitted even if target id is missing')
+    } finally {
+      expect(contactInfo).toBeDefined()
+      expect(contactInfo[0].fromEmail).toEqual('[email protected]')
+      expect(contactInfo[0].subject).toEqual(expect.any(String))
+      expect(contactInfo[0].body).toEqual(expect.any(String))
+    }
+  })
+
+  test('should return Contact when contact info is successfully submitted with identifier', async () => {
+    const test2ContactDTO: ContactDTO = {
+      identifier: 'root',
+      subject: 'Data Question',
+      body: 'Please help me understand your data. Thank you!',
+      fromEmail: '[email protected]'
+    }
+    const contactInfo = await submitContactInfo.execute(test2ContactDTO)
+
+    expect(contactInfo).toBeDefined()
+    expect(contactInfo[0].fromEmail).toEqual(test2ContactDTO.fromEmail)
+    expect(contactInfo[0].subject).toEqual(expect.any(String))
+    expect(contactInfo[0].body).toEqual(expect.any(String))
+  })
+
+  test('should return error if the target id is unexisted', async () => {
+    const contactDTO: ContactDTO = {
+      targetId: 0,
+      subject: '',
+      body: '',
+      fromEmail: '[email protected]'
+    }
+    const expectedError = new WriteError(`[400] Feedback target object not found.`)
+    await expect(submitContactInfo.execute(contactDTO)).rejects.toThrow(expectedError)
+  })
+})

test/integration/contact/ContactRepository.test.ts

@@ -0,0 +1,76 @@
+import { ContactRepository } from '../../../src/contactInfo/infra/repositories/ContactRepository'
+import { ApiConfig, Contact, ContactDTO, WriteError } from '../../../src'
+import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig'
+import { TestConstants } from '../../testHelpers/TestConstants'
+
+describe('submitContactInfo', () => {
+  beforeAll(async () => {
+    ApiConfig.init(
+      TestConstants.TEST_API_URL,
+      DataverseApiAuthMechanism.API_KEY,
+      process.env.TEST_API_KEY
+    )
+  })
+
+  const testContactDTO: ContactDTO = {
+    targetId: 1,
+    subject: 'Data Question',
+    body: 'Please help me understand your data. Thank you!',
+    fromEmail: '[email protected]'
+  }
+
+  const test2ContactDTO: ContactDTO = {
+    identifier: 'root',
+    subject: 'Data Question',
+    body: 'Please help me understand your data. Thank you!',
+    fromEmail: '[email protected]'
+  }
+
+  const sut: ContactRepository = new ContactRepository()
+
+  test('should return Contact when contact info is successfully submitted', async () => {
+    const contactInfo = await sut.submitContactInfo(test2ContactDTO)
+
+    expect(contactInfo).toBeDefined()
+    expect(contactInfo[0].fromEmail).toEqual(testContactDTO.fromEmail)
+    expect(contactInfo[0].subject).toEqual(expect.any(String))
+    expect(contactInfo[0].body).toEqual(expect.any(String))
+  })
+
+  test('should return Contact when contact info is successfully submitted if accessed by identifier', async () => {
+    const contactInfo = await sut.submitContactInfo(testContactDTO)
+
+    expect(contactInfo).toBeDefined()
+    expect(contactInfo[0].fromEmail).toEqual(test2ContactDTO.fromEmail)
+    expect(contactInfo[0].subject).toEqual(expect.any(String))
+    expect(contactInfo[0].body).toEqual(expect.any(String))
+  })
+
+  test('should return a Contact when targetId is not provided', async () => {
+    const contactDTOWithoutTargetId: Partial<ContactDTO> = {
+      subject: 'General Inquiry',
+      body: 'I have a general question.',
+      fromEmail: '[email protected]'
+    }
+
+    const contactInfo: Contact[] = await sut.submitContactInfo(
+      contactDTOWithoutTargetId as ContactDTO
+    )
+
+    expect(contactInfo).toBeDefined()
+    expect(contactInfo[0].fromEmail).toEqual(contactDTOWithoutTargetId.fromEmail)
+    expect(contactInfo[0].subject).toEqual(expect.any(String))
+    expect(contactInfo[0].body).toEqual(expect.any(String))
+  })
+
+  test('should return error if the target id is unexisted', async () => {
+    const invalidContactDTO: ContactDTO = {
+      targetId: 0,
+      subject: '',
+      body: '',
+      fromEmail: ''
+    }
+    const expectedError = new WriteError(`[400] Feedback target object not found.`)
+    await expect(sut.submitContactInfo(invalidContactDTO)).rejects.toThrow(expectedError)
+  })
+})