@tma.js/sdk 0.13.3 → 1.0.0

package/src/main-button/MainButton.ts

@@ -0,0 +1,239 @@
+import {
+  off,
+  on,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import type { RGB } from '~/colors/index.js';
+
+import type {
+  MainButtonEvents,
+  MainButtonParams,
+  MainButtonProps,
+  MainButtonState,
+} from './types.js';
+
+type Emitter = EventEmitter<MainButtonEvents>;
+
+/**
+ * Controls the main button, which is displayed at the bottom
+ * of the Mini App in the Telegram interface.
+ */
+export class MainButton {
+  private readonly ee: Emitter = new EventEmitter();
+
+  private readonly state: State<MainButtonState>;
+
+  private readonly postEvent: PostEvent;
+
+  constructor(props: MainButtonProps) {
+    const {
+      postEvent = defaultPostEvent,
+      text,
+      textColor,
+      backgroundColor,
+      isEnabled,
+      isVisible,
+      isLoaderVisible,
+    } = props;
+
+    this.postEvent = postEvent;
+    this.state = new State({
+      backgroundColor,
+      isEnabled,
+      isVisible,
+      isLoaderVisible,
+      text,
+      textColor,
+    }, this.ee);
+  }
+
+  /**
+   * Sends current local state to Telegram application.
+   */
+  private commit(): void {
+    // We should not commit changes until payload is correct. We could
+    // have some invalid values in case, button instance was created
+    // with empty values. Otherwise, an unexpected behaviour could be received.
+    if (this.text === '') {
+      return;
+    }
+
+    this.postEvent('web_app_setup_main_button', {
+      is_visible: this.isVisible,
+      is_active: this.isEnabled,
+      is_progress_visible: this.isLoaderVisible,
+      text: this.text,
+      color: this.backgroundColor,
+      text_color: this.textColor,
+    });
+  }
+
+  private set isEnabled(isEnabled: boolean) {
+    this.setParams({ isEnabled });
+  }
+
+  /**
+   * True if the Main Button is currently enabled.
+   */
+  get isEnabled(): boolean {
+    return this.state.get('isEnabled');
+  }
+
+  private set isLoaderVisible(isLoaderVisible: boolean) {
+    this.setParams({ isLoaderVisible });
+  }
+
+  /**
+   * True if the Main Button loader is currently visible.
+   */
+  get isLoaderVisible(): boolean {
+    return this.state.get('isLoaderVisible');
+  }
+
+  private set isVisible(isVisible: boolean) {
+    this.setParams({ isVisible });
+  }
+
+  /**
+   * True if the Main Button is currently visible.
+   */
+  get isVisible(): boolean {
+    return this.state.get('isVisible');
+  }
+
+  /**
+   * The Main Button background color.
+   */
+  get backgroundColor(): RGB {
+    return this.state.get('backgroundColor');
+  }
+
+  /**
+   * The Main Button text.
+   */
+  get text(): string {
+    return this.state.get('text');
+  }
+
+  /**
+   * The Main Button text color.
+   */
+  get textColor(): RGB {
+    return this.state.get('textColor');
+  }
+
+  /**
+   * Disables the Main Button.
+   */
+  disable(): this {
+    // FIXME: This method does not work on Android. Event "main_button_pressed"
+    //  keeps getting received even in case, button is disabled.
+    //  Issue: https://github.com/Telegram-Mini-Apps/documentation/issues/1
+    this.isEnabled = false;
+    return this;
+  }
+
+  /**
+   * Enables the Main Button.
+   */
+  enable(): this {
+    this.isEnabled = true;
+    return this;
+  }
+
+  /**
+   * Hides the Main Button.
+   */
+  hide(): this {
+    this.isVisible = false;
+    return this;
+  }
+
+  /**
+   * Hides the Main Button loader.
+   */
+  hideLoader(): this {
+    this.isLoaderVisible = false;
+    return this;
+  }
+
+  /**
+   * Adds new event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  on: Emitter['on'] = (event, listener) => (
+    // FIXME: Event 'main_button_pressed' is still being received on Android
+    //  even if the main button is disabled.
+    //  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/3
+    event === 'click'
+      ? on('main_button_pressed', listener)
+      : this.ee.on(event, listener)
+  );
+
+  /**
+   * Removes event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  off: Emitter['off'] = (event, listener) => (
+    event === 'click'
+      ? off('main_button_pressed', listener)
+      : this.ee.off(event, listener)
+  );
+
+  /**
+   * Shows the Main Button. Note that opening the Mini App from the attachment menu hides the
+   * main button until the user interacts with the Mini App interface.
+   */
+  show(): this {
+    this.isVisible = true;
+    return this;
+  }
+
+  /**
+   * A method to show a loading indicator on the Main Button. It is recommended to display
+   * loader if the action tied to the button may take a long time.
+   */
+  showLoader(): this {
+    this.isLoaderVisible = true;
+    return this;
+  }
+
+  /**
+   * Sets new Main Button text. Minimal length for text is 1 symbol, and maximum is 64 symbols.
+   * @param text - new text.
+   */
+  setText(text: string): this {
+    return this.setParams({ text });
+  }
+
+  /**
+   * Sets new Main Button text color.
+   * @param textColor - new text color.
+   */
+  setTextColor(textColor: RGB): this {
+    return this.setParams({ textColor });
+  }
+
+  /**
+   * Updates current Main Button color.
+   * @param backgroundColor - color to set.
+   */
+  setBackgroundColor(backgroundColor: RGB): this {
+    return this.setParams({ backgroundColor });
+  }
+
+  /**
+   * Allows setting multiple Main Button parameters.
+   * @param params - Main Button parameters.
+   */
+  setParams(params: MainButtonParams): this {
+    this.state.set(params);
+    this.commit();
+    return this;
+  }
+}

package/src/main-button/index.ts

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

package/src/main-button/types.ts

@@ -0,0 +1,26 @@
+import type { PostEvent } from '~/bridge/index.js';
+import type { RGB } from '~/colors/index.js';
+import type { StateEvents } from '~/state/index.js';
+
+export interface MainButtonParams {
+  backgroundColor?: RGB;
+  isEnabled?: boolean;
+  isLoaderVisible?: boolean;
+  isVisible?: boolean;
+  text?: string;
+  textColor?: RGB;
+}
+
+export interface MainButtonProps extends Required<MainButtonParams> {
+  postEvent?: PostEvent;
+}
+
+export type MainButtonState = Required<MainButtonParams>;
+
+export interface MainButtonEvents extends StateEvents<MainButtonState> {
+  click: () => void;
+}
+
+export type MainButtonEventName = keyof MainButtonEvents;
+
+export type MainButtonEventListener<E extends MainButtonEventName> = MainButtonEvents[E];

package/src/mini-app/MiniApp.ts

@@ -0,0 +1,237 @@
+import {
+  type PhoneRequestedStatus,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  request,
+  type SwitchInlineQueryChatType,
+  type WriteAccessRequestedStatus,
+} from '~/bridge/index.js';
+import {
+  isColorDark,
+  isRGB,
+  type RGB,
+} from '~/colors/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import {
+  createSupportsFunc,
+  createSupportsParamFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+
+import type {
+  MiniAppEvents,
+  MiniAppHeaderColor, MiniAppProps,
+  MiniAppState,
+} from './types.js';
+
+/**
+ * Provides common Mini Apps functionality not covered by other system components.
+ */
+export class MiniApp {
+  private readonly ee = new EventEmitter<MiniAppEvents>();
+
+  private readonly state: State<MiniAppState>;
+
+  private readonly botInline: boolean;
+
+  private readonly postEvent: PostEvent;
+
+  constructor(props: MiniAppProps) {
+    const {
+      postEvent = defaultPostEvent,
+      headerColor,
+      backgroundColor,
+      version,
+      botInline,
+    } = props;
+
+    const isSupported = createSupportsFunc(version, {
+      requestPhoneAccess: 'web_app_request_phone',
+      requestWriteAccess: 'web_app_request_write_access',
+      switchInlineQuery: 'web_app_switch_inline_query',
+      setHeaderColor: 'web_app_set_header_color',
+      setBackgroundColor: 'web_app_set_background_color',
+    });
+
+    this.postEvent = postEvent;
+    this.botInline = botInline;
+    this.supports = (method) => {
+      if (!isSupported(method)) {
+        return false;
+      }
+
+      // web_app_switch_inline_query requires a Mini App to be in inline mode, that's why we
+      // add 1 more check here.
+      if (method === 'switchInlineQuery' && !botInline) {
+        return false;
+      }
+
+      return true;
+    };
+
+    this.state = new State({ backgroundColor, headerColor }, this.ee);
+    this.supportsParam = createSupportsParamFunc(version, {
+      'setHeaderColor.color': ['web_app_set_header_color', 'color'],
+    });
+  }
+
+  /**
+   * The Mini App background color.
+   */
+  get backgroundColor(): RGB {
+    return this.state.get('backgroundColor');
+  }
+
+  /**
+   * Closes the Mini App.
+   */
+  close(): void {
+    this.postEvent('web_app_close');
+  }
+
+  /**
+   * The Mini App header color. Could either be a header color key or RGB color.
+   */
+  get headerColor(): MiniAppHeaderColor {
+    return this.state.get('headerColor');
+  }
+
+  /**
+   * True if Mini App is currently launched in bot inline mode.
+   */
+  get isBotInline(): boolean {
+    return this.botInline;
+  }
+
+  /**
+   * True if current Mini App background color recognized as dark.
+   */
+  get isDark(): boolean {
+    return isColorDark(this.backgroundColor);
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+
+  /**
+   * 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');
+  }
+
+  /**
+   * Requests current user phone access.
+   */
+  requestPhoneAccess(): Promise<PhoneRequestedStatus> {
+    return request(
+      'web_app_request_phone',
+      'phone_requested',
+      { postEvent: this.postEvent },
+    ).then((data) => data.status);
+  }
+
+  /**
+   * Requests write message access to current user.
+   */
+  requestWriteAccess(): Promise<WriteAccessRequestedStatus> {
+    return request(
+      'web_app_request_write_access',
+      'write_access_requested',
+      { postEvent: this.postEvent },
+    ).then((data) => data.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](https://core.telegram.org/bots/api#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 {
+    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 Mini App header color.
+   * @param color - color key or RGB color.
+   */
+  setHeaderColor(color: MiniAppHeaderColor): void {
+    // 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
+    this.postEvent('web_app_set_header_color', isRGB(color) ? { color } : { color_key: color });
+    this.state.set('headerColor', color);
+  }
+
+  /**
+   * Updates current Mini App background color.
+   * @param color - RGB color.
+   */
+  setBackgroundColor(color: RGB): void {
+    // 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
+    this.postEvent('web_app_set_background_color', { color });
+    this.state.set('backgroundColor', color);
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<
+  | 'requestWriteAccess'
+  | 'requestPhoneAccess'
+  | 'switchInlineQuery'
+  | 'setHeaderColor'
+  | 'setBackgroundColor'
+  >;
+
+  /**
+   * Checks if specified method parameter is supported by current component.
+   */
+  supportsParam: SupportsFunc<'setHeaderColor.color'>;
+
+  /**
+   * Inserts the bot's username and the specified inline query in the current chat's input field.
+   * Query may be empty, in which case only the bot's username will be inserted. The client prompts
+   * the user to choose a specific chat, then opens that chat and inserts the bot's username and
+   * the specified inline query in the input field.
+   * @param text - text which should be inserted in the input after the current bot name. Max
+   * length is 256 symbols.
+   * @param chatTypes - List of chat types which could be chosen to send the message. Could be
+   * empty list.
+   */
+  switchInlineQuery(text: string, chatTypes: SwitchInlineQueryChatType[] = []): void {
+    if (!this.supports('switchInlineQuery') && !this.isBotInline) {
+      throw new Error('Method is unsupported because Mini App should be launched in inline mode.');
+    }
+    this.postEvent('web_app_switch_inline_query', {
+      query: text,
+      chat_types: chatTypes,
+    });
+  }
+}

package/src/mini-app/index.ts

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

package/src/mini-app/types.ts

@@ -0,0 +1,25 @@
+import type { HeaderColorKey, PostEvent } from '~/bridge/index.js';
+import type { RGB } from '~/colors/index.js';
+import type { StateEvents } from '~/state/index.js';
+import type { Version } from '~/version/index.js';
+
+export interface MiniAppProps {
+  headerColor: MiniAppHeaderColor;
+  backgroundColor: RGB;
+  version: Version;
+  botInline: boolean;
+  postEvent?: PostEvent;
+}
+
+export type MiniAppHeaderColor = HeaderColorKey | RGB;
+
+export interface MiniAppState {
+  backgroundColor: RGB;
+  headerColor: MiniAppHeaderColor;
+}
+
+export type MiniAppEvents = StateEvents<MiniAppState>;
+
+export type MiniAppEventName = keyof MiniAppEvents;
+
+export type MiniAppEventListener<E extends MiniAppEventName> = MiniAppEvents[E];

package/src/misc/index.ts

@@ -0,0 +1,2 @@
+export * from './isRecord.js';
+export * from './isTMA.js';

package/src/misc/isRecord.ts

@@ -0,0 +1,7 @@
+/**
+ * States that passed value is Record and not Array.
+ * @param value - value to check.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/misc/isTMA.ts

@@ -0,0 +1,13 @@
+import { retrieveLaunchData } from '~/launch-params/index.js';
+
+/**
+ * Returns true in case, current environment is Telegram Mini Apps.
+ */
+export function isTMA(): boolean {
+  try {
+    retrieveLaunchData();
+    return true;
+  } catch (e) {
+    return false;
+  }
+}