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 с автоматической пагинацией, трекингом прогресса и обработкой ограничений. Рекомендуется работать через BxBoot, а Batch использовать напрямую только при необходимости.

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

const rest = new Batch({
	callBatch: BX24.callBatch,
	callMethod: BX24.callMethod,
});
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); // ошибки по ключам
console.log(rest.timeLimit); // { limit: boolean, date?: string }

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

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

Методы

• batch(commandList, progressCall?) – запрос данных
• batchTotalCount(commandList, progressCall?) – запрос количества данных без подробного текста (более быстрый, чем batch)
• call({ method, params? }) – одиночный REST-вызов с теми же retry/timeout правилами, что и batch
• stop() – принудительная остановка

BxBoot

Promise-обёртка над методами BX24 с продвинутой инициализацией, логированием и хелперами для работы с встройками. Фоновые встройки PAGE_BACKGROUND_WORKER обрабатываются только через BackgroundWorker и в placementBind/placementUnBind/placementCheck пропускаются.

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
  • updateList – массив описаний изменений для логера (method, name, list[{ id, fields }]), отображается в истории операций
• batchTotalCount(commandList, progressCall?, options?) – подсчет элементов в пакетном режиме
• timeLimit – глобальный статус лимита выполнения ({ limit, date }), можно напрямую читать в компонентах (например, в лоадере)
• placementBind(place, userId?), placementUnBind(...), placementCheck() – работа с встройками (кроме PAGE_BACKGROUND_WORKER, их ведёт BackgroundWorker)
• 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 – опциональная функция-условие, которая определяет, можно ли запускать воркер. Должна вернуть true, чтобы продолжить цикл. По умолчанию всегда возвращает true; см. пример ниже.
• timing – объект с таймингами poll-цикла, подтверждения лидерства и разнесённого старта приложений (см. Тайминги). Можно передать только нужные поля — остальные возьмутся из DEFAULT_BACKGROUND_WORKER_TIMING;
• coordinationScope – область координации лидера и пула вкладок (см. Область координации). По умолчанию 'user'.

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

Область координации (coordinationScope)

Передаётся строкой: 'user' или 'portal'. Другие значения игнорируются с предупреждением в консоль, используется 'user'.

| Значение | Поведение | |----------|-----------| | 'user' (по умолчанию) | Один запуск appFunc одновременно на пользователя. Вкладки разных пользователей не конкурируют. | | 'portal' | Один запуск appFunc одновременно на портал. Все пользователи в общем пуле вкладок; лидер один на всё приложение. |

Как это работает:

• В режиме 'user' записи в entity хранятся с NAME = userId, Web Lock тоже per-user.
• В режиме 'portal' все вкладки пишутся с общим ключом NAME = {appCodeName}:portal, Web Lock — per-portal (per-app).
• В данных вкладки всегда сохраняется userId — в portal-режиме видно, у кого открыта вкладка, хотя appFunc выполняется только у лидера.
• setBackgroundWorkerAll в portal-режиме привязывает только общую встройку PAGE_BACKGROUND_WORKER и отвязывает персональные (USER_ID=…).

const worker = new BackgroundWorker({
	bx,
	appFunc: async () => {
		console.log("background job started (once per portal)");
	},
	coordinationScope: "portal",
});
await worker.init();

Тайминги (timing)

Экспортируются DEFAULT_BACKGROUND_WORKER_TIMING и resolveBackgroundWorkerTiming — удобно собирать конфиг заранее или переопределять отдельные поля.

import {
	BackgroundWorker,
	DEFAULT_BACKGROUND_WORKER_TIMING,
	resolveBackgroundWorkerTiming,
} from "szdl-utils-kit";

const timing = resolveBackgroundWorkerTiming({
	startDelayMs: 10_000,
	leaderConfirmDelayMs: 10_000,
});

const worker = new BackgroundWorker({ bx, appFunc, timing });

Поля объекта timing:

| Поле | По умолчанию | Назначение | |------|--------------|------------| | startDelayMs | 0 | Пауза перед первым poll-тиком. Разносит старт разных приложений (один апп — через 20 с, другой — через 4–5 мин). | | pollIntervalMs | 60_000 | Базовый интервал фонового poll-цикла (обновление lastActive, выбор лидера, очистка мёртвых вкладок). | | pollIntervalJitterMs | 30_000 | Случайная добавка к pollIntervalMs. Итоговый интервал: от pollIntervalMs до pollIntervalMs + pollIntervalJitterMs (по умолчанию 1–1,5 мин). | | leaderConfirmDelayMs | 60_000 | Пауза после захвата Web Lock перед повторной проверкой лидерства и вызовом appFunc. Защита от гонки между вкладками. | | activeMaxPauseMs | 180_000 | Порог «мёртвой» вкладки: если lastActive не обновлялся дольше — запись удаляется из entity. Должен быть больше startDelayMs + leaderConfirmDelayMs, иначе вкладка может удалиться во время пауз перед стартом. | | quickCleanupThresholdMs | 300_000 | Отдельный порог для агрессивной очистки, когда достигнут лимит вкладок (maxTabs). | | leaderHeartbeatMs | null | Интервал обновления lastActive лидером во время appFunc. Если не задан — вычисляется автоматически из pollInterval и activeMaxPauseMs. |

Как устроен старт (без лишних раундов):

1. Регистрация вкладки в entity.
2. Пауза startDelayMs (если задана).
3. Poll-тик: выбор лидера по entity (самая старая вкладка).
4. Если текущая вкладка — лидер: захват Web Lock → пауза leaderConfirmDelayMs → повторная проверка лидера → appFunc.
5. Далее poll-цикл продолжается с интервалом pollIntervalMs … + pollIntervalJitterMs.

Пример: старт через ~20 секунд

const START_DELAY_MS = 10_000;
const LEADER_CONFIRM_MS = 10_000;

const worker = new BackgroundWorker({
	bx,
	appFunc: async () => {
		console.log("background job started");
	},
	timing: {
		...DEFAULT_BACKGROUND_WORKER_TIMING,
		startDelayMs: START_DELAY_MS,
		leaderConfirmDelayMs: LEADER_CONFIRM_MS,
		activeMaxPauseMs: Math.max(
			60_000,
			(START_DELAY_MS + LEADER_CONFIRM_MS) * 3,
		),
	},
});

Пример: отложенный старт (~4–5 минут)

const worker = new BackgroundWorker({
	bx,
	appFunc: async () => {
		/* ... */
	},
	timing: {
		...DEFAULT_BACKGROUND_WORKER_TIMING,
		startDelayMs: 4 * 60_000,
		leaderConfirmDelayMs: 60_000,
	},
});

Методы:

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

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 – в том числе BackgroundWorkerTiming, DEFAULT_BACKGROUND_WORKER_TIMING.

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

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