@pushler/js 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# @pushler/js
+
+JavaScript SDK для [Pushler.ru](https://pushler.ru) — сервиса real-time сообщений через WebSocket.
+
+## Установка
+
+```bash
+npm install @pushler/js
+```
+
+Или через CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@pushler/js/dist/pushler-ru.min.js"></script>
+```
+
+## Быстрый старт
+
+### Браузер (WebSocket клиент)
+
+```javascript
+import Pushler from '@pushler/js';
+
+// Создание клиента
+const pushler = Pushler.Create({
+  appKey: 'your-app-key',
+  wsUrl: 'wss://pushler.ru/ws',
+  apiUrl: 'https://api.pushler.ru'
+});
+
+// Обработка событий подключения
+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)
+
+```javascript
+import Pushler from '@pushler/js';
+
+// Создание серверного клиента
+const server = Pushler.Server({
+  appKey: 'your-app-key',
+  appSecret: 'your-app-secret',
+  apiUrl: 'https://api.pushler.ru'
+});
+
+// Отправка сообщения в канал
+await server.trigger('my-channel', 'new-message', {
+  text: 'Привет, мир!',
+  timestamp: Date.now()
+});
+
+// Отправка в несколько каналов
+await server.trigger(
+  ['channel-1', 'channel-2'],
+  'notification',
+  { message: 'Важное уведомление!' }
+);
+```
+
+## API
+
+### PushlerClient (браузер)
+
+#### Создание клиента
+
+```javascript
+const pushler = Pushler.Create({
+  appKey: 'your-app-key',        // Обязательно
+  wsUrl: 'wss://pushler.ru/ws',  // URL WebSocket сервера
+  apiUrl: 'https://api.pushler.ru', // URL API сервера
+  authEndpoint: '/pushler/auth', // Путь для авторизации приватных каналов
+  autoConnect: true,             // Автоподключение (по умолчанию: true)
+  reconnectDelay: 1000,          // Задержка переподключения (мс)
+  maxReconnectAttempts: 5        // Максимум попыток переподключения
+});
+```
+
+#### Методы
+
+| Метод | Описание |
+|-------|----------|
+| `connect()` | Подключиться к серверу |
+| `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)
+
+#### Создание сервера
+
+```javascript
+const server = Pushler.Server({
+  appKey: 'your-app-key',           // Обязательно
+  appSecret: 'your-app-secret',     // Обязательно
+  apiUrl: 'https://api.pushler.ru', // URL API
+  timeout: 30000                    // Таймаут запросов (мс)
+});
+```
+
+#### Методы
+
+| Метод | Описание |
+|-------|----------|
+| `trigger(channels, event, data, socketId?)` | Отправить событие в канал(ы) |
+| `authorizeChannel(channelName, socketId)` | Авторизация приватного канала |
+| `authorizePresenceChannel(channelName, socketId, userData)` | Авторизация presence канала |
+| `verifyWebhook(headers, body)` | Проверка подписи вебхука |
+| `getMessageStatus(messageId)` | Статус сообщения |
+| `getMessages(params?)` | Список сообщений |
+
+## Типы каналов
+
+### Публичные каналы
+
+Доступны всем без авторизации:
+
+```javascript
+const channel = pushler.subscribe('news');
+```
+
+### Приватные каналы
+
+Требуют авторизации на вашем сервере:
+
+```javascript
+const channel = pushler.subscribe('private-user-123');
+```
+
+### Presence каналы
+
+Для отслеживания онлайн-пользователей:
+
+```javascript
+const channel = pushler.subscribe('presence-room-1', {
+  user: { id: 'user-123', name: 'Иван' }
+});
+```
+
+## Авторизация каналов
+
+Для приватных и presence каналов настройте endpoint авторизации на вашем сервере:
+
+```javascript
+// 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);
+  }
+});
+```
+
+## Вебхуки
+
+Проверка подписи входящих вебхуков:
+
+```javascript
+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](https://pushler.ru)