@tma.js/sdk 0.13.2 → 1.0.0

package/src/event-emitter/EventEmitter.ts

@@ -0,0 +1,146 @@
+import type {
+  AnySubscribeListener,
+  EmptyEventName,
+  EventListener, EventName,
+  EventParams, NonEmptyEventName, RemoveEventListener,
+} from './types.js';
+
+type AddedEventListener = [listener: EventListener<any>, once: boolean];
+
+/**
+ * Opinionated event emitter implementation.
+ */
+export class EventEmitter<Schema> {
+  private readonly listeners: Map<string, AddedEventListener[]> = new Map();
+
+  private readonly subscribeListeners: AnySubscribeListener<Schema>[] = [];
+
+  /**
+   * Adds specified event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   * @param once - should listener called only once.
+   */
+  private addListener<E extends EventName<Schema>>(
+    event: E,
+    listener: EventListener<Schema[E]>,
+    once: boolean,
+  ): RemoveEventListener {
+    let listeners = this.listeners.get(event);
+    if (!listeners) {
+      listeners = [];
+      this.listeners.set(event, listeners);
+    }
+
+    listeners.push([listener, once]);
+
+    return () => this.off(event, listener);
+  }
+
+  /**
+   * Emits known event which has no parameters.
+   * @param event - event name.
+   */
+  emit<E extends EmptyEventName<Schema>>(event: E): void;
+
+  /**
+   * Emits known event which has parameters.
+   * @param event - event name.
+   * @param args - list of event listener arguments.
+   */
+  emit<E extends NonEmptyEventName<Schema>>(
+    event: E,
+    ...args: EventParams<Schema[E]>
+  ): void;
+
+  emit(event: EventName<Schema>, ...args: any[]): void {
+    this.subscribeListeners.forEach((l) => (l as any)(event, ...args));
+
+    const listeners = this.listeners.get(event);
+    if (!listeners) {
+      return;
+    }
+
+    listeners.forEach(([listener, once], idx) => {
+      listener(...args);
+      if (once) {
+        listeners.splice(idx, 1);
+      }
+    });
+  }
+
+  /**
+   * Adds event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   * @returns Function to remove event listener.
+   */
+  on<E extends EventName<Schema>>(
+    event: E,
+    listener: EventListener<Schema[E]>,
+  ): RemoveEventListener {
+    return this.addListener(event, listener, false);
+  }
+
+  /**
+   * Adds event listener following the logic, described in `on` method, but calls specified
+   * listener only once, removing it after.
+   * @param event - event name.
+   * @param listener - event listener.
+   * @returns Function to remove event listener.
+   * @see on
+   */
+  once<E extends EventName<Schema>>(
+    event: E,
+    listener: EventListener<Schema[E]>,
+  ): RemoveEventListener {
+    return this.addListener(event, listener, true);
+  }
+
+  /**
+   * Removes event listener. In case, specified listener was bound several times, it removes
+   * only a single one.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  off<E extends EventName<Schema>>(event: E, listener: EventListener<Schema[E]>): void {
+    const listeners = this.listeners.get(event);
+    if (!listeners) {
+      return;
+    }
+
+    for (let i = 0; i < listeners.length; i += 1) {
+      if (listener === listeners[i][0]) {
+        listeners.splice(i, 1);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Adds event listener to all events.
+   * @param listener - events listener.
+   * @returns Function to remove event listener.
+   * @see on
+   * @see once
+   */
+  subscribe(listener: AnySubscribeListener<Schema>): RemoveEventListener {
+    this.subscribeListeners.push(listener);
+    return () => this.unsubscribe(listener);
+  }
+
+  /**
+   * Removes global event listener. In case, specified listener was bound several times, it removes
+   * only a single one.
+   * @param listener - events listener.
+   * @returns Function to remove event listener.
+   */
+  unsubscribe(listener: AnySubscribeListener<Schema>): void {
+    for (let i = 0; i < this.subscribeListeners.length; i += 1) {
+      if (this.subscribeListeners[i] === listener) {
+        this.subscribeListeners.splice(i, 1);
+        return;
+      }
+    }
+  }
+}

package/src/event-emitter/index.ts

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

package/src/event-emitter/types.ts

@@ -0,0 +1,60 @@
+import type { IsNever } from '~/types/index.js';
+
+/**
+ * Function accepting the list of passed arguments and returning nothing.
+ */
+type VoidFunc<Args extends any[] = []> = (...args: Args) => void;
+
+/**
+ * Accepts type assuming, it is responsible for describing event listener
+ * parameters. Covers following cases:
+ * 1. If function is passed, return its arguments.
+ * 2. If never or void is passed, return empty tuple.
+ * 3. If array is passed return this type.
+ * 4. Otherwise, return tuple with passed type.
+ */
+export type EventParams<Params> = Params extends any[]
+  ? Params
+  : Params extends (...args: any[]) => any
+    ? Parameters<Params>
+    : IsNever<Params> extends true
+      ? []
+      : Params extends void
+        ? []
+        : [Params];
+
+/**
+ * Returns function that represents event listener with specified
+ * list of parameters.
+ */
+export type EventListener<Params> = VoidFunc<EventParams<Params>>;
+
+/**
+ * Returns event names.
+ */
+export type EventName<Schema> = Extract<keyof Schema, string>;
+
+/**
+ * Returns event names which do not require any arguments.
+ */
+export type EmptyEventName<Schema> = {
+  [E in EventName<Schema>]: EventParams<Schema[E]> extends [] ? E : never;
+}[EventName<Schema>];
+
+/**
+ * Returns event names which require arguments.
+ */
+export type NonEmptyEventName<Schema> =
+  Exclude<EventName<Schema>, EmptyEventName<Schema>>;
+
+/**
+ * Represents any listener, which could be used in EventEmitter.subscribe.
+ */
+export type AnySubscribeListener<Schema> = {
+  [E in keyof Schema]: (event: E, ...args: EventParams<Schema[E]>) => void;
+}[keyof Schema];
+
+/**
+ * Function which removes event listener.
+ */
+export type RemoveEventListener = () => void;

package/src/globals.ts

@@ -0,0 +1,38 @@
+import { Logger } from '~/logger/index.js';
+
+let currentTargetOrigin = 'https://web.telegram.org';
+
+export const logger = new Logger('[SDK]', false);
+
+/**
+ * Sets new debug mode. Enabling debug mode leads to printing
+ * additional messages in console, related to the processes
+ * inside the package.
+ * @param value - should debug mode be enabled.
+ */
+export function setDebug(value: boolean): void {
+  if (value) {
+    logger.enable();
+    return;
+  }
+  logger.disable();
+}
+
+/**
+ * Sets new global targetOrigin, used by `postEvent` method.
+ * Default value is "https://web.telegram.org". You don't need to
+ * use this method until you know what you are doing.
+ *
+ * This method could be used for test purposes.
+ * @param value - new target origin.
+ */
+export function setTargetOrigin(value: string): void {
+  currentTargetOrigin = value;
+}
+
+/**
+ * Returns current global target origin.
+ */
+export function targetOrigin(): string {
+  return currentTargetOrigin;
+}

package/src/{components/HapticFeedback → haptic-feedback}/HapticFeedback.ts

@@ -1,12 +1,14 @@
-import type { Version } from '@tma.js/utils';
 import {
-  postEvent as defaultPostEvent,
-  type PostEvent,
   type ImpactHapticFeedbackStyle,
   type NotificationHapticFeedbackType,
-} from '@tma.js/bridge';
-
-import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+  type PostEvent,
+  postEvent as defaultPostEvent,
+} from '~/bridge/index.js';
+import {
+  createSupportsFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
 
 /**
  * Class which controls haptic feedback. It allows calling different types of
@@ -14,7 +16,10 @@ import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
  * application.
  */
 export class HapticFeedback {
-  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+  constructor(
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
     this.supports = createSupportsFunc(version, {
       impactOccurred: 'web_app_trigger_haptic_feedback',
       notificationOccurred: 'web_app_trigger_haptic_feedback',
@@ -28,7 +33,10 @@ export class HapticFeedback {
    * @param style - impact style.
    */
   impactOccurred(style: ImpactHapticFeedbackStyle): void {
-    this.postEvent('web_app_trigger_haptic_feedback', { type: 'impact', impact_style: style });
+    this.postEvent('web_app_trigger_haptic_feedback', {
+      type: 'impact',
+      impact_style: style,
+    });
   }
 
   /**

package/src/index.ts

@@ -1,6 +1,171 @@
-export * from './components/index.js';
-export * from './errors/index.js';
-export * from './init/index.js';
-export * from './env.js';
-export * from './types.js';
-export * from './url.js';
+export {
+  BackButton,
+  type BackButtonEventName,
+  type BackButtonEventListener,
+} from './back-button/index.js';
+export {
+  createPostEvent,
+  isIframe,
+  on,
+  off,
+  once,
+  postEvent,
+  request,
+  subscribe,
+  unsubscribe,
+  MethodUnsupportedError,
+  ParameterUnsupportedError,
+  type HeaderColorKey,
+  type InvoiceStatus,
+  type ImpactHapticFeedbackStyle,
+  type MiniAppsMethodName,
+  type MiniAppsEventName,
+  type MiniAppsEventParams,
+  type MiniAppsEventListener,
+  type MiniAppsGlobalEventListener,
+  type MiniAppsEmptyMethodName,
+  type MiniAppsMethodAcceptParams,
+  type MiniAppsMethodParams,
+  type MiniAppsNonEmptyMethodName,
+  type MiniAppsMethods,
+  type MiniAppsEventEmitter,
+  type MiniAppsEventHasParams,
+  type MiniAppsEvents,
+  type NotificationHapticFeedbackType,
+  type PhoneRequestedStatus,
+  type PostEvent,
+  type RequestOptions,
+  type SwitchInlineQueryChatType,
+  type WriteAccessRequestedStatus,
+} from './bridge/index.js';
+export {
+  classNames,
+  mergeClassNames,
+} from './classnames/index.js';
+export {
+  ClosingBehavior,
+  type ClosingBehaviorEventListener,
+  type ClosingBehaviorEventName,
+  type ClosingBehaviorEvents,
+} from './closing-behavior/index.js';
+export { CloudStorage } from './cloud-storage/index.js';
+export {
+  isRGB,
+  isRGBShort,
+  isColorDark,
+  toRGB,
+  type RGB,
+  type RGBShort,
+} from './colors/index.js';
+export { HapticFeedback } from './haptic-feedback/index.js';
+export {
+  init,
+  type InitOptions,
+  type InitResult,
+} from './init/index.js';
+export {
+  chatParser,
+  InitData,
+  initDataParser,
+  parseInitData,
+  userParser,
+  type Chat,
+  type ChatType,
+  type InitDataParsed,
+  type User,
+} from './init-data/index.js';
+export {
+  Invoice,
+  type InvoiceEvents,
+  type InvoiceEventListener,
+  type InvoiceEventName,
+} from './invoice/index.js';
+export {
+  launchParamsParser,
+  parseLaunchParams,
+  retrieveLaunchData,
+  serializeLaunchParams,
+  type LaunchParams,
+  type LaunchData,
+} from './launch-params/index.js';
+export {
+  MainButton,
+  type MainButtonParams,
+  type MainButtonProps,
+  type MainButtonEvents,
+  type MainButtonEventName,
+  type MainButtonEventListener,
+} from './main-button/index.js';
+export {
+  MiniApp,
+  type MiniAppHeaderColor,
+  type MiniAppEventName,
+  type MiniAppEventListener,
+  type MiniAppEvents,
+  type MiniAppProps,
+} from './mini-app/index.js';
+export {
+  isTMA,
+  isRecord,
+} from './misc/index.js';
+export {
+  getHash,
+  HashNavigator,
+  Navigator,
+  type NavigationEntry,
+  type NavigatorConEntry,
+  type NavigatorOptions,
+  type HashNavigatorOptions,
+  type HashNavigatorEventsMap,
+  type HashNavigatorEventListener,
+  type HashNavigatorEventName,
+} from './navigation/index.js';
+export {
+  Popup,
+  type PopupEventName,
+  type PopupEventListener,
+  type PopupEvents,
+  type OpenPopupOptions,
+  type OpenPopupOptionsButton,
+} from './popup/index.js';
+export {
+  QRScanner,
+  type QRScannerEventListener,
+  type QRScannerEventName,
+  type QRScannerEvents,
+} from './qr-scanner/index.js';
+export { supports } from './supports/index.js';
+export {
+  parseThemeParams,
+  requestThemeParams,
+  serializeThemeParams,
+  themeParamsParser,
+  ThemeParams,
+  type ThemeParamsEventListener,
+  type ThemeParamsEventName,
+  type ThemeParamsEvents,
+  type ThemeParamsKey,
+  type ThemeParamsParsed,
+} from './theme-params/index.js';
+export type {
+  RequestId,
+  CreateRequestIdFunc,
+} from './types/index.js';
+export { Utils } from './utils/index.js';
+export {
+  compareVersions,
+  type Version,
+} from './version/index.js';
+export {
+  requestViewport,
+  Viewport,
+  type RequestViewportResult,
+  type ViewportProps,
+  type ViewportEventName,
+  type ViewportEventListener,
+  type ViewportEvents,
+} from './viewport/index.js';
+export {
+  setTargetOrigin,
+  setDebug,
+} from './globals.js';

package/src/init/catchCustomStyles.ts

@@ -0,0 +1,17 @@
+import { on } from '~/bridge/index.js';
+
+/**
+ * Creates style html element which contains styles sent from the Telegram application.
+ */
+export function catchCustomStyles(): void {
+  const element = document.createElement('style');
+  element.id = 'telegram-custom-styles';
+  document.head.appendChild(element);
+
+  on('set_custom_style', (html) => {
+    // It is safe to use innerHTML here as long as style tag has a special behavior related
+    // to the specified content. In case, any script will be passed here, it will not be
+    // executed.
+    element.innerHTML = html;
+  });
+}

package/src/init/creators/createBackButton.ts

@@ -1,8 +1,6 @@
-import type { PostEvent } from '@tma.js/bridge';
-
-import { BackButton } from '../../components/index.js';
-
-import { getStorageValue, saveStorageValue } from '../../storage.js';
+import { BackButton } from '~/back-button/index.js';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import type { PostEvent } from '~/bridge/index.js';
 
 /**
  * Creates BackButton instance using last locally saved data also saving each state in
@@ -19,7 +17,7 @@ export function createBackButton(
   const { isVisible = false } = isPageReload ? getStorageValue('back-button') || {} : {};
   const component = new BackButton(isVisible, version, postEvent);
 
-  component.on('isVisibleChanged', () => {
+  component.on('change', () => {
     saveStorageValue('back-button', { isVisible: component.isVisible });
   });
 

package/src/init/creators/createClosingBehavior.ts

@@ -1,8 +1,6 @@
-import type { PostEvent } from '@tma.js/bridge';
-
-import { ClosingBehaviour } from '../../components/index.js';
-
-import { getStorageValue, saveStorageValue } from '../../storage.js';
+import { ClosingBehavior } from '~/closing-behavior/index.js';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import type { PostEvent } from '~/bridge/index.js';
 
 /**
  * Creates ClosingBehaviour instance using last locally saved data also saving each state in
@@ -13,12 +11,12 @@ import { getStorageValue, saveStorageValue } from '../../storage.js';
 export function createClosingBehavior(
   isPageReload: boolean,
   postEvent: PostEvent,
-): ClosingBehaviour {
+): ClosingBehavior {
   const { isConfirmationNeeded = false } = isPageReload ? getStorageValue('closing-behavior') || {} : {};
 
-  const component = new ClosingBehaviour(isConfirmationNeeded, postEvent);
+  const component = new ClosingBehavior(isConfirmationNeeded, postEvent);
 
-  component.on('isConfirmationNeededChanged', () => saveStorageValue('closing-behavior', {
+  component.on('change', () => saveStorageValue('closing-behavior', {
     isConfirmationNeeded: component.isConfirmationNeeded,
   }));
 

package/src/init/creators/createMainButton.ts

@@ -1,9 +1,7 @@
-import type { RGB } from '@tma.js/colors';
-import type { PostEvent } from '@tma.js/bridge';
-
-import { MainButton } from '../../components/index.js';
-
-import { getStorageValue, saveStorageValue } from '../../storage.js';
+import { MainButton } from '~/main-button/index.js';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import type { PostEvent } from '~/bridge/index.js';
+import type { RGB } from '~/colors/index.js';
 
 /**
  * Creates MainButton instance using last locally saved data also saving each state in
@@ -23,36 +21,31 @@ export function createMainButton(
     backgroundColor: stateBackgroundColor = backgroundColor,
     isEnabled = false,
     isVisible = false,
-    isProgressVisible = false,
+    isLoaderVisible = false,
     textColor: stateTextColor = textColor,
     text = '',
   } = isPageReload ? getStorageValue('main-button') || {} : {};
 
-  const component = new MainButton(
-    stateBackgroundColor,
+  const component = new MainButton({
+    backgroundColor: stateBackgroundColor,
     isEnabled,
+    isLoaderVisible,
     isVisible,
-    isProgressVisible,
-    text,
-    stateTextColor,
     postEvent,
-  );
+    text,
+    textColor: stateTextColor,
+  });
 
   const saveState = () => saveStorageValue('main-button', {
     backgroundColor: component.backgroundColor,
     isEnabled: component.isEnabled,
+    isLoaderVisible: component.isLoaderVisible,
     isVisible: component.isVisible,
-    isProgressVisible: component.isProgressVisible,
     text: component.text,
     textColor: component.textColor,
   });
 
-  component.on('backgroundColorChanged', saveState);
-  component.on('isEnabledChanged', saveState);
-  component.on('isVisibleChanged', saveState);
-  component.on('isProgressVisibleChanged', saveState);
-  component.on('textColorChanged', saveState);
-  component.on('textChanged', saveState);
+  component.on('change', saveState);
 
   return component;
 }

package/src/init/creators/createMiniApp.ts

@@ -0,0 +1,44 @@
+import { MiniApp } from '~/mini-app/index.js';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import type { PostEvent } from '~/bridge/index.js';
+import type { RGB } from '~/colors/index.js';
+import type { Version } from '~/version/index.js';
+
+/**
+ * Creates MiniApp 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 botInline - is Mini App launched in inline mode.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createMiniApp(
+  isPageReload: boolean,
+  backgroundColor: RGB,
+  version: Version,
+  botInline: boolean,
+  postEvent: PostEvent,
+): MiniApp {
+  const {
+    backgroundColor: stateBackgroundColor = backgroundColor,
+    headerColor = 'bg_color',
+  } = isPageReload ? getStorageValue('mini-app') || {} : {};
+
+  const component = new MiniApp({
+    headerColor,
+    backgroundColor: stateBackgroundColor,
+    version,
+    botInline,
+    postEvent,
+  });
+
+  const saveState = () => saveStorageValue('mini-app', {
+    backgroundColor: component.backgroundColor,
+    headerColor: component.headerColor,
+  });
+
+  component.on('change', saveState);
+
+  return component;
+}

package/src/init/creators/createRequestIdGenerator.ts

@@ -1,4 +1,4 @@
-import type { CreateRequestIdFunc } from '../../types.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
 
 /**
  * Creates function which generated request identifiers.

package/src/init/creators/createThemeParams.ts

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