@torrow/sdk-auth 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,543 @@
+import { A as AppCredentials, T as TokenSessionOptions, a as TokenStorage, b as TokenSessionStatus, c as TokenSessionStatusListener, d as AuthTokenSnapshot } from './types-C4e90uOw.js';
+export { R as RefreshFailureAction } from './types-C4e90uOw.js';
+import { SendCodeAccountType, VerificationMethod, TorrowClient, DeviceInfo, TokenResp, AuthScope, AuthCaptchaType, AccountType, TokenStatusValues } from '@torrow/sdk-client';
+
+/** Defaults и преобразование credentials приложения в HTTP Basic. */
+
+/**
+ * Дефолтные app credentials SDK для `/api/v1/auth/*`, если {@link TokenSessionOptions.appCredentials}
+ * не передан. Своё приложение может переопределить явной парой.
+ *
+ * Публикуется в npm `@torrow/sdk-auth` (inspectable); свой prod-secret — только override / BFF.
+ */
+declare const DEFAULT_APP_CREDENTIALS: AppCredentials;
+
+/**
+ * Внутренний оркестратор OTP-логина (не публичный export целиком; типы UI — да).
+ *
+ * **`sendCode`** → ветка по **`usedMethod`** (Mobile ID poll | classic код) →
+ * **`TokenResp`**. UI снаружи: **`onSendCode`** + **`getCode`**.
+ * IMAP / stdin / env — в app / `examples/node/_shared`, не здесь.
+ *
+ * Вызывается из `TorrowAuth.loginWithOtp`; Mobile ID — `mobile-id.ts`.
+ */
+
+/**
+ * Аргумент **`onSendCode`**: снимок **после** успешного `sendCode` (в основном поля **`SendCodeResp`**).
+ * Не путать с телом запроса: в `sendCode` уходят `supportedMethods` / `preferredMethod`
+ * (см. {@link RunOtpLoginOptions}); здесь — что сервер **выбрал** и что ещё доступно.
+ *
+ * Типичный UI: по `usedMethod` показать «ждём SMS» / «код на email» / «подтвердите push»;
+ * по `codeLength` — маску поля ввода.
+ */
+type OtpSendCodeResult = {
+    /** Аккаунт из `SendCodeReq` (телефон / email). */
+    accountName: string;
+    /** `Phone` \| `Email` из запроса (не путать с `usedMethod`). */
+    accountType: SendCodeAccountType;
+    /** Id auth-сессии для последующего `requestToken` / Mobile ID poll. */
+    sessionId: string;
+    /**
+     * Фактический канал из **`SendCodeResp.usedMethod`** — ради этого и нужен `onSendCode`.
+     * Sms / Email / FlashCall / TelegramGateway / MtsMobileId / …
+     */
+    usedMethod?: VerificationMethod;
+    /** Длина кода для input/маски; у Mobile ID часто `0` (keypad не нужен). */
+    codeLength?: number;
+    /** Интервал poll при Mobile ID (`SendCodeResp.pollIntervalSeconds`). */
+    pollIntervalSeconds?: number;
+    /**
+     * Из **`SendCodeResp`** (не тело `sendCode`): методы, доступные для этого аккаунта
+     * (UX «другой способ»). В запрос передаётся {@link RunOtpLoginOptions.supportedMethods}.
+     */
+    availableMethods?: VerificationMethod[] | null;
+    /** TTL auth-сессии `sendCode` (сек); для Mobile ID — ориентир max wait. */
+    sessionLifeTimeInSeconds?: number;
+    /** Когда снова можно дернуть `sendCode` (rate-limit hint из ответа). */
+    nextAvailableUsageTime?: Date | null;
+};
+/**
+ * Аргумент **`getCode`**: только когда нужны цифры (stdin / UI / IMAP снаружи).
+ *
+ * UI-экран уже выбран в **`onSendCode`** (`usedMethod`). Здесь — собрать код
+ * (длина из `codeLength`). На happy-path Mobile ID (push) **`getCode` не вызывается**;
+ * SMS-fallback после poll — тот же колбэк, без отдельного `reason`.
+ *
+ * `accountName` / `accountType` не дублируются — они в options и в `onSendCode`.
+ */
+type OtpGetCodeContext = {
+    sessionId: string;
+    /** Эффективная длина для валидации (Mobile ID SMS fallback: при `0` с сервера → 4). */
+    codeLength?: number;
+    /** Канал из `sendCode` (опциональная подсказка; экран уже из `onSendCode`). */
+    usedMethod?: VerificationMethod;
+};
+/** Превышен лимит `sendCode` (`CODE_REQUEST_LIMIT_EXCEEDED`). */
+declare class OtpCodeRequestLimitExceededError extends Error {
+    readonly name = "OtpCodeRequestLimitExceededError";
+    readonly minutes?: string;
+    readonly seconds?: string;
+    readonly traceUrl?: string;
+    readonly apiMessage?: string;
+    readonly body: unknown;
+    constructor(body: unknown);
+}
+/** Нет Basic на `/auth/token` (`AUTH_HEADER_MISSING`). */
+declare class OtpAuthHeaderMissingError extends Error {
+    readonly name = "OtpAuthHeaderMissingError";
+    readonly body: unknown;
+    readonly systemMessage?: string;
+    constructor(body: unknown);
+}
+
+/**
+ * Ядро пользовательской сессии: persist + проактивный refresh + single-flight + 401-retry.
+ *
+ * Low-level API: {@link TokenSession.open}. Канон для приложений —
+ * **`TorrowAuth.connect` / `login*` / `fromTokens`** (см. `torrow-auth.ts`).
+ *
+ * Логин снаружи: `TorrowAuth.loginWithOtp` / `loginWithLink`, либо
+ * `requestTokenWithCode` / `applyTokenResp` на уже открытой сессии.
+ * Не путать статус `"unauthenticated"` с `TorrowAuth.anonymous` (клиент без сессии).
+ */
+
+/**
+ * Пользовательская сессия (класс). См. file overview выше.
+ */
+declare class TokenSession {
+    private readonly opts;
+    private tokenSnapshot;
+    private ensureFreshMutex;
+    private _client;
+    private readonly statusListeners;
+    private closed;
+    /** Set in refreshWithFailurePolicy catch; not cleared on success (see public refresh). */
+    private lastRefreshError;
+    private constructor();
+    static open(opts: TokenSessionOptions): Promise<TokenSession>;
+    /** Persist, переданный в `TokenSession.open` / `TorrowAuth.*`. */
+    get tokenStorage(): TokenStorage;
+    get client(): TorrowClient;
+    /** Текущий статус сессии. */
+    get status(): TokenSessionStatus;
+    /** Подписка на смену статуса; возвращает unsubscribe. Сразу вызывает listener с текущим статусом. */
+    onStatusChange(listener: TokenSessionStatusListener): () => void;
+    /** Текущий снимок токенов сессии (копия {@link AuthTokenSnapshot}). */
+    getTokenSnapshot(): AuthTokenSnapshot;
+    /** `deviceInfo` из options open или fallback Desktop + deviceId из tokenSnapshot. */
+    getDeviceInfo(): DeviceInfo;
+    getAccessToken(): Promise<string | undefined>;
+    /**
+     * Сохранить ответ `requestToken` / `refresh` (только TokenReady).
+     * Сериализован с `ensureFresh` / `logout` через mutex. Дефолт merge намеренно
+     * (refresh-shaped); логин — `{ replace: true }`. После `logout` — новая сессия.
+     */
+    applyTokenResp(tokens: TokenResp, opts?: {
+        replace?: boolean;
+    }): Promise<void>;
+    clearTokens(): Promise<void>;
+    /**
+     * Revoke refresh (если есть) + очистка storage.
+     * Единственное публичное имя выхода из сессии.
+     */
+    logout(): Promise<void>;
+    /**
+     * Получить токены по **id auth-сессии** (`sessionId` из `sendCode` / `createSession`)
+     * и **OTP-коду доступа**, затем сохранить их в storage сессии.
+     *
+     * Один вызов `POST /api/v1/auth/token` (`requestToken`) с `{ sessionId, code }`.
+     * При успехе (`TokenReady`) — persist; если сессия ещё не готова —
+     * {@link AuthSessionNotReadyError} (поллинг для deep-link — внутри `TorrowAuth.loginWithLink`).
+     *
+     * HTTP вне mutex; persist сериализован через {@link applyTokenResp} (не оборачивать
+     * весь метод в `runExclusive` — вложенный mutex с публичным `applyTokenResp`).
+     */
+    requestTokenWithCode(args: {
+        sessionId: string;
+        code: string;
+        scopes?: AuthScope[];
+        signal?: AbortSignal;
+    }): Promise<TokenResp>;
+    /**
+     * Явный refresh (single-flight через общий mutex сессии).
+     * Сериализован с `logout` / `ensureFresh` / `applyTokenResp`.
+     * При гонке с `logout()`: promise может resolve с `TokenResp`, но snapshot уже очищен —
+     * не используй return value; смотри `session.status` / `getTokenSnapshot()`.
+     */
+    refresh(): Promise<TokenResp>;
+    ensureFresh(): Promise<void>;
+    private assertNotClosedForWrite;
+    /** Caller must hold `runExclusive`. Do not call public `applyTokenResp` from here. */
+    private applyTokenRespUnlocked;
+    private clearTokensUnlocked;
+    /** Caller must hold `runExclusive`. `refreshWithFailurePolicy` skips when no refreshToken; guard here is intentional defense-in-depth. */
+    private refreshUnlocked;
+    /** Caller must hold `runExclusive`. */
+    private refreshWithFailurePolicy;
+    private runExclusive;
+    private ensureFreshImpl;
+    private isAccessStillFresh;
+    private computeStatus;
+    private emitStatusChange;
+    private resolveDeviceInfo;
+    /** Identity-клиент с Basic приложения, без Bearer пользователя. */
+    identityClient(): TorrowClient;
+    private buildClient;
+    private persist;
+}
+
+/**
+ * Публичный фасад аутентификации **`TorrowAuth`**.
+ *
+ * Точка входа приложения: `createOtpFlow` / `connect` / `loginWithOtp` / `loginWithLink` /
+ * `fromTokens` / `anonymous`. Возвращает {@link TorrowAuthResult}
+ * (`{ client, session }`), кроме `anonymous` (только `TorrowClient`).
+ *
+ * Оркестрация OTP/Telegram — в `otp-login.ts` / `link-login.ts`;
+ * persist и refresh — в {@link TokenSession}.
+ */
+
+/** Результат `TorrowAuth.connect` / `loginWithOtp` / `loginWithLink` / `fromTokens`: API-клиент + сессия. */
+type TorrowAuthResult = {
+    client: TorrowClient;
+    session: TokenSession;
+};
+/**
+ * Общая база опций `TorrowAuth.connect` / `loginWithOtp` / `loginWithLink` / `fromTokens`.
+ *
+ * Производная от {@link TokenSessionOptions}: те же HTTP-кнопки + storage + app creds,
+ * но `deviceInfo` **обязателен**; `onRefreshFailure` пробрасывается в `TokenSession.open`.
+ *
+ * **Карта:** `TorrowClientConfig` → (Pick HTTP) → `TokenSessionOptions` → **эта база** →
+ * `TorrowAuthConnectOptions` / `TorrowAuthLoginWithOtpOptions` / …
+ * Приложение обычно передаёт именно `TorrowAuth*Options`, не `TorrowClientConfig`.
+ *
+ * `appCredentials` опционален: без него — дефолт SDK (`DEFAULT_APP_CREDENTIALS`).
+ */
+type TorrowAuthSessionBase = Omit<TokenSessionOptions, "deviceInfo"> & {
+    deviceInfo: DeviceInfo;
+};
+/** Опции {@link TorrowAuth.connect}: restore / refresh из `tokenStorage`. */
+type TorrowAuthConnectOptions = TorrowAuthSessionBase;
+/** Аккаунт для OTP `sendCode` — плоско, как OpenAPI `SendCodeReq`. */
+type TorrowAuthAccount = {
+    /** `Phone` \| `Email` → `SendCodeReq.type`. */
+    accountType: SendCodeAccountType;
+    /** Телефон или email → `SendCodeReq.accountName`. */
+    accountName: string;
+};
+/** Опции {@link TorrowAuth.loginWithOtp}: connect-база + OTP-колбэки / поля `sendCode`. */
+type TorrowAuthLoginWithOtpOptions = TorrowAuthSessionBase & {
+    account: TorrowAuthAccount;
+    /**
+     * Сигнал UI после `sendCode` (`usedMethod`, `codeLength`, …).
+     * До Mobile ID poll и до classic `getCode`. См. {@link OtpSendCodeResult}.
+     */
+    onSendCode: (result: OtpSendCodeResult) => void | Promise<void>;
+    /**
+     * Вернуть одноразовый код. Не зовётся на happy-path Mobile ID (push без SMS).
+     * См. {@link OtpGetCodeContext}.
+     */
+    getCode: (ctx: OtpGetCodeContext) => Promise<string>;
+    /** → `TokenReq.scopes`. По умолчанию `DefaultAuthScopes`. */
+    scopes?: AuthScope[];
+    /** → `SendCodeReq.language`. По умолчанию `"ru"`. */
+    language?: string;
+    /** → `SendCodeReq.regionStorageId`. По умолчанию `70`. */
+    regionStorageId?: number;
+    /** → `SendCodeReq.captcha` (если шлюз требует). */
+    captcha?: string;
+    /** → `SendCodeReq.captchaType`. */
+    captchaType?: AuthCaptchaType;
+    /** → `SendCodeReq.inviteSessionId`. */
+    inviteSessionId?: string;
+    /**
+     * Hint серверу → `SendCodeReq.preferredMethod`.
+     * Факт смотри в `onSendCode.usedMethod`.
+     */
+    preferredMethod?: VerificationMethod;
+    /**
+     * Capability клиента → `SendCodeReq.supportedMethods`.
+     * Без `MtsMobileId` сервер обычно не выберет Mobile ID.
+     */
+    supportedMethods?: VerificationMethod[];
+    /** Отмена `sendCode` / poll / `requestToken`. */
+    signal?: AbortSignal;
+};
+/** Опции {@link TorrowAuth.loginWithLink} (Telegram deep-link). */
+type TorrowAuthLoginWithLinkOptions = TorrowAuthSessionBase & {
+    /** Показать deep-link / QR (`CreateAuthSessionResp.authUrl`). */
+    onLink: (authUrl: string) => void | Promise<void>;
+    /** По умолчанию `Telegram`. */
+    accountType?: AccountType;
+    language?: string;
+    regionStorageId?: number;
+    captcha?: string;
+    inviteSessionId?: string;
+    scopes?: AuthScope[];
+    /** Интервал poll `requestToken` (мс). По умолчанию 2000. */
+    pollIntervalMs?: number;
+    /** Max wait poll (сек). Иначе TTL сессии из ответа или 180. */
+    pollTimeoutSec?: number;
+    signal?: AbortSignal;
+};
+/** Опции {@link TorrowAuth.fromTokens}: сид токенов от хоста в `tokenStorage` → connect. */
+type TorrowAuthFromTokensOptions = TorrowAuthSessionBase & {
+    accessToken: string;
+    /** Без него refresh недоступен (даже если задан `appCredentials`). */
+    refreshToken?: string;
+    /**
+     * Абсолютное истечение access (мс). Для opaque/integration keys без JWT `exp`.
+     * Приоритет **записи в snapshot**: explicit (`> 0` finite) → JWT `exp` → `undefined` (бессрочный ключ).
+     * Runtime freshness AND-ит JWT `exp`: будущий explicit TTL не оживит просроченный JWT.
+     * Opaque без JWT-формы: explicit TTL или бессрочно без TTL.
+     */
+    accessExpiresAtMs?: number;
+};
+/**
+ * Фасад аутентификации для приложений и виджетов.
+ *
+ * - {@link TorrowAuth.connect} — restore / refresh
+ * - {@link TorrowAuth.createOtpFlow} — раздельные OTP-шаги без сессии
+ * - {@link TorrowAuth.loginWithOtp} — OTP (Phone/Email, Mobile ID / classic)
+ * - {@link TorrowAuth.loginWithLink} — Telegram deep-link
+ * - {@link TorrowAuth.fromTokens} — сид токенов от хоста
+ * - {@link TorrowAuth.anonymous} — клиент без Bearer
+ */
+declare const TorrowAuth: {
+    /** Пошаговый OTP без storage, polling и refresh. */
+    readonly createOtpFlow: typeof createOtpFlow;
+    readonly connect: (options: TorrowAuthConnectOptions) => Promise<TorrowAuthResult>;
+    readonly loginWithOtp: (options: TorrowAuthLoginWithOtpOptions) => Promise<TorrowAuthResult>;
+    readonly loginWithLink: (options: TorrowAuthLoginWithLinkOptions) => Promise<TorrowAuthResult>;
+    readonly fromTokens: (options: TorrowAuthFromTokensOptions) => Promise<TorrowAuthResult>;
+    readonly anonymous: (config?: Pick<TokenSessionOptions, "baseUrl" | "fetch" | "defaultHeaders" | "userAgent">) => TorrowClient;
+};
+
+/**
+ * Опции пошагового входа без TokenStorage и пользовательской сессии.
+ *
+ * HTTP-настройки из {@link TokenSessionOptions} применяются к обоим шагам:
+ * - `baseUrl` — адрес шлюза без `/api/v1`; по умолчанию `https://torrow.net`.
+ * - `fetch` — реализация HTTP-транспорта; по умолчанию глобальный `fetch`.
+ * - `defaultHeaders` — дополнительные заголовки каждого запроса.
+ * - `userAgent` — значение заголовка `User-Agent` для диагностики сервера.
+ *
+ * Между `start` и `complete`, в том числе на разных экземплярах flow,
+ * приложение сохраняет одинаковые deviceInfo, scopes и splitTokens.
+ */
+type TorrowAuthOtpFlowOptions = Pick<TokenSessionOptions, "baseUrl" | "fetch" | "defaultHeaders" | "userAgent"> & {
+    /**
+     * Учётные данные приложения для Basic на `/api/v1/auth/*`.
+     * Если не заданы — используется {@link DEFAULT_APP_CREDENTIALS};
+     * явная пара полностью заменяет default и требует непустых clientId/clientSecret.
+     */
+    appCredentials?: AppCredentials;
+    /**
+     * Обязательное описание устройства для `TokenReq.deviceInfo` при `complete`.
+     * Требуются непустой deviceId и поддерживаемый deviceType; flow не генерирует deviceId.
+     */
+    deviceInfo: DeviceInfo;
+    /**
+     * Запрашиваемые области доступа → `TokenReq.scopes` при `complete`.
+     * Если поле отсутствует или массив пуст — `user_api` и `offline_access`.
+     */
+    scopes?: AuthScope[];
+    /**
+     * Разделение access/refresh сервером → `TokenReq.splitTokens` при `complete`.
+     * false: полные токены в JSON; используйте для Node, MCP и интеграционных ключей.
+     * true: части токенов в JSON, остальные части в HttpOnly cookies;
+     * только для браузерного приложения с настроенной передачей cookies.
+     * SDK не управляет cookies и не восстанавливает полные токены из частей.
+     * Явные true/false передаются без изменения; отсутствующее поле не отправляется.
+     */
+    splitTokens?: boolean;
+};
+/**
+ * Вход отправки кода; поля наследуются из {@link TorrowAuthLoginWithOtpOptions}.
+ * account задаёт Phone/Email и получателя; language — язык (default ru),
+ * regionStorageId — регион (default 70), captcha/captchaType — ответ и провайдер captcha,
+ * inviteSessionId — приглашение. preferredMethod — пожелание серверу,
+ * supportedMethods — способы, которые приложение умеет обработать.
+ * UI и получение captcha остаются в приложении.
+ */
+type OtpStartInput = Pick<TorrowAuthLoginWithOtpOptions, "account" | "language" | "regionStorageId" | "captcha" | "captchaType" | "inviteSessionId" | "preferredMethod" | "supportedMethods">;
+/** Опции одного HTTP-шага. */
+type OtpRequestOptions = {
+    /** Отмена текущего HTTP-шага; не отменяет независимый cleanup приложения. */
+    signal?: AbortSignal;
+};
+/**
+ * Действие приложения для продолжения входа, отдельно от серверного TokenStatus.
+ * AwaitingCode — первоначальный ввод classic OTP либо новая фаза ввода SMS-кода
+ * после fallback из Pending в той же Mobile ID auth-сессии.
+ * Pending — ожидание Mobile ID, complete вызывается без кода.
+ */
+declare enum OtpPhaseValues {
+    /** Требуется первоначальный OTP или SMS-код после Mobile ID fallback. */
+    AwaitingCode = "AwaitingCode",
+    /** Ожидание Mobile ID; следующий запрос выполняется без кода. */
+    Pending = "Pending"
+}
+/** JSON-значение фазы; принимает строковый литерал или член {@link OtpPhaseValues}. */
+type OtpPhase = `${OtpPhaseValues}`;
+/** Переносимое продолжение; приложение обеспечивает его целостность. */
+type OtpChallenge = {
+    /** Идентификатор auth-сессии из SendCodeResp; сохраняется между шагами. */
+    sessionId: string;
+    /** Тип получателя первоначального кода: Phone или Email. */
+    accountType: SendCodeAccountType;
+    /** Фактический способ подтверждения; при SMS fallback меняется на Sms. */
+    usedMethod: VerificationMethod;
+    /** Следующее действие приложения: ввод кода или ожидание без кода. */
+    phase: OtpPhase;
+    /** Локальный deadline в Unix milliseconds, без продления; не гарантирует серверный срок. TTL из SendCodeResp либо 180 секунд от начала start. */
+    expiresAtMs: number;
+    /** Подсказка длины кода из SendCodeResp; default 6 для classic Email, 4 для Phone/Mobile ID. В переносимом challenge может отсутствовать. */
+    codeLength?: number;
+    /** Интервал ожидания в секундах для Pending; default 3. SDK сам не выполняет polling. */
+    pollIntervalSeconds?: number;
+    /** Оставшиеся попытки из SendCodeResp.attemptCountToUseSession; SDK не уменьшает их. Отсутствие означает, что корректная подсказка не получена. */
+    attemptsRemaining?: number;
+    /** Время следующей отправки из SendCodeResp.nextAvailableUsageTime в Unix milliseconds; отсутствует без корректной подсказки. */
+    nextSendAtMs?: number;
+    /** Доступные способы из SendCodeResp; отсутствуют, если список отсутствовал или содержал неизвестные значения. */
+    availableMethods?: VerificationMethod[];
+};
+/** Параметры одной попытки обмена или ожидания. */
+type OtpCompleteInput = {
+    /** Переносимое продолжение; проверяется перед запросом, целостность обеспечивает приложение. */
+    challenge: OtpChallenge;
+    /** Непустой OTP в AwaitingCode; в Pending поле должно отсутствовать. */
+    code?: string;
+};
+/** Данные для явного cleanup вызывающим приложением. */
+type OtpCleanupData = {
+    /** Refresh-секрет для явного отзыва приложением; не предназначен для диагностики. */
+    refreshToken: string;
+};
+/** Причины локального отказа; HTTP и отмена пробрасываются без преобразования. */
+declare enum OtpFlowErrorCodeValues {
+    /** Некорректные опции, вход start или код для текущей фазы. */
+    InvalidArguments = "InvalidArguments",
+    /** Повреждённое, противоречивое или просроченное продолжение. */
+    InvalidChallenge = "InvalidChallenge",
+    /** Ответ не соответствует строгому контракту шага. */
+    InvalidResponse = "InvalidResponse",
+    /** Фактический способ подтверждения отсутствует или не поддерживается для аккаунта. */
+    UnsupportedMethod = "UnsupportedMethod"
+}
+/** Строковое представление безопасной причины отказа. */
+type OtpFlowErrorCode = `${OtpFlowErrorCodeValues}`;
+/** Отказ с безопасной диагностикой и отдельно доступным секретом для cleanup. */
+declare class OtpFlowError extends Error {
+    #private;
+    /** Безопасная причина локального отказа, без исходного ответа и секретов. */
+    readonly code: OtpFlowErrorCode;
+    readonly name = "OtpFlowError";
+    constructor(
+    /** Безопасная причина локального отказа, без исходного ответа и секретов. */
+    code: OtpFlowErrorCode, cleanup?: OtpCleanupData);
+    /** Секрет доступен явно; не является перечисляемым полем исключения. */
+    get cleanup(): OtpCleanupData | undefined;
+}
+/**
+ * Результат одного шага: серверный статус отдельно от фазы challenge.
+ * Pending — сервер ещё не завершил аутентификацию, следующий запрос без кода.
+ * AwaitingSmsCode — продолжение Mobile ID-сценария через SMS fallback,
+ * если аутентификацию через Mobile ID не удалось завершить. Возвращённый challenge
+ * меняет фазу Pending на AwaitingCode и метод на Sms; sessionId и deadline сохраняются.
+ * TokenReady — токены выданы; Failed — терминальный отказ без продолжения.
+ * Обычный Email/SMS OTP начинается с AwaitingCode после start,
+ * без отдельного серверного AwaitingEmailCode.
+ */
+type OtpCompleteResult = {
+    /** Сервер ещё ожидает подтверждения либо запросил SMS fallback. */
+    status: TokenStatusValues.Pending | TokenStatusValues.AwaitingSmsCode;
+    /** Продолжение с новым действием приложения и прежним deadline. */
+    challenge: OtpChallenge;
+    /** Неожиданный refresh для явного отзыва; отсутствует, если сервер его не выдал. */
+    cleanup?: OtpCleanupData;
+} | {
+    /** Терминальный отказ сервера; продолжение не возвращается. */
+    status: TokenStatusValues.Failed;
+    /** Неожиданный refresh для явного отзыва; отсутствует без refresh в ответе. */
+    cleanup?: OtpCleanupData;
+} | {
+    /** Сервер явно подтвердил выдачу токенов. */
+    status: TokenStatusValues.TokenReady;
+    /**
+     * Проверенные поля TokenResp: accessToken обязателен, refreshToken и expiration
+     * (TTL в секундах) сохраняются при наличии; splitTokens определяет полноту токенов.
+     */
+    tokens: Omit<TokenResp, "status" | "accessToken"> & {
+        /** Явный статус готовности из token-ответа. */
+        status: TokenStatusValues.TokenReady;
+        /** Непустой access token из ответа после нормализации aliases. */
+        accessToken: string;
+    };
+};
+/** Пошаговый интерфейс: каждый метод выполняет только один upstream-запрос. */
+interface OtpFlow {
+    /** Отправляет один код и возвращает переносимое продолжение без токенов. */
+    start(input: OtpStartInput, options?: OtpRequestOptions): Promise<OtpChallenge>;
+    /** Проверяет продолжение и выполняет одну попытку обмена/ожидания без сохранения. */
+    complete(input: OtpCompleteInput, options?: OtpRequestOptions): Promise<OtpCompleteResult>;
+}
+/**
+ * Создаёт OTP-flow с фиксированными настройками транспорта и token-обмена.
+ * Создание не выполняет HTTP; start и complete выполняют по одному запросу.
+ * Challenge и токены остаются у приложения, без storage, polling и refresh внутри flow.
+ * @param options Настройки HTTP, credentials приложения, устройства и выдачи токенов.
+ * @returns Независимые шаги отправки кода и завершения/ожидания аутентификации.
+ * @throws OtpFlowError При некорректных опциях устройства, scopes или splitTokens.
+ */
+declare function createOtpFlow(options: TorrowAuthOtpFlowOptions): OtpFlow;
+
+/**
+ * In-memory реализация {@link TokenStorage}.
+ *
+ * Тесты, эфемерные процессы, `TorrowAuth.fromTokens` без диска.
+ * Для Node-примеров обычно {@link FileTokenStorage}; для браузера —
+ * {@link LocalStorageTokenStorage}.
+ */
+
+/** In-memory хранилище токенов сессии. */
+declare class MemoryTokenStorage implements TokenStorage {
+    private snapshot;
+    constructor(initial?: AuthTokenSnapshot);
+    load(): Promise<AuthTokenSnapshot>;
+    save(snapshot: AuthTokenSnapshot): Promise<void>;
+}
+
+/**
+ * Persist snapshot в браузерный **`localStorage`** — реализация {@link TokenStorage}.
+ *
+ * Для виджетов / SPA (`TorrowAuth.fromTokens` / `connect`). В Node без
+ * `globalThis.localStorage` конструктор бросит. Не путать с {@link FileTokenStorage}.
+ */
+
+type LocalStorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+};
+/**
+ * Persist snapshot токенов в браузерный `localStorage` (виджет / SPA).
+ */
+declare class LocalStorageTokenStorage implements TokenStorage {
+    readonly key: string;
+    private readonly store;
+    constructor(key: string, store?: LocalStorageLike);
+    load(): Promise<AuthTokenSnapshot>;
+    save(snapshot: AuthTokenSnapshot): Promise<void>;
+}
+
+/** Сессия auth ещё не подтверждена (например Telegram до Start у бота). */
+declare class AuthSessionNotReadyError extends Error {
+    readonly name = "AuthSessionNotReadyError";
+    readonly cause?: unknown;
+    constructor(message?: string, cause?: unknown);
+}
+
+export { AppCredentials, AuthSessionNotReadyError, AuthTokenSnapshot, DEFAULT_APP_CREDENTIALS, LocalStorageTokenStorage, MemoryTokenStorage, OtpAuthHeaderMissingError, type OtpChallenge, type OtpCleanupData, OtpCodeRequestLimitExceededError, type OtpCompleteInput, type OtpCompleteResult, type OtpFlow, OtpFlowError, type OtpFlowErrorCode, OtpFlowErrorCodeValues, type OtpGetCodeContext, type OtpPhase, OtpPhaseValues, type OtpRequestOptions, type OtpSendCodeResult, type OtpStartInput, TokenSession, TokenSessionOptions, TokenSessionStatus, TokenSessionStatusListener, TokenStorage, TorrowAuth, type TorrowAuthAccount, type TorrowAuthConnectOptions, type TorrowAuthFromTokensOptions, type TorrowAuthLoginWithLinkOptions, type TorrowAuthLoginWithOtpOptions, type TorrowAuthOtpFlowOptions, type TorrowAuthResult, type TorrowAuthSessionBase };