itd-sdk-js 1.0.3 → 1.0.5

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,10 +51,59 @@ 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',
+});
+client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+```
+
+- `projectRoot` — директория, в которой ищутся `.env` и `.cookies` (по умолчанию `process.cwd()`).
+- `envPath` / `cookiesPath` — при указании переопределяют пути, собранные из `projectRoot`.
+
 ### Автоматическое обновление (Refresh Token)
 
 При получении ошибки `401 Unauthorized` клиент автоматически обращается к эндпоинту `/api/v1/auth/refresh`, используя данные из `.cookies`. В случае успеха новый токен сохраняется в `.env`, обновляются куки, и исходный запрос повторяется.
 
+**Важно:** Для автоматического обновления токена необходим `refresh_token` в файле `.cookies`. Если его нет, SDK не сможет обновить токен автоматически.
+
+**Проверка наличия refresh_token:**
+```javascript
+if (client.hasRefreshToken()) {
+    console.log('✅ Refresh token доступен, токен будет обновляться автоматически');
+} else {
+    console.log('⚠️  Refresh token не найден - обновите файл .cookies');
+}
+```
+
+**Ручная проверка и обновление токена:**
+```javascript
+// Проверяет валидность токена и обновляет его при необходимости
+const isValid = await client.validateAndRefreshToken();
+if (isValid) {
+    console.log('✅ Токен валиден или успешно обновлен');
+} else {
+    console.log('❌ Токен невалиден и не удалось обновить');
+}
+```
+
+**Рекомендация для множественных запросов с интервалами:**
+Если вы делаете запросы с большими интервалами (более 10-15 минут), рекомендуется проверять токен перед каждым запросом:
+```javascript
+// Перед публикацией поста
+await client.validateAndRefreshToken();
+const post = await client.createPost('Текст поста', 'image.jpg');
+```
+
 ---
 
 ## Методы API: Посты
@@ -137,6 +188,14 @@ client.auth.isAuthenticated = true;
 - `followUser(username)` **/** `unfollowUser(username)` — подписка/отписка.
 - `getUserClan(username)` — получение эмодзи-аватара пользователя.
 
+## Методы API: Управление токенами
+
+- `hasRefreshToken()` — проверяет наличие refresh_token в cookies. Возвращает `boolean`.
+- `validateAndRefreshToken()` — проверяет валидность токена и обновляет его при необходимости. Возвращает `Promise<boolean>`.
+- `refreshAccessToken()` — принудительно обновляет токен через refresh endpoint. Возвращает `Promise<string|null>`.
+
+**Рекомендация:** При множественных запросах с интервалами (более 10-15 минут) вызывайте `validateAndRefreshToken()` перед каждым запросом.
+
 ---
 
 ## Методы API: Уведомления и поиск

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).
 
 ## Примеры
 

package/examples/token-validation.js

@@ -0,0 +1,88 @@
+/**
+ * Пример работы с токенами при множественных запросах
+ * 
+ * Демонстрирует правильную обработку истечения токена
+ * при публикации нескольких постов с интервалами
+ */
+
+import { ITDClient } from '../src/client.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function publishMultiplePosts() {
+    const client = new ITDClient();
+    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+    client.auth.isAuthenticated = true;
+    
+    console.log('📝 Публикация нескольких постов с проверкой токена\n');
+    
+    // Проверяем наличие refresh_token
+    if (!client.hasRefreshToken()) {
+        console.error('❌ ВНИМАНИЕ: refresh_token не найден в cookies!');
+        console.error('💡 Решение:');
+        console.error('   1. Откройте итд.com в браузере и войдите');
+        console.error('   2. Откройте DevTools (F12) → Network');
+        console.error('   3. Найдите любой запрос к итд.com');
+        console.error('   4. Скопируйте значение заголовка Cookie');
+        console.error('   5. Вставьте в файл .cookies в корне проекта');
+        console.error('   6. Убедитесь, что в Cookie есть refresh_token\n');
+        console.error('⚠️  Без refresh_token токен не будет обновляться автоматически!\n');
+    } else {
+        console.log('✅ Refresh token найден - токен будет обновляться автоматически\n');
+    }
+    
+    const posts = [
+        { text: 'Первый пост', image: 'image1.jpg' },
+        { text: 'Второй пост', image: 'image2.jpg' },
+        { text: 'Третий пост', image: 'image3.jpg' }
+    ];
+    
+    for (let i = 0; i < posts.length; i++) {
+        const post = posts[i];
+        console.log(`📝 Публикация поста ${i + 1}/${posts.length}...`);
+        
+        try {
+            // ВАЖНО: Проверяем и обновляем токен перед каждым запросом
+            // Это особенно важно при больших интервалах между запросами
+            const tokenValid = await client.validateAndRefreshToken();
+            
+            if (!tokenValid) {
+                console.error(`❌ Токен невалиден и не удалось обновить`);
+                console.error(`   Пропускаю пост: ${post.text}`);
+                continue;
+            }
+            
+            // Публикуем пост
+            const result = await client.createPost(post.text, post.image);
+            
+            if (result) {
+                console.log(`✅ Пост ${i + 1} опубликован: ${result.id}\n`);
+            } else {
+                console.error(`❌ Не удалось опубликовать пост ${i + 1}\n`);
+            }
+            
+        } catch (error) {
+            console.error(`❌ Ошибка при публикации поста ${i + 1}: ${error.message}\n`);
+        }
+        
+        // Имитация интервала между постами
+        if (i < posts.length - 1) {
+            console.log('⏳ Ожидание перед следующим постом...\n');
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+    }
+    
+    console.log('✅ Все посты обработаны');
+}
+
+async function main() {
+    try {
+        await publishMultiplePosts();
+    } catch (error) {
+        console.error('❌ Критическая ошибка:', error.message);
+        process.exit(1);
+    }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itd-sdk-js",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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",
@@ -15,6 +15,7 @@
     "examples/basic-usage.js",
     "examples/quick-start.js",
     "examples/user-friendly.js",
+    "examples/token-validation.js",
     "examples/README.md",
     ".env.example",
     ".cookies.example"
@@ -38,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

@@ -16,6 +16,20 @@ export class AuthManager {
         this.userData = null;
     }
     
+    /**
+     * Проверяет наличие refresh_token в cookies
+     * 
+     * @returns {boolean} True если refresh_token доступен
+     */
+    hasRefreshToken() {
+        try {
+            const cookies = this.client.cookieJar.getCookiesSync(this.client.baseUrl);
+            return cookies.some(c => c.key === 'refresh_token');
+        } catch (e) {
+            return false;
+        }
+    }
+    
     /**
      * Обновляет accessToken через /api/v1/auth/refresh
      * ВАЖНО: обычно этот endpoint работает только при наличии refresh-cookie,
@@ -24,6 +38,19 @@ export class AuthManager {
      * @returns {Promise<string|null>} accessToken или null
      */
     async refreshAccessToken() {
+        // Проверяем наличие refresh_token перед попыткой обновления
+        if (!this.hasRefreshToken()) {
+            console.error('❌ Не удалось обновить токен: refresh_token не найден в cookies');
+            console.error('💡 Решение:');
+            console.error('   1. Откройте итд.com в браузере и войдите в аккаунт');
+            console.error('   2. Откройте DevTools (F12) → Network');
+            console.error('   3. Найдите любой запрос к итд.com');
+            console.error('   4. Скопируйте значение заголовка Cookie');
+            console.error('   5. Вставьте в файл .cookies в корне проекта');
+            console.error('   6. Убедитесь, что в Cookie есть refresh_token');
+            return null;
+        }
+        
         try {
             const refreshUrl = `${this.client.baseUrl}/api/v1/auth/refresh`;
 
@@ -41,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']) {
@@ -67,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);
@@ -80,7 +107,13 @@ export class AuthManager {
             return null;
         } catch (error) {
             if (error.response) {
-                console.error('refreshAccessToken failed:', error.response.status, error.response.data);
+                const errorData = error.response.data;
+                if (errorData?.error?.code === 'REFRESH_TOKEN_MISSING') {
+                    console.error('❌ Не удалось обновить токен: refresh_token не найден');
+                    console.error('💡 Решение: обновите файл .cookies из браузера (см. инструкцию выше)');
+                } else {
+                    console.error('refreshAccessToken failed:', error.response.status, error.response.data);
+                }
             } else {
                 console.error('refreshAccessToken failed:', error.message);
             }
@@ -123,4 +156,36 @@ export class AuthManager {
         // Реальная проверка происходит на уровне API (401 ошибка)
         return !!(this.client.accessToken || this.isAuthenticated);
     }
+    
+    /**
+     * Проверяет валидность токена, делая тестовый запрос
+     * Если токен истек и есть refresh_token, автоматически обновляет его
+     * 
+     * @returns {Promise<boolean>} True если токен валиден или успешно обновлен
+     */
+    async validateAndRefreshToken() {
+        if (!this.client.accessToken) {
+            return false;
+        }
+        
+        try {
+            // Делаем легкий запрос для проверки токена
+            const profileUrl = `${this.client.baseUrl}/api/users/me`;
+            const response = await this.client.axios.get(profileUrl);
+            
+            if (response.status === 200) {
+                return true; // Токен валиден
+            }
+            
+            return false;
+        } catch (error) {
+            // Если получили 401, пытаемся обновить токен
+            if (error.response?.status === 401) {
+                const newToken = await this.refreshAccessToken();
+                return !!newToken;
+            }
+            
+            return false;
+        }
+    }
 }

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,46 @@ 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)
      */
-    constructor(baseUrl = null, userAgent = null) {
+    constructor(baseUrlOrOptions = null, userAgent = null) {
+        let baseUrl, projectRoot, envPath, cookiesPath;
+
+        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');
+        } 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');
+        }
+
         // Используем реальный домен (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;
+
         /** @type {string|null} */
         this.accessToken = null;
 
@@ -178,13 +201,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;
             }
@@ -219,6 +241,25 @@ export class ITDClient {
         return await this.auth.refreshAccessToken();
     }
     
+    /**
+     * Проверяет наличие refresh_token в cookies
+     * 
+     * @returns {boolean} True если refresh_token доступен для обновления токена
+     */
+    hasRefreshToken() {
+        return this.auth.hasRefreshToken();
+    }
+    
+    /**
+     * Проверяет валидность токена и обновляет его при необходимости
+     * Полезно вызывать перед множественными запросами с большими интервалами
+     * 
+     * @returns {Promise<boolean>} True если токен валиден или успешно обновлен
+     */
+    async validateAndRefreshToken() {
+        return await this.auth.validateAndRefreshToken();
+    }
+    
     /**
      * Выход из аккаунта
      * 

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