itd-api 0.0.11 → 0.2.0

package/guides/README.md

@@ -1,22 +0,0 @@
-# Руководства
-
-| Руководство | О чём |
-|---|---|
-| [Быстрый старт](./quickstart/README.md) | установка, клиент, публикация, пагинация и ошибки |
-| [Разметка текста](./text-markup/README.md) | spans, `markup()`, `autoSpans()`, пересечения и `renderSpans()` |
-| [Авторизация](./authentication/README.md) | токены, Turnstile, OTP, продление и хранение сессии |
-| [Realtime](./realtime/README.md) | уведомления, SSE, переподключение и fallback на polling |
-| [Несколько аккаунтов](./multi-accounts/README.md) | `ItdAccounts`, общее хранилище, очереди и личные настройки |
-| [Интеграции](./integrations/README.md) | proxy, Turnstile и точки подключения внешних возможностей |
-| [Плагины](./plugins/README.md) | Cache, Crypto, `ItdPlugin` и создание нового плагина |
-
-## Запуск примеров
-
-Установите зависимости и соберите библиотеку:
-
-```bash
-npm install
-npm run build
-```
-
-Команды запуска и переменные окружения указаны в каждом руководстве.

package/guides/authentication/README.md

@@ -1,176 +0,0 @@
-# Авторизация и сессии
-
-Клиент может получить доступ к API из `auth`, сохранённой сессии или явного вызова
-`itd.auth`. Обязательного способа нет:
-
-```ts
-new ItdClient({ auth: '<accessToken>' });
-new ItdClient({ auth: { accessToken, refreshToken } });
-new ItdClient({ auth: { email, password, getTurnstileToken } });
-new ItdClient({ auth: { getToken: () => vault.read() } });
-new ItdClient({ storage: new FileTokenStorage('./.itd-session.json') });
-new ItdClient();
-```
-
-`storage` отражает текущее состояние сессии и имеет приоритет, а отсутствующие поля
-дополняются из `auth`.
-
-## Сохранённая сессия
-
-В Node, Bun и Deno:
-
-```ts
-import { FileTokenStorage, ItdClient } from 'itd-api/node';
-
-const itd = new ItdClient({
-  storage: new FileTokenStorage('./.itd-session.json'),
-});
-
-const me = await itd.users.me();
-```
-
-Если access token истёк, клиент использует refresh-сессию, повторяет исходный запрос и
-сохраняет обновлённые данные. Параллельные `401` ждут одного refresh.
-
-Refresh-токен обновляется при каждом продлении. Штатные хранилища записывают его
-автоматически. При собственном хранении сохраняйте сессию после каждого события `tokens`:
-
-```ts
-itd.on('tokens', async () => saveSomewhere(await itd.getSession()));
-
-await itd.setSession(await loadFromSomewhere());
-```
-
-Проверить возможность продления заранее:
-
-```ts
-if (await itd.auth.hasRefreshSession()) await itd.auth.refresh();
-else redirectToLogin();
-```
-
-Автоматическое продление отключается через `autoRefresh: false`.
-
-## Что хранится
-
-Полная сессия включает:
-
-- access и refresh tokens;
-- cookie;
-- `deviceId`.
-
-Вне браузера `fetch` не ведёт cookie сам, поэтому библиотека хранит их вместе с сессией.
-`deviceId` должен переживать перезапуски, иначе сервер будет видеть каждый запуск как новое
-устройство.
-
-Доступные хранилища:
-
-| Хранилище | Импорт | Среда |
-|---|---|---|
-| `MemoryTokenStorage` | `itd-api` | везде |
-| `LocalStorageTokenStorage` | `itd-api` | браузер |
-| `FileTokenStorage` | `itd-api/node` | Node, Bun, Deno |
-| `createTokenStorage()` | `itd-api` | Redis, БД, AsyncStorage и другие |
-
-`getUserId()` читает идентификатор из JWT без запроса, но не проверяет подпись:
-
-```ts
-const cachedId = await itd.getUserId();
-const actualProfile = await itd.users.me();
-```
-
-## Turnstile
-
-`signIn`, `signUp` и `forgotPassword` требуют одноразовый токен Cloudflare Turnstile.
-В браузере используйте виджет с экспортируемым ключом:
-
-```ts
-import { TURNSTILE_SITE_KEY } from 'itd-api';
-
-turnstile.render('#captcha', {
-  sitekey: TURNSTILE_SITE_KEY,
-  callback: (turnstileToken) =>
-    itd.auth.signIn({ email, password, turnstileToken }),
-});
-```
-
-Долгоживущему процессу передавайте функцию получения свежего токена:
-
-```ts
-new ItdClient({
-  auth: {
-    email,
-    password,
-    getTurnstileToken: () => captchaSolver.solve(),
-  },
-});
-```
-
-Для Node доступен пакет `@itd-api/turnstile`:
-
-```bash
-npm i @itd-api/turnstile playwright
-npx playwright install chromium
-```
-
-```ts
-import { createTurnstileSolver } from '@itd-api/turnstile';
-
-const itd = new ItdClient({
-  storage: new FileTokenStorage('./.itd-session.json'),
-  auth: {
-    email,
-    password,
-    getTurnstileToken: createTurnstileSolver(),
-  },
-});
-```
-
-## Вход и восстановление через OTP
-
-```ts
-await itd.auth.signInWithOtp({
-  email,
-  password,
-  turnstileToken,
-  getOtp: () => rl.question('Код из письма: '),
-});
-
-await itd.auth.resetPasswordWithOtp({
-  email,
-  turnstileToken,
-  newPassword,
-  getOtp: () => rl.question('Код из письма: '),
-});
-```
-
-## Потеря сессии
-
-Если refresh не удался, серверная ошибка приходит вызывающему коду и в событии
-`authError`:
-
-```ts
-itd.on('authError', ({ error }) => {
-  if (isItdApiError(error)) {
-    console.error(error.code);
-  }
-});
-```
-
-Полезные коды: `SESSION_NOT_FOUND`, `SESSION_REVOKED`, `REFRESH_TOKEN_MISSING`.
-
-## Примеры
-
-- [`examples/bot-with-session.mjs`](./examples/bot-with-session.mjs) — ручной токен
-  Turnstile при первом входе и сохранение сессии.
-- [`examples/turnstile-login.mjs`](./examples/turnstile-login.mjs) — автоматическое
-  получение Turnstile через браузер.
-
-Запуск из корня:
-
-```bash
-ITD_EMAIL=you@example.com ITD_PASSWORD=secret ITD_TURNSTILE=... \
-  node guides/authentication/examples/bot-with-session.mjs
-
-ITD_EMAIL=you@example.com ITD_PASSWORD=secret \
-  node guides/authentication/examples/turnstile-login.mjs
-```

package/guides/authentication/examples/bot-with-session.mjs

@@ -1,98 +0,0 @@
-/**
- * Бот на Node: вход по логину и паролю, сохранение сессии, публикация с опросом.
- *
- * Запуск:
- *   ITD_EMAIL=you@example.com ITD_PASSWORD=secret ITD_TURNSTILE=... \
- *     node guides/authentication/examples/bot-with-session.mjs
- *
- * Вход требует токен капчи Cloudflare Turnstile: получите его в браузере на странице входа
- * (ключ виджета — TURNSTILE_SITE_KEY) и передайте в ITD_TURNSTILE. Токен одноразовый
- * и живёт несколько минут, поэтому нужен только при первом запуске.
- *
- * Дальше сессия сохраняется в `.itd-session.json`, и повторный вход не понадобится:
- * библиотека продлевает её сама. Добавьте этот файл в .gitignore — в нём лежат токены.
- */
-
-import { createInterface } from 'node:readline/promises';
-import { FileTokenStorage, ItdClient, isItdApiError } from 'itd-api/node';
-
-const itd = new ItdClient({
-  // auth здесь не задаём: вход по паролю требует свежей капчи, поэтому он делается
-  // явно и только когда сохранённая сессия не подошла — см. ensureSignedIn().
-
-  // Без хранилища бот входил бы заново при каждом запуске, а серия входов подряд
-  // может привести к временной блокировке аккаунта.
-  storage: new FileTokenStorage('./.itd-session.json'),
-
-  // Ограничение нагрузки: запросы уходят не залпом, а ровным потоком.
-  rateLimit: { concurrency: 4, rps: 8 },
-
-  // logger: true, // раскомментируйте, чтобы видеть каждый запрос (токены маскируются)
-});
-
-// Сессия истекла и продлить её не удалось — здесь стоит уведомить владельца бота.
-// В error лежит ответ сервера: по error.code видно, отозвана сессия или просто истекла.
-itd.on('authError', ({ error }) =>
-  console.error('Сессия потеряна:', isItdApiError(error) ? error.code : error),
-);
-
-/**
- * Работает с сохранённой сессией, а входит заново, только если та не подошла.
- *
- * Отдельная проверка `hasRefreshSession()` не нужна: продление происходит само при 401.
- * Достаточно поймать 401, который пережил и продление тоже.
- */
-async function ensureSignedIn() {
-  try {
-    return await itd.users.me();
-  } catch (error) {
-    if (!isItdApiError(error) || error.status !== 401) throw error;
-  }
-
-  if (!process.env.ITD_TURNSTILE) {
-    throw new Error('Сохранённая сессия не подошла — нужен новый токен капчи в ITD_TURNSTILE');
-  }
-
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    await itd.auth.signInWithOtp({
-      email: process.env.ITD_EMAIL,
-      password: process.env.ITD_PASSWORD,
-      turnstileToken: process.env.ITD_TURNSTILE,
-      getOtp: () => rl.question('Код из письма: '),
-    });
-  } finally {
-    rl.close();
-  }
-
-  return itd.users.me();
-}
-
-const me = await ensureSignedIn();
-console.log(`Вошли как @${me.username}\n`);
-
-// Публикация с опросом. Файл загрузится сам, порядок вложений сохранится.
-const post = await itd.posts.create((p) =>
-  p
-    .content('Собираю мнения')
-    .poll((q) => q.question('Какой язык удобнее?').options('TypeScript', 'JavaScript')),
-);
-
-console.log(`Опубликовано: ${post.id}`);
-
-// Пример с картинкой — раскомментируйте, подставив существующий путь:
-// await itd.posts.create((p) => p.content('смотрите').attach('./photo.jpg'));
-
-// Обход подписок и реакция на непонравившиеся записи.
-let liked = 0;
-
-for await (const item of itd.posts.iterate({ tab: 'following' })) {
-  if (liked >= 5) break;
-  if (item.isLiked || item.isOwner) continue;
-
-  await itd.posts.like(item.id);
-  liked += 1;
-  console.log(`❤ @${item.author.username}: ${item.content.slice(0, 40)}`);
-}
-
-console.log(`\nПоставлено реакций: ${liked}`);

package/guides/authentication/examples/turnstile-login.mjs

@@ -1,56 +0,0 @@
-/**
- * Полностью автоматический вход: токен капчи добывается сам.
- *
- * Запуск:
- *   ITD_EMAIL=you@example.com ITD_PASSWORD=secret \
- *     node guides/authentication/examples/turnstile-login.mjs
- *
- * В соседнем `bot-with-session.mjs` токен капчи приходится добывать руками и передавать
- * в ITD_TURNSTILE. Здесь его берёт `@itd-api/turnstile`: поднимает браузер, забирает токен
- * и закрывается. Установите отдельно, основному пакету он не нужен:
- *
- *   npm i @itd-api/turnstile playwright
- *   npx playwright install chromium
- *
- * Браузер открывается с окном — так виджет проходится надёжнее. На сервере без графической
- * оболочки запускайте через
- * `xvfb-run -a node guides/authentication/examples/turnstile-login.mjs`.
- */
-
-import { FileTokenStorage, ItdClient, isItdApiError } from 'itd-api/node';
-import { createTurnstileSolver } from '@itd-api/turnstile';
-
-const itd = new ItdClient({
-  // Сессия переживает перезапуск, поэтому браузер поднимется только в первый раз —
-  // дальше клиент продлевает токен сам и до входа по паролю дело не доходит.
-  storage: new FileTokenStorage('./.itd-session.json'),
-
-  auth: {
-    email: process.env.ITD_EMAIL,
-    password: process.env.ITD_PASSWORD,
-
-    // Функция, а не готовая строка: токен одноразовый и живёт несколько минут, поэтому
-    // клиент спрашивает свежий перед каждой попыткой входа — в том числе через сутки,
-    // когда сессия истечёт и понадобится войти заново.
-    getTurnstileToken: createTurnstileSolver({
-      logger: (message) => console.log(`[turnstile] ${message}`),
-    }),
-  },
-});
-
-itd.on('signIn', () => console.log('Вход выполнен, сессия сохранена'));
-
-try {
-  const me = await itd.users.me();
-  console.log(`Вошли как @${me.username}`);
-
-  for await (const item of itd.posts.iterate({ tab: 'following' })) {
-    console.log(`@${item.author.username}: ${item.content.slice(0, 60)}`);
-    break;
-  }
-} catch (error) {
-  // Если аккаунт требует подтверждения кодом из письма, автоматический вход невозможен —
-  // клиент скажет об этом отдельно и предложит itd.auth.signInWithOtp().
-  console.error(isItdApiError(error) ? `${error.code}: ${error.message}` : error);
-  process.exitCode = 1;
-}

package/guides/integrations/README.md

@@ -1,62 +0,0 @@
-# Интеграции
-
-Готовые интеграции добавляют поддержку прокси-серверов и автоматическое получение
-Turnstile-токенов.
-
-| Пакет | Точка подключения |
-|---|---|
-| [`@itd-api/proxy`](../../proxy/README.md) | `ItdClientOptions.fetch` |
-| [`@itd-api/turnstile`](../../turnstile/README.md) | `auth.getTurnstileToken` |
-
-## Proxy
-
-Пакет создаёт совместимый `fetch`, который направляет HTTP/HTTPS-запросы через HTTP,
-HTTPS или SOCKS5-прокси:
-
-```bash
-npm install @itd-api/proxy
-```
-
-```ts
-import { ItdClient } from 'itd-api';
-import { proxyFetch } from '@itd-api/proxy';
-
-const fetch = proxyFetch('socks5://user:password@127.0.0.1:1080');
-const itd = new ItdClient({ auth: token, fetch });
-
-try {
-  console.log(await itd.users.me());
-} finally {
-  await itd.close();
-  await fetch.close();
-}
-```
-
-Через этот транспорт идут API-запросы, авторизация, повторы и realtime. Пакет работает
-в Node, Bun и Deno. В браузере исходящий SOCKS/HTTP-прокси таким способом настроить нельзя.
-
-Запускаемый пример:
-
-```bash
-ITD_TOKEN=<accessToken> ITD_PROXY=socks5://127.0.0.1:1080 \
-  node guides/integrations/examples/proxy.mjs
-```
-
-## Turnstile
-
-`@itd-api/turnstile` получает одноразовый токен капчи и передаёт его механизму входа:
-
-```ts
-import { createTurnstileSolver } from '@itd-api/turnstile';
-
-const itd = new ItdClient({
-  auth: {
-    email,
-    password,
-    getTurnstileToken: createTurnstileSolver(),
-  },
-});
-```
-
-Установка Playwright, сохранение сессии и запускаемые примеры описаны в
-[руководстве по авторизации](../authentication/README.md).

package/guides/integrations/examples/proxy.mjs

@@ -1,26 +0,0 @@
-/**
- * Запуск:
- *   ITD_TOKEN=<accessToken> ITD_PROXY=socks5://127.0.0.1:1080 \
- *     node guides/integrations/examples/proxy.mjs
- */
-
-import { proxyFetch } from '@itd-api/proxy';
-import { ItdClient } from 'itd-api';
-
-const token = process.env.ITD_TOKEN;
-const proxy = process.env.ITD_PROXY;
-
-if (!token || !proxy) {
-  throw new Error('Передайте ITD_TOKEN и ITD_PROXY');
-}
-
-const fetch = proxyFetch(proxy);
-const itd = new ItdClient({ auth: token, fetch });
-
-try {
-  const me = await itd.users.me();
-  console.log(`Прокси работает: @${me.username}`);
-} finally {
-  await itd.close();
-  await fetch.close();
-}

package/guides/multi-accounts/README.md

@@ -1,142 +0,0 @@
-# Несколько аккаунтов
-
-`ItdAccounts` управляет именованными клиентами. У каждого аккаунта отдельные tokens, cookie
-и `deviceId`, но сессии складываются в одно `MultiTokenStorage`.
-
-```ts
-import { FileMultiTokenStorage, ItdAccounts } from 'itd-api/node';
-
-const accounts = new ItdAccounts({
-  storage: new FileMultiTokenStorage('./.itd-sessions.json'),
-  rateLimit: { concurrency: 4 },
-});
-
-await accounts.restore();
-
-if (!accounts.has('kiow')) {
-  accounts.addAccount('kiow', {
-    auth: { email, password, getTurnstileToken },
-  });
-}
-
-const itd = accounts.account('kiow');
-await itd.posts.create({ content: 'привет' });
-await accounts.close();
-```
-
-Имя аккаунта локальное: сервер его не знает и библиотека не нормализует.
-
-## Основные операции
-
-| Метод | Назначение |
-|---|---|
-| `addAccount(name, options?)` | добавить аккаунт |
-| `account(name)` | получить обычный `ItdClient` |
-| `restore()` | восстановить аккаунты из хранилища |
-| `removeAccount(name, { forget })` | убрать аккаунт и при необходимости забыть сессию |
-| `has(name)`, `names()`, `size` | проверить состав |
-| `use(plugin)` | подключить плагин существующим и будущим клиентам |
-| `on(event, listener)` | слушать события всех аккаунтов |
-| `close()` | закрыть все клиенты |
-
-Идентификатор профиля можно прочитать из JWT без запроса:
-
-```ts
-for (const [name, itd] of accounts) {
-  console.log(name, await itd.getUserId());
-}
-```
-
-## Общие и личные настройки
-
-Общие опции задаются контейнеру, личные — в `addAccount()`. `headers` и `services`
-объединяются по ключам.
-
-```ts
-accounts.addAccount('первый', {
-  auth: token1,
-  fetch: proxyFetch('socks5://127.0.0.1:1080'),
-});
-
-accounts.addAccount('второй', {
-  auth: token2,
-  fetch: proxyFetch('socks5://127.0.0.1:1081'),
-});
-```
-
-`auth` и `deviceId` нельзя задавать контейнеру: они принадлежат конкретному аккаунту.
-Обычный `TokenStorage` здесь заменён общим `MultiTokenStorage`, поэтому личный `storage`
-в `addAccount()` также запрещён.
-
-## Очереди запросов
-
-По умолчанию у каждого аккаунта отдельная очередь. Это соответствует лимитам по аккаунту
-и не связывает клиентов, работающих через разные прокси.
-
-Если общий IP сам становится ограничением, включите одну очередь:
-
-```ts
-const accounts = new ItdAccounts({
-  storage,
-  rateLimit: { concurrency: 4, rps: 8 },
-  rateLimitScope: 'shared',
-});
-```
-
-В shared-режиме параметры очереди берутся из контейнера. Личный `rateLimit` у аккаунта
-запрещён, но `rateLimit: false` полностью выводит конкретный клиент из общей очереди.
-
-## Собственное хранилище
-
-Методы `MultiTokenStorage` получают имя аккаунта:
-
-```ts
-import { createMultiTokenStorage } from 'itd-api';
-
-const storage = createMultiTokenStorage({
-  get: async (account) =>
-    JSON.parse((await redis.get(`itd:session:${account}`)) ?? 'null'),
-
-  set: async (account, session) => {
-    await redis.set(`itd:session:${account}`, JSON.stringify(session));
-    await redis.sadd('itd:accounts', account);
-  },
-
-  clear: async (account) => {
-    await redis.del(`itd:session:${account}`);
-    await redis.srem('itd:accounts', account);
-  },
-
-  accounts: () => redis.smembers('itd:accounts'),
-});
-```
-
-Список `accounts()` ведёт сам адаптер. По нему `restore()` узнаёт, какие аккаунты нужно
-поднять после перезапуска.
-
-## События
-
-Контейнер добавляет имя аккаунта в полезную нагрузку:
-
-```ts
-accounts.on('authError', ({ account, error }) => {
-  console.error(`[${account}]`, error);
-});
-```
-
-Плагины, подключённые через `accounts.use(plugin)`, применяются ко всем существующим и
-будущим клиентам.
-
-## Realtime
-
-Каждый аккаунт держит своё SSE-соединение. Не открывайте поток автоматически всем, если
-уведомления нужны только части аккаунтов.
-
-## Запускаемый пример
-
-```bash
-ITD_TOKENS='бот-1=<accessToken>,бот-2=<accessToken>' \
-  node guides/multi-accounts/examples/multi-accounts.mjs
-```
-
-Исходник: [`examples/multi-accounts.mjs`](./examples/multi-accounts.mjs).

package/guides/multi-accounts/examples/multi-accounts.mjs

@@ -1,71 +0,0 @@
-/**
- * Несколько аккаунтов в одном процессе: общее хранилище сессий, свой токен у каждого.
- *
- * Запуск:
- *   ITD_TOKENS='бот-1=<accessToken>,бот-2=<accessToken>' \
- *     node guides/multi-accounts/examples/multi-accounts.mjs
- *
- * Первый запуск заводит аккаунты по токенам и складывает их сессии в `.itd-sessions.json`.
- * При следующих ITD_TOKENS уже не нужен: restore() поднимет всех из файла, а истёкшие
- * токены библиотека продлит сама. Файл в .gitignore — в нём лежат токены доступа.
- */
-
-import { FileMultiTokenStorage, ItdAccounts, isItdApiError } from 'itd-api/node';
-
-const accounts = new ItdAccounts({
-  storage: new FileMultiTokenStorage('./.itd-sessions.json'),
-
-  // Ограничение нагрузки. Лимиты итд.com считаются по аккаунту, поэтому очередь
-  // по умолчанию у каждого своя. Если все аккаунты ходят с одного IP и упираются
-  // в ограничение по адресу — добавьте rateLimitScope: 'shared'.
-  rateLimit: { concurrency: 4, rps: 8 },
-
-  // logger: true, // раскомментируйте, чтобы видеть каждый запрос (токены маскируются)
-});
-
-try {
-  // Обработчик один на всех: в полезной нагрузке приходит имя аккаунта.
-  accounts.on('authError', ({ account, error }) =>
-    console.error(`[${account}] сессия потеряна:`, isItdApiError(error) ? error.code : error),
-  );
-
-  // Поднимаем тех, кто уже входил раньше, — ни токена, ни капчи для этого не нужно.
-  const restored = await accounts.restore();
-  if (restored.length > 0) console.log(`Из хранилища: ${restored.join(', ')}`);
-
-  // Новые аккаунты — из переменной окружения вида «имя=токен,имя=токен».
-  for (const pair of (process.env.ITD_TOKENS ?? '').split(',').filter(Boolean)) {
-    const [name, token] = pair.split('=');
-    if (!name || !token || accounts.has(name)) continue;
-
-    accounts.addAccount(name, { auth: token });
-    console.log(`Добавлен: ${name}`);
-  }
-
-  if (accounts.size === 0) {
-    throw new Error('Ни одного аккаунта: передайте ITD_TOKENS при первом запуске');
-  }
-
-  // Клиент аккаунта — обычный ItdClient со всеми разделами.
-  for (const [name, itd] of accounts) {
-    // getUserId() читает идентификатор из самого токена и не стоит ни одного запроса.
-    const id = await itd.getUserId();
-
-    try {
-      const me = await itd.users.me();
-      console.log(`${name} → @${me.username} (${id ?? 'id неизвестен'})`);
-    } catch (error) {
-      console.error(`${name} → не отвечает:`, isItdApiError(error) ? error.code : error);
-    }
-  }
-
-  // Действие одним аккаунтом.
-  const [first] = accounts.names();
-  const posts = await accounts.account(first).posts.iterate({ tab: 'popular' }).collect(3);
-  console.log(`\n${first} видит ${posts.length} популярных записей`);
-
-  // Убрать аккаунт вместе с сохранённой сессией:
-  // await accounts.removeAccount('бот-2', { forget: true });
-} finally {
-  await accounts.close();
-}