itd-sdk-js 1.0.4 → 1.0.6

package/API_REFERENCE.md

@@ -30,15 +30,17 @@ import { ITDClient } from 'itd-sdk-js';
 
 Для работы автоматического обновления токена создайте файл `.cookies` в корне проекта. Скопируйте содержимое заголовка `Cookie` из любого сетевого запроса к сайту в браузере и вставьте в этот файл.
 
+**Пути к .env и .cookies:** по умолчанию SDK ищет и сохраняет эти файлы в **корне проекта** (`process.cwd()`). При refresh токена обновлённые значения пишутся в ваш проект, а не в папку пакета. При необходимости можно задать свой корень или явные пути через опции конструктора (см. ниже).
+
 ---
 
 ## Авторизация и сессии
 
 ### Инициализация клиента
 
-JavaScript
+**Простой вариант (корень проекта = текущая рабочая директория):**
 
-```
+```javascript
 import { ITDClient } from 'itd-sdk-js';
 import dotenv from 'dotenv';
 
@@ -49,6 +51,28 @@ client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
 client.auth.isAuthenticated = true;
 ```
 
+**С опциями (projectRoot / envPath / cookiesPath):**
+
+Если скрипт запускается из подпапки или нужны явные пути:
+
+```javascript
+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)
 
 При получении ошибки `401 Unauthorized` клиент автоматически обращается к эндпоинту `/api/v1/auth/refresh`, используя данные из `.cookies`. В случае успеха новый токен сохраняется в `.env`, обновляются куки, и исходный запрос повторяется.
@@ -91,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, опционально).
@@ -99,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`.
@@ -195,14 +225,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

@@ -26,11 +26,11 @@ npm install
 
 ## Настройка
 
-1. Создайте `.env` на основе `.env.example` (или используйте переменные окружения).
+1. Создайте `.env` в корне проекта на основе `.env.example` (или используйте переменные окружения).
 2. Вставьте свой `ITD_ACCESS_TOKEN` (его можно вытащить из Network в DevTools).
-3. Для работы авто-обновления сессии создайте файл `.cookies` и вставьте туда строку `Cookie` из любого запроса к сайту в браузере.
+3. Для работы авто-обновления сессии создайте файл `.cookies` в корне проекта и вставьте туда строку `Cookie` из любого запроса к сайту в браузере.
 
-Подробный гайд по настройке лежит в [API_REFERENCE.md](API_REFERENCE.md).
+SDK по умолчанию читает и пишет `.env` и `.cookies` в корне проекта (`process.cwd()`). При обновлении токена изменения сохраняются в ваш проект. При необходимости можно задать `projectRoot` или явные пути в конструкторе — см. [API_REFERENCE.md](API_REFERENCE.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.4",
+  "version": "1.0.6",
   "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",
@@ -39,7 +39,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/FriceKa/ITD-SDK-js.git"
+    "url": "git+https://github.com/FriceKa/ITD-SDK-js.git"
   },
   "bugs": {
     "url": "https://github.com/FriceKa/ITD-SDK-js/issues"

package/src/auth.js

@@ -68,8 +68,8 @@ export class AuthManager {
                 this.client.setAccessToken(newToken);
                 this.isAuthenticated = true;
                 
-                // Сохраняем токен в .env файл
-                await saveAccessToken(newToken);
+                // Сохраняем токен в .env файл (в корне проекта)
+                await saveAccessToken(newToken, this.client.envPath);
                 
                 // Обновляем cookies, если они пришли в ответе
                 if (response.headers['set-cookie']) {
@@ -94,7 +94,7 @@ export class AuthManager {
                         );
                         if (importantCookies.length > 0) {
                             const cookieHeader = importantCookies.map(c => `${c.key}=${c.value}`).join('; ');
-                            await saveCookieHeader(cookieHeader);
+                            await saveCookieHeader(cookieHeader, this.client.cookiesPath);
                         }
                     } catch (e) {
                         console.warn('⚠️  Не удалось сохранить обновленные cookies:', e.message);

package/src/client.js

@@ -5,7 +5,6 @@ import axios from 'axios';
 import dotenv from 'dotenv';
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
 import { CookieJar } from 'tough-cookie';
 import { wrapper } from 'axios-cookiejar-support';
 import { AuthManager } from './auth.js';
@@ -20,22 +19,57 @@ import { SearchManager } from './search.js';
 
 dotenv.config();
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
 export class ITDClient {
     /**
      * Инициализация клиента
      * 
-     * @param {string} baseUrl - Базовый URL сайта (по умолчанию из .env)
-     * @param {string} userAgent - User-Agent для запросов (по умолчанию из .env)
+     * @param {string|Object} baseUrlOrOptions - Базовый URL сайта или объект опций
+     * @param {string} [userAgent] - User-Agent (если первый аргумент — baseUrl)
+     * 
+     * Опции (если первый аргумент — объект):
+     * @param {string} [options.baseUrl] - Базовый URL сайта
+     * @param {string} [options.userAgent] - User-Agent
+     * @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(baseUrl = null, userAgent = null) {
+    constructor(baseUrlOrOptions = null, userAgent = null) {
+        let baseUrl, projectRoot, envPath, cookiesPath, requestTimeout, uploadTimeout;
+
+        if (baseUrlOrOptions && typeof baseUrlOrOptions === 'object' && !(baseUrlOrOptions instanceof URL)) {
+            const opts = baseUrlOrOptions;
+            baseUrl = opts.baseUrl ?? process.env.ITD_BASE_URL ?? 'https://xn--d1ah4a.com';
+            userAgent = opts.userAgent ?? process.env.ITD_USER_AGENT ?? null;
+            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)
-        this.baseUrl = baseUrl || process.env.ITD_BASE_URL || 'https://xn--d1ah4a.com';
-        this.userAgent = userAgent || process.env.ITD_USER_AGENT || 
+        this.baseUrl = baseUrl;
+        this.userAgent = userAgent || process.env.ITD_USER_AGENT ||
             'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
 
+        /** Пути к .env и .cookies (корень проекта по умолчанию) */
+        this.envPath = envPath;
+        this.cookiesPath = cookiesPath;
+
+        /** Таймаут обычных запросов (мс). Для загрузки и создания поста используется uploadTimeout. */
+        this.requestTimeout = requestTimeout;
+        /** Таймаут загрузки файлов и создания поста (мс), чтобы не зависать при 504/медленной сети. */
+        this.uploadTimeout = uploadTimeout;
+
         /** @type {string|null} */
         this.accessToken = null;
 
@@ -55,6 +89,7 @@ export class ITDClient {
         // Создание axios instance + cookie jar
         const axiosConfig = {
             baseURL: this.baseUrl,
+            timeout: requestTimeout,
             withCredentials: true,
             jar: this.cookieJar,
             headers: {
@@ -178,13 +213,12 @@ export class ITDClient {
      */
     _loadCookiesFromFile() {
         try {
-            const cookiesPath = path.join(__dirname, '..', '.cookies');
-            if (!fs.existsSync(cookiesPath)) {
+            if (!fs.existsSync(this.cookiesPath)) {
                 // Файл не существует - это нормально, просто пропускаем
                 return;
             }
             
-            const cookieHeader = fs.readFileSync(cookiesPath, 'utf8').trim();
+            const cookieHeader = fs.readFileSync(this.cookiesPath, 'utf8').trim();
             if (!cookieHeader) {
                 return;
             }

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/token-storage.js

@@ -3,27 +3,24 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
 
 /**
  * Обновляет ITD_ACCESS_TOKEN в .env файле
- * 
+ *
  * @param {string} newToken - Новый access token
+ * @param {string} [envPath] - Путь к .env (по умолчанию process.cwd() + '/.env')
  * @returns {Promise<boolean>} True если успешно
  */
-export async function saveAccessToken(newToken) {
+export async function saveAccessToken(newToken, envPath = null) {
     try {
-        const envPath = path.join(__dirname, '..', '.env');
-        
-        if (!fs.existsSync(envPath)) {
+        const targetPath = envPath ?? path.join(process.cwd(), '.env');
+
+        if (!fs.existsSync(targetPath)) {
             console.warn('⚠️  Файл .env не найден, токен не сохранен');
             return false;
         }
-        
-        let content = fs.readFileSync(envPath, 'utf8');
+
+        let content = fs.readFileSync(targetPath, 'utf8');
         
         // Ищем строку с ITD_ACCESS_TOKEN
         const tokenRegex = /^ITD_ACCESS_TOKEN=.*$/m;
@@ -36,7 +33,7 @@ export async function saveAccessToken(newToken) {
             content += `\nITD_ACCESS_TOKEN=${newToken}\n`;
         }
         
-        fs.writeFileSync(envPath, content, 'utf8');
+        fs.writeFileSync(targetPath, content, 'utf8');
         console.log('✅ Токен сохранен в .env');
         return true;
     } catch (error) {
@@ -47,16 +44,17 @@ export async function saveAccessToken(newToken) {
 
 /**
  * Сохраняет cookies в файл .cookies
- * 
+ *
  * @param {string} newCookieHeader - Новый cookie header
+ * @param {string} [cookiesPath] - Путь к .cookies (по умолчанию process.cwd() + '/.cookies')
  * @returns {Promise<boolean>} True если успешно
  */
-export async function saveCookieHeader(newCookieHeader) {
+export async function saveCookieHeader(newCookieHeader, cookiesPath = null) {
     try {
-        const cookiesPath = path.join(__dirname, '..', '.cookies');
-        
+        const targetPath = cookiesPath ?? path.join(process.cwd(), '.cookies');
+
         // Просто записываем cookies в файл (одна строка)
-        fs.writeFileSync(cookiesPath, newCookieHeader, 'utf8');
+        fs.writeFileSync(targetPath, newCookieHeader, 'utf8');
         console.log('✅ Cookies сохранены в .cookies');
         return true;
     } catch (error) {

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 {