@tma.js/sdk 0.13.3 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tma.js/sdk",
-  "version": "0.13.3",
+  "version": "1.0.1",
   "description": "TypeScript Source Development Kit for Telegram Mini Apps client application.",
   "author": "Vladislav Kibenko <wolfram.deus@gmail.com>",
   "homepage": "https://github.com/Telegram-Mini-Apps/tma.js#readme",
@@ -36,28 +36,19 @@
       "default": "./dist/index.cjs"
     }
   },
-  "dependencies": {
-    "@tma.js/bridge": "1.4.1",
-    "@tma.js/colors": "0.0.5",
-    "@tma.js/init-data": "0.2.22",
-    "@tma.js/utils": "0.5.6",
-    "@tma.js/util-types": "0.0.3",
-    "@tma.js/parsing": "1.0.1",
-    "@tma.js/theme-params": "1.0.0",
-    "@tma.js/launch-params": "1.0.1",
-    "@tma.js/event-emitter": "0.1.0"
-  },
   "devDependencies": {
-    "tsconfig": "0.0.2",
+    "build-utils": "0.0.1",
     "eslint-config-custom": "0.1.0",
-    "build-utils": "0.0.1"
+    "test-utils": "0.0.1",
+    "tsconfig": "0.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "test": "vitest",
-    "lint": "eslint -c .eslintrc.cjs src/**/* tests/**/*",
+    "test": "vitest --run",
+    "lint": "eslint src/**/*",
+    "lint:fix": "pnpm run lint --fix",
     "typecheck": "tsc --noEmit -p tsconfig.build.json",
     "build": "pnpm run build:default && pnpm run build:iife",
     "build:default": "vite build --config vite.config.ts",

package/src/{components/BackButton → back-button}/BackButton.ts

@@ -1,21 +1,25 @@
-import { EventEmitter } from '@tma.js/event-emitter';
-import { on, off, postEvent as defaultPostEvent, type PostEvent } from '@tma.js/bridge';
+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 { createSupportsFunc, type SupportsFunc } from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
 
-import type { Version } from '@tma.js/utils';
+import type { BackButtonEvents, BackButtonState } from './types.js';
 
-import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
-import { State } from '../../state/index.js';
-
-import type { BackButtonEvents, BackButtonState, BackButtonEventListener } from './types.js';
+type Emitter = EventEmitter<BackButtonEvents>;
 
 /**
- * Class which controls the back button displayed in the header
- * of the Mini App in the Telegram interface. It is mostly used in case, when
- * you want to provide a way to go bach in routing history or "rollback" some
- * action.
+ * Class which controls the back button displayed in the header of the Mini App in the Telegram
+ * interface. It is mostly used in case, when you want to provide a way to go bach in routing
+ * history or "rollback" some action.
  */
 export class BackButton {
-  private readonly ee = new EventEmitter<BackButtonEvents>();
+  private readonly ee: Emitter = new EventEmitter();
 
   private readonly state: State<BackButtonState>;
 
@@ -55,9 +59,9 @@ export class BackButton {
    * @param event - event name.
    * @param listener - event listener.
    */
-  on: typeof this.ee.on = (event, listener) => (
+  on: Emitter['on'] = (event, listener) => (
     event === 'click'
-      ? on('back_button_pressed', listener as BackButtonEventListener<'click'>)
+      ? on('back_button_pressed', listener)
       : this.ee.on(event, listener)
   );
 
@@ -66,13 +70,11 @@ export class BackButton {
    * @param event - event name.
    * @param listener - event listener.
    */
-  off: typeof this.ee.off = (event, listener) => {
-    if (event === 'click') {
-      return off('back_button_pressed', listener as BackButtonEventListener<'click'>);
-    }
-
-    this.ee.off(event, listener);
-  };
+  off: Emitter['off'] = (event, listener) => (
+    event === 'click'
+      ? off('back_button_pressed', listener)
+      : this.ee.off(event, listener)
+  );
 
   /**
    * Shows the BackButton.

package/src/back-button/index.ts

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

package/src/{components/BackButton → back-button}/types.ts

@@ -1,11 +1,12 @@
-import type { StateEvents } from '../../state/index.js';
+import type { MiniAppsEventListener } from '~/bridge/index.js';
+import type { StateEvents } from '~/state/index.js';
 
 export interface BackButtonState {
   isVisible: boolean;
 }
 
 export interface BackButtonEvents extends StateEvents<BackButtonState> {
-  click: () => void;
+  click: MiniAppsEventListener<'main_button_pressed'>;
 }
 
 export type BackButtonEventName = keyof BackButtonEvents;

package/src/bridge/env/hasExternalNotify.ts

@@ -0,0 +1,19 @@
+import { isRecord } from '~/misc/index.js';
+
+type WithExternalNotify<T> = T & {
+  external: {
+    notify: (...args: any) => any;
+  };
+};
+
+/**
+ * Returns true in case, passed value contains path `external.notify` property and `notify` is a
+ * function.
+ * @param value - value to check.
+ */
+export function hasExternalNotify<T extends {}>(value: T): value is WithExternalNotify<T> {
+  return 'external' in value
+    && isRecord(value.external)
+    && 'notify' in value.external
+    && typeof value.external.notify === 'function';
+}

package/src/bridge/env/hasWebviewProxy.ts

@@ -0,0 +1,19 @@
+import { isRecord } from '~/misc/index.js';
+
+type WithWebviewProxy<T> = T & {
+  TelegramWebviewProxy: {
+    postEvent: (...args: any) => any;
+  }
+};
+
+/**
+ * Returns true in case, passed value contains path `TelegramWebviewProxy.postEvent` property and
+ * `postEvent` is a function.
+ * @param value - value to check.
+ */
+export function hasWebviewProxy<T extends {}>(value: T): value is WithWebviewProxy<T> {
+  return 'TelegramWebviewProxy' in value
+    && isRecord(value.TelegramWebviewProxy)
+    && 'postEvent' in value.TelegramWebviewProxy
+    && typeof value.TelegramWebviewProxy.postEvent === 'function';
+}

package/src/bridge/env/index.ts

@@ -0,0 +1,3 @@
+export * from './hasExternalNotify.js';
+export * from './hasWebviewProxy.js';
+export * from './isIframe.js';

package/src/bridge/env/isIframe.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns true in case, current environment is iframe.
+ * @see https://stackoverflow.com/a/326076
+ */
+export function isIframe(): boolean {
+  try {
+    return window.self !== window.top;
+  } catch (e) {
+    return true;
+  }
+}

package/src/bridge/errors/MethodUnsupportedError.ts

@@ -0,0 +1,13 @@
+import type { Version } from '~/version/index.js';
+
+import type { MiniAppsMethodName } from '../methods/index.js';
+
+/**
+ * Error thrown in case, unsupported method was called.
+ */
+export class MethodUnsupportedError extends Error {
+  constructor(method: MiniAppsMethodName, version: Version) {
+    super(`Method "${method}" is unsupported in the Mini Apps version ${version}.`);
+    Object.setPrototypeOf(this, MethodUnsupportedError.prototype);
+  }
+}

package/src/bridge/errors/ParameterUnsupportedError.ts

@@ -0,0 +1,13 @@
+import type { Version } from '~/version/index.js';
+
+import type { MiniAppsMethodName } from '../methods/index.js';
+
+/**
+ * Error thrown in case, unsupported parameter was used.
+ */
+export class ParameterUnsupportedError extends Error {
+  constructor(method: MiniAppsMethodName, param: string, version: Version) {
+    super(`Parameter "${param}" in method "${method}" is unsupported in the Mini Apps version ${version}.`);
+    Object.setPrototypeOf(this, ParameterUnsupportedError.prototype);
+  }
+}

package/src/bridge/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './MethodUnsupportedError.js';
+export * from './ParameterUnsupportedError.js';

package/src/bridge/events/createEmitter.ts

@@ -0,0 +1,108 @@
+import { EventEmitter } from '~/event-emitter/index.js';
+import { logger } from '~/globals.js';
+import { string } from '~/parsing/index.js';
+
+import type { MiniAppsEventEmitter, MiniAppsEventName } from './events.js';
+import { onTelegramEvent } from './onTelegramEvent.js';
+import {
+  clipboardTextReceived,
+  customMethodInvoked,
+  invoiceClosed,
+  phoneRequested,
+  popupClosed,
+  qrTextReceived,
+  themeChanged,
+  viewportChanged,
+  writeAccessRequested,
+} from './parsers/index.js';
+
+/**
+ * Returns event emitter which could be safely used, to process events from
+ * Telegram native application.
+ */
+export function createEmitter(): MiniAppsEventEmitter {
+  const emitter: MiniAppsEventEmitter = new EventEmitter();
+  const emit: MiniAppsEventEmitter['emit'] = (event: any, ...data: any[]) => {
+    logger.log('Emitting processed event:', event, ...data);
+    emitter.emit(event, ...data);
+  };
+
+  // Desktop version of Telegram is sometimes not sending the viewport_changed
+  // event. For example, when main button is shown. That's why we should
+  // add our own listener to make sure, viewport information is always fresh.
+  // Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/10
+  window.addEventListener('resize', () => {
+    emit('viewport_changed', {
+      width: window.innerWidth,
+      height: window.innerHeight,
+      is_state_stable: true,
+      is_expanded: true,
+    });
+  });
+
+  // In case, any Telegram event was received, we should prepare data before
+  // passing it to emitter.
+  onTelegramEvent((eventType: MiniAppsEventName | string, eventData): void => {
+    logger.log('Received raw event:', eventType, eventData);
+
+    try {
+      switch (eventType) {
+        case 'viewport_changed':
+          return emit(eventType, viewportChanged().parse(eventData));
+
+        case 'theme_changed':
+          return emit(eventType, themeChanged().parse(eventData));
+
+        case 'popup_closed':
+          // FIXME: Payloads are different on different platforms.
+          //  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/2
+          if (
+            // Sent on desktop.
+            eventData === undefined
+            // Sent on iOS.
+            || eventData === null
+          ) {
+            return emit(eventType, {});
+          }
+          return emit(eventType, popupClosed().parse(eventData));
+
+        case 'set_custom_style':
+          return emit(eventType, string().parse(eventData));
+
+        case 'qr_text_received':
+          return emit(eventType, qrTextReceived().parse(eventData));
+
+        case 'clipboard_text_received':
+          return emit(eventType, clipboardTextReceived().parse(eventData));
+
+        case 'invoice_closed':
+          return emit(eventType, invoiceClosed().parse(eventData));
+
+        case 'phone_requested':
+          return emit('phone_requested', phoneRequested().parse(eventData));
+
+        case 'custom_method_invoked':
+          return emit('custom_method_invoked', customMethodInvoked().parse(eventData));
+
+        case 'write_access_requested':
+          return emit('write_access_requested', writeAccessRequested().parse(eventData));
+
+        // Events which have no parameters.
+        case 'main_button_pressed':
+        case 'back_button_pressed':
+        case 'settings_button_pressed':
+        case 'scan_qr_popup_closed':
+        case 'reload_iframe':
+          return emit(eventType);
+
+        // All other event listeners will receive unknown type of data.
+        default:
+          return emit(eventType as any, eventData);
+      }
+    } catch (cause) {
+      logger.error('Error processing event:', cause);
+    }
+  });
+
+  return emitter;
+}

package/src/bridge/events/events.ts

@@ -0,0 +1,170 @@
+import type {
+  AnySubscribeListener,
+  EventEmitter,
+  EventListener,
+  EventParams,
+} from '~/event-emitter/index.js';
+import type { IsNever, Not } from '~/types/index.js';
+
+import type {
+  ClipboardTextReceivedPayload,
+  CustomMethodInvokedPayload,
+  InvoiceClosedPayload,
+  PhoneRequestedPayload,
+  PopupClosedPayload,
+  QrTextReceivedPayload,
+  ThemeChangedPayload,
+  ViewportChangedPayload,
+  WriteAccessRequestedPayload,
+} from './parsers/index.js';
+
+/**
+ * Map where key is known event name, and value is its listener.
+ * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events
+ */
+export interface MiniAppsEvents {
+  /**
+   * User clicked back button.
+   * @since v6.1
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#back-button-pressed
+   */
+  back_button_pressed: () => void;
+
+  /**
+   * Telegram application attempted to extract text from clipboard.
+   * @param payload - event payload.
+   * @since v6.4
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#clipboard-text-received
+   */
+  clipboard_text_received: (payload: ClipboardTextReceivedPayload) => void;
+
+  /**
+   * Custom method invocation completed.
+   * @param payload - event payload.
+   * @since v6.9
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#custom-method-invoked
+   */
+  custom_method_invoked: (payload: CustomMethodInvokedPayload) => void;
+
+  /**
+   * An invoice was closed.
+   * @param payload - invoice close information.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#invoice-closed
+   */
+  invoice_closed: (payload: InvoiceClosedPayload) => void;
+
+  /**
+   * User clicked the Main Button.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#main-button-pressed
+   */
+  main_button_pressed: () => void;
+
+  /**
+   * Application received phone access request status.
+   * @param payload - event payload.
+   * @since v6.9
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#phone-requested
+   */
+  phone_requested: (payload: PhoneRequestedPayload) => void;
+
+  /**
+   * Popup was closed.
+   * @param payload - event payload.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#popup-closed
+   */
+  popup_closed: (payload: PopupClosedPayload) => void;
+
+  /**
+   * Parent iframe requested current iframe reload.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#reload-iframe
+   */
+  reload_iframe: () => void;
+
+  /**
+   * The QR scanner scanned some QR and extracted its content.
+   * @param payload - event payload.
+   * @since v6.4
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#qr-text-received
+   */
+  qr_text_received: (payload: QrTextReceivedPayload) => void;
+
+  /**
+   * QR scanner was closed.
+   * @since v6.4
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#scan-qr-popup-closed
+   */
+  scan_qr_popup_closed: () => void;
+
+  /**
+   * The event which is usually sent by the Telegram web application. Its payload represents
+   * `<style/>` tag html content, a developer could use. The stylesheet described in the payload
+   * will help the developer to stylize the app scrollbar (but he is still able to do it himself).
+   * @param html - `style` tag inner HTML.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#set-custom-style
+   */
+  set_custom_style: (html: string) => void;
+
+  /**
+   * Occurs when the Settings Button was pressed.
+   * @since v6.1
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#settings-button-pressed
+   */
+  settings_button_pressed: () => void;
+
+  /**
+   * Occurs whenever theme settings are changed in the user's Telegram app
+   * (including switching to night mode).
+   * @param payload - event payload.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#theme-changed
+   */
+  theme_changed: (payload: ThemeChangedPayload) => void;
+
+  /**
+   * Occurs whenever the viewport has been changed. For example, when the user started
+   * dragging the application or called the expansion method.
+   * @param payload - event payload.
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#viewport-changed
+   */
+  viewport_changed: (payload: ViewportChangedPayload) => void;
+
+  /**
+   * Application received write access request status.
+   * @param payload - event payload.
+   * @since v6.9
+   * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#write-access-requested
+   */
+  write_access_requested: (payload: WriteAccessRequestedPayload) => void;
+}
+
+/**
+ * Any known event name.
+ */
+export type MiniAppsEventName = keyof MiniAppsEvents;
+
+/**
+ * Parameters of specified event.
+ */
+export type MiniAppsEventParams<E extends MiniAppsEventName> = EventParams<MiniAppsEvents[E]>[0];
+
+/**
+ * Returns event listener for specified event name.
+ */
+export type MiniAppsEventListener<E extends MiniAppsEventName> = EventListener<MiniAppsEvents[E]>;
+
+/**
+ * Event emitter, based describe events map.
+ */
+export type MiniAppsEventEmitter = EventEmitter<MiniAppsEvents>;
+
+/**
+ * Returns true in case, event has parameters.
+ */
+export type MiniAppsEventHasParams<E extends MiniAppsEventName> =
+  Not<IsNever<MiniAppsEventParams<E>>>;
+
+/**
+ * Event listener used in `subscribe` and `unsubscribe` functions.
+ */
+export type MiniAppsGlobalEventListener =
+  | AnySubscribeListener<MiniAppsEvents>
+  | ((event: string, data: unknown) => void);

package/src/bridge/events/index.ts

@@ -0,0 +1,9 @@
+export * from './createEmitter.js';
+export * from './events.js';
+export * from './off.js';
+export * from './on.js';
+export * from './once.js';
+export * from './parsers/index.js';
+export * from './singletonEmitter.js';
+export * from './subscribe.js';
+export * from './unsubscribe.js';

package/src/bridge/events/off.ts

@@ -0,0 +1,14 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+import { singletonEmitter } from './singletonEmitter.js';
+
+/**
+ * Removes listener from specified event.
+ * @param event - event to listen.
+ * @param listener - event listener.
+ */
+export function off<E extends MiniAppsEventName>(
+  event: E,
+  listener: MiniAppsEventListener<E>,
+): void {
+  singletonEmitter().off(event, listener);
+}

package/src/bridge/events/on.ts

@@ -0,0 +1,19 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+import { off } from './off.js';
+import { singletonEmitter } from './singletonEmitter.js';
+
+type StopListening = () => void;
+
+/**
+ * Adds new listener to the specified event. Returns handler
+ * which allows to stop listening to event.
+ * @param event - event name.
+ * @param listener - event listener.
+ */
+export function on<E extends MiniAppsEventName>(
+  event: E,
+  listener: MiniAppsEventListener<E>,
+): StopListening {
+  singletonEmitter().on(event, listener);
+  return () => off(event, listener);
+}

package/src/bridge/events/onTelegramEvent.ts

@@ -0,0 +1,83 @@
+import { json, string } from '~/parsing/index.js';
+
+/**
+ * Extracts event data from native application event.
+ */
+const eventDataJson = json<{ eventType: string; eventData?: unknown }>({
+  eventType: string(),
+  eventData: (value) => value,
+});
+
+/**
+ * Emits event sent from Telegram native application like it was sent in
+ * default web environment between 2 iframes. It dispatches new MessageEvent
+ * and expects it to be handled via `window.addEventListener('message', ...)`
+ * as developer would do it to handle messages sent from parent iframe.
+ * @param eventType - event name.
+ * @param eventData - event payload.
+ */
+function emitEvent(eventType: string, eventData: unknown): void {
+  window.dispatchEvent(new MessageEvent('message', {
+    data: JSON.stringify({ eventType, eventData }),
+  }));
+}
+
+/**
+ * Defines special handlers by known paths, which are recognized by
+ * Telegram as ports to receive events. This function also sets special
+ * function in global window object to prevent duplicate declaration.
+ */
+function defineEventHandlers(): void {
+  const wnd: any = window;
+
+  // Prevent from duplicate event handlers definition.
+  if ('TelegramGameProxy_receiveEvent' in wnd) {
+    return;
+  }
+
+  // Iterate over each path, where "receiveEvent" function should be
+  // defined. This function is called by external environment in case,
+  // it wants to emit some event.
+  [
+    ['TelegramGameProxy_receiveEvent'], // Windows Phone.
+    ['TelegramGameProxy', 'receiveEvent'], // Desktop.
+    ['Telegram', 'WebView', 'receiveEvent'], // Android and iOS.
+  ].forEach((path) => {
+    // Path starts from "window" object.
+    let pointer = wnd;
+
+    path.forEach((item, idx, arr) => {
+      // We are on the last iteration, where function property name is passed.
+      if (idx === arr.length - 1) {
+        pointer[item] = emitEvent;
+        return;
+      }
+
+      if (!(item in pointer)) {
+        pointer[item] = {};
+      }
+      pointer = pointer[item];
+    });
+  });
+}
+
+/**
+ * Adds listener to window "message" event assuming, that this event could
+ * be sent by Telegram native application. Calls passed callback with event
+ * type and data.
+ * @param cb - callback to call.
+ */
+export function onTelegramEvent(cb: (eventType: string, eventData: unknown) => void): void {
+  // Define event handlers to make sure, message handler will work correctly.
+  defineEventHandlers();
+
+  // We expect Telegram to send us new event through "message" event.
+  window.addEventListener('message', (event) => {
+    try {
+      const { eventType, eventData } = eventDataJson.parse(event.data);
+      cb(eventType, eventData);
+    } catch {
+      // We ignore incorrect messages as they could be generated by any other code.
+    }
+  });
+}

package/src/bridge/events/once.ts

@@ -0,0 +1,18 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+import { off } from './off.js';
+import { singletonEmitter } from './singletonEmitter.js';
+
+type StopListening = () => void;
+
+/**
+ * Works the same as "on" method, but after catching the event, will remove event listener.
+ * @param event - event name.
+ * @param listener - event listener.
+ */
+export function once<E extends MiniAppsEventName>(
+  event: E,
+  listener: MiniAppsEventListener<E>,
+): StopListening {
+  singletonEmitter().once(event, listener);
+  return () => off(event, listener);
+}

package/src/bridge/events/parsers/clipboardTextReceived.ts

@@ -0,0 +1,26 @@
+import { json, string } from '~/parsing/index.js';
+import type { RequestId } from '~/types/index.js';
+
+export interface ClipboardTextReceivedPayload {
+  /**
+   * Passed during the `web_app_read_text_from_clipboard` method invocation `req_id` value.
+   */
+  req_id: RequestId;
+
+  /**
+   * Data extracted from the clipboard. The returned value will have the type `string` only in
+   * the case, application has access to the clipboard.
+   */
+  data?: string | null;
+}
+
+export function clipboardTextReceived() {
+  return json<ClipboardTextReceivedPayload>({
+    req_id: string(),
+    data: (value) => (
+      value === null
+        ? value
+        : string().optional().parse(value)
+    ),
+  });
+}