itd-sdk-js 1.0.6 → 1.0.8

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()`).
@@ -174,11 +194,24 @@ const post = await client.createPost('Текст поста', 'image.jpg');
 
 Получает дерево комментариев к посту.
 
-- **Параметры**: `postId`, `limit`, `sort` (`popular`, `new`, `old`).
+- **Параметры**: `postId`, `limit` (по умолчанию 20, в запросе ограничивается 1–100), `sort` — в SDK можно передавать `"popular"`, `"new"`, `"old"`; в API уходит `popular`, `newest`, `oldest` соответственно.
+- **Ответ API:** `{ data: { comments: [], total, hasMore, nextCursor } }`. Комментарии могут содержать вложенные `replies`, у ответов — поле `replyTo`.
 
 ### addComment(postId, text, replyToCommentId?)
 
-Добавляет новый комментарий или ответ на существующий.
+Добавляет новый комментарий или ответ на существующий (POST к посту: `/api/posts/:postId/comments`).
+
+### replyToComment(commentId, content, replyToUserId)
+
+Ответ на комментарий через отдельный эндпоинт **POST** `/api/comments/:commentId/replies`.
+
+- **Параметры**:
+  - `commentId` — ID комментария, на который отвечаем.
+  - `content` — текст ответа.
+  - `replyToUserId` — ID пользователя-автора комментария (обязательно для API).
+- **Возвращает:** объект созданного комментария-ответа или `null` при ошибке.
+
+Пример: `client.replyToComment('80a775df-811a-4b60-b2fd-24651c1e546e', 'кака', '220e565c-45b9-4634-bdba-a6ebe6e8c5d1')`.
 
 ### Управление комментариями
 
@@ -200,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.6",
+  "version": "1.0.8",
   "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,8 +129,6 @@ 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'] = '';
@@ -152,9 +147,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
@@ -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
@@ -481,6 +544,18 @@ export class ITDClient {
     async addComment(postId, text, replyToCommentId = null) {
         return await this.comments.addComment(postId, text, replyToCommentId);
     }
+
+    /**
+     * Ответ на комментарий (POST /api/comments/:id/replies).
+     *
+     * @param {string} commentId - ID комментария, на который отвечаем
+     * @param {string} content - Текст ответа
+     * @param {string} replyToUserId - ID пользователя-автора комментария (обязательно для API)
+     * @returns {Promise<Object|null>} Данные созданного комментария-ответа или null при ошибке
+     */
+    async replyToComment(commentId, content, replyToUserId) {
+        return await this.comments.replyToComment(commentId, content, replyToUserId);
+    }
     
     /**
      * Ставит лайк на комментарий
@@ -883,15 +958,6 @@ export class ITDClient {
     
     // === Пользователи ===
     
-    /**
-     * Получает свой профиль (удобный метод)
-     * 
-     * @returns {Promise<Object|null>} Данные профиля или null
-     */
-    async getMyProfile() {
-        return await this.users.getMyProfile();
-    }
-    
     /**
      * Проверяет, подписан ли текущий пользователь на указанного (удобный метод)
      * 

package/src/comments.js

@@ -54,58 +54,107 @@ export class CommentsManager {
             return null;
         }
     }
+
+    /**
+     * Ответ на комментарий (отдельный эндпоинт /api/comments/:id/replies).
+     *
+     * @param {string} commentId - ID комментария, на который отвечаем
+     * @param {string} content - Текст ответа
+     * @param {string} replyToUserId - ID пользователя-автора комментария (обязательно для API)
+     * @returns {Promise<Object|null>} Данные созданного комментария-ответа или null при ошибке
+     */
+    async replyToComment(commentId, content, replyToUserId) {
+        if (!await this.client.auth.checkAuth()) {
+            console.error('Ошибка: необходимо войти в аккаунт');
+            return null;
+        }
+        if (!replyToUserId) {
+            console.error('Ошибка: replyToUserId обязателен для ответа на комментарий');
+            return null;
+        }
+        try {
+            const url = `${this.client.baseUrl}/api/comments/${commentId}/replies`;
+            const response = await this.axios.post(url, {
+                content,
+                replyToUserId,
+            });
+            if (response.status === 200 || response.status === 201) {
+                return response.data;
+            }
+            console.error(`Ошибка ответа на комментарий: ${response.status} - ${JSON.stringify(response.data)}`);
+            return null;
+        } catch (error) {
+            console.error('Исключение при ответе на комментарий:', error.message);
+            if (error.response) {
+                console.error('Response status:', error.response.status);
+                console.error('Response data:', error.response.data);
+            }
+            return null;
+        }
+    }
     
     /**
-     * Получает комментарии к посту
-     * 
+     * Получает комментарии к посту.
+     * API ожидает sort: "newest" | "oldest" | "popular". SDK принимает "new"/"old"/"popular" и маппит в newest/oldest/popular.
+     *
      * @param {string} postId - ID поста
-     * @param {number} limit - Количество комментариев
-     * @param {string} sort - Сортировка: "popular", "new", "old" (по умолчанию "popular")
+     * @param {number} limit - Количество комментариев (по умолчанию 20)
+     * @param {string} sort - Сортировка: "popular", "new", "old" (в API уходит как popular, newest, oldest)
      * @returns {Promise<Object>} { comments: [], total, hasMore, nextCursor } или { comments: [] } при ошибке
-     * 
-     * Примечание: Авторизация не требуется для просмотра комментариев
      */
     async getComments(postId, limit = 20, sort = 'popular') {
+        const commentsUrl = `${this.client.baseUrl}/api/posts/${postId}/comments`;
+        const reqLimit = Math.min(Math.max(1, Number(limit) || 20), 100);
+        const sortMap = { new: 'newest', old: 'oldest', popular: 'popular', newest: 'newest', oldest: 'oldest' };
+        const reqSort = sortMap[sort] || 'popular';
+
+        const parseResponse = (response) => {
+            const data = response.data?.data ?? response.data;
+            if (data?.comments) {
+                return {
+                    comments: data.comments,
+                    total: data.total ?? data.comments.length,
+                    hasMore: data.hasMore ?? false,
+                    nextCursor: data.nextCursor ?? null
+                };
+            }
+            if (Array.isArray(data)) {
+                return {
+                    comments: data,
+                    total: data.length,
+                    hasMore: false,
+                    nextCursor: null
+                };
+            }
+            return { comments: [], total: 0, hasMore: false, nextCursor: null };
+        };
+
         try {
-            const commentsUrl = `${this.client.baseUrl}/api/posts/${postId}/comments`;
-            const params = {
-                limit: limit,
-                sort: sort,
-            };
-            
-            const response = await this.axios.get(commentsUrl, { params });
-            
+            const response = await this.axios.get(commentsUrl, {
+                params: { limit: reqLimit, sort: reqSort },
+            });
+
             if (response.status === 200) {
-                const data = response.data;
-                // Структура: { data: { comments: [...], total, hasMore, nextCursor } }
-                if (data.data && data.data.comments) {
-                    return {
-                        comments: data.data.comments,
-                        total: data.data.total || 0,
-                        hasMore: data.data.hasMore || false,
-                        nextCursor: data.data.nextCursor || null
-                    };
-                } else if (data.comments) {
-                    return {
-                        comments: data.comments,
-                        total: data.total || 0,
-                        hasMore: data.hasMore || false,
-                        nextCursor: data.nextCursor || null
-                    };
-                } else if (Array.isArray(data)) {
-                    return {
-                        comments: data,
-                        total: data.length,
-                        hasMore: false,
-                        nextCursor: null
-                    };
+                return parseResponse(response);
+            }
+            if (response.status === 422) {
+                const fallback = await this.axios.get(commentsUrl, { params: { limit: reqLimit, sort: 'popular' } });
+                if (fallback.status === 200) {
+                    return parseResponse(fallback);
                 }
-                return { comments: [], total: 0, hasMore: false, nextCursor: null };
-            } else {
-                console.error(`Ошибка получения комментариев: ${response.status}`);
-                return { comments: [], total: 0, hasMore: false, nextCursor: null };
+                console.warn('⚠️  GET /api/posts/:postId/comments: 422. API ожидает sort: newest | oldest | popular.');
             }
+            console.error(`Ошибка получения комментариев: ${response.status}`);
+            return { comments: [], total: 0, hasMore: false, nextCursor: null };
         } catch (error) {
+            if (error.response?.status === 422) {
+                try {
+                    const retry = await this.axios.get(commentsUrl, { params: { limit: 20, sort: 'popular' } });
+                    if (retry.status === 200) {
+                        return parseResponse(retry);
+                    }
+                } catch (_) {}
+            }
             console.error('Исключение при получении комментариев:', error.message);
             if (error.response) {
                 console.error('Response status:', error.response.status);