gitverse-api-sdk 4.0.1 → 5.0.0

package/README.md

@@ -3,21 +3,41 @@
 [![npm version](https://img.shields.io/npm/v/gitverse-api-sdk.svg)](https://www.npmjs.com/package/gitverse-api-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://gitverse.ru/rainypixel/gitverse-sdk)
-[![GitVerse API](https://img.shields.io/badge/GitVerse%20API-v22.0.0-blue.svg)](https://gitverse.ru)
+[![GitVerse API](https://img.shields.io/badge/GitVerse%20API-v1.1-blue.svg)](https://gitverse.ru)
 
 Полнофункциональный TypeScript SDK для GitVerse API с поддержкой всех эндпоинтов, обработкой Rate Limits и версионирования.
 
-> **Совместимость:** SDK синхронизирован с GitVerse API v22.0.0 (обновлено: 06.11.2025)
+> **Совместимость:** SDK синхронизирован с GitVerse OpenAPI v1.1
+
+## ⚠️ Breaking Changes в v4.0.0
+
+В версии 4.0.0 произошла реструктуризация API модулей:
+
+- **Удалены отдельные модули**: `branches`, `collaborators`, `commits`, `contents`, `forks`, `git`
+- **Консолидированы в `repos`**: Все методы теперь доступны через `client.repos.*`
+
+**Миграция:**
+```typescript
+// До v4.0.0
+await client.branches.list('owner', 'repo');
+await client.contents.get('owner', 'repo', 'path');
+await client.forks.create('owner', 'repo');
+
+// После v4.0.0
+await client.repos.listBranches('owner', 'repo');
+await client.repos.getContent('owner', 'repo', 'path');
+await client.repos.createFork('owner', 'repo');
+```
 
 ## Ключевые особенности
 
-- ✅ **100% покрытие API** — Все 91 эндпоинт GitVerse API поддерживаются
-- ✅ **Rate Limits** — Автоматическая обработка лимитов запросов с информативными ошибками
-- ✅ **Версионирование API** — Предупреждения об устаревших версиях API
-- ✅ **Специализированные ошибки** — `RateLimitError`, `ApiVersionWarning` для точной обработки
+- ✅ **Полное покрытие API** — Все эндпоинты GitVerse OpenAPI v1.1
+- ✅ **Rate Limits** — Автоматическая обработка лимитов запросов
+- ✅ **Версионирование API** — Предупреждения об устаревших версиях
+- ✅ **Специализированные ошибки** — `RateLimitError`, `ApiVersionWarning`
 - ✅ **100% покрытие тестами** — Полное тестирование всех методов
 - ✅ **Нет зависимостей** — Только нативный `fetch` API и `Buffer`
-- ✅ **Tree-shakable** — Модульная архитектура для минимального размера бандла
+- ✅ **Tree-shakable** — Модульная архитектура
 - ✅ **TypeScript** — Полная типизация из коробки
 
 ## Установка
@@ -41,11 +61,10 @@ bun add gitverse-api-sdk
 ```typescript
 import { GitVerse } from 'gitverse-api-sdk';
 
-// Создание клиента с токеном
 const client = new GitVerse({ token: 'your-token-here' });
 
 // Получение информации о текущем пользователе
-const user = await client.users.getCurrent();
+const user = await client.users.getAuthenticated();
 console.log(user.login);
 
 // Получение репозитория
@@ -63,8 +82,6 @@ const pr = await client.pulls.create('owner', 'repo', {
 
 ## Обработка Rate Limits
 
-SDK автоматически отслеживает лимиты запросов и предоставляет подробную информацию при их превышении:
-
 ```typescript
 import { GitVerse, RateLimitError } from 'gitverse-api-sdk';
 
@@ -77,169 +94,99 @@ try {
     console.log(`Rate limit exceeded!`);
     console.log(`Limit: ${error.rateLimit.limit}`);
     console.log(`Remaining: ${error.rateLimit.remaining}`);
-    console.log(`Reset at: ${new Date(error.rateLimit.reset * 1000)}`);
-
-    // Ожидание сброса лимита
-    const waitTime = error.rateLimit.reset * 1000 - Date.now();
-    await new Promise(resolve => setTimeout(resolve, waitTime));
+    console.log(`Retry after: ${error.rateLimit.retryAfter}s`);
   }
 }
 ```
 
-## Обработка версионирования API
-
-SDK предупреждает об использовании устаревших версий API:
-
-```typescript
-import { GitVerse } from 'gitverse-api-sdk';
-
-const client = new GitVerse({
-  token: 'your-token',
-  apiVersion: '2022-11-28', // Указание версии API
-  onApiVersionWarning: (warning) => {
-    console.warn(`API Warning: ${warning.message}`);
-    console.warn(`Current version: ${warning.currentVersion}`);
-    console.warn(`Sunset date: ${warning.sunsetDate}`);
-  }
-});
-```
-
 ## Отмена запросов (AbortSignal)
 
-SDK поддерживает отмену HTTP-запросов через стандартный Web API `AbortController`:
-
 ```typescript
-import { GitVerse } from 'gitverse-api-sdk';
-
-const client = new GitVerse({ token: 'your-token' });
-
-// Создание контроллера для управления отменой запроса
 const controller = new AbortController();
 
-// Выполнение запроса с возможностью отмены
+// Запрос с возможностью отмены
 const promise = client.repos.get('owner', 'repo', { signal: controller.signal });
 
-// Отмена запроса (например, при размонтировании компонента)
+// Отмена запроса
 controller.abort();
 
 try {
-  const repo = await promise;
+  await promise;
 } catch (error) {
   if (error.name === 'AbortError') {
-    console.log('Запрос был отменен');
+    console.log('Запрос отменён');
   }
 }
 ```
 
-### Использование с таймаутом
-
-```typescript
-// Автоматическая отмена запроса через 5 секунд
-const controller = new AbortController();
-const timeoutId = setTimeout(() => controller.abort(), 5000);
-
-try {
-  const repo = await client.repos.get('owner', 'repo', { signal: controller.signal });
-  clearTimeout(timeoutId);
-  console.log('Репозиторий получен:', repo.name);
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('Запрос превысил таймаут');
-  }
-  throw error;
-}
-```
+## API Модули
 
-### Отмена при размонтировании React-компонента
+### 👤 Users (4 метода)
 
 ```typescript
-import { useEffect, useState } from 'react';
-import { GitVerse } from 'gitverse-api-sdk';
-
-function RepositoryView({ owner, repo }) {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    const controller = new AbortController();
-    const client = new GitVerse({ token: 'your-token' });
-
-    client.repos.get(owner, repo, { signal: controller.signal })
-      .then(setData)
-      .catch(error => {
-        if (error.name !== 'AbortError') {
-          console.error('Ошибка загрузки:', error);
-        }
-      });
-
-    // Отмена запроса при размонтировании компонента
-    return () => controller.abort();
-  }, [owner, repo]);
-
-  return <div>{data ? data.name : 'Загрузка...'}</div>;
-}
+await client.users.getAuthenticated();
+await client.users.get('username');
+await client.users.listEmails();
+await client.users.listFollowers('username');
 ```
 
-### Поддержка во всех методах
-
-AbortSignal поддерживается во **всех 102 методах API** — просто передайте опциональный параметр `{ signal }`:
+### 📦 Repositories (27 методов)
 
 ```typescript
-// GET запросы
-await client.users.getCurrent({ signal: controller.signal });
-await client.repos.list({ signal: controller.signal });
-
-// POST запросы
-await client.repos.create(params, { signal: controller.signal });
-await client.pulls.create('owner', 'repo', params, { signal: controller.signal });
+// Основные операции
+await client.repos.get('owner', 'repo');
+await client.repos.update('owner', 'repo', { description: 'Updated' });
+await client.repos.delete('owner', 'repo');
+await client.repos.listForAuthenticatedUser();
+await client.repos.createForAuthenticatedUser({ name: 'new-repo' });
 
-// PUT/PATCH/DELETE запросы
-await client.contents.update('owner', 'repo', 'path', params, { signal: controller.signal });
-await client.repos.delete('owner', 'repo', { signal: controller.signal });
-```
+// Ветки
+await client.repos.listBranches('owner', 'repo');
 
-## API Модули
+// Коллабораторы
+await client.repos.listCollaborators('owner', 'repo');
+await client.repos.addCollaborator('owner', 'repo', 'username', { permission: 'push' });
 
-SDK организован в специализированные модули для различных областей GitVerse API:
+// Коммиты
+await client.repos.listCommits('owner', 'repo');
+await client.repos.getCommit('owner', 'repo', 'sha');
+await client.repos.compareCommits('owner', 'repo', 'base...head');
+await client.repos.createCommit('owner', 'repo', { message: 'msg', tree: 'sha' });
 
-### 👤 Users (2 метода)
+// Контент
+await client.repos.getContent('owner', 'repo', 'path/to/file');
+await client.repos.createOrUpdateFile('owner', 'repo', 'path', { message: 'Add', content: 'base64' });
+await client.repos.deleteFile('owner', 'repo', 'path', { message: 'Delete', sha: 'sha' });
 
-```typescript
-await client.users.getCurrent();
-await client.users.getByUsername('username');
-```
+// Форки
+await client.repos.createFork('owner', 'repo');
 
-### 📦 Repositories (7 методов)
+// Git объекты
+await client.repos.getTree('owner', 'repo', 'sha');
+await client.repos.createTree('owner', 'repo', { tree: [...] });
+await client.repos.createRef('owner', 'repo', { ref: 'refs/heads/new', sha: 'sha' });
 
-```typescript
-await client.repos.get('owner', 'repo');
-await client.repos.create({ name: 'new-repo', private: true });
-await client.repos.update('owner', 'repo', { description: 'Updated' });
-await client.repos.delete('owner', 'repo');
-await client.repos.compare('owner', 'repo', 'main...dev');
-await client.repos.getLanguages('owner', 'repo');
-await client.repos.listForAuthenticatedUser();
-```
+// Pull Requests (через repos)
+await client.repos.listPulls('owner', 'repo');
+await client.repos.getPull('owner', 'repo', 123);
+await client.repos.updatePull('owner', 'repo', 123, { title: 'New title' });
 
-### 📁 Contents (4 метода)
+// Секреты репозитория
+await client.repos.listRepoSecrets('owner', 'repo');
+await client.repos.createOrUpdateRepoSecret('owner', 'repo', 'SECRET', { encrypted_value: '...' });
 
-```typescript
-await client.contents.get('owner', 'repo', 'path/to/file');
-await client.contents.create('owner', 'repo', 'path', { message: 'Add file', content: 'base64' });
-await client.contents.update('owner', 'repo', 'path', { message: 'Update', content: 'base64', sha: 'sha' });
-await client.contents.delete('owner', 'repo', 'path', { message: 'Delete', sha: 'sha' });
+// Прочее
+await client.repos.listLanguages('owner', 'repo');
 ```
 
-### 🔀 Pull Requests (8 методов)
+### 🔀 Pull Requests (5 методов)
 
 ```typescript
 await client.pulls.list('owner', 'repo');
-await client.pulls.create('owner', 'repo', { title: 'New PR', head: 'feature', base: 'main' });
+await client.pulls.create('owner', 'repo', { title: 'PR', head: 'feature', base: 'main' });
 await client.pulls.get('owner', 'repo', 123);
-await client.pulls.update('owner', 'repo', 123, { title: 'Updated title' });
+await client.pulls.update('owner', 'repo', 123, { title: 'Updated' });
 await client.pulls.merge('owner', 'repo', 123);
-await client.pulls.getFiles('owner', 'repo', 123);
-await client.pulls.updateBranch('owner', 'repo', 123);
-await client.pulls.checkIfMerged('owner', 'repo', 123); // Проверка: был ли PR влит
 ```
 
 ### 🐛 Issues (6 методов)
@@ -248,15 +195,24 @@ await client.pulls.checkIfMerged('owner', 'repo', 123); // Проверка: б
 await client.issues.list('owner', 'repo');
 await client.issues.create('owner', 'repo', { title: 'Bug report' });
 await client.issues.get('owner', 'repo', 123);
+await client.issues.listComments('owner', 'repo', 123);
 await client.issues.getComment('owner', 'repo', 456);
-await client.issues.getComments('owner', 'repo', 123);
-await client.issues.getLabels('owner', 'repo', 123);
+await client.issues.listLabels('owner', 'repo');
 ```
 
-### 🍴 Forks (1 метод)
+### 🚀 Releases (10 методов)
 
 ```typescript
-await client.forks.create('owner', 'repo');
+await client.releases.list('owner', 'repo');
+await client.releases.create('owner', 'repo', { tag_name: 'v1.0.0', name: 'Release' });
+await client.releases.get('owner', 'repo', 123);
+await client.releases.getByTag('owner', 'repo', 'v1.0.0');
+await client.releases.update('owner', 'repo', 123, { name: 'Updated' });
+await client.releases.delete('owner', 'repo', 123);
+await client.releases.deleteByTag('owner', 'repo', 'v1.0.0');
+await client.releases.listAssets('owner', 'repo', 123);
+await client.releases.uploadAsset('owner', 'repo', 123, { name: 'asset.zip' });
+await client.releases.deleteAsset('owner', 'repo', 123, 456);
 ```
 
 ### ⭐ Stars (4 метода)
@@ -276,206 +232,106 @@ await client.emails.add(['email@example.com']);
 await client.emails.delete(['email@example.com']);
 ```
 
-### 🌿 Branches (1 метод)
+### 🏢 Organizations (5 методов)
 
 ```typescript
-await client.branches.list('owner', 'repo');
+await client.orgs.listOrgSecrets('org');
+await client.orgs.getOrgSecret('org', 'SECRET');
+await client.orgs.createOrUpdateOrgSecret('org', 'SECRET', { encrypted_value: '...' });
+await client.orgs.deleteOrgSecret('org', 'SECRET');
+await client.orgs.isMember('org', 'username');
 ```
 
-### 📝 Commits (3 метода)
-
-```typescript
-await client.commits.list('owner', 'repo');
-await client.commits.get('owner', 'repo', 'sha');
-await client.commits.getCommits('owner', 'repo', 123);
-```
-
-### 👥 Collaborators (2 метода)
-
-```typescript
-await client.collaborators.list('owner', 'repo');
-await client.collaborators.add('owner', 'repo', 'username');
-```
-
-### 🏢 Organizations (1 метод)
-
-```typescript
-await client.organizations.list();
-```
-
-### 👨‍👩‍👧‍👦 Teams (4 метода)
+### 👨‍👩‍👧‍👦 Teams (3 метода)
 
 ```typescript
 await client.teams.list('org');
-await client.teams.get('org', 'team-slug');
 await client.teams.listMembers('org', 'team-slug');
 await client.teams.getMembershipForUser('org', 'team-slug', 'username');
 ```
 
-### 🚀 Releases (10 методов)
-
-```typescript
-await client.releases.list('owner', 'repo');
-await client.releases.create('owner', 'repo', { tag_name: 'v1.0.0' });
-await client.releases.get('owner', 'repo', 123);
-await client.releases.getByTag('owner', 'repo', 'v1.0.0');
-await client.releases.update('owner', 'repo', 123, { name: 'New name' });
-await client.releases.delete('owner', 'repo', 123);
-await client.releases.deleteByTag('owner', 'repo', 'v1.0.0');
-await client.releases.getAssets('owner', 'repo', 123);
-await client.releases.uploadAsset('owner', 'repo', 123, { name: 'asset.zip' });
-await client.releases.deleteAsset('owner', 'repo', 123, 456);
-```
-
-### 🔧 Git Objects (3 метода)
-
-```typescript
-await client.git.getTree('owner', 'repo', 'sha');
-await client.git.getBlob('owner', 'repo', 'sha');
-await client.git.getRef('owner', 'repo', 'heads/main');
-```
-
-### ⚡ Actions (33 метода)
+### ⚡ Actions (25 методов)
 
-Полная поддержка GitHub Actions API, включая:
-
-**Runners (8 методов)**
+**Runners**
 ```typescript
 await client.actions.listOrgRunners('org');
-await client.actions.createOrgRegistrationToken('org');
 await client.actions.getOrgRunner('org', 123);
 await client.actions.deleteOrgRunner('org', 123);
+await client.actions.createOrgRegistrationToken('org');
 await client.actions.listRepoRunners('owner', 'repo');
-await client.actions.createRepoRegistrationToken('owner', 'repo');
 await client.actions.getRepoRunner('owner', 'repo', 123);
 await client.actions.deleteRepoRunner('owner', 'repo', 123);
+await client.actions.createRepoRegistrationToken('owner', 'repo');
 ```
 
-**Secrets (8 методов)**
+**Secrets**
 ```typescript
 await client.actions.listOrgSecrets('org');
-await client.actions.getOrgSecret('org', 'SECRET_NAME');
-await client.actions.createOrUpdateOrgSecret('org', 'SECRET_NAME', { encrypted_value: '...' });
-await client.actions.deleteOrgSecret('org', 'SECRET_NAME');
+await client.actions.getOrgSecret('org', 'SECRET');
+await client.actions.createOrUpdateOrgSecret('org', 'SECRET', { encrypted_value: '...' });
+await client.actions.deleteOrgSecret('org', 'SECRET');
 await client.actions.listRepoSecrets('owner', 'repo');
-await client.actions.getRepoSecret('owner', 'repo', 'SECRET_NAME');
-await client.actions.createOrUpdateRepoSecret('owner', 'repo', 'SECRET_NAME', { encrypted_value: '...' });
-await client.actions.deleteRepoSecret('owner', 'repo', 'SECRET_NAME');
+await client.actions.getRepoSecret('owner', 'repo', 'SECRET');
+await client.actions.createOrUpdateRepoSecret('owner', 'repo', 'SECRET', { encrypted_value: '...' });
+await client.actions.deleteRepoSecret('owner', 'repo', 'SECRET');
 ```
 
-**Variables (10 методов)**
+**Variables**
 ```typescript
 await client.actions.listOrgVariables('org');
-await client.actions.createOrgVariable('org', { name: 'VAR', value: 'value' });
 await client.actions.getOrgVariable('org', 'VAR');
-await client.actions.updateOrgVariable('org', 'VAR', { value: 'new-value' });
+await client.actions.createOrgVariable('org', { name: 'VAR', value: 'value' });
+await client.actions.updateOrgVariable('org', 'VAR', { value: 'new' });
 await client.actions.deleteOrgVariable('org', 'VAR');
 await client.actions.listRepoVariables('owner', 'repo');
-await client.actions.createRepoVariable('owner', 'repo', { name: 'VAR', value: 'value' });
 await client.actions.getRepoVariable('owner', 'repo', 'VAR');
+await client.actions.createRepoVariable('owner', 'repo', { name: 'VAR', value: 'value' });
 await client.actions.updateRepoVariable('owner', 'repo', 'VAR', { value: 'new' });
 await client.actions.deleteRepoVariable('owner', 'repo', 'VAR');
 ```
 
-**Artifacts (5 методов)**
-```typescript
-await client.actions.listArtifacts('owner', 'repo');
-await client.actions.getArtifact('owner', 'repo', 123);
-await client.actions.deleteArtifact('owner', 'repo', 123);
-await client.actions.downloadArtifact('owner', 'repo', 123);
-await client.actions.downloadArtifactRaw('owner', 'repo', 123);
-```
-
-**Workflows (2 метода)**
-```typescript
-await client.actions.getWorkflowDispatchInputs('owner', 'repo', 'workflow.yml');
-await client.actions.dispatchWorkflow('owner', 'repo', 'workflow.yml', { ref: 'main' });
-```
-
-## Продвинутое использование
-
-### Tree-shaking
-
-Для минимального размера бандла импортируйте только нужные модули:
-
-```typescript
-import { RepositoriesApi, GitVerseClient } from 'gitverse-api-sdk/api/repositories';
-import { PullsApi } from 'gitverse-api-sdk/api/pulls';
-
-const client = new GitVerseClient({ token: 'your-token' });
-const repos = new RepositoriesApi(client);
-const pulls = new PullsApi(client);
-
-const repo = await repos.get('owner', 'repo');
-const prList = await pulls.list('owner', 'repo');
-```
-
-### Обработка ошибок
+## Обработка ошибок
 
 ```typescript
 import { GitVerse, GitVerseApiError, RateLimitError } from 'gitverse-api-sdk';
 
-const client = new GitVerse({ token: 'your-token' });
-
 try {
   await client.repos.get('owner', 'repo');
 } catch (error) {
   if (error instanceof RateLimitError) {
-    console.error('Rate limit exceeded:', error.rateLimit);
+    console.error('Rate limit:', error.rateLimit);
   } else if (error instanceof GitVerseApiError) {
     console.error(`API Error ${error.status}:`, error.message);
-  } else {
-    console.error('Unexpected error:', error);
   }
 }
 ```
 
-### Конфигурация клиента
+## Конфигурация
 
 ```typescript
-import { GitVerse } from 'gitverse-api-sdk';
-
 const client = new GitVerse({
   token: 'your-token',
-  baseUrl: 'https://gitverse.ru/api/v1', // По умолчанию
-  apiVersion: '2022-11-28', // Версия API
+  baseUrl: 'https://gitverse.ru/api/v1',
+  apiVersion: '2022-11-28',
   onApiVersionWarning: (warning) => {
     console.warn('API version warning:', warning);
   }
 });
+
+// Динамическое обновление токена
+client.setToken('new-token');
 ```
 
 ## Разработка
 
 ```bash
-# Установка зависимостей
-bun install
-
-# Запуск тестов
-bun test
-
-# Проверка покрытия (требуется 100%)
-bun test:coverage
-
-# Сборка проекта
-bun run build
-
-# Линтинг
-bun run lint
-bun run lint:fix
+bun install      # Установка зависимостей
+bun test         # Запуск тестов
+bun test:coverage # Проверка покрытия (требуется 100%)
+bun run build    # Сборка
+bun run lint     # Линтинг
 ```
 
 ## Лицензия
 
 MIT © [RainyPixel](https://gitverse.ru/RainyPixel)
-
-## Полезные ссылки
-
-- [GitVerse SDK](https://gitverse.ru/RainyPixel/gitverse-sdk) - Основной репозиторий
-- [GitVerse API Docs](https://gitverse.ru/gitverse/rest-api-description/content/master/v1/openapi-1.0.json) - Документация API
-- [Issues](https://gitverse.ru/RainyPixel/gitverse-sdk/tasktracker) - Сообщить об ошибке
-- [npm пакет](https://www.npmjs.com/package/gitverse-api-sdk)
-
----
-
-Сделано с ❤️ для GitVerse