Implement add to home screen functionality

.changeset/curly-cats-poke.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/sdk": minor
+---
+
+Implement add to home screen-related functionality.

.changeset/fair-timers-arrive.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/toolkit": minor
+---
+
+Set name for the TypedError class.

.changeset/real-pigs-deny.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/bridge": minor
+---
+
+Implement `home_screen_added`, `home_screen_checked` and `home_screen_failed` events. Implement `web_app_add_to_home_screen` and `web_app_check_home_screen` methods.

apps/docs/.vitepress/packages.ts

@@ -110,6 +110,7 @@ export const packagesLinksGenerator = (prefix: string = '') => {
             ],
             'Utilities': [{ url: 'utils', page: false }, fromEntries([
               scope('emoji-status'),
+              scope('home-screen'),
               scope('links'),
               scope('privacy'),
               scope('uncategorized'),

apps/docs/packages/telegram-apps-sdk/2-x/utils/home-screen.md

@@ -0,0 +1,68 @@
+# Home Screen
+
+## `addToHomeScreen`
+
+To prompt the user to add the Mini App to the home screen, use the `addToHomeScreen` function.
+
+::: code-group
+
+```ts [Using isAvailable]
+import { addToHomeScreen } from '@telegram-apps/sdk';
+
+if (addToHomeScreen.isAvailable()) {
+  addToHomeScreen();
+}
+```
+
+```ts [Using ifAvailable]
+import { addToHomeScreen } from '@telegram-apps/sdk';
+
+addToHomeScreen.ifAvailable();
+```
+
+:::
+
+To track whether the current Mini App is added to the device's home screen, use
+the `onAddedToHomeScreen` and `offAddedToHomeScreen` functions:
+
+```ts
+import {
+  onAddedToHomeScreen,
+  onAddToHomeScreenFailed,
+  offAddedToHomeScreen,
+  offAddToHomeScreenFailed,
+} from '@telegram-apps/sdk';
+
+function onAdded() {
+  console.log('Added');
+}
+
+onAddedToHomeScreen(onAdded);
+offAddedToHomeScreen(onAdded);
+
+function onFailed() {
+  console.log('User declined the request');
+}
+
+onAddToHomeScreenFailed(onFailed);
+offAddToHomeScreenFailed(onFailed);
+```
+
+> [!NOTE]  
+> If the device cannot determine the installation status, the corresponding event may not be
+> received even if the icon has been added.
+
+## `checkHomeScreenStatus`
+
+The `checkHomeScreenStatus` function checks if the user has already added the Mini App to the
+device's home screen.
+
+```ts
+import { checkHomeScreenStatus } from '@telegram-apps/sdk';
+
+if (checkHomeScreenStatus.isAvailable()) {
+  checkHomeScreenStatus().then(status => {
+    console.log(status);
+  });
+}
+```

apps/docs/platform/events.md

@@ -237,6 +237,35 @@ Occurs whenever the mini app enters or exits the fullscreen mode.
 |-------|----------|---------------------------------------------------------------------------------------|
 | error | `string` | Fullscreen mode status error. Possible values: `UNSUPPORTED` or `ALREADY_FULLSCREEN`. |
 
+### `home_screen_added`
+
+Available since: **v8.0**
+
+The mini application was added to the device's home screen.
+
+### `home_screen_checked`
+
+Available since: **v8.0**
+
+The status of the mini application being added to the home screen has been checked.
+
+| Field  | Type     | Description                                                                                                                        |
+|--------|----------|------------------------------------------------------------------------------------------------------------------------------------|
+| status | `string` | The status of the mini application being added to the home screen. Possible values: `unsupported`, `unknown`, `added` and `missed` |
+
+- `unsupported` – the feature is not supported, and it is not possible to add the icon to the home
+  screen,
+- `unknown` – the feature is supported, and the icon can be added, but it is not possible to
+  determine if the icon has already been added,
+- `added` – the icon has already been added to the home screen,
+- `missed` – the icon has not been added to the home screen.
+
+### `home_screen_failed`
+
+Available since: **v8.0**
+
+User declined the request to add the current mini application to the device's home screen.
+
 ### `invoice_closed`
 
 An invoice was closed.

apps/docs/platform/methods.md

@@ -114,6 +114,14 @@ event.
 
 Notifies parent iframe about the current iframe is going to reload.
 
+### `web_app_add_to_home_screen`
+
+Available since: **v8.0**
+
+Prompts the user to add the Mini App to the home screen. Note that if the device cannot
+determine the installation status, the event may not be received even if the icon has
+been added.
+
 ### `web_app_biometry_get_info`
 
 Available since: **v7.2**
@@ -162,6 +170,13 @@ string.
 |-------|----------|-------------------------------------------------|
 | token | `string` | Token to store. Has max length of 1024 symbols. |
 
+### `web_app_check_home_screen`
+
+Available since: **v8.0**
+
+Sends a request to the native Telegram application to check if the current mini
+application is added to the device's home screen.
+
 ### `web_app_close`
 
 Closes Mini App.

packages/bridge/src/events/types/events.ts

@@ -1,6 +1,6 @@
 import type { RGB } from '@telegram-apps/types';
 
-import {
+import type {
   PhoneRequestedStatus,
   InvoiceStatus,
   WriteAccessRequestedStatus,
@@ -11,6 +11,7 @@ import {
   FullScreenErrorStatus,
   EmojiStatusAccessRequestedStatus,
   EmojiStatusFailedError,
+  HomeScreenStatus,
 } from './misc.js';
 
 /**
@@ -199,6 +200,37 @@ export interface Events {
      */
     error: FullScreenErrorStatus;
   };
+  /**
+   * The mini application was added to the device's home screen.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/events#home_screen_added
+   */
+  home_screen_added: never;
+  /**
+   * The status of the mini application being added to the home screen has been checked.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/events#home_screen_checked
+   */
+  home_screen_checked: {
+    /**
+     * The status of the mini application being added to the home screen.
+     *
+     * Possible values:
+     * - `unsupported` – the feature is not supported, and it is not possible to add the icon to the home
+     *   screen,
+     * - `unknown` – the feature is supported, and the icon can be added, but it is not possible to
+     *   determine if the icon has already been added,
+     * - `added` – the icon has already been added to the home screen,
+     * - `missed` – the icon has not been added to the home screen.
+     */
+    status?: HomeScreenStatus;
+  };
+  /**
+   * User declined the request to add the current mini application to the device's home screen.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/events#home_screen_failed
+   */
+  home_screen_failed: never;
   /**
    * An invoice was closed.
    * @see https://docs.telegram-mini-apps.com/platform/events#invoice-closed

packages/bridge/src/events/types/misc.ts

@@ -33,4 +33,6 @@ export interface SafeAreaInsets {
   bottom: number;
   left: number;
   right: number;
-}
+}
+
+export type HomeScreenStatus = 'unsupported' | 'unknown' | 'added' | 'missed' | string;

packages/bridge/src/methods/supports.test.ts

@@ -121,6 +121,8 @@ describe.each<[
     'web_app_exit_fullscreen',
     'web_app_set_emoji_status',
     'web_app_request_emoji_status_access',
+    'web_app_add_to_home_screen',
+    'web_app_check_home_screen',
   ]],
 ])('%s', (version, methods) => {
   const higher = increaseVersion(version, 1);

packages/bridge/src/methods/supports.ts

@@ -106,6 +106,8 @@ export function supports(
     case 'web_app_request_fullscreen':
     case 'web_app_exit_fullscreen':
     case 'web_app_set_emoji_status':
+    case 'web_app_add_to_home_screen':
+    case 'web_app_check_home_screen':
     case 'web_app_request_emoji_status_access':
       return versionLessOrEqual('8.0', paramOrVersion);
     default:

packages/bridge/src/methods/types/methods.ts

@@ -68,6 +68,14 @@ export interface Methods {
    * @see https://docs.telegram-mini-apps.com/platform/methods#iframe-will-reload
    */
   iframe_will_reload: CreateMethodParams;
+  /**
+   * Prompts the user to add the Mini App to the home screen. Note that if the device cannot
+   * determine the installation status, the event may not be received even if the icon has
+   * been added.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-add-to-home-screen
+   */
+  web_app_add_to_home_screen: CreateMethodParams;
   /**
    * Emitted by bot mini apps to ask the client to initialize the biometric authentication manager
    * object for the current bot, emitting a `biometry_info_received` event on completion.
@@ -148,6 +156,13 @@ export interface Methods {
      */
     token: string;
   }>;
+  /**
+   * Sends a request to the native Telegram application to check if the current mini
+   * application is added to the device's home screen.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-check-home-screen
+   */
+  web_app_check_home_screen: CreateMethodParams;
   /**
    * Closes Mini App.
    * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-close

packages/sdk/src/index.ts

@@ -18,6 +18,7 @@ export * from '@/scopes/components/swipe-behavior/exports.js';
 export * from '@/scopes/components/theme-params/exports.js';
 export * from '@/scopes/components/viewport/exports.js';
 export * from '@/scopes/utilities/emoji-status/exports.js';
+export * from '@/scopes/utilities/home-screen/exports.js';
 export * from '@/scopes/utilities/links/exports.js';
 export * from '@/scopes/utilities/privacy/exports.js';
 export * from '@/scopes/utilities/uncategorized/exports.js';

packages/sdk/src/scopes/utilities/home-screen/exports.ts

@@ -0,0 +1,11 @@
+export {
+  checkHomeScreenStatusError,
+  checkHomeScreenStatusPromise,
+  isCheckingHomeScreenStatus,
+  checkHomeScreenStatus,
+  offAddedToHomeScreen,
+  onAddedToHomeScreen,
+  addToHomeScreen,
+  offAddToHomeScreenFailed,
+  onAddToHomeScreenFailed,
+} from './home-screen.js';

packages/sdk/src/scopes/utilities/home-screen/home-screen.test.ts

@@ -0,0 +1,33 @@
+import { beforeEach, describe, vi } from 'vitest';
+
+import { testSafety } from '@test-utils/predefined/testSafety.js';
+import { resetPackageState } from '@test-utils/reset/reset.js';
+import { mockPostEvent } from '@test-utils/mockPostEvent.js';
+
+import {
+  addToHomeScreen,
+  onAddedToHomeScreen,
+  offAddedToHomeScreen,
+  checkHomeScreenStatus,
+} from './home-screen.js';
+
+beforeEach(() => {
+  resetPackageState();
+  vi.restoreAllMocks();
+  mockPostEvent();
+});
+
+describe('safety', () => {
+  testSafety(addToHomeScreen, 'addToHomeScreen', { minVersion: '8.0' });
+});
+
+describe.each([
+  ['addToHomeScreen', addToHomeScreen],
+  ['onAddedToHomeScreen', onAddedToHomeScreen],
+  ['offAddedToHomeScreen', offAddedToHomeScreen],
+  ['checkHomeScreenStatus', checkHomeScreenStatus],
+] as const)('%s', (name, fn) => {
+  testSafety(fn, name, {
+    minVersion: '8.0',
+  });
+});