bx-rest 0.26.0 → 1.0.0

package/README.en.md

@@ -17,11 +17,13 @@ Also known as: Bitrix24 REST client, BX24 REST SDK, Bitrix24 API client, Bitrix
 - [Quick Start](#quick-start)
   - [Result modes](#result-modes)
 - [Authentication and OAuth2](#authentication-and-oauth2)
+  - [`withCredentials`](#withcredentials)
 - [Error handling](#error-handling)
 - [Usage in Angular](#usage-in-angular)
 - [SessionKeyServices](#sessionkeyservices)
 - [Usage in Vue](#usage-in-vue)
 - [Usage in React](#usage-in-react)
+- [Demo](#demo)
 - [Custom REST methods](#custom-rest-methods)
   - [Mapper](#mapper)
   - [A custom method with `simple()`](#a-custom-method-with-simple)
@@ -107,14 +109,35 @@ REST calls are lazy: the request starts when the returned `Observable` is subscr
 | Scenario | `auth.source` | `auth.key` | Behaviour |
 | --- | --- | --- | --- |
 | Access token from application state | `() => accessToken` | `auth` | Calls the function before each request and sends its value in the `auth` parameter. Recommended for OAuth2 access tokens managed by the application. |
-| Access token in local storage | `localStorage` | `auth` | Reads `localStorage["auth"]` and sends it as `auth`. |
-| Access token in a cookie | `cookies` | `auth` | Reads the `auth` cookie and sends it as `auth`. |
+| Access token in local storage | `localStorage` | `auth` | Reads `localStorage["auth"]` and sends it as `auth`. The value is fully readable by any JS on the page (including via XSS) — a good fit for local development/prototyping; for production, prefer the function-based source managed by your application. |
+| Access token in a cookie | `cookies` | `auth` | Reads the `auth` cookie via `document.cookie` and sends it as `auth`. Your own JS code reads the cookie, so it can't be `HttpOnly` — from an XSS-protection standpoint this is no safer than `localStorage`. Like the previous option, mainly useful for local development. |
 | Embedded Bitrix page / local session | `cookies` | `sessid` | Tries `window.BX.bitrix_sessid()`, the `sessid` query parameter, `localStorage.sessid`, then the `auth` cookie. Sends the resolved value as `sessid`. |
-| Incoming webhook or URL that already contains authorization | `off` | Any value | Skips credential lookup and does not add an authorization parameter. |
-| Cookie-based credential request | Any source returning a non-empty value | `OAuth2` | Does not append the resolved value to request params and enables Axios `withCredentials`. Use only when the portal and CORS policy support credential cookies. |
+| Incoming webhook, an already-authorized URL, or your own proxy | `off` | Any value | Skips credential lookup and does not add an authorization parameter — used both for webhooks (the secret is already in the URL) and for routing through your own backend proxy (the secret stays server-side, the browser never sees it). For the proxy case, if it authenticates the browser with its own session cookie, see `withCredentials` below. |
+| Cookie-based credential request | Any source returning a non-empty value | `OAuth2` | Does not append the resolved value to request params and, by default, enables Axios `withCredentials` (unless overridden by the `withCredentials` setting, see below). Use only when the portal and CORS policy support credential cookies — also keep in mind that modern browsers increasingly block third-party cookies by default. |
 
 For a regular Bitrix OAuth2 `access_token`, use `auth.key: 'auth'` and provide the current token through a function or `localStorage`. The special `auth.key: 'OAuth2'` mode is for credential cookies; it does not send an OAuth access token by itself.
 
+### `withCredentials`
+
+By default, the axios `withCredentials` option (whether to attach browser cookies to the request) is only enabled for `auth.key: 'OAuth2'`. If you need it in another case — e.g. `auth.source: 'off'` points at your own proxy, and the browser should attach *that proxy's* session cookie (not Bitrix24's) — set `withCredentials` explicitly, independent of `auth.key`:
+
+```typescript
+BXRestSettings.update({
+  auth: {
+    source: 'off',
+    key: 'auth'
+  },
+  urls: {
+    source: 'string',
+    key: 'https://your-proxy.example.com/bitrix-proxy',
+    additional_part: ''
+  },
+  withCredentials: true
+})
+```
+
+An explicit value always takes priority over the "only for `OAuth2`" rule — you can also force `withCredentials` off for `auth.key: 'OAuth2'` if you don't need it.
+
 For an incoming webhook URL, keep the full webhook path in `urls.key`, set `additional_part` to an empty string and disable additional authorization:
 
 ```typescript
@@ -381,6 +404,31 @@ export function Deals() {
 }
 ```
 
+## Demo
+
+There are three independent demo apps in [`projects/`](../) — Angular, Vue
+and React (`demo-angular`, `demo-vue`, `demo-react`). Each one has a
+connection form covering every scenario from the "Authentication and OAuth2"
+section above (not just an access token and a webhook), a Monaco-based code
+editor with real autocompletion from `bx-rest`'s own types (not a plain text
+box or a request-builder form), and a result panel that actually runs the
+code you write against your portal. The UI switches between Russian and
+English automatically based on the browser/OS language. The shared logic
+(Monaco typings, code execution, ready-made snippets, i18n) lives in
+`projects/demo-shared` — the three demos mainly differ in the integration
+style (a DI provider in Angular, a plugin in Vue, a singleton + hook in
+React — see the sections above) and, for Angular, in the UI library
+(Angular Material — the idiomatic choice for that framework).
+
+Run from the repository root:
+
+```shell
+npm run demo:bootstrap
+```
+
+Then, in any of `projects/demo-angular|demo-vue|demo-react`: `npm run dev`
+(for Angular, `npm start`). See each demo's own README for details.
+
 ## Custom REST methods
 
 `Navvy` is exported from `bx-rest`. In Angular, register the `NavvyProvider` shown above and inject `Navvy` into your custom API service. A method URL is represented as an array and is joined with dots before the request is sent.

package/README.md

@@ -1,3 +1,5 @@
+<!-- This file is generated from projects/bx-rest/README.md by `npm run sync-readme`. Do not edit directly. -->
+
 <img src="https://flagcdn.com/20x15/ru.png" width="20" height="15" alt="RU"> **Русский** | <img src="https://flagcdn.com/20x15/gb.png" width="20" height="15" alt="GB"> [English](README.en.md)
 
 # bx-rest — REST API клиент Bitrix24 для TypeScript, Angular, Vue и React
@@ -6,9 +8,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/bx-rest.svg)](https://www.npmjs.com/package/bx-rest)
 [![license](https://img.shields.io/npm/l/bx-rest.svg)](https://github.com/Aricatofuka/bx-rest/blob/main/LICENSE)
 
-`bx-rest` — SDK на TypeScript для REST API Bitrix24. Помогает вызывать методы BX24 REST, работать с токенами авторизации, sessid, OAuth2, пагинацией, мапперами и типизированными API-запросами.
-
-Также известен как: REST-клиент Bitrix24, BX24 REST SDK, API-клиент Bitrix24, Bitrix REST TypeScript библиотека.
+`bx-rest` — TypeScript SDK для работы с REST API Bitrix24. Предоставляет типизированный интерфейс для вызова REST-методов, управления авторизацией и токенами (sessid, OAuth 2.0), обработки пагинации и преобразования данных с помощью мапперов.
 
 ## Содержание
 
@@ -17,11 +17,13 @@
 - [Быстрый старт](#быстрый-старт)
   - [Режимы результата](#режимы-результата)
 - [Аутентификация и OAuth2](#аутентификация-и-oauth2)
+  - [`withCredentials`](#withcredentials)
 - [Обработка ошибок](#обработка-ошибок)
 - [Использование в Angular](#использование-в-angular)
 - [SessionKeyServices](#sessionkeyservices)
 - [Использование в Vue](#использование-в-vue)
 - [Использование в React](#использование-в-react)
+- [Демо](#демо)
 - [Кастомные REST-методы](#кастомные-rest-методы)
   - [Mapper](#mapper)
   - [Кастомный метод с `simple()`](#кастомный-метод-с-simple)
@@ -40,11 +42,21 @@ npm install bx-rest
 
 ## Требования
 
-- **Формат модулей:** `bx-rest` поставляется только в виде ES-модулей — сборки CommonJS/`require` нет. Используйте его через ESM-совместимый бандлер (Angular CLI, Vite, webpack 5+, Next.js, ...) или нативный `import()`. Обычный `require('bx-rest')` (старые конфигурации Jest без поддержки ESM, `ts-node` в режиме CJS и т.п.) пакет не разрешит.
-- **TypeScript:** разработан под TypeScript 5.5+. Рекомендуется режим `strict` — встроенная типизация опирается на него для точных типов полей.
-- **RxJS:** `rxjs` (^7.8) — обычная зависимость, поставляемая вместе с пакетом, а не `peerDependency`, поэтому конкретная версия у хоста не требуется. Каждый REST-вызов возвращает RxJS `Observable`.
-- **Фреймворки:** примеры для Angular, Vue и React ниже написаны под API Angular 18/19, Vue 3 и React 18+ (версии, на которых собирается и тестируется библиотека). Ни один из этих фреймворков не объявлен как `peerDependencies` — `bx-rest` не имеет жёсткой зависимости ни от одного из них, — но показанные паттерны DI/композиции рассчитаны именно на эти мажорные версии.
-- **Окружение:** `bx-rest` ориентирован на браузер. Источники авторизации `cookies`/`localStorage`/`sessid` и `SessionKeyServices` напрямую читают `window`, `document` и `localStorage`. В приложении с серверным рендерингом (Angular Universal, Next.js и т.п.) выполняйте эти участки кода только в браузере (например, под защитой `isPlatformBrowser`/`typeof window !== 'undefined'`), либо используйте источник авторизации, не обращающийся к браузерным глобальным объектам, например `source: () => accessToken` или `source: 'off'`.
+* **Формат модулей:** `bx-rest` поставляется только в формате ES Modules. Сборка CommonJS и поддержка `require()` не предусмотрены. Используйте пакет через ESM-совместимый бандлер (Angular CLI, Vite, webpack 5+, Next.js и др.) или нативный `import()`.
+
+* **TypeScript:** требуется TypeScript 5.5 или выше. Рекомендуется включить режим `strict`, поскольку типизация SDK рассчитана на работу со строгой проверкой типов.
+
+* **RxJS:** `rxjs` версии `^7.8` является обычной зависимостью пакета и поставляется вместе с `bx-rest`, а не объявляется как `peerDependency`. Поэтому установка отдельной версии RxJS на стороне приложения не требуется. Все REST-запросы возвращают `Observable`.
+
+* **Фреймворки:** `bx-rest` не зависит от конкретного frontend-фреймворка и не объявляет Angular, Vue или React в качестве `peerDependencies`. Примеры интеграции рассчитаны на Angular 18/19, Vue 3 и React 18+ — эти версии используются при сборке и тестировании библиотеки.
+
+* **Окружение:** `bx-rest` ориентирован преимущественно на браузерное окружение. Источники авторизации `cookies`, `localStorage`, `sessid` и `SessionKeyServices` используют браузерные API (`window`, `document`, `localStorage`). При использовании SSR (Angular Universal, Next.js и др.) такой код должен выполняться только на стороне клиента. Например, можно использовать проверки `isPlatformBrowser` / `typeof window !== 'undefined'` либо источник авторизации, не зависящий от браузерных глобальных объектов:
+
+  `source: () => accessToken`
+
+  или
+
+  `source: 'off'`.
 
 ## Быстрый старт
 
@@ -107,14 +119,35 @@ REST-вызовы ленивые: запрос начинается, когда
 | Сценарий | `auth.source` | `auth.key` | Поведение |
 | --- | --- | --- | --- |
 | Access-токен из состояния приложения | `() => accessToken` | `auth` | Вызывает функцию перед каждым запросом и отправляет её значение в параметре `auth`. Рекомендуется для OAuth2 access-токенов, которыми управляет приложение. |
-| Access-токен в local storage | `localStorage` | `auth` | Читает `localStorage["auth"]` и отправляет его как `auth`. |
-| Access-токен в куке | `cookies` | `auth` | Читает куку `auth` и отправляет её как `auth`. |
+| Access-токен в local storage | `localStorage` | `auth` | Читает `localStorage["auth"]` и отправляет его как `auth`. Значение полностью доступно любому JS на странице (в том числе через XSS) — годится для локальной разработки/прототипирования, для продакшена предпочтительнее источник-функция, управляемый приложением. |
+| Access-токен в куке | `cookies` | `auth` | Читает куку `auth` через `document.cookie` и отправляет её как `auth`. Куку читает сам JS-код, поэтому она не может быть `HttpOnly` — с точки зрения защиты от XSS это не безопаснее `localStorage`. Как и предыдущий вариант, в первую очередь удобен для локальной разработки. |
 | Встроенная страница Bitrix / локальная сессия | `cookies` | `sessid` | Пробует `window.BX.bitrix_sessid()`, query-параметр `sessid`, `localStorage.sessid`, затем куку `auth`. Отправляет полученное значение как `sessid`. |
-| Входящий вебхук или URL, уже содержащий авторизацию | `off` | Любое значение | Пропускает поиск учётных данных и не добавляет параметр авторизации. |
-| Запрос учётных данных через куки | Любой источник, возвращающий непустое значение | `OAuth2` | Не добавляет полученное значение в параметры запроса и включает `withCredentials` в Axios. Используйте только если портал и политика CORS поддерживают куки с учётными данными. |
+| Входящий вебхук, URL с авторизацией или собственный прокси | `off` | Любое значение | Пропускает поиск учётных данных и не добавляет параметр авторизации — используется и для вебхука (секрет уже в URL), и для запроса через собственный бэкенд-прокси (секрет остаётся на сервере, браузер токен не видит вообще). Для второго случая, если прокси авторизует браузер собственной cookie-сессией, см. настройку `withCredentials` ниже. |
+| Запрос учётных данных через куки | Любой источник, возвращающий непустое значение | `OAuth2` | Не добавляет полученное значение в параметры запроса и по умолчанию включает `withCredentials` в Axios (если не переопределено настройкой `withCredentials`, см. ниже). Используйте только если портал и политика CORS поддерживают куки с учётными данными — учтите также, что современные браузеры всё активнее блокируют сторонние (third-party) куки по умолчанию. |
 
 Для обычного OAuth2 `access_token` Bitrix используйте `auth.key: 'auth'` и передавайте текущий токен через функцию или `localStorage`. Специальный режим `auth.key: 'OAuth2'` предназначен для куки с учётными данными; сам по себе он не отправляет OAuth access-токен.
 
+### `withCredentials`
+
+По умолчанию axios-опция `withCredentials` (прикладывать ли браузерные куки к запросу) включается только при `auth.key: 'OAuth2'`. Если нужен другой случай — например, `auth.source: 'off'` указывает на собственный прокси, а браузер должен приложить куку сессии *этого прокси* (не Bitrix24) — задайте `withCredentials` явно в настройках, независимо от `auth.key`:
+
+```typescript
+BXRestSettings.update({
+  auth: {
+    source: 'off',
+    key: 'auth'
+  },
+  urls: {
+    source: 'string',
+    key: 'https://your-proxy.example.com/bitrix-proxy',
+    additional_part: ''
+  },
+  withCredentials: true
+})
+```
+
+Явное значение всегда имеет приоритет над правилом «включать только для `OAuth2`» — можно и принудительно выключить `withCredentials` при `auth.key: 'OAuth2'`, если он не нужен.
+
 Для URL входящего вебхука сохраните полный путь вебхука в `urls.key`, установите `additional_part` в пустую строку и отключите дополнительную авторизацию:
 
 ```typescript
@@ -381,6 +414,31 @@ export function Deals() {
 }
 ```
 
+## Демо
+
+В [`projects/`](../) есть три независимых демо-приложения — Angular, Vue и React
+(`demo-angular`, `demo-vue`, `demo-react`). Каждое: форма подключения,
+покрывающая все варианты из раздела «Аутентификация и OAuth2» выше (а не
+только access-токен и вебхук), редактор кода на Monaco с 
+автодополнением по типам `bx-rest` (а не текстовое поле или конструктор
+запроса) и панель результата, которая реально выполняет написанный код
+против вашего портала. Интерфейс переключается между русским и английским
+автоматически по языку браузера/ОС. Общая логика (типы для Monaco,
+выполнение кода, готовые примеры, i18n) вынесена в `projects/demo-shared` —
+разница между тремя демо в первую очередь в способе интеграции (DI-провайдер
+в Angular, плагин в Vue, синглтон+хук в React — см. разделы выше) и, для
+Angular, в UI-библиотеке (Angular Material — идиоматичный выбор для этого
+фреймворка).
+
+Запуск из корня репозитория:
+
+```shell
+npm run demo:bootstrap
+```
+
+Дальше в любой из `projects/demo-angular|demo-vue|demo-react`: `npm run dev`
+(для Angular — `npm start`). Подробности — в README каждого демо.
+
 ## Кастомные REST-методы
 
 `Navvy` экспортируется из `bx-rest`. В Angular зарегистрируйте показанный выше `NavvyProvider` и внедрите `Navvy` в ваш кастомный API-сервис. URL метода представлен массивом и перед отправкой запроса соединяется точками.
@@ -568,8 +626,7 @@ bxRest.crm.callList.get({ ID: 1 }, dateTimeFormat).res()
 ```
 
 ## Планы на будущее
-- Автоматическое получение токена
-- Мапперы для типов нормализации
+- Автоматическое получение токена авторизации
 
 Есть предложение по функциональности или нашли баг? Посмотрите [существующие issues](https://github.com/Aricatofuka/bx-rest/issues) или создайте новый.