itd-api 0.0.5 → 0.0.7

package/dist/{chunk-RUPF4X5L.js → chunk-CG4SERVM.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",
@@ -596,14 +614,18 @@ var RealtimeStatus = Object.freeze({
   Error: "error",
   Disconnected: "disconnected"
 });
-var WallAccess = Object.freeze({
-  Everyone: "everyone"
-});
-var LikesVisibility = Object.freeze({
-  Everyone: "everyone",
+var AccessType = Object.freeze({
+  /** Никто. */
+  Nobody: "nobody",
   /** Только взаимные подписки. */
-  Mutual: "mutual"
+  Mutual: "mutual",
+  /** Подписчики. */
+  Followers: "followers",
+  /** Все. */
+  Everyone: "everyone"
 });
+var WallAccess = AccessType;
+var LikesVisibility = AccessType;
 var NotificationType = Object.freeze({
   /** Реакция на пост. Старое имя — `like`. */
   PostReaction: "post_reaction",
@@ -632,6 +654,36 @@ var NotificationType = Object.freeze({
   /** Верификация отклонена. Приходит только по REST. */
   VerificationRejected: "verification_rejected"
 });
+var InteractionType = Object.freeze({
+  /** Открытие фотографии. */
+  PhotoOpen: 1,
+  /** Прогресс просмотра видео. Несёт поля `pm`/`dm`. */
+  VideoProgress: 2
+});
+var ViewSource = Object.freeze({
+  FeedGlobal: 1,
+  FeedFollowing: 2,
+  FeedClan: 3,
+  Profile: 4,
+  Hashtag: 5,
+  PostPage: 6,
+  Link: 7,
+  Search: 8
+});
+var ViewReason = Object.freeze({
+  /** Пост ушёл из зоны видимости при обычной прокрутке. */
+  Normal: 0,
+  /** Потеря фокуса окна. */
+  Blur: 1,
+  /** Вкладка скрыта. */
+  Hidden: 2,
+  /** Уход со страницы (`pagehide`). */
+  PageHide: 3,
+  /** Элемент перестал наблюдаться. */
+  Unobserve: 4,
+  /** Достигнут порог времени просмотра. */
+  ThresholdMet: 5
+});
 var ItdErrorCode = Object.freeze({
   BAD_REQUEST: "BAD_REQUEST",
   UNAUTHORIZED: "UNAUTHORIZED",
@@ -1696,7 +1748,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.7";
 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 +2143,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 +2197,7 @@ function createAbortBundle(userSignal, timeout) {
 var HttpClient = class {
   #config;
   #collaborators;
+  #plugins;
   constructor(config, collaborators = {}) {
     this.#config = config;
     this.#collaborators = collaborators;
@@ -2152,6 +2206,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 +2238,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 +2399,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 +3410,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;
   }
   /**
    * Собирает перебор страниц.
@@ -4089,49 +4275,6 @@ var PlatformResource = class extends BaseResource {
     });
   }
 };
-var TelemetryResource = class extends BaseResource {
-  /**
-   * Отправляет время просмотра постов.
-   *
-   * @experimental Имена полей на проводе сжаты (`ai`, `v`, `s`), и их соответствие
-   * смыслу **не проверено** на реальных запросах. Может измениться без предупреждения.
-   */
-  dwell(entries, options = {}) {
-    return this.http.request({
-      method: "POST",
-      path: "/api/v1/i",
-      body: {
-        items: entries.map((entry) => ({
-          ai: entry.postId,
-          v: entry.duration,
-          ...entry.vs ? { s: entry.vs } : {}
-        }))
-      },
-      ...this.requestOptions(options)
-    });
-  }
-  /**
-   * Отправляет события взаимодействия с контентом.
-   *
-   * @experimental См. предупреждение у {@link TelemetryResource}.
-   */
-  interaction(entries, options = {}) {
-    return this.http.request({
-      method: "POST",
-      path: "/api/v1/x",
-      body: {
-        items: entries.map((entry) => ({
-          t: entry.type,
-          ...entry.value !== void 0 ? { v: entry.value } : {},
-          ...entry.postId ? { ai: entry.postId } : {},
-          ...entry.attachmentId ? { mi: entry.attachmentId } : {},
-          ...entry.vs ? { s: entry.vs } : {}
-        }))
-      },
-      ...this.requestOptions(options)
-    });
-  }
-};
 
 // src/resources/notifications.ts
 var READ_BATCH_SIZE = 20;
@@ -4621,6 +4764,70 @@ var PostsResource = class extends BaseResource {
   }
 };
 
+// src/resources/telemetry.ts
+var TelemetryResource = class extends BaseResource {
+  /** Идентификатор сессии телеметрии, общий для всех событий этого объекта. */
+  #sessionId;
+  /**
+   * Идентификатор сессии телеметрии (`sid`).
+   *
+   * Создаётся лениво при первом обращении и далее неизменен.
+   */
+  get sessionId() {
+    this.#sessionId ??= createDeviceId();
+    return this.#sessionId;
+  }
+  /**
+   * Отправляет события просмотра постов (`POST /api/v1/i`).
+   *
+   * @experimental См. предупреждение у {@link TelemetryResource}.
+   */
+  dwell(entries, options = {}) {
+    return this.http.request({
+      method: "POST",
+      path: "/api/v1/i",
+      body: {
+        sid: options.sid ?? this.sessionId,
+        e: entries.map((entry) => ({
+          md: entry.durationMs ?? entry.exitAt - entry.enterAt,
+          et: entry.enterAt,
+          xt: entry.exitAt,
+          r: entry.reason,
+          v: entry.vs,
+          ...entry.sourceContext !== void 0 ? { sc: entry.sourceContext } : {},
+          ...entry.source !== void 0 ? { s: entry.source } : {},
+          ...entry.repeat ? { b: 1 } : {}
+        }))
+      },
+      ...this.requestOptions(options)
+    });
+  }
+  /**
+   * Отправляет события взаимодействия с контентом (`POST /api/v1/x`).
+   *
+   * @experimental См. предупреждение у {@link TelemetryResource}.
+   */
+  interaction(entries, options = {}) {
+    return this.http.request({
+      method: "POST",
+      path: "/api/v1/x",
+      body: {
+        sid: options.sid ?? this.sessionId,
+        e: entries.map((entry) => ({
+          t: entry.type,
+          v: entry.vs,
+          ai: entry.postId,
+          ...entry.mediaIndex !== void 0 ? { mi: entry.mediaIndex } : {},
+          ...entry.source !== void 0 ? { s: entry.source } : {},
+          ...entry.positionMs !== void 0 ? { pm: Math.round(entry.positionMs) } : {},
+          ...entry.durationMs !== void 0 ? { dm: Math.round(entry.durationMs) } : {}
+        }))
+      },
+      ...this.requestOptions(options)
+    });
+  }
+};
+
 // src/resources/users.ts
 var UsersResource = class extends BaseResource {
   /** Загружает свой профиль — с подпиской и признаком подтверждённого телефона. */
@@ -4909,6 +5116,7 @@ var ItdClient = class {
   #authManager;
   #jar;
   #queue;
+  #plugins = new PluginRegistry();
   /** Авторизация, сессии и пароли. */
   auth;
   /** Профили, подписки, блокировки, приватность. */
@@ -4945,6 +5153,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 +5199,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 +5446,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, AccessType, AttachmentType, CommentSort, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_USER_AGENT, DEVICE_ID_HEADER, DetectedRuntime, FeedTab, IMAGE_MIME_TYPES, InteractionType, 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, ViewReason, ViewSource, 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-CG4SERVM.js.map
+//# sourceMappingURL=chunk-CG4SERVM.js.map