@core-ease/telegram-kit 3.0.1

package/dist/hooks-C5Per70R.d.mts

@@ -0,0 +1,1066 @@
+/**
+ * Pure, side-effect-light helper functions.
+ * Direct TypeScript port of the `window.Telegram.Utils` helpers plus a
+ * handful of private helpers that lived as free functions in the original
+ * IIFE (strTrim, byteLength, versionCompare, parseColorToHex, isColorDark).
+ */
+declare function urlSafeDecode(urlencoded: string): string;
+declare function urlParseQueryString(queryString: string): Record<string, string | null>;
+declare function urlParseHashParams(locationHash: string): Record<string, any>;
+/**
+ * Telegram apps use this to add service params (e.g. tgShareScoreUrl) to a
+ * game URL.
+ * url looks like 'https://game.com/path?query=1#hash'
+ * addHash looks like 'tgShareScoreUrl=' + encodeURIComponent('tgb://share_game_score?hash=very_long_hash123')
+ */
+declare function urlAppendHashParams(url: string, addHash: string): string;
+declare function sessionStorageSet(key: string, value: unknown): boolean;
+declare function sessionStorageGet<T = any>(key: string): T | null;
+
+/**
+ * Shared type definitions for the Telegram WebApp SDK port.
+ *
+ * These types describe the wire format exchanged with the native Telegram
+ * client (postEvent/receiveEvent payloads) as well as the public-facing
+ * shapes exposed to the Mini App developer. Kept in one file so every
+ * module (core, ui, features, theme) can depend on a single source of truth.
+ */
+/** Generic string-keyed dictionary used for loosely-typed event payloads. */
+type AnyRecord = Record<string, any>;
+/** Callback signature used throughout the SDK for fire-and-forget events. */
+type VoidCallback = (...args: any[]) => void;
+/** Handler used internally by the WebView event bus. */
+type EventHandler = (eventType: string, eventData: any) => void;
+/** Raw key/value hash-params parsed from `location.hash`. */
+interface InitParams extends AnyRecord {
+    _path?: string;
+    tgWebAppData?: string;
+    tgWebAppThemeParams?: string;
+    tgWebAppDefaultColors?: string;
+    tgWebAppVersion?: string;
+    tgWebAppPlatform?: string;
+    tgWebAppFullscreen?: string;
+    tgWebAppShowSettings?: string;
+    tgWebAppBotInline?: string;
+    tgWebAppDebug?: string;
+}
+/** Theme color palette pushed by the Telegram client. */
+interface ThemeParams extends AnyRecord {
+    bg_color?: string;
+    text_color?: string;
+    hint_color?: string;
+    link_color?: string;
+    button_color?: string;
+    button_text_color?: string;
+    secondary_bg_color?: string;
+    header_bg_color?: string;
+    bottom_bar_bg_color?: string;
+    accent_text_color?: string;
+    section_bg_color?: string;
+    section_header_text_color?: string;
+    section_separator_color?: string;
+    subtitle_text_color?: string;
+    destructive_text_color?: string;
+}
+/** Default (fallback) colors sent alongside theme params. */
+interface DefaultColors {
+    bg_color?: string;
+    bg_dark_color?: string;
+    header_color?: string;
+    header_dark_color?: string;
+}
+type ColorScheme = 'light' | 'dark';
+interface SafeAreaInset {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** `Telegram.WebApp.initDataUnsafe` shape - untrusted, parsed client-side. */
+interface WebAppInitDataUnsafe extends AnyRecord {
+    query_id?: string;
+    user?: WebAppUser;
+    receiver?: WebAppUser;
+    chat?: WebAppChat;
+    chat_type?: string;
+    chat_instance?: string;
+    start_param?: string;
+    can_send_after?: number;
+    auth_date?: string;
+    hash?: string;
+    signature?: string;
+}
+interface WebAppUser extends AnyRecord {
+    id: number;
+    is_bot?: boolean;
+    first_name: string;
+    last_name?: string;
+    username?: string;
+    language_code?: string;
+    is_premium?: boolean;
+    added_to_attachment_menu?: boolean;
+    allows_write_to_pm?: boolean;
+    photo_url?: string;
+}
+interface WebAppChat extends AnyRecord {
+    id: number;
+    type: string;
+    title: string;
+    username?: string;
+    photo_url?: string;
+}
+/** Button position for the SecondaryButton relative to the MainButton. */
+type BottomButtonPosition = 'left' | 'right' | 'top' | 'bottom';
+interface BottomButtonParams {
+    is_visible?: boolean;
+    is_active?: boolean;
+    is_progress_visible?: boolean;
+    icon_custom_emoji_id?: string | false | null;
+    text?: string;
+    color?: string | false | null;
+    text_color?: string | false | null;
+    has_shine_effect?: boolean;
+    position?: BottomButtonPosition;
+}
+type PopupButtonType = 'default' | 'ok' | 'close' | 'cancel' | 'destructive';
+interface PopupButton {
+    id?: string | number;
+    type?: PopupButtonType;
+    text?: string;
+}
+interface PopupParams {
+    title?: string;
+    message: string;
+    buttons?: PopupButton[];
+}
+interface ScanQrPopupParams {
+    text?: string;
+}
+interface OpenLinkOptions {
+    try_instant_view?: boolean;
+    try_browser?: string;
+}
+interface OpenTelegramLinkOptions {
+    force_request?: boolean;
+}
+interface CloseOptions {
+    return_back?: boolean;
+}
+type HapticImpactStyle = 'light' | 'medium' | 'heavy' | 'rigid' | 'soft';
+type HapticNotificationType = 'error' | 'success' | 'warning';
+type HomeScreenStatus = 'unsupported' | 'unknown' | 'added' | 'missed';
+type BiometricType = 'unknown' | 'finger' | 'face';
+interface BiometricRequestAccessParams {
+    reason?: string;
+}
+interface BiometricAuthenticateParams {
+    reason?: string;
+}
+interface LocationData {
+    latitude: number;
+    longitude: number;
+    altitude: number | null;
+    course: number | null;
+    speed: number | null;
+    horizontal_accuracy: number | null;
+    vertical_accuracy: number | null;
+    course_accuracy: number | null;
+    speed_accuracy: number | null;
+}
+interface MotionSensorStartParams {
+    refresh_rate?: number;
+}
+interface DeviceOrientationStartParams extends MotionSensorStartParams {
+    need_absolute?: boolean;
+}
+interface DownloadFileParams {
+    url: string;
+    file_name: string;
+}
+interface ShareToStoryWidgetLink {
+    url: string;
+    name?: string;
+}
+interface ShareToStoryParams {
+    text?: string;
+    widget_link?: ShareToStoryWidgetLink;
+}
+/** Two-way callback shape shared by storage-like features (err-first). */
+type ErrCallback<T = any> = (error: string | null, result?: T) => void;
+/** Generic result callback for CloudStorage.getItems(). */
+type ItemsCallback = ErrCallback<Record<string, string>>;
+
+/**
+ * WebView bridge / transport layer.
+ *
+ * This is a faithful port of the first `(function () { ... })()` block in
+ * the original telegram-web-app.js: it is responsible for talking to the
+ * native Telegram client (Android/iOS WebView proxy, Windows `external`
+ * bridge, or a browser `postMessage` iframe bridge) and for the generic
+ * pub/sub event bus that every higher-level feature (WebApp, buttons,
+ * storages, sensors, ...) is built on top of.
+ *
+ * Nothing Telegram.WebApp-specific lives here on purpose: this module only
+ * knows how to send/receive named events and parse the initial hash params.
+ */
+
+declare global {
+    interface Window {
+        TelegramWebviewProxy?: {
+            postEvent(eventType: string, eventData: string): void;
+        };
+        TelegramGameProxy_receiveEvent?: (eventType: string, eventData: any) => void;
+        TelegramGameProxy?: {
+            receiveEvent: (eventType: string, eventData: any) => void;
+        };
+    }
+}
+type PostEventCallback = (error?: {
+    notAvailable?: true;
+} | Error | undefined) => void;
+declare class TelegramWebView {
+    readonly initParams: InitParams;
+    readonly isIframe: boolean;
+    private eventHandlers;
+    private iFrameStyleEl;
+    constructor();
+    private handleParentMessage;
+    /** Sends a named event + payload to the native Telegram client. */
+    postEvent(eventType: string, callback?: PostEventCallback, eventData?: unknown): void;
+    /** Dispatches an incoming event to every subscriber of `eventType`. */
+    receiveEvent: (eventType: string, eventData: any) => void;
+    callEventCallbacks(eventType: string, func: (handler: EventHandler) => void): void;
+    onEvent(eventType: string, callback: EventHandler): void;
+    offEvent(eventType: string, callback: EventHandler): void;
+}
+/** Re-exported so consumers of `window.Telegram.Utils` keep the same surface. */
+declare const Utils: {
+    urlSafeDecode: typeof urlSafeDecode;
+    urlParseQueryString: typeof urlParseQueryString;
+    urlParseHashParams: typeof urlParseHashParams;
+    urlAppendHashParams: typeof urlAppendHashParams;
+    sessionStorageSet: typeof sessionStorageSet;
+    sessionStorageGet: typeof sessionStorageGet;
+};
+
+/**
+ * WebApp-level kernel.
+ *
+ * The original script keeps a pile of closures (`versionAtLeast`,
+ * `receiveWebViewEvent`, `webAppCallbacks`, `generateCallbackId`,
+ * `setCssProperty`, `invokeCustomMethod`, ...) that every feature
+ * (buttons, storages, sensors, popups...) reaches into.
+ *
+ * To keep the TypeScript port modular while preserving that exact runtime
+ * behavior, those closures are grouped into one small `WebAppKernel` class
+ * that gets constructed once and injected into every feature module. This
+ * is the *only* piece of shared mutable plumbing; everything else lives in
+ * its own dedicated module.
+ */
+
+type WebAppCallback = (...args: any[]) => void;
+interface PendingCallback {
+    callback?: WebAppCallback;
+}
+declare class WebAppKernel {
+    readonly webView: TelegramWebView;
+    readonly initParams: InitParams;
+    /** Mutable current protocol version reported by the client, e.g. '8.0'. */
+    private _version;
+    private callbacks;
+    /** Height (px) reserved by the in-browser debug bottom bar, if active. */
+    bottomBarHeightPx: number;
+    constructor(webView: TelegramWebView);
+    get version(): string;
+    set version(v: string);
+    versionAtLeast(ver: string): boolean;
+    /** Logs + throws `WebAppMethodUnsupported` for a method gated by version. */
+    requireVersion(ver: string, methodName: string): void;
+    /** Same as {@link requireVersion} but warns instead of throwing (soft-gated features). */
+    warnIfUnsupported(ver: string, featureName: string): boolean;
+    setCssProperty(name: string, value: string): void;
+    strTrim(str: unknown): string;
+    byteLength(str: string): number;
+    /** Dispatches an internal `webview:<eventType>` event to WebApp-level subscribers. */
+    receiveWebViewEvent(eventType: string, ...args: any[]): void;
+    onWebViewEvent(eventType: string, callback: EventHandler): void;
+    offWebViewEvent(eventType: string, callback: EventHandler): void;
+    /** Allocates a fresh request id and registers its pending callback. */
+    registerCallback(callback?: WebAppCallback, len?: number): string;
+    takeCallback(reqId: string): PendingCallback | undefined;
+    hasCallback(reqId: string): boolean;
+    /** Generic `web_app_invoke_custom_method` used by CloudStorage, contact lookup, etc. */
+    invokeCustomMethod(method: string, params: AnyRecordLike | undefined, callback?: WebAppCallback): void;
+    onCustomMethodInvoked: (_eventType: string, eventData: any) => void;
+}
+type AnyRecordLike = Record<string, any>;
+
+/**
+ * `Telegram.WebApp.BackButton` - port of the `BackButton` IIFE.
+ */
+
+declare class BackButton {
+    private readonly kernel;
+    private _isVisible;
+    private curButtonState;
+    constructor(kernel: WebAppKernel);
+    private handleBackButtonPressed;
+    get isVisible(): boolean;
+    set isVisible(val: boolean);
+    private checkVersion;
+    private buttonParams;
+    private updateButton;
+    setParams(params: {
+        is_visible?: boolean;
+    }): this;
+    onClick(callback: VoidCallback): this;
+    offClick(callback: VoidCallback): this;
+    show(): this;
+    hide(): this;
+}
+
+/**
+ * Debug bottom bar - the little on-page mock of Telegram's native Main /
+ * Secondary button bar, shown only when `tgWebAppDebug` is present in the
+ * init hash params (i.e. when testing a Mini App directly in a desktop
+ * browser instead of inside the real Telegram client).
+ *
+ * Isolated into its own module so it can be tree-shaken/omitted entirely in
+ * builds that never run in debug mode, and so `BottomButton` doesn't need
+ * to know anything about DOM styling.
+ */
+
+interface DebugButtonVisualState {
+    is_visible?: boolean;
+    is_active?: boolean;
+    is_progress_visible?: boolean;
+    text?: string;
+    color?: string;
+    text_color?: string;
+    has_shine_effect?: boolean;
+}
+type ButtonType = 'main' | 'secondary';
+declare class DebugBottomBar {
+    private readonly kernel;
+    private readonly getBottomBarColor;
+    readonly enabled: boolean;
+    private container;
+    private buttons;
+    /** Invoked whenever the reserved bottom-bar height changes. */
+    onHeightChanged: (() => void) | null;
+    constructor(kernel: WebAppKernel, getBottomBarColor: () => string);
+    /** Creates & registers a debug clone of a Main/Secondary button; returns its element. */
+    registerButton(type: ButtonType, onPressed: () => void): HTMLElement | null;
+    /** Applies visual state coming from `BottomButton.buttonParams()`. */
+    updateButtonVisual(type: ButtonType, params: DebugButtonVisualState & {
+        position?: BottomButtonPosition;
+    }): void;
+    private updateBar;
+    /** Called after the bottom-bar color changes so the debug bar repaints too. */
+    refreshColor(): void;
+}
+
+/**
+ * Theme & chrome-color manager.
+ *
+ * Owns `themeParams`, `colorScheme`, `headerColor`, `backgroundColor` and
+ * `bottomBarColor` - i.e. everything the original script updates whenever a
+ * `theme_changed` event arrives or the developer calls one of the
+ * `set*Color` setters.
+ */
+
+declare class ThemeManager {
+    private readonly kernel;
+    private themeParams;
+    private _colorScheme;
+    private backgroundColorValue;
+    private appBackgroundColor;
+    private headerColorKey;
+    private headerColorValue;
+    private appHeaderColorKey;
+    private appHeaderColorValue;
+    private bottomBarColorValue;
+    private appBottomBarColor;
+    /** Called after every bottom-bar color update, e.g. to refresh the debug bar. */
+    onBottomBarColorApplied: (() => void) | null;
+    constructor(kernel: WebAppKernel);
+    get colorScheme(): ColorScheme;
+    getThemeParams(): ThemeParams;
+    setThemeParams(theme: ThemeParams): void;
+    setDefaultColors(defColors: DefaultColors): void;
+    getHeaderColor(): string | null | undefined;
+    setHeaderColor(color: string): void;
+    updateHeaderColor(): void;
+    getBackgroundColor(): string | undefined;
+    setBackgroundColor(color: string): void;
+    updateBackgroundColor(): void;
+    getBottomBarColor(): string;
+    setBottomBarColor(color: string): void;
+    updateBottomBarColor(): void;
+}
+
+/**
+ * `Telegram.WebApp.MainButton` / `Telegram.WebApp.SecondaryButton`.
+ *
+ * Both buttons share 100% of their behavior in the original SDK
+ * (`BottomButtonConstructor(type)`); this class keeps that single
+ * implementation and is instantiated twice by the WebApp aggregator.
+ */
+
+type BottomButtonType = 'main' | 'secondary';
+interface SetBottomButtonParams {
+    text?: string;
+    color?: string | false | null;
+    text_color?: string | false | null;
+    is_visible?: boolean;
+    is_active?: boolean;
+    has_shine_effect?: boolean;
+    position?: BottomButtonPosition;
+    icon_custom_emoji_id?: string | false | null;
+}
+declare class BottomButton {
+    private readonly kernel;
+    private readonly theme;
+    private readonly debugBar;
+    readonly type: BottomButtonType;
+    private isVisibleValue;
+    private isActiveValue;
+    private hasShineEffectValue;
+    private isProgressVisibleValue;
+    private iconCustomEmojiIdValue;
+    private textValue;
+    private colorValue;
+    private textColorValue;
+    private positionValue;
+    private curButtonState;
+    private readonly isMain;
+    private readonly setupEventName;
+    private readonly nativePressEventName;
+    private readonly webViewEventName;
+    private readonly defaultText;
+    private readonly defaultColor;
+    private readonly defaultTextColor;
+    constructor(type: BottomButtonType, kernel: WebAppKernel, theme: ThemeManager, debugBar: DebugBottomBar);
+    private handlePressed;
+    get iconCustomEmojiId(): string | false;
+    set iconCustomEmojiId(val: string | false);
+    get text(): string;
+    set text(val: string);
+    get color(): string;
+    set color(val: string);
+    get textColor(): string;
+    set textColor(val: string);
+    get isVisible(): boolean;
+    set isVisible(val: boolean);
+    get isProgressVisible(): boolean;
+    get isActive(): boolean;
+    set isActive(val: boolean);
+    get hasShineEffect(): boolean;
+    set hasShineEffect(val: boolean);
+    get position(): BottomButtonPosition;
+    set position(val: BottomButtonPosition);
+    private buttonParams;
+    private updateButton;
+    setParams(params: SetBottomButtonParams): this;
+    setText(text: string): this;
+    onClick(callback: VoidCallback): this;
+    offClick(callback: VoidCallback): this;
+    show(): this;
+    hide(): this;
+    enable(): this;
+    disable(): this;
+    showProgress(leaveActive?: boolean): this;
+    hideProgress(): this;
+}
+
+/**
+ * `Telegram.WebApp.SettingsButton` - port of the `SettingsButton` IIFE.
+ */
+
+declare class SettingsButton {
+    private readonly kernel;
+    private _isVisible;
+    private curButtonState;
+    constructor(kernel: WebAppKernel);
+    private handleSettingsButtonPressed;
+    get isVisible(): boolean;
+    set isVisible(val: boolean);
+    private checkVersion;
+    private buttonParams;
+    private updateButton;
+    setParams(params: {
+        is_visible?: boolean;
+    }): this;
+    onClick(callback: VoidCallback): this;
+    offClick(callback: VoidCallback): this;
+    show(): this;
+    hide(): this;
+}
+
+/**
+ * `Telegram.WebApp.HapticFeedback`.
+ */
+
+declare class HapticFeedback {
+    private readonly kernel;
+    constructor(kernel: WebAppKernel);
+    private trigger;
+    impactOccurred(style: HapticImpactStyle): this;
+    notificationOccurred(type: HapticNotificationType): this;
+    selectionChanged(): this;
+}
+
+/**
+ * `Telegram.WebApp.CloudStorage`.
+ */
+
+declare class CloudStorage {
+    private readonly kernel;
+    constructor(kernel: WebAppKernel);
+    private invoke;
+    setItem(key: string, value: string, callback?: ErrCallback): this;
+    getItem(key: string, callback?: ErrCallback<string>): this;
+    getItems(keys: string[], callback?: ItemsCallback): this;
+    removeItem(key: string, callback?: ErrCallback): this;
+    removeItems(keys: string[], callback?: ErrCallback): this;
+    getKeys(callback?: ErrCallback<string[]>): this;
+}
+
+/**
+ * `Telegram.WebApp.DeviceStorage`.
+ */
+
+declare class DeviceStorage {
+    private readonly kernel;
+    constructor(kernel: WebAppKernel);
+    private handleEvent;
+    private invoke;
+    setItem(key: string, value: string, callback?: ErrCallback): this;
+    getItem(key: string, callback?: ErrCallback<string>): this;
+    removeItem(key: string, callback?: ErrCallback): this;
+    clear(callback?: ErrCallback): this;
+}
+
+/**
+ * `Telegram.WebApp.SecureStorage`.
+ */
+
+type SecureStorageCallback = (error: string | null, result?: any, canRestore?: boolean) => void;
+declare class SecureStorage {
+    private readonly kernel;
+    constructor(kernel: WebAppKernel);
+    private handleEvent;
+    private invoke;
+    setItem(key: string, value: string, callback?: SecureStorageCallback): this;
+    getItem(key: string, callback?: SecureStorageCallback): this;
+    restoreItem(key: string, callback?: SecureStorageCallback): this;
+    removeItem(key: string, callback?: SecureStorageCallback): this;
+    clear(callback?: SecureStorageCallback): this;
+}
+
+/**
+ * `Telegram.WebApp.BiometricManager`.
+ */
+
+type InitCallback$1 = () => void;
+type AccessCallback = (granted: boolean) => void;
+type AuthCallback = (authenticated: boolean, token: string | null) => void;
+type TokenCallback = (applied: boolean) => void;
+declare class BiometricManager {
+    private readonly kernel;
+    private _isInited;
+    private _isBiometricAvailable;
+    private _biometricType;
+    private _isAccessRequested;
+    private _isAccessGranted;
+    private _isBiometricTokenSaved;
+    private _deviceId;
+    private initCallbacks;
+    private accessRequestState;
+    private authRequestState;
+    private tokenRequestState;
+    constructor(kernel: WebAppKernel);
+    get isInited(): boolean;
+    get isBiometricAvailable(): boolean;
+    get biometricType(): BiometricType;
+    get isAccessRequested(): boolean;
+    get isAccessGranted(): boolean;
+    get isBiometricTokenSaved(): boolean;
+    get deviceId(): string;
+    private handleInfoReceived;
+    private handleAuthRequested;
+    private handleTokenUpdated;
+    private checkVersion;
+    private checkInit;
+    init(callback?: InitCallback$1): this;
+    requestAccess(params: BiometricRequestAccessParams, callback?: AccessCallback): this;
+    authenticate(params: BiometricAuthenticateParams, callback?: AuthCallback): this;
+    updateBiometricToken(token: string, callback?: TokenCallback): this;
+    openSettings(): this;
+}
+
+/**
+ * `Telegram.WebApp.LocationManager`.
+ */
+
+type InitCallback = () => void;
+type GetLocationCallback = (data: LocationData | null) => void;
+declare class LocationManager {
+    private readonly kernel;
+    private _isInited;
+    private _isLocationAvailable;
+    private _isAccessRequested;
+    private _isAccessGranted;
+    private initCallbacks;
+    private getRequestCallbacks;
+    constructor(kernel: WebAppKernel);
+    get isInited(): boolean;
+    get isLocationAvailable(): boolean;
+    get isAccessRequested(): boolean;
+    get isAccessGranted(): boolean;
+    private handleLocationChecked;
+    private handleLocationRequested;
+    private locationResponse;
+    private checkVersion;
+    private checkInit;
+    init(callback?: InitCallback): this;
+    getLocation(callback: GetLocationCallback): this;
+    openSettings(): this;
+}
+
+/**
+ * Shared implementation for the three near-identical motion sensors
+ * (`Accelerometer`, `Gyroscope`, `DeviceOrientation`). All three follow the
+ * exact same start/stop/changed/failed event protocol in the original SDK,
+ * differing only in event names and payload shape - so we factor that
+ * protocol out once here and let each sensor supply its own config +
+ * payload mapping.
+ */
+
+interface MotionSensorEventNames {
+    started: string;
+    stopped: string;
+    changed: string;
+    failed: string;
+    webViewStarted: string;
+    webViewStopped: string;
+    webViewChanged: string;
+    webViewFailed: string;
+    startCommand: string;
+    stopCommand: string;
+    minVersion: string;
+    displayName: string;
+}
+type StartCallback = (success: boolean) => void;
+type StopCallback = (success: boolean) => void;
+declare abstract class MotionSensorBase<TValues extends Record<string, any>> {
+    protected readonly kernel: WebAppKernel;
+    private readonly names;
+    protected _isStarted: boolean;
+    protected values: TValues;
+    private startCallbacks;
+    private stopCallbacks;
+    protected constructor(kernel: WebAppKernel, names: MotionSensorEventNames, initialValues: TValues);
+    get isStarted(): boolean;
+    private handleStarted;
+    private handleStopped;
+    private handleChanged;
+    private handleFailed;
+    /** Subclasses map the raw `*_changed` event payload onto their typed value shape. */
+    protected abstract mapChangedPayload(eventData: any): TValues;
+    protected checkVersion(): boolean;
+    protected buildStartParams(refreshRate: unknown): {
+        refresh_rate?: number;
+    };
+    protected doStart(reqParams: Record<string, any>, callback?: StartCallback): void;
+    stop(callback?: StopCallback): this;
+}
+
+interface AccelerometerValues {
+    x: number | null;
+    y: number | null;
+    z: number | null;
+}
+declare class Accelerometer extends MotionSensorBase<AccelerometerValues> {
+    constructor(kernel: WebAppKernel);
+    protected mapChangedPayload(eventData: any): AccelerometerValues;
+    get x(): number | null;
+    get y(): number | null;
+    get z(): number | null;
+    start(params?: MotionSensorStartParams, callback?: (success: boolean) => void): this;
+}
+
+interface GyroscopeValues {
+    x: number | null;
+    y: number | null;
+    z: number | null;
+}
+declare class Gyroscope extends MotionSensorBase<GyroscopeValues> {
+    constructor(kernel: WebAppKernel);
+    protected mapChangedPayload(eventData: any): GyroscopeValues;
+    get x(): number | null;
+    get y(): number | null;
+    get z(): number | null;
+    start(params?: MotionSensorStartParams, callback?: (success: boolean) => void): this;
+}
+
+interface DeviceOrientationValues {
+    absolute: boolean;
+    alpha: number | null;
+    beta: number | null;
+    gamma: number | null;
+}
+declare class DeviceOrientation extends MotionSensorBase<DeviceOrientationValues> {
+    constructor(kernel: WebAppKernel);
+    protected mapChangedPayload(eventData: any): DeviceOrientationValues;
+    get absolute(): boolean;
+    get alpha(): number | null;
+    get beta(): number | null;
+    get gamma(): number | null;
+    start(params?: DeviceOrientationStartParams, callback?: (success: boolean) => void): this;
+}
+
+/**
+ * `Telegram.WebApp` - the public-facing composition root.
+ *
+ * This class owns no protocol logic itself; it wires the kernel + every
+ * feature module together (dependency injection) and re-exposes their
+ * public surface under the exact same property/method names as the
+ * original monolithic script, so existing integrations keep working
+ * unchanged (just typed, and testable module-by-module now).
+ *
+ * Adding a new feature later means: write a small class in `features/`,
+ * `sensors/`, `ui/` or `theme/` that takes a `WebAppKernel`, then
+ * instantiate + expose it here. No other module needs to change.
+ */
+
+declare class WebApp {
+    readonly webView: TelegramWebView;
+    private readonly kernel;
+    private webAppInitData;
+    private webAppInitDataUnsafe;
+    private webAppPlatform;
+    private webAppIsActive;
+    private readonly theme;
+    private readonly viewport;
+    private readonly debugBar;
+    readonly BackButton: BackButton;
+    readonly MainButton: BottomButton;
+    readonly SecondaryButton: BottomButton;
+    readonly SettingsButton: SettingsButton;
+    readonly HapticFeedback: HapticFeedback;
+    readonly CloudStorage: CloudStorage;
+    readonly DeviceStorage: DeviceStorage;
+    readonly SecureStorage: SecureStorage;
+    readonly BiometricManager: BiometricManager;
+    readonly LocationManager: LocationManager;
+    readonly Accelerometer: Accelerometer;
+    readonly DeviceOrientation: DeviceOrientation;
+    readonly Gyroscope: Gyroscope;
+    private readonly popups;
+    private readonly scanQr;
+    private readonly invoices;
+    private readonly clipboard;
+    private readonly contact;
+    private readonly homeScreen;
+    private readonly downloadFileManager;
+    private readonly sharing;
+    private readonly emojiStatus;
+    private readonly links;
+    constructor(webView: TelegramWebView);
+    private handleThemeChanged;
+    private handleVisibilityChanged;
+    get initData(): string;
+    get initDataUnsafe(): WebAppInitDataUnsafe;
+    get version(): string;
+    get platform(): string;
+    get colorScheme(): ColorScheme;
+    get themeParams(): ThemeParams;
+    get isExpanded(): boolean;
+    get viewportHeight(): number;
+    get viewportStableHeight(): number;
+    get safeAreaInset(): SafeAreaInset;
+    get contentSafeAreaInset(): SafeAreaInset;
+    get isFullscreen(): boolean;
+    get isActive(): boolean;
+    get isClosingConfirmationEnabled(): boolean;
+    set isClosingConfirmationEnabled(val: boolean);
+    get isVerticalSwipesEnabled(): boolean;
+    set isVerticalSwipesEnabled(val: boolean);
+    get isOrientationLocked(): boolean;
+    set isOrientationLocked(val: boolean);
+    get headerColor(): string | null | undefined;
+    set headerColor(val: string);
+    get backgroundColor(): string | undefined;
+    set backgroundColor(val: string);
+    get bottomBarColor(): string;
+    set bottomBarColor(val: string);
+    isVersionAtLeast(ver: string): boolean;
+    setHeaderColor(colorKey: string): void;
+    setBackgroundColor(color: string): void;
+    setBottomBarColor(color: string): void;
+    enableClosingConfirmation(): void;
+    disableClosingConfirmation(): void;
+    enableVerticalSwipes(): void;
+    disableVerticalSwipes(): void;
+    lockOrientation(): void;
+    unlockOrientation(): void;
+    requestFullscreen(): void;
+    exitFullscreen(): void;
+    addToHomeScreen(): void;
+    checkHomeScreenStatus(callback?: (status: HomeScreenStatus) => void): void;
+    onEvent(eventType: string, callback: (...args: any[]) => void): void;
+    offEvent(eventType: string, callback: (...args: any[]) => void): void;
+    sendData(data: string): void;
+    switchInlineQuery(query: string, chooseChatTypes?: string[]): void;
+    openLink(url: string, options?: OpenLinkOptions): void;
+    openTelegramLink(url: string, options?: OpenTelegramLinkOptions): void;
+    openInvoice(url: string, callback?: (status: 'paid' | 'cancelled' | 'failed' | 'pending') => void): void;
+    showPopup(params: PopupParams, callback?: (buttonId: string | null) => void): void;
+    showAlert(message: string, callback?: () => void): void;
+    showConfirm(message: string, callback?: (ok: boolean) => void): void;
+    showScanQrPopup(params: ScanQrPopupParams, callback?: (data: string | null) => boolean | void): void;
+    closeScanQrPopup(): void;
+    readTextFromClipboard(callback?: (data: string | null) => void): void;
+    requestWriteAccess(callback?: (granted: boolean) => void): void;
+    requestContact(callback?: (sent: boolean, eventPayload: Record<string, any>) => void): void;
+    downloadFile(params: DownloadFileParams, callback?: (isDownloading: boolean) => void): void;
+    shareToStory(mediaUrl: string, params?: ShareToStoryParams): void;
+    shareMessage(msgId: string, callback?: (sent: boolean) => void): void;
+    requestChat(reqId: string, callback?: (sent: boolean) => void): void;
+    setEmojiStatus(customEmojiId: string, params?: {
+        duration?: number;
+    }, callback?: (applied: boolean) => void): void;
+    requestEmojiStatusAccess(callback?: (granted: boolean) => void): void;
+    invokeCustomMethod(method: string, params?: Record<string, any>, callback?: (err: any, res: any) => void): void;
+    hideKeyboard(): void;
+    ready(): void;
+    expand(): void;
+    close(options?: CloseOptions): void;
+}
+
+/**
+ * Public-facing types for `window.Telegram.WebApp`, used throughout
+ * `core/`, `react/hooks.ts`, and `_internal/providers/TelegramProvider.tsx`.
+ *
+ * These are now thin re-exports/aliases of the bundled SDK's real types
+ * (`../sdk`) rather than a hand-maintained parallel interface set. Two
+ * things made that possible:
+ *
+ * 1. `TgWebApp` is a straight alias for the SDK's real `WebApp` class -
+ *    every property/method here is authoritative, not a best-effort copy
+ *    that can drift out of sync.
+ * 2. `core/dev.ts` no longer builds a plain-object mock that has to
+ *    structurally satisfy this type (see its own docs): it seeds fake init
+ *    data and lets the *real* SDK bootstrap from it, so there's no more
+ *    need for a parallel, private-field-free interface just to keep mocks
+ *    buildable.
+ *
+ * `getWebApp()` in `core/index.ts` returns the SDK's `WebApp` type
+ * directly; `TgWebApp` exists mainly so older imports of this module don't
+ * need to change.
+ */
+
+/** `WebApp.setEmojiStatus()` options. Not exported by the SDK as a named type (it's inline there), so kept here. */
+interface EmojiStatusParams {
+    duration?: number;
+}
+type WebAppEventType = 'activated' | 'deactivated' | 'themeChanged' | 'viewportChanged' | 'safeAreaChanged' | 'contentSafeAreaChanged' | 'mainButtonClicked' | 'secondaryButtonClicked' | 'backButtonClicked' | 'settingsButtonClicked' | 'invoiceClosed' | 'popupClosed' | 'qrTextReceived' | 'scanQrPopupClosed' | 'clipboardTextReceived' | 'writeAccessRequested' | 'contactRequested' | 'biometricManagerUpdated' | 'biometricAuthRequested' | 'biometricTokenUpdated' | 'fullscreenChanged' | 'fullscreenFailed' | 'homeScreenAdded' | 'homeScreenChecked' | 'accelerometerStarted' | 'accelerometerStopped' | 'accelerometerChanged' | 'accelerometerFailed' | 'deviceOrientationStarted' | 'deviceOrientationStopped' | 'deviceOrientationChanged' | 'deviceOrientationFailed' | 'gyroscopeStarted' | 'gyroscopeStopped' | 'gyroscopeChanged' | 'gyroscopeFailed' | 'locationManagerUpdated' | 'locationRequested' | 'shareMessageSent' | 'shareMessageFailed' | 'emojiStatusSet' | 'emojiStatusFailed' | 'emojiStatusAccessRequested' | 'fileDownloadRequested' | 'customMethodInvoked';
+type TgPlatform = 'android' | 'android_x' | 'ios' | 'macos' | 'tdesktop' | 'weba' | 'webz' | 'webk' | 'unigram' | 'unknown';
+type RuntimeMode = 'node' | 'edge';
+/** The real, authoritative `WebApp` class from the bundled SDK. */
+type TgWebApp = WebApp;
+declare global {
+    interface Window {
+        Telegram?: {
+            WebApp: TgWebApp;
+            WebView?: unknown;
+            Utils?: unknown;
+        };
+    }
+}
+
+declare function useTelegramWebApp(): TgWebApp | null;
+declare function useTelegramUser(): WebAppUser | null;
+declare function useTelegramStartParam(): string | null;
+declare function useInitData(): string | null;
+declare function useReady(): void;
+declare function useShowPopup(): (params: {
+    title?: string;
+    message: string;
+    buttons?: Array<{
+        id?: string;
+        type?: 'default' | 'ok' | 'close' | 'cancel' | 'destructive';
+        text?: string;
+    }>;
+}) => Promise<string | null>;
+declare function useShowConfirm(): (message: string) => Promise<boolean>;
+declare function useShowAlert(): (message: string) => Promise<void>;
+declare function useScanQrPopup(): (params?: {
+    text?: string;
+}) => Promise<string | null>;
+declare function useReadTextFromClipboard(): () => Promise<string | null>;
+declare function useTelegramEvent(eventType: WebAppEventType | string, handler: (...args: unknown[]) => void): void;
+declare function useTelegramBackButton(options?: {
+    pathname?: string;
+    onBack?: () => void;
+    hideOnRoot?: boolean;
+}): void;
+declare function useTelegramMainButton(options: {
+    text: string;
+    onClick: () => void;
+    isVisible?: boolean;
+    isActive?: boolean;
+    color?: string;
+    textColor?: string;
+    hasShineEffect?: boolean;
+    showProgress?: boolean;
+}): void;
+declare function useTelegramSecondaryButton(options: {
+    text: string;
+    onClick: () => void;
+    isVisible?: boolean;
+    isActive?: boolean;
+    position?: 'left' | 'right' | 'top' | 'bottom';
+    color?: string;
+    textColor?: string;
+}): void;
+declare function useTelegramSettingsButton(onClick: () => void): void;
+declare function useHapticFeedback(): {
+    impact: (style?: "light" | "medium" | "heavy" | "rigid" | "soft") => void;
+    notification: (type: "error" | "success" | "warning") => void;
+    selectionChanged: () => void;
+};
+declare function useTelegramTheme(): {
+    colorScheme: "light" | "dark";
+    themeParams: ThemeParams;
+    isDark: boolean;
+};
+declare function useTelegramViewport(): {
+    expand: () => void;
+    height: number;
+    stableHeight: number;
+    isExpanded: boolean;
+};
+declare function useTelegramFullscreen(): {
+    isFullscreen: boolean;
+    error: {
+        error: string;
+    } | null;
+    enter: () => void;
+    exit: () => void;
+    toggle: () => void;
+};
+declare function useOrientationLock(): {
+    isLocked: boolean;
+    lock: () => void;
+    unlock: () => void;
+};
+declare function useSafeArea(): {
+    safeArea: SafeAreaInset;
+    contentSafeArea: SafeAreaInset;
+};
+declare function useIsActive(): boolean;
+declare function useCloudStorage(): {
+    setItem: (key: string, value: string) => Promise<boolean>;
+    getItem: (key: string) => Promise<string | undefined>;
+    getItems: (keys: string[]) => Promise<Record<string, string>>;
+    removeItem: (key: string) => Promise<boolean>;
+    removeItems: (keys: string[]) => Promise<boolean>;
+    getKeys: () => Promise<string[]>;
+};
+declare function useDeviceStorage(): {
+    setItem: (key: string, value: string) => Promise<boolean>;
+    getItem: (key: string) => Promise<string | undefined>;
+    removeItem: (key: string) => Promise<boolean>;
+    clear: () => Promise<boolean>;
+};
+declare function useSecureStorage(): {
+    setItem: (key: string, value: string) => Promise<boolean>;
+    getItem: (key: string) => Promise<{
+        value: string | null | undefined;
+        canRestore: boolean;
+    }>;
+    removeItem: (key: string) => Promise<boolean>;
+    clear: () => Promise<boolean>;
+    restoreItem: (key: string) => Promise<string | undefined>;
+};
+declare function useAccelerometer(options?: {
+    refreshRate?: number;
+    autoStart?: boolean;
+}): {
+    isStarted: boolean;
+    start: () => void;
+    stop: () => void;
+    x: number;
+    y: number;
+    z: number;
+};
+declare function useGyroscope(options?: {
+    refreshRate?: number;
+    autoStart?: boolean;
+}): {
+    isStarted: boolean;
+    start: () => void;
+    stop: () => void;
+    x: number;
+    y: number;
+    z: number;
+};
+declare function useDeviceOrientation(options?: {
+    refreshRate?: number;
+    needAbsolute?: boolean;
+    autoStart?: boolean;
+}): {
+    isStarted: boolean;
+    start: () => void;
+    stop: () => void;
+    alpha: number;
+    beta: number;
+    gamma: number;
+    absolute: boolean;
+};
+declare function useBiometric(): {
+    isInited: boolean;
+    isAvailable: boolean;
+    biometricType: "unknown" | "finger" | "face";
+    init: () => Promise<void>;
+    requestAccess: (reason?: string) => Promise<boolean>;
+    authenticate: (reason?: string) => Promise<{
+        authenticated: boolean;
+        token?: string;
+    }>;
+    updateBiometricToken: (token: string) => Promise<boolean>;
+    openSettings: () => void;
+};
+declare function useLocation(): {
+    locationData: LocationData | null;
+    isInited: boolean;
+    isGranted: boolean;
+    init: () => Promise<void>;
+    getLocation: () => Promise<LocationData | null>;
+    openSettings: () => void;
+};
+declare function useHomeScreen(): {
+    status: "unsupported" | "unknown" | "added" | "missed" | null;
+    addToHomeScreen: () => void;
+    checkHomeScreenStatus: () => void;
+};
+declare function useShareToStory(): (mediaUrl: string, params?: ShareToStoryParams) => void;
+declare function useShareMessage(): (msgId: string) => Promise<boolean>;
+declare function useSetEmojiStatus(): (customEmojiId: string, params?: EmojiStatusParams) => Promise<boolean>;
+declare function useRequestEmojiStatusAccess(): () => Promise<boolean>;
+declare function useDownloadFile(): (params: DownloadFileParams) => Promise<boolean>;
+declare function useRequestWriteAccess(): () => Promise<boolean>;
+declare function useRequestContact(): () => Promise<boolean>;
+declare function useSwitchInlineQuery(): (query: string, chooseChatTypes?: Array<"users" | "bots" | "groups" | "channels">) => void;
+/**
+ * Opens Telegram's native chat-request dialog for a chat request you
+ * already created server-side, identified by `reqId`. Requires Bot API
+ * 9.6+.
+ */
+declare function useRequestChat(): (reqId: string) => Promise<boolean>;
+declare function useHideKeyboard(): () => void;
+declare function useInvokeCustomMethod(): (method: string, params?: object) => Promise<unknown>;
+
+export { type TgWebApp as $, Accelerometer as A, BackButton as B, type CloseOptions as C, type DownloadFileParams as D, type ErrCallback as E, type PopupButtonType as F, Gyroscope as G, type HomeScreenStatus as H, type InitParams as I, SecureStorage as J, SettingsButton as K, type LocationData as L, type MotionSensorStartParams as M, type ShareToStoryWidgetLink as N, type OpenLinkOptions as O, type PopupParams as P, ThemeManager as Q, type ThemeParams as R, type SafeAreaInset as S, TelegramWebView as T, Utils as U, type VoidCallback as V, WebAppKernel as W, type WebAppChat as X, type WebAppInitDataUnsafe as Y, type WebAppUser as Z, type EmojiStatusParams as _, type ScanQrPopupParams as a, type RuntimeMode as a0, type TgPlatform as a1, type WebAppEventType as a2, useAccelerometer as a3, useBiometric as a4, useCloudStorage as a5, useDeviceOrientation as a6, useDeviceStorage as a7, useDownloadFile as a8, useGyroscope as a9, useTelegramFullscreen as aA, useTelegramMainButton as aB, useTelegramSecondaryButton as aC, useTelegramSettingsButton as aD, useTelegramStartParam as aE, useTelegramTheme as aF, useTelegramUser as aG, useTelegramViewport as aH, useTelegramWebApp as aI, useHapticFeedback as aa, useHideKeyboard as ab, useHomeScreen as ac, useInitData as ad, useInvokeCustomMethod as ae, useIsActive as af, useLocation as ag, useOrientationLock as ah, useReadTextFromClipboard as ai, useReady as aj, useRequestChat as ak, useRequestContact as al, useRequestEmojiStatusAccess as am, useRequestWriteAccess as an, useSafeArea as ao, useScanQrPopup as ap, useSecureStorage as aq, useSetEmojiStatus as ar, useShareMessage as as, useShareToStory as at, useShowAlert as au, useShowConfirm as av, useShowPopup as aw, useSwitchInlineQuery as ax, useTelegramBackButton as ay, useTelegramEvent as az, type ShareToStoryParams as b, type OpenTelegramLinkOptions as c, WebApp as d, type AnyRecord as e, type BiometricAuthenticateParams as f, BiometricManager as g, type BiometricRequestAccessParams as h, type BiometricType as i, BottomButton as j, type BottomButtonParams as k, type BottomButtonPosition as l, CloudStorage as m, type ColorScheme as n, DebugBottomBar as o, type DefaultColors as p, DeviceOrientation as q, type DeviceOrientationStartParams as r, DeviceStorage as s, type EventHandler as t, HapticFeedback as u, type HapticImpactStyle as v, type HapticNotificationType as w, type ItemsCallback as x, LocationManager as y, type PopupButton as z };