itd-api 0.1.0 → 0.2.0

package/guides/reference/models.md

@@ -1,448 +0,0 @@
-# Модели данных
-
-Формы объектов, которые возвращает 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

@@ -1,77 +0,0 @@
-# Уведомления — `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

@@ -1,82 +0,0 @@
-# Пагинация — `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

@@ -1,47 +0,0 @@
-# Платформа — `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;   // доступность за сегодня
-```