bx-rest 0.11.1 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-rest",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Bitrix24 REST API client and TypeScript SDK for Angular, Vue and browser apps",
   "keywords": [
     "bitrix",
@@ -68,6 +68,9 @@
     "./typification/calendar": {
       "types": "./typification/rest/calendar.d.ts"
     },
+    "./typification/common": {
+      "types": "./typification/rest/common.d.ts"
+    },
     "./typification/department": {
       "types": "./typification/rest/department.d.ts"
     },

package/request-navvy/access.d.ts

@@ -0,0 +1,12 @@
+import { iBXRestAccessNameResult, iBXRestParamAccessName } from '../typification/rest/common';
+/** Получение сведений о кодах доступа (`access.*`). */
+export declare class BXRestNavvyAccess {
+    private readonly Navvy;
+    /**
+     * Возвращает человекочитаемые названия переданных кодов доступа.
+     *
+     * Например, `{ ACCESS: ['G2', 'AU'] }` вернет описания прав для всех
+     * посетителей и всех авторизованных пользователей.
+     */
+    name(param: iBXRestParamAccessName): import("../services/navvy").NavvySimple<iBXRestAccessNameResult, iBXRestAccessNameResult, iBXRestParamAccessName | undefined>;
+}

package/request-navvy/app/option.d.ts

@@ -0,0 +1,19 @@
+import { iBXRestOptionGetResult, iBXRestParamAppOptionGet, iBXRestParamAppOptionSet } from '../../typification/rest/app';
+/** Общие настройки текущего приложения (`app.option.*`). */
+export declare class BXRestNavvyAppOption {
+    private readonly Navvy;
+    /**
+     * Сохраняет или обновляет общие настройки приложения.
+     *
+     * Метод работает только в контексте приложения и требует прав администратора.
+     * Пустой объект `options` приводит к ошибке `ArgumentNullException`.
+     */
+    set(param: iBXRestParamAppOptionSet): import("../../services/navvy").NavvySimple<boolean, boolean, iBXRestParamAppOptionSet | undefined>;
+    /**
+     * Возвращает одну настройку приложения или все настройки сразу.
+     *
+     * Если `option` не указан, возвращаются все свойства, сохраненные через
+     * `app.option.set`. Метод работает только в контексте приложения.
+     */
+    get(param?: iBXRestParamAppOptionGet): import("../../services/navvy").NavvySimple<iBXRestOptionGetResult, iBXRestOptionGetResult, iBXRestParamAppOptionGet | undefined>;
+}

package/request-navvy/app.d.ts

@@ -1,8 +1,16 @@
 import { iBXRestAppInfo, iBXRestAppInfoHttp } from '../typification/rest/app';
+import { BXRestNavvyAppOption } from './app/option';
+/** Информация и общие настройки текущего приложения (`app.*`). */
 export declare class BXRestNavvyApp {
     private readonly Navvy;
+    /** Общие настройки приложения. */
+    readonly option: BXRestNavvyAppOption;
     /**
-     * Показ информации о приложении. Метод поддерживает безопасный вызов
+     * Возвращает информацию о текущем приложении и лицензии портала.
+     *
+     * Метод не принимает параметров, работает только в контексте приложения и
+     * доступен любому пользователю. Результат содержит код, версию, статус,
+     * состояние оплаты и сведения о тарифе.
      */
     info(): import("../services/navvy").NavvySimple<iBXRestAppInfoHttp, iBXRestAppInfo, undefined>;
 }

package/request-navvy/feature.d.ts

@@ -0,0 +1,12 @@
+import { iBXRestFeatureAvailability, iBXRestParamFeatureGet } from '../typification/rest/common';
+/** Проверка доступности возможностей портала (`feature.*`). */
+export declare class BXRestNavvyFeature {
+    private readonly Navvy;
+    /**
+     * Проверяет доступность указанной возможности на текущем портале.
+     *
+     * Поддерживаемые коды: `rest_offline_extended` и `rest_auth_connector`.
+     * В поле `value` сервер возвращает `Y` или `N`.
+     */
+    get(param: iBXRestParamFeatureGet): import("../services/navvy").NavvySimple<iBXRestFeatureAvailability, iBXRestFeatureAvailability, iBXRestParamFeatureGet | undefined>;
+}

package/request-navvy/method.d.ts

@@ -0,0 +1,11 @@
+import { iBXRestMethodAvailability, iBXRestParamMethodGet } from '../typification/rest/common';
+/** Проверка существования и доступности REST-методов (`method.*`). */
+export declare class BXRestNavvyMethod {
+    private readonly Navvy;
+    /**
+     * Проверяет, существует ли метод на портале и доступен ли он приложению.
+     *
+     * Передавайте имя метода в нижнем регистре, например `{ name: 'user.get' }`.
+     */
+    get(param: iBXRestParamMethodGet): import("../services/navvy").NavvySimple<iBXRestMethodAvailability, iBXRestMethodAvailability, iBXRestParamMethodGet | undefined>;
+}

package/request-navvy/server.d.ts

@@ -3,5 +3,12 @@ export declare class BXRestNavvyServer {
         time: string[];
     };
     private readonly Navvy;
+    /**
+     * Возвращает текущее время сервера как объект `Date`.
+     *
+     * Исходный ответ REST API имеет формат ISO 8601
+     * `YYYY-MM-DDThh:mm:ss±hh:mm`; получить его без преобразования можно через
+     * `resVanilla()` у возвращаемого навигатора.
+     */
     time(): import("../services/navvy").NavvySimple<string, Date, undefined>;
 }

package/request-navvy/user/option.d.ts

@@ -0,0 +1,20 @@
+import { iBXRestOptionGetResult } from '../../typification/rest/app';
+import { iBXRestParamUserOptionGet, iBXRestParamUserOptionSet } from '../../typification/rest/user';
+/** Персональные настройки текущего пользователя (`user.option.*`). */
+export declare class BXRestNavvyUserOption {
+    private readonly Navvy;
+    /**
+     * Сохраняет или обновляет настройки текущего пользователя для приложения.
+     *
+     * Метод работает только в контексте приложения. Пустой объект `options`
+     * приводит к ошибке `ArgumentNullException`.
+     */
+    set(param: iBXRestParamUserOptionSet): import("../../services/navvy").NavvySimple<boolean, boolean, iBXRestParamUserOptionSet | undefined>;
+    /**
+     * Возвращает одну пользовательскую настройку или все настройки сразу.
+     *
+     * Если `option` не указан, возвращаются все свойства, сохраненные через
+     * `user.option.set`. Метод работает только в контексте приложения.
+     */
+    get(param?: iBXRestParamUserOptionGet): import("../../services/navvy").NavvySimple<iBXRestOptionGetResult, iBXRestOptionGetResult, iBXRestParamUserOptionGet | undefined>;
+}

package/request-navvy/user.d.ts

@@ -1,5 +1,6 @@
-import { iBXRestParamUserGet, iBXRestParamUserSearch, iBXRestUser, iBXRestUserHttp, iBXRestUserHttpField } from '../typification/rest/user';
+import { iBXRestParamUserGet, iBXRestParamUserAccess, iBXRestParamUserSearch, iBXRestUser, iBXRestUserHttp, iBXRestUserHttpField } from '../typification/rest/user';
 import { BXRestNavvyUserUserfield } from './user/userfield';
+import { BXRestNavvyUserOption } from './user/option';
 export declare class BXRestNavvyUser {
     def: {
         params: {
@@ -17,12 +18,26 @@ export declare class BXRestNavvyUser {
         fields: string[];
     };
     readonly userField: BXRestNavvyUserUserfield;
+    /** Персональные настройки текущего пользователя для приложения. */
+    readonly option: BXRestNavvyUserOption;
     private readonly Navvy;
+    /**
+     * Проверяет, может ли текущий пользователь управлять настройками приложений.
+     *
+     * Возвращает `true` для пользователя с соответствующими административными
+     * правами и `false` в остальных случаях.
+     */
     admin(): import("../services/navvy").NavvySimple<boolean, boolean, undefined>;
     get(params?: iBXRestParamUserGet): import("../services/navvy").NavvyPag<iBXRestUserHttp, iBXRestUser, iBXRestParamUserGet>;
     current(): import("../services/navvy").NavvySimple<iBXRestUserHttp, iBXRestUser, undefined>;
     search(params: iBXRestParamUserSearch): import("../services/navvy").NavvyPag<iBXRestUserHttp, iBXRestUser, iBXRestParamUserSearch>;
-    access(params: string[]): import("../services/navvy").NavvySimple<boolean, boolean, string[] | undefined>;
+    /**
+     * Проверяет наличие хотя бы одного из указанных кодов доступа.
+     *
+     * Для обратной совместимости можно передать как объект
+     * `{ ACCESS: ['G2', 'AU'] }`, так и непосредственно массив кодов.
+     */
+    access(params: iBXRestParamUserAccess | string[]): import("../services/navvy").NavvySimple<boolean, boolean, iBXRestParamUserAccess | undefined>;
     fields(): import("../services/navvy").NavvySimple<iBXRestUserHttpField, iBXRestUserHttpField, undefined>;
     private setDefParam;
 }

package/rest/navvy.d.ts

@@ -18,6 +18,10 @@ 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';
+import { BXRestNavvyMethod } from '../request-navvy/method';
+import { BXRestNavvyAccess } from '../request-navvy/access';
+import { BXRestNavvyFeature } from '../request-navvy/feature';
+import { iBXRestParamScope } from '../typification/rest/common';
 export declare class BXRestNavvy {
     readonly user: BXRestNavvyUser;
     readonly lists: BXRestNavvyLists;
@@ -38,6 +42,25 @@ export declare class BXRestNavvy {
     readonly crm: BXRestNavvyCrm;
     /** Регистрация обработчиков и работа с онлайн- и офлайн-событиями. */
     readonly event: BXRestNavvyEvent;
+    /** Проверка существования и доступности REST-методов. */
+    readonly method: BXRestNavvyMethod;
+    /** Получение описаний кодов доступа. */
+    readonly access: BXRestNavvyAccess;
+    /** Проверка доступности возможностей портала. */
+    readonly feature: BXRestNavvyFeature;
     readonly Navvy: Navvy;
+    /**
+     * Возвращает базовую информацию о текущем пользователе без scope `user`.
+     *
+     * Результат содержит идентификатор, имя, фамилию, признак администратора,
+     * пол, часовой пояс и связанные поля профиля.
+     */
     profile(): import("../services/navvy").NavvySimple<iBXRestProfileHttp, iBXRestProfile, undefined>;
+    /**
+     * Возвращает разрешения текущего приложения.
+     *
+     * Передайте `{ full: true }`, чтобы запросить полный список разрешений
+     * портала. Без параметров возвращаются разрешения, доступные приложению.
+     */
+    scope(param?: iBXRestParamScope): import("../services/navvy").NavvySimple<string[], string[], iBXRestParamScope | undefined>;
 }

package/typification/rest/app/info.d.ts

@@ -1,17 +1,33 @@
 import { iBXRestYesNo } from '../base/yes-no';
 export interface iBXRestAppInfo extends iBXRestAppInfoBase {
+    /** Локальный идентификатор приложения на портале. */
     ID: number;
+    /** Истек ли оплаченный или пробный период. */
     PAYMENT_EXPIRED: boolean;
 }
 export interface iBXRestAppInfoHttp extends iBXRestAppInfoBase {
-    ID: string;
+    /** Локальный идентификатор приложения в исходном формате REST API. */
+    ID: string | number;
+    /** Признак окончания оплаченного или пробного периода. */
     PAYMENT_EXPIRED: iBXRestYesNo;
 }
 export interface iBXRestAppInfoBase {
-    VERSION: 1;
+    /** Код приложения. */
+    CODE: string;
+    /** Установленная версия приложения. */
+    VERSION: number;
+    /** Статус: бесплатное, демо, пробное, платное, локальное или подписное. */
     STATUS: 'F' | 'D' | 'T' | 'P' | 'L' | 'S';
+    /** Завершена ли установка приложения. */
     INSTALLED: boolean;
-    DAYS: null;
-    LICENSE: // Обозначение тарифа с указанием региона в виде префикса.Состоит из базового языка портала и идентификатора тарифного плана. В случае с тарифами, состав которых менялся при сохранении публичного наименования (как CRM+, Команда и Компания), понять, какой именно тариф действует по этому полю нельзя. Примеры вариантов значений:
-    'ru_project' | 'ru_basic' | 'ru_std' | 'ru_pro100' | 'ru_ent250' | 'ru_ent500' | 'ru_ent1000' | 'ru_ent2000' | 'ru_ent10000';
+    /** Количество дней до конца оплаченного или пробного периода. */
+    DAYS: number | null;
+    /** Базовый язык портала. */
+    LANGUAGE_ID: string;
+    /** Тариф с региональным префиксом, например `ru_ent10000`. */
+    LICENSE: string;
+    /** Идентификатор тарифного плана без регионального префикса. */
+    LICENSE_TYPE: string;
+    /** Семейство тарифного плана. */
+    LICENSE_FAMILY: string;
 }

package/typification/rest/app/option.d.ts

@@ -0,0 +1,18 @@
+/** Значение, которое можно сохранить в настройках приложения. */
+export type iBXRestOptionValue = string | number | boolean | null | iBXRestOptionValue[] | {
+    [key: string]: iBXRestOptionValue;
+};
+/** Набор именованных настроек приложения или пользователя. */
+export type iBXRestOptionValues = Record<string, iBXRestOptionValue>;
+/** Параметры `app.option.set`. */
+export interface iBXRestParamAppOptionSet {
+    /** Настройки: ключ — имя свойства, значение — сохраняемые данные. */
+    options: iBXRestOptionValues;
+}
+/** Параметры `app.option.get`. */
+export interface iBXRestParamAppOptionGet {
+    /** Имя свойства. Если не указано, метод вернет все настройки приложения. */
+    option?: string;
+}
+/** Результат чтения одной настройки или всего набора настроек. */
+export type iBXRestOptionGetResult = iBXRestOptionValue | iBXRestOptionValues;

package/typification/rest/app.d.ts

@@ -2,3 +2,4 @@
  * Файл для возможности импорта интерфейсов данного пакета в локальные проекты
  */
 export * from './app/info';
+export * from './app/option';

package/typification/rest/common.d.ts

@@ -0,0 +1,56 @@
+/** Параметры проверки REST-метода через `method.get`. */
+export interface iBXRestParamMethodGet {
+    /** Имя метода в нижнем регистре, например `user.get`. */
+    name: string;
+}
+/** Результат проверки REST-метода через `method.get`. */
+export interface iBXRestMethodAvailability {
+    /** Метод существует на портале. */
+    isExisting: boolean;
+    /** Метод доступен с текущими разрешениями приложения. */
+    isAvailable: boolean;
+}
+/** Параметры получения разрешений через `scope`. */
+export interface iBXRestParamScope {
+    /** Вернуть полный список разрешений портала, а не только разрешения приложения. */
+    full?: boolean;
+}
+/** Параметры получения названий кодов доступа через `access.name`. */
+export interface iBXRestParamAccessName {
+    /** Коды доступа, например `G2` и `AU`. */
+    ACCESS: string[];
+}
+/** Описание кода доступа, возвращаемое методом `access.name`. */
+export interface iBXRestAccessDescription {
+    /** Название поставщика права. */
+    provider: string;
+    /** Человекочитаемое название права. */
+    name: string;
+    /** Идентификатор поставщика права. */
+    provider_id: string;
+}
+/** Результат `access.name`, индексированный исходными кодами доступа. */
+export type iBXRestAccessNameResult = Record<string, iBXRestAccessDescription>;
+/** Поддерживаемые документацией коды `feature.get`. */
+export type iBXRestFeatureCode = 
+/** Доступность офлайн-событий. */
+'rest_offline_extended'
+/** Доступность ключа `auth_connector` в событиях. */
+ | 'rest_auth_connector';
+/** Параметры проверки функционала через `feature.get`. */
+export interface iBXRestParamFeatureGet {
+    /** Код проверяемой возможности портала. */
+    CODE: iBXRestFeatureCode;
+}
+/** Основной результат проверки функционала через `feature.get`. */
+export interface iBXRestFeatureAvailabilityBase {
+    /** Признак наличия функционала: `Y` — доступен, `N` — недоступен. */
+    value: 'Y' | 'N';
+}
+/**
+ * Результат проверки функционала через `feature.get`.
+ *
+ * Коробочная версия может дополнительно вернуть языковой флаг, например
+ * `ru_selfhosted`; `lang` в документации заменяется кодом языка портала.
+ */
+export type iBXRestFeatureAvailability = iBXRestFeatureAvailabilityBase & Partial<Record<`${string}_selfhosted`, 'Y' | 'N'>>;

package/typification/rest/profile.d.ts

@@ -1,16 +1,25 @@
 export interface iBXRestProfileHttp extends iBXRestProfileBase {
+    /** Идентификатор пользователя в исходном строковом формате REST API. */
     ID: string;
 }
 export interface iBXRestProfile extends iBXRestProfileBase {
+    /** Числовой идентификатор текущего пользователя. */
     ID: number;
 }
 interface iBXRestProfileBase {
+    /** Может ли пользователь управлять настройками портала. */
     ADMIN: boolean;
+    /** Фамилия пользователя. */
     LAST_NAME: string;
+    /** Имя пользователя. */
     NAME: string;
+    /** Пол пользователя в формате Битрикс24. */
     PERSONAL_GENDER: 'M' | 'F' | '';
-    PERSONAL_PHOTO: string;
-    TIME_ZONE: number | null;
-    TIME_ZONE_OFFSET: string;
+    /** URL фотографии, если она присутствует в ответе портала. */
+    PERSONAL_PHOTO?: string;
+    /** Название часового пояса; может быть пустой строкой. */
+    TIME_ZONE: string;
+    /** Смещение часового пояса, если оно присутствует в ответе портала. */
+    TIME_ZONE_OFFSET?: string;
 }
 export {};

package/typification/rest/user/option.d.ts

@@ -0,0 +1,16 @@
+import { iBXRestOptionValues } from '../app/option';
+/** Параметры `user.option.set`. */
+export interface iBXRestParamUserOptionSet {
+    /** Настройки: ключ — имя свойства, значение — данные текущего пользователя. */
+    options: iBXRestOptionValues;
+}
+/** Параметры `user.option.get`. */
+export interface iBXRestParamUserOptionGet {
+    /** Имя свойства. Если не указано, метод вернет все настройки пользователя. */
+    option?: string;
+}
+/** Параметры проверки прав текущего пользователя через `user.access`. */
+export interface iBXRestParamUserAccess {
+    /** Один или несколько кодов доступа, наличие которых требуется проверить. */
+    ACCESS: string | string[];
+}

package/typification/rest/user.d.ts

@@ -6,3 +6,4 @@ export * from './user/get';
 export * from './user/search';
 export * from './user/userFilter';
 export * from './user/userfield/list';
+export * from './user/option';