@tma.js/bridge 1.3.10 → 1.3.11

package/README.md

@@ -4,7 +4,7 @@
 
 [code-badge]: https://img.shields.io/badge/source-black?logo=github
 
-[docs-link]: https://docs.telegram-mini-apps.com/docs/libraries/twa-js-bridge
+[docs-link]: https://docs.telegram-mini-apps.com/packages/typescript/tma-js-bridge
 
 [docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
 
@@ -25,4 +25,4 @@ data difference problems to protect developers code and save their time.
 
 This library is a part of TypeScript packages ecosystem around Telegram Web
 Apps. You can learn more about this package in this
-[documentation](https://docs.telegram-mini-apps.com/docs/libraries/twa-js-bridge).
+[documentation][docs-link].

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

@@ -3,87 +3,99 @@ import type { IsNever, Not } from '@tma.js/util-types';
 import type { ClipboardTextReceivedPayload, CustomMethodInvokedPayload, InvoiceClosedPayload, PhoneRequestedPayload, PopupClosedPayload, QrTextReceivedPayload, ThemeChangedPayload, ViewportChangedPayload, WriteAccessRequestedPayload } from './payloads.js';
 /**
  * Map where key is known event name, and value is its listener.
- * @see Documentation https://docs.telegram-mini-apps.com/docs/apps-communication/events
+ * @see https://docs.telegram-mini-apps.com/apps-communication/events
  */
 export interface Events {
     /**
      * User clicked back button.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#back_button_pressed
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#back-button-pressed
      */
     back_button_pressed: () => void;
     /**
-     * Text was extracted from clipboard.
-     * @param payload - event information.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#clipboard_text_received
+     * Telegram application attempted to extract text from clipboard.
+     * @param payload - event payload.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#clipboard-text-received
      */
     clipboard_text_received: (payload: ClipboardTextReceivedPayload) => void;
     /**
-     * Being called whenever custom method was invoked.
+     * Custom method invocation completed.
      * @param payload - event payload.
-     * @since 6.9
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#custom-method-invoked
      */
     custom_method_invoked: (payload: CustomMethodInvokedPayload) => void;
     /**
-     * Invoice was closed.
+     * An invoice was closed.
      * @param payload - invoice close information.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#invoice_closed
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#invoice-closed
      */
     invoice_closed: (payload: InvoiceClosedPayload) => void;
     /**
-     * User clicked main button.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#main_button_pressed
+     * User clicked the Main Button.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#main-button-pressed
      */
     main_button_pressed: () => void;
     /**
      * Application received phone access request status.
-     * @param payload - event payload. - event payload.
-     * @since 6.9
+     * @param payload - event payload.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#phone-requested
      */
     phone_requested: (payload: PhoneRequestedPayload) => void;
     /**
      * Popup was closed.
-     * @param payload - popup close information.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#main_button_pressed
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#popup-closed
      */
     popup_closed: (payload: PopupClosedPayload) => void;
     /**
-     * Data from QR was extracted.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#qr_text_received
+     * The QR scanner scanned some QR and extracted its content.
+     * @param payload - event payload.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#qr-text-received
      */
     qr_text_received: (payload: QrTextReceivedPayload) => void;
     /**
      * QR scanner was closed.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#scan_qr_popup_closed
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#scan-qr-popup-closed
      */
     scan_qr_popup_closed: () => void;
     /**
-     * Telegram requested to update current application style.
+     * 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).
      * @param html - `style` tag inner HTML.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#set_custom_style
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#set-custom-style
      */
     set_custom_style: (html: string) => void;
     /**
-     * Occurs when the Settings item in context menu is pressed.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#settings_button_pressed
+     * Occurs when the Settings Button was pressed.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#settings-button-pressed
      */
     settings_button_pressed: () => void;
     /**
      * Occurs whenever theme settings are changed in the user's Telegram app
      * (including switching to night mode).
-     * @param payload - theme information.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#theme_changed
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#theme-changed
      */
     theme_changed: (payload: ThemeChangedPayload) => void;
     /**
-     * Viewport was changed.
-     * @param payload - viewport information.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#viewport_changed
+     * Occurs whenever the viewport has been changed. For example, when the user started
+     * dragging the application or called the expansion method.
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#viewport-changed
      */
     viewport_changed: (payload: ViewportChangedPayload) => void;
     /**
-     * Application received write access requests status.
+     * Application received write access request status.
      * @param payload - event payload.
-     * @since 6.9
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/events#write-access-requested
      */
     write_access_requested: (payload: WriteAccessRequestedPayload) => void;
 }

package/dist/dts/events/payloads.d.ts

@@ -1,23 +1,52 @@
 import type { RGB } from '@tma.js/colors';
 import type { RequestId } from '../shared.js';
 export interface ClipboardTextReceivedPayload {
+    /**
+     * 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;
 }
 export interface CustomMethodInvokedPayload<R = unknown> {
+    /**
+     * Unique identifier of this invocation.
+     */
     req_id: RequestId;
+    /**
+     * Method invocation successful result.
+     */
     result?: R;
+    /**
+     * Method invocation error code.
+     */
     error?: string;
 }
 export type InvoiceStatus = 'paid' | 'failed' | 'pending' | 'cancelled' | string;
 export interface InvoiceClosedPayload {
+    /**
+     * Passed during the `web_app_open_invoice` method invocation `slug` value.
+     */
     slug: string;
+    /**
+     * Invoice status
+     */
     status: InvoiceStatus;
 }
 export interface QrTextReceivedPayload {
+    /**
+     * Data extracted from the QR.
+     */
     data?: string;
 }
 export interface ThemeChangedPayload {
+    /**
+     * Map where the key is a theme stylesheet key and value is  the corresponding color in
+     * `#RRGGBB` format.
+     */
     theme_params: {
         bg_color?: RGB;
         text_color?: RGB;
@@ -29,19 +58,41 @@ export interface ThemeChangedPayload {
     };
 }
 export interface ViewportChangedPayload {
+    /**
+     * 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;
 }
 export interface PopupClosedPayload {
+    /**
+     * Identifier of the clicked button. In case, the popup was closed without clicking any button,
+     * this property will be omitted.
+     */
     button_id?: string;
 }
 export type PhoneRequestedStatus = 'sent' | string;
 export interface PhoneRequestedPayload {
+    /**
+     * Request status.
+     */
     status: PhoneRequestedStatus;
 }
 export type WriteAccessRequestedStatus = 'allowed' | string;
 export interface WriteAccessRequestedPayload {
+    /**
+     * Request status.
+     */
     status: WriteAccessRequestedStatus;
 }

package/dist/dts/methods/params.d.ts

@@ -5,198 +5,281 @@ import type { AnyHapticFeedbackParams } from './haptic.js';
 import type { RequestId } from '../shared.js';
 import type { AnyInvokeCustomMethodParams } from './invoke-custom-method.js';
 /**
- * Color key which could be used tot update header color.
+ * Color key which could be used to update header color.
  */
 export type HeaderColorKey = 'bg_color' | 'secondary_bg_color';
+/**
+ * Chat type which could be used when calling `web_app_switch_inline_query` method.
+ */
+export type SwitchInlineQueryChatType = 'users' | 'bots' | 'groups' | 'channels';
 type CreateParams<P = never, SupportCheckKey extends UnionKeys<P> = never> = {
     params: P;
     supportCheckKey: SupportCheckKey;
 };
 /**
- * Describes list of events and their parameters that could be posted by
- * Bridge.
- * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods
+ * Describes list of events and their parameters that could be posted by Bridge.
+ * @see https://docs.telegram-mini-apps.com/apps-communication/methods
  */
 export interface MethodsParams {
     /**
-     * Notifies parent iframe about current frame is ready.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#iframe_ready
-     * @since 6.0
+     * Notifies parent iframe about the current frame is ready. This method is only used in the Web
+     * version of Telegram. As a result, Mini App will receive `set_custom_style` event.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#iframe-ready
      */
     iframe_ready: CreateParams;
     /**
-     * Closes WebApp.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_close
-     * @since 6.0
+     * Closes Mini App.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-close
      */
     web_app_close: CreateParams;
     /**
-     * Closes QR scanner.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_close_scan_qr_popup
-     * @since 6.4
+     * Closes a QR scanner. The Telegram application creates `scan_qr_popup_closed` event.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-close-scan-qr-popup
      */
     web_app_close_scan_qr_popup: CreateParams;
     /**
-     * Sends data to bot.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_data_send
-     * @since 6.0
+     * Sends data to the bot. When this method is called, a service message is sent to the bot
+     * containing the data of the length up to 4096 bytes. Then, Mini App will be closed.
+     *
+     * To get more information, take a look at `web_app_data` field in the
+     * class [Message](https://core.telegram.org/bots/api#message).
+     *
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-data-send
      */
     web_app_data_send: CreateParams<{
+        /**
+         * Data to send to a bot. Should not have size of more than 4096 bytes.
+         */
         data: string;
     }>;
     /**
-     * Expands Web App.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_expand
-     * @since 6.0
+     * Expands the Mini App.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-expand
      */
     web_app_expand: CreateParams;
     /**
      * Invokes custom method.
-     * @since 6.9
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-invoke-custom-method
      */
     web_app_invoke_custom_method: CreateParams<AnyInvokeCustomMethodParams>;
     /**
-     * Opens new invoice.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_invoice
-     * @since 6.1
+     * Opens an invoice by its specified slug. More information about invoices in
+     * this [documentation](https://core.telegram.org/bots/payments).
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-open-invoice
      */
     web_app_open_invoice: CreateParams<{
+        /**
+         * Invoice unique identifier.
+         */
         slug: string;
     }>;
     /**
-     * Opens link in default browser. Doesn't close application.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_link
-     * @since 6.0
+     * Opens link in the default browser. Mini App will not be closed.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-open-link
      */
     web_app_open_link: CreateParams<{
+        /**
+         * URL to be opened by Telegram application. Should be a full path with `https` protocol.
+         */
         url: string;
         /**
          * Link will be opened in Instant View mode if possible.
+         * @since v6.4
          * @see https://instantview.telegram.org/
-         * @since 6.4
          */
         try_instant_view?: boolean;
     }, 'try_instant_view'>;
     /**
-     * Opens new popup.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_popup
-     * @since 6.2
+     * Opens a new popup. When user closes the popup, Telegram creates the `popup_closed` event.
+     * @since v6.2
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-open-popup
      */
     web_app_open_popup: CreateParams<PopupParams>;
     /**
-     * Opens QR scanner.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_scan_qr_popup
-     * @since 6.4
+     * Opens a QR scanner. When the scanner was closed, the Telegram application creates
+     * the `scan_qr_popup_closed` event. When the scanner reads QR, Telegram creates the
+     * `qr_text_received` event.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-open-scan-qr-popup
      */
     web_app_open_scan_qr_popup: CreateParams<{
+        /**
+         * Text to be displayed in the QR scanner.
+         */
         text?: string;
     }>;
     /**
-     * Opens link which has format like "https://t.me/*".
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_tg_link
-     * @since 6.1
+     * Opens the Telegram link by its pathname and query parameters. The link will be opened in the
+     * Telegram app, Mini App will be closed.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-open-tg-link
      */
     web_app_open_tg_link: CreateParams<{
+        /**
+         * Should be a value taken from the link of this format: `https://t.me/{path_full}`. Can
+         * additionally contain query parameters.
+         */
         path_full: string;
     }>;
     /**
-     * Reads text from clipboard.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_read_text_from_clipboard
-     * @since 6.4
+     * Reads text from the clipboard. The method accepts a request identifier which is used to
+     * appropriately retrieve the method execution result from the `clipboard_text_received` event.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-read-text-from-clipboard
      */
     web_app_read_text_from_clipboard: CreateParams<{
+        /**
+         * Unique request identifier. Should be any unique string to handle the generated event
+         * appropriately.
+         */
         req_id: RequestId;
     }>;
     /**
-     * Notifies Telegram about current application is ready to be shown.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_ready
-     * @since 6.0
+     * Notifies Telegram about current application is ready to be shown. This method will make
+     * Telegram to remove application loader and display Mini App.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-ready
      */
     web_app_ready: CreateParams;
     /**
      * Requests access to current user's phone.
-     * @since 6.9
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-request-phone
      */
     web_app_request_phone: CreateParams;
     /**
-     * Requests current theme from Telegram.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_request_theme
-     * @since 6.0
+     * Requests current theme from Telegram. As a result, Telegram will create `theme_changed` event.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-request-theme
      */
     web_app_request_theme: CreateParams;
     /**
-     * Requests current viewport information from Telegram.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_request_viewport
-     * @since 6.0
+     * Requests current viewport information from Telegram. As a result, Telegram will create
+     * `viewport_changed` event.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-request-viewport
      */
     web_app_request_viewport: CreateParams;
     /**
      * Requests write message access to current user.
-     * @since 6.9
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-rqeuest-write-access
      */
     web_app_request_write_access: CreateParams;
     /**
-     * Updates current background color.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_set_background_color
-     * @since 6.1
+     * Updates the Mini App background color.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-set-background-color
      */
     web_app_set_background_color: CreateParams<{
-        color: string;
+        /**
+         * The Mini App background color in `#RRGGBB` format.
+         */
+        color: RGB;
     }>;
     /**
-     * Updates current header color.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_set_header_color
-     * @since 6.1
+     * Updates the Mini App header color.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-set-header-color
      */
     web_app_set_header_color: CreateParams<{
+        /**
+         * The Mini App header color key.
+         */
         color_key: HeaderColorKey;
     } | {
         /**
-         * @since 6.9
+         * Color in RGB format.
+         * @since v6.9
          */
         color: RGB;
     }, 'color'>;
     /**
-     * Updates current information about back button.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_back_button
-     * @since 6.1
+     * Updates the Back Button settings.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-setup-back-button
      */
     web_app_setup_back_button: CreateParams<{
+        /**
+         * Should the Back Button be visible.
+         */
         is_visible: boolean;
     }>;
     /**
-     * Changes current closing confirmation requirement status.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_closing_behavior
-     * @since 6.0
+     * Updates current closing behavior.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-setup-closing-behavior
      */
     web_app_setup_closing_behavior: CreateParams<{
+        /**
+         * Will user be prompted in case, an application is going to be closed.
+         */
         need_confirmation: boolean;
     }>;
     /**
-     * Updates current information about main button.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_main_button
-     * @since 6.0
+     * Updates the Main Button settings.
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-setup-main-button
      */
     web_app_setup_main_button: CreateParams<{
+        /**
+         * Should the Main Button be displayed.
+         */
         is_visible?: boolean;
+        /**
+         * Should the Main Button be enabled.
+         */
         is_active?: boolean;
+        /**
+         * Should loader inside the Main Button be displayed. Use this property in case, some
+         * operation takes time. This loader will make user notified about it.
+         */
         is_progress_visible?: boolean;
+        /**
+         * Text inside the Main Button.
+         */
         text?: string;
+        /**
+         * The Main Button background color in `#RRGGBB` format.
+         */
         color?: string;
+        /**
+         * The Main Button text color in `#RRGGBB` format.
+         */
         text_color?: string;
     }>;
     /**
-     * Updates current information about Settings Button.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_settings_button
-     * @since 6.10
+     * Updates current state of Settings Button.
+     * @since v6.10
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-setup-settings-button
      */
     web_app_setup_settings_button: CreateParams<{
+        /**
+         * Should the Settings Button be displayed.
+         */
         is_visible: boolean;
     }>;
+    /**
+     * Inserts the bot's username and the specified inline query in the current chat's input field.
+     * Query may be empty, in which case only the bot's username will be inserted. The client prompts
+     * the user to choose a specific chat, then opens that chat and inserts the bot's username and
+     * the specified inline query in the input field.
+     * @since v6.7
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-switch-inline-query
+     */
+    web_app_switch_inline_query: CreateParams<{
+        /**
+         * Text which should be inserted in the input after the current bot name. Max length is
+         * 256 symbols.
+         */
+        query: string;
+        /**
+         * List of chat types which could be chosen to send the message. Could be empty list.
+         */
+        chat_types: SwitchInlineQueryChatType[];
+    }>;
     /**
      * Generates haptic feedback event.
-     * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_trigger_haptic_feedback
-     * @since 6.1
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/apps-communication/methods#web-app-trigger-haptic-feedback
      */
     web_app_trigger_haptic_feedback: CreateParams<AnyHapticFeedbackParams>;
 }

package/dist/dts/methods/popup.d.ts

@@ -1,6 +1,5 @@
 /**
  * Describes the native popup.
- * @see https://core.telegram.org/bots/webapps#popupparams
  */
 export interface PopupParams {
     /**
@@ -18,7 +17,7 @@ export interface PopupParams {
 }
 /**
  * Describes the native popup button.
- * @see https://core.telegram.org/bots/webapps#popupbutton
+ * @see https://docs.telegram-mini-apps.com/apps-communication/methods#popupbutton
  */
 export type PopupButton = {
     /**

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

@@ -10,7 +10,7 @@ interface PostEventOptions {
 }
 export type PostEvent = typeof postEvent;
 /**
- * Sends event to native application which launched Web App. This function
+ * 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.
@@ -20,7 +20,7 @@ export type PostEvent = typeof postEvent;
  */
 export declare function postEvent<E extends NonEmptyMethodName>(eventType: E, params: MethodParams<E>, options?: PostEventOptions): void;
 /**
- * Sends event to native application which launched Web App. This function
+ * Sends event to native application which launched Mini App. This function
  * accepts only events, which require arguments.
  * @param eventType - event name.
  * @param options - posting options.