itd-api 0.0.2 → 0.0.4

package/dist/{index-RzyK1gKg.d.ts → index-olL_q_yu.d.ts}

@@ -198,8 +198,15 @@ declare const ItdErrorCode: Readonly<{
     readonly BUSINESS_RULE_VIOLATION: "BUSINESS_RULE_VIOLATION";
     readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
     readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    /** Сервер отвечает так на `404`, `ENTITY_NOT_FOUND` в этом случае не приходит. */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** На практике не приходит: вместо него сервер шлёт `TURNSTILE_VERIFICATION_FAILED`. */
     readonly CAPTCHA_FAILED: "CAPTCHA_FAILED";
+    /** Капча не пройдена: токен Turnstile недействителен, просрочен или уже использован. */
+    readonly TURNSTILE_VERIFICATION_FAILED: "TURNSTILE_VERIFICATION_FAILED";
     readonly OTP_INVALID: "OTP_INVALID";
+    /** `flowToken` неизвестен или просрочен — поток подтверждения нужно начинать заново. */
+    readonly INVALID_FLOW_TOKEN: "INVALID_FLOW_TOKEN";
     readonly ACCOUNT_DEACTIVATED: "ACCOUNT_DEACTIVATED";
     readonly ACCOUNT_EMAIL_DOMAIN_NOT_ALLOWED: "ACCOUNT_EMAIL_DOMAIN_NOT_ALLOWED";
     readonly ACCOUNT_INVALID_CREDENTIALS: "ACCOUNT_INVALID_CREDENTIALS";
@@ -208,6 +215,10 @@ declare const ItdErrorCode: Readonly<{
     readonly SESSION_EXPIRED: "SESSION_EXPIRED";
     readonly SESSION_REVOKED: "SESSION_REVOKED";
     readonly SESSION_INVALID_REFRESH_TOKEN: "SESSION_INVALID_REFRESH_TOKEN";
+    /** Запрос обновления пришёл без cookie `refresh_token` — продлевать нечего. */
+    readonly REFRESH_TOKEN_MISSING: "REFRESH_TOKEN_MISSING";
+    /** Cookie `refresh_token` есть, но сессии за ней уже нет: отозвана или истекла. */
+    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
     readonly MISSING_FLOW_TOKEN: "MISSING_FLOW_TOKEN";
     readonly PROFILE_USERNAME_TAKEN: "PROFILE_USERNAME_TAKEN";
     readonly PROFILE_RESTRICTION_ACTIVE: "PROFILE_RESTRICTION_ACTIVE";
@@ -1064,7 +1075,23 @@ type ReportInput = BuilderInput<CreateReportInput, ReportBuilder>;
  * - `server` — cookie ведёт встроенный jar, заголовок `Cookie` подставляется вручную;
  * - `auto` — определяется по среде исполнения (значение по умолчанию).
  */
-type RuntimeMode = 'auto' | 'browser' | 'server';
+declare const RuntimeMode: Readonly<{
+    /** Определяется по среде исполнения. Значение по умолчанию. */
+    readonly Auto: "auto";
+    /** Cookie ведёт браузер, запросы уходят с `credentials: 'include'`. */
+    readonly Browser: "browser";
+    /** Cookie ведёт встроенный jar, заголовок `Cookie` подставляется вручную. */
+    readonly Server: "server";
+}>;
+type RuntimeMode = (typeof RuntimeMode)[keyof typeof RuntimeMode];
+/** Распознанная среда исполнения. */
+declare const DetectedRuntime: Readonly<{
+    readonly Browser: "browser";
+    /** Есть `window`, но нет `document`; cookie ведёт нативный сетевой слой. */
+    readonly ReactNative: "react-native";
+    readonly Server: "server";
+}>;
+type DetectedRuntime = (typeof DetectedRuntime)[keyof typeof DetectedRuntime];
 
 /**
  * Сохранённая сессия.
@@ -1084,6 +1111,14 @@ interface ItdSession {
     refreshToken?: string | undefined;
     /** Сырые cookie в форме `имя=значение`, привязанные к origin API. */
     cookies?: string[] | undefined;
+    /**
+     * Идентификатор устройства для заголовка `X-Device-Id`.
+     *
+     * Сервер различает по нему записи в списке сессий, поэтому значение должно пережить
+     * перезапуск процесса — иначе каждый старт бота порождает новую сессию. Библиотека
+     * заводит его сама при первом запросе и хранит здесь.
+     */
+    deviceId?: string | undefined;
     /** Когда сессия получена, мс с начала эпохи. Нужно для диагностики. */
     obtainedAt?: number | undefined;
 }
@@ -1159,27 +1194,44 @@ type QueryValue = string | number | boolean | null | undefined | readonly (strin
 /** Параметры строки запроса. */
 type QueryParams = Record<string, QueryValue>;
 
+/**
+ * Вход по логину и паролю.
+ *
+ * Вход требует токен капчи Cloudflare Turnstile, поэтому полностью автоматическим он быть
+ * не может: капчу должен решить кто-то снаружи. Токен одноразовый и живёт несколько минут,
+ * так что долгоживущему клиенту нужен `getTurnstileToken` — он спрашивается заново перед
+ * каждой попыткой входа. Одиночный `turnstileToken` годится для разового скрипта.
+ */
+interface CredentialsAuth {
+    email: string;
+    password: string;
+    /** Разовый токен капчи. Для повторного входа после истечения сессии не подойдёт. */
+    turnstileToken?: string | undefined;
+    /** Источник свежего токена капчи. Спрашивается перед каждым входом. */
+    getTurnstileToken?: (() => string | Promise<string>) | undefined;
+}
 /**
  * Как клиент получает доступ к API.
  *
- * Поддерживаются четыре формы — от разового вызова с готовым токеном до полноценной
- * сессии, которую библиотека заводит и продлевает сама.
+ * Четыре формы — от разового вызова с готовым токеном до полноценной сессии, которую
+ * библиотека заводит и продлевает сама.
+ *
+ * Опция необязательна: если {@link ItdClientOptions.storage} уже содержит сессию, доступ
+ * берётся оттуда. Когда заданы обе, хранилище главнее — оно отражает текущее состояние
+ * сессии, — а недостающие поля берутся отсюда.
  *
  * @example
  * ```ts
  * new ItdClient({ auth: '<accessToken>' });                    // разовый вызов
  * new ItdClient({ auth: { accessToken, refreshToken } });      // восстановить сессию
- * new ItdClient({ auth: { email, password } });                // залогиниться самому
+ * new ItdClient({ auth: { email, password, getTurnstileToken } });  // залогиниться самому
  * new ItdClient({ auth: { getToken: () => vault.read() } });   // токен из внешнего источника
  * ```
  */
 type AuthInput = string | {
     accessToken: string;
     refreshToken?: string | undefined;
-} | {
-    email: string;
-    password: string;
-} | {
+} | CredentialsAuth | {
     getToken: () => string | null | Promise<string | null>;
 };
 /** Куда библиотека пишет отладочные сообщения. Совместим с `console`. */
@@ -1326,6 +1378,22 @@ interface ItdClientOptions {
     logger?: Logger | boolean | undefined;
     /** Заголовки, добавляемые ко всем запросам, — например `User-Agent` для бота. */
     headers?: Record<string, string> | undefined;
+    /**
+     * Значение заголовка `X-Device-Id`, который уходит с каждым запросом.
+     *
+     * Сервер различает по нему записи в списке сессий, поэтому значение должно быть стабильным.
+     * Если не задать, библиотека заведёт идентификатор сама и сохранит его в {@link ItdSession},
+     * так что при постоянном хранилище он переживёт перезапуск процесса.
+     */
+    deviceId?: string | undefined;
+    /**
+     * Значение заголовка `User-Agent`. `false` — не отправлять его вовсе.
+     *
+     * По умолчанию `Mozilla/5.0 (compatible; itd-api/<версия>; …)`: `fetch` в Node не шлёт
+     * `User-Agent` сам, а сайт стоит за DDoS-Guard, который такие запросы может не пропустить.
+     * В браузере опция не действует — там заголовок менять запрещено.
+     */
+    userAgent?: string | false | undefined;
     /** Как обращаться с cookie. По умолчанию определяется по среде исполнения. */
     mode?: RuntimeMode | undefined;
 }
@@ -1352,6 +1420,14 @@ interface RawRequestOptions extends RequestOptions {
     skipAuth?: boolean | undefined;
     /** Не пытаться обновить токен при `401` — используется самими эндпоинтами авторизации. */
     skipAuthRefresh?: boolean | undefined;
+    /**
+     * Выполнить запрос мимо очереди.
+     *
+     * Нужно запросам, которые слой авторизации делает **изнутри** другого запроса: продление
+     * токена и отложенный вход. Такой запрос обязан стартовать, пока исходный держит место
+     * в очереди и ждёт его результата, — иначе оба ждут друг друга и не завершатся никогда.
+     */
+    skipQueue?: boolean | undefined;
     /** Вернуть тело ответа без снятия обёртки `{ data: … }`. */
     raw?: boolean | undefined;
 }
@@ -1360,6 +1436,21 @@ interface RawRequestOptions extends RequestOptions {
 declare const DEFAULT_BASE_URL = "https://xn--d1ah4a.com";
 /** Таймаут запроса по умолчанию. Столько же использует официальный клиент итд.com. */
 declare const DEFAULT_TIMEOUT = 30000;
+/**
+ * Версия библиотеки — попадает в `User-Agent`.
+ */
+declare const LIBRARY_VERSION = "0.0.4";
+/**
+ * `User-Agent` по умолчанию.
+ *
+ * Сайт стоит за DDoS-Guard, и запросы вовсе без `User-Agent` (так делает `fetch` в Node)
+ * имеют шанс не пройти фильтр. Префикс `Mozilla/5.0` — дань традиции таких фильтров,
+ * дальше идёт честное имя библиотеки: подделываться под браузер она не должна.
+ *
+ * В браузере заголовок не выставляется — `User-Agent` там запрещён к изменению, и среда
+ * молча его игнорирует.
+ */
+declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; itd-api/0.0.4; +https://github.com/KiowDev/itd-api)";
 /**
  * Настройки повторов со всеми значениями по умолчанию.
  *
@@ -1395,6 +1486,10 @@ interface ResolvedConfig {
     hooks: ClientHooks;
     logger: Logger | undefined;
     headers: Record<string, string>;
+    /** Значение заголовка `X-Device-Id`, если задано вручную. Иначе заводится само. */
+    deviceId: string | undefined;
+    /** Значение заголовка `User-Agent`. `undefined` — заголовок не выставляется. */
+    userAgent: string | undefined;
     mode: RuntimeMode;
     /** Вести ли собственный cookie-jar (вне браузера и React Native). */
     useCookieJar: boolean;
@@ -1402,6 +1497,18 @@ interface ResolvedConfig {
     sendCredentials: boolean;
 }
 
+/** Имя cookie-флага «есть refresh-сессия». Ставится сайтом итд.com рядом с refresh-токеном. */
+declare const AUTH_FLAG_COOKIE = "is_auth";
+/**
+ * Имя cookie с refresh-токеном.
+ *
+ * `POST /api/v1/auth/refresh` читает токен **только отсюда** — тело запроса сервер игнорирует.
+ * Cookie помечена `HttpOnly`, поэтому в браузере её не прочитать и не выставить; вне браузера
+ * она проходит через jar, и туда же кладётся токен, переданный строкой.
+ */
+declare const REFRESH_COOKIE = "refresh_token";
+/** Путь, которым сервер ограничивает {@link REFRESH_COOKIE}. */
+declare const REFRESH_COOKIE_PATH = "/api/v1/auth";
 /**
  * Минимальное хранилище cookie для сред без своего.
  *
@@ -1422,6 +1529,13 @@ declare class CookieJar {
      * внутри `Expires=Wed, 09 Jun 2027 …`. Разделением занимается `set-cookie-parser`.
      */
     setFromResponse(url: string, response: Response): void;
+    /**
+     * Кладёт cookie напрямую, минуя `Set-Cookie`.
+     *
+     * Нужно ровно в одном случае: пользователь передал refresh-токен строкой, а сервер читает
+     * его только из cookie. Значение не кодируется — оно уходит в заголовок как есть.
+     */
+    set(url: string, name: string, value: string, path?: string): void;
     /** Сохраняет cookie из готовых строк `Set-Cookie`. */
     setFromStrings(url: string, setCookieStrings: string[]): void;
     /**
@@ -1430,6 +1544,15 @@ declare class CookieJar {
      * @returns строка вида `a=1; b=2` либо `undefined`, если подходящих cookie нет
      */
     getHeader(url: string): string | undefined;
+    /**
+     * Значение действующей cookie.
+     *
+     * Нужно, чтобы забрать обновлённый refresh-токен: сервер ротирует его при каждом
+     * продлении сессии, и сохранять надо именно новое значение.
+     *
+     * @param url если указан, учитываются origin, путь и флаг `Secure`
+     */
+    getValue(name: string, url?: string): string | undefined;
     /**
      * Есть ли действующая cookie с таким именем.
      *
@@ -1504,6 +1627,13 @@ interface HttpCollaborators {
      * Повтор выполняется ровно один раз.
      */
     onUnauthorized?(): Promise<boolean>;
+    /**
+     * Идентификатор устройства для заголовка `X-Device-Id`.
+     *
+     * Отдельно от {@link getAuthHeaders}, потому что нужен и на анонимных запросах —
+     * например на `sign-in`, где заголовка авторизации ещё нет.
+     */
+    getDeviceId?(): Promise<string> | string;
     /** Значение заголовка `Cookie` для указанного URL. */
     getCookieHeader?(url: string): string | undefined;
     /** Приём `Set-Cookie` из ответа. */
@@ -1555,6 +1685,28 @@ declare class HttpClient {
     request<T = unknown>(options: RawRequestOptions): Promise<T>;
 }
 
+/** Пути авторизации. Вынесены, чтобы не расходиться между модулями. */
+declare const AUTH_PATHS: {
+    readonly signIn: "/api/v1/auth/sign-in";
+    readonly refresh: "/api/v1/auth/refresh";
+};
+/**
+ * Публичный ключ Cloudflare Turnstile платформы итд.com.
+ *
+ * Нужен, чтобы отрисовать виджет капчи и получить токен для `signIn`, `signUp`
+ * и `forgotPassword`.
+ *
+ * @example
+ * ```ts
+ * turnstile.render('#captcha', {
+ *   sitekey: TURNSTILE_SITE_KEY,
+ *   callback: (turnstileToken) => itd.auth.signIn({ email, password, turnstileToken }),
+ * });
+ * ```
+ */
+declare const TURNSTILE_SITE_KEY = "0x4AAAAAACHhxczw6fJGwPBg";
+/** Заголовок с идентификатором устройства. Сервер связывает с ним запись в списке сессий. */
+declare const DEVICE_ID_HEADER = "X-Device-Id";
 /** События слоя авторизации. */
 interface AuthEvents {
     /** Токен получен или обновлён. */
@@ -1590,13 +1742,24 @@ declare class AuthManager {
     /**
      * Есть ли признак живой refresh-сессии.
      *
-     * Сайт итд.com ставит рядом с refresh-токеном незакрытую cookie `is_auth` — по ней клиент
-     * понимает, что обновление вообще имеет смысл, и не дёргает API у анонимов.
+     * Рядом с refresh-токеном сервер ставит незакрытую cookie `is_auth` — по ней видно,
+     * что продлевать сессию вообще есть смысл, и API не дёргается у анонимов.
      * В браузере cookie ведёт сама среда, поэтому там ответ всегда `true`.
+     *
+     * Асинхронный, потому что признак может лежать в {@link TokenStorage}: до чтения оттуда
+     * ответ был бы `false` даже при полностью рабочей сохранённой сессии.
      */
-    hasRefreshSession(): boolean;
+    hasRefreshSession(): Promise<boolean>;
     /** Заголовки авторизации для очередного запроса. Пустой объект, если токена нет. */
     getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Идентификатор устройства для заголовка `X-Device-Id`.
+     *
+     * Заводится один раз и сохраняется в сессии, чтобы пережить перезапуск процесса:
+     * сервер связывает с ним запись в списке сессий, и плавающее значение плодило бы
+     * по новой сессии на каждый старт.
+     */
+    getDeviceId(): Promise<string>;
     /**
      * Текущий токен доступа.
      *
@@ -1624,7 +1787,12 @@ declare class AuthManager {
     getSession(): Promise<ItdSession | null>;
     /** Заменяет сессию целиком. */
     setSession(session: ItdSession): Promise<void>;
-    /** Забывает сессию и cookie. Сетевой запрос не выполняется. */
+    /**
+     * Забывает сессию и cookie. Сетевой запрос не выполняется.
+     *
+     * Идентификатор устройства выход переживает: иначе каждая пара «выход — вход» плодила бы
+     * новую запись в списке сессий.
+     */
     clear(): Promise<void>;
 }
 
@@ -1748,6 +1916,10 @@ interface RealtimeTransport {
      */
     connect(context: TransportContext): Promise<void>;
 }
+/** Ошибка, по которой видно, что сервер отверг авторизацию потока. */
+declare class UnauthorizedStreamError extends Error {
+    constructor();
+}
 
 /** События потока уведомлений. */
 interface RealtimeEvents {
@@ -1795,7 +1967,15 @@ interface RealtimeEvents {
     };
 }
 /** Способ получения событий. */
-type RealtimeTransportKind = 'auto' | 'sse' | 'poll';
+declare const RealtimeTransportKind: Readonly<{
+    /** Поток событий, если среда умеет читать тело по частям, иначе опрос. */
+    readonly Auto: "auto";
+    /** Поток `text/event-stream`. */
+    readonly Sse: "sse";
+    /** Периодический опрос REST. */
+    readonly Poll: "poll";
+}>;
+type RealtimeTransportKind = (typeof RealtimeTransportKind)[keyof typeof RealtimeTransportKind];
 /** Настройки потока уведомлений. */
 interface RealtimeOptions extends ReconnectOptions {
     /**
@@ -1920,7 +2100,15 @@ interface Page<T> {
     raw: unknown;
 }
 /** Схема пагинации эндпоинта. */
-type PaginationMode = 'cursor' | 'page' | 'offset';
+declare const PaginationMode: Readonly<{
+    /** Следующая страница запрашивается непрозрачным курсором. */
+    readonly Cursor: "cursor";
+    /** Следующая страница запрашивается номером. */
+    readonly Page: "page";
+    /** Следующая страница запрашивается смещением от начала списка. */
+    readonly Offset: "offset";
+}>;
+type PaginationMode = (typeof PaginationMode)[keyof typeof PaginationMode];
 /** Позиция, с которой запрашивается очередная страница. */
 interface PageState {
     cursor?: string | undefined;
@@ -1932,6 +2120,13 @@ interface PaginatorOptions<T> {
     mode: PaginationMode;
     /** Загружает одну страницу для указанной позиции. */
     load: (state: PageState) => Promise<Page<T>>;
+    /**
+     * С какой позиции начать. По умолчанию с начала списка.
+     *
+     * Нужно, чтобы перебор можно было продолжить с сохранённого курсора, а не только
+     * начать заново.
+     */
+    start?: PageState | undefined;
     /**
      * Предохранитель от бесконечного перебора. По умолчанию 1000.
      *
@@ -1948,6 +2143,10 @@ interface PaginatorOptions<T> {
  * Скрывает различия трёх схем пагинации: перебор элементов, страниц и сбор в массив
  * выглядят одинаково независимо от эндпоинта.
  *
+ * **Одноразовый.** Позиция хранится внутри, поэтому повторный перебор того же объекта
+ * ничего не вернёт: он продолжится с места, где закончился прошлый. Нужен второй проход —
+ * возьмите новый перебор у того же метода ресурса.
+ *
  * @example Перебор элементов
  * ```ts
  * for await (const post of itd.posts.iterate({ tab: 'following' })) {
@@ -2004,9 +2203,11 @@ declare class BaseResource {
      *
      * @param mode схема пагинации эндпоинта
      * @param load загружает одну страницу для указанной позиции
+     * @param options `maxPages` и `signal`, а также `start` — позиция, с которой продолжить
      */
     protected paginate<T>(mode: PaginationMode, load: (state: PageState) => Promise<Page<T>>, options?: RequestOptions & {
         maxPages?: number;
+        start?: PageState;
     }): Paginator<T>;
 }
 
@@ -2015,6 +2216,45 @@ interface Credentials {
     email: string;
     password: string;
 }
+/**
+ * Учётные данные вместе с токеном капчи.
+ *
+ * `turnstileToken` обязателен: без него сервер отвечает `VALIDATION_ERROR`, с недействительным —
+ * `TURNSTILE_VERIFICATION_FAILED`. Токен даёт виджет Cloudflare Turnstile с ключом
+ * {@link TURNSTILE_SITE_KEY}; он одноразовый и живёт несколько минут.
+ */
+interface CaptchaCredentials extends Credentials {
+    turnstileToken: string;
+}
+/** Запрос письма для сброса пароля. Капча обязательна, как и при входе. */
+interface ForgotPasswordInput {
+    email: string;
+    turnstileToken: string;
+}
+/**
+ * Установка нового пароля.
+ *
+ * Сброс идёт тем же потоком с кодом, что и вход: {@link AuthResource.forgotPassword} выдаёт
+ * `flowToken`, письмо приносит `otp`, и всё это вместе с новым паролем уходит сюда.
+ */
+interface ResetPasswordInput {
+    email: string;
+    otp: string;
+    flowToken: string;
+    newPassword: string;
+}
+/** Провайдер внешнего входа. */
+declare const OAuthProvider: Readonly<{
+    readonly Yandex: "yandex";
+    readonly Google: "google";
+}>;
+type OAuthProvider = (typeof OAuthProvider)[keyof typeof OAuthProvider];
+/** Чем закончился вход: сразу токеном или запросом кода подтверждения. */
+declare const SignInStatus: Readonly<{
+    readonly Authenticated: "authenticated";
+    readonly OtpRequired: "otp_required";
+}>;
+type SignInStatus = (typeof SignInStatus)[keyof typeof SignInStatus];
 /**
  * Результат входа.
  *
@@ -2022,14 +2262,12 @@ interface Credentials {
  * объединение делает оба случая явными.
  */
 type SignInResult = {
-    status: 'authenticated';
+    status: typeof SignInStatus.Authenticated;
     accessToken: string;
 } | {
-    status: 'otp_required';
+    status: typeof SignInStatus.OtpRequired;
     flowToken: string | undefined;
 };
-/** Провайдер внешнего входа. */
-type OAuthProvider = 'yandex' | 'google';
 /**
  * Авторизация, сессии и пароли.
  *
@@ -2045,7 +2283,7 @@ declare class AuthResource extends BaseResource {
      *
      * @returns `flowToken`, который нужно передать в {@link verifyOtp}
      */
-    signUp(credentials: Credentials, options?: RequestOptions): Promise<string>;
+    signUp(credentials: CaptchaCredentials, options?: RequestOptions): Promise<string>;
     /**
      * Выполняет вход.
      *
@@ -2053,8 +2291,10 @@ declare class AuthResource extends BaseResource {
      * тогда продолжайте через {@link verifyOtp} либо воспользуйтесь {@link signInWithOtp}.
      *
      * При успешном входе токен сохраняется в клиенте автоматически.
+     *
+     * @param credentials email, пароль и обязательный токен капчи — см. {@link CaptchaCredentials}
      */
-    signIn(credentials: Credentials, options?: RequestOptions): Promise<SignInResult>;
+    signIn(credentials: CaptchaCredentials, options?: RequestOptions): Promise<SignInResult>;
     /**
      * Подтверждает вход кодом из письма.
      *
@@ -2087,7 +2327,7 @@ declare class AuthResource extends BaseResource {
      * });
      * ```
      */
-    signInWithOtp(input: Credentials & {
+    signInWithOtp(input: CaptchaCredentials & {
         getOtp: () => string | Promise<string>;
     }, options?: RequestOptions): Promise<string>;
     /**
@@ -2100,25 +2340,71 @@ declare class AuthResource extends BaseResource {
     /**
      * Есть ли признак живой сессии обновления.
      *
-     * Проверяет cookie `is_auth`, которую сервер ставит рядом с refresh-токеном. Позволяет
-     * не дёргать API у неавторизованного пользователя. В браузере всегда `true`:
-     * cookie ведёт сама среда, и прочитать её из JS нельзя.
+     * Проверяет cookie `is_auth`, которую сервер ставит рядом с refresh-токеном, а также
+     * refresh-токен, переданный строкой. Позволяет не дёргать API у неавторизованного
+     * пользователя. В браузере всегда `true`: cookie ведёт сама среда, и прочитать её
+     * из JS нельзя.
+     *
+     * Читает {@link TokenStorage}, поэтому результат верен и до первого запроса.
+     *
+     * @example
+     * ```ts
+     * if (await itd.auth.hasRefreshSession()) await itd.auth.refresh();
+     * else redirectToLogin();
+     * ```
      */
-    hasRefreshSession(): boolean;
+    hasRefreshSession(): Promise<boolean>;
     /** Завершает текущую сессию на сервере и очищает локальную. */
     logout(options?: RequestOptions): Promise<void>;
-    /** Завершает все сессии пользователя и очищает локальную. */
+    /**
+     * Завершает все сессии пользователя и очищает локальную.
+     *
+     * Собран из двух запросов, потому что единого эндпоинта на сервере нет:
+     * `POST /api/v1/auth/logout-all` отвечает `404`. Сначала отзываются все прочие сессии
+     * (`DELETE /api/v1/auth/sessions`), затем завершается текущая — в обратном порядке
+     * отзывать было бы уже нечем.
+     */
     logoutAll(options?: RequestOptions): Promise<void>;
     /** Забывает сессию локально, не обращаясь к серверу. */
     signOut(): Promise<void>;
-    /** Запрашивает письмо для сброса пароля. */
-    forgotPassword(email: string, options?: RequestOptions): Promise<void>;
-    /** Устанавливает новый пароль по токену из письма. */
-    resetPassword(input: {
-        token: string;
+    /**
+     * Запрашивает письмо с кодом для сброса пароля.
+     *
+     * @returns `flowToken`, который нужно передать в {@link resetPassword}
+     */
+    forgotPassword(input: ForgotPasswordInput, options?: RequestOptions): Promise<string>;
+    /**
+     * Устанавливает новый пароль по коду из письма.
+     *
+     * Сервер ждёт все четыре поля сразу — `email`, `otp`, `flowToken` и `newPassword`;
+     * при нехватке любого отвечает `422`.
+     */
+    resetPassword(input: ResetPasswordInput, options?: RequestOptions): Promise<void>;
+    /**
+     * Полный сброс пароля с кодом из письма.
+     *
+     * Тот же приём, что и {@link signInWithOtp}: код запрашивается функцией `getOtp`,
+     * остальное библиотека делает сама.
+     *
+     * @example
+     * ```ts
+     * await itd.auth.resetPasswordWithOtp({
+     *   email,
+     *   turnstileToken,
+     *   newPassword,
+     *   getOtp: () => rl.question('Код из письма: '),
+     * });
+     * ```
+     */
+    resetPasswordWithOtp(input: ForgotPasswordInput & {
         newPassword: string;
+        getOtp: () => string | Promise<string>;
     }, options?: RequestOptions): Promise<void>;
-    /** Меняет пароль. Требует действующей сессии обновления. */
+    /**
+     * Меняет пароль. Требует действующей сессии.
+     *
+     * При неверном текущем пароле сервер отвечает `ACCOUNT_CURRENT_PASSWORD_INCORRECT`.
+     */
     changePassword(input: {
         oldPassword: string;
         newPassword: string;
@@ -2268,8 +2554,6 @@ declare class FilesResource extends BaseResource {
     get(fileId: string, options?: RequestOptions): Promise<unknown>;
     /** Удаляет загруженный файл. */
     remove(fileId: string, options?: RequestOptions): Promise<void>;
-    /** Приводит любой поддерживаемый вход к `Blob` с именем и проверенным типом. */
-    private prepare;
 }
 
 /** Параметры запроса постов по хэштегу. */
@@ -2461,6 +2745,7 @@ type UpdateNotificationSettingsInput = Partial<NotificationSettings>;
  * объекты отсюда и из потока событий можно складывать в один список.
  */
 declare class NotificationsResource extends BaseResource {
+    #private;
     /**
      * Загружает страницу уведомлений.
      *
@@ -2734,10 +3019,7 @@ declare class UsersResource extends BaseResource {
     /** Загружает рекомендации, на кого подписаться. */
     whoToFollow(options?: RequestOptions): Promise<UserSummary[]>;
     /** Загружает рейтинг кланов. */
-    topClans(options?: RequestOptions): Promise<{
-        avatar: string;
-        memberCount: number;
-    }[]>;
+    topClans(options?: RequestOptions): Promise<Clan[]>;
     /**
      * Подписывается на пользователя.
      *
@@ -2808,7 +3090,10 @@ declare class UsersResource extends BaseResource {
  * import { FileTokenStorage } from 'itd-api/node';
  *
  * const itd = new ItdClient({
- *   auth: { email, password },
+ *   // `auth` не обязателен: когда хранилище уже содержит сессию, токен берётся оттуда,
+ *   // а истёкший продлевается сам. Здесь он нужен на первый запуск.
+ *   // Вход по паролю требует токена капчи — см. AuthInput и TURNSTILE_SITE_KEY.
+ *   auth: { email, password, getTurnstileToken },
  *   storage: new FileTokenStorage('./.itd-session.json'),
  *   rateLimit: { concurrency: 4, rps: 8 },
  * });
@@ -2926,8 +3211,44 @@ declare function createClient(options?: ItdClientOptions): ItdClient;
 
 /** Бренд, по которому ошибки библиотеки распознаются надёжнее, чем через `instanceof`. */
 declare const ITD_ERROR: unique symbol;
-/** Категория ошибки. Определяет, какие поля у неё есть. */
-type ItdErrorKind = 'api' | 'network' | 'timeout' | 'abort' | 'config';
+/**
+ * Категория ошибки. Определяет, какие поля у неё есть.
+ *
+ * Значение, а не только тип: категорию нужно с чем-то сравнивать в рантайме.
+ */
+declare const ItdErrorKind: Readonly<{
+    /** Сервер ответил статусом ≥ 400. */
+    readonly Api: "api";
+    /** Запрос не дошёл до сервера. */
+    readonly Network: "network";
+    /** Истёк таймаут запроса. */
+    readonly Timeout: "timeout";
+    /** Запрос отменён через `AbortSignal`. */
+    readonly Abort: "abort";
+    /** Некорректная конфигурация или аргументы — обнаружено до обращения к сети. */
+    readonly Config: "config";
+}>;
+type ItdErrorKind = (typeof ItdErrorKind)[keyof typeof ItdErrorKind];
+/**
+ * Разновидность ошибки API — то же, что класс ошибки, но в виде данных.
+ *
+ * Существует потому, что `instanceof` подводит, когда в дереве зависимостей оказались
+ * две копии пакета или смешаны сборки ESM и CJS: классы тогда разные, хотя ошибка та же.
+ * Проверки {@link isItdValidationError} и соседние опираются на это поле, а не на класс.
+ */
+declare const ItdApiErrorKind: Readonly<{
+    /** Ни одна из специализаций не подошла. */
+    readonly Generic: "generic";
+    readonly Validation: "validation";
+    readonly Auth: "auth";
+    readonly Forbidden: "forbidden";
+    readonly NotFound: "not_found";
+    readonly Conflict: "conflict";
+    readonly RateLimit: "rate_limit";
+    readonly PhoneVerification: "phone_verification";
+    readonly Server: "server";
+}>;
+type ItdApiErrorKind = (typeof ItdApiErrorKind)[keyof typeof ItdApiErrorKind];
 /** Ошибки по полям формы: `{ email: ['уже занят'] }`. */
 type ItdFieldErrors = Record<string, string[]>;
 /**
@@ -3004,6 +3325,13 @@ interface ItdApiErrorInit {
  * ```
  */
 declare class ItdApiError extends ItdError {
+    /**
+     * Разновидность ошибки: та же информация, что и класс, но пригодная для сравнения.
+     *
+     * Позволяет разбирать ошибку через `switch`, а проверкам вроде {@link isItdAuthError} —
+     * работать даже когда в проекте оказались две копии библиотеки.
+     */
+    readonly apiKind: ItdApiErrorKind;
     /** HTTP-статус ответа. */
     readonly status: number;
     /** Строковый код ошибки, например `VALIDATION_ERROR`. */
@@ -3034,7 +3362,10 @@ declare class ItdApiError extends ItdError {
     readonly rateLimit: number | undefined;
     /** Сколько запросов осталось в окне — заголовок `x-ratelimit-remaining`. */
     readonly rateLimitRemaining: number | undefined;
-    constructor(init: ItdApiErrorInit);
+    /**
+     * @param apiKind разновидность; подставляется подклассами, снаружи задавать не нужно
+     */
+    constructor(init: ItdApiErrorInit, apiKind?: ItdApiErrorKind);
     /**
      * Проверяет код ошибки. Удобнее, чем сравнивать строки вручную.
      *
@@ -3139,17 +3470,31 @@ declare function isItdApiError(value: unknown): value is ItdApiError;
 declare function isItdValidationError(value: unknown): value is ItdValidationError;
 /** Ошибка авторизации: истёкший или отозванный токен. */
 declare function isItdAuthError(value: unknown): value is ItdAuthError;
+/** Доступ запрещён либо действие ограничено настройками приватности. */
+declare function isItdForbiddenError(value: unknown): value is ItdForbiddenError;
+/** Сущность не найдена. */
+declare function isItdNotFoundError(value: unknown): value is ItdNotFoundError;
+/** Сущность уже существует. */
+declare function isItdConflictError(value: unknown): value is ItdConflictError;
 /** Превышен лимит запросов. */
 declare function isItdRateLimitError(value: unknown): value is ItdRateLimitError;
+/** Действие требует подтверждённого телефона. Ссылка — в `verificationUrl`. */
+declare function isItdPhoneVerificationError(value: unknown): value is ItdPhoneVerificationError;
+/** Ошибка на стороне сервера (`5xx`). */
+declare function isItdServerError(value: unknown): value is ItdServerError;
 
 /** Изображения, которые принимает `POST /api/files/upload`. */
-declare const IMAGE_MIME_TYPES: readonly string[];
+declare const IMAGE_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp", "image/avif", "image/heic", "image/heif"];
+type ImageMimeType = (typeof IMAGE_MIME_TYPES)[number];
 /** Видео, которые принимает `POST /api/files/upload`. */
-declare const VIDEO_MIME_TYPES: readonly string[];
+declare const VIDEO_MIME_TYPES: readonly ["video/mp4", "video/webm", "video/quicktime"];
+type VideoMimeType = (typeof VIDEO_MIME_TYPES)[number];
 /** Аудио для голосовых комментариев. */
-declare const AUDIO_MIME_TYPES: readonly string[];
+declare const AUDIO_MIME_TYPES: readonly ["audio/ogg"];
+type AudioMimeType = (typeof AUDIO_MIME_TYPES)[number];
 /** Все типы, которые принимает загрузка. */
-declare const ALLOWED_MIME_TYPES: readonly string[];
+declare const ALLOWED_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp", "image/avif", "image/heic", "image/heif", "video/mp4", "video/webm", "video/quicktime", "audio/ogg"];
+type AllowedMimeType = (typeof ALLOWED_MIME_TYPES)[number];
 
 /**
  * Собирает текст уведомления на русском.
@@ -3235,4 +3580,4 @@ interface SseTransportOptions {
     idleTimeout?: number;
 }
 
-export { ItdError as $, ALLOWED_MIME_TYPES as A, type BuilderInput as B, type ChangelogEntry as C, DEFAULT_BASE_URL as D, type DwellEntry as E, type FileReader as F, type ErrorContextHook as G, type FeedParams as H, type ItdSession as I, FeedTab as J, type FileInput as K, FilesResource as L, type FollowResult as M, type Hashtag as N, type HashtagPostsParams as O, HashtagsResource as P, IMAGE_MIME_TYPES as Q, type InteractionEntry as R, type IsoDate as S, type TokenStorage as T, ItdAbortError as U, ItdApiError as V, type ItdApiErrorInit as W, ItdAuthError as X, type ItdBuilder as Y, ItdConfigError as Z, ItdConflictError as _, ItdClient as a, type Report as a$, ItdErrorCode as a0, type ItdErrorKind as a1, type ItdFieldErrors as a2, ItdForbiddenError as a3, ItdNetworkError as a4, ItdNotFoundError as a5, ItdPhoneVerificationError as a6, ItdRateLimitError as a7, ItdRealtime as a8, ItdServerError as a9, type PinsResult as aA, PlatformResource as aB, type Poll as aC, PollBuilder as aD, type PollInput as aE, type PollOption as aF, type PollTransportOptions as aG, type Portal as aH, type Post as aI, PostBuilder as aJ, type PostInput as aK, type PostStats as aL, PostsResource as aM, type PrivacySettings as aN, type Profile as aO, type PublicProfile as aP, RECONNECT_BACKOFF as aQ, RECONNECT_JITTER as aR, type RateLimitOptions as aS, type RawRequestOptions as aT, type RealtimeEvents as aU, type RealtimeOptions as aV, RealtimeStatus as aW, type RealtimeTransport as aX, type RealtimeTransportKind as aY, type ReconnectOptions as aZ, type RepliesParams as a_, ItdTimeoutError as aa, ItdValidationError as ab, type LikeResult as ac, LikesVisibility as ad, type Listener as ae, LocalStorageTokenStorage as af, type Logger as ag, type Loose as ah, MAX_RECONNECT_ATTEMPTS as ai, MemoryTokenStorage as aj, type MyProfile as ak, NOTIFICATION_TYPE_ALIASES as al, type Notification as am, type NotificationEvent as an, type NotificationListParams as ao, type NotificationSettings as ap, NotificationType as aq, NotificationsResource as ar, type OAuthProvider as as, type Page as at, type PageState as au, type PaginationMode as av, Paginator as aw, type PaymentMethod as ax, type Pin as ay, type PinPostResult as az, type ItdClientOptions as b, ReportBuilder as b0, type ReportInput as b1, ReportReason as b2, ReportTargetType as b3, ReportsResource as b4, type RequestContext as b5, type RequestOptions as b6, type ResponseContext as b7, type RetryContext as b8, type RetryOptions as b9, VIDEO_MIME_TYPES as bA, VerificationResource as bB, type VerificationStatus as bC, WallAccess as bD, canonicalNotificationType as bE, comment as bF, createTokenStorage as bG, formatNotificationText as bH, isBuilder as bI, isItdApiError as bJ, isItdAuthError as bK, isItdError as bL, isItdRateLimitError as bM, isItdValidationError as bN, isKnownNotificationType as bO, isMyProfile as bP, normalizeNotification as bQ, poll as bR, post as bS, readNotificationEvent as bT, readUnreadCountEvent as bU, report as bV, resolveNotificationUrl as bW, toDate as bX, createClient as bY, type RuntimeMode as ba, STREAM_PATH as bb, SearchResource as bc, type SearchResult as bd, type Session as be, type SignInResult as bf, type Span as bg, type SseTransportOptions as bh, type Subscription as bi, SubscriptionResource as bj, type SubscriptionState as bk, TelemetryResource as bl, type TransportContext as bm, type TransportEvent as bn, type Unsubscribe as bo, type UpdateNotificationSettingsInput as bp, type UpdatePrivacyInput as bq, type UpdateProfileInput as br, type UploadOptions as bs, type UploadedFile as bt, type UserId as bu, type UserListParams as bv, type UserPostsParams as bw, type UserRef as bx, type UserSummary as by, UsersResource as bz, AUDIO_MIME_TYPES as c, type Actor as d, type Announcement as e, type AnnouncementButton as f, type Attachment as g, AttachmentType as h, type AuthInput as i, AuthResource as j, type Author as k, type Clan as l, type ClientHooks as m, type Comment as n, CommentBuilder as o, type CommentInput as p, type CommentReplyTo as q, CommentSort as r, type CommentsParams as s, CommentsResource as t, type CreateCommentInput as u, type CreatePollInput as v, type CreatePostInput as w, type CreateReportInput as x, type Credentials as y, DEFAULT_TIMEOUT as z };
+export { IMAGE_MIME_TYPES as $, ALLOWED_MIME_TYPES as A, type BuilderInput as B, type CaptchaCredentials as C, type CreatePollInput as D, type CreatePostInput as E, type FileReader as F, type CreateReportInput as G, type Credentials as H, type ItdSession as I, type CredentialsAuth as J, DEFAULT_BASE_URL as K, DEFAULT_TIMEOUT as L, DEFAULT_USER_AGENT as M, DEVICE_ID_HEADER as N, DetectedRuntime as O, type DwellEntry as P, type ErrorContextHook as Q, type FeedParams as R, FeedTab as S, type TokenStorage as T, type FileInput as U, FilesResource as V, type FollowResult as W, type ForgotPasswordInput as X, type Hashtag as Y, type HashtagPostsParams as Z, HashtagsResource as _, ItdClient as a, type Profile as a$, type ImageMimeType as a0, type InteractionEntry as a1, type IsoDate as a2, ItdAbortError as a3, ItdApiError as a4, type ItdApiErrorInit as a5, ItdApiErrorKind as a6, ItdAuthError as a7, type ItdBuilder as a8, ItdConfigError as a9, type NotificationEvent as aA, type NotificationListParams as aB, type NotificationSettings as aC, NotificationType as aD, NotificationsResource as aE, OAuthProvider as aF, type Page as aG, type PageState as aH, PaginationMode as aI, Paginator as aJ, type PaymentMethod as aK, type Pin as aL, type PinPostResult as aM, type PinsResult as aN, PlatformResource as aO, type Poll as aP, PollBuilder as aQ, type PollInput as aR, type PollOption as aS, type PollTransportOptions as aT, type Portal as aU, type Post as aV, PostBuilder as aW, type PostInput as aX, type PostStats as aY, PostsResource as aZ, type PrivacySettings as a_, ItdConflictError as aa, ItdError as ab, ItdErrorCode as ac, ItdErrorKind as ad, type ItdFieldErrors as ae, ItdForbiddenError as af, ItdNetworkError as ag, ItdNotFoundError as ah, ItdPhoneVerificationError as ai, ItdRateLimitError as aj, ItdRealtime as ak, ItdServerError as al, ItdTimeoutError as am, ItdValidationError as an, LIBRARY_VERSION as ao, type LikeResult as ap, LikesVisibility as aq, type Listener as ar, LocalStorageTokenStorage as as, type Logger as at, type Loose as au, MAX_RECONNECT_ATTEMPTS as av, MemoryTokenStorage as aw, type MyProfile as ax, NOTIFICATION_TYPE_ALIASES as ay, type Notification as az, type ItdClientOptions as b, formatNotificationText as b$, type PublicProfile as b0, RECONNECT_BACKOFF as b1, RECONNECT_JITTER as b2, REFRESH_COOKIE as b3, REFRESH_COOKIE_PATH as b4, type RateLimitOptions as b5, type RawRequestOptions as b6, type RealtimeEvents as b7, type RealtimeOptions as b8, RealtimeStatus as b9, SubscriptionResource as bA, type SubscriptionState as bB, TURNSTILE_SITE_KEY as bC, TelemetryResource as bD, type TransportContext as bE, type TransportEvent as bF, UnauthorizedStreamError as bG, type Unsubscribe as bH, type UpdateNotificationSettingsInput as bI, type UpdatePrivacyInput as bJ, type UpdateProfileInput as bK, type UploadOptions as bL, type UploadedFile as bM, type UserId as bN, type UserListParams as bO, type UserPostsParams as bP, type UserRef as bQ, type UserSummary as bR, UsersResource as bS, VIDEO_MIME_TYPES as bT, VerificationResource as bU, type VerificationStatus as bV, type VideoMimeType as bW, WallAccess as bX, canonicalNotificationType as bY, comment as bZ, createTokenStorage as b_, type RealtimeTransport as ba, RealtimeTransportKind as bb, type ReconnectOptions as bc, type RepliesParams as bd, type Report as be, ReportBuilder as bf, type ReportInput as bg, ReportReason as bh, ReportTargetType as bi, ReportsResource as bj, type RequestContext as bk, type RequestOptions as bl, type ResetPasswordInput as bm, type ResponseContext as bn, type RetryContext as bo, type RetryOptions as bp, RuntimeMode as bq, STREAM_PATH as br, SearchResource as bs, type SearchResult as bt, type Session as bu, type SignInResult as bv, SignInStatus as bw, type Span as bx, type SseTransportOptions as by, type Subscription as bz, AUDIO_MIME_TYPES as c, isBuilder as c0, isItdApiError as c1, isItdAuthError as c2, isItdConflictError as c3, isItdError as c4, isItdForbiddenError as c5, isItdNotFoundError as c6, isItdPhoneVerificationError as c7, isItdRateLimitError as c8, isItdServerError as c9, isItdValidationError as ca, isKnownNotificationType as cb, isMyProfile as cc, normalizeNotification as cd, poll as ce, post as cf, readNotificationEvent as cg, readUnreadCountEvent as ch, report as ci, resolveNotificationUrl as cj, toDate as ck, createClient as cl, AUTH_FLAG_COOKIE as d, AUTH_PATHS as e, type Actor as f, type AllowedMimeType as g, type Announcement as h, type AnnouncementButton as i, type Attachment as j, AttachmentType as k, type AudioMimeType as l, type AuthInput as m, AuthResource as n, type Author as o, type ChangelogEntry as p, type Clan as q, type ClientHooks as r, type Comment as s, CommentBuilder as t, type CommentInput as u, type CommentReplyTo as v, CommentSort as w, type CommentsParams as x, CommentsResource as y, type CreateCommentInput as z };