vv-iiko-pp-parser 1.0.6

package/README.md

@@ -0,0 +1,582 @@
+# vv-iiko-pp-parser
+
+🇺🇿 **Unofficial SDK for iiko Partner Portal API** — Node.js клиент для получения данных инвойсов из партнерского портала iiko.
+
+> ⚠️ **Важно:** Это частный пакет с ограниченным доступом. Для установки требуется авторизация в npm.
+
+## 📋 Что это?
+
+Этот пакет предоставляет простой API для работы с закрытым веб-интерфейсом [iiko Partner Portal](https://pp.iiko.uz), позволяя автоматизировать получение:
+
+- 📄 **Инвойсов** с детальной информацией
+- 🏢 **Данных компании** и профиля
+- 🔍 **Фильтрации** по различным критериям
+
+## 🚀 Установка
+
+### Авторизация в npm
+
+Перед установкой необходимо авторизоваться в npm:
+
+```bash
+npm login
+```
+
+### Установка пакета
+
+```bash
+npm install @mirzaev/vv-iiko-pp-parser
+```
+
+## ⚙️ Конфигурация
+
+Создайте `.env` файл с вашими учетными данными:
+
+```env
+IIKO_PP_LOGIN=your_username
+IIKO_PP_PASSWORD=your_password
+
+# Опционально: пользовательский путь для хранения cookies
+# По умолчанию используется: {projectRoot}/.vv-cookies
+# VV_IIKO_COOKIES_DIR=/custom/path/to/cookies
+```
+
+### 📂 Хранение cookies
+
+Cookies сохраняются автоматически после авторизации для переиспользования между запусками.
+
+**Расположение по умолчанию:** `.vv-cookies/` в корне вашего проекта
+
+**Пользовательский путь:**
+```typescript
+const parser = new IikoParser({
+    login: process.env.IIKO_PP_LOGIN,
+    password: process.env.IIKO_PP_PASSWORD,
+    cookiesPath: '/custom/path/iiko.cookies.json'  // Абсолютный путь к файлу
+});
+```
+
+Или через переменную окружения:
+```env
+VV_IIKO_COOKIES_DIR=/custom/path/to/cookies
+```
+
+## 🎯 Быстрый старт
+
+```typescript
+import { IikoParser } from '@mirzaev/vv-iiko-pp-parser';
+import 'dotenv/config';
+
+const parser = new IikoParser({
+    baseUrl: 'https://pp.iiko.uz',
+    language: 'en',
+    login: process.env.IIKO_PP_LOGIN,
+    password: process.env.IIKO_PP_PASSWORD
+});
+
+// Инициализация сессии
+await parser.ensureSession();
+
+// Получение всех инвойсов за январь 2026
+const invoices = await parser.getInvoices({
+    dateFrom: '2026-01-01',
+    dateTo: '2026-01-31'
+});
+
+console.log(`Найдено ${invoices.length} инвойсов`);
+```
+
+## 🔍 Фильтрация данных
+
+### По периоду времени
+
+Фильтрация по датам выполняется через параметры `dateFrom` и `dateTo` в формате `YYYY-MM-DD`:
+
+```typescript
+const invoices = await parser.getInvoices({
+    dateFrom: '2026-01-01',  // С какой даты
+    dateTo: '2026-01-31'     // До какой даты (включительно)
+});
+```
+
+> 📝 **Формат дат**: `YYYY-MM-DD` (например, `2026-01-15`)  
+> API iiko автоматически конвертирует в формат `dd.mm.yyyy`
+
+### Загрузка деталей из модального окна
+
+По умолчанию `items` и `subscriptions` остаются пустыми массивами. Чтобы загрузить детали из модальных окон, используйте флаг `withDetails`:
+
+```typescript
+const invoices = await parser.getInvoices({
+    withDetails: true  // 🔥 Загрузит items и subscriptions для каждого инвойса
+});
+
+// Теперь у каждого инвойса заполнены:
+console.log(invoices[0].items);         // [{ productName, price, quantity, discount, amount }]
+console.log(invoices[0].subscriptions); // [{ productName, quantity, price, amount }]
+```
+
+⚠️ **Важно**: Загрузка деталей выполняется последовательно для каждого инвойса, это может занять время при большом количестве инвойсов.
+
+### По tax_id компании
+
+> ⚠️ **Важно**: Используйте формат с пробелами как в системе!
+
+```typescript
+const invoices = await parser.getInvoices({
+    dateFrom: '2026-01-01',
+    dateTo: '2026-01-31',
+    searchBy: 'tax_id',
+    searchValue: '305 845 090'  // ← Формат с пробелами!
+});
+```
+
+### По номеру инвойса
+
+```typescript
+const invoice = await parser.getInvoices({
+    dateFrom: '2025-01-01',
+    dateTo: '2026-01-31',
+    searchBy: 'invoice_number',
+    searchValue: 'INV3816690'
+});
+```
+
+### По имени клиента
+
+```typescript
+const invoices = await parser.getInvoices({
+    dateFrom: '2025-01-01',
+    dateTo: '2026-01-31',
+    searchBy: 'client',
+    searchValue: 'KURANT'
+});
+```
+
+### По имени фирмы
+
+```typescript
+const invoices = await parser.getInvoices({
+    dateFrom: '2025-01-01',
+    dateTo: '2026-01-31',
+    searchBy: 'firm',
+    searchValue: 'VEDA VECTOR'
+});
+```
+
+## � Пагинация
+
+По умолчанию загружаются **все страницы** инвойсов автоматически.
+
+Вы можете управлять пагинацией:
+
+```typescript
+// Ограничить количество страниц
+const invoices = await parser.getInvoices({
+    pagination: {
+        maxPages: 2  // Загрузить только первые 2 страницы
+    }
+});
+```
+
+```typescript
+// Изменить размер страницы
+const invoices = await parser.getInvoices({
+    pagination: {
+        pageSize: 100,  // 100 инвойсов на страницу (по умолчанию: 50)
+        maxPages: 5     // Максимум 5 страниц
+    }
+});
+```
+
+```typescript
+// Без ограничений (поведение по умолчанию)
+const invoices = await parser.getInvoices();
+// Загрузит все страницы до пустой
+```
+
+⚠️ **Примечание:** Пагинация останавливается автоматически при достижении пустой страницы, даже если лимит `maxPages` не достигнут.
+
+## �📊 Структура данных
+
+### InvoiceData
+
+```typescript
+interface InvoiceData {
+    invoiceNumber: string;    // Номер инвойса (например: "INV3816690")
+    invoiceDate: string;      // Дата инвойса
+    dueDate: string;          // Срок оплаты
+    clientName: string;       // Название клиента
+    companyName: string;      // Название компании
+    taxId: string;            // Tax ID (только цифры)
+    status: string;           // Статус (Issued, Paid, Cancelled)
+    amount: number;           // Общая сумма (число)
+    detailsUrl: string;       // URL для загрузки деталей из модального окна
+    items: InvoiceItem[];     // Элементы инвойса (заполняются при withDetails: true)
+    subscriptions: Subscription[]; // Подписки (заполняются при withDetails: true)
+}
+```
+
+### InvoiceItem
+
+```typescript
+interface InvoiceItem {
+    productName: string;      // Название продукта
+    price: number;            // Цена
+    quantity: number;         // Количество
+    discount: number;         // Скидка (%)
+    amount: number;           // Сумма
+}
+```
+
+### Subscription
+
+```typescript
+interface Subscription {
+    productName: string;      // Название продукта
+    quantity: number;         // Количество
+    price: number;            // Цена
+    amount: number;           // Сумма
+}
+```
+
+### CompanyProfile
+
+```typescript
+interface CompanyProfile {
+    name: string;        // Название компании
+    phone: string;       // Телефон
+    email: string;       // Email
+    address: string;     // Адрес
+}
+```
+
+### ClientData
+
+```typescript
+interface ClientData {
+    uuid: string;             // UUID клиента (формат: XXX-XXX-XXX)
+    name: string;             // Название клиента
+    clientId: string;         // ID клиента в системе
+    iikoVersion?: string;     // Версия iiko (например: "9.2.6029")
+    email?: string;           // Email клиента
+    phone?: string;           // Телефон клиента
+    address?: string;         // Адрес клиента
+    legalEntity?: string;     // Юридическое лицо
+    tin?: string;             // ИНН (только цифры)
+}
+```
+
+### ClientsFilter
+
+```typescript
+interface ClientsFilter {
+    query?: string;           // Поиск по названию или UID
+    perPage?: number;         // Количество клиентов на странице (по умолчанию: 20)
+    maxPages?: number;        // Максимальное количество страниц (по умолчанию: все)
+}
+```
+
+### InvoicesFilter
+
+```typescript
+interface InvoicesFilter {
+    dateFrom?: string;   // Дата начала (YYYY-MM-DD)
+    dateTo?: string;     // Дата окончания (YYYY-MM-DD)
+    searchBy?: 'client' | 'firm' | 'tax_id' | 'invoice_number';
+    searchValue?: string; // Значение для поиска
+}
+```
+
+## 👥 Получение списка клиентов
+
+```typescript
+// Получить всех клиентов с полной информацией
+const allClients = await parser.getClients();
+
+console.log(`Найдено ${allClients.length} клиентов`);
+
+// Вывести информацию о первом клиенте
+const client = allClients[0];
+console.log({
+    name: client.name,
+    uuid: client.uuid,
+    iikoVersion: client.iikoVersion,
+    email: client.email,
+    phone: client.phone,
+    address: client.address,
+    legalEntity: client.legalEntity,
+    tin: client.tin
+});
+```
+
+### Фильтрация клиентов
+
+```typescript
+// Поиск по названию
+const restaurantClients = await parser.getClients({ 
+    query: 'Restaurant' 
+});
+
+// Поиск по UUID
+const specificClient = await parser.getClients({ 
+    query: '212-191-451' 
+});
+
+// Ограничение пагинации
+const firstPage = await parser.getClients({ 
+    perPage: 20,
+    maxPages: 1
+});
+
+// Загрузить больше клиентов за раз
+const manyClients = await parser.getClients({ 
+    perPage: 50,
+    maxPages: 5
+});
+```
+
+### Обработка данных клиентов
+
+```typescript
+const clients = await parser.getClients();
+
+// Фильтрация клиентов с email
+const clientsWithEmail = clients.filter(c => c.email);
+
+// Группировка по версии iiko
+const byVersion = clients.reduce((acc, client) => {
+    const version = client.iikoVersion || 'Unknown';
+    if (!acc[version]) acc[version] = [];
+    acc[version].push(client);
+    return acc;
+}, {});
+
+// Клиенты без ИНН
+const withoutTin = clients.filter(c => !c.tin);
+
+// Сохранение в файл
+import fs from 'fs';
+fs.writeFileSync('clients.json', JSON.stringify(clients, null, 2));
+```
+
+## 🏢 Получение профиля компании
+
+```typescript
+const profile = await parser.getCompanyProfile();
+console.log(profile);
+// {
+//   name: "VEDA VECTOR",
+//   phone: "+998901234567",
+//   email: "info@vedavector.uz", 
+//   address: ""
+// }
+```
+
+## 🔧 Продвинутые примеры
+
+### Обработка ошибок
+
+```typescript
+try {
+    await parser.ensureSession();
+    const invoices = await parser.getInvoices({
+        dateFrom: '2026-01-01',
+        dateTo: '2026-01-31'
+    });
+    
+    console.log(`✅ Получено ${invoices.length} инвойсов`);
+} catch (error) {
+    console.error('❌ Ошибка получения данных:', error.message);
+}
+```
+
+## 🔌 Интеграция с фреймворками
+
+### NestJS
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IikoParser } from 'vv-iiko-pp-parser';
+
+@Injectable()
+export class IikoService {
+    private parser: IikoParser;
+    
+    constructor() {
+        this.parser = new IikoParser({
+            baseUrl: 'https://pp.iiko.uz',
+            language: 'en',
+            login: process.env.IIKO_PP_LOGIN!,
+            password: process.env.IIKO_PP_PASSWORD!
+        });
+    }
+    
+    async getRecentInvoices() {
+        await this.parser.ensureSession();
+        return this.parser.getInvoices({
+            dateFrom: '2026-01-01',
+            dateTo: '2026-01-31'
+        });
+    }
+}
+```
+
+## 🚨 Важные замечания
+
+### Форматы tax_id
+
+Используйте **точно такой же формат**, как отображается в системе:
+
+```typescript
+// ✅ Правильно
+searchValue: '305 845 090'    // С пробелами
+searchValue: '302 987 179'    // С пробелами
+
+// ❌ Неправильно  
+searchValue: '305845090'      // Без пробелов
+searchValue: '302987179'      // Без пробелов
+```
+
+### Управление сессиями
+
+Пакет автоматически:
+- 🍪 Сохраняет cookies в файл
+- 🔄 Восстанавливает сессию при перезапуске
+- ✅ Проверяет валидность сессии
+- 🔐 Переавторизуется при необходимости
+
+## 📚 Примеры кода
+
+Полные рабочие примеры доступны в папке [`examples/`](./examples/):
+
+- [`basic.js`](./examples/basic.js) — Базовое использование
+- [`filtering.js`](./examples/filtering.js) — Примеры фильтрации
+- [`nestjs-service.ts`](./examples/nestjs-service.ts) — Интеграция с NestJS
+
+## 🛡️ TypeScript
+
+Пакет полностью типизирован и экспортирует все необходимые типы:
+
+```typescript
+import { 
+    IikoParser,
+    IikoParserOptions,
+    InvoicesFilter,
+    InvoiceData,
+    CompanyProfile 
+} from 'vv-iiko-pp-parser';
+```
+
+## 🐛 Устранение неполадок
+
+### Ошибки авторизации
+
+```bash
+❌ Ошибка: Invalid credentials
+```
+
+**Решение**: Проверьте правильность логина и пароля в `.env` файле.
+
+### Пустые результаты поиска
+
+```bash
+✅ Найдено 0 инвойсов
+```
+
+**Возможные причины**:
+- Неправильный формат `tax_id` (должен быть с пробелами)
+- Неправильный диапазон дат
+- Инвойсы отсутствуют за указанный период
+
+### Проблемы с сессиями
+
+```bash
+❌ Ошибка: Session expired
+```
+
+**Решение**: Пакет автоматически переавторизуется. Если проблема повторяется, очистите файл cookies:
+
+```bash
+rm -f .cookies.json
+```
+
+## � Progress Tracking
+
+Вы можете подписаться на события прогресса выполнения для отслеживания состояния парсера:
+
+```typescript
+const parser = new IikoParser({
+  baseUrl: 'https://pp.iiko.uz',
+  login: process.env.IIKO_PP_LOGIN,
+  password: process.env.IIKO_PP_PASSWORD,
+  onProgress: (event) => {
+    console.log(`[${event.stage}] ${event.message}`);
+    
+    if (event.current && event.total) {
+      const progress = Math.round((event.current / event.total) * 100);
+      console.log(`Progress: ${progress}% (${event.current}/${event.total})`);
+    }
+    
+    if (event.invoiceNumber) {
+      console.log(`Processing invoice: ${event.invoiceNumber}`);
+    }
+  }
+});
+```
+
+### События прогресса
+
+| Stage | Описание | Поля |
+|-------|----------|------|
+| `session` | Инициализация сессии | `message` |
+| `auth` | Процесс авторизации | `message` |
+| `fetch_invoices` | Загрузка страниц инвойсов | `message`, `current`, `total` |
+| `parse_invoices` | Парсинг HTML страниц | `message` |
+| `fetch_invoice_details` | Загрузка деталей инвойсов | `message`, `current`, `total`, `invoiceNumber` |
+| `fetch_clients` | Загрузка страниц со списком клиентов | `message`, `current`, `total` |
+| `parse_clients` | Парсинг списка клиентов | `message`, `current`, `total` |
+| `fetch_client_details` | Загрузка профилей клиентов | `message`, `current`, `total` |
+| `done` | Завершение работы | `message` |
+
+### Интеграция с WebSocket/SSE
+
+```typescript
+// В NestJS с WebSocket
+@WebSocketGateway()
+export class ProgressGateway {
+  constructor(private parser: IikoParser) {
+    this.parser = new IikoParser({
+      // ... config
+      onProgress: (event) => {
+        this.server.emit('parser-progress', event);
+      }
+    });
+  }
+}
+
+// В Express с SSE
+app.get('/parse-progress', (req, res) => {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+  });
+
+  const parser = new IikoParser({
+    // ... config
+    onProgress: (event) => {
+      res.write(`data: ${JSON.stringify(event)}\n\n`);
+    }
+  });
+  
+  // Start parsing...
+});
+```
+
+## 📝 Лицензия
+
+UNLICENSED
+
+## ⚠️ Disclaimer
+
+Это неофициальный пакет. Используйте в соответствии с условиями использования iiko Partner Portal.

package/dist/clients/clients.fetcher.d.ts

@@ -0,0 +1,102 @@
+import { IikoSessionService } from '../core/session/iiko-session.service';
+import { ClientsFetchParams } from './clients.types';
+/**
+ * Сервис для загрузки HTML страниц клиентов из iiko Partner Portal.
+ *
+ * Выполняет HTTP GET запросы к endpoints:
+ * - AJAX endpoint для получения списка клиентов
+ * - Страница профиля клиента для получения деталей
+ *
+ * Использует авторизованный HTTP клиент с cookies из IikoSessionService.
+ */
+export declare class ClientsFetcher {
+    private readonly sessionService;
+    private readonly clientsListEndpoint;
+    private readonly clientAreaEndpoint;
+    private readonly cloudAllocationEndpoint;
+    private readonly saasAllocationEndpoint;
+    constructor(sessionService: IikoSessionService);
+    /**
+     * Выполняет HTTP GET запрос к AJAX endpoint для получения списка клиентов.
+     *
+     * Endpoint: GET /en/cabinet/ajax/clients-list.html
+     *
+     * Параметры запроса:
+     * - query: поисковая строка (фильтрует клиентов по имени или UID на сервере)
+     * - perPage: количество клиентов на странице (по умолчанию: 10)
+     * - page: номер страницы (по умолчанию: 1)
+     *
+     * Возвращаемый HTML содержит:
+     * - Полную HTML страницу с <div id="clientsTable_ajax"> (первый запрос)
+     * - ИЛИ только <tbody class="ajax"> фрагмент (последующие AJAX запросы)
+     *
+     * Предусловия:
+     * - Сессия должна быть инициализирована через sessionService.ensureSession()
+     * - HTTP клиент уже содержит валидные cookies
+     *
+     * @param params Опциональные параметры запроса (query, perPage, page)
+     * @returns Promise с HTML строкой со списком клиентов
+     * @throws Error если запрос вернул ошибку или невалидный ответ
+     */
+    fetchClientsHtml(params?: ClientsFetchParams): Promise<string>;
+    /**
+     * Загружает HTML страницу профиля конкретного клиента.
+     *
+     * Endpoint: GET /en/cabinet/client-area/index.html?clientId=XXX
+     *
+     * Возвращаемый HTML содержит:
+     * - UUID клиента (в кнопке "UID: XXX-XXX-XXX")
+     * - Версию iiko (в кнопке "Version iiko: X.X.XXXX")
+     * - Контактную информацию (email, phone в таблице)
+     * - Юридические данные (Legal entity и Company tax id в таблице)
+     * - Информацию о лицензиях и хостинге
+     *
+     * Предусловия:
+     * - Сессия должна быть инициализирована
+     * - Пользователь должен иметь доступ к данному clientId
+     *
+     * @param clientId ID клиента (целочисленный идентификатор)
+     * @returns Promise с HTML строкой страницы профиля клиента
+     * @throws Error если запрос вернул ошибку или клиент не найден
+     */
+    fetchClientProfile(clientId: string): Promise<string>;
+    /**
+     * Загружает HTML страницу Cloud license allocation для chain.
+     *
+     * Endpoint: GET /en/cabinet/client-area/licenses/cloud-mapping.html?clientId=XXX
+     *
+     * Эта страница содержит таблицу "Store of the chain" с членами chain и их Cloud лицензиями.
+     * Каждая строка таблицы содержит:
+     * - Имя клиента (ссылка на client-area)
+     * - Input поле с количеством выделенных Cloud лицензий
+     *
+     * Предусловия:
+     * - Сессия должна быть инициализирована
+     * - clientId должен быть Chain (иметь Cloud license allocation)
+     *
+     * @param clientId ID chain для загрузки allocation
+     * @returns Promise с HTML строкой страницы cloud allocation
+     * @throws Error если запрос вернул ошибку или клиент не chain
+     */
+    fetchCloudAllocationHtml(clientId: string): Promise<string>;
+    /**
+     * Загружает HTML страницу SaaS license allocation для chain.
+     *
+     * Endpoint: GET /en/cabinet/client-area/licenses/saas-mapping.html?clientId=XXX
+     *
+     * Эта страница содержит таблицу "Store of the chain" с членами chain и их SaaS лицензиями.
+     * Каждая строка таблицы содержит:
+     * - Имя клиента (ссылка на client-area)
+     * - Input поле с количеством выделенных SaaS лицензий
+     *
+     * Предусловия:
+     * - Сессия должна быть инициализирована
+     * - clientId должен быть Chain (иметь SaaS license allocation)
+     *
+     * @param clientId ID chain для загрузки allocation
+     * @returns Promise с HTML строкой страницы saas allocation
+     * @throws Error если запрос вернул ошибку или клиент не chain
+     */
+    fetchSaasAllocationHtml(clientId: string): Promise<string>;
+}
+//# sourceMappingURL=clients.fetcher.d.ts.map

package/dist/clients/clients.fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.fetcher.d.ts","sourceRoot":"","sources":["../../src/clients/clients.fetcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,cAAc;IAL3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAwC;IAC5E,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwC;IAC3E,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAyD;IACjG,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAwD;gBAElE,cAAc,EAAE,kBAAkB;IAE/D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IA2CpE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB3D;;;;;;;;;;;;;;;;;OAiBG;IACG,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyBjE;;;;;;;;;;;;;;;;;OAiBG;IACG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAwBjE"}