itd-api 0.0.10 → 0.1.0

package/guides/reference/models.md

@@ -0,0 +1,448 @@
+# Модели данных
+
+Формы объектов, которые возвращает API. Все поля дат — строки ISO-8601 (`IsoDate`); для разбора
+есть [`toDate()`](#вспомогательные-функции). Смещения разметки измеряются в единицах UTF-16.
+
+Особенности, о которых легко забыть:
+
+- **`avatar` — это эмодзи, а не URL.** На итд.com аватар — символ клана (`🩵`, `🦎`).
+  Отрисовывать его нужно как текст. Исключение — `banner`: это настоящий URL.
+- **`UserRef`** = UUID или username; **`UserId`** = строго UUID.
+
+## Пользователи
+
+### Author
+
+Автор поста или комментария (`post.author`, `comment.author`).
+
+```ts
+interface Author {
+  id: UserId;
+  username: string;
+  displayName: string;
+  avatar: string;                        // эмодзи, не URL
+  verified: boolean;
+  pin?: Pin | null;                      // активный значок
+  hasNuksta?: boolean;                   // премиум-подписка
+}
+```
+
+### Actor
+
+Участник события в уведомлении.
+
+```ts
+interface Actor {
+  id: UserId;
+  username: string;
+  displayName: string;
+  avatar: string;
+  isFollowing?: boolean;                 // подписаны ли вы на него
+  isFollowedBy?: boolean;                // подписан ли он на вас
+}
+```
+
+### UserSummary
+
+Пользователь в списках. Набор необязательных полей зависит от эндпоинта.
+
+```ts
+interface UserSummary {
+  id: UserId;
+  username: string;
+  displayName: string;
+  avatar: string;
+  verified: boolean;
+  isFollowing?: boolean;                 // в списках подписчиков/подписок
+  hasNuksta?: boolean;                   // в поиске/рекомендациях
+  followersCount?: number;               // в поиске/рекомендациях
+}
+```
+
+### MyProfile
+
+Свой профиль — ответ `itd.users.me()`.
+
+```ts
+interface MyProfile {
+  id: UserId; username: string; displayName: string;
+  avatar: string; banner: string | null; bio: string;
+  verified: boolean; pin?: Pin | null;
+  wallAccess: WallAccess;                // кто может писать на стену
+  likesVisibility: LikesVisibility;      // кто видит реакции
+  followersCount: number; followingCount: number; postsCount: number;
+  createdAt: IsoDate;
+  isPrivate: boolean;
+  isPhoneVerified: boolean;
+  subscription: SubscriptionState;       // { isActive, expiresAt, autoRenewal }
+}
+```
+
+### PublicProfile
+
+Чужой профиль — ответ `itd.users.get()`.
+
+```ts
+interface PublicProfile {
+  id: UserId; username: string; displayName: string;
+  avatar: string; banner: string | null; bio: string;
+  verified: boolean; pin?: Pin | null;
+  wallAccess: WallAccess; likesVisibility: LikesVisibility;
+  followersCount: number; followingCount: number; postsCount: number;
+  createdAt: IsoDate;
+  hasNuksta?: boolean;
+  pinnedPostId: string | null;
+  isFollowing: boolean;                  // подписаны ли вы
+  isFollowedBy: boolean;                 // подписан ли он на вас
+  online: boolean;
+  lastSeen: IsoDate | null;              // null, если скрыто приватностью
+}
+
+type Profile = MyProfile | PublicProfile;
+isMyProfile(profile): profile is MyProfile   // различает их
+```
+
+### Pin
+
+Значок-«пин» в профиле.
+
+```ts
+interface Pin {
+  slug: string;                          // постоянный идентификатор
+  name: string;
+  description: string;
+  url: string;                           // адрес изображения
+  grantedAt?: IsoDate;                   // только в списке своих пинов
+}
+```
+
+### PinsResult
+
+```ts
+interface PinsResult {
+  pins: Pin[];
+  activePin: string | null;              // идентификатор, а не объект
+}
+```
+
+### PrivacySettings
+
+```ts
+interface PrivacySettings {
+  isPrivate: boolean;                    // подписка требует одобрения
+  wallAccess: WallAccess;
+  likesVisibility: LikesVisibility;
+  showLastSeen: boolean;
+}
+```
+
+### FollowResult
+
+```ts
+interface FollowResult {
+  following: boolean;                    // false, если у закрытого профиля отправлена заявка
+  followersCount?: number;
+  status?: 'following' | 'requested' | (string & {});
+}
+```
+
+### Clan
+
+```ts
+interface Clan {
+  avatar: string;                        // эмодзи клана
+  memberCount: number;
+}
+```
+
+## Посты и комментарии
+
+### Post
+
+```ts
+interface Post {
+  id: string;
+  content: string;
+  spans: Span[];                         // разметка текста
+  author: Author;
+  attachments: Attachment[];
+  likesCount: number; commentsCount: number; repostsCount: number; viewsCount: number;
+  wallRecipientId: UserId | null;        // чья стена, если пост не у себя
+  wallRecipient?: Author | null;         // владелец стены
+  isLiked: boolean; isReposted: boolean; isViewed: boolean; isOwner: boolean;
+  originalPost?: Post | null;            // если это репост
+  poll?: Poll | null;
+  dominantEmoji?: string | null;         // преобладающая реакция
+  editedAt: IsoDate | null;
+  createdAt: IsoDate;
+  comments?: Comment[];                  // только в ответе itd.posts.get()
+}
+```
+
+### Comment
+
+```ts
+interface Comment {
+  id: string;
+  content: string;                       // у голосового пустой
+  spans?: Span[];
+  author: Author;
+  likesCount: number; repliesCount: number;
+  isLiked: boolean;
+  createdAt: IsoDate;
+  attachments?: Attachment[];            // у голосового — одно audio/ogg
+  replies?: Comment[];                   // превью; полный список — comments.replies()
+  replyTo?: CommentReplyTo;              // { id, username, displayName } — только у ответов
+}
+```
+
+### Attachment
+
+```ts
+interface Attachment {
+  id: string;
+  type: AttachmentType;                  // 'image' | 'video' | 'audio'
+  url: string;                           // адрес на CDN
+  width?: number; height?: number;
+  mimeType: string;
+  filename?: string; size?: number;      // приходят не всегда
+  duration?: number | null;             // аудио/видео, секунды
+  order?: number;                        // порядок во вложениях
+}
+```
+
+### Poll
+
+```ts
+interface Poll {
+  id: string; postId: string;
+  question: string;
+  multipleChoice: boolean;
+  options: PollOption[];                 // { id, text, votesCount, position }
+  totalVotes: number;
+  hasVoted: boolean;
+  votedOptionIds: string[];
+  createdAt: IsoDate;
+}
+```
+
+### PostStats
+
+```ts
+interface PostStats {
+  id: string;
+  likesCount: number; commentsCount: number; repostsCount: number; viewsCount: number;
+  dominantEmoji: string | null;
+}
+```
+
+### LikeResult
+
+```ts
+interface LikeResult { liked: boolean; likesCount: number; }
+```
+
+### PinPostResult
+
+```ts
+interface PinPostResult { success: boolean; pinnedPostId: string | null; }
+```
+
+### Span
+
+Фрагмент разметки. `offset`/`length` — в единицах UTF-16.
+
+```ts
+interface Span {
+  type: SpanType;
+  offset: number;
+  length: number;
+  tag?: string;                          // имя хэштега без решётки
+  url?: string;                          // только у link
+  username?: string;                     // у mention
+  id?: string;                           // id пользователя у некоторых mention
+}
+```
+
+## Уведомления
+
+### Notification
+
+Единая форма для REST-списка и SSE-потока.
+
+```ts
+interface Notification {
+  id: string;
+  type: NotificationType;                // канонический тип
+  rawType: string;                       // имя типа как прислал сервер
+  entityId: string | null;               // объект события
+  parentEntityId: string | null;         // родитель (пост комментария)
+  isRead: boolean;
+  actors: Actor[];                       // для схлопнутых — несколько
+  count: number;                         // сколько участников схлопнуто; минимум 1
+  preview: string | null;
+  clickUrl?: string;                     // ссылка от сервера (resolveNotificationUrl обычно точнее)
+  createdAt: IsoDate; updatedAt: IsoDate;
+  raw: unknown;                          // исходный объект
+}
+```
+
+### NotificationSettings
+
+```ts
+interface NotificationSettings {
+  enabled: boolean;                      // общий выключатель
+  sound: boolean;
+  follows: boolean;
+  wallPosts: boolean;
+  likes: boolean;
+  comments: boolean;
+  mentions: boolean;
+}
+```
+
+## Авторизация и подписка
+
+### Session
+
+```ts
+interface Session {
+  id: string;
+  isCurrent: boolean;
+  createdAt: IsoDate; lastUsedAt: IsoDate; expiresAt: IsoDate;
+  ipAddress: string; ipCountry: string | null; ipCity: string | null;
+  deviceType: 'desktop' | 'mobile' | (string & {});
+  osName: string | null; osVersion: string | null;
+  clientName: string | null; clientVersion: string | null;
+  deviceModel: string | null;
+}
+```
+
+### Subscription
+
+```ts
+interface Subscription {
+  active: boolean;
+  recurringEnabled: boolean;             // автопродление
+  price: number;                         // рубли
+}
+```
+
+### PaymentMethod
+
+```ts
+interface PaymentMethod {
+  id: string;
+  last4?: string;
+  brand?: string;                        // 'visa' | 'mastercard' | 'mir'
+  isDefault?: boolean;
+  expiresAt?: IsoDate | null;
+}
+```
+
+### VerificationStatus
+
+```ts
+interface VerificationStatus {
+  status: 'none' | 'pending' | 'approved' | 'rejected' | (string & {});
+}
+```
+
+## Поиск и платформа
+
+### Hashtag
+
+```ts
+interface Hashtag {
+  id: string;
+  name: string;                          // без решётки
+  postsCount: number;
+}
+```
+
+### Report
+
+```ts
+interface Report { id: string; createdAt: IsoDate; }
+```
+
+### Portal
+
+```ts
+interface Portal { active: boolean; title: string; url: string; }
+```
+
+### ChangelogEntry
+
+```ts
+interface ChangelogEntry { version: string; date: string; changes: string[]; }
+```
+
+### Announcement
+
+```ts
+interface Announcement {
+  id: string;
+  image: { url: string; width: number; height: number };
+  title: string;
+  description: string;
+  additional_text?: string;
+  buttons: AnnouncementButton[];         // { title, style, action }
+}
+```
+
+### PlatformStatus
+
+```ts
+interface PlatformStatus {
+  overall_status: ServiceState;          // худшее среди сервисов
+  updated_at: IsoDate;
+  services: ServiceStatus[];
+}
+```
+
+### ServiceStatus
+
+```ts
+interface ServiceStatus {
+  id: string;                            // 'auth' | 'main' | 'media' | …
+  name: string;
+  current_status: ServiceState;
+  current_message: string;
+  latency_ms: number;
+  last_checked: IsoDate;                 // приведён к ISO
+  uptime_90d: number;                    // проценты
+  days: Record<string, StatusDay | undefined>;  // разреженный; ровный массив — statusDays()
+}
+```
+
+### StatusDay
+
+```ts
+interface StatusDay {
+  type: ServiceState;                    // худшее состояние за сутки
+  date_key: string;                      // YYYY-MM-DD, нарезка по UTC
+  uptime: number;
+  lines: StatusIncidentLine[];           // { t: IncidentKind; text } — text готов к показу, время МСК
+}
+```
+
+## Вспомогательные функции
+
+Экспортируются из корня пакета:
+
+```ts
+toDate(value: IsoDate | null | undefined): Date | null
+```
+Разбирает дату API в `Date`; `null`, если строки нет или она не разбирается.
+
+```ts
+statusDays(service: ServiceStatus): (StatusDay | null)[]
+```
+Разворачивает разреженную историю сервиса в массив на 90 суток. Индекс — сколько суток назад,
+`[0]` — сегодня, пропуски равны `null`.
+
+```ts
+isMyProfile(profile: Profile): profile is MyProfile
+```
+Свой ли это профиль.

package/guides/reference/notifications.md

@@ -0,0 +1,77 @@
+# Уведомления — `itd.notifications`
+
+Список, счётчик, отметки о прочтении и настройки. Все уведомления приведены к единой форме,
+поэтому объекты отсюда и из [потока](./realtime.md) можно складывать в один список. См.
+[`Notification`](./models.md#notification), [`NotificationType`](./enums.md#notificationtype).
+
+## Список
+
+```ts
+list(params?: NotificationListParams): Promise<Page<Notification>>
+iterate(params?: NotificationListParams): Paginator<Notification>
+```
+Страница уведомлений / перебор. Пагинация по смещению (`offset` / `nextOffset`).
+
+```ts
+count(): Promise<number>
+```
+Число непрочитанных уведомлений.
+
+## Отметки о прочтении
+
+```ts
+markRead(notificationId: string): Promise<number>
+```
+Отмечает одно уведомление прочитанным. Возвращает, сколько записей отметил сервер.
+
+```ts
+markReadBatch(ids: string[]): Promise<number>
+```
+Отмечает несколько. Список автоматически режется на части по 20 идентификаторов, части уходят
+последовательно, результат суммируется.
+
+```ts
+markAllRead(): Promise<number>
+```
+Отмечает прочитанными все уведомления.
+
+## Настройки
+
+```ts
+getSettings(): Promise<NotificationSettings>
+updateSettings(input: UpdateNotificationSettingsInput): Promise<NotificationSettings>
+```
+Читает / обновляет настройки. Отправляются только изменяемые поля. Отсутствующая настройка
+считается включённой. См. [`NotificationSettings`](./models.md#notificationsettings).
+
+## Типы
+
+```ts
+interface NotificationListParams extends RequestOptions {
+  limit?: number;
+  offset?: number;                       // смещение от начала списка
+  maxPages?: number;
+}
+
+type UpdateNotificationSettingsInput = Partial<NotificationSettings>;
+```
+
+## Вспомогательные функции
+
+Экспортируются из корня пакета, работают с любым `Notification`:
+
+```ts
+formatNotificationText(notification: Notification): string
+```
+Готовый текст: «Аня и ещё 2 оценили ваш пост».
+
+```ts
+resolveNotificationUrl(notification: Notification): string | null
+```
+Ссылка перехода: `/@anya/post/9f1c…`. Обычно точнее серверного `clickUrl`.
+
+```ts
+canonicalNotificationType(rawType: string): NotificationType
+isKnownNotificationType(type: string): boolean
+```
+Приведение серверного имени типа к каноническому и проверка известности.

package/guides/reference/pagination.md

@@ -0,0 +1,82 @@
+# Пагинация — `Page<T>`, `Paginator<T>`
+
+Три разные схемы API (курсор, страницы, смещение) приведены к одной форме. Методы-списки идут
+парами: `list()` и подобные возвращают одну `Page<T>`, а `iterate()` и подобные — `Paginator<T>`
+для `for await`.
+
+## `Page<T>`
+
+Одна страница. Какие необязательные поля заполнены — зависит от эндпоинта.
+
+```ts
+interface Page<T> {
+  items: T[];
+  hasMore: boolean;
+  nextCursor?: string | null;            // курсорная схема (лента, хэштеги, комментарии к посту)
+  page?: number;                         // постраничная схема (ответы, списки пользователей)
+  limit?: number;
+  total?: number;                        // если сервер сообщил
+  nextOffset?: number;                   // схема со смещением (уведомления)
+  raw: unknown;                          // исходный ответ
+}
+```
+
+Курсор **непрозрачен**: у вкладки `popular` это номер страницы, у `following` — отметка
+времени. Передавайте его обратно как есть.
+
+## `Paginator<T>`
+
+Перебор страниц. Реализует `AsyncIterable<T>` — годится для `for await`. **Одноразовый**:
+позиция хранится внутри, второй проход по тому же объекту ничего не выдаст.
+
+```ts
+[Symbol.asyncIterator](): AsyncGenerator<T>   // for await (const item of paginator)
+```
+Перебирает элементы всех страниц подряд.
+
+```ts
+pages(): AsyncGenerator<Page<T>>
+```
+Перебирает страницы целиком — когда нужны сведения о самой странице (`total`, `page`).
+
+```ts
+next(): Promise<Page<T> | null>
+```
+Загружает следующую страницу или `null`, если перебор закончен.
+
+```ts
+collect(max?: number): Promise<T[]>
+```
+Собирает элементы в массив. `max` — сколько достаточно (можно остановиться раньше конца).
+
+```ts
+// пример форм
+for await (const post of itd.posts.iterate({ tab: 'popular' })) { … }
+for await (const page of itd.posts.iterateComments(postId).pages()) { page.total; }
+const first100 = await itd.posts.iterate({ tab: 'popular' }).collect(100);
+```
+
+## Ограничение числа страниц
+
+Параметры-списки принимают `maxPages` — предохранитель от бесконечного перебора (по умолчанию
+1000). Перебор также сам останавливается на пустой странице, неизменившемся или отсутствующем
+курсоре.
+
+## Схемы
+
+```ts
+const PaginationMode = { Cursor: 'cursor', Page: 'page', Offset: 'offset' } as const;
+```
+
+| Схема | Эндпоинты | Позиция |
+|---|---|---|
+| `Cursor` | лента, стена, лайки, посты по хэштегу, комментарии к посту | `cursor` / `nextCursor` |
+| `Page` | подписчики, подписки, заблокированные, ответы на комментарий | `page` |
+| `Offset` | уведомления | `offset` / `nextOffset` |
+
+## Вспомогательное
+
+```ts
+mapPage<T, R>(page: Page<T>, map: (item: T) => R): Page<R>
+```
+Преобразует элементы страницы, сохраняя сведения о пагинации.

package/guides/reference/platform.md

@@ -0,0 +1,47 @@
+# Платформа — `itd.platform`
+
+Журнал изменений, анонсы, баннер события и статус сервисов. Авторизация этим методам не нужна.
+
+## Методы
+
+```ts
+changelog(): Promise<ChangelogEntry[]>
+```
+Журнал изменений платформы. См. [`ChangelogEntry`](./models.md#changelogentry).
+
+```ts
+announcements(): Promise<Announcement[]>
+```
+Анонсы на главной странице. См. [`Announcement`](./models.md#announcement).
+
+```ts
+portal(): Promise<Portal>
+```
+Баннер текущего события — виджет «портал». См. [`Portal`](./models.md#portal). Также в
+[Поиск и обнаружение](./discovery.md).
+
+```ts
+status(): Promise<PlatformStatus>
+```
+Состояние сервисов за последние 90 суток. Идёт на отдельный хост `статус.итд.com` без
+авторизации, ответ кэшируется сервером на минуту. Работает из браузера напрямую (в отличие
+от остального API). См. [`PlatformStatus`](./models.md#platformstatus).
+
+## Статус: разбор истории
+
+История по суткам приходит разреженным объектом (`days: Record<string, StatusDay>`); сутки
+без данных сервер пропускает. Ровный массив на 90 элементов даёт функция из корня пакета:
+
+```ts
+statusDays(service: ServiceStatus): (StatusDay | null)[]
+```
+Индекс — сколько суток назад: `[0]` — сегодня, пропуски равны `null`. См.
+[`ServiceStatus`](./models.md#servicestatus), [`StatusDay`](./models.md#statusday),
+[`ServiceState`](./enums.md#servicestate).
+
+```ts
+const status = await itd.platform.status();
+const auth = status.services.find((s) => s.id === 'auth');
+const days = auth ? statusDays(auth) : [];
+days[0]?.uptime;   // доступность за сегодня
+```