itd-api 0.0.11 → 0.1.0

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { M as MultiTokenStorage, I as ItdSession, T as TokenStorage, a as ItdAccounts$1, b as ItdAccountsOptions, c as ItdClient$1, d as ItdClientOptions, e as ItdClientInternals, F as FileReader } from './index-CrlTO7sR.js';
-export { A as ALLOWED_MIME_TYPES, f as AUDIO_MIME_TYPES, g as AUTH_FLAG_COOKIE, h as AUTH_PATHS, i as AccessType, j as AccountEvents, k as Actor, l as AddAccountOptions, m as AllowedMimeType, n as Announcement, o as AnnouncementButton, p as Attachment, q as AttachmentType, r as AudioMimeType, s as AuthEvents, t as AuthIdentity, u as AuthInput, v as AuthResource, w as Author, x as AutoSpansOptions, B as BUILT_IN_SERVICES, y as BuilderInput, C as CaptchaCredentials, z as ChangelogEntry, D as Clan, E as ClientHooks, G as Comment, H as CommentBuilder, J as CommentInput, K as CommentReplyTo, L as CommentSort, N as CommentsParams, O as CommentsResource, P as CreateCommentInput, Q as CreatePollInput, R as CreatePostInput, S as CreateReportInput, U as Credentials, V as CredentialsAuth, W as DEFAULT_BASE_URL, X as DEFAULT_STATUS_BASE_URL, Y as DEFAULT_TIMEOUT, Z as DEFAULT_UPLOAD_TIMEOUT, _ as DEFAULT_USER_AGENT, $ as DEVICE_ID_HEADER, a0 as DetectedRuntime, a1 as DwellEntry, a2 as ErrorContextHook, a3 as FeedParams, a4 as FeedTab, a5 as FileInput, a6 as FilesResource, a7 as FollowResult, a8 as ForgotPasswordInput, a9 as Hashtag, aa as HashtagPostsParams, ab as HashtagsResource, ac as IMAGE_MIME_TYPES, ad as ImageMimeType, ae as IncidentKind, af as InteractionEntry, ag as InteractionType, ah as IsoDate, ai as ItdAbortError, aj as ItdApiError, ak as ItdApiErrorInit, al as ItdApiErrorKind, am as ItdAuthError, an as ItdBuilder, ao as ItdConfigError, ap as ItdConflictError, aq as ItdError, ar as ItdErrorCode, as as ItdErrorKind, at as ItdFieldErrors, au as ItdForbiddenError, av as ItdNetworkError, aw as ItdNotFoundError, ax as ItdPhoneVerificationError, ay as ItdPlugin, az as ItdRateLimitError, aA as ItdRealtime, aB as ItdServerError, aC as ItdTimeoutError, aD as ItdValidationError, aE as LIBRARY_VERSION, aF as LikeResult, aG as LikesVisibility, aH as Listener, aI as LocalStorageTokenStorage, aJ as Logger, aK as Loose, aL as MAX_RECONNECT_ATTEMPTS, aM as MarkupBuilder, aN as MarkupContent, aO as MarkupInput, aP as MarkupSpan, aQ as MemoryMultiTokenStorage, aR as MemoryTokenStorage, aS as MyProfile, aT as NOTIFICATION_TYPE_ALIASES, aU as Notification, aV as NotificationEvent, aW as NotificationListParams, aX as NotificationSettings, aY as NotificationType, aZ as NotificationsResource, a_ as OAuthProvider, a$ as Page, b0 as PageState, b1 as PaginationMode, b2 as Paginator, b3 as PaginatorOptions, b4 as PaymentMethod, b5 as Pin, b6 as PinPostResult, b7 as PinsResult, b8 as PlatformResource, b9 as PlatformStatus, ba as PluginContext, bb as Poll, bc as PollBuilder, bd as PollInput, be as PollOption, bf as PollTransportOptions, bg as Portal, bh as Post, bi as PostBuilder, bj as PostInput, bk as PostStats, bl as PostUpdateInput, bm as PostsResource, bn as PrivacySettings, bo as Profile, bp as PublicProfile, bq as QueryParams, br as QueryValue, bs as RECONNECT_BACKOFF, bt as RECONNECT_JITTER, bu as REFRESH_COOKIE, bv as REFRESH_COOKIE_PATH, bw as REQUEST_OPTION_KEYS, bx as RateLimitOptions, by as RateLimitScope, bz as RawRequestOptions, bA as RealtimeDeps, bB as RealtimeEvents, bC as RealtimeOptions, bD as RealtimeStatus, bE as RealtimeTransport, bF as RealtimeTransportKind, bG as ReconnectOptions, bH as RecordStorageSource, bI as RemoveAccountOptions, bJ as RenderSpansOptions, bK as RepliesParams, bL as Report, bM as ReportBuilder, bN as ReportInput, bO as ReportReason, bP as ReportTargetType, bQ as ReportsResource, bR as RequestContext, bS as RequestOptions, bT as ResetPasswordInput, bU as ResponseContext, bV as RetryContext, bW as RetryOptions, bX as RuntimeMode, bY as STATUS_SERVICE, bZ as STREAM_PATH, b_ as SearchResource, b$ as SearchResult, c0 as ServiceDefinition, c1 as ServiceRegistry, c2 as ServiceState, c3 as ServiceStatus, c4 as Session, c5 as SignInResult, c6 as SignInStatus, c7 as Span, c8 as SpanRenderFormat, c9 as SpanType, ca as SseTransportOptions, cb as StatusDay, cc as StatusIncidentLine, cd as Subscription, ce as SubscriptionResource, cf as SubscriptionState, cg as TURNSTILE_SITE_KEY, ch as TelemetryOptions, ci as TelemetryResource, cj as TextMarkup, ck as Transformer, cl as TransportContext, cm as TransportEvent, cn as UnauthorizedStreamError, co as Unsubscribe, cp as UpdateNotificationSettingsInput, cq as UpdatePostInput, cr as UpdatePrivacyInput, cs as UpdateProfileInput, ct as UploadOptions, cu as UploadedFile, cv as UserId, cw as UserListParams, cx as UserPostsParams, cy as UserRef, cz as UserSummary, cA as UsersResource, cB as VIDEO_MIME_TYPES, cC as VerificationResource, cD as VerificationStatus, cE as VideoMimeType, cF as ViewReason, cG as ViewSource, cH as WallAccess, cI as autoSpans, cJ as canonicalNotificationType, cK as comment, cL as createMultiTokenStorage, cM as createRecordMultiStorage, cN as createTokenStorage, cO as formatNotificationText, cP as isBuilder, cQ as isItdApiError, cR as isItdAuthError, cS as isItdConflictError, cT as isItdError, cU as isItdForbiddenError, cV as isItdNotFoundError, cW as isItdPhoneVerificationError, cX as isItdRateLimitError, cY as isItdServerError, cZ as isItdValidationError, c_ as isKnownNotificationType, c$ as isMyProfile, d0 as mapPage, d1 as markup, d2 as normalizeNotification, d3 as poll, d4 as post, d5 as readNotificationEvent, d6 as readUnreadCountEvent, d7 as renderSpans, d8 as report, d9 as resolveNotificationUrl, da as scopedTokenStorage, db as statusDays, dc as toDate, dd as utcStampToIso } from './index-CrlTO7sR.js';
+import { M as MultiTokenStorage, I as ItdSession, T as TokenStorage, a as ItdAccounts$1, b as ItdAccountsOptions, c as ItdClient$1, d as ItdClientOptions, e as ItdClientInternals, F as FileReader } from './index-BZF4K90s.js';
+export { A as ALLOWED_MIME_TYPES, f as AUDIO_MIME_TYPES, g as AUTH_FLAG_COOKIE, h as AUTH_PATHS, i as AccessType, j as AccountEvents, k as Actor, l as AddAccountOptions, m as AllowedMimeType, n as Announcement, o as AnnouncementButton, p as Attachment, q as AttachmentType, r as AudioMimeType, s as AuthEvents, t as AuthIdentity, u as AuthInput, v as AuthResource, w as Author, x as AutoSpansOptions, B as BUILT_IN_SERVICES, y as BuilderInput, C as CaptchaCredentials, z as ChangelogEntry, D as Clan, E as ClientHooks, G as Comment, H as CommentBuilder, J as CommentInput, K as CommentReplyTo, L as CommentSort, N as CommentsParams, O as CommentsResource, P as CreateCommentInput, Q as CreatePollInput, R as CreatePostInput, S as CreateReportInput, U as Credentials, V as CredentialsAuth, W as DEFAULT_BASE_URL, X as DEFAULT_STATUS_BASE_URL, Y as DEFAULT_TIMEOUT, Z as DEFAULT_UPLOAD_TIMEOUT, _ as DEFAULT_USER_AGENT, $ as DEVICE_ID_HEADER, a0 as DetectedRuntime, a1 as DwellEntry, a2 as ErrorContextHook, a3 as FeedParams, a4 as FeedTab, a5 as FileInput, a6 as FilesResource, a7 as FollowResult, a8 as ForgotPasswordInput, a9 as Hashtag, aa as HashtagPostsParams, ab as HashtagsResource, ac as IMAGE_MIME_TYPES, ad as ImageMimeType, ae as IncidentKind, af as InteractionEntry, ag as InteractionType, ah as IsoDate, ai as ItdAbortError, aj as ItdApiError, ak as ItdApiErrorInit, al as ItdApiErrorKind, am as ItdAuthError, an as ItdBuilder, ao as ItdConfigError, ap as ItdConflictError, aq as ItdError, ar as ItdErrorCode, as as ItdErrorKind, at as ItdFieldErrors, au as ItdForbiddenError, av as ItdNetworkError, aw as ItdNotFoundError, ax as ItdPhoneVerificationError, ay as ItdPlugin, az as ItdRateLimitError, aA as ItdRealtime, aB as ItdServerError, aC as ItdTimeoutError, aD as ItdValidationError, aE as LIBRARY_VERSION, aF as LikeResult, aG as LikesVisibility, aH as Listener, aI as LocalStorageTokenStorage, aJ as Logger, aK as Loose, aL as MAX_RECONNECT_ATTEMPTS, aM as MarkupBuilder, aN as MarkupContent, aO as MarkupInput, aP as MarkupSpan, aQ as MemoryMultiTokenStorage, aR as MemoryTokenStorage, aS as MyProfile, aT as NOTIFICATION_TYPE_ALIASES, aU as Notification, aV as NotificationEvent, aW as NotificationListParams, aX as NotificationSettings, aY as NotificationType, aZ as NotificationsResource, a_ as OAuthProvider, a$ as Page, b0 as PageState, b1 as PaginationMode, b2 as Paginator, b3 as PaginatorOptions, b4 as PaymentMethod, b5 as Pin, b6 as PinPostResult, b7 as PinsResult, b8 as PlatformResource, b9 as PlatformStatus, ba as PluginContext, bb as PluginTeardown, bc as Poll, bd as PollBuilder, be as PollInput, bf as PollOption, bg as PollTransportOptions, bh as Portal, bi as Post, bj as PostBuilder, bk as PostInput, bl as PostStats, bm as PostUpdateInput, bn as PostsResource, bo as PrivacySettings, bp as Profile, bq as PublicProfile, br as QueryParams, bs as QueryValue, bt as RECONNECT_BACKOFF, bu as RECONNECT_JITTER, bv as REFRESH_COOKIE, bw as REFRESH_COOKIE_PATH, bx as REQUEST_OPTION_KEYS, by as RateLimitOptions, bz as RateLimitScope, bA as RawRequestOptions, bB as RealtimeDeps, bC as RealtimeEvents, bD as RealtimeOptions, bE as RealtimeStatus, bF as RealtimeTransport, bG as RealtimeTransportKind, bH as ReconnectOptions, bI as RecordStorageSource, bJ as RemoveAccountOptions, bK as RenderSpansOptions, bL as RepliesParams, bM as Report, bN as ReportBuilder, bO as ReportInput, bP as ReportReason, bQ as ReportTargetType, bR as ReportsResource, bS as RequestContext, bT as RequestOptions, bU as ResetPasswordInput, bV as ResponseContext, bW as RetryContext, bX as RetryOptions, bY as RuntimeMode, bZ as STATUS_SERVICE, b_ as STREAM_PATH, b$ as SearchResource, c0 as SearchResult, c1 as ServiceDefinition, c2 as ServiceRegistry, c3 as ServiceState, c4 as ServiceStatus, c5 as Session, c6 as SignInResult, c7 as SignInStatus, c8 as Span, c9 as SpanRenderFormat, ca as SpanType, cb as SseTransportOptions, cc as StatusDay, cd as StatusIncidentLine, ce as Subscription, cf as SubscriptionResource, cg as SubscriptionState, ch as TURNSTILE_SITE_KEY, ci as TelemetryOptions, cj as TelemetryResource, ck as TextMarkup, cl as Transformer, cm as TransportContext, cn as TransportEvent, co as UnauthorizedStreamError, cp as Unsubscribe, cq as UpdateNotificationSettingsInput, cr as UpdatePostInput, cs as UpdatePrivacyInput, ct as UpdateProfileInput, cu as UploadOptions, cv as UploadedFile, cw as UserId, cx as UserListParams, cy as UserPostsParams, cz as UserRef, cA as UserSummary, cB as UsersResource, cC as VIDEO_MIME_TYPES, cD as VerificationResource, cE as VerificationStatus, cF as VideoMimeType, cG as ViewReason, cH as ViewSource, cI as WallAccess, cJ as autoSpans, cK as canonicalNotificationType, cL as comment, cM as createMultiTokenStorage, cN as createRecordMultiStorage, cO as createTokenStorage, cP as formatNotificationText, cQ as isBuilder, cR as isItdApiError, cS as isItdAuthError, cT as isItdConflictError, cU as isItdError, cV as isItdForbiddenError, cW as isItdNotFoundError, cX as isItdPhoneVerificationError, cY as isItdRateLimitError, cZ as isItdServerError, c_ as isItdValidationError, c$ as isKnownNotificationType, d0 as isMyProfile, d1 as mapPage, d2 as markup, d3 as normalizeNotification, d4 as poll, d5 as post, d6 as readNotificationEvent, d7 as readUnreadCountEvent, d8 as renderSpans, d9 as report, da as resolveNotificationUrl, db as scopedTokenStorage, dc as statusDays, dd as toDate, de as utcStampToIso } from './index-BZF4K90s.js';
 
 /**
  * `itd-api/node` — то же, что `itd-api`, плюс работа с файловой системой.

package/dist/node.js

@@ -1,5 +1,5 @@
-import { copySession, createRecordMultiStorage, ItdConfigError, ItdClient, ItdAccounts } from './chunk-TB7HW3VX.js';
-export { ALLOWED_MIME_TYPES, AUDIO_MIME_TYPES, AUTH_FLAG_COOKIE, AUTH_PATHS, AccessType, AttachmentType, BUILT_IN_SERVICES, CommentSort, DEFAULT_BASE_URL, DEFAULT_STATUS_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, DEFAULT_USER_AGENT, DEVICE_ID_HEADER, DetectedRuntime, FeedTab, IMAGE_MIME_TYPES, IncidentKind, InteractionType, ItdAbortError, ItdApiError, ItdApiErrorKind, ItdAuthError, ItdConfigError, ItdConflictError, ItdError, ItdErrorCode, ItdErrorKind, ItdForbiddenError, ItdNetworkError, ItdNotFoundError, ItdPhoneVerificationError, ItdRateLimitError, ItdRealtime, ItdServerError, ItdTimeoutError, ItdValidationError, LIBRARY_VERSION, LikesVisibility, LocalStorageTokenStorage, MAX_RECONNECT_ATTEMPTS, MemoryMultiTokenStorage, MemoryTokenStorage, NOTIFICATION_TYPE_ALIASES, NotificationType, OAuthProvider, PaginationMode, Paginator, RECONNECT_BACKOFF, RECONNECT_JITTER, REFRESH_COOKIE, REFRESH_COOKIE_PATH, REQUEST_OPTION_KEYS, RealtimeStatus, RealtimeTransportKind, ReportReason, ReportTargetType, RuntimeMode, STATUS_SERVICE, STREAM_PATH, ServiceRegistry, ServiceState, SignInStatus, SpanType, TURNSTILE_SITE_KEY, UnauthorizedStreamError, VIDEO_MIME_TYPES, ViewReason, ViewSource, WallAccess, autoSpans, canonicalNotificationType, comment, createMultiTokenStorage, createRecordMultiStorage, createTokenStorage, formatNotificationText, isBuilder, isItdApiError, isItdAuthError, isItdConflictError, isItdError, isItdForbiddenError, isItdNotFoundError, isItdPhoneVerificationError, isItdRateLimitError, isItdServerError, isItdValidationError, isKnownNotificationType, isMyProfile, mapPage, markup, normalizeNotification, poll, post, readNotificationEvent, readUnreadCountEvent, renderSpans, report, resolveNotificationUrl, scopedTokenStorage, statusDays, toDate, utcStampToIso } from './chunk-TB7HW3VX.js';
+import { copySession, createRecordMultiStorage, ItdConfigError, ItdClient, ItdAccounts } from './chunk-6FB4HTKH.js';
+export { ALLOWED_MIME_TYPES, AUDIO_MIME_TYPES, AUTH_FLAG_COOKIE, AUTH_PATHS, AccessType, AttachmentType, BUILT_IN_SERVICES, CommentSort, DEFAULT_BASE_URL, DEFAULT_STATUS_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, DEFAULT_USER_AGENT, DEVICE_ID_HEADER, DetectedRuntime, FeedTab, IMAGE_MIME_TYPES, IncidentKind, InteractionType, ItdAbortError, ItdApiError, ItdApiErrorKind, ItdAuthError, ItdConfigError, ItdConflictError, ItdError, ItdErrorCode, ItdErrorKind, ItdForbiddenError, ItdNetworkError, ItdNotFoundError, ItdPhoneVerificationError, ItdRateLimitError, ItdRealtime, ItdServerError, ItdTimeoutError, ItdValidationError, LIBRARY_VERSION, LikesVisibility, LocalStorageTokenStorage, MAX_RECONNECT_ATTEMPTS, MemoryMultiTokenStorage, MemoryTokenStorage, NOTIFICATION_TYPE_ALIASES, NotificationType, OAuthProvider, PaginationMode, Paginator, RECONNECT_BACKOFF, RECONNECT_JITTER, REFRESH_COOKIE, REFRESH_COOKIE_PATH, REQUEST_OPTION_KEYS, RealtimeStatus, RealtimeTransportKind, ReportReason, ReportTargetType, RuntimeMode, STATUS_SERVICE, STREAM_PATH, ServiceRegistry, ServiceState, SignInStatus, SpanType, TURNSTILE_SITE_KEY, UnauthorizedStreamError, VIDEO_MIME_TYPES, ViewReason, ViewSource, WallAccess, autoSpans, canonicalNotificationType, comment, createMultiTokenStorage, createRecordMultiStorage, createTokenStorage, formatNotificationText, isBuilder, isItdApiError, isItdAuthError, isItdConflictError, isItdError, isItdForbiddenError, isItdNotFoundError, isItdPhoneVerificationError, isItdRateLimitError, isItdServerError, isItdValidationError, isKnownNotificationType, isMyProfile, mapPage, markup, normalizeNotification, poll, post, readNotificationEvent, readUnreadCountEvent, renderSpans, report, resolveNotificationUrl, scopedTokenStorage, statusDays, toDate, utcStampToIso } from './chunk-6FB4HTKH.js';
 
 // src/node.ts
 function hasErrorCode(error, code) {

package/guides/README.md

@@ -10,6 +10,8 @@
 | [Интеграции](./integrations/README.md) | proxy, Turnstile и точки подключения внешних возможностей |
 | [Плагины](./plugins/README.md) | Cache, Crypto, `ItdPlugin` и создание нового плагина |
 
+Технический справочник всех методов и типов по категориям — в [`reference/`](./reference/README.md).
+
 ## Запуск примеров
 
 Установите зависимости и соберите библиотеку:

package/guides/multi-accounts/README.md

@@ -125,7 +125,8 @@ accounts.on('authError', ({ account, error }) => {
 ```
 
 Плагины, подключённые через `accounts.use(plugin)`, применяются ко всем существующим и
-будущим клиентам.
+будущим клиентам. `await accounts.unuse(name)` отключает плагин у всех, а
+`accounts.pluginNames()` показывает фактический общий порядок.
 
 ## Realtime
 

package/guides/plugins/README.md

@@ -107,8 +107,97 @@ itd.use(timing);
 - вернуть результат без обращения к сети;
 - выбросить собственную ошибку.
 
-Подключённая раньше обёртка оказывается снаружи. Она выполняется один раз на логический
-запрос, независимо от внутренних повторов транспорта.
+Без явных правил подключённая раньше обёртка оказывается снаружи. Она выполняется один раз
+на логический запрос, независимо от внутренних повторов транспорта.
+
+## Порядок и зависимости
+
+Плагин может описать отношения с другими плагинами:
+
+```ts
+const tracing: ItdPlugin = {
+  name: 'tracing',
+  before: ['cache'],       // обёртка tracing снаружи cache
+  requires: ['transport'], // без transport подключение завершится ошибкой
+  conflicts: ['legacy-tracing'],
+  install({ use }) {
+    use((request, next) => next(request));
+  },
+};
+```
+
+- `before` ставит плагин снаружи названных;
+- `after` — внутри названных;
+- `requires` требует уже подключённый плагин и ставит его раньше зависимого;
+- `conflicts` запрещает совместное подключение, даже если конфликт объявлен только одной
+  стороной.
+
+Ссылки `before` и `after` на ещё не подключённый плагин допустимы: порядок перестроится,
+когда тот появится. Цикл отклоняется до вызова `install()`.
+
+Фактический порядок можно проверить:
+
+```ts
+itd.pluginNames();
+itd.hasPlugin('cache');
+```
+
+## Хуки отдельных попыток
+
+`use()` видит логический запрос один раз. Для метрик и трассировки есть `useHooks()`:
+
+```ts
+const telemetry: ItdPlugin = {
+  name: 'telemetry',
+  install({ useHooks }) {
+    useHooks({
+      onRequest({ method, path, attempt }) {
+        console.log(`попытка ${attempt}: ${method} ${path}`);
+      },
+      onResponse({ status, duration }) {
+        console.log(status, duration);
+      },
+      onError({ error, duration }) {
+        console.error(error, duration);
+      },
+      onRetry({ attempt, delay }) {
+        console.log(`после попытки ${attempt} ждём ${delay} мс`);
+      },
+    });
+  },
+};
+```
+
+Хуки, заданные в конструкторе `ItdClient`, вызываются раньше хуков плагинов. Исключение
+из хука прерывает запрос — плагину наблюдаемости лучше обрабатывать собственные ошибки
+внутри.
+
+## Отключение и очистка
+
+`install()` может вернуть синхронную или асинхронную функцию очистки:
+
+```ts
+const plugin: ItdPlugin = {
+  name: 'connection',
+  install({ use }) {
+    const connection = openConnection();
+    use((request, next) => next(request));
+
+    return () => connection.close();
+  },
+};
+
+itd.use(plugin);
+await itd.unuse('connection');
+```
+
+Новые запросы перестают видеть плагин сразу, а teardown ждёт завершения запроса, который
+уже проходит через его обёртку. Обязательную зависимость нельзя отключить раньше зависящего
+от неё плагина.
+
+`close()` по-прежнему временно останавливает очередь и realtime, не отключая плагины.
+`dispose()` делает окончательную очистку и вызывает teardown всех плагинов изнутри наружу.
+`await using` вызывает `dispose()` автоматически.
 
 ## Собственные опции метода
 
@@ -140,9 +229,11 @@ declare module 'itd-api' {
 
 ```ts
 accounts.use(plugin);
+await accounts.unuse(plugin.name);
 ```
 
 Плагин установится всем существующим аккаунтам и будет автоматически применяться к новым.
+`accounts.pluginNames()` и `accounts.hasPlugin()` описывают общий набор.
 
 ## Структура нового плагина
 

package/guides/reference/README.md

@@ -0,0 +1,67 @@
+# Справочник API
+
+Техническое описание всех методов и типов `itd-api`. В отличие от [руководств](../README.md),
+здесь нет сценариев и рабочих примеров — только сигнатуры, параметры и возвращаемые типы,
+разбитые по категориям.
+
+## Ресурсы клиента
+
+| Категория | Доступ | О чём |
+|---|---|---|
+| [Клиент](./client.md) | `new ItdClient()` | конструктор, `request()`, `use()`, сервисы, события, `realtime()`, `close()` |
+| [Авторизация](./auth.md) | `itd.auth` | вход, регистрация, OTP, пароли, OAuth, сессии |
+| [Пользователи](./users.md) | `itd.users` | профили, подписки, блокировки, приватность, значки |
+| [Посты](./posts.md) | `itd.posts` | лента, публикация, реакции, репосты, опросы, комментарии к постам |
+| [Комментарии](./comments.md) | `itd.comments` | ответы на комментарии и действия над ними |
+| [Уведомления](./notifications.md) | `itd.notifications` | список, счётчик, отметки о прочтении, настройки |
+| [Файлы](./files.md) | `itd.files` | загрузка и удаление медиа |
+| [Поиск и обнаружение](./discovery.md) | `itd.search`, `itd.hashtags` | глобальный поиск, хэштеги, тренды, рекомендации, кланы, портал |
+| [Подписка](./subscription.md) | `itd.subscription` | состояние премиума, автопродление, способы оплаты |
+| [Верификация](./verification.md) | `itd.verification` | статус и подача заявки |
+| [Жалобы](./reports.md) | `itd.reports` | жалобы на контент и пользователей |
+| [Платформа](./platform.md) | `itd.platform` | журнал изменений, анонсы, портал, статус сервисов |
+| [Realtime](./realtime.md) | `itd.realtime()` | поток уведомлений, события, транспорт, переподключение |
+
+## Несколько аккаунтов
+
+| Категория | Доступ | О чём |
+|---|---|---|
+| [Аккаунты](./accounts.md) | `new ItdAccounts()` | контейнер именованных клиентов с общим хранилищем |
+
+## Справочники типов
+
+| Файл | О чём |
+|---|---|
+| [Модели данных](./models.md) | `Post`, `Comment`, `Profile`, `Notification`, `Attachment` и остальные ответы API |
+| [Перечисления](./enums.md) | `FeedTab`, `SpanType`, `NotificationType`, `ReportReason` и прочие |
+| [Ошибки](./errors.md) | иерархия `ItdError`, коды `ItdErrorCode`, функции-предикаты |
+| [Билдеры](./builders.md) | `post()`, `comment()`, `poll()`, `report()`, `markup()`, `renderSpans()` |
+| [Пагинация](./pagination.md) | `Page<T>`, `Paginator<T>`, три схемы под одним `for await` |
+
+## Общие соглашения
+
+**`RequestOptions` в каждом методе.** Почти все методы ресурсов принимают необязательный
+последний аргумент `options: RequestOptions` — он не повторяется в сигнатурах ниже:
+
+```ts
+interface RequestOptions {
+  signal?: AbortSignal;                  // отмена запроса
+  timeout?: number;                      // таймаут только этого запроса, мс
+  headers?: Record<string, string>;      // дополнительные заголовки
+  retry?: RetryOptions | false;          // повторы только этого запроса
+}
+```
+
+**`UserRef` против `UserId`.** `UserRef` — это UUID **или** имя пользователя: подходят оба
+(`itd.users.get('durov')` и `itd.users.get('9f1c…')`). `UserId` — строго UUID; имя
+пользователя там не работает (например, `wallRecipientId`).
+
+**Даты.** Все поля дат — строки ISO-8601 (`IsoDate`). Библиотека не превращает их в `Date`;
+для разбора есть [`toDate()`](./models.md#вспомогательные-функции).
+
+**Пагинация.** Методы-списки идут парами: `list()`/`comments()`/… возвращают одну
+[`Page<T>`](./pagination.md), а `iterate()`/`iterateComments()`/… — [`Paginator<T>`](./pagination.md)
+для `for await`. Подробнее — в [пагинации](./pagination.md).
+
+**Снятие обёртки.** Сервер оборачивает ответы в `{ data: … }`; библиотека снимает обёртку
+сама. Чтобы получить тело как есть, используйте `itd.request({ …, raw: true })`.

package/guides/reference/accounts.md

@@ -0,0 +1,101 @@
+# Аккаунты — `ItdAccounts`
+
+Контейнер именованных `ItdClient`: у каждого аккаунта свой токен, cookie и `deviceId`,
+а сессии всех складываются в одно хранилище (`MultiTokenStorage`). Имя аккаунта выбираете вы;
+сервер о нём ничего не знает. Полное руководство — [Несколько аккаунтов](../multi-accounts/README.md).
+
+```ts
+new ItdAccounts(options?: ItdAccountsOptions)
+createAccounts(options?: ItdAccountsOptions): ItdAccounts   // фабрика
+```
+
+## Методы
+
+```ts
+addAccount(name: string, options?: AddAccountOptions): ItdClient
+```
+Заводит аккаунт. Возвращает обычный `ItdClient` со всеми ресурсами. Хранилище подставляется
+само — срез общего по имени. `auth` не обязателен, если сессия уже в хранилище.
+
+```ts
+account(name: string): ItdClient
+```
+Клиент аккаунта. Бросает `ItdConfigError`, если аккаунта нет.
+
+```ts
+restore(): Promise<string[]>
+```
+Поднимает аккаунты, сессии которых уже лежат в хранилище (после перезапуска — без `auth` и
+капчи). Возвращает имена добавленных.
+
+```ts
+removeAccount(name: string, options?: RemoveAccountOptions): Promise<boolean>
+```
+Убирает аккаунт: закрывает клиента и, при `forget: true`, забывает сессию. Сетевого запроса
+не делает — для завершения сессии на сервере вызовите `itd.auth.logout()` до удаления.
+
+```ts
+has(name: string): boolean
+names(): string[]
+get size: number
+get storage: MultiTokenStorage
+```
+Состав контейнера.
+
+```ts
+use(plugin: ItdPlugin): this
+pluginNames(): string[]
+hasPlugin(name: string): boolean
+unuse(name: string): Promise<boolean>
+```
+Подключает плагин всем аккаунтам — и заведённым, и будущим; показывает общий набор или
+отключает плагин сразу у всех клиентов.
+
+```ts
+on<K>(event: K, listener): Unsubscribe
+```
+Подписка на [события авторизации всех аккаунтов](#события) сразу.
+
+```ts
+close(): Promise<void>
+dispose(): Promise<void>
+```
+`close()` временно закрывает все аккаунты и останавливает общую очередь, не отключая
+плагины. `dispose()` дополнительно вызывает teardown плагинов. `await using` вызывает
+`dispose()`.
+
+```ts
+[Symbol.iterator](): IterableIterator<[string, ItdClient]>
+```
+Перебор парами «имя — клиент»: `for (const [name, itd] of accounts) { … }`.
+
+## События (`AccountEvents`)
+
+Те же, что у одиночного клиента, плюс имя аккаунта:
+
+| Событие | Данные |
+|---|---|
+| `tokens` | `{ account, accessToken }` |
+| `signIn` | `{ account, accessToken }` |
+| `signOut` | `{ account }` |
+| `authError` | `{ account, error }` |
+
+## Опции
+
+```ts
+interface ItdAccountsOptions extends Omit<ItdClientOptions, 'auth' | 'storage' | 'deviceId'> {
+  storage?: MultiTokenStorage;           // по умолчанию MemoryMultiTokenStorage
+  plugins?: readonly ItdPlugin[];        // подключаются каждому аккаунту
+  rateLimitScope?: 'account' | 'shared'; // очередь: своя у каждого / общая; по умолчанию 'account'
+}
+
+type AddAccountOptions = Omit<ItdClientOptions, 'storage'>;
+
+interface RemoveAccountOptions {
+  forget?: boolean;                      // удалить и сохранённую сессию; по умолчанию false
+}
+```
+
+`rateLimitScope: 'shared'` нужен, когда все аккаунты сидят на одном IP и упираются в лимит по
+адресу. Настройки самой очереди тогда задаются контейнеру опцией `rateLimit`; аккаунту можно
+передать только `rateLimit: false`, чтобы вывести его из общей очереди.

package/guides/reference/auth.md

@@ -0,0 +1,141 @@
+# Авторизация — `itd.auth`
+
+Вход, регистрация, подтверждение по коду, пароли, OAuth и управление сессиями. Обычно
+клиент авторизуется сам через опцию `auth` конструктора; эти методы нужны для ручных
+сценариев входа. Полное руководство — [Авторизация](../authentication/README.md).
+
+Вход, регистрация и сброс пароля требуют одноразовый **Turnstile token**. Ключ виджета —
+экспорт `TURNSTILE_SITE_KEY`.
+
+## Вход и регистрация
+
+```ts
+signUp(credentials: CaptchaCredentials): Promise<string>
+```
+Регистрирует аккаунт и запускает подтверждение по коду. Возвращает `flowToken` для `verifyOtp()`.
+
+```ts
+signIn(credentials: CaptchaCredentials): Promise<SignInResult>
+```
+Выполняет вход. При успехе токен сохраняется в клиенте автоматически. Если сервер потребовал
+код, вернётся `{ status: 'otp_required', flowToken }`.
+
+```ts
+signInWithOtp(input: CaptchaCredentials & { getOtp: () => string | Promise<string> }): Promise<string>
+```
+Полный вход с подтверждением: код запрашивается функцией `getOtp`, остальное — само. Возвращает
+`accessToken`.
+
+```ts
+verifyOtp(input: Credentials & { otp: string; flowToken: string }): Promise<string>
+```
+Подтверждает вход кодом из письма. Токен сохраняется автоматически.
+
+```ts
+resendOtp(input: { email: string; flowToken: string }): Promise<void>
+```
+Отправляет код подтверждения повторно.
+
+## Сессия
+
+```ts
+refresh(): Promise<string>
+```
+Обновляет токен доступа. Параллельные вызовы объединяются в один сетевой запрос. При включённом
+`autoRefresh` вручную обычно не нужен.
+
+```ts
+hasRefreshSession(): Promise<boolean>
+```
+Есть ли признак живой сессии обновления (cookie `is_auth` или строковый refresh-токен).
+В браузере всегда `true`. Читает хранилище — верен и до первого запроса.
+
+```ts
+logout(): Promise<void>
+```
+Завершает текущую сессию на сервере и очищает локальную.
+
+```ts
+logoutAll(): Promise<void>
+```
+Завершает все сессии пользователя и очищает локальную.
+
+```ts
+signOut(): Promise<void>
+```
+Забывает сессию локально, не обращаясь к серверу.
+
+## Пароли
+
+```ts
+forgotPassword(input: ForgotPasswordInput): Promise<string>
+```
+Запрашивает письмо с кодом для сброса. Возвращает `flowToken` для `resetPassword()`.
+
+```ts
+resetPassword(input: ResetPasswordInput): Promise<void>
+```
+Устанавливает новый пароль по коду. Нужны все четыре поля: `email`, `otp`, `flowToken`, `newPassword`.
+
+```ts
+resetPasswordWithOtp(input: ForgotPasswordInput & { newPassword: string; getOtp: () => string | Promise<string> }): Promise<void>
+```
+Полный сброс: код запрашивается функцией `getOtp`, остальное — само.
+
+```ts
+changePassword(input: { currentPassword: string; newPassword: string }): Promise<void>
+```
+Меняет пароль. Требует действующей сессии. При неверном текущем пароле — код
+`ACCOUNT_CURRENT_PASSWORD_INCORRECT`.
+
+## Управление сессиями
+
+```ts
+sessions(): Promise<Session[]>
+```
+Список активных сессий. У текущей `isCurrent === true`. См. [`Session`](./models.md#session).
+
+```ts
+revokeSession(sessionId: string): Promise<void>
+```
+Завершает указанную сессию.
+
+```ts
+revokeOtherSessions(): Promise<void>
+```
+Завершает все сессии, кроме текущей.
+
+## Типы
+
+```ts
+interface Credentials {
+  email: string;
+  password: string;
+}
+
+interface CaptchaCredentials extends Credentials {
+  turnstileToken: string;                // одноразовый, живёт несколько минут
+}
+
+interface ForgotPasswordInput {
+  email: string;
+  turnstileToken: string;
+}
+
+interface ResetPasswordInput {
+  email: string;
+  otp: string;
+  flowToken: string;
+  newPassword: string;
+}
+
+type SignInResult =
+  | { status: 'authenticated'; accessToken: string }
+  | { status: 'otp_required'; flowToken: string | undefined };
+
+const OAuthProvider = { Yandex: 'yandex', Google: 'google' } as const;
+const SignInStatus = { Authenticated: 'authenticated', OtpRequired: 'otp_required' } as const;
+```
+
+Связанные: [`AuthInput`](./client.md#авторизация-authinput) (как клиент получает доступ),
+события авторизации `itd.on('tokens' | 'authError' | …)` — см. [Клиент](./client.md#события).

package/guides/reference/builders.md

@@ -0,0 +1,135 @@
+# Билдеры — `post()`, `comment()`, `poll()`, `report()`, `markup()`
+
+Билдеры собирают данные для публикующих методов и проверяют их **до** обращения к сети
+(бросают [`ItdConfigError`](./errors.md)). Все билдеры **неизменяемые**: каждый метод
+возвращает новый экземпляр, поэтому заготовку можно переиспользовать.
+
+Методы вроде `posts.create`, `posts.comment`, `comments.reply`, `reports.create` принимают три
+равноправные формы: обычный объект, готовый билдер или функцию-настройщик.
+
+```ts
+isBuilder(value: unknown): boolean       // это билдер?
+```
+
+## Пост — `post()`
+
+```ts
+post(content?: string): PostBuilder
+```
+
+| Метод | Описание |
+|---|---|
+| `.content(text)` | задаёт текст, сбрасывая прежнюю разметку |
+| `.append(text)` | дописывает текст к уже заданному |
+| `.spans(spans)` | задаёт готовую разметку `Span[]` |
+| `.markup(input)` | заменяет текст и разметку результатом `MarkupBuilder` |
+| `.autoSpans(options?)` | находит ссылки, хэштеги и упоминания в тексте |
+| `.onWall(userId)` | публикует на стене пользователя (**UUID**) |
+| `.attach(file)` | прикладывает файл (загрузится перед публикацией) |
+| `.attachId(id)` | прикладывает уже загруженное вложение |
+| `.poll(input)` | добавляет опрос |
+| `.build()` | возвращает проверенный `CreatePostInput` |
+
+## Комментарий — `comment()`
+
+```ts
+comment(content?: string): CommentBuilder
+```
+
+| Метод | Описание |
+|---|---|
+| `.content(text)` | задаёт текст |
+| `.attach(file)` / `.attachId(id)` | прикладывает вложение |
+| `.voice(audio)` | делает комментарий голосовым (без текста, одно аудио `audio/ogg`) |
+| `.replyTo(userId)` | адресат ответа (только в `comments.reply()`) |
+| `.build()` | возвращает проверенный `CreateCommentInput` |
+
+## Опрос — `poll()`
+
+```ts
+poll(question?: string): PollBuilder
+```
+
+| Метод | Описание |
+|---|---|
+| `.question(text)` | задаёт вопрос (≤ 200 символов) |
+| `.option(text)` | добавляет один вариант (≤ 100 символов) |
+| `.options(...texts)` | добавляет несколько вариантов сразу |
+| `.multipleChoice(enabled?)` | разрешает выбор нескольких |
+| `.build()` | возвращает проверенный `CreatePollInput` |
+
+Требуется от 2 до 10 различных непустых вариантов.
+
+## Жалоба — `report`
+
+Объект-фабрика: тип объекта выбирается точкой входа, поэтому рассогласовать тип и идентификатор
+нельзя.
+
+```ts
+report.post(postId: string): ReportBuilder
+report.comment(commentId: string): ReportBuilder
+report.user(userId: string): ReportBuilder
+```
+
+| Метод | Описание |
+|---|---|
+| `.reason(reason)` | причина ([`ReportReason`](./enums.md#reportreason)) |
+| `.description(text)` | пояснение в свободной форме |
+| `.build()` | возвращает проверенный `CreateReportInput` |
+
+## Разметка текста — `markup()`
+
+Собирает текст и сам считает `offset`/`length` в единицах UTF-16.
+
+```ts
+markup(content?: string): MarkupBuilder
+```
+
+| Метод | Описание |
+|---|---|
+| `.text(value)` | обычный текст без разметки |
+| `.newline(count?)` | переводы строк |
+| `.bold` · `.italic` · `.underline` · `.strike` · `.spoiler` · `.monospace` · `.quote` | стиль на фрагменте |
+| `.hashtag(tag)` | `#хэштег` |
+| `.mention(username)` | `@упоминание` |
+| `.link(content, url?)` | ссылка |
+| `.span(value, span)` | произвольный тип разметки |
+| `.styled(value, ...types)` | несколько стилей на одном диапазоне |
+| `.build()` | возвращает `{ content, spans }` |
+
+Все методы контента принимают строку **или** вложенный билдер/разметку — так стили вкладываются
+друг в друга.
+
+## Автоопределение сущностей
+
+```ts
+autoSpans(text: string, options?: AutoSpansOptions): Span[]
+```
+Находит HTTP(S)-ссылки, `#хэштеги` и `@упоминания` в готовом тексте.
+
+```ts
+interface AutoSpansOptions {
+  hashtags?: boolean;                    // по умолчанию true
+  mentions?: boolean;                    // по умолчанию true
+  links?: boolean;                       // по умолчанию true
+}
+```
+
+## Рендеринг разметки
+
+```ts
+renderSpans(content: string, spans: Span[] | null | undefined, options?: RenderSpansOptions): string
+```
+Превращает текст и spans в HTML (по умолчанию, безопасный), Markdown или ANSI.
+
+```ts
+interface RenderSpansOptions {
+  format?: 'html' | 'markdown' | 'ansi';                     // по умолчанию 'html'
+  mentionUrl?: (username: string) => string | null | undefined;
+  hashtagUrl?: (tag: string) => string | null | undefined;
+  classPrefix?: string | null;           // префикс CSS-классов; по умолчанию 'itd'
+}
+```
+
+Подробное руководство по разметке — [Разметка текста](../text-markup/README.md).
+См. [`Span`](./models.md#span), [`SpanType`](./enums.md#spantype).