@andrey4emk/npm-app-front-b24 0.2.0 → 0.4.0

package/ConfigLogs.vue

@@ -1,6 +1,6 @@
 <template>
     <div class="config-logs">
-        <h2>Уровни логирования</h2>
+        <h2 class="config-logs__title">Уровни логирования</h2>
 
         <div v-if="loading" class="config-logs__loading">Загрузка...</div>
 
@@ -47,10 +47,10 @@
             </table>
 
             <div class="config-logs__actions">
-                <button @click="saveConfig" :disabled="saving">
+                <button @click="saveConfig" :disabled="loading || saving">
                     {{ saving ? "Сохранение..." : "Сохранить" }}
                 </button>
-                <button @click="loadConfig" :disabled="loading">Обновить</button>
+                <button @click="loadConfig" :disabled="loading || saving">Обновить</button>
             </div>
 
             <div v-if="message" :class="['config-logs__message', messageType === 'ok' ? 'config-logs__message--success' : 'config-logs__message--error']">
@@ -110,37 +110,97 @@ function getHeaders() {
 
 function getUrl() {
     const base = props.apiBase.replace(/\/+$/, "");
-    return `${base}/api/config/${props.configName}`;
+    // Имя конфига подставляется в путь URL: без экранирования «#» и «?» обрежут путь,
+    // а «/» уведёт запрос на другой маршрут
+    return `${base}/api/config/${encodeURIComponent(props.configName)}`;
+}
+
+// Разбирает тело ответа: JSON — объект, любой другой Content-Type — null.
+// Отдельная функция нужна, потому что сервер на неизвестный маршрут отвечает
+// HTML-страницей с кодом 200, и слепой res.json() падает с невнятной ошибкой
+async function parseJsonBody(res) {
+    const contentType = res.headers.get("content-type") || "";
+    if (!contentType.includes("application/json")) {
+        return null;
+    }
+    try {
+        return await res.json();
+    } catch {
+        return null;
+    }
+}
+
+// Один и тот же отказ показывается и при загрузке, и при сохранении.
+// Держим текст в одном месте, чтобы формулировки не разъехались
+const NOT_JSON_ERROR_TEXT = "Неожиданный ответ сервера: тело не JSON. Проверьте apiBase";
+
+// Текст ошибки по HTTP-статусу. Если сервер прислал message — он попадает в текст
+// при любом коде, включая 401/403 и 5xx: иначе причина отказа теряется
+function httpErrorText(res, json) {
+    if (res.status === 401 || res.status === 403) {
+        return json?.message
+            ? `Нет доступа (${res.status}): ${json.message}`
+            : "Нет доступа, проверьте secretKey";
+    }
+    if (res.status >= 500) {
+        return json?.message
+            ? `Ошибка на сервере (${res.status}): ${json.message}`
+            : `Ошибка на сервере (${res.status})`;
+    }
+    const detail = json?.message ? `: ${json.message}` : "";
+    return `Ошибка запроса (${res.status})${detail}`;
+}
+
+// Раскладывает пришедший конфиг по реактивным уровням
+function applyConfig(data) {
+    for (const level of levels) {
+        if (!data[level.key]) continue;
+        config[level.key].enabled = data[level.key].enabled ?? false;
+        config[level.key].json = data[level.key].json ?? true;
+        config[level.key].color = data[level.key].color ?? "";
+    }
 }
 
 async function loadConfig() {
+    // Пока идёт загрузка или сохранение, повторный запуск запрещён:
+    // иначе ответы двух запросов затирают друг друга
+    if (loading.value || saving.value) return;
+
     loading.value = true;
     error.value = "";
     message.value = "";
 
     try {
         const res = await fetch(getUrl(), { headers: getHeaders() });
-        const json = await res.json();
-
-        if (json.status === "ok" && json.data) {
-            for (const level of levels) {
-                if (json.data[level.key]) {
-                    config[level.key].enabled = json.data[level.key].enabled ?? false;
-                    config[level.key].json = json.data[level.key].json ?? true;
-                    config[level.key].color = json.data[level.key].color ?? "";
-                }
-            }
-        } else {
+        const json = await parseJsonBody(res);
+
+        if (!res.ok) {
+            error.value = httpErrorText(res, json);
+            return;
+        }
+        if (!json) {
+            error.value = NOT_JSON_ERROR_TEXT;
+            return;
+        }
+        if (json.status !== "ok" || !json.data) {
             error.value = json.message || "Не удалось загрузить конфиг";
+            return;
         }
+
+        applyConfig(json.data);
     } catch (e) {
-        error.value = `Ошибка загрузки: ${e.message}`;
+        // Сюда попадает только сбой сети: fetch не бросает на 4xx и 5xx
+        error.value = `Сервер недоступен: ${e.message}`;
     } finally {
         loading.value = false;
     }
 }
 
 async function saveConfig() {
+    // Пока идёт загрузка или сохранение, повторный запуск запрещён:
+    // иначе ответы двух запросов затирают друг друга
+    if (loading.value || saving.value) return;
+
     saving.value = true;
     message.value = "";
 
@@ -159,17 +219,28 @@ async function saveConfig() {
             headers: getHeaders(),
             body: JSON.stringify(payload),
         });
-        const json = await res.json();
+        const json = await parseJsonBody(res);
 
-        if (json.status === "ok") {
-            message.value = json.message || "Конфиг сохранён";
-            messageType.value = "ok";
-        } else {
+        if (!res.ok) {
+            message.value = httpErrorText(res, json);
+            messageType.value = "error";
+            return;
+        }
+        if (!json) {
+            message.value = NOT_JSON_ERROR_TEXT;
+            messageType.value = "error";
+            return;
+        }
+        if (json.status !== "ok") {
             message.value = json.message || "Ошибка сохранения";
             messageType.value = "error";
+            return;
         }
+
+        message.value = json.message || "Конфиг сохранён";
+        messageType.value = "ok";
     } catch (e) {
-        message.value = `Ошибка сохранения: ${e.message}`;
+        message.value = `Сервер недоступен: ${e.message}`;
         messageType.value = "error";
     } finally {
         saving.value = false;
@@ -190,7 +261,7 @@ onMounted(() => {
     background: #fafafa;
 }
 
-.config-logs h2 {
+.config-logs__title {
     margin: 0 0 16px 0;
     font-size: 18px;
 }

package/README.md

@@ -12,7 +12,9 @@ npm install @andrey4emk/npm-app-front-b24
 
 ### Subscriptions
 
-Управление подписками на события и оффлайн-сущностями Bitrix24.
+Управление подписками на события и оффлайн-очередью событий Bitrix24: список подписок,
+подписка и отписка, просмотр и очистка оффлайн-сущностей, повторная запись сущности
+с последующим снятием из очереди.
 
 ```vue
 <script setup>
@@ -24,11 +26,28 @@ import Subscriptions from "@andrey4emk/npm-app-front-b24/Subscriptions.vue";
 </template>
 ```
 
-Требует глобальный объект `$b24` (клиент Bitrix24 REST API).
+**Props:**
+
+| Prop | Тип | По умолчанию | Описание |
+|------|-----|-------------|----------|
+| `b24` | Object | не задан | Клиент Bitrix24 REST API (`B24Frame` из `@bitrix24/b24jssdk`) |
+| `authConnector` | String | `""` | Значение `auth_connector` для методов работы с событиями |
+| `portalDomain` | String | `""` | Адрес портала для ссылок на сущности, `portal.bitrix24.ru` или с `https://` |
+| `timeZone` | String | `""` | Часовой пояс для колонки «Дата», строка IANA (`Europe/Moscow`). Пусто — зона браузера |
+
+Клиент ищется в таком порядке: prop `b24`, затем `inject("$b24")` (если приложение сделало
+`app.provide("$b24", client)`), затем глобальный `window.$b24`. Без клиента компонент показывает
+сообщение «Клиент Bitrix24 не инициализирован» и не падает.
+
+Адрес портала без `portalDomain` берётся из `client.getTargetOrigin()`, а если его нет, из
+`client.auth.getAuthData().domain`.
+
+Автообновление списка сущностей (раз в 3 секунды, включается тумблером) останавливается на
+скрытой вкладке браузера и при уходе со страницы.
 
 ### ConfigLogs
 
-Управление уровнями логирования через `config/log.json`.
+Управление уровнями логирования через `config/log.json` на сервере.
 
 ```vue
 <script setup>
@@ -48,17 +67,81 @@ import ConfigLogs from "@andrey4emk/npm-app-front-b24/ConfigLogs.vue";
 | `secretKey` | String | `""` | Ключ авторизации (заголовок `secret`) |
 | `configName` | String | `"log"` | Имя конфига (без `.json`) |
 
+Компонент ходит на `GET` и `POST` `${apiBase}/api/config/${configName}` и ждёт JSON вида
+`{ status: "ok", data: {...} }`. Ошибки сети, ответы 401/403 и 5xx и не-JSON тела показываются
+пользователю с кодом и текстом сервера.
+
+## Стили
+
+Стили компонентов глобальные, без `scoped`, все правила под классами с префиксами
+`subscriptions__*` и `config-logs__*`. Их можно переопределять из CSS приложения по имени класса.
+
+Цвета вынесены в кастомные свойства на корневых элементах `.subscriptions` и `.config-logs`,
+например `--subscriptions-table-line` и `--subscriptions-table-head-ink`. Переопределяйте их
+в своём CSS, если нужна перекраска без переписывания правил.
+
+В `Subscriptions` на элементах вторым классом стоят старые имена `tooltip`, `tooltipParent`,
+`switch`, `slider`, `main` и хуки без правил `subscriptions__title`, `subscriptions__subtitle`.
+Правил под старые имена в пакете нет, они остаются на элементах навсегда как точки подключения
+для стилей приложения. Таблицы получили класс `subscriptions__table` с нейтральным оформлением:
+правила написаны через `:where()`, поэтому любой селектор приложения по `table.main` их перебьёт.
+
+## Типы
+
+Декларации props генерируются из исходников (`types/*.vue.d.ts`) и подключены через условие
+`types` в карте `exports` для каждого файла. Ничего подключать вручную не нужно: TypeScript
+потребителя (Vite + vue-tsc) подхватит их сам и будет проверять типы props при импорте
+`@andrey4emk/npm-app-front-b24/Subscriptions.vue` и `.../ConfigLogs.vue`.
+
+Требования на стороне потребителя:
+
+- `moduleResolution` в `tsconfig.json` должен быть `bundler`, `node16` или `nodenext`.
+  При устаревшем `node` карта `exports` не читается, типы молча заменяются общим shim `*.vue`,
+  props становятся `any`.
+- Не добавляйте пакет в `compilerOptions.types` и не пишите `/// <reference types=...>`:
+  корневой файл деклараций отсутствует, обе конструкции дают ошибку TS2688.
+
 ## Требования
 
-- Vue 3 (`^3.0.0`) — peer dependency
+- Vue 3 (`^3.5.2`) — peer dependency. Ниже 3.5.2 сгенерированные декларации не компилируются
+  при `skipLibCheck: false`
 - Проект-потребитель должен поддерживать компиляцию `.vue` файлов (Vite / webpack + vue-loader)
-- `luxon` (`^3.7.2`) — используется в Subscriptions для форматирования дат
 
-## Важно (v0.2.0)
+Других зависимостей нет: даты форматируются через `Intl.DateTimeFormat`.
+
+## История версий
+
+### 0.4.0
+
+- `Subscriptions`: prop `timeZone`; автообновление останавливается на скрытой вкладке и
+  перезапускается после операций; ошибка загрузки гаснет после удачного обновления
+- `Subscriptions`: массовое удаление считает снятые пачки по ответу портала на каждую команду,
+  «Удалить все пустые» считает записи по идентификаторам, тексты отчётов уточнены
+- Стили: сняты глобальные правила под старыми именами `tooltip` и `tooltipParent` (имена на
+  элементах остались), добавлены `subscriptions__table` и кастомные свойства цветов
+- `ConfigLogs`: имя конфига экранируется в URL
+- Типы: ручной `index.d.ts` заменён на декларации, генерируемые `vue-tsc` при публикации;
+  подключение на стороне потребителя больше не требуется
+- `peerDependencies.vue` сужен до `^3.5.2`
+
+### 0.3.0
+
+- `Subscriptions`: состояние вкладок внутри компонента, props `b24`, `authConnector`,
+  `portalDomain`, адрес портала из клиента вместо захардкоженного домена, ссылки на
+  смарт-процессы
+- `Subscriptions`: починены «Изменить» для смарт-процессов и «Удалить все», автообновление
+  останавливается при уходе со страницы, ошибки показываются на экране, подтверждение
+  удаления вторым кликом вместо `confirm()`
+- `ConfigLogs`: разбор ответа сервера с проверкой `res.ok` и Content-Type
+- Классы стилей с префиксами, добавлены стили тумблера
+- Снята зависимость `luxon`
+- Добавлен `index.d.ts` с типами props (в 0.4.0 заменён на генерируемые декларации)
 
-Начиная с версии `0.2.0` пакет поставляет **исходные `.vue` файлы** вместо скомпилированного бандла. Компиляция происходит на стороне проекта-потребителя.
+### 0.2.0
 
-Если вы обновляетесь с `0.1.x`, измените импорты:
+Пакет поставляет исходные `.vue` файлы вместо скомпилированного бандла. Компиляция
+происходит на стороне проекта-потребителя. Импорт по голому имени пакета и файл `style.css`
+из 0.1.x больше не существуют. При обновлении с `0.1.x` измените импорты:
 
 ```js
 // Было (0.1.x)
@@ -68,3 +151,23 @@ import "@andrey4emk/npm-app-front-b24/style.css";
 // Стало (0.2.0+)
 import Subscriptions from "@andrey4emk/npm-app-front-b24/Subscriptions.vue";
 ```
+
+## Публикация
+
+Версия по semver: `patch` для исправлений, `minor` для новых функций, `major` для ломающих
+изменений. Декларации типов перегенерируются автоматически скриптом `prepublishOnly`, поэтому
+перед публикацией нужны установленные `devDependencies`.
+
+```bash
+npm install
+npm run build:types        # обновить types/, закоммитить вместе с правками
+git add .
+git commit -m "upd(client): описание"
+npm version minor          # или patch / major
+git push origin main --follow-tags
+npm publish --access public
+npm info @andrey4emk/npm-app-front-b24 version
+```
+
+Если `npm publish` отвечает 403: проверить `npm whoami`, при необходимости `npm login`,
+для scoped-пакета флаг `--access public` обязателен.