telegram-mock-init-data

English | Русский

Библиотека для мокирования окружения Telegram Mini Apps с криптографически валидной подписью init data в целях разработки и тестирования.

🎯 Мотивация

Оригинальная библиотека @tma.js/bridge предоставляет метод mockTelegramEnv, однако он не генерирует валидную HMAC-SHA256 подпись для init data. Это делает невозможным тестирование серверной части приложения, которая проверяет подлинность данных от Telegram.

telegram-mock-init-data решает эту проблему, предоставляя полностью валидные подписи с использованием Web Crypto API.

🌟 Возможности

• 🔐 Правильная подпись Init Data - Криптографически корректные HMAC-SHA256 подписи с использованием Web Crypto API
• 🎨 Настройка темы - Включает тёмную тему по умолчанию с возможностью кастомизации
• 🔄 Перехват событий - Возможность перехватывать и обрабатывать события Telegram Mini Apps
• 💾 Работа со Storage - Автоматическое сохранение параметров в sessionStorage
• 🌐 Поддержка iframe - Работает как в iframe, так и в standalone окружении
• 🧪 Готовность к тестированию - Специально разработана для использования в тестах
• 📦 Без конфигурации - Работает из коробки с разумными значениями по умолчанию
• 🔧 TypeScript First - Полная поддержка TypeScript с определениями типов
• 🌐 Browser-First - Без зависимостей от Node.js, работает в любом современном браузере

📦 Установка

npm install telegram-mock-init-data
# или
pnpm add telegram-mock-init-data
# или
yarn add telegram-mock-init-data

Peer Dependencies

Библиотека требует следующие peer dependencies:

npm install @tma.js/sdk @tma.js/types @tma.js/toolkit @tma.js/transformers @tma.js/bridge

🚀 Использование

Базовый пример

Простая генерация launch параметров без настройки окружения:

import { mockTelegramEnvExtended } from 'telegram-mock-init-data'

// Генерируем только launch параметры
const launchParams = await mockTelegramEnvExtended({
  user: {
    id: 123456,
    first_name: 'Иван',
    last_name: 'Петров',
    username: 'ivan_petrov',
    language_code: 'ru',
    is_premium: true,
  },
  botToken: 'YOUR_BOT_TOKEN',
})

console.log('Launch params:', launchParams)
// Теперь можно использовать эту строку для инициализации приложения

С автоматической настройкой окружения

Генерация параметров + автоматическая настройка окружения (storage + TelegramWebviewProxy):

import { mockTelegramEnvExtended } from 'telegram-mock-init-data'

// Генерация параметров + настройка окружения
await mockTelegramEnvExtended({
  user: {
    id: 123456,
    first_name: 'Иван',
    username: 'ivan_petrov',
  },
  botToken: 'YOUR_BOT_TOKEN',
  setupEnvironment: true, // 👈 Автоматически сохраняет в storage и настраивает окружение
})

// Теперь можно использовать @tma.js/sdk
import { retrieveLaunchParams } from '@tma.js/sdk'
const params = retrieveLaunchParams() // Параметры будут доступны из storage!

С кастомной конфигурацией

import { mockTelegramEnvExtended, DEFAULT_MOCK_USER } from '@bazaar/telegram-mock'

await mockTelegramEnvExtended({
  user: {
    id: 99281932,
    first_name: 'Андрей',
    last_name: 'Рогов',
    username: 'rogue',
    language_code: 'en',
    is_premium: true,
    allows_write_to_pm: true,
    photo_url: 'https://telegram.org/img/t_logo.png',
  },
  botToken: process.env.TELEGRAM_BOT_TOKEN,
  queryId: 'custom_query_id',
  chatInstance: '1234567890',
  chatType: 'private',
  startParam: 'debug_mode',
  platform: 'ios',
  version: '7.2',
  themeParams: {
    bg_color: '#ffffff',
    text_color: '#000000',
    button_color: '#0088cc',
  },
  setupEnvironment: true,
})

Перехват событий Telegram Mini Apps

Вы можете перехватывать события, которые отправляет ваше приложение в Telegram:

import { mockTelegramEnvExtended } from 'telegram-mock-init-data'

await mockTelegramEnvExtended({
  user: { id: 123456, first_name: 'Иван' },
  botToken: 'YOUR_BOT_TOKEN',
  setupEnvironment: true,
  onEvent: (event, next) => {
    console.log('📤 Событие:', event.name)
    console.log('📦 Параметры:', event.params)

    // Можно изменить поведение или добавить логирование
    if (event.name === 'web_app_data_send') {
      console.log('✉️ Отправка данных боту:', event.params)
    }

    if (event.name === 'web_app_close') {
      console.log('❌ Приложение закрывается')
    }

    // Вызвать оригинальный обработчик
    next()
  },
})

// Теперь все вызовы postEvent будут перехватываться

Использование в тестах

import { describe, it, expect, beforeEach } from 'vitest'
import { mockTelegramEnvExtended } from '@bazaar/telegram-mock'
import { retrieveLaunchParams } from '@tma.js/sdk'

describe('Telegram Mini App', () => {
  beforeEach(async () => {
    // Настройка мок-окружения перед каждым тестом
    await mockTelegramEnvExtended({
      user: {
        id: 123456,
        first_name: 'Тест',
        username: 'test_user',
      },
      botToken: 'test_bot_token',
      setupEnvironment: true,
    })
  })

  it('должен получить launch параметры', () => {
    const params = retrieveLaunchParams()
    expect(params.tgWebAppPlatform).toBe('tdesktop')
    expect(params.tgWebAppData?.user?.id).toBe(123456)
  })
})

📖 API

mockTelegramEnvExtended(config)

Генерирует launch параметры для Telegram Mini App с возможностью автоматической настройки окружения.

Параметры

Данные пользователя:

• config.user (опционально) - Данные пользователя для мок-окружения
  • id (number) - Telegram user ID
  • first_name (string) - Имя пользователя
  • last_name (string, опционально) - Фамилия пользователя
  • username (string, опционально) - Username пользователя
  • language_code (string, опционально) - Код языка (IETF), например 'ru', 'en'
  • is_premium (boolean, опционально) - Premium статус пользователя
  • is_bot (boolean, опционально) - Является ли бот
  • allows_write_to_pm (boolean, опционально) - Разрешение боту писать личные сообщения
  • photo_url (string, опционально) - URL фото профиля

Конфигурация окружения:

• config.botToken (string, требуется) - Токен Telegram бота для подписи init data
• config.queryId (string, опционально) - Query ID для мок-сессии
  • По умолчанию: 'AAF4s85OAAAAALizzk7h'
• config.chatInstance (string, опционально) - Chat instance ID
  • По умолчанию: '8428209589180549439'
• config.chatType (string, опционально) - Тип чата
  • По умолчанию: 'sender'
  • Опции: 'sender' | 'private' | 'group' | 'supergroup' | 'channel'
• config.startParam (string, опционально) - Start параметр из прямой ссылки
• config.platform (string, опционально) - Идентификатор платформы
  • По умолчанию: 'tdesktop'
  • Опции: 'tdesktop' | 'android' | 'ios' | 'macos' | 'web'
• config.version (string, опционально) - Версия Telegram Mini App
  • По умолчанию: '7.0'
• config.themeParams (object, опционально) - Кастомные параметры темы
  • bg_color - Цвет фона
  • text_color - Цвет текста
  • hint_color - Цвет подсказок
  • link_color - Цвет ссылок
  • button_color - Цвет кнопок
  • И другие параметры темы Telegram

Расширенные опции:

• config.setupEnvironment (boolean, опционально) - Автоматически настроить окружение

  • По умолчанию: false
  • Что делает:
    • ✅ Сохраняет launch параметры в sessionStorage
    • ✅ Настраивает TelegramWebviewProxy.postEvent (для non-iframe)
    • ✅ Перехватывает window.parent.postMessage (для iframe)
    • ✅ Валидирует launch параметры

• config.onEvent (function, опционально) - Callback для перехвата событий Telegram Mini Apps

  onEvent: (event: { name: string, params: unknown }, next: () => void) => void

  • event.name - Имя события (например: 'web_app_data_send', 'web_app_close')
  • event.params - Параметры события
  • next() - Функция для вызова оригинального обработчика

• config.resetPostMessage (boolean, опционально) - Сбросить предыдущие модификации postMessage

  • По умолчанию: false

Возвращает

Promise<string> - URL-encoded строка с launch параметрами

Пример возвращаемого значения:

tgWebAppData=user%3D%7B%22id%22%3A123456...&tgWebAppThemeParams=%7B%22bg_color%22...&tgWebAppVersion=7.0&tgWebAppPlatform=tdesktop

Константы

DEFAULT_MOCK_USER

Дефолтный пользователь для быстрого старта:

{
  id: 512345678,
  is_bot: false,
  first_name: 'Иван',
  last_name: 'Петров',
  username: 'ivan_petrov',
  language_code: 'ru',
  is_premium: true,
  allows_write_to_pm: true,
  photo_url: 'https://t.me/i/userpic/320/abc123.png',
}

DEFAULT_THEME_PARAMS

Параметры тёмной темы по умолчанию:

{
  accent_text_color: '#6ab2f2',
  bg_color: '#17212b',
  button_color: '#5288c1',
  button_text_color: '#ffffff',
  destructive_text_color: '#ec3942',
  header_bg_color: '#17212b',
  hint_color: '#708499',
  link_color: '#6ab3f3',
  secondary_bg_color: '#232e3c',
  section_bg_color: '#17212b',
  section_header_text_color: '#6ab3f3',
  subtitle_text_color: '#708499',
  text_color: '#f5f5f5',
}

Исключения

InvalidLaunchParamsError

Выбрасывается, когда сгенерированные launch параметры невалидны:

try {
  await mockTelegramEnvExtended({
    botToken: 'invalid_token',
    setupEnvironment: true,
  })
} catch (error) {
  if (error instanceof InvalidLaunchParamsError) {
    console.error('Невалидные launch параметры:', error.message)
    console.error('Причина:', error.cause)
  }
}

🔧 TypeScript

Пакет полностью написан на TypeScript и предоставляет все необходимые типы:

import type {
  MockUser,
  MockTelegramConfig,
  MockTelegramEnvExtendedOptions,
  InvalidLaunchParamsError,
} from 'telegram-mock-init-data'

// Пример использования типов
const user: MockUser = {
  id: 123456,
  first_name: 'Иван',
  username: 'ivan_petrov',
}

const config: MockTelegramEnvExtendedOptions = {
  user,
  botToken: 'token',
  setupEnvironment: true,
  onEvent: (event, next) => {
    console.log(event.name)
    next()
  },
}

🔗 Совместимость с @tma.js

Библиотека полностью совместима с @tma.js:

✅ Использует те же библиотеки:

• @tma.js/toolkit - для работы со storage
• @tma.js/transformers - для парсинга и валидации
• @tma.js/bridge - для определения окружения

✅ Совместимость с функциями:

• retrieveLaunchParams() из @tma.js/sdk - работает из коробки
• postEvent() - перехватывается через onEvent
• miniAppsMessage() - используется для валидации сообщений

✅ Поддержка окружений:

• iframe (с window.parent.postMessage)
• standalone (с TelegramWebviewProxy)

🧪 Примеры использования

Интеграция с Vitest

// vitest.setup.ts
import { beforeAll } from 'vitest'
import { mockTelegramEnvExtended } from '@bazaar/telegram-mock'

beforeAll(async () => {
  await mockTelegramEnvExtended({
    user: {
      id: 123456,
      first_name: 'Test User',
      username: 'test_user',
    },
    botToken: process.env.TEST_BOT_TOKEN || 'test_token',
    setupEnvironment: true,
  })
})

Использование в Vite приложении

// src/main.ts
import { mockTelegramEnvExtended } from '@bazaar/telegram-mock'

// В development режиме настраиваем мок-окружение
if (import.meta.env.DEV) {
  await mockTelegramEnvExtended({
    botToken: import.meta.env.VITE_BOT_TOKEN,
    setupEnvironment: true,
    onEvent: (event, next) => {
      console.log('[Mock] Event:', event.name, event.params)
      next()
    },
  })
}

// Далее обычная инициализация приложения
import { init } from '@tma.js/sdk'
init()

🛠️ Разработка

# Установить зависимости
pnpm install

# Собрать пакет
pnpm build

# Запустить тесты
pnpm test

# Watch режим для разработки
pnpm dev

# Проверка типов
pnpm typecheck

📝 Лицензия

MIT

🤝 Вклад в проект

Contributions приветствуются! Пожалуйста, создавайте Pull Request или Issue.

🔗 Полезные ссылки

• @tma.js Documentation
• Telegram Mini Apps Guide
• Web Crypto API