@tma.js/sdk 0.11.3

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

@@ -0,0 +1,44 @@
+import { type PostEvent } from '@tma.js/bridge';
+import type { Version } from '@tma.js/utils';
+import { type SupportsFunc } from '../../supports.js';
+/**
+ * Class which controls the back button displayed in the header
+ * of the Web App in the Telegram interface. It is mostly used in case, when
+ * you want to provide a way to go bach in routing history or "rollback" some
+ * action.
+ */
+export declare class BackButton {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(isVisible: boolean, version: Version, postEvent?: PostEvent);
+    private set isVisible(value);
+    /**
+     * True if BackButton is currently visible.
+     */
+    get isVisible(): boolean;
+    /**
+     * Hides the BackButton.
+     */
+    hide(): void;
+    /**
+     * Adds event listener.
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    off: typeof this.ee.off;
+    /**
+     * Shows the BackButton.
+     */
+    show(): void;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'show' | 'hide'>;
+}

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

@@ -0,0 +1,2 @@
+export * from './BackButton.js';
+export type { BackButtonEventListener, BackButtonEventName, BackButtonEvents } from './types.js';

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

@@ -0,0 +1,9 @@
+import type { StateEvents } from '../../state/index.js';
+export interface BackButtonState {
+    isVisible: boolean;
+}
+export interface BackButtonEvents extends StateEvents<BackButtonState> {
+    click: () => void;
+}
+export type BackButtonEventName = keyof BackButtonEvents;
+export type BackButtonEventListener<E extends BackButtonEventName> = BackButtonEvents[E];

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

@@ -0,0 +1,35 @@
+import { type PostEvent } from '@tma.js/bridge';
+/**
+ * Component responsible for controlling current closing confirmation
+ * status.
+ */
+export declare class ClosingBehaviour {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(isConfirmationNeeded: boolean, postEvent?: PostEvent);
+    private set isConfirmationNeeded(value);
+    /**
+     * Returns true, if the confirmation dialog enabled while the user is trying
+     * to close the Web App.
+     */
+    get isConfirmationNeeded(): boolean;
+    /**
+     * Disables the confirmation dialog while the user is trying to close the
+     * Web App.
+     */
+    disableConfirmation(): void;
+    /**
+     * Enables the confirmation dialog while the user is trying to close the
+     * Web App.
+     */
+    enableConfirmation(): void;
+    /**
+     * Adds new event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     */
+    off: typeof this.ee.off;
+}

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

@@ -0,0 +1,2 @@
+export * from './ClosingBehaviour.js';
+export type { ClosingBehaviourEventName, ClosingBehaviourEventListener, ClosingBehaviourEvents, } from './types.js';

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

@@ -0,0 +1,7 @@
+import type { StateEvents } from '../../state/index.js';
+export interface ClosingBehaviourState {
+    isConfirmationNeeded: boolean;
+}
+export type ClosingBehaviourEvents = StateEvents<ClosingBehaviourState>;
+export type ClosingBehaviourEventName = keyof ClosingBehaviourEvents;
+export type ClosingBehaviourEventListener<E extends ClosingBehaviourEventName> = ClosingBehaviourEvents[E];

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

@@ -0,0 +1,47 @@
+import { postEvent as defaultPostEvent, type RequestOptions } from '@tma.js/bridge';
+import type { Version } from '@tma.js/utils';
+import { type SupportsFunc } from '../../supports.js';
+import type { CreateRequestIdFunc } from '../../types.js';
+type WiredRequestOptions = Omit<RequestOptions, 'postEvent'>;
+export declare class CloudStorage {
+    private readonly createRequestId;
+    private readonly postEvent;
+    constructor(version: Version, createRequestId: CreateRequestIdFunc, postEvent?: typeof defaultPostEvent);
+    /**
+     * Invokes custom method related to CloudStorage.
+     * @param method - method name.
+     * @param params - method parameters.
+     * @param options - execution options.
+     */
+    private invokeCustomMethod;
+    /**
+     * Deletes specified keys from the CloudStorage.
+     * @param keys - keys list.
+     * @param options - request execution options.
+     */
+    deleteKeys(keys: string[], options?: WiredRequestOptions): Promise<void>;
+    /**
+     * Returns list of all keys presented in CloudStorage.
+     * @param options - request execution options.
+     */
+    getKeys(options?: WiredRequestOptions): Promise<string[]>;
+    /**
+     * Returns map, where key is one of the specified in keys argument, and value is according
+     * storage value.
+     * @param keys - keys list.
+     * @param options - request execution options.
+     */
+    getValues<K extends string>(keys: K[], options?: WiredRequestOptions): Promise<Record<K, string>>;
+    /**
+     * Saves specified value by key.
+     * @param key - storage key.
+     * @param value - storage value.
+     * @param options - request execution options.
+     */
+    saveValue(key: string, value: string, options?: WiredRequestOptions): Promise<void>;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'deleteKeys' | 'getKeys' | 'getValues' | 'saveValue'>;
+}
+export {};

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

@@ -0,0 +1 @@
+export * from './CloudStorage.js';

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

@@ -0,0 +1,37 @@
+import type { Version } from '@tma.js/utils';
+import { type PostEvent, type ImpactHapticFeedbackStyle, type NotificationHapticFeedbackType } from '@tma.js/bridge';
+import { type SupportsFunc } from '../../supports.js';
+/**
+ * Class which controls haptic feedback. It allows calling different types of
+ * haptic notifications which usually occur after user interaction with
+ * application.
+ */
+export declare class HapticFeedback {
+    private readonly postEvent;
+    constructor(version: Version, postEvent?: PostEvent);
+    /**
+     * A method tells that an impact occurred. The Telegram app may play the
+     * appropriate haptics based on style value passed.
+     * @param style - impact style.
+     */
+    impactOccurred(style: ImpactHapticFeedbackStyle): void;
+    /**
+     * A method tells that a task or action has succeeded, failed, or produced
+     * a warning. The Telegram app may play the appropriate haptics based on
+     * type value passed.
+     * @param type - notification type.
+     */
+    notificationOccurred(type: NotificationHapticFeedbackType): void;
+    /**
+     * A method tells that the user has changed a selection. The Telegram app
+     * may play the appropriate haptics.
+     *
+     * Do not use this feedback when the user makes or confirms a selection;
+     * use it only when the selection changes.
+     */
+    selectionChanged(): void;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'impactOccurred' | 'notificationOccurred' | 'selectionChanged'>;
+}

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

@@ -0,0 +1 @@
+export * from './HapticFeedback.js';

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

@@ -0,0 +1,52 @@
+import type { Chat, InitData as InitDataType, User } from '@tma.js/init-data';
+/**
+ * Class which is responsible for displaying Web Apps init data.
+ */
+export declare class InitData {
+    private readonly state;
+    constructor(authDate: Date, hash: string, options?: Omit<InitDataType, 'authDate' | 'hash'>);
+    /**
+     * Init data generation date.
+     */
+    get authDate(): Date;
+    /**
+     * Date after which a message can be sent via the answerWebAppQuery
+     * method.
+     * @see https://core.telegram.org/bots/api#answerwebappquery
+     */
+    get canSendAfter(): Date | null;
+    /**
+     * An object containing data about the chat where the bot was
+     * launched via the attachment menu. Returned for supergroups, channels and
+     * group chats – only for Web Apps launched via the attachment menu.
+     */
+    get chat(): Chat | null;
+    /**
+     * A hash of all passed parameters, which the bot server can use to
+     * check their validity.
+     * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app
+     */
+    get hash(): string;
+    /**
+     * A unique identifier for the Web App session, required for sending
+     * messages via the `answerWebAppQuery` method.
+     * @see https://core.telegram.org/bots/api#answerwebappquery
+     */
+    get queryId(): string | null;
+    /**
+     * An object containing data about the chat partner of the current
+     * user in the chat where the bot was launched via the attachment menu.
+     * Returned only for private chats and only for Web Apps launched
+     * via the attachment menu.
+     */
+    get receiver(): User | null;
+    /**
+     * The value of the `startattach` parameter, passed via link. Only
+     * returned for Web Apps when launched from the attachment menu via link.
+     */
+    get startParam(): string | null;
+    /**
+     * An object containing data about the current user.
+     */
+    get user(): User | null;
+}

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

@@ -0,0 +1 @@
+export * from './InitData.js';

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

@@ -0,0 +1,114 @@
+import { type PostEvent } from '@tma.js/bridge';
+import type { RGB } from '@tma.js/colors';
+/**
+ * Controls the main button, which is displayed at the bottom
+ * of the Web App in the Telegram interface.
+ */
+export declare class MainButton {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(backgroundColor: RGB, isEnabled: boolean, isVisible: boolean, isProgressVisible: boolean, text: string, textColor: RGB, postEvent?: PostEvent);
+    private set isEnabled(value);
+    /**
+     * Returns true in case, MainButton is currently enabled.
+     */
+    get isEnabled(): boolean;
+    private set isProgressVisible(value);
+    /**
+     * Returns true in case, MainButton loading progress is currently visible.
+     */
+    get isProgressVisible(): boolean;
+    private set isVisible(value);
+    /**
+     * Returns true in case, MainButton is currently visible.
+     */
+    get isVisible(): boolean;
+    /**
+     * Sends current local button state to Telegram application.
+     */
+    private commit;
+    /**
+     * Returns current main button background color.
+     */
+    get backgroundColor(): RGB;
+    /**
+     * Returns current main button text.
+     */
+    get text(): string;
+    /**
+     * Returns current main button text color.
+     */
+    get textColor(): RGB;
+    /**
+     * Disables button. Returns current button instance for chaining.
+     */
+    disable(): this;
+    /**
+     * Enables button. Returns current button instance for chaining.
+     */
+    enable(): this;
+    /**
+     * Hides button. Returns current button instance for chaining.
+     */
+    hide(): this;
+    /**
+     * Hides button progress. Returns current button instance for chaining.
+     */
+    hideProgress(): this;
+    /**
+     * Adds new event listener.
+     * FIXME: Event 'main_button_pressed' is still being received on Android
+     *  even if the main button is disabled.
+     *  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/3
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    off: typeof this.ee.off;
+    /**
+     * Shows the button. Note that opening the Web App from the attachment
+     * menu hides the main button until the user interacts with the Web App
+     * interface.
+     *
+     * Returns current button instance for chaining.
+     */
+    show(): this;
+    /**
+     * A method to show a loading indicator on the button.
+     * It is recommended to display loading progress if the action tied to the
+     * button may take a long time.
+     *
+     * Returns current button instance for chaining.
+     */
+    showProgress(): this;
+    /**
+     * Sets new main button text. Returns current button instance for chaining.
+     * Minimal length for text is 1 symbol, and maximum is 64 symbols.
+     *
+     * Returns current button instance for chaining.
+     * @param value - new text.
+     */
+    setText(value: string): this;
+    /**
+     * Sets new main button text color. Returns current button instance for
+     * chaining.
+     *
+     * Returns current button instance for chaining.
+     * @param value - new text color.
+     */
+    setTextColor(value: RGB): this;
+    /**
+     * Updates current button color. Returns current button instance for
+     * chaining.
+     *
+     * Returns current button instance for chaining.
+     * @param value - color to set.
+     */
+    setBackgroundColor(value: RGB): this;
+}

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

@@ -0,0 +1,2 @@
+export * from './MainButton.js';
+export type { MainButtonEvents, MainButtonEventListener, MainButtonEventName } from './types.js';

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

@@ -0,0 +1,15 @@
+import type { RGB } from '@tma.js/colors';
+import type { StateEvents } from '../../state/index.js';
+export interface MainButtonState {
+    backgroundColor: RGB;
+    isEnabled: boolean;
+    isVisible: boolean;
+    isProgressVisible: boolean;
+    text: string;
+    textColor: RGB;
+}
+export interface MainButtonEvents extends StateEvents<MainButtonState> {
+    click: () => void;
+}
+export type MainButtonEventName = keyof MainButtonEvents;
+export type MainButtonEventListener<E extends MainButtonEventName> = MainButtonEvents[E];

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

@@ -0,0 +1,44 @@
+import { type PostEvent } from '@tma.js/bridge';
+import type { Version } from '@tma.js/utils';
+import { type SupportsFunc } from '../../supports.js';
+import type { PopupParams } from './types.js';
+/**
+ * Controls currently displayed application popup. It allows developers to
+ * open new custom popups and detect popup-connected events.
+ */
+export declare class Popup {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(version: Version, postEvent?: PostEvent);
+    /**
+     * Shows whether popup is currently opened.
+     */
+    get isOpened(): boolean;
+    /**
+     * Adds new event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     */
+    off: typeof this.ee.off;
+    /**
+     * A method that shows a native popup described by the `params` argument.
+     * Promise will be resolved when popup is closed. Resolved value will have
+     * an identifier of pressed button.
+     *
+     * In case, user clicked outside the popup or clicked top right popup close
+     * button, null will be returned.
+     *
+     * FIXME: In desktop, this function may work incorrectly.
+     *  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/7
+     * @param params - popup parameters.
+     * @throws {Error} Popup is already opened.
+     */
+    open(params: PopupParams): Promise<string | null>;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'open'>;
+}

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

@@ -0,0 +1,2 @@
+export * from './Popup.js';
+export type { PopupParams, PopupEvents, PopupEventListener, PopupEventName, PopupButton, } from './types.js';

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

@@ -0,0 +1,60 @@
+import type { StateEvents } from '../../state/index.js';
+export interface PopupState {
+    isOpened: boolean;
+}
+export type PopupEvents = StateEvents<PopupState>;
+export type PopupEventName = keyof PopupEvents;
+export type PopupEventListener<E extends PopupEventName> = PopupEvents[E];
+/**
+ * This object describes the native popup.
+ * @see https://core.telegram.org/bots/webapps#popupparams
+ */
+export interface PopupParams {
+    /**
+     * The text to be displayed in the popup title, 0-64 characters.
+     * @default ""
+     */
+    title?: string;
+    /**
+     * The message to be displayed in the body of the popup, 1-256 characters.
+     */
+    message: string;
+    /**
+     * List of buttons to be displayed in the popup, 1-3 buttons.
+     * @default [{type: 'close'}]
+     */
+    buttons?: PopupButton[];
+}
+/**
+ * This object describes the native popup button.
+ * @see https://core.telegram.org/bots/webapps#popupbutton
+ */
+export type PopupButton = {
+    /**
+     * Identifier of the button, 0-64 characters.
+     * @default ""
+     */
+    id?: string;
+} & ({
+    /**
+     * Type of the button:
+     * - `default`, a button with the default style;
+     * - `destructive`, a button with a style that indicates a destructive
+     * action (e.g. "Remove", "Delete", etc.).
+     *
+     * @default "default"
+     */
+    type?: 'default' | 'destructive';
+    /**
+     * The text to be displayed on the button, 0-64 characters.
+     */
+    text: string;
+} | {
+    /**
+     * Type of the button:
+     * - `ok`, a button with the localized text "OK";
+     * - `close`, a button with the localized text "Close";
+     * - `cancel`, a button with the localized text "Cancel".
+     */
+    type: 'ok' | 'close' | 'cancel';
+});

package/dist/types/components/Popup/utils.d.ts

@@ -0,0 +1,7 @@
+import type { PopupParams as BridgePopupParams } from '@tma.js/bridge';
+import type { PopupParams } from './types.js';
+/**
+ * Prepares popup parameters before sending them to native app.
+ * @param params - popup parameters.
+ */
+export declare function preparePopupParams(params: PopupParams): BridgePopupParams;

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

@@ -0,0 +1,40 @@
+import { type PostEvent } from '@tma.js/bridge';
+import type { Version } from '@tma.js/utils';
+import { type SupportsFunc } from '../../supports.js';
+/**
+ * Provides QR scanner functionality.
+ */
+export declare class QRScanner {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(version: Version, postEvent?: PostEvent);
+    /**
+     * Closes scanner.
+     */
+    close(): void;
+    private set isOpened(value);
+    /**
+     * Returns true in case, QR scanner is currently opened.
+     */
+    get isOpened(): boolean;
+    /**
+     * Opens scanner with specified title shown to user. Method returns promise
+     * with scanned QR content in case, it was scanned. It will contain null in
+     * case, scanner was closed.
+     * @param text - title to display.
+     */
+    open(text?: string): Promise<string | null>;
+    /**
+     * Adds new event listener.
+     */
+    on: typeof this.ee.on;
+    /**
+     * Removes event listener.
+     */
+    off: typeof this.ee.off;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'open' | 'close'>;
+}

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

@@ -0,0 +1,2 @@
+export * from './QRScanner.js';
+export type { QRScannerEvents, QRScannerEventName, QRScannerEventListener } from './types.js';

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

@@ -0,0 +1,7 @@
+import type { StateEvents } from '../../state/index.js';
+export interface QRScannerState {
+    isOpened: boolean;
+}
+export type QRScannerEvents = StateEvents<QRScannerState>;
+export type QRScannerEventName = keyof QRScannerEvents;
+export type QRScannerEventListener<E extends QRScannerEventName> = QRScannerEvents[E];

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

@@ -0,0 +1,73 @@
+import { type RequestOptions } from '@tma.js/bridge';
+import type { RGB } from '@tma.js/colors';
+import { type ThemeParamsType } from '../../theme-params.js';
+import type { ThemeParamsEvents } from './types.js';
+/**
+ * Contains information about currently used theme by application.
+ * @see https://core.telegram.org/bots/webapps#themeparams
+ */
+export declare class ThemeParams {
+    /**
+     * Requests fresh information about current theme.
+     * FIXME: Be careful using this function in desktop version of Telegram as
+     *  long as method web_app_request_theme does not work on `macos` platform.
+     * @param options - method options.
+     */
+    static request(options?: RequestOptions): Promise<ThemeParamsType>;
+    /**
+     * Synchronizes specified instance of ThemeParams with the actual value in the native
+     * application.
+     * @param themeParams - ThemeParams instance.
+     */
+    static sync(themeParams: ThemeParams): void;
+    /**
+     * Returns instance of ThemeParams which is synchronized with external
+     * environment.
+     * @param options - method options.
+     */
+    static synced(options?: RequestOptions): Promise<ThemeParams>;
+    private readonly ee;
+    private readonly state;
+    constructor(params: ThemeParamsType);
+    /**
+     * Returns background color.
+     */
+    get backgroundColor(): RGB | null;
+    /**
+     * Returns button color.
+     */
+    get buttonColor(): RGB | null;
+    /**
+     * Returns button text color.
+     */
+    get buttonTextColor(): RGB | null;
+    /**
+     * Returns hint color.
+     */
+    get hintColor(): RGB | null;
+    /**
+     * Returns true in case, current color scheme is recognized as dark. This
+     * value is calculated according to theme background color.
+     */
+    get isDark(): boolean;
+    /**
+     * Returns current link color.
+     */
+    get linkColor(): RGB | null;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends "changed" | "backgroundColorChanged" | "textColorChanged" | "buttonColorChanged" | "buttonTextColorChanged" | "hintColorChanged" | "linkColorChanged" | "secondaryBackgroundColorChanged">(event: E, listener: import("@tma.js/event-emitter").EventListener<ThemeParamsEvents[E]>) => void;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends "changed" | "backgroundColorChanged" | "textColorChanged" | "buttonColorChanged" | "buttonTextColorChanged" | "hintColorChanged" | "linkColorChanged" | "secondaryBackgroundColorChanged">(event: E, listener: import("@tma.js/event-emitter").EventListener<ThemeParamsEvents[E]>) => void;
+    /**
+     * Returns secondary background color.
+     */
+    get secondaryBackgroundColor(): RGB | null;
+    /**
+     * Returns text color.
+     */
+    get textColor(): RGB | null;
+}

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

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

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

@@ -0,0 +1,9 @@
+import type { HasUndefined, If } from '@tma.js/util-types';
+import type { ThemeParamsType } from '../../theme-params.js';
+import type { StateEvents } from '../../state/index.js';
+export type ThemeParamsState = {
+    [K in keyof ThemeParamsType]-?: If<HasUndefined<ThemeParamsType[K]>, Exclude<ThemeParamsType[K], undefined> | null, ThemeParamsType[K]>;
+};
+export type ThemeParamsEvents = StateEvents<ThemeParamsState>;
+export type ThemeParamsEventName = keyof ThemeParamsEvents;
+export type ThemeParamsEventListener<E extends ThemeParamsEventName> = ThemeParamsEvents[E];