@torrow/sdk-auth 0.8.0 → 0.9.0

package/dist/index.js

@@ -13,8 +13,69 @@ function appCredentialsToAuthIdentityBasic(appCredentials) {
   return { username: clientId, password: clientSecret };
 }
 
+// ../../src/auth-session/otp-errors.ts
+import {
+  OtpErrorReason,
+  TorrowSdkError,
+  TorrowSdkErrorCategory,
+  TorrowSdkErrorDomain,
+  TorrowSdkRequestState
+} from "@torrow/sdk-client";
+function otpFailure(kind, cleanup, cause) {
+  let category;
+  let reason;
+  switch (kind) {
+    case OtpErrorReason.InvalidChallenge:
+      category = TorrowSdkErrorCategory.InvalidInput;
+      reason = kind;
+      break;
+    case OtpErrorReason.UnsupportedMethod:
+      category = TorrowSdkErrorCategory.UnsupportedOperation;
+      reason = kind;
+      break;
+    case OtpErrorReason.AuthHeaderMissing:
+      category = TorrowSdkErrorCategory.AuthenticationRequired;
+      reason = kind;
+      break;
+    case OtpErrorReason.CodeRequestLimitExceeded:
+      category = TorrowSdkErrorCategory.RateLimited;
+      reason = kind;
+      break;
+    default:
+      category = kind;
+  }
+  return new TorrowSdkError({ category, detail: { domain: TorrowSdkErrorDomain.Otp, ...reason ? { reason } : {} }, sensitive: { cleanup, cause } });
+}
+function otpHttpFailure(error) {
+  if (!(error instanceof TorrowSdkError)) return error;
+  const body = error.getSensitiveDetails().body;
+  if (body === null || typeof body !== "object") return error;
+  const value = body;
+  if (value.name === "AUTH_HEADER_MISSING" /* AuthHeaderMissing */) {
+    return error.withContext({ category: TorrowSdkErrorCategory.AuthenticationRequired, detail: { domain: TorrowSdkErrorDomain.Otp, reason: OtpErrorReason.AuthHeaderMissing } });
+  }
+  if (value.name !== "CODE_REQUEST_LIMIT_EXCEEDED" /* CodeRequestLimitExceeded */) return error;
+  const minutes = duration(value.parameters?.minutes);
+  const seconds = duration(value.parameters?.seconds);
+  const wait = minutes === void 0 && seconds === void 0 ? void 0 : (minutes ?? 0) * 60 + (seconds ?? 0);
+  return error.withContext({ category: TorrowSdkErrorCategory.RateLimited, detail: {
+    domain: TorrowSdkErrorDomain.Otp,
+    reason: OtpErrorReason.CodeRequestLimitExceeded,
+    ...wait !== void 0 && Number.isFinite(wait) ? { retryAfterSeconds: wait } : {}
+  } });
+}
+function duration(value) {
+  const number = typeof value === "number" ? value : typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : void 0;
+  return number !== void 0 && Number.isFinite(number) && number >= 0 ? number : void 0;
+}
+function throwIfOtpAborted(signal) {
+  if (signal?.aborted) throw new TorrowSdkError({ category: TorrowSdkErrorCategory.Cancelled, request: TorrowSdkRequestState.NotStarted, sensitive: { cause: signal.reason } });
+}
+
 // ../../src/auth-session/otp-flow.ts
 import {
+  OtpErrorReason as OtpErrorReason2,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory2,
   isAuthCaptchaType,
   isDeviceType,
   isSendCodeAccountType,
@@ -98,40 +159,24 @@ var OtpPhaseValues = /* @__PURE__ */ ((OtpPhaseValues2) => {
   OtpPhaseValues2["Pending"] = "Pending";
   return OtpPhaseValues2;
 })(OtpPhaseValues || {});
-var OtpFlowErrorCodeValues = /* @__PURE__ */ ((OtpFlowErrorCodeValues2) => {
-  OtpFlowErrorCodeValues2["InvalidArguments"] = "InvalidArguments";
-  OtpFlowErrorCodeValues2["InvalidChallenge"] = "InvalidChallenge";
-  OtpFlowErrorCodeValues2["InvalidResponse"] = "InvalidResponse";
-  OtpFlowErrorCodeValues2["UnsupportedMethod"] = "UnsupportedMethod";
-  return OtpFlowErrorCodeValues2;
-})(OtpFlowErrorCodeValues || {});
-var OtpFlowError = class extends Error {
-  constructor(code, cleanup) {
-    super(`OTP flow: ${code}`);
-    this.code = code;
-    this.#cleanup = cleanup ? Object.freeze({ ...cleanup }) : void 0;
-  }
-  code;
-  name = "OtpFlowError";
-  #cleanup;
-  /** Секрет доступен явно; не является перечисляемым полем исключения. */
-  get cleanup() {
-    return this.#cleanup;
-  }
-};
 function createOtpFlow(options) {
   if (!isRecord(options) || !isRecord(options.deviceInfo) || typeof options.deviceInfo.deviceId !== "string" || !options.deviceInfo.deviceId.trim() || typeof options.deviceInfo.deviceType !== "string" || !isDeviceType(options.deviceInfo.deviceType) || options.scopes !== void 0 && (!Array.isArray(options.scopes) || !options.scopes.every(
     (scope) => typeof scope === "string" && scope.trim()
   )) || options.splitTokens !== void 0 && typeof options.splitTokens !== "boolean")
-    throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
-  const client = createIdentityClient(options);
+    throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
+  let client;
+  try {
+    client = createIdentityClient(options);
+  } catch (cause) {
+    throw otpFailure(TorrowSdkErrorCategory2.InvalidInput, void 0, cause);
+  }
   const deviceInfo = { ...options.deviceInfo };
   const scopes = options.scopes ? [...options.scopes] : void 0;
   const splitTokens = options.splitTokens;
   return {
     async start(input, requestOptions) {
       validateStartInput(input);
-      requestOptions?.signal?.throwIfAborted();
+      throwIfOtpAborted(requestOptions?.signal);
       const startedAt = Date.now();
       const response = await sendOtpCode(
         client,
@@ -141,16 +186,18 @@ function createOtpFlow(options) {
           type: input.account.accountType
         },
         requestOptions?.signal
-      );
+      ).catch((error) => {
+        throw otpHttpFailure(error);
+      });
       if (!isRecord(response) || typeof response.sessionId !== "string" || !response.sessionId.trim())
-        throw new OtpFlowError("InvalidResponse" /* InvalidResponse */);
+        throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse);
       if (!supportedMethod(response.usedMethod, input.account.accountType))
-        throw new OtpFlowError("UnsupportedMethod" /* UnsupportedMethod */);
+        throw otpFailure(OtpErrorReason2.UnsupportedMethod);
       const ttl = response.sessionLifeTimeInSeconds ?? 180;
-      if (!positive(ttl)) throw new OtpFlowError("InvalidResponse" /* InvalidResponse */);
+      if (!positive(ttl)) throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse);
       const expiresAtMs = startedAt + ttl * 1e3;
       if (!timestamp(expiresAtMs) || expiresAtMs <= Date.now())
-        throw new OtpFlowError("InvalidResponse" /* InvalidResponse */);
+        throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse);
       const mobile = response.usedMethod === VerificationMethodValues.MtsMobileId;
       const nextSendAtMs = response.nextAvailableUsageTime instanceof Date ? response.nextAvailableUsageTime.getTime() : typeof response.nextAvailableUsageTime === "string" ? Date.parse(response.nextAvailableUsageTime) : void 0;
       return {
@@ -169,11 +216,11 @@ function createOtpFlow(options) {
       };
     },
     async complete(input, requestOptions) {
-      if (!isRecord(input)) throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
-      requestOptions?.signal?.throwIfAborted();
+      if (!isRecord(input)) throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
+      throwIfOtpAborted(requestOptions?.signal);
       const continuation = validateChallenge(input.challenge);
       if (continuation.phase === "Pending" /* Pending */ && input.code !== void 0 || continuation.phase === "AwaitingCode" /* AwaitingCode */ && (typeof input.code !== "string" || !input.code.trim()))
-        throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
+        throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
       const raw = await requestAuthToken(
         client,
         {
@@ -184,8 +231,10 @@ function createOtpFlow(options) {
           splitTokens
         },
         requestOptions?.signal
-      );
-      if (!isRecord(raw)) throw new OtpFlowError("InvalidResponse" /* InvalidResponse */);
+      ).catch((error) => {
+        throw otpHttpFailure(error);
+      });
+      if (!isRecord(raw)) throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse);
       const fields = tokenResponseFields(raw);
       const refreshToken = typeof fields.refresh === "string" && fields.refresh.trim() ? fields.refresh.trim() : void 0;
       const cleanup = refreshToken ? { refreshToken } : void 0;
@@ -193,7 +242,7 @@ function createOtpFlow(options) {
         typeof fields.status === "string" ? fields.status.trim() : fields.status
       );
       if (!status || fields.access != null && typeof fields.access !== "string" || fields.refresh != null && typeof fields.refresh !== "string" || fields.expiration != null && (typeof fields.expiration !== "number" || !Number.isFinite(fields.expiration) || fields.expiration < 0))
-        throw new OtpFlowError("InvalidResponse" /* InvalidResponse */, cleanup);
+        throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse, cleanup);
       if (status === TokenStatusValues2.Pending)
         return {
           status,
@@ -220,7 +269,7 @@ function createOtpFlow(options) {
       }
       if (status === TokenStatusValues2.Failed) return { status, cleanup };
       if (typeof fields.access !== "string" || !fields.access.trim())
-        throw new OtpFlowError("InvalidResponse" /* InvalidResponse */, cleanup);
+        throw otpFailure(TorrowSdkErrorCategory2.InvalidResponse, cleanup);
       return {
         status,
         tokens: {
@@ -258,19 +307,19 @@ function supportedMethod(value, accountType) {
 }
 function validateStartInput(input) {
   if (!isRecord(input) || !isRecord(input.account) || typeof input.account.accountType !== "string" || !isSendCodeAccountType(input.account.accountType) || typeof input.account.accountName !== "string" || !input.account.accountName.trim())
-    throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
+    throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
   for (const field of ["language", "captcha", "inviteSessionId"]) {
     if (input[field] !== void 0 && typeof input[field] !== "string")
-      throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
+      throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
   }
   if (input.regionStorageId !== void 0 && !attempts(input.regionStorageId) || input.captchaType !== void 0 && (typeof input.captchaType !== "string" || !isAuthCaptchaType(input.captchaType)) || input.preferredMethod !== void 0 && (typeof input.preferredMethod !== "string" || !isVerificationMethod(input.preferredMethod)) || input.supportedMethods !== void 0 && !methods(input.supportedMethods))
-    throw new OtpFlowError("InvalidArguments" /* InvalidArguments */);
+    throw otpFailure(TorrowSdkErrorCategory2.InvalidInput);
 }
 function validateChallenge(value) {
   if (!isRecord(value) || typeof value.sessionId !== "string" || !value.sessionId.trim() || typeof value.accountType !== "string" || !isSendCodeAccountType(value.accountType) || !supportedMethod(value.usedMethod, value.accountType) || value.phase !== "Pending" /* Pending */ && value.phase !== "AwaitingCode" /* AwaitingCode */ || !timestamp(value.expiresAtMs) || value.expiresAtMs <= Date.now() || value.phase === "Pending" /* Pending */ !== (value.usedMethod === VerificationMethodValues.MtsMobileId))
-    throw new OtpFlowError("InvalidChallenge" /* InvalidChallenge */);
+    throw otpFailure(OtpErrorReason2.InvalidChallenge);
   if (value.codeLength !== void 0 && !codeLength(value.codeLength) || value.pollIntervalSeconds !== void 0 && !positive(value.pollIntervalSeconds) || value.attemptsRemaining !== void 0 && !attempts(value.attemptsRemaining) || value.nextSendAtMs !== void 0 && !timestamp(value.nextSendAtMs) || value.availableMethods !== void 0 && !methods(value.availableMethods))
-    throw new OtpFlowError("InvalidChallenge" /* InvalidChallenge */);
+    throw otpFailure(OtpErrorReason2.InvalidChallenge);
   return {
     sessionId: value.sessionId.trim(),
     accountType: value.accountType,
@@ -354,36 +403,92 @@ var LocalStorageTokenStorage = class {
   }
 };
 
-// ../../src/auth-session/auth-session-not-ready.ts
-import { TorrowHttpError } from "@torrow/sdk-client";
-var AuthSessionNotReadyError = class extends Error {
-  name = "AuthSessionNotReadyError";
-  cause;
-  constructor(message = "Auth session is not ready yet", cause) {
-    super(message);
-    this.cause = cause;
-  }
-};
-function isAuthSessionNotReadyYet(e) {
-  if (e instanceof AuthSessionNotReadyError) return true;
-  if (!(e instanceof TorrowHttpError)) return false;
-  const text = [
-    e.message,
-    e.apiErrorName,
-    typeof e.body === "string" ? e.body : JSON.stringify(e.body ?? "")
-  ].join(" ").toLowerCase();
-  return text.includes("session is not ready") || text.includes("unauthorized_client");
-}
-
 // ../../src/auth-session/TokenSession.ts
 import {
   DefaultAuthScopes as DefaultAuthScopes2,
   TorrowClient as TorrowClient2,
-  TorrowHttpError as TorrowHttpError2,
+  TorrowSdkError as TorrowSdkError4,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory4,
+  TorrowSdkEffectArea,
+  TorrowSdkEffectState,
+  TorrowSdkRequestState as TorrowSdkRequestState2,
+  AuthSessionEffectStep,
+  AuthSessionErrorReason as AuthSessionErrorReason2,
   DeviceTypeValues,
   TokenStatusValues as TokenStatusValues3
 } from "@torrow/sdk-client";
 
+// ../../src/auth-session/auth-session-not-ready.ts
+import { AuthSessionErrorReason, TorrowSdkError as TorrowSdkError2, TorrowSdkErrorDomain as TorrowSdkErrorDomain2 } from "@torrow/sdk-client";
+function isAuthSessionNotReadyYet(error) {
+  if (!(error instanceof TorrowSdkError2)) return false;
+  if (error.detail?.domain === TorrowSdkErrorDomain2.AuthSession && error.detail.reason === AuthSessionErrorReason.SessionNotReady) return true;
+  if (!error.http) return false;
+  const body = error.getSensitiveDetails().body;
+  const text = [error.http.apiErrorName, typeof body === "string" ? body : JSON.stringify(body ?? "")].join(" ").toLowerCase();
+  return text.includes("session is not ready") || text.includes("unauthorized_client");
+}
+
+// ../../src/auth-session/session-error.ts
+import {
+  TorrowSdkError as TorrowSdkError3,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory3,
+  TorrowSdkErrorDomain as TorrowSdkErrorDomain3
+} from "@torrow/sdk-client";
+var SessionFailureStage = /* @__PURE__ */ ((SessionFailureStage2) => {
+  SessionFailureStage2["SendCode"] = "SendCode";
+  SessionFailureStage2["CreateAuthSession"] = "CreateAuthSession";
+  SessionFailureStage2["OnSendCode"] = "OnSendCode";
+  SessionFailureStage2["GetCode"] = "GetCode";
+  SessionFailureStage2["OnLink"] = "OnLink";
+  SessionFailureStage2["PollTokens"] = "PollTokens";
+  SessionFailureStage2["ValidateResponse"] = "ValidateResponse";
+  SessionFailureStage2["ValidateInput"] = "ValidateInput";
+  SessionFailureStage2["ValidateState"] = "ValidateState";
+  SessionFailureStage2["LoadStorage"] = "LoadStorage";
+  SessionFailureStage2["InitializeDevice"] = "InitializeDevice";
+  SessionFailureStage2["BuildClient"] = "BuildClient";
+  SessionFailureStage2["IssueTokens"] = "IssueTokens";
+  SessionFailureStage2["ValidateTokens"] = "ValidateTokens";
+  SessionFailureStage2["ApplyTokens"] = "ApplyTokens";
+  SessionFailureStage2["RefreshTokens"] = "RefreshTokens";
+  SessionFailureStage2["RefreshFailureCallback"] = "RefreshFailureCallback";
+  SessionFailureStage2["ClearTokens"] = "ClearTokens";
+  SessionFailureStage2["SaveTokens"] = "SaveTokens";
+  SessionFailureStage2["ClearStorage"] = "ClearStorage";
+  SessionFailureStage2["OpenSession"] = "OpenSession";
+  SessionFailureStage2["SeedStorage"] = "SeedStorage";
+  SessionFailureStage2["Connect"] = "Connect";
+  return SessionFailureStage2;
+})(SessionFailureStage || {});
+function sessionFailure(error, context) {
+  const detail = { domain: TorrowSdkErrorDomain3.AuthSession, ...context.reason ? { reason: context.reason } : {} };
+  if (context.category !== void 0) {
+    return new TorrowSdkError3({
+      ...context,
+      category: context.category,
+      detail,
+      sensitive: { cause: error }
+    });
+  }
+  if (error instanceof TorrowSdkError3) {
+    return error.withContext({
+      operation: context.operation,
+      failureAt: error.operation?.startsWith("TokenSession") ? error.failureAt ?? context.failureAt : context.failureAt,
+      effects: context.effects,
+      ...context.reason ? { detail } : {}
+    });
+  }
+  return new TorrowSdkError3({
+    category: TorrowSdkErrorCategory3.Unknown,
+    operation: context.operation,
+    failureAt: context.failureAt,
+    effects: context.effects,
+    detail,
+    sensitive: { cause: error }
+  });
+}
+
 // ../../src/auth-session/fetch-with-401-retry.ts
 function requestUrl(input) {
   if (typeof input === "string") return input;
@@ -500,8 +605,8 @@ function assertTokenRespReadyForStorage(tokens, context) {
 var DEFAULT_SKEW_MS = 3e4;
 var SESSION_CLOSED_MESSAGE = "TokenSession: session closed (logout)";
 function defaultOnRefreshFailure(err) {
-  if (!(err instanceof TorrowHttpError2)) return "keep";
-  const s = err.status;
+  if (!(err instanceof TorrowSdkError4) || !err.http) return "keep";
+  const s = err.http?.status;
   if (s === 429 || s === 502 || s === 503 || s === 504) return "keep";
   return "clear";
 }
@@ -517,22 +622,48 @@ var TokenSession = class _TokenSession {
   closed = false;
   /** Set in refreshWithFailurePolicy catch; not cleared on success (see public refresh). */
   lastRefreshError;
+  /** Открыть сессию; storage/refresh ошибки описывают только выполненную инициализацию. */
   static async open(opts) {
+    return (await _TokenSession.openWithEffects(opts)).session;
+  }
+  /**
+   * @internal Инициализация с явными сведениями только текущего вызова для составного login.
+   * Не наблюдает fetch/storage и не хранит историю независимых операций.
+   */
+  static async openWithEffects(opts) {
     const session = new _TokenSession(opts);
-    session.tokenSnapshot = await opts.tokenStorage.load();
-    if (!session.tokenSnapshot.deviceId?.trim()) {
-      const di = session.resolveDeviceInfo();
-      const id = di.deviceId?.trim();
-      if (id) {
-        session.tokenSnapshot = { ...session.tokenSnapshot, deviceId: id };
-        await session.persist(false);
+    const effects = [];
+    let failureAt = "LoadStorage" /* LoadStorage */;
+    try {
+      try {
+        session.tokenSnapshot = await opts.tokenStorage.load();
+      } catch (error) {
+        throw sessionFailure(error, {
+          operation: "TokenSession.open",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory4.StorageFailure
+        });
       }
+      effects.push({ area: TorrowSdkEffectArea.SessionMemory, step: AuthSessionEffectStep.SetTokens, state: TorrowSdkEffectState.Applied });
+      failureAt = "InitializeDevice" /* InitializeDevice */;
+      if (!session.tokenSnapshot.deviceId?.trim()) {
+        const id = session.resolveDeviceInfo().deviceId?.trim();
+        if (id) {
+          session.tokenSnapshot = { ...session.tokenSnapshot, deviceId: id };
+          await session.persist(false, effects);
+        }
+      }
+      failureAt = "BuildClient" /* BuildClient */;
+      session._client = session.buildClient();
+      if (!opts.skipEnsureFreshOnOpen) {
+        failureAt = "RefreshTokens" /* RefreshTokens */;
+        await session.runExclusive(() => session.ensureFreshImpl(effects));
+      }
+      return { session, effects: Object.freeze(effects.map((effect) => Object.freeze({ ...effect }))) };
+    } catch (error) {
+      throw sessionFailure(error, { operation: "TokenSession.open", failureAt, effects });
     }
-    session._client = session.buildClient();
-    if (!opts.skipEnsureFreshOnOpen) {
-      await session.ensureFresh();
-    }
-    return session;
   }
   /** Persist, переданный в `TokenSession.open` / `TorrowAuth.*`. */
   get tokenStorage() {
@@ -567,9 +698,18 @@ var TokenSession = class _TokenSession {
   getDeviceInfo() {
     return this.resolveDeviceInfo();
   }
+  /** Получить access после проактивного refresh; closed возвращает undefined без записи. */
   async getAccessToken() {
     if (this.closed) return void 0;
-    await this.ensureFresh();
+    try {
+      await this.ensureFresh();
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TokenSession.getAccessToken",
+        failureAt: "RefreshTokens" /* RefreshTokens */,
+        effects: error instanceof TorrowSdkError4 ? error.effects ?? [] : []
+      });
+    }
     return this.tokenSnapshot.accessToken?.trim() || void 0;
   }
   /**
@@ -578,26 +718,53 @@ var TokenSession = class _TokenSession {
    * (refresh-shaped); логин — `{ replace: true }`. После `logout` — новая сессия.
    */
   async applyTokenResp(tokens, opts) {
-    await this.runExclusive(() => this.applyTokenRespUnlocked(tokens, opts));
+    const effects = [];
+    await this.runExclusive(async () => {
+      try {
+        await this.applyTokenRespUnlocked(tokens, opts, effects);
+      } catch (error) {
+        throw sessionFailure(error, { operation: "TokenSession.applyTokenResp", failureAt: "ApplyTokens" /* ApplyTokens */, effects });
+      }
+    });
   }
+  /** Очистить память и сохранить snapshot; storage-сбой не отменяет очистку памяти. */
   async clearTokens() {
-    await this.runExclusive(() => this.clearTokensUnlocked());
+    const effects = [];
+    await this.runExclusive(async () => {
+      try {
+        await this.clearTokensUnlocked(effects);
+      } catch (error) {
+        throw sessionFailure(error, { operation: "TokenSession.clearTokens", failureAt: "ClearTokens" /* ClearTokens */, effects });
+      }
+    });
   }
   /**
    * Revoke refresh (если есть) + очистка storage.
    * Единственное публичное имя выхода из сессии.
    */
   async logout() {
+    const effects = [];
     await this.runExclusive(async () => {
       this.closed = true;
+      effects.push({ area: TorrowSdkEffectArea.SessionMemory, step: AuthSessionEffectStep.CloseSession, state: TorrowSdkEffectState.Applied });
       const refresh = this.tokenSnapshot.refreshToken?.trim();
       if (refresh) {
+        let state = TorrowSdkEffectState.Applied;
+        let prepared = false;
         try {
-          await this.identityClient().auth.revoke({ token: refresh });
-        } catch {
+          const identity = this.identityClient();
+          prepared = true;
+          await identity.auth.revoke({ token: refresh });
+        } catch (error) {
+          state = !prepared || error instanceof TorrowSdkError4 && error.request === TorrowSdkRequestState2.NotStarted ? TorrowSdkEffectState.NotApplied : TorrowSdkEffectState.Unknown;
         }
+        effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.RevokeTokens, state });
+      }
+      try {
+        await this.clearTokensUnlocked(effects);
+      } catch (error) {
+        throw sessionFailure(error, { operation: "TokenSession.logout", failureAt: "ClearTokens" /* ClearTokens */, effects });
       }
-      await this.clearTokensUnlocked();
     });
   }
   /**
@@ -606,43 +773,79 @@ var TokenSession = class _TokenSession {
    *
    * Один вызов `POST /api/v1/auth/token` (`requestToken`) с `{ sessionId, code }`.
    * При успехе (`TokenReady`) — persist; если сессия ещё не готова —
-   * {@link AuthSessionNotReadyError} (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
+   * `TorrowSdkError` с причиной `SessionNotReady` (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
    *
    * HTTP вне mutex; persist сериализован через {@link applyTokenResp} (не оборачивать
    * весь метод в `runExclusive` — вложенный mutex с публичным `applyTokenResp`).
    */
   async requestTokenWithCode(args) {
-    this.assertNotClosedForWrite();
-    const sessionId = args.sessionId.trim();
-    const code = args.code.trim();
-    if (!sessionId || !code) {
-      throw new Error("TokenSession.requestTokenWithCode: sessionId and code are required");
-    }
-    const scopes = args.scopes && args.scopes.length > 0 ? args.scopes : [...DefaultAuthScopes2];
-    const deviceInfo = this.resolveDeviceInfo();
-    let resp;
+    const effects = [];
+    let failureAt = "ValidateInput" /* ValidateInput */;
     try {
-      resp = normalizeTokenResp(
-        await requestAuthToken(
-          this.identityClient(),
-          { sessionId, code, scopes, deviceInfo },
-          args.signal
-        )
-      );
-    } catch (e) {
-      if (isAuthSessionNotReadyYet(e)) {
-        throw new AuthSessionNotReadyError("Auth session is not ready yet", e);
+      this.assertNotClosedForWrite();
+      const sessionId = args.sessionId.trim();
+      const code = args.code.trim();
+      if (!sessionId || !code) {
+        throw sessionFailure(void 0, {
+          operation: "TokenSession.requestTokenWithCode",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory4.InvalidInput
+        });
       }
-      throw e;
-    }
-    if (tokenTransition(resp.status, true) !== TokenStatusValues3.TokenReady) {
-      throw new AuthSessionNotReadyError(
-        `TokenResp.status=${resp.status} (\u043E\u0436\u0438\u0434\u0430\u043B\u0441\u044F TokenReady)`
-      );
+      const scopes = args.scopes && args.scopes.length > 0 ? args.scopes : [...DefaultAuthScopes2];
+      const deviceInfo = this.resolveDeviceInfo();
+      failureAt = "IssueTokens" /* IssueTokens */;
+      const identity = this.identityClient();
+      let resp;
+      try {
+        resp = normalizeTokenResp(await requestAuthToken(identity, { sessionId, code, scopes, deviceInfo }, args.signal));
+      } catch (error) {
+        effects.push({
+          area: TorrowSdkEffectArea.Remote,
+          step: AuthSessionEffectStep.IssueTokens,
+          state: error instanceof TorrowSdkError4 && error.request === TorrowSdkRequestState2.NotStarted ? TorrowSdkEffectState.NotApplied : TorrowSdkEffectState.Unknown
+        });
+        if (isAuthSessionNotReadyYet(error)) {
+          throw sessionFailure(error, {
+            operation: "TokenSession.requestTokenWithCode",
+            failureAt,
+            effects,
+            reason: AuthSessionErrorReason2.SessionNotReady
+          });
+        }
+        throw error;
+      }
+      failureAt = "ValidateTokens" /* ValidateTokens */;
+      if (tokenTransition(resp.status, true) !== TokenStatusValues3.TokenReady) {
+        effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.IssueTokens, state: TorrowSdkEffectState.Unknown });
+        throw sessionFailure(void 0, {
+          operation: "TokenSession.requestTokenWithCode",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory4.InvalidState,
+          reason: AuthSessionErrorReason2.SessionNotReady
+        });
+      }
+      let ready;
+      try {
+        ready = assertTokenRespReadyForStorage(resp, "TokenSession.requestTokenWithCode");
+      } catch (error) {
+        effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.IssueTokens, state: TorrowSdkEffectState.Unknown });
+        throw sessionFailure(error, {
+          operation: "TokenSession.requestTokenWithCode",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory4.InvalidResponse
+        });
+      }
+      effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.IssueTokens, state: TorrowSdkEffectState.Applied });
+      failureAt = "ApplyTokens" /* ApplyTokens */;
+      await this.runExclusive(() => this.applyTokenRespUnlocked(ready, { replace: true }, effects));
+      return ready;
+    } catch (error) {
+      throw sessionFailure(error, { operation: "TokenSession.requestTokenWithCode", failureAt, effects });
     }
-    const ready = assertTokenRespReadyForStorage(resp, "TokenSession.requestTokenWithCode");
-    await this.applyTokenResp(ready, { replace: true });
-    return ready;
   }
   /**
    * Явный refresh (single-flight через общий mutex сессии).
@@ -651,86 +854,145 @@ var TokenSession = class _TokenSession {
    * не используй return value; смотри `session.status` / `getTokenSnapshot()`.
    */
   async refresh() {
+    const effects = [];
     return this.runExclusive(async () => {
-      this.assertNotClosedForWrite();
-      if (!this.tokenSnapshot.refreshToken?.trim()) {
-        throw new Error("TokenSession.refresh: \u043D\u0435\u0442 refreshToken \u0432 storage");
-      }
-      const result = await this.refreshWithFailurePolicy();
-      if (result.outcome === "refreshed") {
-        return result.resp;
-      }
-      if (this.lastRefreshError !== void 0) {
-        throw this.lastRefreshError;
+      try {
+        this.assertNotClosedForWrite();
+        if (!this.tokenSnapshot.refreshToken?.trim()) {
+          throw sessionFailure(void 0, {
+            operation: "TokenSession.refresh",
+            failureAt: "ValidateState" /* ValidateState */,
+            effects,
+            category: TorrowSdkErrorCategory4.InvalidState
+          });
+        }
+        const result = await this.refreshWithFailurePolicy(effects);
+        if (result.outcome === "refreshed") return result.resp;
+        throw result.error ?? this.lastRefreshError;
+      } catch (error) {
+        throw sessionFailure(error, { operation: "TokenSession.refresh", failureAt: "RefreshTokens" /* RefreshTokens */, effects });
       }
-      throw new Error("TokenSession.refresh: refresh failed");
     });
   }
+  /** Обновить просроченный access; политика keep/clear сохраняет прежнее resolve-поведение. */
   async ensureFresh() {
-    await this.runExclusive(() => this.ensureFreshImpl());
+    const effects = [];
+    await this.runExclusive(async () => {
+      try {
+        await this.ensureFreshImpl(effects);
+      } catch (error) {
+        throw sessionFailure(error, { operation: "TokenSession.ensureFresh", failureAt: "RefreshTokens" /* RefreshTokens */, effects });
+      }
+    });
   }
   assertNotClosedForWrite() {
     if (this.closed) {
-      throw new Error(SESSION_CLOSED_MESSAGE);
+      throw sessionFailure(new Error(SESSION_CLOSED_MESSAGE), {
+        operation: "TokenSession",
+        failureAt: "ValidateState" /* ValidateState */,
+        effects: [],
+        category: TorrowSdkErrorCategory4.InvalidState
+      });
     }
   }
   /** Caller must hold `runExclusive`. Do not call public `applyTokenResp` from here. */
-  async applyTokenRespUnlocked(tokens, opts) {
+  async applyTokenRespUnlocked(tokens, opts, effects = []) {
     this.assertNotClosedForWrite();
     const normalized = normalizeTokenResp(tokens);
-    assertTokenRespReadyForStorage(normalized, "TokenSession.applyTokenResp");
+    try {
+      assertTokenRespReadyForStorage(normalized, "TokenSession.applyTokenResp");
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TokenSession",
+        failureAt: "ValidateTokens" /* ValidateTokens */,
+        effects,
+        category: TorrowSdkErrorCategory4.InvalidResponse
+      });
+    }
     this.tokenSnapshot = mergeAuthTokens(this.tokenSnapshot, normalized, {
       ...opts,
       // Host TTL survives refresh without expiration only while still fresh (incl. skew); else cleared → opaque until 401.
       keepPrevTtlIfExpiresAfterMs: Date.now() + (this.opts.accessTokenSkewMs ?? DEFAULT_SKEW_MS)
     });
-    await this.persist(true);
+    effects.push({ area: TorrowSdkEffectArea.SessionMemory, step: AuthSessionEffectStep.SetTokens, state: TorrowSdkEffectState.Applied });
+    await this.persist(true, effects);
   }
-  async clearTokensUnlocked() {
+  async clearTokensUnlocked(effects = []) {
     this.tokenSnapshot = {
       ...this.tokenSnapshot,
       accessToken: void 0,
       refreshToken: void 0,
       accessExpiresAtMs: void 0
     };
-    await this.persist(true);
+    effects.push({ area: TorrowSdkEffectArea.SessionMemory, step: AuthSessionEffectStep.ClearTokens, state: TorrowSdkEffectState.Applied });
+    await this.persist(true, effects, true);
   }
   /** Caller must hold `runExclusive`. `refreshWithFailurePolicy` skips when no refreshToken; guard here is intentional defense-in-depth. */
-  async refreshUnlocked() {
+  async refreshUnlocked(effects) {
     const refresh = this.tokenSnapshot.refreshToken?.trim();
     if (!refresh) {
-      throw new Error("TokenSession.refresh: \u043D\u0435\u0442 refreshToken \u0432 storage");
+      throw sessionFailure(void 0, {
+        operation: "TokenSession",
+        failureAt: "ValidateState" /* ValidateState */,
+        effects,
+        category: TorrowSdkErrorCategory4.InvalidState
+      });
     }
     const deviceInfo = this.resolveDeviceInfo();
-    const resp = await this.identityClient().auth.refresh({
-      refreshToken: refresh,
-      deviceInfo
-    });
-    await this.applyTokenRespUnlocked(resp);
-    return resp;
-  }
-  /** Caller must hold `runExclusive`. */
-  async refreshWithFailurePolicy() {
-    if (this.closed) {
-      return { outcome: "unchanged" };
+    const identity = this.identityClient();
+    let resp;
+    try {
+      resp = await identity.auth.refresh({ refreshToken: refresh, deviceInfo });
+    } catch (error) {
+      effects.push({
+        area: TorrowSdkEffectArea.Remote,
+        step: AuthSessionEffectStep.RefreshTokens,
+        state: error instanceof TorrowSdkError4 && error.request === TorrowSdkRequestState2.NotStarted ? TorrowSdkEffectState.NotApplied : TorrowSdkEffectState.Unknown
+      });
+      throw error;
     }
-    const refresh = this.tokenSnapshot.refreshToken?.trim();
-    if (!refresh) {
-      return { outcome: "unchanged" };
+    const normalized = normalizeTokenResp(resp);
+    try {
+      assertTokenRespReadyForStorage(normalized, "TokenSession.refresh");
+    } catch (error) {
+      effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.RefreshTokens, state: TorrowSdkEffectState.Unknown });
+      throw sessionFailure(error, {
+        operation: "TokenSession",
+        failureAt: "ValidateTokens" /* ValidateTokens */,
+        effects,
+        category: TorrowSdkErrorCategory4.InvalidResponse
+      });
     }
+    effects.push({ area: TorrowSdkEffectArea.Remote, step: AuthSessionEffectStep.RefreshTokens, state: TorrowSdkEffectState.Applied });
+    await this.applyTokenRespUnlocked(resp, void 0, effects);
+    return resp;
+  }
+  /** Caller must hold `runExclusive`; сведения принадлежат только текущей операции. */
+  async refreshWithFailurePolicy(effects = []) {
+    if (this.closed || !this.tokenSnapshot.refreshToken?.trim()) return { outcome: "unchanged" };
     try {
-      const resp = await this.refreshUnlocked();
+      const resp = await this.refreshUnlocked(effects);
       this.lastRefreshError = void 0;
       return { outcome: "refreshed", resp };
-    } catch (e) {
-      this.lastRefreshError = e;
-      const action = await this.opts.onRefreshFailure?.(e) ?? defaultOnRefreshFailure(e);
-      if (action === "throw") throw e;
-      if (action === "keep") {
-        return { outcome: "unchanged" };
+    } catch (cause) {
+      const error = sessionFailure(cause, { operation: "TokenSession", failureAt: "RefreshTokens" /* RefreshTokens */, effects });
+      this.lastRefreshError = error.withContext({ effects: void 0, operation: void 0, failureAt: void 0 });
+      let action;
+      try {
+        action = await this.opts.onRefreshFailure?.(error) ?? defaultOnRefreshFailure(error);
+      } catch (callbackError) {
+        throw sessionFailure(callbackError, {
+          operation: "TokenSession",
+          failureAt: "RefreshFailureCallback" /* RefreshFailureCallback */,
+          effects,
+          category: TorrowSdkErrorCategory4.Unknown,
+          reason: AuthSessionErrorReason2.CallbackFailed
+        });
       }
-      await this.clearTokensUnlocked();
-      return { outcome: "cleared" };
+      if (action === "throw") throw error;
+      if (action === "keep") return { outcome: "unchanged", error };
+      await this.clearTokensUnlocked(effects);
+      return { outcome: "cleared", error: error.withContext({ effects }) };
     }
   }
   async runExclusive(fn) {
@@ -746,7 +1008,7 @@ var TokenSession = class _TokenSession {
       release();
     }
   }
-  async ensureFreshImpl() {
+  async ensureFreshImpl(effects = []) {
     if (this.closed) return;
     const skew = this.opts.accessTokenSkewMs ?? DEFAULT_SKEW_MS;
     const access = this.tokenSnapshot.accessToken?.trim() ?? "";
@@ -756,7 +1018,7 @@ var TokenSession = class _TokenSession {
     }
     const refresh = this.tokenSnapshot.refreshToken?.trim() ?? "";
     if (refresh) {
-      await this.refreshWithFailurePolicy();
+      await this.refreshWithFailurePolicy(effects);
     }
   }
   isAccessStillFresh(access, expiresAtMs, accessTokenSkewMs) {
@@ -821,7 +1083,7 @@ var TokenSession = class _TokenSession {
         refresh: async () => {
           await this.runExclusive(async () => {
             if (this.closed) {
-              throw new Error(SESSION_CLOSED_MESSAGE);
+              this.assertNotClosedForWrite();
             }
             const result = await this.refreshWithFailurePolicy();
             if (result.outcome !== "refreshed") {
@@ -842,19 +1104,47 @@ var TokenSession = class _TokenSession {
       getAccessToken: async () => this.getAccessToken()
     });
   }
-  async persist(emitStatus) {
-    await this.opts.tokenStorage.save(this.tokenSnapshot);
+  async persist(emitStatus, effects = [], clear = false) {
+    const effect = {
+      area: TorrowSdkEffectArea.Storage,
+      step: clear ? AuthSessionEffectStep.ClearStorage : AuthSessionEffectStep.SaveTokens,
+      state: TorrowSdkEffectState.Unknown
+    };
+    effects.push(effect);
+    try {
+      await this.opts.tokenStorage.save(this.tokenSnapshot);
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TokenSession",
+        failureAt: clear ? "ClearStorage" /* ClearStorage */ : "SaveTokens" /* SaveTokens */,
+        effects,
+        category: TorrowSdkErrorCategory4.StorageFailure
+      });
+    }
+    effects[effects.length - 1] = { ...effect, state: TorrowSdkEffectState.Applied };
     if (emitStatus) this.emitStatusChange();
   }
 };
 
 // ../../src/auth-session/torrow-auth.ts
 import {
-  TorrowClient as TorrowClient3
+  TorrowClient as TorrowClient3,
+  TorrowSdkError as TorrowSdkError8,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory8,
+  TorrowSdkEffectArea as TorrowSdkEffectArea4,
+  TorrowSdkEffectState as TorrowSdkEffectState4,
+  AuthSessionEffectStep as AuthSessionEffectStep4
 } from "@torrow/sdk-client";
 
 // ../../src/auth-session/link-login.ts
 import {
+  TorrowSdkError as TorrowSdkError5,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory5,
+  TorrowSdkRequestState as TorrowSdkRequestState3,
+  TorrowSdkEffectArea as TorrowSdkEffectArea2,
+  TorrowSdkEffectState as TorrowSdkEffectState2,
+  AuthSessionEffectStep as AuthSessionEffectStep2,
+  AuthSessionErrorReason as AuthSessionErrorReason3,
   AccountTypeValues,
   DefaultAuthScopes as DefaultAuthScopes3
 } from "@torrow/sdk-client";
@@ -885,62 +1175,96 @@ var DEFAULT_POLL_TIMEOUT_SEC = 180;
 var DEFAULT_LANGUAGE = "ru";
 var DEFAULT_REGION = 70;
 async function runLinkLogin(session, options) {
-  const client = session.identityClient();
-  const accountType = options.accountType ?? AccountTypeValues.Telegram;
-  const body = {
-    accountType,
-    language: options.language?.trim() || DEFAULT_LANGUAGE,
-    regionStorageId: typeof options.regionStorageId === "number" && Number.isFinite(options.regionStorageId) ? options.regionStorageId : DEFAULT_REGION,
-    ...options.inviteSessionId?.trim() ? { inviteSessionId: options.inviteSessionId.trim() } : {},
-    ...options.captcha?.trim() ? { captcha: options.captcha.trim() } : {},
-    ...options.deviceInfo.deviceId?.trim() ? { deviceId: options.deviceInfo.deviceId.trim() } : {}
-  };
-  const createResp = await client.auth.createSession(body, { signal: options.signal });
-  const sessionId = createResp.sessionId?.trim();
-  const code = createResp.code?.trim();
-  const authUrl = createResp.authUrl?.trim();
-  if (!sessionId || !code || !authUrl) {
-    throw new Error(
-      "runLinkLogin: createSession response incomplete (need sessionId, code, authUrl)"
-    );
-  }
-  await options.onLink(authUrl);
-  const scopes = options.scopes && options.scopes.length > 0 ? options.scopes : [...DefaultAuthScopes3];
-  const intervalMs = typeof options.pollIntervalMs === "number" && options.pollIntervalMs > 0 ? options.pollIntervalMs : DEFAULT_POLL_INTERVAL_MS;
-  const timeoutSec = typeof options.pollTimeoutSec === "number" && options.pollTimeoutSec > 0 ? options.pollTimeoutSec : typeof createResp.sessionLifeTimeInSeconds === "number" && createResp.sessionLifeTimeInSeconds > 0 ? createResp.sessionLifeTimeInSeconds : DEFAULT_POLL_TIMEOUT_SEC;
-  const deadline = Date.now() + timeoutSec * 1e3;
-  for (; ; ) {
-    options.signal?.throwIfAborted?.();
+  const effects = [];
+  let failureAt = "CreateAuthSession" /* CreateAuthSession */;
+  try {
+    throwIfOtpAborted(options.signal);
+    const client = session.identityClient();
+    const accountType = options.accountType ?? AccountTypeValues.Telegram;
+    const body = {
+      accountType,
+      language: options.language?.trim() || DEFAULT_LANGUAGE,
+      regionStorageId: typeof options.regionStorageId === "number" && Number.isFinite(options.regionStorageId) ? options.regionStorageId : DEFAULT_REGION,
+      ...options.inviteSessionId?.trim() ? { inviteSessionId: options.inviteSessionId.trim() } : {},
+      ...options.captcha?.trim() ? { captcha: options.captcha.trim() } : {},
+      ...options.deviceInfo.deviceId?.trim() ? { deviceId: options.deviceInfo.deviceId.trim() } : {}
+    };
+    let createResp;
     try {
-      return await session.requestTokenWithCode({
-        sessionId,
-        code,
-        scopes,
-        signal: options.signal
+      createResp = await client.auth.createSession(body, { signal: options.signal });
+    } catch (error) {
+      effects.push({
+        area: TorrowSdkEffectArea2.Remote,
+        step: AuthSessionEffectStep2.CreateAuthSession,
+        state: error instanceof TorrowSdkError5 && error.request === TorrowSdkRequestState3.NotStarted ? TorrowSdkEffectState2.NotApplied : TorrowSdkEffectState2.Unknown
       });
-    } catch (e) {
-      if (!isAuthSessionNotReadyYet(e)) throw e;
-      if (Date.now() >= deadline) {
-        throw new Error(
-          `runLinkLogin: timeout ~${timeoutSec}s waiting for auth session to become ready`
-        );
+      throw error;
+    }
+    effects.push({ area: TorrowSdkEffectArea2.Remote, step: AuthSessionEffectStep2.CreateAuthSession, state: TorrowSdkEffectState2.Unknown });
+    failureAt = "ValidateResponse" /* ValidateResponse */;
+    const sessionId = createResp.sessionId?.trim();
+    const code = createResp.code?.trim();
+    const authUrl = createResp.authUrl?.trim();
+    if (!sessionId || !code || !authUrl) {
+      throw sessionFailure(void 0, { operation: "TorrowAuth.loginWithLink", failureAt, effects: [], category: TorrowSdkErrorCategory5.InvalidResponse });
+    }
+    effects[effects.length - 1] = { area: TorrowSdkEffectArea2.Remote, step: AuthSessionEffectStep2.CreateAuthSession, state: TorrowSdkEffectState2.Applied };
+    failureAt = "OnLink" /* OnLink */;
+    await options.onLink(authUrl);
+    const scopes = options.scopes && options.scopes.length > 0 ? options.scopes : [...DefaultAuthScopes3];
+    const intervalMs = typeof options.pollIntervalMs === "number" && options.pollIntervalMs > 0 ? options.pollIntervalMs : DEFAULT_POLL_INTERVAL_MS;
+    const timeoutSec = typeof options.pollTimeoutSec === "number" && options.pollTimeoutSec > 0 ? options.pollTimeoutSec : typeof createResp.sessionLifeTimeInSeconds === "number" && createResp.sessionLifeTimeInSeconds > 0 ? createResp.sessionLifeTimeInSeconds : DEFAULT_POLL_TIMEOUT_SEC;
+    const deadline = Date.now() + timeoutSec * 1e3;
+    failureAt = "PollTokens" /* PollTokens */;
+    for (; ; ) {
+      throwIfOtpAborted(options.signal);
+      try {
+        return await session.requestTokenWithCode({
+          sessionId,
+          code,
+          scopes,
+          signal: options.signal
+        });
+      } catch (e) {
+        if (!isAuthSessionNotReadyYet(e)) throw e;
+        if (Date.now() >= deadline) {
+          throw sessionFailure(e, { operation: "TorrowAuth.loginWithLink", failureAt, effects: [], category: TorrowSdkErrorCategory5.InvalidState, reason: AuthSessionErrorReason3.SessionNotReady });
+        }
+        await sleepMs(intervalMs, options.signal);
       }
-      await sleepMs(intervalMs, options.signal);
     }
+  } catch (cause) {
+    const error = options.signal?.aborted && !(cause instanceof TorrowSdkError5) ? new TorrowSdkError5({ category: TorrowSdkErrorCategory5.Cancelled, sensitive: { cause } }) : cause;
+    const callback = failureAt === "OnLink" /* OnLink */;
+    throw sessionFailure(error, {
+      operation: "TorrowAuth.loginWithLink",
+      failureAt,
+      effects: [...effects, ...failureAt === "PollTokens" /* PollTokens */ && error instanceof TorrowSdkError5 ? error.effects ?? [] : []],
+      ...callback ? { category: TorrowSdkErrorCategory5.Unknown, reason: AuthSessionErrorReason3.CallbackFailed } : {}
+    });
   }
 }
 
 // ../../src/auth-session/otp-login.ts
 import {
+  AuthSessionEffectStep as AuthSessionEffectStep3,
+  AuthSessionErrorReason as AuthSessionErrorReason4,
+  TorrowSdkEffectArea as TorrowSdkEffectArea3,
+  TorrowSdkEffectState as TorrowSdkEffectState3,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory7,
+  TorrowSdkRequestState as TorrowSdkRequestState4,
   DefaultAuthScopes as DefaultAuthScopes5,
   SendCodeAccountTypeValues,
-  TorrowHttpError as TorrowHttpError3,
+  TorrowSdkError as TorrowSdkError7,
   VerificationMethodValues as VerificationMethodValues2,
   TokenStatusValues as TokenStatusValues5
 } from "@torrow/sdk-client";
 
 // ../../src/auth-session/mobile-id.ts
 import {
+  TorrowSdkError as TorrowSdkError6,
+  TorrowSdkErrorCategory as TorrowSdkErrorCategory6,
+  TorrowSdkErrorDomain as TorrowSdkErrorDomain4,
   DefaultAuthScopes as DefaultAuthScopes4,
   TokenStatusValues as TokenStatusValues4
 } from "@torrow/sdk-client";
@@ -952,7 +1276,7 @@ function scopesOrDefault(scopes) {
 async function pollMobileIdOnce(client, args) {
   const sessionId = args.sessionId.trim();
   if (!sessionId) {
-    throw new Error("pollMobileIdOnce: sessionId is empty");
+    throw otpFailure(TorrowSdkErrorCategory6.InvalidInput);
   }
   const body = {
     sessionId,
@@ -961,21 +1285,24 @@ async function pollMobileIdOnce(client, args) {
     scopes: scopesOrDefault(args.scopes),
     deviceInfo: args.deviceInfo
   };
-  return normalizeTokenResp(await requestAuthToken(client, body, args.signal));
+  const raw = await requestAuthToken(client, body, args.signal);
+  try {
+    return normalizeTokenResp(raw);
+  } catch (cause) {
+    throw otpFailure(TorrowSdkErrorCategory6.InvalidResponse, void 0, cause);
+  }
 }
 async function pollMobileIdUntilReady(client, options) {
   const sessionId = options.sessionId.trim();
   if (!sessionId) {
-    throw new Error("pollMobileIdUntilReady: sessionId is empty");
+    throw otpFailure(TorrowSdkErrorCategory6.InvalidInput);
   }
   const intervalSec = typeof options.pollIntervalSeconds === "number" && options.pollIntervalSeconds > 0 ? options.pollIntervalSeconds : DEFAULT_POLL_INTERVAL_SEC;
   const maxWaitSec = typeof options.maxWaitSeconds === "number" && options.maxWaitSeconds > 0 ? options.maxWaitSeconds : DEFAULT_MAX_WAIT_SEC;
   const deadline = Date.now() + maxWaitSec * 1e3;
   const scopes = scopesOrDefault(options.scopes);
   for (; ; ) {
-    if (options.signal?.aborted) {
-      throw options.signal.reason ?? new Error("Aborted");
-    }
+    throwIfOtpAborted(options.signal);
     const resp = await pollMobileIdOnce(client, {
       sessionId,
       deviceInfo: options.deviceInfo,
@@ -984,25 +1311,21 @@ async function pollMobileIdUntilReady(client, options) {
     });
     const status = resp.status;
     if (tokenTransition(status, true) === TokenStatusValues4.TokenReady) {
-      return assertTokenRespReadyForStorage(resp, "pollMobileIdUntilReady");
+      return readyTokens(resp);
     }
     if (status === TokenStatusValues4.Failed) {
-      throw new Error(
-        "pollMobileIdUntilReady: TokenResp.status=Failed \u2014 \u043D\u0443\u0436\u0435\u043D \u043D\u043E\u0432\u044B\u0439 sendCode."
-      );
+      throw mobileInvalidState();
     }
     if (status === TokenStatusValues4.AwaitingSmsCode) {
       const obtain = options.obtainSmsCode;
       if (!obtain) {
-        throw new Error(
-          "pollMobileIdUntilReady: AwaitingSmsCode, \u043D\u043E obtainSmsCode \u043D\u0435 \u0437\u0430\u0434\u0430\u043D."
-        );
+        throw otpFailure(TorrowSdkErrorCategory6.InvalidInput);
       }
       const code = (await obtain({
         codeLength: options.smsCodeLength
       })).trim();
       if (!code) {
-        throw new Error("pollMobileIdUntilReady: \u043F\u0443\u0441\u0442\u043E\u0439 SMS-\u043A\u043E\u0434 \u043F\u043E\u0441\u043B\u0435 AwaitingSmsCode.");
+        throw otpFailure(TorrowSdkErrorCategory6.InvalidInput);
       }
       const afterSms = await pollMobileIdOnce(client, {
         sessionId,
@@ -1012,12 +1335,10 @@ async function pollMobileIdUntilReady(client, options) {
         signal: options.signal
       });
       if (tokenTransition(afterSms.status, true) === TokenStatusValues4.TokenReady) {
-        return assertTokenRespReadyForStorage(afterSms, "pollMobileIdUntilReady (SMS)");
+        return readyTokens(afterSms);
       }
       if (afterSms.status === TokenStatusValues4.Failed) {
-        throw new Error(
-          "pollMobileIdUntilReady: TokenResp.status=Failed \u043F\u043E\u0441\u043B\u0435 SMS \u2014 \u043D\u0443\u0436\u0435\u043D \u043D\u043E\u0432\u044B\u0439 sendCode."
-        );
+        throw mobileInvalidState();
       }
       if (afterSms.status === TokenStatusValues4.Pending) {
         continue;
@@ -1025,86 +1346,33 @@ async function pollMobileIdUntilReady(client, options) {
       if (afterSms.status === TokenStatusValues4.AwaitingSmsCode) {
         continue;
       }
-      throw new Error(
-        `pollMobileIdUntilReady: \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0439 TokenResp.status=${String(afterSms.status)} \u043F\u043E\u0441\u043B\u0435 SMS.`
-      );
+      throw otpFailure(TorrowSdkErrorCategory6.InvalidResponse);
     }
     if (status !== TokenStatusValues4.Pending) {
-      throw new Error(
-        `pollMobileIdUntilReady: \u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0439 TokenResp.status=${String(status)}.`
-      );
+      throw otpFailure(TorrowSdkErrorCategory6.InvalidResponse);
     }
     if (Date.now() >= deadline) {
-      throw new Error(
-        `pollMobileIdUntilReady: timeout ~${maxWaitSec}\u0441 (poll \u043A\u0430\u0436\u0434\u044B\u0435 ${intervalSec}\u0441) \u2014 \u0441\u0442\u0430\u0442\u0443\u0441 Pending.`
-      );
+      throw mobileInvalidState();
     }
     await sleepMs(intervalSec * 1e3, options.signal);
   }
 }
-
-// ../../src/auth-session/otp-login.ts
-var MOBILE_ID_SMS_CODE_LENGTH = 4;
-var OtpCodeRequestLimitExceededError = class extends Error {
-  name = "OtpCodeRequestLimitExceededError";
-  minutes;
-  seconds;
-  traceUrl;
-  apiMessage;
-  body;
-  constructor(body) {
-    const parsed = parseRateLimitBody(body);
-    const wait = parsed.min || parsed.sec ? `\u041F\u043E\u0432\u0442\u043E\u0440 \u043F\u0440\u0438\u043C\u0435\u0440\u043D\u043E \u0447\u0435\u0440\u0435\u0437 ${[parsed.min && `${parsed.min} \u043C\u0438\u043D.`, parsed.sec && `${parsed.sec} \u0441\u0435\u043A.`].filter(Boolean).join(" ")}.` : "\u0422\u043E\u0447\u043D\u043E\u0435 \u0432\u0440\u0435\u043C\u044F \u043E\u0436\u0438\u0434\u0430\u043D\u0438\u044F \u0441\u0435\u0440\u0432\u0435\u0440 \u043D\u0435 \u043F\u0435\u0440\u0435\u0434\u0430\u043B.";
-    super(`sendCode: CODE_REQUEST_LIMIT_EXCEEDED. ${wait}`);
-    this.minutes = parsed.min;
-    this.seconds = parsed.sec;
-    this.traceUrl = parsed.trace;
-    this.apiMessage = parsed.message;
-    this.body = body;
-  }
-};
-var OtpAuthHeaderMissingError = class extends Error {
-  name = "OtpAuthHeaderMissingError";
-  body;
-  systemMessage;
-  constructor(body) {
-    const sys = body !== null && typeof body === "object" && typeof body.systemMessage === "string" ? body.systemMessage.trim() : void 0;
-    super(
-      [
-        "requestToken: AUTH_HEADER_MISSING \u2014 \u0437\u0430\u0434\u0430\u0439 appCredentials: { clientId, clientSecret }.",
-        sys ? `\u0421\u043E\u043E\u0431\u0449\u0435\u043D\u0438\u0435 \u0441\u0435\u0440\u0432\u0435\u0440\u0430: ${sys}` : ""
-      ].filter(Boolean).join(" ")
-    );
-    this.body = body;
-    this.systemMessage = sys;
+function readyTokens(response) {
+  try {
+    return assertTokenRespReadyForStorage(response, "pollMobileIdUntilReady");
+  } catch (cause) {
+    throw otpFailure(TorrowSdkErrorCategory6.InvalidResponse, void 0, cause);
   }
-};
-function parseRateLimitBody(body) {
-  if (body === null || typeof body !== "object") return {};
-  const o = body;
-  const p = o.parameters ?? {};
-  return {
-    min: p.minutes != null && String(p.minutes) !== "" ? String(p.minutes) : void 0,
-    sec: p.seconds != null && String(p.seconds) !== "" ? String(p.seconds) : void 0,
-    message: typeof o.message === "string" && o.message.trim() ? o.message.trim() : void 0,
-    trace: typeof o.traceUrl === "string" && o.traceUrl.trim() ? o.traceUrl.trim() : void 0
-  };
 }
-function isSendCodeRateLimitedBody(body) {
-  if (body === null || typeof body !== "object") return false;
-  return body.name === "CODE_REQUEST_LIMIT_EXCEEDED";
-}
-function isAuthHeaderMissingBody(body) {
-  if (body === null || typeof body !== "object") return false;
-  return body.name === "AUTH_HEADER_MISSING";
-}
-function httpErrorBody(e) {
-  if (e instanceof TorrowHttpError3) return e.body;
-  if (e !== null && typeof e === "object" && "body" in e) {
-    return e.body;
-  }
-  return void 0;
+function mobileInvalidState() {
+  return new TorrowSdkError6({
+    category: TorrowSdkErrorCategory6.InvalidState,
+    detail: { domain: TorrowSdkErrorDomain4.AuthSession }
+  });
 }
+
+// ../../src/auth-session/otp-login.ts
+var MOBILE_ID_SMS_CODE_LENGTH = 4;
 function scopesOrDefault2(scopes) {
   return scopes && scopes.length > 0 ? scopes : [...DefaultAuthScopes5];
 }
@@ -1113,100 +1381,141 @@ function effectiveCodeLength(raw, fallback) {
   return fallback > 0 ? fallback : void 0;
 }
 async function requestTokenOrThrow(client, body, signal) {
+  let raw;
   try {
-    return normalizeTokenResp(await requestAuthToken(client, body, signal));
-  } catch (e) {
-    const errBody = httpErrorBody(e);
-    if (errBody !== void 0 && isAuthHeaderMissingBody(errBody)) {
-      throw new OtpAuthHeaderMissingError(errBody);
-    }
-    throw e;
+    raw = await requestAuthToken(client, body, signal);
+  } catch (error) {
+    throw otpHttpFailure(error);
   }
-}
-async function runOtpLogin(client, options) {
-  const accountName = options.accountName.trim();
-  const accountType = options.type;
-  const scopes = scopesOrDefault2(options.scopes);
-  const signal = options.signal;
-  let sendResp;
   try {
-    sendResp = await sendOtpCode(client, options, signal);
-  } catch (e) {
-    const errBody = httpErrorBody(e);
-    if (errBody !== void 0 && isSendCodeRateLimitedBody(errBody)) {
-      throw new OtpCodeRequestLimitExceededError(errBody);
-    }
-    throw e;
+    return normalizeTokenResp(raw);
+  } catch (cause) {
+    throw otpFailure(TorrowSdkErrorCategory7.InvalidResponse, void 0, cause);
   }
-  const sessionId = sendResp.sessionId?.trim();
-  if (!sessionId) {
-    throw new Error("runOtpLogin: sendCode response had no sessionId");
-  }
-  const result = {
-    accountName,
-    accountType,
-    sessionId,
-    usedMethod: sendResp.usedMethod,
-    codeLength: sendResp.codeLength,
-    pollIntervalSeconds: sendResp.pollIntervalSeconds,
-    availableMethods: sendResp.availableMethods,
-    sessionLifeTimeInSeconds: sendResp.sessionLifeTimeInSeconds,
-    nextAvailableUsageTime: sendResp.nextAvailableUsageTime ?? null
-  };
-  await options.onSendCode(result);
-  if (sendResp.usedMethod === VerificationMethodValues2.MtsMobileId) {
+}
+async function runOtpLoginWithEffects(client, options) {
+  const effects = [];
+  let failureAt = "SendCode" /* SendCode */;
+  try {
+    throwIfOtpAborted(options.signal);
+    const accountName = options.accountName.trim();
+    const accountType = options.type;
+    const scopes = scopesOrDefault2(options.scopes);
+    const signal = options.signal;
+    let sendResp;
     try {
-      return await pollMobileIdUntilReady(client, {
-        sessionId,
-        deviceInfo: options.deviceInfo,
-        scopes,
-        pollIntervalSeconds: sendResp.pollIntervalSeconds,
-        maxWaitSeconds: sendResp.sessionLifeTimeInSeconds,
-        signal,
-        smsCodeLength: typeof sendResp.codeLength === "number" && sendResp.codeLength > 0 ? sendResp.codeLength : MOBILE_ID_SMS_CODE_LENGTH,
-        obtainSmsCode: async (ctx) => {
-          const codeLength2 = effectiveCodeLength(ctx.codeLength, MOBILE_ID_SMS_CODE_LENGTH);
-          return (await options.getCode({
-            sessionId,
-            codeLength: codeLength2,
-            usedMethod: sendResp.usedMethod
-          })).trim();
-        }
+      sendResp = await sendOtpCode(client, options, signal);
+    } catch (error) {
+      effects.push({
+        area: TorrowSdkEffectArea3.Remote,
+        step: AuthSessionEffectStep3.SendCode,
+        state: error instanceof TorrowSdkError7 && error.request === TorrowSdkRequestState4.NotStarted ? TorrowSdkEffectState3.NotApplied : TorrowSdkEffectState3.Unknown
       });
-    } catch (e) {
-      const errBody = httpErrorBody(e);
-      if (errBody !== void 0 && isAuthHeaderMissingBody(errBody)) {
-        throw new OtpAuthHeaderMissingError(errBody);
+      throw otpHttpFailure(error);
+    }
+    effects.push({ area: TorrowSdkEffectArea3.Remote, step: AuthSessionEffectStep3.SendCode, state: TorrowSdkEffectState3.Unknown });
+    failureAt = "ValidateResponse" /* ValidateResponse */;
+    const sessionId = sendResp.sessionId?.trim();
+    if (!sessionId) {
+      throw otpFailure(TorrowSdkErrorCategory7.InvalidResponse);
+    }
+    effects[effects.length - 1] = { area: TorrowSdkEffectArea3.Remote, step: AuthSessionEffectStep3.SendCode, state: TorrowSdkEffectState3.Applied };
+    const result = {
+      accountName,
+      accountType,
+      sessionId,
+      usedMethod: sendResp.usedMethod,
+      codeLength: sendResp.codeLength,
+      pollIntervalSeconds: sendResp.pollIntervalSeconds,
+      availableMethods: sendResp.availableMethods,
+      sessionLifeTimeInSeconds: sendResp.sessionLifeTimeInSeconds,
+      nextAvailableUsageTime: sendResp.nextAvailableUsageTime ?? null
+    };
+    failureAt = "OnSendCode" /* OnSendCode */;
+    await options.onSendCode(result);
+    if (sendResp.usedMethod === VerificationMethodValues2.MtsMobileId) {
+      try {
+        failureAt = "PollTokens" /* PollTokens */;
+        const tokens = await pollMobileIdUntilReady(client, {
+          sessionId,
+          deviceInfo: options.deviceInfo,
+          scopes,
+          pollIntervalSeconds: sendResp.pollIntervalSeconds,
+          maxWaitSeconds: sendResp.sessionLifeTimeInSeconds,
+          signal,
+          smsCodeLength: typeof sendResp.codeLength === "number" && sendResp.codeLength > 0 ? sendResp.codeLength : MOBILE_ID_SMS_CODE_LENGTH,
+          obtainSmsCode: async (ctx) => {
+            const codeLength2 = effectiveCodeLength(ctx.codeLength, MOBILE_ID_SMS_CODE_LENGTH);
+            failureAt = "GetCode" /* GetCode */;
+            const code2 = (await options.getCode({
+              sessionId,
+              codeLength: codeLength2,
+              usedMethod: sendResp.usedMethod
+            })).trim();
+            failureAt = "PollTokens" /* PollTokens */;
+            return code2;
+          }
+        });
+        effects.push({ area: TorrowSdkEffectArea3.Remote, step: AuthSessionEffectStep3.IssueTokens, state: TorrowSdkEffectState3.Applied });
+        return { tokens, effects };
+      } catch (error) {
+        throw otpHttpFailure(error);
       }
-      throw e;
     }
-  }
-  const classicLength = effectiveCodeLength(
-    sendResp.codeLength,
-    accountType === SendCodeAccountTypeValues.Email ? 6 : 4
-  );
-  const code = (await options.getCode({
-    sessionId,
-    codeLength: classicLength,
-    usedMethod: sendResp.usedMethod
-  })).trim();
-  if (!code) {
-    throw new Error("runOtpLogin: empty OTP code");
-  }
-  const resp = await requestTokenOrThrow(
-    client,
-    {
+    const classicLength = effectiveCodeLength(
+      sendResp.codeLength,
+      accountType === SendCodeAccountTypeValues.Email ? 6 : 4
+    );
+    failureAt = "GetCode" /* GetCode */;
+    const code = (await options.getCode({
       sessionId,
-      code,
-      scopes,
-      deviceInfo: options.deviceInfo
-    },
-    signal
-  );
-  if (tokenTransition(resp.status, true) !== TokenStatusValues5.TokenReady) {
-    throw new Error(`runOtpLogin: TokenResp.status=${resp.status} (\u043E\u0436\u0438\u0434\u0430\u043B\u0441\u044F TokenReady)`);
+      codeLength: classicLength,
+      usedMethod: sendResp.usedMethod
+    })).trim();
+    failureAt = "ValidateInput" /* ValidateInput */;
+    if (!code) {
+      throw otpFailure(TorrowSdkErrorCategory7.InvalidInput);
+    }
+    failureAt = "IssueTokens" /* IssueTokens */;
+    const resp = await requestTokenOrThrow(
+      client,
+      {
+        sessionId,
+        code,
+        scopes,
+        deviceInfo: options.deviceInfo
+      },
+      signal
+    );
+    if (tokenTransition(resp.status, true) !== TokenStatusValues5.TokenReady) {
+      throw otpFailure(TorrowSdkErrorCategory7.InvalidResponse);
+    }
+    let ready;
+    try {
+      ready = assertTokenRespReadyForStorage(resp, "runOtpLogin");
+    } catch (cause) {
+      throw otpFailure(TorrowSdkErrorCategory7.InvalidResponse, void 0, cause);
+    }
+    effects.push({ area: TorrowSdkEffectArea3.Remote, step: AuthSessionEffectStep3.IssueTokens, state: TorrowSdkEffectState3.Applied });
+    return { tokens: ready, effects };
+  } catch (cause) {
+    const error = options.signal?.aborted && !(cause instanceof TorrowSdkError7) ? new TorrowSdkError7({ category: TorrowSdkErrorCategory7.Cancelled, sensitive: { cause } }) : cause;
+    const tokenStages = ["IssueTokens" /* IssueTokens */, "PollTokens" /* PollTokens */];
+    if (tokenStages.includes(failureAt)) {
+      effects.push({
+        area: TorrowSdkEffectArea3.Remote,
+        step: AuthSessionEffectStep3.IssueTokens,
+        state: error instanceof TorrowSdkError7 && error.request === TorrowSdkRequestState4.NotStarted ? TorrowSdkEffectState3.NotApplied : TorrowSdkEffectState3.Unknown
+      });
+    }
+    const callback = failureAt === "GetCode" /* GetCode */ || failureAt === "OnSendCode" /* OnSendCode */;
+    throw sessionFailure(error, {
+      operation: "TorrowAuth.loginWithOtp",
+      failureAt,
+      effects,
+      ...callback && !options.signal?.aborted ? { category: TorrowSdkErrorCategory7.Unknown, reason: AuthSessionErrorReason4.CallbackFailed } : {}
+    });
   }
-  return assertTokenRespReadyForStorage(resp, "runOtpLogin");
 }
 
 // ../../src/auth-session/torrow-auth.ts
@@ -1227,72 +1536,157 @@ function sessionOpenOpts(base) {
 function sessionOpenOptsForLogin(base) {
   return { ...sessionOpenOpts(base), skipEnsureFreshOnOpen: true };
 }
+function loginFailureStage(error, current) {
+  return error instanceof TorrowSdkError8 ? Object.values(SessionFailureStage).find((stage) => stage === error.failureAt) ?? current : current;
+}
 var TorrowAuth = {
   /** Пошаговый OTP без storage, polling и refresh. */
   createOtpFlow,
+  /** Загрузить сессию; общий отказ сохраняет текущую диагностику open/refresh. */
   async connect(options) {
-    const session = await TokenSession.open(sessionOpenOpts(options));
-    return { client: session.client, session };
+    try {
+      const session = await TokenSession.open(sessionOpenOpts(options));
+      return { client: session.client, session };
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TorrowAuth.connect",
+        failureAt: "OpenSession" /* OpenSession */,
+        effects: error instanceof TorrowSdkError8 ? error.effects ?? [] : []
+      });
+    }
   },
   async loginWithOtp(options) {
-    const accountName = options.account.accountName.trim();
-    if (!accountName) {
-      throw new Error("TorrowAuth.loginWithOtp: account.accountName is empty");
+    const effects = [];
+    let failureAt = "ValidateInput" /* ValidateInput */;
+    try {
+      const accountName = options.account.accountName.trim();
+      if (!accountName) throw sessionFailure(void 0, {
+        operation: "TorrowAuth.loginWithOtp",
+        failureAt,
+        effects,
+        category: TorrowSdkErrorCategory8.InvalidInput
+      });
+      failureAt = "OpenSession" /* OpenSession */;
+      const opened = await TokenSession.openWithEffects(sessionOpenOptsForLogin(options));
+      const session = opened.session;
+      effects.push(...opened.effects);
+      const deviceInfo = session.getDeviceInfo();
+      failureAt = "SendCode" /* SendCode */;
+      const ready = await runOtpLoginWithEffects(session.identityClient(), {
+        accountName,
+        type: options.account.accountType,
+        deviceInfo,
+        onSendCode: options.onSendCode,
+        getCode: options.getCode,
+        scopes: options.scopes,
+        language: options.language,
+        regionStorageId: options.regionStorageId,
+        captcha: options.captcha,
+        captchaType: options.captchaType,
+        inviteSessionId: options.inviteSessionId,
+        preferredMethod: options.preferredMethod,
+        supportedMethods: options.supportedMethods,
+        signal: options.signal
+      });
+      effects.push(...ready.effects);
+      failureAt = "ApplyTokens" /* ApplyTokens */;
+      await session.applyTokenResp(ready.tokens, { replace: true });
+      return { client: session.client, session };
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TorrowAuth.loginWithOtp",
+        failureAt: loginFailureStage(error, failureAt),
+        effects: [...effects, ...error instanceof TorrowSdkError8 ? error.effects ?? [] : []]
+      });
     }
-    const session = await TokenSession.open(sessionOpenOptsForLogin(options));
-    const deviceInfo = session.getDeviceInfo();
-    const ready = await runOtpLogin(session.identityClient(), {
-      accountName,
-      type: options.account.accountType,
-      deviceInfo,
-      onSendCode: options.onSendCode,
-      getCode: options.getCode,
-      scopes: options.scopes,
-      language: options.language,
-      regionStorageId: options.regionStorageId,
-      captcha: options.captcha,
-      captchaType: options.captchaType,
-      inviteSessionId: options.inviteSessionId,
-      preferredMethod: options.preferredMethod,
-      supportedMethods: options.supportedMethods,
-      signal: options.signal
-    });
-    await session.applyTokenResp(ready, { replace: true });
-    return { client: session.client, session };
   },
   async loginWithLink(options) {
-    const session = await TokenSession.open(sessionOpenOptsForLogin(options));
-    await runLinkLogin(session, {
-      deviceInfo: session.getDeviceInfo(),
-      onLink: options.onLink,
-      accountType: options.accountType,
-      language: options.language,
-      regionStorageId: options.regionStorageId,
-      captcha: options.captcha,
-      inviteSessionId: options.inviteSessionId,
-      scopes: options.scopes,
-      pollIntervalMs: options.pollIntervalMs,
-      pollTimeoutSec: options.pollTimeoutSec,
-      signal: options.signal
-    });
-    return { client: session.client, session };
+    const effects = [];
+    let failureAt = "OpenSession" /* OpenSession */;
+    try {
+      const opened = await TokenSession.openWithEffects(sessionOpenOptsForLogin(options));
+      const session = opened.session;
+      effects.push(...opened.effects);
+      failureAt = "CreateAuthSession" /* CreateAuthSession */;
+      await runLinkLogin(session, {
+        deviceInfo: session.getDeviceInfo(),
+        onLink: options.onLink,
+        accountType: options.accountType,
+        language: options.language,
+        regionStorageId: options.regionStorageId,
+        captcha: options.captcha,
+        inviteSessionId: options.inviteSessionId,
+        scopes: options.scopes,
+        pollIntervalMs: options.pollIntervalMs,
+        pollTimeoutSec: options.pollTimeoutSec,
+        signal: options.signal
+      });
+      return { client: session.client, session };
+    } catch (error) {
+      throw sessionFailure(error, {
+        operation: "TorrowAuth.loginWithLink",
+        failureAt: loginFailureStage(error, failureAt),
+        effects: [...effects, ...error instanceof TorrowSdkError8 ? error.effects ?? [] : []]
+      });
+    }
   },
+  /** Сохранить host tokens, затем connect; последующий отказ не отменяет Applied сохранение. */
   async fromTokens(options) {
-    const accessToken = options.accessToken.trim();
-    if (!accessToken) {
-      throw new Error("TorrowAuth.fromTokens: accessToken is empty");
+    const effects = [];
+    let failureAt = "ValidateInput" /* ValidateInput */;
+    try {
+      const accessToken = options.accessToken.trim();
+      if (!accessToken) {
+        throw sessionFailure(void 0, {
+          operation: "TorrowAuth.fromTokens",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory8.InvalidInput
+        });
+      }
+      const refreshToken = options.refreshToken?.trim() || void 0;
+      failureAt = "LoadStorage" /* LoadStorage */;
+      let prev;
+      try {
+        prev = await options.tokenStorage.load();
+      } catch (error) {
+        throw sessionFailure(error, {
+          operation: "TorrowAuth.fromTokens",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory8.StorageFailure
+        });
+      }
+      const explicitTtl = options.accessExpiresAtMs;
+      const accessExpiresAtMs = typeof explicitTtl === "number" && Number.isFinite(explicitTtl) && explicitTtl > 0 ? explicitTtl : accessExpiresAtMsFromJwt(accessToken);
+      failureAt = "SeedStorage" /* SeedStorage */;
+      effects.push({ area: TorrowSdkEffectArea4.Storage, step: AuthSessionEffectStep4.SaveTokens, state: TorrowSdkEffectState4.Unknown });
+      try {
+        await options.tokenStorage.save({
+          accessToken,
+          refreshToken,
+          accessExpiresAtMs: typeof accessExpiresAtMs === "number" && accessExpiresAtMs > 0 ? accessExpiresAtMs : void 0,
+          deviceId: options.deviceInfo.deviceId?.trim() || prev.deviceId?.trim() || void 0
+        });
+      } catch (error) {
+        throw sessionFailure(error, {
+          operation: "TorrowAuth.fromTokens",
+          failureAt,
+          effects,
+          category: TorrowSdkErrorCategory8.StorageFailure
+        });
+      }
+      effects[0] = { ...effects[0], state: TorrowSdkEffectState4.Applied };
+      failureAt = "Connect" /* Connect */;
+      try {
+        return await TorrowAuth.connect(options);
+      } catch (error) {
+        if (error instanceof TorrowSdkError8) effects.push(...error.effects ?? []);
+        throw error;
+      }
+    } catch (error) {
+      throw sessionFailure(error, { operation: "TorrowAuth.fromTokens", failureAt, effects });
     }
-    const refreshToken = options.refreshToken?.trim() || void 0;
-    const prev = await options.tokenStorage.load();
-    const explicitTtl = options.accessExpiresAtMs;
-    const accessExpiresAtMs = typeof explicitTtl === "number" && Number.isFinite(explicitTtl) && explicitTtl > 0 ? explicitTtl : accessExpiresAtMsFromJwt(accessToken);
-    await options.tokenStorage.save({
-      accessToken,
-      refreshToken,
-      ...typeof accessExpiresAtMs === "number" && accessExpiresAtMs > 0 ? { accessExpiresAtMs } : { accessExpiresAtMs: void 0 },
-      deviceId: options.deviceInfo.deviceId?.trim() || prev.deviceId?.trim() || void 0
-    });
-    return TorrowAuth.connect(options);
   },
   anonymous(config = {}) {
     return new TorrowClient3({
@@ -1302,14 +1696,9 @@ var TorrowAuth = {
   }
 };
 export {
-  AuthSessionNotReadyError,
   DEFAULT_APP_CREDENTIALS,
   LocalStorageTokenStorage,
   MemoryTokenStorage,
-  OtpAuthHeaderMissingError,
-  OtpCodeRequestLimitExceededError,
-  OtpFlowError,
-  OtpFlowErrorCodeValues,
   OtpPhaseValues,
   TokenSession,
   TorrowAuth