🏀 Hoop

🇬🇧 Read in English

TypeScript SDK для упрощения разработки интеграций с Loop и Mattermost.

📦 Установка

npm install @triple-sun/hoop
# или
pnpm add @triple-sun/hoop
# или
yarn add @triple-sun/hoop

🎯 Что это?

Hoop предоставляет удобные и типобезопасные билдеры и фабрики для создания объектов Loop (или Mattermost) API, таких как посты, формы, диалоги, кнопки и т.д. Вместе с loop-client он сильно упрощает разработку интеграций для Loop и Mattermost.

✨ Фичи

• 🏗️ Билдеры - Построение сложных объектов цепочками вызовов
• 🏭 Фабрики - Шорткаты для билдеров и пресеты
• 📘 Строгая типизация - типобезопасность, неизменяемые объекты, подсказки и автокомплит
• 🌐 Локализация - Поддержка локализации
• 🔗 Сделан специально для loop-client

🚀 Быстрый старт

import { HoopFactory, ActionFactory } from '@triple-sun/hoop';

// Создаем пост с вложениями и интерактивными кнопками
const post = HoopFactory.Post()
  .set('message', 'Выберите действие:')
  .attachments.append({
    text: 'Нажмите кнопку ниже',
    actions: [
      ActionFactory.Button({ name: 'approve', integration: { url: 'https://some.url/approve' } }),
      ActionFactory.Button({ name: 'reject', integration: { url: 'https://some.url/reject' } })
    ]
  })
  .build();

📚 Основные компоненты

Билдеры (Builders)

Билдеры предоставляют fluent-интерфейс для создания сложных объектов:

• PostBuilder - Создание и изменение постов с вложениями, действиями и полями (подробный гайд)
• FormBuilder - Построение интерактивных форм (подробный гайд)
• DialogBuilder - Создание модальных диалогов (подробный гайд)
• AppBindingBuilder - Создание app bindings и embedded bindings в постах
• AttachmentBuilder - Управление вложениями постов

Фабрики (Factories)

Фабрики предлагают быстрые шорткаты для стандартных паттернов и групп билдеров:

• HoopFactory - Создание крупных объектов - постов, форм и диалогов
• ActionFactory - Создание кнопок и выпадающих списков
• AttachmentFactory - Создание вложений для постов
• BindingFactory - Настройка app bindings и embedded bindings в постах
• FormFieldFactory - Создание полей для форм
• DialogElementFactory - Создание элементов для диалогов

🔨 Примеры

Создание интерактивного поста

import { HoopFactory, ActionFactory } from '@triple-sun/hoop';

const post = HoopFactory.Post()
  .set('message', 'Вопрос опроса')
  .attachments.append({
    title: 'Насколько вы довольны?',
    text: 'Пожалуйста, выберите оценку',
    actions: [
      ActionFactory.Select.Static({
        name: 'rating',
        integration: { url: 'https://some.url/submit-rating' },
        options: [
          { text: 'Очень доволен', value: '5' },
          { text: 'Доволен', value: '4' },
          { text: 'Нейтрально', value: '3' },
          { text: 'Недоволен', value: '2' }
        ]
      })
    ]
  })
  .build();

Построение форм

import { HoopFactory } from '@triple-sun/hoop';

const form = HoopFactory.Form()
  .set('title', 'Регистрация пользователя')
  .fields.append(
    { type: 'text', name: 'username', display_name: 'Имя пользователя' },
    { type: 'text', name: 'email', display_name: 'Email', subtype: 'email' }
  )
  .build();

Работа с вложениями

const post = HoopFactory.Post()
  .set('message', 'Отчет о статусе')
  .attachments.append({
    color: '#00FF00',
    title: 'Сборка успешна',
    fields: [
      { title: 'Длительность', value: '2m 34s', short: true },
      { title: 'Тесты', value: '142 passed', short: true }
    ]
  })
  .build();

🌐 Локализация

Hoop поддерживает английскую и русскую локали для стандартных лейблов (например, "Отправить", "Диалог" и т.д.). По умолчанию используется русская (ru).

Для переключения локали используйте setLocale:

import { setLocale } from '@triple-sun/hoop';

setLocale('en'); // Переключиться на английские дефолтные значения

🧪 Разработка

# Запуск тестов
npm test

# Сборка проекта
npm run build

# Форматирование кода
npm run format

# Линтинг кода
npm run check

📄 Лицензия

MIT

🔗 Ссылки

• Репозиторий
• Issues
• Документация Mattermost Interactive Messages