@allior/wmake-donatty

Библиотека для интеграции с сервисом Donatty. Поддерживает работу с API и получение событий в реальном времени через SSE (Server-Sent Events).

Установка

bun add @allior/wmake-donatty
# или
npm install @allior/wmake-donatty

Возможности

• 🔑 Авторизация: Получение токенов через widgetToken.
• 📡 SSE (Real-time): Подписка на события виджетов (донаты, цели, общие суммы) и ленту стримера.
• 📜 События: Получение списка прошедших событий и донатов.
• 👤 Профиль: Получение данных текущего пользователя.
• 🏗 TypeScript: Полная типизация всех ответов и параметров.

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

Получение токена авторизации

Для работы с большинством методов требуется accessToken (JWT). Его можно получить, зная widgetToken (токен виджета из URL настроек Donatty).

import { getAuthTokens } from "@allior/wmake-donatty";

const { accessToken } = await getAuthTokens("your_widget_token");

Подписка на события (SSE)

Библиотека позволяет подключаться к стриму событий Donatty.

import { DonattySSEClient, getAuthTokens } from "@allior/wmake-donatty";

async function connectToAlerts() {
    const WIDGET_TOKEN = "xxx";
    const WIDGET_REF = "yyy"; // ID виджета (ref из URL)

    const { accessToken } = await getAuthTokens(WIDGET_TOKEN);
    
    // Создаем клиент для виджета оповещений (Alerts)
    const client = DonattySSEClient.forDonationsWidget(WIDGET_REF, accessToken);

    client.on("DATA", (msg) => {
        console.log("Новое событие:", msg.data);
    });

    client.connect();
}

Получение списка донатов

import { DonattyEventsClient } from "@allior/wmake-donatty";

const client = new DonattyEventsClient(accessToken);
const donations = await client.getDonations(10); // Последние 10 донатов

console.log(donations.response.items);

React: хуки для SSE

Библиотека предоставляет набор хуков для удобной работы с SSE в React-приложениях.

Автоматическое подключение (лента стримера)

import { useDonattyStreamerSSE } from "@allior/wmake-donatty/react";

function App() {
  const { isConnected } = useDonattyStreamerSSE("YOUR_JWT_TOKEN", {
    handlers: {
      "STREAM_EVENT": (data) => console.log("Новое событие:", data.event),
    }
  });

  return <div>Статус: {isConnected ? "Подключено" : "Отключено"}</div>;
}

Работа с виджетами

import { useDonattyDonationsWidget } from "@allior/wmake-donatty/react";

function Alerts() {
  const { isConnected } = useDonattyDonationsWidget("WIDGET_REF_ID", "JWT_TOKEN", {
    handlers: {
      "DATA": (msg) => console.log("Оповещение:", msg.data),
    }
  });

  return <div>Оповещения: {isConnected ? "Работают" : "Загрузка..."}</div>;
}

Доступные хуки:

• useDonattySSE — базовый хук.
• useDonattyStreamerSSE(jwt, options) — лента событий стримера.
• useDonattyGoalWidget(refId, jwt, options) — виджет целей.
• useDonattyTotalWidget(refId, jwt, options) — виджет общей суммы.
• useDonattyDonationsWidget(refId, jwt, options) — виджет оповещений.

API Reference

DonattySSEClient

Класс для работы с Server-Sent Events.

• static forStreamer(jwt) — лента событий для дашборда стримера.
• static forWidget(refId, jwt) — общий метод для виджетов.
• static forGoalWidget(refId, jwt) — виджет "Цель".
• static forTotalWidget(refId, jwt) — виджет "Общая сумма".
• static forDonationsWidget(refId, jwt) — виджет "Оповещения".
• connect() — установить соединение.
• disconnect() — закрыть соединение.
• on(event, handler) — подписаться на событие.
• off(event, handler) — отписаться.

DonattyEventsClient

Класс для получения исторических данных.

• get(params) — получить список событий с фильтрами.
• getDonations(maxResults) — получить только донаты.

Вспомогательные функции

• getAuthTokens(widgetToken) — обмен токена виджета на JWT.
• getMe(accessToken) — получение профиля пользователя.

Примеры

Больше примеров можно найти в директории examples/:

• react-hooks-usage.tsx — использование хуков в React.
• handle-events.ts — отладка всех SSE событий.
• handle-goal-widget.ts — работа с виджетом целей.
• fetch-events.ts — работа с историей событий.

Лицензия

CC BY-SA 4.0