itd-sdk-js 1.0.5 → 1.0.7

package/API_REFERENCE.md

@@ -60,15 +60,18 @@ 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 с)
 });
 client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
 ```
 
 - `projectRoot` — директория, в которой ищутся `.env` и `.cookies` (по умолчанию `process.cwd()`).
 - `envPath` / `cookiesPath` — при указании переопределяют пути, собранные из `projectRoot`.
+- `requestTimeout` — таймаут обычных запросов в мс (по умолчанию 60000). Предотвращает бесконечное ожидание при «тяжёлой» сети.
+- `uploadTimeout` — таймаут для загрузки файлов и создания поста в мс (по умолчанию 120000). Используется в `uploadFile`, `createPost`, `createWallPost`.
 
 ### Автоматическое обновление (Refresh Token)
 
@@ -112,6 +115,10 @@ const post = await client.createPost('Текст поста', 'image.jpg');
 
 Создает новый пост. При указании `imagePath` файл предварительно загружается через `/api/files/upload`, после чего ID файла прикрепляется к посту через поле `attachmentIds`.
 
+- **Возвращает:** объект поста при успехе; **`null`** при любой ошибке (сеть, 5xx, 429, не удалось загрузить файл, неверный ответ). Всегда проверяйте результат на `null`.
+- **Таймаут:** для загрузки файла и создания поста используется `uploadTimeout` (по умолчанию 120 с), чтобы запрос не зависал при 504 или медленной сети.
+- **Ретраи:** при 5xx/429 или «API вернул null» рекомендуется повторять запрос в приложении (например, до 3–8 попыток с экспоненциальной задержкой). Встроенных ретраев в SDK нет.
+
 **Важно:** API использует поле `attachmentIds` (массив ID файлов), а не `attachments`. SDK автоматически использует правильное поле.
 
 - **Параметры**: `text` (string), `imagePath` (string, опционально).
@@ -120,6 +127,8 @@ const post = await client.createPost('Текст поста', 'image.jpg');
 
 Создает пост **на стене другого пользователя** (wall post).
 
+- **Возвращает:** объект поста при успехе; **`null`** при любой ошибке. Проверяйте результат на `null`; при 5xx/429 рекомендуется ретраи в приложении.
+- **Таймаут:** используется `uploadTimeout` (по умолчанию 120 с).
 - Делается через `POST /api/posts` с телом `{ content, wallRecipientId, attachmentIds? }`.
 - `wallRecipientId` — это **ID пользователя-получателя**, поэтому метод сначала запрашивает профиль через `getUserProfile(username)` и берет `profile.id`.
 - При указании `imagePath` файл загружается и прикрепляется через `attachmentIds`.
@@ -165,11 +174,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')`.
 
 ### Управление комментариями
 
@@ -216,14 +238,14 @@ const post = await client.createPost('Текст поста', 'image.jpg');
 - `search(query, userLimit?, hashtagLimit?)` — универсальный поиск пользователей и хэштегов. Возвращает `{ users: [], hashtags: [] }`.
 - `searchUsers(query, limit?)` — поиск только пользователей.
 - `searchHashtags(query, limit?)` — поиск только хэштегов.
-- `getTopClans()` — рейтинг кланов по количеству участников. Возвращает `{ clans: [{ avatar, memberCount }] }`.
+- `getTopClans()` — рейтинг кланов по количеству участников. **Возвращает массив** `Array<{ avatar, memberCount }>` или **`null`** при ошибке (не объект с полем `clans`).
 - `getWhoToFollow()` — рекомендованные пользователи.
 - `getTrendingHashtags(limit)` — список популярных тегов.
 - `getPostsByHashtag(tagName, limit, cursor)` — поиск постов по тегу. Возвращает `{ posts: [], hashtag: {}, pagination: {} }`.
 
 ### Файлы и репорты
 
-- `uploadFile(filePath)` — загрузка файла через `/api/files/upload`. Возвращает `{ id, url, filename, mimeType, size }`. Используется автоматически при создании поста с изображением.
+- `uploadFile(filePath)` — загрузка файла через `/api/files/upload`. Возвращает `{ id, url, filename, mimeType, size }` или **`null`** при ошибке. Таймаут — `uploadTimeout` (по умолчанию 120 с). Используется автоматически при создании поста с изображением.
 - `report(targetType, targetId, reason?, description?)` — отправка репорта. `targetType`: `"post"`, `"comment"`, `"user"`. Возвращает `{ id, createdAt }`.
 - `reportPost(postId, reason?, description?)` — репорт поста.
 - `reportComment(commentId, reason?, description?)` — репорт комментария.

package/README.md

@@ -91,6 +91,12 @@ console.log(`${stats.likes} лайков, ${stats.views} просмотров`);
 await client.createWallPost('ITD_API', 'Тестовый пост на чужой стене 🦫');
 ```
 
+## Рекомендации при создании постов
+
+- **createPost** и **createWallPost** при любой ошибке возвращают **`null`** — всегда проверяйте результат.
+- Для загрузки файла и создания поста используется таймаут **120 с** по умолчанию (`uploadTimeout` в опциях клиента), чтобы запрос не зависал при 504 или медленной сети.
+- При 5xx/429 или «API вернул null» рекомендуется повторять запрос в приложении (ретраи с задержкой). Подробнее — в [API_REFERENCE.md](API_REFERENCE.md).
+
 ## Важно
 
 Это неофициальный проект. Если разработчики сайта изменят структуру API или введут новую защиту, методы могут временно перестать работать. Используйте аккуратно и не спамьте запросами.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itd-sdk-js",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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/client.js

@@ -32,9 +32,11 @@ export class ITDClient {
      * @param {string} [options.projectRoot] - Корень проекта (по умолчанию process.cwd()); .env и .cookies ищутся здесь
      * @param {string} [options.envPath] - Полный путь к .env (переопределяет projectRoot для .env)
      * @param {string} [options.cookiesPath] - Полный путь к .cookies (переопределяет projectRoot для .cookies)
+     * @param {number} [options.requestTimeout] - Таймаут обычных запросов в мс (по умолчанию 60000)
+     * @param {number} [options.uploadTimeout] - Таймаут загрузки файлов и создания поста в мс (по умолчанию 120000)
      */
     constructor(baseUrlOrOptions = null, userAgent = null) {
-        let baseUrl, projectRoot, envPath, cookiesPath;
+        let baseUrl, projectRoot, envPath, cookiesPath, requestTimeout, uploadTimeout;
 
         if (baseUrlOrOptions && typeof baseUrlOrOptions === 'object' && !(baseUrlOrOptions instanceof URL)) {
             const opts = baseUrlOrOptions;
@@ -43,11 +45,15 @@ export class ITDClient {
             projectRoot = opts.projectRoot ?? process.cwd();
             envPath = opts.envPath ?? path.join(projectRoot, '.env');
             cookiesPath = opts.cookiesPath ?? path.join(projectRoot, '.cookies');
+            requestTimeout = opts.requestTimeout ?? 60000;
+            uploadTimeout = opts.uploadTimeout ?? 120000;
         } else {
             projectRoot = process.cwd();
             baseUrl = baseUrlOrOptions || process.env.ITD_BASE_URL || 'https://xn--d1ah4a.com';
             envPath = path.join(projectRoot, '.env');
             cookiesPath = path.join(projectRoot, '.cookies');
+            requestTimeout = 60000;
+            uploadTimeout = 120000;
         }
 
         // Используем реальный домен (IDN: итд.com = xn--d1ah4a.com)
@@ -59,6 +65,11 @@ export class ITDClient {
         this.envPath = envPath;
         this.cookiesPath = cookiesPath;
 
+        /** Таймаут обычных запросов (мс). Для загрузки и создания поста используется uploadTimeout. */
+        this.requestTimeout = requestTimeout;
+        /** Таймаут загрузки файлов и создания поста (мс), чтобы не зависать при 504/медленной сети. */
+        this.uploadTimeout = uploadTimeout;
+
         /** @type {string|null} */
         this.accessToken = null;
 
@@ -78,6 +89,7 @@ export class ITDClient {
         // Создание axios instance + cookie jar
         const axiosConfig = {
             baseURL: this.baseUrl,
+            timeout: requestTimeout,
             withCredentials: true,
             jar: this.cookieJar,
             headers: {
@@ -469,6 +481,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);
+    }
     
     /**
      * Ставит лайк на комментарий

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);

package/src/files.js

@@ -11,8 +11,9 @@ export class FilesManager {
     }
 
     /**
-     * Загружает файл (изображение) на сервер
-     * 
+     * Загружает файл (изображение) на сервер.
+     * Таймаут — client.uploadTimeout (по умолчанию 120 с). При ошибке возвращает null.
+     *
      * @param {string} filePath - Путь к файлу
      * @returns {Promise<Object|null>} { id, url, filename, mimeType, size } или null при ошибке
      */
@@ -36,6 +37,7 @@ export class FilesManager {
             formData.append('file', fs.createReadStream(filePath));
 
             const response = await this.axios.post(uploadUrl, formData, {
+                timeout: this.client.uploadTimeout ?? 120000,
                 headers: {
                     ...formData.getHeaders(),
                 }

package/src/posts.js

@@ -16,8 +16,10 @@ export class PostsManager {
     }
     
     /**
-     * Создает новый пост
-     * 
+     * Создает новый пост.
+     * При любой ошибке (сеть, 5xx, 429, не удалось загрузить файл) возвращает null.
+     * Таймаут загрузки и создания — client.uploadTimeout (по умолчанию 120 с).
+     *
      * @param {string} text - Текст поста
      * @param {string|null} imagePath - Путь к изображению (опционально)
      * @returns {Promise<Object|null>} Данные созданного поста или null при ошибке
@@ -51,9 +53,11 @@ export class PostsManager {
                 postData.attachmentIds = [uploadedFile.id];
             }
             
-            // Создаем пост (с изображением или без)
-            const response = await this.axios.post(postUrl, postData);
-            
+            // Создаем пост (с изображением или без); увеличенный таймаут для тяжёлых запросов
+            const response = await this.axios.post(postUrl, postData, {
+                timeout: this.client.uploadTimeout ?? 120000,
+            });
+
             if (response.status === 200 || response.status === 201) {
                 return response.data;
             } else {
@@ -71,8 +75,9 @@ export class PostsManager {
     }
     
     /**
-     * Создает пост на стене другого пользователя (wall post)
-     * 
+     * Создает пост на стене другого пользователя (wall post).
+     * При любой ошибке возвращает null. Таймаут — client.uploadTimeout (по умолчанию 120 с).
+     *
      * @param {string} username - Имя пользователя, на чью стену нужно написать
      * @param {string} text - Текст поста
      * @param {string|null} imagePath - Путь к изображению (опционально)
@@ -117,9 +122,11 @@ export class PostsManager {
                 postData.attachmentIds = [uploadedFile.id];
             }
             
-            // Создаем пост на стене
-            const response = await this.axios.post(postUrl, postData);
-            
+            // Создаем пост на стене; увеличенный таймаут для тяжёлых запросов
+            const response = await this.axios.post(postUrl, postData, {
+                timeout: this.client.uploadTimeout ?? 120000,
+            });
+
             if (response.status === 200 || response.status === 201) {
                 return response.data;
             } else {

package/src/users.js

@@ -295,9 +295,10 @@ export class UsersManager {
     }
 
     /**
-     * Получает топ кланов по количеству участников
-     * 
-     * @returns {Promise<Array|null>} Массив кланов [{ avatar: "🦎", memberCount: 3794 }, ...] или null при ошибке
+     * Получает топ кланов по количеству участников.
+     * Возвращает массив (Array), не объект с полем clans.
+     *
+     * @returns {Promise<Array|null>} Массив кланов [{ avatar, memberCount }, ...] или null при ошибке
      */
     async getTopClans() {
         try {