Перейти к содержанию

SDK-клиент

Для удобства разработки доступен SDK-клиент, который обеспечивает удобный программный доступ к запросам, мутациям и подпискам GraphQL-API с типизацией входных и выходных данных на TypeScript. Он упрощает программное взаимодействие с MONO, делая интеграцию максимально простой. В настоящий момент SDK-клиент доступен только на TypeScript. Если ваш проект использует другой язык, вам потребуется обратиться к документации GraphQL-API и создать собственный клиент на основе предоставленных схем данных.

SDK реализует структурированное пространство имён запросов, мутаций, подписок, и классов, необходимых для взаимодействия с MONO. Основная цель SDK - предоставить инструменты для разработчиков, которые предельно упростят интеграцию с MONO и Кооперативной Экономикой.

SDK основан на гененаторе GraphQL-Zeus, который на основании схемы данных GraphQL-API генерирует типизированный клиент доступа, упрощающий разработку и интеграцию с MONO.

Установка

pnpm install @coopenomics/sdk

// или 

yarn add @coopenomics/sdk

Как пользоваться

Для начала, нам потребуется подключенный к MONO клиент: 

import { createClient } from '@coopenomics/sdk'

// создаём клиента
const client = createClient({
  api_url: "http://127.0.0.1:2998/v1/graphql", //адрес MONO GraphQL-API
  chain_url: "https://api.coopenomics.world", //адрес конечной точки блокчейна
  chain_id: "6e37f9ac0f0ea717bfdbf57d1dd5d7f0e2d773227d9659a63bbf86eec0326c1b", //идентификатор цепочки публичной сети
});

При хостинге у ПК ВОСХОД адрес конечной точки GraphQL будет следующего формата: https://{{ domain }}/backend/v1/graphql, где domain - это имя домена, по которому доступен рабочий стол кооператива.

Созданный клиент обладает встроенными фабриками для вызова мутаций, запросов, и подписок в MONO, а также, методами для работы с блокчейном и цифровой подписью.

Для аудентификации клиента необходимо токен доступа через вызов метода:

client.setToken(<token>)

Подробнее о получении токенов доступа смотри раздел Аудентификация.

Запросы

Для того, чтобы создать запрос на получение информации из MONO, необходимо извлечь его из пространства имён Queries, выбрав соответствующий область. Пространство запроса включает в себя:

  • Интерфейс входных данных IInput
  • Интерфейс выходных данных IOutput
  • Селектор запроса query
  • Имя запроса name
  • Требуемую роль role для выполнения запроса

Все запросы выполняются типично в следующем порядке на примере извлечения аккаунта 🛠️ SDK: Queries.Accounts.GetAccount:

// импортируем пространство запросов
import { Queries } from '@coopenomics/sdk'

// формируем объект с параметрами запроса согласно интерфейсу IInput
const variables: Queries.Accounts.GetAccount.IInput = {
  data: {
    username: <string>; // Имя аккаунта пользователя
  };
};

// отправляем запрос и получаем результат в result
const { [Queries.Accounts.GetAccount.name]: result } = await client.Query(
  Queries.Accounts.GetAccount.query,
  { variables }
);

Где Queries.Accounts.GetAccount.name - это имя запроса, по ключу которого в ответе будет типизированный result в соответствии с интерфейсом Queries.Accounts.GetAccount.IOutput, а Queries.Accounts.GetAccount.query - это предварительно сформированный селектор для получения result.

Таким образом, для выполнения любого запроса необходимо только знать пространство имени в SDK и использовать данные из него для отправки запроса. В role же содержится вспомогательная информация, которая сообщает о том, какая минимальная роль пользователя допустима для совершения запроса.

Мутации

Мутация - это способ изменения данных в MONO через GraphQL-API. Мутации производятся аналогично запросам, для их проведения необходимо извлечь её из пространства имён Mutations, выбрав соответствующую область. Пространство мутации включает в себя:

  • Интерфейс входных данных IInput
  • Интерфейс выходных данных IOutput
  • Селектор мутации mutation
  • Имя мутации name
  • Требуемую роль role для выполнения мутации

Все запросы выполняются типично в следующем порядке на примере паевого взноса 🛠️ SDK: Mutations.Payments.CreateDepositPayment:

// импортируем пространство мутаций
import { Mutations } from '@coopenomics/sdk'

// формируем объект с параметрами запроса согласно интерфейсу IInput
const variables: Queries.Payments.CreateDepositPayment.IInput = {
  data: {
    username: <string>; // Имя аккаунта пользователя
    quantity: <string>; // Сумма взноса
  };
};

// отправляем мутацию и получаем результат в result
const { [Mutations.Payments.CreateDepositPayment.name]: result } = await client.Query(
  Mutations.Payments.CreateDepositPayment.mutation,
  { variables }
);
Типизированный результат исполнения мутации согласно интерфейсу Mutations.Payments.CreateDepositPayment.IOutput будет возвращен в переменной result.

Классы

Пространство имён классов содержит вспомогательные классы для работы с MONO, например, класс Blockchain отвечает за извлечение таблиц и отправку транзакций в блокчейне, класс Canvas - за извлечение собственноручной подписи пайщика в необходимом формате для MONO, класс Document - обеспечивает вычисление и восстановление цифровой подписи документов, и т.д. и т.п.

Системное пространство

Иногда при создании запросов или выполнении мутаций могут требоваться специализированные списки, которые находятся в пространстве имён Zeus. На примере мутации для изменения статуса платежа:

import { Zeus, Mutations } from '@coopenomics/sdk'


const variables: Mutations.Payments.SetPaymentStatus.IInput = {
  data: {
    id: <string>; // Идентификатор платежа, для которого устанавливается статус
    status: Zeus.PaymentStatus.PAID; // используем список статусов платежей для указания оплаченного платежа
  };
};

const { [Mutations.Payments.SetPaymentStatus.name]: result } = await client.Mutation(
  Mutations.Payments.SetPaymentStatus.mutation,
  { variables }
);

Полный набор списков доступен в документации SDK в пространстве имён Zeus.