bx-rest 0.11.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-rest",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Bitrix24 REST API client and TypeScript SDK for Angular, Vue and browser apps",
   "keywords": [
     "bitrix",
@@ -74,6 +74,9 @@
     "./typification/disk": {
       "types": "./typification/rest/disk.d.ts"
     },
+    "./typification/event": {
+      "types": "./typification/rest/event.d.ts"
+    },
     "./typification/im": {
       "types": "./typification/rest/im.d.ts"
     },

package/request-navvy/event/offline.d.ts

@@ -0,0 +1,49 @@
+import { iBXRestEventOfflineGetResult, iBXRestEventOfflineListItem, iBXRestParamEventOfflineClear, iBXRestParamEventOfflineError, iBXRestParamEventOfflineGet, iBXRestParamEventOfflineList } from '../../typification/rest/event';
+/** Очередь офлайн-событий (`event.offline.*`). Доступна администраторам. */
+export declare class BXRestNavvyEventOffline {
+    private readonly Navvy;
+    readonly url: {
+        /** Возвращает и удаляет либо резервирует первые записи очереди. */
+        get: string[];
+        /** Возвращает страницу очереди, не меняя состояние записей. */
+        list: string[];
+        /** Удаляет обработанные записи зарезервированного пакета. */
+        clear: string[];
+        /** Помечает записи зарезервированного пакета ошибочными. */
+        error: string[];
+    };
+    /**
+     * Возвращает первые записи очереди согласно фильтру.
+     *
+     * По умолчанию метод удаляет выбранные записи. Передайте `clear: 0`, чтобы
+     * зарезервировать их и получить `process_id` для последующего вызова
+     * `clear` или `error`. Параллельные запросы получают разные наборы записей.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-offline-get.html
+     */
+    get(param?: iBXRestParamEventOfflineGet): import("../../services/navvy").NavvySimple<iBXRestEventOfflineGetResult, iBXRestEventOfflineGetResult, iBXRestParamEventOfflineGet | undefined>;
+    /**
+     * Читает одну страницу текущей очереди, не меняя состояние записей.
+     *
+     * Метод не резервирует записи и не формирует `process_id`. Размер страницы
+     * фиксирован и равен 50 записям.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-offline-list.html
+     */
+    list(param?: iBXRestParamEventOfflineList): import("../../services/navvy").NavvyPag<iBXRestEventOfflineListItem, iBXRestEventOfflineListItem, iBXRestParamEventOfflineList>;
+    /**
+     * Удаляет обработанные записи зарезервированного пакета.
+     *
+     * Без `id` и `message_id` удаляет все записи с переданным `process_id`.
+     * Если указаны оба массива, `id` имеет приоритет.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-offline-clear.html
+     */
+    clear(param: iBXRestParamEventOfflineClear): import("../../services/navvy").NavvySimple<boolean, boolean, iBXRestParamEventOfflineClear | undefined>;
+    /**
+     * Помечает записи зарезервированного пакета ошибочными.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-offline-error.html
+     */
+    error(param: iBXRestParamEventOfflineError): import("../../services/navvy").NavvySimple<boolean, boolean, iBXRestParamEventOfflineError | undefined>;
+}

package/request-navvy/event.d.ts

@@ -0,0 +1,57 @@
+import { iBXRestEventHandler, iBXRestEventUnbindResult, iBXRestParamEventBind, iBXRestParamEventUnbind, iBXRestParamEvents } from '../typification/rest/event';
+import { BXRestNavvyEventOffline } from './event/offline';
+/** Регистрация обработчиков и работа с событиями Битрикс24. */
+export declare class BXRestNavvyEvent {
+    private readonly Navvy;
+    /** Очередь офлайн-событий. Для вызовов требуются права администратора. */
+    readonly offline: BXRestNavvyEventOffline;
+    readonly url: {
+        /** Регистрирует обработчик события. */
+        bind: string[];
+        /** Возвращает зарегистрированные обработчики приложения. */
+        get: string[];
+        /** Удаляет зарегистрированный обработчик. */
+        unbind: string[];
+        /** Возвращает доступные текущему приложению события. */
+        events: string[];
+    };
+    /**
+     * Регистрирует новый обработчик события.
+     *
+     * Метод работает только в контексте авторизации приложения. URL обработчика
+     * должен быть доступен серверам Битрикс24 извне. Пользователь без прав
+     * администратора может регистрировать только онлайн-события от своего имени.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-bind.html
+     */
+    bind(param: iBXRestParamEventBind): import("../services/navvy").NavvySimple<boolean, boolean, iBXRestParamEventBind | undefined>;
+    /**
+     * Возвращает список зарегистрированных обработчиков событий.
+     *
+     * Пользователь без прав администратора получает только обработчики,
+     * зарегистрированные для него. Метод работает только в контексте авторизации
+     * приложения.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-get.html
+     */
+    get(): import("../services/navvy").NavvySimple<iBXRestEventHandler[], iBXRestEventHandler[], undefined>;
+    /**
+     * Удаляет зарегистрированный обработчик события.
+     *
+     * Пользователь без прав администратора может удалять только собственные
+     * обработчики онлайн-событий.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/event-unbind.html
+     */
+    unbind(param: iBXRestParamEventUnbind): import("../services/navvy").NavvySimple<iBXRestEventUnbindResult, iBXRestEventUnbindResult, iBXRestParamEventUnbind | undefined>;
+    /**
+     * Возвращает общий список доступных событий.
+     *
+     * `SCOPE` ограничивает результат указанным разрешением. `FULL: true`
+     * запрашивает полный список, но игнорируется при одновременной передаче
+     * `SCOPE`.
+     *
+     * @see https://apidocs.bitrix24.ru/api-reference/events/events.html
+     */
+    events(param?: iBXRestParamEvents): import("../services/navvy").NavvySimple<string[], string[], iBXRestParamEvents | undefined>;
+}

package/rest/navvy.d.ts

@@ -16,6 +16,7 @@ import { BXRestNavvyTimeMan } from '../request-navvy/timeman';
 import { BXRestNavvySocialNetWork } from '../request-navvy/socialnetwork';
 import { BXRestNavvyPull } from '../request-navvy/pull';
 import { BXRestNavvyCrm } from '../request-navvy/crm';
+import { BXRestNavvyEvent } from '../request-navvy/event';
 import { iBXRestProfile, iBXRestProfileHttp } from '../typification/rest/profile';
 export declare class BXRestNavvy {
     readonly user: BXRestNavvyUser;
@@ -35,6 +36,8 @@ export declare class BXRestNavvy {
     readonly socialNetWork: BXRestNavvySocialNetWork;
     readonly pull: BXRestNavvyPull;
     readonly crm: BXRestNavvyCrm;
+    /** Регистрация обработчиков и работа с онлайн- и офлайн-событиями. */
+    readonly event: BXRestNavvyEvent;
     readonly Navvy: Navvy;
     profile(): import("../services/navvy").NavvySimple<iBXRestProfileHttp, iBXRestProfile, undefined>;
 }

package/typification/rest/event.d.ts

@@ -0,0 +1,178 @@
+import { iBXRestPagination } from './base/api-pagination-bx';
+import { iBXRestFilterKeys } from './base/filter-generator';
+/** Режим доставки события. */
+export type iBXRestEventType = 'online' | 'offline';
+/** Дополнительные настройки обработчика события. */
+export interface iBXRestEventBindOptions {
+    /**
+     * Минимальный интервал между уведомлениями `ONOFFLINEEVENT` в секундах.
+     *
+     * Если не указан, Битрикс24 использует интервал в одну секунду.
+     */
+    minTimeout?: number;
+    /** Дополнительные настройки, поддерживаемые конкретным событием. */
+    [key: string]: unknown;
+}
+/** Параметры `event.bind`. */
+export interface iBXRestParamEventBind {
+    /** Имя события, например `ONCRMLEADADD`. */
+    event: string;
+    /** Внешний URL обработчика, доступный серверам Битрикс24. */
+    handler: string;
+    /**
+     * Идентификатор пользователя, под которым авторизуется обработчик.
+     *
+     * Если не указан, используется авторизация пользователя, действие которого
+     * привело к событию.
+     */
+    auth_type?: number;
+    /** Режим доставки. По умолчанию — `online`. */
+    event_type?: iBXRestEventType;
+    /**
+     * Ключ источника для офлайн-событий.
+     *
+     * Позволяет разделять очередь по источникам и исключать ложные срабатывания.
+     */
+    auth_connector?: string;
+    /** Дополнительные настройки регистрируемого события. */
+    options?: iBXRestEventBindOptions;
+}
+/** Зарегистрированный обработчик, возвращаемый `event.get`. */
+export interface iBXRestEventHandler {
+    /** Имя события. */
+    event: string;
+    /** URL обработчика. */
+    handler: string;
+    /** Идентификатор пользователя авторизации в исходном формате REST API. */
+    auth_type: string;
+    /** Признак офлайн-обработчика: `1` — офлайн, `0` — онлайн. */
+    offline: 0 | 1;
+}
+/** Параметры `event.unbind`. */
+export interface iBXRestParamEventUnbind {
+    /** Имя события. */
+    event: string;
+    /** URL обработчика события. */
+    handler: string;
+    /**
+     * Идентификатор пользователя авторизации.
+     *
+     * Передайте `0`, чтобы удалить обработчики с пустым `auth_type`, не затрагивая
+     * обработчики, зарегистрированные для конкретных пользователей.
+     */
+    auth_type?: number;
+    /** Режим доставки. По умолчанию — `online`. */
+    event_type?: iBXRestEventType;
+}
+/** Результат удаления обработчиков методом `event.unbind`. */
+export interface iBXRestEventUnbindResult {
+    /** Количество удаленных обработчиков. */
+    count: number;
+}
+/** Параметры получения общего списка доступных событий методом `events`. */
+export interface iBXRestParamEvents {
+    /** Разрешение, которому должны принадлежать возвращаемые события. */
+    SCOPE?: string;
+    /**
+     * Вернуть полный список событий.
+     *
+     * Игнорируется, если одновременно передан `SCOPE`.
+     */
+    FULL?: boolean;
+}
+/** Поле записи очереди, доступное для фильтрации и сортировки. */
+export type iBXRestEventOfflineField = 'ID' | 'TIMESTAMP_X' | 'EVENT_NAME' | 'MESSAGE_ID' | 'PROCESS_ID' | 'ERROR';
+/** Значение фильтра очереди офлайн-событий. */
+export type iBXRestEventOfflineFilterValue = string | number | boolean | (string | number | boolean)[];
+/**
+ * Фильтр очереди офлайн-событий.
+ *
+ * Операция указывается перед именем поля, например `=EVENT_NAME` или `>=ID`.
+ */
+export type iBXRestEventOfflineFilter = Partial<Record<`${iBXRestFilterKeys}${iBXRestEventOfflineField}`, iBXRestEventOfflineFilterValue>>;
+/** Направление сортировки очереди офлайн-событий. */
+export type iBXRestEventOfflineSortOrder = 'ASC' | 'DESC';
+/** Сортировка очереди офлайн-событий. */
+export type iBXRestEventOfflineOrder = Partial<Record<iBXRestEventOfflineField, iBXRestEventOfflineSortOrder>>;
+/** Общие параметры выборки очереди офлайн-событий. */
+export interface iBXRestParamEventOfflineSelection {
+    /** Фильтр по полям записи очереди. */
+    filter?: iBXRestEventOfflineFilter;
+    /** Сортировка по полям записи очереди. */
+    order?: iBXRestEventOfflineOrder;
+    /**
+     * Ключ источника.
+     *
+     * Должен совпадать с `auth_connector`, переданным при подписке через
+     * `event.bind`.
+     */
+    auth_connector?: string;
+}
+/** Параметры `event.offline.get`. */
+export interface iBXRestParamEventOfflineGet extends iBXRestParamEventOfflineSelection {
+    /** Максимальное количество записей. По умолчанию — `50`. */
+    limit?: number;
+    /** Удалять выбранные записи: `1` — да, `0` — зарезервировать. По умолчанию — `1`. */
+    clear?: 0 | 1;
+    /** Идентификатор процесса для повторного получения необработанных им записей. */
+    process_id?: string;
+    /** Возвращать записи, помеченные ошибочными. По умолчанию — `0`. */
+    error?: 0 | 1;
+}
+/** Параметры `event.offline.list`. */
+export interface iBXRestParamEventOfflineList extends iBXRestParamEventOfflineSelection, iBXRestPagination {
+}
+/** Запись очереди офлайн-событий. */
+export interface iBXRestEventOfflineItem {
+    /** Идентификатор записи. */
+    ID: string;
+    /** Дата и время создания записи в формате ISO 8601. */
+    TIMESTAMP_X: string;
+    /** Имя события. */
+    EVENT_NAME: string;
+    /** Данные события в исходном формате REST API. */
+    EVENT_DATA: unknown;
+    /** Дополнительные данные события в исходном формате REST API. */
+    EVENT_ADDITIONAL: unknown;
+    /** Идентификатор сообщения. */
+    MESSAGE_ID: string;
+}
+/** Запись, возвращаемая методом `event.offline.list`. */
+export interface iBXRestEventOfflineListItem extends iBXRestEventOfflineItem {
+    /** Идентификатор процесса, зарезервировавшего запись; пустая строка, если запись свободна. */
+    PROCESS_ID: string;
+    /** Признак ошибки обработки в исходном формате REST API. */
+    ERROR: '0' | '1';
+}
+/** Результат `event.offline.get`. */
+export interface iBXRestEventOfflineGetResult {
+    /**
+     * Идентификатор зарезервированного пакета.
+     *
+     * Возвращается при `clear: 0`; при немедленной очистке имеет значение `null`.
+     */
+    process_id: string | null;
+    /** Выбранные записи очереди. */
+    events: iBXRestEventOfflineItem[];
+}
+/** Параметры `event.offline.clear`. */
+export interface iBXRestParamEventOfflineClear {
+    /** Идентификатор пакета, полученный от `event.offline.get` при `clear: 0`. */
+    process_id: string;
+    /**
+     * Идентификаторы записей для удаления.
+     *
+     * Если не указаны, удаляются все записи пакета. Имеют приоритет над
+     * `message_id`.
+     */
+    id?: (string | number)[];
+    /** Значения `MESSAGE_ID` удаляемых записей. */
+    message_id?: (string | number)[];
+}
+/** Параметры `event.offline.error`. */
+export interface iBXRestParamEventOfflineError {
+    /** Идентификатор процесса, обрабатывающего записи. */
+    process_id: string;
+    /** Значения `MESSAGE_ID` записей, которые нужно пометить ошибочными. */
+    message_id?: (string | number)[];
+}