@tma.js/sdk 0.13.3 → 1.0.0

package/src/components/WebApp/WebApp.ts

@@ -1,311 +0,0 @@
-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 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 } from '../../types.js';
-import type { WebAppEvents, WebAppHeaderColor, WebAppState } from './types.js';
-
-/**
- * Provides common Mini 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 Mini 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
-   * Mini App version.
-   * @param version - compared version.
-   */
-  isVersionAtLeast(version: Version): boolean {
-    return compareVersions(version, this.version) >= 0;
-  }
-
-  /**
-   * Opens a link in an external browser. The Mini App will not be closed.
-   *
-   * Note that this method can be called only in response to the user
-   * interaction with the Mini App interface (e.g. click inside the Mini 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 Mini 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 Mini App platform.
-   */
-  get platform(): Platform {
-    return this.currentPlatform;
-  }
-
-  /**
-   * Informs the Telegram app that the Mini 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 Mini 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 Mini App closed. See the field
-   * `web_app_data` in the class Message.
-   *
-   * This method is only available for Mini 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 Mini 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

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

package/src/components/WebApp/types.ts

@@ -1,17 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,22 +0,0 @@
-import { retrieveLaunchData } from '@tma.js/launch-params';
-
-/**
- * Returns true in case, current environment is Telegram Mini Apps.
- */
-export function isTMA(): boolean {
-  try {
-    retrieveLaunchData();
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Returns true in case, current environment is Telegram Mini Apps.
- * @see computeLaunchData
- * @deprecated Use `isTMA`
- */
-export function isTWA(): boolean {
-  return isTMA();
-}

package/src/errors/MethodNotSupportedError.ts

@@ -1,9 +0,0 @@
-/**
- * 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 Mini Apps version ${version}.`);
-    Object.setPrototypeOf(this, MethodNotSupportedError.prototype);
-  }
-}

package/src/errors/ParameterNotSupportedError.ts

@@ -1,9 +0,0 @@
-/**
- * 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 Mini Apps version ${version}.`);
-    Object.setPrototypeOf(this, ParameterUnsupportedError.prototype);
-  }
-}

package/src/errors/index.ts

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

package/src/init/creators/createWebApp.ts

@@ -1,52 +0,0 @@
-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 } 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 Mini Apps platform name.
- * @param createRequestId - function which generates request identifiers.
- * @param postEvent - Bridge postEvent function
- */
-export function createWebApp(
-  isPageReload: boolean,
-  backgroundColor: RGB,
-  version: string,
-  platform: Platform,
-  createRequestId: CreateRequestIdFunc,
-  postEvent: PostEvent,
-): WebApp {
-  const {
-    backgroundColor: stateBackgroundColor = backgroundColor,
-    headerColor = 'bg_color',
-  } = isPageReload ? 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/css.ts

@@ -1,142 +0,0 @@
-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 Mini 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 CSS variables names are
- * following the pattern "--tg-theme-{name}". {name} is a theme parameters key name converted
- * from snake to kebab case.
- *
- * 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 = () => {
-    const state = themeParams.getState();
-
-    Object.entries(state).forEach(([k, v]) => {
-      const key = k.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
-      setColorVariable(`--tg-theme-${key}`, v || null);
-    });
-  };
-
-  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/supports.ts

@@ -1,44 +0,0 @@
-import type { Version } from '@tma.js/utils';
-import {
-  supports,
-  type MethodName,
-  type MethodVersionedParams,
-  type MethodWithVersionedParams,
-} from '@tma.js/bridge';
-
-export type SupportsFunc<M extends string> = (method: M) => boolean;
-
-type HasCheckSupportMethodTuple = {
-  [M in MethodWithVersionedParams]: [M, MethodVersionedParams<M>]
-}[MethodWithVersionedParams];
-
-/**
- * Returns function, which accepts predefined method name and checks if it is supported
- * via passed schema and version.
- * @param schema - object which contains methods names and TWA method as a dependency.
- * @param version - platform version.
- */
-export function createSupportsFunc<M extends string>(
-  version: Version,
-  schema: Record<M, MethodName>,
-): SupportsFunc<M> {
-  return (method) => supports(schema[method], version);
-}
-
-/**
- * Returns function, which accepts predefined method name and checks if it is supported
- * via passed schema and version.
- * @param schema - object which contains methods names and TWA methods with specified parameter
- * as a dependency.
- * @param version - platform version.
- */
-export function createSupportsParamFunc<P extends string>(
-  version: Version,
-  schema: Record<P, HasCheckSupportMethodTuple>,
-): SupportsFunc<P> {
-  return (method) => {
-    const [tmaMethod, param] = schema[method];
-
-    return supports(tmaMethod, param, version);
-  };
-}

package/src/types.ts

@@ -1,13 +0,0 @@
-import type { PostEvent as BridgePostEvent } from '@tma.js/bridge';
-
-export type PostEvent = BridgePostEvent;
-
-/**
- * Color scheme.
- */
-export type ColorScheme = 'dark' | 'light';
-
-/**
- * Function which generates unique request identifiers.
- */
-export type CreateRequestIdFunc = () => string;

package/src/url.ts

@@ -1,23 +0,0 @@
-/**
- * Converts passed URL to its full form.
- * @param url - URL to format.
- * @throws {Error} URL protocol is not supported by OS, or link has not allowed
- * protocol.
- */
-export function formatURL(url: string): string {
-  // TODO: Maybe, there is a bit easier way? window.open will accept
-  //  unformatted URL too, probably.
-
-  // We do create new anchor element and assign its href to passed URL. This
-  // will format link, so it could be used in `window.open`.
-  const anchor = document.createElement('a');
-  anchor.href = url;
-
-  // Check if protocol is correct.
-  if (anchor.protocol !== 'http:' && anchor.protocol !== 'https:') {
-    throw Error(
-      `URL protocol is not supported by OS, or link has not allowed protocol: ${anchor.protocol}`,
-    );
-  }
-  return anchor.href;
-}