itd-api 0.0.4 → 0.0.5

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`.
+
 ---
 
 ## Публикация
@@ -361,8 +396,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 +406,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`).

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

@@ -1554,7 +1554,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 +1696,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.5";
 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) {
@@ -4475,7 +4475,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 +4499,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 +4742,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 +4809,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 +4874,9 @@ var UsersResource = class extends BaseResource {
    * Имена полей перечислены с запасом: списки подписчиков и заблокированных приходят
    * под `users`, но альтернативное имя ничего не стоит и спасает, если эндпоинт назовёт
    * список по-своему.
+   *
+   * `page` уходит в запрос, хотя сервер его сейчас не читает (см. {@link followers}):
+   * когда пагинацию починят, работать начнёт само.
    */
   async #loadUserPage(path, params, state) {
     const body = await this.http.request({
@@ -5190,5 +5217,5 @@ function toDate(value) {
 }
 
 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
+//# sourceMappingURL=chunk-RUPF4X5L.js.map
+//# sourceMappingURL=chunk-RUPF4X5L.js.map