itd-api 0.1.0 → 0.3.0

package/guides/reference/posts.md

@@ -1,157 +0,0 @@
-# Посты — `itd.posts`
-
-Лента, публикация, реакции, репосты, опросы и комментарии к постам. Публикующие методы
-принимают объект, [билдер](./builders.md) или функцию-настройщик.
-
-## Лента
-
-```ts
-list(params?: FeedParams): Promise<Page<Post>>
-iterate(params?: FeedParams): Paginator<Post>
-```
-Страница ленты / перебор ленты. Курсорная пагинация. См. [`Post`](./models.md#post),
-[`FeedTab`](./enums.md#feedtab).
-
-## Публикация
-
-```ts
-create(input: PostInput): Promise<Post>
-```
-Публикует пост. Файлы из поля `files` загружаются автоматически, порядок вложений сохраняется.
-
-```ts
-get(postId: string): Promise<Post>
-```
-Один пост вместе с топовыми комментариями (заполнено поле `comments`).
-
-```ts
-update(postId: string, input: PostUpdateInput): Promise<Post>
-```
-Редактирует текст и разметку. Поля создания (вложения, опрос, стена) отвергаются до запроса.
-`content` обязателен.
-
-```ts
-remove(postId: string): Promise<void>
-restore(postId: string): Promise<Post>
-```
-Удаляет / восстанавливает пост.
-
-## Реакции, репосты, закрепление
-
-```ts
-like(postId: string): Promise<LikeResult>
-unlike(postId: string): Promise<LikeResult>
-```
-Ставит / убирает реакцию. См. [`LikeResult`](./models.md#likeresult).
-
-```ts
-repost(postId: string, content?: string): Promise<Post>
-unrepost(postId: string): Promise<void>
-```
-Репост с необязательным комментарием / отмена репоста. Вложения к репосту не поддерживаются.
-
-```ts
-pin(postId: string): Promise<PinPostResult>
-unpin(postId: string): Promise<PinPostResult>
-```
-Закрепляет / открепляет пост в профиле. См. [`PinPostResult`](./models.md#pinpostresult).
-
-## Опросы
-
-```ts
-vote(postId: string, optionIds: string[]): Promise<Poll>
-```
-Голосует в опросе. Несколько вариантов допустимы только при `multipleChoice`. См.
-[`Poll`](./models.md#poll).
-
-## Счётчики
-
-```ts
-stats(ids: string[]): Promise<PostStats[]>
-```
-Счётчики сразу для нескольких постов. См. [`PostStats`](./models.md#poststats).
-
-## Стена и лайки пользователя
-
-```ts
-byUser(user: UserRef, params?: UserPostsParams): Promise<Page<Post>>
-iterateByUser(user: UserRef, params?: UserPostsParams): Paginator<Post>
-```
-Стена пользователя.
-
-> ⚠️ Это **не только его собственные посты**: сюда попадают и записи, которые другие оставили
-> на его стене (у них `author` чужой, `wallRecipient` — владелец стены). Поэтому записей обычно
-> больше, чем `postsCount` в профиле. Нужны только авторские — отфильтруйте по `post.author.id`.
-
-```ts
-likedByUser(user: UserRef, params?: UserPostsParams): Promise<Page<Post>>
-iterateLikedByUser(user: UserRef, params?: UserPostsParams): Paginator<Post>
-```
-Посты, которые пользователь отметил реакцией.
-
-## Комментарии к посту
-
-Комментарии **к посту** живут здесь; ответы на комментарии — в [`itd.comments`](./comments.md).
-
-```ts
-comments(postId: string, params?: CommentsParams): Promise<Page<Comment>>
-iterateComments(postId: string, params?: CommentsParams): Paginator<Comment>
-```
-Комментарии к посту. Курсорная пагинация. См. [`Comment`](./models.md#comment),
-[`CommentSort`](./enums.md#commentsort).
-
-```ts
-comment(postId: string, input: CommentInput | string): Promise<Comment>
-```
-Комментирует пост. Строка — это просто текст.
-
-```ts
-voiceComment(postId: string, audio: FileInput): Promise<Comment>
-```
-Голосовой комментарий: без текста, одно аудиовложение `audio/ogg`.
-
-## Типы
-
-```ts
-type PostInput = CreatePostInput | PostBuilder | ((b: PostBuilder) => PostBuilder | CreatePostInput);
-type PostUpdateInput = UpdatePostInput | PostBuilder | ((b: PostBuilder) => PostBuilder | UpdatePostInput);
-type CommentInput = CreateCommentInput | CommentBuilder | ((b: CommentBuilder) => CommentBuilder | CreateCommentInput);
-
-interface CreatePostInput {
-  content?: string;
-  spans?: Span[];                        // проверяются относительно content
-  wallRecipientId?: UserId | null;       // строго UUID
-  attachmentIds?: string[];              // заранее загруженные вложения
-  files?: FileInput[];                   // загрузятся перед публикацией, порядок сохраняется
-  poll?: PollInput;
-}
-
-interface UpdatePostInput {
-  content: string;                       // обязателен
-  spans?: Span[];
-}
-
-interface FeedParams extends RequestOptions {
-  tab?: FeedTab;                         // по умолчанию популярное
-  limit?: number;
-  cursor?: string;                       // непрозрачный, из nextCursor
-  maxPages?: number;
-}
-
-interface UserPostsParams extends RequestOptions {
-  limit?: number;
-  cursor?: string;
-  sort?: string;
-  pinnedPostId?: string;                 // поднять закреплённый пост наверх
-  maxPages?: number;
-}
-
-interface CommentsParams extends RequestOptions {
-  limit?: number;
-  cursor?: string;                       // id последнего полученного комментария
-  sort?: CommentSort;
-  maxPages?: number;
-}
-```
-
-См. также [Билдеры](./builders.md) (`post()`, `comment()`, `poll()`, разметка текста).

package/guides/reference/realtime.md

@@ -1,78 +0,0 @@
-# Realtime — `itd.realtime()`
-
-Поток уведомлений в реальном времени. Создаётся `itd.realtime(options?)`, соединение
-поднимается `connect()` и держится само: обрывы, обновление токена, keep-alive и повторные
-попытки — внутри. Транспорт выбирается автоматически: SSE, а если среда не умеет читать тело
-по частям — опрос REST. Полное руководство — [Realtime](../realtime/README.md).
-
-```ts
-const stream = itd.realtime(options?: RealtimeOptions): ItdRealtime
-```
-
-## Методы `ItdRealtime`
-
-```ts
-connect(): Promise<void>
-```
-Поднимает соединение. Повторный вызов при живом соединении ничего не делает. Возвращает
-управление сразу — соединение живёт в фоне.
-
-```ts
-disconnect(): void
-```
-Закрывает соединение и отменяет запланированные попытки.
-
-```ts
-on<K>(event: K, listener): Unsubscribe
-once<K>(event: K, listener): Unsubscribe
-removeAllListeners(): void
-```
-Подписка на события / однократная подписка / снятие всех подписок (соединение при этом
-не закрывается).
-
-```ts
-get status: RealtimeStatus              // 'connecting' | 'connected' | 'error' | 'disconnected'
-get transport: string                   // 'sse' | 'poll'
-```
-
-## События (`RealtimeEvents`)
-
-| Событие | Данные | Когда |
-|---|---|---|
-| `notification` | `NotificationEvent` | пришло новое уведомление |
-| `ready` | `{ userId?: string }` | сервер подтвердил подключение (первый кадр) |
-| `unreadCount` | `number` | сервер сообщил число непрочитанных (на практике редко — держите счётчик сами) |
-| `status` | `RealtimeStatus` | изменилось состояние соединения |
-| `error` | `{ error, willReconnect }` | соединение оборвалось |
-| `reconnect` | `{ attempt, delay }` | запланировано переподключение |
-| `giveup` | — | попытки исчерпаны; нужен ручной `connect()` |
-| `parseError` | `{ error, raw }` | сообщение не удалось разобрать (соединение живо) |
-| `message` | `{ name, data }` | любое событие потока в необработанном виде |
-
-`NotificationEvent` содержит `{ notification: Notification; unreadCount?: number }`; уведомление
-в той же форме, что и в [`itd.notifications`](./notifications.md).
-
-## Опции (`RealtimeOptions`)
-
-```ts
-interface RealtimeOptions {
-  transport?: 'auto' | 'sse' | 'poll' | RealtimeTransport;   // по умолчанию 'auto'
-  idleTimeout?: number;                  // молчание сервера = мёртвое соединение; 90000
-  pollInterval?: number;                 // период опроса для запасного транспорта
-  syncCount?: boolean;                   // запросить число непрочитанных при connect; true
-  reconnectOnVisible?: boolean;          // переподключаться при возврате вкладки; true (браузер)
-  reconnectOnOnline?: boolean;           // переподключаться при восстановлении сети; true (браузер)
-  // из ReconnectOptions:
-  maxAttempts?: number;
-  backoff?: number[];                    // лестница пауз переподключения
-  jitter?: number;                       // 0…1
-}
-
-const RealtimeTransportKind = { Auto: 'auto', Sse: 'sse', Poll: 'poll' } as const;
-const RealtimeStatus = {
-  Connecting: 'connecting', Connected: 'connected', Error: 'error', Disconnected: 'disconnected',
-} as const;
-```
-
-Можно передать и свою реализацию `RealtimeTransport` — например для WebSocket. Смена
-авторизации на другого пользователя завершает все потоки клиента; смена только сессии — нет.

package/guides/reference/reports.md

@@ -1,28 +0,0 @@
-# Жалобы — `itd.reports`
-
-Жалобы на контент и пользователей. Принимает объект или [билдер](./builders.md)
-`report`, у которого тип объекта и его идентификатор задаются одновременно.
-
-## Метод
-
-```ts
-create(input: ReportInput): Promise<Report>
-```
-Отправляет жалобу. Повторная жалоба на тот же объект отклоняется сервером. См.
-[`Report`](./models.md#report).
-
-## Типы
-
-```ts
-type ReportInput = CreateReportInput | ReportBuilder | ((b: ReportBuilder) => ReportBuilder | CreateReportInput);
-
-interface CreateReportInput {
-  targetType: ReportTargetType;          // 'post' | 'comment' | 'user'
-  targetId: string;
-  reason: ReportReason;                  // 'spam' | 'violence' | 'hate' | 'adult' | 'fraud' | 'other'
-  description?: string;                  // пояснение в свободной форме
-}
-```
-
-См. [`ReportTargetType`](./enums.md#reporttargettype), [`ReportReason`](./enums.md#reportreason)
-и билдер [`report`](./builders.md).

package/guides/reference/subscription.md

@@ -1,41 +0,0 @@
-# Подписка — `itd.subscription`
-
-Состояние платной подписки (премиум NUKSTA), автопродление и способы оплаты. Форма ответа
-у платёжных методов в документации API не описана, поэтому часть возвращает `unknown`.
-
-## Методы
-
-```ts
-status(): Promise<Subscription>
-```
-Состояние подписки и её цена. См. [`Subscription`](./models.md#subscription).
-
-```ts
-pay(): Promise<unknown>
-```
-Запускает оплату подписки.
-
-```ts
-setAutoRenewal(enabled: boolean): Promise<unknown>
-```
-Включает / отключает автопродление.
-
-```ts
-bindCard(): Promise<unknown>
-```
-Запускает привязку карты.
-
-```ts
-methods(): Promise<PaymentMethod[]>
-```
-Список способов оплаты. Пустой массив, если карт нет. См. [`PaymentMethod`](./models.md#paymentmethod).
-
-```ts
-setDefaultMethod(methodId: string): Promise<unknown>
-```
-Делает способ оплаты основным.
-
-```ts
-removeMethod(methodId: string): Promise<void>
-```
-Удаляет способ оплаты.

package/guides/reference/users.md

@@ -1,146 +0,0 @@
-# Пользователи — `itd.users`
-
-Профили, подписки, блокировки, приватность и значки. Методы принимают
-[`UserRef`](./README.md#общие-соглашения) — UUID **или** имя пользователя, если не
-указано иное.
-
-## Свой профиль
-
-```ts
-me(): Promise<MyProfile>
-```
-Свой профиль — с подпиской и признаком подтверждённого телефона. См. [`MyProfile`](./models.md#myprofile).
-
-```ts
-updateMe(input: UpdateProfileInput): Promise<MyProfile>
-```
-Обновляет свой профиль. Передавайте только изменяемые поля.
-
-```ts
-createProfile(input: { username: string; displayName: string; avatar?: string }): Promise<MyProfile>
-```
-Создаёт профиль после регистрации.
-
-```ts
-deactivate(): Promise<void>
-restore(): Promise<void>
-```
-Деактивирует / восстанавливает аккаунт.
-
-## Чужие профили
-
-```ts
-get(user: UserRef): Promise<PublicProfile>
-```
-Профиль пользователя по UUID или имени. См. [`PublicProfile`](./models.md#publicprofile).
-
-```ts
-checkUsername(username: string): Promise<boolean>
-```
-Свободно ли имя пользователя.
-
-## Подписки
-
-```ts
-follow(user: UserRef): Promise<FollowResult>
-```
-Подписывается. У закрытого профиля отправляется заявка — видно по полю `status`. См.
-[`FollowResult`](./models.md#followresult).
-
-```ts
-unfollow(user: UserRef): Promise<void>
-```
-Отписывается.
-
-```ts
-followStatus(userIds: UserId[]): Promise<Record<string, boolean>>
-```
-Проверяет подписку сразу для нескольких пользователей. Возвращает «идентификатор → подписаны ли вы».
-
-```ts
-followers(user: UserRef, params?: UserListParams): Promise<Page<UserSummary>>
-iterateFollowers(user: UserRef, params?: UserListParams): Paginator<UserSummary>
-following(user: UserRef, params?: UserListParams): Promise<Page<UserSummary>>
-iterateFollowing(user: UserRef, params?: UserListParams): Paginator<UserSummary>
-```
-Подписчики и подписки. См. [`UserSummary`](./models.md#usersummary).
-
-> ⚠️ **Сервер эти списки не листает.** Возвращаются первые 20 записей: `page` игнорируется,
-> `limit` больше 20 молча уменьшается, `hasMore` всегда `false`. Полю `total` доверять тоже
-> нельзя — оно расходится с `followersCount` из профиля. Методы-итераторы закончатся после
-> первых 20 записей и оставлены на случай, если пагинацию починят.
-
-## Блокировки
-
-```ts
-block(user: UserRef): Promise<void>
-unblock(user: UserRef): Promise<void>
-```
-Блокирует / снимает блокировку.
-
-```ts
-blocked(params?: UserListParams): Promise<Page<UserSummary>>
-iterateBlocked(params?: UserListParams): Paginator<UserSummary>
-```
-Заблокированные пользователи. Ограничения листания те же, что у `followers`.
-
-## Приватность
-
-```ts
-getPrivacy(): Promise<PrivacySettings>
-updatePrivacy(input: UpdatePrivacyInput): Promise<PrivacySettings>
-```
-Читает / обновляет настройки приватности. См. [`PrivacySettings`](./models.md#privacysettings).
-
-## Значки профиля («пины»)
-
-```ts
-pins(): Promise<PinsResult>
-```
-Значки профиля и выбранный из них. `activePin` — строка-идентификатор, а не объект. См.
-[`PinsResult`](./models.md#pinsresult).
-
-```ts
-setPin(slug: string): Promise<void>
-removePin(): Promise<void>
-```
-Выбирает / снимает активный значок.
-
-## Поиск и рекомендации
-
-Также описаны в разделе [Поиск и обнаружение](./discovery.md).
-
-```ts
-search(query: string, params?: { limit?: number }): Promise<UserSummary[]>
-```
-Ищет пользователей по строке запроса.
-
-```ts
-whoToFollow(): Promise<UserSummary[]>
-```
-Рекомендации, на кого подписаться.
-
-```ts
-topClans(): Promise<Clan[]>
-```
-Рейтинг кланов. См. [`Clan`](./models.md#clan).
-
-## Типы
-
-```ts
-interface UpdateProfileInput {
-  displayName?: string;
-  username?: string;
-  avatar?: string;                       // эмодзи-символ клана, а не URL картинки
-  bio?: string;
-  banner?: string;                       // URL изображения-шапки
-}
-
-type UpdatePrivacyInput = Partial<PrivacySettings>;
-
-interface UserListParams extends RequestOptions {
-  limit?: number;                        // > 20 сервер зажимает до 20
-  page?: number;                         // сервер игнорирует
-  maxPages?: number;
-}
-```

package/guides/reference/verification.md

@@ -1,24 +0,0 @@
-# Верификация — `itd.verification`
-
-Статус заявки на верификацию профиля и её подача.
-
-## Методы
-
-```ts
-status(): Promise<VerificationStatus>
-```
-Статус заявки. Значение `'none'` означает, что заявка не подавалась. См.
-[`VerificationStatus`](./models.md#verificationstatus).
-
-```ts
-submit(videoUrl: string): Promise<unknown>
-```
-Подаёт заявку на верификацию с видео.
-
-## Типы
-
-```ts
-interface VerificationStatus {
-  status: 'none' | 'pending' | 'approved' | 'rejected' | (string & {});
-}
-```

package/guides/text-markup/README.md

@@ -1,214 +0,0 @@
-# Разметка текста
-
-ИТД хранит форматирование отдельным массивом `spans`. Каждый span задаёт тип, смещение и
-длину фрагмента:
-
-```ts
-{
-  type: 'bold',
-  offset: 0,
-  length: 5,
-}
-```
-
-Смещения измеряются в UTF-16 code units — тех же единицах, которые используют
-`String#slice`, `substring` и DOM Selection. Поэтому эмодзи вне BMP обычно занимает две
-единицы.
-
-## Создание поста
-
-`markup()` собирает текст и вычисляет смещения одновременно:
-
-```ts
-import { post } from 'itd-api';
-
-await itd.posts.create(
-  post().markup((m) =>
-    m
-      .text('смотрите ')
-      .hashtag('котики')
-      .text(' от ')
-      .mention('durov')
-      .newline()
-      .bold('важно')
-      .text(': ')
-      .link('документация', 'https://example.com/docs'),
-  ),
-);
-```
-
-Доступны:
-
-- `bold`, `italic`, `underline`, `strike`;
-- `spoiler`, `monospace`, `quote`;
-- `link`, `hashtag`, `mention`;
-- произвольный `span()`;
-- несколько стилей сразу через `styled()`.
-
-Билдер неизменяемый: каждый вызов возвращает новый экземпляр.
-
-## Несколько стилей и пересечения
-
-API хранит каждый стиль отдельным span, поэтому один диапазон может быть одновременно
-жирным и подчёркнутым:
-
-```ts
-import { SpanType, markup } from 'itd-api';
-
-const sameRange = markup()
-  .styled('жирный и подчёркнутый', SpanType.Bold, SpanType.Underline)
-  .build();
-```
-
-Вложенность выражает частичное пересечение без ручных offsets:
-
-```ts
-const nested = markup()
-  .bold((m) => m.text('весь жирный, ').underline('а это ещё и подчёркнуто'))
-  .build();
-
-const linked = markup()
-  .link((m) => m.bold('документация'), 'https://example.com')
-  .build();
-```
-
-При сборке spans стабильно сортируются по `offset`, а при одинаковом начале — от длинного
-к короткому.
-
-## Автоматическая разметка
-
-Для готового текста `autoSpans()` находит HTTP(S)-ссылки, хэштеги и упоминания:
-
-```ts
-await itd.posts.create(
-  post('#котики от @durov: https://example.com').autoSpans(),
-);
-```
-
-Метод сохраняет ручные стили и не создаёт дубли при повторном вызове. Отдельная функция
-возвращает только найденный массив:
-
-```ts
-import { autoSpans } from 'itd-api';
-
-const spans = autoSpans('спасибо @durov. #котики', {
-  links: true,
-  mentions: true,
-  hashtags: true,
-});
-```
-
-Сущности внутри URL не размечаются, даже если `{ links: false }`: ссылки всё равно
-распознаются как защищённые диапазоны, но не попадают в результат.
-
-## Замена текста
-
-Spans рассчитаны для конкретной строки. Поэтому `.content()` заменяет текст и сбрасывает
-старую разметку:
-
-```ts
-post('#старый')
-  .autoSpans()
-  .content('новый текст')
-  .build();
-
-// { content: 'новый текст' }
-```
-
-После `.content()` вызовите `.spans()`, `.markup()` или `.autoSpans()` заново. Метод
-`.append()` сохраняет существующие spans: старые offsets при дописывании текста не меняются.
-
-## Сырые spans
-
-Готовый массив можно передать объектом или через билдер:
-
-```ts
-import { SpanType } from 'itd-api';
-
-await itd.posts.create({
-  content: 'важно',
-  spans: [{ type: SpanType.Bold, offset: 0, length: 5 }],
-});
-```
-
-Перед запросом библиотека проверяет, что каждый диапазон непустой и целиком лежит внутри
-`content`. Spans без текста также отклоняются. Семантику типа проверить невозможно:
-формально валидный диапазон остаётся ответственностью вызывающего кода.
-
-У `link` адрес лежит в `url`, у `hashtag` имя — в `tag`, у `mention` — в `username`.
-Старые ответы сервера могут хранить username упоминания в `tag`.
-
-## Обновление поста
-
-`posts.update()` принимает объект, билдер или функцию-настройщик:
-
-```ts
-await itd.posts.update(postId, post().markup((m) => m.bold('новый текст')));
-await itd.posts.update(postId, (p) => p.content('#новый текст').autoSpans());
-```
-
-Update endpoint меняет только `content` и `spans`. Вложения, опрос и чужая стена
-отклоняются до запроса. `content` требуется задать явно, чтобы `{}` или обновление только
-spans не стёрло текущий текст.
-
-Явный пустой текст разрешён одинаково во всех формах:
-
-```ts
-await itd.posts.update(postId, { content: '' });
-await itd.posts.update(postId, post(''));
-await itd.posts.update(postId, (p) => p.content(''));
-```
-
-## Отображение
-
-`renderSpans()` поддерживает HTML, Markdown и ANSI:
-
-```ts
-import { renderSpans } from 'itd-api';
-
-renderSpans(post.content, post.spans); // безопасный HTML по умолчанию
-renderSpans(post.content, post.spans, { format: 'markdown' });
-renderSpans(post.content, post.spans, { format: 'ansi' });
-```
-
-HTML экранируется, опасные схемы ссылок не превращаются в `<a>`. Для собственного
-приложения можно заменить маршруты и CSS-префикс:
-
-```ts
-renderSpans(post.content, post.spans, {
-  mentionUrl: (username) => `/users/${username}`,
-  hashtagUrl: (tag) => `/topics/${tag}`,
-  classPrefix: 'feed',
-});
-```
-
-Возврат `null` из `mentionUrl` или `hashtagUrl` отключает соответствующую ссылку,
-`classPrefix: null` отключает классы. По умолчанию используются `/@username`,
-`/hashtag/name` и классы `itd-*`.
-
-Пересекающиеся spans разбиваются на корректно вложенные сегменты. В Markdown цитаты
-применяются после сборки сегментов, а code spans выбирают забор длиннее внутренних
-последовательностей обратных апострофов.
-
-## Комментарии
-
-Сервер может вернуть `comment.spans`; поле необязательно, поэтому оба вызова безопасны:
-
-```ts
-renderSpans(comment.content, comment.spans);
-renderSpans(comment.content);
-```
-
-Скачанный клиент сайта и документированный API комментариев отправляют при создании и
-редактировании только текст и вложения. Поэтому библиотека читает разметку комментариев,
-но не обещает неподтверждённую сервером запись ручных spans.
-
-## Запускаемый пример
-
-Пример создаёт один настоящий пост и показывает авторазметку, пересечения и рендер:
-
-```bash
-ITD_TOKEN=<accessToken> node guides/text-markup/examples/create-post.mjs
-```
-
-Исходник: [`examples/create-post.mjs`](./examples/create-post.mjs).