tg-mini-app-binder/src/index.js

A modular and extendable wrapper for the Telegram Mini App API to simplify interactions between your web app and the Telegram client.

import WebAppModule from './modules/WebAppModule.js';
import UserModule from './modules/UserModule.js';
import UIModule from './modules/UIModule.js';
import MessagingModule from './modules/MessagingModule.js';
import LinksModule from './modules/LinksModule.js';

/**
 * @class TelegramMiniAppBinder
 * @description The main class that initializes and provides access to all Telegram Mini App functionalities.
 */
class TelegramMiniAppBinder {
    /**
     * @constructor
     */
    constructor() {
        /**
         * The raw Telegram WebApp object.
         * @type {object|null}
         */
        this.tg = window.Telegram?.WebApp || null;

        if (!this.tg) {
            console.error("Telegram WebApp script is not loaded or the app is not running inside Telegram.");
            // In a non-Telegram environment, we create mock objects to prevent errors.
            this.tg = this.createMockWebApp();
        }

        /**
         * Manages general app properties like closing, expanding, and events.
         * @type {WebAppModule}
         */
        this.app = new WebAppModule(this.tg);

        /**
         * Manages user-related data.
         * @type {UserModule}
         */
        this.user = new UserModule(this.tg);

        /**
         * Manages UI components like MainButton, BackButton, and HapticFeedback.
         * @type {UIModule}
         */
        this.ui = new UIModule(this.tg);
        
        /**
         * Manages sending data back to the bot.
         * @type {MessagingModule}
         */
        this.messaging = new MessagingModule(this.tg);

        /**
         * Manages opening t.me links and invoices.
         * @type {LinksModule}
         */
        this.links = new LinksModule(this.tg);

        // Notify Telegram that the app is ready.
        this.tg.ready();
    }

    /**
     * Creates a mock WebApp object for development and testing outside of Telegram.
     * @returns {object} A mock WebApp object.
     */
    createMockWebApp() {
        console.warn("Running in mock mode. Functionality will be limited.");
        const mockUser = {
            id: 123456789,
            is_bot: false,
            first_name: "John",
            last_name: "Doe",
            username: "johndoe",
            language_code: "en",
            is_premium: true
        };

        return {
            initData: "mock_init_data_string",
            initDataUnsafe: { user: mockUser },
            version: "6.4",
            platform: "test",
            colorScheme: "light",
            themeParams: {
                bg_color: "#ffffff",
                text_color: "#000000"
            },
            isExpanded: true,
            viewportHeight: 800,
            headerColor: "#ffffff",
            backgroundColor: "#ffffff",
            isClosingConfirmationEnabled: false,
            BackButton: { show: () => {}, hide: () => {}, onClick: () => {}, offClick: () => {} },
            MainButton: { 
                text: '', 
                color: '', 
                textColor: '', 
                isVisible: false, 
                isActive: true,
                setText: (text) => this.MainButton.text = text,
                onClick: (cb) => {},
                offClick: (cb) => {},
                show: () => this.MainButton.isVisible = true,
                hide: () => this.MainButton.isVisible = false,
                enable: () => this.MainButton.isActive = true,
                disable: () => this.MainButton.isActive = false,
                showProgress: () => {},
                hideProgress: () => {}
            },
            HapticFeedback: {
                impactOccurred: (style) => console.log(`Mock Haptic Impact: ${style}`),
                notificationOccurred: (type) => console.log(`Mock Haptic Notification: ${type}`),
                selectionChanged: () => console.log('Mock Haptic Selection Changed')
            },
            ready: () => console.log("Mock App Ready"),
            expand: () => console.log("Mock App Expand"),
            close: () => console.log("Mock App Close"),
            sendData: (data) => console.log("Mock sending data:", data),
            requestContact: (callback) => { 
                console.log("Mock requesting contact...");
                if (callback) callback(true);
            },
            onEvent: (eventType, callback) => console.log(`Mock event listener for ${eventType}`),
            offEvent: (eventType, callback) => console.log(`Mock removing event listener for ${eventType}`),
            openTelegramLink: (url) => console.log(`Mock opening Telegram link: ${url}`),
            openInvoice: (url, cb) => console.log(`Mock opening invoice: ${url}`),
        };
    }
}

// Export a singleton instance for ease of use.
window.TelegramMiniAppBinder = TelegramMiniAppBinder;