omnis-logger-sdk/README.md

SDK для интеграции Omnis Logger в проекты

# Omnis Logger SDK

Универсальный SDK для логирования с автоматическим перехватом сетевых ошибок для Web и React Native приложений.

## Основные возможности

- 🌐 **Автоматический перехват сетевых ошибок** (fetch, XMLHttpRequest)
- 🔧 **Поддержка Web и React Native**
- 📱 **Автоматический сбор данных о браузере** (для Web)
- 📊 **Передача готовых данных об устройстве** (для React Native)
- 🚨 **Перехват необработанных ошибок**
- 📝 **Гибкое логирование** с контекстом
- 🔄 **Автоматические повторы** при ошибках отправки

## Установка

```bash
npm install @your-org/omnis-logger
```

## Использование

### Web (Браузер)

```javascript
import { initOmnisLogger } from '@your-org/omnis-logger';

// Инициализация для Web
const logger = initOmnisLogger({
  endpoint: 'https://your-api.com',
  apiKey: 'your-api-key',
  environment: 'production',
  platform: 'web',
  version: '1.0.0',
  userId: 'user-123',
  sessionId: 'session-456'
});

// Логирование
logger.error('Произошла ошибка', { 
  action: 'user_click',
  component: 'Button' 
});

logger.info('Пользователь вошел в систему');
```

Для Web браузера SDK автоматически соберет:
- Данные о браузере и ОС
- Размер экрана и пиксельное соотношение
- User Agent
- Язык и временная зона

### React Native

```javascript
import { initOmnisLogger } from '@your-org/omnis-logger';
import DeviceInfo from 'react-native-device-info';
import { Platform } from 'react-native';

// Простая инициализация - SDK сам соберет все данные
const logger = initOmnisLogger({
  endpoint: 'https://your-api.com',
  apiKey: 'your-api-key',
  environment: 'production',
  platform: Platform.OS,
  version: '1.0.0',
  userId: 'user-123',
  sessionId: 'session-456',
  deviceInfoModule: DeviceInfo // Передаем модуль, SDK сам соберет данные
});

// Логирование
logger.error('Сетевая ошибка', { screen: 'Profile' });
```

SDK автоматически соберет:
- **Синхронные данные** (мгновенно): deviceId, model, brand, systemName, version, isTablet и др.
- **Асинхронные данные** (в фоне): deviceName, manufacturer, isEmulator, uniqueId и др.
- **Платформо-специфичные данные**: hasNotch/hasDynamicIsland для iOS, androidId/apiLevel для Android
- **Размеры экрана** из React Native Dimensions API
- **Сетевые данные** (если установлен @react-native-netinfo/netinfo)

## Конфигурация

### OmnisLoggerConfig

```typescript
interface OmnisLoggerConfig {
  endpoint: string;                    // URL API для отправки логов
  apiKey: string;                      // API ключ для авторизации
  environment?: 'development' | 'staging' | 'production'; // Окружение
  platform?: string;                  // Платформа (web, react-native)
  version?: string;                    // Версия приложения
  userId?: string;                     // ID пользователя
  sessionId?: string;                  // ID сессии
  enableConsole?: boolean;             // Логирование в консоль (по умолчанию: true)
  enableGlobalErrorHandlers?: boolean; // Перехват глобальных ошибок (по умолчанию: true)
  enableNetworkErrorCapture?: boolean; // Перехват сетевых ошибок (по умолчанию: true)
  maxRetries?: number;                 // Количество повторов (по умолчанию: 3)
  timeout?: number;                    // Таймаут запросов в мс (по умолчанию: 5000)
  deviceInfo?: DeviceInfo;             // Готовые данные об устройстве (для Web или кастомных данных)
  deviceInfoModule?: any;              // Модуль react-native-device-info (для React Native)
}
```

### DeviceInfo (упрощенный)

```typescript
interface DeviceInfo {
  // Общие поля
  platform?: string;
  os?: string;
  osVersion?: string;
  userAgent?: string;
  language?: string;
  timezone?: string;
  
  // Экран
  screenWidth?: number;
  screenHeight?: number;
  pixelRatio?: number;
  
  // React Native основные поля
  deviceId?: string;
  deviceName?: string;
  manufacturer?: string;
  brand?: string;
  model?: string;
  systemName?: string;
  systemVersion?: string;
  version?: string;
  isTablet?: boolean;
  isEmulator?: boolean;
  
  // Сетевые данные
  networkType?: string;
  isConnected?: boolean;
  
  // Дополнительные поля
  [key: string]: any;
}
```

## API

### Методы логирования

```javascript
logger.error('Сообщение об ошибке', context);
logger.warn('Предупреждение', context);
logger.info('Информация', context);
logger.debug('Отладочная информация', context);
logger.exception(error, context); // Для объектов Error
```

### Управление контекстом

```javascript
// Установка глобального контекста (будет добавлен ко всем логам)
logger.setGlobalContext({ 
  feature: 'auth',
  experiment: 'new-ui' 
});

// Получение текущего контекста
const context = logger.getGlobalContext();

// Очистка глобального контекста
logger.clearGlobalContext();
```

### Управление пользователем и сессией

```javascript
logger.setUser('new-user-id');
logger.setSession('new-session-id');
```

### Управление данными об устройстве

```javascript
// Установка новых данных об устройстве (для React Native)
logger.setDeviceInfo(newDeviceInfo);

// Обновление существующих данных
logger.updateDeviceInfo({ 
  customField: 'value',
  networkType: '5g' 
});

// Получение текущих данных
const deviceInfo = logger.getDeviceInfo();
```

### Принудительная отправка

```javascript
// Отправить все логи из очереди немедленно
await logger.flush();
```

## Автоматический перехват

### Сетевые ошибки

SDK автоматически перехватывает:
- HTTP ошибки (статус >= 400)
- Сетевые ошибки (нет соединения)
- Таймауты

Для **fetch** и **XMLHttpRequest** в браузере и React Native.

### Глобальные ошибки

SDK автоматически перехватывает:
- Необработанные исключения
- Unhandled Promise rejections
- JavaScript ошибки в React Native

## Примеры использования

### Базовое использование в React Native

```javascript
import { initOmnisLogger } from '@your-org/omnis-logger';
import DeviceInfo from 'react-native-device-info';

// App.js
const App = () => {
  useEffect(() => {
    const initializeLogger = async () => {
      const deviceInfo = {
        platform: 'react-native',
        deviceId: await DeviceInfo.getDeviceId(),
        deviceName: await DeviceInfo.getDeviceName(),
        manufacturer: await DeviceInfo.getManufacturer(),
        model: DeviceInfo.getModel(),
        systemName: DeviceInfo.getSystemName(),
        systemVersion: DeviceInfo.getSystemVersion(),
        version: DeviceInfo.getVersion(),
        isTablet: DeviceInfo.isTablet(),
        isEmulator: await DeviceInfo.isEmulator(),
      };

      const logger = initOmnisLogger({
        endpoint: 'https://api.example.com',
        apiKey: 'your-api-key',
        environment: __DEV__ ? 'development' : 'production',
        platform: 'react-native',
        version: '1.0.0',
        deviceInfo: deviceInfo
      });

      // Глобальный контекст
      logger.setGlobalContext({
        appVersion: '1.0.0',
        buildNumber: '123'
      });
    };

    initializeLogger();
  }, []);

  return <YourApp />;
};
```

### Использование в компонентах

```javascript
import { getOmnisLogger } from '@your-org/omnis-logger';

const ProfileScreen = () => {
  const logger = getOmnisLogger();

  const handleSaveProfile = async () => {
    try {
      await saveProfile();
      logger?.info('Профиль сохранен', { 
        screen: 'Profile',
        action: 'save' 
      });
    } catch (error) {
      logger?.exception(error, { 
        screen: 'Profile',
        action: 'save' 
      });
    }
  };

  return (
    // ваш UI
  );
};
```

## Формат данных лога

Каждый лог отправляется в следующем формате:

```javascript
{
  level: 'error' | 'warn' | 'info' | 'debug',
  message: 'Сообщение лога',
  stack?: 'Stack trace для ошибок',
  context: { /* пользовательский контекст */ },
  userAgent: 'User agent браузера',
  url: 'Текущий URL (для браузера)',
  userId: 'ID пользователя',
  sessionId: 'ID сессии',
  platform: 'Платформа',
  version: 'Версия приложения',
  environment: 'development|staging|production',
  deviceInfo: { /* данные об устройстве */ }
}
```