@mirta/chatbot — Telegram-бот для Wiren Board

Управляйте вашим контроллером через Telegram — безопасно, просто, без лишнего кода.

Этот модуль позволяет:

• Принимать команды из чата: включить свет, открыть ворота и т.д.
• Отправлять уведомления: "Температура упала ниже 18°C"
• Ограничивать доступ: только администраторы или участники группы
• Использовать кнопки, меню, колбэки.

Работает внутри проектов на основе Mirta — фреймворка для автоматизаций на базе контроллеров Wiren Board.

💡 Этот пакет — дополнение экосистемы Mirta.
Он подключается к вашему проекту и работает вместе с ним.

📦 Установка

Если вы ещё не используете Mirta — начните с создания проекта.

Затем добавьте функционал бота одной командой:

pnpm add @mirta/chatbot

🛠️ Быстрый старт

1. Создайте Telegram-бота через @BotFather → получите токен
2. Добавьте токен в .env.local вашего проекта

# Токен доступа бота
APP_TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
# Ваш ID в Telegram
APP_TELEGRAM_USER=123456789

3. Настройте бота в модуле

// src/wb-rules-modules/bot-telegram.ts
import { defineTelegramBot, defineAuthorization } from '@mirta/chatbot'

const auth = defineAuthorization(a => a
  .addPolicy('admin', p => p
    .allow(r => r.userId(process.env.APP_TELEGRAM_USER))
  )
)

export const useTelegramBot = defineTelegramBot(auth, {
  deviceName: 'telegram',
  deviceTitle: 'Telegram Bot',
  token: process.env.APP_TELEGRAM_TOKEN,
  commands: {
    start: { policy: 'admin' }
  }
})

4. Используйте бота в скриптах

// src/wb-rules/bot-usage.ts
import { useTelegramBot } from '#wbm/bot-telegram'

const bot = useTelegramBot()

bot.onCommand('start', (_, reply) => {
  reply('Привет! Добро пожаловать в систему.')
})

5. Соберите и задеплойте проект — бот начнёт работать.

🔐 Политики доступа

Определите, кто может выполнять команды:

const auth = defineAuthorization(a => a
  .addPolicy('admin', p => p
    // Доступ для указанного пользователя
    .allow(r => r.userId('1234567890'))
    // Если он обращается из указанного чата
    .allow(r => r.chatId('9876543210'))
  )
  .addPolicy('subscriber', p => p
    .allow(r => r
      // Доступ для всех пользователей указанного чата
      .chatId('1009876543210')
      // Если это супергруппа
      .chatType('supergroup')
    )
  )
)

Правила:

• allow — разрешить доступ
• deny — запретить (имеет приоритет)

Особенности:

• Несколько allow в одной политике работают по принципу «ИЛИ».
• Условия внутри одного allow — по принципу «И»

🧩 Что умеет бот

• ✅ Любые команды вроде /start, /reboot
• ✅ Колбэк-кнопки
• ✅ Inline-клавиатуры
• ✅ Отправка сообщений
• ✅ Очереди (защита от флуда)
• ⏳ Мессенджер Макс — в разработке (ограничения API)

📚 Где посмотреть пример?

Полный рабочий пример — в репозитории:
👉 projects/chatbot-demo

Там вы найдёте:

• Готовый модуль бота
• Скрипт с командами
• Образец конфигурации .env (в своих проектах используйте .env.local)

❤️ Благодарности

Спасибо, что используете Мирту!
Вместе мы делаем автоматизации проще — для всех.