itd-api 0.0.4 → 0.0.6

package/dist/{chunk-XG43KEYF.cjs → chunk-K7NBFQEE.cjs}

@@ -579,6 +579,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",
@@ -1556,7 +1574,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) {
@@ -1698,7 +1716,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) {
@@ -2093,6 +2111,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);
@@ -2146,6 +2165,7 @@ function createAbortBundle(userSignal, timeout) {
 var HttpClient = class {
   #config;
   #collaborators;
+  #plugins;
   constructor(config, collaborators = {}) {
     this.#config = config;
     this.#collaborators = collaborators;
@@ -2154,6 +2174,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;
+  }
   /**
    * Подключает недостающие части конвейера.
    *
@@ -2173,10 +2206,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++) {
@@ -2322,6 +2367,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;
@@ -3242,15 +3378,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;
   }
   /**
    * Собирает перебор страниц.
@@ -4477,7 +4629,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",
@@ -4492,7 +4653,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(
@@ -4735,19 +4896,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);
   }
@@ -4787,11 +4963,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);
   }
@@ -4852,6 +5028,9 @@ var UsersResource = class extends BaseResource {
    * Имена полей перечислены с запасом: списки подписчиков и заблокированных приходят
    * под `users`, но альтернативное имя ничего не стоит и спасает, если эндпоинт назовёт
    * список по-своему.
+   *
+   * `page` уходит в запрос, хотя сервер его сейчас не читает (см. {@link followers}):
+   * когда пагинацию починят, работать начнёт само.
    */
   async #loadUserPage(path, params, state) {
     const body = await this.http.request({
@@ -4884,6 +5063,7 @@ var ItdClient = class {
   #authManager;
   #jar;
   #queue;
+  #plugins = new PluginRegistry();
   /** Авторизация, сессии и пароли. */
   auth;
   /** Профили, подписки, блокировки, приватность. */
@@ -4920,6 +5100,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(),
@@ -4965,6 +5146,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;
+  }
   /**
    * Подписывается на события авторизации.
    *
@@ -5244,6 +5446,7 @@ exports.ReportTargetType = ReportTargetType;
 exports.RuntimeMode = RuntimeMode;
 exports.STREAM_PATH = STREAM_PATH;
 exports.SignInStatus = SignInStatus;
+exports.SpanType = SpanType;
 exports.TURNSTILE_SITE_KEY = TURNSTILE_SITE_KEY;
 exports.UnauthorizedStreamError = UnauthorizedStreamError;
 exports.VIDEO_MIME_TYPES = VIDEO_MIME_TYPES;
@@ -5274,5 +5477,5 @@ exports.readUnreadCountEvent = readUnreadCountEvent;
 exports.report = report;
 exports.resolveNotificationUrl = resolveNotificationUrl;
 exports.toDate = toDate;
-//# sourceMappingURL=chunk-XG43KEYF.cjs.map
-//# sourceMappingURL=chunk-XG43KEYF.cjs.map
+//# sourceMappingURL=chunk-K7NBFQEE.cjs.map
+//# sourceMappingURL=chunk-K7NBFQEE.cjs.map