@escapenavigator/utils 2.0.27 → 2.0.29

package/dist/decode-escaped-html.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Часть сохранённых документов (`agbs.text`, клиентские договоры операторов)
+ * лежит в БД не как HTML, а как HTML-разметка, прогнанная через
+ * escape: `<p>&lt;h1&gt;Datenschutzerklärung&lt;/h1&gt;</p>`. Так получается,
+ * когда готовый HTML вставляют в ReactQuill в визуальном режиме вместо режима
+ * raw HTML: редактор считает теги обычным текстом, экранирует их и
+ * дополнительно оборачивает каждую строку в свой `<p>`. На странице документа
+ * пользователь видит теги вместо форматирования.
+ *
+ * `decodeEscapedHtml` разворачивает такой контент обратно в разметку. Работает
+ * только при явном признаке — экранированном структурном теге (`&lt;p&gt;`,
+ * `&lt;h2&gt;`, `&lt;li&gt;` и т.п.); обычный текст со случайными `&lt;`/`&gt;`
+ * («цена &lt; 50 €») остаётся как есть, потому что за ними не следует имя тега.
+ *
+ * Экранирование бывает многоуровневым — документ могли переоткрыть и
+ * пересохранить в том же визуальном режиме, тогда `&lt;` превращается в
+ * `&amp;lt;`. Поэтому декодируем в цикле, пока признак сохраняется, с лимитом
+ * `MAX_DECODE_PASSES` от зацикливания.
+ *
+ * XSS: функция только снимает escape, поэтому её результат ОБЯЗАН проходить
+ * через `sanitizeHtml` перед вставкой в DOM — как и любой другой HTML из БД.
+ *
+ * Чистая и идемпотентная: повторный вызов на уже развёрнутом HTML возвращает
+ * тот же результат.
+ */
+export declare const isEscapedHtml: (html: string | null | undefined) => boolean;
+export declare function decodeEscapedHtml(html: string | null | undefined): string;

package/dist/decode-escaped-html.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Часть сохранённых документов (`agbs.text`, клиентские договоры операторов)
+ * лежит в БД не как HTML, а как HTML-разметка, прогнанная через
+ * escape: `<p>&lt;h1&gt;Datenschutzerklärung&lt;/h1&gt;</p>`. Так получается,
+ * когда готовый HTML вставляют в ReactQuill в визуальном режиме вместо режима
+ * raw HTML: редактор считает теги обычным текстом, экранирует их и
+ * дополнительно оборачивает каждую строку в свой `<p>`. На странице документа
+ * пользователь видит теги вместо форматирования.
+ *
+ * `decodeEscapedHtml` разворачивает такой контент обратно в разметку. Работает
+ * только при явном признаке — экранированном структурном теге (`&lt;p&gt;`,
+ * `&lt;h2&gt;`, `&lt;li&gt;` и т.п.); обычный текст со случайными `&lt;`/`&gt;`
+ * («цена &lt; 50 €») остаётся как есть, потому что за ними не следует имя тега.
+ *
+ * Экранирование бывает многоуровневым — документ могли переоткрыть и
+ * пересохранить в том же визуальном режиме, тогда `&lt;` превращается в
+ * `&amp;lt;`. Поэтому декодируем в цикле, пока признак сохраняется, с лимитом
+ * `MAX_DECODE_PASSES` от зацикливания.
+ *
+ * XSS: функция только снимает escape, поэтому её результат ОБЯЗАН проходить
+ * через `sanitizeHtml` перед вставкой в DOM — как и любой другой HTML из БД.
+ *
+ * Чистая и идемпотентная: повторный вызов на уже развёрнутом HTML возвращает
+ * тот же результат.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEscapedHtml = void 0;
+exports.decodeEscapedHtml = decodeEscapedHtml;
+const MAX_DECODE_PASSES = 3;
+/**
+ * Признак экранированной разметки: `&lt;` + опциональный `/` + имя известного
+ * тега + граница (`&gt;`, пробел или `/&gt;` у самозакрывающихся). Требование
+ * границы отсекает ложные срабатывания на тексте вида `&lt;br` внутри слова.
+ *
+ * `&(?:amp;)*` покрывает многоуровневое экранирование: `&lt;`, `&amp;lt;`,
+ * `&amp;amp;lt;`. Без этого второй уровень не распознавался и цикл декодирования
+ * не запускался вовсе.
+ */
+const ESCAPED_TAG_PATTERN = /&(?:amp;)*lt;\/?(?:p|div|span|br|hr|h[1-6]|ul|ol|li|table|thead|tbody|tr|td|th|blockquote|pre|code|strong|em|b|i|u|s|a|img)(?:\s|\/?&(?:amp;)*gt;)/i;
+const ENTITIES = {
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&#39;': "'",
+    '&#x27;': "'",
+    '&amp;': '&',
+};
+/**
+ * Снимает ровно один уровень escape. Один проход регуляркой важен для
+ * корректности: `&amp;lt;` должен стать `&lt;`, а не `<`. Сканер сдвигается
+ * за уже подставленный `&`, поэтому повторного декодирования в этом же
+ * проходе не происходит.
+ */
+const decodeOnce = (html) => html.replace(/&(?:lt|gt|quot|apos|amp|#39|#x27);/gi, (entity) => ENTITIES[entity.toLowerCase()] ?? entity);
+/**
+ * Убирает Quill-обёртку `<p>` вокруг блочного элемента: после декодирования
+ * получается невалидная вложенность `<p><h2>…</h2></p>`. Браузер её всё равно
+ * расклеивает, но с пустым абзацем — лишний вертикальный отступ в документе.
+ *
+ * `<\/?` обязателен: Quill оборачивает каждую строку исходника отдельно,
+ * поэтому одиночный закрывающий тег тоже приезжает в своём `<p>` — как
+ * `<p></ul></p>` у многострочных списков.
+ */
+const unwrapBlockParagraphs = (html) => html.replace(/<p>\s*(<\/?(?:div|h[1-6]|ul|ol|li|table|thead|tbody|tr|td|th|blockquote|pre|hr|p)\b[\s\S]*?)\s*<\/p>/gi, '$1');
+const isEscapedHtml = (html) => !!html && ESCAPED_TAG_PATTERN.test(html);
+exports.isEscapedHtml = isEscapedHtml;
+function decodeEscapedHtml(html) {
+    if (!html)
+        return '';
+    let result = html;
+    let pass = 0;
+    while (pass < MAX_DECODE_PASSES && ESCAPED_TAG_PATTERN.test(result)) {
+        result = decodeOnce(result);
+        pass += 1;
+    }
+    return pass === 0 ? result : unwrapBlockParagraphs(result);
+}

package/dist/decode-escaped-html.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Регрессия на документы, сохранённые через визуальный режим ReactQuill:
+ * разметка попала в БД экранированной и рендерилась пользователю как текст
+ * с тегами (`privacy_policy/de`, `agreement/de`, `agreement/us`).
+ */
+export {};

package/dist/decode-escaped-html.test.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Регрессия на документы, сохранённые через визуальный режим ReactQuill:
+ * разметка попала в БД экранированной и рендерилась пользователю как текст
+ * с тегами (`privacy_policy/de`, `agreement/de`, `agreement/us`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const decode_escaped_html_1 = require("./decode-escaped-html");
+describe('isEscapedHtml', () => {
+    it('находит экранированный структурный тег', () => {
+        expect((0, decode_escaped_html_1.isEscapedHtml)('<p>&lt;h1&gt;Datenschutzerklärung&lt;/h1&gt;</p>')).toBe(true);
+    });
+    it('не реагирует на нормальный HTML', () => {
+        expect((0, decode_escaped_html_1.isEscapedHtml)('<h1>Datenschutzerklärung</h1><p>Stand: Juli 2026</p>')).toBe(false);
+    });
+    it('не реагирует на `<`/`>` в обычном тексте', () => {
+        expect((0, decode_escaped_html_1.isEscapedHtml)('<p>Gruppen &lt; 4 Personen zahlen mehr &gt; 20 €</p>')).toBe(false);
+    });
+    it('не реагирует на пустой ввод', () => {
+        expect((0, decode_escaped_html_1.isEscapedHtml)('')).toBe(false);
+        expect((0, decode_escaped_html_1.isEscapedHtml)(null)).toBe(false);
+        expect((0, decode_escaped_html_1.isEscapedHtml)(undefined)).toBe(false);
+    });
+});
+describe('decodeEscapedHtml', () => {
+    it('разворачивает экранированную разметку и снимает Quill-обёртку', () => {
+        const stored = '<p>&lt;h1&gt;Datenschutzerklärung&lt;/h1&gt;</p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(stored)).toBe('<h1>Datenschutzerklärung</h1>');
+    });
+    it('разворачивает списки', () => {
+        const stored = '<p>&lt;ul&gt;</p><p>&lt;li&gt;unsere Websites&lt;/li&gt;</p><p>&lt;/ul&gt;</p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(stored)).toBe('<ul><li>unsere Websites</li></ul>');
+    });
+    it('сохраняет атрибуты и кавычки', () => {
+        const stored = '<p>&lt;a href=&quot;https://example.com&quot;&gt;hier&lt;/a&gt;</p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(stored)).toBe('<p><a href="https://example.com">hier</a></p>');
+    });
+    it('снимает многоуровневое экранирование', () => {
+        const stored = '<p>&amp;lt;h2&amp;gt;1. Verantwortlicher&amp;lt;/h2&amp;gt;</p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(stored)).toBe('<h2>1. Verantwortlicher</h2>');
+    });
+    it('не трогает нормальный HTML', () => {
+        const html = '<h1>Privacy Policy</h1><p>Last updated: <em>July 2026</em></p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(html)).toBe(html);
+    });
+    it('не декодирует `&amp;` в обычном тексте', () => {
+        const html = '<p>Codeum UG &amp; Co. — Preis &lt; 50 €</p>';
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(html)).toBe(html);
+    });
+    it('идемпотентна', () => {
+        const stored = '<p>&lt;h2&gt;5. Empfänger&lt;/h2&gt;</p><p>&lt;p&gt;Hosting&lt;/p&gt;</p>';
+        const once = (0, decode_escaped_html_1.decodeEscapedHtml)(stored);
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(once)).toBe(once);
+    });
+    it('возвращает пустую строку на пустом вводе', () => {
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(null)).toBe('');
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)(undefined)).toBe('');
+        expect((0, decode_escaped_html_1.decodeEscapedHtml)('')).toBe('');
+    });
+});

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 export * from './agreement-config';
 export * from './booking-lead-time';
 export * from './booking-page-url';
-export * from './city-quest-content';
 export * from './classify-api-error';
 export * from './convert-hhmm-to-minutes';
 export * from './convert-minutes-to-hhmm';
@@ -28,7 +27,6 @@ export * from './promocode-nominal-rules';
 export * from './redirect';
 export * from './role-chat-permissions';
 export * from './role-export-permissions';
-export * from './route-warnings';
 export * from './serialize-record';
 export * from './serialize-slot';
 export * from './slot-representative-price';

package/dist/index.js

@@ -17,7 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./agreement-config"), exports);
 __exportStar(require("./booking-lead-time"), exports);
 __exportStar(require("./booking-page-url"), exports);
-__exportStar(require("./city-quest-content"), exports);
 __exportStar(require("./classify-api-error"), exports);
 __exportStar(require("./convert-hhmm-to-minutes"), exports);
 __exportStar(require("./convert-minutes-to-hhmm"), exports);
@@ -44,7 +43,6 @@ __exportStar(require("./promocode-nominal-rules"), exports);
 __exportStar(require("./redirect"), exports);
 __exportStar(require("./role-chat-permissions"), exports);
 __exportStar(require("./role-export-permissions"), exports);
-__exportStar(require("./route-warnings"), exports);
 __exportStar(require("./serialize-record"), exports);
 __exportStar(require("./serialize-slot"), exports);
 __exportStar(require("./slot-representative-price"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@escapenavigator/utils",
-  "version": "2.0.27",
+  "version": "2.0.29",
   "publishConfig": {
     "access": "public"
   },
@@ -14,12 +14,12 @@
     "test": "jest"
   },
   "dependencies": {
-    "@escapenavigator/types": "^2.0.26",
+    "@escapenavigator/types": "^2.0.27",
     "axios": "^0.21.4",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.13.2",
     "i18next": "^21.6.4",
-    "isomorphic-dompurify": "^3.18.0",
+    "isomorphic-dompurify": "3.18.0",
     "libphonenumber-js": "^1.12.24",
     "quill-delta": "^5.1.0"
   },
@@ -29,5 +29,5 @@
     "ts-jest": "^29.1.1",
     "typescript": "^5.6"
   },
-  "gitHead": "6bc32e94a8667b111cab56b04970f59bbd90afe9"
+  "gitHead": "a3aa3e96ee5a47f3de07c99d982d7302e1e73edc"
 }

package/dist/city-quest-content.d.ts

@@ -1,8 +0,0 @@
-import type { CityQuestContent, CityQuestRouteEvent, CityQuestStop, LocalizedText } from '@escapenavigator/types/dist/city-quest/city-quest-content';
-/** Patch one stop by id; returns new content reference for jsonb saves. */
-export declare const patchQuestStop: (content: CityQuestContent, stopId: string, patch: Partial<CityQuestStop>) => CityQuestContent;
-/** Patch one route event by id. */
-export declare const patchQuestRouteEvent: (content: CityQuestContent, eventId: string, patch: Partial<CityQuestRouteEvent>) => CityQuestContent;
-/** Add a simple message route event after a stop. */
-export declare const addMessageRouteEvent: (content: CityQuestContent, triggerAfterStopId: string, text: LocalizedText, from?: string) => CityQuestContent;
-export declare const removeQuestRouteEvent: (content: CityQuestContent, eventId: string) => CityQuestContent;

package/dist/city-quest-content.js

@@ -1,35 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeQuestRouteEvent = exports.addMessageRouteEvent = exports.patchQuestRouteEvent = exports.patchQuestStop = void 0;
-/** Patch one stop by id; returns new content reference for jsonb saves. */
-const patchQuestStop = (content, stopId, patch) => ({
-    ...content,
-    stops: (content.stops || []).map((stop) => (stop.id === stopId ? { ...stop, ...patch } : stop)),
-});
-exports.patchQuestStop = patchQuestStop;
-/** Patch one route event by id. */
-const patchQuestRouteEvent = (content, eventId, patch) => ({
-    ...content,
-    route_events: (content.route_events || []).map((event) => event.id === eventId ? { ...event, ...patch } : event),
-});
-exports.patchQuestRouteEvent = patchQuestRouteEvent;
-/** Add a simple message route event after a stop. */
-const addMessageRouteEvent = (content, triggerAfterStopId, text, from) => {
-    const id = `re_${Date.now().toString(36)}`;
-    const event = {
-        id,
-        trigger_after_stop: triggerAfterStopId,
-        type: 'message',
-        content: { from, text },
-    };
-    return {
-        ...content,
-        route_events: [...(content.route_events || []), event],
-    };
-};
-exports.addMessageRouteEvent = addMessageRouteEvent;
-const removeQuestRouteEvent = (content, eventId) => ({
-    ...content,
-    route_events: (content.route_events || []).filter((e) => e.id !== eventId),
-});
-exports.removeQuestRouteEvent = removeQuestRouteEvent;

package/dist/route-warnings.d.ts

@@ -1,30 +0,0 @@
-export type RoutePoint = {
-    lat: number;
-    lng: number;
-};
-export type NeighborDistanceWarning = {
-    fromIndex: number;
-    toIndex: number;
-    distanceKm: number;
-    level: 'yellow' | 'red';
-};
-export type RouteWarningsResult = {
-    neighborWarnings: NeighborDistanceWarning[];
-    sequenceWarning: boolean;
-    totalDistanceKm: number;
-    /** Rough walking time in minutes (distance @ 4 km/h + 8 min per stop). */
-    estimatedMinutes: number;
-    nearestNeighborDistanceKm: number;
-};
-/** Haversine distance in kilometres. */
-export declare const haversineKm: (a: RoutePoint, b: RoutePoint) => number;
-/** Greedy nearest-neighbor tour length starting at index 0. */
-export declare const nearestNeighborLengthKm: (points: RoutePoint[]) => number;
-export declare const analyzeRoute: (points: RoutePoint[]) => RouteWarningsResult;
-/** Soft guidance for story length (not blocking). */
-export declare const ROUTE_SOFT_LIMITS: {
-    minSteps: number;
-    maxSteps: number;
-    minTotalKm: number;
-    maxTotalKm: number;
-};

package/dist/route-warnings.js

@@ -1,117 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ROUTE_SOFT_LIMITS = exports.analyzeRoute = exports.nearestNeighborLengthKm = exports.haversineKm = void 0;
-const EARTH_RADIUS_KM = 6371;
-const WALK_KMH = 4;
-const MINUTES_PER_STOP = 8;
-const YELLOW_KM = 1;
-const RED_KM = 2;
-const SEQUENCE_RATIO = 1.25;
-const TURNBACK_DEG = 135;
-/** Haversine distance in kilometres. */
-const haversineKm = (a, b) => {
-    const toRad = (deg) => (deg * Math.PI) / 180;
-    const dLat = toRad(b.lat - a.lat);
-    const dLng = toRad(b.lng - a.lng);
-    const lat1 = toRad(a.lat);
-    const lat2 = toRad(b.lat);
-    const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
-    return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
-};
-exports.haversineKm = haversineKm;
-const bearingDeg = (a, b) => {
-    const toRad = (deg) => (deg * Math.PI) / 180;
-    const toDeg = (rad) => (rad * 180) / Math.PI;
-    const lat1 = toRad(a.lat);
-    const lat2 = toRad(b.lat);
-    const dLng = toRad(b.lng - a.lng);
-    const y = Math.sin(dLng) * Math.cos(lat2);
-    const x = Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLng);
-    return (toDeg(Math.atan2(y, x)) + 360) % 360;
-};
-const angleDiffDeg = (a, b) => {
-    const d = Math.abs(a - b) % 360;
-    return d > 180 ? 360 - d : d;
-};
-/** Greedy nearest-neighbor tour length starting at index 0. */
-const nearestNeighborLengthKm = (points) => {
-    if (points.length < 2)
-        return 0;
-    const remaining = new Set(points.map((_, i) => i));
-    let current = 0;
-    remaining.delete(0);
-    let total = 0;
-    while (remaining.size) {
-        let best = -1;
-        let bestDist = Infinity;
-        remaining.forEach((idx) => {
-            const d = (0, exports.haversineKm)(points[current], points[idx]);
-            if (d < bestDist) {
-                bestDist = d;
-                best = idx;
-            }
-        });
-        total += bestDist;
-        current = best;
-        remaining.delete(best);
-    }
-    return total;
-};
-exports.nearestNeighborLengthKm = nearestNeighborLengthKm;
-const analyzeRoute = (points) => {
-    const neighborWarnings = [];
-    let totalDistanceKm = 0;
-    for (let i = 0; i < points.length - 1; i++) {
-        const distanceKm = (0, exports.haversineKm)(points[i], points[i + 1]);
-        totalDistanceKm += distanceKm;
-        if (distanceKm > RED_KM) {
-            neighborWarnings.push({
-                fromIndex: i,
-                toIndex: i + 1,
-                distanceKm,
-                level: 'red',
-            });
-        }
-        else if (distanceKm > YELLOW_KM) {
-            neighborWarnings.push({
-                fromIndex: i,
-                toIndex: i + 1,
-                distanceKm,
-                level: 'yellow',
-            });
-        }
-    }
-    const nearestNeighborDistanceKm = (0, exports.nearestNeighborLengthKm)(points);
-    let sequenceWarning = false;
-    if (points.length >= 3 && nearestNeighborDistanceKm > 0) {
-        if (totalDistanceKm / nearestNeighborDistanceKm >= SEQUENCE_RATIO) {
-            sequenceWarning = true;
-        }
-    }
-    if (!sequenceWarning && points.length >= 3) {
-        for (let i = 0; i < points.length - 2; i++) {
-            const b1 = bearingDeg(points[i], points[i + 1]);
-            const b2 = bearingDeg(points[i + 1], points[i + 2]);
-            if (angleDiffDeg(b1, b2) > TURNBACK_DEG) {
-                sequenceWarning = true;
-                break;
-            }
-        }
-    }
-    const estimatedMinutes = Math.round((totalDistanceKm / WALK_KMH) * 60 + points.length * MINUTES_PER_STOP);
-    return {
-        neighborWarnings,
-        sequenceWarning,
-        totalDistanceKm,
-        estimatedMinutes,
-        nearestNeighborDistanceKm,
-    };
-};
-exports.analyzeRoute = analyzeRoute;
-/** Soft guidance for story length (not blocking). */
-exports.ROUTE_SOFT_LIMITS = {
-    minSteps: 6,
-    maxSteps: 12,
-    minTotalKm: 2,
-    maxTotalKm: 4,
-};