itd-api 0.1.0 → 0.3.0

package/guides/realtime/README.md

@@ -1,109 +0,0 @@
-# Уведомления и realtime
-
-`itd.realtime()` открывает поток новых уведомлений:
-
-```ts
-import { formatNotificationText, resolveNotificationUrl } from 'itd-api';
-
-const stream = itd.realtime();
-
-stream.on('notification', ({ notification, sound }) => {
-  console.log(sound ? '🔔' : '🔕');
-  console.log(formatNotificationText(notification));
-  console.log(resolveNotificationUrl(notification));
-});
-
-await stream.connect();
-```
-
-## REST и поток
-
-Уведомления из `itd.notifications.list()` и realtime приведены к общей форме, поэтому их
-можно хранить в одном массиве:
-
-```ts
-const history = await itd.notifications.list({ limit: 20 });
-
-stream.on('notification', ({ notification }) => {
-  history.items.unshift(notification);
-});
-```
-
-Сервер использует короткие типы вроде `like`, `comment` и `repost`. Библиотека приводит
-их к однозначным `post_reaction`, `post_comment`, `post_repost`, сохраняя исходное значение
-в `rawType`, а исходный объект — в `raw`.
-
-`resolveNotificationUrl()` учитывает смысл идентификаторов конкретного типа и строит ссылку
-на профиль, пост или комментарий.
-
-## Переподключение
-
-Поток самостоятельно обрабатывает:
-
-- обрыв соединения;
-- обновление access token;
-- восстановление сети;
-- возвращение браузерной вкладки из фона;
-- отсутствие keep-alive дольше `idleTimeout`.
-
-По умолчанию используются задержки `[1, 2, 4, 8, 16, 30]` секунд с джиттером ±30% и не
-более 15 последовательных попыток. Сервер обычно отправляет `: ping` каждые 15 секунд,
-а стандартный `idleTimeout` равен 90 секундам.
-
-Состояние можно отслеживать:
-
-```ts
-stream.on('status', (status) => {
-  console.log(status); // connecting, connected, reconnecting, disconnected, error
-});
-```
-
-Завершение:
-
-```ts
-stream.disconnect();
-await itd.close();
-```
-
-## Счётчик непрочитанных
-
-Сервер практически не присылает отдельное событие изменения счётчика. Получите начальное
-значение через REST и обновляйте локально:
-
-```ts
-let unread = await itd.notifications.count();
-
-stream.on('notification', () => {
-  unread += 1;
-});
-```
-
-После массовой отметки о прочтении лучше снова запросить актуальное значение.
-
-## Polling fallback
-
-В средах без потокового чтения ответа, например в некоторых версиях React Native, realtime
-автоматически переключается на периодический опрос. Интервал настраивается через
-`pollInterval`.
-
-Можно выбрать транспорт явно:
-
-```ts
-const stream = itd.realtime({
-  transport: 'poll',
-  pollInterval: 5_000,
-});
-```
-
-## Несколько аккаунтов
-
-Каждый вызов `itd.realtime()` держит собственное соединение. Для десяти аккаунтов это десять
-SSE-соединений, поэтому открывайте поток только там, где он действительно нужен.
-
-## Запускаемый пример
-
-```bash
-ITD_TOKEN=<accessToken> node guides/realtime/examples/notifications.mjs
-```
-
-Исходник: [`examples/notifications.mjs`](./examples/notifications.mjs).

package/guides/realtime/examples/notifications.mjs

@@ -1,62 +0,0 @@
-/**
- * Уведомления в реальном времени.
- *
- * Запуск:
- *   ITD_TOKEN=<ваш accessToken> node guides/realtime/examples/notifications.mjs
- *
- * Соединение держится само: обрывы, обновление токена и повторные попытки библиотека
- * берёт на себя. Завершение — Ctrl+C.
- */
-
-import { ItdClient, formatNotificationText, resolveNotificationUrl } from 'itd-api';
-
-const itd = new ItdClient({ auth: process.env.ITD_TOKEN });
-
-// Сначала — то, что уже накопилось.
-const history = await itd.notifications.list({ limit: 5 });
-
-console.log(`Непрочитанных: ${await itd.notifications.count()}`);
-console.log('\nПоследние уведомления:');
-
-for (const notification of history.items) {
-  const mark = notification.isRead ? ' ' : '•';
-  console.log(`${mark} ${formatNotificationText(notification)}`);
-  console.log(`  → ${resolveNotificationUrl(notification)}`);
-}
-
-// Теперь поток новых.
-const stream = itd.realtime();
-
-stream.on('notification', ({ notification, sound }) => {
-  console.log(`\n${sound ? '🔔' : '🔕'} ${formatNotificationText(notification)}`);
-  console.log(`   → ${resolveNotificationUrl(notification)}`);
-
-  // Объекты из списка и из потока имеют одинаковую форму — их можно складывать вместе.
-  history.items.unshift(notification);
-});
-
-// Счётчик непрочитанных сервер по потоку не присылает — ведём его сами.
-let unread = await itd.notifications.count();
-
-stream.on('notification', () => {
-  unread += 1;
-  console.log(`   непрочитанных: ${unread}`);
-});
-
-stream.on('ready', ({ userId }) => console.log(`[поток подтвердил получателя ${userId}]`));
-stream.on('status', (status) => console.log(`[соединение: ${status}]`));
-stream.on('reconnect', ({ attempt, delay }) => {
-  console.log(`[переподключение №${attempt} через ${delay} мс]`);
-});
-stream.on('giveup', () => {
-  console.error('[попытки исчерпаны, соединение восстановится только вручную]');
-});
-
-await stream.connect();
-console.log(`\nЖдём события (транспорт: ${stream.transport}). Ctrl+C для выхода.`);
-
-process.on('SIGINT', () => {
-  stream.disconnect();
-  console.log('\nОтключено');
-  process.exit(0);
-});

package/guides/reference/README.md

@@ -1,67 +0,0 @@
-# Справочник API
-
-Техническое описание всех методов и типов `itd-api`. В отличие от [руководств](../README.md),
-здесь нет сценариев и рабочих примеров — только сигнатуры, параметры и возвращаемые типы,
-разбитые по категориям.
-
-## Ресурсы клиента
-
-| Категория | Доступ | О чём |
-|---|---|---|
-| [Клиент](./client.md) | `new ItdClient()` | конструктор, `request()`, `use()`, сервисы, события, `realtime()`, `close()` |
-| [Авторизация](./auth.md) | `itd.auth` | вход, регистрация, OTP, пароли, OAuth, сессии |
-| [Пользователи](./users.md) | `itd.users` | профили, подписки, блокировки, приватность, значки |
-| [Посты](./posts.md) | `itd.posts` | лента, публикация, реакции, репосты, опросы, комментарии к постам |
-| [Комментарии](./comments.md) | `itd.comments` | ответы на комментарии и действия над ними |
-| [Уведомления](./notifications.md) | `itd.notifications` | список, счётчик, отметки о прочтении, настройки |
-| [Файлы](./files.md) | `itd.files` | загрузка и удаление медиа |
-| [Поиск и обнаружение](./discovery.md) | `itd.search`, `itd.hashtags` | глобальный поиск, хэштеги, тренды, рекомендации, кланы, портал |
-| [Подписка](./subscription.md) | `itd.subscription` | состояние премиума, автопродление, способы оплаты |
-| [Верификация](./verification.md) | `itd.verification` | статус и подача заявки |
-| [Жалобы](./reports.md) | `itd.reports` | жалобы на контент и пользователей |
-| [Платформа](./platform.md) | `itd.platform` | журнал изменений, анонсы, портал, статус сервисов |
-| [Realtime](./realtime.md) | `itd.realtime()` | поток уведомлений, события, транспорт, переподключение |
-
-## Несколько аккаунтов
-
-| Категория | Доступ | О чём |
-|---|---|---|
-| [Аккаунты](./accounts.md) | `new ItdAccounts()` | контейнер именованных клиентов с общим хранилищем |
-
-## Справочники типов
-
-| Файл | О чём |
-|---|---|
-| [Модели данных](./models.md) | `Post`, `Comment`, `Profile`, `Notification`, `Attachment` и остальные ответы API |
-| [Перечисления](./enums.md) | `FeedTab`, `SpanType`, `NotificationType`, `ReportReason` и прочие |
-| [Ошибки](./errors.md) | иерархия `ItdError`, коды `ItdErrorCode`, функции-предикаты |
-| [Билдеры](./builders.md) | `post()`, `comment()`, `poll()`, `report()`, `markup()`, `renderSpans()` |
-| [Пагинация](./pagination.md) | `Page<T>`, `Paginator<T>`, три схемы под одним `for await` |
-
-## Общие соглашения
-
-**`RequestOptions` в каждом методе.** Почти все методы ресурсов принимают необязательный
-последний аргумент `options: RequestOptions` — он не повторяется в сигнатурах ниже:
-
-```ts
-interface RequestOptions {
-  signal?: AbortSignal;                  // отмена запроса
-  timeout?: number;                      // таймаут только этого запроса, мс
-  headers?: Record<string, string>;      // дополнительные заголовки
-  retry?: RetryOptions | false;          // повторы только этого запроса
-}
-```
-
-**`UserRef` против `UserId`.** `UserRef` — это UUID **или** имя пользователя: подходят оба
-(`itd.users.get('durov')` и `itd.users.get('9f1c…')`). `UserId` — строго UUID; имя
-пользователя там не работает (например, `wallRecipientId`).
-
-**Даты.** Все поля дат — строки ISO-8601 (`IsoDate`). Библиотека не превращает их в `Date`;
-для разбора есть [`toDate()`](./models.md#вспомогательные-функции).
-
-**Пагинация.** Методы-списки идут парами: `list()`/`comments()`/… возвращают одну
-[`Page<T>`](./pagination.md), а `iterate()`/`iterateComments()`/… — [`Paginator<T>`](./pagination.md)
-для `for await`. Подробнее — в [пагинации](./pagination.md).
-
-**Снятие обёртки.** Сервер оборачивает ответы в `{ data: … }`; библиотека снимает обёртку
-сама. Чтобы получить тело как есть, используйте `itd.request({ …, raw: true })`.

package/guides/reference/accounts.md

@@ -1,101 +0,0 @@
-# Аккаунты — `ItdAccounts`
-
-Контейнер именованных `ItdClient`: у каждого аккаунта свой токен, cookie и `deviceId`,
-а сессии всех складываются в одно хранилище (`MultiTokenStorage`). Имя аккаунта выбираете вы;
-сервер о нём ничего не знает. Полное руководство — [Несколько аккаунтов](../multi-accounts/README.md).
-
-```ts
-new ItdAccounts(options?: ItdAccountsOptions)
-createAccounts(options?: ItdAccountsOptions): ItdAccounts   // фабрика
-```
-
-## Методы
-
-```ts
-addAccount(name: string, options?: AddAccountOptions): ItdClient
-```
-Заводит аккаунт. Возвращает обычный `ItdClient` со всеми ресурсами. Хранилище подставляется
-само — срез общего по имени. `auth` не обязателен, если сессия уже в хранилище.
-
-```ts
-account(name: string): ItdClient
-```
-Клиент аккаунта. Бросает `ItdConfigError`, если аккаунта нет.
-
-```ts
-restore(): Promise<string[]>
-```
-Поднимает аккаунты, сессии которых уже лежат в хранилище (после перезапуска — без `auth` и
-капчи). Возвращает имена добавленных.
-
-```ts
-removeAccount(name: string, options?: RemoveAccountOptions): Promise<boolean>
-```
-Убирает аккаунт: закрывает клиента и, при `forget: true`, забывает сессию. Сетевого запроса
-не делает — для завершения сессии на сервере вызовите `itd.auth.logout()` до удаления.
-
-```ts
-has(name: string): boolean
-names(): string[]
-get size: number
-get storage: MultiTokenStorage
-```
-Состав контейнера.
-
-```ts
-use(plugin: ItdPlugin): this
-pluginNames(): string[]
-hasPlugin(name: string): boolean
-unuse(name: string): Promise<boolean>
-```
-Подключает плагин всем аккаунтам — и заведённым, и будущим; показывает общий набор или
-отключает плагин сразу у всех клиентов.
-
-```ts
-on<K>(event: K, listener): Unsubscribe
-```
-Подписка на [события авторизации всех аккаунтов](#события) сразу.
-
-```ts
-close(): Promise<void>
-dispose(): Promise<void>
-```
-`close()` временно закрывает все аккаунты и останавливает общую очередь, не отключая
-плагины. `dispose()` дополнительно вызывает teardown плагинов. `await using` вызывает
-`dispose()`.
-
-```ts
-[Symbol.iterator](): IterableIterator<[string, ItdClient]>
-```
-Перебор парами «имя — клиент»: `for (const [name, itd] of accounts) { … }`.
-
-## События (`AccountEvents`)
-
-Те же, что у одиночного клиента, плюс имя аккаунта:
-
-| Событие | Данные |
-|---|---|
-| `tokens` | `{ account, accessToken }` |
-| `signIn` | `{ account, accessToken }` |
-| `signOut` | `{ account }` |
-| `authError` | `{ account, error }` |
-
-## Опции
-
-```ts
-interface ItdAccountsOptions extends Omit<ItdClientOptions, 'auth' | 'storage' | 'deviceId'> {
-  storage?: MultiTokenStorage;           // по умолчанию MemoryMultiTokenStorage
-  plugins?: readonly ItdPlugin[];        // подключаются каждому аккаунту
-  rateLimitScope?: 'account' | 'shared'; // очередь: своя у каждого / общая; по умолчанию 'account'
-}
-
-type AddAccountOptions = Omit<ItdClientOptions, 'storage'>;
-
-interface RemoveAccountOptions {
-  forget?: boolean;                      // удалить и сохранённую сессию; по умолчанию false
-}
-```
-
-`rateLimitScope: 'shared'` нужен, когда все аккаунты сидят на одном IP и упираются в лимит по
-адресу. Настройки самой очереди тогда задаются контейнеру опцией `rateLimit`; аккаунту можно
-передать только `rateLimit: false`, чтобы вывести его из общей очереди.

package/guides/reference/auth.md

@@ -1,141 +0,0 @@
-# Авторизация — `itd.auth`
-
-Вход, регистрация, подтверждение по коду, пароли, OAuth и управление сессиями. Обычно
-клиент авторизуется сам через опцию `auth` конструктора; эти методы нужны для ручных
-сценариев входа. Полное руководство — [Авторизация](../authentication/README.md).
-
-Вход, регистрация и сброс пароля требуют одноразовый **Turnstile token**. Ключ виджета —
-экспорт `TURNSTILE_SITE_KEY`.
-
-## Вход и регистрация
-
-```ts
-signUp(credentials: CaptchaCredentials): Promise<string>
-```
-Регистрирует аккаунт и запускает подтверждение по коду. Возвращает `flowToken` для `verifyOtp()`.
-
-```ts
-signIn(credentials: CaptchaCredentials): Promise<SignInResult>
-```
-Выполняет вход. При успехе токен сохраняется в клиенте автоматически. Если сервер потребовал
-код, вернётся `{ status: 'otp_required', flowToken }`.
-
-```ts
-signInWithOtp(input: CaptchaCredentials & { getOtp: () => string | Promise<string> }): Promise<string>
-```
-Полный вход с подтверждением: код запрашивается функцией `getOtp`, остальное — само. Возвращает
-`accessToken`.
-
-```ts
-verifyOtp(input: Credentials & { otp: string; flowToken: string }): Promise<string>
-```
-Подтверждает вход кодом из письма. Токен сохраняется автоматически.
-
-```ts
-resendOtp(input: { email: string; flowToken: string }): Promise<void>
-```
-Отправляет код подтверждения повторно.
-
-## Сессия
-
-```ts
-refresh(): Promise<string>
-```
-Обновляет токен доступа. Параллельные вызовы объединяются в один сетевой запрос. При включённом
-`autoRefresh` вручную обычно не нужен.
-
-```ts
-hasRefreshSession(): Promise<boolean>
-```
-Есть ли признак живой сессии обновления (cookie `is_auth` или строковый refresh-токен).
-В браузере всегда `true`. Читает хранилище — верен и до первого запроса.
-
-```ts
-logout(): Promise<void>
-```
-Завершает текущую сессию на сервере и очищает локальную.
-
-```ts
-logoutAll(): Promise<void>
-```
-Завершает все сессии пользователя и очищает локальную.
-
-```ts
-signOut(): Promise<void>
-```
-Забывает сессию локально, не обращаясь к серверу.
-
-## Пароли
-
-```ts
-forgotPassword(input: ForgotPasswordInput): Promise<string>
-```
-Запрашивает письмо с кодом для сброса. Возвращает `flowToken` для `resetPassword()`.
-
-```ts
-resetPassword(input: ResetPasswordInput): Promise<void>
-```
-Устанавливает новый пароль по коду. Нужны все четыре поля: `email`, `otp`, `flowToken`, `newPassword`.
-
-```ts
-resetPasswordWithOtp(input: ForgotPasswordInput & { newPassword: string; getOtp: () => string | Promise<string> }): Promise<void>
-```
-Полный сброс: код запрашивается функцией `getOtp`, остальное — само.
-
-```ts
-changePassword(input: { currentPassword: string; newPassword: string }): Promise<void>
-```
-Меняет пароль. Требует действующей сессии. При неверном текущем пароле — код
-`ACCOUNT_CURRENT_PASSWORD_INCORRECT`.
-
-## Управление сессиями
-
-```ts
-sessions(): Promise<Session[]>
-```
-Список активных сессий. У текущей `isCurrent === true`. См. [`Session`](./models.md#session).
-
-```ts
-revokeSession(sessionId: string): Promise<void>
-```
-Завершает указанную сессию.
-
-```ts
-revokeOtherSessions(): Promise<void>
-```
-Завершает все сессии, кроме текущей.
-
-## Типы
-
-```ts
-interface Credentials {
-  email: string;
-  password: string;
-}
-
-interface CaptchaCredentials extends Credentials {
-  turnstileToken: string;                // одноразовый, живёт несколько минут
-}
-
-interface ForgotPasswordInput {
-  email: string;
-  turnstileToken: string;
-}
-
-interface ResetPasswordInput {
-  email: string;
-  otp: string;
-  flowToken: string;
-  newPassword: string;
-}
-
-type SignInResult =
-  | { status: 'authenticated'; accessToken: string }
-  | { status: 'otp_required'; flowToken: string | undefined };
-
-const OAuthProvider = { Yandex: 'yandex', Google: 'google' } as const;
-const SignInStatus = { Authenticated: 'authenticated', OtpRequired: 'otp_required' } as const;
-```
-
-Связанные: [`AuthInput`](./client.md#авторизация-authinput) (как клиент получает доступ),
-события авторизации `itd.on('tokens' | 'authError' | …)` — см. [Клиент](./client.md#события).

package/guides/reference/builders.md

@@ -1,135 +0,0 @@
-# Билдеры — `post()`, `comment()`, `poll()`, `report()`, `markup()`
-
-Билдеры собирают данные для публикующих методов и проверяют их **до** обращения к сети
-(бросают [`ItdConfigError`](./errors.md)). Все билдеры **неизменяемые**: каждый метод
-возвращает новый экземпляр, поэтому заготовку можно переиспользовать.
-
-Методы вроде `posts.create`, `posts.comment`, `comments.reply`, `reports.create` принимают три
-равноправные формы: обычный объект, готовый билдер или функцию-настройщик.
-
-```ts
-isBuilder(value: unknown): boolean       // это билдер?
-```
-
-## Пост — `post()`
-
-```ts
-post(content?: string): PostBuilder
-```
-
-| Метод | Описание |
-|---|---|
-| `.content(text)` | задаёт текст, сбрасывая прежнюю разметку |
-| `.append(text)` | дописывает текст к уже заданному |
-| `.spans(spans)` | задаёт готовую разметку `Span[]` |
-| `.markup(input)` | заменяет текст и разметку результатом `MarkupBuilder` |
-| `.autoSpans(options?)` | находит ссылки, хэштеги и упоминания в тексте |
-| `.onWall(userId)` | публикует на стене пользователя (**UUID**) |
-| `.attach(file)` | прикладывает файл (загрузится перед публикацией) |
-| `.attachId(id)` | прикладывает уже загруженное вложение |
-| `.poll(input)` | добавляет опрос |
-| `.build()` | возвращает проверенный `CreatePostInput` |
-
-## Комментарий — `comment()`
-
-```ts
-comment(content?: string): CommentBuilder
-```
-
-| Метод | Описание |
-|---|---|
-| `.content(text)` | задаёт текст |
-| `.attach(file)` / `.attachId(id)` | прикладывает вложение |
-| `.voice(audio)` | делает комментарий голосовым (без текста, одно аудио `audio/ogg`) |
-| `.replyTo(userId)` | адресат ответа (только в `comments.reply()`) |
-| `.build()` | возвращает проверенный `CreateCommentInput` |
-
-## Опрос — `poll()`
-
-```ts
-poll(question?: string): PollBuilder
-```
-
-| Метод | Описание |
-|---|---|
-| `.question(text)` | задаёт вопрос (≤ 200 символов) |
-| `.option(text)` | добавляет один вариант (≤ 100 символов) |
-| `.options(...texts)` | добавляет несколько вариантов сразу |
-| `.multipleChoice(enabled?)` | разрешает выбор нескольких |
-| `.build()` | возвращает проверенный `CreatePollInput` |
-
-Требуется от 2 до 10 различных непустых вариантов.
-
-## Жалоба — `report`
-
-Объект-фабрика: тип объекта выбирается точкой входа, поэтому рассогласовать тип и идентификатор
-нельзя.
-
-```ts
-report.post(postId: string): ReportBuilder
-report.comment(commentId: string): ReportBuilder
-report.user(userId: string): ReportBuilder
-```
-
-| Метод | Описание |
-|---|---|
-| `.reason(reason)` | причина ([`ReportReason`](./enums.md#reportreason)) |
-| `.description(text)` | пояснение в свободной форме |
-| `.build()` | возвращает проверенный `CreateReportInput` |
-
-## Разметка текста — `markup()`
-
-Собирает текст и сам считает `offset`/`length` в единицах UTF-16.
-
-```ts
-markup(content?: string): MarkupBuilder
-```
-
-| Метод | Описание |
-|---|---|
-| `.text(value)` | обычный текст без разметки |
-| `.newline(count?)` | переводы строк |
-| `.bold` · `.italic` · `.underline` · `.strike` · `.spoiler` · `.monospace` · `.quote` | стиль на фрагменте |
-| `.hashtag(tag)` | `#хэштег` |
-| `.mention(username)` | `@упоминание` |
-| `.link(content, url?)` | ссылка |
-| `.span(value, span)` | произвольный тип разметки |
-| `.styled(value, ...types)` | несколько стилей на одном диапазоне |
-| `.build()` | возвращает `{ content, spans }` |
-
-Все методы контента принимают строку **или** вложенный билдер/разметку — так стили вкладываются
-друг в друга.
-
-## Автоопределение сущностей
-
-```ts
-autoSpans(text: string, options?: AutoSpansOptions): Span[]
-```
-Находит HTTP(S)-ссылки, `#хэштеги` и `@упоминания` в готовом тексте.
-
-```ts
-interface AutoSpansOptions {
-  hashtags?: boolean;                    // по умолчанию true
-  mentions?: boolean;                    // по умолчанию true
-  links?: boolean;                       // по умолчанию true
-}
-```
-
-## Рендеринг разметки
-
-```ts
-renderSpans(content: string, spans: Span[] | null | undefined, options?: RenderSpansOptions): string
-```
-Превращает текст и spans в HTML (по умолчанию, безопасный), Markdown или ANSI.
-
-```ts
-interface RenderSpansOptions {
-  format?: 'html' | 'markdown' | 'ansi';                     // по умолчанию 'html'
-  mentionUrl?: (username: string) => string | null | undefined;
-  hashtagUrl?: (tag: string) => string | null | undefined;
-  classPrefix?: string | null;           // префикс CSS-классов; по умолчанию 'itd'
-}
-```
-
-Подробное руководство по разметке — [Разметка текста](../text-markup/README.md).
-См. [`Span`](./models.md#span), [`SpanType`](./enums.md#spantype).