szdl-utils-kit

Набор утилит для удобной работы с Bitrix24 REST API: пакетные запросы, обёртка над BX24, вспомогательные хелперы, логирование обращений и фоновый исполнитель.

Установка

npm install szdl-utils-kit

Быстрый старт

import {
	Batch,
	BxBoot,
	BxHelper,
	BxLogger,
	BackgroundWorker,
	tempus,
} from "szdl-utils-kit";

Модули

Batch

Утилита для пакетного выполнения запросов Bitrix24 с автоматической пагинацией, трекингом прогресса и обработкой ограничений. Желательно использовать только для Batch.stop, остальное выполнять через BxBoot, указанный под этим модулем

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" } } },
});

console.log(result.deals);
console.log(rest.errors); // ошибки по ключам

Основные свойства

• result – объект с результатами по ключам команд
• errors – словарь ошибок
• limit – текущий лимит команд в чанке (по умолчанию 50)
• canContinue – флаг выполнения
• skipList – методы, исключенные из дальнейшей пагинации

Методы

• batch(commandList, progressCall?, options?) – запрос данных
• batchTotalCount(commandList, progressCall?, options?) – запрос количества данных без подробного текста (Более быстрый, чем batch)
• stop() – принудительная остановка

BxBoot

Promise-обёртка над методами BX24 с продвинутой инициализацией, логированием и хелперами для работы с встройками.

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"] } },
});

Ключевые свойства

• 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

Набор мелких утилит для браузерного окружения.

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"),
});

Полезные методы:

• hash – геттер, возвращает случайный 8-символьный идентификатор; удобно для генерации ключей элементов
• createHash(length = 6) – позволяет задать длину хэша, полезно для кодов подтверждения и временных ссылок
• actionFilter({ keyTimer, duration = 10, action }) – debounce-обертка; гарантирует, что action запустится один раз после серии быстрых вызовов с одинаковым keyTimer
• noSleep() – предотвращает засыпание устройства, создавая и циклически воспроизводя скрытое видео
• downloadFileJson(data, filename) – сохраняет произвольные данные в filename.json, удобно для отладки и экспорта отчётов

BxLogger

Логер для записи истории REST-запросов в пользовательское хранилище Bitrix24 с последующей выгрузкой.

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() },
	});
}

Возможности:

• ведение истории запросов (start / stop);
• загрузка хранилища (getEntityList, downAllEntityJson);
• очистка устаревших записей.

BackgroundWorker

Координация фоновых задач между браузерными табами. Использует HL-подобное хранилище Bitrix24 для синхронизации и предотвращает одновременный запуск нескольких обработчиков.

import { BackgroundWorker } from "szdl-utils-kit";

const worker = new BackgroundWorker({
	bx, // готовый экземпляр BxBoot с инициализированными константами приложения
	appFunc: async () => {
		// здесь размещаем длительную задачу
		console.log("background job started");
	},
	users: [], // подготовленный список пользователей (опционально)
});
await worker.init();

Опции:

• bx – инициализированный экземпляр BxBoot, используемый для работы с REST;
• appFunc – функция, которая должна выполниться в «активном» табе;
• users – подготовленные данные (если не переданы, будут запрошены через REST);
• continueBackground – опциональная функция-условие ((worker) => boolean | Promise<boolean)), которая определяет, можно ли запускать воркер. Должна вернуть true, чтобы продолжить цикл. По умолчанию всегда возвращает true.

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;
	},
});

Методы:

• init – регистрирует бек-встройку для текущего пользователя, создаёт запись текущего таба и запускает цикл наблюдения.
• setBackgroundWorkerAll – массово настраивает встройку PAGE_BACKGROUND_WORKER: привязывает встройку 10 активным админам на портале, если какой-либо из админов уволен/не админ, перепривязывает его встройку на другого админа.

tempus

Функции для работы с датами и временем (библиотека tempusjs). Используется внутри пакета, но может быть импортирована напрямую:

import { tempus } from "szdl-utils-kit";

const formatted = tempus().format("%Y-%m-%d");

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.

Разработка и публикация

1. Вносите изменения в исходники.
2. Собирайте библиотеку npm run build (результат в dist/).
3. Авторизуйтесь в npm: npm login. Если требуется, запросите временный пароль на [email protected].
4. Публикуйте обновление: npm run pub. Скрипт автоматически увеличит версию (при необходимости можно указать вручную).