itd-sdk-js 1.0.7 → 1.0.9

package/API_REFERENCE.md

@@ -2,6 +2,22 @@
 
 Техническое руководство по методам и настройке библиотеки для работы с API сайта `итд.com`.
 
+## Структура SDK
+
+| Файл | Назначение |
+|------|------------|
+| `client.js` | Главный клиент: создание axios, загрузка cookies, хранение токена, менеджеры, хелперы `get/post/put/patch/delete` |
+| `auth.js` | Авторизация: refresh, logout, checkAuth, ensureAuthenticated, validateAndRefreshToken |
+| `token-storage.js` | Сохранение токена в .env и cookies в .cookies (используется auth при refresh) |
+| `posts.js` | Посты: createPost, getPosts, editPost, deletePost и др. |
+| `comments.js` | Комментарии: addComment, replyToComment, getComments, likeComment и др. |
+| `users.js` | Пользователи: getMyProfile, getUserProfile, followUser, getTopClans и др. |
+| `notifications.js` | Уведомления |
+| `hashtags.js` | Хэштеги |
+| `files.js` | Загрузка файлов |
+| `search.js` | Поиск |
+| `reports.js` | Жалобы |
+
 ## Установка
 
 ### Через npm
@@ -38,7 +54,7 @@ import { ITDClient } from 'itd-sdk-js';
 
 ### Инициализация клиента
 
-**Простой вариант (корень проекта = текущая рабочая директория):**
+**Простой вариант:**
 
 ```javascript
 import { ITDClient } from 'itd-sdk-js';
@@ -47,8 +63,14 @@ import dotenv from 'dotenv';
 dotenv.config();
 
 const client = new ITDClient();
-client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-client.auth.isAuthenticated = true;
+// Токен подхватывается из .env автоматически
+```
+
+**Только .cookies (без ITD_ACCESS_TOKEN в .env):**
+
+```javascript
+const client = new ITDClient();
+await client.ensureAuthenticated(); // получит токен через refresh из .cookies
 ```
 
 **С опциями (projectRoot / envPath / cookiesPath):**
@@ -59,13 +81,11 @@ client.auth.isAuthenticated = true;
 const client = new ITDClient({
     baseUrl: 'https://xn--d1ah4a.com',
     userAgent: '...',
-    projectRoot: process.cwd(),              // корень проекта (по умолчанию process.cwd())
-    // envPath: '/path/to/project/.env',
-    // cookiesPath: '/path/to/project/.cookies',
-    requestTimeout: 60000,                    // таймаут обычных запросов, мс (по умолчанию 60 с)
-    uploadTimeout: 120000,                    // таймаут загрузки файлов и создания поста, мс (по умолчанию 120 с)
+    projectRoot: process.cwd(),
+    requestTimeout: 60000,
+    uploadTimeout: 120000,
+    accessToken: '...',                       // опционально; по умолчанию из .env ITD_ACCESS_TOKEN
 });
-client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
 ```
 
 - `projectRoot` — директория, в которой ищутся `.env` и `.cookies` (по умолчанию `process.cwd()`).
@@ -213,9 +233,12 @@ const post = await client.createPost('Текст поста', 'image.jpg');
 ## Методы API: Управление токенами
 
 - `hasRefreshToken()` — проверяет наличие refresh_token в cookies. Возвращает `boolean`.
+- `ensureAuthenticated()` — если нет accessToken, но есть refresh_token — вызывает refresh и получает токен. Возвращает `Promise<boolean>`. Для сценария «только .cookies»: `await client.ensureAuthenticated()` перед первым запросом.
 - `validateAndRefreshToken()` — проверяет валидность токена и обновляет его при необходимости. Возвращает `Promise<boolean>`.
 - `refreshAccessToken()` — принудительно обновляет токен через refresh endpoint. Возвращает `Promise<string|null>`.
 
+**Кастомные запросы:** `client.get(path)`, `client.post(path, data)`, `client.put(path, data)`, `client.patch(path, data)`, `client.delete(path)` — для произвольных эндпоинтов (baseURL уже подставлен).
+
 **Рекомендация:** При множественных запросах с интервалами (более 10-15 минут) вызывайте `validateAndRefreshToken()` перед каждым запросом.
 
 ---

package/README.md

@@ -27,8 +27,8 @@ npm install
 ## Настройка
 
 1. Создайте `.env` в корне проекта на основе `.env.example` (или используйте переменные окружения).
-2. Вставьте свой `ITD_ACCESS_TOKEN` (его можно вытащить из Network в DevTools).
-3. Для работы авто-обновления сессии создайте файл `.cookies` в корне проекта и вставьте туда строку `Cookie` из любого запроса к сайту в браузере.
+2. Токен: добавьте `ITD_ACCESS_TOKEN` в .env или положите `.cookies` с `refresh_token` — клиент сам подхватит токен из .env или получит через refresh.
+3. Для авто-обновления токена создайте файл `.cookies` с Cookie из браузера (обязательно должен быть `refresh_token`).
 
 SDK по умолчанию читает и пишет `.env` и `.cookies` в корне проекта (`process.cwd()`). При обновлении токена изменения сохраняются в ваш проект. При необходимости можно задать `projectRoot` или явные пути в конструкторе — см. [API_REFERENCE.md](API_REFERENCE.md).
 
@@ -45,8 +45,7 @@ import dotenv from 'dotenv';
 dotenv.config();
 
 const client = new ITDClient();
-client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-client.auth.isAuthenticated = true;
+// Токен подхватывается из .env. Если только .cookies — await client.ensureAuthenticated();
 
 // Получаем профиль и тренды
 const myProfile = await client.getMyProfile();

package/examples/auto-refresh.js

@@ -14,10 +14,7 @@ async function main() {
     console.log('🔄 === Автоматическое обновление токена ===\n');
 
     const client = new ITDClient();
-    
-    // Устанавливаем токен (может быть уже истёкшим)
-    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-    client.auth.isAuthenticated = true;
+    // Токен подхватывается из .env автоматически
 
     console.log('💡 SDK автоматически обновит токен при истечении!');
     console.log('   Вы просто используете API - всё работает "из коробки"\n');

package/examples/basic-usage.js

@@ -12,10 +12,8 @@ dotenv.config();
 async function main() {
     console.log('📝 === Базовое использование SDK ===\n');
 
-    // Создаём клиент
+    // Создаём клиент (токен подхватывается из .env автоматически)
     const client = new ITDClient();
-    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-    client.auth.isAuthenticated = true;
 
     try {
         // Получаем свой профиль

package/examples/quick-start.js

@@ -37,31 +37,26 @@ async function quickStart() {
     // ============================================
     // ШАГ 2: Настройка авторизации
     // ============================================
-    console.log('🔐 Шаг 2: Настраиваю авторизацию...\n');
+    console.log('🔐 Шаг 2: Проверяю авторизацию...\n');
     
-    // Получаем токен из переменных окружения (.env файл)
-    const accessToken = process.env.ITD_ACCESS_TOKEN;
-    
-    if (!accessToken) {
-        console.log('❌ ОШИБКА: ITD_ACCESS_TOKEN не найден в .env\n');
+    // Токен подхватывается из .env автоматически. Если нет — пробуем refresh из .cookies
+    if (!client.accessToken && client.hasRefreshToken()) {
+        console.log('   Токена в .env нет, получаю через refresh из .cookies...\n');
+        const ok = await client.ensureAuthenticated();
+        if (!ok) {
+            console.log('❌ Не удалось получить токен из refresh_token\n');
+            return;
+        }
+    }
+    if (!client.accessToken) {
+        console.log('❌ Нет токена. Добавьте ITD_ACCESS_TOKEN в .env или refresh_token в .cookies\n');
         console.log('📋 Как получить токен:');
         console.log('1. Откройте итд.com в браузере и войдите');
-        console.log('2. Откройте DevTools (F12) → вкладка Network');
-        console.log('3. Найдите запрос POST /api/v1/auth/refresh');
-        console.log('4. Откройте Response → скопируйте accessToken');
-        console.log('5. Вставьте в .env: ITD_ACCESS_TOKEN=ваш_токен\n');
+        console.log('2. DevTools (F12) → Network → скопируйте Cookie в .cookies');
+        console.log('3. Или скопируйте accessToken из ответа /api/v1/auth/refresh в .env\n');
         return;
     }
-    
-    // Устанавливаем токен в клиент
-    // Это нужно для авторизации всех запросов
-    client.setAccessToken(accessToken);
-    
-    // Помечаем клиент как авторизованный
-    // Это позволяет использовать методы, требующие авторизации
-    client.auth.isAuthenticated = true;
-    
-    console.log('✅ Авторизация настроена (токен загружен из .env)\n');
+    console.log('✅ Авторизация настроена\n');
 
     // ============================================
     // ШАГ 3: Получение информации о себе

package/examples/token-validation.js

@@ -12,8 +12,6 @@ dotenv.config();
 
 async function publishMultiplePosts() {
     const client = new ITDClient();
-    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-    client.auth.isAuthenticated = true;
     
     console.log('📝 Публикация нескольких постов с проверкой токена\n');
     

package/examples/user-friendly.js

@@ -14,8 +14,6 @@ async function main() {
     console.log('✨ === Удобные методы SDK ===\n');
 
     const client = new ITDClient();
-    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
-    client.auth.isAuthenticated = true;
 
     try {
         // Пример 1: Проверка подписки - одна строка вместо сложного запроса

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itd-sdk-js",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Unofficial SDK for итд.com - Node.js library for working with API. Automatic token refresh, session management, and convenient methods for posts, comments, users, and notifications.",
   "main": "src/client.js",
   "type": "module",

package/src/auth.js

@@ -12,8 +12,6 @@ export class AuthManager {
     constructor(client) {
         this.client = client;
         this.axios = client.axios;
-        this.isAuthenticated = false;
-        this.userData = null;
     }
     
     /**
@@ -66,7 +64,6 @@ export class AuthManager {
                 
                 // Обновляем токен в клиенте
                 this.client.setAccessToken(newToken);
-                this.isAuthenticated = true;
                 
                 // Сохраняем токен в .env файл (в корне проекта)
                 await saveAccessToken(newToken, this.client.envPath);
@@ -132,11 +129,12 @@ export class AuthManager {
             const response = await this.axios.post(logoutUrl);
             
             if (response.status === 200) {
-                this.isAuthenticated = false;
-                this.userData = null;
                 this.client.setAccessToken(null);
-                // Очистка cookies
-                this.axios.defaults.headers.common['Cookie'] = '';
+                try {
+                    this.client.cookieJar.removeAllCookiesSync();
+                } catch (e) {
+                    // MemoryCookieStore поддерживает removeAllCookiesSync
+                }
                 return true;
             }
             return false;
@@ -152,9 +150,8 @@ export class AuthManager {
      * @returns {Promise<boolean>} True если авторизован
      */
     async checkAuth() {
-        // Проверяем наличие accessToken - если он есть, считаем что авторизован
-        // Реальная проверка происходит на уровне API (401 ошибка)
-        return !!(this.client.accessToken || this.isAuthenticated);
+        // Авторизован, если есть accessToken (реальная проверка — 401 при истечении)
+        return !!this.client.accessToken;
     }
     
     /**

package/src/client.js

@@ -34,9 +34,10 @@ export class ITDClient {
      * @param {string} [options.cookiesPath] - Полный путь к .cookies (переопределяет projectRoot для .cookies)
      * @param {number} [options.requestTimeout] - Таймаут обычных запросов в мс (по умолчанию 60000)
      * @param {number} [options.uploadTimeout] - Таймаут загрузки файлов и создания поста в мс (по умолчанию 120000)
+     * @param {string} [options.accessToken] - JWT токен (если не указан — берётся из .env ITD_ACCESS_TOKEN)
      */
     constructor(baseUrlOrOptions = null, userAgent = null) {
-        let baseUrl, projectRoot, envPath, cookiesPath, requestTimeout, uploadTimeout;
+        let baseUrl, projectRoot, envPath, cookiesPath, requestTimeout, uploadTimeout, accessToken;
 
         if (baseUrlOrOptions && typeof baseUrlOrOptions === 'object' && !(baseUrlOrOptions instanceof URL)) {
             const opts = baseUrlOrOptions;
@@ -47,6 +48,7 @@ export class ITDClient {
             cookiesPath = opts.cookiesPath ?? path.join(projectRoot, '.cookies');
             requestTimeout = opts.requestTimeout ?? 60000;
             uploadTimeout = opts.uploadTimeout ?? 120000;
+            accessToken = opts.accessToken ?? process.env.ITD_ACCESS_TOKEN ?? null;
         } else {
             projectRoot = process.cwd();
             baseUrl = baseUrlOrOptions || process.env.ITD_BASE_URL || 'https://xn--d1ah4a.com';
@@ -54,6 +56,7 @@ export class ITDClient {
             cookiesPath = path.join(projectRoot, '.cookies');
             requestTimeout = 60000;
             uploadTimeout = 120000;
+            accessToken = process.env.ITD_ACCESS_TOKEN ?? null;
         }
 
         // Используем реальный домен (IDN: итд.com = xn--d1ah4a.com)
@@ -71,7 +74,7 @@ export class ITDClient {
         this.uploadTimeout = uploadTimeout;
 
         /** @type {string|null} */
-        this.accessToken = null;
+        this.accessToken = accessToken || null;
 
         // Прокси (важно, если браузер ходит через 127.0.0.1:10808)
         // Можно задать: ITD_PROXY=http://127.0.0.1:10808
@@ -196,7 +199,7 @@ export class ITDClient {
         this.hashtags = new HashtagsManager(this);
         this.files = new FilesManager(this);
         this.reports = new ReportsManager(this);
-        this.search = new SearchManager(this);
+        this.searchManager = new SearchManager(this);
     }
 
     /**
@@ -206,6 +209,66 @@ export class ITDClient {
     setAccessToken(token) {
         this.accessToken = token || null;
     }
+
+    /**
+     * Убедиться, что есть accessToken. Если нет, но есть refresh_token в cookies — вызывает refresh.
+     * Для сценария «только .cookies»: await client.ensureAuthenticated() перед первым запросом.
+     * @returns {Promise<boolean>} true если токен есть или получен, false если нет
+     */
+    async ensureAuthenticated() {
+        if (this.accessToken) return true;
+        if (!this.hasRefreshToken()) return false;
+        const token = await this.refreshAccessToken();
+        return !!token;
+    }
+
+    /**
+     * Кастомный GET запрос (baseURL уже подставлен)
+     * @param {string} path - Путь, например /api/users/me
+     * @param {Object} [config] - Доп. опции axios
+     */
+    get(path, config = {}) {
+        return this.axios.get(path, config);
+    }
+
+    /**
+     * Кастомный POST запрос
+     * @param {string} path - Путь, например /api/posts
+     * @param {Object} [data] - Тело запроса (JSON)
+     * @param {Object} [config] - Доп. опции axios
+     */
+    post(path, data = {}, config = {}) {
+        return this.axios.post(path, data, config);
+    }
+
+    /**
+     * Кастомный PUT запрос
+     * @param {string} path - Путь
+     * @param {Object} [data] - Тело запроса
+     * @param {Object} [config] - Доп. опции axios
+     */
+    put(path, data = {}, config = {}) {
+        return this.axios.put(path, data, config);
+    }
+
+    /**
+     * Кастомный PATCH запрос
+     * @param {string} path - Путь
+     * @param {Object} [data] - Тело запроса
+     * @param {Object} [config] - Доп. опции axios
+     */
+    patch(path, data = {}, config = {}) {
+        return this.axios.patch(path, data, config);
+    }
+
+    /**
+     * Кастомный DELETE запрос
+     * @param {string} path - Путь
+     * @param {Object} [config] - Доп. опции axios
+     */
+    delete(path, config = {}) {
+        return this.axios.delete(path, config);
+    }
     
     /**
      * Загружает cookies из файла .cookies
@@ -320,7 +383,7 @@ export class ITDClient {
      * 
      * @param {string|null} username - Имя пользователя (null = лента/свои посты)
      * @param {number} limit - Количество постов
-     * @param {string} sort - Сортировка: "new", "old", "popular"
+     * @param {string} sort - Сортировка: "newest", "oldest", "popular"
      * @param {string|null} cursor - Курсор для пагинации
      * @param {string|null} tab - Тип ленты: "popular" (популярные), "following" (из подписок), null (обычная лента)
      * @returns {Promise<Object>} { posts: [], pagination: {} }
@@ -780,7 +843,7 @@ export class ITDClient {
      * @returns {Promise<Object|null>} { users: [], hashtags: [] } или null при ошибке
      */
     async search(query, userLimit = 5, hashtagLimit = 5) {
-        return await this.search.search(query, userLimit, hashtagLimit);
+        return await this.searchManager.search(query, userLimit, hashtagLimit);
     }
     
     /**
@@ -791,7 +854,7 @@ export class ITDClient {
      * @returns {Promise<Array|null>} Массив пользователей или null при ошибке
      */
     async searchUsers(query, limit = 5) {
-        return await this.search.searchUsers(query, limit);
+        return await this.searchManager.searchUsers(query, limit);
     }
     
     /**
@@ -802,7 +865,7 @@ export class ITDClient {
      * @returns {Promise<Array|null>} Массив хэштегов или null при ошибке
      */
     async searchHashtags(query, limit = 5) {
-        return await this.search.searchHashtags(query, limit);
+        return await this.searchManager.searchHashtags(query, limit);
     }
     
     // ========== USER-FRIENDLY МЕТОДЫ ==========
@@ -895,15 +958,6 @@ export class ITDClient {
     
     // === Пользователи ===
     
-    /**
-     * Получает свой профиль (удобный метод)
-     * 
-     * @returns {Promise<Object|null>} Данные профиля или null
-     */
-    async getMyProfile() {
-        return await this.users.getMyProfile();
-    }
-    
     /**
      * Проверяет, подписан ли текущий пользователь на указанного (удобный метод)
      * 
@@ -941,16 +995,6 @@ export class ITDClient {
         return await this.users.getMyClan();
     }
     
-    /**
-     * Получает клан пользователя (эмодзи аватара) (удобный метод)
-     * 
-     * @param {string} username - Имя пользователя
-     * @returns {Promise<string|null>} Эмодзи клана или null
-     */
-    async getUserClan(username) {
-        return await this.users.getUserClan(username);
-    }
-    
     // === Комментарии ===
     
     /**

package/src/notifications.js

@@ -143,7 +143,8 @@ export class NotificationsManager {
     }
 
     /**
-     * Отмечает все уведомления как прочитанные
+     * Отмечает все уведомления как прочитанные.
+     * Экспериментально: endpoint /api/notifications/read-all может отличаться.
      * 
      * @returns {Promise<boolean>} True если успешно
      */

package/src/posts.js

@@ -314,7 +314,7 @@ export class PostsManager {
             const response = await this.axios.put(editUrl, postData);
             
             if (response.status === 200) {
-                return response.data;
+                return response.data?.data ?? response.data;
             } else {
                 console.error(`Ошибка редактирования поста: ${response.status} - ${JSON.stringify(response.data)}`);
                 return null;
@@ -424,7 +424,7 @@ export class PostsManager {
             const response = await this.axios.post(repostUrl, repostData);
             
             if (response.status === 200 || response.status === 201) {
-                return response.data;
+                return response.data?.data ?? response.data;
             } else {
                 console.error(`Ошибка репоста: ${response.status}`);
                 if (response.data) {

package/src/users.js

@@ -306,9 +306,8 @@ export class UsersManager {
             const response = await this.axios.get(topClansUrl);
 
             if (response.status === 200) {
-                const data = response.data;
-                // Структура: { clans: [...] }
-                return data.clans || [];
+                const data = response.data?.data ?? response.data;
+                return data?.clans || [];
             } else {
                 console.error(`Ошибка получения топ кланов: ${response.status}`);
                 return null;
@@ -403,15 +402,4 @@ export class UsersManager {
         const profile = await this.getMyProfile();
         return profile ? (profile.avatar || null) : null;
     }
-    
-    /**
-     * Получает клан пользователя (эмодзи аватара) (удобный метод)
-     * 
-     * @param {string} username - Имя пользователя
-     * @returns {Promise<string|null>} Эмодзи клана или null
-     */
-    async getUserClan(username) {
-        const profile = await this.getUserProfile(username);
-        return profile ? (profile.avatar || null) : null;
-    }
 }