feat: append widget for show charts with currency (#39)

Author: EndyKaufman

mobile/package-lock.json

@@ -36,6 +36,7 @@
     "@trpc/client": "^10.45.2",
     "@trpc/server": "^10.45.2",
     "@zxing/browser": "^0.1.5",
+    "chart.js": "^4.5.1",
     "html5-qrcode": "^2.3.8",
     "ionicons": "^7.0.0",
     "jsqr": "^1.4.0",

mobile/package.json

@@ -178,7 +178,164 @@ interface CalendarWidgetOptions {
 }
 ```
 
+### Currency Charts Widget
 
+The Currency Charts Widget displays interactive financial charts for cryptocurrency and forex pairs using **real-time data from Yahoo Finance API** with Chart.js professional visualization.
+
+#### Widget Features:
+
+1. **Dual View System**:
+   - **Dashboard Panel**: Shows configurable number of charts (default: 3)
+   - **Modal View**: Displays all configured currency pairs in detail
+   - Click maximize button to view all charts
+
+2. **Multiple Currency Support**:
+   - **Cryptocurrency**: BTC/USD, ETH/USD, BNB/USD, ADA/USD, SOL/USD, XRP/USD, DOT/USD, DOGE/USD, AVAX/USD, MATIC/USD
+   - **Forex**: EUR/USD, GBP/USD, USD/JPY, USD/CAD, AUD/USD, USD/CHF, NZD/USD, USD/SGD
+   - Custom display names for each pair
+
+3. **Chart Features**:
+   - Professional Chart.js implementation
+   - Point styling with circular markers and white borders
+   - Green/red color coding based on price movement
+   - Interactive tooltips showing exact prices
+   - Smooth curved lines (tension: 0.4)
+   - Responsive design for all screen sizes
+
+4. **Real-time Data Features**:
+   - **Yahoo Finance API Integration**: Fetches live market data
+   - **Automatic Symbol Conversion**: Converts BTC/USD → BTC-USD, EUR/USD → EURUSD=X
+   - **30-second Updates**: Automatic periodic data refresh
+   - **Smart Fallback**: Uses mock data when API is unavailable
+   - **Error Handling**: Graceful degradation on API failures
+
+5. **Configuration Options**:
+   - Chart time periods: 1h, 4h, 1d, 1w, 1m
+   - Dashboard charts limit (1-6 charts)
+   - Volume bars toggle
+   - Custom widget name
+   - Individual pair display names
+
+#### Technical Implementation:
+
+##### Implementation Files:
+- `web/src/server/widgets/currency-widget.ts` - Main widget class with Zod schemas and Chart.js integration
+- `web/src/server/widgets/currency-widget.utils.ts` - Client-side utilities and window functions
+- `web/src/server/services/yahoo-finance-api.ts` - Yahoo Finance API service for real-time data
+
+##### Data Structure:
+```typescript
+interface CurrencyPair {
+  symbol: string;
+  name: string;
+  displayName?: string;
+}
+
+interface CurrencyWidgetOptions {
+  type: 'currency';
+  name: string;
+  currencyPairs: CurrencyPair[];
+  chartPeriod: '1h' | '4h' | '1d' | '1w' | '1m';
+  maxDashboardCharts: number;
+}
+```
+
+##### Main Functions:
+- `showCurrencyModal(modalId)` - Display detailed charts modal
+- `hideCurrencyModal(modalId)` - Hide charts modal
+- `updateCurrencyCharts(widgetId)` - Refresh chart data
+
+#### System Integration:
+
+The widget integrates with the general widget system and uses:
+- Chart.js v4.5.1 for professional chart rendering
+- Zod schemas for data validation
+- Formly for widget configuration form
+- Lucide Icons for UI elements
+- Tailwind CSS for styling
+- **Yahoo Finance API** for real-time market data
+- **Rate limiting**: 50 requests per minute per user/session
+- **Rate limiting implementation**: Uses sliding window algorithm with in-memory store
+- **Identification priority**: Session ID → x-session-id header → IP address → 'unknown'
+- **Error handling**: Returns TOO_MANY_REQUESTS TRPC error with retry information
+- **Automatic cleanup**: Expired rate limit entries cleaned up every minute
+- Periodic data updates (every 30 seconds)
+- Smart fallback to mock data on API failures
+- Point styling according to Chart.js official samples
+
+#### Widget Configuration Example:
+
+```json
+{
+  "type": "currency",
+  "name": "Market Overview",
+  "chartPeriod": "1d",
+  "maxDashboardCharts": 3,
+  "currencyPairs": [
+    {
+      "symbol": "BTC/USD",
+      "name": "Bitcoin to US Dollar",
+      "displayName": "Bitcoin Price"
+    },
+    {
+      "symbol": "ETH/USD", 
+      "name": "Ethereum to US Dollar",
+      "displayName": "Ethereum Price"
+    }
+  ]
+}
+```
+
+
+
+## Finance API
+
+The Finance API provides real-time financial data through TRPC endpoints with built-in rate limiting protection.
+
+### API Endpoints
+
+#### `finance.getCurrencyData`
+- **Purpose**: Fetch currency data for multiple symbols
+- **Input**: Array of symbols, period, optional interval
+- **Output**: Array of currency data with chart information
+- **Rate Limited**: Yes (50 requests/minute)
+
+#### `finance.getSingleCurrencyData`
+- **Purpose**: Fetch data for a single currency pair
+- **Input**: Symbol, period, optional interval
+- **Output**: Detailed currency data for one pair
+- **Rate Limited**: Yes (50 requests/minute)
+
+### Rate Limiting Details
+
+- **Algorithm**: Sliding window with 1-minute intervals
+- **Limit**: 50 requests per minute per user/session
+- **Identification**: Session ID → x-session-id header → IP address
+- **Error Response**: `TOO_MANY_REQUESTS` with retry time information
+- **Storage**: In-memory Map with automatic cleanup
+
+### Implementation Files
+
+- `web/src/server/trpc/routers/finance.ts` - Main finance router with rate limiting
+- `web/src/server/services/yahoo-finance-api.ts` - Yahoo Finance data fetching service
+- `web/src/server/middleware/rate-limit.ts` - Generic rate limiting utilities
+
+### Error Handling
+
+When rate limits are exceeded, clients receive:
+```json
+{
+  "code": "TOO_MANY_REQUESTS",
+  "message": "Rate limit exceeded. Maximum 50 requests per minute allowed. Try again in X seconds."
+}
+```
+
+### Best Practices
+
+1. Cache responses when possible to reduce API calls
+2. Implement exponential backoff for retry logic
+3. Monitor rate limit headers in responses
+4. Handle rate limit errors gracefully in client applications
 
 ## Widgets Development Roadmap
 

web/WIDGETS_DOCUMENTATION.md

@@ -184,7 +184,118 @@ interface CalendarWidgetOptions {
 }
 ```
 
+### Виджет графиков курсов валют (Currency Charts Widget)
 
+Виджет графиков курсов валют отображает интерактивные финансовые графики для криптовалютных и форекс пар с использованием **реальных данных из API Yahoo Finance**.
+
+#### Особенности виджета:
+
+1. **Двойная система отображения**:
+   - **Панель дашборда**: Показывает настраиваемое количество графиков (по умолчанию: 3)
+   - **Модальный просмотр**: Отображает все настроенные валютные пары детально
+   - Кнопка максимизации для просмотра всех графиков
+
+2. **Поддержка множества валют**:
+   - **Криптовалюты**: BTC/USD, ETH/USD, BNB/USD, ADA/USD, SOL/USD, XRP/USD, DOT/USD, DOGE/USD, AVAX/USD, MATIC/USD
+   - **Форекс**: EUR/USD, GBP/USD, USD/JPY, USD/CAD, AUD/USD, USD/CHF, NZD/USD, USD/SGD
+   - Пользовательские названия для каждой пары
+
+3. **Функции графиков**:
+   - Профессиональная реализация Chart.js
+   - Стилизация точек с круглыми маркерами и белыми границами
+   - Цветовое кодирование зеленый/красный в зависимости от движения цены
+   - Интерактивные подсказки с точными ценами
+   - Плавные изогнутые линии
+   - Адаптивный дизайн для всех размеров экранов
+
+4. **Реальные данные в реальном времени**:
+   - **Интеграция с API Yahoo Finance**: Получение актуальных рыночных данных
+   - **Автоматическое преобразование символов**: Конвертация BTC/USD → BTC-USD, EUR/USD → EURUSD=X
+   - **Обновление каждые 30 секунд**: Автоматическое периодическое обновление данных
+   - **Умный запасной вариант**: Использование имитационных данных при недоступности API
+   - **Обработка ошибок**: Гладкое восстановление при сбоях API
+
+5. **Параметры настройки**:
+   - Периоды графиков: 1ч, 4ч, 1д, 1н, 1м
+   - Лимит графиков на дашборде (1-6 графиков)
+   - Переключатель объемных баров
+   - Пользовательское имя виджета
+   - Индивидуальные названия пар
+
+#### Техническая реализация:
+
+##### Файлы реализации:
+- `web/src/server/widgets/currency-widget.ts` - Основной класс виджета с Zod схемами и интеграцией Chart.js
+- `web/src/server/widgets/currency-widget.utils.ts` - Вспомогательные утилиты на стороне клиента и функции окна
+- `web/src/server/services/yahoo-finance-api.ts` - Сервис API Yahoo Finance для получения данных в реальном времени
+
+#### Интеграция с системой:
+
+Виджет интегрирован с общей системой виджетов и использует:
+- Chart.js v4.5.1 для профессионального рендеринга графиков
+- Zod схемы для валидации данных
+- Formly для формы настройки виджета
+- Lucide Icons для элементов интерфейса
+- Tailwind CSS для стилизации
+- **API Yahoo Finance** для получения рыночных данных в реальном времени
+- **Ограничение частоты запросов**: 50 запросов в минуту на пользователя/сессию
+- **Реализация ограничения частоты**: Использует алгоритм скользящего окна с хранением в памяти
+- **Приоритет идентификации**: ID сессии → заголовок x-session-id → IP адрес → 'unknown'
+- **Обработка ошибок**: Возвращает ошибку TOO_MANY_REQUESTS TRPC с информацией о повторной попытке
+- **Автоматическая очистка**: Истекшие записи ограничения частоты очищаются каждую минуту
+- Периодические обновления данных (каждые 30 секунд)
+- Умный запасной вариант на имитационные данные при сбоях API
+- Стилизация точек согласно официальным примерам Chart.js
+
+
+## API Финансовых Данных
+
+API финансовых данных предоставляет информацию о курсах валют в реальном времени через TRPC эндпоинты со встроенной защитой от превышения частоты запросов.
+
+### Эндпоинты API
+
+#### `finance.getCurrencyData`
+- **Назначение**: Получение данных по нескольким валютным парам
+- **Входные данные**: Массив символов, период, опциональный интервал
+- **Выходные данные**: Массив данных о валютах с информацией для графиков
+- **Ограничение частоты**: Да (50 запросов/минуту)
+
+#### `finance.getSingleCurrencyData`
+- **Назначение**: Получение данных по одной валютной паре
+- **Входные данные**: Символ, период, опциональный интервал
+- **Выходные данные**: Подробные данные по одной паре
+- **Ограничение частоты**: Да (50 запросов/минуту)
+
+### Детали Ограничения Частоты Запросов
+
+- **Алгоритм**: Скользящее окно с интервалами по 1 минуте
+- **Лимит**: 50 запросов в минуту на пользователя/сессию
+- **Идентификация**: ID сессии → заголовок x-session-id → IP адрес
+- **Ответ при ошибке**: `TOO_MANY_REQUESTS` с информацией о времени повторной попытки
+- **Хранение**: Map в памяти с автоматической очисткой
+
+### Файлы Реализации
+
+- `web/src/server/trpc/routers/finance.ts` - Основной маршрутизатор финансов с ограничением частоты
+- `web/src/server/services/yahoo-finance-api.ts` - Сервис получения данных от Yahoo Finance
+- `web/src/server/middleware/rate-limit.ts` - Универсальные утилиты ограничения частоты
+
+### Обработка Ошибок
+
+При превышении лимита частоты запросов клиенты получают:
+```json
+{
+  "code": "TOO_MANY_REQUESTS",
+  "message": "Превышен лимит запросов. Максимум 50 запросов в минуту разрешено. Попробуйте снова через X секунд."
+}
+```
+
+### Рекомендации
+
+1. Кэшируйте ответы когда это возможно для уменьшения количества вызовов API
+2. Реализуйте экспоненциальную задержку для логики повторных попыток
+3. Отслеживайте заголовки ограничения частоты в ответах
+4. Корректно обрабатывайте ошибки ограничения частоты в клиентских приложениях
 
 ## План развития виджетов