@tma.js/sdk 0.11.3

package/src/components/InitData/InitData.ts

@@ -0,0 +1,116 @@
+import type { HasUndefined, If } from '@tma.js/util-types';
+import type {
+  Chat,
+  InitData as InitDataType,
+  User,
+} from '@tma.js/init-data';
+
+import { State } from '../../state/index.js';
+
+type InitDataState = {
+  [K in keyof InitDataType]-?: If<
+    HasUndefined<InitDataType[K]>,
+    Exclude<InitDataType[K], undefined> | null,
+    InitDataType[K]
+  >;
+};
+
+/**
+ * Class which is responsible for displaying Web Apps init data.
+ */
+export class InitData {
+  private readonly state: State<InitDataState>;
+
+  constructor(
+    authDate: Date,
+    hash: string,
+    options: Omit<InitDataType, 'authDate' | 'hash'> = {},
+  ) {
+    const {
+      chat = null,
+      canSendAfter = null,
+      user = null,
+      queryId = null,
+      receiver = null,
+      startParam = null,
+    } = options;
+    this.state = new State({
+      authDate,
+      canSendAfter,
+      chat,
+      user,
+      queryId,
+      receiver,
+      startParam,
+      hash,
+    });
+  }
+
+  /**
+   * Init data generation date.
+   */
+  get authDate(): Date {
+    return this.state.get('authDate');
+  }
+
+  /**
+   * Date after which a message can be sent via the answerWebAppQuery
+   * method.
+   * @see https://core.telegram.org/bots/api#answerwebappquery
+   */
+  get canSendAfter(): Date | null {
+    return this.state.get('canSendAfter');
+  }
+
+  /**
+   * An object containing data about the chat where the bot was
+   * launched via the attachment menu. Returned for supergroups, channels and
+   * group chats – only for Web Apps launched via the attachment menu.
+   */
+  get chat(): Chat | null {
+    return this.state.get('chat');
+  }
+
+  /**
+   * A hash of all passed parameters, which the bot server can use to
+   * check their validity.
+   * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app
+   */
+  get hash(): string {
+    return this.state.get('hash');
+  }
+
+  /**
+   * A unique identifier for the Web App session, required for sending
+   * messages via the `answerWebAppQuery` method.
+   * @see https://core.telegram.org/bots/api#answerwebappquery
+   */
+  get queryId(): string | null {
+    return this.state.get('queryId');
+  }
+
+  /**
+   * An object containing data about the chat partner of the current
+   * user in the chat where the bot was launched via the attachment menu.
+   * Returned only for private chats and only for Web Apps launched
+   * via the attachment menu.
+   */
+  get receiver(): User | null {
+    return this.state.get('receiver');
+  }
+
+  /**
+   * The value of the `startattach` parameter, passed via link. Only
+   * returned for Web Apps when launched from the attachment menu via link.
+   */
+  get startParam(): string | null {
+    return this.state.get('startParam');
+  }
+
+  /**
+   * An object containing data about the current user.
+   */
+  get user(): User | null {
+    return this.state.get('user');
+  }
+}

package/src/components/InitData/index.ts

@@ -0,0 +1 @@
+export * from './InitData.js';

package/src/components/MainButton/MainButton.ts

@@ -0,0 +1,243 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { on, off, postEvent as defaultPostEvent, type PostEvent } from '@tma.js/bridge';
+
+import type { RGB } from '@tma.js/colors';
+
+import { State } from '../../state/index.js';
+
+import type { MainButtonEventListener, MainButtonEvents, MainButtonState } from './types.js';
+
+/**
+ * Controls the main button, which is displayed at the bottom
+ * of the Web App in the Telegram interface.
+ */
+export class MainButton {
+  private readonly ee = new EventEmitter<MainButtonEvents>();
+
+  private readonly state: State<MainButtonState>;
+
+  constructor(
+    backgroundColor: RGB,
+    isEnabled: boolean,
+    isVisible: boolean,
+    isProgressVisible: boolean,
+    text: string,
+    textColor: RGB,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({
+      backgroundColor,
+      isEnabled,
+      isVisible,
+      isProgressVisible,
+      text,
+      textColor,
+    }, this.ee);
+  }
+
+  private set isEnabled(value: boolean) {
+    this.state.set('isEnabled', value);
+    this.commit();
+  }
+
+  /**
+   * Returns true in case, MainButton is currently enabled.
+   */
+  get isEnabled(): boolean {
+    return this.state.get('isEnabled');
+  }
+
+  private set isProgressVisible(value: boolean) {
+    this.state.set('isProgressVisible', value);
+    this.commit();
+  }
+
+  /**
+   * Returns true in case, MainButton loading progress is currently visible.
+   */
+  get isProgressVisible(): boolean {
+    return this.state.get('isProgressVisible');
+  }
+
+  private set isVisible(value: boolean) {
+    this.state.set('isVisible', value);
+    this.commit();
+  }
+
+  /**
+   * Returns true in case, MainButton is currently visible.
+   */
+  get isVisible(): boolean {
+    return this.state.get('isVisible');
+  }
+
+  /**
+   * Sends current local button 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.isProgressVisible,
+      text: this.text,
+      color: this.backgroundColor,
+      text_color: this.textColor,
+    });
+  }
+
+  /**
+   * Returns current main button background color.
+   */
+  get backgroundColor(): RGB {
+    return this.state.get('backgroundColor');
+  }
+
+  /**
+   * Returns current main button text.
+   */
+  get text(): string {
+    return this.state.get('text');
+  }
+
+  /**
+   * Returns current main button text color.
+   */
+  get textColor(): RGB {
+    return this.state.get('textColor');
+  }
+
+  /**
+   * Disables button. Returns current button instance for chaining.
+   */
+  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-Web-Apps/documentation/issues/1
+    this.isEnabled = false;
+    return this;
+  }
+
+  /**
+   * Enables button. Returns current button instance for chaining.
+   */
+  enable(): this {
+    this.isEnabled = true;
+    return this;
+  }
+
+  /**
+   * Hides button. Returns current button instance for chaining.
+   */
+  hide(): this {
+    this.isVisible = false;
+    return this;
+  }
+
+  /**
+   * Hides button progress. Returns current button instance for chaining.
+   */
+  hideProgress(): this {
+    this.isProgressVisible = false;
+    return this;
+  }
+
+  /**
+   * Adds new 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
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  on: typeof this.ee.on = (event, listener) => {
+    if (event === 'click') {
+      return on('main_button_pressed', listener as MainButtonEventListener<'click'>);
+    }
+    this.ee.on(event, listener);
+  };
+
+  /**
+   * Removes event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  off: typeof this.ee.off = (event, listener) => {
+    if (event === 'click') {
+      return off('main_button_pressed', listener as MainButtonEventListener<'click'>);
+    }
+    this.ee.off(event, listener);
+  };
+
+  /**
+   * Shows the button. Note that opening the Web App from the attachment
+   * menu hides the main button until the user interacts with the Web App
+   * interface.
+   *
+   * Returns current button instance for chaining.
+   */
+  show(): this {
+    this.isVisible = true;
+    return this;
+  }
+
+  /**
+   * A method to show a loading indicator on the button.
+   * It is recommended to display loading progress if the action tied to the
+   * button may take a long time.
+   *
+   * Returns current button instance for chaining.
+   */
+  showProgress(): this {
+    this.isProgressVisible = true;
+    return this;
+  }
+
+  /**
+   * Sets new main button text. Returns current button instance for chaining.
+   * Minimal length for text is 1 symbol, and maximum is 64 symbols.
+   *
+   * Returns current button instance for chaining.
+   * @param value - new text.
+   */
+  setText(value: string): this {
+    this.state.set('text', value);
+    this.commit();
+
+    return this;
+  }
+
+  /**
+   * Sets new main button text color. Returns current button instance for
+   * chaining.
+   *
+   * Returns current button instance for chaining.
+   * @param value - new text color.
+   */
+  setTextColor(value: RGB): this {
+    this.state.set('textColor', value);
+    this.commit();
+
+    return this;
+  }
+
+  /**
+   * Updates current button color. Returns current button instance for
+   * chaining.
+   *
+   * Returns current button instance for chaining.
+   * @param value - color to set.
+   */
+  setBackgroundColor(value: RGB): this {
+    this.state.set('backgroundColor', value);
+    this.commit();
+
+    return this;
+  }
+}

package/src/components/MainButton/index.ts

@@ -0,0 +1,2 @@
+export * from './MainButton.js';
+export type { MainButtonEvents, MainButtonEventListener, MainButtonEventName } from './types.js';

package/src/components/MainButton/types.ts

@@ -0,0 +1,20 @@
+import type { RGB } from '@tma.js/colors';
+
+import type { StateEvents } from '../../state/index.js';
+
+export interface MainButtonState {
+  backgroundColor: RGB;
+  isEnabled: boolean;
+  isVisible: boolean;
+  isProgressVisible: boolean;
+  text: string;
+  textColor: RGB;
+}
+
+export interface MainButtonEvents extends StateEvents<MainButtonState> {
+  click: () => void;
+}
+
+export type MainButtonEventName = keyof MainButtonEvents;
+
+export type MainButtonEventListener<E extends MainButtonEventName> = MainButtonEvents[E];

package/src/components/Popup/Popup.ts

@@ -0,0 +1,81 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { postEvent as defaultPostEvent, request, type PostEvent } from '@tma.js/bridge';
+
+import type { Version } from '@tma.js/utils';
+
+import { preparePopupParams } from './utils.js';
+import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+import { State } from '../../state/index.js';
+
+import type { PopupParams, PopupEvents, PopupState } from './types.js';
+
+/**
+ * Controls currently displayed application popup. It allows developers to
+ * open new custom popups and detect popup-connected events.
+ */
+export class Popup {
+  private readonly ee = new EventEmitter<PopupEvents>();
+
+  private readonly state: State<PopupState>;
+
+  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+    this.state = new State({ isOpened: false }, this.ee);
+    this.supports = createSupportsFunc(version, { open: 'web_app_open_popup' });
+  }
+
+  /**
+   * Shows whether popup is currently opened.
+   */
+  get isOpened(): boolean {
+    return this.state.get('isOpened');
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+
+  /**
+   * A method that shows a native popup described by the `params` argument.
+   * Promise will be resolved when popup is closed. Resolved value will have
+   * an identifier of pressed button.
+   *
+   * In case, user clicked outside the popup or clicked top right popup close
+   * button, null will be returned.
+   *
+   * FIXME: In desktop, this function may work incorrectly.
+   *  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/7
+   * @param params - popup parameters.
+   * @throws {Error} Popup is already opened.
+   */
+  async open(params: PopupParams): Promise<string | null> {
+    if (this.isOpened) {
+      throw new Error('Popup is already opened.');
+    }
+
+    this.state.set('isOpened', true);
+
+    try {
+      const { button_id: buttonId = null } = await request(
+        'web_app_open_popup',
+        preparePopupParams(params),
+        'popup_closed',
+        { postEvent: this.postEvent },
+      );
+
+      return buttonId;
+    } finally {
+      this.state.set('isOpened', false);
+    }
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'open'>;
+}

package/src/components/Popup/index.ts

@@ -0,0 +1,8 @@
+export * from './Popup.js';
+export type {
+  PopupParams,
+  PopupEvents,
+  PopupEventListener,
+  PopupEventName,
+  PopupButton,
+} from './types.js';

package/src/components/Popup/types.ts

@@ -0,0 +1,69 @@
+import type { StateEvents } from '../../state/index.js';
+
+export interface PopupState {
+  isOpened: boolean;
+}
+
+export type PopupEvents = StateEvents<PopupState>;
+
+export type PopupEventName = keyof PopupEvents;
+
+export type PopupEventListener<E extends PopupEventName> = PopupEvents[E];
+
+/**
+ * This object describes the native popup.
+ * @see https://core.telegram.org/bots/webapps#popupparams
+ */
+export interface PopupParams {
+  /**
+   * The text to be displayed in the popup title, 0-64 characters.
+   * @default ""
+   */
+  title?: string;
+
+  /**
+   * The message to be displayed in the body of the popup, 1-256 characters.
+   */
+  message: string;
+
+  /**
+   * List of buttons to be displayed in the popup, 1-3 buttons.
+   * @default [{type: 'close'}]
+   */
+  buttons?: PopupButton[]
+}
+
+/**
+ * This object describes the native popup button.
+ * @see https://core.telegram.org/bots/webapps#popupbutton
+ */
+export type PopupButton = {
+  /**
+   * Identifier of the button, 0-64 characters.
+   * @default ""
+   */
+  id?: string;
+} & (
+  {
+    /**
+     * Type of the button:
+     * - `default`, a button with the default style;
+     * - `destructive`, a button with a style that indicates a destructive
+     * action (e.g. "Remove", "Delete", etc.).
+     *
+     * @default "default"
+     */
+    type?: 'default' | 'destructive';
+    /**
+     * The text to be displayed on the button, 0-64 characters.
+     */
+    text: string;
+  } | {
+  /**
+   * Type of the button:
+   * - `ok`, a button with the localized text "OK";
+   * - `close`, a button with the localized text "Close";
+   * - `cancel`, a button with the localized text "Cancel".
+   */
+    type: 'ok' | 'close' | 'cancel';
+  });

package/src/components/Popup/utils.ts

@@ -0,0 +1,59 @@
+import type { PopupButton, PopupParams as BridgePopupParams } from '@tma.js/bridge';
+
+import type { PopupParams } from './types.js';
+
+/**
+ * Prepares popup parameters before sending them to native app.
+ * @param params - popup parameters.
+ */
+export function preparePopupParams(params: PopupParams): BridgePopupParams {
+  const message = params.message.trim();
+  const title = (params.title || '').trim();
+  const buttons = params.buttons || [];
+  let preparedButtons: PopupButton[];
+
+  // Check title.
+  if (title.length > 64) {
+    throw new Error(`Title has incorrect size: ${title.length}`);
+  }
+
+  // Check message.
+  if (message.length === 0 || message.length > 256) {
+    throw new Error(`Message has incorrect size: ${message.length}`);
+  }
+
+  // Check buttons.
+  if (buttons.length > 3) {
+    throw new Error(`Buttons have incorrect size: ${buttons.length}`);
+  }
+
+  // Append button in case, there are no buttons passed.
+  if (buttons.length === 0) {
+    preparedButtons = [{ type: 'close', id: '' }];
+  } else {
+    // Otherwise, check all the buttons.
+    preparedButtons = buttons.map((b) => {
+      const { id = '' } = b;
+
+      // Check button ID.
+      if (id.length > 64) {
+        throw new Error(`Button ID has incorrect size: ${id}`);
+      }
+
+      if (b.type === undefined || b.type === 'default' || b.type === 'destructive') {
+        const text = b.text.trim();
+
+        if (text.length === 0 || text.length > 64) {
+          const type = b.type || 'default';
+
+          throw new Error(`Button text with type "${type}" has incorrect size: ${b.text.length}`);
+        }
+
+        return { ...b, text, id };
+      }
+
+      return { ...b, id };
+    });
+  }
+  return { title, message, buttons: preparedButtons };
+}

package/src/components/QRScanner/QRScanner.ts

@@ -0,0 +1,87 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { postEvent as defaultPostEvent, request, type PostEvent } from '@tma.js/bridge';
+
+import type { Version } from '@tma.js/utils';
+
+import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+import { State } from '../../state/index.js';
+
+import type { QRScannerEvents, QRScannerState } from './types.js';
+
+/**
+ * Provides QR scanner functionality.
+ */
+export class QRScanner {
+  private readonly ee = new EventEmitter<QRScannerEvents>();
+
+  private readonly state: State<QRScannerState>;
+
+  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+    this.state = new State({ isOpened: false }, this.ee);
+    this.supports = createSupportsFunc(version, {
+      close: 'web_app_close_scan_qr_popup',
+      open: 'web_app_open_scan_qr_popup',
+    });
+  }
+
+  /**
+   * Closes scanner.
+   */
+  close(): void {
+    this.postEvent('web_app_close_scan_qr_popup');
+    this.isOpened = false;
+  }
+
+  private set isOpened(value) {
+    this.state.set('isOpened', value);
+  }
+
+  /**
+   * Returns true in case, QR scanner is currently opened.
+   */
+  get isOpened(): boolean {
+    return this.state.get('isOpened');
+  }
+
+  /**
+   * Opens scanner with specified title shown to user. Method returns promise
+   * with scanned QR content in case, it was scanned. It will contain null in
+   * case, scanner was closed.
+   * @param text - title to display.
+   */
+  async open(text?: string): Promise<string | null> {
+    if (this.isOpened) {
+      throw new Error('QR scanner is already opened.');
+    }
+
+    this.isOpened = true;
+
+    try {
+      const result = await request(
+        'web_app_open_scan_qr_popup',
+        { text },
+        ['qr_text_received', 'scan_qr_popup_closed'],
+        { postEvent: this.postEvent },
+      );
+
+      return typeof result === 'object' && typeof result.data === 'string' ? result.data : null;
+    } finally {
+      this.isOpened = false;
+    }
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'open' | 'close'>;
+}

package/src/components/QRScanner/index.ts

@@ -0,0 +1,2 @@
+export * from './QRScanner.js';
+export type { QRScannerEvents, QRScannerEventName, QRScannerEventListener } from './types.js';