@tma.js/sdk 0.11.6 → 0.12.0

package/src/components/WebApp/WebApp.ts

@@ -10,12 +10,13 @@ import {
   type InvoiceStatus,
   type PostEvent,
 } from '@tma.js/bridge';
+import type { Platform } from '@tma.js/launch-params';
 
 import { formatURL } from '../../url.js';
 import { State } from '../../state/index.js';
 import { createSupportsFunc, createSupportsParamFunc, type SupportsFunc } from '../../supports.js';
 
-import type { ColorScheme, Platform } from '../../types.js';
+import type { ColorScheme } from '../../types.js';
 import type { WebAppEvents, WebAppHeaderColor, WebAppState } from './types.js';
 
 /**

package/src/index.ts

@@ -1,8 +1,7 @@
 export * from './components/index.js';
-export { init, type InitResult, type InitOptions } from './init/index.js';
-export { MethodNotSupportedError } from './errors/index.js';
+export * from './errors/index.js';
+export * from './init/index.js';
 export * from './env.js';
 export * from './launch-params.js';
-export * from './theme-params.js';
 export * from './types.js';
 export * from './url.js';

package/src/init/creators/createBackButton.ts

@@ -7,11 +7,16 @@ import { getStorageValue, saveStorageValue } from '../../storage.js';
 /**
  * Creates BackButton instance using last locally saved data also saving each state in
  * the storage.
+ * @param isPageReload - was current page reloaded.
  * @param version - platform version.
  * @param postEvent - Bridge postEvent function
  */
-export function createBackButton(version: string, postEvent: PostEvent): BackButton {
-  const { isVisible = false } = getStorageValue('back-button') || {};
+export function createBackButton(
+  isPageReload: boolean,
+  version: string,
+  postEvent: PostEvent,
+): BackButton {
+  const { isVisible = false } = isPageReload ? getStorageValue('back-button') || {} : {};
   const component = new BackButton(isVisible, version, postEvent);
 
   component.on('isVisibleChanged', () => {

package/src/init/creators/createClosingBehavior.ts

@@ -7,10 +7,14 @@ import { getStorageValue, saveStorageValue } from '../../storage.js';
 /**
  * Creates ClosingBehaviour instance using last locally saved data also saving each state in
  * the storage.
+ * @param isPageReload - was current page reloaded.
  * @param postEvent - Bridge postEvent function
  */
-export function createClosingBehavior(postEvent: PostEvent): ClosingBehaviour {
-  const { isConfirmationNeeded = false } = getStorageValue('closing-behavior') || {};
+export function createClosingBehavior(
+  isPageReload: boolean,
+  postEvent: PostEvent,
+): ClosingBehaviour {
+  const { isConfirmationNeeded = false } = isPageReload ? getStorageValue('closing-behavior') || {} : {};
 
   const component = new ClosingBehaviour(isConfirmationNeeded, postEvent);
 

package/src/init/creators/createMainButton.ts

@@ -8,11 +8,13 @@ import { getStorageValue, saveStorageValue } from '../../storage.js';
 /**
  * Creates MainButton instance using last locally saved data also saving each state in
  * the storage.
+ * @param isPageReload - was current page reloaded.
  * @param backgroundColor - background color.
  * @param textColor - text color.
  * @param postEvent - Bridge postEvent function
  */
 export function createMainButton(
+  isPageReload: boolean,
   backgroundColor: RGB,
   textColor: RGB,
   postEvent: PostEvent,
@@ -24,7 +26,7 @@ export function createMainButton(
     isProgressVisible = false,
     textColor: stateTextColor = textColor,
     text = '',
-  } = getStorageValue('main-button') || {};
+  } = isPageReload ? getStorageValue('main-button') || {} : {};
 
   const component = new MainButton(
     stateBackgroundColor,

package/src/init/creators/{createSyncedThemeParams.ts → createThemeParams.ts}

@@ -1,12 +1,12 @@
-import { ThemeParams } from '../../components/index.js';
+import type { ThemeParams as ThemeParamsType } from '@tma.js/theme-params';
 
-import type { ThemeParamsType } from '../../theme-params.js';
+import { ThemeParams } from '../../components/index.js';
 
 /**
  * Creates synced instance of ThemeParams.
  * @param params - theme parameters.
  */
-export function createSyncedThemeParams(params: ThemeParamsType): ThemeParams {
+export function createThemeParams(params: ThemeParamsType): ThemeParams {
   const themeParams = new ThemeParams(params);
   ThemeParams.sync(themeParams);
 

package/src/init/creators/createViewport.ts

@@ -1,24 +1,28 @@
 import type { PostEvent } from '@tma.js/bridge';
+import type { Platform } from '@tma.js/launch-params';
 
 import { Viewport } from '../../components/index.js';
 
 import { getStorageValue, saveStorageValue } from '../../storage.js';
 
-import type { Platform } from '../../types.js';
-
 /**
  * Creates Viewport instance using last locally saved data also saving each state in
  * the storage.
+ * @param isPageReload - was current page reloaded.
  * @param platform - Telegram Web Apps platform name.
  * @param postEvent - Bridge postEvent function
  */
-export async function createViewport(platform: Platform, postEvent: PostEvent): Promise<Viewport> {
+export async function createViewport(
+  isPageReload: boolean,
+  platform: Platform,
+  postEvent: PostEvent,
+): Promise<Viewport> {
   const {
     height = window.innerHeight,
     stableHeight = window.innerHeight,
     width = window.innerWidth,
     isExpanded = false,
-  } = getStorageValue('viewport') || {};
+  } = isPageReload ? getStorageValue('viewport') || {} : {};
 
   const createSynced = () => {
     const viewport = new Viewport(height, width, stableHeight, isExpanded, postEvent);

package/src/init/creators/createWebApp.ts

@@ -1,15 +1,17 @@
 import type { RGB } from '@tma.js/colors';
 import type { PostEvent } from '@tma.js/bridge';
+import type { Platform } from '@tma.js/launch-params';
 
 import { WebApp } from '../../components/index.js';
 
 import { getStorageValue, saveStorageValue } from '../../storage.js';
 
-import type { CreateRequestIdFunc, Platform } from '../../types.js';
+import type { CreateRequestIdFunc } from '../../types.js';
 
 /**
  * Creates WebApp instance using last locally saved data also saving each state in
  * the storage.
+ * @param isPageReload - was current page reloaded.
  * @param backgroundColor - web app background color.
  * @param version - platform version.
  * @param platform - Telegram Web Apps platform name.
@@ -17,6 +19,7 @@ import type { CreateRequestIdFunc, Platform } from '../../types.js';
  * @param postEvent - Bridge postEvent function
  */
 export function createWebApp(
+  isPageReload: boolean,
   backgroundColor: RGB,
   version: string,
   platform: Platform,
@@ -26,7 +29,7 @@ export function createWebApp(
   const {
     backgroundColor: stateBackgroundColor = backgroundColor,
     headerColor = 'bg_color',
-  } = getStorageValue('web-app') || {};
+  } = isPageReload ? getStorageValue('web-app') || {} : {};
 
   const component = new WebApp(
     headerColor,

package/src/init/creators/index.ts

@@ -3,6 +3,6 @@ export * from './createClosingBehavior.js';
 export * from './createMainButton.js';
 export * from './createPostEvent.js';
 export * from './createRequestIdGenerator.js';
-export * from './createSyncedThemeParams.js';
+export * from './createThemeParams.js';
 export * from './createViewport.js';
 export * from './createWebApp.js';

package/src/init/init.ts

@@ -5,6 +5,12 @@ import {
   on,
 } from '@tma.js/bridge';
 import { withTimeout } from '@tma.js/utils';
+import type { LaunchParams } from '@tma.js/launch-params';
+import {
+  parse as parseLaunchParams,
+  saveToStorage as saveLaunchParamsToStorage,
+  retrieveFromStorage,
+} from '@tma.js/launch-params';
 
 import {
   CloudStorage,
@@ -13,7 +19,6 @@ import {
   Popup,
   QRScanner,
 } from '../components/index.js';
-import { parseLaunchParams, retrieveLaunchParams, type LaunchParams } from '../launch-params.js';
 import {
   bindThemeCSSVariables,
   bindViewportCSSVariables,
@@ -22,15 +27,48 @@ import {
 } from './css.js';
 import {
   createPostEvent,
-  createSyncedThemeParams,
+  createThemeParams,
   createBackButton,
   createMainButton,
   createViewport,
   createWebApp, createRequestIdGenerator, createClosingBehavior,
 } from './creators/index.js';
+import { retrieveLaunchParams } from '../launch-params.js';
 
 import type { InitOptions, InitResult } from './types.js';
 
+/**
+ * Returns true in case, current session was created due to native location reload.
+ */
+function isNativePageReload(): boolean {
+  return (
+    window
+      .performance
+      .getEntriesByType('navigation') as PerformanceNavigationTiming[]
+  ).some((entry) => entry.type === 'reload');
+}
+
+/**
+ * Returns true if current page was reloaded.
+ * @param launchParamsFromStorage - launch parameters from sessionStorage.
+ * @param currentLaunchParams - actual launch parameters.
+ */
+function computePageReload(
+  launchParamsFromStorage: LaunchParams | null,
+  currentLaunchParams: LaunchParams,
+): boolean {
+  // To check if page was reloaded, we should check if previous init data hash equals to the
+  // current one. Nevertheless, there are some cases, when init data is missing. For example,
+  // when app was launched via KeyboardButton. In this case we try to use the native way of
+  // checking if current page was reloaded (which could still return incorrect result).
+  // Issue: https://github.com/Telegram-Mini-Apps/issues/issues/12
+  if (!launchParamsFromStorage) {
+    return false;
+  }
+
+  return launchParamsFromStorage.initData?.hash === currentLaunchParams.initData?.hash;
+}
+
 /**
  * Represents actual init function.
  * @param options - init options.
@@ -43,29 +81,31 @@ async function actualInit(options: InitOptions = {}): Promise<InitResult> {
     acceptCustomStyles = acceptScrollbarStyle,
     targetOrigin,
     debug = false,
-    launchParams: launchParamsRaw,
+    launchParams: optionsLaunchParams = retrieveLaunchParams(),
   } = options;
 
-  // Set global debug mode.
+  // Set global settings.
   if (debug) {
     setDebug(debug);
   }
 
-  // Set global target origin.
   if (typeof targetOrigin === 'string') {
     setTargetOrigin(targetOrigin);
   }
 
-  // Get Web App launch params.
-  let launchParams: LaunchParams;
+  // Get Web App launch params and save them to session storage, so they will be accessible from
+  // anywhere.
+  const launchParamsFromStorage = retrieveFromStorage();
+  const launchParams = optionsLaunchParams instanceof URLSearchParams || typeof optionsLaunchParams === 'string'
+    ? parseLaunchParams(optionsLaunchParams)
+    : optionsLaunchParams;
 
-  if (launchParamsRaw) {
-    launchParams = launchParamsRaw instanceof URLSearchParams || typeof launchParamsRaw === 'string'
-      ? parseLaunchParams(launchParamsRaw)
-      : launchParamsRaw;
-  } else {
-    launchParams = retrieveLaunchParams();
-  }
+  saveLaunchParamsToStorage(launchParams);
+
+  // Compute if page was reloaded. We will need it to decide if SDK components should be restored
+  // or created from scratch.
+  const isPageReload = isNativePageReload()
+    || computePageReload(launchParamsFromStorage, launchParams);
 
   const {
     initData,
@@ -82,8 +122,15 @@ async function actualInit(options: InitOptions = {}): Promise<InitResult> {
 
   const createRequestId = createRequestIdGenerator();
   const postEvent = createPostEvent(checkCompat, version);
-  const themeParams = createSyncedThemeParams(lpThemeParams);
-  const webApp = createWebApp(backgroundColor, version, platform, createRequestId, postEvent);
+  const themeParams = createThemeParams(lpThemeParams);
+  const webApp = createWebApp(
+    isPageReload,
+    backgroundColor,
+    version,
+    platform,
+    createRequestId,
+    postEvent,
+  );
 
   const {
     themeParams: createThemeParamsCSSVars,
@@ -99,7 +146,7 @@ async function actualInit(options: InitOptions = {}): Promise<InitResult> {
     bindThemeCSSVariables(themeParams);
   }
 
-  const viewport = await createViewport(platform, postEvent);
+  const viewport = await createViewport(isPageReload, platform, postEvent);
 
   // Apply viewport CSS variables.
   if (createViewportCSSVars) {
@@ -128,11 +175,11 @@ async function actualInit(options: InitOptions = {}): Promise<InitResult> {
   }
 
   const result: InitResult = {
-    backButton: createBackButton(version, postEvent),
-    closingBehavior: createClosingBehavior(postEvent),
+    backButton: createBackButton(isPageReload, version, postEvent),
+    closingBehavior: createClosingBehavior(isPageReload, postEvent),
     cloudStorage: new CloudStorage(version, createRequestId, postEvent),
     haptic: new HapticFeedback(version, postEvent),
-    mainButton: createMainButton(buttonColor, buttonTextColor, postEvent),
+    mainButton: createMainButton(isPageReload, buttonColor, buttonTextColor, postEvent),
     popup: new Popup(version, postEvent),
     postEvent,
     qrScanner: new QRScanner(version, postEvent),

package/src/init/types.ts

@@ -1,4 +1,5 @@
 import type { PostEvent } from '@tma.js/bridge';
+import type { LaunchParams } from '@tma.js/launch-params';
 
 import type {
   BackButton,
@@ -13,9 +14,8 @@ import type {
   Viewport,
   WebApp,
 } from '../components/index.js';
-import type { LaunchParams } from '../launch-params.js';
 
-export type InitResult = {
+export interface InitResult {
   backButton: BackButton;
   closingBehavior: ClosingBehaviour;
   cloudStorage: CloudStorage;
@@ -29,9 +29,9 @@ export type InitResult = {
   themeParams: ThemeParams;
   viewport: Viewport;
   webApp: WebApp;
-};
+}
 
-export type InitCSSVarsSpecificOption = {
+export interface InitCSSVarsSpecificOption {
   /**
    * Enables theme parameters CSS variables:
    * - `--tg-theme-bg-color`
@@ -63,7 +63,7 @@ export type InitCSSVarsSpecificOption = {
    * @see bindWebAppVariables
    */
   webApp?: true;
-};
+}
 
 export type InitCSSVarsOption = boolean | InitCSSVarsSpecificOption;
 

package/src/launch-params.ts

@@ -1,70 +1,29 @@
-import { searchParams, string } from '@tma.js/parsing';
-import { initData, type InitData } from '@tma.js/init-data';
-
-import { parseThemeParams, type ThemeParamsType } from './theme-params.js';
-import { saveStorageValue, getStorageValue } from './storage.js';
-
-import type { Platform } from './types.js';
-
-export interface LaunchParams {
-  version: string;
-  initData?: InitData;
-  initDataRaw?: string;
-  platform: Platform;
-  themeParams: ThemeParamsType;
-}
-
-const launchParamsParser = searchParams<LaunchParams>({
-  version: { type: string(), from: 'tgWebAppVersion' },
-  initData: { type: initData.optional(), from: 'tgWebAppData' },
-  initDataRaw: { type: string().optional(), from: 'tgWebAppData' },
-  platform: { type: string(), from: 'tgWebAppPlatform' },
-  themeParams: { type: parseThemeParams, from: 'tgWebAppThemeParams' },
-});
-
-/**
- * Parses query parameters as launch parameters.
- * @param query - query parameters presented as string or URLSearchParams
- * instance.
- */
-export function parseLaunchParams(query: string | URLSearchParams): LaunchParams {
-  return launchParamsParser.parse(query);
-}
+import { parse, retrieveFromStorage } from '@tma.js/launch-params';
+import type { LaunchParams } from '@tma.js/launch-params';
 
 /**
- * Extracts launch params from the current environment.
+ * Attempts to extract launch params from window.location.hash. In case, window.location.hash
+ * lacks of valid data, function attempts to extract launch params from the sessionStorage.
  */
 export function retrieveLaunchParams(): LaunchParams {
-  const errors: string[] = [];
+  let error: unknown | undefined;
 
-  // Try to extract Web App data from hash. This block of code  covers usual flow, when
+  // Try to extract Mini App data from hash. This block of code  covers usual flow, when
   // application was firstly opened by the user and its hash always contains required parameters.
   try {
-    const launchParamsRaw = window.location.hash.slice(1);
-    const launchParamsParsed = parseLaunchParams(launchParamsRaw);
-
-    // Previous line of code worked fine. Then, we can save taken launch params raw value.
-    saveStorageValue('launch-params', launchParamsRaw);
-
-    return launchParamsParsed;
+    return parse(window.location.hash.slice(1));
   } catch (e) {
-    errors.push(e instanceof Error ? e.message : 'unknown error');
+    error = e;
   }
 
-  // Web Apps allows reloading current page. In this case, window.location.reload() will be
+  // Mini Apps allows reloading current page. In this case, window.location.reload() will be
   // called which means, that init will be called again. As the result, current window
-  // location will lose Web App data. To solve this problem, we are extracting launch
+  // location will lose Mini App data. To solve this problem, we are extracting launch
   // params saved previously.
-  try {
-    const launchParamsRaw = getStorageValue('launch-params');
-    if (launchParamsRaw) {
-      return parseLaunchParams(launchParamsRaw);
-    }
-
-    errors.push('Launch params are missing in local storage');
-  } catch (e) {
-    errors.push(e instanceof Error ? e.message : 'unknown error');
+  const fromStorage = retrieveFromStorage();
+  if (fromStorage) {
+    return fromStorage;
   }
 
-  throw new Error(`Unable to extract launch params. Errors: "${errors.join('", "')}"`);
+  throw new Error('Unable to extract launch params', { cause: error });
 }

package/src/storage.ts

@@ -29,7 +29,6 @@ interface StorageParams {
     backgroundColor: RGB;
     headerColor: HeaderColorKey | RGB;
   };
-  'launch-params': string;
 }
 
 /**
@@ -42,7 +41,7 @@ type StorageKey = keyof StorageParams;
  * @param key - session storage key.
  */
 function formatKey(key: StorageKey): string {
-  return `telegram-web-apps-${key}`;
+  return `telegram-mini-apps-${key}`;
 }
 
 /**

package/src/types.ts

@@ -7,21 +7,6 @@ export type PostEvent = BridgePostEvent;
  */
 export type ColorScheme = 'dark' | 'light';
 
-/**
- * Native Telegram application identifier.
- */
-export type Platform =
-  | 'android'
-  | 'android_x'
-  | 'ios'
-  | 'macos'
-  | 'tdesktop'
-  | 'web'
-  | 'weba'
-  | 'unigram'
-  | 'unknown'
-  | string;
-
 /**
  * Function which generates unique request identifiers.
  */

package/dist/dts/init/creators/createSyncedThemeParams.d.ts

@@ -1,7 +0,0 @@
-import { ThemeParams } from '../../components/index.js';
-import type { ThemeParamsType } from '../../theme-params.js';
-/**
- * Creates synced instance of ThemeParams.
- * @param params - theme parameters.
- */
-export declare function createSyncedThemeParams(params: ThemeParamsType): ThemeParams;

package/dist/dts/theme-params.d.ts

@@ -1,18 +0,0 @@
-import type { RGB } from '@tma.js/colors';
-/**
- * Application theme parameters. Defines palette used by the Telegram application.
- */
-export interface ThemeParamsType {
-    backgroundColor?: RGB;
-    buttonColor?: RGB;
-    buttonTextColor?: RGB;
-    hintColor?: RGB;
-    linkColor?: RGB;
-    secondaryBackgroundColor?: RGB;
-    textColor?: RGB;
-}
-/**
- * Parses incoming value as theme parameters.
- * @param value - value to parse.
- */
-export declare function parseThemeParams(value: unknown): ThemeParamsType;

package/src/theme-params.ts

@@ -1,34 +0,0 @@
-import { json, rgb } from '@tma.js/parsing';
-
-import type { RGB } from '@tma.js/colors';
-
-/**
- * Application theme parameters. Defines palette used by the Telegram application.
- */
-export interface ThemeParamsType {
-  backgroundColor?: RGB;
-  buttonColor?: RGB;
-  buttonTextColor?: RGB;
-  hintColor?: RGB;
-  linkColor?: RGB;
-  secondaryBackgroundColor?: RGB;
-  textColor?: RGB;
-}
-
-const themeParamsParser = json<ThemeParamsType>({
-  backgroundColor: { type: rgb().optional(), from: 'bg_color' },
-  buttonColor: { type: rgb().optional(), from: 'button_color' },
-  buttonTextColor: { type: rgb().optional(), from: 'button_text_color' },
-  hintColor: { type: rgb().optional(), from: 'hint_color' },
-  linkColor: { type: rgb().optional(), from: 'link_color' },
-  textColor: { type: rgb().optional(), from: 'text_color' },
-  secondaryBackgroundColor: { type: rgb().optional(), from: 'secondary_bg_color' },
-});
-
-/**
- * Parses incoming value as theme parameters.
- * @param value - value to parse.
- */
-export function parseThemeParams(value: unknown): ThemeParamsType {
-  return themeParamsParser.parse(value);
-}