@pushler/js

JavaScript SDK для Pushler.ru — сервиса real-time сообщений через WebSocket.

Установка

npm install @pushler/js

Или через CDN:

<script src="https://cdn.jsdelivr.net/npm/@pushler/js/dist/pushler-ru.min.js"></script>

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

Браузер (WebSocket клиент)

import Pushler from '@pushler/js';

// Создание клиента
const pushler = Pushler.Create({
  appKey: 'your-app-key'
});

// Обработка событий подключения
pushler.on('connected', ({ socketId }) => {
  console.log('Подключено! Socket ID:', socketId);
});

pushler.on('error', (error) => {
  console.error('Ошибка:', error.message);
});

// Подписка на публичный канал
const channel = pushler.subscribe('my-channel');

channel.on('channel_subscribed', () => {
  console.log('Подписка успешна!');
});

// Получение сообщений
channel.on('new-message', (data) => {
  console.log('Новое сообщение:', data);
});

Node.js (Серверный SDK)

import Pushler from '@pushler/js';

// Создание серверного клиента
const server = Pushler.Server({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret'
});

// Отправка сообщения в канал
await server.trigger('my-channel', 'new-message', {
  text: 'Привет, мир!',
  timestamp: Date.now()
});

// Отправка в несколько каналов
await server.trigger(
  ['channel-1', 'channel-2'],
  'notification',
  { message: 'Важное уведомление!' }
);

API

PushlerClient (браузер)

Создание клиента

const pushler = Pushler.Create({
  appKey: 'your-app-key',           // Обязательно
  authEndpoint: '/pushler/auth',    // Путь для авторизации приватных каналов
  autoConnect: true,                // Автоподключение (по умолчанию: true)
  reconnectDelay: 1000,             // Задержка переподключения (мс)
  maxReconnectAttempts: 5,          // Максимум попыток переподключения
  
  // Кастомные заголовки авторизации (опционально)
  authHeaders: {
    'Authorization': 'Bearer your-token'
  },
  
  // Или динамические заголовки
  getAuthHeaders: () => ({
    'Authorization': `Bearer ${getToken()}`
  })
});

Promise-based подключение

// connect() возвращает Promise
const { socketId } = await pushler.connect();
console.log('Подключено! Socket ID:', socketId);

// Или с таймаутом
try {
  await pushler.waitForConnection(10000); // 10 секунд
} catch (error) {
  console.error('Не удалось подключиться:', error.message);
}

Методы

| Метод | Описание | |-------|----------| | connect() | Подключиться к серверу (возвращает Promise) | | waitForConnection(timeout?) | Ожидание подключения с таймаутом | | disconnect() | Отключиться от сервера | | subscribe(channelName, options?) | Подписаться на канал | | unsubscribe(channelName) | Отписаться от канала | | channel(channelName) | Получить объект канала | | getChannels() | Список подписанных каналов | | getConnectionState() | Текущее состояние подключения |

События

| Событие | Данные | Описание | |---------|--------|----------| | connected | { socketId } | Подключение установлено | | disconnected | event | Подключение разорвано | | connection_state_changed | state | Изменение состояния | | error | { code, message } | Ошибка | | message_received | { channel, event, data } | Получено сообщение |

Channel (канал)

Методы

| Метод | Описание | |-------|----------| | on(event, callback) | Подписка на событие | | off(event, callback) | Отписка от события | | unsubscribe() | Отписаться от канала | | isSubscribed() | Проверка подписки | | getType() | Тип канала (public/private/presence) |

PushlerServer (Node.js)

Создание сервера

const server = Pushler.Server({
  appKey: 'your-app-key',           // Обязательно
  appSecret: 'your-app-secret',     // Обязательно
  timeout: 10000                    // Таймаут запросов (мс)
});

Методы

| Метод | Описание | |-------|----------| | trigger(channels, event, data, socketId?) | Отправить событие в канал(ы) | | authorizeChannel(channelName, socketId) | Авторизация приватного канала | | authorizePresenceChannel(channelName, socketId, userData) | Авторизация presence канала | | verifyWebhook(headers, body) | Проверка подписи вебхука | | getMessageStatus(messageId) | Статус сообщения | | getMessages(params?) | Список сообщений |

Типы каналов

Публичные каналы

Доступны всем без авторизации:

const channel = pushler.subscribe('news');

Приватные каналы

Требуют авторизации на вашем сервере:

const channel = pushler.subscribe('private-user-123');

Presence каналы

Для отслеживания онлайн-пользователей:

const channel = pushler.subscribe('presence-room-1', {
  user: { id: 'user-123', name: 'Иван' }
});

Авторизация каналов

Для приватных и presence каналов настройте endpoint авторизации на вашем сервере:

// Express.js пример
app.post('/pushler/auth', (req, res) => {
  const { channel_name, socket_id, app_key, user_data } = req.body;
  
  // Проверьте права пользователя на доступ к каналу
  const server = Pushler.Server({
    appKey: process.env.PUSHLER_KEY,
    appSecret: process.env.PUSHLER_SECRET
  });
  
  if (channel_name.startsWith('presence-')) {
    const auth = server.authorizePresenceChannel(channel_name, socket_id, user_data);
    res.json(auth);
  } else {
    const auth = server.authorizeChannel(channel_name, socket_id);
    res.json(auth);
  }
});

Вебхуки

Проверка подписи входящих вебхуков:

app.post('/webhooks/pushler', (req, res) => {
  try {
    const data = server.verifyWebhook(req.headers, req.rawBody);
    console.log('Получен вебхук:', data);
    res.sendStatus(200);
  } catch (error) {
    console.error('Невалидный вебхук:', error);
    res.sendStatus(403);
  }
});

Примеры

Смотрите папку examples/ для полных примеров:

• basic.html — базовый пример в браузере
• advanced.html — продвинутый пример с приватными каналами
• send-message.mjs — отправка сообщений из Node.js
• auth-channel.mjs — авторизация каналов

Поддержка браузеров

• Chrome 49+
• Firefox 52+
• Safari 10+
• Edge 14+

Лицензия

MIT © Pushler.ru