@flowfuse/nr-assistant 0.8.1-317b279-202601221339.0 → 0.8.1-8f07517-202601230815.0

package/index.html

@@ -1,5 +1,7 @@
+<script src="resources/@flowfuse/nr-assistant/expertComms.js"></script>
 <script src="resources/@flowfuse/nr-assistant/sharedUtils.js"></script>
 <script>
+    /* global FFExpertComms */ /* loaded from expertComms.js */
     /* global FFAssistantUtils */ /* loaded from sharedUtils.js */
     /* global RED, $ */ /* loaded from Node-RED core */
     (function (RED, n) {
@@ -160,6 +162,7 @@
                 }
             })
         }
+
         function initAssistant (options) {
             debug('initialising...', assistantOptions)
             if (!initialisedInterlock) {
@@ -200,163 +203,7 @@
             }
 
             if (!assistantInitialised) {
-                // Setup postMessage communication with parent window
-                if (!window.parent?.postMessage || window.self === window.top) {
-                    console.warn('Parent window not detected - certain interactions with the FlowFuse Expert will not be available')
-                } else {
-                    const MESSAGE_SOURCE = 'nr-assistant'
-                    const MESSAGE_TARGET = 'flowfuse-expert'
-                    const MESSAGE_SCOPE = 'flowfuse-expert'
-
-                    // proxy certain events from RED Events to the parent window (for state tracking)
-                    RED.events.on('editor:open', function () {
-                        window.parent.postMessage({
-                            type: 'editor:open',
-                            source: MESSAGE_SOURCE,
-                            scope: MESSAGE_SCOPE,
-                            target: MESSAGE_TARGET
-                        }, '*')
-                    })
-                    RED.events.on('editor:close', function () {
-                        window.parent.postMessage({
-                            type: 'editor:close',
-                            source: MESSAGE_SOURCE,
-                            scope: MESSAGE_SCOPE,
-                            target: MESSAGE_TARGET
-                        }, '*')
-                    })
-
-                    // Define supported actions and their parameter schemas
-                    const supportedActions = {
-                        'core:manage-palette': {
-                            params: {
-                                type: 'object',
-                                properties: {
-                                    view: {
-                                        type: 'string',
-                                        enum: ['nodes', 'install'],
-                                        default: 'install'
-                                    },
-                                    filter: {
-                                        description: 'Optional filter string. e.g. `"node-red-contrib-s7","node-red-contrib-other"` to pre-filter the palette view',
-                                        type: 'string'
-                                    }
-                                },
-                                required: ['filter']
-                            }
-                        },
-                        'custom:import-flow': {
-                            params: {
-                                type: 'object',
-                                properties: {
-                                    flow: {
-                                        type: 'string',
-                                        description: 'The flow JSON to import'
-                                    },
-                                    addFlow: {
-                                        type: 'boolean',
-                                        description: 'Whether to add the flow to the current workspace tab (false) or create a new tab (true). Default: false'
-                                    }
-                                },
-                                required: ['flow']
-                            }
-                        }
-                    }
-
-                    // Listen for postMessages from parent window
-                    window.addEventListener('message', function (event) {
-                        // prevent own messages being processed
-                        if (event.source === window.self) {
-                            return
-                        }
-
-                        const { type, action, params, target, source, scope } = event.data || {}
-
-                        // Ensure scope and source match expected values
-                        if (target !== MESSAGE_SOURCE || source !== MESSAGE_TARGET || scope !== MESSAGE_SCOPE) {
-                            return
-                        }
-
-                        debug('Received postMessage:', event.data)
-
-                        const postReply = (message) => {
-                            debug('Posting reply message:', message)
-                            if (event.source && typeof event.source.postMessage === 'function') {
-                                event.source.postMessage({
-                                    ...message,
-                                    source: MESSAGE_SOURCE,
-                                    scope: MESSAGE_SCOPE,
-                                    target: MESSAGE_TARGET
-                                }, event.origin)
-                            } else {
-                                console.warn('Unable to post message reply, source not available', message)
-                            }
-                        }
-
-                        // handle version request
-                        if (type === 'get-assistant-version') {
-                            // Reply with the current version
-                            postReply({ type, version: assistantOptions.assistantVersion, success: true }, event.origin)
-                            return
-                        }
-                        // handle supported actions request
-                        if (type === 'get-supported-actions') {
-                            // Reply with the supported actions and their schemas
-                            postReply({ type, supportedActions, success: true }, event.origin)
-                            return
-                        }
-
-                        // handle action invocation requests (must be registered actions in supportedActions)
-                        if (type === 'invoke-action' && typeof action === 'string') {
-                            if (!supportedActions[action]) {
-                                console.warn(`Action "${action}" is not permitted to be invoked via postMessage`)
-                                postReply({ type, action, error: 'unknown-action' })
-                                return
-                            }
-                            // Validate params against permitted schema (native/naive parsing for now - may introduce a library later if more complex schemas are needed)
-                            const actionSchema = supportedActions[action].params
-                            if (actionSchema) {
-                                const validation = validateSchema(params, actionSchema)
-                                if (!validation || !validation.valid) {
-                                    console.warn(`Params for action "${action}" did not validate against the expected schema`, params, actionSchema, validation)
-                                    postReply({ type, action, error: validation.error || 'invalid-parameters' })
-                                    return
-                                }
-                            }
-
-                            if (action === 'custom:import-flow') {
-                                // import-flow is a custom action - handle it here directly
-                                try {
-                                    importNodes(params.flow, params.addFlow === true)
-                                    postReply({ type, success: true })
-                                } catch (err) {
-                                    postReply({ type, error: err?.message })
-                                }
-                            } else {
-                                // Handle (supported) native Node-RED actions
-                                try {
-                                    RED.actions.invoke(action, params)
-                                    postReply({ type, action, success: true })
-                                } catch (err) {
-                                    postReply({ type, action, error: err?.message })
-                                }
-                            }
-                            return
-                        }
-
-                        // unknown message type
-                        postReply({ type: 'error', error: 'unknown-type', data: event.data })
-                    }, false)
-
-                    // Notify the parent window that the assistant is ready
-                    window.parent.postMessage({
-                        type: 'assistant-ready',
-                        source: MESSAGE_SOURCE,
-                        scope: MESSAGE_SCOPE,
-                        target: MESSAGE_TARGET,
-                        version: assistantOptions.assistantVersion
-                    }, '*')
-                }
+                FFExpertComms.init(RED, assistantOptions)
 
                 registerMonacoExtensions()
                 RED.actions.add('flowfuse-nr-assistant:function-builder', showFunctionBuilderPrompt, { label: '@flowfuse/nr-assistant/flowfuse-nr-assistant:function-builder.action.label' })
@@ -2117,128 +1964,6 @@
             RED.menu.refreshShortcuts()
         }
 
-        /**
-         * Validates data against a simple schema
-         * NOTE: This is a very basic implementation and only supports a subset of JSON Schema for now.
-         * @param {any} data - The data to validate
-         * @param {object} schema - The schema to validate against
-         * @returns {{valid: boolean, error?: string}} - The validation result
-         */
-        function validateSchema (data, schema) {
-            if (schema.type === 'object') {
-                if (typeof data !== 'object') {
-                    return {
-                        valid: false,
-                        error: 'Data is not of type object'
-                    }
-                }
-                if (Array.isArray(data)) {
-                    return {
-                        valid: false,
-                        error: 'Data is an array but an object was expected'
-                    }
-                }
-                // check required properties
-                if (Array.isArray(schema.required)) {
-                    for (const reqProp of schema.required) {
-                        if (!(reqProp in data)) {
-                            return {
-                                valid: false,
-                                error: `Data is missing required parameter "${reqProp}"`
-                            }
-                        }
-                    }
-                }
-                // check properties & apply defaults
-                if (schema.properties) {
-                    for (const [propName, propSchema] of Object.entries(schema.properties)) {
-                        const propExists = propName in data
-                        // check type
-                        if (propSchema.type && propExists) {
-                            const expectedType = propSchema.type
-                            const actualType = Array.isArray(data[propName]) ? 'array' : typeof data[propName]
-                            if (actualType !== expectedType) {
-                                return {
-                                    valid: false,
-                                    error: `Data parameter "${propName}" is of type "${actualType}" but expected type is "${expectedType}"`
-                                }
-                            }
-                        }
-                        // check enum
-                        if (propSchema.enum && propExists) {
-                            if (!propSchema.enum.includes(data[propName])) {
-                                return {
-                                    valid: false,
-                                    error: `Data parameter "${propName}" has invalid value "${data[propName]}". Should be one of: ${propSchema.enum.join(', ')}`
-                                }
-                            }
-                        }
-                        // apply defaults
-                        if (propSchema.default !== undefined && !propExists) {
-                            data[propName] = propSchema.default
-                        }
-                    }
-                }
-            }
-            return { valid: true }
-        }
-
-        /// Function extracted from Node-RED source `editor-client/src/js/ui/clipboard.js`
-        /**
-         * Performs the import of nodes, handling any conflicts that may arise
-         * @param {string} nodesStr the nodes to import as a string
-         * @param {boolean} addFlow whether to add the nodes to a new flow or to the current flow
-         */
-        function importNodes (nodesStr, addFlow) {
-            let newNodes = nodesStr
-            if (typeof nodesStr === 'string') {
-                try {
-                    nodesStr = nodesStr.trim()
-                    if (nodesStr.length === 0) {
-                        return
-                    }
-                    newNodes = validateFlowString(nodesStr)
-                } catch (err) {
-                    const e = new Error(RED._('clipboard.invalidFlow', { message: 'test' }))
-                    e.code = 'NODE_RED'
-                    throw e
-                }
-            }
-            const importOptions = { generateIds: true, addFlow }
-            try {
-                RED.view.importNodes(newNodes, importOptions)
-            } catch (error) {
-                // Thrown for import_conflict
-                RED.notify('Import failed:' + error.message, 'error')
-                throw error
-            }
-        }
-
-        /// Function extracted from Node-RED source `editor-client/src/js/ui/clipboard.js`
-        /**
-         * Validates if the provided string looks like valid flow json
-         * @param {string} flowString the string to validate
-         * @returns If valid, returns the node array
-         */
-        function validateFlowString (flowString) {
-            const res = JSON.parse(flowString)
-            if (!Array.isArray(res)) {
-                throw new Error(RED._('clipboard.import.errors.notArray'))
-            }
-            for (let i = 0; i < res.length; i++) {
-                if (typeof res[i] !== 'object') {
-                    throw new Error(RED._('clipboard.import.errors.itemNotObject', { index: i }))
-                }
-                if (!Object.hasOwn(res[i], 'id')) {
-                    throw new Error(RED._('clipboard.import.errors.missingId', { index: i }))
-                }
-                if (!Object.hasOwn(res[i], 'type')) {
-                    throw new Error(RED._('clipboard.import.errors.missingType', { index: i }))
-                }
-            }
-            return res
-        }
-
         function debug (...args) {
             if (RED.nrAssistant?.DEBUG) {
                 const scriptName = 'assistant-index.html.js' // must match the sourceURL set in the script below

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flowfuse/nr-assistant",
-    "version": "0.8.1-317b279-202601221339.0",
+    "version": "0.8.1-8f07517-202601230815.0",
     "description": "FlowFuse Node-RED Expert plugin",
     "main": "index.js",
     "scripts": {

package/resources/expertComms.js

@@ -0,0 +1,479 @@
+/**
+* FFAssistant Utils
+* Expert Communication functions for the FlowFuse Assistant
+* To import this in js backend code (although you shouldn't), use:
+* const FFExpertComms = require('flowfuse-nr-assistant/resources/expertComms.js')
+* To import this in frontend code, use:
+* <script src="/resources/@flowfuse/nr-assistant/expertComms.js"></script>
+* To use this in the browser, you can access it via:
+* FFExpertComms.cleanFlow(nodeArray)
+*/
+
+'use strict';
+
+(function (root, factory) {
+    if (typeof module === 'object' && module.exports) {
+        // Node.js / CommonJS
+        module.exports = factory()
+    } else {
+        // Browser
+        root.FFExpertComms = factory()
+    }
+}(typeof self !== 'undefined' ? self : this, function () {
+    'use strict'
+
+    class ExpertComms {
+        /** @type {import('node-red').NodeRedInstance} */
+        RED = null
+        assistantOptions = {}
+
+        MESSAGE_SOURCE = 'nr-assistant'
+        MESSAGE_TARGET = 'flowfuse-expert'
+        MESSAGE_SCOPE = 'flowfuse-expert'
+
+        /**
+         * targetOrigin is set to '*' by default, which allows messages to be sent and received from any origin.
+         * This is fine for the initial handshake with the FF Expert (will change to the origin of the expert page once it is loaded)
+         *
+         * @type {string}
+         */
+        targetOrigin = '*'
+
+        /**
+         * Define supported actions and their parameter schemas
+         */
+        supportedActions = {
+            'core:manage-palette': {
+                params: {
+                    type: 'object',
+                    properties: {
+                        view: {
+                            type: 'string',
+                            enum: ['nodes', 'install'],
+                            default: 'install'
+                        },
+                        filter: {
+                            description: 'Optional filter string. e.g. `"node-red-contrib-s7","node-red-contrib-other"` to pre-filter the palette view',
+                            type: 'string'
+                        }
+                    },
+                    required: ['filter']
+                }
+            },
+            'custom:import-flow': {
+                params: {
+                    type: 'object',
+                    properties: {
+                        flow: {
+                            type: 'string',
+                            description: 'The flow JSON to import'
+                        },
+                        addFlow: {
+                            type: 'boolean',
+                            description: 'Whether to add the flow to the current workspace tab (false) or create a new tab (true). Default: false'
+                        }
+                    },
+                    required: ['flow']
+                }
+            }
+        }
+
+        /**
+         * A mapping of Node-RED core events to their respective handler logic.
+         *
+         * This map acts as a router for the assistant's event listeners:
+         * - Functions: Executed immediately when the event fires (e.g., notifying the parent of UI state).
+         * - Strings: Represent the name of a method within this class to be invoked (e.g., refreshing the palette).
+         *            The method name being referenced must be appended with 'notify'
+         *
+         * @type {Object.<string, Function|string>}
+         */
+        nodeRedEventsMap = {
+            'editor:open': () => {
+                this.postParent({ type: 'editor:open' })
+            },
+            'editor:close': () => {
+                this.postParent({ type: 'editor:close' })
+            },
+            'registry:node-set-added': 'notifyPaletteChange',
+            'registry:node-set-removed': 'notifyPaletteChange',
+            'registry:node-set-disabled': 'notifyPaletteChange',
+            'registry:node-set-enabled': 'notifyPaletteChange'
+        }
+
+        /**
+         * A mapping of FlowFuse Expert events to their respective handler logic.
+         *
+         * This map acts as a router for the expert's event listeners:
+         * - Functions: Executed immediately when the event fires (e.g., notifying the parent of UI state).
+         * - Strings: Represent the name of a method within this class to be invoked (e.g., refreshing the palette).
+         *            The method name being referenced must be appended with 'handle'
+         *
+         * @type {Object.<string, Function|string>}
+         */
+        expertEventsMap = {
+            'get-assistant-version': ({ event, type, action, params } = {}) => {
+                // handle version request
+                this.postReply({ type, version: this.assistantOptions.assistantVersion, success: true }, event)
+            },
+            'get-supported-actions': ({ event, type, action, params } = {}) => {
+                // handle supported actions request
+                this.postReply({ type, supportedActions: this.supportedActions, success: true }, event)
+            },
+            'get-palette': async ({ event, type, action, params } = {}) => {
+                // handle palette request
+                this.postReply({ type: 'set-palette', palette: await this.getPalette(), success: true }, event)
+            },
+            'invoke-action': 'handleActionInvocation'
+        }
+
+        init (RED, assistantOptions) {
+            /** @type {import('node-red').NodeRedInstance} */
+            this.RED = RED
+            this.assistantOptions = assistantOptions
+
+            if (!window.parent?.postMessage || window.self === window.top) {
+                console.warn('Parent window not detected - certain interactions with the FlowFuse Expert will not be available')
+                return
+            }
+
+            this.setNodeRedEventListeners()
+
+            this.setupMessageListeners()
+
+            // Notify the parent window that the assistant is ready
+            this.postParent({ type: 'assistant-ready', version: this.assistantOptions.assistantVersion })
+        }
+
+        setupMessageListeners () {
+            // Listen for postMessages from the parent window
+            window.addEventListener('message', async (event) => {
+                // prevent own messages being processed
+                if (event.source === window.self) {
+                    return
+                }
+
+                const { type, action, params, target, source, scope } = event.data || {}
+
+                // Ensure scope and source match expected values
+                if (target !== this.MESSAGE_SOURCE || source !== this.MESSAGE_TARGET || scope !== this.MESSAGE_SCOPE) {
+                    return
+                }
+
+                // Setting target origin for future calls
+                if (this.targetOrigin === '*') {
+                    this.targetOrigin = event.origin
+                }
+
+                this.debug('Received postMessage:', event.data)
+
+                const payload = {
+                    event,
+                    type,
+                    action,
+                    params
+                }
+
+                for (const eventName in this.expertEventsMap) {
+                    if (type === eventName && typeof this.expertEventsMap[eventName] === 'function') {
+                        return this.expertEventsMap[eventName](payload)
+                    }
+
+                    if (
+                        type === eventName &&
+                        typeof this.expertEventsMap[eventName] === 'string' &&
+                        this.expertEventsMap[eventName] in this
+                    ) {
+                        return this[this.expertEventsMap[eventName]](payload)
+                    }
+                }
+
+                // handles unknown message type
+                this.postReply({ type: 'error', error: 'unknown-type', data: event.data }, event)
+            }, false)
+        }
+
+        setNodeRedEventListeners () {
+            Object.keys(this.nodeRedEventsMap).forEach(eventName => {
+                if (typeof this.nodeRedEventsMap[eventName] === 'function') {
+                    this.RED.events.on(eventName, this.nodeRedEventsMap[eventName].bind(this))
+                }
+                if (typeof this.nodeRedEventsMap[eventName] === 'string' && this.nodeRedEventsMap[eventName] in this) {
+                    this.RED.events.on(eventName, this[this.nodeRedEventsMap[eventName]].bind(this))
+                }
+            })
+        }
+
+        /**
+         * FlowFuse Expert Node-RED event notifiers
+         */
+        async notifyPaletteChange () {
+            this.postParent({
+                type: 'set-palette',
+                palette: await this.getPalette()
+            })
+        }
+
+        /**
+         * FlowFuse Expert message handlers
+         */
+        handleActionInvocation ({ event, type, action, params } = {}) {
+            // handle action invocation requests (must be registered actions in supportedActions)
+            if (typeof action !== 'string') {
+                return
+            }
+
+            if (!this.supportedActions[action]) {
+                console.warn(`Action "${action}" is not permitted to be invoked via postMessage`)
+                this.postReply({ type, action, error: 'unknown-action' }, event)
+                return
+            }
+
+            // Validate params against permitted schema (native/naive parsing for now - may introduce a library later if more complex schemas are needed)
+            const actionSchema = this.supportedActions[action].params
+            if (actionSchema) {
+                const validation = this.validateSchema(params, actionSchema)
+                if (!validation || !validation.valid) {
+                    console.warn(`Params for action "${action}" did not validate against the expected schema`, params, actionSchema, validation)
+                    this.postReply({ type, action, error: validation.error || 'invalid-parameters' }, event)
+                    return
+                }
+            }
+
+            if (action === 'custom:import-flow') {
+                // import-flow is a custom action - handle it here directly
+                try {
+                    this.importNodes(params.flow, params.addFlow === true)
+                    this.postReply({ type, success: true }, event)
+                } catch (err) {
+                    this.postReply({ type, error: err?.message }, event)
+                }
+            } else {
+                // Handle (supported) native Node-RED actions
+                try {
+                    this.RED.actions.invoke(action, params)
+                    this.postReply({ type, action, success: true }, event)
+                } catch (err) {
+                    this.postReply({ type, action, error: err?.message }, event)
+                }
+            }
+        }
+
+        async getPalette () {
+            const palette = {}
+            const plugins = await $.ajax({
+                url: 'plugins',
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json'
+                }
+            })
+            const nodes = await $.ajax({
+                url: 'nodes',
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json'
+                }
+            })
+
+            plugins.forEach(plugin => {
+                if (Object.prototype.hasOwnProperty.call(palette, plugin.module)) {
+                    palette[plugin.module].plugins.push(plugin)
+                } else {
+                    palette[plugin.module] = {
+                        version: plugin.version,
+                        enabled: plugin.enabled,
+                        module: plugin.module,
+                        plugins: [
+                            plugin
+                        ],
+                        nodes: []
+                    }
+                }
+            })
+
+            nodes.forEach(node => {
+                if (Object.prototype.hasOwnProperty.call(palette, node.module)) {
+                    palette[node.module].nodes.push(node)
+                } else {
+                    palette[node.module] = {
+                        version: node.version,
+                        enabled: node.enabled,
+                        module: node.module,
+                        plugins: [],
+                        nodes: [
+                            node
+                        ]
+                    }
+                }
+            })
+
+            return palette
+        }
+
+        validateSchema (data, schema) {
+            if (schema.type === 'object') {
+                if (typeof data !== 'object') {
+                    return {
+                        valid: false,
+                        error: 'Data is not of type object'
+                    }
+                }
+                if (Array.isArray(data)) {
+                    return {
+                        valid: false,
+                        error: 'Data is an array but an object was expected'
+                    }
+                }
+                // check required properties
+                if (Array.isArray(schema.required)) {
+                    for (const reqProp of schema.required) {
+                        if (!(reqProp in data)) {
+                            return {
+                                valid: false,
+                                error: `Data is missing required parameter "${reqProp}"`
+                            }
+                        }
+                    }
+                }
+                // check properties & apply defaults
+                if (schema.properties) {
+                    for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                        const propExists = propName in data
+                        // check type
+                        if (propSchema.type && propExists) {
+                            const expectedType = propSchema.type
+                            const actualType = Array.isArray(data[propName]) ? 'array' : typeof data[propName]
+                            if (actualType !== expectedType) {
+                                return {
+                                    valid: false,
+                                    error: `Data parameter "${propName}" is of type "${actualType}" but expected type is "${expectedType}"`
+                                }
+                            }
+                        }
+                        // check enum
+                        if (propSchema.enum && propExists) {
+                            if (!propSchema.enum.includes(data[propName])) {
+                                return {
+                                    valid: false,
+                                    error: `Data parameter "${propName}" has invalid value "${data[propName]}". Should be one of: ${propSchema.enum.join(', ')}`
+                                }
+                            }
+                        }
+                        // apply defaults
+                        if (propSchema.default !== undefined && !propExists) {
+                            data[propName] = propSchema.default
+                        }
+                    }
+                }
+            }
+            return { valid: true }
+        }
+
+        /// Function extracted from Node-RED source `editor-client/src/js/ui/clipboard.js`
+        /**
+         * Performs the import of nodes, handling any conflicts that may arise
+         * @param {string} nodesStr the nodes to import as a string
+         * @param {boolean} addFlow whether to add the nodes to a new flow or to the current flow
+         */
+        importNodes (nodesStr, addFlow) {
+            let newNodes = nodesStr
+            if (typeof nodesStr === 'string') {
+                try {
+                    nodesStr = nodesStr.trim()
+                    if (nodesStr.length === 0) {
+                        return
+                    }
+                    newNodes = this.validateFlowString(nodesStr)
+                } catch (err) {
+                    const e = new Error(this.RED._('clipboard.invalidFlow', { message: 'test' }))
+                    e.code = 'NODE_RED'
+                    throw e
+                }
+            }
+            const importOptions = { generateIds: true, addFlow }
+            try {
+                this.RED.view.importNodes(newNodes, importOptions)
+            } catch (error) {
+                // Thrown for import_conflict
+                this.RED.notify('Import failed:' + error.message, 'error')
+                throw error
+            }
+        }
+
+        /// Function extracted from Node-RED source `editor-client/src/js/ui/clipboard.js`
+        /**
+         * Validates if the provided string looks like valid flow json
+         * @param {string} flowString the string to validate
+         * @returns If valid, returns the node array
+         */
+        validateFlowString (flowString) {
+            const res = JSON.parse(flowString)
+            if (!Array.isArray(res)) {
+                throw new Error(this.RED._('clipboard.import.errors.notArray'))
+            }
+            for (let i = 0; i < res.length; i++) {
+                if (typeof res[i] !== 'object') {
+                    throw new Error(this.RED._('clipboard.import.errors.itemNotObject', { index: i }))
+                }
+                if (!Object.hasOwn(res[i], 'id')) {
+                    throw new Error(this.RED._('clipboard.import.errors.missingId', { index: i }))
+                }
+                if (!Object.hasOwn(res[i], 'type')) {
+                    throw new Error(this.RED._('clipboard.import.errors.missingType', { index: i }))
+                }
+            }
+            return res
+        }
+
+        debug (...args) {
+            if (this.RED.nrAssistant?.DEBUG) {
+                const scriptName = 'assistant-index.html.js' // must match the sourceURL set in the script below
+                const stackLine = new Error().stack.split('\n')[2].trim()
+                const match = stackLine.match(/\(?([^\s)]+):(\d+):(\d+)\)?$/) || stackLine.match(/@?([^@]+):(\d+):(\d+)$/)
+                const file = match?.[1] || 'anonymous'
+                const line = match?.[2] || '1'
+                const col = match?.[3] || '1'
+                let link = `${window.location.origin}/${scriptName}:${line}:${col}`
+                if (/^VM\d+$/.test(file)) {
+                    link = `debugger:///${file}:${line}:${col}`
+                } else if (file !== 'anonymous' && file !== '<anonymous>' && file !== scriptName) {
+                    link = `${file}:${line}:${col}`
+                    if (!link.startsWith('http') && !link.includes('/')) {
+                        link = `${window.location.origin}/${link}`
+                    }
+                }
+                // eslint-disable-next-line no-console
+                console.log('[nr-assistant]', ...args, `\n   at ${link}`)
+            }
+        }
+
+        /**
+         * Internal helper to send a formatted message to a target window
+         */
+        _post (payload, targetWindow) {
+            if (targetWindow && typeof targetWindow.postMessage === 'function') {
+                targetWindow.postMessage({
+                    ...payload,
+                    source: this.MESSAGE_SOURCE,
+                    scope: this.MESSAGE_SCOPE,
+                    target: this.MESSAGE_TARGET
+                }, this.targetOrigin)
+            } else {
+                console.warn('Unable to post message, target window not available', payload)
+            }
+        }
+
+        postParent (payload = {}) {
+            this.debug('Posting parent message', payload)
+            this._post(payload, window.parent)
+        }
+
+        postReply (payload, event) {
+            this.debug('Posting reply message:', payload)
+            this._post(payload, event.source)
+        }
+    }
+
+    return new ExpertComms()
+}))