Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 12 additions & 6 deletions docs/useCases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 7 additions & 0 deletions src/externalTools/domain/dtos/GetExternalToolDTO.ts
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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']
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO'
import { GetExternalToolDTO, GetFileExternalToolDTO } from '../dtos/GetExternalToolDTO'
import {
DatasetExternalToolResolved,
ExternalTool,
Expand All @@ -15,6 +15,6 @@ export interface IExternalToolsRepository {
getFileExternalToolResolved(
fileId: number | string,
toolId: number,
getExternalToolDTO: GetExternalToolDTO
getExternalToolDTO: GetFileExternalToolDTO
): Promise<FileExternalToolResolved>
}
Original file line number Diff line number Diff line change
@@ -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'

Expand All @@ -17,13 +17,13 @@ export class GetFileExternalToolResolved implements UseCase<FileExternalToolReso
*
* @param {number | string} [fileId] - The File identifier, which can be a string (for persistent identifiers), or a number (for numeric identifiers).
* @param {number} toolId - The identifier of the external tool.
* @param {GetExternalToolDTO} getExternalToolDTO - The GetExternalToolDTO object containing additional parameters for the request.
* @param {GetFileExternalToolDTO} getExternalToolDTO - The launch options and optional guestbook response.
* @returns {Promise<FileExternalToolResolved>}
*/
async execute(
fileId: number | string,
toolId: number,
getExternalToolDTO: GetExternalToolDTO
getExternalToolDTO: GetFileExternalToolDTO
): Promise<FileExternalToolResolved> {
return await this.externalToolsRepository.getFileExternalToolResolved(
fileId,
Expand Down
2 changes: 2 additions & 0 deletions src/externalTools/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,5 @@ export {
DatasetExternalToolResolved,
FileExternalToolResolved
} from './domain/models/ExternalTool'

export type { GetFileExternalToolDTO } from './domain/dtos/GetExternalToolDTO'
4 changes: 2 additions & 2 deletions src/externalTools/infra/ExternalToolsRepository.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -39,7 +39,7 @@ export class ExternalToolsRepository extends ApiRepository implements IExternalT
public async getFileExternalToolResolved(
fileId: number | string,
toolId: number,
getExternalToolDTO: GetExternalToolDTO
getExternalToolDTO: GetFileExternalToolDTO
): Promise<FileExternalToolResolved> {
return this.doPost(
this.buildApiEndpoint('files', `externalTool/${toolId}/toolUrl`, fileId),
Expand Down
93 changes: 90 additions & 3 deletions test/integration/externalTools/ExternalToolsRepository.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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, {
Expand Down
58 changes: 57 additions & 1 deletion test/unit/externalTools/GetFileExternalToolUrl.test.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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
)
}
})
Loading