feat: external tool use cases

Author: g-saracca

docs/useCases.md

@@ -93,6 +93,11 @@ The different use cases currently available in the package are classified below,
   - [Send Feedback to Object Contacts](#send-feedback-to-object-contacts)
 - [Search](#Search)
   - [Get Search Services](#get-search-services)
+- [External Tools](#external-tools)
+  - [External Tools read use cases](#external-tools-read-use-cases)
+    - [Get External Tools](#get-external-tools)
+    - [Get Dataset External Tool Url](#get-dataset-external-tool-url)
+    - [Get File External Tool Url](#get-file-external-tool-url)
 
 ## Collections
 
@@ -2142,3 +2147,81 @@ getSearchServices.execute().then((searchServices: SearchService[]) => {
 ```
 
 _See [use case](../src/search/domain/useCases/GetSearchServices.ts) implementation_.
+
+## External Tools
+
+### External Tools Read Use Cases
+
+#### Get External Tools
+
+Returns an array of [ExternalTool](../src/externalTools/domain/models/ExternalTool.ts) objects, which represent the external tools available in the installation.
+
+##### Example call:
+
+```typescript
+import { getExternalTools } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+getExternalTools.execute().then((externalTools: ExternalTool[]) => {
+  /* ... */
+})
+
+/* ... */
+```
+
+_See [use case](../src/externalTools/domain/useCases/GetExternalTools.ts) implementation_.
+
+#### Get Dataset External Tool Url
+
+Returns an instance of [DatasetExternalToolUrl](../src/externalTools/domain/models/ExternalTool.ts), which contains the resolved URL for accessing an external tool that operates at the dataset level.
+
+##### Example call:
+
+```typescript
+import { getDatasetExternalToolUrl } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+const toolId = 1
+const datasetId = 2
+const getExternalToolDTO: GetExternalToolDTO = {
+  preview: true,
+  locale: 'en'
+}
+
+getDatasetExternalToolUrl
+  .execute(toolId, datasetId, getExternalToolDTO)
+  .then((datasetExternalToolUrl: DatasetExternalToolUrl) => {
+    /* ... */
+  })
+/* ... */
+```
+
+_See [use case](../src/externalTools/domain/useCases/GetDatasetExternalToolUrl.ts) implementation_.
+
+#### Get File External Tool Url
+
+Returns an instance of [FileExternalToolUrl](../src/externalTools/domain/models/ExternalTool.ts), which contains the resolved URL for accessing an external tool that operates at the file level.
+
+##### Example call:
+
+```typescript
+import { getFileExternalToolUrl } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+const toolId = 1
+const fileId = 2
+const getExternalToolDTO: GetExternalToolDTO = {
+  preview: true,
+  locale: 'en'
+}
+
+getFileExternalToolUrl
+  .execute(toolId, fileId, getExternalToolDTO)
+  .then((fileExternalToolUrl: FileExternalToolUrl) => {
+    /* ... */
+  })
+/* ... */
+```
+
+_See [use case](../src/externalTools/domain/useCases/GetfileExternalToolUrl.ts) implementation_.

src/externalTools/domain/dtos/GetExternalToolDTO.ts

@@ -0,0 +1,9 @@
+/**
+ * @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
+ */
+
+export interface GetExternalToolDTO {
+  preview: boolean
+  locale: string
+}

src/externalTools/domain/models/ExternalTool.ts

@@ -0,0 +1,33 @@
+export interface ExternalTool {
+  id: number
+  displayName: string
+  description: string
+  types: ToolType[]
+  scope: ToolScope
+}
+
+export enum ToolType {
+  Explore = 'explore',
+  Configure = 'configure',
+  Preview = 'preview',
+  Query = 'query'
+}
+
+export enum ToolScope {
+  Dataset = 'dataset',
+  File = 'file'
+}
+
+export interface DatasetExternalToolUrl {
+  toolUrlResolved: string
+  displayName: string
+  datasetId: number
+  preview: boolean
+}
+
+export interface FileExternalToolUrl {
+  toolUrlResolved: string
+  displayName: string
+  fileId: number
+  preview: boolean
+}

src/externalTools/domain/repositories/IExternalToolsRepository.ts

@@ -0,0 +1,16 @@
+import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO'
+import { DatasetExternalToolUrl, ExternalTool, FileExternalToolUrl } from '../models/ExternalTool'
+
+export interface IExternalToolsRepository {
+  getExternalTools(): Promise<ExternalTool[]>
+  getDatasetExternalToolUrl(
+    datasetId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<DatasetExternalToolUrl>
+  getFileExternalToolUrl(
+    fileId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<FileExternalToolUrl>
+}

src/externalTools/domain/useCases/GetDatasetExternalToolUrl.ts

@@ -0,0 +1,34 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO'
+import { DatasetExternalToolUrl } from '../models/ExternalTool'
+import { IExternalToolsRepository } from '../repositories/IExternalToolsRepository'
+
+export class GetDatasetExternalToolUrl implements UseCase<DatasetExternalToolUrl> {
+  private externalToolsRepository: IExternalToolsRepository
+
+  constructor(externalToolsRepository: IExternalToolsRepository) {
+    this.externalToolsRepository = externalToolsRepository
+  }
+
+  /**
+   * Returns a DatasetExternalToolUrl object containing the resolved URL for accessing an external tool that operates at the dataset level.
+   * The URL includes necessary authentication tokens and parameters based on the user's permissions and the tool's configuration.
+   * Authentication is required for draft or deaccessioned datasets and the user must have ViewUnpublishedDataset permission.
+   *
+   * @param {number | string} [datasetId] - The dataset 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.
+   * @returns {Promise<DatasetExternalToolUrl>}
+   */
+  async execute(
+    datasetId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<DatasetExternalToolUrl> {
+    return await this.externalToolsRepository.getDatasetExternalToolUrl(
+      datasetId,
+      toolId,
+      getExternalToolDTO
+    )
+  }
+}

src/externalTools/domain/useCases/GetExternalTools.ts

@@ -0,0 +1,20 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { ExternalTool } from '../models/ExternalTool'
+import { IExternalToolsRepository } from '../repositories/IExternalToolsRepository'
+
+export class GetExternalTools implements UseCase<ExternalTool[]> {
+  private externalToolsRepository: IExternalToolsRepository
+
+  constructor(externalToolsRepository: IExternalToolsRepository) {
+    this.externalToolsRepository = externalToolsRepository
+  }
+
+  /**
+   * Returns a list containing all the external tools available in the installation.
+   *
+   * @returns {Promise<ExternalTool[]>}
+   */
+  async execute(): Promise<ExternalTool[]> {
+    return await this.externalToolsRepository.getExternalTools()
+  }
+}

src/externalTools/domain/useCases/GetFileExternalToolUrl.ts

@@ -0,0 +1,34 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { GetExternalToolDTO } from '../dtos/GetExternalToolDTO'
+import { FileExternalToolUrl } from '../models/ExternalTool'
+import { IExternalToolsRepository } from '../repositories/IExternalToolsRepository'
+
+export class GetFileExternalToolUrl implements UseCase<FileExternalToolUrl> {
+  private externalToolsRepository: IExternalToolsRepository
+
+  constructor(externalToolsRepository: IExternalToolsRepository) {
+    this.externalToolsRepository = externalToolsRepository
+  }
+
+  /**
+   * Returns a FileExternalToolUrl object containing the resolved URL for accessing an external tool that operates at the file level.
+   * The URL includes necessary authentication tokens and parameters based on the user's permissions and the tool's configuration.
+   * Authentication is required for draft, restricted, embargoed, or expired (retention period) files, the user must have appropriate permissions.
+   *
+   * @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.
+   * @returns {Promise<FileExternalToolUrl>}
+   */
+  async execute(
+    fileId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<FileExternalToolUrl> {
+    return await this.externalToolsRepository.getFileExternalToolUrl(
+      fileId,
+      toolId,
+      getExternalToolDTO
+    )
+  }
+}

src/externalTools/index.ts

@@ -0,0 +1,25 @@
+import { GetDatasetExternalToolUrl } from './domain/useCases/GetDatasetExternalToolUrl'
+import { GetExternalTools } from './domain/useCases/GetExternalTools'
+import { GetFileExternalToolUrl } from './domain/useCases/GetFileExternalToolUrl'
+import { ExternalToolsRepository } from './infra/ExternalToolsRepository'
+
+const externalToolsRepository = new ExternalToolsRepository()
+
+const getExternalTools = new GetExternalTools(externalToolsRepository)
+const getDatasetExternalToolUrl = new GetDatasetExternalToolUrl(externalToolsRepository)
+const getFileExternalToolUrl = new GetFileExternalToolUrl(externalToolsRepository)
+
+export {
+  getExternalTools,
+  getDatasetExternalToolUrl,
+  getFileExternalToolUrl,
+  externalToolsRepository
+}
+
+export {
+  ExternalTool,
+  ToolScope,
+  ToolType,
+  DatasetExternalToolUrl,
+  FileExternalToolUrl
+} from './domain/models/ExternalTool'

src/externalTools/infra/ExternalToolsRepository.ts

@@ -0,0 +1,53 @@
+import { IExternalToolsRepository } from '../domain/repositories/IExternalToolsRepository'
+import { ApiRepository } from '../../core/infra/repositories/ApiRepository'
+import {
+  DatasetExternalToolUrl,
+  ExternalTool,
+  FileExternalToolUrl
+} from '../domain/models/ExternalTool'
+import { GetExternalToolDTO } from '../domain/dtos/GetExternalToolDTO'
+import { datasetExternalToolTransformer } from './transformers/datasetExternalToolTransformer'
+import { fileExternalToolTransformer } from './transformers/fileExternalToolTransformer'
+import { externalToolsTransformer } from './transformers/externalToolsTransformer'
+
+export class ExternalToolsRepository extends ApiRepository implements IExternalToolsRepository {
+  private readonly externalToolsResourceName: string = 'externalTools'
+
+  public async getExternalTools(): Promise<ExternalTool[]> {
+    return this.doGet(this.buildApiEndpoint(this.externalToolsResourceName))
+      .then((response) => externalToolsTransformer(response))
+      .catch((error) => {
+        throw error
+      })
+  }
+
+  public async getDatasetExternalToolUrl(
+    datasetId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<DatasetExternalToolUrl> {
+    return this.doPost(
+      this.buildApiEndpoint('datasets', `externalTool/${toolId}/toolUrl`, datasetId),
+      getExternalToolDTO
+    )
+      .then((response) => datasetExternalToolTransformer(response))
+      .catch((error) => {
+        throw error
+      })
+  }
+
+  public async getFileExternalToolUrl(
+    fileId: number | string,
+    toolId: number,
+    getExternalToolDTO: GetExternalToolDTO
+  ): Promise<FileExternalToolUrl> {
+    return this.doPost(
+      this.buildApiEndpoint('files', `externalTool/${toolId}/toolUrl`, fileId),
+      getExternalToolDTO
+    )
+      .then((response) => fileExternalToolTransformer(response))
+      .catch((error) => {
+        throw error
+      })
+  }
+}

src/externalTools/infra/transformers/ExternalToolPayload.ts

@@ -0,0 +1,19 @@
+export interface ExternalToolPayload {
+  id: number
+  displayName: string
+  description: string
+  types: ToolTypePayload[]
+  scope: ToolScopePayload
+}
+
+enum ToolTypePayload {
+  Explore = 'explore',
+  Configure = 'configure',
+  Preview = 'preview',
+  Query = 'query'
+}
+
+enum ToolScopePayload {
+  Dataset = 'dataset',
+  File = 'file'
+}