@tma.js/sdk 0.11.3

package/dist/types/components/Viewport/Viewport.d.ts

@@ -0,0 +1,108 @@
+import { type RequestOptions, type PostEvent } from '@tma.js/bridge';
+export interface RequestViewportResult {
+    height: number;
+    isStateStable: boolean;
+    isExpanded: boolean;
+    width: number;
+}
+/**
+ * Contains information about current WebApp device viewport, its dimensions
+ * and state.
+ */
+export declare class Viewport {
+    private readonly postEvent;
+    /**
+     * Requests fresh information about current viewport.
+     * FIXME: Be careful using this function in desktop version of Telegram as
+     *  long as method web_app_request_viewport does not work on `macos` platform.
+     * @see Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/5
+     * @param options - method options.
+     */
+    static request(options?: RequestOptions): Promise<RequestViewportResult>;
+    /**
+     * Synchronizes specified instance of Viewport with the actual value in the native
+     * application.
+     * @param viewport - Viewport instance.
+     */
+    static sync(viewport: Viewport): void;
+    /**
+     * Returns initialized instance of Viewport which is synchronized with
+     * its actual state in Web Apps.
+     * @param options - method options.
+     */
+    static synced(options?: RequestOptions): Promise<Viewport>;
+    private readonly ee;
+    private readonly state;
+    constructor(height: number, width: number, stableHeight: number, isExpanded: boolean, postEvent?: PostEvent);
+    /**
+     * The current height of the visible area of the Web App.
+     *
+     * The application can display just the top part of the Web App, with its
+     * lower part remaining outside the screen area. From this position, the
+     * user can "pull" the Web App to its maximum height, while the bot can do
+     * the same by calling `expand` method. As the position of the Web App
+     * changes, the current height value of the visible area will be updated
+     * in real time.
+     *
+     * Please note that the refresh rate of this value is not sufficient
+     * to smoothly follow the lower border of the window. It should not be
+     * used to pin interface elements to the bottom of the visible area. It's
+     * more appropriate to use the value of the `stableHeight`
+     * field for this purpose.
+     *
+     * @see init
+     * @see expand
+     * @see stableHeight
+     */
+    get height(): number;
+    /**
+     * The height of the visible area of the Web App in its last stable state.
+     *
+     * The application can display just the top part of the Web App, with its
+     * lower part remaining outside the screen area. From this position,
+     * the user can "pull" the Web App to its maximum height, while the bot can
+     * do the same by calling `expand` method.
+     *
+     * Unlike the value of `height`, the value of `stableHeight`
+     * does not change as the position of the Web App changes with user
+     * gestures or during animations. The value of `stableHeight`
+     * will be updated after all gestures and animations are completed and
+     * the Web App reaches its final size.
+     *
+     * @see init
+     * @see expand
+     * @see height
+     */
+    get stableHeight(): number;
+    /**
+     * Returns true if the Web App is expanded to the maximum available height.
+     * Otherwise, if the Web App occupies part of the screen and can be expanded
+     * to the full height using `expand` method.
+     * @see expand
+     */
+    get isExpanded(): boolean;
+    /**
+     * Current viewport width.
+     */
+    get width(): number;
+    /**
+     * A method that expands the Web App to the maximum available height. To
+     * find out if the Web App is expanded to the maximum height, refer to the
+     * value of the `isExpanded`.
+     * @see isExpanded
+     */
+    expand(): void;
+    /**
+     * Returns true in case current viewport height is stable and is not going to
+     * change in the next moment.
+     */
+    get isStable(): boolean;
+    /**
+     * Adds new event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     */
+    off: typeof this.ee.off;
+}

package/dist/types/components/Viewport/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Viewport.js';
+export type { ViewportEvents, ViewportEventListener, ViewportEventName } from './types.js';

package/dist/types/components/Viewport/types.d.ts

@@ -0,0 +1,10 @@
+import type { StateEvents } from '../../state/index.js';
+export interface ViewportState {
+    height: number;
+    isExpanded: boolean;
+    stableHeight: number;
+    width: number;
+}
+export type ViewportEvents = StateEvents<ViewportState>;
+export type ViewportEventName = keyof ViewportEvents;
+export type ViewportEventListener<E extends ViewportEventName> = ViewportEvents[E];

package/dist/types/components/WebApp/WebApp.d.ts

@@ -0,0 +1,145 @@
+import { type Version } from '@tma.js/utils';
+import { type RGB } from '@tma.js/colors';
+import { type PhoneRequestedStatus, type WriteAccessRequestedStatus, type InvoiceStatus, type PostEvent } from '@tma.js/bridge';
+import { type SupportsFunc } from '../../supports.js';
+import type { ColorScheme, Platform } from '../../types.js';
+import type { WebAppEvents, WebAppHeaderColor } from './types.js';
+/**
+ * Provides common Web Apps functionality not covered by other system
+ * components.
+ */
+export declare class WebApp {
+    private readonly currentVersion;
+    private readonly currentPlatform;
+    private readonly createRequestId;
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(headerColor: WebAppHeaderColor, backgroundColor: RGB, currentVersion: Version, currentPlatform: Platform, createRequestId: () => string, postEvent?: PostEvent);
+    /**
+     * Returns current application background color.
+     */
+    get backgroundColor(): RGB;
+    /**
+     * Returns current application color scheme. This value is
+     * computed based on the current background color.
+     */
+    get colorScheme(): ColorScheme;
+    /**
+     * Closes the Web App.
+     */
+    close(): void;
+    /**
+     * Returns current application header color.
+     */
+    get headerColor(): WebAppHeaderColor;
+    /**
+     * Returns true if passed version is more than or equal to current
+     * Web App version.
+     * @param version - compared version.
+     */
+    isVersionAtLeast(version: Version): boolean;
+    /**
+     * Opens a link in an external browser. The Web App will not be closed.
+     *
+     * Note that this method can be called only in response to the user
+     * interaction with the Web App interface (e.g. click inside the Web App
+     * or on the main button).
+     * @param url - URL to be opened.
+     * @param tryInstantView
+     */
+    openLink(url: string, tryInstantView?: boolean): void;
+    /**
+     * Opens a Telegram link inside Telegram app. The Web App will be closed.
+     * It expects passing link in full format, with hostname "t.me".
+     * @param url - URL to be opened.
+     * @throws {Error} URL has not allowed hostname.
+     */
+    openTelegramLink(url: string): void;
+    /**
+     * Opens an invoice using its url. It expects passing link in full format,
+     * with hostname "t.me".
+     * @param url - invoice URL.
+     */
+    openInvoice(url: string): Promise<InvoiceStatus>;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends "changed" | "backgroundColorChanged" | "headerColorChanged">(event: E, listener: import("@tma.js/event-emitter").EventListener<WebAppEvents[E]>) => void;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends "changed" | "backgroundColorChanged" | "headerColorChanged">(event: E, listener: import("@tma.js/event-emitter").EventListener<WebAppEvents[E]>) => void;
+    /**
+     * Returns current Web App platform.
+     */
+    get platform(): Platform;
+    /**
+     * Informs the Telegram app that the Web App is ready to be displayed.
+     *
+     * It is recommended to call this method as early as possible, as soon as
+     * all essential interface elements loaded. Once this method called,
+     * the loading placeholder is hidden and the Web App shown.
+     *
+     * If the method not called, the placeholder will be hidden only when
+     * the page fully loaded.
+     */
+    ready(): void;
+    /**
+     * Reads text from clipboard and returns string or null. null is returned
+     * in cases:
+     * - Value in clipboard is not text
+     * - Access to clipboard is not allowed
+     */
+    readTextFromClipboard(): Promise<string | null>;
+    /**
+     * Requests current user phone access.
+     */
+    requestPhoneAccess(): Promise<PhoneRequestedStatus>;
+    /**
+     * Requests write message access to current user.
+     */
+    requestWriteAccess(): Promise<WriteAccessRequestedStatus>;
+    /**
+     * A method used to send data to the bot. When this method called, a
+     * service message sent to the bot containing the data of the
+     * length up to 4096 bytes, and the Web App closed. See the field
+     * `web_app_data` in the class Message.
+     *
+     * This method is only available for Web Apps launched via a Keyboard button.
+     * @param data - data to send to bot.
+     * @throws {Error} data has incorrect size.
+     */
+    sendData(data: string): void;
+    /**
+     * Updates current application header color.
+     * FIXME: Has no effect on desktop, works incorrectly on Android.
+     *  Issues:
+     *  https://github.com/Telegram-Mini-Apps/tma.js/issues/9
+     *  https://github.com/Telegram-Mini-Apps/tma.js/issues/8
+     * @param color - color key or RGB color.
+     */
+    setHeaderColor(color: WebAppHeaderColor): void;
+    /**
+     * Updates current application background color.
+     * FIXME: Has no effect on desktop, works incorrectly in Android.
+     *  Issues:
+     *  https://github.com/Telegram-Mini-Apps/tma.js/issues/9
+     *  https://github.com/Telegram-Mini-Apps/tma.js/issues/8
+     * @param color - RGB color.
+     */
+    setBackgroundColor(color: RGB): void;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'openInvoice' | 'readTextFromClipboard' | 'setHeaderColor' | 'setBackgroundColor' | 'requestWriteAccess' | 'requestPhoneAccess'>;
+    /**
+     * Checks if specified method parameter is supported by current component.
+     */
+    supportsParam: SupportsFunc<'setHeaderColor.color' | 'openLink.tryInstantView'>;
+    /**
+     * Current Web App version. This property is used by other components to check if
+     * some functionality is available on current device.
+     */
+    get version(): Version;
+}

package/dist/types/components/WebApp/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './WebApp.js';

package/dist/types/components/WebApp/types.d.ts

@@ -0,0 +1,11 @@
+import type { RGB } from '@tma.js/colors';
+import type { HeaderColorKey } from '@tma.js/bridge';
+import type { StateEvents } from '../../state/index.js';
+export type WebAppHeaderColor = HeaderColorKey | RGB;
+export interface WebAppState {
+    backgroundColor: RGB;
+    headerColor: WebAppHeaderColor;
+}
+export type WebAppEvents = StateEvents<WebAppState>;
+export type WebAppEventName = keyof WebAppEvents;
+export type WebAppEventListener<E extends WebAppEventName> = WebAppEvents[E];

package/dist/types/components/index.d.ts

@@ -0,0 +1,11 @@
+export * from './BackButton/index.js';
+export * from './ClosingBehaviour/index.js';
+export * from './CloudStorage/index.js';
+export * from './HapticFeedback/index.js';
+export * from './InitData/index.js';
+export * from './MainButton/index.js';
+export * from './Popup/index.js';
+export * from './QRScanner/index.js';
+export * from './ThemeParams/index.js';
+export * from './Viewport/index.js';
+export * from './WebApp/index.js';

package/dist/types/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns true in case, current environment is Telegram Web Apps.
+ *
+ * `isTWA` utilizes such function as `retrieveLaunchParams`, which attempts to retrieve
+ * launch parameters from the current environment.
+ * @see retrieveLaunchParams
+ */
+export declare function isTWA(): boolean;

package/dist/types/errors/MethodNotSupportedError.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Error thrown in case, unsupported method was called.
+ */
+export declare class MethodNotSupportedError extends Error {
+    constructor(method: string, version: string);
+}

package/dist/types/errors/ParameterNotSupportedError.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Error thrown in case, unsupported parameter was used.
+ */
+export declare class ParameterUnsupportedError extends Error {
+    constructor(method: string, param: string, version: string);
+}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MethodNotSupportedError.js';
+export * from './ParameterNotSupportedError.js';

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from './components/index.js';
+export { init, type InitResult, type InitOptions } from './init/index.js';
+export { MethodNotSupportedError } from './errors/index.js';
+export * from './env.js';
+export * from './launch-params.js';
+export * from './theme-params.js';
+export * from './types.js';
+export * from './url.js';

package/dist/types/init/creators/createBackButton.d.ts

@@ -0,0 +1,9 @@
+import type { PostEvent } from '@tma.js/bridge';
+import { BackButton } from '../../components/index.js';
+/**
+ * Creates BackButton instance using last locally saved data also saving each state in
+ * the storage.
+ * @param version - platform version.
+ * @param postEvent - Bridge postEvent function
+ */
+export declare function createBackButton(version: string, postEvent: PostEvent): BackButton;

package/dist/types/init/creators/createClosingBehavior.d.ts

@@ -0,0 +1,8 @@
+import type { PostEvent } from '@tma.js/bridge';
+import { ClosingBehaviour } from '../../components/index.js';
+/**
+ * Creates ClosingBehaviour instance using last locally saved data also saving each state in
+ * the storage.
+ * @param postEvent - Bridge postEvent function
+ */
+export declare function createClosingBehavior(postEvent: PostEvent): ClosingBehaviour;

package/dist/types/init/creators/createMainButton.d.ts

@@ -0,0 +1,11 @@
+import type { RGB } from '@tma.js/colors';
+import type { PostEvent } from '@tma.js/bridge';
+import { MainButton } from '../../components/index.js';
+/**
+ * Creates MainButton instance using last locally saved data also saving each state in
+ * the storage.
+ * @param backgroundColor - background color.
+ * @param textColor - text color.
+ * @param postEvent - Bridge postEvent function
+ */
+export declare function createMainButton(backgroundColor: RGB, textColor: RGB, postEvent: PostEvent): MainButton;

package/dist/types/init/creators/createPostEvent.d.ts

@@ -0,0 +1,7 @@
+import { type PostEvent } from '@tma.js/bridge';
+/**
+ * Creates postEvent function.
+ * @param checkCompat - should compatibility check be enabled.
+ * @param version - platform version.
+ */
+export declare function createPostEvent(checkCompat: boolean, version: string): PostEvent;

package/dist/types/init/creators/createRequestIdGenerator.d.ts

@@ -0,0 +1,5 @@
+import type { CreateRequestIdFunc } from '../../types.js';
+/**
+ * Creates function which generated request identifiers.
+ */
+export declare function createRequestIdGenerator(): CreateRequestIdFunc;

package/dist/types/init/creators/createSyncedThemeParams.d.ts

@@ -0,0 +1,7 @@
+import { ThemeParams } from '../../components/index.js';
+import type { ThemeParamsType } from '../../theme-params.js';
+/**
+ * Creates synced instance of ThemeParams.
+ * @param params - theme parameters.
+ */
+export declare function createSyncedThemeParams(params: ThemeParamsType): ThemeParams;

package/dist/types/init/creators/createViewport.d.ts

@@ -0,0 +1,10 @@
+import type { PostEvent } from '@tma.js/bridge';
+import { Viewport } from '../../components/index.js';
+import type { Platform } from '../../types.js';
+/**
+ * Creates Viewport instance using last locally saved data also saving each state in
+ * the storage.
+ * @param platform - Telegram Web Apps platform name.
+ * @param postEvent - Bridge postEvent function
+ */
+export declare function createViewport(platform: Platform, postEvent: PostEvent): Promise<Viewport>;

package/dist/types/init/creators/createWebApp.d.ts

@@ -0,0 +1,14 @@
+import type { RGB } from '@tma.js/colors';
+import type { PostEvent } from '@tma.js/bridge';
+import { WebApp } from '../../components/index.js';
+import type { CreateRequestIdFunc, Platform } from '../../types.js';
+/**
+ * Creates WebApp instance using last locally saved data also saving each state in
+ * the storage.
+ * @param backgroundColor - web app background color.
+ * @param version - platform version.
+ * @param platform - Telegram Web Apps platform name.
+ * @param createRequestId - function which generates request identifiers.
+ * @param postEvent - Bridge postEvent function
+ */
+export declare function createWebApp(backgroundColor: RGB, version: string, platform: Platform, createRequestId: CreateRequestIdFunc, postEvent: PostEvent): WebApp;

package/dist/types/init/creators/index.d.ts

@@ -0,0 +1,8 @@
+export * from './createBackButton.js';
+export * from './createClosingBehavior.js';
+export * from './createMainButton.js';
+export * from './createPostEvent.js';
+export * from './createRequestIdGenerator.js';
+export * from './createSyncedThemeParams.js';
+export * from './createViewport.js';
+export * from './createWebApp.js';

package/dist/types/init/css.d.ts

@@ -0,0 +1,57 @@
+import type { ThemeParams, WebApp, Viewport } from '../components/index.js';
+import type { InitCSSVarsOption, InitCSSVarsSpecificOption } from './types.js';
+/**
+ * Creates CSS variables connected with theme parameters.
+ *
+ * Created variables:
+ * - `--tg-theme-bg-color`
+ * - `--tg-theme-button-color`
+ * - `--tg-theme-button-text-color`
+ * - `--tg-theme-hint-color`
+ * - `--tg-theme-link-color`
+ * - `--tg-theme-secondary-bg-color`
+ * - `--tg-theme-text-color`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed ThemeParams instance.
+ *
+ * @param themeParams - ThemeParams instance.
+ */
+export declare function bindThemeCSSVariables(themeParams: ThemeParams): void;
+/**
+ * Creates CSS variables connected with WebApp background and header colors based on
+ * passed WebApp and ThemeParams instances.
+ *
+ * Created variables:
+ * - `--tg-bg-color`
+ * - `--tg-header-color`
+ *
+ * Variables are being automatically updated in case, corresponding properties are updating.
+ *
+ * @param webApp - WebApp instance.
+ * @param themeParams - ThemeParams instance.
+ */
+export declare function bindWebAppVariables(webApp: WebApp, themeParams: ThemeParams): void;
+/**
+ * Accepts Viewport instance and sets CSS variables connected with viewport
+ * sizes.
+ *
+ * Be careful using this function as long as it can impact application
+ * performance. Viewport size is changing rather often, this makes CSS
+ * variables update, which leads to possible layout redraw.
+ *
+ * Variables:
+ * - `--tg-viewport-height`
+ * - `--tg-viewport-stable-height`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed Viewport instance.
+ *
+ * @param viewport - Viewport instance.
+ */
+export declare function bindViewportCSSVariables(viewport: Viewport): void;
+/**
+ * Converts init cssVars option to more narrow type.
+ * @param option - option value.
+ */
+export declare function parseCSSVarsOptions(option: InitCSSVarsOption): InitCSSVarsSpecificOption;

package/dist/types/init/index.d.ts

@@ -0,0 +1,2 @@
+export * from './init.js';
+export * from './types.js';

package/dist/types/init/init.d.ts

@@ -0,0 +1,6 @@
+import type { InitOptions, InitResult } from './types.js';
+/**
+ * Initializes all SDK components.
+ * @param options - initialization options.
+ */
+export declare function init(options?: InitOptions): Promise<InitResult>;

package/dist/types/init/types.d.ts

@@ -0,0 +1,107 @@
+import type { PostEvent } from '@tma.js/bridge';
+import type { BackButton, ClosingBehaviour, CloudStorage, HapticFeedback, InitData, MainButton, Popup, QRScanner, ThemeParams, Viewport, WebApp } from '../components/index.js';
+import type { LaunchParams } from '../launch-params.js';
+export type InitResult = {
+    backButton: BackButton;
+    closingBehavior: ClosingBehaviour;
+    cloudStorage: CloudStorage;
+    haptic: HapticFeedback;
+    initData?: InitData;
+    initDataRaw?: string;
+    mainButton: MainButton;
+    popup: Popup;
+    postEvent: PostEvent;
+    qrScanner: QRScanner;
+    themeParams: ThemeParams;
+    viewport: Viewport;
+    webApp: WebApp;
+};
+export type InitCSSVarsSpecificOption = {
+    /**
+     * Enables theme parameters CSS variables:
+     * - `--tg-theme-bg-color`
+     * - `--tg-theme-button-color`
+     * - `--tg-theme-button-text-color`
+     * - `--tg-theme-hint-color`
+     * - `--tg-theme-link-color`
+     * - `--tg-theme-secondary-bg-color`
+     * - `--tg-theme-text-color`
+     *
+     * @see bindThemeCSSVariables
+     */
+    themeParams?: true;
+    /**
+     * Enables viewport CSS variables:
+     * - `--tg-viewport-height`
+     * - `--tg-viewport-stable-height`
+     *
+     * @see bindViewportCSSVariables
+     */
+    viewport?: true;
+    /**
+     * Enables web app CSS variables:
+     * - `--tg-bg-color`
+     * - `--tg-header-color`
+     *
+     * @see bindWebAppVariables
+     */
+    webApp?: true;
+};
+export type InitCSSVarsOption = boolean | InitCSSVarsSpecificOption;
+export interface InitOptions {
+    /**
+     * @deprecated Use acceptCustomStyles
+     */
+    acceptScrollbarStyle?: boolean;
+    /**
+     * Should SDK accept styles sent from the Telegram web application.
+     * This option is only used in Web versions of Telegram.
+     *
+     * @default true
+     */
+    acceptCustomStyles?: boolean;
+    /**
+     * Should SDK throw an error in case, unsupported by current version of
+     * Web App method was called. It is highly recommended not to disable this
+     * feature as long as it helps developer to find issues related to usage
+     * of unsupported methods.
+     *
+     * @default true
+     */
+    checkCompat?: boolean;
+    /**
+     * Should SDK create global CSS variables related to current Telegram
+     * application colors.
+     *
+     * Possible values:
+     * - `false` - no CSS variables will be created.
+     * - `true` - all CSS variables will be created.
+     * - object - applies specific CSS variables.
+     *
+     * @default false
+     */
+    cssVars?: InitCSSVarsOption;
+    /**
+     * Enable debug mode.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Launch parameters presented as query parameters or already parsed
+     * object. In case, this value is not specified, init
+     * function will try to retrieve launch parameters from window.location.hash
+     * via retrieveLaunchParams function.
+     */
+    launchParams?: string | URLSearchParams | LaunchParams;
+    /**
+     * Sets new targetOrigin, used by bridge's `postEvent` function.
+     * @see setTargetOrigin
+     */
+    targetOrigin?: string;
+    /**
+     * Initialization process timeout.
+     * @default 1000
+     */
+    timeout?: number;
+}

package/dist/types/launch-params.d.ts

@@ -0,0 +1,20 @@
+import { type InitData } from '@tma.js/init-data';
+import { type ThemeParamsType } from './theme-params.js';
+import type { Platform } from './types.js';
+export interface LaunchParams {
+    version: string;
+    initData?: InitData;
+    initDataRaw?: string;
+    platform: Platform;
+    themeParams: ThemeParamsType;
+}
+/**
+ * Parses query parameters as launch parameters.
+ * @param query - query parameters presented as string or URLSearchParams
+ * instance.
+ */
+export declare function parseLaunchParams(query: string | URLSearchParams): LaunchParams;
+/**
+ * Extracts launch params from the current environment.
+ */
+export declare function retrieveLaunchParams(): LaunchParams;

package/dist/types/state/State.d.ts

@@ -0,0 +1,15 @@
+import type { EventEmitter } from '@tma.js/event-emitter';
+import type { StateEvents, StringKeys } from './types.js';
+/**
+ * Represents state which is observable via passed EventEmitter.
+ */
+export declare class State<S extends object> {
+    private readonly state;
+    private readonly ee?;
+    constructor(state: S, ee?: EventEmitter<StateEvents<S>> | undefined);
+    private emit;
+    private internalSet;
+    set<K extends StringKeys<S>>(key: K, value: S[K]): void;
+    set(state: Partial<S>): void;
+    get<K extends StringKeys<S>>(key: K): Readonly<S[K]>;
+}

package/dist/types/state/index.d.ts

@@ -0,0 +1,2 @@
+export * from './State.js';
+export * from './types.js';