itd-api 0.0.11 → 0.2.0

package/guides/plugins/README.md

@@ -1,162 +0,0 @@
-# Плагины
-
-Плагин расширяет клиент обёртками вокруг запросов и ответов. Одна установка действует на
-все ресурсы:
-
-```ts
-import { ItdClient } from 'itd-api';
-import { crypt } from '@itd-api/crypto';
-
-const itd = new ItdClient({ auth: token });
-itd.use(crypt());
-```
-
-## Cache
-
-```bash
-npm install @itd-api/cache
-```
-
-```ts
-import { cache } from '@itd-api/cache';
-
-const cached = cache({
-  ttl: 60_000,
-  routes: ['users.get', 'posts.get', 'posts.list'],
-});
-
-itd.use(cached);
-```
-
-Плагин хранит успешные ответы в LRU-кэше и объединяет одновременные одинаковые запросы.
-Маршруты выбираются явно; после мутаций связанные данные инвалидируются автоматически.
-У каждого клиента и аккаунта свой раздел кэша, а изменения общих сущностей сбрасывают
-соответствующие маршруты во всех разделах.
-
-```ts
-await itd.posts.get(postId, { cache: 'reload' });
-cached.invalidate('posts.get');
-```
-
-Полный каталог маршрутов, подключение к нескольким клиентам и привязка к realtime описаны в
-[README пакета](../../cache/README.md).
-
-Запускаемый пример:
-
-```bash
-ITD_TOKEN=<accessToken> ITD_POST_ID=<postId> \
-  node guides/plugins/examples/cache.mjs
-```
-
-## Crypto
-
-```bash
-npm install @itd-api/crypto
-```
-
-```ts
-import { crypt } from '@itd-api/crypto';
-
-itd.use(crypt());
-
-const created = await itd.posts.create(
-  { content: 'секретный текст' },
-  { encrypt: { cipher: 'invisible', cover: 'обычный пост' } },
-);
-
-const post = await itd.posts.get(created.id);
-console.log(post.content);      // обложка
-console.log(post.secret?.text); // секретный текст
-```
-
-Плагин обрабатывает посты, комментарии, ответы и текстовые поля профиля. Доступны
-`invisible` и `beecrypt`; подробные ограничения описаны в README пакета.
-
-Запускаемый пример:
-
-```bash
-ITD_TOKEN=<accessToken> node guides/plugins/examples/crypto.mjs
-```
-
-## Собственный плагин
-
-```ts
-import type { ItdPlugin } from 'itd-api';
-
-const timing: ItdPlugin = {
-  name: 'timing',
-  install({ use, logger }) {
-    use(async (request, next) => {
-      const started = Date.now();
-      try {
-        return await next(request);
-      } finally {
-        logger?.info(`${request.method} ${request.path}: ${Date.now() - started} мс`);
-      }
-    });
-  },
-};
-
-itd.use(timing);
-```
-
-Обёртка может:
-
-- передать в `next()` изменённую копию запроса;
-- изменить полученный ответ;
-- вернуть результат без обращения к сети;
-- выбросить собственную ошибку.
-
-Подключённая раньше обёртка оказывается снаружи. Она выполняется один раз на логический
-запрос, независимо от внутренних повторов транспорта.
-
-## Собственные опции метода
-
-Плагин объявляет разрешённые ключи:
-
-```ts
-const plugin: ItdPlugin = {
-  name: 'мой',
-  optionKeys: ['мояОпция'],
-  install({ use }) {
-    use(async (request, next) => {
-      console.log(request.мояОпция);
-      return next(request);
-    });
-  },
-};
-
-declare module 'itd-api' {
-  interface RequestOptions {
-    мояОпция?: string | undefined;
-  }
-}
-```
-
-Ключи самого запроса — `path`, `body`, `headers`, `signal` и другие системные поля —
-зарезервированы. Плагин с конфликтующим `optionKeys` отклоняется при подключении.
-
-## Несколько аккаунтов
-
-```ts
-accounts.use(plugin);
-```
-
-Плагин установится всем существующим аккаунтам и будет автоматически применяться к новым.
-
-## Структура нового плагина
-
-Структура пакета плагина:
-
-```text
-my-plugin/
-├── package.json
-├── README.md
-├── src/
-│   └── index.ts
-└── test/
-    └── plugin.test.ts
-```
-
-Пакет должен иметь собственные тесты, сборку и экспортировать фабрику либо объект,
-совместимый с `ItdPlugin`.

package/guides/plugins/examples/cache.mjs

@@ -1,33 +0,0 @@
-/**
- * Запуск:
- *   ITD_TOKEN=<accessToken> ITD_POST_ID=<postId> \
- *     node guides/plugins/examples/cache.mjs
- */
-
-import { cache } from '@itd-api/cache';
-import { ItdClient } from 'itd-api';
-
-const token = process.env.ITD_TOKEN;
-const postId = process.env.ITD_POST_ID;
-
-if (!token || !postId) {
-  throw new Error('Передайте ITD_TOKEN и ITD_POST_ID');
-}
-
-const itd = new ItdClient({ auth: token });
-const cached = cache({
-  ttl: 60_000,
-  routes: ['posts.get', 'users.get'],
-});
-
-itd.use(cached);
-
-try {
-  const first = await itd.posts.get(postId);
-  const second = await itd.posts.get(postId);
-
-  console.log(first.content);
-  console.log(`Повторный ответ получен из кэша: ${first.id === second.id}`);
-} finally {
-  await itd.close();
-}

package/guides/plugins/examples/crypto.mjs

@@ -1,54 +0,0 @@
-/**
- * Скрытое сообщение в обычном посте.
- *
- * Запуск:
- *   ITD_TOKEN=<accessToken> node guides/plugins/examples/crypto.mjs
- *
- * Плагин лежит в отдельном пакете — основному он не нужен:
- *
- *   npm i @itd-api/crypto
- *
- * Пример публикует пост, читает его обратно **с сервера** и сравнивает результат.
- * Смысл именно в обратном чтении: сервер итд.com нормализует текст поста при сохранении,
- * и проверить, что нагрузка это пережила, можно только на живом API.
- */
-
-import { ItdClient, isItdApiError } from 'itd-api';
-import { crypt, stripInvisible } from '@itd-api/crypto';
-
-const COVER = 'обычный пост, ничего необычного';
-const SECRET = 'секретный текст: 🦎 привет из @itd-api/crypto';
-
-const itd = new ItdClient({ auth: process.env.ITD_TOKEN });
-
-// Одна строка — и шифрование доступно во всех методах, принимающих текст.
-itd.use(crypt());
-
-try {
-  const created = await itd.posts.create(
-    { content: SECRET },
-    { encrypt: { cipher: 'invisible', cover: COVER } },
-  );
-  console.log(`Опубликован пост ${created.id}`);
-
-  // Читаем с сервера, а не берём ответ на публикацию: интересно именно то,
-  // что сохранилось после нормализации.
-  const post = await itd.posts.get(created.id);
-
-  console.log(`Видят все:  ${stripInvisible(post.content)}`);
-  console.log(`Спрятано:   ${post.secret?.text ?? '— ничего не нашлось —'}`);
-  console.log(`Длина:      ${post.content.length} символов вместо ${COVER.length}`);
-
-  console.log(
-    post.secret?.text === SECRET
-      ? '✔ сообщение пережило сохранение на сервере'
-      : '✘ сообщение потерялось — формат разошёлся с тем, что делает сервер',
-  );
-
-  // Прибираем за собой: пост нужен был только для проверки.
-  await itd.posts.remove(created.id);
-  console.log('Пост удалён');
-} catch (error) {
-  console.error(isItdApiError(error) ? `${error.code}: ${error.message}` : error);
-  process.exitCode = 1;
-}

package/guides/quickstart/README.md

@@ -1,124 +0,0 @@
-# Быстрый старт
-
-## Установка
-
-```bash
-npm install itd-api
-```
-
-Пакет поддерживает ESM и CommonJS, Node 18+, браузер, Bun, Deno и React Native.
-
-## Создание клиента
-
-```ts
-import { FeedTab, ItdClient } from 'itd-api';
-
-const itd = new ItdClient({
-  auth: process.env.ITD_TOKEN,
-});
-
-const me = await itd.users.me();
-console.log(`@${me.username}, подписчиков: ${me.followersCount}`);
-
-for await (const post of itd.posts.iterate({ tab: FeedTab.Following })) {
-  console.log(post.author.username, post.content);
-  if (!post.isLiked) await itd.posts.like(post.id);
-}
-```
-
-Для загрузки файлов по пути и файлового хранилища сессии используйте Node-вход:
-
-```ts
-import { FileTokenStorage, ItdClient } from 'itd-api/node';
-
-const itd = new ItdClient({
-  storage: new FileTokenStorage('./.itd-session.json'),
-});
-
-await itd.posts.create((p) =>
-  p.content('привет').attach('./photo.jpg'),
-);
-```
-
-## Публикация
-
-Методы принимают обычный объект, готовый билдер или функцию-настройщик:
-
-```ts
-import { post } from 'itd-api';
-
-await itd.posts.create({ content: 'привет' });
-
-await itd.posts.create((p) =>
-  p
-    .content('смотрите')
-    .attach('./photo.jpg')
-    .poll((q) => q.question('нравится?').options('да', 'нет')),
-);
-
-const draft = post().onWall(userId);
-await itd.posts.create(draft.content('первый'));
-await itd.posts.create(draft.content('второй'));
-```
-
-Билдеры неизменяемые, а `build()` проверяет данные до обращения к сети.
-
-## Пагинация
-
-```ts
-for await (const post of itd.posts.iterate({ tab: 'popular' })) {
-  console.log(post.id);
-}
-
-const page = await itd.posts.list({ tab: 'popular', limit: 20 });
-const next = await itd.posts.list({
-  tab: 'popular',
-  cursor: page.nextCursor ?? undefined,
-});
-```
-
-Курсор непрозрачен — передавайте его обратно без разбора. Итератор одноразовый; для второго
-прохода создайте новый.
-
-## Ошибки
-
-```ts
-import {
-  ItdRateLimitError,
-  ItdValidationError,
-  isItdApiError,
-} from 'itd-api';
-
-try {
-  await itd.users.updateMe({ username: 'занятое_имя' });
-} catch (error) {
-  if (error instanceof ItdValidationError) {
-    console.error(error.fieldErrors);
-  } else if (error instanceof ItdRateLimitError) {
-    console.error(error.retryAfter);
-  } else if (isItdApiError(error)) {
-    console.error(error.status, error.code, error.message);
-  } else {
-    throw error;
-  }
-}
-```
-
-## Куда дальше
-
-- [Авторизация и сессии](../authentication/README.md)
-- [Разметка текста](../text-markup/README.md)
-- [Realtime](../realtime/README.md)
-- [Несколько аккаунтов](../multi-accounts/README.md)
-- [Интеграции](../integrations/README.md)
-- [Плагины](../plugins/README.md)
-
-## Примеры
-
-```bash
-ITD_TOKEN=<accessToken> node guides/quickstart/examples/quick-start.mjs
-npx tsx guides/quickstart/examples/typescript.ts
-```
-
-- [`examples/quick-start.mjs`](./examples/quick-start.mjs) — профиль и чтение ленты.
-- [`examples/typescript.ts`](./examples/typescript.ts) — типы, билдеры, пагинация и ошибки.

package/guides/quickstart/examples/quick-start.mjs

@@ -1,44 +0,0 @@
-/**
- * Быстрый старт: чтение ленты и реакция на пост.
- *
- * Запуск:
- *   ITD_TOKEN=<ваш accessToken> node guides/quickstart/examples/quick-start.mjs
- *
- * Где взять токен: откройте итд.com, войдите, затем в консоли браузера выполните
- * запрос к /api/v1/auth/refresh — либо воспользуйтесь руководством по авторизации.
- */
-
-import { FeedTab, ItdClient, isItdApiError } from 'itd-api';
-
-const itd = new ItdClient({
-  // Опции допускают undefined, поэтому переменную окружения можно передавать напрямую.
-  auth: process.env.ITD_TOKEN,
-});
-
-try {
-  const me = await itd.users.me();
-  console.log(`Вы вошли как ${me.displayName} (@${me.username})`);
-  console.log(`Подписчиков: ${me.followersCount}, записей: ${me.postsCount}\n`);
-
-  // Одна страница ленты.
-  const page = await itd.posts.list({ tab: FeedTab.Popular, limit: 5 });
-
-  for (const post of page.items) {
-    const text = post.content.slice(0, 60).replace(/\n/g, ' ');
-    console.log(`${post.author.avatar} @${post.author.username}: ${text}`);
-    console.log(`   ❤ ${post.likesCount}  💬 ${post.commentsCount}  🔁 ${post.repostsCount}`);
-  }
-
-  // Перебор нескольких страниц: курсоры подставляются сами.
-  console.log('\nПервые 12 записей из подписок:');
-
-  const posts = await itd.posts.iterate({ tab: FeedTab.Following }).collect(12);
-  console.log(`получено ${posts.length}`);
-} catch (error) {
-  if (isItdApiError(error)) {
-    console.error(`Ошибка API [${error.code}] ${error.status}: ${error.message}`);
-    if (Object.keys(error.fieldErrors).length > 0) console.error(error.fieldErrors);
-  } else {
-    throw error;
-  }
-}

package/guides/quickstart/examples/typescript.ts

@@ -1,90 +0,0 @@
-/**
- * TypeScript: типы, билдеры и разбор ошибок.
- *
- * Запуск:
- *   npx tsx guides/quickstart/examples/typescript.ts
- */
-
-import {
-  FeedTab,
-  ItdClient,
-  ItdValidationError,
-  type Notification,
-  type Post,
-  ReportReason,
-  isItdApiError,
-  ItdErrorCode,
-  ItdRateLimitError,
-  poll,
-  post,
-  report,
-} from 'itd-api';
-
-const itd = new ItdClient({ auth: process.env.ITD_TOKEN });
-
-// ── Перечисления вместо магических строк ────────────────────────────────────────
-// Работают обе формы: константа и обычная строка.
-await itd.posts.list({ tab: FeedTab.Popular });
-await itd.posts.list({ tab: 'following' });
-
-// ── Заготовки билдеров переиспользуются ─────────────────────────────────────────
-// Билдер неизменяемый, поэтому заготовку не испортить.
-const draft = post().content('черновик');
-
-const first: Post = await itd.posts.create(draft.append('первая версия'));
-const second: Post = await itd.posts.create(draft.append('вторая версия'));
-console.log(first.id, second.id);
-
-// Опрос можно собрать заранее и передать в несколько записей.
-const survey = poll('Какой язык удобнее?').options('TypeScript', 'JavaScript').multipleChoice();
-await itd.posts.create({ content: 'голосуем', poll: survey });
-
-// ── Пагинация: три способа ──────────────────────────────────────────────────────
-// По элементам.
-for await (const item of itd.posts.iterate({ tab: FeedTab.Popular })) {
-  console.log(item.content);
-  break;
-}
-
-// По страницам — когда нужны сведения о самой странице.
-for await (const page of itd.users.iterateFollowers('durov').pages()) {
-  console.log(`${page.items.length} из ${page.total ?? '?'}`);
-  break;
-}
-
-// Собрать нужное количество и остановиться.
-const top: Post[] = await itd.posts.iterate({ tab: FeedTab.Popular }).collect(50);
-console.log(`собрано ${top.length}`);
-
-// ── Разбор ошибок ───────────────────────────────────────────────────────────────
-try {
-  await itd.users.updateMe({ username: 'занятое_имя' });
-} catch (error) {
-  if (error instanceof ItdValidationError) {
-    // Обе формы ошибок API сведены к одной структуре.
-    for (const [field, messages] of Object.entries(error.fieldErrors)) {
-      console.error(`${field}: ${messages.join(', ')}`);
-    }
-  } else if (error instanceof ItdRateLimitError) {
-    console.error(`Лимит запросов, повтор через ${error.retryAfter ?? '?'} мс`);
-  } else if (isItdApiError(error) && error.hasCode(ItdErrorCode.PROFILE_USERNAME_TAKEN)) {
-    console.error('Имя уже занято');
-  } else {
-    throw error;
-  }
-}
-
-// ── Стена другого пользователя требует UUID ─────────────────────────────────────
-// Проверка сработает до обращения к сети и подскажет, где взять идентификатор.
-const target = await itd.users.get('durov');
-await itd.posts.create((p) => p.content('привет!').onWall(target.id));
-
-// ── Жалоба: тип объекта и его идентификатор нельзя рассогласовать ───────────────
-await itd.reports.create(report.post(first.id).reason(ReportReason.Spam));
-
-// ── Уведомления из REST и из потока имеют одну форму ────────────────────────────
-const feed: Notification[] = (await itd.notifications.list({ limit: 10 })).items;
-
-const stream = itd.realtime();
-stream.on('notification', ({ notification }) => feed.unshift(notification));
-await stream.connect();

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);
-});