itd-api 0.0.11 → 0.2.0

package/README.md

@@ -1,529 +1,158 @@
-# itd-api
-
-Клиент REST и realtime API социальной сети **итд.com** для JavaScript и TypeScript.
-
-- **Ноль зависимостей** у установленного пакета
-- **Работает везде**: Node 18+, браузер, Bun, Deno, React Native — только web-стандарты
-- **ESM и CommonJS**, полные `.d.ts` с описаниями на русском
-- Авторизация, продление токена, повторы и очередь запросов — **сами**
-- Три схемы пагинации спрятаны за одним `for await`
-- Уведомления из REST и из потока приведены к **одной форме**
-
-```bash
-npm install itd-api
-```
-
----
-
-## Быстрый старт
-
-```ts
-import { ItdClient, FeedTab } from 'itd-api';
-
-const itd = new ItdClient({ auth: process.env.ITD_TOKEN });
-
-const me = await itd.users.me();
-console.log(`@${me.username}, подписчиков: ${me.followersCount}`);
-
-for await (const post of itd.posts.iterate({ tab: FeedTab.Following })) {
-  if (!post.isLiked) await itd.posts.like(post.id);
-}
-```
-
-В Node, Bun и Deno импортируйте `itd-api/node` — оттуда доступны загрузка файлов по пути
-и хранение сессии в файле:
-
-```ts
-import { ItdClient, FileTokenStorage } from 'itd-api/node';
-
-// Сессия из файла: продлевается сама, `auth` не нужен. Как её туда положить —
-// в разделе «Авторизация»: вход требует капчи, поэтому делается один раз.
-const itd = new ItdClient({ storage: new FileTokenStorage('./.itd-session.json') });
-
-await itd.posts.create((p) => p.content('привет').attach('./photo.jpg'));
-```
-
-Продолжение с запускаемыми примерами — в [руководстве по быстрому старту](./guides/quickstart/README.md).
-Все тематические материалы собраны в [`guides/`](./guides/README.md).
-
----
-
-## Авторизация
-
-Клиент может взять доступ из `auth`, сохранённой сессии или явного вызова `itd.auth`:
-
-```ts
-new ItdClient({ auth: '<accessToken>' });
-new ItdClient({ auth: { accessToken, refreshToken } });
-new ItdClient({ auth: { email, password, getTurnstileToken } });
-new ItdClient({ storage: new FileTokenStorage('./.itd-session.json') });
-```
-
-При `401` сессия продлевается, исходный запрос повторяется, а новое состояние сохраняется.
-Параллельные запросы ждут одного refresh. Потерю сессии можно отследить:
-
-```ts
-itd.on('authError', ({ error }) => {
-  if (isItdApiError(error)) console.error('Сессия потеряна:', error.code);
-});
-```
-
-Вход, регистрация и восстановление пароля требуют одноразовый Turnstile token. Подробности
-о cookie, `deviceId`, OTP, собственном storage и автоматическом решателе:
-[руководство по авторизации](./guides/authentication/README.md).
-
----
-
-## Несколько аккаунтов
-
-`ItdAccounts` хранит именованные клиенты с отдельными tokens, cookie и `deviceId`, но одним
-`MultiTokenStorage`:
-
-```ts
-import { ItdAccounts, FileMultiTokenStorage } from 'itd-api/node';
-
-const accounts = new ItdAccounts({
-  storage: new FileMultiTokenStorage('./.itd-sessions.json'),
-  rateLimit: { concurrency: 4 },
-});
-
-// Поднимаем тех, кто уже входил раньше: ни auth, ни капча не нужны.
-await accounts.restore();
-
-if (!accounts.has('kiow')) {
-  accounts.addAccount('kiow', { auth: { email, password, getTurnstileToken } });
-}
-
-const itd = accounts.account('kiow');   // обычный ItdClient со всеми разделами
-await itd.posts.create({ content: 'привет' });
-await accounts.close();
-```
-
-Личные прокси, общая или раздельные очереди, собственное хранилище и события контейнера
-описаны в [руководстве по нескольким аккаунтам](./guides/multi-accounts/README.md).
-
----
-
-## Пагинация
-
-Три разные схемы API (курсор, страницы, смещение) выглядят одинаково:
-
-```ts
-// по элементам
-for await (const post of itd.posts.iterate({ tab: 'popular' })) { … }
-
-// по страницам — когда нужны сведения о самой странице
-for await (const page of itd.posts.iterateComments(postId).pages()) {
-  console.log(page.items.length, 'из', page.total);
-}
-
-// набрать нужное количество и остановиться
-const posts = await itd.posts.iterate({ tab: 'popular' }).collect(100);
-```
-
-Отдельные страницы тоже доступны:
-
-```ts
-const page = await itd.posts.list({ tab: 'popular', limit: 20 });
-const next = await itd.posts.list({ tab: 'popular', cursor: page.nextCursor ?? undefined });
-```
-
-Курсор непрозрачен: у вкладки `popular` это номер страницы, у `following` — отметка времени.
-Передавайте его обратно как есть.
-
-Перебор одноразовый: позиция хранится внутри, поэтому второй `for await` по тому же объекту
-ничего не выдаст. Нужен ещё проход — возьмите новый перебор у того же метода.
-
-### Чего API не умеет
-
-**Подписчики, подписки и заблокированные не листаются.** Сервер отдаёт первые 20 записей
-и на этом всё: `page` он игнорирует, `limit` больше 20 молча уменьшает, а `hasMore` всегда
-`false`. Числу `total` там тоже верить нельзя: оно расходится с `followersCount` из профиля.
-
-```ts
-// вернёт 20 записей и остановится — это предел API, а не библиотеки
-const all = await itd.users.iterateFollowers('durov').collect();
-```
-
-**`posts.byUser()` — это стена, а не авторские посты.** В неё входят и записи, которые
-другие оставили на странице пользователя, поэтому записей обычно больше, чем `postsCount`
-в профиле. Нужны только свои — отфильтруйте по `post.author.id`.
-
----
-
-## Публикация
-
-Три равноправные формы, проверки одинаковы для каждой:
-
-```ts
-// обычный объект
-await itd.posts.create({ content: 'привет' });
-
-// функция-настройщик — импорты не нужны
-await itd.posts.create((p) =>
-  p.content('привет')
-   .attach('./photo.jpg')
-   .poll((q) => q.question('нравится?').options('да', 'нет')),
-);
-
-// билдер — когда объект готовится заранее
-import { post, poll } from 'itd-api';
-
-const draft = post().onWall(userId);
-await itd.posts.create(draft.content('первый'));
-await itd.posts.create(draft.content('второй'));   // заготовка не испорчена
-```
-
-Файлы из `attach()` загружаются автоматически, порядок вложений сохраняется, MIME-тип
-проверяется до отправки.
-
-### Разметка текста
-
-Билдер собирает текст и сам считает смещения:
-
-```ts
-import { post, renderSpans } from 'itd-api';
-
-const created = await itd.posts.create(
-  post().markup((m) =>
-    m
-      .text('смотрите ')
-      .hashtag('котики')
-      .text(' от ')
-      .mention('durov')
-      .text(': ')
-      .bold('важно'),
-  ),
-);
-
-renderSpans(created.content, created.spans); // безопасный HTML по умолчанию
-```
-
-Доступны `bold`, `italic`, `underline`, `strike`, `spoiler`, `monospace`, `quote`, `link`,
-`hashtag`, `mention`, `span()` и несколько стилей сразу через `styled()`. Вложенные и
-пересекающиеся spans поддерживаются. Смещения измеряются в единицах UTF-16, как индексы
-строк и DOM Selection в JavaScript.
-
-Для обычного текста есть автоматическое обнаружение ссылок, хэштегов и упоминаний:
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/KiowDev/itd-api/main/guides/web/public/logos/itd-api-logo-horizontal-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/KiowDev/itd-api/main/guides/web/public/logos/itd-api-logo-horizontal.svg">
+    <img alt="itd-api" src="https://raw.githubusercontent.com/KiowDev/itd-api/main/guides/web/public/logos/itd-api-logo-horizontal.svg" width="560">
+  </picture>
+</p>
 
-```ts
-await itd.posts.create(post('#котики от @durov: https://example.com').autoSpans());
-```
-
-`renderSpans()` также выводит Markdown и ANSI и позволяет настроить маршруты упоминаний,
-хэштегов и префикс CSS-классов. Вызов `postBuilder.content(newText)` сбрасывает прежние
-spans, поскольку они рассчитаны для другого текста. `posts.update()` принимает тот же билдер,
-но требует явно заданный `content`.
-
-Авторазметка, пересекающиеся стили, обновление и настройка рендера подробно разобраны
-в [руководстве по разметке](./guides/text-markup/README.md).
-
-Билдеры есть у разметки, поста, комментария, опроса и жалобы. Все они неизменяемые, а `build()`
-проверяет данные и бросает `ItdConfigError` **до** обращения к сети:
-
-```ts
-post('привет').onWall('durov');
-// ItdConfigError: wallRecipientId должен быть UUID, а не именем пользователя
-// (получено: «durov»). Идентификатор можно взять из профиля:
-// (await itd.users.get(username)).id
-```
-
----
-
-## Уведомления и realtime
-
-```ts
-import { formatNotificationText, resolveNotificationUrl } from 'itd-api';
-
-const stream = itd.realtime();
-
-stream.on('notification', ({ notification }) => {
-  console.log(formatNotificationText(notification));   // «Аня и ещё 2 оценили ваш пост»
-  console.log(resolveNotificationUrl(notification));   // '/@anya/post/9f1c…'
-});
-
-await stream.connect();
-```
-
-REST и поток используют одну форму уведомления. Переподключение, refresh token, keep-alive
-и fallback на polling обрабатываются внутри. Эксплуатационные настройки и счётчик
-непрочитанных разобраны в [руководстве по realtime](./guides/realtime/README.md).
-
----
-
-## Статус сервисов
-
-`itd.platform.status()` отдаёт состояние платформы и историю доступности за 90 суток.
-Авторизация не нужна, ответ кэшируется сервером на минуту.
+# itd-api
 
-```ts
-import { statusDays } from 'itd-api';
+[![npm version](https://img.shields.io/npm/v/itd-api.svg)](https://www.npmjs.com/package/itd-api)
+[![npm downloads](https://img.shields.io/npm/dm/itd-api.svg)](https://www.npmjs.com/package/itd-api)
+[![CI](https://github.com/KiowDev/itd-api/actions/workflows/ci.yml/badge.svg)](https://github.com/KiowDev/itd-api/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/itd-api.svg)](https://www.npmjs.com/package/itd-api)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-3178c6.svg)](./tsconfig.json)
+[![license](https://img.shields.io/npm/l/itd-api.svg)](./LICENSE)
 
-const status = await itd.platform.status();
+Независимый TypeScript-клиент REST и realtime API социальной сети **итд.com**.
+Проект не является официальным SDK и не аффилирован с итд.com.
 
-status.overall_status;                       // 'operational' | 'degraded' | 'downtime'
-status.services.map((s) => s.current_status);
+[Документация](https://kiowdev.github.io/itd-api/) ·
+[Быстрый старт](https://kiowdev.github.io/itd-api/quickstart/) ·
+[Руководства](https://kiowdev.github.io/itd-api/guides/) ·
+[Справочник API](https://kiowdev.github.io/itd-api/reference/) ·
+[Совместимость](#совместимость) ·
+[Сеть и доверие](#сеть-и-доверие) ·
+[Пакеты проекта](#пакеты-проекта)
 
-const auth = status.services.find((s) => s.id === 'auth');
-auth?.uptime_90d;                            // 97.92
-auth?.last_checked;                          // '2026-07-23T23:14:25Z'
+## Установка
 
-const days = auth ? statusDays(auth) : [];   // 90 элементов, [0] — сегодня
-days[0]?.uptime;                             // 100
-days[0]?.lines;                              // [{ t: 'down', text: 'недоступен 6 мин (12:00–12:06)' }]
+```bash
+npm install itd-api
 ```
 
-Поле `days` приходит объектом с числовыми ключами, и сутки без данных сервер пропускает —
-`statusDays()` разворачивает его в массив, где пропуски равны `null`. Строки в `lines`
-готовы к показу как есть: длительность и границы интервала отдельными полями не приходят,
-время в них московское, тогда как `date_key` суток нарезан по UTC.
-
-### Сервисы платформы
-
-Статус живёт на отдельном домене — `статус.итд.com`. Такие домены описываются как сервисы:
-у каждого своё имя, хост, заголовки и признак публичности. Запрос выбирает сервис
-полем `service`.
+Передайте access token и запросите посты со стены пользователя:
 
 ```ts
-const itd = new ItdClient({
-  services: {
-    pb: {
-      baseUrl: 'https://pbapi.xn--d1ah4a.com',
-      headers: { Referer: 'https://pixel.xn--d1ah4a.com/' },
-    },
-  },
-});
-
-await itd.request({ method: 'GET', service: 'pb', path: '/api/pixel-info', query: { x: 1, y: 2 } });
-```
-
-То же самое после создания клиента — `itd.defineService({ name, baseUrl, headers, auth })`;
-базовый URL сервиса отдаёт `itd.serviceBaseUrl(name)`.
-
-Bearer-токен по умолчанию отправляется только основному хосту и его поддоменам.
-Публичный или сторонний сервис его не получает. То же правило действует для разового
-`itd.request({ baseUrl })`; если внешнему хосту действительно нужна авторизация,
-разрешите её явно через `skipAuth: false`.
-
-У каждого сервиса своя очередь `rateLimit`: лимит частоты сервер считает по хосту, поэтому
-`429` от статуса не тормозит основной API и наоборот.
-
----
-
-## Ошибки
+import { ItdClient } from 'itd-api';
 
-Обе формы ошибок API сведены к одному классу:
+const itd = new ItdClient({ auth: '<accessToken>' });
+const page = await itd.posts.byUser('nowkie', { limit: 10 });
 
-```ts
-import { ItdValidationError, ItdRateLimitError, isItdApiError } from 'itd-api';
-
-try {
-  await itd.users.updateMe({ username: 'занятое_имя' });
-} catch (error) {
-  if (error instanceof ItdValidationError) {
-    console.log(error.fieldErrors.username);   // ['Имя уже занято']
-  } else if (error instanceof ItdRateLimitError) {
-    console.log(error.retryAfter);             // мс
-  } else if (isItdApiError(error)) {
-    console.log(error.status, error.code, error.message);
-  }
+for (const post of page.items) {
+  console.log(post.author.username, post.content);
 }
 ```
 
-`ItdApiError` → `ItdValidationError`, `ItdAuthError`, `ItdForbiddenError`, `ItdNotFoundError`,
-`ItdConflictError`, `ItdRateLimitError`, `ItdPhoneVerificationError`, `ItdServerError`.
-Отдельно: `ItdNetworkError`, `ItdTimeoutError`, `ItdAbortError`, `ItdConfigError`.
-
----
-
-## Настройка
-
-```ts
-const itd = new ItdClient({
-  baseUrl: 'https://xn--d1ah4a.com',   // свой прокси, если работаете из браузера
-  auth: { email, password, getTurnstileToken },
-  storage: new FileTokenStorage('./.itd-session.json'),
-  timeout: 30_000,
-  retry: { attempts: 3, retryWrites: false },
-  rateLimit: { concurrency: 4, rps: 8 },
-  // Заголовки латиницей: кириллица в них запрещена самим HTTP.
-  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36',             // по умолчанию itd-api/<версия>; false — не слать
-  deviceId: '3f2a…-uuid',              // по умолчанию заводится сам и живёт в сессии
-  services: { pb: 'https://pbapi.xn--d1ah4a.com' },  // домены сервисов платформы, см. ниже
-  logger: true,                        // токены и пароли в логах маскируются
-  hooks: {
-    onRequest: (ctx) => console.log(ctx.method, ctx.path),
-    onRetry: (ctx) => console.log('повтор через', ctx.delay),
-  },
-});
-```
-
-**Повторы.** Обрыв сети и `5xx` не гарантируют, что запрос не был обработан, поэтому запись
-по умолчанию не повторяется (`retryWrites: false`): повтор мог бы создать дубль поста.
-Чтения повторяются с экспоненциальным откатом.
+Для долгоживущего приложения восстановите сохранённую сессию или настройте вход по
+[руководству по авторизации](https://kiowdev.github.io/itd-api/authentication/).
 
-**Очередь: `concurrency` и `rps` решают разные задачи.** Все запросы идут через одну очередь
-клиента, поэтому достаточно **одного экземпляра `ItdClient` на приложение** — разложите его
-по модулям, и темп будет общим.
+## Возможности
 
-`concurrency` (по умолчанию 6) ограничивает только одновременность. От ограничения частоты
-он почти не спасает: десять запросов подряд при `concurrency: 1` уходят за ~150 мс,
-а окно сервера измеряется десятками секунд. Темп задаёт `rps`:
-
-```ts
-rateLimit: { concurrency: 2, rps: 0.5 }   // не чаще одного запроса в 2 секунды
-```
-
-Ставить `concurrency: 1` без нужды не стоит: загрузка видео с таймаутом в 300 секунд
-заблокирует на это время вообще всё остальное.
-
-**Ограничение частоты — отдельный механизм.** Лимит у каждого эндпоинта свой: замеры по
-`x-ratelimit-limit` дали 90 у `/api/posts`, 40 у `/api/users/me` и `/api/notifications/`,
-25 у `/api/v1/auth/refresh` и всего 15 у `/api/files/upload`. Сервер
-не присылает `Retry-After` и не сообщает, когда окно сбросится: есть только заголовки
-`x-ratelimit-limit` и `x-ratelimit-remaining` (доступны на `ItdRateLimitError` как
-`rateLimit` и `rateLimitRemaining`).
-
-Экспоненциальный откат в сотни миллисекунд при окне около минуты бесполезен, поэтому
-для `429` используется лестница пауз:
-
-```ts
-rateLimit: { retryDelays: [1000, 5000, 30_000, 60_000, 90_000] }  // по умолчанию
-```
-
-Первый шаг короткий — вдруг окно уже истекло, тогда работа продолжится почти сразу.
-Дальше паузы выходят на масштаб окна. Когда лестница кончилась, `ItdRateLimitError`
-пробрасывается вам. Список не зависит от `retry.attempts` и переопределяется одной строкой.
-
-Дополнительно очередь **тормозит заранее**: как только `x-ratelimit-remaining` доходит
-до нуля, запросы придерживаются, не дожидаясь отказа. Отключается через
-`rateLimit: { respectHeaders: false }`.
-
-### Про CORS
-
-**Напрямую из браузера запросы работать не будут.** Проверено запросами к боевому API:
-на preflight сервер отвечает `204` с `Access-Control-Allow-Methods` и
-`Access-Control-Allow-Credentials`, но **без `Access-Control-Allow-Origin`** — браузер
-такой ответ отвергает.
-
-Поэтому в браузерном приложении укажите в `baseUrl` адрес своего прокси. В Node, Bun,
-Deno и React Native ограничение не действует.
-
-Исключение — `itd.platform.status()`: страница статуса отдаёт
-`Access-Control-Allow-Origin: *`, и этот метод работает из браузера напрямую.
-
-### Прокси (HTTP/SOCKS5)
+| Область | Что поддерживается |
+|---|---|
+| REST API | пользователи, посты, комментарии, файлы, уведомления, поиск, жалобы, верификация и подписка |
+| Авторизация | access/refresh token, автоматическое обновление, OTP, хранение сессии и несколько аккаунтов |
+| Realtime | SSE с переподключением и fallback на polling |
+| Пагинация | разные серверные схемы через единый `for await` |
+| Публикация | билдеры постов, комментариев, опросов, разметки текста и загрузки файлов |
+| Надёжность | таймауты, отмена, очередь, rate limiting, безопасные повторы, хуки и типизированные ошибки |
+| Расширение | плагины, собственный `fetch`, сервисы и произвольные запросы |
+| Платформа | версии приложений, changelog, анонсы, портал и состояние сервисов |
 
-Чтобы направить запросы клиента через прокси, возьмите `fetch` из пакета
-[`@itd-api/proxy`](./proxy/README.md):
+У основного пакета нет runtime-зависимостей. Он поставляется как ESM и CommonJS с
+полными TypeScript-типами.
 
-```sh
-npm i @itd-api/proxy
-```
+## Пакеты проекта
 
-```ts
-import { ItdClient } from 'itd-api';
-import { proxyFetch } from '@itd-api/proxy';
+Все пакеты в таблице поддерживаются проектом itd-api.
 
-const fetch = proxyFetch('socks5://127.0.0.1:1080');
-// http://…, https://…, socks5://… — можно с user:pass@
-const itd = new ItdClient({ fetch });
+| Пакет | Назначение | Среда | npm | Документация |
+|---|---|---|---|---|
+| `itd-api` | REST/realtime-клиент | Node.js 18+, браузер, Bun, Deno, React Native | [npm](https://www.npmjs.com/package/itd-api) | [быстрый старт](https://kiowdev.github.io/itd-api/quickstart/) |
+| `@itd-api/cache` | TTL/LRU-кэш и дедупликация запросов | среды основного клиента | [npm](https://www.npmjs.com/package/@itd-api/cache) | [документация](https://kiowdev.github.io/itd-api/packages/cache) |
+| `@itd-api/crypto` | скрытые сообщения в постах, комментариях и профилях | среды основного клиента | [npm](https://www.npmjs.com/package/@itd-api/crypto) | [документация](https://kiowdev.github.io/itd-api/packages/crypto) |
+| `@itd-api/proxy` | HTTP/HTTPS- и SOCKS5-транспорт | Node.js 18+, Bun, Deno | [npm](https://www.npmjs.com/package/@itd-api/proxy) | [документация](https://kiowdev.github.io/itd-api/packages/proxy) |
+| `@itd-api/turnstile` | получение Turnstile-токена в локальном браузере | Node.js 18+, Bun, Deno + Playwright | [npm](https://www.npmjs.com/package/@itd-api/turnstile) | [документация](https://kiowdev.github.io/itd-api/packages/turnstile) |
 
-// …работа…
+## Документация
 
-await itd.close();
-await fetch.close(); // закрывает пул соединений
-```
+| Раздел | Содержание |
+|---|---|
+| [Быстрый старт](https://kiowdev.github.io/itd-api/quickstart/) | создание клиента, чтение и публикация, пагинация, ошибки |
+| [Авторизация](https://kiowdev.github.io/itd-api/authentication/) | токены, Turnstile, OTP, refresh и хранение сессии |
+| [Конфигурация](https://kiowdev.github.io/itd-api/configuration/) | таймауты, повторы, очереди, сервисы, hooks и lifecycle |
+| [Несколько аккаунтов](https://kiowdev.github.io/itd-api/multi-accounts/) | `ItdAccounts`, общее хранилище и отдельные сессии |
+| [Разметка текста](https://kiowdev.github.io/itd-api/text-markup/) | spans, автоматическая разметка и отображение |
+| [Realtime](https://kiowdev.github.io/itd-api/realtime/) | события, SSE, polling и переподключение |
+| [Интеграции](https://kiowdev.github.io/itd-api/integrations/) | browser proxy и Turnstile |
+| [Плагины](https://kiowdev.github.io/itd-api/plugins/) | cache, crypto и создание плагина |
+| [Справочник API](https://kiowdev.github.io/itd-api/reference/) | ресурсы, методы, типы, ошибки и билдеры |
 
-Через тот же `fetch` пойдут авторизация, cookie, очередь, повторы и поток уведомлений.
-Только для Node/Bun/Deno. Подключение proxy и Turnstile разобрано в
-[руководстве по интеграциям](./guides/integrations/README.md), параметры транспорта — в
-[README пакета](./proxy/README.md).
+## Совместимость
 
----
+| Среда | Поддержка |
+|---|---|
+| Node.js 18+ | полная, включая файловую точку входа `itd-api/node` |
+| Bun, Deno | полная |
+| Браузер | кроме файловой системы; хранилище сессии — `itd-api/web`; для основного API нужен server-side proxy из-за CORS |
+| React Native | полная; realtime переключается на polling без потокового чтения |
 
-## Плагины
+TypeScript 5.0+. Пакет проверяется в Node.js 18, 20, 22, 24 и 26, а корректность
+публикации — через `publint` и `@arethetypeswrong/cli`.
 
-Плагин оборачивает запросы и ответы сразу всех ресурсов:
+## Сеть и доверие
 
-```ts
-import { ItdClient } from 'itd-api';
-import { cache } from '@itd-api/cache';
-
-const itd = new ItdClient({ auth: token });
-itd.use(
-  cache({
-    ttl: 60_000,
-    routes: ['users.get', 'posts.get', 'posts.list'],
-  }),
-);
-```
+По умолчанию основной пакет обращается ровно к двум хостам:
 
-Официальные плагины Cache и Crypto, полный контракт `ItdPlugin`, собственные опции и
-структура пакета описаны в
-[руководстве по плагинам](./guides/plugins/README.md).
+| Хост | Назначение | Автоматическая передача 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, заданный пользователем.
 
-## Что доступно
+Пользовательские настройки меняют границу доверия:
 
-| Раздел | Методы |
+| Настройка | Последствие |
 |---|---|
-| `itd.auth` | вход, регистрация, OTP, пароли, сессии, OAuth-ссылки |
-| `itd.users` | профили, подписки, блокировки, приватность, значки |
-| `itd.posts` | лента, публикация, реакции, репосты, опросы, комментарии к постам |
-| `itd.comments` | ответы, редактирование, реакции |
-| `itd.notifications` | список, счётчик, отметки о прочтении, настройки |
-| `itd.files` | загрузка медиа |
-| `itd.hashtags` · `itd.search` | хэштеги, трендовые, глобальный поиск |
-| `itd.reports` · `itd.verification` | жалобы, заявка на верификацию |
-| `itd.subscription` · `itd.platform` | подписка, способы оплаты, анонсы, статус сервисов |
-| `itd.realtime()` | поток уведомлений |
-| `itd.use()` | плагины: обёртки вокруг запроса и ответа |
-| `itd.request()` | произвольный запрос, если метода ещё нет |
-| `ItdAccounts` | несколько аккаунтов с общим хранилищем сессий |
-
-Метода не хватает или ответ разошёлся с документацией — есть запасной путь:
-
-```ts
-const raw = await itd.request({ method: 'GET', path: '/api/что-то', raw: true });
-```
+| `baseUrl` | становится основным API-хостом; на него идут авторизация, сессия, защищённые запросы и realtime |
+| `fetch` | получает URL, заголовки и body всех запросов клиента; передавайте только доверенную реализацию |
+| `proxyFetch(...)` | направляет запросы через указанный вами proxy, которому будут доступны соединения с API |
+| `defineService({ auth: true })` | явно разрешает отправлять Bearer-токен на хост этого сервиса |
+| `request({ baseUrl })` | внешний хост не получает Bearer автоматически; `skipAuth: false` явно разрешает его передачу |
 
----
+Уязвимости следует отправлять приватно по
+[политике безопасности](./.github/SECURITY.md).
 
-## Совместимость
+## Известные ограничения платформы
 
-| Среда | Поддержка |
+| Ограничение | Что учитывать |
 |---|---|
-| Node.js 18+ | полная, включая `itd-api/node` |
-| Bun, Deno | полная |
-| Браузер | всё, кроме файловой системы; нужен прокси из-за CORS |
-| React Native | полная; realtime автоматически переключается на опрос, если нет потокового чтения |
+| CORS основного API | браузерному приложению нужен собственный серверный proxy; [подробнее](https://kiowdev.github.io/itd-api/integrations/#браузер-и-cors) |
+| Подписчики, подписки и блокировки | сервер возвращает только первые 20 записей; [подробнее](https://kiowdev.github.io/itd-api/reference/users) |
+| Посты пользователя | `posts.byUser()` возвращает стену, включая чужие публикации на ней; [подробнее](https://kiowdev.github.io/itd-api/reference/posts) |
+| Rate limiting | лимиты различаются по endpoint, а сервер не сообщает время сброса окна; [настройка очереди](https://kiowdev.github.io/itd-api/configuration/#очередь-и-rate-limiting) |
 
-TypeScript 5.0+. Пакет собран в ESM и CommonJS, типы корректны во всех режимах
-резолвинга (проверено `publint` и `@arethetypeswrong/cli`).
+Матрица известных маршрутов, wire-контрактов и статуса поддержки находится в
+[справочнике endpoint](https://kiowdev.github.io/itd-api/reference/endpoints).
 
----
+## Проект
 
-## Разработка
+- [CI](https://github.com/KiowDev/itd-api/actions/workflows/ci.yml)
+- [История релизов](https://github.com/KiowDev/itd-api/releases)
+- [Как внести вклад](./.github/CONTRIBUTING.md)
+- [Политика безопасности](./.github/SECURITY.md)
+- [MIT License](./LICENSE) и [NOTICE](./NOTICE)
 
-```bash
-npm install
-npm test            # 611 тестов
-npm run test:all    # вместе с пакетами workspace
-npm run typecheck
-npm run lint
-npm run build
-npm run check:pack  # publint + attw
-npm run docs        # сайт документации из TSDoc
-```
-
-Тесты не обращаются к сети: `fetch` подменяется через опцию конфигурации.
-
----
+Публикация `itd-api@0.1.0` содержит проверяемое
+[npm provenance](https://registry.npmjs.org/-/npm/v1/attestations/itd-api@0.1.0).
 
 ## Лицензия
 
-MIT. Библиотека не связана с итд.com и разработана независимо.
-
-Сторонний код, включённый в сборку, перечислен в [NOTICE](./NOTICE).
+MIT © Kiow. Проект использует независимо восстановленные сведения о публичном
+интерфейсе платформы; товарные знаки и сама платформа принадлежат их владельцам.