feat(extensions): add missing parameter + JSDoc to Extensions (#878)

* feat(extensions): add missing parameter + JSDoc to Extensions * Apply suggestions from code review Co-authored-by: Germain Bergeron <[email protected]> --------- Co-authored-by: Germain Bergeron <[email protected]>
coveo · Oct 21, 2024 · ff22dda · ff22dda
1 parent 4e2fecf
commit ff22dda
Show file tree

Hide file tree

Showing 2 changed files with 228 additions and 44 deletions.
diff --git a/src/resources/Extensions/Extensions.ts b/src/resources/Extensions/Extensions.ts
@@ -11,56 +11,99 @@ import {
 export default class Extension extends Resource {
     static baseUrl = `/rest/organizations/${API.orgPlaceholder}/extensions`;
 
-    create(extension: CreateExtension) {
+    /**
+     * Creates an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     * @param extension The configuration to use for the new extension.
+     * @returns The newly created extension.
+     */
+    create(extension: CreateExtension): Promise<ExtensionModel> {
         return this.api.post<ExtensionModel>(Extension.baseUrl, extension);
     }
 
-    update(extensionId: string, options: CreateExtension) {
+    /**
+     * Updates an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     * @param extensionId The unique identifier of the extension to update.
+     * @param options The new configuration to use for the updated extension.
+     * @returns The updated extension.
+     */
+    update(extensionId: string, options: CreateExtension): Promise<ExtensionModel> {
         return this.api.put<ExtensionModel>(`${Extension.baseUrl}/${extensionId}`, options);
     }
 
-    delete(extensionId: string) {
+    /**
+     * Deletes an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     * @param extensionId The unique identifier of the extension to delete.
+     * @returns
+     */
+    delete(extensionId: string): Promise<void> {
         return this.api.delete<void>(`${Extension.baseUrl}/${extensionId}`);
     }
 
-    enable(extensionId: string) {
+    /**
+     * Enables a disabled [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     *
+     * Note: Disabled extensions are not executed.
+     * @param extensionId The unique identifier of the extension to enable.
+     * @returns
+     */
+    enable(extensionId: string): Promise<void> {
         return this.api.post<void>(`${Extension.baseUrl}/${extensionId}/enable`);
     }
 
-    disable(extensionId: string, reason?: string) {
+    /**
+     * Disables an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     *
+     * Note: Disabled extensions are not executed.
+     * @param extensionId The unique identifier of the extension to disable.
+     * @param reason The reason why the extension is disabled.
+     * @returns
+     */
+    disable(extensionId: string, reason?: string): Promise<void> {
         return this.api.post<void>(`${Extension.baseUrl}/${extensionId}/disable`, {reason});
     }
 
-    get(extensionId: string) {
+    /**
+     * Shows an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     * @param extensionId Shows an extension in a Coveo Cloud organization.
+     * @returns The extension specified by the provided id.
+     */
+    get(extensionId: string): Promise<ExtensionModel> {
         return this.api.get<ExtensionModel>(`${Extension.baseUrl}/${extensionId}`);
     }
 
-    list() {
+    /**
+     * Lists all [extensions](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
+     * @returns A list of extensions.
+     */
+    list(): Promise<ExtensionModel[]> {
         return this.api.get<ExtensionModel[]>(Extension.baseUrl);
     }
 
     /**
      * Lists all versions of an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
-     * @param extensionId
+     * @param extensionId he unique identifier of the target extension.
+     * @returns A list of versions of the extension.
      */
-    listVersions(extensionId: string) {
+    listVersions(extensionId: string): Promise<ExtensionContentVersionModel[]> {
         return this.api.get<ExtensionContentVersionModel[]>(`${Extension.baseUrl}/${extensionId}/versions`);
     }
 
     /**
      * Shows a specific version of an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
-     * @param extensionId
-     * @param versionId
+     * @param extensionId The unique identifier of the target extension.
+     * @param versionId The unique identifier of the extension version to show.
+     * @returns The extension specified by the provided id and version id.
      */
-    getVersion(extensionId: string, versionId: string) {
+    getVersion(extensionId: string, versionId: string): Promise<ExtensionModel> {
         return this.api.get<ExtensionModel>(`${Extension.baseUrl}/${extensionId}/versions/${versionId}`);
     }
 
     /**
-     * Validates the extension's script
+     * Tries to compile code that would be used in an [extension](https://docs.coveo.com/en/206/) in a [Coveo Cloud organization](https://docs.coveo.com/en/185/).
      * @param extensionCode The code to compile
+     * @returns Details regarding the outcome of an extension script compilation.
      */
-    validateCode(extensionCode: ExtensionCompileCode) {
+    validateCode(extensionCode: ExtensionCompileCode): Promise<ExtensionCompileResult> {
         return this.api.post<ExtensionCompileResult>(`${Extension.baseUrl}/test/compile`, extensionCode);
     }
 }
diff --git a/src/resources/Extensions/ExtensionsInterfaces.ts b/src/resources/Extensions/ExtensionsInterfaces.ts
@@ -3,57 +3,198 @@ import {DataStreamType, ExtensionLanguageType} from '../Enums.js';
 
 type Version = 'v1' | 'v2';
 
+export interface ExtensionHealthModel {
+    /**
+     * A qualitative health indicator.
+     *
+     */
+    healthIndicator: 'GOOD' | 'WARNING' | 'PROBLEMATIC' | 'UNKNOWN';
+    /**
+     * Additional details if healthIndicator value is `WARNING` or `PROBLEMATIC`.
+     */
+    reason: string;
+}
+
+export interface ExtensionDisabledStatusModel {
+    /**
+     * The extension disablement date (in number of milliseconds since UNIX epoch).
+     * @example 1556034174000
+     */
+    disabledDate: number;
+    /**
+     * The reason why the extension was disabled.
+     */
+    reason: string;
+}
+
+export interface ExtensionStatisticsModel {
+    /**
+     * The average extension execution duration in seconds.
+     */
+    averageDurationInSeconds: number;
+    /**
+     * The number of extension executions for which the script returned an error.
+     */
+    numberOfErrors: number;
+    /**
+     * The total number of executions of the extension.
+     */
+    numberOfExecutions: number;
+    /**
+     * The number of times the extension was not executed due to any of the following reasons:
+     * - The extension condition was evaluated to false.
+     * - The extension timed out.
+     * - The extension was disabled.
+     */
+    numberOfSkips: number;
+    /**
+     * The number of executions that reached the maximum execution time (default of 5 seconds).
+     */
+    numberOfTimeouts: number;
+}
+
+export interface ExtensionStatusModel {
+    /**
+     * Execution statistics pertaining to an extension over the past 24 hours (for all items from all sources to which the extension applies).
+     */
+    dailyStatistics: ExtensionStatisticsModel;
+    /**
+     * Information regarding the disabled state of an extension, if applicable.
+     */
+    disabledStatus?: ExtensionDisabledStatusModel;
+    /**
+     * Information regarding a health characteristic of the extension.
+     */
+    durationHealth: ExtensionHealthModel;
+    /**
+     * The last date at which the extension was automatically disabled by the service, (in number of milliseconds since UNIX epoch).
+     * @example 1533916446000
+     */
+    lastAutoDisablingDate: number;
+    /**
+     * @deprecated use lastAutoDisablingDate instead.
+     */
+    lastDisablingDate: number;
+    /**
+     * Information regarding a health characteristic of the extension.
+     */
+    timeoutHealth: ExtensionHealthModel;
+    /**
+     * A qualitative indicator of the likelihood that the extension will time out.
+     *
+     */
+    timeoutLikeliness: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
+}
+
+export interface ExtensionUsedByModel {
+    /**
+     * The unique identifier of the source.
+     * @example mycoveocloudv2organizationg8tp8wu3-tqv7hb5wfju45im3lnuvtw2moq
+     */
+    sourceId: string;
+    /**
+     * The name of the source.
+     * @example mysource
+     */
+    sourceName: string;
+}
+
 export interface ExtensionModel {
+    /**
+     * The api version.
+     */
     apiVersion: Version;
+    /**
+     * The body of the extension (user script), written in Python using the [document object](https://docs.coveo.com/en/34/index-content/document-object-python-api-reference).
+     */
     content: string;
+    /**
+     * The creation date of the extension (in number of milliseconds since UNIX epoch).
+     * @example 1556034174000
+     */
     createdDate: number;
+    /**
+     * A description of the extension
+     */
     description: string;
+    /**
+     * Whether the extension is enabled.
+     *
+     * Note: Disabled extensions are not executed.
+     */
     enabled: boolean;
+    /**
+     * The unique identifier of the extension.
+     * @example mycoveocloudv2organizationg8tp8wu3-vwlyqfbtjkotxqkmrxqjcbcpoy
+     */
     id: string;
+    /**
+     * The Python version.
+     */
     language: ExtensionLanguageType;
+    /**
+     * The last modification date of the extension (in number of milliseconds since UNIX epoch).
+     * @example 1556308241000
+     */
     lastModified: number;
+    /**
+     * The name of the extension.
+     */
     name: string;
+    /**
+     * The [data streams](https://docs.coveo.com/en/2891/glossary/data-stream) required by the extension.
+     */
     requiredDataStreams: DataStreamType[];
-    status: {
-        dailyStatistics: {
-            averageDurationInSeconds: number;
-            numberOfErrors: number;
-            numberOfExecutions: number;
-            numberOfSkips: number;
-            numberOfTimeouts: number;
-        };
-        disabledStatus?: {
-            disabledDate: number;
-            reason: string;
-        };
-        durationHealth: {
-            healthIndicator: string;
-            reason: string;
-        };
-        lastAutoDisablingDate: number;
-        lastDisablingDate: number;
-        timeoutHealth: {
-            healthIndicator: string;
-            reason: string;
-        };
-        timeoutLikeliness: string;
-    };
-    usedBy: [
-        {
-            sourceId: string;
-            sourceName: string;
-        },
-    ];
+    /**
+     * Status details of an extension.
+     */
+    status: ExtensionStatusModel;
+    /**
+     * The sources the extension applies to.
+     *
+     * Note: Only returned when performing GET/PUT /extensions/{extensionId} requests.
+     */
+    usedBy: ExtensionUsedByModel[];
+    /**
+     * Whether the extension uses vault parameters or not.
+     */
+    useVault?: boolean;
+    /**
+     * The unique identifier of the extension version.
+     * @example hdJSDb4hTkdnsCynNtF.d657FgLSDydcj
+     */
     versionId: string;
 }
 
 export interface CreateExtension extends GranularResource {
+    /**
+     * The body of the extension (user script), written in Python using the [document object](https://docs.coveo.com/en/34/index-content/document-object-python-api-reference).
+     */
     content: string;
+    /**
+     * A name for the extension.
+     */
     name: string;
+    /**
+     * The api version.
+     */
     apiVersion?: Version;
+    /**
+     * A description of the extension.
+     */
     description?: string;
+    /**
+     * The Python version.
+     */
     language?: ExtensionLanguageType;
+    /**
+     * The [data streams](https://docs.coveo.com/en/2891/glossary/data-stream) required by the extension.
+     */
     requiredDataStreams?: DataStreamType[];
+    /**
+     * Whether the extension uses vault parameters or not.
+     */
+    useVault?: boolean;
 }
 
 export interface ExtensionCompileCode {