itd-api 0.7.2 → 0.9.0

package/dist/shared/events-DGAWlCaI.d.cts

@@ -0,0 +1,698 @@
+import { Bt as ItdClock, Ft as QueryParams, Pt as RuntimeOptions, a as NotificationEvent, bt as Logger, ct as Unsubscribe, et as ClientConnection, mn as NotificationType, nt as AuthProvider, s as Notification, sn as EventChannelStatus, st as Listener, tt as AuthIdentity } from "./url-XBsMdAcv.cjs";
+//#region src/events/transports/transport.d.ts
+/** Идентификаторы операций транспорта уведомлений. */
+type EventOperationId = 'events.notifications.poll.updates' | 'events.notifications.poll.unread';
+/** Запрос транспорта к конвейеру клиента. */
+interface EventRequestInput {
+  operationId: EventOperationId;
+  path: string;
+  query?: QueryParams | undefined;
+  /**
+   * Сигнал отмены текущей попытки соединения.
+   */
+  signal?: AbortSignal | undefined;
+}
+/**
+ * Запрос через очередь, авторизацию, повторы, плагины и обработчики клиента.
+ *
+ * Ответ приходит уже разобранным и без обёртки `{ data: … }`, а неудача — типизированной
+ * ошибкой библиотеки.
+ */
+type EventRequest = (input: EventRequestInput) => Promise<unknown>;
+/** Событие, пришедшее по каналу реального времени. */
+interface EventTransportFrame {
+  /** Имя события: `notification`, `unread_count` и другие. */
+  name: string;
+  /** Полезная нагрузка, уже разобранная из JSON. */
+  data: unknown;
+}
+/** Что транспорт получает от клиента при подключении. */
+interface EventTransportContext extends Pick<ClientConnection, 'baseUrl' | 'authorize' | 'fetch' | 'baseHeaders' | 'getToken'> {
+  /** Отмена подключения. */
+  signal: AbortSignal;
+  /** Сообщает о полученном событии. */
+  onEvent: (event: EventTransportFrame) => void;
+  /** Сообщает о разобранном, но некорректном сообщении. Соединение при этом живёт. */
+  onParseError: (error: unknown, raw: string) => void;
+  /** Вызывается, когда соединение установлено. */
+  onOpen: () => void;
+}
+/** Канал получения исходных событий в реальном времени. */
+interface EventTransport {
+  /** Понятное имя для логов и диагностики. */
+  readonly name: string;
+  /**
+   * Держит соединение, пока оно живо.
+   *
+   * Должен завершиться, когда поток закрылся, и бросить исключение при ошибке.
+   * Отмена через `context.signal` должна приводить к `AbortError`.
+   */
+  connect(context: EventTransportContext): Promise<void>;
+}
+/** Ошибка, по которой видно, что сервер отверг авторизацию потока. */
+declare class UnauthorizedStreamError extends Error {
+  constructor();
+}
+//#endregion
+//#region src/events/updates.d.ts
+/** Типы нормализованных обновлений потока. */
+declare const NotificationUpdateType: Readonly<{
+  readonly Notification: "notification";
+  readonly UnreadCount: "unreadCount";
+  readonly Unknown: "unknown";
+}>;
+/** Источники нормализованных обновлений потока. */
+declare const NotificationUpdateOrigin: Readonly<{
+  readonly Stream: "stream";
+  readonly Sync: "sync";
+}>;
+type NotificationUpdateOrigin = (typeof NotificationUpdateOrigin)[keyof typeof NotificationUpdateOrigin];
+/** Уведомление с типом, суженным фильтром потока. */
+type NotificationOfType<T extends NotificationType> = Omit<Notification, 'type'> & {
+  type: T;
+};
+/** Конверт уведомления с типом, суженным фильтром потока. */
+type NotificationEventOfType<T extends NotificationType> = Omit<NotificationEvent, 'notification'> & {
+  notification: NotificationOfType<T>;
+};
+/** Нормализованное уведомление из потока. */
+interface NotificationUpdate<T extends NotificationType = NotificationType> {
+  readonly type: typeof NotificationUpdateType.Notification;
+  readonly data: NotificationEventOfType<T>;
+}
+/** Актуальное число непрочитанных уведомлений. */
+interface UnreadCountUpdate {
+  readonly type: typeof NotificationUpdateType.UnreadCount;
+  readonly data: number;
+}
+/** Неизвестное библиотеке событие потока. */
+interface UnknownNotificationUpdate {
+  readonly type: typeof NotificationUpdateType.Unknown;
+  readonly name: string;
+  readonly data: unknown;
+}
+/** Данные, проходящие через промежуточные обработчики потока. */
+type NotificationEventsUpdate = NotificationUpdate | UnreadCountUpdate | UnknownNotificationUpdate;
+/** Тип нормализованного обновления потока. */
+type NotificationUpdateType = NotificationEventsUpdate['type'];
+/** Обновление потока указанного типа. */
+type NotificationUpdateOfType<T extends NotificationUpdateType> = Extract<NotificationEventsUpdate, {
+  type: T;
+}>;
+/**
+ * Общая форма контекста обработки: то, что есть у любого потока независимо от домена.
+ *
+ * Контекст — обычный объектный литерал, а не класс с геттерами и не `Object.freeze`:
+ * плагины-флейворы присваивают в него свои поля (`ctx.session = …`), а `@itd-api/hydrate`
+ * подменяет `update` и `stream` через `Object.defineProperty`.
+ *
+ * @typeParam U нормализованное обновление домена
+ * @typeParam S поток, который его получил
+ */
+interface EventContext<U = unknown, S = unknown, O = unknown> {
+  /** Нормализованные данные обновления. */
+  readonly update: U;
+  /** Поток, который получил обновление. */
+  readonly stream: S;
+  /** Исходный кадр транспорта. Для начальной REST-синхронизации равен `undefined`. */
+  readonly raw: EventTransportFrame | undefined;
+  /** Откуда получены данные. */
+  readonly origin: O;
+}
+/** Контекст обработки одного обновления потока уведомлений. */
+type NotificationEventContext<U extends NotificationEventsUpdate = NotificationEventsUpdate> = EventContext<U, NotificationEvents, NotificationUpdateOrigin>;
+/** Контекст уведомления с типом, суженным фильтром. */
+type NotificationContext<T extends NotificationType = NotificationType> = NotificationEventContext<NotificationUpdate<T>>;
+/** Условия отбора уведомлений. Все указанные поля объединяются через логическое И. */
+interface NotificationEventFilter<T extends NotificationType = NotificationType> {
+  /** Один или несколько канонических типов уведомления. */
+  type?: T | readonly T[];
+  /** Идентификатор хотя бы одного участника уведомления. */
+  actorId?: string;
+  /** Идентификатор объекта события. */
+  entityId?: string | null;
+  /** Идентификатор родительского объекта. */
+  parentEntityId?: string | null;
+  /** Дополнительная проверка после сопоставления полей. */
+  predicate?: (context: NotificationContext<T>) => boolean;
+}
+/** Краткая или объектная форма фильтра уведомлений. */
+type NotificationEventSelector<T extends NotificationType = NotificationType> = T | readonly T[] | NotificationEventFilter<T>;
+//#endregion
+//#region src/events/middleware.d.ts
+/** Продолжает цепочку промежуточных обработчиков потока. */
+type EventNext = () => Promise<void>;
+/** Обрабатывает обновление потока до его передачи подписчикам. */
+type EventMiddleware<C extends EventContext = NotificationEventContext> = (context: C, next: EventNext) => void | Promise<void>;
+/** Объект, предоставляющий снимок промежуточного обработчика потока. */
+interface EventMiddlewareObject<C extends EventContext = NotificationEventContext> {
+  middleware(): EventMiddleware<C>;
+}
+/** Асинхронный обработчик нормализованного обновления потока. */
+type EventHandler<C extends EventContext = NotificationEventContext> = (context: C) => unknown | Promise<unknown>;
+/** Условие отбора контекста потока. */
+type EventPredicate<C extends EventContext = NotificationEventContext> = (context: C) => boolean;
+/** Проверка, сужающая тип контекста потока. */
+type EventTypeGuard<C extends B, B extends EventContext = NotificationEventContext> = (context: B) => context is C;
+/** Ключи, по которым обновления нельзя обрабатывать одновременно. */
+type EventSequentializer<C extends EventContext = NotificationEventContext> = (context: C) => PropertyKey | readonly PropertyKey[] | undefined;
+/** Выполняет промежуточные обработчики по порядку и запрещает повторный вызов `next()`. */
+declare function runEventMiddleware<C extends EventContext>(middleware: readonly EventMiddleware<C>[], context: C, terminal: EventNext): Promise<void>;
+//#endregion
+//#region src/events/reconnect.d.ts
+/** Настройки переподключения. */
+interface ReconnectOptions {
+  /** Таблица пауз. Последнее значение действует для всех дальнейших попыток. */
+  backoff?: readonly number[];
+  /** Доля разброса, 0…1. */
+  jitter?: number;
+  /** Предел числа попыток. */
+  maxAttempts?: number;
+}
+//#endregion
+//#region src/events/engine.d.ts
+/** Зачем движок просит домен синхронизироваться. */
+type EventSyncReason = 'initial' | 'reconnect';
+/** Параметры постановки доменного события из REST или другого внешнего источника. */
+interface EventEnqueueOptions<O = unknown> {
+  readonly origin: O;
+  readonly raw?: EventTransportFrame | undefined;
+}
+/** Контекст одной попытки подключения, теряющий актуальность после её завершения. */
+interface EventSession<U, O = unknown> {
+  readonly signal: AbortSignal;
+  /** Завершается только после фактического `EventTransportContext.onOpen` этой попытки. */
+  readonly opened: Promise<void>;
+  /** Ставит нормализованное событие только пока эта попытка актуальна. */
+  enqueue(update: U, options: EventEnqueueOptions<O>): void;
+}
+/**
+ * События, которые движок рассылает сам.
+ *
+ * Ни одно из них не зависит от домена, поэтому они одинаковы у любого потока.
+ * Домен расширяет эту карту своими событиями.
+ */
+interface EventChannelEvents<C extends EventContext = EventContext> {
+  /** Изменилось состояние соединения. */
+  status: EventChannelStatus;
+  /** Соединение оборвалось; будет предпринята попытка переподключения. */
+  error: {
+    error: unknown;
+    willReconnect: boolean;
+  };
+  /** Сообщение не удалось разобрать. Соединение при этом продолжает работать. */
+  parseError: {
+    error: unknown;
+    raw: string;
+  };
+  /** Запланировано переподключение. */
+  reconnect: {
+    attempt: number;
+    delay: number;
+  };
+  /** Попытки исчерпаны — соединение восстановится только ручным `connect()`. */
+  giveup: undefined;
+  /** Любой исходный кадр транспорта. Отправляется до нормализации и обработчиков. */
+  message: EventTransportFrame;
+  /** Промежуточный обработчик потока завершился исключением. */
+  middlewareError: {
+    error: unknown;
+    context: C;
+  };
+  /** Обработчик обновления завершился исключением. */
+  handlerError: {
+    error: unknown;
+    context: C;
+  };
+}
+/**
+ * Что движок получает от домена.
+ *
+ * @typeParam U нормализованное обновление домена
+ * @typeParam C контекст обработки, который домен собирает вокруг обновления
+ *
+ */
+interface EventChannelDeps<U, C extends EventContext<U, unknown, O>, O = unknown> {
+  connection: ClientConnection;
+  clock?: ItdClock | undefined;
+  logger?: Logger | undefined;
+  transport: EventTransport;
+  /** Источник, который домен назначает нормализованным кадрам транспорта. */
+  streamOrigin: O;
+  /**
+   * Доменная обработка сырого кадра до нормализации. `true` — кадр поглощён и дальше
+   * не идёт. Нужна там, где кадр не является обновлением: у уведомлений так приходит
+   * `connected`.
+   */
+  handleFrame?: ((event: EventTransportFrame) => boolean) | undefined;
+  /** Превращает кадр в доменное обновление; `undefined` — кадр игнорируется. */
+  readUpdate: (event: EventTransportFrame) => U | undefined;
+  /**
+   * Ключ коалесцирования: ожидающее обновление с тем же ключом заменяется новым.
+   * `undefined` — обновление не коалесцируется.
+   */
+  coalesceKey?: ((update: U) => PropertyKey | undefined) | undefined;
+  /** Собирает контекст. Точка, куда домен добавляет свои поля и действия. */
+  createContext: (update: U, raw: EventTransportFrame | undefined, origin: O) => C;
+  /** Доставляет обновление доменным подписчикам после цепочки обработчиков. */
+  deliver: (update: U) => void;
+  /** Проверяет, можно ли запустить канал. */
+  connectGuard?: (() => void) | undefined;
+  /** Подготовка одной попытки соединения. */
+  initialize?: ((reason: EventSyncReason, session: EventSession<U, O>) => Promise<void>) | undefined;
+  /** Открывает транспорт до подготовки и накапливает выбранные кадры до её завершения. */
+  openBeforeInitialize?: boolean | undefined;
+  /** Ошибка подготовки отклоняет первый `connect()`. */
+  initializationRequired?: boolean | undefined;
+  /** Выбирает кадры, которые нужно накопить до завершения подготовки. По умолчанию все. */
+  bufferFrame?: ((event: EventTransportFrame) => boolean) | undefined;
+}
+/** Настройки движка: переподключение, параллелизм и реакция на среду. */
+interface EventChannelOptions<C extends EventContext = EventContext> extends ReconnectOptions {
+  /** Максимальное число одновременно обрабатываемых обновлений. По умолчанию 1. */
+  concurrency?: number | undefined;
+  /** Возвращает ключи обновлений, которые нельзя обрабатывать одновременно. */
+  sequentialize?: EventSequentializer<C> | undefined;
+  /** Переподключаться, когда вкладка снова становится видимой. По умолчанию `true`. */
+  reconnectOnVisible?: boolean | undefined;
+  /** Переподключаться при восстановлении сети. По умолчанию `true`. */
+  reconnectOnOnline?: boolean | undefined;
+}
+/** Проверяет настройки общей механики потока. */
+declare function resolveEventChannelOptions<C extends EventContext>(options?: EventChannelOptions<C>): Readonly<EventChannelOptions<C>>;
+/**
+ * Общая механика потока событий: соединение, переподключение с задержкой, обновление
+ * токена, реакция на среду, статусы и очередь обработчиков.
+ *
+ * Ничего не знает о домене: что считать обновлением, как собрать контекст и кому его
+ * доставить, решают {@link EventChannelDeps}. Поэтому один и тот же движок несёт
+ * и поток уведомлений, и любой другой.
+ *
+ */
+declare class EventChannel<U, C extends EventContext<U, unknown, O>, E extends EventChannelEvents<C> = EventChannelEvents<C>, O = unknown> {
+  #private;
+  constructor(deps: EventChannelDeps<U, C, O>, options?: EventChannelOptions<C>);
+  /** Текущее состояние соединения. */
+  get status(): EventChannelStatus;
+  /** Имя используемого транспорта. */
+  get transport(): string;
+  /** Подписывается на событие потока. @returns функция отписки */
+  on<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe;
+  /** Подписывается на одно срабатывание события потока. */
+  once<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe;
+  /** Рассылает доменное событие через общий эмиттер потока. */
+  emit<K extends keyof E>(event: K, payload: E[K]): void;
+  /** Снимает подписки на события. Обработчики обновлений и middleware остаются. */
+  removeAllListeners(): void;
+  /** Добавляет промежуточный обработчик. @returns функция его удаления */
+  use(middleware: EventMiddleware<C> | EventMiddlewareObject<C>): Unsubscribe;
+  /** Подписывает обработчик обновлений, подходящих под условие. */
+  onUpdate(predicate: EventPredicate<C>, handler: EventHandler<C>): Unsubscribe;
+  /**
+   * Поднимает соединение.
+   *
+   * Повторный вызов при уже живом соединении ничего не делает. Возвращает управление
+   * сразу после запуска: соединение живёт в фоне.
+   */
+  connect(): Promise<void>;
+  /** Закрывает соединение и отменяет запланированные попытки. */
+  disconnect(): void;
+  /**
+   * Ждёт обработчики и полное завершение уже остановленной сессии соединения.
+   *
+   * Работающий транспорт намеренно не блокирует `drain()`: сначала владелец вызывает
+   * {@link disconnect}, который синхронно отменяет сессию. После этого `drain()` ждёт
+   * завершения подготовки, транспорта и фонового обновления авторизации, включая их
+   * асинхронное освобождение ресурсов.
+   */
+  drain(): Promise<void>;
+}
+//#endregion
+//#region src/events/stream.d.ts
+/**
+ * События потока уведомлений.
+ *
+ * Общая часть — {@link EventChannelEvents}: статусы, ошибки и переподключение одинаковы
+ * у любого потока. Ниже — то, что есть только у уведомлений.
+ */
+interface NotificationEventsMap<C extends NotificationEventContext = NotificationEventContext> extends EventChannelEvents<C> {
+  /** Пришло новое уведомление. */
+  notification: NotificationEvent;
+  /**
+   * Сервер подтвердил подключение и назвал получателя событий.
+   *
+   * Приходит первым кадром сразу после установки соединения.
+   */
+  ready: {
+    userId: string | undefined;
+  };
+  /**
+   * Получено актуальное число непрочитанных.
+   *
+   * При подключении клиент может запросить начальное значение через REST. Затем событие
+   * возникает, только если счётчик пришёл в потоке. В остальных случаях обновляйте его
+   * в приложении либо запрашивайте `itd.notifications.count()`.
+   */
+  unreadCount: number;
+}
+/** Способ получения событий. */
+declare const NotificationEventsTransport: Readonly<{
+  /** Поток событий, если среда умеет читать тело по частям, иначе опрос. */
+  readonly Auto: "auto";
+  /** Поток `text/event-stream`. */
+  readonly Sse: "sse";
+  /** Периодический опрос REST. */
+  readonly Poll: "poll";
+}>;
+type NotificationEventsTransport = (typeof NotificationEventsTransport)[keyof typeof NotificationEventsTransport];
+/** Настройки потока уведомлений. */
+interface NotificationEventsOptions<C extends NotificationEventContext = NotificationEventContext> extends ReconnectOptions {
+  /**
+   * Транспорт. По умолчанию `auto`: поток событий, если среда умеет читать тело ответа
+   * по частям, иначе опрос.
+   *
+   * Можно передать и свою реализацию {@link EventTransport} — это пригодится, если
+   * у платформы появится WebSocket либо нужен нестандартный способ доставки.
+   */
+  transport?: NotificationEventsTransport | EventTransport;
+  /**
+   * Молчание сервера, после которого соединение считается мёртвым, мс. По умолчанию 90 000.
+   *
+   * Сервер не присылает keep-alive, поэтому без этой проверки оборванное соединение
+   * может незаметно «зависнуть».
+   */
+  idleTimeout?: number;
+  /**
+   * Сколько ждать ответа на запрос потока, прежде чем оборвать попытку, мс. По умолчанию
+   * 20 000. Защищает от зависания на установке соединения, когда {@link idleTimeout} ещё
+   * не действует. `0` отключает проверку. Только для потокового транспорта.
+   */
+  handshakeTimeout?: number;
+  /** Как часто опрашивать сервер, если используется запасной транспорт. */
+  pollInterval?: number;
+  /**
+   * Запрашивать число непрочитанных при подключении. По умолчанию `true`.
+   *
+   * Так поступает сайт итд.com: поток присылает только новые события, а начальное
+   * значение счётчика нужно получить отдельно.
+   */
+  syncCount?: boolean;
+  /**
+   * Переподключаться, когда вкладка снова становится видимой. По умолчанию `true`.
+   *
+   * Только в браузере. У сайта итд.com такой обработки нет, из-за чего вкладка,
+   * пролежавшая в фоне, может остаться без соединения.
+   */
+  reconnectOnVisible?: boolean;
+  /** Переподключаться при восстановлении сети. По умолчанию `true`. Только в браузере. */
+  reconnectOnOnline?: boolean;
+  /** Максимальное число одновременно обрабатываемых обновлений. По умолчанию 1. */
+  concurrency?: number;
+  /** Возвращает ключи обновлений, которые нельзя обрабатывать одновременно. */
+  sequentialize?: EventSequentializer<C>;
+}
+/** Что поток получает от клиента. */
+interface NotificationEventsDeps {
+  connection: ClientConnection;
+  /** Конвейер клиента — см. {@link EventTransportContext.request}. */
+  request?: EventRequest | undefined;
+  clock?: ItdClock;
+  /** Идентификаторы аккаунта и сессии создавшего поток клиента. */
+  getAuthIdentity?: (() => AuthIdentity) | undefined;
+  /** Непрозрачная область авторизации создавшего поток клиента. */
+  getAuthScope?: (() => string) | undefined;
+  /** Загружает начальное число непрочитанных. */
+  fetchUnreadCount: (signal: AbortSignal) => Promise<number>;
+  /** Вызывается при явном закрытии потока. */
+  onClose?: (() => void) | undefined;
+  /** Вызывается при запуске ранее закрытого потока. */
+  onConnect?: (() => void) | undefined;
+  logger?: Logger | undefined;
+}
+/**
+ * Поток уведомлений в реальном времени.
+ *
+ * Доступен как стабильное свойство `itd.notifications.events`. Соединение поднимается методом {@link connect}
+ * и держится само: обрывы, обновление токена и повторные попытки библиотека берёт на себя.
+ *
+ * Параметр типа задаёт форму контекста: плагин может расширить её своими полями
+ * (`NotificationEvents<NotificationEventContext & SessionFlavor<S>>`) и типизировать обработчики.
+ *
+ * @example
+ * ```ts
+ * import { NotificationType } from 'itd-api';
+ *
+ * const stream = itd.notifications.events;
+ *
+ * stream.onNotification(NotificationType.PostComment, async ({ update }) => {
+ *   await saveCommentNotification(update.data.notification);
+ * });
+ * stream.on('status', (status) => console.log('соединение:', status));
+ *
+ * await stream.connect();
+ * // …позже
+ * stream.disconnect();
+ * await stream.drain();
+ * ```
+ */
+declare class NotificationEvents<C extends NotificationEventContext = NotificationEventContext> {
+  #private;
+  /** @internal */
+  constructor(deps: NotificationEventsDeps, options?: NotificationEventsOptions<C>);
+  /** Текущее состояние соединения. */
+  get status(): EventChannelStatus;
+  /** Имя используемого транспорта. */
+  get transport(): string;
+  /** Базовый URL клиента, создавшего поток. @internal */
+  get baseUrl(): string;
+  /** Идентификаторы аккаунта и сессии клиента, создавшего поток. @internal */
+  getAuthIdentity(): AuthIdentity | undefined;
+  /** Непрозрачная область авторизации создавшего поток клиента. @internal */
+  getAuthScope(): string | undefined;
+  /** Подписывается на событие потока. @returns функция отписки */
+  on<K extends keyof NotificationEventsMap<C>>(event: K, listener: Listener<NotificationEventsMap<C>[K]>): Unsubscribe;
+  /** Подписывается на одно срабатывание. */
+  once<K extends keyof NotificationEventsMap<C>>(event: K, listener: Listener<NotificationEventsMap<C>[K]>): Unsubscribe;
+  /**
+   * Добавляет промежуточный обработчик или объект, предоставляющий его через `middleware()`.
+   *
+   * Обработчики выполняются в порядке регистрации. Если `next()` не вызван, обновление не
+   * передаётся дальше по цепочке, асинхронным обработчикам и слушателям событий.
+   *
+   * @returns функция удаления обработчика
+   */
+  use(middleware: EventMiddleware<C> | EventMiddlewareObject<C>): Unsubscribe;
+  /** Подписывает асинхронный обработчик на все нормализованные обновления. */
+  onUpdate(handler: EventHandler<C>): Unsubscribe;
+  /** Подписывает асинхронный обработчик на обновление указанного типа. */
+  onUpdate<T extends NotificationUpdateType>(type: T, handler: EventHandler<C & NotificationEventContext<NotificationUpdateOfType<T>>>): Unsubscribe;
+  /** Подписывает асинхронный обработчик по функции сужения типа. */
+  onUpdate<N extends C>(guard: EventTypeGuard<N, C>, handler: EventHandler<N>): Unsubscribe;
+  /** Подписывает асинхронный обработчик по пользовательскому условию. */
+  onUpdate(predicate: EventPredicate<C>, handler: EventHandler<C>): Unsubscribe;
+  /** Подписывает асинхронный обработчик на уведомления, подходящие под фильтр. */
+  onNotification<T extends NotificationType>(selector: NotificationEventSelector<T>, handler: EventHandler<C & NotificationContext<T>>): Unsubscribe;
+  /** Подписывает асинхронный обработчик по функции сужения типа уведомления. */
+  onNotification<N extends C & NotificationContext>(guard: (context: C & NotificationContext) => context is N, handler: EventHandler<N>): Unsubscribe;
+  /** Подписывает асинхронный обработчик по пользовательскому условию. */
+  onNotification(predicate: (context: C & NotificationContext) => boolean, handler: EventHandler<C & NotificationContext>): Unsubscribe;
+  /**
+   * Поднимает соединение.
+   *
+   * Повторный вызов при уже живом соединении ничего не делает — это защита от двойного
+   * подключения при перерисовке интерфейса.
+   *
+   * Возвращает управление сразу после запуска: соединение живёт в фоне.
+   *
+   * @throws если создавший поток клиент уже освобождён
+   */
+  connect(): Promise<void>;
+  /** Закрывает соединение и отменяет запланированные попытки. */
+  disconnect(): void;
+  /** Ждёт завершения принятых обновлений и освобождения ресурсов остановленной сессии. */
+  drain(): Promise<void>;
+  /** Снимает подписки `on()` и `once()`. Остальные обработчики остаются. */
+  removeAllListeners(): void;
+}
+//#endregion
+//#region src/events/client.d.ts
+/** Опции конструктора {@link NotificationEventsClient}. */
+interface NotificationEventsClientOptions<C extends NotificationEventContext = NotificationEventContext> extends RuntimeOptions, NotificationEventsOptions<C> {
+  /**
+   * Авторизация. Строка — сокращение для `bearerToken()`.
+   *
+   * Без неё поток идёт анонимно. Токен считается готовым: продлевать его клиент не умеет,
+   * а на отказ авторизации переподключение спрашивает токен заново. Сессия, которая входит
+   * по паролю и продлевает себя сама, живёт в полном `ItdClient`.
+   */
+  auth?: string | AuthProvider | undefined;
+}
+/**
+ * Поток уведомлений с собственным конвейером запросов.
+ *
+ * Тот же {@link NotificationEvents}, что доступен как `itd.notifications.events`, но собранный без полного клиента:
+ * ресурсы, билдеры и сессия сюда не входят. Нужен приложениям, которым от API нужны только
+ * события, — виджетам, счётчикам непрочитанного, фоновым слушателям.
+ *
+ * @example
+ * ```ts
+ * import { createNotificationEventsClient } from 'itd-api/events';
+ *
+ * await using stream = createNotificationEventsClient({ auth: token });
+ * stream.on('notification', ({ notification }) => console.log(notification.type));
+ * await stream.connect();
+ * ```
+ */
+declare class NotificationEventsClient<C extends NotificationEventContext = NotificationEventContext> extends NotificationEvents<C> {
+  #private;
+  constructor(options?: NotificationEventsClientOptions<C>);
+  /**
+   * Окончательно освобождает поток и его конвейер: отключает соединение, дожидается
+   * обработчиков и останавливает очередь запросов.
+   *
+   * Повторные вызовы возвращают тот же результат очистки.
+   */
+  dispose(): Promise<void>;
+  /** Позволяет использовать поток с `await using`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Создаёт поток уведомлений с собственным конвейером. Равнозначно конструктору
+ * {@link NotificationEventsClient}.
+ */
+declare function createNotificationEventsClient<C extends NotificationEventContext = NotificationEventContext>(options?: NotificationEventsClientOptions<C>): NotificationEventsClient<C>;
+//#endregion
+//#region src/events/router.d.ts
+/** Выбирает маршрут обновления. `undefined` и `null` означают отсутствие маршрута. */
+type EventRouteSelector<K extends PropertyKey, C extends EventContext = NotificationEventContext> = (context: C) => K | null | undefined | Promise<K | null | undefined>;
+/**
+ * Направляет обновления потока в именованные цепочки промежуточных обработчиков.
+ *
+ * @example
+ * ```ts
+ * import { EventRouter, NotificationUpdateType } from 'itd-api/events';
+ *
+ * const router = new EventRouter((context) => context.update.type);
+ * router.route(NotificationUpdateType.Notification, async (context, next) => {
+ *   if (context.update.type === NotificationUpdateType.Notification) {
+ *     await handleNotification(context.update.data.notification);
+ *   }
+ *   await next();
+ * });
+ * stream.use(router);
+ * ```
+ */
+declare class EventRouter<K extends PropertyKey = PropertyKey, C extends EventContext = NotificationEventContext> implements EventMiddlewareObject<C> {
+  #private;
+  constructor(selector: EventRouteSelector<K, C>);
+  /** Добавляет промежуточные обработчики к маршруту и возвращает функцию их удаления. */
+  route(key: K, ...middleware: readonly EventMiddleware<C>[]): Unsubscribe;
+  /** Добавляет промежуточные обработчики для обновлений без зарегистрированного маршрута. */
+  otherwise(...middleware: readonly EventMiddleware<C>[]): Unsubscribe;
+  /** Возвращает снимок маршрутов для `stream.use(router)` или ручной композиции. */
+  middleware(): EventMiddleware<C>;
+}
+//#endregion
+//#region src/events/composer.d.ts
+/** Функция или объект промежуточного обработчика для {@link EventComposer}. */
+type EventMiddlewareLike<C extends EventContext = NotificationEventContext> = EventMiddleware<C> | EventMiddlewareObject<C>;
+/** Один или несколько промежуточных обработчиков ветки. */
+type EventMiddlewareGroup<C extends EventContext = NotificationEventContext> = EventMiddlewareLike<C> | readonly EventMiddlewareLike<C>[];
+/** Синхронное или асинхронное условие ветвления. */
+type EventFilter<C extends EventContext = NotificationEventContext> = (context: C) => boolean | Promise<boolean>;
+/** Ошибка локальной ветки событий вместе с контекстом обрабатываемого обновления. */
+interface EventErrorContext<C extends EventContext = NotificationEventContext> {
+  /** Исходное исключение обработчика. */
+  readonly error: unknown;
+  /** Контекст обновления, на котором завершилась ветка. */
+  readonly context: C;
+}
+/** Обработчик локальной границы ошибок. */
+type EventErrorBoundary<C extends EventContext = NotificationEventContext> = (failure: EventErrorContext<C>, next: EventNext) => unknown | Promise<unknown>;
+/** Именованные ветки для `EventComposer.route()`. */
+type EventRouteTable<K extends string | symbol, C extends EventContext = NotificationEventContext> = Partial<Record<K, EventMiddlewareGroup<C>>>;
+/**
+ * Собирает переиспользуемую цепочку обработчиков событий.
+ *
+ * Не открывает соединение. Готовый объект подключается через `stream.use(composer)`.
+ * Для каждого обновления используется текущий снимок вложенных обработчиков.
+ *
+ * @example
+ * ```ts
+ * const feature = new EventComposer<AppEventContext>();
+ * const safe = feature.errorBoundary(reportFeatureError);
+ * safe.filter(isPostUpdate).use(handlePost);
+ * stream.use(feature);
+ * ```
+ */
+declare class EventComposer<C extends EventContext = NotificationEventContext> implements EventMiddlewareObject<C> {
+  #private;
+  constructor(...middleware: readonly EventMiddlewareLike<C>[]);
+  /** Добавляет промежуточные обработчики в конец цепочки. */
+  use(...middleware: readonly EventMiddlewareLike<C>[]): this;
+  /** Создаёт дочернюю ветку для контекста указанного типа. */
+  filter<N extends C>(predicate: EventTypeGuard<N, C>, ...middleware: readonly EventMiddlewareLike<N>[]): EventComposer<N>;
+  /** Создаёт дочернюю ветку по синхронному или асинхронному условию. */
+  filter(predicate: EventFilter<C>, ...middleware: readonly EventMiddlewareLike<C>[]): EventComposer<C>;
+  /**
+   * Направляет контекст в одну именованную ветку.
+   *
+   * Неизвестный ключ без запасной ветки передаёт обновление следующему обработчику. Для
+   * динамической регистрации и числовых ключей используйте {@link EventRouter} напрямую.
+   */
+  route<K extends string | symbol>(selector: EventRouteSelector<K, C>, routes: EventRouteTable<K, C>, fallback?: EventMiddlewareGroup<C>): this;
+  /**
+   * Создаёт дочернюю ветку с локальной границей ошибок.
+   *
+   * Перехватывает ошибки только из дочерней ветки. Вызов `next()` в обработчике ошибки
+   * продолжает внешнюю цепочку.
+   */
+  errorBoundary(handler: EventErrorBoundary<C>, ...middleware: readonly EventMiddlewareLike<C>[]): EventComposer<C>;
+  /** Возвращает промежуточный обработчик для `stream.use()` или вложенной цепочки. */
+  middleware(): EventMiddleware<C>;
+}
+//#endregion
+//#region src/events/transports/websocket.d.ts
+/** Дополнительные параметры конструктора, поддерживаемые Node-реализациями вроде `ws`. */
+interface WebSocketImplementationOptions {
+  headers?: Record<string, string> | undefined;
+  handshakeTimeout?: number | undefined;
+}
+/** Конструктор WebSocket, который можно передать вместо глобальной реализации. */
+interface WebSocketLike {
+  new (url: string | URL, protocols?: string | string[], options?: WebSocketImplementationOptions): unknown;
+}
+/** Определяет, был ли отказ до открытия сокета вызван недействительным токеном. */
+type WebSocketOpenFailureClassifier = (error: unknown, signal: AbortSignal) => boolean | Promise<boolean>;
+/** Настройки WebSocket-транспорта. */
+interface WebSocketTransportOptions {
+  /** Путь апгрейда. По умолчанию `/api/ws`. */
+  path?: string | undefined;
+  /** Реализация WebSocket для сред без глобальной либо для передачи заголовков апгрейда. */
+  webSocketImpl?: WebSocketLike | undefined;
+  /** Способ передачи токена. `auto` выбирает заголовок при инъекции и query иначе. */
+  auth?: 'query' | 'header' | 'auto' | undefined;
+  /** Молчание открытого соединения до переподключения, мс. По умолчанию 90 000. */
+  idleTimeout?: number | undefined;
+  /** Период текстового `ping`, мс. По умолчанию 30 000. */
+  keepAlive?: number | undefined;
+  /** Максимальное время установки соединения, мс. По умолчанию 20 000. */
+  handshakeTimeout?: number | undefined;
+  /**
+   * Проверяет отказ до `open`, когда среда скрыла HTTP-статус WebSocket-upgrade.
+   * `true` преобразует отказ в {@link UnauthorizedStreamError}.
+   */
+  classifyOpenFailure?: WebSocketOpenFailureClassifier | undefined;
+  /** Часы транспорта. Обычно подменяются только в тестах. */
+  clock?: ItdClock | undefined;
+}
+/** Транспорт исходных событий поверх стандартного WebSocket. */
+declare class WebSocketTransport implements EventTransport {
+  #private;
+  readonly name = "ws";
+  constructor(options?: WebSocketTransportOptions);
+  connect(context: EventTransportContext): Promise<void>;
+}
+//#endregion
+export { EventTransport as $, ReconnectOptions as A, NotificationContext as B, EventChannelDeps as C, EventSession as D, EventEnqueueOptions as E, EventPredicate as F, NotificationEventsUpdate as G, NotificationEventFilter as H, EventSequentializer as I, NotificationUpdateOfType as J, NotificationOfType as K, EventTypeGuard as L, EventMiddleware as M, EventMiddlewareObject as N, EventSyncReason as O, EventNext as P, UnreadCountUpdate as Q, runEventMiddleware as R, EventChannel as S, EventChannelOptions as T, NotificationEventOfType as U, NotificationEventContext as V, NotificationEventSelector as W, NotificationUpdateType as X, NotificationUpdateOrigin as Y, UnknownNotificationUpdate as Z, createNotificationEventsClient as _, WebSocketTransportOptions as a, NotificationEventsOptions as b, EventErrorContext as c, EventMiddlewareLike as d, EventTransportContext as et, EventRouteTable as f, NotificationEventsClientOptions as g, NotificationEventsClient as h, WebSocketTransport as i, EventHandler as j, resolveEventChannelOptions as k, EventFilter as l, EventRouter as m, WebSocketLike as n, UnauthorizedStreamError as nt, EventComposer as o, EventRouteSelector as p, NotificationUpdate as q, WebSocketOpenFailureClassifier as r, EventErrorBoundary as s, WebSocketImplementationOptions as t, EventTransportFrame as tt, EventMiddlewareGroup as u, NotificationEvents as v, EventChannelEvents as w, NotificationEventsTransport as x, NotificationEventsMap as y, EventContext as z };
+//# sourceMappingURL=events-DGAWlCaI.d.cts.map