itd-api 0.7.1 → 0.7.2

package/dist/shared/{render-vtLixIiU.js → render-C6HRPs10.js}

@@ -1,7 +1,270 @@
-import { F as pickArray, I as pickBoolean, L as pickNumber, P as isRecord, R as pickObject, et as createDeviceId, nt as isFile, p as InteractionType, q as STATUS_SERVICE, r as normalizeNotification, tt as isBlob, v as ReportReason, x as SpanType, y as ReportTargetType, z as pickString } from "./url-CYXgxqGx.js";
-import { a as ItdConfigError, l as ItdFileError, s as ItdError, u as ItdFileErrorReason } from "./errors-Bhrd2fJd.js";
+import { F as pickArray, H as RetrySafety, I as pickBoolean, J as DEFAULT_STATUS_BASE_URL, L as pickNumber, P as isRecord, R as pickObject, U as mergeService, Y as STATUS_SERVICE, it as isFile, nt as createDeviceId, p as InteractionType, r as normalizeNotification, rt as isBlob, v as ReportReason, x as SpanType, y as ReportTargetType, z as pickString } from "./url-IU0xN9wX.js";
+import { _ as ItdStateError, a as ItdConfigError, l as ItdFileError, s as ItdError, t as ItdAbortError, u as ItdFileErrorReason } from "./errors-Bhrd2fJd.js";
 import { o as encodePathSegment } from "./cookies-tX2sNwxb.js";
 import { a as fileTooLarge, c as FileTransferMode, i as isReadableByteStream, n as boundedFileStream, o as optionalBytes, r as isBoundedFileStream, s as DEFAULT_URL_FILE_MAX_BYTES, t as resolveFileStreamOptions } from "./options-DtATYdLr.js";
+//#region src/core/feature-catalog.ts
+/**
+* Изменяемый слой над каталогом конкретного API.
+*
+* Базовый каталог остаётся замороженным и общим для всех клиентов, а регистрации feature
+* принадлежат одному facade. Поэтому установка модуля в одном клиенте не меняет остальные.
+*
+* @internal
+*/
+var ExtensibleOperationCatalog = class {
+	#base;
+	#operations = /* @__PURE__ */ new Map();
+	#operationOwners = /* @__PURE__ */ new Map();
+	#bucketOwners = /* @__PURE__ */ new Map();
+	#bucketLimits;
+	#bucketOverrides;
+	constructor(base) {
+		this.#base = base;
+		this.#bucketLimits = { ...base.bucketLimits };
+		this.#bucketOverrides = { ...base.bucketOverrides };
+	}
+	get bucketLimits() {
+		return this.#bucketLimits;
+	}
+	get bucketOverrides() {
+		return this.#bucketOverrides;
+	}
+	get defaultBucket() {
+		return this.#base.defaultBucket;
+	}
+	retrySafetyOf(id) {
+		return this.#operations.get(id)?.retrySafety ?? this.#base.retrySafetyOf(id);
+	}
+	methodOf(id) {
+		return this.#operations.get(id)?.method ?? this.#base.methodOf(id);
+	}
+	bucketOf(id) {
+		return this.#operations.get(id)?.bucket ?? this.#base.bucketOf(id);
+	}
+	isKnownBucket(name) {
+		return this.#bucketOwners.has(name) || this.#base.isKnownBucket(name);
+	}
+	/** Регистрирует принадлежащий feature бакет и возвращает откат регистрации. */
+	registerBucket(owner, name, definition) {
+		if (this.#base.isKnownBucket(name) || this.#bucketOwners.has(name)) throw new ItdConfigError(`feature «${owner}»: бакет «${name}» уже зарегистрирован`);
+		this.#bucketOwners.set(name, owner);
+		if (definition.limit !== void 0) this.#bucketLimits[name] = definition.limit;
+		if (definition.concurrency !== void 0) this.#bucketOverrides[name] = Object.freeze({ concurrency: definition.concurrency });
+		return () => {
+			if (this.#bucketOwners.get(name) !== owner) return;
+			this.#bucketOwners.delete(name);
+			delete this.#bucketLimits[name];
+			delete this.#bucketOverrides[name];
+		};
+	}
+	/** Регистрирует операцию и возвращает откат регистрации. */
+	registerOperation(owner, id, definition) {
+		const ownerPrefix = `${owner}.`;
+		if (!id.startsWith(ownerPrefix) || id.length === ownerPrefix.length) throw new ItdConfigError(`feature «${owner}»: операция «${id}» должна находиться в пространстве имён «${owner}»`);
+		const occupiedBy = this.#operationOwners.get(id);
+		if (occupiedBy !== void 0) throw new ItdConfigError(`feature «${owner}»: операция «${id}» уже зарегистрирована feature «${occupiedBy}»`);
+		if (this.#base.methodOf(id) !== void 0) throw new ItdConfigError(`feature «${owner}»: операция «${id}» уже существует в базовом каталоге`);
+		this.#operationOwners.set(id, owner);
+		this.#operations.set(id, Object.freeze({ ...definition }));
+		return () => {
+			if (this.#operationOwners.get(id) !== owner) return;
+			this.#operationOwners.delete(id);
+			this.#operations.delete(id);
+		};
+	}
+};
+//#endregion
+//#region src/core/features.ts
+function requireName(value, kind) {
+	if (typeof value !== "string" || value.trim() === "") throw new ItdConfigError(`${kind} должен иметь непустое имя`);
+	return value.trim();
+}
+function requireOperationName(value, featureName) {
+	const name = requireName(value, `Операция feature «${featureName}»`);
+	if (name.includes(".")) throw new ItdConfigError(`feature «${featureName}»: локальное имя операции «${name}» не должно содержать точку`);
+	return name;
+}
+function validateBucket(owner, localName, bucket) {
+	if (typeof bucket !== "object" || bucket === null || Array.isArray(bucket)) throw new ItdConfigError(`feature «${owner}»: бакет «${localName}» должен быть объектом`);
+	if (bucket.limit !== void 0 && (!Number.isFinite(bucket.limit) || bucket.limit <= 0)) throw new ItdConfigError(`feature «${owner}»: limit бакета «${localName}» должен быть положительным числом`);
+	if (bucket.concurrency !== void 0 && (!Number.isInteger(bucket.concurrency) || bucket.concurrency < 1)) throw new ItdConfigError(`feature «${owner}»: concurrency бакета «${localName}» должен быть целым числом от 1`);
+}
+/** Реестр feature одного facade. @internal */
+var FeatureRegistry = class {
+	#deps;
+	#features = /* @__PURE__ */ new Map();
+	#serviceOwners = /* @__PURE__ */ new Map();
+	#disposed = false;
+	constructor(deps) {
+		this.#deps = deps;
+	}
+	install(feature) {
+		this.#deps.assertActive("установить feature");
+		if (this.#disposed) throw new ItdStateError("Реестр feature уже освобождён");
+		if (typeof feature !== "object" || feature === null) throw new ItdConfigError("feature должен быть объектом");
+		const name = requireName(feature.name, "Feature");
+		if (this.#features.has(name)) throw new ItdConfigError(`feature «${name}» уже установлен`);
+		if (typeof feature.setup !== "function") throw new ItdConfigError(`feature «${name}» должен предоставлять setup()`);
+		if (typeof feature.operations !== "object" || feature.operations === null || Array.isArray(feature.operations)) throw new ItdConfigError(`feature «${name}» должен объявлять operations`);
+		if (feature.services !== void 0 && !Array.isArray(feature.services)) throw new ItdConfigError(`feature «${name}»: services должен быть массивом`);
+		if (feature.buckets !== void 0 && (typeof feature.buckets !== "object" || feature.buckets === null || Array.isArray(feature.buckets))) throw new ItdConfigError(`feature «${name}»: buckets должен быть объектом`);
+		const rollback = [];
+		const services = /* @__PURE__ */ new Set();
+		const bucketNames = /* @__PURE__ */ new Map();
+		const operations = /* @__PURE__ */ new Map();
+		const controller = new AbortController();
+		let committed = false;
+		try {
+			for (const service of feature.services ?? []) {
+				const serviceName = requireName(service?.name, `Сервис feature «${name}»`);
+				const owner = this.#serviceOwners.get(serviceName);
+				if (owner !== void 0) throw new ItdConfigError(`feature «${name}»: сервис «${serviceName}» уже принадлежит feature «${owner}»`);
+				if (services.has(serviceName)) throw new ItdConfigError(`feature «${name}»: сервис «${serviceName}» объявлен повторно`);
+				if (!this.#deps.services.has(serviceName)) {
+					this.#deps.services.define(service);
+					rollback.push(() => void this.#deps.services.delete(serviceName));
+				} else {
+					const override = this.#deps.serviceOverrides.find((candidate) => candidate.name.trim() === serviceName);
+					if (override) {
+						const previous = this.#deps.services.replace(mergeService(service, override));
+						rollback.push(() => void this.#deps.services.replace(previous));
+					}
+				}
+				this.#serviceOwners.set(serviceName, name);
+				rollback.push(() => {
+					if (this.#serviceOwners.get(serviceName) === name) this.#serviceOwners.delete(serviceName);
+				});
+				services.add(serviceName);
+			}
+			for (const [rawLocalName, bucket] of Object.entries(feature.buckets ?? {})) {
+				const localName = requireName(rawLocalName, `Бакет feature «${name}»`);
+				validateBucket(name, localName, bucket);
+				const globalName = `feature:${name}/${localName}`;
+				const unregisterCatalog = this.#deps.catalog.registerBucket(name, globalName, bucket);
+				rollback.push(unregisterCatalog);
+				const unregisterQueue = this.#deps.registerBucket(globalName, bucket);
+				if (unregisterQueue) rollback.push(unregisterQueue);
+				bucketNames.set(localName, globalName);
+			}
+			for (const [rawLocalName, definition] of Object.entries(feature.operations)) {
+				const localName = requireOperationName(rawLocalName, name);
+				if (typeof definition !== "object" || definition === null) throw new ItdConfigError(`feature «${name}»: операция «${localName}» должна быть объектом`);
+				if (![
+					"GET",
+					"POST",
+					"PUT",
+					"PATCH",
+					"DELETE"
+				].includes(definition.method)) throw new ItdConfigError(`feature «${name}»: операция «${localName}» содержит неизвестный HTTP-метод`);
+				if (!Object.values(RetrySafety).includes(definition.retrySafety)) throw new ItdConfigError(`feature «${name}»: операция «${localName}» содержит неизвестную retrySafety`);
+				if (definition.service !== void 0 && typeof definition.service !== "string") throw new ItdConfigError(`feature «${name}»: service операции «${localName}» должен быть строкой`);
+				if (definition.bucket !== void 0 && typeof definition.bucket !== "string") throw new ItdConfigError(`feature «${name}»: bucket операции «${localName}» должен быть строкой`);
+				if (definition.service !== void 0 && !services.has(definition.service)) throw new ItdConfigError(`feature «${name}»: операция «${localName}» ссылается на необъявленный сервис «${definition.service}»`);
+				const bucket = definition.bucket === void 0 ? this.#deps.catalog.defaultBucket : bucketNames.get(definition.bucket);
+				if (bucket === void 0) throw new ItdConfigError(`feature «${name}»: операция «${localName}» ссылается на необъявленный бакет «${definition.bucket}»`);
+				const operationId = `${name}.${localName}`;
+				const unregister = this.#deps.catalog.registerOperation(name, operationId, {
+					method: definition.method,
+					retrySafety: definition.retrySafety,
+					bucket
+				});
+				rollback.push(unregister);
+				operations.set(localName, {
+					operationId,
+					method: definition.method,
+					service: definition.service
+				});
+			}
+			const context = Object.freeze({
+				featureName: name,
+				baseUrl: this.#deps.baseUrl,
+				signal: controller.signal,
+				clock: this.#deps.clock,
+				logger: this.#deps.logger,
+				request: (operation, options) => {
+					try {
+						this.#deps.assertActive(`выполнить операцию feature «${name}»`);
+						if (!committed || controller.signal.aborted) throw new ItdStateError(`feature «${name}» не активен`);
+						const resolved = operations.get(operation);
+						if (!resolved) throw new ItdConfigError(`feature «${name}» не объявляет операцию «${operation}»`);
+						const scoped = { ...options };
+						delete scoped.operationId;
+						delete scoped.method;
+						delete scoped.service;
+						delete scoped.baseUrl;
+						delete scoped.retrySafety;
+						delete scoped.rateLimitBucket;
+						return this.#deps.http.request({
+							...scoped,
+							operationId: resolved.operationId,
+							method: resolved.method,
+							...resolved.service === void 0 ? {} : { service: resolved.service }
+						});
+					} catch (error) {
+						return Promise.reject(error);
+					}
+				},
+				serviceBaseUrl: (serviceName) => {
+					if (!services.has(serviceName)) throw new ItdConfigError(`feature «${name}» не объявляет сервис «${serviceName}»`);
+					return this.#deps.services.resolveBaseUrl(serviceName);
+				}
+			});
+			const installation = feature.setup(context);
+			if (typeof installation !== "object" || installation === null || !("api" in installation)) throw new ItdConfigError(`setup() feature «${name}» должен вернуть объект с полем api`);
+			if (installation.close !== void 0 && typeof installation.close !== "function") throw new ItdConfigError(`feature «${name}»: close должен быть функцией`);
+			if (installation.dispose !== void 0 && typeof installation.dispose !== "function") throw new ItdConfigError(`feature «${name}»: dispose должен быть функцией`);
+			this.#features.set(name, {
+				name,
+				controller,
+				close: installation.close,
+				dispose: installation.dispose,
+				cleanup: [...rollback]
+			});
+			committed = true;
+			return installation.api;
+		} catch (error) {
+			controller.abort(new ItdAbortError(`Установка feature «${name}» отменена`));
+			for (const undo of rollback.reverse()) undo();
+			throw error;
+		}
+	}
+	names() {
+		return [...this.#features.keys()];
+	}
+	has(name) {
+		return this.#features.has(name);
+	}
+	async close() {
+		const errors = [];
+		for (const feature of [...this.#features.values()].reverse()) try {
+			await feature.close?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length > 0) throw new AggregateError(errors, "Не удалось закрыть feature");
+	}
+	async dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		const errors = [];
+		for (const feature of [...this.#features.values()].reverse()) {
+			feature.controller.abort(new ItdAbortError(`Feature «${feature.name}» освобождён`));
+			try {
+				await feature.dispose?.();
+			} catch (error) {
+				errors.push(error);
+			}
+			for (const cleanup of [...feature.cleanup].reverse()) try {
+				cleanup();
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		this.#features.clear();
+		if (errors.length > 0) throw new AggregateError(errors, "Не удалось освободить feature");
+	}
+};
+//#endregion
 //#region src/resources/pagination.ts
 /** Схема пагинации эндпоинта. */
 const PaginationMode = Object.freeze({
@@ -311,6 +574,84 @@ function withPageState(query, state) {
 	};
 }
 //#endregion
+//#region src/domain/time.ts
+const NAIVE_STAMP = /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
+/**
+* Приводит отметку времени без часового пояса к ISO-8601, считая её временем UTC.
+*
+* Строку другого вида возвращает нетронутой.
+*
+* @example
+* ```ts
+* utcStampToIso('2026-07-23 23:14:25');  // '2026-07-23T23:14:25Z'
+* utcStampToIso('2026-07-23T23:14:25Z'); // без изменений
+* ```
+*/
+function utcStampToIso(value) {
+	const match = typeof value === "string" ? NAIVE_STAMP.exec(value) : null;
+	if (!match) return value;
+	const iso = `${match[1]}T${match[2]}Z`;
+	return Number.isFinite(Date.parse(iso)) ? iso : value;
+}
+/**
+* Разбирает дату API в объект `Date`.
+*
+* @returns `null`, если строки нет или она не разбирается
+*
+* @example
+* ```ts
+* const created = toDate(post.createdAt);
+* ```
+*/
+function toDate(value) {
+	if (!value) return null;
+	const date = new Date(value);
+	return Number.isFinite(date.getTime()) ? date : null;
+}
+//#endregion
+//#region src/resources/status.ts
+/** Приводит `last_checked` каждого сервиса к ISO. Остальное остаётся как прислал сервер. */
+function normalizeStatus(body) {
+	if (!isRecord(body) || !Array.isArray(body.services)) return body;
+	return {
+		...body,
+		services: body.services.map((service) => typeof service?.last_checked === "string" ? {
+			...service,
+			last_checked: utcStampToIso(service.last_checked)
+		} : service)
+	};
+}
+/** API встроенного status feature. @internal */
+var StatusResource = class {
+	#context;
+	constructor(context) {
+		this.#context = context;
+	}
+	async get(options = {}) {
+		return normalizeStatus(await this.#context.request("get", {
+			path: "/api/status",
+			...options
+		}));
+	}
+};
+/** Встроенный модуль страницы состояния платформы. @internal */
+function createStatusFeature() {
+	return {
+		name: "status",
+		services: [{
+			name: STATUS_SERVICE,
+			baseUrl: DEFAULT_STATUS_BASE_URL,
+			auth: false
+		}],
+		operations: { get: {
+			method: "GET",
+			retrySafety: RetrySafety.Safe,
+			service: STATUS_SERVICE
+		} },
+		setup: (context) => ({ api: new StatusResource(context) })
+	};
+}
+//#endregion
 //#region src/builders/base.ts
 /** Метка билдера. Через `Symbol.for` — чтобы распознавание переживало смешивание ESM и CJS. */
 const BUILDER = Symbol.for("itd.builder");
@@ -1240,59 +1581,19 @@ var NotificationsResource = class extends BaseResource {
 	}
 };
 //#endregion
-//#region src/domain/time.ts
-const NAIVE_STAMP = /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
-/**
-* Приводит отметку времени без часового пояса к ISO-8601, считая её временем UTC.
-*
-* Строку другого вида возвращает нетронутой.
-*
-* @example
-* ```ts
-* utcStampToIso('2026-07-23 23:14:25');  // '2026-07-23T23:14:25Z'
-* utcStampToIso('2026-07-23T23:14:25Z'); // без изменений
-* ```
-*/
-function utcStampToIso(value) {
-	const match = typeof value === "string" ? NAIVE_STAMP.exec(value) : null;
-	if (!match) return value;
-	const iso = `${match[1]}T${match[2]}Z`;
-	return Number.isFinite(Date.parse(iso)) ? iso : value;
-}
-/**
-* Разбирает дату API в объект `Date`.
-*
-* @returns `null`, если строки нет или она не разбирается
-*
-* @example
-* ```ts
-* const created = toDate(post.createdAt);
-* ```
-*/
-function toDate(value) {
-	if (!value) return null;
-	const date = new Date(value);
-	return Number.isFinite(date.getTime()) ? date : null;
-}
-//#endregion
 //#region src/resources/platform.ts
-/** Приводит `last_checked` каждого сервиса к ISO. Остальное остаётся как прислал сервер. */
-function normalizeStatus(body) {
-	if (!isRecord(body) || !Array.isArray(body.services)) return body;
-	return {
-		...body,
-		services: body.services.map((service) => typeof service?.last_checked === "string" ? {
-			...service,
-			last_checked: utcStampToIso(service.last_checked)
-		} : service)
-	};
-}
 /**
 * Сведения о платформе: версии приложений, изменения, анонсы, баннер события.
 *
 * Доступна как `itd.platform`.
 */
 var PlatformResource = class extends BaseResource {
+	#status;
+	/** @internal */
+	constructor(http, status) {
+		super(http);
+		this.#status = status;
+	}
 	/**
 	* Загружает минимальные и актуальные версии клиентских приложений.
 	*
@@ -1351,11 +1652,7 @@ var PlatformResource = class extends BaseResource {
 	* ```
 	*/
 	async status(options = {}) {
-		return normalizeStatus(await this.http.operation("platform.status", {
-			service: STATUS_SERVICE,
-			path: "/api/status",
-			...options
-		}));
+		return this.#status.get(options);
 	}
 };
 //#endregion
@@ -3684,7 +3981,7 @@ function createResources(deps) {
 			return subscription;
 		},
 		get platform() {
-			platform ??= new PlatformResource(deps.http);
+			platform ??= new PlatformResource(deps.http, deps.status);
 			return platform;
 		},
 		get telemetry() {
@@ -3987,6 +4284,6 @@ function renderSpans(content, spans = [], options = {}) {
 	return result;
 }
 //#endregion
-export { BaseResource as C, mapPage as E, isBuilder as S, Paginator as T, ALLOWED_MIME_TYPES as _, fromStream as a, VIDEO_MIME_TYPES as b, report as c, autoSpans as d, markup as f, utcStampToIso as g, toDate as h, isMyProfile as i, post as l, parseMarkdown as m, renderSpans as n, fromUrl as o, parseHtml as p, statusDays as r, createResources as s, SpanRenderFormat as t, poll as u, AUDIO_MIME_TYPES as v, PaginationMode as w, comment as x, IMAGE_MIME_TYPES as y };
+export { utcStampToIso as C, mapPage as D, Paginator as E, FeatureRegistry as O, toDate as S, PaginationMode as T, IMAGE_MIME_TYPES as _, fromStream as a, isBuilder as b, report as c, autoSpans as d, markup as f, AUDIO_MIME_TYPES as g, ALLOWED_MIME_TYPES as h, isMyProfile as i, ExtensibleOperationCatalog as k, post as l, parseMarkdown as m, renderSpans as n, fromUrl as o, parseHtml as p, statusDays as r, createResources as s, SpanRenderFormat as t, poll as u, VIDEO_MIME_TYPES as v, BaseResource as w, createStatusFeature as x, comment as y };
 
-//# sourceMappingURL=render-vtLixIiU.js.map
+//# sourceMappingURL=render-C6HRPs10.js.map