👽️ Add typings for BOT API 7.2 (#12)

.prettierrc

@@ -2,7 +2,5 @@
   "printWidth": 90,
   "semi": false,
   "singleQuote": true,
-  "trailingComma": "none",
-  "plugins": ["prettier-plugin-sort-imports"],
-  "pluginSearchDirs": false
+  "trailingComma": "none"
 }

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Dmitry
+Copyright (c) 2023-2024 Dmitry
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,20 +1,20 @@
-<h1 align="center">Typings for Telegram Web Apps</h1>
+<h1 align="center">Typings for Telegram Mini Apps</h1>
 
 <p align="center">
 <a href="https://npmjs.com/package/telegram-webapps"><img alt="Version" src="https://img.shields.io/npm/v/telegram-webapps"/></a>
 <a href="https://npmjs.com/package/telegram-webapps"><img alt="License MIT" src="https://img.shields.io/npm/l/telegram-webapps"/></a>
 <a href="https://npmjs.com/package/telegram-webapps"><img alt="npm" src="https://img.shields.io/npm/dt/telegram-webapps"/></a>
 </p>
 <p align="center">
-<a href="https://core.telegram.org/bots/webapps"><img alt="Telegram Bot API Version 7.0" src="https://img.shields.io/badge/Telegram%20Bot%20API-7.0-blue.svg?logo=telegram"/></a>
+<a href="https://core.telegram.org/bots/webapps"><img alt="Telegram Bot API Version 7.2" src="https://img.shields.io/badge/Telegram%20Bot%20API-7.2-blue.svg?logo=telegram"/></a>
 </p>
 <p align="center">
 <a href="https://github.com/DavisDmitry/telegram-webapps/actions/workflows/lint.yml"><img alt="CI Lint" src="https://github.com/DavisDmitry/telegram-webapps/actions/workflows/lint.yml/badge.svg"/></a>
 </p>
 
 ---
 
-<p align="center"><a href="https://core.telegram.org/bots/webapps">About Telegram Web Apps</a></p>
+<p align="center"><a href="https://core.telegram.org/bots/webapps">About Telegram Mini Apps</a></p>
 
 ---
 

package.json

@@ -1,10 +1,14 @@
 {
   "name": "telegram-webapps",
-  "version": "7.0.0",
-  "description": "Typings for Telegram Web Apps",
+  "version": "7.2.0",
+  "description": "Typings for Telegram Mini Apps",
   "keywords": [
     "telegram",
     "telegram-webapps",
+    "telegram-web-apps",
+    "telegram-miniapps",
+    "telegram-mini-apps",
+    "telegram-bot",
     "typescript",
     "types",
     "typings"
@@ -21,16 +25,11 @@
     "url": "https://github.com/DavisDmitry/telegram-webapps.git"
   },
   "scripts": {
-    "lint": "prettier --plugin-search-dir . --check . && eslint .",
-    "format": "prettier --plugin-search-dir . --check . --write ."
+    "lint": "prettier --check src",
+    "format": "prettier -w src"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^5.62.0",
-    "@typescript-eslint/parser": "^5.62.0",
-    "eslint": "^8.48.0",
-    "eslint-config-prettier": "^8.10.0",
-    "prettier": "^2.8.2",
-    "prettier-plugin-sort-imports": "^1.7.1",
-    "typescript": "^4.9.4"
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.4"
   }
 }

src/index.d.ts

@@ -164,6 +164,10 @@ export declare namespace TelegramWebApps {
      * An object for controlling cloud storage.
      */
     readonly CloudStorage: CloudStorage
+    /**
+     * An object for controlling biometrics on the device.
+     */
+    readonly BiometricManager: BiometricManager
     /**
      * Returns true if the user's app supports a version of the Bot API that is equal to
      * or higher than the version passed as the parameter.
@@ -311,6 +315,34 @@ export declare namespace TelegramWebApps {
       eventType: 'contactRequested',
       eventHandler: (status: 'sent' | 'cancelled') => void
     ): void
+    /**
+     * `Bot API 7.2+` Occurs whenever `BiometricManager` object is changed
+     *
+     * *eventHandler* receives no parameters.
+     */
+    onEvent(eventType: 'biometricManagerUpdated', eventHandler: () => void): void
+    /**
+     * 	`Bot API 7.2+` Occurs whenever biometric authentication was requested.
+     *
+     * *eventHandler* receives an object with the field *isAuthenticated* containing a
+     * boolean indicating whether the user was authenticated successfully. If
+     * *isAuthenticated* is true, the field *biometricToken() will contain the biometric
+     * token stored in secure storage on the device.
+     */
+    onEvent(
+      eventType: 'biometricAuthRequested',
+      eventHandler: BiometricAuthRequestedEventHandler
+    ): void
+    /**
+     * `Bot API 7.2+` Occurs whenever the biometric token was updated.
+     *
+     * *eventHandler* receives an object with the single field *isUpdated*, containing a
+     * boolean indicating whether the token was updated.
+     */
+    onEvent(
+      eventType: 'biometricTokenUpdated',
+      eventHandler: BiometricTokenUpdatedEventHandler
+    ): void
     /**
      * A method that deletes a previously set event handler.
      */
@@ -319,7 +351,8 @@ export declare namespace TelegramWebApps {
         | 'themeChanged'
         | 'mainButtonClicked'
         | 'backButtonClicked'
-        | 'settingsButtonClicked',
+        | 'settingsButtonClicked'
+        | 'biometricManagerUpdated',
       eventHandler: () => void
     ): void
     /**
@@ -348,6 +381,20 @@ export declare namespace TelegramWebApps {
       eventType: 'clipboardTextReceived',
       eventHandler: ClipboardTextReceivedEventHandler
     ): void
+    /**
+     * A method that deletes a previously set event handler.
+     */
+    offEvent(
+      eventType: 'biometricAuthRequested',
+      eventHandler: BiometricAuthRequestedEventHandler
+    ): void
+    /**
+     * A method that deletes a previously set event handler.
+     */
+    offEvent(
+      eventType: 'biometricTokenUpdated',
+      eventHandler: BiometricTokenUpdatedEventHandler
+    ): void
     /**
      * A method used to send data to the bot. When this method is called, a service
      * message is sent to the bot containing the data *data* of the length up to 4096
@@ -807,7 +854,7 @@ export declare namespace TelegramWebApps {
       key: string,
       value: string,
       callback?: ((error: Error) => void) | ((error: null, valueStored: boolean) => void)
-    ): void
+    ): CloudStorage
     /**
      * `Bot API 6.9+` A method that receives a value from the cloud storage using the
      * specified key. The key should contain 1-128 characters, only `A-Z`, `a-z`, `0-9`,
@@ -818,7 +865,7 @@ export declare namespace TelegramWebApps {
     getItem(
       key: string,
       callback: ((error: Error) => void) | ((error: null, value: string) => void)
-    ): void
+    ): CloudStorage
     /**
      * `Bot API 6.9+` A method that receives values from the cloud storage using the
      * specified keys. The keys should contain 1-128 characters, only `A-Z`, `a-z`, `0-9`,
@@ -829,7 +876,7 @@ export declare namespace TelegramWebApps {
     getItems(
       keys: string[],
       callback: ((error: Error) => void) | ((error: null, values: string[]) => void)
-    ): void
+    ): CloudStorage
     /**
      * `Bot API 6.9+` A method that removes a value from the cloud storage using the
      * specified key. The key should contain 1-128 characters, only `A-Z`, `a-z`, `0-9`,
@@ -841,7 +888,7 @@ export declare namespace TelegramWebApps {
     removeItem(
       key: string,
       callback?: ((error: Error) => void) | ((error: null, valueRemove: boolean) => void)
-    ): void
+    ): CloudStorage
     /**
      * `Bot API 6.9+` A method that removes values from the cloud storage using the
      * specified keys. The keys should contain 1-128 characters, only `A-Z`, `a-z`, `0-9`,
@@ -855,7 +902,7 @@ export declare namespace TelegramWebApps {
       callback?:
         | ((error: Error) => void)
         | ((error: null, valuesRemoved: boolean) => void)
-    ): void
+    ): CloudStorage
     /**
      * `Bot API 6.9+` A method that receives the list of all keys stored in the cloud
      * storage. In case of an error, the *callback* function will be called and the first
@@ -864,7 +911,116 @@ export declare namespace TelegramWebApps {
      */
     getKeys(
       callback: ((error: Error) => void) | ((error: null, keys: string[]) => void)
-    ): void
+    ): CloudStorage
+  }
+
+  /**
+   * This object controls biometrics on the device. Before the first use of this object,
+   * it needs to be initialized using the init method.
+   */
+  interface BiometricManager {
+    /**
+     * `Bot API 7.2+` Shows whether biometrics object is initialized.
+     */
+    readonly isInited: boolean
+    /**
+     * `Bot API 7.2+` Shows whether biometrics is available on the current device.
+     */
+    readonly isBiometricAvailable: boolean
+    /**
+     * `Bot API 7.2+` The type of biometrics currently available on the device.
+     *
+     * Can be one of these values:
+     * - *finger*, fingerprint-based biometrics,
+     * - *face*, face-based biometrics,
+     * - *unknown*, biometrics of an unknown type.
+     */
+    readonly biometricType: 'finger' | 'face' | 'unknown'
+    /**
+     * `Bot API 7.2+` Shows whether permission to use biometrics has been requested.
+     */
+    readonly isAccessRequested: boolean
+    /**
+     * `Bot API 7.2+` Shows whether permission to use biometrics has been granted.
+     */
+    readonly isAccessGranted: boolean
+    /**
+     * `Bot API 7.2+` Shows whether the token is saved in secure storage on the device.
+     */
+    readonly isBiometricTokenSaved: boolean
+    /**
+     * `Bot API 7.2+` A unique device identifier that can be used to match the token to
+     * the device.
+     */
+    readonly deviceId: string
+    /**
+     * `Bot API 7.2+` A method that initializes the BiometricManager object. It should be
+     * called before the object's first use. If an optional *callback* parameter was
+     * passed, the *callback* function will be called when the object is initialized.
+     */
+    init(callback?: () => void): BiometricManager
+    /**
+     * `Bot API 7.2+` A method that requests permission to use biometrics according to the
+     * *params* argument of type `BiometricRequestAccessParams`. If an optional *callback*
+     * parameter was passed, the *callback* function will be called and the first argument
+     * will be a boolean indicating whether the user granted access.
+     */
+    requestAccess(
+      params: BiometricRequestAccessParams,
+      callback?: (accessGranted: boolean) => void
+    ): BiometricManager
+    /**
+     * `Bot API 7.2+` A method that authenticates the user using biometrics according to
+     * the *params* argument of type `BiometricAuthenticateParams`. If an optional
+     * *callback* parameter was passed, the *callback* function will be called and the
+     * first argument will be a boolean indicating whether the user authenticated
+     * successfully. If so, the second argument will be a biometric token.
+     */
+    authenticate(
+      params: BiometricAuthenticateParams,
+      callback?: (authenticatedSuccessfully: boolean) => void
+    ): BiometricManager
+    /**
+     * `Bot API 7.2+` A method that updates the biometric token in secure storage on the
+     * device. To remove the token, pass an empty string. If an optional *callback*
+     * parameter was passed, the *callback* function will be called and the first argument
+     * will be a boolean indicating whether the token was updated.
+     */
+    updateBiometricToken(
+      token: string,
+      callback?: (tokenPassed: boolean) => void
+    ): BiometricManager
+    /**
+     * `Bot API 7.2+` A method that 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)*
+     */
+    openSettings(): BiometricManager
+  }
+
+  /**
+   * This object describes the native popup for requesting permission to use biometrics.
+   */
+  interface BiometricRequestAccessParams {
+    /**
+     * The text to be displayed to a user in the popup describing why the bot needs access
+     * to biometrics, 0-128 characters.
+     */
+    reason?: string
+  }
+
+  /**
+   * This object describes the native popup for authenticating the user using biometrics.
+   */
+  interface BiometricAuthenticateParams {
+    /**
+     * The text to be displayed to a user in the popup describing why you are asking them
+     * to authenticate and what action you will be taking based on that authentication,
+     * 0-128 characters.
+     */
+    reason?: string
   }
 
   /**
@@ -1009,6 +1165,10 @@ export declare namespace TelegramWebApps {
   type PopupClosedEventHandler = (params: { button_id: string | null }) => void
   type QrTextReceivedEventHandler = (params: { data: string }) => void
   type ClipboardTextReceivedEventHandler = (params: { data: string | null }) => void
+  type BiometricAuthRequestedEventHandler = (
+    params: { isAuthenticated: true; biometricToken: string } | { isAuthenticated: false }
+  ) => void
+  type BiometricTokenUpdatedEventHandler = (params: { isUpdated: boolean }) => void
 }
 
 declare global {