diff --git a/CHANGELOG.md b/CHANGELOG.md index c1d822c2..dd6ad438 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel ### Added +- External tools: `getFileExternalToolResolved` accepts a guestbook response when launching a file tool. + ### Changed ### Fixed diff --git a/docs/useCases.md b/docs/useCases.md index 64a2c8d6..9d272fd2 100644 --- a/docs/useCases.md +++ b/docs/useCases.md @@ -3238,28 +3238,34 @@ _See [use case](../src/externalTools/domain/useCases/GetDatasetExternalToolResol Returns an instance of [FileExternalToolResolved](../src/externalTools/domain/models/ExternalTool.ts), which contains the resolved URL for accessing an external tool that operates at the file level. +For a file that requires a guestbook, pass the completed form as `guestbookResponse` in the launch options. + ##### Example call: ```typescript -import { getFileExternalToolResolved } from '@iqss/dataverse-client-javascript' +import { + getFileExternalToolResolved, + type GetFileExternalToolDTO +} from '@iqss/dataverse-client-javascript' /* ... */ const toolId = 1 const fileId = 2 -const getExternalToolDTO: GetExternalToolDTO = { +const getExternalToolDTO: GetFileExternalToolDTO = { preview: true, - locale: 'en' + locale: 'en', + guestbookResponse: { name: 'Example Reader', email: 'reader@example.org' } } getFileExternalToolResolved - .execute(toolId, fileId, getExternalToolDTO) - .then((fileExternalToolResolved: FileExternalToolResolved) => { + .execute(fileId, toolId, getExternalToolDTO) + .then((fileExternalToolResolved) => { /* ... */ }) /* ... */ ``` -_See [use case](../src/externalTools/domain/useCases/GetfileExternalToolResolved.ts) implementation_. +_See [use case](../src/externalTools/domain/useCases/GetFileExternalToolResolved.ts) implementation_. ## Guestbooks diff --git a/src/externalTools/domain/dtos/GetExternalToolDTO.ts b/src/externalTools/domain/dtos/GetExternalToolDTO.ts index 7e415d25..efb08d1a 100644 --- a/src/externalTools/domain/dtos/GetExternalToolDTO.ts +++ b/src/externalTools/domain/dtos/GetExternalToolDTO.ts @@ -1,3 +1,5 @@ +import type { GuestbookResponseDTO } from '../../../access/domain/dtos/GuestbookResponseDTO' + /** * @property {boolean} preview - boolean flag to indicate if the request is for previewing the tool or not. * @property {string} locale - string specifying the locale for internationalization @@ -7,3 +9,8 @@ export interface GetExternalToolDTO { preview: boolean locale: string } + +export interface GetFileExternalToolDTO extends GetExternalToolDTO { + /** The completed guestbook form for files that require one. */ + guestbookResponse?: GuestbookResponseDTO['guestbookResponse'] +} diff --git a/src/externalTools/domain/repositories/IExternalToolsRepository.ts b/src/externalTools/domain/repositories/IExternalToolsRepository.ts index 36db3870..4b394ed3 100644 --- a/src/externalTools/domain/repositories/IExternalToolsRepository.ts +++ b/src/externalTools/domain/repositories/IExternalToolsRepository.ts @@ -1,4 +1,4 @@ -import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO' +import { GetExternalToolDTO, GetFileExternalToolDTO } from '../dtos/GetExternalToolDTO' import { DatasetExternalToolResolved, ExternalTool, @@ -15,6 +15,6 @@ export interface IExternalToolsRepository { getFileExternalToolResolved( fileId: number | string, toolId: number, - getExternalToolDTO: GetExternalToolDTO + getExternalToolDTO: GetFileExternalToolDTO ): Promise } diff --git a/src/externalTools/domain/useCases/GetFileExternalToolResolved.ts b/src/externalTools/domain/useCases/GetFileExternalToolResolved.ts index 47f6b090..cecd3be1 100644 --- a/src/externalTools/domain/useCases/GetFileExternalToolResolved.ts +++ b/src/externalTools/domain/useCases/GetFileExternalToolResolved.ts @@ -1,5 +1,5 @@ import { UseCase } from '../../../core/domain/useCases/UseCase' -import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO' +import { GetFileExternalToolDTO } from '../dtos/GetExternalToolDTO' import { FileExternalToolResolved } from '../models/ExternalTool' import { IExternalToolsRepository } from '../repositories/IExternalToolsRepository' @@ -17,13 +17,13 @@ export class GetFileExternalToolResolved implements UseCase} */ async execute( fileId: number | string, toolId: number, - getExternalToolDTO: GetExternalToolDTO + getExternalToolDTO: GetFileExternalToolDTO ): Promise { return await this.externalToolsRepository.getFileExternalToolResolved( fileId, diff --git a/src/externalTools/index.ts b/src/externalTools/index.ts index 96b2581f..048301ce 100644 --- a/src/externalTools/index.ts +++ b/src/externalTools/index.ts @@ -23,3 +23,5 @@ export { DatasetExternalToolResolved, FileExternalToolResolved } from './domain/models/ExternalTool' + +export type { GetFileExternalToolDTO } from './domain/dtos/GetExternalToolDTO' diff --git a/src/externalTools/infra/ExternalToolsRepository.ts b/src/externalTools/infra/ExternalToolsRepository.ts index 5e104593..3a95eeb6 100644 --- a/src/externalTools/infra/ExternalToolsRepository.ts +++ b/src/externalTools/infra/ExternalToolsRepository.ts @@ -5,7 +5,7 @@ import { ExternalTool, FileExternalToolResolved } from '../domain/models/ExternalTool' -import { GetExternalToolDTO } from '../domain/dtos/GetExternalToolDTO' +import { GetExternalToolDTO, GetFileExternalToolDTO } from '../domain/dtos/GetExternalToolDTO' import { datasetExternalToolTransformer } from './transformers/datasetExternalToolTransformer' import { fileExternalToolTransformer } from './transformers/fileExternalToolTransformer' import { externalToolsTransformer } from './transformers/externalToolsTransformer' @@ -39,7 +39,7 @@ export class ExternalToolsRepository extends ApiRepository implements IExternalT public async getFileExternalToolResolved( fileId: number | string, toolId: number, - getExternalToolDTO: GetExternalToolDTO + getExternalToolDTO: GetFileExternalToolDTO ): Promise { return this.doPost( this.buildApiEndpoint('files', `externalTool/${toolId}/toolUrl`, fileId), diff --git a/test/integration/externalTools/ExternalToolsRepository.test.ts b/test/integration/externalTools/ExternalToolsRepository.test.ts index ef2c9248..ecf08bf8 100644 --- a/test/integration/externalTools/ExternalToolsRepository.test.ts +++ b/test/integration/externalTools/ExternalToolsRepository.test.ts @@ -10,13 +10,27 @@ import { CREATE_FILE_EXTERNAL_TOOL_PAYLOAD, CREATE_DATASET_EXTERNAL_TOOL_PAYLOAD } from '../../testHelpers/externalTools/externalToolsHelper' -import { createDataset, CreatedDatasetIdentifiers, getDatasetFiles, WriteError } from '../../../src' +import { + assignDatasetGuestbook, + createDataset, + CreatedDatasetIdentifiers, + createGuestbook, + getDatasetFiles, + getFileExternalToolResolved, + WriteError +} from '../../../src' import { createCollectionViaApi, - deleteCollectionViaApi + deleteCollectionViaApi, + publishCollectionViaApi } from '../../testHelpers/collections/collectionHelper' import { uploadFileViaApi } from '../../testHelpers/files/filesHelper' -import { deleteUnpublishedDatasetViaApi } from '../../testHelpers/datasets/datasetHelper' +import { + deletePublishedDatasetViaApi, + deleteUnpublishedDatasetViaApi, + publishDatasetViaApi, + waitForNoLocks +} from '../../testHelpers/datasets/datasetHelper' describe('ExternalToolsRepository', () => { const sut: ExternalToolsRepository = new ExternalToolsRepository() @@ -112,6 +126,79 @@ describe('ExternalToolsRepository', () => { expect(fileExternalToolResolved.preview).toBe(true) }) + test('creates a new guestbook response when launching a file tool again', async () => { + const dataset = await createDataset.execute( + TestConstants.TEST_NEW_DATASET_DTO, + testCollectionAlias + ) + let published = false + + try { + const guestbookId = await createGuestbook.execute( + { + name: 'File tool guestbook', + enabled: true, + nameRequired: true, + emailRequired: true, + institutionRequired: false, + positionRequired: false, + customQuestions: [] + }, + testCollectionAlias + ) + await assignDatasetGuestbook.execute(dataset.numericId, guestbookId) + await uploadFileViaApi(dataset.numericId, testTextFile1Name) + const { files } = await getDatasetFiles.execute(dataset.numericId) + await publishCollectionViaApi(testCollectionAlias) + await publishDatasetViaApi(dataset.numericId) + published = true + await waitForNoLocks(dataset.numericId) + + ApiConfig.init(TestConstants.TEST_API_URL, DataverseApiAuthMechanism.API_KEY) + const options = { + locale: 'en', + guestbookResponse: { name: 'Example Reader', email: 'reader@example.org' } + } + const preview = await getFileExternalToolResolved.execute( + files[0].id, + testFileExternalToolId, + { + ...options, + preview: true + } + ) + const newWindow = await getFileExternalToolResolved.execute( + files[0].id, + testFileExternalToolId, + { + ...options, + preview: false + } + ) + + const responseIds = [preview, newWindow].map(({ toolUrlResolved }) => { + const callback = new URL(toolUrlResolved).searchParams.get('callback') ?? '' + return new URL(Buffer.from(callback, 'base64').toString()).searchParams.get( + 'guestbookResponseId' + ) + }) + expect(responseIds[0]).toMatch(/^\d+$/) + expect(responseIds[1]).toMatch(/^\d+$/) + expect(responseIds[0]).not.toBe(responseIds[1]) + } finally { + ApiConfig.init( + TestConstants.TEST_API_URL, + DataverseApiAuthMechanism.API_KEY, + process.env.TEST_API_KEY + ) + if (published) { + await deletePublishedDatasetViaApi(dataset.persistentId) + } else { + await deleteUnpublishedDatasetViaApi(dataset.numericId) + } + } + }) + test('should return error if file external tool id does not exist', async () => { await expect( sut.getFileExternalToolResolved(testFileId, 999999, { diff --git a/test/unit/externalTools/GetFileExternalToolUrl.test.ts b/test/unit/externalTools/GetFileExternalToolUrl.test.ts index a55cca29..bedf6a0f 100644 --- a/test/unit/externalTools/GetFileExternalToolUrl.test.ts +++ b/test/unit/externalTools/GetFileExternalToolUrl.test.ts @@ -1,4 +1,11 @@ -import { WriteError } from '../../../src' +import axios from 'axios' +import { + ApiConfig, + getFileExternalToolResolved, + GetFileExternalToolDTO, + WriteError +} from '../../../src' +import { DataverseApiAuthMechanism } from '../../../src/core/infra/repositories/ApiConfig' import { IExternalToolsRepository } from '../../../src/externalTools/domain/repositories/IExternalToolsRepository' import { GetFileExternalToolResolved } from '../../../src/externalTools/domain/useCases/GetFileExternalToolResolved' import { createFileExternalToolResolvedModel } from '../../testHelpers/externalTools/externalToolsHelper' @@ -27,3 +34,52 @@ describe('execute', () => { await expect(sut.execute(123, 3, { preview: true, locale: 'en' })).rejects.toThrow(WriteError) }) }) + +test('sends the guestbook response to the file tool URL endpoint', async () => { + const options: GetFileExternalToolDTO = { + preview: true, + locale: 'en', + guestbookResponse: { + name: 'Example Reader', + email: 'reader@example.org', + answers: [{ id: 1, value: 'Research' }] + } + } + const { + dataverseApiUrl, + dataverseApiAuthMechanism, + dataverseApiKey, + bearerTokenLocalStorageKey, + bearerTokenGetFunction + } = ApiConfig + ApiConfig.init('https://example.org/api/v1', DataverseApiAuthMechanism.API_KEY) + const post = jest.spyOn(axios, 'post').mockResolvedValue({ + data: { + data: { + toolUrl: 'https://example.org/text-tool?preview=true', + displayName: 'Text File Tool', + fileId: 123, + preview: true + } + } + }) + + try { + await getFileExternalToolResolved.execute(123, 3, options) + + expect(post).toHaveBeenCalledWith( + 'https://example.org/api/v1/files/123/externalTool/3/toolUrl', + JSON.stringify(options), + expect.objectContaining({ headers: { 'Content-Type': 'application/json' } }) + ) + } finally { + post.mockRestore() + ApiConfig.init( + dataverseApiUrl, + dataverseApiAuthMechanism, + dataverseApiKey, + bearerTokenLocalStorageKey, + bearerTokenGetFunction + ) + } +})