itd-api 0.0.5 → 0.0.6

package/README.md

@@ -287,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` **до** обращения к сети:
 
@@ -440,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`
+молча подменяла бы путь или тело любого вызова.
+
+---
+
 ## Что доступно
 
 | Раздел | Методы |
@@ -454,6 +558,7 @@ Deno и React Native ограничение не действует.
 | `itd.reports` · `itd.verification` | жалобы, заявка на верификацию |
 | `itd.subscription` · `itd.platform` | подписка, способы оплаты, анонсы |
 | `itd.realtime()` | поток уведомлений |
+| `itd.use()` | плагины: обёртки вокруг запроса и ответа |
 | `itd.request()` | произвольный запрос, если метода ещё нет |
 
 Метода не хватает или ответ разошёлся с документацией — есть запасной путь:
@@ -482,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-RUPF4X5L.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",
@@ -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.5";
+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;
   }
   /**
    * Собирает перебор страниц.
@@ -4909,6 +5061,7 @@ var ItdClient = class {
   #authManager;
   #jar;
   #queue;
+  #plugins = new PluginRegistry();
   /** Авторизация, сессии и пароли. */
   auth;
   /** Профили, подписки, блокировки, приватность. */
@@ -4945,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(),
@@ -4990,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;
+  }
   /**
    * Подписывается на события авторизации.
    *
@@ -5216,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-RUPF4X5L.js.map
-//# sourceMappingURL=chunk-RUPF4X5L.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