itd-api

Независимый TypeScript-клиент REST и realtime API социальной сети итд.com. Проект не является официальным SDK и не аффилирован с итд.com.

Документация · Быстрый старт · Руководства · Справочник API · Совместимость · Сеть и доверие · Пакеты проекта

Установка

npm install itd-api

Передайте access token и запросите посты со стены пользователя:

import { ItdClient } from 'itd-api';

const itd = new ItdClient({ auth: '<accessToken>' });
const page = await itd.posts.byUser('nowkie', { limit: 10 });

for (const post of page.items) {
  console.log(post.author.username, post.content);
}

Для долгоживущего приложения восстановите сохранённую сессию или настройте вход по руководству по авторизации.

Возможности

| Область | Что поддерживается | |---|---| | REST API | пользователи, посты, комментарии, файлы, уведомления, поиск, жалобы, верификация и подписка | | Авторизация | access/refresh token, автоматическое обновление, OTP, хранение сессии и несколько аккаунтов | | Realtime | SSE и резервный опрос, промежуточные обработчики, типизированные фильтры и маршрутизация | | Пагинация | разные серверные схемы через единый for await | | Публикация | билдеры постов, комментариев, опросов, разметки текста и загрузки файлов | | Надёжность | таймауты, отмена, очередь, rate limiting, безопасные повторы, хуки и типизированные ошибки | | Расширение | плагины, собственный fetch, сервисы и произвольные запросы | | Платформа | версии приложений, changelog, анонсы, портал и состояние сервисов |

У основного пакета нет runtime-зависимостей. Он поставляется как ESM и CommonJS с полными TypeScript-типами.

Пакеты проекта

Все пакеты в таблице поддерживаются проектом itd-api.

| Пакет | Назначение | Среда | npm | Документация | |---|---|---|---|---| | itd-api | REST/realtime-клиент | Node.js 18+, браузер, Bun, Deno, React Native | npm | быстрый старт | | @itd-api/turnstile | получение Turnstile-токена в локальном браузере | Node.js 18+, Bun, Deno + драйвер браузера | npm | документация | | @itd-api/proxy | HTTP/HTTPS- и SOCKS5-транспорт | Node.js 18+, Bun, Deno | npm | документация | | @itd-api/cache | TTL/LRU-кэш и дедупликация запросов | среды основного клиента | npm | документация | | @itd-api/hydrate | методы действий на моделях API | среды основного клиента | npm | документация | | @itd-api/crypto | скрытые сообщения в постах, комментариях и профилях | среды основного клиента | npm | документация | | @itd-api/testing | сценарные ответы и сервер API в памяти | среды основного клиента | npm | документация |

Документация

| Раздел | Содержание | |---|---| | Быстрый старт | создание клиента, чтение и публикация, пагинация, ошибки | | Авторизация | токены, Turnstile, OTP, refresh и хранение сессии | | Конфигурация | таймауты, повторы, очереди, сервисы, хуки и жизненный цикл | | Несколько аккаунтов | ItdAccounts, общее хранилище и отдельные сессии | | Разметка текста | spans, автоматическая разметка и отображение | | Realtime | обновления, обработчики, фильтры, маршрутизация и переподключение | | Интеграции | browser proxy и Turnstile | | Плагины | cache, crypto и создание плагина | | Справочник API | ресурсы, методы, типы, ошибки и билдеры |

Совместимость

| Среда | Поддержка | |---|---| | Node.js 18+ | полная, включая файловую точку входа itd-api/node | | Bun, Deno | полная | | Браузер | кроме файловой системы; хранилище сессии — itd-api/web; для основного API нужен server-side proxy из-за CORS | | React Native | полная; поток переключается на периодический опрос без потокового чтения |

TypeScript 5.0+. Пакет проверяется в Node.js 18, 20, 22, 24 и 26, а корректность публикации — через publint и @arethetypeswrong/cli.

Сеть и доверие

По умолчанию основной пакет обращается ровно к двум хостам:

| Хост | Назначение | Автоматическая передача Bearer-токена | |---|---|---| | https://xn--d1ah4a.com (итд.com) | REST API, авторизация и realtime | да, для защищённых REST-методов и realtime | | https://xn--80a7abcbg.xn--d1ah4a.com (статус.итд.com) | публичное состояние сервисов | нет |

Опциональный @itd-api/turnstile дополнительно загружает виджет с https://challenges.cloudflare.com; пакет не передаёт пароль странице браузера. @itd-api/cache и @itd-api/crypto сами не создают сетевые запросы, а @itd-api/proxy использует только адрес proxy, заданный пользователем.

Пользовательские настройки меняют границу доверия:

| Настройка | Последствие | |---|---| | baseUrl | становится основным API-хостом; на него идут авторизация, сессия, защищённые запросы и realtime | | fetch | получает URL, заголовки и body всех запросов клиента; передавайте только доверенную реализацию | | proxyFetch(...) | направляет запросы через указанный вами proxy, которому будут доступны соединения с API | | defineService({ auth: true }) | явно разрешает отправлять Bearer-токен на хост этого сервиса | | request({ baseUrl }) | внешний хост не получает Bearer автоматически; skipAuth: false явно разрешает его передачу |

Уязвимости следует отправлять приватно по политике безопасности.

Известные ограничения платформы

| Ограничение | Что учитывать | |---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | CORS основного API | браузерному приложению нужен собственный серверный proxy; подробнее | | Подписчики, подписки и блокировки | сервер возвращает только первые 20 записей; подробнее | | Посты пользователя | posts.byUser() возвращает стену, включая чужие публикации на ней; подробнее | | Rate limiting | маршруты разбиты на бакеты, у каждого свой лимит запросов в минуту, считается по IP; таблица бакетов |

Матрица известных маршрутов, wire-контрактов и статуса поддержки находится в справочнике endpoint.

Проект

• DeepWiki по исходному коду — автоматический разбор репозитория с ответами на вопросы про внутреннее устройство
• CI
• История релизов
• Как внести вклад
• Политика безопасности
• MIT License и NOTICE

Пакет публикуется через npm Trusted Publishing с проверяемым provenance.

Лицензия

MIT © Kiow. Проект использует независимо восстановленные сведения о публичном интерфейсе платформы; товарные знаки и сама платформа принадлежат их владельцам.