@tma.js/sdk 1.5.2 → 2.0.0

package/dist/dts/bridge/events/event-emitter/createMiniAppsEventEmitter.d.ts

@@ -0,0 +1,15 @@
+import { MiniAppsEventEmitter } from '../types.js';
+
+/**
+ * Creates new event emitter, which handles events from the Telegram application.
+ */
+export declare function createMiniAppsEventEmitter(): [
+    /**
+     * Created event emitter.
+     */
+    emitter: MiniAppsEventEmitter,
+    /**
+     * Function to dispose created emitter.
+     */
+    dispose: () => void
+];

package/dist/dts/bridge/events/event-emitter/singleton.d.ts

@@ -0,0 +1,8 @@
+import { MiniAppsEventEmitter } from '../types.js';
+
+declare const resetMiniAppsEventEmitter: () => void;
+/**
+ * Returns Mini Apps event emitter singleton.
+ */
+export declare function miniAppsEventEmitter(): MiniAppsEventEmitter;
+export { resetMiniAppsEventEmitter };

package/dist/dts/bridge/events/event-handlers/cleanupEventHandlers.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Removes global event handlers, used by the package.
+ */
+export declare function cleanupEventHandlers(): void;

package/dist/dts/bridge/events/event-handlers/defineEventHandlers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Defines special handlers by known paths, which are recognized by
+ * Telegram as ports to receive events. This function also sets special
+ * function in global window object to prevent duplicate declaration.
+ */
+export declare function defineEventHandlers(): void;

package/dist/dts/bridge/events/event-handlers/emitMiniAppsEvent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Emits event sent from Telegram native application like it was sent in
+ * default web environment between 2 iframes. It dispatches new MessageEvent
+ * and expects it to be handled via `window.addEventListener('message', ...)`
+ * as developer would do it to handle messages sent from the parent iframe.
+ * @param eventType - event name.
+ * @param eventData - event payload.
+ */
+export declare function emitMiniAppsEvent(eventType: string, eventData: unknown): void;

package/dist/dts/bridge/events/{off.d.ts → listening/off.d.ts}

@@ -1,7 +1,8 @@
-import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+import { MiniAppsEventListener, MiniAppsEventName } from '../types.js';
+
 /**
  * Removes listener from specified event.
  * @param event - event to listen.
- * @param listener - event listener.
+ * @param listener - event listener to remove.
  */
 export declare function off<E extends MiniAppsEventName>(event: E, listener: MiniAppsEventListener<E>): void;

package/dist/dts/bridge/events/listening/on.d.ts

@@ -0,0 +1,12 @@
+import { RemoveEventListenerFn } from '../../../events/types.js';
+import { MiniAppsEventListener, MiniAppsEventName } from '../types.js';
+
+/**
+ * Adds new listener to the specified event. Returns handler
+ * which allows to stop listening to event.
+ * @param event - event name.
+ * @param listener - event listener.
+ * @param once - should listener be called only once.
+ * @returns Function to remove bound event listener.
+ */
+export declare function on<E extends MiniAppsEventName>(event: E, listener: MiniAppsEventListener<E>, once?: boolean): RemoveEventListenerFn;

package/dist/dts/bridge/events/listening/subscribe.d.ts

@@ -0,0 +1,9 @@
+import { RemoveEventListenerFn } from '../../../events/types.js';
+import { MiniAppsSubscribeListener } from '../types.js';
+
+/**
+ * Subscribes to all events sent from the native Telegram application.
+ * @param listener - event listener to bind.
+ * @returns Function to remove bound event listener.
+ */
+export declare function subscribe(listener: MiniAppsSubscribeListener): RemoveEventListenerFn;

package/dist/dts/bridge/events/listening/unsubscribe.d.ts

@@ -0,0 +1,7 @@
+import { MiniAppsSubscribeListener } from '../types.js';
+
+/**
+ * Removes global event listener.
+ * @param listener - event listener.
+ */
+export declare function unsubscribe(listener: MiniAppsSubscribeListener): void;

package/dist/dts/bridge/events/types.d.ts

@@ -1,4 +1,296 @@
+import { RGB } from '../../colors/types.js';
+import { EventEmitter } from '../../events/event-emitter/EventEmitter.js';
+import { EventListener, SubscribeListener } from '../../events/event-emitter/types.js';
+import { RequestId } from '../../request-id/types.js';
+
+export type InvoiceStatus = 'paid' | 'failed' | 'pending' | 'cancelled' | string;
+export type PhoneRequestedStatus = 'sent' | 'cancelled' | string;
+export type WriteAccessRequestedStatus = 'allowed' | string;
+export type BiometryType = 'finger' | 'face' | string;
+export type BiometryTokenUpdateStatus = 'updated' | 'removed' | string;
+export type BiometryAuthRequestStatus = 'failed' | 'authorized' | string;
 /**
- * Removes event listener.
+ * Map where key is known event name, and value is its listener.
+ * @see https://docs.telegram-mini-apps.com/platform/events
  */
-export type RemoveListenerFn = () => void;
+export interface MiniAppsEvents {
+    /**
+     * User clicked the BackButton.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/platform/events#back-button-pressed
+     */
+    back_button_pressed: never;
+    /**
+     * Biometry authentication request completed.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/events#biometry-auth-requested
+     */
+    biometry_auth_requested: {
+        /**
+         * Authentication status.
+         */
+        status: BiometryAuthRequestStatus;
+        /**
+         * Token from the local secure storage saved previously.
+         */
+        token?: string;
+    };
+    /**
+     * Biometry settings were received.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/events#biometry-info-received
+     */
+    biometry_info_received: {
+        /**
+         * Shows whether biometry is available.
+         */
+        available: false;
+    } | {
+        /**
+         * Shows whether biometry is available.
+         */
+        available: true;
+        /**
+         * Shows whether permission to use biometrics has been requested.
+         */
+        access_requested: boolean;
+        /**
+         * Shows whether permission to use biometrics has been granted.
+         */
+        access_granted: boolean;
+        /**
+         * A unique device identifier that can be used to match the token to the device.
+         */
+        device_id: string;
+        /**
+         * Show whether local storage contains previously saved token.
+         */
+        token_saved: boolean;
+        /**
+         * The type of biometrics currently available on the device.
+         */
+        type: BiometryType;
+    };
+    /**
+     * Biometry token was updated.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/events#biometry-token-updated
+     */
+    biometry_token_updated: {
+        /**
+         * Update status.
+         */
+        status: BiometryTokenUpdateStatus;
+    };
+    /**
+     * Telegram application attempted to extract text from clipboard.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/events#clipboard-text-received
+     */
+    clipboard_text_received: {
+        /**
+         * Passed during the `web_app_read_text_from_clipboard` method invocation `req_id` value.
+         */
+        req_id: RequestId;
+        /**
+         * Data extracted from the clipboard. The returned value will have the type `string` only in
+         * the case, application has access to the clipboard.
+         */
+        data?: string | null;
+    };
+    /**
+     * Custom method invocation completed.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/events#custom-method-invoked
+     */
+    custom_method_invoked: {
+        /**
+         * Unique identifier of this invocation.
+         */
+        req_id: RequestId;
+        /**
+         * Method invocation successful result.
+         */
+        result?: unknown;
+        /**
+         * Method invocation error code.
+         */
+        error?: string;
+    };
+    /**
+     * An invoice was closed.
+     * @see https://docs.telegram-mini-apps.com/platform/events#invoice-closed
+     */
+    invoice_closed: {
+        /**
+         * Passed during the `web_app_open_invoice` method invocation `slug` value.
+         */
+        slug: string;
+        /**
+         * Invoice status.
+         */
+        status: InvoiceStatus;
+    };
+    /**
+     * User clicked the Main Button.
+     * @see https://docs.telegram-mini-apps.com/platform/events#main-button-pressed
+     */
+    main_button_pressed: never;
+    /**
+     * Application received phone access request status.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/events#phone-requested
+     */
+    phone_requested: {
+        /**
+         * Request status.
+         */
+        status: PhoneRequestedStatus;
+    };
+    /**
+     * Popup was closed.
+     * @see https://docs.telegram-mini-apps.com/platform/events#popup-closed
+     */
+    popup_closed: {
+        /**
+         * Identifier of the clicked button. In case, the popup was closed without clicking any button,
+         * this property will be omitted.
+         */
+        button_id?: string;
+    };
+    /**
+     * The QR scanner scanned some QR and extracted its content.
+     * @param payload - event payload.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/events#qr-text-received
+     */
+    qr_text_received: {
+        /**
+         * Data extracted from the QR.
+         */
+        data?: string;
+    };
+    /**
+     * Parent iframe requested current iframe reload.
+     * @see https://docs.telegram-mini-apps.com/platform/events#reload-iframe
+     */
+    reload_iframe: never;
+    /**
+     * QR scanner was closed.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/events#scan-qr-popup-closed
+     */
+    scan_qr_popup_closed: never;
+    /**
+     * The event which is usually sent by the Telegram web application. Its payload represents
+     * `<style/>` tag html content, a developer could use. The stylesheet described in the payload
+     * will help the developer to stylize the app scrollbar (but he is still able to do it himself).
+     * @see https://docs.telegram-mini-apps.com/platform/events#set-custom-style
+     */
+    set_custom_style: string;
+    /**
+     * Occurs when the Settings Button was pressed.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/platform/events#settings-button-pressed
+     */
+    settings_button_pressed: never;
+    /**
+     * Occurs whenever theme settings are changed in the user's Telegram app
+     * (including switching to night mode).
+     * @see https://docs.telegram-mini-apps.com/platform/events#theme-changed
+     */
+    theme_changed: {
+        /**
+         * Map where the key is a theme stylesheet key and value is  the corresponding color in
+         * `#RRGGBB` format.
+         */
+        theme_params: {
+            /**
+             * @since v6.10
+             */
+            accent_text_color?: RGB;
+            bg_color?: RGB;
+            button_color?: RGB;
+            button_text_color?: RGB;
+            /**
+             * @since v6.10
+             */
+            destructive_text_color?: RGB;
+            /**
+             * @since v6.10
+             */
+            header_bg_color?: RGB;
+            hint_color?: RGB;
+            link_color?: RGB;
+            secondary_bg_color?: RGB;
+            /**
+             * @since v6.10
+             */
+            section_bg_color?: RGB;
+            /**
+             * @since v6.10
+             */
+            section_header_text_color?: RGB;
+            /**
+             * @since v6.10
+             */
+            subtitle_text_color?: RGB;
+            text_color?: RGB;
+            [key: string]: RGB | undefined;
+        };
+    };
+    /**
+     * Occurs whenever the viewport has been changed. For example, when the user started
+     * dragging the application or called the expansion method.
+     * @see https://docs.telegram-mini-apps.com/platform/events#viewport-changed
+     */
+    viewport_changed: {
+        /**
+         * The viewport height.
+         */
+        height: number;
+        /**
+         * The viewport width.
+         */
+        width: number;
+        /**
+         * Is the viewport currently expanded.
+         */
+        is_expanded: boolean;
+        /**
+         * Is the viewport current state stable and not going to change in the next moment.
+         */
+        is_state_stable: boolean;
+    };
+    /**
+     * Application received write access request status.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/events#write-access-requested
+     */
+    write_access_requested: {
+        /**
+         * Request status.
+         */
+        status: WriteAccessRequestedStatus;
+    };
+}
+/**
+ * Mini Apps event name.
+ */
+export type MiniAppsEventName = keyof MiniAppsEvents;
+/**
+ * Payload of the specified Mini Apps event.
+ */
+export type MiniAppsEventPayload<E extends MiniAppsEventName> = MiniAppsEvents[E];
+/**
+ * Returns event listener for the specified Mini Apps event.
+ */
+export type MiniAppsEventListener<E extends MiniAppsEventName> = EventListener<MiniAppsEvents[E]>;
+/**
+ * Mini Apps event listener used in `subscribe` and `unsubscribe` functions.
+ */
+export type MiniAppsSubscribeListener = SubscribeListener<MiniAppsEvents>;
+/**
+ * Mini Apps event emitter.
+ */
+export type MiniAppsEventEmitter = EventEmitter<MiniAppsEvents>;

package/dist/dts/bridge/methods/createPostEvent.d.ts

@@ -1,10 +1,13 @@
-import { type PostEvent } from './postEvent.js';
-import type { Version } from '../../version/types.js';
+import { Version } from '../../version/types.js';
+import { PostEvent } from './postEvent.js';
+
 /**
  * Creates function which checks if specified method and parameters are supported. In case,
  * method or parameters are unsupported, an error will be thrown.
  * @param version - Telegram Mini Apps version.
- * @throws {MethodUnsupportedError} Method is unsupported.
- * @throws {ParameterUnsupportedError} Method parameter is unsupported.
+ * @throws {SDKError} ERR_METHOD_UNSUPPORTED
+ * @throws {SDKError} ERR_METHOD_PARAMETER_UNSUPPORTED
+ * @see ERR_METHOD_UNSUPPORTED
+ * @see ERR_METHOD_PARAMETER_UNSUPPORTED
  */
 export declare function createPostEvent(version: Version): PostEvent;

package/dist/dts/bridge/methods/postEvent.d.ts

@@ -1,29 +1,38 @@
-import type { MiniAppsEmptyMethodName, MiniAppsMethodParams, MiniAppsNonEmptyMethodName } from './methods.js';
+import { MiniAppsMethodParams, MiniAppsMethodWithOptionalParams, MiniAppsMethodWithoutParams, MiniAppsMethodWithRequiredParams } from './types/methods.js';
+
 interface PostEventOptions {
     /**
-     * Origin used while posting message. This option is only used in case,
-     * current environment is browser (Web version of Telegram) and could
-     * be used for test purposes.
+     * Origin used while posting message. This option is only used in case, current environment
+     * is browser (Web version of Telegram) and could be used for test purposes.
      * @default 'https://web.telegram.org'
      */
     targetOrigin?: string;
 }
 export type PostEvent = typeof postEvent;
 /**
- * Sends event to native application which launched Mini App. This function
- * accepts only events, which require arguments.
- * @param eventType - event name.
- * @param params - event parameters.
+ * Calls Mini Apps method with optional parameters.
+ * @param method - method name.
+ * @param params - method parameters.
  * @param options - posting options.
- * @throws {Error} Bridge could not determine current environment and possible way to send event.
+ * @throws {SDKError} ERR_UNKNOWN_ENV
+ * @see ERR_UNKNOWN_ENV
  */
-export declare function postEvent<E extends MiniAppsNonEmptyMethodName>(eventType: E, params: MiniAppsMethodParams<E>, options?: PostEventOptions): void;
+export declare function postEvent<Method extends MiniAppsMethodWithOptionalParams>(method: Method, params?: MiniAppsMethodParams<Method>, options?: PostEventOptions): void;
 /**
- * Sends event to native application which launched Mini App. This function
- * accepts only events, which require arguments.
- * @param eventType - event name.
+ * Calls Mini Apps method without parameters.
+ * @param method - method name.
  * @param options - posting options.
- * @throws {Error} Bridge could not determine current environment and possible way to send event.
+ * @throws {SDKError} ERR_UNKNOWN_ENV
+ * @see ERR_UNKNOWN_ENV
  */
-export declare function postEvent(eventType: MiniAppsEmptyMethodName, options?: PostEventOptions): void;
+export declare function postEvent(method: MiniAppsMethodWithoutParams, options?: PostEventOptions): void;
+/**
+ * Calls Mini Apps method with parameters.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param options - posting options.
+ * @throws {SDKError} ERR_UNKNOWN_ENV
+ * @see ERR_UNKNOWN_ENV
+ */
+export declare function postEvent<Method extends MiniAppsMethodWithRequiredParams>(method: Method, params: MiniAppsMethodParams<Method>, options?: PostEventOptions): void;
 export {};

package/dist/dts/bridge/methods/{custom-methods.d.ts → types/custom-methods.d.ts}

@@ -1,4 +1,5 @@
-import type { RequestId } from '../../types/request-id.js';
+import { RequestId } from '../../../request-id/types.js';
+
 interface CreateInvokeCustomMethodParams<M extends string, Params extends object> {
     /**
      * Unique request identifier.

package/dist/dts/bridge/methods/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './custom-methods.js';
+export * from './haptic.js';
+export * from './methods.js';
+export * from './popup.js';

package/dist/dts/bridge/methods/{methods.d.ts → types/methods.d.ts}

@@ -1,11 +1,10 @@
-import type { AnyInvokeCustomMethodParams } from './custom-methods.js';
-import type { AnyHapticFeedbackParams } from './haptic.js';
-import type { PopupParams } from './popup.js';
-import type { RGB } from '../../colors/types.js';
-import type { If, Not } from '../../types/logical.js';
-import type { RequestId } from '../../types/request-id.js';
-import type { UnionKeys } from '../../types/unions.js';
-import type { IsNever } from '../../types/utils.js';
+import { RGB } from '../../../colors/types.js';
+import { RequestId } from '../../../request-id/types.js';
+import { If, IsNever, UnionKeys } from '../../../types/index.js';
+import { AnyInvokeCustomMethodParams } from './custom-methods.js';
+import { AnyHapticFeedbackParams } from './haptic.js';
+import { PopupParams } from './popup.js';
+
 /**
  * Color key which could be used to update header color.
  */
@@ -39,6 +38,58 @@ export interface MiniAppsMethods {
      * @see https://docs.telegram-mini-apps.com/platform/methods#iframe-will-reload
      */
     iframe_will_reload: CreateParams;
+    /**
+     * Request current biometry settings.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-biometry-get-info
+     */
+    web_app_biometry_get_info: CreateParams;
+    /**
+     * Opens the biometric access settings for bots. Useful when you need to request biometrics
+     * access to users who haven't granted it yet.
+     *
+     * _Note that this method can be called only in response to user interaction with the Mini
+     * App interface (e.g. a click inside the Mini App or on the main button)_.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-biometry-open-settings
+     */
+    web_app_biometry_open_settings: CreateParams;
+    /**
+     * Requests access to use biometrics.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-biometry-request-access
+     */
+    web_app_biometry_request_access: CreateParams<{
+        /**
+         * Reason to request biometry access. Should be at least 1 symbol length, but not
+         * more than 128 symbols.
+         */
+        reason?: string;
+    }>;
+    /**
+     * Authenticates the user using biometrics.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-biometry-request-auth
+     */
+    web_app_biometry_request_auth: CreateParams<{
+        /**
+         * Reason to request biometry data. Should be at least 1 symbol length, but not more than
+         * 128 symbols.
+         */
+        reason?: string;
+    }>;
+    /**
+     * Updates the biometric token in secure storage on the device. To remove the token, pass
+     * an empty string.
+     * @since 7.2
+     * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-biometry-update-token
+     */
+    web_app_biometry_update_token: CreateParams<{
+        /**
+         * Token to store. Has max length of 1024 symbols.
+         */
+        token: string;
+    }>;
     /**
      * Closes Mini App.
      * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-close
@@ -296,27 +347,29 @@ export interface MiniAppsMethods {
     web_app_trigger_haptic_feedback: CreateParams<AnyHapticFeedbackParams>;
 }
 /**
- * Any Telegram Mini Apps known method name.
+ * Mini Apps method name.
  */
 export type MiniAppsMethodName = keyof MiniAppsMethods;
 /**
- * Returns parameters for specified post-available event.
+ * Parameters of the specified Mini Apps method.
  */
 export type MiniAppsMethodParams<M extends MiniAppsMethodName> = MiniAppsMethods[M]['params'];
 /**
- * True if specified method accepts parameters.
+ * Methods with optional parameters.
  */
-export type MiniAppsMethodAcceptParams<M extends MiniAppsMethodName> = Not<IsNever<MiniAppsMethodParams<M>>>;
+export type MiniAppsMethodWithOptionalParams = {
+    [Method in MiniAppsMethodName]: undefined extends MiniAppsMethodParams<Method> ? Method : never;
+}[MiniAppsMethodName];
 /**
- * Any post-available event name which does not require arguments.
+ * Methods without parameters.
  */
-export type MiniAppsEmptyMethodName = {
-    [Method in MiniAppsMethodName]: If<MiniAppsMethodAcceptParams<Method>, never, Method>;
+export type MiniAppsMethodWithoutParams = {
+    [Method in MiniAppsMethodName]: If<IsNever<MiniAppsMethodParams<Method>>, Method, never>;
 }[MiniAppsMethodName];
 /**
- * Any post-available event name which require arguments.
+ * Methods with parameters.
  */
-export type MiniAppsNonEmptyMethodName = Exclude<MiniAppsMethodName, MiniAppsEmptyMethodName>;
+export type MiniAppsMethodWithRequiredParams = Exclude<MiniAppsMethodName, MiniAppsMethodWithoutParams | MiniAppsMethodWithOptionalParams>;
 /**
  * Method names which have versioned params.
  */

package/dist/dts/{globals.d.ts → bridge/target-origin.d.ts}

@@ -1,12 +1,3 @@
-import { Logger } from './logger/Logger.js';
-export declare const logger: Logger;
-/**
- * Sets new debug mode. Enabling debug mode leads to printing
- * additional messages in console, related to the processes
- * inside the package.
- * @param value - should debug mode be enabled.
- */
-export declare function setDebug(value: boolean): void;
 /**
  * Sets new global targetOrigin, used by `postEvent` method.
  * Default value is "https://web.telegram.org". You don't need to

package/dist/dts/bridge/{invokeCustomMethod.d.ts → utils/invokeCustomMethod.d.ts}

@@ -1,11 +1,14 @@
-import type { CustomMethodName, CustomMethodParams } from './methods/custom-methods.js';
-import type { ExecuteWithOptions } from '../types/methods.js';
+import { ExecuteWithOptions } from '../../types/index.js';
+import { CustomMethodName, CustomMethodParams } from '../methods/types/custom-methods.js';
+
 /**
  * Invokes known custom method. Returns method execution result.
  * @param method - method name.
  * @param params - method parameters.
  * @param requestId - request identifier.
  * @param options - additional options.
+ * @throws {SDKError} ERR_INVOKE_CUSTOM_METHOD_RESPONSE
+ * @see ERR_INVOKE_CUSTOM_METHOD_RESPONSE
  */
 export declare function invokeCustomMethod<M extends CustomMethodName>(method: M, params: CustomMethodParams<M>, requestId: string, options?: ExecuteWithOptions): Promise<unknown>;
 /**
@@ -14,5 +17,7 @@ export declare function invokeCustomMethod<M extends CustomMethodName>(method: M
  * @param params - method parameters.
  * @param requestId - request identifier.
  * @param options - additional options.
+ * @throws {SDKError} ERR_INVOKE_CUSTOM_METHOD_RESPONSE
+ * @see ERR_INVOKE_CUSTOM_METHOD_RESPONSE
  */
 export declare function invokeCustomMethod(method: string, params: object, requestId: string, options?: ExecuteWithOptions): Promise<unknown>;