itd-api 0.1.0 → 0.2.0

package/guides/plugins/README.md

@@ -1,253 +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 tracing: ItdPlugin = {
-  name: 'tracing',
-  before: ['cache'],       // обёртка tracing снаружи cache
-  requires: ['transport'], // без transport подключение завершится ошибкой
-  conflicts: ['legacy-tracing'],
-  install({ use }) {
-    use((request, next) => next(request));
-  },
-};
-```
-
-- `before` ставит плагин снаружи названных;
-- `after` — внутри названных;
-- `requires` требует уже подключённый плагин и ставит его раньше зависимого;
-- `conflicts` запрещает совместное подключение, даже если конфликт объявлен только одной
-  стороной.
-
-Ссылки `before` и `after` на ещё не подключённый плагин допустимы: порядок перестроится,
-когда тот появится. Цикл отклоняется до вызова `install()`.
-
-Фактический порядок можно проверить:
-
-```ts
-itd.pluginNames();
-itd.hasPlugin('cache');
-```
-
-## Хуки отдельных попыток
-
-`use()` видит логический запрос один раз. Для метрик и трассировки есть `useHooks()`:
-
-```ts
-const telemetry: ItdPlugin = {
-  name: 'telemetry',
-  install({ useHooks }) {
-    useHooks({
-      onRequest({ method, path, attempt }) {
-        console.log(`попытка ${attempt}: ${method} ${path}`);
-      },
-      onResponse({ status, duration }) {
-        console.log(status, duration);
-      },
-      onError({ error, duration }) {
-        console.error(error, duration);
-      },
-      onRetry({ attempt, delay }) {
-        console.log(`после попытки ${attempt} ждём ${delay} мс`);
-      },
-    });
-  },
-};
-```
-
-Хуки, заданные в конструкторе `ItdClient`, вызываются раньше хуков плагинов. Исключение
-из хука прерывает запрос — плагину наблюдаемости лучше обрабатывать собственные ошибки
-внутри.
-
-## Отключение и очистка
-
-`install()` может вернуть синхронную или асинхронную функцию очистки:
-
-```ts
-const plugin: ItdPlugin = {
-  name: 'connection',
-  install({ use }) {
-    const connection = openConnection();
-    use((request, next) => next(request));
-
-    return () => connection.close();
-  },
-};
-
-itd.use(plugin);
-await itd.unuse('connection');
-```
-
-Новые запросы перестают видеть плагин сразу, а teardown ждёт завершения запроса, который
-уже проходит через его обёртку. Обязательную зависимость нельзя отключить раньше зависящего
-от неё плагина.
-
-`close()` по-прежнему временно останавливает очередь и realtime, не отключая плагины.
-`dispose()` делает окончательную очистку и вызывает teardown всех плагинов изнутри наружу.
-`await using` вызывает `dispose()` автоматически.
-
-## Собственные опции метода
-
-Плагин объявляет разрешённые ключи:
-
-```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);
-await accounts.unuse(plugin.name);
-```
-
-Плагин установится всем существующим аккаунтам и будет автоматически применяться к новым.
-`accounts.pluginNames()` и `accounts.hasPlugin()` описывают общий набор.
-
-## Структура нового плагина
-
-Структура пакета плагина:
-
-```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();