@aiot-nexus/plugin-sdk 1.0.0

package/dev-host/preload.js

@@ -0,0 +1,22 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const { contextBridge, ipcRenderer } = require("electron");
+
+const ipcChannels = {
+  getConfig: "nexus-plugin-dev:get-config",
+  invoke: "nexus-plugin-dev:invoke",
+  frameReady: "nexus-plugin-dev:frame-ready"
+};
+
+contextBridge.exposeInMainWorld("nexusPluginDevHost", {
+  getConfig: function getConfig() {
+    return ipcRenderer.invoke(ipcChannels.getConfig);
+  },
+  invoke: function invoke(request) {
+    return ipcRenderer.invoke(ipcChannels.invoke, request);
+  },
+  notifyFrameReady: function notifyFrameReady() {
+    ipcRenderer.send(ipcChannels.frameReady);
+  }
+});

package/dist/.generated/plugin-framework-version.d.ts

@@ -0,0 +1,11 @@
+export declare const PLUGIN_FRAMEWORK_VERSION = "1.0.0";
+export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+export declare const PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+export interface ParsedPluginVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parsePluginCompatibleVersion(value: string): ParsedPluginVersion | undefined;
+export declare function comparePluginVersions(left: string, right: string): number | undefined;
+export declare function isPluginFrameworkVersionCompatible(requiredVersion: string, supportedVersion?: string): boolean;

package/dist/.generated/plugin-framework-version.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
+exports.PLUGIN_FRAMEWORK_VERSION = "1.0.0";
+exports.PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+function parsePluginCompatibleVersion(value) {
+    const match = /^(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*))?(?:\.(0|[1-9][0-9]*))?$/.exec(value.trim());
+    if (!match) {
+        return undefined;
+    }
+    const segments = [Number(match[1]), Number(match[2] || 0), Number(match[3] || 0)];
+    if (segments.some((segment) => !Number.isSafeInteger(segment))) {
+        return undefined;
+    }
+    return { major: segments[0], minor: segments[1], patch: segments[2] };
+}
+exports.parsePluginCompatibleVersion = parsePluginCompatibleVersion;
+function comparePluginVersions(left, right) {
+    const leftVersion = parsePluginCompatibleVersion(left);
+    const rightVersion = parsePluginCompatibleVersion(right);
+    if (!leftVersion || !rightVersion) {
+        return undefined;
+    }
+    for (const key of ["major", "minor", "patch"]) {
+        const difference = leftVersion[key] - rightVersion[key];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+exports.comparePluginVersions = comparePluginVersions;
+function isPluginFrameworkVersionCompatible(requiredVersion, supportedVersion = exports.PLUGIN_FRAMEWORK_VERSION) {
+    const required = parsePluginCompatibleVersion(requiredVersion);
+    const supported = parsePluginCompatibleVersion(supportedVersion);
+    return Boolean(required && supported && required.major === supported.major && required.minor <= supported.minor);
+}
+exports.isPluginFrameworkVersionCompatible = isPluginFrameworkVersionCompatible;

package/dist/.generated/plugin-manifest.schema.json

@@ -0,0 +1,106 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://aiot-nexus.local/schemas/plugin-manifest.schema.json",
+    "title": "AIoT Nexus Plugin Manifest",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "schemaVersion",
+        "pluginId",
+        "displayNameKey",
+        "descriptionKey",
+        "pluginVersion",
+        "hostApiVersion",
+        "minHostVersion",
+        "supportedCultures",
+        "permissions"
+    ],
+    "properties": {
+        "schemaVersion": { "const": 1 },
+        "pluginId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
+        "displayNameKey": { "type": "string", "minLength": 1 },
+        "descriptionKey": { "type": "string" },
+        "pluginVersion": { "type": "string", "minLength": 1 },
+        "hostApiVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
+        "minHostVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
+        "supportedCultures": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 2 },
+            "uniqueItems": true
+        },
+        "mainEntry": { "type": "string", "minLength": 1 },
+        "rendererEntry": { "type": "string", "minLength": 1 },
+        "permissions": {
+            "type": "array",
+            "items": {
+                "enum": ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog"]
+            },
+            "uniqueItems": true
+        },
+        "deferred": { "type": "boolean" },
+        "resources": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": { "type": "string" }
+            }
+        },
+        "businessEntries": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/businessEntry" }
+        },
+        "tools": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/tool" }
+        },
+        "settingsSections": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/settingsSection" }
+        }
+    },
+    "$defs": {
+        "businessEntry": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["businessId", "titleKey", "iconKey", "section", "order", "component"],
+            "properties": {
+                "businessId": { "type": "string", "minLength": 1 },
+                "titleKey": { "type": "string", "minLength": 1 },
+                "descriptionKey": { "type": "string" },
+                "iconKey": { "type": "string", "minLength": 1 },
+                "section": { "type": "string", "minLength": 1 },
+                "order": { "type": "number" },
+                "component": { "type": "string", "minLength": 1 },
+                "pageRoute": { "type": "string", "minLength": 1 },
+                "isFullBleed": { "type": "boolean" },
+                "showBusinessLogToggle": { "type": "boolean" }
+            }
+        },
+        "tool": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["toolId", "titleKey", "iconKey", "navGroup", "order", "component"],
+            "properties": {
+                "toolId": { "type": "string", "minLength": 1 },
+                "titleKey": { "type": "string", "minLength": 1 },
+                "descriptionKey": { "type": "string" },
+                "iconKey": { "type": "string", "minLength": 1 },
+                "navGroup": { "type": "string", "minLength": 1 },
+                "order": { "type": "number" },
+                "component": { "type": "string", "minLength": 1 }
+            }
+        },
+        "settingsSection": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["sectionId", "titleKey", "order", "component"],
+            "properties": {
+                "sectionId": { "type": "string", "minLength": 1 },
+                "titleKey": { "type": "string", "minLength": 1 },
+                "descriptionKey": { "type": "string" },
+                "order": { "type": "number" },
+                "component": { "type": "string", "minLength": 1 }
+            }
+        }
+    }
+}

package/dist/browser/frame-client.d.ts

@@ -0,0 +1,26 @@
+import type { BusinessLogAppendRequest, BusinessLogEntry, NexusResult, PluginRendererContext, PluginRendererMethod, PluginSettingsDocument } from "../types";
+export type PluginFrameClientErrorCode = "Disposed" | "ProtocolError" | "RequestTimeout";
+export declare class PluginFrameClientError extends Error {
+    readonly code: PluginFrameClientErrorCode;
+    constructor(code: PluginFrameClientErrorCode, message: string);
+}
+export interface PluginFrameClientOptions {
+    frameWindow?: Window;
+    targetWindow?: Window;
+    requestTimeoutMs?: number;
+    autoResize?: boolean;
+    resizeRoot?: HTMLElement;
+}
+export type PluginFrameContextListener = (context: PluginRendererContext) => void;
+export interface PluginFrameClient {
+    waitForContext(): Promise<PluginRendererContext>;
+    onContextChanged(listener: PluginFrameContextListener): () => void;
+    request<TResult>(method: PluginRendererMethod, params?: Record<string, unknown>): Promise<NexusResult<TResult>>;
+    getSettings(): Promise<NexusResult<PluginSettingsDocument>>;
+    updateSettings(values: Record<string, unknown>): Promise<NexusResult<PluginSettingsDocument>>;
+    appendLog(request: BusinessLogAppendRequest): Promise<NexusResult<BusinessLogEntry>>;
+    invokeMain<TInput extends Record<string, unknown>, TResult>(operation: string, input?: TInput): Promise<NexusResult<TResult>>;
+    notifyResize(): void;
+    dispose(): void;
+}
+export declare function createPluginFrameClient(options?: PluginFrameClientOptions): PluginFrameClient;

package/dist/browser/frame-client.mjs

@@ -0,0 +1,239 @@
+const initMessageType = "nexus-plugin:init";
+const contextChangedMessageType = "nexus-plugin:context-changed";
+const readyMessageType = "nexus-plugin:ready";
+const requestMessageType = "nexus-plugin:request";
+const responseMessageType = "nexus-plugin:response";
+const resizeMessageType = "nexus-plugin:resize";
+const defaultRequestTimeoutMs = 15000;
+export class PluginFrameClientError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "PluginFrameClientError";
+        this.code = code;
+    }
+}
+export function createPluginFrameClient(options = {}) {
+    const resolvedFrameWindow = options.frameWindow || (typeof window === "undefined" ? undefined : window);
+    if (!resolvedFrameWindow) {
+        throw new PluginFrameClientError("ProtocolError", "PluginFrame client requires a browser window.");
+    }
+    const frameWindow = resolvedFrameWindow;
+    const targetWindow = options.targetWindow || frameWindow.parent;
+    const requestTimeoutMs = options.requestTimeoutMs === undefined ? defaultRequestTimeoutMs : options.requestTimeoutMs;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+        throw new PluginFrameClientError("ProtocolError", "requestTimeoutMs must be a positive finite number.");
+    }
+    let requestSequence = 0;
+    let disposed = false;
+    let contextValue;
+    let hostOrigin;
+    let contextSettled = false;
+    let contextTimeoutId;
+    let resizeTimer;
+    let resizeObserver;
+    const pendingRequests = new Map();
+    const contextListeners = new Set();
+    let resolveContext;
+    let rejectContext;
+    const contextPromise = new Promise((resolve, reject) => {
+        resolveContext = resolve;
+        rejectContext = reject;
+    });
+    void contextPromise.catch(() => undefined);
+    contextTimeoutId = frameWindow.setTimeout(() => {
+        contextTimeoutId = undefined;
+        if (!contextSettled) {
+            contextSettled = true;
+            rejectContext(new PluginFrameClientError("RequestTimeout", "PluginFrame initialization timed out."));
+        }
+    }, requestTimeoutMs);
+    frameWindow.addEventListener("message", handleMessage);
+    if (options.autoResize !== false) {
+        frameWindow.addEventListener("resize", scheduleResize);
+        const ResizeObserverConstructor = frameWindow.ResizeObserver;
+        if (typeof ResizeObserverConstructor === "function") {
+            const observer = new ResizeObserverConstructor(scheduleResize);
+            observer.observe(options.resizeRoot || frameWindow.document.documentElement);
+            resizeObserver = observer;
+        }
+    }
+    targetWindow.postMessage({ type: readyMessageType }, "*");
+    function waitForContext() {
+        if (disposed) {
+            return Promise.reject(disposedError());
+        }
+        return contextValue ? Promise.resolve(contextValue) : contextPromise;
+    }
+    function onContextChanged(listener) {
+        if (disposed) {
+            throw disposedError();
+        }
+        contextListeners.add(listener);
+        return () => {
+            contextListeners.delete(listener);
+        };
+    }
+    async function request(method, params) {
+        await waitForContext();
+        if (disposed) {
+            throw disposedError();
+        }
+        const requestId = "nexus-sdk-" + Date.now() + "-" + (++requestSequence);
+        return new Promise((resolve, reject) => {
+            const timeoutId = frameWindow.setTimeout(() => {
+                pendingRequests.delete(requestId);
+                reject(new PluginFrameClientError("RequestTimeout", "PluginFrame request timed out: " + method));
+            }, requestTimeoutMs);
+            pendingRequests.set(requestId, {
+                resolve: (result) => resolve(result),
+                reject,
+                timeoutId
+            });
+            post({ type: requestMessageType, requestId, method, params });
+        });
+    }
+    function getSettings() {
+        return request("getSettings");
+    }
+    function updateSettings(values) {
+        return request("updateSettings", { values });
+    }
+    function appendLog(logRequest) {
+        return request("appendLog", logRequest);
+    }
+    function invokeMain(operation, input) {
+        return request("invokeMain", { operation, input });
+    }
+    function handleMessage(event) {
+        if (disposed || event.source !== targetWindow || !isRecord(event.data)) {
+            return;
+        }
+        if (hostOrigin !== undefined && event.origin !== hostOrigin) {
+            return;
+        }
+        if (event.data.type === initMessageType || event.data.type === contextChangedMessageType) {
+            if (!isPluginRendererContext(event.data.context)) {
+                return;
+            }
+            const hadContext = contextValue !== undefined;
+            hostOrigin = event.origin;
+            contextValue = event.data.context;
+            if (!contextSettled) {
+                contextSettled = true;
+                if (contextTimeoutId !== undefined) {
+                    frameWindow.clearTimeout(contextTimeoutId);
+                    contextTimeoutId = undefined;
+                }
+                resolveContext(contextValue);
+            }
+            if (hadContext) {
+                notifyContextChanged(contextValue);
+            }
+            scheduleResize();
+            return;
+        }
+        if (event.data.type !== responseMessageType || typeof event.data.requestId !== "string") {
+            return;
+        }
+        const pending = pendingRequests.get(event.data.requestId);
+        if (!pending) {
+            return;
+        }
+        pendingRequests.delete(event.data.requestId);
+        frameWindow.clearTimeout(pending.timeoutId);
+        if (!isNexusResult(event.data.result)) {
+            pending.reject(new PluginFrameClientError("ProtocolError", "PluginFrame response is malformed."));
+            return;
+        }
+        pending.resolve(event.data.result);
+    }
+    function notifyContextChanged(context) {
+        for (const listener of Array.from(contextListeners)) {
+            try {
+                listener(context);
+            }
+            catch (error) {
+                const logger = frameWindow.console;
+                logger?.error("PluginFrame context listener failed.", error);
+            }
+        }
+    }
+    function scheduleResize() {
+        if (disposed || !contextValue || options.autoResize === false) {
+            return;
+        }
+        if (resizeTimer !== undefined) {
+            frameWindow.clearTimeout(resizeTimer);
+        }
+        if (contextTimeoutId !== undefined) {
+            frameWindow.clearTimeout(contextTimeoutId);
+        }
+        resizeTimer = frameWindow.setTimeout(() => {
+            resizeTimer = undefined;
+            notifyResize();
+        }, 0);
+    }
+    function notifyResize() {
+        if (disposed || !contextValue) {
+            return;
+        }
+        const root = options.resizeRoot || frameWindow.document.documentElement;
+        const body = frameWindow.document.body;
+        const height = Math.max(root.scrollHeight, root.offsetHeight, body?.scrollHeight || 0, body?.offsetHeight || 0);
+        post({ type: resizeMessageType, height });
+    }
+    function post(message) {
+        targetWindow.postMessage(message, hostOrigin && hostOrigin !== "null" ? hostOrigin : "*");
+    }
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        frameWindow.removeEventListener("message", handleMessage);
+        frameWindow.removeEventListener("resize", scheduleResize);
+        resizeObserver?.disconnect();
+        if (resizeTimer !== undefined) {
+            frameWindow.clearTimeout(resizeTimer);
+        }
+        const error = disposedError();
+        if (!contextSettled) {
+            contextSettled = true;
+            rejectContext(error);
+        }
+        for (const pending of pendingRequests.values()) {
+            frameWindow.clearTimeout(pending.timeoutId);
+            pending.reject(error);
+        }
+        pendingRequests.clear();
+        contextListeners.clear();
+    }
+    return { waitForContext, onContextChanged, request, getSettings, updateSettings, appendLog, invokeMain, notifyResize, dispose };
+}
+function disposedError() {
+    return new PluginFrameClientError("Disposed", "PluginFrame client has been disposed.");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPluginRendererContext(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return typeof value.schemaVersion === "number"
+        && typeof value.pluginId === "string"
+        && (value.surface === "business" || value.surface === "tool" || value.surface === "settings")
+        && typeof value.contributionId === "string"
+        && typeof value.language === "string"
+        && (value.themeMode === "light" || value.themeMode === "dark" || value.themeMode === "system")
+        && typeof value.hostApiVersion === "string";
+}
+function isNexusResult(value) {
+    if (!isRecord(value) || typeof value.ok !== "boolean") {
+        return false;
+    }
+    if (value.ok) {
+        return Object.prototype.hasOwnProperty.call(value, "value");
+    }
+    return isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
+}

package/dist/src/browser/frame-client.d.ts

@@ -0,0 +1,26 @@
+import type { BusinessLogAppendRequest, BusinessLogEntry, NexusResult, PluginRendererContext, PluginRendererMethod, PluginSettingsDocument } from "../types";
+export type PluginFrameClientErrorCode = "Disposed" | "ProtocolError" | "RequestTimeout";
+export declare class PluginFrameClientError extends Error {
+    readonly code: PluginFrameClientErrorCode;
+    constructor(code: PluginFrameClientErrorCode, message: string);
+}
+export interface PluginFrameClientOptions {
+    frameWindow?: Window;
+    targetWindow?: Window;
+    requestTimeoutMs?: number;
+    autoResize?: boolean;
+    resizeRoot?: HTMLElement;
+}
+export type PluginFrameContextListener = (context: PluginRendererContext) => void;
+export interface PluginFrameClient {
+    waitForContext(): Promise<PluginRendererContext>;
+    onContextChanged(listener: PluginFrameContextListener): () => void;
+    request<TResult>(method: PluginRendererMethod, params?: Record<string, unknown>): Promise<NexusResult<TResult>>;
+    getSettings(): Promise<NexusResult<PluginSettingsDocument>>;
+    updateSettings(values: Record<string, unknown>): Promise<NexusResult<PluginSettingsDocument>>;
+    appendLog(request: BusinessLogAppendRequest): Promise<NexusResult<BusinessLogEntry>>;
+    invokeMain<TInput extends Record<string, unknown>, TResult>(operation: string, input?: TInput): Promise<NexusResult<TResult>>;
+    notifyResize(): void;
+    dispose(): void;
+}
+export declare function createPluginFrameClient(options?: PluginFrameClientOptions): PluginFrameClient;