Привет! Меня зовут Сергей Востриков, я руковожу направлением Маркет и интеграций в Битрикс. Моя команда развивает решения для разработчиков тиражных решений и индивидуальных кастомизаций. Сегодня я хочу рассказать про наш новый официальный SDK под JavaScript для работы с REST API Битрикс24. Он опубликован в виде отдельного репозитория на Github и распространяется на условиях лицензии MIT. 

В этом посте — о принципах разработки SDK, наших планах по его обновлению и том, как можно повлиять на развитие инструмента. 

Принципы разработки 

Самый главный факт: мы видим наш новый SDK в качестве полной замены давно существующей JS-библиотеки https://api.bitrix24.com/api/v1, которую вы используете на фронтенде ваших приложений. Но, в отличие от нее, новый SDK можно использовать и на бекенде, если вы разрабатываете его на Node.js. 

И конечно, новый SDK изначально делался с использованием современных средств языка: под капотом — реализация через интерфейсы и объекты Promise. В SDK используются HTTP-клиент Axios и библиотека Luxon для работы с датами. Поддержан стандарт ECMAScript modules (ESM). 

Библиотека реализована на TypeScript, соответственно, используется жесткая типизация. Прокачана производительность в списочных методах с помощью AsyncGenerator. Всё, как вы любите.

import AlertIcon from '@bitrix24/b24icons-vue/button/AlertIcon';
import FileDownloadIcon from '@bitrix24/b24icons-vue/button/FileDownloadIcon';
import CompanyIcon from '@bitrix24/b24icons-vue/button/CompanyIcon';

import {
  LoggerBrowser,
  Result,
  B24Hook,
  EnumCrmEntityTypeId,
  Text, B24LangList
} from '@bitrix24/b24jssdk';
import type { IResult, ISODate } from '@bitrix24/b24jssdk';

const $logger = LoggerBrowser.build(
  'Demo: crm.items.list',
  import.meta.env?.DEV === true
);

const $b24 = new B24Hook(
  B24HookConfig
);

$b24.setLogger($logger);

Дальше расскажу, что уже есть внутри SDK — надеюсь, что вам понравится :) 

Поддержка вебхуков

В отличие от старой библиотеки, SDK поддерживает использование входящих вебхуков. А значит, локальные разработки на JS становятся ещё проще, чем раньше.

const $b24 = new B24Hook(
  B24HookConfig
);

let commands = {
  CompanyList: {
    method: 'crm.item.list',
    params: {
      entityTypeId: EnumCrmEntityTypeId.company,
      order: { id: 'desc' },
      select: ['id', 'title', 'createdTime']
    }
  }
};

let data: any;

return $b24.callBatch(
  commands,
  true
)
.then((response: Result) => {
  data = response.getData();
});

Конечно, здесь нужно оговориться, что использование вебхуков на фронтенде — это не безопасная история. Если вы предполагаете, что доступ к фронтенду имеет не только владелец вебхука, лучше вызывать его с бекенда на Node.js. 

Поддержка приложений 

Поскольку SDK можно вызывать с фронтенда, то он прекрасно работает с токенами приложений (если они встраиваются в Битрикс24 во фрейме). И это может быть как локальное, так и тиражное приложение.

const $logger = LoggerBrowser.build('MyApp', import.meta.env?.DEV === true);
let $b24: B24Frame;

initializeB24Frame()
  .then((response: B24Frame) => {
    $b24 = response;

    return $b24.callBatch({
      CompanyList: {
        method: 'crm.item.list',
        params: {
          entityTypeId: EnumCrmEntityTypeId.company,
          order: { id: 'desc' },
          select: [
            'id',
            'title',
            'createdTime'
          ]
        }
      }
    }, true);
  })
  .then((response: Result) => {
    const data = response.getData();
  });

SDK изначально автоматически обновляет OAuth-токены, если теущий access-токен “протух”. В случае использования SDK на бекенде вы можете подставить свой колбек, в который SDK будет передавать обновленные токены. А значит, вы можете организовать хранение токенов в удобном для вашего приложения виде.

Дополнительные возможности

Говоря о полной замене старой библиотеки, я, конечно, имел в виду и возможность вызова дополнительных инструментов. Для удобства сделал сравнительную табличку. Вы сможете открывать слайдеры приложения, стандартные слайдеры и специальные диалоги.

Пока что SDK открывает стандартные диалоги вроде выбора пользователя или объекта CRM, так же, как и старая библиотека. Но будем откровенны: они страшные мы планируем сделать новые диалоги в рамках официального UI Ki. 

Расширенное управление слайдерами 

В отличие от старой библиотеки, в которой был вшит белый список адресов при открытии стандартных слайдеров, новый SDK вообще не ограничивает вас в передаваемых URL. Более того, он позволяет управлять шириной таких слайдеров.

const makeOpenSliderEditCurrency = async(currencyCode: string) =>
{
	return $b24.slider.openPath(
		$b24.slider.getUrl(`/crm/configs/currency/edit/${currencyCode}/`),
		950
	)
		.then((response: StatusClose) =>
		{
			$logger.warn(response)
			if(
				!response.isOpenAtNewWindow
				&& response.isClose
			)
			{
				$logger.info("Slider is closed! Reinit the application")
				return reloadData()
			}
		})
}

Встроенный менеджер ограничения интенсивности запросов 

Новый SDK решает частую головную боль разработчиков, которые работают с REST API с фронтенда с помощью старой библиотеки, а именно - попадание в лимиты REST API по интенсивности.

В новый SDK встроен готовый менеджер, у которого есть ряд типовых настроек, в частности, под тариф Enterprise. Но вы можете и сами сформировать эти параметры при необходимости. 

$b24.getHttpClient().setRestrictionManagerParams({
  sleep: 600,
  speed: 0.01,
  amount: 30 * 5
});

Готовые хелперы 

Мы воспринимаем SDK не просто как обёртку над REST API на JS — это полноценный инструмент с множеством фич, которые упрощают разработку и ускоряют создание приложений. Это готовые методы для работы с датами, форматирования данных, получения информации о портале, валютах и так далее. 

$logger.info(
  Text.toDateTime('2012-04-12T09:53:51')
    .toFormat('HH:mm:ss y-MM-dd')
) // '09:53:51 2012-04-12'

$logger.info(Text.getDateForLog()) 
// '2012-04-12 09:53:51'

$logger.info(
  Text.toDateTime('2012-04-12 14:05:56', 'y-MM-dd HH:mm:ss')
    .toISO()
)
// '2012-04-12T14:05:56.000+03:00'

Лицензия MIT 

Поскольку SDK сам по себе — лишь часть ваших приложений и интеграций, мы изначально публиковали его на условиях лицензии MIT. Это значит, что вы можете спокойно включать этот код в состав своего ПО, копировать и  модифицировать его. Это не создаст для вас никаких юридических рисков. 

Планы 

Теперь расскажу немного о наших планах. 

Добавление типизации для параметров и результатов методов 

В отличие от SDK на PHP, который уже содержит множество оберток над методами REST API, что позволяет следить за типизацией входных параметров и полученных данных, в текущей версии SDK для JS работа с REST API пока реализована в виде ряда универсальных методов. Как вы понимаете, это значит, что вы указываете название метода, какие-то его параметры, а SDK просто транслирует это в HTTP-запрос. Но это также значит, что вы можете легко ошибиться с параметрами, и SDK пока никак не поможет разобраться с этим на этапе разработки.

Мы планируем делать обёртки над методами REST API, чтобы на уровне SDK помогать вам следить за параметрами и отдавать уже типизированные и сконвертированные в нужные форматы данные. Вы, кстати, и сами можете помочь с этим: подключиться к нашей разработке и делать обёртки над методами, которые для вас наиболее важны. Или — как минимум — оставить issue в репозитории, чтобы мы понимали, какие методы нужно поддержать в первую очередь.

Шаблоны приложений 

А следующим этапом, как и в случае с SDK для PHP, мы планируем публиковать заготовки на базе популярных фреймворков (например, Vue и React), чтобы вы могли брать их в качестве основы для создания новых приложений. Мы планируем, что заготовки можно будет использовать как для локальных, так и для тиражных приложений. Они будут доступны как уже со встроенным UI, так без него в зависимости от сценариев. Вы сможете управлять токенами многопользовательских приложений и настраивать очереди обработки событий и роботов. 

Первый такой мега-шаблон уже опубликован: https://github.com/bitrix24/app-template-automation-rules

Это полностью готовое, быстро разворачиваемое приложение, реализующее библиотеку роботов CRM. С блэкджеком менеджером очередей, фронтом на UI Kit и JS SDK, и беком на NodeJs или PHP. Вы можете посмотреть наш митап, полностью посвященный демонстрации этого шаблона https://apidocs.bitrix24.ru/meetups.html#app-template-automation-rules.

Мы не планируем на этом останавливаться. И здесь мы тоже ждём вашего участия. Как минимум — расскажите, какие именно шаблоны приложений пригодились бы вам для решения актуальных задач. Как максимум — вы можете сами поучаствовать в разработке полезного open-source проекта и поделиться собственными шаблонами с сообществом. 

Делитесь наработками на Github

Ещё раз подчеркну, что мы специально изначально выложили SDK в виде публичного репозитория. И точно так же открыто мы будем публиковать заготовки приложений. 

В отличие от изменения кода самого Битрикс24, по отношению к SDK и другим инструментам разработчика, мы только приветствуем любое участие комьюнити. Мы уже видим активность в правках документации, несмотря на то, что считается, что разработчики не любят еёе писать. Верим, что в случае с SDK тоже получится настроить совместную работу.