@iobroker/dm-utils 2.0.1 → 3.0.2

package/build/types/api.d.ts

@@ -1,7 +1,72 @@
 import type * as base from './base';
+import type { ActionButton, DeviceId, ErrorResponse, JsonFormSchema, ProgressUpdate } from './common';
 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'>;
+export type DeviceRefreshResponse = base.DeviceRefreshResponse<'api'>;
+export type InstanceRefreshResponse = base.InstanceRefreshResponse;
+export type DeviceLoadIncrement = {
+    add: DeviceInfo[];
+    total?: number;
+    next?: {
+        origin: number;
+    };
+};
+export type DmResponseBase = {
+    origin: number;
+};
+export type DmControlResponse = DmResponseBase & {
+    type: 'result';
+    result: {
+        deviceId: DeviceId;
+        controlId: string;
+    } & (ErrorResponse | {
+        state: ioBroker.State;
+    });
+};
+export type DmActionResultResponse = DmResponseBase & {
+    type: 'result';
+    result: ErrorResponse | DeviceRefreshResponse | InstanceRefreshResponse;
+};
+export type DmActionMessageResponse = DmResponseBase & {
+    type: 'message';
+    message: ioBroker.StringOrTranslated;
+};
+export type DmActionConfirmResponse = DmResponseBase & {
+    type: 'confirm';
+    confirm: ioBroker.StringOrTranslated;
+};
+export type DmActionUrlResponse = DmResponseBase & {
+    type: 'url';
+    data: {
+        url: string;
+        target: string;
+    };
+};
+export interface CommunicationForm {
+    title?: ioBroker.StringOrTranslated | null | undefined;
+    label?: ioBroker.StringOrTranslated | null | undefined;
+    noTranslation?: boolean;
+    schema: JsonFormSchema;
+    data?: Record<string, any>;
+    buttons?: (ActionButton | 'apply' | 'cancel' | 'close')[];
+    maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Minimal width of the dialog */
+    minWidth?: number;
+    /** Always allow the Apply button. Even when nothing was changed */
+    ignoreApplyDisabled?: boolean;
+}
+export type DmActionFormResponse = DmResponseBase & {
+    type: 'form';
+    form: CommunicationForm;
+};
+export type DmActionProgressResponse = DmResponseBase & {
+    type: 'progress';
+    progress: ProgressUpdate & {
+        open?: boolean;
+    };
+};
+export type DmActionResponse = DmActionResultResponse | DmActionMessageResponse | DmActionConfirmResponse | DmActionUrlResponse | DmActionFormResponse | DmActionProgressResponse;

package/build/types/base.d.ts

@@ -1,13 +1,13 @@
 import type { ActionContext, ConfigConnectionType, ErrorResponse, MessageContext, ValueOrObject, ValueOrState, ValueOrStateOrObject } from '..';
-import type { ApiVersion, DeviceRefresh, DeviceStatus, RetVal } from './common';
+import type { ApiVersion, DeviceId, DeviceStatus, RetVal } from './common';
 type ActionType = 'api' | 'adapter';
 export type Color = 'primary' | 'secondary' | (string & {});
 export type ControlState = string | number | boolean | null;
 /** Reserved action names */
 export declare const ACTIONS: {
-    /** This action will be called when user clicks on connection icon */
+    /** This action will be called when the user clicks on the connection icon */
     STATUS: string;
-    /** This action will be called when the user clicks on enabled/disabled icon. The enabled/disabled icon will be shown only if the node status has "enabled" flag set to false or true */
+    /** This action will be called when the user clicks on the enabled / disabled icon. The enabled/disabled icon will be shown only if the node status has the "enabled" flag set to false or true */
     ENABLE_DISABLE: string;
 };
 export interface ActionBase<T extends ActionType> {
@@ -16,7 +16,7 @@ export interface ActionBase<T extends ActionType> {
     /**
      * This can either be base64 or the URL to an icon.
      */
-    icon?: 'edit' | 'rename' | 'delete' | 'refresh' | 'newDevice' | 'new' | 'add' | 'discover' | 'search' | 'unpairDevice' | 'pairDevice' | 'identify' | 'play' | 'stop' | 'pause' | 'forward' | 'next' | 'rewind' | 'previous' | 'lamp' | 'light' | 'backlight' | 'dimmer' | 'socket' | 'settings' | 'users' | 'group' | 'user' | string;
+    icon?: 'edit' | 'rename' | 'delete' | 'refresh' | 'newDevice' | 'new' | 'add' | 'discover' | 'search' | 'unpairDevice' | 'pairDevice' | 'identify' | 'play' | 'stop' | 'pause' | 'forward' | 'next' | 'rewind' | 'previous' | 'lamp' | 'light' | 'backlight' | 'dimmer' | 'socket' | 'settings' | 'users' | 'group' | 'user' | 'info' | (string & {});
     description?: ioBroker.StringOrTranslated;
     disabled?: T extends 'api' ? boolean : never;
     color?: Color;
@@ -81,31 +81,46 @@ export interface ControlBase {
     }[];
     channel?: ChannelInfo;
 }
-export interface DeviceControl<T extends ActionType = 'api'> extends ControlBase {
-    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 DeviceControl<TType extends ActionType = 'api', TId extends DeviceId = DeviceId> extends ControlBase {
+    handler?: TType extends 'api' ? never : (deviceId: TId, actionId: string, state: ControlState, context: MessageContext<TId>) => RetVal<ErrorResponse | ioBroker.State>;
+    getStateHandler?: TType extends 'api' ? never : (deviceId: TId, actionId: string, context: MessageContext<TId>) => RetVal<ErrorResponse | ioBroker.State>;
 }
-export interface InstanceAction<T extends ActionType = 'api'> extends ActionBase<T> {
-    handler?: T extends 'api' ? never : (context: ActionContext, options?: Record<string, any>) => RetVal<{
-        refresh: boolean;
-    }>;
+export type InstanceRefreshResponse = {
+    refresh: boolean;
+};
+export type WithHandlerOrUrl<TType extends ActionType, THandler> = {
+    handler?: TType extends 'api' ? never : THandler;
+} | {
+    url: ioBroker.StringOrTranslated;
+};
+export type InstanceAction<T extends ActionType = 'api'> = ActionBase<T> & WithHandlerOrUrl<T, (context: ActionContext, options?: Record<string, any>) => RetVal<InstanceRefreshResponse>> & {
     title: ioBroker.StringOrTranslated;
-}
-export interface DeviceAction<T extends ActionType = 'api'> extends ActionBase<T> {
-    handler?: T extends 'api' ? never : (deviceId: string, context: ActionContext, options?: Record<string, any>) => RetVal<{
-        refresh: DeviceRefresh;
-    }>;
-}
+};
+export type DeviceUpdate<T extends ActionType = 'api', TId extends DeviceId = DeviceId> = {
+    update: DeviceInfo<T, TId>;
+};
+export type DeviceDelete<TId extends DeviceId = DeviceId> = {
+    delete: TId;
+};
+export type DeviceRefresh = 'all' | 'devices' | 'instance' | 'none';
+export type DeviceRefreshResponse<T extends ActionType = 'api', TId extends DeviceId = DeviceId> = {
+    refresh: DeviceRefresh;
+} | DeviceUpdate<T, TId> | DeviceDelete<TId>;
+export type DeviceAction<T extends ActionType = 'api', TId extends DeviceId = DeviceId> = ActionBase<T> & WithHandlerOrUrl<T, (deviceId: TId, context: ActionContext, options?: Record<string, any>) => RetVal<DeviceRefreshResponse<'adapter', TId>>>;
 export interface InstanceDetails<T extends ActionType = 'api'> {
     /** API Version: 1 - till 2025 (including), 2 - from 2026 */
     apiVersion: ApiVersion;
     actions?: InstanceAction<T>[];
     /** ID of state used for communication with GUI */
     communicationStateId?: string;
+    /** Human-readable label next to the identifier */
+    identifierLabel?: ioBroker.StringOrTranslated;
 }
-export interface DeviceInfo<T extends ActionType = 'api'> {
-    /** ID of the action. Should be unique only in one adapter. Other adapters could have same names */
-    id: string;
+export interface DeviceInfo<T extends ActionType = 'api', TId extends DeviceId = DeviceId> {
+    /** ID of the device. Must be unique only in one adapter. Other adapters could have the same IDs */
+    id: TId;
+    /** Human-readable identifier of the device */
+    identifier?: ValueOrObject<string>;
     /** Name of the device. It will be shown in the card header */
     name: ValueOrObject<ioBroker.StringOrTranslated>;
     /** base64 or url icon for device card */
@@ -119,12 +134,12 @@ export interface DeviceInfo<T extends ActionType = 'api'> {
     status?: DeviceStatus | DeviceStatus[];
     /** Connection type, how the device is connected */
     connectionType?: ValueOrStateOrObject<ConfigConnectionType>;
-    /** If this flag is true or false, the according indication will be shown. Additionally, if ACTIONS.ENABLE_DISABLE is implemented, this action will be sent to backend by clicking on this indication */
+    /** If this flag is true or false, the according indication will be shown. Additionally, if ACTIONS.ENABLE_DISABLE is implemented, this action will be sent to the backend by clicking on this indication */
     enabled?: ValueOrState<boolean>;
     /** List of actions on the card */
-    actions?: DeviceAction<T>[];
+    actions?: DeviceAction<T, TId>[];
     /** List of controls on the card. The difference of controls and actions is that the controls can show status (e.g. on/off) and can work directly with states */
-    controls?: DeviceControl<T>[];
+    controls?: DeviceControl<T, TId>[];
     /** If true, the button `more` will be shown on the card and called `dm:deviceDetails` action to get the details  */
     hasDetails?: ValueOrStateOrObject<boolean>;
     /** Device type for grouping */
@@ -134,30 +149,30 @@ export interface DeviceInfo<T extends ActionType = 'api'> {
         icon?: string;
     };
 }
-export interface BackendToGuiCommandDeviceInfoUpdate {
-    /** Used for updating and for adding new device */
+export interface BackendToGuiCommandDeviceInfoUpdate<TId extends DeviceId = DeviceId> {
+    /** Used for updating and for adding a new device */
     command: 'infoUpdate';
     /** Device ID */
-    deviceId: string;
-    /** Backend can send directly new information about device to avoid extra request from GUI */
+    deviceId: TId;
+    /** Backend can directly send new information about a device to avoid extra request from GUI */
     info?: DeviceInfo;
 }
-export interface BackendToGuiCommandDeviceStatusUpdate {
-    /** Status of device was updated */
+export interface BackendToGuiCommandDeviceStatusUpdate<TId extends DeviceId = DeviceId> {
+    /** Status of a device was updated */
     command: 'statusUpdate';
     /** Device ID */
-    deviceId: string;
-    /** Backend can send directly new status to avoid extra request from GUI */
+    deviceId: TId;
+    /** Backend can directly send new status to avoid extra request from GUI */
     status?: DeviceStatus;
 }
-export interface BackendToGuiCommandDeviceDelete {
+export interface BackendToGuiCommandDeviceDelete<TId extends DeviceId = DeviceId> {
     /** Device was deleted */
     command: 'delete';
-    deviceId: string;
+    deviceId: TId;
 }
 export interface BackendToGuiCommandAllUpdate {
     /** Read ALL information about all devices anew */
     command: 'all';
 }
-export type BackendToGuiCommand = BackendToGuiCommandDeviceInfoUpdate | BackendToGuiCommandDeviceStatusUpdate | BackendToGuiCommandDeviceDelete | BackendToGuiCommandAllUpdate;
+export type BackendToGuiCommand<TId extends DeviceId = DeviceId> = BackendToGuiCommandDeviceInfoUpdate<TId> | BackendToGuiCommandDeviceStatusUpdate<TId> | BackendToGuiCommandDeviceDelete<TId> | BackendToGuiCommandAllUpdate;
 export {};

package/build/types/base.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ACTIONS = void 0;
 /** Reserved action names */
 exports.ACTIONS = {
-    /** This action will be called when user clicks on connection icon */
+    /** This action will be called when the user clicks on the connection icon */
     STATUS: 'status',
-    /** This action will be called when the user clicks on enabled/disabled icon. The enabled/disabled icon will be shown only if the node status has "enabled" flag set to false or true */
+    /** This action will be called when the user clicks on the enabled / disabled icon. The enabled/disabled icon will be shown only if the node status has the "enabled" flag set to false or true */
     ENABLE_DISABLE: 'enable/disable',
 };