@picteus/extension-sdk 0.14.0 → 0.16.0

package/dist/picteusExtension.d.ts

@@ -1,28 +1,35 @@
 import { Socket } from "socket.io-client";
 import { ApiSecretApi, CollectionApi, Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, Manifest, MiscellaneousApi, RepositoryApi } from "./index.js";
 import { Intent } from "./intents.js";
-export type NotificationValue = Record<string, any>;
-export declare enum NotificationReturnedErrorCause {
-    Cancel = 0,
-    Error = 1
+export type EventValue = Record<string, any>;
+export declare const InstructionReturnedErrorCause: {
+    readonly Cancel: 0;
+    readonly Error: 1;
+};
+export type InstructionReturnedErrorCause = (typeof InstructionReturnedErrorCause)[keyof typeof InstructionReturnedErrorCause];
+export declare class InstructionReturnedError extends Error {
+    readonly reason: InstructionReturnedErrorCause;
+    constructor(message: string, reason: InstructionReturnedErrorCause);
 }
-export declare class NotificationReturnedError extends Error {
-    readonly reason: NotificationReturnedErrorCause;
-    constructor(message: string, reason: NotificationReturnedErrorCause);
-}
-export declare enum NotificationEvent {
-    ProcessRunCommand = "process.runCommand",
-    ImageCreated = "image.created",
-    ImageUpdated = "image.updated",
-    ImageTagsUpdated = "image.tags.updated",
-    ImageFeaturesUpdated = "image.features.updated",
-    ImageDeleted = "image.deleted",
-    ImageComputeFeatures = "image.computeFeatures",
-    ImageComputeEmbeddings = "image.computeEmbeddings",
-    ImageComputeTags = "image.computeTags",
-    ImageRunCommand = "image.runCommand",
-    TextComputeEmbeddings = "text.computeEmbeddings"
+export type CommandParameters = Record<string, any>;
+export declare class CommandError extends Error {
+    static fromError(error: CommandParameters): CommandError;
+    constructor(message: string);
 }
+export declare const EventName: {
+    readonly ProcessRunCommand: "process.runCommand";
+    readonly ImageCreated: "image.created";
+    readonly ImageUpdated: "image.updated";
+    readonly ImageTagsUpdated: "image.tags.updated";
+    readonly ImageFeaturesUpdated: "image.features.updated";
+    readonly ImageDeleted: "image.deleted";
+    readonly ImageComputeFeatures: "image.computeFeatures";
+    readonly ImageComputeEmbeddings: "image.computeEmbeddings";
+    readonly ImageComputeTags: "image.computeTags";
+    readonly ImageRunCommand: "image.runCommand";
+    readonly TextComputeEmbeddings: "text.computeEmbeddings";
+};
+export type EventName = (typeof EventName)[keyof typeof EventName];
 export declare class Helper {
     static readonly GENERATION_RECIPE_SCHEMA_VERSION = 1;
 }
@@ -61,7 +68,7 @@ declare class MessageSender {
     private _maximumPayloadSizeInBytes?;
     constructor(logger: Logger, parameters: ExtensionParameters, socket: Socket, toString: () => string, contextId?: string);
     set maximumPayloadSizeInBytes(value: number);
-    sendMessage(channel: string, body: Record<string, any>, callback?: (result: any) => Promise<void>): void;
+    sendMessage(event: string, body: Record<string, any>, callback?: (result: any) => Promise<void>): void;
 }
 export declare class Communicator {
     private readonly logger;
@@ -73,6 +80,10 @@ export declare class Communicator {
     private sendMessage;
 }
 export type SettingsValue = Record<string, any>;
+export type Versions = {
+    previous: string | undefined;
+    current: string;
+};
 export declare class PicteusExtension {
     static getManifest(): Manifest;
     static getSdkVersion(): string;
@@ -86,15 +97,26 @@ export declare class PicteusExtension {
     protected readonly apiKey: string;
     protected readonly configuration: Configuration;
     private socket?;
-    private globalCommunicator?;
     constructor();
     run(): Promise<void>;
     protected toString(): string;
     protected initialize(): Promise<boolean>;
+    protected onUpgrade(_communicator: Communicator, _versions: Versions): Promise<void>;
     protected onReady(_communicator?: Communicator): Promise<void>;
     protected onTerminate(): Promise<void>;
     protected onSettings(_communicator: Communicator, _value: SettingsValue): Promise<void>;
-    protected onEvent(_communicator: Communicator, _event: string, _value: NotificationValue): Promise<any>;
+    protected onEvent(communicator: Communicator, event: EventName, value: EventValue): Promise<any>;
+    protected onImageCreated(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onImageUpdated(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onImageDeleted(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onImageTagsUpdated(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onImageFeaturesUpdated(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onComputeImageTags(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onComputeImageFeatures(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onComputeImageEmbeddings(_communicator: Communicator, _imageId: string): Promise<void>;
+    protected onImagesCommand(_communicator: Communicator, _commandId: string, _imageIds: string[], _parameters: CommandParameters): Promise<void>;
+    protected onProcessCommand(_communicator: Communicator, _commandId: string, _parameters: CommandParameters): Promise<void>;
+    protected onComputeTextEmbeddings(_communicator: Communicator, _text: string): Promise<number[]>;
     protected getMiscellaneousApi(): MiscellaneousApi;
     protected getApiSecretApi(): ApiSecretApi;
     protected getExtensionApi(): ExtensionApi;
@@ -106,6 +128,7 @@ export declare class PicteusExtension {
     private getParameters;
     private connectSocket;
     private disconnectSocket;
+    private exit;
     private getApiConfiguration;
 }
 export {};

package/dist/picteusExtension.js

@@ -4,35 +4,39 @@ import { fileURLToPath } from "node:url";
 // We do not import the "process" package on purpose, otherwise we get the runtime error "process.on is not a function"
 import console from "node:console";
 import { io } from "socket.io-client";
-import { ApiSecretApi, CollectionApi, Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, ManifestFromJSON, MiscellaneousApi, RepositoryApi } from "./index.js";
-export var NotificationReturnedErrorCause;
-(function (NotificationReturnedErrorCause) {
-    NotificationReturnedErrorCause[NotificationReturnedErrorCause["Cancel"] = 0] = "Cancel";
-    NotificationReturnedErrorCause[NotificationReturnedErrorCause["Error"] = 1] = "Error";
-})(NotificationReturnedErrorCause || (NotificationReturnedErrorCause = {}));
-export class NotificationReturnedError extends Error {
+import { ApiSecretApi, CollectionApi, Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, IntentToastType, ManifestFromJSON, MiscellaneousApi, RepositoryApi } from "./index.js";
+export const InstructionReturnedErrorCause = { Cancel: 0, Error: 1 };
+export class InstructionReturnedError extends Error {
     reason;
     constructor(message, reason) {
         super(message);
         this.reason = reason;
     }
 }
-// noinspection JSUnusedGlobalSymbols
-export var NotificationEvent;
-(function (NotificationEvent) {
-    NotificationEvent["ProcessRunCommand"] = "process.runCommand";
-    NotificationEvent["ImageCreated"] = "image.created";
-    NotificationEvent["ImageUpdated"] = "image.updated";
-    NotificationEvent["ImageTagsUpdated"] = "image.tags.updated";
-    NotificationEvent["ImageFeaturesUpdated"] = "image.features.updated";
-    NotificationEvent["ImageDeleted"] = "image.deleted";
-    NotificationEvent["ImageComputeFeatures"] = "image.computeFeatures";
-    NotificationEvent["ImageComputeEmbeddings"] = "image.computeEmbeddings";
-    NotificationEvent["ImageComputeTags"] = "image.computeTags";
-    NotificationEvent["ImageRunCommand"] = "image.runCommand";
-    NotificationEvent["TextComputeEmbeddings"] = "text.computeEmbeddings";
-})(NotificationEvent || (NotificationEvent = {}));
-const extensionSettingsEvent = "extension.settings";
+export class CommandError extends Error {
+    static fromError(error) {
+        return new CommandError(error.message);
+    }
+    constructor(message) {
+        super(message);
+    }
+}
+export const EventName = {
+    ProcessRunCommand: "process.runCommand",
+    ImageCreated: "image.created",
+    ImageUpdated: "image.updated",
+    ImageTagsUpdated: "image.tags.updated",
+    ImageFeaturesUpdated: "image.features.updated",
+    ImageDeleted: "image.deleted",
+    ImageComputeFeatures: "image.computeFeatures",
+    ImageComputeEmbeddings: "image.computeEmbeddings",
+    ImageComputeTags: "image.computeTags",
+    ImageRunCommand: "image.runCommand",
+    TextComputeEmbeddings: "text.computeEmbeddings"
+};
+const extensionVersionsChannel = "extension.versions";
+const extensionReadyChannel = "extension.ready";
+const extensionSettingsChannel = "extension.settings";
 // noinspection JSUnusedGlobalSymbols
 export class Helper {
     static GENERATION_RECIPE_SCHEMA_VERSION = 1;
@@ -40,7 +44,7 @@ export class Helper {
 export class ApiCallError extends Error {
     details;
     constructor(details) {
-        super();
+        super(details.message);
         this.details = details;
     }
 }
@@ -106,9 +110,9 @@ class MessageSender {
     set maximumPayloadSizeInBytes(value) {
         this._maximumPayloadSizeInBytes = value;
     }
-    sendMessage(channel, body, callback) {
+    sendMessage(event, body, callback) {
         const contextId = this.contextId;
-        this.logger.debug(`Sending the message '${stringifyWithStrippedBuffers(body)}' on channel '${channel}' for ${this.toString()}${contextId === undefined ? "" : ` attached to the context with id '${contextId}'`}${callback === undefined ? "" : " and waiting for a callback"}`);
+        this.logger.debug(`Sending the message '${stringifyWithStrippedBuffers(body)}' through the '${event}' event for ${this.toString()}${contextId === undefined ? "" : ` attached to the context with id '${contextId}'`}${callback === undefined ? "" : " and waiting for a callback"}`);
         const value = {
             extensionId: this.parameters.extensionId,
             ...body
@@ -121,14 +125,14 @@ class MessageSender {
             value.contextId = contextId;
         }
         if (callback === undefined) {
-            this.socket.emit(channel, value);
+            this.socket.emit(event, value);
         }
         else {
-            this.socket.emit(channel, value, callback);
+            this.socket.emit(event, value, callback);
         }
     }
 }
-const notificationsChannel = "notifications";
+const instructionsEvent = "instructions";
 export class Communicator {
     logger;
     sender;
@@ -138,21 +142,21 @@ export class Communicator {
     }
     sendLog(message, level) {
         this.logger[level](message);
-        this.sendMessage(notificationsChannel, { log: { message, level } });
+        this.sendMessage(instructionsEvent, { log: { message, level } });
     }
     // noinspection JSUnusedGlobalSymbols
     sendNotification(value) {
-        this.sendMessage(notificationsChannel, { notification: value });
+        this.sendMessage(instructionsEvent, { notification: value });
     }
     async launchIntent(intent) {
         return await new Promise((resolve, reject) => {
-            this.sendMessage(notificationsChannel, { intent }, async ({ value, cancel, error }) => {
+            this.sendMessage(instructionsEvent, { intent }, async ({ value, cancel, error }) => {
                 this.logger.debug(`Received a result related to the intent '${stringifyWithStrippedBuffers(intent)}' for ${this.sender.toString()}`);
                 if (cancel !== undefined) {
-                    reject(new NotificationReturnedError(cancel, NotificationReturnedErrorCause.Cancel));
+                    reject(new InstructionReturnedError(cancel, InstructionReturnedErrorCause.Cancel));
                 }
                 else if (error !== undefined) {
-                    reject(new NotificationReturnedError(error, NotificationReturnedErrorCause.Error));
+                    reject(new InstructionReturnedError(error, InstructionReturnedErrorCause.Error));
                 }
                 else {
                     resolve(value);
@@ -160,8 +164,8 @@ export class Communicator {
             });
         });
     }
-    sendMessage(channel, body, callback) {
-        this.sender.sendMessage(channel, body, callback);
+    sendMessage(event, body, callback) {
+        this.sender.sendMessage(event, body, callback);
     }
 }
 export class PicteusExtension {
@@ -171,6 +175,7 @@ export class PicteusExtension {
     static getSdkVersion() {
         return JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), { encoding: "utf8" })).version;
     }
+    // noinspection JSUnusedGlobalSymbols
     static getCacheDirectoryPath() {
         return path.join(PicteusExtension.getExtensionHomeDirectoryPath(), ".cache");
     }
@@ -185,7 +190,6 @@ export class PicteusExtension {
     apiKey;
     configuration;
     socket;
-    globalCommunicator;
     constructor() {
         this.logger.info(`Instantiating the ${this.toString()} through the process with id '${process.pid}' relying on the SDK version '${PicteusExtension.getSdkVersion()}'`);
         process.on("SIGTERM", async (signal) => {
@@ -212,41 +216,105 @@ export class PicteusExtension {
             result = await this.initialize();
         }
         catch (error) {
-            this.logger.error(`The initialization of the ${this.toString()} failed. Reason: '${error.message}'`, error);
-            process.exit(1);
+            this.exit(1, error, "the initialization failed");
         }
-        try {
-            if (result === true) {
-                try {
-                    this.connectSocket();
-                }
-                catch (error) {
-                    this.logger.error(`The connection of the ${this.toString()} failed. Reason: '${error.message}'`, error);
-                    process.exit(2);
-                }
+        if (result === true) {
+            try {
+                this.connectSocket();
             }
-            else {
-                await this.onReady();
+            catch (error) {
+                this.exit(2, error, "the connection failed");
             }
         }
-        finally {
-            this.logger.info(`The ${this.toString()} is over`);
+        else {
+            await this.onReady();
         }
     }
     toString() {
-        return `extension` + (this.extensionId === undefined ? "" : ` with id '${this.extensionId}'`) + ` of class '${this.constructor.name}'`;
+        return `extension${this.extensionId === undefined ? "" : ` with id '${this.extensionId}'`} of class '${this.constructor.name}'`;
     }
     async initialize() {
         return true;
     }
+    async onUpgrade(_communicator, _versions) {
+    }
     async onReady(_communicator) {
     }
     async onTerminate() {
     }
     async onSettings(_communicator, _value) {
-        return Promise.resolve();
     }
-    async onEvent(_communicator, _event, _value) {
+    async onEvent(communicator, event, value) {
+        if (event === EventName.ImageCreated) {
+            const imageId = value["id"];
+            return await this.onImageCreated(communicator, imageId);
+        }
+        else if (event === EventName.ImageUpdated) {
+            const imageId = value["id"];
+            return await this.onImageUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageDeleted) {
+            const imageId = value["id"];
+            return await this.onImageDeleted(communicator, imageId);
+        }
+        else if (event === EventName.ImageTagsUpdated) {
+            const imageId = value["id"];
+            return await this.onImageTagsUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageFeaturesUpdated) {
+            const imageId = value["id"];
+            return await this.onImageFeaturesUpdated(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeTags) {
+            const imageId = value["id"];
+            return await this.onComputeImageTags(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeFeatures) {
+            const imageId = value["id"];
+            return await this.onComputeImageFeatures(communicator, imageId);
+        }
+        else if (event === EventName.ImageComputeEmbeddings) {
+            const imageId = value["id"];
+            return await this.onComputeImageEmbeddings(communicator, imageId);
+        }
+        else if (event === EventName.ImageRunCommand) {
+            const commandId = value["commandId"];
+            const imageIds = value["imageIds"];
+            const parameters = value["parameters"] ?? {};
+            return await this.onImagesCommand(communicator, commandId, imageIds, parameters);
+        }
+        else if (event === EventName.ProcessRunCommand) {
+            const commandId = value["commandId"];
+            const parameters = value["parameters"] ?? {};
+            return await this.onProcessCommand(communicator, commandId, parameters);
+        }
+        else if (event === EventName.TextComputeEmbeddings) {
+            const text = value["text"];
+            return await this.onComputeTextEmbeddings(communicator, text);
+        }
+    }
+    async onImageCreated(_communicator, _imageId) {
+    }
+    async onImageUpdated(_communicator, _imageId) {
+    }
+    async onImageDeleted(_communicator, _imageId) {
+    }
+    async onImageTagsUpdated(_communicator, _imageId) {
+    }
+    async onImageFeaturesUpdated(_communicator, _imageId) {
+    }
+    async onComputeImageTags(_communicator, _imageId) {
+    }
+    async onComputeImageFeatures(_communicator, _imageId) {
+    }
+    async onComputeImageEmbeddings(_communicator, _imageId) {
+    }
+    async onImagesCommand(_communicator, _commandId, _imageIds, _parameters) {
+    }
+    async onProcessCommand(_communicator, _commandId, _parameters) {
+    }
+    async onComputeTextEmbeddings(_communicator, _text) {
+        return [];
     }
     // noinspection JSUnusedGlobalSymbols
     getMiscellaneousApi() {
@@ -293,7 +361,6 @@ export class PicteusExtension {
         const globalSender = new MessageSender(this.logger, this.parameters, this.socket, () => {
             return this.toString();
         });
-        this.globalCommunicator = new Communicator(this.logger, globalSender);
         this.socket.on("connect", async () => {
             this.logger.info(`The ${this.toString()} socket is connected`);
             globalSender.sendMessage("connection", {
@@ -304,7 +371,6 @@ export class PicteusExtension {
                 const maximumPayloadSizeInBytes = result.maximumPayloadSizeInBytes;
                 this.logger.debug(`The ${this.toString()} socket has a maximum payload size of ${maximumPayloadSizeInBytes} bytes`);
                 globalSender.maximumPayloadSizeInBytes = maximumPayloadSizeInBytes;
-                await this.onReady(this.globalCommunicator);
             });
         });
         this.socket.on("connect_error", async () => {
@@ -321,22 +387,53 @@ export class PicteusExtension {
             }, contextId);
             sender.maximumPayloadSizeInBytes = globalSender.maximumPayloadSizeInBytes;
             const communicator = new Communicator(this.logger, sender);
-            const isRegularEvent = channel !== extensionSettingsEvent;
+            const requiresResult = channel !== extensionSettingsChannel;
             let result;
             let success = false;
+            let eventName;
             try {
-                result = await (isRegularEvent === true ? this.onEvent(communicator, channel, value) : this.onSettings(communicator, value.value));
+                if (channel === extensionSettingsChannel) {
+                    result = await this.onSettings(communicator, value.value);
+                }
+                else if (channel === extensionVersionsChannel) {
+                    const { upgrade, ...versions } = value;
+                    if (upgrade === true) {
+                        await this.onUpgrade(communicator, versions);
+                        result = true;
+                    }
+                    else {
+                        result = true;
+                    }
+                }
+                else if (channel === extensionReadyChannel) {
+                    try {
+                        await this.onReady(communicator);
+                        result = true;
+                    }
+                    catch (error) {
+                        this.exit(3, error, "an error occurred during the execution of the 'onReady()' method: stopping the process");
+                    }
+                }
+                else {
+                    eventName = channel;
+                    result = await this.onEvent(communicator, eventName, value);
+                }
                 success = true;
             }
             catch (error) {
                 // We want the process to continue even if an exception occurs
                 this.logger.error(`An error occurred during the handling of the event on channel '${channel}'`, error);
-                communicator.sendLog(`The handling of the event failed for the ${this.toString()}. Reason: '${error.message}'`, "error");
+                if ((eventName === EventName.ImageRunCommand || eventName === EventName.ProcessRunCommand) && error instanceof CommandError) {
+                    void communicator.launchIntent({ toast: { type: IntentToastType.Error, subtitle: error.message } });
+                }
+                else {
+                    communicator.sendLog(`The handling of the event failed for the ${this.toString()}. Reason: '${error.message}'`, "error");
+                }
             }
             finally {
-                sender.sendMessage(notificationsChannel, { acknowledgment: { success } });
+                sender.sendMessage(instructionsEvent, { acknowledgment: { success } });
             }
-            if (isRegularEvent === true && onResult !== undefined) {
+            if (requiresResult === true && onResult !== undefined) {
                 onResult(result);
             }
         });
@@ -348,6 +445,10 @@ export class PicteusExtension {
             this.socket = undefined;
         }
     }
+    exit(code, error, message) {
+        this.logger.error(`For the ${this.toString()}, ${message}. Reason: '${error.message}'`, error);
+        process.exit(code);
+    }
     getApiConfiguration() {
         if (this.parameters.webServicesBaseUrl.startsWith("https://localhost") == true) {
             // This enables to discard the warning log message, caused by the fact that we are issuing HTTPS request on the localhost exposing a self-served certificate
@@ -374,7 +475,15 @@ export class PicteusExtension {
                     message = await response.text();
                 }
                 return Promise.reject(new ApiCallError({ status: response.status, code, message }));
-            }
+            },
+            middleware: [
+                {
+                    onError: async (context) => {
+                        // We rethrow the original error directly, e.g. an "ApiCallError"
+                        throw context.error;
+                    }
+                }
+            ]
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picteus/extension-sdk",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "productName": "Picteus TypeScript SDK",
   "description": "The Picteus extension TypeScript SDK.",
   "keywords": [