@iobroker/dm-utils 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 ioBroker Community Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# dm-utils
+
+Utility classes for ioBroker adapters to support [ioBroker.device-manager](https://github.com/ioBroker/ioBroker.device-manager).
+
+## How to use
+
+Add in your `io-package.json` the property `deviceManager: true` to `common.supportedMessages`.
+Note: If you don't have a `common.supportedMessages` property yet, you have to add it.
+Also, if you don't have a `common.messagebox: true` property yet, you have to add it.
+
+In your ioBroker adapter, add a subclass of `DeviceManagement` and override the methods you need (see next chapters):
+
+Example:
+
+- Create a subclass:
+
+```ts
+class MyAdapterDeviceManagement extends DeviceManagement<MyAdapter> {
+    // contents see in the next chapters
+}
+```
+
+- Instantiate the subclass in your adapter class constructor:
+
+```ts
+class MyAdapter extends utils.Adapter {
+    private readonly deviceManagement: MyAdapterDeviceManagement;
+
+    public constructor(options: Partial<utils.AdapterOptions> = {}) {
+        super({
+            ...options,
+            name: "my-adapter",
+        });
+        this.deviceManagement = new DmTestDeviceManagement(this);
+
+        // ... more code here
+    }
+}
+```
+
+## Core concepts
+
+### Structure
+
+In the UI, there are three levels of information:
+
+- In the top level, a list of all adapter instances is shown (only containing adapter instances that support device management).
+- Inside the adapter instance (when expanded), a list of devices is shown.
+- Devices may contain additional details, which are shown when the row of the device is expanded.
+
+### Actions
+
+The device manager tab allows the user to interact with the adapter instance in two ways:
+
+- Actions per instance are shown above the list and should contain actions like "Search devices" or "Pair new device".
+- Actions per device are shown in the device list inside an instance and should contain actions like "Edit settings" or "Remove".
+
+When the user clicks on an action (i.e., a button in the UI),
+the `DeviceManagement` implementation's `handleXxxAction()` is called, and the adapter can perform arbitrary actions
+(see below for details).
+
+### Controls
+
+The device manager tab allows the user to control devices too. If devices are controllable, the device manager tab shows a control elements in the device card.
+
+When the user clicks on a control (i.e., a button in the UI),
+the `DeviceManagement` implementation's `handleXxxAction()` is called, and the adapter can perform arbitrary actions
+(see below for details).
+
+### Communication
+
+The communication between the `ioBroker.device-manager` tab and the adapter happens through `sendTo`.
+
+**IMPORTANT:** make sure your adapter doesn't handle `sendTo` messages starting with `dm:`, otherwise the communication will not work.
+
+### Access adapter methods
+
+You can access all adapter methods like `getState()` or `getStateAsync()` via `this.adapter`.  
+Example: `this.getState()` -> `this.adapter.getState()`
+
+### Error Codes
+| Code | Description                                                                                                                  | 
+|------|------------------------------------------------------------------------------------------------------------------------------|
+| 101  | Instance action ${actionId} was called before getInstanceInfo() was called. This could happen if the instance has restarted. |   
+| 102  | Instance action ${actionId} is unknown.                                                                                      |                                                   
+| 103  | Instance action ${actionId} is disabled because it has no handler.                                                           |       
+| 201  | Device action ${actionId} was called before listDevices() was called. This could happen if the instance has restarted.       |
+| 202  | Device action ${actionId} was called on unknown device: ${deviceId}.                                                         |
+| 203  | Device action ${actionId} doesn't exist on device ${deviceId}.                                                               |
+| 204  | Device action ${actionId} on ${deviceId} is disabled because it has no handler.                                              |
+
+## Examples
+
+To get an idea of how to use `dm-utils`, please have a look at:
+- [the folder "examples"](examples/dm-test.ts) or
+- [ioBroker.dm-test](https://github.com/UncleSamSwiss/ioBroker.dm-test)
+
+## `DeviceManagement` methods to override
+
+All methods can either return an object of the defined value or a `Promise` resolving to the object.
+
+This allows you to implement the method synchronously or asynchronously, depending on your implementation.
+
+### `listDevices()`
+
+This method must always be overridden (as it is abstract in the base class).
+
+You must return an array with information about all devices of this adapter's instance.
+
+This method is called when the user expands an instance in the list.
+
+In most cases, you will get all states of your instance and fill the array with the relevant information.
+
+Every array entry is an object of type `DeviceInfo` which has the following properties:
+
+- `id` (string): a unique (human readable) identifier of the device (it must be unique for your adapter instance only)
+- `name` (string or translations): the human-readable name of this device
+- `status` (optional): the current status of the device, which can be one of:
+  - `"disconnected"`
+  - `"connected"`
+  - an object containing:
+    - `icon` (string): an icon depicting the status of the device (see below for details)
+    - `description` (string, optional): a text that will be shown as a tooltip on the status
+- `actions` (array, optional): an array of actions that can be performed on the device; each object contains:
+  - `id` (string): unique identifier to recognize an action (never shown to the user)
+  - `icon` (string): an icon shown on the button (see below for details)
+  - `description` (string, optional): a text that will be shown as a tooltip on the button
+  - `disabled` (boolean, optional): if set to `true`, the button can't be clicked but is shown to the user
+- `hasDetails` (boolean, optional): if set to `true`, the row of the device can be expanded and details are shown below
+
+### `getInstanceInfo()`
+
+This method allows the device manager tab to gather some general information about the instance. It is called when the user opens the tab.
+
+If you override this method, the returned object must contain:
+
+- `apiVersion` (string): the supported API version; must currently always be `"v1"`
+- `actions` (array, optional): an array of actions that can be performed on the instance; each object contains:
+  - `id` (string): unique identifier to recognize an action (never shown to the user)
+  - `icon` (string): an icon shown on the button (see below for details)
+  - `title` (string): the title shown next to the icon on the button
+  - `description` (string, optional): a text that will be shown as a tooltip on the button
+  - `disabled` (boolean, optional): if set to `true`, the button can't be clicked but is shown to the user
+
+### `getDeviceDetails(id: string)`
+
+This method is called if a device's `hasDetails` is set to `true` and the user clicks on the expander.
+
+The returned object must contain:
+
+- `id` (string): the `id` given as parameter to the method call
+- `schema` (Custom JSON form schema): the schema of the Custom JSON form to show below the device information
+- `data` (object, optional): the data used to populate the Custom JSON form
+
+For more details about the schema, see [here](https://github.com/ioBroker/ioBroker.admin/blob/master/src-rx/src/components/JsonConfigComponent/SCHEMA.md).
+
+Please keep in mind that there is no "Save" button, so in most cases, the form shouldn't contain editable fields, but you may use `sendTo<xxx>` objects to send data to the adapter.
+
+### `handleInstanceAction(actionId: string, context: ActionContext)
+
+This method is called when to user clicks on an action (i.e., button) for an adapter instance.
+
+The parameters of this method are:
+- `actionId` (string): the `id` that was given in `getInstanceInfo()` --> `actions[].id`
+- `context` (object): object containing helper methods that can be used when executing the action
+
+The returned object must contain:
+- `refresh` (boolean): set this to `true` if you want the list to be reloaded after this action
+
+This method can be implemented asynchronously and can take a lot of time to complete.
+
+See below for how to interact with the user.
+
+### `handleDeviceAction(deviceId: string, actionId: string, context: ActionContext)
+
+This method is called when the user clicks on an action (i.e., button) for a device.
+
+The parameters of this method are:
+- `deviceId` (string): the `id` that was given in `listDevices()` --> `[].id`
+- `actionId` (string): the `id` that was given in `listDevices()` --> `[].actions[].id`
+- `context` (object): object containing helper methods that can be used when executing the action
+
+The returned object must contain:
+- `refresh` (string / boolean): the following values are allowed:
+    - `"device"`: if you want the device details to be reloaded after this action
+    - `"instance"`: if you want the entire device list to be reloaded after this action
+    - `false`: if you don't want anything to be refreshed (important: this is a boolean, not a string!)
+
+This method can be implemented asynchronously and can take a lot of time to complete.
+
+See below for how to interact with the user.
+
+### `handleDeviceControl(deviceId: string, controlId: string, state: ControlState, context: MessageContext)
+
+This method is called when the user clicks on a control (i.e., slider) in the device card.
+
+The parameters of this method are:
+- `deviceId` (string): the `id` that was given in `listDevices()` --> `[].id`
+- `controlId` (string): the `id` that was given in `listDevices()` --> `[].controls[].id`
+- `state` (string | number | boolean): new state for the control, that will be sent to real device
+- `context` (object): object containing helper methods that can be used when executing the action
+
+The returned object must contain:
+- `state`: ioBroker state object
+
+This method can be implemented asynchronously and can take a lot of time to complete.
+
+### `handleDeviceControlState(deviceId: string, controlId: string, context: MessageContext)
+
+This method is called when GUI requests the update of the state.
+
+The parameters of this method are:
+- `deviceId` (string): the `id` that was given in `listDevices()` --> `[].id`
+- `controlId` (string): the `id` that was given in `listDevices()` --> `[].controls[].id`
+- `context` (object): object containing helper methods that can be used when executing the action
+
+The returned object must contain:
+- `state`: ioBroker state object
+
+This method can be implemented asynchronously and can take a lot of time to complete.
+
+## Action sequences
+
+To allow your adapter to interact with the user, you can use "actions".
+
+As described above, there are actions on the instance and on devices. The behavior of both methods is similar.
+
+Inside an action method (`handleInstanceAction()` or `handleDeviceAction()`) you can perform arbitrary actions, like talking to a device or API, and you can interact with the user. For interactions, there are methods you can call on `context`:
+
+### `showMessage(text: ioBroker.StringOrTranslated)`
+
+Shows a message to the user.
+
+The method has the following parameter:
+- `text` (string or translation): the text to show to the user
+
+This asynchronous method returns (or rather: the Promise is resolved) once the user has clicked on "OK".
+
+### `showConfirmation(text: ioBroker.StringOrTranslated)`
+
+Lets the user confirm an action by showing a message with an "OK" and "Cancel" button.
+
+The method has the following parameter:
+- `text` (string or translation): the text to show to the user
+
+This asynchronous method returns (or rather: the Promise is resolved) once the user has clicked a button in the dialog:
+- `true` if the user clicked "OK"
+- `false` if the user clicked "Cancel"
+
+### `showForm(schema: JsonFormSchema, options?: { data?: JsonFormData; title?: string })`
+
+Shows a dialog with a Custom JSON form that can be edited by the user.
+
+The method has the following parameters:
+- `schema` (Custom JSON form schema): the schema of the Custom JSON form to show in the dialog
+- `options` (object, optional): options to configure the dialog further
+  - `data` (object, optional): the data used to populate the Custom JSON form
+  - `title` (string, optional): the dialog title
+
+This asynchronous method returns (or rather: the Promise is resolved) once the user has clicked a button in the dialog:
+- the form data, if the user clicked "OK"
+- `undefined`, if the user clicked "Cancel"
+
+### `openProgress(title: string, options?: {indeterminate?: boolean, value?: number, label?: string})`
+
+Shows a dialog with a linear progress bar to the user. There is no way for the user to dismiss this dialog.
+
+The method has the following parameters:
+- `title` (string): the dialog title
+- `options` (object, optional): options to configure the dialog further
+  - `indeterminate` (boolean, optional): set to `true` to visualize an unspecified wait time
+  - `value` (number, optional): the progress value to show to the user (if set, it must be a value between 0 and 100)
+  - `label` (string, optional): label to show to the right of the progress bar; you may show the progress value in a human readable way (e.g. "42%") or show the current step in a multi-step progress (e.g. "Logging in...")
+
+This method returns a promise that resolves to a `ProgressDialog` object.
+
+**Important:** you must always call `close()` on the returned object before you may open any other dialog.
+
+`ProgressDialog` has two methods:
+
+- `update(update: { title?: string; indeterminate?: boolean; value?:number; label?: string; })`
+  - Updates the progress dialog with new values
+  - The method has the following parameter:
+    - `update` (object): what to update in the dialog
+      - `title` (string, optional): change the dialog title
+      - `indeterminate` (boolean, optional): change whether the progress is indeterminate
+      - `value` (number, optional): change the progress value
+      - `label` (string, optional): change the label to the right of the progress bar
+- `close()`
+  - Closes the progress dialog (and allows you to open other dialogs)
+  
+<!--
+	Placeholder for the next version (at the beginning of the line):
+	### **WORK IN PROGRESS**
+-->
+## Changelog
+### 0.1.2 (2023-12-10)
+* (bluefox) added some fields to DeviceInfo interface
+* (bluefox) added control possibilities
+
+## License
+MIT License
+
+Copyright (c) 2023 ioBroker Community Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/ActionContext.d.ts

@@ -0,0 +1,15 @@
+import { JsonFormData, JsonFormSchema } from ".";
+import { ProgressDialog } from "./ProgressDialog";
+export interface ActionContext {
+    showMessage(text: ioBroker.StringOrTranslated): Promise<void>;
+    showConfirmation(text: ioBroker.StringOrTranslated): Promise<boolean>;
+    showForm(schema: JsonFormSchema, options?: {
+        data?: JsonFormData;
+        title?: ioBroker.StringOrTranslated;
+    }): Promise<JsonFormData | undefined>;
+    openProgress(title: string, options?: {
+        indeterminate?: boolean;
+        value?: number;
+        label?: ioBroker.StringOrTranslated;
+    }): Promise<ProgressDialog>;
+}

package/build/ActionContext.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/DeviceManagement.d.ts

@@ -0,0 +1,50 @@
+import { AdapterInstance } from "@iobroker/adapter-core";
+import { ActionContext } from "./ActionContext";
+import { ProgressDialog } from "./ProgressDialog";
+import { DeviceDetails, DeviceInfo, ErrorResponse, InstanceDetails, JsonFormData, JsonFormSchema, RefreshResponse, RetVal } from "./types";
+import { ControlState } from "./types/base";
+export declare abstract class DeviceManagement<T extends AdapterInstance = AdapterInstance> {
+    protected readonly adapter: T;
+    private instanceInfo?;
+    private devices?;
+    private readonly contexts;
+    constructor(adapter: T);
+    protected get log(): ioBroker.Log;
+    protected getInstanceInfo(): RetVal<InstanceDetails>;
+    protected abstract listDevices(): RetVal<DeviceInfo[]>;
+    protected getDeviceDetails(id: string): RetVal<DeviceDetails | null | {
+        error: string;
+    }>;
+    protected handleInstanceAction(actionId: string, context: ActionContext): RetVal<ErrorResponse> | RetVal<RefreshResponse>;
+    protected handleDeviceAction(deviceId: string, actionId: string, context: ActionContext): RetVal<ErrorResponse> | RetVal<RefreshResponse>;
+    protected handleDeviceControl(deviceId: string, controlId: string, newState: ControlState, context: MessageContext): RetVal<ErrorResponse | ioBroker.State>;
+    protected handleDeviceControlState(deviceId: string, controlId: string, context: MessageContext): RetVal<ErrorResponse | ioBroker.State>;
+    private onMessage;
+    private handleMessage;
+    private convertActions;
+    private convertControls;
+    private sendReply;
+}
+export declare class MessageContext implements ActionContext {
+    private readonly adapter;
+    private hasOpenProgressDialog;
+    private lastMessage?;
+    private progressHandler?;
+    constructor(msg: ioBroker.Message, adapter: AdapterInstance);
+    showMessage(text: ioBroker.StringOrTranslated): Promise<void>;
+    showConfirmation(text: ioBroker.StringOrTranslated): Promise<boolean>;
+    showForm(schema: JsonFormSchema, options?: {
+        data?: JsonFormData;
+        title?: string;
+    }): Promise<JsonFormData | undefined>;
+    openProgress(title: string, options?: {
+        indeterminate?: boolean;
+        value?: number;
+        label?: string;
+    }): Promise<ProgressDialog>;
+    sendFinalResult(result: ErrorResponse | RefreshResponse): void;
+    sendControlResult(deviceId: string, controlId: string, result: ErrorResponse | ioBroker.State): void;
+    handleProgress(message: ioBroker.Message): void;
+    private checkPreconditions;
+    private send;
+}

package/build/DeviceManagement.js

@@ -0,0 +1,359 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageContext = exports.DeviceManagement = void 0;
+class DeviceManagement {
+    constructor(adapter) {
+        this.adapter = adapter;
+        this.contexts = new Map();
+        adapter.on("message", this.onMessage.bind(this));
+    }
+    get log() {
+        return this.adapter.log;
+    }
+    getInstanceInfo() {
+        return { apiVersion: "v1" };
+    }
+    getDeviceDetails(id) {
+        return { id, schema: {} };
+    }
+    handleInstanceAction(actionId, context) {
+        var _a;
+        if (!this.instanceInfo) {
+            this.log.warn(`Instance action ${actionId} was called before getInstanceInfo()`);
+            return { error: { code: 101, message: `Instance action ${actionId} was called before getInstanceInfo()` } };
+        }
+        const action = (_a = this.instanceInfo.actions) === null || _a === void 0 ? void 0 : _a.find((a) => a.id === actionId);
+        if (!action) {
+            this.log.warn(`Instance action ${actionId} is unknown`);
+            return { error: { code: 102, message: `Instance action ${actionId} is unknown` } };
+        }
+        if (!action.handler) {
+            this.log.warn(`Instance action ${actionId} is disabled because it has no handler`);
+            return {
+                error: { code: 103, message: `Instance action ${actionId} is disabled because it has no handler` },
+            };
+        }
+        return action.handler(context);
+    }
+    handleDeviceAction(deviceId, actionId, context) {
+        var _a;
+        if (!this.devices) {
+            this.log.warn(`Device action ${actionId} was called before listDevices()`);
+            return { error: { code: 201, message: `Device action ${actionId} was called before listDevices()` } };
+        }
+        const device = this.devices.get(deviceId);
+        if (!device) {
+            this.log.warn(`Device action ${actionId} was called on unknown device: ${deviceId}`);
+            return {
+                error: { code: 202, message: `Device action ${actionId} was called on unknown device: ${deviceId}` },
+            };
+        }
+        const action = (_a = device.actions) === null || _a === void 0 ? void 0 : _a.find((a) => a.id === actionId);
+        if (!action) {
+            this.log.warn(`Device action ${actionId} doesn't exist on device ${deviceId}`);
+            return { error: { code: 203, message: `Device action ${actionId} doesn't exist on device ${deviceId}` } };
+        }
+        if (!action.handler) {
+            this.log.warn(`Device action ${actionId} on ${deviceId} is disabled because it has no handler`);
+            return {
+                error: {
+                    code: 204,
+                    message: `Device action ${actionId} on ${deviceId} is disabled because it has no handler`,
+                },
+            };
+        }
+        return action.handler(deviceId, context);
+    }
+    handleDeviceControl(deviceId, controlId, newState, context) {
+        var _a;
+        if (!this.devices) {
+            this.log.warn(`Device control ${controlId} was called before listDevices()`);
+            return { error: { code: 201, message: `Device control ${controlId} was called before listDevices()` } };
+        }
+        const device = this.devices.get(deviceId);
+        if (!device) {
+            this.log.warn(`Device control ${controlId} was called on unknown device: ${deviceId}`);
+            return {
+                error: { code: 202, message: `Device control ${controlId} was called on unknown device: ${deviceId}` },
+            };
+        }
+        const control = (_a = device.controls) === null || _a === void 0 ? void 0 : _a.find((a) => a.id === controlId);
+        if (!control) {
+            this.log.warn(`Device control ${controlId} doesn't exist on device ${deviceId}`);
+            return { error: { code: 203, message: `Device control ${controlId} doesn't exist on device ${deviceId}` } };
+        }
+        if (!control.handler) {
+            this.log.warn(`Device control ${controlId} on ${deviceId} is disabled because it has no handler`);
+            return {
+                error: {
+                    code: 204,
+                    message: `Device control ${controlId} on ${deviceId} is disabled because it has no handler`,
+                },
+            };
+        }
+        return control.handler(deviceId, controlId, newState, context);
+    }
+    // request state of control
+    handleDeviceControlState(deviceId, controlId, context) {
+        var _a;
+        if (!this.devices) {
+            this.log.warn(`Device control ${controlId} was called before listDevices()`);
+            return { error: { code: 201, message: `Device control ${controlId} was called before listDevices()` } };
+        }
+        const device = this.devices.get(deviceId);
+        if (!device) {
+            this.log.warn(`Device control ${controlId} was called on unknown device: ${deviceId}`);
+            return {
+                error: { code: 202, message: `Device control ${controlId} was called on unknown device: ${deviceId}` },
+            };
+        }
+        const control = (_a = device.controls) === null || _a === void 0 ? void 0 : _a.find((a) => a.id === controlId);
+        if (!control) {
+            this.log.warn(`Device control ${controlId} doesn't exist on device ${deviceId}`);
+            return { error: { code: 203, message: `Device control ${controlId} doesn't exist on device ${deviceId}` } };
+        }
+        if (!control.handler) {
+            this.log.warn(`Device control ${controlId} on ${deviceId} is disabled because it has no handler`);
+            return {
+                error: {
+                    code: 204,
+                    message: `Device control ${controlId} on ${deviceId} is disabled because it has no handler`,
+                },
+            };
+        }
+        return control.getStateHandler(deviceId, controlId, context);
+    }
+    onMessage(obj) {
+        if (!obj.command.startsWith("dm:")) {
+            return;
+        }
+        this.handleMessage(obj).catch(this.log.error);
+    }
+    async handleMessage(msg) {
+        this.log.debug(`DeviceManagement received: ${JSON.stringify(msg)}`);
+        switch (msg.command) {
+            case "dm:instanceInfo": {
+                this.instanceInfo = await this.getInstanceInfo();
+                this.sendReply(Object.assign(Object.assign({}, this.instanceInfo), { actions: this.convertActions(this.instanceInfo.actions) }), msg);
+                return;
+            }
+            case "dm:listDevices": {
+                const deviceList = await this.listDevices();
+                this.devices = deviceList.reduce((map, value) => {
+                    if (map.has(value.id)) {
+                        throw new Error(`Device ID ${value.id} is not unique`);
+                    }
+                    map.set(value.id, value);
+                    return map;
+                }, new Map());
+                const apiDeviceList = deviceList.map((d) => (Object.assign(Object.assign({}, d), { actions: this.convertActions(d.actions), controls: this.convertControls(d.controls) })));
+                this.sendReply(apiDeviceList, msg);
+                this.adapter.sendTo(msg.from, msg.command, this.devices, msg.callback);
+                return;
+            }
+            case "dm:deviceDetails": {
+                const details = await this.getDeviceDetails(msg.message);
+                this.adapter.sendTo(msg.from, msg.command, details, msg.callback);
+                return;
+            }
+            case "dm:instanceAction": {
+                const action = msg.message;
+                const context = new MessageContext(msg, this.adapter);
+                this.contexts.set(msg._id, context);
+                const result = await this.handleInstanceAction(action.actionId, context);
+                this.contexts.delete(msg._id);
+                context.sendFinalResult(result);
+                return;
+            }
+            case "dm:deviceAction": {
+                const action = msg.message;
+                const context = new MessageContext(msg, this.adapter);
+                this.contexts.set(msg._id, context);
+                const result = await this.handleDeviceAction(action.deviceId, action.actionId, context);
+                this.contexts.delete(msg._id);
+                context.sendFinalResult(result);
+                return;
+            }
+            case "dm:deviceControl": {
+                const control = msg.message;
+                const context = new MessageContext(msg, this.adapter);
+                this.contexts.set(msg._id, context);
+                const result = await this.handleDeviceControl(control.deviceId, control.controlId, control.state, context);
+                this.contexts.delete(msg._id);
+                context.sendControlResult(control.deviceId, control.controlId, result);
+                return;
+            }
+            case "dm:deviceControlState": {
+                const control = msg.message;
+                const context = new MessageContext(msg, this.adapter);
+                this.contexts.set(msg._id, context);
+                const result = await this.handleDeviceControlState(control.deviceId, control.controlId, context);
+                this.contexts.delete(msg._id);
+                context.sendControlResult(control.deviceId, control.controlId, result);
+                return;
+            }
+            case "dm:actionProgress": {
+                const { origin } = msg.message;
+                const context = this.contexts.get(origin);
+                if (!context) {
+                    this.log.warn(`Unknown message origin: ${origin}`);
+                    this.sendReply({ error: "Unknown action origin" }, msg);
+                    return;
+                }
+                context.handleProgress(msg);
+                return;
+            }
+        }
+    }
+    convertActions(actions) {
+        if (!actions) {
+            return undefined;
+        }
+        // detect duplicate IDs
+        const ids = new Set();
+        actions.forEach((a) => {
+            if (ids.has(a.id)) {
+                throw new Error(`Action ID ${a.id} is used twice, this would lead to unexpected behavior`);
+            }
+            ids.add(a.id);
+        });
+        // remove handler function to send it as JSON
+        return actions.map((a) => (Object.assign(Object.assign({}, a), { handler: undefined, disabled: !a.handler })));
+    }
+    convertControls(controls) {
+        if (!controls) {
+            return undefined;
+        }
+        // detect duplicate IDs
+        const ids = new Set();
+        controls.forEach((a) => {
+            if (ids.has(a.id)) {
+                throw new Error(`Control ID ${a.id} is used twice, this would lead to unexpected behavior`);
+            }
+            ids.add(a.id);
+        });
+        // remove handler function to send it as JSON
+        return controls.map((a) => (Object.assign(Object.assign({}, a), { handler: undefined, getStateHandler: undefined })));
+    }
+    sendReply(reply, msg) {
+        this.adapter.sendTo(msg.from, msg.command, reply, msg.callback);
+    }
+}
+exports.DeviceManagement = DeviceManagement;
+class MessageContext {
+    constructor(msg, adapter) {
+        this.adapter = adapter;
+        this.hasOpenProgressDialog = false;
+        this.lastMessage = msg;
+    }
+    showMessage(text) {
+        this.checkPreconditions();
+        const promise = new Promise((resolve) => {
+            this.progressHandler = () => resolve();
+        });
+        this.send("message", {
+            message: text,
+        });
+        return promise;
+    }
+    showConfirmation(text) {
+        this.checkPreconditions();
+        const promise = new Promise((resolve) => {
+            this.progressHandler = (msg) => resolve(!!msg.confirm);
+        });
+        this.send("confirm", {
+            confirm: text,
+        });
+        return promise;
+    }
+    showForm(schema, options) {
+        this.checkPreconditions();
+        const promise = new Promise((resolve) => {
+            this.progressHandler = (msg) => resolve(msg.data);
+        });
+        this.send("form", {
+            form: Object.assign({ schema }, options),
+        });
+        return promise;
+    }
+    openProgress(title, options) {
+        this.checkPreconditions();
+        this.hasOpenProgressDialog = true;
+        const dialog = {
+            update: (update) => {
+                const promise = new Promise((resolve) => {
+                    this.progressHandler = () => resolve();
+                });
+                this.send("progress", {
+                    progress: Object.assign(Object.assign(Object.assign({ title }, options), update), { open: true }),
+                });
+                return promise;
+            },
+            close: () => {
+                const promise = new Promise((resolve) => {
+                    this.progressHandler = () => {
+                        this.hasOpenProgressDialog = false;
+                        resolve();
+                    };
+                });
+                this.send("progress", {
+                    progress: { open: false },
+                });
+                return promise;
+            },
+        };
+        const promise = new Promise((resolve) => {
+            this.progressHandler = () => resolve(dialog);
+        });
+        this.send("progress", {
+            progress: Object.assign(Object.assign({ title }, options), { open: true }),
+        });
+        return promise;
+    }
+    sendFinalResult(result) {
+        this.send("result", {
+            result,
+        });
+    }
+    sendControlResult(deviceId, controlId, result) {
+        if (typeof result === "object" && "error" in result) {
+            this.send("result", {
+                result: {
+                    error: result.error,
+                    deviceId,
+                    controlId,
+                },
+            });
+        }
+        else {
+            this.send("result", {
+                result: {
+                    state: result,
+                    deviceId,
+                    controlId,
+                },
+            });
+        }
+    }
+    handleProgress(message) {
+        const currentHandler = this.progressHandler;
+        if (currentHandler && typeof message.message !== "string") {
+            this.lastMessage = message;
+            this.progressHandler = undefined;
+            currentHandler(message.message);
+        }
+    }
+    checkPreconditions() {
+        if (this.hasOpenProgressDialog) {
+            throw new Error("Can't show another dialog while a progress dialog is open. Please call 'close()' on the dialog before opening another dialog.");
+        }
+    }
+    send(type, message) {
+        if (!this.lastMessage) {
+            throw new Error("No outstanding message, can't send a new one");
+        }
+        this.adapter.sendTo(this.lastMessage.from, this.lastMessage.command, Object.assign(Object.assign({}, message), { type, origin: this.lastMessage.message.origin || this.lastMessage._id }), this.lastMessage.callback);
+        this.lastMessage = undefined;
+    }
+}
+exports.MessageContext = MessageContext;

package/build/ProgressDialog.d.ts

@@ -0,0 +1,9 @@
+export interface ProgressDialog {
+    update(update: {
+        title?: ioBroker.StringOrTranslated;
+        indeterminate?: boolean;
+        value?: number;
+        label?: ioBroker.StringOrTranslated;
+    }): Promise<void>;
+    close(): Promise<void>;
+}

package/build/ProgressDialog.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ActionContext";
+export * from "./DeviceManagement";
+export * from "./types";

package/build/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ActionContext"), exports);
+__exportStar(require("./DeviceManagement"), exports);
+// don't export * from "./MessageContext" as it is private
+__exportStar(require("./types"), exports);

package/build/types/adapter.d.ts

@@ -0,0 +1,7 @@
+import * as base from "./base";
+export type ActionBase = base.ActionBase<"adapter">;
+export type InstanceAction = base.InstanceAction<"adapter">;
+export type DeviceAction = base.DeviceAction<"adapter">;
+export type InstanceDetails = base.InstanceDetails<"adapter">;
+export type DeviceInfo = base.DeviceInfo<"adapter">;
+export type DeviceControl = base.DeviceControl<"adapter">;

package/build/types/adapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/api.d.ts

@@ -0,0 +1,7 @@
+import * as base from "./base";
+export type ActionBase = base.ActionBase<"api">;
+export type InstanceAction = base.InstanceAction<"api">;
+export type DeviceAction = base.DeviceAction<"api">;
+export type InstanceDetails = base.InstanceDetails<"api">;
+export type DeviceInfo = base.DeviceInfo<"api">;
+export type DeviceControl = base.DeviceControl<"api">;

package/build/types/api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/base.d.ts

@@ -0,0 +1,71 @@
+import { ActionContext, ErrorResponse, MessageContext } from "..";
+import { ApiVersion, DeviceRefresh, DeviceStatus, RetVal } from "./common";
+type ActionType = "api" | "adapter";
+export type Color = "primary" | "secondary" | string & {};
+export type ControlState = string | number | boolean | null;
+export interface ActionBase<T extends ActionType> {
+    id: string;
+    /**
+     * This can either be base64 or the URL to an icon.
+     */
+    icon: string;
+    description?: ioBroker.StringOrTranslated;
+    disabled?: T extends "api" ? boolean : never;
+    color?: Color;
+    backgroundColor?: Color;
+}
+export interface ControlBase {
+    id: string;
+    type: "button" | "switch" | "slider" | "select" | "icon" | "color";
+    state?: ioBroker.State;
+    stateId?: string;
+    icon?: string;
+    iconOn?: string;
+    min?: number;
+    max?: number;
+    label?: ioBroker.StringOrTranslated;
+    labelOn?: ioBroker.StringOrTranslated;
+    description?: ioBroker.StringOrTranslated;
+    color?: Color;
+    colorOn?: Color;
+    controlDelay?: number;
+    options?: {
+        label: ioBroker.StringOrTranslated;
+        value: ControlState;
+        icon?: string;
+        color?: Color;
+    }[];
+}
+export interface DeviceControl<T extends ActionType = "api"> extends ActionBase<T> {
+    handler?: T extends "api" ? never : (deviceId: string, actionId: string, state: ControlState, context: MessageContext) => RetVal<ErrorResponse | ioBroker.State>;
+    getStateHandler?: T extends "api" ? never : (deviceId: string, actionId: string, context: MessageContext) => RetVal<ErrorResponse | ioBroker.State>;
+}
+export interface InstanceAction<T extends ActionType = "api"> extends ActionBase<T> {
+    handler?: T extends "api" ? never : (context: ActionContext) => RetVal<{
+        refresh: boolean;
+    }>;
+    title: ioBroker.StringOrTranslated;
+}
+export interface DeviceAction<T extends ActionType = "api"> extends ActionBase<T> {
+    handler?: T extends "api" ? never : (deviceId: string, context: ActionContext) => RetVal<{
+        refresh: DeviceRefresh;
+    }>;
+}
+export interface InstanceDetails<T extends ActionType = "api"> {
+    apiVersion: ApiVersion;
+    actions?: InstanceAction<T>[];
+}
+export interface DeviceInfo<T extends ActionType = "api"> {
+    id: string;
+    icon?: string;
+    manufacturer?: ioBroker.StringOrTranslated;
+    model?: ioBroker.StringOrTranslated;
+    color?: Color;
+    backgroundColor?: Color;
+    name: ioBroker.StringOrTranslated;
+    status?: DeviceStatus | DeviceStatus[];
+    actions?: DeviceAction<T>[];
+    controls?: DeviceControl<T>[];
+    hasDetails?: boolean;
+}
+export {};

package/build/types/base.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/common.d.ts

@@ -0,0 +1,29 @@
+export type ApiVersion = "v1";
+export type DeviceStatus = "connected" | "disconnected" | {
+    /**
+     * This can either be the name of a font awesome icon (e.g. "fa-signal") or the URL to an icon.
+     */
+    icon?: string;
+    battery?: number | boolean | "charging" | string;
+    connection: "connected" | "disconnected";
+    rssi?: number;
+    warning?: ioBroker.StringOrTranslated | boolean;
+};
+export type DeviceRefresh = "device" | "instance" | false | true;
+export type RefreshResponse = {
+    refresh: DeviceRefresh;
+};
+export type ErrorResponse = {
+    error: {
+        code: number;
+        message: string;
+    };
+};
+export type RetVal<T> = T | Promise<T>;
+export type JsonFormSchema = Record<string, any>;
+export type JsonFormData = Record<string, any>;
+export interface DeviceDetails {
+    id: string;
+    schema: JsonFormSchema;
+    data?: JsonFormData;
+}

package/build/types/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./adapter";
+export * from "./common";

package/build/types/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./common"), exports);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@iobroker/dm-utils",
+  "version": "0.1.2",
+  "description": "ioBroker Device Manager utilities for backend",
+  "main": "build/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "prettier": "prettier -u -w examples src",
+    "release": "release-script",
+    "release-patch": "release-script patch --yes",
+    "release-minor": "release-script minor --yes",
+    "release-major": "release-script major --yes",
+    "update-packages": "ncu --upgrade",
+    "npm": "npm i"
+  },
+  "author": "UncleSamSwiss",
+  "license": "MIT",
+  "dependencies": {
+    "@iobroker/adapter-core": "^3.0.4"
+  },
+  "devDependencies": {
+    "@alcalzone/release-script": "^3.7.0",
+    "@alcalzone/release-script-plugin-license": "^3.7.0",
+    "@types/node": "^20.10.4",
+    "@typescript-eslint/eslint-plugin": "^6.13.2",
+    "@typescript-eslint/parser": "^6.13.2",
+    "eslint": "^8.55.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.1.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "build"
+  ]
+}