itd-api

Тема

itd-api / ItdClient

Class: ItdClient ​

Defined in: client.ts:120

Клиент API итд.com.

Методы сгруппированы по разделам: itd.posts, itd.users, itd.comments, itd.auth, itd.files. Авторизация, обновление токена, повторы и очередь запросов работают сами.

Examples ​

Готовый токен — для разового вызова

ts
const itd = new ItdClient({ auth: '<accessToken>' });
const me = await itd.users.me();

Полноценная сессия для бота

ts
import { ItdClient } from 'itd-api';
import { FileTokenStorage } from 'itd-api/node';

const itd = new ItdClient({
  // `auth` не обязателен: когда хранилище уже содержит сессию, токен берётся оттуда,
  // а истёкший продлевается сам. Здесь он нужен на первый запуск.
  auth: { email, password },
  // Капчу входа решает пакет @itd-api/captcha — см. CaptchaSolver.
  captcha: createCaptchaSolver(),
  storage: new FileTokenStorage('./.itd-session.json'),
  rateLimit: { concurrency: 4, rps: 8 },
});

for await (const post of itd.posts.iterate({ tab: 'following' })) {
  if (!post.isLiked) await itd.posts.like(post.id);
}

Constructors ​

Constructor ​

ts
new ItdClient(options?): ItdClient;

Defined in: client.ts:205

Parameters ​

options? ​

ItdClientOptions = {}

Returns ​

ItdClient

Accessors ​

auth ​

Get Signature ​

ts
get auth(): AuthResource;

Defined in: client.ts:132

Авторизация, сессии и пароли.

Returns ​

AuthResource

baseUrl ​

Get Signature ​

ts
get baseUrl(): string;

Defined in: client.ts:287

Базовый URL, к которому обращается клиент.

Returns ​

string

comments ​

Get Signature ​

ts
get comments(): CommentsResource;

Defined in: client.ts:151

Ответы на комментарии и действия над ними.

Returns ​

CommentsResource

files ​

Get Signature ​

ts
get files(): FilesResource;

Defined in: client.ts:156

Загрузка файлов и медиа.

Returns ​

FilesResource

hashtags ​

Get Signature ​

ts
get hashtags(): HashtagsResource;

Defined in: client.ts:166

Хэштеги и посты по ним.

Returns ​

HashtagsResource

notifications ​

Get Signature ​

ts
get notifications(): NotificationsApi;

Defined in: client.ts:161

Уведомления: список, счётчик, отметки о прочтении, настройки.

Returns ​

NotificationsApi

platform ​

Get Signature ​

ts
get platform(): PlatformResource;

Defined in: client.ts:191

Сведения о платформе: версии приложений, изменения, анонсы, баннер события.

Returns ​

PlatformResource

posts ​

Get Signature ​

ts
get posts(): PostsResource;

Defined in: client.ts:146

Лента, публикация, реакции, репосты, комментарии к постам.

Returns ​

PostsResource

reports ​

Get Signature ​

ts
get reports(): ReportsResource;

Defined in: client.ts:176

Жалобы на контент и пользователей.

Returns ​

ReportsResource

Get Signature ​

ts
get search(): SearchResource;

Defined in: client.ts:171

Глобальный поиск по пользователям и хэштегам.

Returns ​

SearchResource

shop ​

Get Signature ​

ts
get shop(): ShopResource;

Defined in: client.ts:201

Каталог, доставка и заказы магазина ИТД.

Returns ​

ShopResource

subscription ​

Get Signature ​

ts
get subscription(): SubscriptionResource;

Defined in: client.ts:186

Подписка и способы оплаты.

Returns ​

SubscriptionResource

telemetry ​

Get Signature ​

ts
get telemetry(): TelemetryResource;

Defined in: client.ts:196

Телеметрия просмотров.

Returns ​

TelemetryResource

users ​

Get Signature ​

ts
get users(): UsersResource;

Defined in: client.ts:141

Профили, подписки, блокировки, приватность.

Returns ​

UsersResource

verification ​

Get Signature ​

ts
get verification(): VerificationResource;

Defined in: client.ts:181

Верификация профиля.

Returns ​

VerificationResource

Methods ​

[asyncDispose]() ​

ts
asyncDispose: Promise<void>;

Defined in: client.ts:584

Позволяет использовать клиент с await using.

Returns ​

Promise<void>

close() ​

ts
close(): Promise<void>;

Defined in: client.ts:506

Освобождает ресурсы клиента: закрывает все потоки уведомлений, отправляет открытые накопители telemetry, затем останавливает очередь запросов.

Метод дожидается завершения активных обработчиков и освобождения ресурсов остановленных событийных соединений, но не дольше shutdownTimeout. После вызова клиентом можно пользоваться снова; ранее созданный поток можно запустить повторным connect().

Общая очередь, полученная от ItdAccounts, не останавливается: её гасит сам контейнер, когда закрывает все аккаунты разом.

Терминальное освобождение — это dispose.

Returns ​

Promise<void>

Throws ​

если остановка событийного соединения не завершилась за отведённый срок

defineService() ​

ts
defineService(definition): this;

Defined in: client.ts:457

Регистрирует сервис платформы — домен, отличный от основного.

Запросы с { service: 'имя' } уходят на его хост с его заголовками. То же самое умеет опция services конструктора. Занятое имя не переопределяется — ни своё, ни встроенное: разовому запросу хост задаётся полем baseUrl.

Заголовок авторизации по умолчанию уходит только своим — домену клиента и его поддоменам. Стороннему хосту токен нужно разрешить явно: auth: true.

Parameters ​

definition ​

ServiceDefinition

Returns ​

this

Throws ​

если определение неверно или имя уже занято

Throws ​

если клиент уже освобождён через dispose

Example ​

Сервис платформы на поддомене — токен уходит сам

ts
itd.defineService({
  name: 'pb',
  baseUrl: 'https://pbapi.xn--d1ah4a.com',
  headers: { Referer: 'https://pixel.xn--d1ah4a.com/' },
});

await itd.request({ method: 'GET', service: 'pb', path: '/api/pixel-info' });

dispose() ​

ts
dispose(): Promise<void>;

Defined in: client.ts:555

Окончательно освобождает клиент: выполняет close, отменяет незавершённые запросы и отключает все плагины.

Терминальное состояние устанавливается сразу при первом вызове. После этого новые запросы, подключение плагинов, регистрация сервисов и создание или повторный запуск событийных каналов завершаются с ItdStateError. Повторные вызовы возвращают тот же результат очистки.

Ожидание остановки событийных соединений и операций плагинов ограничено shutdownTimeout.

Returns ​

Promise<void>

Example ​

ts
await using itd = new ItdClient({ auth: token });
// …работа…
// dispose() вызовется сам на выходе из блока

featureNames() ​

ts
featureNames(): string[];

Defined in: client.ts:370

Имена установленных модулей в порядке установки.

Returns ​

string[]

getSession() ​

ts
getSession(): Promise<ItdSession | null>;

Defined in: client.ts:593

Текущая сессия целиком — чтобы сохранить её самостоятельно.

Returns ​

Promise<ItdSession | null>

getUserId() ​

ts
getUserId(): Promise<string | undefined>;

Defined in: client.ts:615

Идентификатор аккаунта, под которым работает клиент.

Читается из токена доступа и не стоит ни одного запроса. undefined, когда сессии ещё нет или токен выдан не в формате JWT. Полезен прежде всего с ItdAccounts: показывает, какому профилю соответствует восстановленная из хранилища запись. Свежий профиль целиком отдаёт itd.users.me().

Returns ​

Promise<string | undefined>

Remarks ​

JWT только декодируется: его подпись не проверяется. Результат подходит для локального разделения состояния, но не доказывает личность пользователя и не заменяет проверку авторизации сервером.

Example ​

ts
for (const [name, itd] of accounts) console.log(name, await itd.getUserId());

hasFeature() ​

ts
hasFeature(name): boolean;

Defined in: client.ts:375

Установлен ли модуль с таким именем.

Parameters ​

name ​

string

Returns ​

boolean

hasPlugin() ​

ts
hasPlugin(name): boolean;

Defined in: client.ts:416

Подключён ли плагин с таким именем.

Parameters ​

name ​

string

Returns ​

boolean

install() ​

ts
install<TApi>(feature): TApi;

Defined in: client.ts:334

Устанавливает предметный модуль с общей сессией и обработкой запросов клиента.

Сервисы, операции и бакеты регистрируются до синхронного setup(). Возвращает типизированный API модуля.

Type Parameters ​

TApi ​

TApi

Parameters ​

feature ​

ClientFeature<TApi>

Returns ​

TApi

on() ​

ts
on<K>(event, listener): Unsubscribe;

Defined in: client.ts:486

Подписывается на события авторизации.

Полезно, чтобы сохранять сессию во внешнее хранилище или узнавать, что вход окончательно потерян.

Type Parameters ​

K ​

K extends keyof AuthEvents

Parameters ​

event ​

K

listener ​

Listener<AuthEvents[K]>

Returns ​

Unsubscribe

функция отписки

Example ​

ts
itd.on('tokens', ({ accessToken }) => cache.set('itd', accessToken));
itd.on('authError', () => notifyUser('Сессия истекла, войдите заново'));

pluginNames() ​

ts
pluginNames(): string[];

Defined in: client.ts:411

Имена подключённых плагинов в фактическом порядке выполнения обёрток.

Returns ​

string[]

rateLimitState() ​

ts
rateLimitState(): RateLimitBucketState[];

Defined in: client.ts:324

Остаток серверных лимитов по бакетам, через которые уже проходили запросы.

Значения берутся из последнего ответа каждого бакета и быстро устаревают: сервер восстанавливает квоту линейно и границу окна не сообщает. Пустой массив при rateLimit: false. close снимок сохраняет, dispose очищает.

Returns ​

RateLimitBucketState[]

Example ​

ts
const posts = itd.rateLimitState().find((state) => state.bucket === 'posts.create');
if ((posts?.remaining ?? Number.POSITIVE_INFINITY) < 3) await sleep(60_000);

request() ​

ts
request<T>(options): Promise<T>;

Defined in: client.ts:304

Выполняет произвольный запрос к API.

Запасной путь для случаев, когда нужного метода ещё нет или ответ сервера разошёлся с документацией. Проходит через ту же авторизацию, очередь и обработку ошибок.

Type Parameters ​

T ​

T = unknown

Parameters ​

options ​

RawRequestOptions

Returns ​

Promise<T>

Example ​

ts
const raw = await itd.request({ method: 'GET', path: '/api/posts', raw: true });

Throws ​

если клиент уже освобождён через dispose

serviceBaseUrl() ​

ts
serviceBaseUrl(name): string;

Defined in: client.ts:468

Базовый URL зарегистрированного сервиса.

Parameters ​

name ​

string

Returns ​

string

Throws ​

если сервис не зарегистрирован

setSession() ​

ts
setSession(session): Promise<void>;

Defined in: client.ts:624

Восстанавливает сохранённую сессию, включая cookie.

Parameters ​

session ​

ItdSession

Returns ​

Promise<void>

Throws ​

если клиент уже освобождён через dispose

unuse() ​

ts
unuse(name): Promise<boolean>;

Defined in: client.ts:429

Отключает плагин и освобождает заведённые им ресурсы.

Новые запросы перестают видеть плагин сразу. Очистка дождётся логического запроса, который уже проходил через его обёртку.

Parameters ​

name ​

string

Returns ​

Promise<boolean>

false, если такого плагина не было

Throws ​

если от плагина зависит другой подключённый плагин

use() ​

ts
use(plugin): this;

Defined in: client.ts:399

Подключает плагин.

Плагин может регистрировать обёртки операций и перехватчики сетевых попыток.

Parameters ​

plugin ​

ClientPlugin

Returns ​

this

Throws ​

если плагин задан неверно или уже подключён

Throws ​

если клиент уже освобождён через dispose

Example ​

ts
import { crypt } from '@itd-api/crypto';

itd.use(crypt());
await itd.posts.create({
  content: 'секрет',
}, {
  extensions: { crypto: { encrypt: 'invisible' } },
});

withFeature() ​

ts
withFeature<K, TApi>(key, feature): ItdClient & { readonly [P in string]: TApi };

Defined in: client.ts:344

Устанавливает модуль и добавляет его API в свойство клиента только для чтения.

Возвращаемое пересечение сохраняет тип уже подключённых свойств, поэтому вызовы можно объединять в цепочку: new ItdClient().withFeature('pixelBattle', pixelBattleFeature).

Type Parameters ​

K ​

K extends string

TApi ​

TApi

Parameters ​

key ​

K

feature ​

ClientFeature<TApi>

Returns ​

ItdClient & { readonly [P in string]: TApi }

Документация itd-api

MIT License