szdl-utils-kit 0.2.30 → 0.3.5

package/Readme.md

@@ -1,168 +1,234 @@
-## ***UTILS-KIT***
-### **Подключение и использование**
-```sh
-npm i szdl-utils-kit
+# szdl-utils-kit
+
+Набор утилит для удобной работы с Bitrix24 REST API: пакетные запросы, обёртка над BX24, вспомогательные хелперы, логирование обращений и фоновый исполнитель.
+
+## Установка
+
+```bash
+npm install szdl-utils-kit
 ```
-```JavaScript
-import { Batch, BxBoot, tempus } from 'szdl-utils-kit';
+
+## Быстрый старт
+
+```ts
+import {
+	Batch,
+	BxBoot,
+	BxHelper,
+	BxLogger,
+	BackgroundWorker,
+	tempus,
+} from "szdl-utils-kit";
 ```
 
-### ***{ Batch }***
-Утилита пакетного запроса данных из B24
+## Модули
+
+### Batch
+
+Утилита для пакетного выполнения запросов Bitrix24 с автоматической пагинацией, трекингом прогресса и обработкой ограничений.
+Желательно использовать только для Batch.stop, остальное выполнять через BxBoot, указанный под этим модулем
 
-```JavaScript
-import { Batch } from 'szdl-utils-kit';
+```ts
+import { Batch } from "szdl-utils-kit";
 
 const rest = new Batch(BX24.callBatch);
-```
+const result = await rest.batch({
+	deals: { method: "crm.deal.list", params: { select: ["ID", "TITLE"] } },
+	users: { method: "user.get", params: { filter: { ACTIVE: "Y" } } },
+});
 
-#### **Свойства**
-<b><i>serial</i></b> - флаг режима передачи <br>
-
-#### **Методы**
-<b><i>setSerial()</i></b> - установка последовательного режима <br>
-<b><i>setParallel()</i></b> - установка параллельного режима <br>
-<b><i>stop()</i></b> - принудительно остановить выгрузку данных <br>
-<b><i>batch(commandList, progressCall)</i></b> - запрос данных <br>
-<b><i>batchTotalCount(commandList, progressCall)</i></b> - запрос количества элементов по сущностям <br>
-
-
-### ***{ BxBoot }***
-Утилита Promise-обертка над некоторыми методами BX24.
-
-#### **Свойства**
-<b><i>domain</i></b> - доменное имя портала <br>
-<b><i>isAdmin</i></b> - флаг проверки текущего пользователя на админа <br>
-
-<b><i>appInfo</i></b> - Информация о приложении
-```TypeScript
-type appInfo = {
-		ID: number,
-		CODE: string,
-		VERSION: number,
-		STATUS: string,
-		INSTALLED: boolean,
-		PAYMENT_EXPIRED: string,
-		DAYS: null | number,
-		LANGUAGE_ID: string,
-		LICENSE: string,
-		LICENSE_TYPE: string,
-		LICENSE_FAMILY: string
-	};
-```
-<b><i>appConst</i></b> - Параметры приложения
-```TypeScript
-type appConst = {
-		appName: string,
-		appNameEng: string,
-		pathApp: string,
-		zip: string,
-		chatBotLogo: string,
-		entity: { key: string, name: string }[],
-	};
-```
-<b><i>userInfo</i></b> - Информация о текущем пользователе
-<b><i>placeData</i></b> - Информация о встройках
-
-<b><i>placeInfo</i></b> - Информация о текущем месте встройки
-```TypeScript
-type placeInfo = {
-		placement: string;
-		options: Record<string, string>;
-	};
+console.log(result.deals);
+console.log(rest.errors); // ошибки по ключам
 ```
 
-#### **Методы**
-<b><i>init()</i></b> - Метод инициализации библиотеки rest api BX24
-```TypeScript
-init(): Promise<boolean>;
+**Основные свойства**
+
+-   `result` – объект с результатами по ключам команд
+-   `errors` – словарь ошибок
+-   `limit` – текущий лимит команд в чанке (по умолчанию 50)
+-   `canContinue` – флаг выполнения
+-   `skipList` – методы, исключенные из дальнейшей пагинации
+
+**Методы**
+
+-   `batch(commandList, progressCall?, options?)` – запрос данных
+-   `batchTotalCount(commandList, progressCall?, options?)` – запрос количества данных без подробного текста (Более быстрый, чем batch)
+-   `stop()` – принудительная остановка
+
+### BxBoot
+
+Promise-обёртка над методами BX24 с продвинутой инициализацией, логированием и хелперами для работы с встройками.
+
+```ts
+import { BxBoot } from "szdl-utils-kit";
+
+const bx = new BxBoot({
+	appName: "My App",
+	pathApp: "https://example.com/app",
+});
+
+await bx.init();
+
+const currentUser = await bx.call({ method: "user.current" });
+const deals = await bx.batch({
+	deals: { method: "crm.deal.list", params: { select: ["ID", "TITLE"] } },
+});
 ```
 
-<b><i>userOption(key, ?value)</i></b> - Получение\изменение опций юзера.
- * Если передан 'key', то возвращает опцию по ключу. <br>
- * Если передан 'key' и 'value', то функция изменяет ключ по переданному значению.
-```TypeScript
-userOption(key: string, value?: string | number)
+**Ключевые свойства**
+
+-   `domain` – доменное имя портала, например `example.bitrix24.ru`
+-   `isAdmin` – флаг администратора текущего пользователя; используется для условных сценариев и проверок прав
+-   `appInfo` – объект из REST-метода `App.info` с идентификатором приложения, типом запуска, тарифами и статусами подписки
+-   `userInfo` – данные, полученные из `user.current` (`ID`, `NAME`, `EMAIL`, `TIME_ZONE` и др.)
+-   `placeData` – исходные данные встроек, возвращаемые `BX24.getPlacement()`, включая `placement`, `placementId`, `options`
+-   `placeInfo` – результат REST-метода `placement.get`, расширяет `placeData` подробностями о привязках и доступных действиях
+-   `logger` – экземпляр `BxLogger` (при активном логировании) или `BxLoggerStub`; независимо от режима доступны методы `info`, `warn`, `error`
+
+**Основные методы**
+
+-   `init()` – инициализация SDK, получение основных данных
+-   `userOption(key, value?)` – чтение/запись пользовательских настроек
+-   `appOption(key, value?)` – чтение/запись пользовательских настроек
+-   `call({ method, params, updateList })` – одиночный REST-вызов
+-   `batch(commandList, progressCall?, options?)` – пакетные вызовы с обновлениями/логом
+    -   `errorCall(errors)` – вызывается после выполнения всего батча, получает объект с ключами запросов и списком ошибок Bitrix24
+    -   `limitCall(method)` – вызывается при превышении лимитов
+    -   `updateList` – массив описаний изменений для логера (`method`, `name`, `list[{ id, fields }]`), отображается в истории операций
+    -   `limitCommandSerial` – устаревший флаг последовательной отправки; сохранен для обратной совместимости, фактически игнорируется
+-   `batchTotalCount(commandList, progressCall?, options?)` – подсчет элементов в пакетном режиме
+    -   `errorCall(errors)` – вызывается после выполнения всего батча, получает объект с ключами запросов и списком ошибок Bitrix24
+    -   `limitCall(method)` – вызывается при превышении лимитов
+    -   `updateList` – массив описаний изменений для логера (`method`, `name`, `list[{ id, fields }]`), отображается в истории операций
+-   `placementBind(place, userId?)`, `placementUnBind(...)`, `placementCheck()` – работа с встройками
+-   `getBotList()`, `regBot()`, `unRegBot()` – управление чат-ботом
+
+### BxHelper
+
+Набор мелких утилит для браузерного окружения.
+
+```ts
+import { BxHelper } from "szdl-utils-kit";
+
+const helper = new BxHelper();
+const hash = helper.hash; // случайный 8-символьный хэш
+
+helper.actionFilter({
+	keyTimer: "submit",
+	duration: 300,
+	action: () => console.log("debounced action"),
+});
 ```
 
-<b><i>call({ method, params })</i></b> - Вызывает указанный метод REST-сервиса с указанными параметрам
-```TypeScript
-call({ method, params }: TCommand): Promise<unknown[] | boolean>;
-type TCommand = {
-	method: string,
-	params: Record<string, unknown> | {
-		select?: string[],
-		filter?: Record<string, string | string[]>,
-	} | {
-		id?: string,
-		params?: Record<string, string>,
-		fields?: Record<string, unknown>,
-	}
+Полезные методы:
+
+-   `hash` – геттер, возвращает случайный 8-символьный идентификатор; удобно для генерации ключей элементов
+-   `createHash(length = 6)` – позволяет задать длину хэша, полезно для кодов подтверждения и временных ссылок
+-   `actionFilter({ keyTimer, duration = 10, action })` – debounce-обертка; гарантирует, что `action` запустится один раз после серии быстрых вызовов с одинаковым `keyTimer`
+-   `noSleep()` – предотвращает засыпание устройства, создавая и циклически воспроизводя скрытое видео
+-   `downloadFileJson(data, filename)` – сохраняет произвольные данные в `filename.json`, удобно для отладки и экспорта отчётов
+
+### BxLogger
+
+Логер для записи истории REST-запросов в пользовательское хранилище Bitrix24 с последующей выгрузкой.
+
+```ts
+import { BxLogger } from "szdl-utils-kit";
+
+const logger = new BxLogger();
+await logger.init();
+
+const key = logger.start({
+	type: "call",
+	data: { method: "crm.deal.list", params: {} },
+});
+
+try {
+	// ... выполняем запрос
+	await logger.stop({ key, status: "success" });
+} catch (error) {
+	await logger.stop({
+		key,
+		status: "fail",
+		errorList: { 0: error.toString() },
+	});
 }
 ```
 
-<b><i>batch(commandList, ?progressCall)</i></b> - Пакетный запрос данных
- * commandList - лист команд можно передавать как в виде объекта, так и в виде массива команд
- * progressCall - принимает callback в который передается статус загрузки данных в процентах
-```TypeScript
-batch(
-		commandList: Record<string, TCommand>,
-		progressCall?: (data:{ percent: number })=>void
-	): Promise<Record<string, unknown[]> | boolean>;
-```
+Возможности:
 
-<b><i>batchTotalCount(commandList, ?progressCall)</i></b> - Пакетный запрос количества элементов по запрошенным сущностям
- * commandList - лист команд можно передавать как в виде объекта, так и в виде массива команд
- * progressCall - принимает callback в который передается статус загрузки данных в процентах
-```TypeScript
-batchTotalCount(
-		commandList: Record<string, TCommand>,
-		progressCall?: (data:{ percent: number })=>void
-	): Promise<Record<string, number> | boolean>;
-```
+-   ведение истории запросов (`start` / `stop`);
+-   загрузка хранилища (`getEntityList`, `downAllEntityJson`);
+-   очистка устаревших записей.
 
-<b><i>getPlacement()</i></b> - Запрос данных о местах встройки приложения
-```TypeScript
-getPlacement(): Promise<unknown[] | boolean>;
-```
+### BackgroundWorker
 
-<b><i>placementBind(place)</i></b> - Встройка приложения в place
- * place - индификатор места встройки
-```TypeScript
-placementBind(place: string): void;
-```
+Координация фоновых задач между браузерными табами. Использует HL-подобное хранилище Bitrix24 для синхронизации и предотвращает одновременный запуск нескольких обработчиков.
 
-<b><i>placementUnBind(place)</i></b> - Отвязка встройки из place
- * place - индификатор места встройки
-```TypeScript
-placementUnBind(place: string): Promise<boolean>;
-```
+```ts
+import { BackgroundWorker } from "szdl-utils-kit";
 
-<b><i>getBotList()</i></b> - Получение списка чат-ботов
-```TypeScript
-getBotList(): Promise<unknown[] | boolean>;
+const worker = new BackgroundWorker({
+	bx, // готовый экземпляр BxBoot с инициализированными константами приложения
+	appFunc: async () => {
+		// здесь размещаем длительную задачу
+		console.log("background job started");
+	},
+	users: [], // подготовленный список пользователей (опционально)
+});
+await worker.init();
 ```
 
-<b><i>regBot({ code, type, name })</i></b> - Регистрация чат-бота
- * code - Строковой идентификатор бота, уникальный в рамках вашего приложения
- * type - Тип бота, B - чат-бот, ответы поступают сразу, H - человек, ответы поступают с задержкой от 2-х до 10 секунд, O - чат-бот для Открытых линий, S - чат-бот с повышенными привилегиями (supervisor)
- * name - Имя чат-бота
-```TypeScript
-regBot({ code, type, name }:{
-		code: string, type: string, name: string
-	}): Promise<unknown | boolean>;
+Опции:
+
+-   `bx` – инициализированный экземпляр `BxBoot`, используемый для работы с REST;
+-   `appFunc` – функция, которая должна выполниться в «активном» табе;
+-   `users` – подготовленные данные (если не переданы, будут запрошены через REST);
+-   `continueBackground` – опциональная функция-условие (`(worker) => boolean | Promise<boolean)`), которая определяет, можно ли запускать воркер. Должна вернуть `true`, чтобы продолжить цикл. По умолчанию всегда возвращает `true`.
+
+```ts
+const worker = new BackgroundWorker({
+	bx,
+	appFunc: async () => {
+		/* ... */
+	},
+	continueBackground: async (worker) => {
+		const lastCheck = BX24.userOption.get("checkDate");
+		if (!lastCheck) return false;
+		const nextCheck = new Date(lastCheck).setMinutes(
+			new Date(lastCheck).getMinutes() + 30
+		);
+		return Date.now() >= nextCheck;
+	},
+});
 ```
 
-<b><i>unRegBot(id)</i></b> - Удаление чат-бота
-```TypeScript
-unRegBot(id: number|string): Promise<unknown | boolean>;
+Методы:
+
+-   **`init`** – регистрирует бек-встройку для текущего пользователя, создаёт запись текущего таба и запускает цикл наблюдения.
+-   **`setBackgroundWorkerAll`** – массово настраивает встройку `PAGE_BACKGROUND_WORKER`: привязывает встройку 10 активным админам на портале, если какой-либо из админов уволен/не админ, перепривязывает его встройку на другого админа.
+
+### tempus
+
+Функции для работы с датами и временем (библиотека [tempusjs](https://habr.com/ru/articles/204162/)). Используется внутри пакета, но может быть импортирована напрямую:
+
+```ts
+import { tempus } from "szdl-utils-kit";
+
+const formatted = tempus().format("%Y-%m-%d");
 ```
 
-### ***{ tempus }***
-Утилита для работы с датами и временем, [документация](https://habr.com/ru/articles/204162/)
+## TypeScript
+
+Все основные API описаны в папке `types/`. Импорты доступны напрямую из пакета, при необходимости можно посмотреть определения:
+
+-   `types/batch.d.ts` – детальное описание Batch;
+-   `types/bx-boot.d.ts`, `types/bx-helper.d.ts`, `types/bx-logger.d.ts`;
+-   `types/background-worker.d.ts`.
+
+## Разработка и публикация
 
-### **Инструкция по обновлению npm-пакета**
-- вносим изменения в проект
-- собираем библиотеку в папке dist `npm run build`
-- с помощью `npm login` заходим в аккаунт (вводим логин/пароль, затем получаем временный пароль на почту support@sozdavatel.ru, и вводим его)
-- публикуем библиотеку `npm run pub` (счётчик версии автоматически увеличится, можно указать вручную)
+1. Вносите изменения в исходники.
+2. Собирайте библиотеку `npm run build` (результат в `dist/`).
+3. Авторизуйтесь в npm: `npm login`. Если требуется, запросите временный пароль на support@sozdavatel.ru.
+4. Публикуйте обновление: `npm run pub`. Скрипт автоматически увеличит версию (при необходимости можно указать вручную).