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

SDK

SDK

Для удобства интеграции с ЦК доступен SDK-клиент, который обеспечивает структурированный по пространствам имён программный доступ к запросам, мутациям и подпискам GraphQL-API, а также, вспомогательным классам для работы.

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

Установка

pnpm install @coopenomics/sdk

// или 

yarn add @coopenomics/sdk
npm install @coopenomics/sdk

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

SDK основан на гененаторе GraphQL-Zeus, который на основании схемы данных GraphQL-API генерирует типизированный клиент доступа к ЦК.

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

import { Client } from '@coopenomics/sdk'

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

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

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

client.setToken(<token>)

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

Запросы

Для того, чтобы создать запрос на получение информации из ЦК, необходимо извлечь его из пространства имён 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 и использовать данные из него для составления запроса.

Мутации

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

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

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

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

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

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

Классы

Пространство имён классов содержит вспомогательные классы для работы с ЦК. Доступ к классам осуществляется через пространство имён 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 - за извлечение собственноручной подписи пайщика в необходимом формате для ЦК Document - за вычисление и восстановление цифровой подписи документов Account - за генерацию имени и ключей нового аккаунта

Константы

Иногда при создании запросов или выполнении мутаций могут требоваться специализированные списки или типы данных ЦК, которые находятся в пространстве имён Zeus, т.к. генерируются автоматически с использованием GraphQL-Zeus из схемы. Для их извлечения необходимо импортировать Zeus из SDK и обратиться к элементу списку схемы. На примере мутации для изменения статуса платежа:

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.