itd-api 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -130,6 +130,56 @@ function readTokenSubject(token) {
 	return readTokenIdentity(token).subject;
 }
 //#endregion
+//#region src/core/buckets.ts
+/**
+* Ёмкость серверных счётчиков частоты, запросов в минуту.
+*
+* Таблица действует до первого ответа бакета; дальше ёмкость берётся из заголовка
+* `x-ratelimit-limit` и заменяет табличную. `default` — счётчик любого пути без
+* собственного правила на сервере.
+*/
+const BUCKET_LIMITS = Object.freeze({
+	"posts.stats": 180,
+	default: 150,
+	feed: 90,
+	"posts.like": 85,
+	"posts.comments": 80,
+	hashtags: 50,
+	users: 40,
+	notifications: 40,
+	"files.get": 40,
+	auth: 35,
+	"auth.refresh": 25,
+	search: 25,
+	"comments.like": 22,
+	"files.upload": 15,
+	"files.remove": 15,
+	"posts.comment": 14,
+	"hashtags.trending": 13,
+	"posts.repost": 7,
+	"users.follow": 7,
+	"verification.status": 6,
+	"posts.create": 5,
+	"users.updateMe": 3,
+	"reports.create": 3,
+	"verification.submit": 3
+});
+/** Счётчик, из которого списывается путь без собственного правила на сервере. */
+const DEFAULT_RATE_LIMIT_BUCKET = "default";
+/** Известно ли библиотеке имя бакета. */
+function isKnownBucket(name) {
+	return Object.hasOwn(BUCKET_LIMITS, name);
+}
+/** Реакция на остаток лимита из заголовков ответа. */
+const RateLimitPacing = Object.freeze({
+	/** Задержек нет, пока в бакете есть остаток; исчерпанный бакет ждёт `60000 / limit`. */
+	React: "react",
+	/** Ровный темп в пределах минутного лимита: задержки идут с первого запроса. */
+	Smooth: "smooth",
+	/** Остаток на темп не влияет; остаётся пауза после `429`. */
+	Off: "off"
+});
+//#endregion
 //#region src/core/operations.ts
 /** Семантическая безопасность автоматического повтора операции. */
 const RetrySafety = Object.freeze({
@@ -157,59 +207,73 @@ const OPERATIONS = freezeOperations({
 	},
 	"auth.signUp": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.signIn": {
 		method: "POST",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "auth"
 	},
 	"auth.verifyOtp": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.resendOtp": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.refresh": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth.refresh"
 	},
 	"auth.logout": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.forgotPassword": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.resetPassword": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.changePassword": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.sessions": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "auth"
 	},
 	"auth.revokeSession": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"auth.revokeOtherSessions": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "auth"
 	},
 	"users.me": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.updateMe": {
 		method: "PUT",
-		retrySafety: RetrySafety.Idempotent
+		retrySafety: RetrySafety.Idempotent,
+		bucket: "users.updateMe"
 	},
 	"users.deactivate": {
 		method: "DELETE",
@@ -225,39 +289,48 @@ const OPERATIONS = freezeOperations({
 	},
 	"users.get": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.checkUsername": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.search": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.whoToFollow": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.topClans": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.follow": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "users.follow"
 	},
 	"users.unfollow": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "users.follow"
 	},
 	"users.followers": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.following": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.followStatus": {
 		method: "POST",
@@ -273,11 +346,13 @@ const OPERATIONS = freezeOperations({
 	},
 	"users.blocked": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.getPrivacy": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.updatePrivacy": {
 		method: "PUT",
@@ -285,7 +360,8 @@ const OPERATIONS = freezeOperations({
 	},
 	"users.pins": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "users"
 	},
 	"users.setPin": {
 		method: "PUT",
@@ -297,11 +373,13 @@ const OPERATIONS = freezeOperations({
 	},
 	"posts.list": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "feed"
 	},
 	"posts.create": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.create"
 	},
 	"posts.get": {
 		method: "GET",
@@ -321,19 +399,23 @@ const OPERATIONS = freezeOperations({
 	},
 	"posts.like": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.like"
 	},
 	"posts.unlike": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.like"
 	},
 	"posts.repost": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.repost"
 	},
 	"posts.unrepost": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.repost"
 	},
 	"posts.pin": {
 		method: "POST",
@@ -349,7 +431,8 @@ const OPERATIONS = freezeOperations({
 	},
 	"posts.stats": {
 		method: "POST",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "posts.stats"
 	},
 	"posts.byUser": {
 		method: "GET",
@@ -361,11 +444,13 @@ const OPERATIONS = freezeOperations({
 	},
 	"posts.comments": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "posts.comments"
 	},
 	"posts.comment": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "posts.comment"
 	},
 	"comments.replies": {
 		method: "GET",
@@ -389,31 +474,38 @@ const OPERATIONS = freezeOperations({
 	},
 	"comments.like": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "comments.like"
 	},
 	"comments.unlike": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "comments.like"
 	},
 	"files.upload": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "files.upload"
 	},
 	"files.get": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "files.get"
 	},
 	"files.remove": {
 		method: "DELETE",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "files.remove"
 	},
 	"notifications.list": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "notifications"
 	},
 	"notifications.count": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "notifications"
 	},
 	"notifications.markRead": {
 		method: "POST",
@@ -429,7 +521,8 @@ const OPERATIONS = freezeOperations({
 	},
 	"notifications.getSettings": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "notifications"
 	},
 	"notifications.updateSettings": {
 		method: "PUT",
@@ -437,31 +530,38 @@ const OPERATIONS = freezeOperations({
 	},
 	"realtime.poll.updates": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "notifications"
 	},
 	"realtime.poll.unread": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "notifications"
 	},
 	"hashtags.search": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "hashtags"
 	},
 	"hashtags.trending": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "hashtags.trending"
 	},
 	"hashtags.posts": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "hashtags"
 	},
 	"search.all": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "search"
 	},
 	"reports.create": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "reports.create"
 	},
 	"subscription.status": {
 		method: "GET",
@@ -493,11 +593,13 @@ const OPERATIONS = freezeOperations({
 	},
 	"verification.status": {
 		method: "GET",
-		retrySafety: RetrySafety.Safe
+		retrySafety: RetrySafety.Safe,
+		bucket: "verification.status"
 	},
 	"verification.submit": {
 		method: "POST",
-		retrySafety: RetrySafety.Unsafe
+		retrySafety: RetrySafety.Unsafe,
+		bucket: "verification.submit"
 	},
 	"platform.version": {
 		method: "GET",
@@ -541,6 +643,16 @@ function operationMethod(id) {
 function operationRetrySafety(id) {
 	return OPERATIONS[id].retrySafety;
 }
+/**
+* Бакет операции.
+*
+* `raw` и `custom:*` попадают в `default`; назвать бакет явно позволяет
+* `rateLimitBucket` у запроса.
+*/
+function operationBucket(id) {
+	if (!isBuiltInOperationId(id)) return DEFAULT_RATE_LIMIT_BUCKET;
+	return OPERATIONS[id].bucket ?? "default";
+}
 //#endregion
 //#region src/core/runtime.ts
 /**
@@ -1220,7 +1332,7 @@ function createDeadline(timeout, clock = systemClock) {
 //#endregion
 //#region src/core/version.ts
 /** Версия библиотеки. Попадает в `User-Agent`. */
-const LIBRARY_VERSION = "0.6.0";
+const LIBRARY_VERSION = "0.7.0";
 //#endregion
 //#region src/core/config.ts
 /** Базовый URL API итд.com. Домен записан в punycode: `итд.com`. */
@@ -1249,9 +1361,8 @@ const DEFAULT_USER_AGENT = `Mozilla/5.0 (compatible; itd-api/${LIBRARY_VERSION};
 /**
 * Паузы перед повторами при ответе `429`.
 *
-* Сервер итд.com не присылает `Retry-After` и не сообщает время сброса окна, поэтому
-* паузу приходится подбирать лестницей: от секунды, если окно почти истекло,
-* до полутора минут, если лимит исчерпан всерьёз.
+* Сервер итд.com не присылает `Retry-After` и не сообщает время сброса окна, поэтому паузу
+* приходится подбирать лестницей: от секунды, если окно почти истекло, до полутора минут.
 */
 const DEFAULT_RATE_LIMIT_DELAYS = Object.freeze([
 	1e3,
@@ -1260,6 +1371,13 @@ const DEFAULT_RATE_LIMIT_DELAYS = Object.freeze([
 	6e4,
 	9e4
 ]);
+/**
+* Встроенные поправки бакетов.
+*
+* Таймаут загрузки файла — пять минут против обычных тридцати секунд, поэтому её
+* одновременность ограничена одним запросом.
+*/
+const DEFAULT_BUCKET_OVERRIDES = Object.freeze({ "files.upload": Object.freeze({ concurrency: 1 }) });
 function requirePositive(value, name) {
 	if (!Number.isFinite(value) || value < 0) throw new require_storage.ItdConfigError(`${name} должен быть неотрицательным числом, получено: ${value}`);
 	return value;
@@ -1348,6 +1466,54 @@ function resolveRetry(retry) {
 	};
 }
 /**
+* Сверяет имя бакета со встроенной картой.
+*
+* Своё правило выбора заводит собственное пространство имён, и встроенные имена в нём
+* необязательны — тогда проверка снимается.
+*
+* @param option путь опции для текста ошибки
+* @throws {ItdConfigError} если имени нет во встроенной карте
+*
+* @internal
+*/
+function assertKnownBucket(name, option, bucket) {
+	if (bucket !== void 0 || isKnownBucket(name)) return;
+	throw new require_storage.ItdConfigError(`${option}: бакета «${name}» нет. Известны: ${Object.keys(BUCKET_LIMITS).join(", ")}`);
+}
+function requireConcurrency(value, name) {
+	if (!Number.isInteger(value) || value < 1) throw new require_storage.ItdConfigError(`${name} должен быть целым числом от 1, получено: ${value}`);
+	return value;
+}
+function resolvePacing(pacing) {
+	const known = Object.values(RateLimitPacing);
+	if (pacing !== void 0 && !known.includes(pacing)) throw new require_storage.ItdConfigError(`rateLimit.pacing должен быть одним из ${known.join(", ")}, получено: ${pacing}`);
+	return pacing ?? RateLimitPacing.React;
+}
+/**
+* Проверяет поправки бакетов и накладывает их на встроенные.
+*
+* Имена сверяются со встроенной картой, пока не задано своё правило выбора бакета.
+* Поля сливаются по отдельности: своя ёмкость `files.upload` не снимает встроенный
+* предел одновременности.
+*/
+function resolveBucketOverrides(overrides, bucket) {
+	if (overrides === void 0) return DEFAULT_BUCKET_OVERRIDES;
+	if (!isRecord$1(overrides)) throw new require_storage.ItdConfigError("rateLimit.bucketOverrides должен быть объектом");
+	const resolved = { ...DEFAULT_BUCKET_OVERRIDES };
+	for (const [name, override] of Object.entries(overrides)) {
+		if (!isRecord$1(override)) throw new require_storage.ItdConfigError(`rateLimit.bucketOverrides.${name} должен быть объектом`);
+		assertKnownBucket(name, "rateLimit.bucketOverrides", bucket);
+		if (override.concurrency !== void 0) requireConcurrency(override.concurrency, `rateLimit.bucketOverrides.${name}.concurrency`);
+		if (override.limit !== void 0 && (!Number.isFinite(override.limit) || override.limit <= 0)) throw new require_storage.ItdConfigError(`rateLimit.bucketOverrides.${name}.limit должен быть положительным числом, получено: ${override.limit}`);
+		const built = DEFAULT_BUCKET_OVERRIDES[name];
+		resolved[name] = Object.freeze({
+			concurrency: override.concurrency ?? built?.concurrency,
+			limit: override.limit ?? built?.limit
+		});
+	}
+	return Object.freeze(resolved);
+}
+/**
 * Приводит настройки очереди к полному виду. `undefined` — очередь не нужна.
 *
 * Кроме создания клиента вызывается ещё из {@link ItdAccounts}: общая на всех аккаунтов
@@ -1364,21 +1530,29 @@ function resolveRateLimit(rateLimit) {
 		concurrency: 6,
 		rps: void 0,
 		retryDelays: DEFAULT_RATE_LIMIT_DELAYS,
-		respectHeaders: true
+		buckets: true,
+		pacing: RateLimitPacing.React,
+		bucketConcurrency: 6,
+		bucketOverrides: DEFAULT_BUCKET_OVERRIDES,
+		bucket: void 0
 	};
 	if (!rateLimit) return defaults;
-	const concurrency = rateLimit.concurrency ?? 6;
-	if (!Number.isInteger(concurrency) || concurrency < 1) throw new require_storage.ItdConfigError(`rateLimit.concurrency должен быть целым числом от 1, получено: ${concurrency}`);
+	const concurrency = requireConcurrency(rateLimit.concurrency ?? 6, "rateLimit.concurrency");
 	if (rateLimit.rps !== void 0 && (!Number.isFinite(rateLimit.rps) || rateLimit.rps <= 0)) throw new require_storage.ItdConfigError(`rateLimit.rps должен быть положительным числом, получено: ${rateLimit.rps}`);
 	const retryDelays = rateLimit.retryDelays ?? defaults.retryDelays;
 	if (!Array.isArray(retryDelays)) throw new require_storage.ItdConfigError("rateLimit.retryDelays должен быть массивом чисел");
 	for (const delay of retryDelays) requirePositive(delay, "rateLimit.retryDelays");
-	requireOptionalBoolean(rateLimit.respectHeaders, "rateLimit.respectHeaders");
+	requireOptionalBoolean(rateLimit.buckets, "rateLimit.buckets");
+	if (rateLimit.bucket !== void 0 && typeof rateLimit.bucket !== "function") throw new require_storage.ItdConfigError("rateLimit.bucket должен быть функцией");
 	return {
 		concurrency,
 		rps: rateLimit.rps,
 		retryDelays: [...retryDelays],
-		respectHeaders: rateLimit.respectHeaders ?? true
+		buckets: rateLimit.buckets ?? true,
+		pacing: resolvePacing(rateLimit.pacing),
+		bucketConcurrency: requireConcurrency(rateLimit.bucketConcurrency ?? concurrency, "rateLimit.bucketConcurrency"),
+		bucketOverrides: resolveBucketOverrides(rateLimit.bucketOverrides, rateLimit.bucket),
+		bucket: rateLimit.bucket
 	};
 }
 /**
@@ -1476,6 +1650,7 @@ function resolveConfig(options = {}) {
 //#endregion
 //#region src/core/pipeline.ts
 const REQUEST_ATTEMPT_STATE = Symbol("itd-api.request-attempt-state");
+const REQUEST_QUEUE_KEY = Symbol("itd-api.request-queue-key");
 const DISPOSE_CLEANUP_REQUEST = Symbol("itd-api.dispose-cleanup-request");
 /** Один раз присваивает низкоуровневому запросу семантический ID до входа в middleware. */
 function identifyRequest(request) {
@@ -1507,6 +1682,23 @@ function beginTransportAttempt(request) {
 function currentTransportAttempt(request) {
 	return request[REQUEST_ATTEMPT_STATE]?.value ?? 0;
 }
+/**
+* Вычисляет ключ очереди один раз на логическую операцию.
+*
+* Ключ спрашивают трижды: при постановке в очередь, при чтении заголовков ответа и при
+* паузе после `429`. Значение пишется прямо в объект запроса — слои ниже копируют его
+* через spread, и перечислимое символьное поле переходит в копии.
+*
+* @internal
+*/
+function requestQueueKey(request, compute) {
+	const internal = request;
+	const cached = internal[REQUEST_QUEUE_KEY];
+	if (cached) return cached;
+	const key = compute(request);
+	internal[REQUEST_QUEUE_KEY] = key;
+	return key;
+}
 /** Помечает запрос как часть внутренней финализации уже начатого `dispose()`. @internal */
 function markDisposeCleanupRequest(request) {
 	return {
@@ -1851,7 +2043,7 @@ function createRetryMiddleware(deps) {
 			const transportAttempt = currentTransportAttempt(trackedRequest);
 			if (require_storage.isItdRateLimitError(error)) rateLimitAttempt += 1;
 			else retryAttempt += 1;
-			const delay = nextDelay(error, retryAttempt, rateLimitAttempt, request, policy, backoff);
+			const delay = nextDelay(error, retryAttempt, rateLimitAttempt, trackedRequest, policy, backoff);
 			if (delay === void 0) throw error;
 			await dispatchRequestHook(deps.hooks, "onRetry", {
 				operationId: request.operationId,
@@ -2240,6 +2432,10 @@ var PluginRegistry = class {
 function queueAbortError() {
 	return new require_storage.ItdAbortError("Запрос отменён во время ожидания очереди");
 }
+/** Ошибка запроса, которого застала остановка очереди. */
+function queueStoppedError() {
+	return new require_storage.ItdAbortError("Клиент закрыт, запрос отменён");
+}
 /**
 * Очередь запросов: ограничивает одновременность и частоту.
 *
@@ -2255,6 +2451,7 @@ var RequestQueue = class {
 	#concurrency;
 	/** Минимальный промежуток между стартами, мс. `0` — без ограничения частоты. */
 	#minGap;
+	#onDispatch;
 	#waiting = [];
 	#active = 0;
 	/** Момент, раньше которого следующий запрос стартовать не должен. */
@@ -2264,6 +2461,7 @@ var RequestQueue = class {
 	constructor(options, clock = systemClock) {
 		this.#concurrency = options.concurrency;
 		this.#minGap = options.rps ? 1e3 / options.rps : 0;
+		this.#onDispatch = options.onDispatch;
 		this.#clock = clock;
 	}
 	/** Сколько задач выполняется прямо сейчас. */
@@ -2295,6 +2493,7 @@ var RequestQueue = class {
 				run: () => {
 					detach();
 					this.#active += 1;
+					this.#onDispatch?.();
 					Promise.resolve().then(task).then(resolve, reject).finally(() => {
 						this.#active -= 1;
 						this.#drain();
@@ -2320,16 +2519,10 @@ var RequestQueue = class {
 			this.#cancelTimer();
 			this.#cancelTimer = void 0;
 		}
-		this.#nextSlot = 0;
 		const pending = this.#waiting.splice(0, this.#waiting.length);
-		for (const task of pending) task.cancel(new require_storage.ItdAbortError("Клиент закрыт, запрос отменён"));
+		for (const task of pending) task.cancel(queueStoppedError());
 	}
-	/**
-	* Придерживает всю очередь на заданное время.
-	*
-	* Вызывается при получении `429` с заголовком `Retry-After`: тормозить нужно все запросы,
-	* а не только тот, который наткнулся на лимит, — иначе остальные продолжат добивать API.
-	*/
+	/** Придерживает очередь на заданное время: ждут все её задачи, а не только одна. */
 	pause(ms) {
 		if (ms <= 0) return;
 		this.#nextSlot = Math.max(this.#nextSlot, this.#clock.now() + ms);
@@ -2360,40 +2553,241 @@ var RequestQueue = class {
 		this.#drain();
 	}
 };
+/** Длина окна лимита на сервере. */
+const RATE_LIMIT_WINDOW = 6e4;
+/**
+* Пауза при исчерпании бакета неизвестной ёмкости.
+*
+* Ёмкость приходит в заголовке вместе с остатком, поэтому случай возможен только у чужого
+* прокси, который прислал `remaining` без `limit`.
+*/
+const UNKNOWN_CAPACITY_PAUSE = 1e3;
+/**
+* Очередь одного бакета поверх общей очереди направления.
+*
+* Задача занимает слот бакета, затем общий слот направления, поэтому суммарная
+* одновременность остаётся равной `concurrency`. Пауза бакета удерживает задачу до
+* захвата общего слота: притормозивший счётчик не занимает общую ёмкость.
+*
+* @internal
+*/
+var BucketQueue = class {
+	#destination;
+	#bucket;
+	#gate;
+	#shared;
+	#clock;
+	#pacing;
+	/** Ровный темп. Требует раздельных бакетов: без них ёмкость счётчика неизвестна. */
+	#smooth;
+	/**
+	* Пауза на исчерпанный остаток в режиме `buckets: false`; `undefined` — бакеты разделены.
+	*
+	* Одна очередь на направление принимает заголовки всех счётчиков вперемешку, поэтому
+	* `x-ratelimit-limit` принадлежит тому счётчику, который ответил последним, и ёмкость
+	* очереди из него не выводится: ответ `posts.create` с ёмкостью 5 остановил бы всё
+	* направление на двенадцать секунд. Вместо расчёта берётся первая ступень `retryDelays`.
+	*/
+	#flatPause;
+	/** Лимит бакета до первого ответа. */
+	#seedLimit;
+	/** Последнее, что сказал сервер. Живёт и в режиме `off` — ради `rateLimitState()`. */
+	#limit;
+	#remaining;
+	/**
+	* Оценка остатка для режима `smooth`.
+	*
+	* Начинается с единицы, а не с полной ёмкости: где сейчас граница минутного окна,
+	* из ответа не вывести, и считать бакет нетронутым нельзя.
+	*/
+	#tokens = 1;
+	#tokensAt;
+	/**
+	* Номер поколения очереди. `stop()` увеличивает его, отсекая задачи, которые уже взяли
+	* слот бакета, но до общей очереди ещё не дошли.
+	*/
+	#generation = 0;
+	constructor(destination, bucket, shared, options, clock) {
+		this.#destination = destination;
+		this.#bucket = bucket;
+		this.#shared = shared;
+		this.#clock = clock;
+		this.#pacing = options.pacing;
+		this.#smooth = options.buckets && options.pacing === RateLimitPacing.Smooth;
+		this.#flatPause = options.buckets ? void 0 : options.retryDelays[0] ?? 0;
+		this.#seedLimit = options.buckets ? seedLimit(bucket, options) : void 0;
+		this.#gate = new RequestQueue({
+			concurrency: options.buckets ? options.bucketOverrides[bucket]?.concurrency ?? options.bucketConcurrency : options.concurrency,
+			onDispatch: this.#smooth ? () => this.#spend() : void 0
+		}, clock);
+	}
+	/** Имя счётчика. При `buckets: false` — всегда `default`, каким бы ни был запрос. */
+	get bucket() {
+		return this.#bucket;
+	}
+	/** Запросов бакета прошло в общую очередь и ещё не завершилось. */
+	get active() {
+		return this.#gate.active;
+	}
+	/** Запросов бакета ждёт своей очереди. */
+	get pending() {
+		return this.#gate.pending;
+	}
+	/** Ставит запрос в очередь: сначала слот бакета, затем общий слот направления. */
+	schedule(task, signal) {
+		const generation = this.#generation;
+		return this.#gate.schedule(() => {
+			if (generation !== this.#generation) return Promise.reject(queueStoppedError());
+			return this.#shared.schedule(task, signal);
+		}, signal);
+	}
+	/**
+	* Учитывает заголовки ответа.
+	*
+	* Вызывается после каждого ответа, включая ошибочные: сервер списывает квоту одинаково
+	* с `404`, `422` и `200`.
+	*
+	* @returns на сколько миллисекунд придержан бакет; `0` — темп не ограничен
+	*/
+	observe(limit, remaining) {
+		if (limit !== void 0 && Number.isFinite(limit) && limit > 0) this.#limit = limit;
+		if (remaining !== void 0) this.#remaining = remaining;
+		if (this.#pacing === RateLimitPacing.Off || remaining === void 0) return 0;
+		if (this.#flatPause !== void 0) {
+			if (remaining > 0) return 0;
+			this.#gate.pause(this.#flatPause);
+			return this.#flatPause;
+		}
+		const capacity = this.#capacity();
+		if (this.#smooth) {
+			if (capacity === void 0) return 0;
+			this.#refill(capacity);
+			if (remaining < this.#tokens) this.#tokens = remaining;
+			return this.#armPause(capacity);
+		}
+		if (remaining > 0) return 0;
+		const wait = capacity === void 0 ? UNKNOWN_CAPACITY_PAUSE : Math.ceil(RATE_LIMIT_WINDOW / Math.max(capacity, 1));
+		this.#gate.pause(wait);
+		return wait;
+	}
+	/** Придерживает бакет на названное время — путь ответа `429`. Оценка остатка обнуляется. */
+	pause(ms) {
+		if (this.#smooth) {
+			this.#tokens = 0;
+			this.#tokensAt = this.#clock.now();
+		}
+		this.#gate.pause(ms);
+	}
+	/** Снимок для `rateLimitState()`. */
+	state() {
+		return {
+			destination: this.#destination,
+			bucket: this.#bucket,
+			limit: this.#limit,
+			remaining: this.#remaining,
+			active: this.#gate.active,
+			pending: this.#gate.pending
+		};
+	}
+	/**
+	* Останавливает уровень бакета. Общая очередь направления гасится пулом.
+	*
+	*/
+	stop() {
+		this.#generation += 1;
+		this.#gate.stop();
+	}
+	/** Лимит бакета: сказанный сервером, иначе табличный. */
+	#capacity() {
+		return this.#limit ?? this.#seedLimit;
+	}
+	/** Списывает токен на уходящий запрос и придерживает бакет до следующего. */
+	#spend() {
+		const capacity = this.#capacity();
+		if (capacity === void 0) return;
+		this.#refill(capacity);
+		this.#tokens -= 1;
+		this.#armPause(capacity);
+	}
+	/** Возвращает накопленное с прошлой проверки: `limit` единиц за минуту. */
+	#refill(capacity) {
+		const now = this.#clock.now();
+		if (this.#tokensAt !== void 0) {
+			const restored = (now - this.#tokensAt) * capacity / RATE_LIMIT_WINDOW;
+			this.#tokens = Math.min(capacity, this.#tokens + restored);
+		}
+		this.#tokensAt = now;
+	}
+	/** Держит бакет, пока не накопится хотя бы один токен. */
+	#armPause(capacity) {
+		if (this.#tokens >= 1) return 0;
+		const wait = Math.ceil((1 - this.#tokens) * RATE_LIMIT_WINDOW / capacity);
+		this.#gate.pause(wait);
+		return wait;
+	}
+};
+/** Лимит бакета до первого ответа: поправка пользователя важнее табличного значения. */
+function seedLimit(bucket, options) {
+	const override = options.bucketOverrides[bucket]?.limit;
+	if (override !== void 0) return override;
+	return isKnownBucket(bucket) ? BUCKET_LIMITS[bucket] : void 0;
+}
 /**
-* Очереди по конечным направлениям запросов.
+* Очереди по парам «направление — серверный счётчик частоты».
 *
-* Ключом обычно служит origin уже разрешённого URL. Поэтому разные локальные имена одного
-* хоста разделяют лимит, а запрос с разовым внешним `baseUrl` не попадает в основную очередь.
+* Направление — origin уже разрешённого URL: разные локальные имена одного хоста делят
+* лимит, а запрос с разовым внешним `baseUrl` не попадает в основную очередь. Мощность
+* карты ограничена каталогом операций, поэтому ни TTL, ни вытеснение не нужны.
 *
 * @internal
 */
 var RequestQueuePool = class {
 	#options;
 	#clock;
-	#main;
-	/** Очереди направлений заводятся при первом запросе. */
-	#byDestination = /* @__PURE__ */ new Map();
+	/** Ключ `undefined` — основная очередь внутренних клиентов без известного направления. */
+	#destinations = /* @__PURE__ */ new Map();
 	constructor(options, clock = systemClock) {
 		this.#options = options;
 		this.#clock = clock;
-		this.#main = new RequestQueue(options, clock);
 	}
-	/** Очередь направления. `undefined` сохраняет основную очередь для внутренних клиентов. */
-	for(destination) {
-		if (destination === void 0) return this.#main;
-		let queue = this.#byDestination.get(destination);
+	/** Очередь бакета на направлении. При `buckets: false` бакет всегда `default`. */
+	for(destination, bucket = DEFAULT_RATE_LIMIT_BUCKET) {
+		const name = this.#options.buckets ? bucket : DEFAULT_RATE_LIMIT_BUCKET;
+		let entry = this.#destinations.get(destination);
+		if (!entry) {
+			entry = {
+				shared: new RequestQueue(this.#options, this.#clock),
+				buckets: /* @__PURE__ */ new Map()
+			};
+			this.#destinations.set(destination, entry);
+		}
+		let queue = entry.buckets.get(name);
 		if (!queue) {
-			queue = new RequestQueue(this.#options, this.#clock);
-			this.#byDestination.set(destination, queue);
+			queue = new BucketQueue(destination, name, entry.shared, this.#options, this.#clock);
+			entry.buckets.set(name, queue);
 		}
 		return queue;
 	}
-	/** Останавливает все очереди. */
+	/** Снимки всех бакетов, о которых что-то известно. */
+	states() {
+		const states = [];
+		for (const entry of this.#destinations.values()) for (const queue of entry.buckets.values()) states.push(queue.state());
+		return states;
+	}
+	/**
+	* Останавливает оба уровня всех очередей: ожидающие задачи отклоняются, а состояние
+	* счётчиков и отложенные паузы сохраняются до следующего запуска — путь `close()`.
+	*/
 	stop() {
-		this.#main.stop();
-		for (const queue of this.#byDestination.values()) queue.stop();
-		this.#byDestination.clear();
+		for (const entry of this.#destinations.values()) {
+			for (const queue of entry.buckets.values()) queue.stop();
+			entry.shared.stop();
+		}
+	}
+	/** Останавливает очереди и забывает всё, что известно о счётчиках, — путь `dispose()`. */
+	clear() {
+		this.stop();
+		this.#destinations.clear();
 	}
 };
 //#endregion
@@ -2761,6 +3155,11 @@ function readIntHeader(headers, name) {
 	const value = Number.parseInt(raw, 10);
 	return Number.isFinite(value) ? value : void 0;
 }
+/** Читает положительное целое число из заголовка. */
+function readPositiveIntHeader(headers, name) {
+	const value = readIntHeader(headers, name);
+	return value !== void 0 && value > 0 ? value : void 0;
+}
 /**
 * Читает сведения об ограничении частоты.
 *
@@ -2769,7 +3168,7 @@ function readIntHeader(headers, name) {
 */
 function readRateLimit(headers) {
 	return {
-		limit: readIntHeader(headers, "x-ratelimit-limit"),
+		limit: readPositiveIntHeader(headers, "x-ratelimit-limit"),
 		remaining: readIntHeader(headers, "x-ratelimit-remaining")
 	};
 }
@@ -3252,31 +3651,43 @@ function createClientRuntime(options = {}, internals = {}) {
 	const ownsQueues = sharedQueues === void 0;
 	let auth;
 	let transport;
+	/**
+	* Бакет, из которого спишется запрос.
+	*
+	* Источники по убыванию приоритета: `rateLimitBucket` запроса, правило `rateLimit.bucket`,
+	* каталог операций.
+	*/
+	const bucketFor = (request) => {
+		if (request.rateLimitBucket !== void 0) return request.rateLimitBucket;
+		return config.rateLimit?.bucket?.({
+			operationId: request.operationId,
+			method: request.method,
+			path: request.path
+		}) ?? operationBucket(request.operationId);
+	};
+	const queueKeyFor = (request) => requestQueueKey(request, (target) => ({
+		destination: require_multi_storage.originOf(transport.buildUrl(target)) || void 0,
+		bucket: bucketFor(target)
+	}));
 	const queueFor = (request) => {
-		const destination = require_multi_storage.originOf(transport.buildUrl(request));
-		return queues?.for(destination || void 0);
+		if (!queues) return void 0;
+		const key = queueKeyFor(request);
+		return queues.for(key.destination, key.bucket);
 	};
-	/**
-	* Сервер сообщает остаток окна в `x-ratelimit-remaining`, но не сообщает момент сброса.
-	* При нуле заранее ставим очередь конечного origin на первую, самую короткую паузу из
-	* `retryDelays`: окно могло почти истечь, поэтому длинный backoff здесь преждевременен.
-	* Если окно всё ещё закрыто, следующий `429` применит самостоятельную лестницу повторов.
-	* Общая пауза очереди не даёт параллельным запросам одновременно ударить в тот же лимит.
-	*/
-	const throttleByHeaders = (limit, remaining, request) => {
-		if (remaining === void 0 || remaining > 0) return;
-		const first = config.rateLimit?.retryDelays[0];
-		if (first === void 0) return;
-		queueFor(request)?.pause(first);
-		config.logger?.debug(`лимит сервера исчерпан (${remaining} из ${limit ?? "?"}), очередь ждёт ${first} мс`);
+	/** Передаёт остаток из заголовков ответа бакету запроса; тот решает, тормозить ли себя. */
+	const observeRateLimit = (limit, remaining, request) => {
+		const queue = queueFor(request);
+		if (!queue) return;
+		const waited = queue.observe(limit, remaining);
+		if (waited > 0) config.logger?.debug(`остаток лимита ${remaining} из ${limit ?? "?"}, бакет ${queue.bucket} ждёт ${waited} мс`);
 	};
 	transport = new Transport({
 		...config,
 		hooks: config.hooks
 	}, {
+		onRateLimit: queues ? observeRateLimit : void 0,
 		cookies: config.useCookieJar ? jar : void 0,
 		getDeviceId: () => auth.getDeviceId(),
-		onRateLimit: queues && config.rateLimit?.respectHeaders ? throttleByHeaders : void 0,
 		lifetimeSignal: lifetime.signal
 	});
 	const stages = [
@@ -3331,6 +3742,7 @@ function createClientRuntime(options = {}, internals = {}) {
 	const clientHandler = (request) => {
 		try {
 			if (!isDisposeCleanupRequest(request)) internals.assertActive?.("выполнить новый запрос");
+			if (request.rateLimitBucket !== void 0) assertKnownBucket(request.rateLimitBucket, "rateLimitBucket", config.rateLimit?.bucket);
 		} catch (error) {
 			return Promise.reject(error);
 		}
@@ -3351,11 +3763,13 @@ function createClientRuntime(options = {}, internals = {}) {
 		services,
 		stageOrder,
 		platformHeaders: (url) => transport.platformHeaders(url),
+		rateLimitState: () => queues?.states() ?? [],
 		close: () => {
 			if (ownsQueues) queues?.stop();
 		},
 		dispose: async () => {
 			lifetime.abort(new require_storage.ItdAbortError("Клиент освобождён через dispose(), запрос отменён"));
+			if (ownsQueues) queues?.clear();
 			auth.dispose();
 			await plugins.dispose();
 		}
@@ -9078,6 +9492,22 @@ var ItdClient = class ItdClient {
 		});
 	}
 	/**
+	* Остаток серверных лимитов по бакетам, через которые уже проходили запросы.
+	*
+	* Значения берутся из последнего ответа каждого бакета и быстро устаревают: сервер
+	* восстанавливает квоту линейно и границу окна не сообщает. Пустой массив при
+	* `rateLimit: false`. {@link close} снимок сохраняет, {@link dispose} очищает.
+	*
+	* @example
+	* ```ts
+	* const posts = itd.rateLimitState().find((state) => state.bucket === 'posts.create');
+	* if ((posts?.remaining ?? Number.POSITIVE_INFINITY) < 3) await sleep(60_000);
+	* ```
+	*/
+	rateLimitState() {
+		return this.#runtime.rateLimitState();
+	}
+	/**
 	* Подключает плагин.
 	*
 	* Плагин может независимо регистрировать transformer логической операции и interceptor
@@ -9447,7 +9877,7 @@ var ItdAccounts = class ItdAccounts {
 		this.#base = base;
 		this.#storage = storage ?? new require_multi_storage.MemoryMultiTokenStorage();
 		this.#plugins = orderPluginDefinitions(plugins ?? []);
-		this.#rateLimitScope = rateLimitScope ?? "account";
+		this.#rateLimitScope = rateLimitScope ?? "shared";
 		const rateLimit = this.#rateLimitScope === "shared" ? resolveRateLimit(base.rateLimit) : void 0;
 		this.#queues = rateLimit ? new RequestQueuePool(rateLimit, base.clock ?? systemClock) : void 0;
 		const logger = typeof base.logger === "object" ? base.logger : void 0;
@@ -9739,7 +10169,7 @@ var ItdAccounts = class ItdAccounts {
 			...clients.map((client) => client.dispose()),
 			...controls.map((control) => control.drain()),
 			...accountRemovals,
-			Promise.resolve().then(() => this.#queues?.stop())
+			Promise.resolve().then(() => this.#queues?.clear())
 		]);
 		this.#plugins.splice(0);
 		this.#removingPlugins.clear();
@@ -10775,8 +11205,10 @@ exports.ALLOWED_MIME_TYPES = ALLOWED_MIME_TYPES;
 exports.AUDIO_MIME_TYPES = AUDIO_MIME_TYPES;
 exports.AccessType = AccessType;
 exports.AttachmentType = AttachmentType;
+exports.BUCKET_LIMITS = BUCKET_LIMITS;
 exports.CommentSort = CommentSort;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_RATE_LIMIT_BUCKET = DEFAULT_RATE_LIMIT_BUCKET;
 exports.FeedTab = FeedTab;
 exports.FileTransferMode = require_multi_storage.FileTransferMode;
 exports.IMAGE_MIME_TYPES = IMAGE_MIME_TYPES;
@@ -10814,6 +11246,7 @@ exports.NotificationType = NotificationType;
 exports.OPERATIONS = OPERATIONS;
 exports.PaginationMode = PaginationMode;
 exports.Paginator = Paginator;
+exports.RateLimitPacing = RateLimitPacing;
 exports.RealtimeComposer = RealtimeComposer;
 exports.RealtimeRouter = RealtimeRouter;
 exports.RealtimeStatus = RealtimeStatus;
@@ -10868,6 +11301,7 @@ exports.isMyProfile = isMyProfile;
 exports.mapPage = mapPage;
 exports.markup = markup;
 exports.normalizeNotification = normalizeNotification;
+exports.operationBucket = operationBucket;
 exports.operationMethod = operationMethod;
 exports.operationRetrySafety = operationRetrySafety;
 exports.parseHtml = parseHtml;