@alfalab/bridge-to-native 1.3.1 → 1.3.2-beta.0828f8f

package/client/bridge-to-native.d.ts

@@ -147,15 +147,8 @@ export declare class BridgeToNative {
      * экзепляру B2N следующей страницы текущего WA (в случае multi-page application).
      *
      * ВАЖНО!
-     *
-     * Не поддерживаются такие сценарии:
-     *
-     * 1. Микс client-side навигации и server-side навигации в рамках одного WA.
-     *  т.е. одно WA должно использовать либо только `navigateClientSide`, либо только `navigateServerSide`.
-     * 2. Старт в WA 1 → переход к WA 2 → переход к WA 1,
-     *  т.е. при использовании server-side навигации, история переходов разных WA не должна смешиваться.
-     *
-     * Снять эти ограничения возможно, но нужны доработки.
+     * `goBackAFewStepsClientSide` можно использовать только в рамках истории по SPA WA! Движение назад
+     * server-side переходом на несколько шагов не поддерживается.
      *
      * @param url URL для перехода внутри WA server-side навигацией.
      * @param nativeTitle Текст заголовка, для «нативной» части WV, пустая строка — отсутствие заголовка.
@@ -206,8 +199,9 @@ export declare class BridgeToNative {
     /**
      * Для перезагрузки страницы необходимо использовать этот метод.
      * Иначе синхронизация состояния с NA будет потеряна.
-     * По умолчанию метод сам делает location.reload,
-     * но с помощью аргумента можно отключить этот вызов
+     *
+     * @param skipReload По умолчанию метод сам делает `location.reload`,
+     *  но с помощью аргумента можно отключить этот вызов, если нужно.
      */
     reload(skipReload?: boolean): void;
     /**

package/client/bridge-to-native.js

@@ -181,15 +181,8 @@ class BridgeToNative {
      * экзепляру B2N следующей страницы текущего WA (в случае multi-page application).
      *
      * ВАЖНО!
-     *
-     * Не поддерживаются такие сценарии:
-     *
-     * 1. Микс client-side навигации и server-side навигации в рамках одного WA.
-     *  т.е. одно WA должно использовать либо только `navigateClientSide`, либо только `navigateServerSide`.
-     * 2. Старт в WA 1 → переход к WA 2 → переход к WA 1,
-     *  т.е. при использовании server-side навигации, история переходов разных WA не должна смешиваться.
-     *
-     * Снять эти ограничения возможно, но нужны доработки.
+     * `goBackAFewStepsClientSide` можно использовать только в рамках истории по SPA WA! Движение назад
+     * server-side переходом на несколько шагов не поддерживается.
      *
      * @param url URL для перехода внутри WA server-side навигацией.
      * @param nativeTitle Текст заголовка, для «нативной» части WV, пустая строка — отсутствие заголовка.
@@ -248,8 +241,9 @@ class BridgeToNative {
     /**
      * Для перезагрузки страницы необходимо использовать этот метод.
      * Иначе синхронизация состояния с NA будет потеряна.
-     * По умолчанию метод сам делает location.reload,
-     * но с помощью аргумента можно отключить этот вызов
+     *
+     * @param skipReload По умолчанию метод сам делает `location.reload`,
+     *  но с помощью аргумента можно отключить этот вызов, если нужно.
      */
     reload(skipReload) {
         this.nativeNavigationAndTitleService.reload(skipReload);

package/client/services-and-utils/native-navigation-and-title-service.d.ts

@@ -1,9 +1,11 @@
- 
 import { type BrowserHistoryApiWrappers, type HistoryPushStateParams, type LocationAssignParam, type LogError } from '../types';
 import { type NativeParamsService } from './native-params-service';
 /**
  * Сервис, отвечающий за взаимодействие WA с WV компонентами NA —
  * «заголовком» и кнопкой «назад».
+ *
+ * Подробное описание сценариев навигации и логики восстановления состояния при hard навигации
+ * см. в документе {@link ./NAVIGATION_SCENARIOS.md}.
  */
 export declare class NativeNavigationAndTitleService {
     private nativeParamsService;
@@ -34,14 +36,23 @@ export declare class NativeNavigationAndTitleService {
      * после нажатия на кнопку «Назад» в NA, вызова `history.back()` и `history.go(-x)`.
      */
     private handleClientSideNavigationBack;
-    private static hasSavedHistoryStack;
+    private hasSavedHistoryStack;
     /**
-     * Инициализирует `nativeHistoryStack`, учитывая варианты:
-     * - Инициализация при открытии WV (Сценарий 1);
-     * - Инициализация при server-side навигации в рамках одной WV-сессии (Сценарий 2);
-     * - Инициализация при server-side переходе «назад» по истории (Сценарий 3).
+     * Инициализирует `nativeHistoryStack`.
+     *
+     * Подробное описание каждого сценария см. в {@link ./NAVIGATION_SCENARIOS.md}.
      */
     private initializeNativeHistoryStack;
+    private initializeForNewOrigin;
+    private initializeForForward;
+    private initializeFromBackwardOrReload;
+    private stackContainsCrossOriginMarker;
+    private truncateToLastCrossOriginMarker;
+    /**
+     * Читает и парсит `nativeHistoryStack` из SessionStorage.
+     * При ошибке чтения или парсинга логирует через `logError` и пробрасывает исключение.
+     */
+    private readSavedHistoryStack;
     /**
      * Подготавливает ссылку для корректного перехода server-side навигацией.
      *
@@ -51,15 +62,7 @@ export declare class NativeNavigationAndTitleService {
      */
     private prepareExternalLinkBeforeOpen;
     /**
-     * Читает сохраннённый в sessionStorage `nativeHistoryStack`,
-     * снова сохраняет его в sessionStorage, уменьшая список на одну запись,
-     * на случай, если будет дальнейший переход назад server-side навигацией.
-     *
-     * @returns Актуальное состояние `nativeHistoryStack` из sessionStorage.
-     */
-    private readAndUpdateNativeHistoryStackSessionStorage;
-    /**
-     * Сохранение состояния связи текущего WA с NA при server-side навигации в sessionStorage.
+     * Сохраняет `nativeHistoryStack` в SessionStorage.
      */
     private saveNativeHistoryStack;
     /**

package/client/services-and-utils/native-navigation-and-title-service.js

@@ -1,5 +1,5 @@
 "use strict";
-/* eslint max-lines: ["error", {"skipComments": true}] */ // Много комментариев.
+/* eslint max-lines: ["error", {"max": 360, "skipComments": true}] */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NativeNavigationAndTitleService = void 0;
 const query_and_headers_keys_1 = require("../../query-and-headers-keys");
@@ -7,6 +7,9 @@ const close_webview_util_1 = require("./close-webview-util");
 /**
  * Сервис, отвечающий за взаимодействие WA с WV компонентами NA —
  * «заголовком» и кнопкой «назад».
+ *
+ * Подробное описание сценариев навигации и логики восстановления состояния при hard навигации
+ * см. в документе {@link ./NAVIGATION_SCENARIOS.md}.
  */
 class NativeNavigationAndTitleService {
     constructor(nativeParamsService, browserHistoryApiWrappers, logError) {
@@ -64,20 +67,26 @@ class NativeNavigationAndTitleService {
             window.history.pushState(state, '', url);
         }
         this.nativeHistoryStack.push(nativeTitle);
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     navigateServerSide(link, nativeTitle = '') {
         const url = link instanceof URL ? link : new URL(link);
+        const isCrossOrigin = url.origin !== window.location.origin;
+        if (isCrossOrigin) {
+            this.nativeHistoryStack.push(2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */);
+        }
+        else {
+            this.nativeHistoryStack.push(nativeTitle);
+        }
         if (nativeTitle) {
             url.searchParams.set(query_and_headers_keys_1.QUERY_B2N_TITLE, nativeTitle);
         }
-        // TODO: Предыдущая реализация на iOS открывала новое WV. Возможно, что-то плохо работало,
-        // обязательно протестировать.
         this.saveNativeHistoryStack();
         window.location.assign(this.prepareExternalLinkBeforeOpen(url));
     }
     reload(skipReload = false) {
-        this.nativeHistoryStack.push(1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */); // небольшой костыль, чтобы переиспользовать server-side сценарий
+        this.nativeHistoryStack.push(1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */);
         this.saveNativeHistoryStack();
         // информация для серверной стороны B2N, что происходит `reload` и парсить запрос на предмет NA параметров не нужно (в нем их скорее всего не будет)
         document.cookie = `${query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_RELOAD}=true; Path=/`;
@@ -87,10 +96,12 @@ class NativeNavigationAndTitleService {
     }
     setInitialView(nativeTitle = '') {
         this.nativeHistoryStack = [nativeTitle];
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     setTitle(nativeTitle) {
         this.nativeHistoryStack[this.nativeHistoryStack.length - 1] = nativeTitle;
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
     /**
@@ -122,89 +133,152 @@ class NativeNavigationAndTitleService {
             (0, close_webview_util_1.closeWebviewUtil)();
             return;
         }
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
-    static hasSavedHistoryStack() {
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    hasSavedHistoryStack() {
         return sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK) !== null;
     }
     /**
-     * Инициализирует `nativeHistoryStack`, учитывая варианты:
-     * - Инициализация при открытии WV (Сценарий 1);
-     * - Инициализация при server-side навигации в рамках одной WV-сессии (Сценарий 2);
-     * - Инициализация при server-side переходе «назад» по истории (Сценарий 3).
+     * Инициализирует `nativeHistoryStack`.
+     *
+     * Подробное описание каждого сценария см. в {@link ./NAVIGATION_SCENARIOS.md}.
      */
     initializeNativeHistoryStack() {
         const { nextPageId, title } = this.nativeParamsService;
-        if (nextPageId) {
-            // Сценарий 2 – `nextPageId` ставит метод `this.navigateServerSide`,
-            // т.е. это инициализация сразу после перехода server-side навигацией.
-            this.nativeHistoryStack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
-            this.nativeHistoryStack[this.nativeHistoryStack.length - 1] = title;
-        }
-        else if (NativeNavigationAndTitleService.hasSavedHistoryStack()) {
-            // Сценарий 3 - в sessionStorage есть сохранённый nativeHistoryStack,
-            // значит это инициализация сразу после перехода назад server-side навигацией,
-            // или инициализация после использования метода `reload`.
-            try {
-                this.nativeHistoryStack = this.readAndUpdateNativeHistoryStackSessionStorage();
-            }
-            catch (_a) {
-                this.nativeHistoryStack = [''];
-            }
+        const hasSS = this.hasSavedHistoryStack();
+        if (nextPageId && !hasSS) {
+            // есть nextPageId + нет SS → на этом origin ранее не были.
+            this.nativeHistoryStack = this.initializeForNewOrigin(nextPageId, title);
+        }
+        else if (nextPageId && hasSS) {
+            // есть nextPageId + есть SS → forward навигация.
+            this.nativeHistoryStack = this.initializeForForward(nextPageId, title);
+        }
+        else if (!nextPageId && hasSS) {
+            // нет nextPageId + есть SS → back-навигация или reload.
+            this.nativeHistoryStack = this.initializeFromBackwardOrReload(title);
         }
         else {
-            // Сценарий 1 - запись в sessionStorage ставит метод `this.navigateServerSide`,
-            // её нет, значит это инициализация сразу после открытия нового WV.
+            // нет nextPageId + нет SS → старт нового WV, назад идти некуда.
             this.nativeHistoryStack = [title];
         }
+        this.saveNativeHistoryStack();
         this.syncHistoryWithNative();
     }
-    /**
-     * Подготавливает ссылку для корректного перехода server-side навигацией.
-     *
-     * @param url URL для перехода внутри WA server-side навигацией.
-     * @return Подготовленная ссылка для экземпляра B2N следующего WA или
-     * экзепляра B2N следующей страницы текущего WA
-     */
-    prepareExternalLinkBeforeOpen(url) {
-        const currentPageId = this.nativeHistoryStack.length;
-        const divider = new URL(url).searchParams.toString() ? '&' : '?';
-        const modifiedUrl = new URL(`${url}${divider}${this.nativeParamsService.originalWebviewParams}`);
-        modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_B2N_NEXT_PAGEID, (currentPageId + 1).toString());
-        return modifiedUrl;
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    initializeForNewOrigin(nextPageId, title) {
+        const stack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
+        stack[stack.length - 1] = title;
+        return stack;
+    }
+    initializeForForward(nextPageId, title) {
+        try {
+            const savedStack = this.readSavedHistoryStack();
+            const lastSaved = savedStack[savedStack.length - 1];
+            if (lastSaved === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */ &&
+                savedStack.length < nextPageId) {
+                const stack = new Array(nextPageId).fill(0 /* NativeHistoryStackSpecialValues.ServerSideNavigationStub */);
+                for (let i = 0; i < savedStack.length; i++) {
+                    stack[i] = savedStack[i];
+                }
+                stack[stack.length - 1] = title;
+                return stack;
+            }
+            if (savedStack.length === nextPageId) {
+                savedStack[savedStack.length - 1] = title;
+                return savedStack;
+            }
+            return this.initializeForNewOrigin(nextPageId, title);
+        }
+        catch (_a) {
+            return this.initializeForNewOrigin(nextPageId, title);
+        }
+    }
+    initializeFromBackwardOrReload(title) {
+        try {
+            const savedStack = this.readSavedHistoryStack();
+            const lastEntry = savedStack[savedStack.length - 1];
+            if (lastEntry === 1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */) {
+                savedStack.pop();
+                if (savedStack.length === 0) {
+                    return [title];
+                }
+                return savedStack;
+            }
+            if (this.stackContainsCrossOriginMarker(savedStack)) {
+                return this.truncateToLastCrossOriginMarker(savedStack);
+            }
+            savedStack.pop();
+            if (savedStack.length === 0) {
+                return [title];
+            }
+            return savedStack;
+        }
+        catch (_a) {
+            return [title];
+        }
+    }
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    stackContainsCrossOriginMarker(stack) {
+        return stack.find((el) => el === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */);
+    }
+    // eslint-disable-next-line class-methods-use-this -- удобней использовать метод в контексте экземпляра.
+    truncateToLastCrossOriginMarker(stack) {
+        for (let i = stack.length - 1; i >= 0; i--) {
+            if (stack[i] === 2 /* NativeHistoryStackSpecialValues.ServerSideNavigationNextOrigin */) {
+                return stack.slice(0, i);
+            }
+        }
+        return stack;
     }
     /**
-     * Читает сохраннённый в sessionStorage `nativeHistoryStack`,
-     * снова сохраняет его в sessionStorage, уменьшая список на одну запись,
-     * на случай, если будет дальнейший переход назад server-side навигацией.
-     *
-     * @returns Актуальное состояние `nativeHistoryStack` из sessionStorage.
+     * Читает и парсит `nativeHistoryStack` из SessionStorage.
+     * При ошибке чтения или парсинга логирует через `logError` и пробрасывает исключение.
      */
-    readAndUpdateNativeHistoryStackSessionStorage() {
+    readSavedHistoryStack() {
+        const serialized = sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK);
         try {
-            const serializedNativeHistoryStack = sessionStorage.getItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK);
-            if (!serializedNativeHistoryStack) {
-                throw new Error();
-            }
-            const nativeHistoryStack = JSON.parse(serializedNativeHistoryStack); // происходит внутри оператора `catch`, поэтому кастинг типа приемлем
-            const nativeHistoryStackToSerialize = nativeHistoryStack.slice(0, -1);
-            sessionStorage.setItem(query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK, JSON.stringify(nativeHistoryStackToSerialize));
-            if (nativeHistoryStack[nativeHistoryStack.length - 1] ===
-                1 /* NativeHistoryStackSpecialValues.TemporaryReloadStub */) {
-                return nativeHistoryStack.slice(0, -1);
+            if (!serialized) {
+                throw new Error(`${query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK} sessionStorage expected not to be null`);
             }
-            return nativeHistoryStack;
+            return JSON.parse(serialized);
         }
         catch (e) {
             if (this.logError) {
-                this.logError('Клиентский код B2N не смог восстановить `nativeHistoryStack` из sessionStorage. ' +
-                    'Могут возникнуть проблемы с кнопкой «Назад» в NA.', e);
+                this.logError(`Клиентский код B2N не смог получить ${query_and_headers_keys_1.SS_KEY_BRIDGE_TO_NATIVE_HISTORY_STACK} из sessionStorage
+                    Могут возникнуть проблемы с кнопкой «Назад» в NA.`, e);
             }
-            throw new Error();
+            throw e;
+        }
+    }
+    /**
+     * Подготавливает ссылку для корректного перехода server-side навигацией.
+     *
+     * @param url URL для перехода внутри WA server-side навигацией.
+     * @return Подготовленная ссылка для экземпляра B2N следующего WA или
+     * экзепляра B2N следующей страницы текущего WA
+     */
+    prepareExternalLinkBeforeOpen(url) {
+        const currentPageId = this.nativeHistoryStack.length;
+        const modifiedUrl = new URL(url);
+        const { originalWebviewParams, appVersion } = this.nativeParamsService;
+        if (originalWebviewParams) {
+            const originalWebviewSearchParams = new URLSearchParams(originalWebviewParams);
+            originalWebviewSearchParams.forEach((value, key) => {
+                modifiedUrl.searchParams.set(key, value);
+            });
         }
+        // Явно добавляем query-параметр `device_app_version` используемый NA на iOS, чтобы он был и в Android окружении.
+        // Таким образом гарантируется, что версию приложения будет видеть следующее WA
+        // (заголовок `app-version` может отсутствовать при server-side переходах).
+        modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_NATIVE_IOS_APPVERSION, appVersion);
+        modifiedUrl.searchParams.set(query_and_headers_keys_1.QUERY_B2N_NEXT_PAGEID, currentPageId.toString());
+        return modifiedUrl;
     }
     /**
-     * Сохранение состояния связи текущего WA с NA при server-side навигации в sessionStorage.
+     * Сохраняет `nativeHistoryStack` в SessionStorage.
      */
     saveNativeHistoryStack() {
         const serializedNativeHistoryStack = JSON.stringify(this.nativeHistoryStack);

package/package.json

@@ -1,121 +1,121 @@
 {
-    "name": "@alfalab/bridge-to-native",
-    "version": "1.3.1",
-    "license": "MIT",
-    "description": "Утилита для удобной работы веб приложения внутри нативного приложения и коммуникации с ним.",
-    "engines": {
-        "node": ">=20.19.2",
-        "npm": "please-use-yarn"
+  "name": "@alfalab/bridge-to-native",
+  "version": "1.3.2-beta.0828f8f",
+  "license": "MIT",
+  "description": "Утилита для удобной работы веб приложения внутри нативного приложения и коммуникации с ним.",
+  "engines": {
+    "node": ">=20.19.2",
+    "npm": "please-use-yarn"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/core-ds/bridge-to-native.git"
+  },
+  "exports": {
+    "./client": {
+      "import": "./client/index.js",
+      "require": "./client/index.js",
+      "types": "./client/index.d.ts"
     },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/core-ds/bridge-to-native.git"
+    "./server": {
+      "import": "./server/index.js",
+      "require": "./server/index.js",
+      "types": "./server/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "bugs": {
+    "url": "https://github.com/core-ds/bridge-to-native/issues"
+  },
+  "scripts": {
+    "build": "yarn build:clean && yarn build:ts",
+    "build:clean": "shx rm -rf .publish",
+    "build:copy-package-json": "shx cp package.json .publish/package.json",
+    "build:ts": "tsc --build",
+    "format": "arui-presets-lint format",
+    "format:check": "arui-presets-lint format:check",
+    "lint": "yarn lint:scripts && yarn format:check",
+    "lint:fix": "yarn lint:scripts --fix && yarn format",
+    "lint:scripts": "arui-presets-lint scripts",
+    "pub": "npm publish .publish --userconfig \"../.npmrc\" --tag \"$TAG\"",
+    "release": "yarn build && yarn build:copy-package-json && yarn pub",
+    "test": "arui-scripts test --silent --collect-coverage"
+  },
+  "devDependencies": {
+    "@happy-dom/jest-environment": "18.0.1",
+    "@types/jest": "29.5.14",
+    "@types/node": "20.19.1",
+    "arui-presets-lint": "8.7.0",
+    "arui-scripts": "19.0.7",
+    "copyfiles": "2.4.1",
+    "jest-junit": "10.0.0",
+    "lint-staged": "^12.5.0",
+    "promisify-child-process": "4.1.1",
+    "shx": "0.3.4",
+    "typescript": "5.5.4"
+  },
+  "commitlint": {
+    "extends": "./node_modules/arui-presets-lint/commitlint"
+  },
+  "eslintConfig": {
+    "extends": "./node_modules/arui-presets-lint/eslint",
+    "parserOptions": {
+      "project": [
+        "./__tests__/tsconfig.json",
+        "./src/client/tsconfig.json",
+        "./src/server/tsconfig.json"
+      ]
     },
-    "exports": {
-        "./client": {
-            "import": "./client/index.js",
-            "require": "./client/index.js",
-            "types": "./client/index.d.ts"
-        },
-        "./server": {
-            "import": "./server/index.js",
-            "require": "./server/index.js",
-            "types": "./server/index.d.ts"
-        }
-    },
-    "sideEffects": false,
-    "bugs": {
-        "url": "https://github.com/core-ds/bridge-to-native/issues"
-    },
-    "scripts": {
-        "build": "yarn build:clean && yarn build:ts",
-        "build:clean": "shx rm -rf .publish",
-        "build:copy-package-json": "shx cp package.json .publish/package.json",
-        "build:ts": "tsc --build",
-        "format": "arui-presets-lint format",
-        "format:check": "arui-presets-lint format:check",
-        "lint": "yarn lint:scripts && yarn format:check",
-        "lint:fix": "yarn lint:scripts --fix && yarn format",
-        "lint:scripts": "arui-presets-lint scripts",
-        "pub": "npm publish .publish --userconfig \"../.npmrc\" --tag \"$TAG\"",
-        "release": "yarn build && yarn build:copy-package-json && yarn pub",
-        "test": "arui-scripts test --silent --collect-coverage"
-    },
-    "devDependencies": {
-        "@happy-dom/jest-environment": "18.0.1",
-        "@types/jest": "29.5.14",
-        "@types/node": "20.19.1",
-        "arui-presets-lint": "8.7.0",
-        "arui-scripts": "19.0.7",
-        "copyfiles": "2.4.1",
-        "jest-junit": "10.0.0",
-        "lint-staged": "^12.5.0",
-        "promisify-child-process": "4.1.1",
-        "shx": "0.3.4",
-        "typescript": "5.5.4"
-    },
-    "commitlint": {
-        "extends": "./node_modules/arui-presets-lint/commitlint"
-    },
-    "eslintConfig": {
-        "extends": "./node_modules/arui-presets-lint/eslint",
-        "parserOptions": {
-            "project": [
-                "./__tests__/tsconfig.json",
-                "./src/client/tsconfig.json",
-                "./src/server/tsconfig.json"
-            ]
-        },
-        "overrides": [
-            {
-                "files": [
-                    "__tests__/**/*"
-                ],
-                "rules": {
-                    "max-lines": "off"
-                }
-            }
-        ]
-    },
-    "jest": {
-        "projects": [
-            {
-                "displayName": "client-tests",
-                "testEnvironment": "@happy-dom/jest-environment",
-                "testPathIgnorePatterns": [
-                    "/__tests__/server/"
-                ]
-            },
-            {
-                "displayName": "server-tests",
-                "testEnvironment": "node",
-                "testPathIgnorePatterns": [
-                    "/__tests__/client/"
-                ]
-            }
-        ],
-        "testRegex": [
-            "__tests__/.*\\.test\\.ts"
+    "overrides": [
+      {
+        "files": [
+          "__tests__/**/*"
         ],
-        "coveragePathIgnorePatterns": [
-            "/node_modules/",
-            "/src/(client|server)/index.ts"
-        ],
-        "reporters": [
-            "default",
-            "jest-junit"
+        "rules": {
+          "max-lines": "off"
+        }
+      }
+    ]
+  },
+  "jest": {
+    "projects": [
+      {
+        "displayName": "client-tests",
+        "testEnvironment": "@happy-dom/jest-environment",
+        "testPathIgnorePatterns": [
+          "/__tests__/server/"
         ]
-    },
-    "prettier": "arui-presets-lint/prettier",
-    "stylelint": {
-        "extends": "arui-presets-lint/stylelint",
-        "ignoreFiles": [
-            "coverage/**/*.js",
-            ".yarn/releases/*"
+      },
+      {
+        "displayName": "server-tests",
+        "testEnvironment": "node",
+        "testPathIgnorePatterns": [
+          "/__tests__/client/"
         ]
-    },
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org"
-    },
-    "packageManager": "yarn@4.12.0"
+      }
+    ],
+    "testRegex": [
+      "__tests__/.*\\.test\\.ts"
+    ],
+    "coveragePathIgnorePatterns": [
+      "/node_modules/",
+      "/src/(client|server)/index.ts"
+    ],
+    "reporters": [
+      "default",
+      "jest-junit"
+    ]
+  },
+  "prettier": "arui-presets-lint/prettier",
+  "stylelint": {
+    "extends": "arui-presets-lint/stylelint",
+    "ignoreFiles": [
+      "coverage/**/*.js",
+      ".yarn/releases/*"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "packageManager": "yarn@4.12.0"
 }

package/query-and-headers-keys.js

@@ -34,7 +34,7 @@ exports.QUERY_B2N_TITLE = 'b2n-title';
 // (т.к. `title` часто может использоваться самим веб-приложением).
 // Игнорируется, если указан 'b2n-title'.
 exports.QUERY_B2N_TITLE_DEPRECATED = 'title';
-// NA на iOS приложение передаёт в этом параметре схему,
+// NA на iOS передаёт в этом параметре схему,
 // под которым оно зарегистрировано в OS.
 // Известные проблемы:
 // * В старых версиях отсутствует, клиентский код использует хардкод (см. `src/client/constants.ts`);
@@ -42,7 +42,9 @@ exports.QUERY_B2N_TITLE_DEPRECATED = 'title';
 //  и схемой, которая приходит в этом параметре.
 //  Нужно просить iOS разработчика собрать сборку нормально.
 exports.QUERY_NATIVE_IOS_APPID = 'applicationId';
-// NA на iOS приложение передаёт в этом параметре свою версию.
+// Исторически NA на iOS передаёт в этом параметре свою версию.
+// B2N сознательно переиспользует этот query и для server-side переходов в Android,
+// чтобы не вводить отдельный служебный параметр только для переноса версии между WA.
 exports.QUERY_NATIVE_IOS_APPVERSION = 'device_app_version';
 // NA на обеих платформах в этом параметре передаёт активную тему (светлая/тёмная).
 exports.QUERY_NATIVE_THEME = 'theme';

package/server/prepare-native-app-details-for-client.d.ts

@@ -1,3 +1,4 @@
+import { type NativeParams } from '../types';
 import { type UniversalRequest } from './types';
 /**
  * Парсит запрос, доставая из него данные о нативном приложении,
@@ -10,4 +11,4 @@ import { type UniversalRequest } from './types';
  *  Нужно передать функцию, которая средствами используемого веб-сервера добавит заголовок в ответ.
  *  b2native с её помощью добавит `Set-Cookie` заголовок с некоторыми данными для своего клиентского кода.
  */
-export declare function prepareNativeAppDetailsForClient(request: UniversalRequest, setResponseHeader: (headerKey: string, headerValue: string) => void): any;
+export declare function prepareNativeAppDetailsForClient(request: UniversalRequest, setResponseHeader: (headerKey: string, headerValue: string) => void): Partial<NativeParams>;

package/server/prepare-native-app-details-for-client.js

@@ -25,25 +25,21 @@ function prepareNativeAppDetailsForClient(request, setResponseHeader) {
     // 1) Данных NA в запросе с большой вероятностью не будет;
     // 2) клиентская сторона сохранит всё, что нужно в SessionStorage
     const cookieHeader = (0, utils_1.getHeaderValue)(request, query_and_headers_keys_1.HEADER_KEY_COOKIE);
+    const nativeParamsFromCookie = (0, utils_1.readNativeParamsFromCookie)(cookieHeader);
     const hasReloadFlag = cookieHeader?.includes(`${query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_RELOAD}=true`);
     if (hasReloadFlag) {
         setResponseHeader('Set-Cookie', `${query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_RELOAD}=false; Max-Age=0; Path=/`);
-        const cookieData = (0, utils_1.getBridgeToNativeDataCookie)(cookieHeader);
-        if (cookieData) {
-            try {
-                return JSON.parse(decodeURIComponent(cookieData));
-            }
-            catch {
-                return parseRequest(request);
-            }
+        if (nativeParamsFromCookie) {
+            return nativeParamsFromCookie;
         }
+        return buildNativeParams(request);
     }
-    const nativeParams = parseRequest(request);
+    const nativeParams = buildNativeParams(request, nativeParamsFromCookie);
     const serializedNativeParams = encodeURIComponent(JSON.stringify(nativeParams));
     setResponseHeader('Set-Cookie', `${query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_DATA}=${serializedNativeParams}; Path=/`);
     return nativeParams;
 }
-function parseRequest(request) {
+function buildNativeParams(request, nativeParamsFromCookie) {
     // Прихраним «сервисные» query-параметры от нативного приложения,
     // чтобы подмешать их к URL при переходе в другое веб-приложение
     // в рамках одной вебвью-сессии.
@@ -70,6 +66,9 @@ function parseRequest(request) {
         const [, appIdSubsting] = iosAppIdQuery.match(regexp_patterns_1.iosAppIdPattern); // кастинг ок — в условии блока регулярка проверена
         nativeParams.iosAppId = appIdSubsting;
     }
+    // Версия приложения может приехать прямо в текущем request (в query-параметре `device_app_version`
+    // или заголовке `app-version`), а при server-side переходах / возврате назад может уже не приехать.
+    // В таких сценариях берём `appVersion` фолбэком из куки `bridgeToNativeData`.
     if (iosAppVersionQuery && regexp_patterns_1.versionPattern.test(iosAppVersionQuery)) {
         nativeParams.appVersion = iosAppVersionQuery;
     }
@@ -77,6 +76,11 @@ function parseRequest(request) {
         const [, versionSubstring] = appVersionFromHeaders.match(regexp_patterns_1.versionPattern); // кастинг ок — в условии блока регулярка проверена
         nativeParams.appVersion = versionSubstring;
     }
+    else if (nativeParamsFromCookie?.appVersion &&
+        regexp_patterns_1.versionPattern.test(nativeParamsFromCookie.appVersion)) {
+        const [, versionSubstring] = nativeParamsFromCookie.appVersion.match(regexp_patterns_1.versionPattern);
+        nativeParams.appVersion = versionSubstring;
+    }
     else {
         nativeParams.appVersion = '0.0.0';
     }

package/server/utils.d.ts

@@ -1,3 +1,4 @@
+import { type NativeParams } from '../types';
 import { type UniversalRequest } from './types';
 /**
  * На основе объекта запроса любого типа возвращает
@@ -31,6 +32,10 @@ export declare function parseHeaderTimestamp(headerValue: string | number | null
 /**
  * Возвращает значение для нужной куки
  *
- * @param cookieName Имя куки
+ * @param cookieHeader Имя куки
  */
-export declare const getBridgeToNativeDataCookie: (cookieName: string | null) => string | undefined;
+export declare const getBridgeToNativeDataCookie: (cookieHeader: string | null) => string | undefined;
+/**
+ * Возвращает десериализованные данные из `bridgeToNativeData` cookie.
+ */
+export declare function readNativeParamsFromCookie(cookieHeader: string | null): Partial<NativeParams> | null;

package/server/utils.js

@@ -5,6 +5,7 @@ exports.getHeaderValue = getHeaderValue;
 exports.getQueryValues = getQueryValues;
 exports.hasBridgeToNativeDataCookie = hasBridgeToNativeDataCookie;
 exports.parseHeaderTimestamp = parseHeaderTimestamp;
+exports.readNativeParamsFromCookie = readNativeParamsFromCookie;
 const query_and_headers_keys_1 = require("../query-and-headers-keys");
 const regexp_patterns_1 = require("./regexp-patterns");
 /**
@@ -57,13 +58,13 @@ function parseHeaderTimestamp(headerValue) {
 /**
  * Возвращает значение для нужной куки
  *
- * @param cookieName Имя куки
+ * @param cookieHeader Имя куки
  */
-const getBridgeToNativeDataCookie = (cookieName) => {
-    if (!cookieName) {
+const getBridgeToNativeDataCookie = (cookieHeader) => {
+    if (!cookieHeader) {
         return undefined;
     }
-    const cookies = cookieName.split(';');
+    const cookies = cookieHeader.split(';');
     for (const cookie of cookies) {
         const [key, value] = cookie.trim().split('=');
         if (key === query_and_headers_keys_1.COOKIE_KEY_BRIDGE_TO_NATIVE_DATA) {
@@ -73,3 +74,18 @@ const getBridgeToNativeDataCookie = (cookieName) => {
     return undefined;
 };
 exports.getBridgeToNativeDataCookie = getBridgeToNativeDataCookie;
+/**
+ * Возвращает десериализованные данные из `bridgeToNativeData` cookie.
+ */
+function readNativeParamsFromCookie(cookieHeader) {
+    const cookieData = (0, exports.getBridgeToNativeDataCookie)(cookieHeader);
+    if (!cookieData) {
+        return null;
+    }
+    try {
+        return JSON.parse(decodeURIComponent(cookieData));
+    }
+    catch {
+        return null;
+    }
+}