@mirta/globals 0.3.2 → 0.3.3

package/eslint/index.d.ts

@@ -21,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

@@ -21,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.2",
+  "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" />
+
 /**
  * Используется для нормализации составных типов.
  *
@@ -20,6 +22,29 @@
  **/
 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 {
 
@@ -600,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 {
@@ -862,40 +922,34 @@ declare class PersistentStorage {
 }
 
 /**
- * Класс оповещения.
+ * Сервис уведомлений Notify — инструмент для отправки произвольных
+ * сообщений по разным каналам коммуникации (почта, SMS, Telegram).
  *
  **/
-declare abstract class Notify {
-  /**
-   * Отправляет электронное письмо указанному адресату.
-   *
-   * @param to Адресат.
-   * @param subject Тема письма.
-   * @param text Текст письма.
-   *
-   **/
-  static sendEmail(to: string, subject: string, text: string): void
+declare var Notify: WbRules.Notify
 
-  /**
-   * Отправляет SMS на указанный номер
-   * Для отправки SMS используется ModemManager, а если он не установлен, то gammu.
-   *
-   * @param to Номер адресата.
-   * @param text Текст сообщения.
-   * @param command Используя команду.
-   *
-   **/
-  static sendSMS(to: string, text: string, command?: string): void
-
-  /**
-   * Отправляет сообщение в указанный чат или канал Telegram.
-   *
-   * @param token Токен вашего бота Telegram.
-   * @param chatId Уникальный идентификатор целевого чата или username целевого канала (в формате `@channelusername`).
-   * @param text Текст сообщения.
-   *
-   * @since 0.3.2
-   *
-   **/
-  static sendTelegramMessage(token: string, chatId: string, text: 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