itd-api 0.7.2 → 0.8.0

package/dist/shared/{render-CgwKdOzu.d.ts → render-DVB7T8pm.d.ts}

@@ -1,31 +1,229 @@
-import { $ as UserSummary, B as Notification, Ct as ReportReason, Dt as ViewReason, Ft as Logger, G as FollowResult, It as OperationRequestOptions, J as PinsResult, K as MyProfile, Lt as PaginationOptions, Mt as Unsubscribe, Ot as ViewSource, Qt as ServiceDefinition, Tt as ServiceState, V as NotificationSettings, Vt as RawRequestOptions, W as Author, Wt as RequestOptions, X as Profile, Xt as QueryParams, Y as PrivacySettings, Z as PublicProfile, _n as RetrySafety, _t as InteractionType, bt as Loose, ct as IsoDate, dt as UserRef, et as AuthIdentity, gn as OperationMethod, gt as IncidentKind, ht as FeedTab, lt as Span, mt as CommentSort, pt as AttachmentType, rn as BuiltInOperationId, sn as OperationId, tn as ItdClock, ut as UserId, wt as ReportTargetType, zt as RateLimitBucketOverride } from "./url-DTfZ2toq.js";
+import { Bt as ItdClock, Et as RawRequestOptions, Ft as QueryParams, Ht as BuiltInOperationId, Kt as OperationId, Lt as ServiceDefinition, St as PaginationOptions, _ as Profile, _n as ServiceState, _t as RetrySafety, an as AttachmentType, b as UserSummary, bn as ViewSource, bt as Logger, c as NotificationSettings, cn as FeedTab, ct as Unsubscribe, d as Author, en as IsoDate, et as ClientConnection, f as FollowResult, g as PrivacySettings, gn as ReportTargetType, gt as OperationMethod, h as PinsResult, hn as ReportReason, ht as OperationMetadata, kt as RequestOptions, ln as IncidentKind, mt as OperationContract, nn as UserId, on as CommentSort, p as MyProfile, pn as Loose, pt as OperationAnnotations, rn as UserRef, s as Notification, tn as Span, tt as AuthIdentity, un as InteractionType, v as PublicProfile, wt as RateLimitBucketOverride, xt as OperationRequestOptions, yn as ViewReason } from "./url-Be9jlWRv.js";
 import { c as LazyFile, d as UrlFileOptions, i as FileStreamContent, l as StreamFile, n as FileContext, o as FileTransferMode, r as FileInput, s as FromStreamOptions } from "./contracts-BoT7msmq.js";
-//#region src/core/catalog.d.ts
+//#region src/core/plugins/contracts.d.ts
+/**
+ * Обёртка одной логической операции.
+ *
+ * Вызывается один раз независимо от повторов и обновления авторизации. Может изменить
+ * параметры запроса, обработать публичный результат метода или завершить операцию локально.
+ * `operationId`, HTTP-метод и безопасность повтора задаются операцией.
+ *
+ * @param request описание логической операции; не изменяйте сам объект — передайте копию в `next`
+ * @param next следующая обёртка либо выполнение операции
+ * `next()` возвращает результат публичного метода. Если обёртка не вызывает `next`, её
+ * собственный результат считается готовым и повторно не нормализуется.
+ *
+ * @returns результат в том виде, в котором его получит вызывающий код
+ *
+ * @example Дописать заголовок ко всем операциям
+ * ```ts
+ * const transformer: OperationTransformer = (request, next) =>
+ *   next({ ...request, headers: { ...request.headers, 'X-Trace': trace() } });
+ * ```
+ */
+type OperationTransformer = (request: OperationRequestOptions, next: (request: OperationRequestOptions) => Promise<unknown>) => Promise<unknown>;
+/** Финальные данные одной транспортной попытки. */
+interface AttemptContext {
+  /** Постоянный идентификатор операции. */
+  readonly operationId: OperationId;
+  /** Нормализованный HTTP-метод. */
+  readonly method: string;
+  /** Исходный путь операции до выбора сервиса или `baseUrl`. */
+  readonly path: string;
+  /** Полный URL со строкой запроса. */
+  readonly url: string;
+  /** Итоговые изменяемые заголовки. */
+  readonly headers: Headers;
+  /** Номер сетевой попытки, начиная с 1. */
+  readonly attempt: number;
+  /** Подготовленное тело запроса. Поток нельзя читать заранее. */
+  readonly body: BodyInit | undefined;
+  /** Общий сигнал отмены и таймаута этой попытки. */
+  readonly signal: AbortSignal;
+}
+/**
+ * Продолжение цепочки перехватчиков. Можно вызвать только один раз.
+ */
+type AttemptNext = () => Promise<Response>;
 /**
- * Всё, что ядро знает о предметной области.
+ * Обёртка одной транспортной попытки.
+ *
+ * Получает уже разрешённый URL, итоговые заголовки, подготовленное тело и номер попытки.
+ * Может изменить заголовки, измерить задержку, обработать сырой `Response` или вернуть
+ * созданный вручную `Response`.
  *
- * Ядро исполняет операцию, не зная, что такое пост, комментарий или профиль: оно спрашивает
- * каталог о повторяемости, методе и счётчике частоты, а таблицы конкретного API живут
- * в доменном слое. Именно эта граница позволяет позже вынести retry и планировщик очереди
- * в отдельные слоты executor, не таща за ними каталог эндпоинтов.
+ * Вызывается для каждой сетевой попытки. Если перехватчик читает тело ответа, используйте
+ * `response.clone()`: исходный ответ дальше обрабатывает транспорт.
+ *
+ * @param context окончательные данные текущей транспортной попытки
+ * @param next следующий перехватчик либо вызов `fetch`
+ * @returns исходный или синтетический сырой `Response`
+ */
+type AttemptInterceptor = (context: AttemptContext, next: AttemptNext) => Promise<Response>;
+/** Регистрация расширений логической операции. */
+interface OperationExtensions {
+  /** Возвращает неизменяемые метаданные зарегистрированной операции. */
+  get(operationId: OperationId): OperationMetadata | undefined;
+  /**
+   * Подключает обёртку операции.
+   *
+   * Зарегистрированные раньше оборачивают зарегистрированные позже. Возвращённая функция
+   * идемпотентна и снимает только эту регистрацию.
+   */
+  use(transformer: OperationTransformer): Unsubscribe;
+}
+/** Регистрация расширений транспортной попытки. */
+interface AttemptExtensions {
+  /**
+   * Подключает перехватчик попытки.
+   *
+   * Зарегистрированные раньше оборачивают зарегистрированные позже. Возвращённая функция
+   * идемпотентна и снимает только эту регистрацию.
+   */
+  use(interceptor: AttemptInterceptor): Unsubscribe;
+}
+/**
+ * Функция освобождения ресурсов плагина.
+ */
+type PluginTeardown = () => void | Promise<void>;
+/** API, доступный плагину при подключении. */
+interface PluginApi {
+  /** Базовый URL клиента — например чтобы разобрать абсолютные ссылки из ответа. */
+  baseUrl: string;
+  /** Логгер клиента, если он включён. */
+  logger: Logger | undefined;
+  /** Обёртки логической операции. */
+  operations: OperationExtensions;
+  /** Перехватчики сетевой попытки. */
+  attempts: AttemptExtensions;
+  /**
+   * Внутренний идентификатор текущей авторизации.
+   */
+  getAuthScope?: (() => string) | undefined;
+  /**
+   * Загружает сессию и возвращает идентификаторы аккаунта и конкретной сессии из JWT.
+   *
+   * Используйте для общего состояния нескольких клиентов одного аккаунта.
+   */
+  getAuthIdentity?: (() => Promise<AuthIdentity>) | undefined;
+}
+/**
+ * Плагин клиента.
+ *
+ * Подключается через `itd.use(plugin)` и регистрирует расширения одного или обоих уровней:
+ * {@link OperationTransformer} для логической операции и {@link AttemptInterceptor} для
+ * отдельной транспортной попытки.
+ *
+ * Настройки отдельного вызова плагин объявляет своим полем в `RequestExtensions` через
+ * дополнение интерфейса. Пользователь передаёт их в `RequestOptions.extensions`, а обёртка
+ * операции читает поле своего плагина.
+ *
+ * @example Логирование логических операций
+ * ```ts
+ * const logging: ClientPlugin = {
+ *   name: 'logging',
+ *   install({ operations, logger }) {
+ *     operations.use(async (request, next) => {
+ *       logger?.info(`${request.method} ${request.path}`);
+ *       return next(request);
+ *     });
+ *   },
+ * };
+ *
+ * itd.use(logging);
+ * ```
+ */
+interface ClientPlugin {
+  /** Имя плагина. Должно быть уникальным: повторное подключение — ошибка. */
+  name: string;
+  /** Плагины, которые обязаны быть подключены раньше этого. */
+  requires?: readonly string[];
+  /** Несовместимые плагины. Достаточно объявить конфликт с одной стороны. */
+  conflicts?: readonly string[];
+  /** Имена плагинов, снаружи которых должны стоять оба вида расширений этого плагина. */
+  before?: readonly string[];
+  /** Имена плагинов, внутри которых должны стоять оба вида расширений этого плагина. */
+  after?: readonly string[];
+  /**
+   * Устанавливает плагин.
+   *
+   * Может вернуть функцию освобождения ресурсов. Она вызывается при `unuse()` или
+   * окончательном `dispose()` клиента и может быть асинхронной. Сам `install()` синхронный:
+   * регистрация расширений завершается до того, как `use()` вернёт управление.
+   */
+  install(api: PluginApi): void | PluginTeardown;
+}
+//#endregion
+//#region src/core/plugins/registry.d.ts
+/** Что реестру нужно знать об остановке. @internal */
+interface PluginRegistryOptions {
+  /** Срок ожидания операций плагина при его отключении, мс. `0` — ждать без ограничения. */
+  shutdownTimeout: number;
+  clock: ItdClock;
+  /** Возвращает публичные метаданные встроенной или feature-операции. */
+  operationMetadata: (operationId: OperationRequestOptions['operationId']) => OperationMetadata | undefined;
+}
+/**
+ * Список подключённых плагинов и зарегистрированных ими расширений.
+ *
+ * {@link run} собирает operation transformers вокруг одной логической операции и прикрепляет
+ * к ней неизменяемый снимок attempt interceptors. Transport исполняет этот снимок отдельно
+ * для каждой сетевой попытки. Порядок плагинов одинаков для обеих цепочек.
  *
  * @internal
  */
-interface OperationCatalog {
-  /** Безопасность повтора операции. `undefined` — операция каталогу неизвестна. */
-  retrySafetyOf(id: string): RetrySafety | undefined;
-  /** HTTP-метод операции. `undefined` — операция каталогу неизвестна. */
-  methodOf(id: string): OperationMethod | undefined;
-  /** Счётчик частоты операции. Для неизвестной возвращает {@link defaultBucket}. */
-  bucketOf(id: string): string;
-  /** Известно ли каталогу имя бакета. */
-  isKnownBucket(name: string): boolean;
-  /** Ёмкость бакетов до первого ответа сервера, запросов в минуту. */
-  readonly bucketLimits: Readonly<Record<string, number>>;
-  /** Встроенные поправки бакетов, например предел одновременности загрузки файлов. */
-  readonly bucketOverrides: Readonly<Record<string, RateLimitBucketOverride>>;
-  /** Счётчик, из которого списывается путь без собственного правила на сервере. */
-  readonly defaultBucket: string;
+declare class PluginRegistry {
+  #private;
+  constructor(options: PluginRegistryOptions);
+  /** Сколько плагинов подключено. */
+  get size(): number;
+  /** Имена плагинов в фактическом порядке выполнения. */
+  names(): string[];
+  /** Подключён ли плагин с таким именем. */
+  has(name: string): boolean;
+  /** Проверяет добавление без вызова `install()`. @internal */
+  assertCanAdd(plugin: ClientPlugin): void;
+  /** Проверяет удаление без изменения реестра. @internal */
+  assertCanRemove(name: string): void;
+  /**
+   * Подключает плагин.
+   *
+   * `install()` выполняется синхронно. Каждая регистрация принадлежит установившему её
+   * плагину и участвует в общем порядке `before`/`after`.
+   *
+   * @throws {ItdConfigError} если плагин задан неверно, уже подключён или нарушает зависимости
+   */
+  add(plugin: ClientPlugin, context: Omit<PluginApi, 'operations' | 'attempts'>): void;
+  /**
+   * Отключает плагин и вызывает его функцию очистки.
+   *
+   * Новые запросы перестают видеть расширения плагина сразу. Снимок уже начавшейся операции,
+   * включая её будущие retry, остаётся неизменным; очистка дождётся завершения операции,
+   * но не дольше отведённого срока.
+   *
+   * @returns `false`, если такого плагина не было
+   * @throws {ItdStateError} если операции плагина не завершились за отведённый срок
+   */
+  remove(name: string): Promise<boolean>;
+  /**
+   * Отключает все плагины окончательно.
+   *
+   * Очистка идёт изнутри наружу — в порядке, обратном выполнению расширений. Срок ожидания
+   * общий на все плагины.
+   */
+  dispose(): Promise<void>;
+  /**
+   * Прогоняет запрос через operation transformers и прикрепляет attempt interceptors.
+   *
+   * Снимки обеих цепочек берутся в начале: `unuse()` влияет на новые операции, но не меняет
+   * уже выполняющуюся и не удаляет interceptors из её последующих retry.
+   *
+   * Каждый `next` одноразовый: transformer может завершить операцию сам, но не может породить
+   * вторую — для `posts.create` это была бы вторая публикация.
+   *
+   * @param execute выполнение логической операции, вызываемое самым внутренним transformer
+   */
+  run(request: OperationRequestOptions, execute: (request: OperationRequestOptions) => Promise<unknown>): Promise<unknown>;
 }
 //#endregion
 //#region src/core/execution/pipeline.d.ts
@@ -82,15 +280,15 @@ type RequestHandler = (request: PipelineRequest) => Promise<unknown>;
 interface HttpClientDeps {
   /** Готовый обработчик — вся цепочка слоёв поверх транспорта. */
   handler: RequestHandler;
+  plugins: PluginRegistry;
   baseUrl: string;
-  /** Каталог, из которого берётся HTTP-метод семантической операции. */
-  catalog: OperationCatalog;
 }
+/** Параметры операции без ID и метода, заданных её контрактом. @internal */
+type HttpOperationOptions = Omit<PipelineRequest, 'operationId' | 'method'>;
 /**
  * Точка входа ресурсов в конвейер запросов.
  *
- * Принимает готовый обработчик — цепочку слоёв поверх транспорта, собранную
- * во внутреннем runtime клиента, — и отдаёт ресурсам методы `request`/`operation`.
+ * Принимает готовую цепочку обработки и предоставляет ресурсам методы `request`/`execute`.
  * О слоях и их порядке ресурсы не знают.
  */
 declare class HttpClient {
@@ -108,23 +306,91 @@ declare class HttpClient {
    * @throws {ItdNetworkError} если запрос не дошёл до сервера
    */
   request<T = unknown>(options: PipelineRequestInput): Promise<T>;
-  /** Выполняет встроенную семантическую операцию, подставляя её HTTP-метод из каталога. */
-  operation<T = unknown>(operationId: BuiltInOperationId, options: Omit<PipelineRequest, 'operationId' | 'method'>): Promise<T>;
+  /** Выполняет контракт операции; `next()` плагина возвращает результат после `read`. */
+  execute<T, TId extends OperationId>(operation: OperationContract<T, TId>, options: HttpOperationOptions): Promise<T>;
   /** Выполняет внутреннюю операцию финализации после начала `ItdClient.dispose()`. @internal */
-  cleanupOperation<T = unknown>(operationId: BuiltInOperationId, options: Omit<PipelineRequest, 'operationId' | 'method'>): Promise<T>;
+  cleanupOperation<T, TId extends OperationId>(operation: OperationContract<T, TId>, options: HttpOperationOptions): Promise<T>;
+}
+//#endregion
+//#region src/core/attachments/resolver.d.ts
+/** Дополнительные требования потребителя к подготовленному источнику. */
+interface ResolveFileOptions {
+  /** Имя, которое имеет приоритет над именем источника. */
+  readonly filename?: string | undefined;
+  /** MIME-тип, который имеет приоритет над типом источника. */
+  readonly contentType?: string | undefined;
+  /** Дополнительный предел размера для любого вида источника. */
+  readonly maxBytes?: number | undefined;
+  /** Размер очереди библиотеки при потоковом чтении. */
+  readonly streamBufferBytes?: number | undefined;
+  /** Отклонить поток, размер которого нельзя узнать до чтения. */
+  readonly requireKnownSize?: boolean | undefined;
+}
+/** Буфер, полностью принадлежащий вызывающему коду. */
+interface PreparedBufferSource {
+  readonly mode: typeof FileTransferMode.Buffer;
+  readonly blob: Blob;
+  readonly size: number;
+  readonly filename?: string | undefined;
+  readonly contentType: string | undefined;
+}
+/**
+ * Одна открытая сессия чтения потокового источника.
+ *
+ * Потребитель обязан вызвать {@link close} в `finally`. Повторный вызов безопасен и ждёт
+ * тот же результат освобождения ресурсов.
+ */
+interface PreparedStreamSource {
+  readonly mode: typeof FileTransferMode.Stream;
+  readonly stream: ReadableStream<Uint8Array>;
+  readonly size: number | undefined;
+  readonly filename?: string | undefined;
+  readonly contentType: string | undefined;
+  close(): Promise<void>;
+}
+/** Подготовленный файловый источник без правил конкретного протокола загрузки. */
+type PreparedFileSource = PreparedBufferSource | PreparedStreamSource;
+/** Контекст одной попытки открытия файлового источника. */
+interface ResolveFileContext {
+  readonly signal?: AbortSignal | undefined;
+  /** Номер попытки потребителя, начиная с 1. */
+  readonly attempt?: number | undefined;
+}
+/** Узкий файловый порт, доступный подключаемым предметным модулям. */
+interface FileResolver {
+  resolve(input: FileInput, options?: ResolveFileOptions, context?: ResolveFileContext): Promise<PreparedFileSource>;
+}
+/** Внутренний контракт нужен `FilesResource` для сохранения семантики повторных попыток. */
+interface InternalFileResolver extends FileResolver {
+  mode(input: FileInput): FileTransferMode;
+}
+//#endregion
+//#region src/core/managed-resources.d.ts
+/** Долгоживущий ресурс клиента. */
+interface ManagedClientResource {
+  /** Короткое имя для диагностики зависшей остановки. */
+  readonly kind: string;
+  /** Синхронно прекращает принимать новую работу и запускает отмену. */
+  stop(): void;
+  /** Завершается после остановки обработчиков и освобождения внешних ресурсов. */
+  drain(): Promise<void>;
 }
 //#endregion
 //#region src/core/features.d.ts
 /** Параметры запроса feature: маршрут задаёт ресурс, transport metadata — manifest. */
 type FeatureRequestOptions = Omit<RawRequestOptions, 'operationId' | 'method' | 'service' | 'baseUrl' | 'retrySafety' | 'rateLimitBucket'>;
 /** Операция одного feature. Локальный ключ используется в {@link FeatureContext.request}. */
-interface FeatureOperationDefinition {
+interface FeatureOperationDefinition<T = unknown> {
   readonly method: OperationMethod;
   readonly retrySafety: RetrySafety;
   /** Имя сервиса из {@link ClientFeature.services}; без него используется основной API. */
   readonly service?: string | undefined;
   /** Локальное имя бакета из {@link ClientFeature.buckets}. */
   readonly bucket?: string | undefined;
+  /** Преобразует тело ответа в публичный результат операции. По умолчанию возвращает тело без изменений. */
+  readonly read?: OperationContract<T>['read'] | undefined;
+  /** Необязательные метаданные, интерпретируемые подключёнными плагинами. */
+  readonly annotations?: OperationAnnotations | undefined;
 }
 /** Начальные ограничения нового серверного счётчика feature. */
 interface FeatureBucketDefinition extends RateLimitBucketOverride {}
@@ -151,178 +417,30 @@ interface ClientFeature<TApi> {
   readonly buckets?: Readonly<Record<string, FeatureBucketDefinition>> | undefined;
   setup(context: FeatureContext): FeatureInstallation<TApi>;
 }
-/** Ограниченный доступ feature к общему runtime клиента. */
+/** Доступ подключаемого модуля к клиенту. */
 interface FeatureContext {
   readonly featureName: string;
   readonly baseUrl: string;
   readonly signal: AbortSignal;
   readonly clock: ItdClock;
   readonly logger: Logger | undefined;
-  /** Выполняет объявленную операцию через общие auth, plugins, retry и очереди клиента. */
-  request<T = unknown>(operation: string, options: FeatureRequestOptions): Promise<T>;
-  /** Возвращает фактический URL объявленного сервиса с учётом настроек клиента. */
-  serviceBaseUrl(name: string): string;
-}
-//#endregion
-//#region src/core/plugins/contracts.d.ts
-/**
- * Обёртка одной логической операции.
- *
- * Вызывается ровно один раз независимо от retry и auth recovery. Может изменить
- * семантический запрос, обработать разобранный результат или завершить операцию локально.
- *
- * @param request описание логической операции; не изменяйте сам объект — передайте копию в `next`
- * @param next следующая обёртка либо выполнение операции
- * @returns разобранный результат в том виде, в котором его получит вызывающий код
- *
- * @example Дописать заголовок ко всем операциям
- * ```ts
- * const transformer: OperationTransformer = (request, next) =>
- *   next({ ...request, headers: { ...request.headers, 'X-Trace': trace() } });
- * ```
- */
-type OperationTransformer = (request: OperationRequestOptions, next: (request: OperationRequestOptions) => Promise<unknown>) => Promise<unknown>;
-/** Финальные данные одной транспортной попытки. */
-interface AttemptContext {
-  /** Стабильная семантическая операция. */
-  readonly operationId: OperationId;
-  /** Нормализованный HTTP-метод. */
-  readonly method: string;
-  /** Исходный путь операции до разрешения service/base URL. */
-  readonly path: string;
-  /** Полностью разрешённый URL со строкой query. */
-  readonly url: string;
-  /** Итоговые заголовки. Сам объект mutable для подписи и diagnostic headers. */
-  readonly headers: Headers;
-  /** Номер transport attempt, начиная с 1. */
-  readonly attempt: number;
-  /** Тело после сериализации либо подготовки body factory. Поток нельзя читать заранее. */
-  readonly body: BodyInit | undefined;
-  /** Общий сигнал отмены и таймаута этой попытки. */
-  readonly signal: AbortSignal;
-}
-/**
- * Продолжение attempt chain.
- *
- * В рамках одного interceptor его можно вызвать только один раз. Возвращает сырой ответ:
- * transport ещё не проверял status и не читал body.
- */
-type AttemptNext = () => Promise<Response>;
-/**
- * Обёртка одной транспортной попытки.
- *
- * Получает уже разрешённый URL, итоговые заголовки, подготовленное тело и номер попытки.
- * Может дописать заголовки, измерить wire latency, обработать сырой `Response` или вернуть
- * синтетический `Response`. Семантический input здесь намеренно недоступен для изменения.
- *
- * Вызывается заново для каждого retry и auth recovery. `next()` разрешено вызвать один раз.
- * Если interceptor читает тело ответа, читать нужно `response.clone()`: исходный body после
- * цепочки разбирает transport. Исключение interceptor остаётся пользовательской ошибкой и не
- * классифицируется как сетевой сбой для автоматического retry.
- *
- * @param context окончательные данные текущей транспортной попытки
- * @param next следующий interceptor либо вызов `fetch`
- * @returns исходный или синтетический сырой `Response`
- */
-type AttemptInterceptor = (context: AttemptContext, next: AttemptNext) => Promise<Response>;
-/** Регистрация расширений логической операции. */
-interface OperationExtensions {
-  /**
-   * Подключает transformer.
-   *
-   * Зарегистрированные раньше оборачивают зарегистрированные позже. Возвращённая функция
-   * идемпотентна и снимает только эту регистрацию.
-   */
-  use(transformer: OperationTransformer): Unsubscribe;
-}
-/** Регистрация расширений транспортной попытки. */
-interface AttemptExtensions {
-  /**
-   * Подключает interceptor.
-   *
-   * Зарегистрированные раньше оборачивают зарегистрированные позже. Возвращённая функция
-   * идемпотентна и снимает только эту регистрацию.
-   */
-  use(interceptor: AttemptInterceptor): Unsubscribe;
-}
-/**
- * Освобождение ресурсов, заведённых плагином при установке.
- *
- * Вызывается после завершения логических операций, уже вошедших в расширения плагина,
- * поэтому может безопасно закрывать используемые ими соединения и хранилища.
- */
-type PluginTeardown = () => void | Promise<void>;
-/** API, доступный плагину при подключении. */
-interface PluginApi {
-  /** Базовый URL клиента — например чтобы разобрать абсолютные ссылки из ответа. */
-  baseUrl: string;
-  /** Отладочный вывод клиента, если он включён. */
-  logger: Logger | undefined;
-  /** Расширения логической операции: выполняются один раз и могут short-circuit сеть. */
-  operations: OperationExtensions;
-  /** Расширения wire attempt: выполняются заново после каждого retry/auth recovery. */
-  attempts: AttemptExtensions;
-  /**
-   * Непрозрачная fallback-область текущей авторизации.
-   *
-   * Нужна плагинам, которые обязаны безопасно изолировать непрозрачный токен. Для объединения
-   * состояния копий одного аккаунта используйте {@link getAuthIdentity}.
-   */
-  getAuthScope?: (() => string) | undefined;
-  /**
-   * Загружает сессию и возвращает идентификаторы аккаунта и конкретной сессии из JWT.
-   *
-   * Предпочтительнее {@link getAuthScope} для состояния, которое должно объединяться между
-   * несколькими экземплярами клиента одного аккаунта.
-   */
-  getAuthIdentity?: (() => Promise<AuthIdentity>) | undefined;
-}
-/**
- * Плагин клиента.
- *
- * Подключается через `itd.use(plugin)` и регистрирует расширения одного или обоих уровней:
- * {@link OperationTransformer} для логической операции и {@link AttemptInterceptor} для
- * отдельной транспортной попытки. Core взаимодействует с плагином только через эти контракты
- * и его lifecycle, не зная деталей реализации.
- *
- * Настройки отдельного вызова плагин объявляет своим полем в `RequestExtensions` через
- * declaration merging. Пользователь передаёт их в `RequestOptions.extensions`, а operation
- * transformer читает только принадлежащий плагину namespace.
- *
- * @example Логирование логических операций
- * ```ts
- * const logging: ClientPlugin = {
- *   name: 'logging',
- *   install({ operations, logger }) {
- *     operations.use(async (request, next) => {
- *       logger?.info(`${request.method} ${request.path}`);
- *       return next(request);
- *     });
- *   },
- * };
- *
- * itd.use(logging);
- * ```
- */
-interface ClientPlugin {
-  /** Имя плагина. Должно быть уникальным: повторное подключение — ошибка. */
-  name: string;
-  /** Плагины, которые обязаны быть подключены раньше этого. */
-  requires?: readonly string[];
-  /** Несовместимые плагины. Достаточно объявить конфликт с одной стороны. */
-  conflicts?: readonly string[];
-  /** Имена плагинов, снаружи которых должны стоять оба вида расширений этого плагина. */
-  before?: readonly string[];
-  /** Имена плагинов, внутри которых должны стоять оба вида расширений этого плагина. */
-  after?: readonly string[];
+  /** Открывает файловый источник без правил конкретного протокола загрузки. */
+  readonly files: FileResolver;
   /**
-   * Устанавливает плагин.
+   * Выполняет объявленную операцию через авторизацию, плагины, повторы и очередь клиента.
    *
-   * Может вернуть функцию освобождения ресурсов. Она вызывается при `unuse()` или
-   * окончательном `dispose()` клиента и может быть асинхронной. Сам `install()` синхронный:
-   * регистрация расширений завершается до того, как `use()` вернёт управление.
+   * Форма результата задаётся один раз полем `read` в описании операции. Плагины получают
+   * готовый результат и не видят функцию преобразования.
    */
-  install(api: PluginApi): void | PluginTeardown;
+  request<T = unknown>(operation: string, options: FeatureRequestOptions): Promise<T>;
+  /** Возвращает фактический URL объявленного сервиса с учётом настроек клиента. */
+  serviceBaseUrl(name: string): string;
+  /** Окружение долговременного соединения объявленного сервиса. */
+  connection(name: string): ClientConnection;
+  /** Регистрирует активный долгоживущий ресурс до его остановки. */
+  manage(resource: ManagedClientResource): () => void;
+  /** Проверяет, что создавший модуль клиент ещё работает. */
+  assertActive(action: string): void;
 }
 //#endregion
 //#region src/core/scheduling/rate-limit.d.ts
@@ -341,48 +459,6 @@ interface RateLimitBucketState {
   pending: number;
 }
 //#endregion
-//#region src/models/account.d.ts
-/** Активная сессия входа. */
-interface Session {
-  id: string;
-  /** Та ли это сессия, из которой выполнен запрос. */
-  isCurrent: boolean;
-  createdAt: IsoDate;
-  lastUsedAt: IsoDate;
-  expiresAt: IsoDate;
-  ipAddress: string;
-  /** Код страны по IP, например `RU`. */
-  ipCountry: string | null;
-  ipCity: string | null;
-  deviceType: Loose<'desktop' | 'mobile'>;
-  osName: string | null;
-  osVersion: string | null;
-  /** Название браузера или приложения. */
-  clientName: string | null;
-  clientVersion: string | null;
-  deviceModel: string | null;
-}
-/** Состояние платной подписки и её цена. */
-interface Subscription {
-  /** Активна ли подписка сейчас. */
-  active: boolean;
-  /** Включено ли автопродление. */
-  recurringEnabled: boolean;
-  /** Цена в рублях. */
-  price: number;
-}
-/** Сохранённый способ оплаты. */
-interface PaymentMethod {
-  id: string;
-  /** Последние четыре цифры карты. */
-  last4?: string;
-  /** Платёжная система: `visa`, `mastercard`, `mir`. */
-  brand?: string;
-  /** Основной ли это способ оплаты. */
-  isDefault?: boolean;
-  expiresAt?: IsoDate | null;
-}
-//#endregion
 //#region src/resources/pagination.d.ts
 /**
  * Страница списка — единая форма для всех трёх схем пагинации API.
@@ -520,13 +596,11 @@ declare class Paginator<T> implements AsyncIterable<T> {
  */
 interface ListingSpec<T, P extends object> {
   /** Стабильная семантическая операция списка. */
-  operationId: BuiltInOperationId | ((params: P) => BuiltInOperationId);
+  operation: OperationContract<Page<T>, BuiltInOperationId> | ((params: P) => OperationContract<Page<T>, BuiltInOperationId>);
   /** Путь эндпоинта. */
   path: (params: P) => string;
   /** Параметры запроса без полей пагинации — их добавит перебор. */
   query: (params: P) => QueryParams;
-  /** Читает страницу из ответа. Получает позицию — она нужна схеме со смещением. */
-  read: (body: unknown, state: PageState) => Page<T>;
   /** Схема пагинации эндпоинта. */
   mode: PaginationMode;
   /** Начальная позиция, вычисленная из параметров (курсор, номер или смещение). */
@@ -544,6 +618,8 @@ declare class BaseResource {
   /** @internal */
   protected readonly http: HttpClient;
   constructor(http: HttpClient);
+  /** Выполняет операцию без возвращаемого значения и отбрасывает служебное тело ответа. */
+  protected voidOperation(operation: OperationContract<void, BuiltInOperationId>, options: HttpOperationOptions): Promise<void>;
   /**
    * Собирает перебор страниц.
    *
@@ -563,11 +639,10 @@ declare class BaseResource {
    * @example
    * ```ts
    * #feed = this.paginated<Post, FeedParams>({
-   *   operationId: 'posts.list',
+   *   operation: POSTS_LIST,
    *   path: () => '/api/posts',
    *   query: (p) => ({ tab: p.tab, limit: p.limit }),
    *   start: (p) => (p.cursor ? { cursor: p.cursor } : {}),
-   *   read: (body) => readCursorPage<Post>(body, 'posts'),
    *   mode: PaginationMode.Cursor,
    * });
    * ```
@@ -575,6 +650,118 @@ declare class BaseResource {
   protected paginated<T, P extends object>(spec: ListingSpec<T, P>): Listing<T, P>;
 }
 //#endregion
+//#region src/resources/notifications.d.ts
+/** Параметры запроса списка уведомлений. */
+interface NotificationListParams {
+  limit?: number;
+  /** Смещение от начала списка. */
+  offset?: number;
+}
+/** Изменяемые настройки уведомлений. */
+type UpdateNotificationSettingsInput = Partial<NotificationSettings>;
+/**
+ * Уведомления: список, счётчик, отметки о прочтении, настройки.
+ *
+ * Доступна как `itd.notifications`. Все уведомления приведены к единой форме, поэтому
+ * объекты отсюда и из потока событий можно складывать в один список.
+ */
+declare class NotificationsResource extends BaseResource {
+  #private;
+  /**
+   * Загружает страницу уведомлений.
+   *
+   * Пагинация здесь основана на смещении.
+   *
+   * @example
+   * ```ts
+   * const page = await itd.notifications.list({ limit: 20 });
+   * const next = await itd.notifications.list({ limit: 20, offset: page.nextOffset });
+   * ```
+   */
+  list(params?: NotificationListParams, options?: RequestOptions): Promise<Page<Notification>>;
+  /**
+   * Перебирает уведомления.
+   *
+   * @example
+   * ```ts
+   * for await (const notification of itd.notifications.iterate()) {
+   *   console.log(formatNotificationText(notification));
+   * }
+   * ```
+   */
+  iterate(params?: NotificationListParams, options?: PaginationOptions): Paginator<Notification>;
+  /** Загружает число непрочитанных уведомлений. */
+  count(options?: RequestOptions): Promise<number>;
+  /**
+   * Отмечает уведомление прочитанным.
+   *
+   * @returns сколько записей отметил сервер
+   */
+  markRead(notificationId: string, options?: RequestOptions): Promise<number>;
+  /**
+   * Отмечает прочитанными сразу несколько уведомлений.
+   *
+   * Список автоматически режется на части по 20 идентификаторов — столько же отправляет
+   * сайт итд.com, поэтому на сервере вероятен предел. Части уходят последовательно,
+   * результат суммируется.
+   *
+   * @returns сколько записей отметил сервер суммарно
+   */
+  markReadBatch(ids: string[], options?: RequestOptions): Promise<number>;
+  /** Отмечает прочитанными все уведомления. */
+  markAllRead(options?: RequestOptions): Promise<number>;
+  /** Загружает настройки уведомлений. */
+  getSettings(options?: RequestOptions): Promise<NotificationSettings>;
+  /**
+   * Обновляет настройки уведомлений.
+   *
+   * Отправляются только изменяемые поля, в том же виде, в каком сервер их возвращает.
+   */
+  updateSettings(input: UpdateNotificationSettingsInput, options?: RequestOptions): Promise<NotificationSettings>;
+}
+//#endregion
+//#region src/models/account.d.ts
+/** Активная сессия входа. */
+interface Session {
+  id: string;
+  /** Та ли это сессия, из которой выполнен запрос. */
+  isCurrent: boolean;
+  createdAt: IsoDate;
+  lastUsedAt: IsoDate;
+  expiresAt: IsoDate;
+  ipAddress: string;
+  /** Код страны по IP, например `RU`. */
+  ipCountry: string | null;
+  ipCity: string | null;
+  deviceType: Loose<'desktop' | 'mobile'>;
+  osName: string | null;
+  osVersion: string | null;
+  /** Название браузера или приложения. */
+  clientName: string | null;
+  clientVersion: string | null;
+  deviceModel: string | null;
+}
+/** Состояние платной подписки и её цена. */
+interface Subscription {
+  /** Активна ли подписка сейчас. */
+  active: boolean;
+  /** Включено ли автопродление. */
+  recurringEnabled: boolean;
+  /** Цена в рублях. */
+  price: number;
+}
+/** Сохранённый способ оплаты. */
+interface PaymentMethod {
+  id: string;
+  /** Последние четыре цифры карты. */
+  last4?: string;
+  /** Платёжная система: `visa`, `mastercard`, `mir`. */
+  brand?: string;
+  /** Основной ли это способ оплаты. */
+  isDefault?: boolean;
+  expiresAt?: IsoDate | null;
+}
+//#endregion
 //#region src/domain/params.d.ts
 /** Данные для создания опроса. */
 interface CreatePollInput {
@@ -973,7 +1160,7 @@ interface UploadOptions {
 declare class FilesResource extends BaseResource {
   #private;
   constructor(http: HttpClient, deps: {
-    fetch: typeof fetch;
+    files: InternalFileResolver;
   });
   /**
    * Загружает файл и возвращает его идентификатор.
@@ -1030,76 +1217,6 @@ declare class HashtagsResource extends BaseResource {
   iteratePosts(tag: string, params?: HashtagPostsParams, options?: PaginationOptions): Paginator<Post>;
 }
 //#endregion
-//#region src/resources/notifications.d.ts
-/** Параметры запроса списка уведомлений. */
-interface NotificationListParams {
-  limit?: number;
-  /** Смещение от начала списка. */
-  offset?: number;
-}
-/** Изменяемые настройки уведомлений. */
-type UpdateNotificationSettingsInput = Partial<NotificationSettings>;
-/**
- * Уведомления: список, счётчик, отметки о прочтении, настройки.
- *
- * Доступна как `itd.notifications`. Все уведомления приведены к единой форме, поэтому
- * объекты отсюда и из потока событий можно складывать в один список.
- */
-declare class NotificationsResource extends BaseResource {
-  #private;
-  /**
-   * Загружает страницу уведомлений.
-   *
-   * Пагинация здесь основана на смещении.
-   *
-   * @example
-   * ```ts
-   * const page = await itd.notifications.list({ limit: 20 });
-   * const next = await itd.notifications.list({ limit: 20, offset: page.nextOffset });
-   * ```
-   */
-  list(params?: NotificationListParams, options?: RequestOptions): Promise<Page<Notification>>;
-  /**
-   * Перебирает уведомления.
-   *
-   * @example
-   * ```ts
-   * for await (const notification of itd.notifications.iterate()) {
-   *   console.log(formatNotificationText(notification));
-   * }
-   * ```
-   */
-  iterate(params?: NotificationListParams, options?: PaginationOptions): Paginator<Notification>;
-  /** Загружает число непрочитанных уведомлений. */
-  count(options?: RequestOptions): Promise<number>;
-  /**
-   * Отмечает уведомление прочитанным.
-   *
-   * @returns сколько записей отметил сервер
-   */
-  markRead(notificationId: string, options?: RequestOptions): Promise<number>;
-  /**
-   * Отмечает прочитанными сразу несколько уведомлений.
-   *
-   * Список автоматически режется на части по 20 идентификаторов — столько же отправляет
-   * сайт итд.com, поэтому на сервере вероятен предел. Части уходят последовательно,
-   * результат суммируется.
-   *
-   * @returns сколько записей отметил сервер суммарно
-   */
-  markReadBatch(ids: string[], options?: RequestOptions): Promise<number>;
-  /** Отмечает прочитанными все уведомления. */
-  markAllRead(options?: RequestOptions): Promise<number>;
-  /** Загружает настройки уведомлений. */
-  getSettings(options?: RequestOptions): Promise<NotificationSettings>;
-  /**
-   * Обновляет настройки уведомлений.
-   *
-   * Отправляются только изменяемые поля, в том же виде, в каком сервер их возвращает.
-   */
-  updateSettings(input: UpdateNotificationSettingsInput, options?: RequestOptions): Promise<NotificationSettings>;
-}
-//#endregion
 //#region src/models/platform.d.ts
 /** Клан в рейтинге. */
 interface Clan {
@@ -2307,5 +2424,5 @@ interface RenderSpansOptions {
  */
 declare function renderSpans(content: string, spans?: readonly Span[] | null | undefined, options?: RenderSpansOptions): string;
 //#endregion
-export { poll as $, CreatePostData as $t, TelemetryResource as A, FilesResource as At, ReportInput as B, PinPostResult as Bt, DwellEntry as C, FeatureBucketDefinition as Cn, Report as Ct, TelemetryBatchOptions as D, FeatureRequestOptions as Dn, UpdateNotificationSettingsInput as Dt, TelemetryBatch as E, FeatureOperationDefinition as En, NotificationsResource as Et, SubscriptionResource as F, Attachment as Ft, UserPostsParams as G, CommentBuilder as Gt, CommentsParams as H, PollOption as Ht, SearchResource as I, Comment as It, PostInput as J, BuilderInput as Jt, CreatePostInput as K, CommentInput as Kt, SearchResult as L, CommentReplyTo as Lt, ViewTracker as M, UploadedFile as Mt, ViewTrackerInput as N, CommentsResource as Nt, TelemetryClock as O, HttpClient as On, HashtagPostsParams as Ot, ViewTrackerOptions as P, RepliesParams as Pt, PollInput as Q, CreatePollInput as Qt, ReportsResource as R, Hashtag as Rt, UsersResource as S, ClientFeature as Sn, Portal as St, PhotoOpenInput as T, FeatureInstallation as Tn, NotificationListParams as Tt, FeedParams as U, Post as Ut, report as V, Poll as Vt, PostsResource as W, PostStats as Wt, post as X, isBuilder as Xt, PostUpdateInput as Y, ItdBuilder as Yt, PollBuilder as Z, CreateCommentInput as Zt, fromUrl as _, ClientPlugin as _n, StatusIncidentLine as _t, isMyProfile as a, PaginationMode as an, MarkupContent as at, UpdateProfileInput as b, PluginApi as bn, ChangelogEntry as bt, ALLOWED_MIME_TYPES as c, mapPage as cn, TextMarkup as ct, AudioMimeType as d, Subscription as dn, PlatformClientVersion as dt, CreateReportInput as en, ParseMarkupOptions as et, IMAGE_MIME_TYPES as f, RateLimitBucketState as fn, PlatformResource as ft, fromStream as g, AttemptNext as gn, StatusDay as gt, VideoMimeType as h, AttemptInterceptor as hn, ServiceStatus as ht, statusDays as i, PageState as in, MarkupBuilder as it, VideoProgressInput as j, UploadOptions as jt, TelemetryOptions as k, RequestHandler as kn, HashtagsResource as kt, AUDIO_MIME_TYPES as l, PaymentMethod as ln, autoSpans as lt, VIDEO_MIME_TYPES as m, AttemptExtensions as mn, PlatformStatus as mt, SpanRenderFormat as n, BaseResource as nn, parseMarkdown as nt, toDate as o, Paginator as on, MarkupInput as ot, ImageMimeType as p, AttemptContext as pn, PlatformVersions as pt, PostBuilder as q, comment as qt, renderSpans as r, Page as rn, AutoSpansOptions as rt, utcStampToIso as s, PaginatorOptions as sn, MarkupSpan as st, RenderSpansOptions as t, UpdatePostInput as tn, parseHtml as tt, AllowedMimeType as u, Session as un, markup as ut, VerificationResource as v, OperationExtensions as vn, Announcement as vt, InteractionEntry as w, FeatureContext as wn, VerificationStatus as wt, UserListParams as x, PluginTeardown as xn, Clan as xt, UpdatePrivacyInput as y, OperationTransformer as yn, AnnouncementButton as yt, ReportBuilder as z, LikeResult as zt };
-//# sourceMappingURL=render-CgwKdOzu.d.ts.map
+export { poll as $, PaymentMethod as $t, TelemetryResource as A, AttemptNext as An, CommentsResource as At, ReportInput as B, Post as Bt, DwellEntry as C, PreparedStreamSource as Cn, Report as Ct, TelemetryBatchOptions as D, AttemptContext as Dn, FilesResource as Dt, TelemetryBatch as E, HttpClient as En, HashtagsResource as Et, SubscriptionResource as F, PluginTeardown as Fn, Hashtag as Ft, UserPostsParams as G, BuilderInput as Gt, CommentsParams as H, CommentBuilder as Ht, SearchResource as I, LikeResult as It, PostInput as J, CreateCommentInput as Jt, CreatePostInput as K, ItdBuilder as Kt, SearchResult as L, PinPostResult as Lt, ViewTracker as M, OperationExtensions as Mn, Attachment as Mt, ViewTrackerInput as N, OperationTransformer as Nn, Comment as Nt, TelemetryClock as O, AttemptExtensions as On, UploadOptions as Ot, ViewTrackerOptions as P, PluginApi as Pn, CommentReplyTo as Pt, PollInput as Q, UpdatePostInput as Qt, ReportsResource as R, Poll as Rt, UsersResource as S, PreparedFileSource as Sn, Portal as St, PhotoOpenInput as T, ResolveFileOptions as Tn, HashtagPostsParams as Tt, FeedParams as U, CommentInput as Ut, report as V, PostStats as Vt, PostsResource as W, comment as Wt, post as X, CreatePostData as Xt, PostUpdateInput as Y, CreatePollInput as Yt, PollBuilder as Z, CreateReportInput as Zt, fromUrl as _, FeatureOperationDefinition as _n, StatusIncidentLine as _t, isMyProfile as a, BaseResource as an, MarkupContent as at, UpdateProfileInput as b, FileResolver as bn, ChangelogEntry as bt, ALLOWED_MIME_TYPES as c, PaginationMode as cn, TextMarkup as ct, AudioMimeType as d, mapPage as dn, PlatformClientVersion as dt, Session as en, ParseMarkupOptions as et, IMAGE_MIME_TYPES as f, RateLimitBucketState as fn, PlatformResource as ft, fromStream as g, FeatureInstallation as gn, StatusDay as gt, VideoMimeType as h, FeatureContext as hn, ServiceStatus as ht, statusDays as i, UpdateNotificationSettingsInput as in, MarkupBuilder as it, VideoProgressInput as j, ClientPlugin as jn, RepliesParams as jt, TelemetryOptions as k, AttemptInterceptor as kn, UploadedFile as kt, AUDIO_MIME_TYPES as l, Paginator as ln, autoSpans as lt, VIDEO_MIME_TYPES as m, FeatureBucketDefinition as mn, PlatformStatus as mt, SpanRenderFormat as n, NotificationListParams as nn, parseMarkdown as nt, toDate as o, Page as on, MarkupInput as ot, ImageMimeType as p, ClientFeature as pn, PlatformVersions as pt, PostBuilder as q, isBuilder as qt, renderSpans as r, NotificationsResource as rn, AutoSpansOptions as rt, utcStampToIso as s, PageState as sn, MarkupSpan as st, RenderSpansOptions as t, Subscription as tn, parseHtml as tt, AllowedMimeType as u, PaginatorOptions as un, markup as ut, VerificationResource as v, FeatureRequestOptions as vn, Announcement as vt, InteractionEntry as w, ResolveFileContext as wn, VerificationStatus as wt, UserListParams as x, PreparedBufferSource as xn, Clan as xt, UpdatePrivacyInput as y, ManagedClientResource as yn, AnnouncementButton as yt, ReportBuilder as z, PollOption as zt };
+//# sourceMappingURL=render-DVB7T8pm.d.ts.map