itd-api / ItdClient

Class: ItdClient

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

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

Examples

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

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

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

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

const itd = new ItdClient({
  // `auth` не обязателен: когда хранилище уже содержит сессию, токен берётся оттуда,
  // а истёкший продлевается сам. Здесь он нужен на первый запуск.
  // Вход по паролю требует токена капчи — см. AuthInput и TURNSTILE_SITE_KEY.
  auth: { email, password, getTurnstileToken },
  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

new ItdClient(options?, internals?): ItdClient;

Defined in: client.ts:148

Parameters

options?

ItdClientOptions = {}

internals?

ItdClientInternals = {}

Returns

ItdClient

Properties

auth

readonly auth: AuthResource;

Defined in: client.ts:122

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

comments

readonly comments: CommentsResource;

Defined in: client.ts:128

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

files

readonly files: FilesResource;

Defined in: client.ts:130

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

hashtags

readonly hashtags: HashtagsResource;

Defined in: client.ts:134

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

notifications

readonly notifications: NotificationsResource;

Defined in: client.ts:132

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

platform

readonly platform: PlatformResource;

Defined in: client.ts:144

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

posts

readonly posts: PostsResource;

Defined in: client.ts:126

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

reports

readonly reports: ReportsResource;

Defined in: client.ts:138

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

search

readonly search: SearchResource;

Defined in: client.ts:136

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

subscription

readonly subscription: SubscriptionResource;

Defined in: client.ts:142

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

telemetry

readonly telemetry: TelemetryResource;

Defined in: client.ts:146

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

users

readonly users: UsersResource;

Defined in: client.ts:124

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

verification

readonly verification: VerificationResource;

Defined in: client.ts:140

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

Accessors

baseUrl

Get Signature

get baseUrl(): string;

Defined in: client.ts:269

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

Returns

string

Methods

[asyncDispose]()

asyncDispose: Promise<void>;

Defined in: client.ts:483

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

Returns

Promise<void>

close()

close(): Promise<void>;

Defined in: client.ts:452

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

После вызова клиентом можно пользоваться снова — новые запросы поднимут всё заново, но уже созданные потоки и успешно закрытые накопители останутся закрытыми.

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

Returns

Promise<void>

Example

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

defineService()

defineService(definition): this;

Defined in: client.ts:361

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

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

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

Parameters

definition

ServiceDefinition

Returns

this

Throws

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

Example

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

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()

dispose(): Promise<void>;

Defined in: client.ts:468

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

В отличие от close(), после dispose() плагины не восстанавливаются автоматически. Сам клиент остаётся пригоден для обычных запросов; при необходимости плагины можно подключить заново через use.

Returns

Promise<void>

getSession()

getSession(): Promise<ItdSession | null>;

Defined in: client.ts:499

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

Returns

Promise<ItdSession | null>

getUserId()

getUserId(): Promise<string | undefined>;

Defined in: client.ts:521

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

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

Returns

Promise<string | undefined>

Remarks

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

Example

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

hasPlugin()

hasPlugin(name): boolean;

Defined in: client.ts:321

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

Parameters

name

string

Returns

boolean

on()

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

Defined in: client.ts:389

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

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

Type Parameters

K

K extends keyof AuthEvents

Parameters

event

K

listener

Listener<AuthEvents[K]>

Returns

Unsubscribe

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

Example

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

pluginNames()

pluginNames(): string[];

Defined in: client.ts:316

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

Returns

string[]

realtime()

realtime(options?): ItdRealtime;

Defined in: client.ts:412

Создаёт поток уведомлений в реальном времени.

Каждый вызов даёт новый независимый поток; обычно он нужен один на приложение. Соединение поднимается методом connect() и держится само. Замена авторизации на токен другого пользователя завершает все потоки клиента; смена только сессии их не затрагивает.

Parameters

options?

RealtimeOptions = {}

Returns

ItdRealtime

Example

const stream = itd.realtime();

stream.on('notification', ({ notification }) => {
  console.log(formatNotificationText(notification));
});
stream.on('unreadCount', (count) => setBadge(count));

await stream.connect();

request()

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

Defined in: client.ts:284

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

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

Type Parameters

T

T = unknown

Parameters

options

RawRequestOptions

Returns

Promise<T>

Example

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

serviceBaseUrl()

serviceBaseUrl(name): string;

Defined in: client.ts:371

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

Parameters

name

string

Returns

string

Throws

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

setSession()

setSession(session): Promise<void>;

Defined in: client.ts:526

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

Parameters

session

ItdSession

Returns

Promise<void>

unuse()

unuse(name): Promise<boolean>;

Defined in: client.ts:334

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

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

Parameters

name

string

Returns

Promise<boolean>

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

Throws

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

use()

use(plugin): this;

Defined in: client.ts:305

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

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

Parameters

plugin

ItdPlugin

Returns

this

Throws

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

Example

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

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

Class: ItdClient ​

Examples ​

Constructors ​

Constructor ​

Parameters ​

options? ​

internals? ​

Returns ​

Properties ​

auth ​

comments ​

files ​

hashtags ​

notifications ​

platform ​

posts ​

reports ​

search ​

subscription ​

telemetry ​

users ​

verification ​

Accessors ​

baseUrl ​

Get Signature ​

Returns ​

Methods ​

[asyncDispose]() ​

Returns ​

close() ​

Returns ​

Example ​

defineService() ​

Parameters ​

definition ​

Returns ​

Throws ​

Example ​

dispose() ​

Returns ​

getSession() ​

Returns ​

getUserId() ​

Returns ​

Remarks ​

Example ​

hasPlugin() ​

Parameters ​

name ​

Returns ​

on() ​

Type Parameters ​

K ​

Parameters ​

event ​

listener ​

Returns ​

Example ​

pluginNames() ​

Returns ​

realtime() ​

Parameters ​

options? ​

Returns ​

Example ​

request() ​

Type Parameters ​

T ​

Parameters ​

options ​

Returns ​

Example ​

serviceBaseUrl() ​

Parameters ​

name ​

Returns ​

Throws ​

setSession() ​

Parameters ​

session ​

Class: ItdClient

Examples

Constructors

Constructor

Parameters

options?

internals?

Returns

Properties

auth

comments

files

hashtags

notifications

platform

posts

reports

search

subscription

telemetry

users

verification

Accessors

baseUrl

Get Signature

Returns

Methods

[asyncDispose]()

Returns

close()

Returns

Example

defineService()

Parameters

definition

Returns

Throws

Example

dispose()

Returns

getSession()

Returns

getUserId()

Returns

Remarks

Example

hasPlugin()

Parameters

name

Returns

on()

Type Parameters

K

Parameters

event

listener

Returns

Example

pluginNames()

Returns

realtime()

Parameters

options?

Returns

Example

request()

Type Parameters

T

Parameters

options

Returns

Example

serviceBaseUrl()

Parameters

name

Returns

Throws

setSession()

Parameters

session