@tma.js/sdk 0.11.3

package/src/init/css.ts

@@ -0,0 +1,166 @@
+import type { RGB } from '@tma.js/colors';
+
+import type { ThemeParams, WebApp, Viewport } from '../components/index.js';
+import type { InitCSSVarsOption, InitCSSVarsSpecificOption } from './types.js';
+
+/**
+ * Sets CSS variable.
+ * @param name - variable name.
+ * @param value - variable value.
+ */
+function setVariable(name: string, value: string): void {
+  document.documentElement.style.setProperty(name, value);
+}
+
+/**
+ * Sets new CSS color variable in case, its value is not null.
+ * @param name - variable name.
+ * @param color - variable value.
+ */
+function setColorVariable(name: string, color: RGB | null): void {
+  if (color === null) {
+    return;
+  }
+  setVariable(name, color);
+}
+
+/**
+ * Sets new CSS variable which value is amount of pixels.
+ * @param name - variable name.
+ * @param size - variable value.
+ */
+function setSizeVariable(name: string, size: number) {
+  setVariable(name, `${size}px`);
+}
+
+/**
+ * Creates CSS variables based on theme parameters.
+ * @param themeParams - ThemeParams instance.
+ */
+function createThemeVariables(themeParams: ThemeParams): void {
+  const {
+    backgroundColor,
+    buttonTextColor,
+    secondaryBackgroundColor,
+    hintColor,
+    buttonColor,
+    linkColor,
+    textColor,
+  } = themeParams;
+
+  setColorVariable('--tg-theme-bg-color', backgroundColor);
+  setColorVariable('--tg-theme-button-color', buttonColor);
+  setColorVariable('--tg-theme-button-text-color', buttonTextColor);
+  setColorVariable('--tg-theme-hint-color', hintColor);
+  setColorVariable('--tg-theme-link-color', linkColor);
+  setColorVariable('--tg-theme-secondary-bg-color', secondaryBackgroundColor);
+  setColorVariable('--tg-theme-text-color', textColor);
+}
+
+/**
+ * Creates CSS variables based on Web App background and header colors with
+ * theme parameters.
+ * @param webApp - WebApp instance.
+ * @param themeParams - theme parameters.
+ */
+function createWebAppVariables(webApp: WebApp, themeParams: ThemeParams): void {
+  const { backgroundColor, secondaryBackgroundColor } = themeParams;
+  const { backgroundColor: webAppBackgroundColor, headerColor } = webApp;
+
+  setColorVariable('--tg-bg-color', webAppBackgroundColor);
+  setColorVariable('--tg-header-color', headerColor === 'bg_color' ? backgroundColor : secondaryBackgroundColor);
+}
+
+/**
+ * Creates CSS variables connected with theme parameters.
+ *
+ * Created variables:
+ * - `--tg-theme-bg-color`
+ * - `--tg-theme-button-color`
+ * - `--tg-theme-button-text-color`
+ * - `--tg-theme-hint-color`
+ * - `--tg-theme-link-color`
+ * - `--tg-theme-secondary-bg-color`
+ * - `--tg-theme-text-color`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed ThemeParams instance.
+ *
+ * @param themeParams - ThemeParams instance.
+ */
+export function bindThemeCSSVariables(themeParams: ThemeParams): void {
+  const actualize = () => createThemeVariables(themeParams);
+
+  themeParams.on('changed', actualize);
+
+  actualize();
+}
+
+/**
+ * Creates CSS variables connected with WebApp background and header colors based on
+ * passed WebApp and ThemeParams instances.
+ *
+ * Created variables:
+ * - `--tg-bg-color`
+ * - `--tg-header-color`
+ *
+ * Variables are being automatically updated in case, corresponding properties are updating.
+ *
+ * @param webApp - WebApp instance.
+ * @param themeParams - ThemeParams instance.
+ */
+export function bindWebAppVariables(webApp: WebApp, themeParams: ThemeParams): void {
+  const actualize = () => createWebAppVariables(webApp, themeParams);
+
+  themeParams.on('changed', actualize);
+  webApp.on('backgroundColorChanged', actualize);
+  webApp.on('headerColorChanged', actualize);
+
+  actualize();
+}
+
+/**
+ * Accepts Viewport instance and sets CSS variables connected with viewport
+ * sizes.
+ *
+ * Be careful using this function as long as it can impact application
+ * performance. Viewport size is changing rather often, this makes CSS
+ * variables update, which leads to possible layout redraw.
+ *
+ * Variables:
+ * - `--tg-viewport-height`
+ * - `--tg-viewport-stable-height`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed Viewport instance.
+ *
+ * @param viewport - Viewport instance.
+ */
+export function bindViewportCSSVariables(viewport: Viewport): void {
+  const setHeight = () => {
+    setSizeVariable('--tg-viewport-height', viewport.height);
+  };
+
+  const setStableHeight = () => {
+    setSizeVariable('--tg-viewport-stable-height', viewport.stableHeight);
+  };
+
+  viewport.on('heightChanged', setHeight);
+  viewport.on('stableHeightChanged', setStableHeight);
+
+  setHeight();
+  setStableHeight();
+}
+
+/**
+ * Converts init cssVars option to more narrow type.
+ * @param option - option value.
+ */
+export function parseCSSVarsOptions(option: InitCSSVarsOption): InitCSSVarsSpecificOption {
+  if (typeof option === 'boolean') {
+    return option
+      ? { themeParams: true, viewport: true, webApp: true }
+      : {};
+  }
+  return option;
+}

package/src/init/index.ts

@@ -0,0 +1,2 @@
+export * from './init.js';
+export * from './types.js';

package/src/init/init.ts

@@ -0,0 +1,160 @@
+import {
+  isIframe,
+  setDebug,
+  setTargetOrigin,
+  on,
+} from '@tma.js/bridge';
+import { withTimeout } from '@tma.js/utils';
+
+import {
+  CloudStorage,
+  HapticFeedback,
+  InitData,
+  Popup,
+  QRScanner,
+} from '../components/index.js';
+import { parseLaunchParams, retrieveLaunchParams, type LaunchParams } from '../launch-params.js';
+import {
+  bindThemeCSSVariables,
+  bindViewportCSSVariables,
+  bindWebAppVariables,
+  parseCSSVarsOptions,
+} from './css.js';
+import {
+  createPostEvent,
+  createSyncedThemeParams,
+  createBackButton,
+  createMainButton,
+  createViewport,
+  createWebApp, createRequestIdGenerator, createClosingBehavior,
+} from './creators/index.js';
+
+import type { InitOptions, InitResult } from './types.js';
+
+/**
+ * Represents actual init function.
+ * @param options - init options.
+ */
+async function actualInit(options: InitOptions = {}): Promise<InitResult> {
+  const {
+    checkCompat = true,
+    cssVars = false,
+    acceptScrollbarStyle = true,
+    acceptCustomStyles = acceptScrollbarStyle,
+    targetOrigin,
+    debug = false,
+    launchParams: launchParamsRaw,
+  } = options;
+
+  // Set global debug mode.
+  if (debug) {
+    setDebug(debug);
+  }
+
+  // Set global target origin.
+  if (typeof targetOrigin === 'string') {
+    setTargetOrigin(targetOrigin);
+  }
+
+  // Get Web App launch params.
+  let launchParams: LaunchParams;
+
+  if (launchParamsRaw) {
+    launchParams = launchParamsRaw instanceof URLSearchParams || typeof launchParamsRaw === 'string'
+      ? parseLaunchParams(launchParamsRaw)
+      : launchParamsRaw;
+  } else {
+    launchParams = retrieveLaunchParams();
+  }
+
+  const {
+    initData,
+    initDataRaw,
+    version,
+    platform,
+    themeParams: lpThemeParams,
+  } = launchParams;
+  const {
+    backgroundColor = '#ffffff',
+    buttonColor = '#000000',
+    buttonTextColor = '#ffffff',
+  } = lpThemeParams;
+
+  const createRequestId = createRequestIdGenerator();
+  const postEvent = createPostEvent(checkCompat, version);
+  const themeParams = createSyncedThemeParams(lpThemeParams);
+  const webApp = createWebApp(backgroundColor, version, platform, createRequestId, postEvent);
+
+  const {
+    themeParams: createThemeParamsCSSVars,
+    viewport: createViewportCSSVars,
+    webApp: createWebAppCSSVars,
+  } = parseCSSVarsOptions(cssVars);
+
+  if (createWebAppCSSVars) {
+    bindWebAppVariables(webApp, themeParams);
+  }
+
+  if (createThemeParamsCSSVars) {
+    bindThemeCSSVariables(themeParams);
+  }
+
+  const viewport = await createViewport(platform, postEvent);
+
+  // Apply viewport CSS variables.
+  if (createViewportCSSVars) {
+    bindViewportCSSVariables(viewport);
+  }
+
+  // In case, we are currently in iframe, it is required to listen to
+  // messages, coming from parent source to apply requested changes.
+  // The only one case, when current application was placed into iframe is
+  // web version of Telegram.
+  if (acceptCustomStyles && isIframe()) {
+    // Create special style element which is responsible for application
+    // style controlled by external app.
+    const styleElement = document.createElement('style');
+    styleElement.id = 'telegram-custom-styles';
+    document.head.appendChild(styleElement);
+
+    // Listen to custom style changes.
+    on('set_custom_style', (html) => {
+      styleElement.innerHTML = html;
+    });
+
+    // Notify Telegram, iframe is ready. This will result in sending style
+    // tag html from native application.
+    postEvent('iframe_ready');
+  }
+
+  const result: InitResult = {
+    backButton: createBackButton(version, postEvent),
+    closingBehavior: createClosingBehavior(postEvent),
+    cloudStorage: new CloudStorage(version, createRequestId, postEvent),
+    haptic: new HapticFeedback(version, postEvent),
+    mainButton: createMainButton(buttonColor, buttonTextColor, postEvent),
+    popup: new Popup(version, postEvent),
+    postEvent,
+    qrScanner: new QRScanner(version, postEvent),
+    themeParams,
+    viewport,
+    webApp,
+  };
+
+  // Init data could be missing in case, application was launched via InlineKeyboardButton.
+  if (initData !== undefined) {
+    const { authDate, hash, ...restInitData } = initData;
+    result.initData = new InitData(authDate, hash, restInitData);
+    result.initDataRaw = initDataRaw;
+  }
+
+  return result;
+}
+
+/**
+ * Initializes all SDK components.
+ * @param options - initialization options.
+ */
+export function init(options: InitOptions = {}): Promise<InitResult> {
+  return withTimeout(actualInit(options), options.timeout || 1000);
+}

package/src/init/types.ts

@@ -0,0 +1,133 @@
+import type { PostEvent } from '@tma.js/bridge';
+
+import type {
+  BackButton,
+  ClosingBehaviour,
+  CloudStorage,
+  HapticFeedback,
+  InitData,
+  MainButton,
+  Popup,
+  QRScanner,
+  ThemeParams,
+  Viewport,
+  WebApp,
+} from '../components/index.js';
+import type { LaunchParams } from '../launch-params.js';
+
+export type InitResult = {
+  backButton: BackButton;
+  closingBehavior: ClosingBehaviour;
+  cloudStorage: CloudStorage;
+  haptic: HapticFeedback;
+  initData?: InitData;
+  initDataRaw?: string;
+  mainButton: MainButton;
+  popup: Popup;
+  postEvent: PostEvent;
+  qrScanner: QRScanner;
+  themeParams: ThemeParams;
+  viewport: Viewport;
+  webApp: WebApp;
+};
+
+export type InitCSSVarsSpecificOption = {
+  /**
+   * Enables theme parameters CSS variables:
+   * - `--tg-theme-bg-color`
+   * - `--tg-theme-button-color`
+   * - `--tg-theme-button-text-color`
+   * - `--tg-theme-hint-color`
+   * - `--tg-theme-link-color`
+   * - `--tg-theme-secondary-bg-color`
+   * - `--tg-theme-text-color`
+   *
+   * @see bindThemeCSSVariables
+   */
+  themeParams?: true;
+
+  /**
+   * Enables viewport CSS variables:
+   * - `--tg-viewport-height`
+   * - `--tg-viewport-stable-height`
+   *
+   * @see bindViewportCSSVariables
+   */
+  viewport?: true;
+
+  /**
+   * Enables web app CSS variables:
+   * - `--tg-bg-color`
+   * - `--tg-header-color`
+   *
+   * @see bindWebAppVariables
+   */
+  webApp?: true;
+};
+
+export type InitCSSVarsOption = boolean | InitCSSVarsSpecificOption;
+
+export interface InitOptions {
+  /**
+   * @deprecated Use acceptCustomStyles
+   */
+  acceptScrollbarStyle?: boolean;
+
+  /**
+   * Should SDK accept styles sent from the Telegram web application.
+   * This option is only used in Web versions of Telegram.
+   *
+   * @default true
+   */
+  acceptCustomStyles?: boolean;
+
+  /**
+   * Should SDK throw an error in case, unsupported by current version of
+   * Web App method was called. It is highly recommended not to disable this
+   * feature as long as it helps developer to find issues related to usage
+   * of unsupported methods.
+   *
+   * @default true
+   */
+  checkCompat?: boolean;
+
+  /**
+   * Should SDK create global CSS variables related to current Telegram
+   * application colors.
+   *
+   * Possible values:
+   * - `false` - no CSS variables will be created.
+   * - `true` - all CSS variables will be created.
+   * - object - applies specific CSS variables.
+   *
+   * @default false
+   */
+  cssVars?: InitCSSVarsOption;
+
+  /**
+   * Enable debug mode.
+   *
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Launch parameters presented as query parameters or already parsed
+   * object. In case, this value is not specified, init
+   * function will try to retrieve launch parameters from window.location.hash
+   * via retrieveLaunchParams function.
+   */
+  launchParams?: string | URLSearchParams | LaunchParams;
+
+  /**
+   * Sets new targetOrigin, used by bridge's `postEvent` function.
+   * @see setTargetOrigin
+   */
+  targetOrigin?: string;
+
+  /**
+   * Initialization process timeout.
+   * @default 1000
+   */
+  timeout?: number;
+}

package/src/launch-params.ts

@@ -0,0 +1,70 @@
+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);
+}
+
+/**
+ * Extracts launch params from the current environment.
+ */
+export function retrieveLaunchParams(): LaunchParams {
+  const errors: string[] = [];
+
+  // Try to extract Web 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;
+  } catch (e) {
+    errors.push(e instanceof Error ? e.message : 'unknown error');
+  }
+
+  // Web 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
+  // 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');
+  }
+
+  throw new Error(`Unable to extract launch params. Errors: "${errors.join('", "')}"`);
+}

package/src/state/State.ts

@@ -0,0 +1,53 @@
+import type { EventEmitter } from '@tma.js/event-emitter';
+
+import type { StateEvents, StringKeys } from './types.js';
+
+/**
+ * Represents state which is observable via passed EventEmitter.
+ */
+export class State<S extends object> {
+  constructor(private readonly state: S, private readonly ee?: EventEmitter<StateEvents<S>>) {
+  }
+
+  private emit(key: string, value?: unknown) {
+    if (this.ee) {
+      (this.ee as any).emit(key, value);
+    }
+  }
+
+  private internalSet<K extends StringKeys<S>>(key: K, value: S[K]): boolean {
+    if (this.state[key] === value) {
+      return false;
+    }
+
+    this.state[key] = value;
+    this.emit(`${key}Changed`, value);
+
+    return true;
+  }
+
+  set<K extends StringKeys<S>>(key: K, value: S[K]): void;
+  set(state: Partial<S>): void;
+  set(keyOrState: any, value?: any): void {
+    let didChange = false;
+
+    if (typeof keyOrState === 'string') {
+      didChange = this.internalSet(keyOrState as any, value);
+    } else {
+      // eslint-disable-next-line
+      for (const key in keyOrState) {
+        if (this.internalSet(key as any, keyOrState[key])) {
+          didChange = true;
+        }
+      }
+    }
+
+    if (didChange) {
+      this.emit('changed');
+    }
+  }
+
+  get<K extends StringKeys<S>>(key: K): Readonly<S[K]> {
+    return this.state[key];
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,2 @@
+export * from './State.js';
+export * from './types.js';

package/src/state/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Computes state property changed event.
+ */
+export type PropChangedEvent<K extends string> = `${K}Changed`;
+
+/**
+ * Returns object string keys.
+ */
+export type StringKeys<T extends object> = Extract<keyof T, string>;
+
+/**
+ * Extracts state property type by its computed change event name.
+ */
+export type PropertyType<State extends object, Event extends string> = {
+  [Key in StringKeys<State>]: Event extends PropChangedEvent<Key> ? State[Key] : never;
+}[StringKeys<State>];
+
+/**
+ * Creates map, where key is event name which is used, when state property was changed.
+ * Value is according listener.
+ */
+export type PropChangedEventsMap<State extends object> = {
+  [Event in `${StringKeys<State>}Changed`]: (value: PropertyType<State, Event>) => void;
+};
+
+/**
+ * Creates map with all events emitted by state.
+ */
+export type StateEvents<State extends object> = PropChangedEventsMap<State> & {
+  /**
+   * Being called whenever any property was updated.
+   */
+  changed: () => void;
+};

package/src/storage.ts

@@ -0,0 +1,65 @@
+import type { HeaderColorKey } from '@tma.js/bridge';
+import type { RGB } from '@tma.js/colors';
+
+/**
+ * Describes storage keys and according values.
+ */
+interface StorageParams {
+  'back-button': {
+    isVisible: boolean
+  };
+  'closing-behavior': {
+    isConfirmationNeeded: boolean;
+  };
+  'main-button': {
+    backgroundColor: RGB;
+    isEnabled: boolean;
+    isVisible: boolean;
+    isProgressVisible: boolean;
+    text: string;
+    textColor: RGB;
+  };
+  viewport: {
+    height: number;
+    isExpanded: boolean;
+    stableHeight: number;
+    width: number;
+  };
+  'web-app': {
+    backgroundColor: RGB;
+    headerColor: HeaderColorKey | RGB;
+  };
+  'launch-params': string;
+}
+
+/**
+ * Key which could be used to store data in storage.
+ */
+type StorageKey = keyof StorageParams;
+
+/**
+ * Formats key which could be used during the communication with the storage.
+ * @param key - session storage key.
+ */
+function formatKey(key: StorageKey): string {
+  return `telegram-web-apps-${key}`;
+}
+
+/**
+ * Saves value in sessionStorage.
+ * @param key - storage key.
+ * @param value - storage value.
+ */
+export function saveStorageValue<K extends StorageKey>(key: K, value: StorageParams[K]): void {
+  sessionStorage.setItem(formatKey(key), JSON.stringify(value));
+}
+
+/**
+ * Extracts value from the sessionStorage.
+ * @param key - storage key.
+ */
+export function getStorageValue<K extends StorageKey>(key: K): StorageParams[K] | null {
+  const value = sessionStorage.getItem(formatKey(key));
+
+  return value ? JSON.parse(value) : null;
+}