itd-api 0.0.11 → 0.1.0

package/guides/reference/posts.md

@@ -0,0 +1,157 @@
+# Посты — `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

@@ -0,0 +1,78 @@
+# 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

@@ -0,0 +1,28 @@
+# Жалобы — `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

@@ -0,0 +1,41 @@
+# Подписка — `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

@@ -0,0 +1,146 @@
+# Пользователи — `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

@@ -0,0 +1,24 @@
+# Верификация — `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itd-api",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "Клиент REST и realtime API социальной сети итд.com для JavaScript и TypeScript",
   "repository": {
     "type": "git",