@tgio/sdk

TypeScript/JavaScript SDK для tgio.app API — полнофункциональный клиент для управления короткими ссылками, пикселями отслеживания, Telegram-каналами, тегами и многим другим.

Установка

npm install @tgio/sdk
# или
yarn add @tgio/sdk
# или
pnpm add @tgio/sdk

Быстрый старт

import { TgioClient } from '@tgio/sdk';

// Создаём клиент с API-токеном
const client = new TgioClient({
  token: 'tgio_sk_ваш_токен',
});

// Создаём короткую ссылку
const link = await client.links.create({
  url: 'https://example.com/product/123',
  title: 'Продвижение товара',
  utm_source: 'telegram',
  utm_medium: 'bot',
});

console.log(link.trackingUrl); // https://tgio.app/abc123

// Получаем статистику
const stats = await client.links.getStats(link.id, '30d');
console.log(`Клики: ${stats.totalClicks}, Уникальные: ${stats.uniqueClicks}`);

Модули API

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

Модуль	Свойство	Описание
Аутентификация	client.auth	Вход через Telegram initData или Login Widget
Ссылки	client.links	CRUD коротких ссылок + полная аналитика
Пиксели	client.pixels	CRUD пикселей отслеживания + аналитика
Каналы	client.channels	Аналитика Telegram-каналов (подписчики, посты, retention и др.)
Теги	client.tags	Организация ссылок и пикселей по тегам
API-токены	client.tokens	Управление токенами доступа
Аккаунт	client.account	Подписка, тарифы, настройки
Домены	client.domains	Кастомные домены для коротких ссылок
Трекинг	client.tracking	Мониторинг ключевых слов в Telegram
Secure Sharing	client.secure	Защищённый обмен файлами
Каталог	client.catalog	Каталог публичных каналов

Примеры

Управление ссылками

// Список всех ссылок
const links = await client.links.list();

// Список ссылок по тегам
const tagged = await client.links.list([1, 2, 3]);

// Создать ссылку с настройками
const link = await client.links.create({
  url: 'https://shop.example.com',
  title: 'Акция',
  expires_at: '2025-12-31T23:59:59Z',
  max_clicks: 1000,
  password: 'secret',
  ios_url: 'https://apps.apple.com/app/...',
  android_url: 'https://play.google.com/store/apps/details?id=...',
  domain_id: 5, // кастомный домен
  webhook_url: 'https://myserver.com/webhook',
});

// Обновить
await client.links.update(link.id, { title: 'Новое название', is_active: false });

// Удалить
await client.links.delete(link.id);

// Массовое создание (до 100 URL)
const bulk = await client.links.bulkCreate(['https://example.com/page1', 'https://example.com/page2']);

Аналитика ссылок

// Обзорная статистика
const stats = await client.links.getStats(linkId, '30d');

// Клики с пагинацией
const { clicks, total } = await client.links.getClicks(linkId, 1, 50);

// География
const geo = await client.links.getGeo(linkId, '7d');

// Устройства
const devices = await client.links.getDevices(linkId);

// Таймлайн
const timeline = await client.links.getTimeline(linkId, '7d', 'hourly', 'Europe/Moscow');

// Боты
const bots = await client.links.getBots(linkId);

// Тепловая карта
const heatmap = await client.links.getHeatmap(linkId, '30d');

// Экспорт в файл (отправится в Telegram-бот)
await client.links.export(linkId, 'xlsx', '30d');

Каналы

// Список каналов
const channels = await client.channels.list();

// Подписчики за 30 дней
const subs = await client.channels.getSubscribers(channelId, '30d');
console.log(`Тренд: ${subs.trend}, Среднее: ${subs.avgPerDay}/день`);

// Лучшее время для публикации
const bestTime = await client.channels.getBestTime(channelId);
console.log(bestTime.recommendation);

// Воронка: клики → подписки → ретеншен
const funnel = await client.channels.getFunnel(channelId);

// Пересечение аудиторий
const overlap = await client.channels.getAudienceOverlap(channelA, channelB);
console.log(`Общих подписчиков: ${overlap.overlap} (${overlap.overlap_pct}%)`);

// Бенчмарк (сравнение с категорией)
const benchmark = await client.channels.getBenchmark(channelId, 30);

Трекинг ключевых слов

// Создать трекер
const tracker = await client.tracking.create({
  name: 'Мониторинг бренда',
  keyword: 'tgio',
  exact_match: false,
  search_channels: true,
  search_chats: false,
  notify_via: 'bot',
});

// Совпадения
const { items, total } = await client.tracking.getMatches(tracker.id, { limit: 20 });

// Непрочитанные
const { count } = await client.tracking.getUnread(tracker.id);

// Пометить всё прочитанным
await client.tracking.markAllRead(tracker.id);

Защищённый обмен файлами

// Создать папку
const folder = await client.secure.createFolder({ name: 'Контракты' });

// Создать текстовый файл
const file = await client.secure.createFile(folder.id, {
  name: 'NDA',
  contentType: 'text',
  textContent: 'Текст контракта...',
});

// Создать ссылку с ограничениями
const link = await client.secure.createLink(file.id, {
  maxViews: 3, // макс. 3 просмотра
  expiresInHours: 48, // истечёт через 48 часов
});

console.log(link.url); // Отправьте эту ссылку получателю

Кастомные домены

// Добавить домен
const domain = await client.domains.create({ domain: 'go.mysite.com' });
console.log(`Настройте CNAME: go.mysite.com → ${domain.cname_target}`);

// Проверить DNS
const verified = await client.domains.verify(domain.id);

// Выпустить SSL
await client.domains.issueCert(domain.id);

Авторизация

API-токен (рекомендуется)

Создайте токен в личном кабинете → API-токены. Формат: tgio_sk_...

const client = new TgioClient({ token: 'tgio_sk_...' });

Telegram initData (для Mini Apps)

const client = new TgioClient();
const { accessToken } = await client.auth.telegram(window.Telegram.WebApp.initData);
client.setToken(accessToken);

Telegram Login Widget

const client = new TgioClient();
const { accessToken } = await client.auth.loginWidget(widgetData);
client.setToken(accessToken);

Обработка ошибок

SDK бросает TgioApiError при HTTP-ошибках:

import { TgioClient, TgioApiError } from '@tgio/sdk';

try {
  await client.links.create({ url: 'invalid' });
} catch (err) {
  if (err instanceof TgioApiError) {
    console.error(`HTTP ${err.status}: ${err.message}`);
    // HTTP 400: "Invalid URL format"
  }
}

Коды ошибок:

• 400 — Некорректный запрос
• 401 — Не авторизован (невалидный токен)
• 403 — Недостаточно прав (scope токена не включает нужное действие)
• 404 — Ресурс не найден
• 409 — Конфликт (дубликат и т.п.)
• 429 — Превышен лимит запросов

Настройки

const client = new TgioClient({
  // API-токен
  token: 'tgio_sk_...',

  // Базовый URL (по умолчанию https://back.tgio.app/api)
  baseUrl: 'https://back.tgio.app/api',

  // Тайм-аут в мс (по умолчанию 30000)
  timeout: 15000,

  // Кастомная реализация fetch (для Node.js <18 или тестов)
  fetch: customFetch,
});

Совместимость

• Node.js ≥ 18 (встроенный fetch)
• Браузеры: все современные
• Bun, Deno: поддерживается
• Для Node.js < 18 передайте node-fetch или undici через опцию fetch

Лицензия

MIT