@iobroker/socket-classes 0.5.3 → 1.0.1

package/lib/socketCommandsAdmin.js

@@ -551,6 +551,10 @@ class SocketCommandsAdmin extends SocketCommands {
 
     _initCommandsUser() {
         this.commands['addUser'] = (socket, user, pass, callback) => {
+            // Add new user
+            // @param {string} user - user name, like `benjamin`
+            // @param {string} pass - user password
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'addUser', callback, user)) {
                 this._addUser(user, pass, {user: socket._acl.user}, (error, ...args) =>
                     SocketCommands._fixCallback(callback, error, ...args));
@@ -558,6 +562,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['delUser'] = (socket, user, callback) => {
+            // Delete existing user. Admin cannot be deleted.
+            // @param {string} user - user name, like 'benjamin
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'delUser', callback, user)) {
                 this._delUser(user, {user: socket._acl.user}, (error, ...args) =>
                     SocketCommands._fixCallback(callback, error, ...args));
@@ -565,6 +572,11 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['addGroup'] = (socket, group, desc, acl, callback) => {
+            // Add new group.
+            // @param {string} group - user name, like 'benjamin
+            // @param {string} desc - optional description
+            // @param {object} acl - optional access control list object, like `{"object":{"list":true,"read":true,"write":false,"delete":false},"state":{"list":true,"read":true,"write":true,"create":true,"delete":false},"users":{"list":true,"read":true,"write":false,"create":false,"delete":false},"other":{"execute":false,"http":true,"sendto":false},"file":{"list":true,"read":true,"write":false,"create":false,"delete":false}}`
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'addGroup', callback, group)) {
                 this._addGroup(group, desc, acl, {user: socket._acl.user}, (error, ...args) =>
                     SocketCommands._fixCallback(callback, error, ...args));
@@ -572,12 +584,20 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['delGroup'] = (socket, group, callback) => {
+            // Delete existing group. Administrator group cannot be deleted.
+            // @param {string} group - group name, like 'users`
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'delGroup', callback, group)) {
                 this._delGroup(group, {user: socket._acl.user}, (error, ...args) =>
                     SocketCommands._fixCallback(callback, error, ...args));
             }
         };
+
         this.commands['changePassword'] = (socket, user, pass, callback) => {
+            // Change user password
+            // @param {string} user - user name, like 'benjamin`
+            // @param {string} pass - new password
+            // @param {function} callback - `function (error)`
             if (user === socket._acl.user || this._checkPermissions(socket, 'changePassword', callback, user)) {
                 try {
                     this.adapter.setPassword(user, pass, {user: socket._acl.user}, (error, ...args) =>
@@ -592,6 +612,9 @@ class SocketCommandsAdmin extends SocketCommands {
 
     _initCommandsAdmin() {
         this.commands['getHostByIp'] = (socket, ip, callback) => {
+            // Read host object by IP address
+            // @param {string} ip - ip address. IPv4 or IPv6
+            // @param {function} callback - `function (ip, obj)`. If host not found, obj is null
             if (typeof callback !== 'function') {
                 return this.adapter.log.warn('[getHostByIp] Invalid callback');
             }
@@ -632,6 +655,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['requireLog'] = (socket, isEnabled, callback) => {
+            // Activate or deactivate logging events. Events will be sent to the socket as `log` event. Adapter must have `common.logTransporter = true`
+            // @param {boolean} isEnabled - is logging enabled
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'setObject', callback)) {
                 if (isEnabled) {
                     this.subscribe(socket, 'log', 'dummy');
@@ -646,6 +672,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['readLogs'] = (socket, host, callback) => {
+            // Get logs file from given host
+            // @param {string} host - host id, like 'system.host.raspberrypi'
+            // @param {function} callback - `function (error, files)`, where `files` is array of `{fileName: `log/hostname/transport/file`, size: 123}`
             if (this._checkPermissions(socket, 'readLogs', callback)) {
                 let timeout = setTimeout(() => {
                     if (timeout) {
@@ -713,6 +742,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['delState'] = (socket, id, callback) => {
+            // Delete state. Corresponding object will be deleted too.
+            // @param {string} id - state ID
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'delState', callback, id)) {
                 // clear cache
                 if (this.states && this.states[id]) {
@@ -731,12 +763,18 @@ class SocketCommandsAdmin extends SocketCommands {
         // commands will be executed on host/controller
         // following response commands are expected: cmdStdout, cmdStderr, cmdExit
         this.commands['cmdExec'] = (socket, host, id, cmd, callback) => {
+            // Execute shell command on host/controller. Following response commands are expected: ´cmdStdout, cmdStderr, cmdExit´
+            // @param {string} host - host name, like 'system.host.raspberrypi'
+            // @param {string} id - session ID, like `Date.now()´. This session ID will come in events `cmdStdout, cmdStderr, cmdExit`
+            // @param {string} cmd - command
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'cmdExec', callback, cmd)) {
                 this.adapter.log.debug(`cmdExec on ${host}(${id}): ${cmd}`);
                 // remember socket for this ID.
                 this.cmdSessions[id] = {socket};
                 try {
                     this.adapter.sendToHost(host, 'cmdExec', {data: cmd, id});
+                    SocketCommands._fixCallback(callback, null);
                 } catch (error) {
                     this.adapter.log.error('[cmdExec] ERROR: ' + error.toString());
                     SocketCommands._fixCallback(callback, error);
@@ -745,6 +783,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['eventsThreshold'] = (socket, isActive) => {
+            // Used only for admin to limit number of events to front-end.
+            // @param {boolean} isActive - if true, then events will be limited
             if (!isActive) {
                 this.disableEventThreshold(true);
             } else {
@@ -753,6 +793,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getRatings'] = (socket, update, callback) => {
+            // Read ratings of adapters
+            // @param {boolean} update - if true, the ratings will be read from central server, if false from local cache
+            // @param {function} callback - `function (error, ratings)`, where `ratings` is object like `{accuweather: {rating: {r: 3.33, c: 3}, 1.2.1: {r: 3, c: 1}},…}`
             if (update || !this.adapter._ratings) {
                 this.updateRatings()
                     .then(() => SocketCommands._fixCallback(callback, null, this.adapter._ratings));
@@ -762,14 +805,22 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCurrentInstance'] = (socket, callback) => {
+            // Return current instance name like `admin.0`
+            // @param {function} callback - `function (error, namespace)`
             SocketCommands._fixCallback(callback, null, this.adapter.namespace);
         };
 
         this.commands['checkFeatureSupported'] = (socket, feature, callback) => {
+            // Checks if same feature is supported by current js-controller
+            // @param {string} feature - feature name like `CONTROLLER_LICENSE_MANAGER`
+            // @param {function} callback - `function (error, isSupported)`
             SocketCommands._fixCallback(callback, null, this.adapter.supportsFeature && this.adapter.supportsFeature(feature));
         };
 
         this.commands['decrypt'] = (socket, encryptedText, callback) => {
+            // Decrypts text with system secret key
+            // @param {string} encryptedText - encrypted text
+            // @param {function} callback - `function (error, decryptedText)`
             if (this.secret) {
                 SocketCommands._fixCallback(callback, null, this.adapter.decrypt(this.secret, encryptedText));
             } else {
@@ -791,6 +842,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['encrypt'] = (socket, plainText, callback) => {
+            // Encrypts text with system secret key
+            // @param {string} plainText - normal text
+            // @param {function} callback - `function (error, encryptedText)`
             if (this.secret) {
                 SocketCommands._fixCallback(callback, null, this.adapter.encrypt(this.secret, plainText));
             } else {
@@ -813,10 +867,15 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getIsEasyModeStrict'] = (socket, callback) => {
+            // Returns if admin has easy mode enabled
+            // @param {function} callback - `function (error, isEasyModeStrict)`
             SocketCommands._fixCallback(callback, null, this.adapter.config.accessLimit);
         };
 
         this.commands['getEasyMode'] = (socket, callback) => {
+            // Get easy mode configuration
+            // @param {function} callback - `function (error, easyModeConfig)`, where `easyModeConfig` is object like `{strict: true, configs: [{_id: 'system.adapter.javascript.0', common: {...}}, {...}]}`
+            // }`
             if (this._checkPermissions(socket, 'getObject', callback)) {
                 let user;
                 if (this.adapter.config.auth) {
@@ -829,7 +888,7 @@ class SocketCommandsAdmin extends SocketCommands {
                 }
 
                 if (this.adapter.config.accessLimit) {
-                    const configs = [];
+                    const configs  = [];
                     const promises = [];
                     this.adapter.config.accessAllowedConfigs.forEach(id => promises.push(this._readInstanceConfig(id, user, false, configs)));
                     this.adapter.config.accessAllowedTabs.forEach(id    => promises.push(this._readInstanceConfig(id, user, true, configs)));
@@ -872,6 +931,9 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getAdapters'] = (socket, adapterName, callback) => {
+            // Read all adapters objects
+            // @param {string} adapterName - optional adapter name
+            // @param {function} callback - `function (error, results)`, where `results` is array of objects like `{_id: 'system.adapter.javascript', common: {...}}`
             if (typeof callback === 'function' && this._checkPermissions(socket, 'getObject', callback)) {
                 this.adapter.getObjectView('system', 'adapter',
                     {startkey: `system.adapter.${adapterName || ''}`, endkey: `system.adapter.${adapterName || '\u9999'}`},
@@ -897,6 +959,10 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['updateLicenses'] = (socket, login, password, callback) => {
+            // Read software licenses (vis, knx, ...) from ioBroker.net cloud for given user
+            // @param {string} login - cloud login
+            // @param {string} password - cloud password
+            // @param {function} callback - `function (error, results)`, where `results` is array of objects like `[{"json":"xxx","id":"ab","email":"dogafox@gmail.com","product":"iobroker.knx.year","version":"2","invoice":"Pxx","uuid":"uuid","time":"2021-11-16T19:53:02.000Z","validTill":"2022-11-16T22:59:59.000Z","datapoints":1000}]`
             if (this._checkPermissions(socket, 'setObject', callback, login, password)) {
                 if (this.adapter.supportsFeature('CONTROLLER_LICENSE_MANAGER')) {
                     let timeout = setTimeout(() => {
@@ -923,6 +989,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactInstances'] = (socket, callback) => {
+            // Read all instances in short form to save bandwidth
+            // @param {function} callback - `function (error, results)`, where `results` is an object like `{'system.adapter.javascript.0': {adminTab, name, icon, enabled}}`
             if (typeof callback === 'function') {
                 if (this._checkPermissions(socket, 'getObject', callback)) {
                     this.adapter.getObjectView('system', 'instance',
@@ -952,6 +1020,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactAdapters'] = (socket, callback) => {
+            // Read all adapters in short for to save bandwidth
+            // @param {function} callback - `function (error, results)`, where `results` is an object like `{'javascript': {icon, v: '1.0.1', iv: 'ignoredVersion}}`
             if (typeof callback === 'function') {
                 if (this._checkPermissions(socket, 'getObject', callback)) {
                     this.adapter.getObjectView('system', 'adapter',
@@ -981,6 +1051,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactInstalled'] = (socket, host, callback) => {
+            // Read all installed adapters in short form to save bandwidth
+            // @param {function} callback - `function (error, results)`, where `results` is an object like `{'javascript': {version: '1.0.1'}}``
             if (typeof callback === 'function') {
                 if (this._checkPermissions(socket, 'sendToHost', callback)) {
                     this._sendToHost(host, 'getInstalled', null, data => {
@@ -993,6 +1065,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactSystemConfig'] = (socket, callback) => {
+            // Read system config in short form to save bandwidth
+            // @param {function} callback - `function (error, systemConfig)`, where `systemConfig` is an object like `{common: {...}, native: {secret: 'aaa'}}`
             if (this._checkPermissions(socket, 'getObject', callback)) {
                 this.adapter.getForeignObject('system.config', (error, obj) => {
                     obj = obj || {};
@@ -1007,6 +1081,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactSystemRepositories'] = (socket, callback) => {
+            // Read repositories from cache in short form to save bandwidth
+            // @param {function} callback - `function (error, repositories)`, where `repositories` is an object like `{_id: 'system.repositories', common: {...}, native: {repositories: {default: {json: {_repoInfo: {...}}}}}}`
             if (this._checkPermissions(socket, 'getObject', callback)) {
                 this.adapter.getForeignObject('system.repositories', (error, obj) => {
                     obj && obj.native && obj.native.repositories && Object.keys(obj.native.repositories).forEach(name => {
@@ -1023,6 +1099,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactRepository'] = (socket, host, callback) => {
+            // Read current repository in short form to save bandwidth
+            // @param {function} callback - `function (error, repository)`, where `repository` is an object like `{'javascript': {version: '1.0.1', icon}, 'admin': {version: '1.0.1', icon}}`
             if (this._checkPermissions(socket, 'sendToHost', callback)) {
                 this._sendToHost(host, 'getRepository', null, data => {
                     // Extract only version and icon
@@ -1037,6 +1115,8 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getCompactHosts'] = (socket, callback) => {
+            // Read all hosts in short form to save bandwidth
+            // @param {function} callback - `function (error, hosts)`, where `hosts` is an array of objects like `[{_id:'system.host.raspi',common:{name:'raspi',icon:'icon',color:'blue',installedVersion:'2.1.0'},native:{hardware:{networkInterfaces:[...]}}}]`
             if (this._checkPermissions(socket, 'getObject', callback)) {
                 this.adapter.getObjectView('system', 'host',
                     {startkey: 'system.host.', endkey: 'system.host.\u9999'}, (error, doc) => {
@@ -1082,6 +1162,9 @@ class SocketCommandsAdmin extends SocketCommands {
         super.__initCommandsStates();
 
         this.commands['getForeignStates'] = (socket, pattern, callback) => {
+            // Read all states (which might not belong to this adapter) which match the given pattern
+            // @param {string} pattern - pattern like
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'getStates', callback)) {
                 if (typeof callback === 'function') {
                     try {
@@ -1096,46 +1179,18 @@ class SocketCommandsAdmin extends SocketCommands {
                 }
             }
         };
-
-        this.commands['delObject'] = (socket, id, options, callback) => {
-            if (this._checkPermissions(socket, 'delObject', callback, id)) {
-                if (!options || typeof options !== 'object') {
-                    options = {};
-                }
-                options.user = socket._acl.user;
-                try {
-                    // options.recursive = true; // the only difference between delObject and delObjects is this line
-                    this.adapter.delForeignObject(id, options, (error, ...args) =>
-                        SocketCommands._fixCallback(callback, error, ...args));
-                } catch (error) {
-                    this.adapter.log.error(`[delObject] ERROR: ${error}`);
-                    SocketCommands._fixCallback(callback, error);
-                }
-            }
-        };
-
-        this.commands['delObjects'] = (socket, id, options, callback) => {
-            if (this._checkPermissions(socket, 'delObject', callback, id)) {
-                if (!options || typeof options !== 'object') {
-                    options = {};
-                }
-                options.user = socket._acl.user;
-                options.recursive = true; // the only difference between delObject and delObjects is this line
-                try {
-                    this.adapter.delForeignObject(id, options, (error, ...args) =>
-                        SocketCommands._fixCallback(callback, error, ...args));
-                } catch (error) {
-                    this.adapter.log.error(`[delObjects] ERROR: ${error}`);
-                    SocketCommands._fixCallback(callback, error);
-                }
-            }
-        };
     }
 
     __initCommandsFiles() {
         super.__initCommandsFiles();
 
         this.commands['writeFile'] = (socket, _adapter, fileName, data64, options, callback) => {
+            // Write file into ioBroker DB as base64 string
+            // @param {string} _adapter - instance name, e.g. `vis.0`
+            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} data64 - file content as base64 string
+            // @param {object} options - optional `{mode: 0x0644}`
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'writeFile', callback, fileName)) {
                 if (typeof options === 'function') {
                     callback = options;
@@ -1159,12 +1214,24 @@ class SocketCommandsAdmin extends SocketCommands {
     __initCommandsObjects() {
         super.__initCommandsObjects();
 
-        this.commands['getAllObjects'] = (socket, callback) => this._getAllObjects(socket, callback);
+        this.commands['getAllObjects'] = (socket, callback) => {
+            // Read absolutely all objects
+            // @param {function} callback - `function (error, objects)`, where `objects` is an object like `{'system.adapter.admin.0': {...}, 'system.adapter.web.0': {...}}`
+            return this._getAllObjects(socket, callback);
+        }
 
         // Identical to getAllObjects
-        this.commands['getObjects'] = (socket, callback) => this._getAllObjects(socket, callback);
+        this.commands['getObjects'] = (socket, callback) => {
+            // Read absolutely all objects. Same as `getAllObjects`.
+            // @param {function} callback - `function (error, objects)`, where `objects` is an object like `{'system.adapter.admin.0': {...}, 'system.adapter.web.0': {...}}`
+            return this._getAllObjects(socket, callback);
+        }
 
         this.commands['extendObject'] = (socket, id, obj, callback) => {
+            // Extend existing object
+            // @param {string} id - object ID
+            // @param {object} obj - new parts of the object, like `{common: {name: 'new name'}}`
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'extendObject', callback, id)) {
                 try {
                     this.adapter.extendForeignObject(id, obj, {user: socket._acl.user}, (error, ...args) =>
@@ -1177,6 +1244,10 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['getForeignObjects'] = (socket, pattern, type, callback) => {
+            // Read objects by pattern
+            // @param {string} pattern - pattern like `system.adapter.admin.0.*`
+            // @param {string} type - type of objects to delete, like `state`, `channel`, `device`, `host`, `adapter`. Default - `state`
+            // @param {function} callback - `function (error, objects)`, where `objects` is an object like `{'system.adapter.admin.0': {...}, 'system.adapter.web.0': {...}}`
             if (this._checkPermissions(socket, 'getObjects', callback)) {
                 if (typeof type === 'function') {
                     callback = type;
@@ -1198,6 +1269,10 @@ class SocketCommandsAdmin extends SocketCommands {
         };
 
         this.commands['delObject'] = (socket, id, options, callback) => {
+            // Delete object or objects recursively. Objects with `dontDelete` cannot be deleted.
+            // @param {string} id - Object ID like, 'adapterName.0.channel'
+            // @param {string} options - `{recursive: true}`
+            // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'delObject', callback, id)) {
                 if (typeof options === 'function') {
                     callback = options;
@@ -1208,6 +1283,7 @@ class SocketCommandsAdmin extends SocketCommands {
                 }
                 options.user = socket._acl.user;
                 try {
+                    // options.recursive = true; // the only difference between delObject and delObjects is this line
                     this.adapter.delForeignObject(id, options, (error, ...args) =>
                         SocketCommands._fixCallback(callback, error, ...args));
                 } catch (error) {
@@ -1216,6 +1292,27 @@ class SocketCommandsAdmin extends SocketCommands {
                 }
             }
         };
+
+        this.commands['delObjects'] = (socket, id, options, callback) => {
+            // Delete objects recursively. Objects with `dontDelete` cannot be deleted. Same as `delObject` but with `recursive: true`.
+            // @param {string} id - Object ID like, 'adapterName.0.channel'
+            // @param {string} options - optional
+            // @param {function} callback - `function (error)`
+            if (this._checkPermissions(socket, 'delObject', callback, id)) {
+                if (!options || typeof options !== 'object') {
+                    options = {};
+                }
+                options.user = socket._acl.user;
+                options.recursive = true; // the only difference between delObject and delObjects is this line
+                try {
+                    this.adapter.delForeignObject(id, options, (error, ...args) =>
+                        SocketCommands._fixCallback(callback, error, ...args));
+                } catch (error) {
+                    this.adapter.log.error(`[delObjects] ERROR: ${error}`);
+                    SocketCommands._fixCallback(callback, error);
+                }
+            }
+        };
     }
 
     stateChange(id, state) {

package/lib/socketCommon.js

@@ -109,7 +109,7 @@ class SocketCommon {
             // ignore "failed connection" as it already shown
             if (!error || !error.message || !error.message.includes('failed connection')) {
                 if ((error && error.message && error.message.includes('authentication failed') ||
-                    (details && details.includes('authentication failed')))
+                    (details && details.toString().includes('authentication failed')))
                 ) {
                     this.adapter.log.debug(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ' - ' + details : ''}`);
                 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/socket-classes",
-  "version": "0.5.3",
+  "version": "1.0.1",
   "description": "ioBroker server-side web sockets",
   "author": {
     "name": "bluefox",
@@ -21,6 +21,7 @@
     "url": "https://github.com/ioBroker/ioBroker.socket-classes"
   },
   "dependencies": {
+    "@iobroker/adapter-core": "^2.6.7",
     "passport": "^0.6.0",
     "cookie-parser": "^1.4.6",
     "axios": "^0.27.2"
@@ -28,8 +29,10 @@
   "devDependencies": {
     "@alcalzone/release-script": "^3.5.9",
     "@alcalzone/release-script-plugin-license": "^3.5.9",
+    "iobroker.js-controller": "dev",
+    "gulp": "^4.0.2",
     "chai": "^4.3.6",
-    "mocha": "^9.2.2"
+    "mocha": "^10.0.0"
   },
   "bugs": {
     "url": "https://github.com/ioBroker/ioBroker.web/issues"
@@ -47,7 +50,8 @@
     "release": "release-script",
     "release-patch": "release-script patch --yes",
     "release-minor": "release-script minor --yes",
-    "release-major": "release-script major --yes"
+    "release-major": "release-script major --yes",
+    "docs": "gulp"
   },
   "license": "MIT",
   "maintainers": [