@rynt/sdk 0.9.53

package/src/shared/types/API_DOCUMENTATION.md

@@ -0,0 +1,422 @@
+# API Documentation для Backend
+
+Документация сущностей системы zakLauncher для интеграции с backend API.
+
+## Общие принципы
+
+- Все даты в формате ISO 8601 (например: `2026-02-06T17:47:21.955Z`)
+- Все идентификаторы - строки (UUID или другие уникальные строки)
+- Изображения хранятся в Cloudinary, передаются полные URL
+
+---
+## 2. Build (Сборки)
+
+### Описание
+Базовая информация о сборке Minecraft. Содержит только публичные метаданные для отображения в UI и маркетплейсе.
+
+### Структура
+
+```typescript
+interface Build {
+  id: string;                    // UUID сборки
+  name: string;                  // Название сборки
+  description: string;           // Описание сборки
+  image?: string;                // URL изображения сборки (Cloudinary)
+  author: User;           // Информация об авторе
+  createdAt: string;             // Дата создания (ISO 8601)
+  updatedAt: string;            // Дата обновления (ISO 8601)
+  isPublic: boolean;            // Публичная сборка (видна в маркетплейсе)
+  downloads: number;            // Количество скачиваний
+  rating?: number;              // Рейтинг (0-5)
+  tags: string[];               // Теги сборки (например: ["adventure", "modded"])
+}
+```
+
+### Особенности
+- Сборка содержит только базовую информацию для отображения
+- Полный манифест хранится в связанной сущности `Version`
+- `image` - опциональное поле, если не указано - используется placeholder
+- `isPublic: false` - сборка видна только автору
+
+---
+
+## 3. Version (Версии сборок)
+
+### Описание
+Версия сборки содержит полный манифест сборки (JSON) и плоский блок метаданных `_meta` для удобной работы в базе данных.
+
+### Структура
+
+```typescript
+interface Version {
+  id: string;                    // UUID версии
+  buildId: string;               // ID связанной сборки (FK -> Build.id)
+  version: string;               // Номер версии (например: "1.0.0")
+  manifest: JSON;                // Полный манифест сборки (BuildVersionManifest как JSON)
+  
+  // Плоские поля из _meta (для индексации и фильтрации)
+  name: string;                  // Название из _meta.name
+  description: string;           // Описание из _meta.description
+  image: string;                 // URL изображения из _meta.image
+  releaseTime: string;           // Дата релиза из _meta.releaseTime (ISO 8601)
+  time: string;                  // Время создания из _meta.time (ISO 8601)
+  
+  // Поля из _meta.manifest
+  minecraftVersion: string;      // Версия Minecraft (например: "1.21")
+  loader: string;                // Загрузчик ("fabric", "quilt", "vanilla", etc.)
+  loaderVersion: string;         // Версия загрузчика (например: "0.18.4")
+  
+  createdAt: string;             // Дата создания записи (ISO 8601)
+  updatedAt: string;             // Дата обновления записи (ISO 8601)
+}
+```
+
+### Структура манифеста (manifest JSON)
+
+Манифест представляет собой полный объект `BuildVersionManifest`:
+
+```typescript
+interface BuildVersionManifest {
+  id: string;
+  type: string;                  // "release", "snapshot", etc.
+  inheritsFrom?: string;         // ID базовой версии Minecraft
+  arguments?: {
+    game: (string | { rules?: Rule[]; value: string | string[] })[];
+    jvm: (string | { rules?: Rule[]; value: string | string[] })[];
+  };
+  libraries: Library[];          // Список библиотек
+  mods: Mod[];                   // Список модов
+  resourcePacks: ResourcePack[]; // Список ресурс-паков
+  versionAssets: VersionAsset[]; // Кастомные ассеты
+  selectedFiles?: string[];      // Выбранные файлы
+  _meta: BuildMetadata;        // Метаданные (дублируются в плоских полях)
+  // ... другие поля манифеста
+}
+```
+
+### Особенности
+- `manifest` хранится как JSON в базе данных
+- Некоторые плоские поля из `_meta` дублируются для удобства запросов и индексации
+- При обновлении версии необходимо синхронизировать плоские поля с `manifest._meta`
+- `buildId` связывает версию с базовой информацией сборки
+- Одна сборка может иметь несколько версий
+
+---
+
+## 4. User (Пользователи системы)
+
+### Описание
+Пользователи системы zakLauncher (авторизованные через систему).
+
+### Структура
+
+```typescript
+interface User {
+  id: string;                    // UUID пользователя
+  username: string;              // Username (уникальный)
+  email: string;                 // Email (уникальный)
+  name?: string;                 // Отображаемое имя
+  avatar?: string;               // URL аватара
+  status: 'offline' | 'online';  // Статус пользователя
+  statusDetail: JSON;             // Поле, которое будет иметь необычный формат, там может быть инфа о том в какой игре находится, или на каком мероприятии
+  level: number;                 // Уровень пользователя (для геймификации)
+  
+  // Подписка и хранилище
+  subscriptionId?: string;        // ID активной подписки (FK -> Subscription.id)
+  usedStorage: number;           // Использованное место в байтах (сумма размеров всех ассетов пользователя)
+  storageQuota: number;          // Квота хранилища в байтах (из активной подписки или 50мб (лень считать сколько в байтах) для бесплатного плана)
+  
+  createdAt: string;             // Дата регистрации (ISO 8601)
+  lastSeenAt?: string;           // Дата последнего визита (ISO 8601)
+  friends: User[];               // Список друзей (загружается отдельно)
+}
+```
+
+### Особенности
+- `usedStorage` рассчитывается автоматически как сумма `size` всех ассетов, где пользователь является владельцем
+- `storageQuota` берется из активной подписки, если подписки нет - значение 0 (бесплатный план)
+- `statusDetail` может содержать JSON с информацией о текущей игре, мероприятии и т.д.
+  Пример: `{ game: "Minecraft", buildId: "uuid", server: "example.com" }`
+
+---
+
+## 5. Subscription (Подписки)
+
+### Описание
+Платные подписки пользователей с квотами на хранилище и другие функции.
+
+### Структура
+
+```typescript
+interface Subscription {
+  id: string;                    // UUID подписки
+  userId: string;                // ID пользователя (FK -> User.id)
+  planId: string;                // ID плана подписки (FK -> SubscriptionPlan.id)
+  planName: string;              // Название плана (для быстрого доступа)
+  
+  // Квоты и лимиты
+  storageQuota: number;          // Квота хранилища в байтах
+  maxBuilds?: number;            // Максимальное количество сборок (null = без ограничений)
+  maxVersionsPerBuild?: number;  // Максимальное количество версий на сборку (null = без ограничений)
+  
+  // Даты подписки
+  startedAt: string;             // Дата начала подписки (ISO 8601)
+  expiresAt: string;             // Дата окончания подписки (ISO 8601)
+  cancelledAt?: string;          // Дата отмены подписки (ISO 8601, если отменена)
+  autoRenew: boolean;             // Автопродление подписки
+  
+  // Статус
+  status: 'active' | 'expired' | 'cancelled' | 'pending';  // Статус подписки
+  isActive: boolean;             // Активна ли подписка (вычисляемое поле: status === 'active' && expiresAt > now)
+  
+  createdAt: string;             // Дата создания записи (ISO 8601)
+  updatedAt: string;             // Дата обновления записи (ISO 8601)
+}
+```
+
+### SubscriptionPlan (Планы подписок)
+
+```typescript
+interface SubscriptionPlan {
+  id: string;                    // UUID плана
+  name: string;                  // Название плана (например: "Basic", "Pro", "Premium")
+  description: string;           // Описание плана
+  price: number;                 // Цена в копейках (или минимальной валюте)
+  currency: string;              // Валюта (например: "RUB", "USD")
+  interval: 'month' | 'year';    // Интервал оплаты
+  storageQuota: number;          // Квота хранилища в байтах
+  maxBuilds?: number;            // Максимальное количество сборок
+  maxVersionsPerBuild?: number;  // Максимальное количество версий на сборку
+  features: string[];            // Список функций плана
+  isActive: boolean;             // Активен ли план для продажи
+  createdAt: string;             // Дата создания (ISO 8601)
+}
+```
+
+### Особенности
+- При создании подписки `storageQuota` копируется из плана
+- `isActive` вычисляется как `status === 'active' && expiresAt > now`
+- При истечении подписки `status` меняется на `expired`, `storageQuota` пользователя обнуляется
+- `autoRenew: true` означает автоматическое продление через платежную систему
+
+---
+
+## 6. Payment (Платежи)
+
+### Описание
+История платежей за подписки.
+
+### Структура
+
+```typescript
+interface Payment {
+  id: string;                    // UUID платежа
+  userId: string;                // ID пользователя (FK -> User.id)
+  subscriptionId: string;        // ID подписки (FK -> Subscription.id)
+  planId: string;                // ID плана подписки (FK -> SubscriptionPlan.id)
+  
+  // Информация о платеже
+  amount: number;                // Сумма в копейках (или минимальной валюте)
+  currency: string;              // Валюта (например: "RUB", "USD")
+  status: 'pending' | 'completed' | 'failed' | 'refunded';  // Статус платежа
+  
+  // Интеграция с платежной системой
+  paymentMethod: string;         // Метод оплаты (например: "card", "yookassa", "stripe")
+  externalId?: string;           // ID платежа во внешней системе
+  externalData?: JSON;           // Дополнительные данные от платежной системы
+  
+  // Даты
+  paidAt?: string;               // Дата успешной оплаты (ISO 8601)
+  refundedAt?: string;           // Дата возврата средств (ISO 8601)
+  createdAt: string;             // Дата создания платежа (ISO 8601)
+  updatedAt: string;             // Дата обновления (ISO 8601)
+}
+```
+
+### Особенности
+- `status: 'pending'` - платеж создан, ожидает оплаты
+- `status: 'completed'` - платеж успешно завершен, подписка активирована/продлена
+- `status: 'failed'` - платеж не прошел
+- `status: 'refunded'` - средства возвращены
+- `externalData` может содержать webhook данные от платежной системы
+
+---
+
+## 7. VersionAsset (Ассеты файлов сборок)
+
+### Описание
+Файлы сборок, хранящиеся в S3. Каждый файл (мод, ресурс-пак, кастомный файл) загружается в S3 и регистрируется как ассет.
+
+### Структура
+
+```typescript
+interface Asset {
+  id: string;                    // UUID ассета
+  
+  versions: Version[];             // версии, в которых этот ассет используется
+  authors: User[];               // Пользователи, которые "загружали" этот ассет (авторы версий)
+  
+  // Информация о файле
+  filename: string;               // Оригинальное имя файла
+  mimeType: string;              // MIME тип файла (например: "application/java-archive", "application/zip")
+  size: number;                  // Размер файла в байтах
+  sha1: string;                  // SHA1 хеш файла (для проверки целостности)
+  
+  // S3 информация
+  s3Key: string;                 // Ключ файла в S3 (путь)
+  s3Bucket: string;              // Бакет S3
+  s3Url: string;                 // Публичный URL файла в S3 (или presigned URL)
+  
+  createdAt: string;             // Дата загрузки (ISO 8601)
+  updatedAt: string;             // Дата обновления (ISO 8601)
+}
+```
+
+### Особенности
+- При загрузке сборки система анализирует манифест и определяет, какие файлы нужно загрузить
+- Пользователь загружает файлы, backend сохраняет их в S3 и создает записи `VersionAsset`
+- `size` используется для расчета `User.usedStorage`
+- При удалении ассета файл удаляется из S3, при удалении версий, связанные ассеты проверяются, удаляется из ассета связанная версия. Смотрится на автора версии, берём другие версии этого юзера, и смотрим есть ли в них этот ассет. Если в других версиях этого юзера этого ассета нет, то удаляем из ассета и юзера. Если выходит так, что у ассета нет привязанных других версий (от кого либо) и нет юзеров, то ассет удаляется из s3 и из базы.
+
+### Расчет использованного места
+
+`User.usedStorage` рассчитывается как сумма `size` всех ассетов, где:
+- `Asset.userId === User.id` (пользователь является владельцем)
+
+Формула: `SELECT SUM(size) FROM assets WHERE userId = ? AND isPublic = false`
+
+---
+
+## 10. Project (Проекты/Серверы)
+
+### Описание
+Проекты Minecraft (серверы, моды, ресурс-паки и т.д.).
+
+### Структура
+
+```typescript
+interface Project {
+  id: string;                    // UUID проекта
+  name: string;                  // Название проекта
+  description: string;            // Описание
+  online: number;                // Количество игроков онлайн
+  maxPlayers: number;            // Максимальное количество игроков
+  version: string;               // Версия Minecraft
+  tags: string[];                // Теги проекта
+  image?: string;                // URL изображения
+  welcomeMessage?: string;       // Приветственное сообщение
+  servers?: ProjectServer[];     // Список серверов проекта
+  events?: ProjectEvent[];       // События проекта
+  news?: ProjectNews[];          // Новости проекта
+  createdAt: string;             // Дата создания (ISO 8601)
+  updatedAt: string;             // Дата обновления (ISO 8601)
+}
+```
+
+### ProjectServer
+
+```typescript
+interface ProjectServer {
+  id: string;                    // UUID сервера
+  projectId: string;             // ID проекта (FK -> Project.id)
+  name: string;                  // Название сервера
+  address: string;               // IP адрес или домен
+  port: number;                  // Порт сервера
+  status: 'online' | 'offline';  // Статус сервера
+  buildId?: string;              // ID рекомендуемой сборки (FK -> Build.id)
+  buildName?: string;            // Название сборки (для отображения)
+  players?: number;              // Количество игроков онлайн
+  maxPlayers?: number;           // Максимальное количество игроков
+}
+```
+
+### ProjectEvent
+
+```typescript
+interface ProjectEvent {
+  id: string;                    // UUID события
+  projectId: string;             // ID проекта (FK -> Project.id)
+  title: string;                 // Заголовок события
+  description: string;           // Описание
+  date: string;                  // Дата события (ISO 8601)
+  startTime?: string;            // Время начала (ISO 8601)
+  endTime?: string;              // Время окончания (ISO 8601)
+  participants: number;          // Количество участников
+  image?: string;                // URL изображения
+  serverId?: string;             // ID сервера (FK -> ProjectServer.id)
+  isActive: boolean;             // Активно ли событие
+  createdAt: string;             // Дата создания (ISO 8601)
+}
+```
+
+### ProjectNews
+
+```typescript
+interface ProjectNews {
+  id: string;                    // UUID новости
+  projectId: string;             // ID проекта (FK -> Project.id)
+  title: string;                 // Заголовок новости
+  description: string;           // Описание
+  image?: string;                // URL изображения
+  author: string;                // Автор новости
+  date: string;                  // Дата публикации (ISO 8601)
+  createdAt: string;             // Дата создания (ISO 8601)
+}
+```
+
+## 12. Event (События)
+
+### Описание
+События, привязанные к проектам.
+
+### Структура
+
+```typescript
+interface Event {
+  id: string;                    // UUID события
+  projectId: string;              // ID проекта (FK -> Project.id)
+  title: string;                 // Заголовок
+  description: string;           // Описание
+  date: string;                  // Дата события (ISO 8601)
+  startTime?: string;            // Время начала (ISO 8601)
+  endTime?: string;              // Время окончания (ISO 8601)
+  participants: number;          // Количество участников
+  image?: string;                // URL изображения
+  serverId?: string;             // ID сервера (FK -> ProjectServer.id, опционально)
+  isActive: boolean;             // Активно ли событие
+  createdAt: string;             // Дата создания (ISO 8601)
+  updatedAt: string;             // Дата обновления (ISO 8601)
+}
+```
+
+### Особенности
+- События всегда привязаны к проекту через `projectId`
+- `serverId` опционален - событие может быть привязано к конкретному серверу проекта
+- `isActive: true` означает, что событие активно и отображается пользователям
+- `participants` обновляется при регистрации участников на событие
+
+---
+
+## Примечания
+
+1. **Безопасность**: Все токены и чувствительные данные должны быть зашифрованы
+2. **Валидация**: Все входящие данные должны валидироваться на backend
+3. **Авторизация**: Проверка прав доступа для всех операций (создание, редактирование, удаление)
+4. **Синхронизация**: При обновлении `Version.manifest` необходимо синхронизировать плоские поля с `_meta`
+5. **Изображения**: Все изображения хранятся в Cloudinary, передаются полные URL
+6. **Пагинация**: Для списков рекомендуется использовать пагинацию (limit/offset или cursor-based)
+7. **Хранилище**: 
+   - При загрузке/удалении ассета необходимо пересчитывать `User.usedStorage`
+   - Проверять квоту перед загрузкой: `usedStorage + newFileSize <= storageQuota`
+8. **Подписки**:
+   - При истечении подписки автоматически обновлять `status` на `expired`
+   - При отмене подписки устанавливать `cancelledAt` и `status: 'cancelled'`
+   - При активации новой подписки обновлять `User.storageQuota` из плана
+9. **Ассеты**:
+   - Использовать SHA1 для дедупликации файлов (один файл может использоваться несколькими версиями)
+   - При удалении ассета проверять, используется ли он другими версиями
+   - Генерировать presigned URL для безопасной загрузки/скачивания из S3
+10. **Платежи**:
+    - Webhook от платежной системы должен обновлять статус платежа и активировать подписку
+    - При успешном платеже (`status: 'completed'`) активировать/продлить подписку
+

package/src/shared/types/account.ts

@@ -0,0 +1,40 @@
+export type MinecraftAccountProvider = 'Microsoft' | 'Ely.by' | 'LittleSkin' | 'Offline' | 'Mojang';
+
+export interface MinecraftAccount {
+  id: string;
+  provider: MinecraftAccountProvider;
+  username: string;
+  uuid?: string;
+  email?: string; // Для Microsoft/Mojang
+  accessToken?: string; // Токен доступа (зашифрован)
+  refreshToken?: string; // Токен обновления (зашифрован)
+  expiresAt?: string; // Дата истечения токена
+  isActive: boolean; // Активный аккаунт для запуска
+  avatar?: string; // URL аватара
+  skinSha1?: string; // SHA1 хеш скина для кеширования рендеров
+  createdAt: string;
+  lastUsedAt?: string;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/src/shared/types/build.ts

@@ -0,0 +1,8 @@
+export interface BuildVersion {
+  id: string;
+  version: string;
+  createdAt: string;
+  publishedAt?: string;
+  description?: string;
+  size: number;
+}

package/src/shared/types/entities.ts

@@ -0,0 +1,181 @@
+import type { BuildVersionManifest } from '../minecraft-types/build-manifest';
+import type { InviteLauncherConfigPayload } from './invite-payloads';
+import type { ServerMember } from './serverMember';
+import type { UserStatusDetail } from './user';
+
+export type EntityUser = {
+  id: string;
+  username: string;
+  email: string;
+  avatar: string;
+  bio?: string;
+  status: 'online' | 'offline';
+  statusDetail: UserStatusDetail | null;
+  level: number;
+  usedStorage: number;
+  storageQuota: number;
+  lastSeenAt: string;
+  serverMemberships: EntityServerMember[];
+  friends: EntityUser[];
+};
+
+export type EntityPost = {
+  id: string;
+  server: EntityServer | null;
+  title: string;
+  description: string;
+  image: string;
+  attachments?: string[];
+  author: EntityUser;
+  date: string;
+};
+
+export type EntityEvent = {
+  id: string;
+  title: string;
+  description: string;
+  startDateTime: string;
+  endTime: string;
+  participants: number;
+  image: string | null;
+  attachments?: string[];
+  server: EntityServer;
+  isActive: boolean;
+};
+
+export type EntityServerMember = {
+  id: string;
+  server: EntityServer;
+  user: EntityUser;
+  displayName: string;
+  role: 'player' | 'moderator' | 'admin';
+  joinedAt: string;
+  invitedBy: EntityUser | null;
+};
+
+export type EntityServer = {
+  id: string;
+  name: string;
+  address: string;
+  port: number;
+  status: 'online' | 'offline';
+  /** Заполняется из GraphQL `build` или нормализуется в `buildId` в API */
+  build?: EntityBuild | null;
+  buildId?: string;
+  buildName: string;
+  players: number;
+  maxPlayers: number;
+  tags: string[];
+  allowedProviders: string[] | null;
+  image: string;
+  description: string;
+  rules: string;
+  isPublic?: boolean;
+  events: EntityEvent[];
+  members: ServerMember[];
+  /** Проект может приходить только в части доменных сценариев (лаунчер/профиль сервера). */
+  project?: { author?: { id: string } } | null;
+};
+
+/** Встроенные типы инвайта; API допускает и произвольные строки (`Invite.type` на бэкенде). */
+export type KnownEntityInviteType =
+  | 'friend'
+  | 'server'
+  | 'build'
+  | 'map'
+  | 'local_build'
+  | 'local_game'
+  | 'request_join_local';
+
+export type EntityInviteType = KnownEntityInviteType | (string & {});
+
+export type EntityInvite = {
+  id: string;
+  target: EntityUser;
+  author: EntityUser;
+  type: EntityInviteType;
+  status: 'pending' | 'accepted' | 'rejected';
+  /** Для `friend` — обычно `{}`. Для лаунчер-типов — см. `InviteLauncherConfigPayload`. */
+  config: InviteLauncherConfigPayload | Record<string, unknown> | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * Общие поля сборки для карточек и локального индекса (без обязательного графа `versions`).
+ */
+export type EntityBuildBase = {
+  id: string;
+  name: string;
+  description: string | null;
+  image: string | null;
+  minecraftVersion: string | null;
+  loader: string | null;
+  loaderVersion?: string | null;
+  uuid?: string;
+  lastPlayed?: string;
+  playTime?: number;
+  hasIssues?: boolean;
+  downloads?: number;
+  rating?: number | null;
+  author?: EntityUser | null;
+  authorPublic?: EntityUser | null;
+};
+
+/** Локальная запись из манифестов (`getBuildsList` и карточка «Мои сборки»). */
+export type EntityBuildLocal = EntityBuildBase & {
+  uuid: string;
+  loaderVersion: string;
+  hasIssues: boolean;
+};
+
+/** Сборка в graph cache (поля догружаются по мере запросов). */
+export type EntityBuild = EntityBuildBase & {
+  isPublic?: boolean;
+  managers?: EntityUser[];
+  tags?: unknown[] | null;
+  versions?: Partial<EntityVersion> | Record<string, unknown>;
+};
+
+/**
+ * Общие поля карты для карточек и локального индекса
+ */
+export type EntityMapBase = {
+  id: string;
+  name: string;
+  description: string | null;
+  image: string | null;
+  minecraftVersion: string | null;
+  mapType: 'any' | 'build';
+  buildId?: string;
+  buildName?: string;
+  version: string | null;
+  sha1: string;
+  size: number;
+  s3Url: string;
+  isPublic: boolean;
+  downloads: number;
+  manifest?: Record<string, unknown>;
+  author?: EntityUser | null;
+  authorPublic?: EntityUser | null;
+  createdAt?: string;
+};
+
+/** Карта в graph cache (поля догружаются по мере запросов). */
+export type EntityMap = EntityMapBase;
+
+export type EntityVersion = {
+  id: string;
+  build: EntityBuild;
+  version: string;
+  manifest: BuildVersionManifest;
+  name: string;
+  description: string | null;
+  image: string | null;
+  releaseTime: string | null;
+  time: string | null;
+  minecraftVersion: string;
+  loader: string;
+  loaderVersion: string | null;
+  assets: Record<string, any>[];
+};

package/src/shared/types/index.ts

@@ -0,0 +1,6 @@
+export * from './account';
+export * from './user';
+export * from './running-build';
+export * from './navigation';
+export * from './build';
+export * from './entities';