gitverse-api-sdk 5.0.1 → 5.2.0

package/README.md

@@ -3,15 +3,15 @@
 [![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-v1.1-blue.svg)](https://gitverse.ru)
+[![GitVerse API](https://img.shields.io/badge/GitVerse%20API-v1.2-blue.svg)](https://gitverse.ru)
 
 Полнофункциональный TypeScript SDK для GitVerse API с поддержкой всех эндпоинтов, обработкой Rate Limits и версионирования.
 
-> **Совместимость:** SDK синхронизирован с GitVerse OpenAPI v1.1 от 15.01.2026
+> **Совместимость:** SDK синхронизирован с GitVerse OpenAPI v1.2
 
 ## Ключевые особенности
 
-- ✅ **Полное покрытие API** — Все эндпоинты GitVerse OpenAPI v1.1
+- ✅ **Полное покрытие API** — Все эндпоинты GitVerse OpenAPI v1.2
 - ✅ **Rate Limits** — Автоматическая обработка лимитов запросов
 - ✅ **Версионирование API** — Предупреждения об устаревших версиях
 - ✅ **Специализированные ошибки** — `RateLimitError`, `ApiVersionWarning`
@@ -272,16 +272,121 @@ await client.actions.deleteRepoVariable('owner', 'repo', 'VAR');
 
 ## Обработка ошибок
 
+SDK экспортирует три класса для обработки ошибок и предупреждений:
+
+### GitVerseApiError
+
+Базовый класс ошибки API. Выбрасывается при любой HTTP ошибке (4xx, 5xx).
+
 ```typescript
-import { GitVerse, GitVerseApiError, RateLimitError } from 'gitverse-api-sdk';
+import { GitVerse, GitVerseApiError } from 'gitverse-api-sdk';
+
+try {
+  await client.repos.get('owner', 'repo');
+} catch (error) {
+  if (error instanceof GitVerseApiError) {
+    console.error(`API Error ${error.status}: ${error.message}`);
+
+    // Метаданные ответа (если доступны)
+    if (error.metadata?.requestId) {
+      console.error(`Request ID: ${error.metadata.requestId}`);
+    }
+  }
+}
+```
+
+**Свойства:**
+- `status: number` — HTTP статус код (401, 403, 404, 500 и т.д.)
+- `message: string` — Текст ошибки
+- `metadata?: ApiResponseMetadata` — Метаданные ответа (requestId, rateLimit, apiVersion)
+
+### RateLimitError
+
+Наследует `GitVerseApiError`. Выбрасывается при превышении лимита запросов (429).
+
+```typescript
+import { GitVerse, RateLimitError } from 'gitverse-api-sdk';
 
 try {
   await client.repos.get('owner', 'repo');
 } catch (error) {
   if (error instanceof RateLimitError) {
-    console.error('Rate limit:', error.rateLimit);
-  } else if (error instanceof GitVerseApiError) {
-    console.error(`API Error ${error.status}:`, error.message);
+    console.error(`Rate limit exceeded!`);
+    console.error(`Limit: ${error.rateLimit.limit}`);
+    console.error(`Remaining: ${error.rateLimit.remaining}`);
+    console.error(`Retry after: ${error.getRetryAfterSeconds()}s`);
+    console.error(`Reset at: ${error.getResetDate().toISOString()}`);
+  }
+}
+```
+
+**Свойства:**
+- `rateLimit.limit: number` — Максимальное количество запросов
+- `rateLimit.remaining: number` — Оставшееся количество запросов
+- `rateLimit.reset: number` — Unix timestamp сброса лимита
+- `rateLimit.retryAfter: number` — Секунд до сброса лимита
+
+**Методы:**
+- `getRetryAfterSeconds(): number` — Количество секунд до сброса
+- `getResetDate(): Date` — Дата/время сброса лимита
+
+### ApiVersionWarning
+
+Предупреждение об устаревшей версии API. Не является ошибкой, передаётся через callback.
+
+```typescript
+import { GitVerse, ApiVersionWarning } from 'gitverse-api-sdk';
+
+const client = new GitVerse({
+  token: 'your-token',
+  onApiVersionWarning: (warning: ApiVersionWarning) => {
+    console.warn(warning.getMessage());
+    console.warn(`Current: ${warning.currentVersion}`);
+    console.warn(`Latest: ${warning.latestVersion}`);
+    if (warning.decommissioning) {
+      console.warn(`Decommissioning: ${warning.decommissioning}`);
+    }
+  }
+});
+```
+
+**Свойства:**
+- `currentVersion: string` — Текущая используемая версия
+- `latestVersion: string` — Последняя доступная версия
+- `decommissioning?: string` — Дата вывода из эксплуатации
+
+**Методы:**
+- `getMessage(): string` — Форматированное сообщение о предупреждении
+
+### Пример полной обработки
+
+```typescript
+import { GitVerse, GitVerseApiError, RateLimitError } from 'gitverse-api-sdk';
+
+async function fetchRepo(owner: string, repo: string) {
+  try {
+    return await client.repos.get(owner, repo);
+  } catch (error) {
+    if (error instanceof RateLimitError) {
+      // Ждём и повторяем
+      await new Promise(r => setTimeout(r, error.getRetryAfterSeconds() * 1000));
+      return fetchRepo(owner, repo);
+    }
+
+    if (error instanceof GitVerseApiError) {
+      switch (error.status) {
+        case 401:
+          throw new Error('Invalid token');
+        case 403:
+          throw new Error('Access denied');
+        case 404:
+          return null; // Репозиторий не найден
+        default:
+          throw error;
+      }
+    }
+
+    throw error;
   }
 }
 ```