itd-api 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -419,7 +419,7 @@ var AuthManager = class {
 		await this.#saveSession({
 			...this.#session ?? {},
 			accessToken,
-			obtainedAt: Date.now()
+			obtainedAt: this.#config.clock.now()
 		});
 		this.#emitter.emit("tokens", { accessToken });
 	}
@@ -504,12 +504,12 @@ var AuthManager = class {
 		if (!auth) return null;
 		if (typeof auth === "string") return {
 			accessToken: auth,
-			obtainedAt: Date.now()
+			obtainedAt: this.#config.clock.now()
 		};
 		if ("accessToken" in auth) return {
 			accessToken: auth.accessToken,
 			refreshToken: auth.refreshToken,
-			obtainedAt: Date.now()
+			obtainedAt: this.#config.clock.now()
 		};
 		return null;
 	}
@@ -557,7 +557,7 @@ var AuthManager = class {
 				...this.#session ?? {},
 				accessToken,
 				...rotated ? { refreshToken: rotated } : {},
-				obtainedAt: Date.now()
+				obtainedAt: this.#config.clock.now()
 			});
 			this.#emitter.emit("tokens", { accessToken });
 			return accessToken;
@@ -632,7 +632,7 @@ var AuthManager = class {
 		this.#transitionAuth(accessToken);
 		await this.#saveSession({
 			accessToken,
-			obtainedAt: Date.now()
+			obtainedAt: this.#config.clock.now()
 		});
 		this.#emitter.emit("tokens", { accessToken });
 		this.#emitter.emit("signIn", { accessToken });
@@ -640,6 +640,16 @@ var AuthManager = class {
 	}
 };
 //#endregion
+//#region src/core/clock.ts
+/** Системные часы, используемые клиентом по умолчанию. */
+const systemClock = Object.freeze({
+	now: () => Date.now(),
+	schedule(callback, delay) {
+		const timer = setTimeout(callback, delay);
+		return () => clearTimeout(timer);
+	}
+});
+//#endregion
 //#region src/core/url.ts
 /**
 * Собирает строку запроса.
@@ -717,7 +727,7 @@ function normalizeBaseUrl(baseUrl) {
 //#endregion
 //#region src/core/version.ts
 /** Версия библиотеки. Попадает в `User-Agent`. */
-const LIBRARY_VERSION = "0.2.0";
+const LIBRARY_VERSION = "0.3.0";
 //#endregion
 //#region src/core/config.ts
 /** Базовый URL API итд.com. Домен записан в punycode: `итд.com`. */
@@ -945,6 +955,7 @@ function resolveConfig(options = {}) {
 	const mode = options.mode ?? require_runtime.RuntimeMode.Auto;
 	if (!Object.values(require_runtime.RuntimeMode).includes(mode)) throw new require_storage.ItdConfigError(`mode должен быть одним из ${Object.values(require_runtime.RuntimeMode).join(", ")}, получено: ${mode}`);
 	const timeout = requirePositive(options.timeout ?? 3e4, "timeout");
+	if (options.clock !== void 0 && (typeof options.clock !== "object" || options.clock === null || typeof options.clock.now !== "function" || typeof options.clock.schedule !== "function")) throw new require_storage.ItdConfigError("clock должен предоставлять методы now() и schedule()");
 	requireOptionalBoolean(options.autoRefresh, "autoRefresh");
 	requireOptionalBoolean(options.reloginOnRefreshFailure, "reloginOnRefreshFailure");
 	if (options.userAgent !== void 0 && options.userAgent !== false && typeof options.userAgent !== "string") throw new require_storage.ItdConfigError("userAgent должен быть строкой или false");
@@ -957,6 +968,7 @@ function resolveConfig(options = {}) {
 		autoRefresh: options.autoRefresh ?? true,
 		reloginOnRefreshFailure: options.reloginOnRefreshFailure ?? true,
 		fetch: require_runtime.resolveFetch(options.fetch),
+		clock: options.clock ?? systemClock,
 		timeout,
 		retry: resolveRetry(options.retry),
 		rateLimit: resolveRateLimit(options.rateLimit),
@@ -1467,16 +1479,16 @@ function createRetryScheduler(options, random = Math.random) {
 //#endregion
 //#region src/core/middleware.ts
 /** Ожидание повтора, которое уважает отмену запроса. */
-function sleep(ms, signal) {
-	if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(clock, ms, signal) {
+	if (!signal) return new Promise((resolve) => clock.schedule(resolve, ms));
 	if (signal.aborted) return Promise.reject(new require_storage.ItdAbortError("Запрос отменён во время ожидания повтора"));
 	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => {
+		const cancel = clock.schedule(() => {
 			signal.removeEventListener("abort", onAbort);
 			resolve();
 		}, ms);
 		const onAbort = () => {
-			clearTimeout(timer);
+			cancel();
 			reject(new require_storage.ItdAbortError("Запрос отменён во время ожидания повтора"));
 		};
 		signal.addEventListener("abort", onAbort, { once: true });
@@ -1620,7 +1632,7 @@ function createRetryMiddleware(deps) {
 				delay
 			}, request);
 			deps.logger?.debug(`повтор ${method} ${request.path}, попытка ${attempt + 1} через ${delay} мс`);
-			await sleep(delay, request.signal);
+			await sleep(deps.clock ?? systemClock, delay, request.signal);
 		}
 	};
 }
@@ -1649,10 +1661,12 @@ var RequestQueue = class {
 	#active = 0;
 	/** Момент, раньше которого следующий запрос стартовать не должен. */
 	#nextSlot = 0;
-	#timer;
-	constructor(options) {
+	#clock;
+	#cancelTimer;
+	constructor(options, clock = systemClock) {
 		this.#concurrency = options.concurrency;
 		this.#minGap = options.rps ? 1e3 / options.rps : 0;
+		this.#clock = clock;
 	}
 	/** Сколько задач выполняется прямо сейчас. */
 	get active() {
@@ -1704,9 +1718,9 @@ var RequestQueue = class {
 	* ошибкой `ItdAbortError`. Уже выполняющиеся задачи доводятся до конца.
 	*/
 	stop() {
-		if (this.#timer !== void 0) {
-			clearTimeout(this.#timer);
-			this.#timer = void 0;
+		if (this.#cancelTimer) {
+			this.#cancelTimer();
+			this.#cancelTimer = void 0;
 		}
 		this.#nextSlot = 0;
 		const pending = this.#waiting.splice(0, this.#waiting.length);
@@ -1720,23 +1734,23 @@ var RequestQueue = class {
 	*/
 	pause(ms) {
 		if (ms <= 0) return;
-		this.#nextSlot = Math.max(this.#nextSlot, Date.now() + ms);
+		this.#nextSlot = Math.max(this.#nextSlot, this.#clock.now() + ms);
 	}
 	/** Запускает столько ожидающих задач, сколько позволяют ограничения. */
 	#drain() {
 		if (this.#waiting.length === 0) {
-			if (this.#timer !== void 0) {
-				clearTimeout(this.#timer);
-				this.#timer = void 0;
+			if (this.#cancelTimer) {
+				this.#cancelTimer();
+				this.#cancelTimer = void 0;
 			}
 			return;
 		}
 		if (this.#active >= this.#concurrency) return;
-		if (this.#timer !== void 0) return;
-		const now = Date.now();
+		if (this.#cancelTimer) return;
+		const now = this.#clock.now();
 		if (this.#nextSlot > now) {
-			this.#timer = setTimeout(() => {
-				this.#timer = void 0;
+			this.#cancelTimer = this.#clock.schedule(() => {
+				this.#cancelTimer = void 0;
 				this.#drain();
 			}, this.#nextSlot - now);
 			return;
@@ -1755,19 +1769,21 @@ var RequestQueue = class {
 */
 var RequestQueuePool = class {
 	#options;
+	#clock;
 	#main;
 	/** Очереди сервисов заводятся при первом запросе — обычно не нужна ни одна. */
 	#byService = /* @__PURE__ */ new Map();
-	constructor(options) {
+	constructor(options, clock = systemClock) {
 		this.#options = options;
-		this.#main = new RequestQueue(options);
+		this.#clock = clock;
+		this.#main = new RequestQueue(options, clock);
 	}
 	/** Очередь хоста. */
 	for(service) {
 		if (service === void 0) return this.#main;
 		let queue = this.#byService.get(service);
 		if (!queue) {
-			queue = new RequestQueue(this.#options);
+			queue = new RequestQueue(this.#options, this.#clock);
 			this.#byService.set(service, queue);
 		}
 		return queue;
@@ -2215,7 +2231,7 @@ function createApiError(context) {
 		path: context.path,
 		raw: safeRawBody(context.body),
 		response: context.response,
-		retryAfter: parseRetryAfter(context.headers?.get("retry-after"))
+		retryAfter: parseRetryAfter(context.headers?.get("retry-after"), context.now)
 	};
 	if (parsed.code === "PHONE_VERIFICATION_REQUIRED") return new require_storage.ItdPhoneVerificationError({
 		...init,
@@ -2291,13 +2307,13 @@ function abortable(promise, signal) {
 * Реализовано вручную, а не через `AbortSignal.any`: последний появился только в Node 20,
 * а библиотека поддерживает Node 18.
 */
-function createAbortBundle(userSignal, timeout) {
+function createAbortBundle(userSignal, timeout, clock) {
 	const controller = new AbortController();
 	let timedOut = false;
 	const onUserAbort = () => controller.abort(userSignal?.reason);
 	if (userSignal) if (userSignal.aborted) controller.abort(userSignal.reason);
 	else userSignal.addEventListener("abort", onUserAbort, { once: true });
-	const timer = timeout > 0 ? setTimeout(() => {
+	const cancelTimer = timeout > 0 ? clock.schedule(() => {
 		timedOut = true;
 		controller.abort();
 	}, timeout) : void 0;
@@ -2305,7 +2321,7 @@ function createAbortBundle(userSignal, timeout) {
 		signal: controller.signal,
 		timedOut: () => timedOut,
 		cleanup: () => {
-			if (timer !== void 0) clearTimeout(timer);
+			cancelTimer?.();
 			userSignal?.removeEventListener("abort", onUserAbort);
 		}
 	};
@@ -2342,8 +2358,8 @@ var Transport = class {
 		const headers = await this.#buildHeaders(request, url);
 		const attempt = request.attempt ?? 1;
 		const timeout = request.timeout ?? this.#config.timeout;
-		const abort = createAbortBundle(request.signal, timeout);
-		const startedAt = Date.now();
+		const abort = createAbortBundle(request.signal, timeout, this.#config.clock);
+		const startedAt = this.#config.clock.now();
 		let cleanupBody;
 		try {
 			let body;
@@ -2362,7 +2378,7 @@ var Transport = class {
 				};
 				await dispatchRequestHook(this.#config.hooks, "onError", {
 					...context,
-					duration: Date.now() - startedAt,
+					duration: this.#config.clock.now() - startedAt,
 					error: failure
 				}, request);
 				throw failure;
@@ -2391,7 +2407,7 @@ var Transport = class {
 				if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) init.duplex = "half";
 				response = await this.#config.fetch(url, init);
 			} catch (error) {
-				const duration = Date.now() - startedAt;
+				const duration = this.#config.clock.now() - startedAt;
 				const failure = this.#toTransportError(error, abort, request, method, timeout);
 				await dispatchRequestHook(this.#config.hooks, "onError", {
 					...context,
@@ -2409,16 +2425,17 @@ var Transport = class {
 			if (response.ok) await dispatchRequestHook(this.#config.hooks, "onResponse", {
 				...context,
 				status: response.status,
-				duration: Date.now() - startedAt,
+				duration: this.#config.clock.now() - startedAt,
 				response
 			}, request);
 			const payload = await this.#readBodyOrFail(response, context, request, method, abort, timeout);
-			const duration = Date.now() - startedAt;
+			const duration = this.#config.clock.now() - startedAt;
 			if (!response.ok) {
 				const error = createApiError({
 					method,
 					path: request.path,
 					status: response.status,
+					now: this.#config.clock.now(),
 					statusText: response.statusText,
 					headers: response.headers,
 					response,
@@ -2487,7 +2504,7 @@ var Transport = class {
 	}
 	/** Читает тело и преобразует ошибку чтения в транспортную ошибку библиотеки. */
 	async #readBodyOrFail(response, context, request, method, abort, timeout) {
-		const startedAt = Date.now();
+		const startedAt = this.#config.clock.now();
 		try {
 			return await abortable(readBody(response), abort.signal);
 		} catch (error) {
@@ -2495,7 +2512,7 @@ var Transport = class {
 			const failure = this.#toTransportError(error, abort, request, method, timeout);
 			await dispatchRequestHook(this.#config.hooks, "onError", {
 				...context,
-				duration: Date.now() - startedAt,
+				duration: this.#config.clock.now() - startedAt,
 				error: failure
 			}, request);
 			this.#config.logger?.warn(`× ${method} ${request.path}: не удалось прочитать тело ответа — ${failure.message}`);
@@ -2816,144 +2833,167 @@ const ItdErrorCode = Object.freeze({
 	WRITE_ACCESS_RESTRICTED: "WRITE_ACCESS_RESTRICTED"
 });
 //#endregion
-//#region src/notifications/type-map.ts
-/**
-* Соответствие коротких имён типов уведомлений развёрнутым.
-*
-* Сервер — и в списке, и в потоке событий — присылает короткие имена: `like`, `comment`,
-* `reply`, `repost`, `comment_like`. Развёрнутые (`post_reaction`, `post_comment`)
-* встречаются в оформлении интерфейса, поэтому библиотека приводит типы к ним:
-* они однозначно называют и объект, и действие.
-*
-* Пришедшее значение всегда остаётся в поле `rawType`.
-*/
-const NOTIFICATION_TYPE_ALIASES = Object.freeze({
-	like: NotificationType.PostReaction,
-	comment: NotificationType.PostComment,
-	comment_like: NotificationType.CommentReaction,
-	reply: NotificationType.CommentReply,
-	repost: NotificationType.PostRepost,
-	mention: NotificationType.PostMention
-});
-const KNOWN_TYPES = new Set(Object.values(NotificationType));
-/**
-* Приводит имя типа к каноническому.
-*
-* Неизвестное значение возвращается без изменений, чтобы не менять смысл нового типа
-* уведомления на другой.
-*
-* @example
-* ```ts
-* canonicalNotificationType('like');           // 'post_reaction'
-* canonicalNotificationType('post_reaction');  // 'post_reaction'
-* canonicalNotificationType('новое_событие');  // 'новое_событие'
-* ```
-*/
-function canonicalNotificationType(rawType) {
-	return NOTIFICATION_TYPE_ALIASES[rawType] ?? rawType;
-}
-/**
-* Известен ли библиотеке этот тип уведомления.
-*
-* Полезно, чтобы решить, показывать ли уведомление, для которого нет своего оформления.
-*/
-function isKnownNotificationType(type) {
-	return KNOWN_TYPES.has(canonicalNotificationType(type));
-}
-//#endregion
-//#region src/notifications/normalize.ts
-function asActor(value) {
-	if (!isRecord(value)) return void 0;
-	const id = asString(value.id);
-	if (!id) return void 0;
-	return {
-		id,
-		username: asString(value.username) ?? "",
-		displayName: asString(value.displayName) ?? "",
-		avatar: asString(value.avatar) ?? "",
-		...typeof value.isFollowing === "boolean" ? { isFollowing: value.isFollowing } : {},
-		...typeof value.isFollowedBy === "boolean" ? { isFollowedBy: value.isFollowedBy } : {}
-	};
-}
-/** Собирает участников: сервер присылает либо одного `actor`, либо массив `actors`. */
-function readActors(source) {
-	if (Array.isArray(source.actors)) return source.actors.map(asActor).filter((actor) => actor !== void 0);
-	const single = asActor(source.actor);
-	return single ? [single] : [];
-}
-/**
-* Приводит уведомление к единой форме.
-*
-* Нужна потому, что REST-список и поток событий описывают одно и то же событие по-разному:
-* различаются имена типов (`like` против `post_reaction`), имена полей
-* (`targetId`/`entityId`, `read`/`isRead`, `preview`/`entityPreview`) и число участников
-* (`actor` против массива `actors`). После приведения объекты из обоих источников
-* можно складывать в один список.
-*
-* Исходные данные не теряются: имя типа с сервера остаётся в `rawType`,
-* весь объект целиком — в `raw`.
-*
-* @param input уведомление из REST-ответа либо полезная нагрузка события потока
-*
-* @example
-* ```ts
-* const fromRest = normalizeNotification(restItem);
-* const fromStream = normalizeNotification(event.payload);
-* // одинаковая форма — можно объединять
-* ```
-*/
-function normalizeNotification(input) {
-	const source = isRecord(input) ? input : {};
-	const payload = isRecord(source.payload) ? source.payload : source;
-	const rawType = asString(payload.type) ?? asString(source.type) ?? "";
-	const createdAt = asString(payload.createdAt) ?? asString(source.createdAt) ?? "";
-	const readAt = asString(payload.readAt) ?? asString(source.readAt);
-	const isRead = typeof payload.isRead === "boolean" ? payload.isRead : typeof payload.read === "boolean" ? payload.read : Boolean(readAt);
-	const subjectId = asString(payload.subjectId);
-	const targetId = asString(payload.targetId);
-	const subjectIsComment = payload.subjectType === "comment";
-	const clickUrl = asString(payload.clickUrl);
-	return {
-		id: asString(payload.id) ?? asString(source.id) ?? "",
-		type: canonicalNotificationType(rawType),
-		rawType,
-		entityId: asString(payload.entityId) ?? (subjectIsComment ? subjectId ?? targetId : targetId) ?? null,
-		parentEntityId: asString(payload.parentEntityId) ?? (subjectIsComment ? targetId ?? null : null),
-		isRead,
-		actors: readActors(payload),
-		count: typeof payload.count === "number" && payload.count > 0 ? payload.count : 1,
-		preview: asString(payload.entityPreview) ?? asString(payload.preview) ?? null,
-		...clickUrl ? { clickUrl } : {},
-		createdAt,
-		updatedAt: asString(payload.updatedAt) ?? readAt ?? createdAt,
-		raw: input
-	};
-}
-/**
-* Разбирает событие `notification` из потока.
-*
-* Кроме самого уведомления событие несёт служебные поля уровня конверта: актуальный
-* счётчик непрочитанных и признак звука.
-*/
-function readNotificationEvent(data) {
-	const source = isRecord(data) ? data : {};
-	return {
-		notification: normalizeNotification(data),
-		unreadCount: typeof source.unreadCount === "number" ? source.unreadCount : void 0,
-		sound: source.sound === true
+//#region src/realtime/middleware.ts
+const REALTIME_MIDDLEWARE_SNAPSHOT = Symbol("itd-api.realtime.middlewareSnapshot");
+/** @internal */
+function captureRealtimeMiddleware(middleware) {
+	const capture = middleware[REALTIME_MIDDLEWARE_SNAPSHOT];
+	if (!capture) return middleware;
+	const snapshot = capture();
+	if (typeof snapshot !== "function") throw new TypeError("Снимок промежуточного обработчика должен быть функцией");
+	return snapshot;
+}
+/** @internal */
+function withRealtimeMiddlewareSnapshot(middleware, capture) {
+	Object.defineProperty(middleware, REALTIME_MIDDLEWARE_SNAPSHOT, { value: capture });
+	return middleware;
+}
+/** Выполняет промежуточные обработчики по порядку и запрещает повторный вызов `next()`. */
+async function runRealtimeMiddleware(middleware, context, terminal) {
+	let lastIndex = -1;
+	const dispatch = async (index) => {
+		if (index <= lastIndex) throw new Error("next() в промежуточном обработчике вызван повторно");
+		lastIndex = index;
+		const current = middleware[index];
+		if (!current) {
+			await terminal();
+			return;
+		}
+		let downstream;
+		let duplicateCalls;
+		let failure;
+		const next = () => {
+			if (!downstream) {
+				downstream = dispatch(index + 1);
+				return downstream;
+			}
+			const duplicate = Promise.reject(/* @__PURE__ */ new Error("next() в одном промежуточном обработчике вызван повторно"));
+			duplicateCalls = Promise.all(duplicateCalls ? [duplicateCalls, duplicate] : [duplicate]).then(() => void 0);
+			return duplicate;
+		};
+		try {
+			await current(context, next);
+		} catch (error) {
+			failure = { error };
+		}
+		try {
+			await downstream;
+			await duplicateCalls;
+		} catch (error) {
+			failure ??= { error };
+		}
+		if (failure) throw failure.error;
 	};
+	await dispatch(0);
 }
-/**
-* Разбирает событие `unread_count` из потока.
-*
-* Возвращает `undefined`, если сервер прислал событие без вложенного `payload`.
-*/
-function readUnreadCountEvent(data) {
-	if (!isRecord(data)) return void 0;
-	const payload = isRecord(data.payload) ? data.payload : void 0;
-	if (!payload) return void 0;
-	return typeof payload.count === "number" ? payload.count : void 0;
-}
+/** Планирует нормализованные обновления и отслеживает незавершённые обработчики. */
+var RealtimeDispatcher = class {
+	#options;
+	#hooks;
+	#middleware = [];
+	#handlers = [];
+	#queue = [];
+	#activeKeys = /* @__PURE__ */ new Set();
+	#drainWaiters = /* @__PURE__ */ new Set();
+	#active = 0;
+	constructor(options, hooks) {
+		this.#options = options;
+		this.#hooks = hooks;
+	}
+	use(middleware) {
+		this.#middleware.push(middleware);
+		return () => {
+			const index = this.#middleware.indexOf(middleware);
+			if (index >= 0) this.#middleware.splice(index, 1);
+		};
+	}
+	on(predicate, handler) {
+		const registration = {
+			predicate,
+			handler
+		};
+		this.#handlers.push(registration);
+		return () => {
+			const index = this.#handlers.indexOf(registration);
+			if (index >= 0) this.#handlers.splice(index, 1);
+		};
+	}
+	dispatch(context) {
+		let keys;
+		let middleware;
+		try {
+			keys = this.#keysFor(context);
+			middleware = this.#middleware.map(captureRealtimeMiddleware);
+		} catch (error) {
+			this.#hooks.middlewareError(error, context);
+			return;
+		}
+		this.#queue.push({
+			context,
+			middleware,
+			handlers: [...this.#handlers],
+			keys
+		});
+		this.#pump();
+	}
+	/** Отбрасывает обновления, обработка которых ещё не началась. */
+	clearPending() {
+		this.#queue.length = 0;
+		this.#resolveDrain();
+	}
+	/** Ждёт завершения активных и поставленных в очередь обновлений. */
+	drain() {
+		if (this.#active === 0 && this.#queue.length === 0) return Promise.resolve();
+		return new Promise((resolve) => this.#drainWaiters.add(resolve));
+	}
+	#keysFor(context) {
+		const value = this.#options.sequentialize?.(context);
+		if (value === void 0) return [];
+		const values = Array.isArray(value) ? value : [value];
+		for (const key of values) if (typeof key !== "string" && typeof key !== "number" && typeof key !== "symbol") throw new TypeError("sequentialize() должен возвращать PropertyKey или их список");
+		return [...new Set(values)];
+	}
+	#pump() {
+		while (this.#active < this.#options.concurrency) {
+			const blockedKeys = new Set(this.#activeKeys);
+			const index = this.#queue.findIndex(({ keys }) => {
+				const runnable = keys.every((key) => !blockedKeys.has(key));
+				if (!runnable) for (const key of keys) blockedKeys.add(key);
+				return runnable;
+			});
+			if (index < 0) break;
+			const [work] = this.#queue.splice(index, 1);
+			if (!work) break;
+			this.#active += 1;
+			for (const key of work.keys) this.#activeKeys.add(key);
+			this.#run(work);
+		}
+		this.#resolveDrain();
+	}
+	async #run(work) {
+		try {
+			await runRealtimeMiddleware(work.middleware, work.context, async () => {
+				for (const { predicate, handler } of work.handlers) try {
+					if (predicate(work.context)) await handler(work.context);
+				} catch (error) {
+					this.#hooks.handlerError(error, work.context);
+				}
+				this.#hooks.deliver(work.context);
+			});
+		} catch (error) {
+			this.#hooks.middlewareError(error, work.context);
+		} finally {
+			this.#active -= 1;
+			for (const key of work.keys) this.#activeKeys.delete(key);
+			this.#pump();
+		}
+	}
+	#resolveDrain() {
+		if (this.#active !== 0 || this.#queue.length !== 0) return;
+		for (const resolve of this.#drainWaiters) resolve();
+		this.#drainWaiters.clear();
+	}
+};
 //#endregion
 //#region src/realtime/transport.ts
 /** Ошибка, по которой видно, что сервер отверг авторизацию потока. */
@@ -2979,7 +3019,9 @@ var PollTransport = class {
 	name = "poll";
 	#interval;
 	#limit;
+	#clock;
 	constructor(options = {}) {
+		this.#clock = options.clock ?? systemClock;
 		this.#interval = options.interval ?? 15e3;
 		this.#limit = options.limit ?? 20;
 	}
@@ -3047,9 +3089,9 @@ var PollTransport = class {
 	#wait(signal) {
 		if (signal.aborted) return Promise.resolve();
 		return new Promise((resolve) => {
-			const timer = setTimeout(finish, this.#interval);
+			const cancel = this.#clock.schedule(finish, this.#interval);
 			function finish() {
-				clearTimeout(timer);
+				cancel();
 				signal.removeEventListener("abort", finish);
 				resolve();
 			}
@@ -3286,9 +3328,11 @@ var SseTransport = class {
 	name = "sse";
 	#idleTimeout;
 	#handshakeTimeout;
+	#clock;
 	/** Идентификатор последнего события — отправляется при переподключении. */
 	#lastEventId;
 	constructor(options = {}) {
+		this.#clock = options.clock ?? systemClock;
 		this.#idleTimeout = options.idleTimeout ?? 9e4;
 		this.#handshakeTimeout = options.handshakeTimeout ?? 2e4;
 	}
@@ -3319,7 +3363,7 @@ var SseTransport = class {
 	/** Выполняет запрос потока, обрывая его, если ответ не пришёл за отведённое время. */
 	async #handshake(url, headers, context, controller) {
 		let expired = false;
-		const timer = this.#handshakeTimeout > 0 ? setTimeout(() => {
+		const cancelTimer = this.#handshakeTimeout > 0 ? this.#clock.schedule(() => {
 			expired = true;
 			controller.abort(/* @__PURE__ */ new Error("Истёк таймаут рукопожатия SSE"));
 		}, this.#handshakeTimeout) : void 0;
@@ -3333,7 +3377,7 @@ var SseTransport = class {
 			if (expired) throw new Error("Поток уведомлений не ответил: истёк таймаут рукопожатия");
 			throw error;
 		} finally {
-			if (timer !== void 0) clearTimeout(timer);
+			cancelTimer?.();
 		}
 	}
 	async #read(body, context) {
@@ -3354,11 +3398,11 @@ var SseTransport = class {
 				data
 			});
 		} });
-		let idleTimer;
+		let cancelIdleTimer;
 		const armIdleTimer = () => {
 			if (this.#idleTimeout <= 0) return;
-			if (idleTimer !== void 0) clearTimeout(idleTimer);
-			idleTimer = setTimeout(() => {
+			cancelIdleTimer?.();
+			cancelIdleTimer = this.#clock.schedule(() => {
 				reader.cancel(/* @__PURE__ */ new Error("Поток молчит дольше допустимого")).catch(() => {});
 			}, this.#idleTimeout);
 		};
@@ -3371,12 +3415,220 @@ var SseTransport = class {
 				parser.feed(decoder.decode(value, { stream: true }));
 			}
 		} finally {
-			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			cancelIdleTimer?.();
 			reader.releaseLock?.();
 		}
 	}
 };
 //#endregion
+//#region src/notifications/type-map.ts
+/**
+* Соответствие коротких имён типов уведомлений развёрнутым.
+*
+* Сервер — и в списке, и в потоке событий — присылает короткие имена: `like`, `comment`,
+* `reply`, `repost`, `comment_like`. Развёрнутые (`post_reaction`, `post_comment`)
+* встречаются в оформлении интерфейса, поэтому библиотека приводит типы к ним:
+* они однозначно называют и объект, и действие.
+*
+* Пришедшее значение всегда остаётся в поле `rawType`.
+*/
+const NOTIFICATION_TYPE_ALIASES = Object.freeze({
+	like: NotificationType.PostReaction,
+	comment: NotificationType.PostComment,
+	comment_like: NotificationType.CommentReaction,
+	reply: NotificationType.CommentReply,
+	repost: NotificationType.PostRepost,
+	mention: NotificationType.PostMention
+});
+const KNOWN_TYPES = new Set(Object.values(NotificationType));
+/**
+* Приводит имя типа к каноническому.
+*
+* Неизвестное значение возвращается без изменений, чтобы не менять смысл нового типа
+* уведомления на другой.
+*
+* @example
+* ```ts
+* canonicalNotificationType('like');           // 'post_reaction'
+* canonicalNotificationType('post_reaction');  // 'post_reaction'
+* canonicalNotificationType('новое_событие');  // 'новое_событие'
+* ```
+*/
+function canonicalNotificationType(rawType) {
+	return NOTIFICATION_TYPE_ALIASES[rawType] ?? rawType;
+}
+/**
+* Известен ли библиотеке этот тип уведомления.
+*
+* Полезно, чтобы решить, показывать ли уведомление, для которого нет своего оформления.
+*/
+function isKnownNotificationType(type) {
+	return KNOWN_TYPES.has(canonicalNotificationType(type));
+}
+//#endregion
+//#region src/notifications/normalize.ts
+function asActor(value) {
+	if (!isRecord(value)) return void 0;
+	const id = asString(value.id);
+	if (!id) return void 0;
+	return {
+		id,
+		username: asString(value.username) ?? "",
+		displayName: asString(value.displayName) ?? "",
+		avatar: asString(value.avatar) ?? "",
+		...typeof value.isFollowing === "boolean" ? { isFollowing: value.isFollowing } : {},
+		...typeof value.isFollowedBy === "boolean" ? { isFollowedBy: value.isFollowedBy } : {}
+	};
+}
+/** Собирает участников: сервер присылает либо одного `actor`, либо массив `actors`. */
+function readActors(source) {
+	if (Array.isArray(source.actors)) return source.actors.map(asActor).filter((actor) => actor !== void 0);
+	const single = asActor(source.actor);
+	return single ? [single] : [];
+}
+/**
+* Приводит уведомление к единой форме.
+*
+* Нужна потому, что REST-список и поток событий описывают одно и то же событие по-разному:
+* различаются имена типов (`like` против `post_reaction`), имена полей
+* (`targetId`/`entityId`, `read`/`isRead`, `preview`/`entityPreview`) и число участников
+* (`actor` против массива `actors`). После приведения объекты из обоих источников
+* можно складывать в один список.
+*
+* Исходные данные не теряются: имя типа с сервера остаётся в `rawType`,
+* весь объект целиком — в `raw`.
+*
+* @param input уведомление из REST-ответа либо полезная нагрузка события потока
+*
+* @example
+* ```ts
+* const fromRest = normalizeNotification(restItem);
+* const fromStream = normalizeNotification(event.payload);
+* // одинаковая форма — можно объединять
+* ```
+*/
+function normalizeNotification(input) {
+	const source = isRecord(input) ? input : {};
+	const payload = isRecord(source.payload) ? source.payload : source;
+	const rawType = asString(payload.type) ?? asString(source.type) ?? "";
+	const createdAt = asString(payload.createdAt) ?? asString(source.createdAt) ?? "";
+	const readAt = asString(payload.readAt) ?? asString(source.readAt);
+	const isRead = typeof payload.isRead === "boolean" ? payload.isRead : typeof payload.read === "boolean" ? payload.read : Boolean(readAt);
+	const subjectId = asString(payload.subjectId);
+	const targetId = asString(payload.targetId);
+	const subjectIsComment = payload.subjectType === "comment";
+	const clickUrl = asString(payload.clickUrl);
+	return {
+		id: asString(payload.id) ?? asString(source.id) ?? "",
+		type: canonicalNotificationType(rawType),
+		rawType,
+		entityId: asString(payload.entityId) ?? (subjectIsComment ? subjectId ?? targetId : targetId) ?? null,
+		parentEntityId: asString(payload.parentEntityId) ?? (subjectIsComment ? targetId ?? null : null),
+		isRead,
+		actors: readActors(payload),
+		count: typeof payload.count === "number" && payload.count > 0 ? payload.count : 1,
+		preview: asString(payload.entityPreview) ?? asString(payload.preview) ?? null,
+		...clickUrl ? { clickUrl } : {},
+		createdAt,
+		updatedAt: asString(payload.updatedAt) ?? readAt ?? createdAt,
+		raw: input
+	};
+}
+/**
+* Разбирает событие `notification` из потока.
+*
+* Кроме самого уведомления событие несёт служебные поля уровня конверта: актуальный
+* счётчик непрочитанных и признак звука.
+*/
+function readNotificationEvent(data) {
+	const source = isRecord(data) ? data : {};
+	return {
+		notification: normalizeNotification(data),
+		unreadCount: typeof source.unreadCount === "number" ? source.unreadCount : void 0,
+		sound: source.sound === true
+	};
+}
+/**
+* Разбирает событие `unread_count` из потока.
+*
+* Возвращает `undefined`, если сервер прислал событие без вложенного `payload`.
+*/
+function readUnreadCountEvent(data) {
+	if (!isRecord(data)) return void 0;
+	const payload = isRecord(data.payload) ? data.payload : void 0;
+	if (!payload) return void 0;
+	return typeof payload.count === "number" ? payload.count : void 0;
+}
+//#endregion
+//#region src/realtime/updates.ts
+/** Типы нормализованных обновлений потока. */
+const RealtimeUpdateType = Object.freeze({
+	Notification: "notification",
+	UnreadCount: "unreadCount",
+	Unknown: "unknown"
+});
+/** Источники нормализованных обновлений потока. */
+const RealtimeUpdateOrigin = Object.freeze({
+	Stream: "stream",
+	Sync: "sync"
+});
+/** Проверяет форму фильтра уведомлений. */
+function validateNotificationSelector(selector) {
+	if (typeof selector === "string") {
+		if (selector.length === 0) throw new require_storage.ItdConfigError("Тип уведомления не должен быть пустым");
+		return;
+	}
+	if (Array.isArray(selector)) {
+		if (selector.length === 0 || selector.some((type) => typeof type !== "string" || !type)) throw new require_storage.ItdConfigError("Список типов уведомлений должен содержать непустые строки");
+		return;
+	}
+	if (typeof selector !== "object" || selector === null) throw new require_storage.ItdConfigError("Фильтр уведомлений должен быть строкой, списком или объектом");
+	const filter = selector;
+	if (filter.type !== void 0) validateNotificationSelector(filter.type);
+	if (filter.actorId !== void 0 && typeof filter.actorId !== "string") throw new require_storage.ItdConfigError("Фильтр уведомлений: actorId должен быть строкой");
+	for (const field of ["entityId", "parentEntityId"]) {
+		const value = filter[field];
+		if (value !== void 0 && value !== null && typeof value !== "string") throw new require_storage.ItdConfigError(`Фильтр уведомлений: ${field} должен быть строкой или null`);
+	}
+	if (filter.predicate !== void 0 && typeof filter.predicate !== "function") throw new require_storage.ItdConfigError("Фильтр уведомлений: predicate должен быть функцией");
+}
+/** Преобразует транспортный кадр в одно логическое обновление. */
+function readRealtimeUpdate(event) {
+	if (event.name === "notification") return {
+		type: RealtimeUpdateType.Notification,
+		data: readNotificationEvent(event.data)
+	};
+	if (event.name === "unread_count") {
+		const count = readUnreadCountEvent(event.data);
+		return count === void 0 ? void 0 : {
+			type: RealtimeUpdateType.UnreadCount,
+			data: count
+		};
+	}
+	return {
+		type: RealtimeUpdateType.Unknown,
+		name: event.name,
+		data: event.data
+	};
+}
+/** Проверяет объектный или краткий фильтр уведомления. */
+function matchesNotification(context, selector) {
+	const notification = context.update.data.notification;
+	if (typeof selector === "string") return notification.type === selector;
+	if (Array.isArray(selector)) return selector.includes(notification.type);
+	const filter = selector;
+	const types = filter.type === void 0 ? void 0 : [filter.type].flat();
+	if (types && !types.includes(notification.type)) return false;
+	if (filter.actorId !== void 0 && !notification.actors.some(({ id }) => id === filter.actorId)) return false;
+	if (filter.entityId !== void 0 && notification.entityId !== filter.entityId) return false;
+	if (filter.parentEntityId !== void 0 && notification.parentEntityId !== filter.parentEntityId) return false;
+	return filter.predicate?.(context) ?? true;
+}
+/** Сужает произвольный контекст потока до контекста уведомления. */
+function isNotificationContext(context) {
+	return context.update.type === RealtimeUpdateType.Notification;
+}
+//#endregion
 //#region src/realtime/stream.ts
 /** Способ получения событий. */
 const RealtimeTransportKind = Object.freeze({
@@ -3398,6 +3650,8 @@ function validateRealtimeOptions(options) {
 		if (!Number.isFinite(value) || value < min) throw new require_storage.ItdConfigError(`realtime.${name} должен быть числом не меньше ${min}, получено: ${value}`);
 	};
 	positiveInteger(options.maxAttempts, "maxAttempts");
+	positiveInteger(options.concurrency, "concurrency");
+	if (options.concurrency === 0) throw new require_storage.ItdConfigError("realtime.concurrency должен быть больше нуля");
 	duration(options.pollInterval, "pollInterval", 1);
 	duration(options.idleTimeout, "idleTimeout", 0);
 	duration(options.handshakeTimeout, "handshakeTimeout", 0);
@@ -3406,6 +3660,7 @@ function validateRealtimeOptions(options) {
 		if (!Array.isArray(options.backoff) || options.backoff.length === 0) throw new require_storage.ItdConfigError("realtime.backoff должен быть непустым списком пауз");
 		for (const delay of options.backoff) duration(delay, "backoff", 0);
 	}
+	if (options.sequentialize !== void 0 && typeof options.sequentialize !== "function") throw new require_storage.ItdConfigError("realtime.sequentialize должен быть функцией");
 }
 /**
 * Поток уведомлений в реальном времени.
@@ -3415,22 +3670,26 @@ function validateRealtimeOptions(options) {
 *
 * @example
 * ```ts
+* import { NotificationType } from 'itd-api';
+*
 * const stream = itd.realtime();
 *
-* stream.on('notification', ({ notification, unreadCount }) => {
-*   console.log(formatNotificationText(notification), unreadCount);
+* 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();
 * ```
 */
 var ItdRealtime = class {
 	#deps;
 	#options;
 	#emitter;
+	#dispatcher;
 	#transport;
 	#maxAttempts;
 	#controller;
@@ -3445,7 +3704,7 @@ var ItdRealtime = class {
 	#wanted = false;
 	#status = RealtimeStatus.Disconnected;
 	#attempt = 0;
-	#timer;
+	#cancelTimer;
 	#detachEnvironment;
 	constructor(deps, options = {}) {
 		validateRealtimeOptions(options);
@@ -3458,6 +3717,14 @@ var ItdRealtime = class {
 			if (deps.logger) deps.logger.error(message, error);
 			else console.error(`[itd-api] ${message}`, error);
 		});
+		this.#dispatcher = new RealtimeDispatcher({
+			concurrency: options.concurrency ?? 1,
+			...options.sequentialize ? { sequentialize: options.sequentialize } : {}
+		}, {
+			deliver: (context) => this.#deliver(context.update),
+			middlewareError: (error, context) => this.#reportDispatchError("middlewareError", error, context),
+			handlerError: (error, context) => this.#reportDispatchError("handlerError", error, context)
+		});
 	}
 	/** Текущее состояние соединения. */
 	get status() {
@@ -3488,6 +3755,40 @@ var ItdRealtime = class {
 		return this.#emitter.once(event, listener);
 	}
 	/**
+	* Добавляет промежуточный обработчик нормализованных обновлений.
+	*
+	* Обработчики выполняются в порядке регистрации. Если `next()` не вызван, обновление не
+	* передаётся дальше по цепочке, асинхронным обработчикам и слушателям событий.
+	*
+	* @returns функция удаления обработчика
+	*/
+	use(middleware) {
+		if (typeof middleware !== "function") throw new require_storage.ItdConfigError("realtime.use() принимает функцию обработки");
+		return this.#dispatcher.use(middleware);
+	}
+	onUpdate(selectorOrHandler, selectedHandler) {
+		const selectAll = selectedHandler === void 0;
+		const handler = selectAll ? selectorOrHandler : selectedHandler;
+		if (typeof handler !== "function") throw new require_storage.ItdConfigError("realtime.onUpdate() принимает функцию обработчика");
+		if (!selectAll && typeof selectorOrHandler !== "function" && !Object.values(RealtimeUpdateType).includes(selectorOrHandler)) throw new require_storage.ItdConfigError(`Неизвестный тип обновления потока: ${String(selectorOrHandler)}`);
+		let predicate;
+		if (selectAll) predicate = () => true;
+		else {
+			const selector = selectorOrHandler;
+			predicate = typeof selector === "function" ? selector : (context) => context.update.type === selector;
+		}
+		return this.#dispatcher.on(predicate, handler);
+	}
+	onNotification(selector, handler) {
+		if (typeof handler !== "function") throw new require_storage.ItdConfigError("realtime.onNotification() принимает функцию обработчика");
+		if (typeof selector !== "function") validateNotificationSelector(selector);
+		const predicate = (context) => {
+			if (!isNotificationContext(context)) return false;
+			return typeof selector === "function" ? selector(context) : matchesNotification(context, selector);
+		};
+		return this.#dispatcher.on(predicate, handler);
+	}
+	/**
 	* Поднимает соединение.
 	*
 	* Повторный вызов при уже живом соединении ничего не делает — это защита от двойного
@@ -3498,9 +3799,14 @@ var ItdRealtime = class {
 	async connect() {
 		if (this.#wanted) return;
 		this.#wanted = true;
+		this.#deps.onConnect?.();
 		this.#attachEnvironmentListeners();
 		if (this.#options.syncCount !== false) try {
-			this.#emitter.emit("unreadCount", await this.#deps.fetchUnreadCount());
+			const count = await this.#deps.fetchUnreadCount();
+			if (this.#wanted) this.#dispatch({
+				type: RealtimeUpdateType.UnreadCount,
+				data: count
+			}, void 0, RealtimeUpdateOrigin.Sync);
 		} catch (error) {
 			this.#deps.logger?.debug("не удалось получить число непрочитанных", error);
 		}
@@ -3509,27 +3815,36 @@ var ItdRealtime = class {
 	/** Закрывает соединение и отменяет запланированные попытки. */
 	disconnect() {
 		this.#wanted = false;
-		if (this.#timer !== void 0) {
-			clearTimeout(this.#timer);
-			this.#timer = void 0;
+		if (this.#cancelTimer) {
+			this.#cancelTimer();
+			this.#cancelTimer = void 0;
 		}
 		this.#detachEnvironment?.();
 		this.#detachEnvironment = void 0;
 		this.#controller?.abort();
 		this.#controller = void 0;
 		this.#attempt = 0;
+		this.#dispatcher.clearPending();
 		this.#setStatus(RealtimeStatus.Disconnected);
 		this.#deps.onClose?.();
 	}
-	/** Снимает все подписки. Соединение при этом не закрывается. */
+	/** Ждёт завершения всех принятых обновлений. */
+	drain() {
+		return this.#dispatcher.drain();
+	}
+	/** Снимает подписки `on()` и `once()`. Остальные обработчики остаются. */
 	removeAllListeners() {
 		this.#emitter.removeAllListeners();
 	}
 	#createTransport() {
 		const kind = this.#options.transport ?? RealtimeTransportKind.Auto;
 		if (typeof kind === "object") return kind;
-		if (kind === RealtimeTransportKind.Poll || kind === RealtimeTransportKind.Auto && !require_runtime.supportsStreamingBody()) return new PollTransport({ ...this.#options.pollInterval !== void 0 ? { interval: this.#options.pollInterval } : {} });
+		if (kind === RealtimeTransportKind.Poll || kind === RealtimeTransportKind.Auto && !require_runtime.supportsStreamingBody()) return new PollTransport({
+			clock: this.#deps.clock ?? systemClock,
+			...this.#options.pollInterval !== void 0 ? { interval: this.#options.pollInterval } : {}
+		});
 		return new SseTransport({
+			clock: this.#deps.clock ?? systemClock,
 			...this.#options.idleTimeout !== void 0 ? { idleTimeout: this.#options.idleTimeout } : {},
 			...this.#options.handshakeTimeout !== void 0 ? { handshakeTimeout: this.#options.handshakeTimeout } : {}
 		});
@@ -3551,7 +3866,7 @@ var ItdRealtime = class {
 				this.#attempt = 0;
 				this.#setStatus(RealtimeStatus.Connected);
 			},
-			onEvent: (event) => this.#handleEvent(event.name, event.data),
+			onEvent: (event) => this.#handleEvent(event),
 			onParseError: (error, raw) => this.#emitter.emit("parseError", {
 				error,
 				raw
@@ -3563,25 +3878,48 @@ var ItdRealtime = class {
 			this.#handleFailure(error);
 		});
 	}
-	#handleEvent(name, data) {
-		this.#emitter.emit("message", {
-			name,
-			data
+	#handleEvent(event) {
+		if (!this.#wanted) return;
+		this.#emitter.emit("message", event);
+		if (event.name === "connected") {
+			this.#emitter.emit("ready", { userId: pickString(event.data, "userId") });
+			return;
+		}
+		const update = readRealtimeUpdate(event);
+		if (update) this.#dispatch(update, event, RealtimeUpdateOrigin.Stream);
+	}
+	#dispatch(update, raw, origin) {
+		this.#dispatcher.dispatch({
+			update,
+			stream: this,
+			raw,
+			origin
 		});
-		if (name === "connected") {
-			this.#emitter.emit("ready", { userId: pickString(data, "userId") });
+	}
+	#deliver(update) {
+		if (update.type === RealtimeUpdateType.Notification) {
+			this.#emitter.emit("notification", update.data);
+			if (update.data.unreadCount !== void 0) this.#emitter.emit("unreadCount", update.data.unreadCount);
 			return;
 		}
-		if (name === "notification") {
-			const event = readNotificationEvent(data);
-			this.#emitter.emit("notification", event);
-			if (event.unreadCount !== void 0) this.#emitter.emit("unreadCount", event.unreadCount);
+		if (update.type === RealtimeUpdateType.UnreadCount) {
+			this.#emitter.emit("unreadCount", update.data);
 			return;
 		}
-		if (name === "unread_count") {
-			const count = readUnreadCountEvent(data);
-			if (count !== void 0) this.#emitter.emit("unreadCount", count);
+		if (update.type === RealtimeUpdateType.Unknown) return;
+		assertNeverUpdate(update);
+	}
+	#reportDispatchError(event, error, context) {
+		if (this.#emitter.listenerCount(event) > 0) {
+			this.#emitter.emit(event, {
+				error,
+				context
+			});
+			return;
 		}
+		const message = event === "middlewareError" ? "Ошибка в промежуточном обработчике потока" : "Ошибка в обработчике обновления потока";
+		if (this.#deps.logger) this.#deps.logger.error(message, error);
+		else console.error(`[itd-api] ${message}`, error);
 	}
 	#handleFailure(error) {
 		this.#controller = void 0;
@@ -3619,8 +3957,8 @@ var ItdRealtime = class {
 			attempt: this.#attempt,
 			delay
 		});
-		this.#timer = setTimeout(() => {
-			this.#timer = void 0;
+		this.#cancelTimer = (this.#deps.clock ?? systemClock).schedule(() => {
+			this.#cancelTimer = void 0;
 			this.#run();
 		}, delay);
 	}
@@ -3647,7 +3985,7 @@ var ItdRealtime = class {
 		const target = globalThis;
 		if (typeof target.addEventListener !== "function") return;
 		const wake = () => {
-			if (this.#controller || this.#timer !== void 0) return;
+			if (this.#controller || this.#cancelTimer) return;
 			if (this.#status === RealtimeStatus.Disconnected) return;
 			this.#attempt = 0;
 			this.#run();
@@ -3669,6 +4007,9 @@ var ItdRealtime = class {
 		this.#emitter.emit("status", status);
 	}
 };
+function assertNeverUpdate(update) {
+	throw new TypeError(`Необработанное обновление потока: ${String(update)}`);
+}
 //#endregion
 //#region src/core/pagination.ts
 /** Схема пагинации эндпоинта. */
@@ -7573,7 +7914,7 @@ var ItdClient = class ItdClient {
 		for (const service of BUILT_IN_SERVICES) this.#services.define(service);
 		for (const service of config.services) this.#services.define(service);
 		const shared = config.rateLimit ? internals.queues : void 0;
-		const queues = shared ?? (config.rateLimit ? new RequestQueuePool(config.rateLimit) : void 0);
+		const queues = shared ?? (config.rateLimit ? new RequestQueuePool(config.rateLimit, config.clock) : void 0);
 		this.#queues = queues;
 		this.#ownsQueues = shared === void 0;
 		let authManager;
@@ -7589,6 +7930,7 @@ var ItdClient = class ItdClient {
 		this.#transport = transport;
 		const pluginsLayer = createPluginsMiddleware(this.#plugins);
 		const retriesLayer = createRetryMiddleware({
+			clock: config.clock,
 			retry: config.retry,
 			rateLimitDelays: config.rateLimit?.retryDelays ?? [],
 			pauseQueue: queues ? (ms, request) => queues.for(request.service).pause(ms) : void 0,
@@ -7768,10 +8110,12 @@ var ItdClient = class ItdClient {
 	*
 	* @example
 	* ```ts
+	* import { NotificationType } from 'itd-api';
+	*
 	* const stream = itd.realtime();
 	*
-	* stream.on('notification', ({ notification }) => {
-	*   console.log(formatNotificationText(notification));
+	* stream.onNotification(NotificationType.PostComment, async ({ update }) => {
+	*   await handleComment(update.data.notification);
 	* });
 	* stream.on('unreadCount', (count) => setBadge(count));
 	*
@@ -7789,8 +8133,10 @@ var ItdClient = class ItdClient {
 			getToken: () => this.#authManager.getAccessToken(),
 			refresh: () => this.#authManager.onUnauthorized(),
 			fetchUnreadCount: () => this.notifications.count(),
+			onConnect: () => this.#streams.add(stream),
 			onClose: () => this.#streams.delete(stream),
-			logger: this.#config.logger
+			logger: this.#config.logger,
+			clock: this.#config.clock
 		}, options);
 		this.#streams.add(stream);
 		return stream;
@@ -7799,8 +8145,8 @@ var ItdClient = class ItdClient {
 	* Освобождает ресурсы клиента: закрывает все потоки уведомлений, отправляет открытые
 	* накопители {@link telemetry}, затем останавливает очередь запросов.
 	*
-	* После вызова клиентом можно пользоваться снова — новые запросы поднимут всё заново,
-	* но уже созданные потоки и успешно закрытые накопители останутся закрытыми.
+	* Метод дожидается активных обработчиков потока. После вызова клиентом можно пользоваться
+	* снова; ранее созданный поток можно запустить повторным `connect()`.
 	*
 	* Общая очередь, полученная от {@link ItdAccounts}, не останавливается: её гасит сам
 	* контейнер, когда закрывает все аккаунты разом.
@@ -7813,8 +8159,9 @@ var ItdClient = class ItdClient {
 	* ```
 	*/
 	async close() {
-		this.#disconnectStreams();
+		const streams = this.#disconnectStreams();
 		try {
+			await Promise.all(streams.map((stream) => stream.drain()));
 			await this.telemetry.close();
 		} finally {
 			if (this.#ownsQueues) this.#queues?.stop();
@@ -7833,8 +8180,10 @@ var ItdClient = class ItdClient {
 	}
 	/** Завершает потоки до того, как запросы начнут использовать другой аккаунт. */
 	#disconnectStreams() {
-		for (const stream of [...this.#streams]) stream.disconnect();
+		const streams = [...this.#streams];
+		for (const stream of streams) stream.disconnect();
 		this.#streams.clear();
+		return streams;
 	}
 	/** Позволяет использовать клиент с `await using`. */
 	[Symbol.asyncDispose]() {
@@ -7973,7 +8322,7 @@ var ItdAccounts = class ItdAccounts {
 		this.#plugins = orderPluginDefinitions(plugins ?? []);
 		this.#rateLimitScope = rateLimitScope ?? "account";
 		const rateLimit = this.#rateLimitScope === "shared" ? resolveRateLimit(base.rateLimit) : void 0;
-		this.#queues = rateLimit ? new RequestQueuePool(rateLimit) : void 0;
+		this.#queues = rateLimit ? new RequestQueuePool(rateLimit, base.clock ?? systemClock) : void 0;
 		const logger = typeof base.logger === "object" ? base.logger : void 0;
 		this.#logger = logger;
 		this.#emitter = new Emitter((error) => reportListenerError(logger, "аккаунтов", error));
@@ -8433,6 +8782,87 @@ function resolveNotificationUrl(notification) {
 	return clickUrl || "/notifications";
 }
 //#endregion
+//#region src/realtime/router.ts
+/**
+* Направляет обновления потока в именованные цепочки промежуточных обработчиков.
+*
+* @example
+* ```ts
+* import { RealtimeRouter, RealtimeUpdateType } from 'itd-api';
+*
+* const router = new RealtimeRouter((context) => context.update.type);
+* router.route(RealtimeUpdateType.Notification, async (context, next) => {
+*   if (context.update.type === RealtimeUpdateType.Notification) {
+*     await handleNotification(context.update.data.notification);
+*   }
+*   await next();
+* });
+* stream.use(router.middleware());
+* ```
+*/
+var RealtimeRouter = class {
+	#selector;
+	#routes = /* @__PURE__ */ new Map();
+	#fallback = [];
+	constructor(selector) {
+		if (typeof selector !== "function") throw new require_storage.ItdConfigError("RealtimeRouter принимает функцию выбора маршрута");
+		this.#selector = selector;
+	}
+	/** Добавляет промежуточные обработчики к маршруту и возвращает функцию их удаления. */
+	route(key, ...middleware) {
+		if (!isPropertyKey(key)) throw new require_storage.ItdConfigError("Ключ realtime route должен быть PropertyKey");
+		const registration = this.#registration(middleware);
+		const registrations = this.#routes.get(key) ?? [];
+		registrations.push(registration);
+		this.#routes.set(key, registrations);
+		return () => {
+			const current = this.#routes.get(key);
+			if (!current) return;
+			const index = current.indexOf(registration);
+			if (index >= 0) current.splice(index, 1);
+			if (current.length === 0) this.#routes.delete(key);
+		};
+	}
+	/** Добавляет промежуточные обработчики для обновлений без зарегистрированного маршрута. */
+	otherwise(...middleware) {
+		const registration = this.#registration(middleware);
+		this.#fallback.push(registration);
+		return () => {
+			const index = this.#fallback.indexOf(registration);
+			if (index >= 0) this.#fallback.splice(index, 1);
+		};
+	}
+	/** Возвращает промежуточный обработчик для `stream.use()`. */
+	middleware() {
+		const middleware = (context, next) => this.#captureMiddleware()(context, next);
+		return withRealtimeMiddlewareSnapshot(middleware, () => this.#captureMiddleware());
+	}
+	#captureMiddleware() {
+		const routes = /* @__PURE__ */ new Map();
+		for (const [key, registrations] of this.#routes) routes.set(key, registrations.flatMap(({ middleware }) => middleware).map(captureRealtimeMiddleware));
+		const fallback = this.#fallback.flatMap(({ middleware }) => middleware).map(captureRealtimeMiddleware);
+		return async (context, next) => {
+			const key = await this.#selector(context);
+			if (key != null && !isPropertyKey(key)) throw new require_storage.ItdConfigError("Функция выбора маршрута должна возвращать PropertyKey, null или undefined");
+			const route = key == null ? void 0 : routes.get(key);
+			const chain = route && route.length > 0 ? route : fallback;
+			if (chain.length === 0) {
+				await next();
+				return;
+			}
+			await runRealtimeMiddleware(chain, context, next);
+		};
+	}
+	#registration(middleware) {
+		if (middleware.length === 0) throw new require_storage.ItdConfigError("Маршрут должен содержать хотя бы один обработчик");
+		for (const item of middleware) if (typeof item !== "function") throw new require_storage.ItdConfigError("Маршрут принимает только функции обработки");
+		return { middleware: [...middleware] };
+	}
+};
+function isPropertyKey(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "symbol";
+}
+//#endregion
 //#region src/spans/render.ts
 /** Формат результата {@link renderSpans}. */
 const SpanRenderFormat = Object.freeze({
@@ -8743,8 +9173,11 @@ exports.RECONNECT_JITTER = RECONNECT_JITTER;
 exports.REFRESH_COOKIE = require_multi_storage.REFRESH_COOKIE;
 exports.REFRESH_COOKIE_PATH = require_multi_storage.REFRESH_COOKIE_PATH;
 exports.REQUEST_OPTION_KEYS = REQUEST_OPTION_KEYS;
+exports.RealtimeRouter = RealtimeRouter;
 exports.RealtimeStatus = RealtimeStatus;
 exports.RealtimeTransportKind = RealtimeTransportKind;
+exports.RealtimeUpdateOrigin = RealtimeUpdateOrigin;
+exports.RealtimeUpdateType = RealtimeUpdateType;
 exports.ReportReason = ReportReason;
 exports.ReportTargetType = ReportTargetType;
 exports.RuntimeMode = require_runtime.RuntimeMode;
@@ -8800,6 +9233,7 @@ exports.report = report;
 exports.resolveNotificationUrl = resolveNotificationUrl;
 exports.scopedTokenStorage = require_multi_storage.scopedTokenStorage;
 exports.statusDays = statusDays;
+exports.systemClock = systemClock;
 exports.toDate = toDate;
 exports.utcStampToIso = utcStampToIso;