@mirta/globals 0.3.1 → 0.3.3

package/eslint/index.d.ts

@@ -2,6 +2,7 @@ declare interface GlobalsMirta {
   readonly '__DEV__': false
   readonly '__TEST__': false
   readonly 'log': false
+  readonly 'debug': false
   readonly 'dev': false
   readonly 'cron': false
   readonly 'timers': false
@@ -20,6 +21,7 @@ declare interface GlobalsMirta {
   readonly 'StorableObject': false
   readonly 'PersistentStorage': false
   readonly 'Notify': false
+  readonly 'Alarms': false
 }
 
 declare const globals: GlobalsMirta

package/eslint/index.js

@@ -2,6 +2,7 @@ export default {
   '__DEV__': 'readonly',
   '__TEST__': 'readonly',
   'log': 'readonly',
+  'debug': 'readonly',
   'dev': 'readonly',
   'cron': 'readonly',
   'timers': 'readonly',
@@ -20,4 +21,5 @@ export default {
   'StorableObject': 'readonly',
   'PersistentStorage': 'readonly',
   'Notify': 'readonly',
+  'Alarms': 'readonly',
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mirta/globals",
   "description": "Complete set of types for wb-rule development in TypeScript",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "Unlicense",
   "keywords": [
     "mirta",

package/types/wb-rules/alarms.d.ts

@@ -0,0 +1,276 @@
+declare namespace WbRules {
+
+  /**
+   * Определения типов для сервиса оповещений.
+   *
+   * @since 0.3.3
+   *
+   **/
+  namespace Alarms {
+
+    /**
+     * Позволяет задать способ оповещения через SMS.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface SmsRecipient {
+
+      /** Конфигурация отправки SMS. */
+      type: 'sms'
+
+      /** Номер телефона получателя SMS. */
+      to: string
+
+      /**
+       * Команда для отправки SMS. Поле можно оставить пустым, чтобы использовать gammu.
+       *
+       * В команде нужно указать как минимум один плейсхолдер `{}` - для номера. Тогда
+       * текст будет отправлен в stdin.
+       *
+       * Если указать 2 плейсхолдера - то в первый запишется номер, во второй - текст.
+       *
+       * @examples
+       * ```sh
+       * /path/to/sender.py --number {}
+       * ```
+       * ```sh
+       * /path/to/sender.py --number {} --text "{}"
+       * ```
+       **/
+      command?: string
+    }
+
+    /**
+     * Позволяет задать способ оповещения через E-mail.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface EmailRecipient {
+
+      /** Конфигурация отправки на адрес электронной почты. */
+      type: 'email'
+
+      /** Адрес электронной почты получателя. */
+      to: string
+
+      /**
+       * Тема письма (необязательное поле).
+       *
+       * Если в теме письма использовать плейсхолдер `{}`, он заменится на текст сообщения.
+       *
+       * @example
+       * ```txt
+       * Alarm: {}
+       * ```
+       **/
+      subject?: string
+    }
+
+    /**
+     * Позволяет задать способ оповещения через Telegram.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface TelegramRecipient {
+
+      /** Конфигурация отправки в Telegram. */
+      type: 'telegram'
+
+      /** Токен вашего бота Telegram. */
+      token: string
+
+      /** Уникальный идентификатор целевого чата или username целевого канала (в формате `@channelusername`). */
+      chatId: string
+    }
+
+    /**
+     * Позволяет настроить один из вариантов
+     * оповещения - через SMS, E-Mail или Telegram.
+     *
+     * Конкретный состав полей меняется в зависимости от значения поля `type`.
+     *
+     * @since 0.3.3
+     *
+     **/
+    type Recipient = SmsRecipient | EmailRecipient | TelegramRecipient
+
+    /**
+     * Базовый компонент аларма - содержит общие свойства.
+     *
+     * Используется в составе типа {@link Alarm}.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface AlarmBase {
+
+      /** Название аларма. */
+      name: string
+
+      /** Наблюдаемые устройство и контрол в формате `deviceId/controlId`. */
+      cell: string
+
+      /**
+       * Сообщение, отправляемое при срабатывании аларма.
+       *
+       * Для подстановки текущего значения контрола используется плейсхолдер `{}`.
+       *
+       * Если сообщение не указано, оно генерируется автоматически на основе
+       * текущего значения контрола.
+       *
+       **/
+      alarmMessage?: string
+
+      /**
+       * Сообщение, отправляемое при деактивации аларма.
+       *
+       * Для подстановки текущего значения контрола используется плейсхолдер `{}`.
+       *
+       * Если сообщение не указано, оно генерируется автоматически на основе
+       * текущего значения контрола.
+       *
+       **/
+      noAlarmMessage?: string
+
+      /**
+       * Интервал (в секундах) повторной отправки сообщения во время активности аларма.
+       *
+       * Если временной интервал не установлен, сообщения направляются
+       * только при срабатывании, а также при деактивации аларма.
+       *
+       **/
+      interval?: number
+
+      /**
+       * Задержка срабатывания аларма (в миллисекундах).
+       *
+       * Если значение указано, то аларм сработает только когда условие срабатывания
+       * будет непрерывно выполняться в течение заданного интервала.
+       *
+       **/
+      alarmDelayMs?: number
+
+      /**
+       * Задержка деактивации аларма (в миллисекундах).
+       *
+       * Если значение указано, то аларм будет деактивирован только когда условие срабатывания
+       * прекратит непрерывно выполняться в течение заданного интервала.
+       *
+       **/
+      noAlarmDelayMs?: number
+
+      /**
+       * Максимальное количество отправленных сообщений.
+       *
+       * Если указано, то за каждый период срабатывания аларма
+       * отправляется не больше заданного количества сообщений.
+       *
+       **/
+      maxCount?: number
+    }
+
+    /**
+     * Компонент аларма, реализующий возможность контроля за соответствием указанному значению.
+     *
+     * Используется в составе типа {@link Alarm}.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface ValueAlarm {
+
+      /**
+       * Ожидаемое значение.
+       *
+       * Аларм сработает, если значение контрола отличается от `expectedValue`.
+       *
+       * Когда значение контрола снова становится равным `expectedValue`,
+       * аларм деактивируется.
+       *
+       **/
+      expectedValue: MqttValue
+    }
+
+    /**
+     * Компонент аларма, реализующий возможность контроля за соответствием
+     * значения контрола допустимому диапазону.
+     *
+     * Используется в составе типа {@link Alarm}.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface RangeAlarm {
+
+      /**
+       * Сервисное поле.
+       *
+       * Предотвращает смешивание с {@link ValueAlarm} внутри обобщённого типа {@link Alarm}.
+       *
+       **/
+      expectedValue: never
+
+      /**
+       * Минимально допустимое значение.
+       *
+       * Если отслеживаемое значение контрола опускается ниже minValue, происходит срабатывание аларма.
+       *
+       **/
+      minValue: number
+
+      /**
+       * Максимально допустимое значение.
+       *
+       * Если отслеживаемое значение контрола поднимается выше maxValue, происходит срабатывание аларма.
+       *
+       **/
+      maxValue: number
+    }
+
+    /**
+     * Позволяет задать устройство и контрол для отслеживания, а также настроить параметры реагирования.
+     *
+     * @since 0.3.3
+     *
+     **/
+    type Alarm = AlarmBase & (ValueAlarm | AtLeastOne<RangeAlarm>)
+
+    /**
+     * Конфигурация блока алармов.
+     *
+     * @since 0.3.3
+     *
+     **/
+    interface Config {
+
+      /** Название MQTT-устройства блока алармов. */
+      deviceName: string
+
+      /** Отображаемое название устройства блока алармов. */
+      deviceTitle: string
+
+      /** Список получателей. */
+      recipients: Recipient[]
+
+      /** Список алармов. */
+      alarms: Alarm[]
+    }
+  }
+
+  /**
+   * Интерфейс для типизации сервиса оповещений.
+   *
+   **/
+  interface Alarms {
+
+    /**
+     * Загружает конфигурацию для блока алармов.
+     *
+     * @param config Объект конфигурации или путь к файлу конфигурации в формате JSON.
+     */
+    load(config: string | Alarms.Config): void
+  }
+}

package/types/wb-rules.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="./wb-rules/alarms.d.ts" />
+
 /**
  * Используется для нормализации составных типов.
  *
@@ -16,56 +18,147 @@
  * // }
  * ```
  * @since 0.0.4
+ *
  **/
 declare type Expand<T> = { [K in keyof T]: T[K] } & {}
 
+/**
+ * Разрешает частичное заполнение полей объекта, но требует наличия хотя бы одного поля.
+ *
+ * @example
+ * ```ts
+ * interface SafeRange {
+ *   minValue: number
+ *   maxValue: number
+ * }
+ *
+ * // Корректное объявление
+ * const a: AtLeastOne<SafeRange> = {
+ *   minValue: 0
+ * }
+ *
+ * // Ошибка - требуется хотя бы одно из обязательных полей
+ * const b: AtLeastOne<SafeRange> = { }
+ * ```
+ * @since 0.3.3
+ *
+ **/
+declare type AtLeastOne<T, U = { [K in keyof T]: Pick<T, K> }> = Partial<T> & U[keyof U]
+
 /** Типы и интерфейсы правил wb-rules */
 declare namespace WbRules {
 
   /** Расширение для поддержки module.static */
   type ModuleStatic = Record<string, unknown>
 
-  type LogFunc = (
-    message: string | undefined, ...args: (string | number | boolean)[]
-  ) => void
+  /**
+   * Набор методов для логирования.
+   *
+   * @since 0.3.2
+   *
+   **/
+  interface LogMethods {
 
-  interface Log {
     /**
      * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    (message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.info('Свет в комнате включён на {} мин.', 30)
+     * ```
+     **/
+    info(format: string, ...args: unknown[]): void
 
     /**
-     * Запись в лог сообщения, полезного при отладке в процессе разработки и не представляющего ценности в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    debug(message: unknown, ...args: (string | number | boolean)[]): void
+     * Запись в лог произвольного значения, полезного в долгосрочной перспективе.
+     * @param value Значение для записи в лог.
+     *
+     **/
+    info(value: unknown): void
 
     /**
-     * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    info(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог сообщения, полезного при отладке и не имеющего долгосрочной ценности.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.debug('Значение сенсора "{}": температура {} °C, влажность {} %', 'bathroom', 25, 40)
+     **/
+    debug(format: string, ...args: unknown[]): void
 
     /**
-     * Запись ненормального или неожиданного события в потоке приложения, но не прекращение выполнения.
-     * @param message
-     * @param args
-     */
-    warning(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог произвольного значения, полезного при отладке и не имеющего долгосрочной ценности.
+     *
+     * @param value Значение для записи в лог.
+     *
+     * @example
+     * ```ts
+     * log.debug(JSON.stringify({ location: 'bathroom', temperature: 25, humidity: 40 }))
+     * ```
+     **/
+    debug(value: unknown): void
 
     /**
-     * Запись события остановки выполнения из-за сбоя текущего действия.
-     * @param message
-     * @param args
-     */
-    error(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог предупреждения о ненормальном или неожиданном событии,
+     * не приводящем к остановке программы.
+     *
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.warning('Движение в охраняемой зоне: {}', 'hallway_sensor_1')
+     * ```
+     **/
+    warning(format: string, ...args: unknown[]): void
+
+    /**
+     * Запись в лог предупреждения о ненормальном или неожиданном значении,
+     * не приводящем к остановке программы.
+     *
+     * @param value Значение для записи в лог.
+     *
+     **/
+    warning(value: unknown): void
+
+    /**
+     * Запись в лог критического события, приведшего к сбою и остановке выполнения.
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.error('Перегев тёплого пола: {} °C, выключение', 30)
+     * ```
+     **/
+    error(format: string, ...args: unknown[]): void
+
+    /**
+     * Запись в лог критического значения, приведшего к сбою и остановке выполнения.
+     *
+     * @param value Значение для записи в лог.
+     *
+     **/
+    error(value: unknown): void
   }
 
+  /** @deprecated since version 0.3.2 */
+  type LogFunc = (format: string, ...args: unknown[]) => void
+
+  type Log = LogMethods['info'] & LogMethods
+
+  type Debug = LogMethods['debug']
+
   interface CronEntry {
     spec: string
   }
@@ -384,6 +477,62 @@ declare namespace WbRules {
     order?: number
   }>
 
+  /**
+   * Опции контрола типа `text`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type TextControlOptions = Extract<ControlOptions, { type: 'text' }>
+
+  /**
+   * Опции контрола типа `value`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type ValueControlOptions = Extract<ControlOptions, { type: 'value' }>
+
+  /**
+   * Опции контрола типа `range`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type RangeControlOptions = Extract<ControlOptions, { type: 'range' }>
+
+  /**
+   * Опции контрола типа `switch`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type SwitchControlOptions = Extract<ControlOptions, { type: 'switch' }>
+
+  /**
+   * Опции контрола типа `pushbutton`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type PushButtonControlOptions = Extract<ControlOptions, { type: 'pushbutton' }>
+
+  /**
+   * Опции контрола типа `rgb`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type RgbControlOptions = Extract<ControlOptions, { type: 'rgb' }>
+
+  /**
+   * Опции контрола типа `alarm`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type AlarmControlOptions = Extract<ControlOptions, { type: 'alarm' }>
+
   /**
    * Интерфейс устройства
    */
@@ -476,6 +625,41 @@ declare namespace WbRules {
   interface StorageOptions {
     global: boolean
   }
+
+  interface Notify {
+    /**
+     * Отправляет электронное письмо указанному адресату.
+     *
+     * @param to Адресат.
+     * @param subject Тема письма.
+     * @param text Текст письма.
+     *
+     **/
+    sendEmail(to: string, subject: string, text: string): void
+
+    /**
+     * Отправляет SMS на указанный номер
+     * Для отправки SMS используется ModemManager, а если он не установлен, то gammu.
+     *
+     * @param to Номер адресата.
+     * @param text Текст сообщения.
+     * @param command Используя команду.
+     *
+     **/
+    sendSMS(to: string, text: string, command?: string): void
+
+    /**
+     * Отправляет сообщение в указанный чат или канал Telegram.
+     *
+     * @param token Токен вашего бота Telegram.
+     * @param chatId Уникальный идентификатор целевого чата или username целевого канала (в формате `@channelusername`).
+     * @param text Текст сообщения.
+     *
+     * @since 0.3.2
+     *
+     **/
+    sendTelegramMessage(token: string, chatId: string, text: string): void
+  }
 }
 
 declare namespace NodeJS {
@@ -495,6 +679,14 @@ declare var __filename: string
 /** Используется для вывода сообщений в журнал контроллера и отладочную консоль. */
 declare var log: WbRules.Log
 
+/**
+ * Используется для вывода отладочных сообщений в журнал контроллера и отладочную консоль.
+ *
+ * @since 0.3.2
+ *
+ **/
+declare var debug: WbRules.Debug
+
 /** Объект доступа к MQTT-топикам устройства. */
 declare var dev: WbRules.Dev
 
@@ -730,28 +922,34 @@ declare class PersistentStorage {
 }
 
 /**
- * Класс оповещения
- * @abstract
- */
-declare abstract class Notify {
-  /**
-   * Отправляет почту указанному адресату
-   * @static
-   * @param to адресат
-   * @param subject тема
-   * @param text содержимое
-   * @memberof Notify
-   */
-  static sendEmail(to: string, subject: string, text: string): void
+ * Сервис уведомлений Notify — инструмент для отправки произвольных
+ * сообщений по разным каналам коммуникации (почта, SMS, Telegram).
+ *
+ **/
+declare var Notify: WbRules.Notify
 
-  /**
-   * Отправляет SMS на указанный номер
-   * Для отправки SMS используется ModemManager, а если он не установлен, то gammu.
-   * @static
-   * @param to номер адресата
-   * @param text содержимое
-   * @param command используя команду
-   * @memberof Notify
-   */
-  static sendSMS(to: string, text: string, command?: string): void
-}
+/**
+ * Сервис оповещений Alarms — инструмент для автоматической отправки
+ * шаблонных сообщений по разным каналам коммуникации (почта, SMS, Telegram)
+ * при обнаружении отклонения от нормы в значениях отслеживаемых контролов.
+ *
+ * @example
+ * Загрузка конфигурации из JSON-файла:
+ * ```ts
+ * Alarms.load('/etc/wb-rules/alarms.conf')
+ * ```
+ * @example
+ * Непосредственная настройка блока алармов через объект конфигурации:
+ * ```ts
+ * Alarms.load({
+ *   deviceName: 'example_alarms',
+ *   deviceTitle: 'Example Alarms',
+ *   recipients: [],
+ *   alarms: []
+ * })
+ * ```
+ *
+ * @since 0.3.3
+ *
+ **/
+declare var Alarms: WbRules.Alarms