itd-api 0.0.4 → 0.0.6

package/README.md

@@ -111,9 +111,8 @@ itd.on('authError', ({ error }) => {
 
 ### Капча обязательна при входе
 
-`signIn`, `signUp` и `forgotPassword` требуют токен Cloudflare Turnstile. Полностью
-автоматического входа по логину и паролю поэтому не бывает: капчу должен решить кто-то
-снаружи, а библиотека принимает готовый токен.
+`signIn`, `signUp` и `forgotPassword` требуют токен Cloudflare Turnstile. Сам клиент капчу
+не решает — он принимает готовый токен, а решает его кто-то снаружи.
 
 ```ts
 import { TURNSTILE_SITE_KEY } from 'itd-api';
@@ -134,6 +133,24 @@ new ItdClient({
 });
 ```
 
+В Node таким источником может быть [`itd-api-turnstile`](./turnstile) — отдельный пакет,
+который поднимает браузер и приносит токен. Отдельный он намеренно: тянет за собой Playwright
+и требует графической оболочки, а нужен далеко не всем — с сохранённой сессией до входа
+по паролю дело обычно вообще не доходит.
+
+```sh
+npm i itd-api-turnstile playwright
+```
+
+```ts
+import { createTurnstileSolver } from 'itd-api-turnstile';
+
+new ItdClient({
+  storage: new FileTokenStorage('./.itd-session.json'),
+  auth: { email, password, getTurnstileToken: createTurnstileSolver() },
+});
+```
+
 ### Вход с кодом из письма
 
 ```ts
@@ -205,8 +222,8 @@ await itd.setSession(await loadFromSomewhere());
 // по элементам
 for await (const post of itd.posts.iterate({ tab: 'popular' })) { … }
 
-// по страницам — когда нужен, например, total
-for await (const page of itd.users.iterateFollowers('durov').pages()) {
+// по страницам — когда нужны сведения о самой странице
+for await (const page of itd.posts.iterateComments(postId).pages()) {
   console.log(page.items.length, 'из', page.total);
 }
 
@@ -224,6 +241,24 @@ const next = await itd.posts.list({ tab: 'popular', cursor: page.nextCursor ?? u
 Курсор непрозрачен: у вкладки `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`.
+
 ---
 
 ## Публикация
@@ -252,6 +287,24 @@ await itd.posts.create(draft.content('второй'));   // заготовка
 Файлы из `attach()` загружаются автоматически, порядок вложений сохраняется, MIME-тип
 проверяется до отправки.
 
+Разметка текста передаётся полем `spans` — библиотека её не генерирует и не пересчитывает.
+Известные типы собраны в `SpanType`: `hashtag`, `mention`, `link`, `bold`, `italic`,
+`underline`, `strike`, `spoiler`, `monospace`, `quote`.
+
+```ts
+import { SpanType } from 'itd-api';
+
+await itd.posts.create({
+  content: 'жирное слово и ссылка',
+  spans: [
+    { type: SpanType.Bold, offset: 0, length: 6 },
+    { type: SpanType.Link, offset: 15, length: 6, url: 'https://example.com' },
+  ],
+});
+```
+
+У `link` адрес лежит в `url`, у `hashtag` и `mention` — имя в `tag`.
+
 Билдеры есть у поста, комментария, опроса и жалобы. Все они неизменяемые, а `build()`
 проверяет данные и бросает `ItdConfigError` **до** обращения к сети:
 
@@ -361,8 +414,8 @@ const itd = new ItdClient({
 по модулям, и темп будет общим.
 
 `concurrency` (по умолчанию 6) ограничивает только одновременность. От ограничения частоты
-он почти не спасает: десять запросов подряд при `concurrency: 1` уходят за ~150 мс, а окно
-сервера — около 5 запросов на минуту с лишним. Темп задаёт `rps`:
+он почти не спасает: десять запросов подряд при `concurrency: 1` уходят за ~150 мс,
+а окно сервера измеряется десятками секунд. Темп задаёт `rps`:
 
 ```ts
 rateLimit: { concurrency: 2, rps: 0.5 }   // не чаще одного запроса в 2 секунды
@@ -371,7 +424,9 @@ rateLimit: { concurrency: 2, rps: 0.5 }   // не чаще одного запр
 Ставить `concurrency: 1` без нужды не стоит: загрузка видео с таймаутом в 300 секунд
 заблокирует на это время вообще всё остальное.
 
-**Ограничение частоты — отдельный механизм.** Сервер разрешает около 5 запросов в окно,
+**Ограничение частоты — отдельный механизм.** Лимит у каждого эндпоинта свой: замеры по
+`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`).
@@ -403,6 +458,92 @@ Deno и React Native ограничение не действует.
 
 ---
 
+## Плагины
+
+Плагин — обёртка вокруг запроса: она видит тело до отправки и разобранный ответ, поэтому
+одна обёртка охватывает сразу все методы клиента. Подключается через `itd.use()`:
+
+```ts
+import { ItdClient } from 'itd-api';
+import { crypt } from 'itd-api-crypto';
+
+const itd = new ItdClient({ auth: token });
+itd.use(crypt());
+```
+
+### `itd-api-crypto` — скрытые сообщения
+
+[Отдельный пакет](./crypto): прячет текст в невидимых символах внутри обычного поста.
+Читатель видит обложку, а тот, у кого подключён плагин, получает спрятанное отдельным полем.
+
+```sh
+npm i itd-api-crypto
+```
+
+```ts
+// отправка: текст прогоняется через шифр, обложка остаётся видимой
+const created = await itd.posts.create(
+  { content: 'секретный текст' },
+  { encrypt: { cipher: 'invisible', cover: 'обычный пост' } },
+);
+
+// чтение: content не меняется, расшифровка приезжает рядом
+const post = await itd.posts.get(created.id);
+post.secret?.text;   // 'секретный текст'
+```
+
+Работает для постов, комментариев, ответов, имени и подписи профиля. Расшифровка идёт сама
+и вглубь: находки появляются и у постов ленты, и у исходного поста репоста, и у авторов.
+
+Шифра два: `invisible` — невидимые символы с обложкой, `beecrypt` — видимый текст из букв
+`жъЖЪ`. Подробности, ограничения и то, как подключить свой шифр, — в
+[README пакета](./crypto).
+
+### Свой плагин
+
+```ts
+import type { ItdPlugin } from 'itd-api';
+
+const timing: ItdPlugin = {
+  name: 'timing',
+  install({ use, logger }) {
+    use(async (request, next) => {
+      const started = Date.now();
+      try {
+        return await next(request);
+      } finally {
+        logger?.info(`${request.method} ${request.path}: ${Date.now() - started} мс`);
+      }
+    });
+  },
+};
+```
+
+Обёртка может изменить запрос (передайте в `next` копию), подменить ответ или вернуть своё,
+не обращаясь к сети. Подключённая раньше оказывается снаружи. Выполняется она один раз
+на запрос, независимо от числа повторов.
+
+Свои опции запроса плагин объявляет сам — библиотека их не понимает, но доносит до обёртки
+нетронутыми:
+
+```ts
+const plugin: ItdPlugin = {
+  name: 'мой',
+  optionKeys: ['мояОпция'],
+  install({ use }) { /* … */ },
+};
+
+declare module 'itd-api' {
+  interface RequestOptions { мояОпция?: string | undefined }
+}
+```
+
+Имена полей самого запроса (`path`, `body`, `headers`, `signal` и прочие) заявить нельзя:
+подключение такого плагина завершится `ItdConfigError`. Иначе опечатка в `optionKeys`
+молча подменяла бы путь или тело любого вызова.
+
+---
+
 ## Что доступно
 
 | Раздел | Методы |
@@ -417,6 +558,7 @@ Deno и React Native ограничение не действует.
 | `itd.reports` · `itd.verification` | жалобы, заявка на верификацию |
 | `itd.subscription` · `itd.platform` | подписка, способы оплаты, анонсы |
 | `itd.realtime()` | поток уведомлений |
+| `itd.use()` | плагины: обёртки вокруг запроса и ответа |
 | `itd.request()` | произвольный запрос, если метода ещё нет |
 
 Метода не хватает или ответ разошёлся с документацией — есть запасной путь:
@@ -445,7 +587,8 @@ TypeScript 5.0+. Пакет собран в ESM и CommonJS, типы корре
 
 ```bash
 npm install
-npm test            # 342 теста
+npm test            # 417 тестов
+npm run test:all    # вместе с пакетами workspace
 npm run typecheck
 npm run lint
 npm run build

package/dist/{chunk-JV75JWOX.js → chunk-CCRQI3ON.js}

@@ -577,6 +577,24 @@ var AttachmentType = Object.freeze({
   /** Голосовые комментарии: `audio/ogg`, с полем `duration`. */
   Audio: "audio"
 });
+var SpanType = Object.freeze({
+  /** Хэштег. Название без решётки лежит в `tag`. */
+  Hashtag: "hashtag",
+  /** Упоминание. Имя пользователя лежит в `tag`. */
+  Mention: "mention",
+  /** Ссылка. Адрес лежит в `url`, а не в `tag`. */
+  Link: "link",
+  Bold: "bold",
+  Italic: "italic",
+  Underline: "underline",
+  /** Зачёркнутый. */
+  Strike: "strike",
+  /** Спойлер: текст скрыт до нажатия. */
+  Spoiler: "spoiler",
+  /** Моноширинный. */
+  Monospace: "monospace",
+  Quote: "quote"
+});
 var ReportTargetType = Object.freeze({
   Post: "post",
   Comment: "comment",
@@ -1554,7 +1572,7 @@ var AuthManager = class {
     }
     if (credentials.turnstileToken) return credentials.turnstileToken;
     throw new ItdConfigError(
-      "\u0412\u0445\u043E\u0434 \u043F\u043E email \u0438 \u043F\u0430\u0440\u043E\u043B\u044E \u0442\u0440\u0435\u0431\u0443\u0435\u0442 \u0442\u043E\u043A\u0435\u043D \u043A\u0430\u043F\u0447\u0438 Cloudflare Turnstile: \u0431\u0435\u0437 \u043D\u0435\u0433\u043E \u0441\u0435\u0440\u0432\u0435\u0440 \u043E\u0442\u0432\u0435\u0447\u0430\u0435\u0442 422. \u041F\u0435\u0440\u0435\u0434\u0430\u0439\u0442\u0435 auth.getTurnstileToken (\u0438\u0441\u0442\u043E\u0447\u043D\u0438\u043A \u0441\u0432\u0435\u0436\u0435\u0433\u043E \u0442\u043E\u043A\u0435\u043D\u0430) \u043B\u0438\u0431\u043E \u0440\u0430\u0437\u043E\u0432\u044B\u0439 auth.turnstileToken. \u041A\u043B\u044E\u0447 \u0432\u0438\u0434\u0436\u0435\u0442\u0430 \u2014 TURNSTILE_SITE_KEY."
+      "\u0412\u0445\u043E\u0434 \u043F\u043E email \u0438 \u043F\u0430\u0440\u043E\u043B\u044E \u0442\u0440\u0435\u0431\u0443\u0435\u0442 \u0442\u043E\u043A\u0435\u043D \u043A\u0430\u043F\u0447\u0438 Cloudflare Turnstile: \u0431\u0435\u0437 \u043D\u0435\u0433\u043E \u0441\u0435\u0440\u0432\u0435\u0440 \u043E\u0442\u0432\u0435\u0447\u0430\u0435\u0442 422. \u041F\u0435\u0440\u0435\u0434\u0430\u0439\u0442\u0435 auth.getTurnstileToken (\u0438\u0441\u0442\u043E\u0447\u043D\u0438\u043A \u0441\u0432\u0435\u0436\u0435\u0433\u043E \u0442\u043E\u043A\u0435\u043D\u0430) \u043B\u0438\u0431\u043E \u0440\u0430\u0437\u043E\u0432\u044B\u0439 auth.turnstileToken. \u041A\u043B\u044E\u0447 \u0432\u0438\u0434\u0436\u0435\u0442\u0430 \u2014 TURNSTILE_SITE_KEY. \u0412 Node \u0442\u043E\u043A\u0435\u043D \u0443\u043C\u0435\u0435\u0442 \u0434\u043E\u0431\u044B\u0432\u0430\u0442\u044C \u043E\u0442\u0434\u0435\u043B\u044C\u043D\u044B\u0439 \u043F\u0430\u043A\u0435\u0442: npm i itd-api-turnstile, \u0437\u0430\u0442\u0435\u043C getTurnstileToken: createTurnstileSolver()."
     );
   }
   async #performSignIn(credentials) {
@@ -1696,7 +1714,7 @@ function normalizeBaseUrl(baseUrl) {
 // src/core/config.ts
 var DEFAULT_BASE_URL = "https://xn--d1ah4a.com";
 var DEFAULT_TIMEOUT = 3e4;
-var LIBRARY_VERSION = "0.0.4";
+var LIBRARY_VERSION = "0.0.6";
 var DEFAULT_USER_AGENT = `Mozilla/5.0 (compatible; itd-api/${LIBRARY_VERSION}; +https://github.com/KiowDev/itd-api)`;
 var DEFAULT_RATE_LIMIT_DELAYS = Object.freeze([1e3, 5e3, 3e4, 6e4, 9e4]);
 function requirePositive(value, name) {
@@ -2091,6 +2109,7 @@ function createApiError(context) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var EMPTY_KEYS = /* @__PURE__ */ new Set();
 function setHeader(headers, name, value) {
   try {
     headers.set(name, value);
@@ -2144,6 +2163,7 @@ function createAbortBundle(userSignal, timeout) {
 var HttpClient = class {
   #config;
   #collaborators;
+  #plugins;
   constructor(config, collaborators = {}) {
     this.#config = config;
     this.#collaborators = collaborators;
@@ -2152,6 +2172,19 @@ var HttpClient = class {
   get baseUrl() {
     return this.#config.baseUrl;
   }
+  /**
+   * Имена опций запроса, заявленные плагинами.
+   *
+   * Читается ресурсами: они переносят в транспорт только известные поля, а чужие,
+   * если их никто не заявил, отсеивают.
+   */
+  get pluginOptionKeys() {
+    return this.#plugins?.optionKeys ?? EMPTY_KEYS;
+  }
+  /** Подключает список плагинов. Реестр общий с клиентом и пополняется через `itd.use()`. */
+  usePlugins(plugins) {
+    this.#plugins = plugins;
+  }
   /**
    * Подключает недостающие части конвейера.
    *
@@ -2171,10 +2204,22 @@ var HttpClient = class {
    * @throws {ItdNetworkError} если запрос не дошёл до сервера
    */
   async request(options) {
-    const task = () => this.#withRetries(options);
+    const task = () => this.#withPlugins(options);
     if (!this.#collaborators.schedule || options.skipQueue) return task();
     return this.#collaborators.schedule(task);
   }
+  /**
+   * Прогоняет запрос через обёртки плагинов.
+   *
+   * Цепочка стоит **снаружи повторов и внутри очереди**: плагин должен увидеть запрос
+   * и ответ по одному разу, независимо от того, сколько попыток понадобилось, — иначе,
+   * например, текст поста зашифруется повторно на второй попытке.
+   */
+  #withPlugins(options) {
+    const plugins = this.#plugins;
+    if (!plugins || plugins.size === 0) return this.#withRetries(options);
+    return plugins.run(options, (request) => this.#withRetries(request));
+  }
   async #withRetries(options) {
     const method = options.method.toUpperCase();
     for (let attempt = 1; ; attempt++) {
@@ -2320,6 +2365,97 @@ var HttpClient = class {
   }
 };
 
+// src/core/plugins.ts
+var NO_KEYS = /* @__PURE__ */ new Set();
+var RESERVED_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "signal",
+  "timeout",
+  "headers",
+  "retry",
+  "method",
+  "path",
+  "query",
+  "body",
+  "skipAuth",
+  "skipAuthRefresh",
+  "skipQueue",
+  "raw"
+]);
+var PluginRegistry = class {
+  #transformers = [];
+  #optionKeys = /* @__PURE__ */ new Set();
+  #names = /* @__PURE__ */ new Set();
+  /** Сколько обёрток подключено. Ноль означает, что запрос идёт прежним путём. */
+  get size() {
+    return this.#transformers.length;
+  }
+  /** Имена опций запроса, заявленные плагинами. */
+  get optionKeys() {
+    return this.#optionKeys.size === 0 ? NO_KEYS : this.#optionKeys;
+  }
+  /**
+   * Подключает плагин.
+   *
+   * @throws {ItdConfigError} если плагин задан неверно, уже подключён или заявил занятое
+   * имя опции
+   */
+  add(plugin, context) {
+    if (typeof plugin?.install !== "function") {
+      throw new ItdConfigError("\u041F\u043B\u0430\u0433\u0438\u043D \u0434\u043E\u043B\u0436\u0435\u043D \u0431\u044B\u0442\u044C \u043E\u0431\u044A\u0435\u043A\u0442\u043E\u043C \u0441 \u043C\u0435\u0442\u043E\u0434\u043E\u043C install()");
+    }
+    const name = plugin.name;
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new ItdConfigError("\u0423 \u043F\u043B\u0430\u0433\u0438\u043D\u0430 \u0434\u043E\u043B\u0436\u043D\u043E \u0431\u044B\u0442\u044C \u043D\u0435\u043F\u0443\u0441\u0442\u043E\u0435 \u0438\u043C\u044F");
+    }
+    if (this.#names.has(name)) {
+      throw new ItdConfigError(`\u041F\u043B\u0430\u0433\u0438\u043D \xAB${name}\xBB \u0443\u0436\u0435 \u043F\u043E\u0434\u043A\u043B\u044E\u0447\u0451\u043D`);
+    }
+    const keys = plugin.optionKeys ?? [];
+    for (const key of keys) {
+      if (typeof key !== "string" || key.trim() === "") {
+        throw new ItdConfigError(`\u041F\u043B\u0430\u0433\u0438\u043D \xAB${name}\xBB \u0437\u0430\u044F\u0432\u0438\u043B \u043F\u0443\u0441\u0442\u043E\u0435 \u0438\u043C\u044F \u043E\u043F\u0446\u0438\u0438`);
+      }
+      if (RESERVED_OPTION_KEYS.has(key)) {
+        throw new ItdConfigError(
+          `\u041F\u043B\u0430\u0433\u0438\u043D \xAB${name}\xBB \u0437\u0430\u044F\u0432\u0438\u043B \u043E\u043F\u0446\u0438\u044E \xAB${key}\xBB: \u044D\u0442\u043E \u043F\u043E\u043B\u0435 \u0437\u0430\u043F\u0440\u043E\u0441\u0430, \u0438\u043C\u044F \u0437\u0430\u043D\u044F\u0442\u043E. \u0417\u0430\u043D\u044F\u0442\u044B\u0435 \u0438\u043C\u0435\u043D\u0430: ${[...RESERVED_OPTION_KEYS].join(", ")}`
+        );
+      }
+    }
+    const before = this.#transformers.length;
+    try {
+      plugin.install({
+        ...context,
+        use: (transformer) => {
+          if (typeof transformer !== "function") {
+            throw new ItdConfigError(`\u041F\u043B\u0430\u0433\u0438\u043D \xAB${name}\xBB \u043F\u0435\u0440\u0435\u0434\u0430\u043B \u0432 use() \u043D\u0435 \u0444\u0443\u043D\u043A\u0446\u0438\u044E`);
+          }
+          this.#transformers.push(transformer);
+        }
+      });
+    } catch (error) {
+      this.#transformers.length = before;
+      throw error;
+    }
+    this.#names.add(name);
+    for (const key of keys) this.#optionKeys.add(key);
+  }
+  /**
+   * Прогоняет запрос через цепочку обёрток.
+   *
+   * Цепочка собирается на каждый запрос заново: плагин можно подключить в любой момент,
+   * а обёрток единицы — экономить тут не на чем.
+   *
+   * @param execute настоящий запрос, вызывается самой внутренней обёрткой
+   */
+  run(request, execute) {
+    const chain = this.#transformers.reduceRight(
+      (next, transformer) => (current) => transformer(current, next),
+      execute
+    );
+    return chain(request);
+  }
+};
+
 // src/core/rate-limit.ts
 var RequestQueue = class {
   #concurrency;
@@ -3240,15 +3376,31 @@ var BaseResource = class {
   constructor(http) {
     this.http = http;
   }
-  /** Переносит общие поля опций запроса в параметры транспорта. */
+  /**
+   * Переносит общие поля опций запроса в параметры транспорта.
+   *
+   * Поля перечислены поимённо, а не скопированы целиком: параметры методов наследуют
+   * {@link RequestOptions} и приносят с собой `limit`, `cursor` и прочее, чему в описании
+   * запроса делать нечего. Исключение — опции, заявленные плагинами: их библиотека
+   * не понимает, но обязана донести до обёрток нетронутыми.
+   */
   requestOptions(options) {
     if (!options) return {};
-    return {
+    const result = {
       ...options.signal !== void 0 ? { signal: options.signal } : {},
       ...options.timeout !== void 0 ? { timeout: options.timeout } : {},
       ...options.headers !== void 0 ? { headers: options.headers } : {},
       ...options.retry !== void 0 ? { retry: options.retry } : {}
     };
+    const pluginKeys = this.http.pluginOptionKeys;
+    if (pluginKeys.size === 0) return result;
+    const source = options;
+    const target = result;
+    for (const key of pluginKeys) {
+      const value = source[key];
+      if (value !== void 0) target[key] = value;
+    }
+    return result;
   }
   /**
    * Собирает перебор страниц.
@@ -4475,7 +4627,16 @@ var PostsResource = class extends BaseResource {
     });
     return pickArray(body, "posts");
   }
-  /** Загружает страницу постов пользователя (его стену). */
+  /**
+   * Загружает страницу стены пользователя.
+   *
+   * Это **не только его собственные посты**: сюда попадают и записи, которые другие
+   * оставили на его стене — у них `author` чужой, а `wallRecipient` указывает на владельца
+   * стены. Поэтому число записей обычно больше, чем `postsCount` из профиля; чтобы
+   * получить только авторские посты, отфильтруйте по `post.author.id`.
+   *
+   * Принимает и UUID, и имя пользователя.
+   */
   async byUser(user, params = {}) {
     const body = await this.http.request({
       method: "GET",
@@ -4490,7 +4651,7 @@ var PostsResource = class extends BaseResource {
     });
     return readCursorPage(body, "posts");
   }
-  /** Перебирает посты пользователя. */
+  /** Перебирает стену пользователя. Что именно в неё входит — см. {@link byUser}. */
   iterateByUser(user, params = {}) {
     const path = `/api/posts/user/${encodePathSegment(user, "user")}`;
     return this.paginate(
@@ -4733,19 +4894,34 @@ var UsersResource = class extends BaseResource {
       ...this.requestOptions(options)
     });
   }
-  /** Загружает страницу подписчиков. */
+  /**
+   * Загружает подписчиков пользователя.
+   *
+   * ⚠️ **Сервер этот список не листает.** Возвращаются первые 20 записей и только они:
+   * параметр `page` игнорируется (любая страница отдаёт те же записи и `pagination.page: 1`),
+   * `limit` больше 20 молча уменьшается, а `hasMore` всегда `false`. Последнее честно —
+   * получить продолжение нечем.
+   *
+   * Числу `total` доверять тоже не стоит: оно расходится с `followersCount` из профиля —
+   * на проверенных аккаунтах занижено примерно на 1–4%.
+   */
   followers(user, params = {}) {
     return this.#userPage(`/api/users/${encodePathSegment(user, "user")}/followers`, params);
   }
-  /** Перебирает подписчиков. */
+  /**
+   * Перебирает подписчиков.
+   *
+   * ⚠️ Перебор закончится после первых 20 записей: сервер список не листает —
+   * см. {@link followers}. Метод оставлен на случай, если пагинацию починят.
+   */
   iterateFollowers(user, params = {}) {
     return this.#userPaginator(`/api/users/${encodePathSegment(user, "user")}/followers`, params);
   }
-  /** Загружает страницу подписок. */
+  /** Загружает подписки пользователя. Ограничения те же, что у {@link followers}. */
   following(user, params = {}) {
     return this.#userPage(`/api/users/${encodePathSegment(user, "user")}/following`, params);
   }
-  /** Перебирает подписки. */
+  /** Перебирает подписки. Закончится после первых 20 записей — см. {@link followers}. */
   iterateFollowing(user, params = {}) {
     return this.#userPaginator(`/api/users/${encodePathSegment(user, "user")}/following`, params);
   }
@@ -4785,11 +4961,11 @@ var UsersResource = class extends BaseResource {
       ...this.requestOptions(options)
     });
   }
-  /** Загружает страницу заблокированных пользователей. */
+  /** Загружает заблокированных пользователей. Ограничения те же, что у {@link followers}. */
   blocked(params = {}) {
     return this.#userPage("/api/users/me/blocked", params);
   }
-  /** Перебирает заблокированных пользователей. */
+  /** Перебирает заблокированных. Закончится после первых 20 записей — см. {@link followers}. */
   iterateBlocked(params = {}) {
     return this.#userPaginator("/api/users/me/blocked", params);
   }
@@ -4850,6 +5026,9 @@ var UsersResource = class extends BaseResource {
    * Имена полей перечислены с запасом: списки подписчиков и заблокированных приходят
    * под `users`, но альтернативное имя ничего не стоит и спасает, если эндпоинт назовёт
    * список по-своему.
+   *
+   * `page` уходит в запрос, хотя сервер его сейчас не читает (см. {@link followers}):
+   * когда пагинацию починят, работать начнёт само.
    */
   async #loadUserPage(path, params, state) {
     const body = await this.http.request({
@@ -4882,6 +5061,7 @@ var ItdClient = class {
   #authManager;
   #jar;
   #queue;
+  #plugins = new PluginRegistry();
   /** Авторизация, сессии и пароли. */
   auth;
   /** Профили, подписки, блокировки, приватность. */
@@ -4918,6 +5098,7 @@ var ItdClient = class {
     this.#http = new HttpClient(this.#config);
     this.#authManager = new AuthManager(this.#config, this.#http, this.#jar);
     this.#queue = this.#config.rateLimit ? new RequestQueue(this.#config.rateLimit) : void 0;
+    this.#http.usePlugins(this.#plugins);
     this.#http.setCollaborators({
       getAuthHeaders: () => this.#authManager.getAuthHeaders(),
       getDeviceId: () => this.#authManager.getDeviceId(),
@@ -4963,6 +5144,27 @@ var ItdClient = class {
   request(options) {
     return this.#http.request(options);
   }
+  /**
+   * Подключает плагин.
+   *
+   * Плагин работает на уровне транспорта: видит запрос до отправки и разобранный ответ,
+   * поэтому одна обёртка охватывает сразу все методы клиента. Подключать можно в любой
+   * момент, но обычно это делают сразу после создания клиента.
+   *
+   * @throws {ItdConfigError} если плагин задан неверно или уже подключён
+   *
+   * @example
+   * ```ts
+   * import { crypt } from 'itd-api-crypto';
+   *
+   * itd.use(crypt());
+   * await itd.posts.create({ content: 'секрет' }, { encrypt: 'invis' });
+   * ```
+   */
+  use(plugin) {
+    this.#plugins.add(plugin, { baseUrl: this.#config.baseUrl, logger: this.#config.logger });
+    return this;
+  }
   /**
    * Подписывается на события авторизации.
    *
@@ -5189,6 +5391,6 @@ function toDate(value) {
   return Number.isFinite(date.getTime()) ? date : null;
 }
 
-export { ALLOWED_MIME_TYPES, AUDIO_MIME_TYPES, AUTH_FLAG_COOKIE, AUTH_PATHS, AttachmentType, CommentSort, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_USER_AGENT, DEVICE_ID_HEADER, DetectedRuntime, FeedTab, IMAGE_MIME_TYPES, ItdAbortError, ItdApiError, ItdApiErrorKind, ItdAuthError, ItdClient, ItdConfigError, ItdConflictError, ItdError, ItdErrorCode, ItdErrorKind, ItdForbiddenError, ItdNetworkError, ItdNotFoundError, ItdPhoneVerificationError, ItdRateLimitError, ItdRealtime, ItdServerError, ItdTimeoutError, ItdValidationError, LIBRARY_VERSION, LikesVisibility, LocalStorageTokenStorage, MAX_RECONNECT_ATTEMPTS, MemoryTokenStorage, NOTIFICATION_TYPE_ALIASES, NotificationType, OAuthProvider, PaginationMode, Paginator, RECONNECT_BACKOFF, RECONNECT_JITTER, REFRESH_COOKIE, REFRESH_COOKIE_PATH, RealtimeStatus, RealtimeTransportKind, ReportReason, ReportTargetType, RuntimeMode, STREAM_PATH, SignInStatus, TURNSTILE_SITE_KEY, UnauthorizedStreamError, VIDEO_MIME_TYPES, WallAccess, canonicalNotificationType, comment, createClient, createTokenStorage, formatNotificationText, isBuilder, isItdApiError, isItdAuthError, isItdConflictError, isItdError, isItdForbiddenError, isItdNotFoundError, isItdPhoneVerificationError, isItdRateLimitError, isItdServerError, isItdValidationError, isKnownNotificationType, isMyProfile, normalizeNotification, poll, post, readNotificationEvent, readUnreadCountEvent, report, resolveNotificationUrl, toDate };
-//# sourceMappingURL=chunk-JV75JWOX.js.map
-//# sourceMappingURL=chunk-JV75JWOX.js.map
+export { ALLOWED_MIME_TYPES, AUDIO_MIME_TYPES, AUTH_FLAG_COOKIE, AUTH_PATHS, AttachmentType, CommentSort, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_USER_AGENT, DEVICE_ID_HEADER, DetectedRuntime, FeedTab, IMAGE_MIME_TYPES, ItdAbortError, ItdApiError, ItdApiErrorKind, ItdAuthError, ItdClient, ItdConfigError, ItdConflictError, ItdError, ItdErrorCode, ItdErrorKind, ItdForbiddenError, ItdNetworkError, ItdNotFoundError, ItdPhoneVerificationError, ItdRateLimitError, ItdRealtime, ItdServerError, ItdTimeoutError, ItdValidationError, LIBRARY_VERSION, LikesVisibility, LocalStorageTokenStorage, MAX_RECONNECT_ATTEMPTS, MemoryTokenStorage, NOTIFICATION_TYPE_ALIASES, NotificationType, OAuthProvider, PaginationMode, Paginator, RECONNECT_BACKOFF, RECONNECT_JITTER, REFRESH_COOKIE, REFRESH_COOKIE_PATH, RealtimeStatus, RealtimeTransportKind, ReportReason, ReportTargetType, RuntimeMode, STREAM_PATH, SignInStatus, SpanType, TURNSTILE_SITE_KEY, UnauthorizedStreamError, VIDEO_MIME_TYPES, WallAccess, canonicalNotificationType, comment, createClient, createTokenStorage, formatNotificationText, isBuilder, isItdApiError, isItdAuthError, isItdConflictError, isItdError, isItdForbiddenError, isItdNotFoundError, isItdPhoneVerificationError, isItdRateLimitError, isItdServerError, isItdValidationError, isKnownNotificationType, isMyProfile, normalizeNotification, poll, post, readNotificationEvent, readUnreadCountEvent, report, resolveNotificationUrl, toDate };
+//# sourceMappingURL=chunk-CCRQI3ON.js.map
+//# sourceMappingURL=chunk-CCRQI3ON.js.map