itd-sdk-js 1.0.0

package/.cookies.example

@@ -0,0 +1 @@
+refresh_token=YOUR_REFRESH_TOKEN_HERE; __ddg1_=...; is_auth=1; __ddgid_=...; __ddgmark_=...; __ddg5_=...; __ddg2_=...; ddg_last_challenge=...; __ddg9_=...; __ddg8_=...; __ddg10_=...

package/.env.example

@@ -0,0 +1,45 @@
+# ============================================
+# ITD SDK - Конфигурация
+# ============================================
+# Скопируйте этот файл в .env и заполните своими данными
+# cp .env.example .env
+
+# ============================================
+# Access Token (JWT) - ОБЯЗАТЕЛЬНО
+# ============================================
+# JWT токен для авторизации запросов
+# Получите из браузера:
+# 1. Откройте итд.com в браузере и войдите
+# 2. Откройте DevTools (F12) → Network
+# 3. Найдите запрос POST /api/v1/auth/refresh
+# 4. Скопируйте accessToken из ответа
+# 5. Вставьте сюда
+# 
+# ВАЖНО: Токен автоматически обновляется при использовании refresh_token из .cookies
+ITD_ACCESS_TOKEN=your_access_token_here
+
+# ============================================
+# Базовый URL
+# ============================================
+# URL сайта итд.com (IDN домен)
+# Обычно не нужно менять
+ITD_BASE_URL=https://xn--d1ah4a.com
+
+# ============================================
+# User-Agent
+# ============================================
+# User-Agent для HTTP запросов
+# Имитирует реальный браузер
+# Обычно не нужно менять
+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
+
+# ============================================
+# Прокси (опционально)
+# ============================================
+# Если используете прокси (например, V2RayN, Clash и т.д.)
+# Раскомментируйте и укажите адрес прокси
+# 
+# Формат: http://127.0.0.1:10808
+# 
+# ВАЖНО: Должен быть HTTP CONNECT proxy, не SOCKS
+# ITD_PROXY=http://127.0.0.1:10808

package/API_REFERENCE.md

@@ -0,0 +1,237 @@
+# API Reference — итд.com (Node.js SDK)
+
+Техническое руководство по методам и настройке библиотеки для работы с API сайта `итд.com`.
+
+## Настройка проекта
+
+### 1. Переменные окружения (.env)
+
+Создайте файл `.env` в корне проекта и укажите следующие параметры:
+
+- `ITD_ACCESS_TOKEN` — ваш JWT токен.
+- `ITD_BASE_URL` — `https://xn--d1ah4a.com`.
+- `ITD_USER_AGENT` — строка User-Agent из браузера.
+
+### 2. Файл .cookies
+
+Для работы автоматического обновления токена создайте файл `.cookies` в корне проекта. Скопируйте содержимое заголовка `Cookie` из любого сетевого запроса к сайту в браузере и вставьте в этот файл.
+
+---
+
+## Авторизация и сессии
+
+### Инициализация клиента
+
+JavaScript
+
+```
+import { ITDClient } from './src/client.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const client = new ITDClient();
+client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+client.auth.isAuthenticated = true;
+```
+
+### Автоматическое обновление (Refresh Token)
+
+При получении ошибки `401 Unauthorized` клиент автоматически обращается к эндпоинту `/api/v1/auth/refresh`, используя данные из `.cookies`. В случае успеха новый токен сохраняется в `.env`, обновляются куки, и исходный запрос повторяется.
+
+---
+
+## Методы API: Посты
+
+### createPost(text, imagePath?)
+
+Создает новый пост. При указании `imagePath` файл предварительно загружается через `/api/files/upload`, после чего ID файла прикрепляется к посту.
+
+- **Параметры**: `text` (string), `imagePath` (string, опционально).
+
+### getPost(postId)
+
+Запрашивает данные конкретного поста.
+
+- **Возвращает**: Объект с контентом, автором и вложенными комментариями.
+
+### getPosts(username, limit, sort, cursor, tab, type, filter)
+
+Универсальный метод получения списков постов.
+
+- **Параметры**:
+  - `username` — имя пользователя (null для общей ленты).
+  - `limit` — количество записей (default: 20).
+  - `sort` — `new`, `old`, `popular`, `trending`, `recent`.
+  - `tab` — `popular`, `following` или null.
+  - `cursor` — идентификатор для пагинации.
+
+### Прочие методы постов
+
+- `getFeedPopular(limit, cursor)` — лента популярных постов. Возвращает `{ posts: [], pagination: {} }`.
+- `getFeedFollowing(limit, cursor)` — лента подписок. Требует авторизацию. Возвращает `{ posts: [], pagination: {} }`.
+- `getPostsList(username?, limit?)` — упрощенный метод, возвращает только массив постов (без pagination).
+- `editPost(postId, newContent)` — редактирование текста. Возвращает обновленный объект поста.
+- `deletePost(postId)` — удаление поста. Возвращает `boolean`.
+- `pinPost(postId)` — закрепление записи. Возвращает `boolean`.
+- `repost(postId, comment?)` — репост (нельзя репостнуть себя). Возвращает объект репоста.
+- `likePost(postId)` **/** `unlikePost(postId)` — управление лайками. Возвращают `{ liked: boolean, likesCount: number }`.
+
+---
+
+## Методы API: Комментарии
+
+### getComments(postId, limit, sort)
+
+Получает дерево комментариев к посту.
+
+- **Параметры**: `postId`, `limit`, `sort` (`popular`, `new`, `old`).
+
+### addComment(postId, text, replyToCommentId?)
+
+Добавляет новый комментарий или ответ на существующий.
+
+### Управление комментариями
+
+- `likeComment(commentId)` **/** `unlikeComment(commentId)` — лайки на комментарии.
+- `deleteComment(commentId)` — удаление комментария.
+
+---
+
+## Методы API: Профили и подписки
+
+- `getMyProfile()` — данные текущего аккаунта (требует auth).
+- `getUserProfile(username)` — публичный профиль любого пользователя.
+- `updateProfile(bio, displayName?)` — изменение описания и имени.
+- `getFollowers(username, page, limit)` — список подписчиков.
+- `getFollowing(username, page, limit)` — список подписок.
+- `followUser(username)` **/** `unfollowUser(username)` — подписка/отписка.
+- `getUserClan(username)` — получение эмодзи-аватара пользователя.
+
+---
+
+## Методы API: Уведомления и поиск
+
+### getNotifications(limit, cursor, type?)
+
+Список уведомлений с фильтрацией по типу (`reply`, `like`, `wall_post`, `follow`, `comment`).
+
+### Прочие методы уведомлений
+
+- `getNotificationsByType(type, limit, cursor)` — получение уведомлений конкретного типа.
+- `markNotificationAsRead(notificationId)` — пометка прочитанным. Возвращает `{ success: true }`.
+- `markAllNotificationsAsRead()` — пометка всех уведомлений (экспериментально).
+- `getNotificationCount()` — счетчик непрочитанных сообщений. Возвращает `number`.
+
+### Поиск и рекомендации
+
+- `search(query, userLimit?, hashtagLimit?)` — универсальный поиск пользователей и хэштегов. Возвращает `{ users: [], hashtags: [] }`.
+- `searchUsers(query, limit?)` — поиск только пользователей.
+- `searchHashtags(query, limit?)` — поиск только хэштегов.
+- `getTopClans()` — рейтинг кланов по количеству участников. Возвращает `{ clans: [{ avatar, memberCount }] }`.
+- `getWhoToFollow()` — рекомендованные пользователи.
+- `getTrendingHashtags(limit)` — список популярных тегов.
+- `getPostsByHashtag(tagName, limit, cursor)` — поиск постов по тегу. Возвращает `{ posts: [], hashtag: {}, pagination: {} }`.
+
+### Файлы и репорты
+
+- `uploadFile(filePath)` — загрузка файла через `/api/files/upload`. Возвращает `{ id, url, filename, mimeType, size }`. Используется автоматически при создании поста с изображением.
+- `report(targetType, targetId, reason?, description?)` — отправка репорта. `targetType`: `"post"`, `"comment"`, `"user"`. Возвращает `{ id, createdAt }`.
+- `reportPost(postId, reason?, description?)` — репорт поста.
+- `reportComment(commentId, reason?, description?)` — репорт комментария.
+- `reportUser(userId, reason?, description?)` — репорт пользователя.
+
+---
+
+## Вспомогательные методы (Helpers)
+
+Методы для быстрого доступа к статистике без парсинга полных объектов:
+
+### Посты
+
+- `getTrendingPosts(limit, cursor)` — трендовые посты. Возвращает `{ posts: [], pagination: {} }`.
+- `getRecentPosts(limit, cursor)` — недавние посты. Возвращает `{ posts: [], pagination: {} }`.
+- `getMyPosts(limit, sort, cursor)` — свои посты. Требует авторизацию.
+- `getUserLatestPost(username)` — последний пост пользователя. Возвращает объект поста или `null`.
+- `getPostStats(postId)` — возвращает `{ likes: number, views: number, comments: number, reposts: number }` или `null`.
+- `getPostLikesCount(postId)`, `getPostViewsCount(postId)`, `getPostCommentsCount(postId)` — получение отдельных счетчиков. Возвращают `number`.
+
+### Пользователи
+
+- `getMyClan()` — свой клан (эмодзи). Возвращает `string` или `null`.
+- `getMyFollowersCount()`, `getMyFollowingCount()` — количество подписчиков/подписок. Возвращают `number`.
+- `isFollowing(username)` — проверка наличия подписки на пользователя. Возвращает `boolean`.
+
+### Комментарии
+
+- `getTopComment(postId)` — получение самого популярного комментария поста. Возвращает объект комментария или `null`.
+- `hasComments(postId)` — проверка наличия комментариев. Возвращает `boolean`.
+
+### Уведомления
+
+- `hasUnreadNotifications()` — проверка наличия непрочитанных уведомлений. Возвращает `boolean`.
+- `getUnreadNotifications(limit, cursor)` — только непрочитанные уведомления. Возвращает `{ notifications: [], pagination: {} }`.
+
+---
+
+## Структура данных
+
+### Пагинация
+
+Методы, возвращающие списки, используют курсорную пагинацию:
+
+```javascript
+const result = await client.getPosts('username', 20, 'new');
+// result = { posts: [...], pagination: { limit: 20, nextCursor: "...", hasMore: true } }
+
+// Следующая страница
+if (result.pagination.hasMore) {
+    const nextPage = await client.getPosts('username', 20, 'new', result.pagination.nextCursor);
+}
+```
+
+### Структура поста
+
+```javascript
+{
+    id: string,
+    content: string,
+    author: { id, username, displayName, avatar, verified },
+    attachments: [{ id, type, url, thumbnailUrl, width, height }],
+    likesCount: number,
+    commentsCount: number,
+    repostsCount: number,
+    viewsCount: number,
+    isLiked: boolean,
+    isReposted: boolean,
+    isOwner: boolean,
+    createdAt: string,
+    updatedAt?: string
+}
+```
+
+### Структура комментария
+
+```javascript
+{
+    id: string,
+    content: string,
+    author: { id, username, displayName, avatar, verified },
+    likesCount: number,
+    repliesCount: number,
+    isLiked: boolean,
+    createdAt: string,
+    replies: [...], // Вложенные ответы
+    replyTo?: { id, username, displayName }
+}
+```
+
+## Обработка ошибок
+
+- **401 Unauthorized**: Ошибка авторизации. SDK инициирует автоматический рефреш токена через `/api/v1/auth/refresh`. Если рефреш не удался, проверьте `.cookies` файл.
+- **429 Too Many Requests**: Превышен лимит запросов. Необходимо проверять заголовок `Retry-After` и делать паузу.
+- **SESSION_REVOKED**: Сессия недействительна. Требуется ручное обновление `.cookies` из браузера.
+
+---
+
+**Последнее обновление документации**: 2026-01-27.

package/README.md

@@ -0,0 +1,85 @@
+# ITD-SDK-js
+
+Неофициальная библиотека на Node.js для работы с API сайта [итд.com](http://итд.com). Упрощает написание ботов и скриптов: берет на себя авторизацию, поддержку сессий и предоставляет готовые методы для основных действий.
+
+## Главное
+
+- **Автоматический Refresh Token**: вам не нужно вручную обновлять `accessToken` в коде. SDK сам подхватит новый, если старый протух, используя данные из `.cookies`.
+- **34 готовых метода**: от получения статистики постов до проверки подписок и работы с кланами.
+- **Минимум зависимостей**: работает на `axios` и `dotenv`.
+
+## Установка
+
+Bash
+
+```
+npm install
+
+```
+
+## Настройка
+
+1. Создайте `.env` на основе `.env.example`.
+2. Вставьте свой `ITD_ACCESS_TOKEN` (его можно вытащить из Network в DevTools).
+3. Для работы авто-обновления сессии создайте файл `.cookies` и вставьте туда строку `Cookie` из любого запроса к сайту в браузере.
+
+Подробный гайд по настройке лежит в [API_REFERENCE.md](API_REFERENCE.md).
+
+## Примеры
+
+### Базовые запросы
+
+JavaScript
+
+```
+import { ITDClient } from './src/client.js';
+import dotenv from 'dotenv';
+dotenv.config();
+
+const client = new ITDClient();
+client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+client.auth.isAuthenticated = true;
+
+// Получаем профиль и тренды
+const myProfile = await client.getMyProfile();
+const trending = await client.getTrendingPosts(10);
+
+console.log(`Авторизован как: ${myProfile.username}`);
+
+```
+
+### Статистика и уведомления
+
+JavaScript
+
+```
+// Простая проверка непрочитанных
+if (await client.hasUnreadNotifications()) {
+    const list = await client.getUnreadNotifications(5);
+    console.log(list.notifications);
+}
+
+// Статистика конкретного поста
+const stats = await client.getPostStats('uuid-поста');
+console.log(`${stats.likes} лайков, ${stats.views} просмотров`);
+
+```
+
+## Что умеет SDK
+
+Весь список методов разбит по категориям в документации:
+
+- **Посты**: тренды, поиск, создание, удаление, статистика.
+- **Пользователи**: профили, счетчики подписок, клановые эмодзи.
+- **Комментарии**: получение топов, ответы, проверка наличия.
+- **Уведомления**: фильтрация только непрочитанных, отметка о прочтении.
+
+Полное описание каждого метода — в **[API_REFERENCE.md](API_REFERENCE.md)**.
+
+## Важно
+
+Это неофициальный проект. Если разработчики сайта изменят структуру API или введут новую защиту, методы могут временно перестать работать. Используйте аккуратно и не спамьте запросами.
+
+---
+
+**Документация:** [API_REFERENCE.md](API_REFERENCE.md) | **Примеры кода:** [examples/README.md](examples/README.md)

package/examples/README.md

@@ -0,0 +1,65 @@
+# 📚 Примеры использования
+
+Примеры, демонстрирующие возможности и преимущества SDK.
+
+## 🚀 Быстрый старт
+
+**Для новичков:** Запустите `quick-start.js` - он содержит подробные комментарии и пошаговые объяснения.
+
+```bash
+node examples/quick-start.js
+```
+
+## 📝 Основные примеры
+
+### 1. `basic-usage.js` - Базовое использование
+
+Показывает простоту работы с API через удобные методы.
+
+```bash
+node examples/basic-usage.js
+```
+
+**Что демонстрирует:**
+- Получение профиля
+- Работа с постами
+- Использование удобных методов
+
+### 2. `user-friendly.js` - Удобные методы
+
+Демонстрирует преимущества user-friendly методов SDK.
+
+```bash
+node examples/user-friendly.js
+```
+
+**Что демонстрирует:**
+- Проверка подписки одной строкой
+- Получение статистики поста
+- Работа с уведомлениями
+- Получение клана пользователя
+
+### 3. `auto-refresh.js` - Автоматическое обновление токена
+
+Показывает, как SDK автоматически обновляет токен при истечении.
+
+```bash
+node examples/auto-refresh.js
+```
+
+**Что демонстрирует:**
+- Автоматическое обновление токена
+- Прозрачная работа с API
+- Обработка ошибок
+
+## 📖 Полная документация
+
+Для полной документации всех методов см. **[API_REFERENCE.md](../API_REFERENCE.md)**
+
+## ⚙️ Настройка перед запуском
+
+1. Установите зависимости: `npm install`
+2. Скопируйте `.env.example` в `.env` и заполните `ITD_ACCESS_TOKEN`
+3. Создайте файл `.cookies` и вставьте туда cookies из браузера
+
+Подробнее см. **[README.md](../README.md)**

package/examples/auto-refresh.js

@@ -0,0 +1,63 @@
+/**
+ * 🔄 Пример 3: Автоматическое обновление токена
+ * 
+ * Демонстрирует, как SDK автоматически обновляет токен при истечении.
+ * Вы просто используете API - всё работает "из коробки"!
+ */
+
+import { ITDClient } from '../src/client.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+    console.log('🔄 === Автоматическое обновление токена ===\n');
+
+    const client = new ITDClient();
+    
+    // Устанавливаем токен (может быть уже истёкшим)
+    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+    client.auth.isAuthenticated = true;
+
+    console.log('💡 SDK автоматически обновит токен при истечении!');
+    console.log('   Вы просто используете API - всё работает "из коробки"\n');
+
+    try {
+        // Делаем несколько запросов
+        // Если токен истёк, SDK автоматически:
+        // 1. Обнаружит ошибку 401
+        // 2. Обновит токен через refresh endpoint
+        // 3. Повторит запрос
+        // Всё это происходит автоматически!
+
+        console.log('📝 Запрос 1: Получаю свой профиль...');
+        const profile = await client.getMyProfile();
+        console.log(`   ✅ Успешно! Username: ${profile.username}\n`);
+
+        console.log('📝 Запрос 2: Получаю свои посты...');
+        const posts = await client.getMyPosts(5);
+        console.log(`   ✅ Успешно! Найдено постов: ${posts.posts.length}\n`);
+
+        console.log('📝 Запрос 3: Получаю уведомления...');
+        const notifications = await client.getNotifications(5);
+        if (notifications) {
+            console.log(`   ✅ Успешно! Найдено уведомлений: ${notifications.notifications.length}\n`);
+        }
+
+        console.log('🎉 Все запросы выполнены успешно!');
+        console.log('   Токен обновлялся автоматически при необходимости.\n');
+
+        // Проверяем текущий токен
+        console.log('🔍 Текущий токен:');
+        console.log(`   ${client.accessToken?.substring(0, 50)}...`);
+
+    } catch (error) {
+        console.error('❌ Ошибка:', error.message);
+        console.error('\n💡 Убедитесь, что:');
+        console.error('   1. В .env указан ITD_ACCESS_TOKEN');
+        console.error('   2. В .cookies есть refresh_token cookie');
+        console.error('   3. Cookies не истекли');
+    }
+}
+
+main();

package/examples/basic-usage.js

@@ -0,0 +1,54 @@
+/**
+ * 📝 Пример 1: Базовое использование SDK
+ * 
+ * Показывает простоту работы с API через удобные методы.
+ */
+
+import { ITDClient } from '../src/client.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+    console.log('📝 === Базовое использование SDK ===\n');
+
+    // Создаём клиент
+    const client = new ITDClient();
+    client.setAccessToken(process.env.ITD_ACCESS_TOKEN);
+    client.auth.isAuthenticated = true;
+
+    try {
+        // Получаем свой профиль
+        console.log('👤 Получаю свой профиль...');
+        const profile = await client.getMyProfile();
+        console.log(`   Имя: ${profile.displayName}`);
+        console.log(`   Username: ${profile.username}`);
+        console.log(`   Клан: ${profile.avatar}`);
+        console.log(`   Подписчиков: ${profile.followersCount}`);
+        console.log();
+
+        // Получаем трендовые посты
+        console.log('🔥 Получаю трендовые посты...');
+        const trending = await client.getTrendingPosts(5);
+        console.log(`   Найдено постов: ${trending.posts.length}`);
+        if (trending.posts.length > 0) {
+            const firstPost = trending.posts[0];
+            console.log(`   Первый пост: ${firstPost.content?.substring(0, 50)}...`);
+            console.log(`   Лайков: ${firstPost.likesCount}, Просмотров: ${firstPost.viewsCount}`);
+        }
+        console.log();
+
+        // Получаем свои посты
+        console.log('📄 Получаю свои посты...');
+        const myPosts = await client.getMyPosts(3);
+        console.log(`   Моих постов: ${myPosts.posts.length}`);
+        myPosts.posts.forEach((post, i) => {
+            console.log(`   ${i + 1}. ${post.content?.substring(0, 40)}... (${post.likesCount} лайков)`);
+        });
+
+    } catch (error) {
+        console.error('❌ Ошибка:', error.message);
+    }
+}
+
+main();