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

Обзор 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.