@wowlabtech/mini-app-adapter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,511 @@
+import { ImpactHapticFeedbackStyle, NotificationHapticFeedbackType } from '@tma.js/bridge';
+import { TapticVibrationPowerType, TapticNotificationType } from '@vkontakte/vk-bridge';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type ShellPlatform = 'shell_ios' | 'shell_android';
+interface ShellStoreTokenPayload {
+    token?: string;
+    [key: string]: unknown;
+}
+type PushListener = (token: string) => void;
+type DeepLinkListener = (path: string) => void;
+type VoidListener = () => void;
+interface ShellAPI {
+    openNativeQR(): Promise<string>;
+    onPushToken(callback: PushListener): () => void;
+    onDeepLink(callback: DeepLinkListener): () => void;
+    onAppActive(callback: VoidListener): () => void;
+    onAppBackground(callback: VoidListener): () => void;
+}
+declare function isShell(platform: MiniAppPlatform): platform is ShellPlatform;
+declare function isShellIOS(platform: MiniAppPlatform): platform is 'shell_ios';
+declare function isShellAndroid(platform: MiniAppPlatform): platform is 'shell_android';
+declare function readShellPlatform(): ShellPlatform | undefined;
+type PlatformResolver = MiniAppPlatform | (() => MiniAppPlatform);
+declare function createShellAPI(platform: PlatformResolver): ShellAPI;
+declare const shell: ShellAPI;
+declare function storeShellToken(payload?: ShellStoreTokenPayload): boolean;
+declare function requestShellPushPermission(): boolean;
+
+type MiniAppPlatform = 'telegram' | 'vk' | 'max' | 'web' | 'shell_ios' | 'shell_android';
+interface MiniAppEnvironmentInfo {
+    platform: MiniAppPlatform;
+    sdkVersion?: string;
+    appVersion?: string;
+    languageCode?: string;
+    appearance?: string;
+    isWebView?: boolean;
+    hasNativeQR?: boolean;
+    hasPush?: boolean;
+    hasWidgets?: boolean;
+    safeArea?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+interface MiniAppSafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface MiniAppViewportInsets {
+    safeArea: MiniAppSafeAreaInsets;
+    contentSafeArea: MiniAppSafeAreaInsets;
+}
+interface MiniAppInitOptions {
+    /**
+     * Enables verbose logs for platforms that support it.
+     */
+    debug?: boolean;
+    /**
+     * Dynamically loads Eruda devtools if supported.
+     */
+    eruda?: boolean;
+    /**
+     * Allows adapters to mock vendor-specific quirks (e.g. Telegram macOS client).
+     */
+    mockForMacOS?: boolean;
+}
+interface MiniAppShareStoryOptions {
+    text?: string;
+    widgetLink?: {
+        url: string;
+        name?: string;
+    };
+}
+type MiniAppCapability = 'haptics' | 'popup' | 'qrScanner' | 'closeApp' | 'backButton' | 'backButtonVisibility' | 'bindCssVariables' | 'requestPhone' | 'notifications';
+interface MiniAppPopupButton {
+    id: string;
+    text?: string;
+    type?: 'default' | 'ok' | 'destructive';
+}
+interface MiniAppPopupOptions {
+    title: string;
+    message: string;
+    buttons?: MiniAppPopupButton[];
+}
+interface MiniAppQrScanOptions {
+    /**
+     * Closes scanner right after the QR code was captured. Defaults to true.
+     */
+    closeOnCapture?: boolean;
+}
+interface MiniAppAdapter {
+    readonly platform: MiniAppPlatform;
+    readonly shell: ShellAPI;
+    /**
+     * Quick capability check before calling platform specific APIs.
+     */
+    supports(capability: MiniAppCapability): boolean | Promise<boolean>;
+    /**
+     * Initializes platform SDK. Safe to call multiple times.
+     */
+    init(options?: MiniAppInitOptions): Promise<void>;
+    /**
+     * Indicates whether init step finished successfully.
+     */
+    isReady(): boolean;
+    /**
+     * Reads environment specific data exposed by the host Mini App platform.
+     */
+    getEnvironment(): MiniAppEnvironmentInfo;
+    /**
+     * Tears down adapter listeners/resources when it is no longer used.
+     */
+    destroy?(): void;
+    /**
+     * Applies navigation / background colors if supported by the host platform.
+     */
+    setColors(colors: {
+        header?: string;
+        background?: string;
+        footer?: string;
+    }): Promise<void>;
+    /**
+     * Registers a callback for platform back button.
+     * Returns disposer that removes the listener.
+     */
+    onBackButton(callback: () => void): () => void;
+    /**
+     * Opens external link using platform capabilities.
+     */
+    openExternalLink(url: string): Promise<void>;
+    /**
+     * Opens internal link using platform capabilities.
+     */
+    openInternalLink(url: string): Promise<void>;
+    /**
+     * Closes the host mini app if supported.
+     */
+    closeApp(): Promise<void>;
+    /**
+     * Updates visibility of the native back button if supported.
+     */
+    setBackButtonVisibility(visible: boolean): void;
+    /**
+     * Optional hook allowing adapters to expose debug helpers.
+     */
+    enableDebug?(state: boolean): void;
+    /**
+     * Subscribes to appearance changes if supported by the platform.
+     */
+    onAppearanceChange?(callback: (appearance: 'dark' | 'light' | undefined) => void): () => void;
+    /**
+     * Provides raw init data string, if available.
+     */
+    getInitData?(): string | undefined;
+    /**
+     * Reads platform launch parameters, if available.
+     */
+    getLaunchParams?(): unknown;
+    /**
+     * Decodes platform specific start parameter.
+     */
+    decodeStartParam?(param: string): unknown;
+    /**
+     * Requests fullscreen mode if supported by the platform.
+     */
+    requestFullscreen?(): void;
+    /**
+     * Returns viewport safe area insets if supported by the platform.
+     */
+    getViewportInsets?(): MiniAppViewportInsets | undefined;
+    /**
+     * Aggregates all known safe area insets into a single value.
+     */
+    computeSafeArea(): MiniAppEnvironmentInfo['safeArea'];
+    /**
+     * Binds platform theme variables to CSS custom properties.
+     */
+    bindCssVariables(mapper?: (key: string) => string): void;
+    /**
+     * Strong/weak haptic feedback helpers.
+     */
+    vibrateImpact(style: ImpactHapticFeedbackStyle): void;
+    vibrateNotification(type: NotificationHapticFeedbackType): void;
+    vibrateSelection(): void;
+    /**
+     * Notifies when the host view goes to background/foreground (VK only).
+     */
+    onViewHide?(callback: () => void): () => void;
+    onViewRestore?(callback: () => void): () => void;
+    /**
+     * Enables or disables vertical swipe gestures if supported by the platform.
+     */
+    enableVerticalSwipes?(): void;
+    disableVerticalSwipes?(): void;
+    /**
+     * Displays native popup if available.
+     * Resolves with button id or null if popup was dismissed.
+     */
+    showPopup(options: MiniAppPopupOptions): Promise<string | null>;
+    /**
+     * Opens QR scanner and resolves with scanned value (if any).
+     */
+    scanQRCode(options?: MiniAppQrScanOptions): Promise<string | null>;
+    /**
+     * Requests phone number from the host platform if supported.
+     */
+    requestPhone(): Promise<string | null>;
+    /**
+     * Requests permission to send push notifications (platform-specific).
+     * Resolves with true if permission was granted.
+     */
+    requestNotificationsPermission?(): Promise<boolean>;
+    /**
+     * Subscribes to push token updates delivered by native shells.
+     */
+    onPushToken(listener: (token: string) => void): () => void;
+    /**
+     * Subscribes to native deep link events exposed by shell containers.
+     */
+    onDeepLink(listener: (path: string) => void): void;
+    /**
+     * Subscribes to adapter environment updates (safe area, appearance etc.).
+     */
+    subscribe?(listener: () => void): () => void;
+    /**
+     * Shares a message using platform-specific capabilities.
+     */
+    shareMessage?(message: string): Promise<void>;
+    /**
+     * Shares a URL using platform-specific capabilities.
+     */
+    shareUrl?(url: string, text: string): void;
+    /**
+     * Copies text to the clipboard if supported by the platform.
+     */
+    copyTextToClipboard?(text: string): Promise<void>;
+    /**
+     * Downloads a file using platform-specific capabilities.
+     */
+    downloadFile?(url: string, filename: string): Promise<void>;
+    /**
+     * Shares a story using platform-specific capabilities.
+     */
+    shareStory?(mediaUrl: string, options?: MiniAppShareStoryOptions): Promise<void>;
+    /**
+     * Sends analytics event to the host platform if supported.
+     */
+    trackConversionEvent(event: string, payload?: Record<string, unknown>): void;
+    /**
+     * Sends retargeting pixel event if supported.
+     */
+    trackPixelEvent(event: string, payload?: Record<string, unknown>): void;
+}
+
+type Disposable = (() => void) | {
+    dispose: () => void;
+} | null | undefined;
+
+declare abstract class BaseMiniAppAdapter implements MiniAppAdapter {
+    protected ready: boolean;
+    protected environment: MiniAppEnvironmentInfo;
+    private listeners;
+    private readonly disposables;
+    readonly shell: ShellAPI;
+    protected constructor(platform: MiniAppPlatform, environment?: Partial<MiniAppEnvironmentInfo>);
+    supports(_capability: MiniAppCapability): boolean | Promise<boolean>;
+    get platform(): MiniAppPlatform;
+    init(_options?: MiniAppInitOptions): Promise<void>;
+    isReady(): boolean;
+    getEnvironment(): MiniAppEnvironmentInfo;
+    destroy(): void;
+    subscribe(listener: () => void): () => void;
+    setColors(colors: {
+        header?: string;
+        background?: string;
+    }): Promise<void>;
+    onBackButton(callback: () => void): () => void;
+    onPushToken(callback: (token: string) => void): () => void;
+    onDeepLink(callback: (path: string) => void): () => void;
+    openExternalLink(url: string): Promise<void>;
+    openInternalLink(_url: string): Promise<void>;
+    closeApp(): Promise<void>;
+    setBackButtonVisibility(_visible: boolean): void;
+    onAppearanceChange(callback: (appearance: 'dark' | 'light' | undefined) => void): () => void;
+    getInitData(): string | undefined;
+    getLaunchParams(): unknown;
+    decodeStartParam(_param: string): unknown;
+    requestFullscreen(): void;
+    getViewportInsets(): MiniAppViewportInsets | undefined;
+    shareMessage(_message: string): Promise<void>;
+    shareUrl(_url: string, _text: string): void;
+    downloadFile(url: string, filename: string): Promise<void>;
+    shareStory(_mediaUrl: string, _options?: MiniAppShareStoryOptions): Promise<void>;
+    trackConversionEvent(_event: string, _payload?: Record<string, unknown>): void;
+    trackPixelEvent(_event: string, _payload?: Record<string, unknown>): void;
+    copyTextToClipboard(text: string): Promise<void>;
+    computeSafeArea(): MiniAppEnvironmentInfo['safeArea'];
+    bindCssVariables(_mapper?: (key: string) => string): void;
+    vibrateImpact(_style: ImpactHapticFeedbackStyle): void;
+    vibrateNotification(_type: NotificationHapticFeedbackType): void;
+    vibrateSelection(): void;
+    onViewHide(_callback: () => void): () => void;
+    onViewRestore(_callback: () => void): () => void;
+    showPopup(options: MiniAppPopupOptions): Promise<string | null>;
+    scanQRCode(_options?: MiniAppQrScanOptions): Promise<string | null>;
+    requestPhone(): Promise<string | null>;
+    requestNotificationsPermission(): Promise<boolean>;
+    enableVerticalSwipes(): void;
+    disableVerticalSwipes(): void;
+    protected notifyEnvironmentChanged(): void;
+    protected onDestroy(): void;
+    protected registerDisposable(disposable: Disposable): () => void;
+    private applyScrollGuards;
+}
+
+declare class MaxMiniAppAdapter extends BaseMiniAppAdapter {
+    private readonly backHandlers;
+    private initData?;
+    private initDataUnsafe?;
+    constructor();
+    init(_options?: MiniAppInitOptions): Promise<void>;
+    supports(capability: MiniAppCapability): boolean;
+    getInitData(): string | undefined;
+    getLaunchParams(): unknown;
+    onBackButton(callback: () => void): () => void;
+    setBackButtonVisibility(visible: boolean): void;
+    openExternalLink(url: string): Promise<void>;
+    closeApp(): Promise<void>;
+    vibrateImpact(style: ImpactHapticFeedbackStyle): void;
+    vibrateNotification(type: NotificationHapticFeedbackType): void;
+    vibrateSelection(): void;
+    scanQRCode(options?: MiniAppQrScanOptions): Promise<string | null>;
+    requestPhone(): Promise<string | null>;
+    showPopup(options: MiniAppPopupOptions): Promise<string | null>;
+    downloadFile(url: string, filename: string): Promise<void>;
+    private requestPhoneViaEvent;
+    private extractPhone;
+    protected onDestroy(): void;
+}
+
+declare class ShellMiniAppAdapter extends BaseMiniAppAdapter {
+    constructor(platform: 'shell_ios' | 'shell_android');
+    supports(capability: MiniAppCapability): boolean | Promise<boolean>;
+    scanQRCode(): Promise<string | null>;
+    requestNotificationsPermission(): Promise<boolean>;
+}
+
+declare class TelegramMiniAppAdapter extends BaseMiniAppAdapter {
+    private readonly backHandlers;
+    private cssVariablesBound;
+    private readonly appearanceListeners;
+    private appearanceWatcherDispose?;
+    private readonly viewHideListeners;
+    private readonly viewRestoreListeners;
+    private activeWatcherDispose?;
+    constructor();
+    init(options?: MiniAppInitOptions): Promise<void>;
+    setColors(colors: {
+        header?: string;
+        background?: string;
+        footer?: string;
+    }): Promise<void>;
+    copyTextToClipboard(text: string): Promise<void>;
+    onBackButton(callback: () => void): () => void;
+    openExternalLink(url: string): Promise<void>;
+    openInternalLink(url: string): Promise<void>;
+    enableDebug(state: boolean): void;
+    supports(capability: MiniAppCapability): boolean;
+    bindCssVariables(mapper?: (key: string) => string): void;
+    vibrateImpact(style: ImpactHapticFeedbackStyle): void;
+    vibrateNotification(type: NotificationHapticFeedbackType): void;
+    vibrateSelection(): void;
+    showPopup(options: MiniAppPopupOptions): Promise<string | null>;
+    scanQRCode(options?: MiniAppQrScanOptions): Promise<string | null>;
+    closeApp(): Promise<void>;
+    getInitData(): string | undefined;
+    getLaunchParams(): unknown;
+    decodeStartParam(param: string): unknown;
+    requestFullscreen(): void;
+    getViewportInsets(): MiniAppViewportInsets | undefined;
+    onAppearanceChange(callback: (appearance: 'dark' | 'light' | undefined) => void): () => void;
+    setBackButtonVisibility(visible: boolean): void;
+    enableVerticalSwipes(): void;
+    disableVerticalSwipes(): void;
+    onViewHide(callback: () => void): () => void;
+    onViewRestore(callback: () => void): () => void;
+    shareUrl(url: string, text?: string): void;
+    downloadFile(url: string, filename: string): Promise<void>;
+    shareStory(mediaUrl: string, options?: MiniAppShareStoryOptions): Promise<void>;
+    requestPhone(): Promise<string | null>;
+    private setupAppearanceWatcher;
+    private notifyAppearance;
+    private setupActiveWatcher;
+    private prepareViewport;
+    private requestFullscreenInternal;
+    private getViewportMountOptions;
+    private notifyViewHide;
+    private notifyViewRestore;
+    protected onDestroy(): void;
+}
+
+declare class VKMiniAppAdapter extends BaseMiniAppAdapter {
+    private configSafeArea?;
+    private stopViewportTracking?;
+    private readonly supportsAsync?;
+    private pixelCodeWarningShown;
+    computeSafeArea(): MiniAppEnvironmentInfo['safeArea'];
+    private unsubscribe?;
+    private launchParams?;
+    private queryParams?;
+    private readonly viewHideListeners;
+    private readonly viewRestoreListeners;
+    constructor();
+    init(_options?: MiniAppInitOptions): Promise<void>;
+    vibrateImpact(style: TapticVibrationPowerType): Promise<void>;
+    vibrateNotification(type: TapticNotificationType): Promise<void>;
+    vibrateSelection(): Promise<void>;
+    setColors(colors: {
+        header?: string;
+        background?: string;
+    }): Promise<void>;
+    getEnvironment(): MiniAppEnvironmentInfo;
+    getLaunchParams(): unknown;
+    supports(capability: MiniAppCapability): Promise<boolean>;
+    requestPhone(): Promise<string | null>;
+    requestNotificationsPermission(): Promise<boolean>;
+    scanQRCode(options?: MiniAppQrScanOptions): Promise<string | null>;
+    onViewHide(callback: () => void): () => void;
+    onViewRestore(callback: () => void): () => void;
+    shareStory(mediaUrl: string, _options?: MiniAppShareStoryOptions): Promise<void>;
+    downloadFile(url: string, filename: string): Promise<void>;
+    trackConversionEvent(event: string, payload?: Record<string, unknown>): void;
+    trackPixelEvent(event: string, payload?: Record<string, unknown>): void;
+    private dispatchAnalytics;
+    private emitAnalyticsFallback;
+    private normalizeAnalyticsEventName;
+    private normalizeAnalyticsPayload;
+    private isPlainObject;
+    private safeBridgeSend;
+    private composeEnvironment;
+    private handleBridgeEvent;
+    private updateEnvironmentFromConfig;
+    private applyAppearance;
+    private resolveStatusBarStyle;
+    private normalizeAppearance;
+    private extractSafeAreaFromConfig;
+    private notifyVisibilityListeners;
+    private computeBaseSafeArea;
+    private startViewportTracking;
+    private resolveOverlayInsets;
+    private isLikelyMobilePlatform;
+    private resolveLaunchParam;
+    private supportsBridgeMethod;
+    protected onDestroy(): void;
+}
+
+declare class WebMiniAppAdapter extends BaseMiniAppAdapter {
+    constructor();
+    downloadFile(url: string, filename: string): Promise<void>;
+    scanQRCode(_options?: MiniAppQrScanOptions): Promise<string | null>;
+}
+
+interface CreateAdapterOptions {
+    platform?: MiniAppPlatform;
+    vk?: {
+        pixelCode?: string;
+    };
+}
+declare function detectPlatform(): MiniAppPlatform;
+declare function createAdapter(): MiniAppAdapter;
+declare function createAdapter(platform: MiniAppPlatform): MiniAppAdapter;
+declare function createAdapter(options: CreateAdapterOptions): MiniAppAdapter;
+
+interface AdapterProviderProps {
+    adapter: MiniAppAdapter;
+    children: ReactNode;
+}
+declare function AdapterProvider({ adapter, children }: AdapterProviderProps): react_jsx_runtime.JSX.Element;
+declare function useMiniAppAdapter(): MiniAppAdapter;
+
+type ThemePreference = 'system' | 'light' | 'dark';
+declare function useAdapterTheme(): {
+    readonly isDark: boolean;
+    readonly appearance: "dark" | "light";
+    readonly preference: ThemePreference;
+    readonly setPreference: (pref: ThemePreference) => void;
+    readonly toggle: () => void;
+};
+
+declare function useSafeArea(): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+
+declare function getActiveAdapter(): MiniAppAdapter | null;
+
+declare function configureVkPixel(pixelCode: string): void;
+declare function trackConversionEvent(event: string, payload?: Record<string, unknown>): void;
+declare function trackPixelEvent(event: string, payload?: Record<string, unknown>): void;
+
+declare function getPlatform(): MiniAppPlatform;
+
+export { AdapterProvider, BaseMiniAppAdapter, type CreateAdapterOptions, MaxMiniAppAdapter, type MiniAppAdapter, type MiniAppCapability, type MiniAppEnvironmentInfo, type MiniAppInitOptions, type MiniAppPlatform, type MiniAppPopupOptions, type MiniAppQrScanOptions, ShellMiniAppAdapter, TelegramMiniAppAdapter, VKMiniAppAdapter, WebMiniAppAdapter, configureVkPixel, createAdapter, createShellAPI, detectPlatform, getActiveAdapter, getPlatform, isShell, isShellAndroid, isShellIOS, readShellPlatform, requestShellPushPermission, shell, storeShellToken, trackConversionEvent, trackPixelEvent, useAdapterTheme, useMiniAppAdapter, useSafeArea };