# 🔌 @coopenomics/sdk

> TypeScript SDK для типобезопасной работы с GraphQL API кооператива

## Описание

`@coopenomics/sdk` — клиентская библиотека для программного взаимодействия с API платформы «Цифровой Кооператив». Обеспечивает полную типизацию запросов, мутаций и подписок через [GraphQL Zeus](https://github.com/graphql-editor/graphql-zeus). Включает классы для работы с блокчейном EOSIO, цифровыми подписями, генерацией документов и JWT-аутентификацией.

📖 Документация: [цифровой-кооператив.рф/sdk](https://цифровой-кооператив.рф/sdk)

## Возможности

- **Типобезопасные запросы** — все GraphQL-запросы и мутации полностью типизированы через Zeus-селекторы
- **Блокчейн-операции** — подпись транзакций, работа с аккаунтами и ключами EOSIO (`@wharfkit`)
- **Документооборот** — генерация, подпись и верификация юридических документов
- **Голосование** — участие в голосованиях совета кооператива
- **Подписки в реальном времени** — WebSocket-подписки на события через `graphql-ws`
- **JWT-аутентификация** — управление токенами доступа
- **Canvas** — утилиты для генерации визуальных представлений

## Установка

```bash
pnpm install --filter @coopenomics/sdk

# Для внешних проектов:
pnpm add @coopenomics/sdk
```

## Быстрый старт

```typescript
import { Client } from '@coopenomics/sdk'

const client = new Client({
  api_url: '<CONTROLLER_API_URL>/v1/graphql',
  chain_url: '<CHAIN_ENDPOINT>',
  chain_id: '<CHAIN_ID>',
})

// Установка JWT-токена
client.setToken('<jwt_token>')

// Выполнение типизированного запроса
const result = await client.Query(Queries.GetSystemInfo, {})
```

## Скрипты

| Скрипт | Описание |
|--------|----------|
| `pnpm run build` | Сборка библиотеки (`unbuild`, с предварительной проверкой типов) |
| `pnpm run dev` | Режим разработки (`unbuild --stub`) |
| `pnpm run test` | Запуск тестов (`vitest`, таймаут 60 сек) |
| `pnpm run lint` | Проверка кода (`ESLint`) |
| `pnpm run typecheck` | Проверка типов TypeScript (`tsc --noEmit`) |
| `pnpm run docs` | Генерация документации (`TypeDoc` + автокомментарии) |

> Все скрипты запускаются из корня монорепозитория через фильтр: `pnpm --filter @coopenomics/sdk run <скрипт>`

## Конфигурация

SDK не требует `.env` файлов — параметры передаются при создании клиента:

| Параметр | Описание |
|----------|----------|
| `api_url` | URL GraphQL API контроллера |
| `chain_url` | URL блокчейн-ноды |
| `chain_id` | Идентификатор цепочки блоков |

## Архитектура

```
src/
├── classes/               # Высокоуровневые классы
│   ├── account.ts         # Работа с аккаунтами
│   ├── blockchain.ts      # Блокчейн-операции
│   ├── canvas.ts          # Визуальные утилиты
│   ├── crypto.ts          # Криптографические операции
│   ├── document.ts        # Документооборот
│   └── vote.ts            # Голосование
├── mutations/             # Типизированные мутации (Zeus selectors)
├── queries/               # Типизированные запросы (Zeus selectors)
├── selectors/             # Переиспользуемые селекторы по доменам
│   ├── system/            # Системные запросы
│   ├── registration/      # Регистрация
│   ├── wallet/            # Кошелёк
│   ├── gateway/           # Платежи
│   ├── documents/         # Документы
│   ├── decisions/         # Решения совета
│   ├── meet/              # Собрания
│   ├── ledger/            # Бухгалтерия
│   ├── extensions/        # Расширения
│   └── ...                # Другие домены
├── types/                 # Типы и интерфейсы клиента
│   ├── client/            # Опции подключения
│   ├── blockchain/        # Блокчейн-типы
│   ├── controller/        # Типы контроллера
│   └── document/          # Типы документов
├── zeus/                  # Сгенерированный клиент GraphQL Zeus
└── index.ts               # Точка входа (экспорт Client)
```

Селекторы генерируются из GraphQL-схемы контроллера с помощью `graphql-zeus`. Каждый селектор валидируется через `MakeAllFieldsRequired` для гарантии полноты полей.

## Тестирование

```bash
pnpm --filter @coopenomics/sdk run test
```

Проект содержит 4 интеграционных теста на `vitest` с таймаутом 60 секунд, проверяющих корректность работы клиента с API.

## Лицензия

[BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)