itd-sdk-js 1.0.2 → 1.0.4

package/API_REFERENCE.md

@@ -53,13 +53,45 @@ client.auth.isAuthenticated = true;
 
 При получении ошибки `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: Посты
 
 ### createPost(text, imagePath?)
 
-Создает новый пост. При указании `imagePath` файл предварительно загружается через `/api/files/upload`, после чего ID файла прикрепляется к посту.
+Создает новый пост. При указании `imagePath` файл предварительно загружается через `/api/files/upload`, после чего ID файла прикрепляется к посту через поле `attachmentIds`.
+
+**Важно:** API использует поле `attachmentIds` (массив ID файлов), а не `attachments`. SDK автоматически использует правильное поле.
 
 - **Параметры**: `text` (string), `imagePath` (string, опционально).
 
@@ -67,8 +99,9 @@ client.auth.isAuthenticated = true;
 
 Создает пост **на стене другого пользователя** (wall post).
 
-- Делается через `POST /api/posts` с телом `{ content, wallRecipientId }`.
+- Делается через `POST /api/posts` с телом `{ content, wallRecipientId, attachmentIds? }`.
 - `wallRecipientId` — это **ID пользователя-получателя**, поэтому метод сначала запрашивает профиль через `getUserProfile(username)` и берет `profile.id`.
+- При указании `imagePath` файл загружается и прикрепляется через `attachmentIds`.
 
 - **Параметры**:
   - `username` — username получателя (string)
@@ -134,6 +167,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: Уведомления и поиск
@@ -261,3 +302,19 @@ if (result.pagination.hasMore) {
 ---
 
 **Последнее обновление документации**: 2026-01-28.
+
+## Загрузка изображений
+
+При создании поста с изображением SDK использует поле `attachmentIds` (массив ID файлов), а не `attachments`. Это правильное поле, которое требует API итд.com.
+
+**Пример:**
+```javascript
+// Создание поста с изображением
+await client.createPost('Текст поста', './image.jpg');
+// SDK автоматически:
+// 1. Загружает файл через /api/files/upload
+// 2. Получает ID файла
+// 3. Создает пост с attachmentIds: [fileId]
+```
+
+**Важно:** API возвращает attachments в ответе GET запроса, но для создания поста требуется использовать `attachmentIds` в payload.

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.2",
+  "version": "1.0.4",
   "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": "git+https://github.com/FriceKa/ITD-SDK-js.git"
+    "url": "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`;
 
@@ -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

@@ -219,6 +219,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/posts.js

@@ -47,7 +47,8 @@ export class PostsManager {
                 }
                 
                 // Затем создаем пост с ID загруженного файла
-                postData.attachments = [uploadedFile.id];
+                // Используем attachmentIds (не attachments!) - это правильное поле из API
+                postData.attachmentIds = [uploadedFile.id];
             }
             
             // Создаем пост (с изображением или без)
@@ -112,7 +113,8 @@ export class PostsManager {
                 }
                 
                 // Затем создаем пост с ID загруженного файла
-                postData.attachments = [uploadedFile.id];
+                // Используем attachmentIds (не attachments!) - это правильное поле из API
+                postData.attachmentIds = [uploadedFile.id];
             }
             
             // Создаем пост на стене