itd-api

Тема

itd-api / AuthResource

Interface: AuthResource ​

Defined in: resources/auth.ts:157

Авторизация, сессии и пароли.

Доступна как itd.auth.

Extends ​

  • BaseResource

Methods ​

approveQrLogin() ​

ts
approveQrLogin(input, options?): Promise<void>;

Defined in: resources/auth.ts:366

Подтверждает вход по QR-коду: показавшее код устройство получит access token.

Осмысленно после scanQrLogin — человек должен увидеть, что подтверждает. Требует мобильную сессию, как и scanQrLogin().

Parameters ​

input ​

QrLoginSecrets

options? ​

RequestOptions = {}

Returns ​

Promise<void>

captchaPage() ​

ts
captchaPage(options?): Promise<CaptchaPage>;

Defined in: resources/auth.ts:237

Узнаёт активного провайдера капчи вместе с адресом страницы виджета.

То же, что captchaProvider, плюс url — готовая страница на домене итд.com, где ключ виджета действителен. Пригодится встроенному браузеру: открыть её и забрать токен, ничего не собирая самому.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<CaptchaPage>

captchaProvider() ​

ts
captchaProvider(options?): Promise<CaptchaProvider>;

Defined in: resources/auth.ts:221

Узнаёт активного провайдера капчи и поле токена.

Сервер может переключить провайдера или переименовать поле без выпуска новой версии SDK. Автоматическому входу этот вызов не нужен — клиент делает его сам.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<CaptchaProvider>

changePassword() ​

ts
changePassword(input, options?): Promise<void>;

Defined in: resources/auth.ts:654

Меняет пароль. Требует действующей сессии.

При неверном текущем пароле сервер отвечает ACCOUNT_CURRENT_PASSWORD_INCORRECT.

Parameters ​

input ​
currentPassword ​

string

newPassword ​

string

options? ​

RequestOptions = {}

Returns ​

Promise<void>

Example ​

ts
await itd.auth.changePassword({ currentPassword, newPassword });

check() ​

ts
check(options?): Promise<AuthState>;

Defined in: resources/auth.ts:208

Проверяет состояние авторизации и возвращает текущего пользователя.

Без авторизации возвращает authenticated: false и user: null.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<AuthState>

claimQrLogin() ​

ts
claimQrLogin(input, options?): Promise<QrLoginClaim>;

Defined in: resources/auth.ts:271

Проверяет QR-сессию и завершает вход после подтверждения на другом устройстве.

До подтверждения возвращает промежуточный статус. Токен капчи добывается, только когда сервер о ней попросил — статусом captcha_required на прошлой проверке, — либо когда передан в сам вызов. Полученный accessToken автоматически сохраняется в клиенте.

Parameters ​

input ​

QrLoginClaimInput

options? ​

RequestOptions = {}

Returns ​

Promise<QrLoginClaim>

forgotPassword() ​

ts
forgotPassword(input, options?): Promise<string>;

Defined in: resources/auth.ts:587

Запрашивает письмо с кодом для сброса пароля.

Parameters ​

input ​

ForgotPasswordInput

options? ​

RequestOptions = {}

Returns ​

Promise<string>

flowToken, который нужно передать в resetPassword

hasRefreshSession() ​

ts
hasRefreshSession(): Promise<boolean>;

Defined in: resources/auth.ts:549

Есть ли признак живой сессии обновления.

Проверяет cookie is_auth, которую сервер ставит рядом с refresh-токеном, а также refresh-токен, переданный строкой. Позволяет не дёргать API у неавторизованного пользователя. В браузере всегда true: cookie ведёт сама среда, и прочитать её из JS нельзя.

Читает TokenStorage, поэтому результат верен и до первого запроса.

Returns ​

Promise<boolean>

Example ​

ts
if (await itd.auth.hasRefreshSession()) await itd.auth.refresh();
else redirectToLogin();

logout() ​

ts
logout(options?): Promise<void>;

Defined in: resources/auth.ts:554

Завершает текущую сессию на сервере и очищает локальную.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<void>

logoutAll() ​

ts
logoutAll(options?): Promise<void>;

Defined in: resources/auth.ts:572

Завершает все сессии пользователя и очищает локальную.

Собран из двух запросов, потому что единого эндпоинта на сервере нет: POST /api/v1/auth/logout-all отвечает 404. Сначала отзываются все прочие сессии (DELETE /api/v1/auth/sessions), затем завершается текущая — в обратном порядке отзывать было бы уже нечем.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<void>

refresh() ​

ts
refresh(): Promise<string>;

Defined in: resources/auth.ts:529

Обновляет токен доступа.

Параллельные вызовы объединяются в один сетевой запрос. При включённом autoRefresh вызывать вручную обычно не нужно.

Returns ​

Promise<string>

rejectQrLogin() ​

ts
rejectQrLogin(input, options?): Promise<void>;

Defined in: resources/auth.ts:378

Отклоняет вход по QR-коду: показавшее код устройство получит статус rejected. Требует мобильную сессию, как и scanQrLogin().

Parameters ​

input ​

QrLoginSecrets

options? ​

RequestOptions = {}

Returns ​

Promise<void>

resendOtp() ​

ts
resendOtp(input, options?): Promise<void>;

Defined in: resources/auth.ts:462

Отправляет код подтверждения повторно.

Parameters ​

input ​
email ​

string

flowToken ​

string

options? ​

RequestOptions = {}

Returns ​

Promise<void>

resetPassword() ​

ts
resetPassword(input, options?): Promise<void>;

Defined in: resources/auth.ts:603

Устанавливает новый пароль по коду из письма.

Сервер ждёт все четыре поля сразу — email, otp, flowToken и newPassword; при нехватке любого отвечает 422.

Parameters ​

input ​

ResetPasswordInput

options? ​

RequestOptions = {}

Returns ​

Promise<void>

resetPasswordWithOtp() ​

ts
resetPasswordWithOtp(input, options?): Promise<void>;

Defined in: resources/auth.ts:629

Полный сброс пароля с кодом из письма.

Тот же приём, что и signInWithOtp: код запрашивается функцией getOtp, остальное библиотека делает сама.

Parameters ​

input ​

ForgotPasswordInput & object

options? ​

RequestOptions = {}

Returns ​

Promise<void>

Example ​

ts
await itd.auth.resetPasswordWithOtp({
  email,
  captcha: { type: provider, token, field },
  newPassword,
  getOtp: () => rl.question('Код из письма: '),
});

revokeOtherSessions() ​

ts
revokeOtherSessions(options?): Promise<void>;

Defined in: resources/auth.ts:682

Завершает все сессии, кроме текущей.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<void>

revokeSession() ​

ts
revokeSession(sessionId, options?): Promise<void>;

Defined in: resources/auth.ts:674

Завершает указанную сессию.

Parameters ​

sessionId ​

string

options? ​

RequestOptions = {}

Returns ​

Promise<void>

scanQrLogin() ​

ts
scanQrLogin(input, options?): Promise<QrLoginTarget>;

Defined in: resources/auth.ts:352

Отмечает QR-код отсканированным и узнаёт, кого впускают.

Обратная сторона QR-входа: этот и два соседних метода вызывает устройство, где сессия уже есть. Показывающая сторона увидит статус scanned, но вход ещё не состоится — его завершают approveQrLogin или rejectQrLogin.

Сервер принимает только сессию, созданную мобильным клиентом. Обычный web access token отклоняется с кодом QR_APPROVER_NOT_ALLOWED, даже если добавить мобильные заголовки уже после выдачи токена.

Parameters ​

input ​

QrLoginSecrets

секреты из отсканированного кода — см. QrLoginSecrets

options? ​

RequestOptions = {}

Returns ​

Promise<QrLoginTarget>

описание устройства, которое просит вход

sessions() ​

ts
sessions(options?): Promise<Session[]>;

Defined in: resources/auth.ts:666

Загружает список активных сессий. У текущей поле isCurrent равно true.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<Session[]>

signIn() ​

ts
signIn(credentials, options?): Promise<SignInResult>;

Defined in: resources/auth.ts:412

Выполняет вход.

Если сервер потребовал код подтверждения, вернётся status: 'otp_required' — тогда продолжайте через verifyOtp либо воспользуйтесь signInWithOtp.

При успешном входе токен сохраняется в клиенте автоматически.

Parameters ​

credentials ​

CredentialsWithCaptcha

email, пароль и токен капчи — см. CredentialsWithCaptcha

options? ​

RequestOptions = {}

Returns ​

Promise<SignInResult>

signInWithOtp() ​

ts
signInWithOtp(input, options?): Promise<string>;

Defined in: resources/auth.ts:493

Полный вход с подтверждением по коду.

Удобно для скриптов и ботов: код запрашивается функцией getOtp, а всё остальное библиотека делает сама.

Parameters ​

input ​

Credentials & object & object

options? ​

RequestOptions = {}

Returns ​

Promise<string>

Example ​

ts
import { createInterface } from 'node:readline/promises';

const rl = createInterface({ input: process.stdin, output: process.stdout });

const token = await itd.auth.signInWithOtp({
  email, password,
  getOtp: () => rl.question('Код из письма: '),
});

signOut() ​

ts
signOut(): Promise<void>;

Defined in: resources/auth.ts:578

Забывает сессию локально, не обращаясь к серверу.

Returns ​

Promise<void>

signUp() ​

ts
signUp(credentials, options?): Promise<string>;

Defined in: resources/auth.ts:391

Регистрирует аккаунт и запускает подтверждение по коду.

Parameters ​

credentials ​

CredentialsWithCaptcha

options? ​

RequestOptions = {}

Returns ​

Promise<string>

flowToken, который нужно передать в verifyOtp

startQrLogin() ​

ts
startQrLogin(options?): Promise<QrLoginStart>;

Defined in: resources/auth.ts:247

Создаёт короткоживущую сессию QR-входа.

Parameters ​

options? ​

RequestOptions = {}

Returns ​

Promise<QrLoginStart>

streamQrLogin() ​

ts
streamQrLogin(
   input, 
   onEvent, 
options?): Promise<void>;

Defined in: resources/auth.ts:310

Слушает состояния QR-входа до закрытия ответа или отмены signal.

Событие approved означает, что подтверждение завершено: после него вызовите claimQrLogin, чтобы получить и сохранить access token.

Parameters ​

input ​

QrLoginStreamInput

onEvent ​

QrLoginStreamListener

options? ​

QrLoginStreamOptions = {}

Returns ​

Promise<void>

verifyOtp() ​

ts
verifyOtp(input, options?): Promise<string>;

Defined in: resources/auth.ts:442

Подтверждает вход кодом из письма.

Полученный токен сохраняется в клиенте автоматически.

Parameters ​

input ​

Credentials & object

options? ​

RequestOptions = {}

Returns ​

Promise<string>

Документация itd-api

MIT License