itd-api 0.10.0 → 0.10.1

package/dist/index.js

@@ -1,9 +1,9 @@
-import { A as ViewReason, B as BUCKET_LIMITS, C as ItdErrorCode, D as ReportTargetType, E as ReportReason, F as defineBuiltInOperation, G as pickArray, H as createClientRuntime, I as isBuiltInOperationId, L as operationBucket, M as WallAccess, N as ITD_CATALOG, O as ServiceState, P as OPERATIONS, R as operationMethod, S as InteractionType, T as NotificationType, U as createApiError, V as DEFAULT_RATE_LIMIT_BUCKET, X as RetrySafety, Y as pickString, _ as CaptchaType, at as orderPluginDefinitions, b as FeedTab, c as normalizeNotification, ct as STATUS_SERVICE, d as canonicalNotificationType, dt as isRecord, et as createRequestAbortScope, f as isKnownNotificationType, ft as requireOptionalBoolean, g as CaptchaField, gt as installAsyncDisposeFallback, h as CaptchaChoice, ht as systemClock, it as assertPluginRemovable, j as ViewSource, k as SpanType, lt as resolveRateLimit, m as AttachmentType, n as formatNotificationText, o as passthroughOperation, ot as DEFAULT_BASE_URL, p as AccessType, pt as RateLimitPacing, rt as RequestQueuePool, s as voidOperation, t as resolveNotificationUrl, tt as requestAbortError, ut as LIBRARY_VERSION, v as CommentSort, w as LikesVisibility, x as IncidentKind, y as EventChannelStatus, z as operationRetrySafety } from "./shared/url-BA5hEwj2.js";
+import { A as ViewReason, B as BUCKET_LIMITS, C as ItdErrorCode, D as ReportTargetType, E as ReportReason, F as defineBuiltInOperation, G as pickArray, H as createClientRuntime, I as isBuiltInOperationId, L as operationBucket, M as WallAccess, N as ITD_CATALOG, O as ServiceState, P as OPERATIONS, R as operationMethod, S as InteractionType, T as NotificationType, U as createApiError, V as DEFAULT_RATE_LIMIT_BUCKET, X as RetrySafety, Y as pickString, _ as CaptchaType, at as orderPluginDefinitions, b as FeedTab, c as normalizeNotification, ct as STATUS_SERVICE, d as canonicalNotificationType, dt as isRecord, et as createRequestAbortScope, f as isKnownNotificationType, ft as requireOptionalBoolean, g as CaptchaField, gt as installAsyncDisposeFallback, h as CaptchaChoice, ht as systemClock, it as assertPluginRemovable, j as ViewSource, k as SpanType, lt as resolveRateLimit, m as AttachmentType, n as formatNotificationText, o as passthroughOperation, ot as DEFAULT_BASE_URL, p as AccessType, pt as RateLimitPacing, rt as RequestQueuePool, s as voidOperation, t as resolveNotificationUrl, tt as requestAbortError, ut as LIBRARY_VERSION, v as CommentSort, w as LikesVisibility, x as IncidentKind, y as EventChannelStatus, z as operationRetrySafety } from "./shared/url-CntTEAxu.js";
 import { A as isItdStateError, C as isItdError, D as isItdPhoneVerificationError, E as isItdNotFoundError, O as isItdRateLimitError, S as isItdConflictError, T as isItdForbiddenError, _ as ItdStateError, a as ItdConfigError, b as isItdApiError, c as ItdErrorKind, d as ItdForbiddenError, f as ItdNetworkError, g as ItdServerError, h as ItdRateLimitError, i as ItdAuthError, j as isItdValidationError, k as isItdServerError, l as ItdFileError, m as ItdPhoneVerificationError, n as ItdApiError, o as ItdConflictError, p as ItdNotFoundError, r as ItdApiErrorKind, s as ItdError, t as ItdAbortError, u as ItdFileErrorReason, v as ItdTimeoutError, w as isItdFileError, x as isItdAuthError, y as ItdValidationError } from "./shared/errors-GI10kZxk.js";
 import { c as REFRESH_COOKIE, h as joinUrl, l as REFRESH_COOKIE_PATH, s as CookieJar, u as isSerializedCookieEntry, v as RuntimeMode, y as createDeviceId } from "./shared/redact-DJV0XM3n.js";
-import { A as utcStampToIso, C as AUDIO_MIME_TYPES, D as isBuilder, E as comment, F as mapPage, I as createFeatureHost, L as ExtensibleOperationCatalog, M as BaseResource, N as PaginationMode, O as createStatusFeature, P as Paginator, S as ALLOWED_MIME_TYPES, T as VIDEO_MIME_TYPES, _ as poll, a as createShopOrderAccessStorage, b as parseHtml, c as ShopOrderStatus, d as isMyProfile, f as fromStream, g as post, h as report, i as MemoryShopOrderAccessStorage, j as NotificationsResource, k as toDate, l as ShopProductCategory, m as createResources, n as renderSpans, o as statusDays, p as fromUrl, r as createShopFeature, s as ShopConsentKind, t as SpanRenderFormat, u as ShopProductStatus, v as autoSpans, w as IMAGE_MIME_TYPES, x as parseMarkdown, y as markup } from "./shared/render-CkhvH_yh.js";
+import { A as utcStampToIso, C as AUDIO_MIME_TYPES, D as isBuilder, E as comment, F as mapPage, I as createFeatureHost, L as ExtensibleOperationCatalog, M as BaseResource, N as PaginationMode, O as createStatusFeature, P as Paginator, S as ALLOWED_MIME_TYPES, T as VIDEO_MIME_TYPES, _ as poll, a as createShopOrderAccessStorage, b as parseHtml, c as ShopOrderStatus, d as isMyProfile, f as fromStream, g as post, h as report, i as MemoryShopOrderAccessStorage, j as NotificationsResource, k as toDate, l as ShopProductCategory, m as createResources, n as renderSpans, o as statusDays, p as fromUrl, r as createShopFeature, s as ShopConsentKind, t as SpanRenderFormat, u as ShopProductStatus, v as autoSpans, w as IMAGE_MIME_TYPES, x as parseMarkdown, y as markup } from "./shared/render-CubTTof_.js";
 import { c as FileTransferMode } from "./shared/options-i4LrKfqx.js";
-import { _ as Emitter, a as WebSocketTransport, c as NotificationEventsTransport, d as NotificationUpdateOrigin, f as NotificationUpdateType, g as runEventMiddleware, h as UnauthorizedStreamError, i as createNotificationEventsClient, l as resolveNotificationEventsOptions, m as EventChannel, n as EventRouter, o as EVENT_OPERATIONS, p as createParser, r as NotificationEventsClient, s as NotificationEvents, t as EventComposer, u as setNotificationEventsConnectGuard, v as reportListenerError } from "./shared/events-B0Wtn4cF.js";
+import { _ as Emitter, a as WebSocketTransport, c as NotificationEventsTransport, d as NotificationUpdateOrigin, f as NotificationUpdateType, g as runEventMiddleware, h as UnauthorizedStreamError, i as createNotificationEventsClient, l as resolveNotificationEventsOptions, m as EventChannel, n as EventRouter, o as EVENT_OPERATIONS, p as createParser, r as NotificationEventsClient, s as NotificationEvents, t as EventComposer, u as setNotificationEventsConnectGuard, v as reportListenerError } from "./shared/events-Cipe-Fm9.js";
 import { a as isEnumerableKeyValueStore, i as createRecordKeyValueStore, o as withCodec, r as createKeyValueStore, s as withNamespace, t as MemoryKeyValueStore } from "./shared/key-value-store-Bt2PSMxY.js";
 import { n as copySession, r as createTokenStorage, t as MemoryTokenStorage } from "./shared/storage-DiDe0PZM.js";
 import { a as scopedTokenStorage, i as isRestorableSession, n as controlledTokenStorage, r as createMultiTokenStorage, t as MemoryMultiTokenStorage } from "./shared/multi-storage-C3Ngtop1.js";
@@ -91,21 +91,36 @@ function requireCaptchaText(value, field) {
 	if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) throw new ItdConfigError(`${field} должен быть непустой строкой`);
 }
 /**
-* Проверяет форму блока `auth.captcha`.
+* Проверяет форму источника токена и приводит его к объекту.
 *
-* Отсутствие источника токена ошибкой не считается: до входа по паролю дело может и не
-* дойти. О нехватке сообщит {@link resolveCaptchaBody} в момент входа.
+* Сам объект сохраняется как есть: `getToken` вызывается на нём, чтобы источнику остался
+* доступен собственный `this`.
 *
 * @throws {ItdConfigError} при некорректных значениях
 */
-function validateCaptchaOptions(captcha) {
+function resolveCaptchaSolver(captcha) {
+	if (captcha === void 0) return void 0;
+	if (typeof captcha === "function") return { getToken: captcha };
+	if (!isRecord(captcha)) throw new ItdConfigError("captcha должен быть функцией либо объектом с getToken");
+	const { getToken, type, field } = captcha;
+	if (typeof getToken !== "function") throw new ItdConfigError("captcha.getToken должен быть функцией");
+	requireCaptchaText(type, "captcha.type");
+	requireCaptchaText(field, "captcha.field");
+	return captcha;
+}
+/**
+* Проверяет форму готового токена капчи.
+*
+* @param path имя опции или аргумента для текста ошибки
+* @throws {ItdConfigError} если токен или его тип не указаны
+*/
+function validateCaptchaToken(captcha, path) {
 	if (captcha === void 0) return;
-	if (!isRecord(captcha)) throw new ItdConfigError("auth.captcha должен быть объектом");
-	const { type, token, getToken, field } = captcha;
-	requireCaptchaText(type, "auth.captcha.type");
-	requireCaptchaText(token, "auth.captcha.token");
-	requireCaptchaText(field, "auth.captcha.field");
-	if (getToken !== void 0 && typeof getToken !== "function") throw new ItdConfigError("auth.captcha.getToken должен быть функцией");
+	if (!isRecord(captcha)) throw new ItdConfigError(`${path} должен быть объектом { type, token }`);
+	const { type, token, field } = captcha;
+	if (typeof token !== "string" || token.trim() === "") throw new ItdConfigError(`${path}.token должен быть непустой строкой`);
+	if (typeof type !== "string" || type.trim() === "") throw new ItdConfigError(`${path}.type должен быть непустой строкой`);
+	requireCaptchaText(field, `${path}.field`);
 }
 /** Разбирает ответ `GET /api/v1/auth/captcha/provider` для автоматического входа. */
 function readCaptchaProvider(body) {
@@ -122,43 +137,40 @@ function readCaptchaProvider(body) {
 function resolveField(type, configured) {
 	const field = configured ?? CAPTCHA_FIELDS[type];
 	if (field) return field;
-	throw new ItdConfigError(`Неизвестно, в каком поле сервер ждёт токен капчи «${type}». Передайте auth.captcha.field либо оставьте auth.captcha.type = ${CaptchaChoice.Auto}, чтобы поле назвал сервер.`);
+	throw new ItdConfigError(`Неизвестно, в каком поле сервер ждёт токен капчи «${type}». Передайте captcha.field либо оставьте captcha.type = ${CaptchaChoice.Auto}, чтобы поле назвал сервер.`);
 }
-/** Спрашивает свежий токен, затем берёт разовый. */
-async function resolveToken(captcha, type) {
-	const token = await captcha.getToken?.(type) || captcha.token;
-	if (token) return token;
-	throw new ItdConfigError(`Источник капчи не вернул токен для провайдера «${type}». Проверьте auth.captcha.getToken.`);
+/** Спрашивает токен у источника и убеждается, что он непустой. */
+async function requireSolvedToken(solver, type) {
+	const token = await solver.getToken(type);
+	if (typeof token === "string" && token.trim() !== "") return token;
+	throw new ItdConfigError(`Источник капчи не вернул токен для провайдера «${type}». Проверьте captcha.getToken.`);
 }
 /**
-* Готовит фрагмент тела запроса с токеном капчи.
+* Готовит фрагмент тела запроса, взяв токен у источника.
 *
 * При `CaptchaChoice.Auto` провайдер спрашивается у сервера — тогда и тип виджета,
-* и имя поля приходят оттуда. Явно названный тип решается без этого запроса.
+* и имя поля приходят оттуда. Явно названный тип обходится без этого запроса.
 *
 * @param askProvider как спросить активного провайдера; вызывается, только если это нужно
-* @throws {ItdConfigError} если капча не настроена или токен не получен
+* @throws {ItdConfigError} если токен получить не удалось
 */
-async function resolveCaptchaBody(captcha, askProvider) {
-	if (!captcha?.token && !captcha?.getToken) throw new ItdConfigError("Вход по email и паролю требует токен капчи. Передайте auth.captcha.getToken — источник свежего токена — либо разовый auth.captcha.token. В Node токен получает пакет @itd-api/captcha.");
-	const choice = captcha.type ?? CaptchaChoice.Auto;
+async function solveCaptchaBody(solver, askProvider) {
+	const choice = solver.type ?? CaptchaChoice.Auto;
 	if (choice === CaptchaChoice.Auto) {
 		const { provider, field } = await askProvider();
-		return { [field]: await resolveToken(captcha, provider) };
+		return { [field]: await requireSolvedToken(solver, provider) };
 	}
-	return { [resolveField(choice, captcha.field)]: await resolveToken(captcha, choice) };
+	return { [resolveField(choice, solver.field)]: await requireSolvedToken(solver, choice) };
 }
 /**
-* Готовит фрагмент тела для разового вызова с готовым доказательством.
+* Готовит фрагмент тела из готового токена.
 *
-* Поле берётся из самого доказательства либо из умолчания провайдера; запроса к серверу нет.
+* Поле берётся из самого токена либо из умолчания провайдера; запроса к серверу нет.
 *
-* @throws {ItdConfigError} если доказательство неполное
+* @throws {ItdConfigError} если токен или его тип не указаны
 */
 function captchaBody(captcha) {
-	if (!isRecord(captcha)) throw new ItdConfigError("captcha должен быть объектом { type, token }");
-	if (typeof captcha.token !== "string" || captcha.token.trim() === "") throw new ItdConfigError("captcha.token должен быть непустой строкой");
-	if (typeof captcha.type !== "string" || captcha.type.trim() === "") throw new ItdConfigError("captcha.type должен быть непустой строкой");
+	validateCaptchaToken(captcha, "captcha");
 	return { [resolveField(captcha.type, captcha.field)]: captcha.token };
 }
 //#endregion
@@ -236,7 +248,7 @@ function validateAuth(auth) {
 		const { email, password, captcha } = auth;
 		if (typeof email !== "string" || email.trim() === "") throw new ItdConfigError("auth.email должен быть непустой строкой");
 		if (typeof password !== "string" || password === "") throw new ItdConfigError("auth.password должен быть непустой строкой");
-		validateCaptchaOptions(captcha);
+		validateCaptchaToken(captcha, "auth.captcha");
 		return { ...auth };
 	}
 	throw new ItdConfigError("auth не распознан. Ожидается строка с accessToken либо объект { accessToken }, { email, password } или { getToken }");
@@ -265,6 +277,7 @@ function resolveSessionConfig(options, runtime) {
 	return {
 		...runtime,
 		auth: validateAuth(options.auth),
+		captcha: resolveCaptchaSolver(options.captcha),
 		storage: resolveStorage(options.storage),
 		deviceId: options.deviceId,
 		autoRefresh: options.autoRefresh ?? true,
@@ -436,6 +449,8 @@ var AuthManager = class {
 	*/
 	#authEpoch = 0;
 	#externalReadGeneration = 0;
+	/** Разовый токен из `auth.captcha` тратится ровно на один запрос. */
+	#configCaptchaSpent = false;
 	#disposed = false;
 	#persistence = Promise.resolve();
 	constructor(config, http, jar, hooks = {}) {
@@ -963,6 +978,34 @@ var AuthManager = class {
 		this.#signingIn = promise;
 		return promise;
 	}
+	/**
+	* Готовит фрагмент тела с токеном капчи для запроса, который её требует.
+	*
+	* Источники в порядке убывания приоритета: токен, переданный в сам вызов; разовый токен
+	* из `auth.captcha`; опция `captcha`. Когда ни одного нет, фрагмент пустой: нужна ли
+	* капча этому запросу, решает сервер.
+	*
+	* @param explicit готовый токен, переданный в вызов
+	* @throws {ItdConfigError} если токен неполный или источник его не вернул
+	*/
+	async captchaBody(explicit) {
+		if (explicit) return captchaBody(explicit);
+		const configured = this.#takeConfiguredCaptcha();
+		if (configured) return captchaBody(configured);
+		const solver = this.#config.captcha;
+		if (solver) return solveCaptchaBody(solver, () => this.#resolveCaptchaProvider());
+		this.#config.logger?.debug("Запрос уходит без токена капчи: не передан аргумент captcha и не задана опция captcha");
+		return {};
+	}
+	/** Отдаёт разовый токен из `auth.captcha`, помечая его потраченным. */
+	#takeConfiguredCaptcha() {
+		if (this.#configCaptchaSpent) return void 0;
+		const auth = this.#config.auth;
+		const captcha = isRecord(auth) ? auth.captcha : void 0;
+		if (!captcha) return void 0;
+		this.#configCaptchaSpent = true;
+		return captcha;
+	}
 	/** Спрашивает у сервера активного провайдера и поле, в котором он ждёт токен. */
 	async #resolveCaptchaProvider() {
 		return readCaptchaProvider(await this.#http.execute(AUTH_CAPTCHA_PROVIDER, {
@@ -972,7 +1015,7 @@ var AuthManager = class {
 		}));
 	}
 	async #performSignIn(credentials, revision) {
-		const captcha = await resolveCaptchaBody(credentials.captcha, () => this.#resolveCaptchaProvider());
+		const captcha = await this.captchaBody();
 		const flowCookies = new CookieJar();
 		const result = await this.#http.execute(AUTH_SIGN_IN, {
 			path: AUTH_PATHS.signIn,
@@ -1153,7 +1196,8 @@ var AuthResource = class extends BaseResource {
 		if (existing) return existing;
 		const flow = {
 			cookies: this.#auth.createCookieFlow(false),
-			expiresAt: void 0
+			expiresAt: void 0,
+			captchaRequired: false
 		};
 		this.#qrFlows.set(qrId, flow);
 		return flow;
@@ -1204,7 +1248,8 @@ var AuthResource = class extends BaseResource {
 		if (typeof result.qrId === "string" && result.qrId !== "") {
 			const flow = {
 				cookies,
-				expiresAt: void 0
+				expiresAt: void 0,
+				captchaRequired: false
 			};
 			this.#touchQrFlow(flow, result.expiresIn);
 			this.#qrFlows.set(result.qrId, flow);
@@ -1214,20 +1259,21 @@ var AuthResource = class extends BaseResource {
 	/**
 	* Проверяет QR-сессию и завершает вход после подтверждения на другом устройстве.
 	*
-	* До подтверждения возвращает промежуточный статус. Если сервер потребовал капчу,
-	* повторите вызов с `captcha` — тип берётся из {@link captchaProvider}.
-	* Полученный `accessToken` автоматически сохраняется в клиенте.
+	* До подтверждения возвращает промежуточный статус. Токен капчи добывается, только когда
+	* сервер о ней попросил — статусом `captcha_required` на прошлой проверке, — либо когда
+	* передан в сам вызов. Полученный `accessToken` автоматически сохраняется в клиенте.
 	*/
 	async claimQrLogin(input, options = {}) {
 		const revision = this.#auth.revision();
 		const flow = this.#qrFlow(input.qrId);
 		try {
 			const { captcha, ...rest } = input;
+			const needsCaptcha = captcha !== void 0 || flow.captchaRequired;
 			const result = await this.http.execute(AUTH_QR_CLAIM, {
 				path: AUTH_PATHS.qrClaim,
 				body: {
 					...rest,
-					...captcha ? captchaBody(captcha) : {}
+					...needsCaptcha ? await this.#auth.captchaBody(captcha) : {}
 				},
 				skipAuth: true,
 				skipAuthRefresh: true,
@@ -1235,6 +1281,7 @@ var AuthResource = class extends BaseResource {
 				...options
 			});
 			this.#touchQrFlow(flow, result.expiresIn);
+			if (result.status === QrLoginStatus.CaptchaRequired) flow.captchaRequired = true;
 			if (result.status === QrLoginStatus.Authorized) {
 				await this.#auth.commitAuthFlow(result.accessToken, flow.cookies, revision);
 				this.#qrFlows.delete(input.qrId);
@@ -1270,13 +1317,13 @@ var AuthResource = class extends BaseResource {
 	*
 	* @returns `flowToken`, который нужно передать в {@link verifyOtp}
 	*/
-	signUp(credentials, options = {}) {
+	async signUp(credentials, options = {}) {
 		const { captcha, ...rest } = credentials;
 		return this.http.execute(AUTH_SIGN_UP, {
 			path: AUTH_PATHS.signUp,
 			body: {
 				...rest,
-				...captchaBody(captcha)
+				...await this.#auth.captchaBody(captcha)
 			},
 			skipAuth: true,
 			skipAuthRefresh: true,
@@ -1291,18 +1338,19 @@ var AuthResource = class extends BaseResource {
 	*
 	* При успешном входе токен сохраняется в клиенте автоматически.
 	*
-	* @param credentials email, пароль и обязательный токен капчи — см. {@link CaptchaCredentials}
+	* @param credentials email, пароль и токен капчи — см. {@link CredentialsWithCaptcha}
 	*/
 	async signIn(credentials, options = {}) {
 		const { captcha, ...rest } = credentials;
 		const revision = this.#auth.revision();
 		const cookies = this.#auth.createCookieFlow(false);
+		const body = {
+			...rest,
+			...await this.#auth.captchaBody(captcha)
+		};
 		const result = await this.http.execute(AUTH_SIGN_IN, {
 			path: AUTH_PATHS.signIn,
-			body: {
-				...rest,
-				...captchaBody(captcha)
-			},
+			body,
 			skipAuth: true,
 			skipAuthRefresh: true,
 			cookieJar: cookies,
@@ -1430,12 +1478,12 @@ var AuthResource = class extends BaseResource {
 	*
 	* @returns `flowToken`, который нужно передать в {@link resetPassword}
 	*/
-	forgotPassword(input, options = {}) {
+	async forgotPassword(input, options = {}) {
 		return this.http.execute(AUTH_FORGOT_PASSWORD, {
 			path: AUTH_PATHS.forgotPassword,
 			body: {
 				email: input.email,
-				...captchaBody(input.captcha)
+				...await this.#auth.captchaBody(input.captcha)
 			},
 			skipAuth: true,
 			skipAuthRefresh: true,
@@ -1570,8 +1618,9 @@ function createManagedClient(options, internals) {
 * const itd = new ItdClient({
 *   // `auth` не обязателен: когда хранилище уже содержит сессию, токен берётся оттуда,
 *   // а истёкший продлевается сам. Здесь он нужен на первый запуск.
-*   // Вход по паролю требует токена капчи — см. CaptchaOptions.
-*   auth: { email, password, captcha: createCaptchaSolver() },
+*   auth: { email, password },
+*   // Капчу входа решает пакет @itd-api/captcha — см. CaptchaSolver.
+*   captcha: createCaptchaSolver(),
 *   storage: new FileTokenStorage('./.itd-session.json'),
 *   rateLimit: { concurrency: 4, rps: 8 },
 * });
@@ -2085,6 +2134,8 @@ function assertAccountsActive(accounts, action) {
 *
 * await using accounts = new ItdAccounts({
 *   storage: new FileMultiTokenStorage('./.itd-sessions.json'),
+*   // Общие опции достаются каждому аккаунту: один источник токена капчи на всех.
+*   captcha: createCaptchaSolver(),
 *   rateLimit: { concurrency: 4 },
 * });
 *
@@ -2092,9 +2143,7 @@ function assertAccountsActive(accounts, action) {
 * await accounts.restore();
 *
 * if (!accounts.has('kiow')) {
-*   accounts.addAccount('kiow', {
-*     auth: { email, password, captcha: createCaptchaSolver() },
-*   });
+*   accounts.addAccount('kiow', { auth: { email, password } });
 * }
 *
 * await accounts.account('kiow').posts.create({ content: 'привет' });
@@ -2173,9 +2222,7 @@ var ItdAccounts = class ItdAccounts {
 	*
 	* @example
 	* ```ts
-	* accounts.addAccount('bot', {
-	*   auth: { email, password, captcha: createCaptchaSolver() },
-	* });
+	* accounts.addAccount('bot', { auth: { email, password } });
 	* accounts.addAccount('reader', { auth: '<accessToken>' });
 	* accounts.addAccount('через-прокси', { fetch: proxyFetch('socks5://…') });
 	* ```