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, работает в любом современном браузере

📦 Установка

``bash
npm install telegram-mock-init-data


или

pnpm add telegram-mock-init-data

или

yarn add telegram-mock-init-data
`

$3

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

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

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

$3

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

`typescript
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)
// Теперь можно использовать эту строку для инициализации приложения
`

$3

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

`typescript
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!
`

$3

`typescript
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,
})
`

$3

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

`typescript
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 будут перехватываться
`

$3

`typescript
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

$3

Генерирует 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
`typescript
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 - URL-encoded строка с launch параметрами

Пример возвращаемого значения:
`
tgWebAppData=user%3D%7B%22id%22%3A123456...&tgWebAppThemeParams=%7B%22bg_color%22...&tgWebAppVersion=7.0&tgWebAppPlatform=tdesktop
`

$3

#### DEFAULT_MOCK_USER

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

`typescript
{
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

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

`typescript
{
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',
}
`

$3

#### InvalidLaunchParamsError

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

`typescript
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 и предоставляет все необходимые типы:

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

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

$3

`typescript
// 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,
})
})
`

$3

`typescript
// 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()
`

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

`bash


Установить зависимости

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