npm package: @pushler/js
Description: JavaScript SDK for Pushler.ru real-time messaging (browser & Node.js)
Author: Pushler.ru
Latest version: 1.2.0

# @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'
});

// Обработка событий подключения
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'
});

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

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

```javascript
// 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)

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

```javascript
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?)` | Список сообщений |

## Типы каналов

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

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

```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)