Обзор SDK
Для удобства интеграции с MONO
доступен SDK-клиент, который обеспечивает структурированный по пространствам имён программный доступ к запросам, мутациям и подпискам GraphQL-API, а также, вспомогательным классам для работы с MONO
.
Все вызовы мутаций, запросов и подписок и ответы строго типизированы в входных и выходных данных на TypeScript. Это упрощает программное взаимодействие с MONO
, делая интеграцию максимально простой. В настоящий момент SDK-клиент доступен только на TypeScript. Если ваш проект использует другой язык, вам потребуется обратиться к документации GraphQL-API и создать собственный клиент на основе предоставленных схем данных.
Установка¶
pnpm install @coopenomics/sdk
// или
yarn add @coopenomics/sdk
Как пользоваться¶
SDK основан на гененаторе GraphQL-Zeus, который на основании схемы данных GraphQL-API генерирует типизированный клиент доступа к MONO
.
Для начала, нам потребуется подключенный к MONO
клиент:
import { Client } from '@coopenomics/sdk'
// создаём клиента
const client = Client.create({
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
Просмотреть все доступные пространства имён запросов можно в документации SDK. Все запросы составляются и выполняются типично. Рассмотрим на примере извлечения аккаунта 🛠️ 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
и использовать данные из него для составления запроса.
Мутации¶
Мутация - это способ изменения данных в MONO
через GraphQL-API. Мутации производятся аналогично запросам, для их проведения необходимо извлечь её из пространства имён Mutations
- пространство мутации с требуемым именем. Каждое пространство мутации включает в себя:
- Интерфейс входных данных
IInput
- Интерфейс выходных данных
IOutput
- Селектор мутации
mutation
- Имя мутации
name
Все мутации выполняются типично в следующем порядке на примере паевого взноса 🛠️ 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
. Доступ к классам осуществляется через пространство имён Classes
на примере класса Canvas
для извлечения собственноручной подписи пайщика:
import { Classes } from '@coopenomics/sdk'
//контейнер для собственноручной подписи пайщика
const container = document.getElementById('signature-container') as HTMLElement
//используем вспомогательный класс Canvas
const signatureCanvas = new Canvas(container, {
lineWidth: 5,
strokeStyle: '#000',
})
// ...
// Извлечение подписи в формате base64
const signature = signatureCanvas.getSignature()
console.log('Подпись в формате base64:', signature)
````
Доступные на текущий момент вспомогательные классы пространства имён Classes:
__`Blockchain`__ - отвечает за извлечение таблиц из блокчейна и отправку транзакций в блокчейн.
__`Canvas`__ - за извлечение собственноручной подписи пайщика в необходимом формате для `MONO`
__`Document`__ - за вычисление и восстановление цифровой подписи документов
__`Account`__ - за генерацию имени и ключей нового аккаунта
### Системное пространство
Иногда при создании запросов или выполнении мутаций могут требоваться специализированные списки или типы данных `MONO`, которые находятся в пространстве имён `Zeus`, т.к. генерируются автоматически с использованием GraphQL-Zeus.
На примере мутации для изменения статуса платежа:
```ts
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.