itd-api 0.0.1 → 0.0.3

package/README.md

@@ -37,7 +37,7 @@ for await (const post of itd.posts.iterate({ tab: FeedTab.Following })) {
 import { ItdClient, FileTokenStorage } from 'itd-api/node';
 
 const itd = new ItdClient({
-  auth: { email, password },
+  auth: { email, password, getTurnstileToken },   // вход требует капчи, см. ниже
   storage: new FileTokenStorage('./.itd-session.json'),
 });
 
@@ -55,7 +55,7 @@ await itd.posts.create((p) => p.content('привет').attach('./photo.jpg'));
 ```ts
 new ItdClient({ auth: '<accessToken>' });                    // разовый вызов
 new ItdClient({ auth: { accessToken, refreshToken } });      // восстановить сессию
-new ItdClient({ auth: { email, password } });                // войти самому
+new ItdClient({ auth: { email, password, getTurnstileToken } });  // войти самому
 new ItdClient({ auth: { getToken: () => vault.read() } });   // токен извне
 ```
 
@@ -65,6 +65,31 @@ new ItdClient({ auth: { getToken: () => vault.read() } });   // токен из
 
 Отключить автоматику: `autoRefresh: false`, дальше `await itd.auth.refresh()` вручную.
 
+### Капча обязательна при входе
+
+`signIn`, `signUp` и `forgotPassword` требуют токен Cloudflare Turnstile. Полностью
+автоматического входа по логину и паролю поэтому не бывает: капчу должен решить кто-то
+снаружи, а библиотека принимает готовый токен.
+
+```ts
+import { TURNSTILE_SITE_KEY } from 'itd-api';
+
+// в браузере — виджет Turnstile с этим ключом
+turnstile.render('#captcha', {
+  sitekey: TURNSTILE_SITE_KEY,
+  callback: (turnstileToken) => itd.auth.signIn({ email, password, turnstileToken }),
+});
+```
+
+Токен одноразовый и живёт несколько минут. Долгоживущему боту передавайте не строку,
+а источник — он спрашивается заново перед каждой попыткой входа:
+
+```ts
+new ItdClient({
+  auth: { email, password, getTurnstileToken: () => captchaSolver.solve() },
+});
+```
+
 ### Вход с кодом из письма
 
 ```ts
@@ -73,7 +98,18 @@ import { createInterface } from 'node:readline/promises';
 const rl = createInterface({ input: process.stdin, output: process.stdout });
 
 await itd.auth.signInWithOtp({
-  email, password,
+  email, password, turnstileToken,
+  getOtp: () => rl.question('Код из письма: '),
+});
+```
+
+### Сброс пароля
+
+Идёт тем же потоком с кодом: `forgotPassword` возвращает `flowToken`, письмо приносит код.
+
+```ts
+await itd.auth.resetPasswordWithOtp({
+  email, turnstileToken, newPassword,
   getOtp: () => rl.question('Код из письма: '),
 });
 ```
@@ -87,9 +123,24 @@ await itd.auth.signInWithOtp({
 | `FileTokenStorage` | `itd-api/node` | Node, Bun, Deno |
 | `createTokenStorage({ get, set, clear })` | `itd-api` | своё: Redis, БД, AsyncStorage |
 
-Refresh-токен приходит в cookie, а `fetch` вне браузера их не хранит — библиотека ведёт
-собственный cookie-jar и сохраняет его вместе с сессией. В браузере используется
-`credentials: 'include'`, в React Native cookie ведёт нативный слой.
+Refresh-токен приходит в cookie `refresh_token`, а `fetch` вне браузера их не хранит —
+библиотека ведёт собственный cookie-jar и сохраняет его вместе с сессией. В браузере
+используется `credentials: 'include'`, в React Native cookie ведёт нативный слой.
+
+Токен можно передать и строкой (`auth: { accessToken, refreshToken }`) — вне браузера
+библиотека сама подставит его нужной cookie. В браузере так не выйдет: настоящая cookie
+помечена `HttpOnly`, и из JS её не выставить.
+
+Сервер выдаёт при каждом обновлении **новый** refresh-токен взамен прежнего, поэтому
+сохранять сессию нужно после обновления, а не один раз при входе:
+
+```ts
+itd.on('tokens', async () => saveSomewhere(await itd.getSession()));
+```
+
+Вместе с сессией хранится `deviceId` — идентификатор устройства из заголовка `X-Device-Id`.
+Сервер различает по нему записи в списке сессий, поэтому при постоянном хранилище он
+переживает перезапуск, а бот не плодит по новой сессии на каждый старт.
 
 ---