@tma.js/sdk 0.11.3

package/src/components/WebApp/WebApp.ts

@@ -0,0 +1,310 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { compareVersions, type Version } from '@tma.js/utils';
+import { isRGB, isColorDark, type RGB } from '@tma.js/colors';
+import {
+  postEvent as defaultPostEvent,
+  supports,
+  request,
+  type PhoneRequestedStatus,
+  type WriteAccessRequestedStatus,
+  type InvoiceStatus,
+  type PostEvent,
+} from '@tma.js/bridge';
+
+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 { WebAppEvents, WebAppHeaderColor, WebAppState } from './types.js';
+
+/**
+ * Provides common Web Apps functionality not covered by other system
+ * components.
+ */
+export class WebApp {
+  private readonly ee = new EventEmitter<WebAppEvents>();
+
+  private readonly state: State<WebAppState>;
+
+  constructor(
+    headerColor: WebAppHeaderColor,
+    backgroundColor: RGB,
+    private readonly currentVersion: Version,
+    private readonly currentPlatform: Platform,
+    private readonly createRequestId: () => string,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({
+      backgroundColor,
+      headerColor,
+    }, this.ee);
+    this.supports = createSupportsFunc(currentVersion, {
+      openInvoice: 'web_app_open_invoice',
+      readTextFromClipboard: 'web_app_read_text_from_clipboard',
+      setHeaderColor: 'web_app_set_header_color',
+      setBackgroundColor: 'web_app_set_background_color',
+      requestPhoneAccess: 'web_app_request_phone',
+      requestWriteAccess: 'web_app_request_write_access',
+    });
+    this.supportsParam = createSupportsParamFunc(currentVersion, {
+      'setHeaderColor.color': ['web_app_set_header_color', 'color'],
+      'openLink.tryInstantView': ['web_app_open_link', 'try_instant_view'],
+    });
+  }
+
+  /**
+   * Returns current application background color.
+   */
+  get backgroundColor(): RGB {
+    return this.state.get('backgroundColor');
+  }
+
+  /**
+   * Returns current application color scheme. This value is
+   * computed based on the current background color.
+   */
+  get colorScheme(): ColorScheme {
+    return isColorDark(this.backgroundColor) ? 'dark' : 'light';
+  }
+
+  /**
+   * Closes the Web App.
+   */
+  close(): void {
+    this.postEvent('web_app_close');
+  }
+
+  /**
+   * Returns current application header color.
+   */
+  get headerColor(): WebAppHeaderColor {
+    return this.state.get('headerColor');
+  }
+
+  /**
+   * Returns true if passed version is more than or equal to current
+   * Web App version.
+   * @param version - compared version.
+   */
+  isVersionAtLeast(version: Version): boolean {
+    return compareVersions(version, this.version) >= 0;
+  }
+
+  /**
+   * Opens a link in an external browser. The Web App will not be closed.
+   *
+   * Note that this method can be called only in response to the user
+   * interaction with the Web App interface (e.g. click inside the Web App
+   * or on the main button).
+   * @param url - URL to be opened.
+   * @param tryInstantView
+   */
+  openLink(url: string, tryInstantView?: boolean): void {
+    const formattedUrl = formatURL(url);
+
+    // If method is not supported, we are doing it in legacy way.
+    if (!supports('web_app_open_link', this.version)) {
+      window.open(formattedUrl, '_blank');
+      return;
+    }
+
+    // Otherwise, do it normally.
+    return this.postEvent('web_app_open_link', {
+      url: formattedUrl,
+      ...(typeof tryInstantView === 'boolean' ? { try_instant_view: tryInstantView } : {}),
+    });
+  }
+
+  /**
+   * Opens a Telegram link inside Telegram app. The Web App will be closed.
+   * It expects passing link in full format, with hostname "t.me".
+   * @param url - URL to be opened.
+   * @throws {Error} URL has not allowed hostname.
+   */
+  openTelegramLink(url: string): void {
+    const { hostname, pathname, search } = new URL(formatURL(url));
+
+    if (hostname !== 't.me') {
+      throw new Error(`URL has not allowed hostname: ${hostname}. Only "t.me" is allowed`);
+    }
+
+    if (!supports('web_app_open_tg_link', this.version)) {
+      window.location.href = url;
+      return;
+    }
+
+    return this.postEvent('web_app_open_tg_link', { path_full: pathname + search });
+  }
+
+  /**
+   * Opens an invoice using its url. It expects passing link in full format,
+   * with hostname "t.me".
+   * @param url - invoice URL.
+   */
+  async openInvoice(url: string): Promise<InvoiceStatus> {
+    // TODO: Allow opening with slug.
+    const { hostname, pathname } = new URL(formatURL(url));
+
+    if (hostname !== 't.me') {
+      throw new Error(`Incorrect hostname: ${hostname}`);
+    }
+    // Valid examples:
+    // "/invoice/my-slug"
+    // "/$my-slug"
+    const match = pathname.match(/^\/(\$|invoice\/)([A-Za-z0-9\-_=]+)$/);
+
+    if (match === null) {
+      throw new Error('Link pathname has incorrect format. Expected to receive "/invoice/slug" or "/$slug"');
+    }
+    const [, , slug] = match;
+
+    const result = await request('web_app_open_invoice', { slug }, 'invoice_closed', {
+      postEvent: this.postEvent,
+      capture: ({ slug: eventSlug }) => slug === eventSlug,
+    });
+
+    return result.status;
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+
+  /**
+   * Returns current Web App platform.
+   */
+  get platform(): Platform {
+    return this.currentPlatform;
+  }
+
+  /**
+   * Informs the Telegram app that the Web App is ready to be displayed.
+   *
+   * It is recommended to call this method as early as possible, as soon as
+   * all essential interface elements loaded. Once this method called,
+   * the loading placeholder is hidden and the Web App shown.
+   *
+   * If the method not called, the placeholder will be hidden only when
+   * the page fully loaded.
+   */
+  ready(): void {
+    this.postEvent('web_app_ready');
+  }
+
+  /**
+   * Reads text from clipboard and returns string or null. null is returned
+   * in cases:
+   * - Value in clipboard is not text
+   * - Access to clipboard is not allowed
+   */
+  async readTextFromClipboard(): Promise<string | null> {
+    // TODO: Generate request id.
+    const { data = null } = await request(
+      'web_app_read_text_from_clipboard',
+      { req_id: this.createRequestId() },
+      'clipboard_text_received',
+      { postEvent: this.postEvent },
+    );
+
+    return data;
+  }
+
+  /**
+   * Requests current user phone access.
+   */
+  async requestPhoneAccess(): Promise<PhoneRequestedStatus> {
+    const { status } = await request('web_app_request_phone', 'phone_requested', {
+      postEvent: this.postEvent,
+    });
+
+    return status;
+  }
+
+  /**
+   * Requests write message access to current user.
+   */
+  async requestWriteAccess(): Promise<WriteAccessRequestedStatus> {
+    const { status } = await request('web_app_request_write_access', 'write_access_requested', {
+      postEvent: this.postEvent,
+    });
+
+    return status;
+  }
+
+  /**
+   * A method used to send data to the bot. When this method called, a
+   * service message sent to the bot containing the data of the
+   * length up to 4096 bytes, and the Web App closed. See the field
+   * `web_app_data` in the class Message.
+   *
+   * This method is only available for Web Apps launched via a Keyboard button.
+   * @param data - data to send to bot.
+   * @throws {Error} data has incorrect size.
+   */
+  sendData(data: string): void {
+    // Firstly, compute passed text size in bytes.
+    const { size } = new Blob([data]);
+    if (size === 0 || size > 4096) {
+      throw new Error(`Passed data has incorrect size: ${size}`);
+    }
+    this.postEvent('web_app_data_send', { data });
+  }
+
+  /**
+   * Updates current application header color.
+   * FIXME: Has no effect on desktop, works incorrectly on Android.
+   *  Issues:
+   *  https://github.com/Telegram-Mini-Apps/tma.js/issues/9
+   *  https://github.com/Telegram-Mini-Apps/tma.js/issues/8
+   * @param color - color key or RGB color.
+   */
+  setHeaderColor(color: WebAppHeaderColor) {
+    this.postEvent('web_app_set_header_color', isRGB(color) ? { color } : { color_key: color });
+    this.state.set('headerColor', color);
+  }
+
+  /**
+   * Updates current application background color.
+   * FIXME: Has no effect on desktop, works incorrectly in Android.
+   *  Issues:
+   *  https://github.com/Telegram-Mini-Apps/tma.js/issues/9
+   *  https://github.com/Telegram-Mini-Apps/tma.js/issues/8
+   * @param color - RGB color.
+   */
+  setBackgroundColor(color: RGB) {
+    this.postEvent('web_app_set_background_color', { color });
+    this.state.set('backgroundColor', color);
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<
+    | 'openInvoice'
+    | 'readTextFromClipboard'
+    | 'setHeaderColor'
+    | 'setBackgroundColor'
+    | 'requestWriteAccess'
+    | 'requestPhoneAccess'
+  >;
+
+  /**
+   * Checks if specified method parameter is supported by current component.
+   */
+  supportsParam: SupportsFunc<'setHeaderColor.color' | 'openLink.tryInstantView'>;
+
+  /**
+   * Current Web App version. This property is used by other components to check if
+   * some functionality is available on current device.
+   */
+  get version(): Version {
+    return this.currentVersion;
+  }
+}

package/src/components/WebApp/index.ts

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

package/src/components/WebApp/types.ts

@@ -0,0 +1,17 @@
+import type { RGB } from '@tma.js/colors';
+import type { HeaderColorKey } from '@tma.js/bridge';
+
+import type { StateEvents } from '../../state/index.js';
+
+export type WebAppHeaderColor = HeaderColorKey | RGB;
+
+export interface WebAppState {
+  backgroundColor: RGB;
+  headerColor: WebAppHeaderColor;
+}
+
+export type WebAppEvents = StateEvents<WebAppState>;
+
+export type WebAppEventName = keyof WebAppEvents;
+
+export type WebAppEventListener<E extends WebAppEventName> = WebAppEvents[E];

package/src/components/index.ts

@@ -0,0 +1,11 @@
+export * from './BackButton/index.js';
+export * from './ClosingBehaviour/index.js';
+export * from './CloudStorage/index.js';
+export * from './HapticFeedback/index.js';
+export * from './InitData/index.js';
+export * from './MainButton/index.js';
+export * from './Popup/index.js';
+export * from './QRScanner/index.js';
+export * from './ThemeParams/index.js';
+export * from './Viewport/index.js';
+export * from './WebApp/index.js';

package/src/env.ts

@@ -0,0 +1,17 @@
+import { retrieveLaunchParams } from './launch-params.js';
+
+/**
+ * Returns true in case, current environment is Telegram Web Apps.
+ *
+ * `isTWA` utilizes such function as `retrieveLaunchParams`, which attempts to retrieve
+ * launch parameters from the current environment.
+ * @see retrieveLaunchParams
+ */
+export function isTWA(): boolean {
+  try {
+    retrieveLaunchParams();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}

package/src/errors/MethodNotSupportedError.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown in case, unsupported method was called.
+ */
+export class MethodNotSupportedError extends Error {
+  constructor(method: string, version: string) {
+    super(`Method "${method}" is not supported in the Web Apps version ${version}.`);
+    Object.setPrototypeOf(this, MethodNotSupportedError.prototype);
+  }
+}

package/src/errors/ParameterNotSupportedError.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown in case, unsupported parameter was used.
+ */
+export class ParameterUnsupportedError extends Error {
+  constructor(method: string, param: string, version: string) {
+    super(`Parameter "${param}" in method "${method}" is not supported in the Web Apps version ${version}.`);
+    Object.setPrototypeOf(this, ParameterUnsupportedError.prototype);
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './MethodNotSupportedError.js';
+export * from './ParameterNotSupportedError.js';

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './components/index.js';
+export { init, type InitResult, type InitOptions } from './init/index.js';
+export { MethodNotSupportedError } from './errors/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

@@ -0,0 +1,22 @@
+import type { PostEvent } from '@tma.js/bridge';
+
+import { BackButton } from '../../components/index.js';
+
+import { getStorageValue, saveStorageValue } from '../../storage.js';
+
+/**
+ * Creates BackButton instance using last locally saved data also saving each state in
+ * the storage.
+ * @param version - platform version.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createBackButton(version: string, postEvent: PostEvent): BackButton {
+  const { isVisible = false } = getStorageValue('back-button') || {};
+  const component = new BackButton(isVisible, version, postEvent);
+
+  component.on('isVisibleChanged', () => {
+    saveStorageValue('back-button', { isVisible: component.isVisible });
+  });
+
+  return component;
+}

package/src/init/creators/createClosingBehavior.ts

@@ -0,0 +1,22 @@
+import type { PostEvent } from '@tma.js/bridge';
+
+import { ClosingBehaviour } from '../../components/index.js';
+
+import { getStorageValue, saveStorageValue } from '../../storage.js';
+
+/**
+ * Creates ClosingBehaviour instance using last locally saved data also saving each state in
+ * the storage.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createClosingBehavior(postEvent: PostEvent): ClosingBehaviour {
+  const { isConfirmationNeeded = false } = getStorageValue('closing-behavior') || {};
+
+  const component = new ClosingBehaviour(isConfirmationNeeded, postEvent);
+
+  component.on('isConfirmationNeededChanged', () => saveStorageValue('closing-behavior', {
+    isConfirmationNeeded: component.isConfirmationNeeded,
+  }));
+
+  return component;
+}

package/src/init/creators/createMainButton.ts

@@ -0,0 +1,56 @@
+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';
+
+/**
+ * Creates MainButton instance using last locally saved data also saving each state in
+ * the storage.
+ * @param backgroundColor - background color.
+ * @param textColor - text color.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createMainButton(
+  backgroundColor: RGB,
+  textColor: RGB,
+  postEvent: PostEvent,
+): MainButton {
+  const {
+    backgroundColor: stateBackgroundColor = backgroundColor,
+    isEnabled = false,
+    isVisible = false,
+    isProgressVisible = false,
+    textColor: stateTextColor = textColor,
+    text = '',
+  } = getStorageValue('main-button') || {};
+
+  const component = new MainButton(
+    stateBackgroundColor,
+    isEnabled,
+    isVisible,
+    isProgressVisible,
+    text,
+    stateTextColor,
+    postEvent,
+  );
+
+  const saveState = () => saveStorageValue('main-button', {
+    backgroundColor: component.backgroundColor,
+    isEnabled: component.isEnabled,
+    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);
+
+  return component;
+}

package/src/init/creators/createPostEvent.ts

@@ -0,0 +1,36 @@
+import {
+  supports,
+  postEvent as defaultPostEvent,
+  detectSupportParams,
+  type PostEvent,
+} from '@tma.js/bridge';
+import { isRecord } from '@tma.js/utils';
+
+import { MethodNotSupportedError, ParameterUnsupportedError } from '../../errors/index.js';
+
+/**
+ * Creates postEvent function.
+ * @param checkCompat - should compatibility check be enabled.
+ * @param version - platform version.
+ */
+export function createPostEvent(checkCompat: boolean, version: string): PostEvent {
+  return checkCompat
+    ? (method: any, params: any) => {
+      // Firstly, check if method itself is supported.
+      if (!supports(method, version)) {
+        throw new MethodNotSupportedError(method, version);
+      }
+
+      // Method could use parameters, which are supported only in specific versions of TWA.
+      if (isRecord(params)) {
+        detectSupportParams(method, params).forEach((param) => {
+          if (!supports(method as any, param, version)) {
+            throw new ParameterUnsupportedError(method, param, version);
+          }
+        });
+      }
+
+      return defaultPostEvent(method, params);
+    }
+    : defaultPostEvent;
+}

package/src/init/creators/createRequestIdGenerator.ts

@@ -0,0 +1,13 @@
+import type { CreateRequestIdFunc } from '../../types.js';
+
+/**
+ * Creates function which generated request identifiers.
+ */
+export function createRequestIdGenerator(): CreateRequestIdFunc {
+  let requestId = 0;
+
+  return () => {
+    requestId += 1;
+    return requestId.toString();
+  };
+}

package/src/init/creators/createSyncedThemeParams.ts

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

package/src/init/creators/createViewport.ts

@@ -0,0 +1,50 @@
+import type { PostEvent } from '@tma.js/bridge';
+
+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 platform - Telegram Web Apps platform name.
+ * @param postEvent - Bridge postEvent function
+ */
+export async function createViewport(platform: Platform, postEvent: PostEvent): Promise<Viewport> {
+  const {
+    height = window.innerHeight,
+    stableHeight = window.innerHeight,
+    width = window.innerWidth,
+    isExpanded = false,
+  } = getStorageValue('viewport') || {};
+
+  const createSynced = () => {
+    const viewport = new Viewport(height, width, stableHeight, isExpanded, postEvent);
+    Viewport.sync(viewport);
+
+    return viewport;
+  };
+
+  // MacOS and Web K versions do not support requesting current viewport information. That's why we
+  // should construct Viewport instance by ourselves.
+  const component = platform === 'macos' || platform === 'web'
+    ? createSynced()
+    : await Viewport.synced({ postEvent });
+
+  const saveState = () => saveStorageValue('viewport', {
+    height: component.height,
+    isExpanded: component.isExpanded,
+    stableHeight: component.stableHeight,
+    width: component.width,
+  });
+
+  // TODO: Should probably use throttle for height.
+  component.on('heightChanged', saveState);
+  component.on('isExpandedChanged', saveState);
+  component.on('stableHeightChanged', saveState);
+  component.on('widthChanged', saveState);
+
+  return component;
+}

package/src/init/creators/createWebApp.ts

@@ -0,0 +1,49 @@
+import type { RGB } from '@tma.js/colors';
+import type { PostEvent } from '@tma.js/bridge';
+
+import { WebApp } from '../../components/index.js';
+
+import { getStorageValue, saveStorageValue } from '../../storage.js';
+
+import type { CreateRequestIdFunc, Platform } from '../../types.js';
+
+/**
+ * Creates WebApp instance using last locally saved data also saving each state in
+ * the storage.
+ * @param backgroundColor - web app background color.
+ * @param version - platform version.
+ * @param platform - Telegram Web Apps platform name.
+ * @param createRequestId - function which generates request identifiers.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createWebApp(
+  backgroundColor: RGB,
+  version: string,
+  platform: Platform,
+  createRequestId: CreateRequestIdFunc,
+  postEvent: PostEvent,
+): WebApp {
+  const {
+    backgroundColor: stateBackgroundColor = backgroundColor,
+    headerColor = 'bg_color',
+  } = getStorageValue('web-app') || {};
+
+  const component = new WebApp(
+    headerColor,
+    stateBackgroundColor,
+    version,
+    platform,
+    createRequestId,
+    postEvent,
+  );
+
+  const saveState = () => saveStorageValue('web-app', {
+    backgroundColor: component.backgroundColor,
+    headerColor: component.headerColor,
+  });
+
+  component.on('backgroundColorChanged', saveState);
+  component.on('headerColorChanged', saveState);
+
+  return component;
+}

package/src/init/creators/index.ts

@@ -0,0 +1,8 @@
+export * from './createBackButton.js';
+export * from './createClosingBehavior.js';
+export * from './createMainButton.js';
+export * from './createPostEvent.js';
+export * from './createRequestIdGenerator.js';
+export * from './createSyncedThemeParams.js';
+export * from './createViewport.js';
+export * from './createWebApp.js';