@torrow/sdk-auth 0.6.0 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@ flowchart TD
   need[Нужен клиент] --> kind{Сценарий}
   kind -->|restore| connect["TorrowAuth.connect"]
   kind -->|OTP login| login["TorrowAuth.loginWithOtp"]
+  kind -->|раздельные OTP-запросы| flow["TorrowAuth.createOtpFlow: start / complete"]
   kind -->|Telegram deep-link| link["TorrowAuth.loginWithLink"]
   kind -->|токены от хоста| fromTok["TorrowAuth.fromTokens"]
   kind -->|без входа| anon["TorrowAuth.anonymous"]
@@ -27,6 +28,123 @@ flowchart TD
 
 ## Целевой клиентский код
 
+### Пошаговый OTP без пользовательской сессии
+
+`TorrowAuth.createOtpFlow` выполняет один `sendCode` на start и один `requestToken` на complete. Он не хранит challenge или токены, не требует TokenStorage/callbacks, не делает polling, refresh, retry или revoke. Для полного входа с callbacks и сохранением используйте `loginWithOtp`.
+
+```mermaid
+sequenceDiagram
+  actor User as Пользователь
+  participant App as Приложение
+  participant Flow as OtpFlow (@torrow/sdk-auth)
+  participant API as Torrow API
+
+  App->>Flow: createOtpFlow(options)
+  App->>Flow: start({ account, ... }, { signal })
+  Flow->>API: POST /auth/sendcode (Basic приложения)
+  API-->>Flow: SendCodeResp
+  Flow-->>App: OtpChallenge
+  Note over App,Flow: Classic — AwaitingCode, Mobile ID — Pending.<br/>Challenge не содержит токенов или OTP.
+  App->>App: Защитить и перенести challenge через JSON
+  Note over App,Flow: complete можно вызвать на новом экземпляре flow.<br/>deviceInfo, scopes и splitTokens сохраняет приложение.
+
+  loop Пока нет TokenReady / Failed и challenge не просрочен
+    alt challenge.phase = AwaitingCode
+      App->>User: Запросить OTP / SMS-код
+      User-->>App: code
+      App->>Flow: complete({ challenge, code }, { signal })
+    else challenge.phase = Pending
+      App->>App: При повторном polling дождаться интервала
+      App->>Flow: complete({ challenge }, { signal })
+    end
+    Note right of Flow: Проверить challenge до HTTP.<br/>Pending — wire code пустой.
+    Flow->>API: POST /auth/token (Basic приложения)
+    API-->>Flow: TokenResp
+    alt status = Pending
+      Flow-->>App: Pending + challenge (phase = Pending)<br/>+ cleanup, если есть refresh
+    else status = AwaitingSmsCode
+      Flow-->>App: SMS fallback той же Mobile ID сессии<br/>AwaitingSmsCode + challenge<br/>(новая phase = AwaitingCode, usedMethod = Sms)<br/>+ cleanup, если есть refresh
+    else status = TokenReady
+      Flow-->>App: TokenReady + tokens
+      App->>App: Использовать токены и решить вопрос хранения / cleanup
+    else status = Failed
+      Flow-->>App: Failed + cleanup, если есть refresh
+    end
+  end
+
+  Note over App,Flow: expiresAtMs не продлевается между шагами.<br/>Ошибки передаются приложению, скрытых повторов нет.<br/>Cleanup выполняет приложение с независимым AbortSignal.
+```
+
+```ts
+import { TorrowAuth, OtpFlowError, type OtpChallenge } from "@torrow/sdk-auth";
+import { TokenStatusValues } from "@torrow/sdk-client";
+
+const options = {
+  deviceInfo: { deviceId: "my-app-device", deviceType: "Desktop" as const },
+  scopes: ["user_api" as const],
+  splitTokens: false,
+};
+const challenge = await TorrowAuth.createOtpFlow(options).start({
+  account: { accountType: "Email", accountName: "user@example.com" },
+});
+// Между запросами приложение защищает целостность этого JSON.
+const continuation: OtpChallenge = JSON.parse(JSON.stringify(challenge));
+try {
+  const result = await TorrowAuth.createOtpFlow(options).complete(
+    { challenge: continuation, code: "123456" },
+    { signal: AbortSignal.timeout(15000) },
+  );
+  if (result.status === TokenStatusValues.TokenReady) {
+    // Использовать result.tokens.accessToken в рамках текущего запроса.
+    // Сохранение/cleanup result.tokens.refreshToken определяет приложение.
+  } else {
+    // result.cleanup?.refreshToken доступен для отдельного cleanup.
+    if ("challenge" in result) {
+      // Защитить result.challenge для следующего шага.
+    }
+  }
+} catch (error) {
+  if (error instanceof OtpFlowError) {
+    // error.code — безопасная причина; error.cleanup?.refreshToken — секрет для cleanup.
+    // Cleanup выполняет приложение с независимым AbortSignal.
+  }
+  throw error;
+}
+```
+
+| Значение | Действие приложения |
+|---|---|
+| `challenge.phase: AwaitingCode` | Для следующего шага требуется непустой код. Это первоначальный ввод при обычном OTP либо ввод SMS-кода после fallback в Mobile ID-сценарии. |
+| `challenge.phase: Pending` | Продолжается ожидание результата Mobile ID. Следующий complete вызывается без кода; wire code будет пустым. |
+| `result.status: Pending` | Сервер ещё не завершил аутентификацию. SDK возвращает challenge с фазой Pending; приложение планирует следующий запрос без кода. Возможен возврат к Pending после отправки SMS-кода. |
+| `result.status: AwaitingSmsCode` | Сервер перевёл Mobile ID-сценарий на SMS fallback, поскольку аутентификацию через Mobile ID не удалось завершить. SDK возвращает challenge с новой фазой AwaitingCode и методом Sms; приложение запрашивает SMS-код и передаёт его в следующий complete. |
+| `result.status: Failed` | Текущая попытка аутентификации завершилась отказом. Challenge для продолжения не возвращается; новый вход требует отдельного start. |
+| `result.status: TokenReady` | Аутентификация завершена, токены получены и проверены SDK. Продолжение не требуется; SDK не сохраняет токены. |
+
+`result.status` отражает серверный `TokenStatus`, а `challenge.phase` определяет следующий шаг приложения. Переход при fallback: ожидание Mobile ID (`Pending`) → серверный `AwaitingSmsCode` → ввод SMS-кода (новая фаза `AwaitingCode`, метод `Sms`). Это продолжение той же auth-сессии с новым способом подтверждения, а не продолжение фазы AwaitingCode: sessionId и deadline сохраняются, фаза меняется. При обычном Email/SMS/FlashCall/TelegramGateway-входе `start` сразу возвращает `AwaitingCode` с фактическим `usedMethod`: ввод кода требуется до первого `complete`. Статуса `AwaitingEmailCode` в текущем API нет. Предпочтительный метод `preferredMethod` является пожеланием; фактический метод определяет сервер в `usedMethod`.
+
+Опции flow: `baseUrl`, `fetch`, `defaultHeaders`, `userAgent`, `appCredentials`, обязательный `deviceInfo`, `scopes`, `splitTokens`. SDK-default Basic и scopes такие же, как в сессии; неуказанный splitTokens не отправляется. Start принимает язык (default ru), регион (70), captcha/type, invite session и preferred/supported methods. Email/UnknownMethod поддерживается; неизвестный метод отклоняется.
+
+**Когда использовать `splitTokens`.** Это параметр `POST /api/v1/auth/token`, который обрабатывает сервер: SDK передаёт флаг и возвращает полученные поля токенов без самостоятельного разделения или восстановления.
+
+| Значение | Поведение сервера и сценарий |
+|---|---|
+| `false` | Возвращает полные access/refresh в JSON и удаляет cookies ранее разделённых токенов. Используйте для Node, MCP и приложений, которым нужны полные токены для API-вызовов, выпуска интеграционного ключа и cleanup. |
+| `true` | При наличии access token разделяет access/refresh: одну часть каждого токена помещает в HttpOnly cookies, другую возвращает в JSON. Используйте только для браузерного приложения, специально настроенного на этот режим авторизации. При Mobile ID без готовых токенов разделение пропускается. |
+| Не задано | Flow не отправляет поле. В текущей реализации шлюза отсутствующий boolean имеет значение `false`; для явно выбранного режима полных токенов задавайте `false`. |
+
+В режиме `true` поля `result.tokens` содержат части токенов, а не самостоятельные полные Bearer/refresh-токены. Последующие запросы должны передавать необходимые части и cookies для восстановления токенов шлюзом. Приложение обеспечивает работу с cookies, включая `credentials` у `fetch` и разрешения CORS при запросах между origin. SDK не добавляет cookie jar или управление cookies; стандартный Node `fetch` не сохраняет и не передаёт их автоматически между запросами. Поэтому Node-примеры задают `splitTokens: false`. Тесты SDK проверяют передачу обоих значений в HTTP-тело, а не серверное разделение или браузерную работу cookies.
+
+Challenge: `sessionId`, `accountType`, `usedMethod`, `phase`, `expiresAtMs` и проверенные подсказки `codeLength`, `pollIntervalSeconds`, `attemptsRemaining`, `nextSendAtMs`, `availableMethods`. Даты — Unix milliseconds, пригодные для JSON. Токенов/OTP в challenge нет. Проверка структуры SDK не заменяет проверку целостности приложением. Между шагами приложение сохраняет тот же deviceInfo, scopes и splitTokens; flow не связывает их криптографически с challenge.
+
+Срок отсчитывается от начала start: серверный sessionLifeTimeInSeconds либо локальные 180 секунд при отсутствии/null. Некорректный TTL отклоняется. Локальный срок не гарантирует действие сессии на сервере и не продлевается. Ограничение 600 секунд относится к MCP. Polling hint default — 3 секунды. Некорректные необязательные подсказки пропускаются; длина кода — корректная серверная либо Email 6, Phone/SMS fallback 4. Число попыток не уменьшается самостоятельно.
+
+Перед проверкой token-ответа нормализуются существующие aliases: AccessToken/access_token, RefreshToken/refresh_token, Expiration/expires_in, Status. Приоритет: имя OpenAPI → PascalCase → snake_case по первому значению, отличному от null/undefined. Flow требует явный известный status и непустой access token при TokenReady. Старые методы сохраняют ответы без status, только с refresh token и прежние callback-поля через внутреннюю legacy-адаптацию общей реализации.
+
+`OtpFlowError.code`: InvalidArguments, InvalidChallenge, InvalidResponse, UnsupportedMethod. Getter `error.cleanup` передаёт обнаруженный refresh даже при повреждённом ответе; он не включён в обычную сериализацию/диагностику ошибки. Валидные незавершённые/Failed ответы передают refresh через result.cleanup. HTTP-ошибки остаются TorrowHttpError, сеть и отмена пробрасываются. Потеря ответа не разрешает слепой повтор. Signal передаётся до fetch на обоих шагах; некорректный/просроченный challenge отклоняется до upstream.
+
+Примеры: auth-otp-flow.ts (JSON и новый flow), auth-otp-flow-mobile-id.ts (polling приложения и SMS fallback). Выпуск интеграционного ключа, подтверждение identity и cleanup выполняются приложением.
+
 Общая база `{ tokenStorage, deviceInfo }` (+ опционально `appCredentials`) у режимов с сессией.
 Без `appCredentials` — **`DEFAULT_APP_CREDENTIALS`** (`sdk.torrow.net`). Своя пара перекрывает дефолт.
 

package/dist/index.d.ts

@@ -1,51 +1,93 @@
-import { T as TokenStorage, A as AuthTokenSnapshot, a as TokenSessionOptions, b as TokenSessionStatus, c as TokenSessionStatusListener } from './types-LCuPy3dY.js';
-export { d as AppCredentials, D as DEFAULT_APP_CREDENTIALS, R as RefreshFailureAction } from './types-LCuPy3dY.js';
-import { TorrowClient, DeviceInfo, TokenResp, AuthScope, VerificationMethod, SendCodeAccountType, AuthCaptchaType, AccountType } from '@torrow/sdk-client';
+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. */
 
 /**
- * In-memory реализация {@link TokenStorage}.
+ * Дефолтные app credentials SDK для `/api/v1/auth/*`, если {@link TokenSessionOptions.appCredentials}
+ * не передан. Своё приложение может переопределить явной парой.
  *
- * Тесты, эфемерные процессы, `TorrowAuth.fromTokens` без диска.
- * Для Node-примеров обычно {@link FileTokenStorage}; для браузера —
- * {@link LocalStorageTokenStorage}.
+ * Публикуется в npm `@torrow/sdk-auth` (inspectable); свой prod-secret — только override / BFF.
  */
-
-/** In-memory хранилище токенов сессии. */
-declare class MemoryTokenStorage implements TokenStorage {
-    private snapshot;
-    constructor(initial?: AuthTokenSnapshot);
-    load(): Promise<AuthTokenSnapshot>;
-    save(snapshot: AuthTokenSnapshot): Promise<void>;
-}
+declare const DEFAULT_APP_CREDENTIALS: AppCredentials;
 
 /**
- * Persist snapshot в браузерный **`localStorage`** — реализация {@link TokenStorage}.
+ * Внутренний оркестратор OTP-логина (не публичный export целиком; типы UI — да).
  *
- * Для виджетов / SPA (`TorrowAuth.fromTokens` / `connect`). В Node без
- * `globalThis.localStorage` конструктор бросит. Не путать с {@link FileTokenStorage}.
+ * **`sendCode`** → ветка по **`usedMethod`** (Mobile ID poll | classic код) →
+ * **`TokenResp`**. UI снаружи: **`onSendCode`** + **`getCode`**.
+ * IMAP / stdin / env — в app / `examples/node/_shared`, не здесь.
+ *
+ * Вызывается из `TorrowAuth.loginWithOtp`; Mobile ID — `mobile-id.ts`.
  */
 
-type LocalStorageLike = {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem?(key: string): void;
+/**
+ * Аргумент **`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;
 };
 /**
- * Persist snapshot токенов в браузерный `localStorage` (виджет / SPA).
+ * Аргумент **`getCode`**: только когда нужны цифры (stdin / UI / IMAP снаружи).
+ *
+ * UI-экран уже выбран в **`onSendCode`** (`usedMethod`). Здесь — собрать код
+ * (длина из `codeLength`). На happy-path Mobile ID (push) **`getCode` не вызывается**;
+ * SMS-fallback после poll — тот же колбэк, без отдельного `reason`.
+ *
+ * `accountName` / `accountType` не дублируются — они в options и в `onSendCode`.
  */
-declare class LocalStorageTokenStorage implements TokenStorage {
-    readonly key: string;
-    private readonly store;
-    constructor(key: string, store?: LocalStorageLike);
-    load(): Promise<AuthTokenSnapshot>;
-    save(snapshot: AuthTokenSnapshot): Promise<void>;
+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);
 }
-
-/** Сессия auth ещё не подтверждена (например Telegram до Start у бота). */
-declare class AuthSessionNotReadyError extends Error {
-    readonly name = "AuthSessionNotReadyError";
-    readonly cause?: unknown;
-    constructor(message?: string, cause?: unknown);
+/** Нет Basic на `/auth/token` (`AUTH_HEADER_MISSING`). */
+declare class OtpAuthHeaderMissingError extends Error {
+    readonly name = "OtpAuthHeaderMissingError";
+    readonly body: unknown;
+    readonly systemMessage?: string;
+    constructor(body: unknown);
 }
 
 /**
@@ -144,88 +186,10 @@ declare class TokenSession {
     private persist;
 }
 
-/**
- * Внутренний оркестратор 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);
-}
-
 /**
  * Публичный фасад аутентификации **`TorrowAuth`**.
  *
- * Точка входа приложения: `connect` / `loginWithOtp` / `loginWithLink` /
+ * Точка входа приложения: `createOtpFlow` / `connect` / `loginWithOtp` / `loginWithLink` /
  * `fromTokens` / `anonymous`. Возвращает {@link TorrowAuthResult}
  * (`{ client, session }`), кроме `anonymous` (только `TorrowClient`).
  *
@@ -334,12 +298,15 @@ type TorrowAuthFromTokensOptions = TorrowAuthSessionBase & {
  * Фасад аутентификации для приложений и виджетов.
  *
  * - {@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>;
@@ -347,4 +314,230 @@ declare const TorrowAuth: {
     readonly anonymous: (config?: Pick<TokenSessionOptions, "baseUrl" | "fetch" | "defaultHeaders" | "userAgent">) => TorrowClient;
 };
 
-export { AuthSessionNotReadyError, AuthTokenSnapshot, LocalStorageTokenStorage, MemoryTokenStorage, OtpAuthHeaderMissingError, OtpCodeRequestLimitExceededError, type OtpGetCodeContext, type OtpSendCodeResult, TokenSession, TokenSessionOptions, TokenSessionStatus, TokenSessionStatusListener, TokenStorage, TorrowAuth, type TorrowAuthAccount, type TorrowAuthConnectOptions, type TorrowAuthFromTokensOptions, type TorrowAuthLoginWithLinkOptions, type TorrowAuthLoginWithOtpOptions, type TorrowAuthResult, type TorrowAuthSessionBase };
+/**
+ * Опции пошагового входа без 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 };