gitverse-api-sdk 1.1.1 → 2.0.0

package/README.md

@@ -1,188 +1,381 @@
 # GitVerse SDK
 
-![Build Status](https://img.shields.io/badge/tests-passing-brightgreen)
-![Coverage](https://img.shields.io/badge/coverage-100%25-blue)
-![Version](https://img.shields.io/npm/v/gitverse-api-sdk)
+[![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)
 
-**Легковесный TypeScript SDK для взаимодействия с GitVerse API**
+Полнофункциональный TypeScript SDK для GitVerse API с поддержкой всех эндпоинтов, обработкой Rate Limits и версионирования.
 
-> 🚀 Без внешних зависимостей | 🌲 Tree-shakable
+## Ключевые особенности
 
----
-
-## 📋 Оглавление
-
-- [Установка](#-установка)
-- [Быстрый старт](#-быстрый-старт)
-- [Использование](#-использование)
-- [Tree-Shaking](#-tree-shaking)
-- [Особенности](#-особенности)
-- [API](#-api)
-- [Тестирование](#-тестирование)
-- [Разработка](#-разработка)
-- [Contributing](#-contributing)
-- [Лицензия](#-лицензия)
+- ✅ **100% покрытие API** — Все 90 эндпоинтов GitVerse API поддерживаются
+- ✅ **Rate Limits** — Автоматическая обработка лимитов запросов с информативными ошибками
+- ✅ **Версионирование API** — Предупреждения об устаревших версиях API
+- ✅ **Специализированные ошибки** — `RateLimitError`, `ApiVersionWarning` для точной обработки
+- ✅ **100% покрытие тестами** — Полное тестирование всех методов
+- ✅ **Нет зависимостей** — Только нативный `fetch` API и `Buffer`
+- ✅ **Tree-shakable** — Модульная архитектура для минимального размера бандла
+- ✅ **TypeScript** — Полная типизация из коробки
 
----
-
-## 🚀 Быстрый старт
+## Установка
 
 ```bash
-# bun
-bun add gitverse-api-sdk
 # npm
 npm install gitverse-api-sdk
+
 # yarn
 yarn add gitverse-api-sdk
+
 # pnpm
 pnpm add gitverse-api-sdk
+
+# bun
+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();
+console.log(user.login);
+
+// Получение репозитория
+const repo = await client.repos.get('owner', 'repo-name');
+console.log(repo.full_name);
+
+// Создание Pull Request
+const pr = await client.pulls.create('owner', 'repo', {
+  title: 'New feature',
+  head: 'feature-branch',
+  base: 'main',
+  body: 'Description of changes'
+});
+```
+
+## Обработка Rate Limits
+
+SDK автоматически отслеживает лимиты запросов и предоставляет подробную информацию при их превышении:
+
+```typescript
+import { GitVerse, 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.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));
+  }
+}
+```
+
+## Обработка версионирования 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}`);
+  }
+});
+```
+
+## API Модули
+
+SDK организован в специализированные модули для различных областей GitVerse API:
+
+### 👤 Users (2 метода)
+
+```typescript
+await client.users.getCurrent();
+await client.users.getByUsername('username');
+```
+
+### 📦 Repositories (7 методов)
+
+```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();
+```
+
+### 📁 Contents (4 метода)
+
+```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' });
+```
+
+### 🔀 Pull Requests (7 методов)
+
+```typescript
+await client.pulls.list('owner', 'repo');
+await client.pulls.create('owner', 'repo', { title: 'New 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.merge('owner', 'repo', 123);
+await client.pulls.getFiles('owner', 'repo', 123);
+await client.pulls.updateBranch('owner', 'repo', 123);
 ```
 
-## 📖 Использование
+### 🐛 Issues (6 методов)
 
 ```typescript
-import { GitVerse } from "gitverse-api-sdk";
+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.getComment('owner', 'repo', 456);
+await client.issues.getComments('owner', 'repo', 123);
+await client.issues.getLabels('owner', 'repo', 123);
+```
+
+### 🍴 Forks (1 метод)
+
+```typescript
+await client.forks.create('owner', 'repo');
+```
 
-(async () => {
-  const sdk = new GitVerse({ token: "YOUR_TOKEN" });
+### ⭐ Stars (4 метода)
 
-  // Получить текущего пользователя
-  const me = await sdk.users.getCurrent();
-  console.log(me);
+```typescript
+await client.stars.list('owner', 'repo');
+await client.stars.listForAuthenticatedUser();
+await client.stars.star('owner', 'repo');
+await client.stars.unstar('owner', 'repo');
+```
+
+### 📧 Emails (3 метода)
+
+```typescript
+await client.emails.list();
+await client.emails.add(['email@example.com']);
+await client.emails.delete(['email@example.com']);
+```
 
-  // Получить репозиторий
-  const repo = await sdk.repos.get("owner", "repo");
-  console.log(repo);
+### 🌿 Branches (1 метод)
 
-  // Создать репозиторий
-  const newRepo = await sdk.repos.create({
-    name: "my-new-repo",
-    description: "Описание репозитория",
-    private: false,
-  });
+```typescript
+await client.branches.list('owner', 'repo');
+```
 
-  // Управление email адресами
-  const emails = await sdk.emails.list();
-  await sdk.emails.add({ emails: ["new@example.com"] });
+### 📝 Commits (3 метода)
 
-  // Работа со звездами
-  await sdk.stars.add("owner", "repo");
-  const isStarred = await sdk.stars.check("owner", "repo");
+```typescript
+await client.commits.list('owner', 'repo');
+await client.commits.get('owner', 'repo', 'sha');
+await client.commits.getCommits('owner', 'repo', 123);
+```
 
-  // Получить issues
-  const issues = await sdk.issues.list("owner", "repo");
+### 👥 Collaborators (2 метода)
 
-  // Создать файл
-  const file = await sdk.contents.createFile("owner", "repo", "path.txt", {
-    content: Buffer.from("Hello").toString("base64"),
-    message: "feat: add greeting",
-  });
-  console.log(file);
-})();
+```typescript
+await client.collaborators.list('owner', 'repo');
+await client.collaborators.add('owner', 'repo', 'username');
 ```
 
-## 🌲 Tree-Shaking
+### 🏢 Organizations (1 метод)
 
-SDK полностью поддерживает tree-shaking, позволяя импортировать только необходимые модули, что уменьшает размер итогового бандла:
+```typescript
+await client.organizations.list();
+```
+
+### 👨‍👩‍👧‍👦 Teams (4 метода)
 
 ```typescript
-// Вместо импорта всего SDK
-import { GitVerse } from "gitverse-api-sdk";
-const sdk = new GitVerse();
+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');
+```
 
-// Можно импортировать только нужные модули
-import { RepositoriesApi, GitVerseClient } from "gitverse-api-sdk/api/repositories";
-const client = new GitVerseClient({ token: "YOUR_TOKEN" });
-const reposApi = new RepositoriesApi(client);
+### 🚀 Releases (10 методов)
 
-// Или даже отдельные типы и утилиты
-import { IssueState } from "gitverse-api-sdk/enums";
-import type { Issue } from "gitverse-api-sdk/types";
+```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 метода)
 
-- **100% покрытие** тестов (lines/functions/statements)
-- **Нет сторонних зависимостей**
-- Поддержка **Conventional Commits**
-- **Tree-shakable** модули для оптимизации размера бандла
-- Интуитивный API, единообразный интерфейс
-- Работа через **fetch**, совместим с Bun и браузером
+```typescript
+await client.git.getTree('owner', 'repo', 'sha');
+await client.git.getBlob('owner', 'repo', 'sha');
+await client.git.getRef('owner', 'repo', 'heads/main');
+```
 
-## 🔍 API
+### ⚡ Actions (33 метода)
 
-### Users
+Полная поддержка GitHub Actions API, включая:
 
-- `sdk.users.getCurrent()`
-- `sdk.users.getByUsername(username: string)`
+**Runners (8 методов)**
+```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.listRepoRunners('owner', 'repo');
+await client.actions.createRepoRegistrationToken('owner', 'repo');
+await client.actions.getRepoRunner('owner', 'repo', 123);
+await client.actions.deleteRepoRunner('owner', 'repo', 123);
+```
 
-### Repositories
+**Secrets (8 методов)**
+```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.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');
+```
 
-- `sdk.repos.get(owner: string, repo: string)`
-- `sdk.repos.getLanguages(owner: string, repo: string)`
-- `sdk.repos.listForAuthenticatedUser()`
-- `sdk.repos.create(params: CreateRepositoryParams)`
+**Variables (10 методов)**
+```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.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.updateRepoVariable('owner', 'repo', 'VAR', { value: 'new' });
+await client.actions.deleteRepoVariable('owner', 'repo', 'VAR');
+```
 
-### Contents
+**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);
+```
 
-- `sdk.contents.get(owner: string, repo: string, path: string)`
-- `sdk.contents.createFile(owner: string, repo: string, path: string, params)`
-- `sdk.contents.updateFile(owner: string, repo: string, path: string, params)`
-- `sdk.contents.deleteFile(owner: string, repo: string, path: string, params)`
+**Workflows (2 метода)**
+```typescript
+await client.actions.getWorkflowDispatchInputs('owner', 'repo', 'workflow.yml');
+await client.actions.dispatchWorkflow('owner', 'repo', 'workflow.yml', { ref: 'main' });
+```
 
-### Pulls
+## Продвинутое использование
 
-- `sdk.pulls.list(owner: string, repo: string, state?)`
-- `sdk.pulls.get(owner: string, repo: string, number: number)`
-- `sdk.pulls.create(owner: string, repo: string, params)`
+### Tree-shaking
 
-### Forks
+Для минимального размера бандла импортируйте только нужные модули:
 
-- `sdk.forks.list(owner: string, repo: string)`
-- `sdk.forks.create(owner: string, repo: string)`
+```typescript
+import { RepositoriesApi, GitVerseClient } from 'gitverse-api-sdk/api/repositories';
+import { PullsApi } from 'gitverse-api-sdk/api/pulls';
 
-### Emails
+const client = new GitVerseClient({ token: 'your-token' });
+const repos = new RepositoriesApi(client);
+const pulls = new PullsApi(client);
 
-- `sdk.emails.list()`
-- `sdk.emails.add(params: AddEmailParams)`
-- `sdk.emails.remove(params: RemoveEmailParams)`
+const repo = await repos.get('owner', 'repo');
+const prList = await pulls.list('owner', 'repo');
+```
 
-### Issues
+### Обработка ошибок
 
-- `sdk.issues.list(owner: string, repo: string, state?: IssueState)`
-- `sdk.issues.get(owner: string, repo: string, number: number)`
+```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);
+  } else if (error instanceof GitVerseApiError) {
+    console.error(`API Error ${error.status}:`, error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
 
-### Stars
+### Конфигурация клиента
 
-- `sdk.stars.add(owner: string, repo: string)`
-- `sdk.stars.check(owner: string, repo: string)`
-- `sdk.stars.remove(owner: string, repo: string)`
+```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
+  onApiVersionWarning: (warning) => {
+    console.warn('API version warning:', warning);
+  }
+});
+```
 
-## 🧪 Тестирование
+## Разработка
 
 ```bash
+# Установка зависимостей
+bun install
+
+# Запуск тестов
 bun test
-bun test --coverage
-```
 
-## 🛠 Разработка
+# Проверка покрытия (требуется 100%)
+bun test:coverage
 
-1. Форк и клон:
-   ```bash
-   git clone https://gitverse.ru/onreza/gitverse-sdk.git
-   ```
-2. Установка зависимостей:
-   ```bash
-   bun install
-   ```
-3. Запуск серверов/скриптов по необходимости
-4. Написание **семантических коммитов** по [Conventional Commits]
-5. Поддержание **100% покрытия** тестов
+# Сборка проекта
+bun run build
 
-## 🤝 Contributing
+# Линтинг
+bun run lint
+bun run lint:fix
+```
 
-См. детали в [CONTRIBUTING.md](./CONTRIBUTING.md).
+## Лицензия
 
-## 📝 Лицензия
+MIT © [Ivan Bobchenkov](https://bobchenkov.ru)
+
+---
 
-MIT
+**Ссылки:**
+- [GitVerse](https://gitverse.ru)
+- [Репозиторий](https://gitverse.ru/rainypixel/gitverse-sdk)
+- [Issues](https://gitverse.ru/rainypixel/gitverse-sdk/issues)
+- [npm пакет](https://www.npmjs.com/package/gitverse-api-sdk)