szdl-utils-kit 0.3.31 → 0.3.32

package/Readme.md

@@ -319,6 +319,33 @@ const worker = new BackgroundWorker({
 -   **`ensureAdminPlacements`** – для админа, обновляет фоновые встройки без запуска фонового цикла. `placement.unbind` и `placement.bind` выполняются одним `batch` (сначала отвязка, затем привязка), чтобы не оставлять портал без встройки между запросами.
 -   **`ensureAdminPlacementsBeforeAppInit`** – опция конструктора: перед `appFunc` у админа вызвать `ensureAdminPlacements`. Можно передать `true` или функцию-условие `(worker) => boolean`.
 
+### loadBx24 — подключение BX24 с фолбэками
+
+Библиотека BX24 подключается по цепочке: `//api.bitrix24.com/api/v1/` → `//api.bitrix24.tech/api/v1/` (по 3 секунды на каждый) → локальная копия, вшитая в utils-kit. Локальная копия лежит отдельным чанком и скачивается, только если оба удалённых источника не сработали.
+
+`BxBoot.init()` вызывает `loadBx24()` сам — тег `<script src="//api.bitrix24.com/api/v1/">` в HTML больше не нужен (если он остался, загрузчик увидит готовый `BX24` и ничего не будет грузить). Для кода, который работает с `BX24` без `BxBoot`:
+
+```ts
+import { loadBx24 } from "szdl-utils-kit";
+
+const { source } = await loadBx24(); // "preloaded" | "com" | "tech" | "local"
+BX24.init(() => { /* ... */ });
+```
+
+Если скрипт загрузился, но BX24 не инициализировался (приложение открыто вне фрейма Битрикс24), остальные источники не перебираются — промис отклоняется с `Bx24EnvironmentError`.
+
+Обновить локальную копию: `npm run update:bx24-local`.
+
+#### Старые приложения (без обновления utils-kit)
+
+`npm run build` дополнительно собирает самодостаточный файл `dist/legacy/bx24-loader.legacy.js` (та же логика + локальная копия BX24 внутри, без зависимостей). Положите его в статику приложения и замените им старый тег:
+
+```html
+<script src="bx24-loader.legacy.js"></script>
+```
+
+Загрузка асинхронная, поэтому до её завершения в `window.BX24` стоит заглушка, которая копит вызовы `BX24.init(cb)` и `BX24.install(cb)` и передаёт их настоящему BX24 после загрузки. Старый `BxBoot.init()` и inline-вызовы `BX24.init(...)` сразу после тега продолжают работать. Другие методы `BX24` до `init` вызывать нельзя. Промис загрузки доступен как `window.szdlBx24Ready`.
+
 ### tempus
 
 Функции для работы с датами и временем (библиотека [tempusjs](https://habr.com/ru/articles/204162/)). Используется внутри пакета, но может быть импортирована напрямую:
@@ -335,11 +362,12 @@ const formatted = tempus().format("%Y-%m-%d");
 
 -   `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`.
+-   `types/background-worker.d.ts` – в том числе `BackgroundWorkerTiming`, `DEFAULT_BACKGROUND_WORKER_TIMING`;
+-   `types/bx24-loader.d.ts` – `loadBx24`, `Bx24EnvironmentError`.
 
 ## Разработка и публикация
 
 1. Вносите изменения в исходники.
-2. Собирайте библиотеку `npm run build` (результат в `dist/`).
+2. Собирайте библиотеку `npm run build` (результат в `dist/`, legacy-загрузчик BX24 — в `dist/legacy/`).
 3. Авторизуйтесь в npm: `npm login`. Если требуется, запросите временный пароль на support@sozdavatel.ru.
 4. Публикуйте обновление: `npm run pub`. Скрипт автоматически увеличит версию (при необходимости можно указать вручную).