@picteus/extension-sdk 0.2.5

package/dist/picteusExtension.d.ts

@@ -0,0 +1,145 @@
+import { Socket } from "socket.io-client";
+import { Configuration, ImageApi, ImageAttachmentApi, Json, RepositoryApi } from "./index.js";
+export type NotificationValue = Record<string, any>;
+export declare enum NotificationReturnedErrorCause {
+    Cancel = 0,
+    Error = 1
+}
+export declare class NotificationReturnedError extends Error {
+    readonly reason: NotificationReturnedErrorCause;
+    constructor(message: string, reason: NotificationReturnedErrorCause);
+}
+export interface NotificationsParametersIntent {
+    readonly parameters: Json;
+}
+export declare enum NotificationsUiAnchor {
+    Modal = "modal",
+    Sidebar = "sidebar",
+    ImageDetail = "imageDetail"
+}
+export interface NotificationsUi {
+    readonly anchor: NotificationsUiAnchor;
+    readonly url: string;
+}
+export interface NotificationsUiIntent {
+    readonly ui: NotificationsUi;
+}
+export declare enum NotificationsDialogType {
+    Error = "Error",
+    Info = "Info",
+    Question = "Question"
+}
+export interface NotificationsDialog {
+    readonly type: NotificationsDialogType;
+    readonly title: string;
+    readonly description: string;
+    readonly details?: string;
+    readonly buttons: {
+        yes: string;
+        no?: string;
+    };
+}
+export interface NotificationsDialogIntent {
+    readonly dialog: NotificationsDialog;
+}
+export interface NotificationsImage {
+    readonly imageId: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly details?: string;
+}
+export interface NotificationsImages {
+    readonly images: NotificationsImage[];
+    readonly title?: string;
+    readonly description?: string;
+    readonly details?: string;
+}
+export interface NotificationsImagesIntent {
+    readonly images: NotificationsImages;
+}
+export declare enum NotificationsShowType {
+    ExtensionSettings = "ExtensionSettings",
+    Image = "Image",
+    Repository = "Repository"
+}
+export interface NotificationsShow {
+    readonly type: NotificationsShowType;
+    readonly id: string;
+}
+export interface NotificationsShowIntent {
+    readonly show: NotificationsShow;
+}
+export type NotificationsIntent = NotificationsParametersIntent | NotificationsUiIntent | NotificationsDialogIntent | NotificationsImagesIntent | NotificationsShowIntent;
+export declare enum NotificationEvent {
+    ProcessRunCommand = "process.runCommand",
+    ImageCreated = "image.created",
+    ImageUpdated = "image.updated",
+    ImageDeleted = "image.deleted",
+    ImageComputeFeatures = "image.computeFeatures",
+    ImageComputeEmbeddings = "image.computeEmbeddings",
+    ImageComputeTags = "image.computeTags",
+    ImageRunCommand = "image.runCommand",
+    TextComputeEmbeddings = "text.computeEmbeddings"
+}
+interface LeveledLogMethod {
+    (message: string, ...meta: any[]): Logger;
+    (message: any): Logger;
+    (infoObject: object): Logger;
+}
+export declare class Logger {
+    readonly debug: LeveledLogMethod;
+    readonly info: LeveledLogMethod;
+    readonly warn: LeveledLogMethod;
+    readonly error: LeveledLogMethod;
+}
+declare class ExtensionParameters {
+    readonly apiKey: string;
+    readonly extensionId: string;
+    readonly webServicesBaseUrl: string;
+    constructor(parameters: Record<string, any>);
+}
+declare class MessageSender {
+    private readonly logger;
+    private readonly parameters;
+    private readonly socket;
+    private readonly toString;
+    private readonly contextId?;
+    constructor(logger: Logger, parameters: ExtensionParameters, socket: Socket, toString: () => string, contextId?: string);
+    sendMessage(channel: string, body: Record<string, any>, callback?: (result: any) => Promise<void>): void;
+}
+export declare class Communicator {
+    private readonly logger;
+    private readonly sender;
+    constructor(logger: Logger, sender: MessageSender);
+    sendLog(message: string, level: "debug" | "info" | "warn" | "error"): void;
+    sendNotification(value: Record<string, any>): void;
+    launchIntent<T>(intent: NotificationsIntent): Promise<T>;
+    private sendMessage;
+}
+export declare class PicteusExtension {
+    static getSdkVersion(): string;
+    protected readonly logger: Logger;
+    protected readonly parameters: ExtensionParameters;
+    protected readonly extensionId: string;
+    protected readonly webServicesBaseUrl: string;
+    protected readonly apiKey: string;
+    protected readonly configuration: Configuration;
+    private socket?;
+    private globalCommunicator?;
+    constructor();
+    run(): Promise<void>;
+    protected toString(): string;
+    protected initialize(): Promise<boolean>;
+    protected onReady(communicator?: Communicator): Promise<void>;
+    protected onTerminate(): Promise<void>;
+    protected onEvent(communicator: Communicator, event: string, value: NotificationValue): Promise<any>;
+    protected getRepositoryApi(): RepositoryApi;
+    protected getImageApi(): ImageApi;
+    protected getImageAttachmentApi(): ImageAttachmentApi;
+    protected getSettings(): Promise<Record<string, any>>;
+    private getParameters;
+    private connectSocket;
+    private disconnectSocket;
+    private getApiConfiguration;
+}
+export {};

package/dist/picteusExtension.js

@@ -0,0 +1,302 @@
+import path, { dirname } from "node:path";
+import fs from "node:fs";
+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 { Configuration, ExtensionApi, ImageApi, ImageAttachmentApi, 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 {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+export var NotificationsUiAnchor;
+(function (NotificationsUiAnchor) {
+    // noinspection JSUnusedGlobalSymbols
+    NotificationsUiAnchor["Modal"] = "modal";
+    NotificationsUiAnchor["Sidebar"] = "sidebar";
+    NotificationsUiAnchor["ImageDetail"] = "imageDetail";
+})(NotificationsUiAnchor || (NotificationsUiAnchor = {}));
+export var NotificationsDialogType;
+(function (NotificationsDialogType) {
+    NotificationsDialogType["Error"] = "Error";
+    NotificationsDialogType["Info"] = "Info";
+    NotificationsDialogType["Question"] = "Question";
+})(NotificationsDialogType || (NotificationsDialogType = {}));
+export var NotificationsShowType;
+(function (NotificationsShowType) {
+    NotificationsShowType["ExtensionSettings"] = "ExtensionSettings";
+    NotificationsShowType["Image"] = "Image";
+    NotificationsShowType["Repository"] = "Repository";
+})(NotificationsShowType || (NotificationsShowType = {}));
+export var NotificationEvent;
+(function (NotificationEvent) {
+    NotificationEvent["ProcessRunCommand"] = "process.runCommand";
+    NotificationEvent["ImageCreated"] = "image.created";
+    NotificationEvent["ImageUpdated"] = "image.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 dateToString = (date) => {
+    function padNumber(number, length) {
+        return number.toString().padStart(length, "0");
+    }
+    return `${padNumber(date.getHours(), 2)}:${padNumber(date.getMinutes(), 2)}:${padNumber(date.getSeconds(), 2)}.${padNumber(date.getMilliseconds(), 3)}`;
+};
+const computeLeveledLogMethod = (logger, level) => {
+    return function (message, ...meta) {
+        // @ts-ignore
+        const consoleFunction = console[level];
+        const prefix = `${dateToString(new Date())} | ${process.pid} | main [${level.toUpperCase().padStart(5, " ")}]`;
+        consoleFunction(`${prefix}: ${message}`, ...meta);
+        return logger;
+    };
+};
+export class Logger {
+    debug = computeLeveledLogMethod(this, "debug");
+    info = computeLeveledLogMethod(this, "info");
+    warn = computeLeveledLogMethod(this, "warn");
+    error = computeLeveledLogMethod(this, "error");
+}
+class ExtensionParameters {
+    apiKey;
+    extensionId;
+    webServicesBaseUrl;
+    constructor(parameters) {
+        this.apiKey = parameters.apiKey;
+        this.extensionId = parameters.extensionId;
+        this.webServicesBaseUrl = parameters.webServicesBaseUrl;
+    }
+}
+class MessageSender {
+    logger;
+    parameters;
+    socket;
+    toString;
+    contextId;
+    constructor(logger, parameters, socket, toString, contextId) {
+        this.logger = logger;
+        this.parameters = parameters;
+        this.socket = socket;
+        this.toString = toString;
+        this.contextId = contextId;
+    }
+    sendMessage(channel, body, callback) {
+        const contextId = this.contextId;
+        this.logger.debug(`Sending the message '${JSON.stringify(body)}' on channel '${channel}' for ${this.toString()}${contextId === undefined ? "" : ` attached to the context with id '${contextId}'`}${callback === undefined ? "" : " and waiting for a callback"}`);
+        const value = {
+            apiKey: this.parameters.apiKey,
+            extensionId: this.parameters.extensionId,
+            ...body
+        };
+        if (contextId !== undefined) {
+            value.contextId = contextId;
+        }
+        if (callback === undefined) {
+            this.socket.emit(channel, value);
+        }
+        else {
+            this.socket.emit(channel, value, callback);
+        }
+    }
+}
+const notificationsChannel = "notifications";
+export class Communicator {
+    logger;
+    sender;
+    constructor(logger, sender) {
+        this.logger = logger;
+        this.sender = sender;
+    }
+    sendLog(message, level) {
+        this.logger[level](message);
+        this.sendMessage(notificationsChannel, { log: { message, level } });
+    }
+    sendNotification(value) {
+        this.sendMessage(notificationsChannel, { notification: value });
+    }
+    async launchIntent(intent) {
+        return await new Promise((resolve, reject) => {
+            this.sendMessage(notificationsChannel, { intent }, async ({ value, cancel, error }) => {
+                this.logger.debug(`Received a result related to the intent '${JSON.stringify(intent)}' for ${this.toString()}`);
+                if (cancel !== undefined) {
+                    reject(new NotificationReturnedError(cancel, NotificationReturnedErrorCause.Cancel));
+                }
+                else if (error !== undefined) {
+                    reject(new NotificationReturnedError(error, NotificationReturnedErrorCause.Error));
+                }
+                else {
+                    resolve(value);
+                }
+            });
+        });
+    }
+    sendMessage(channel, body, callback) {
+        this.sender.sendMessage(channel, body, callback);
+    }
+}
+export class PicteusExtension {
+    static getSdkVersion() {
+        return JSON.parse(fs.readFileSync(path.join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), { encoding: "utf8" })).version;
+    }
+    logger = new Logger();
+    parameters;
+    extensionId;
+    webServicesBaseUrl;
+    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) => {
+            this.logger.info(`Received the termination signal '${signal}' regarding the ${this.toString()}`);
+            try {
+                await this.onTerminate();
+            }
+            finally {
+                this.disconnectSocket();
+                this.logger.info(`Exiting from the ${this.toString()}`);
+                process.exit(0);
+            }
+        });
+        this.parameters = new ExtensionParameters(this.getParameters());
+        this.extensionId = this.parameters.extensionId;
+        this.webServicesBaseUrl = this.parameters.webServicesBaseUrl;
+        this.apiKey = this.parameters.apiKey;
+        this.configuration = this.getApiConfiguration();
+    }
+    async run() {
+        this.logger.info(`Running the ${(this.toString())}`);
+        let result;
+        try {
+            result = await this.initialize();
+        }
+        catch (error) {
+            this.logger.error(`The initialization of the ${this.toString()} failed. Reason: '${error.message}'`, error);
+            process.exit(1);
+        }
+        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);
+                }
+            }
+            else {
+                await this.onReady();
+            }
+        }
+        finally {
+            this.logger.info(`The ${this.toString()} is over`);
+        }
+    }
+    toString() {
+        return `extension` + (this.extensionId === undefined ? "" : ` with id '${this.extensionId}'`) + ` of class '${this.constructor.name}'`;
+    }
+    async initialize() {
+        return true;
+    }
+    async onReady(communicator) {
+    }
+    async onTerminate() {
+    }
+    // noinspection JSUnusedLocalSymbols
+    async onEvent(communicator, event, value) {
+    }
+    getRepositoryApi() {
+        return new RepositoryApi(this.configuration);
+    }
+    getImageApi() {
+        return new ImageApi(this.configuration);
+    }
+    getImageAttachmentApi() {
+        return new ImageAttachmentApi(this.configuration);
+    }
+    async getSettings() {
+        return (await new ExtensionApi(this.configuration).extensionGetSettings({ id: this.extensionId })).value;
+    }
+    getParameters() {
+        return JSON.parse(fs.readFileSync(path.join(".", "parameters.json"), { encoding: "utf8" }));
+    }
+    connectSocket() {
+        this.logger.info(`Connecting the ${this.toString()} to the server`);
+        const options = {
+            autoConnect: true,
+            transports: ["websocket"],
+            rejectUnauthorized: false
+        };
+        this.socket = io(this.parameters.webServicesBaseUrl, options);
+        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`);
+            await this.onReady(this.globalCommunicator);
+        });
+        this.socket.on("connect_error", async () => {
+            this.logger.warn(`The ${this.toString()} socket connection failed"`);
+        });
+        this.socket.on("disconnect", async () => {
+            this.logger.info(`The ${this.toString()} socket is disconnected`);
+        });
+        this.socket.on("events", async (command, onResult) => {
+            const { channel, contextId, milliseconds, value } = command;
+            this.logger.info(`The ${this.toString()} received at ${dateToString(new Date(milliseconds))} the command '${JSON.stringify(command)}' on channel '${channel}' attached to the context with id '${contextId}'`);
+            const sender = new MessageSender(this.logger, this.parameters, this.socket, () => {
+                return this.toString();
+            }, contextId);
+            const communicator = new Communicator(this.logger, sender);
+            let result;
+            let success = false;
+            try {
+                result = await this.onEvent(communicator, channel, 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");
+                return;
+            }
+            finally {
+                sender.sendMessage(notificationsChannel, { acknowledgment: { success } });
+            }
+            if (result !== undefined && onResult !== undefined) {
+                onResult(result);
+            }
+        });
+        globalSender.sendMessage("connection", {
+            isOpen: true,
+            sdkVersion: PicteusExtension.getSdkVersion(),
+            environment: "node"
+        });
+    }
+    disconnectSocket() {
+        if (this.socket !== undefined && this.socket.disconnected === false) {
+            this.logger.info(`Disconnecting the ${this.toString()} from the server`);
+            this.socket.close();
+            this.socket = undefined;
+        }
+    }
+    getApiConfiguration() {
+        // 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
+        process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+        return new Configuration({ basePath: this.webServicesBaseUrl, apiKey: this.apiKey });
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@picteus/extension-sdk",
+  "version": "0.2.5",
+  "productName": "Picteus TypeScript SDK",
+  "description": "The Picteus extension TypeScript SDK.",
+  "keywords": [
+    "picteus",
+    "extension",
+    "sdk"
+  ],
+  "author": {
+    "name": "Édouard Mercier",
+    "email": "edouard@koppasoft.com",
+    "url": "https://github.com/edouardmercier"
+  },
+  "license": "Copyright (C) 2024 KoppaSoft. The code hereby is the private full property of the KoppaSoft company, Paris, France. You have no right to re-use or modify it. There are no open-source, nor free license attached to it!",
+  "private": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://github.com/picteus/Picteus.git",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/picteus/Picteus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/picteus/Picteus/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "scripts": {
+    "compile": "tsc && tsc-alias",
+    "build": "tsup src/index.ts --tsconfig tsconfig.json --format cjs,esm --dts --clean --minify-whitespace --minify-identifiers --minify-syntax"
+  },
+  "devDependencies": {
+    "typescript": "5.9.2",
+    "@types/node": "20.19.0",
+    "tsc-alias": "1.8.16",
+    "tsup": "8.5.0"
+  },
+  "dependencies": {
+    "socket.io-client": "4.8.1"
+  }
+}