@tma.js/bridge 1.3.2

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tma.js/bridge",
+  "version": "1.3.2",
+  "description": "Communication layer between Telegram and frontend applications.",
+  "author": "Vladislav Kibenko <wolfram.deus@gmail.com>",
+  "homepage": "https://github.com/Telegram-Mini-Apps/tma.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Telegram-Mini-Apps/tma.js.git",
+    "directory": "packages/bridge"
+  },
+  "bugs": {
+    "url": "https://github.com/Telegram-Mini-Apps/tma.js/issues"
+  },
+  "keywords": [
+    "telegram-mini-apps",
+    "typescript",
+    "bridge",
+    "webview"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/lib/index.cjs",
+  "browser": "dist/lib/browser.js",
+  "module": "dist/lib/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/lib/index.mjs",
+      "require": "./dist/lib/index.cjs",
+      "default": "./dist/lib/index.cjs"
+    },
+    "./*": {
+      "types": "./dist/types/*.d.ts",
+      "import": "./dist/lib/*.mjs",
+      "require": "./dist/lib/*.cjs",
+      "default": "./dist/lib/*.cjs"
+    }
+  },
+  "dependencies": {
+    "@tma.js/utils": "0.5.2",
+    "@tma.js/logger": "0.0.1",
+    "@tma.js/event-emitter": "0.0.2",
+    "@tma.js/colors": "0.0.2",
+    "@tma.js/parsing": "0.0.2",
+    "@tma.js/util-types": "0.0.2"
+  },
+  "devDependencies": {
+    "tsconfig": "0.0.2",
+    "eslint-config-custom": "0.1.0",
+    "jest-config-custom": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint -c .eslintrc.cjs src/**/* __tests__/**/*",
+    "build": "rimraf dist && rollup --config rollup.config.js"
+  }
+}

package/src/env.ts

@@ -0,0 +1,49 @@
+import { isRecord } from '@tma.js/utils';
+
+type AnyFunc = (...args: unknown[]) => unknown;
+
+type WithExternalNotify<T> = T & {
+  external: { notify: AnyFunc }
+};
+
+type WithWebviewProxy<T> = T & {
+  TelegramWebviewProxy: {
+    postEvent: AnyFunc;
+  }
+};
+
+/**
+ * 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';
+}
+
+/**
+ * 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';
+}
+
+/**
+ * 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/events/emitter.ts

@@ -0,0 +1,125 @@
+import { EventEmitter as UtilEventEmitter } from '@tma.js/event-emitter';
+import { string } from '@tma.js/parsing';
+
+import { log } from '../globals.js';
+import {
+  clipboardTextReceivedPayload,
+  customMethodInvokedPayload,
+  invoiceClosedPayload,
+  phoneRequestedPayload,
+  popupClosedPayload,
+  qrTextReceivedPayload,
+  themeChangedPayload,
+  viewportChangedPayload,
+  writeAccessRequestedPayload,
+} from './parsing.js';
+import { onTelegramEvent } from './onTelegramEvent.js';
+
+import type { EventEmitter, EventName } from './events.js';
+
+const CACHED_EMITTER = '__telegram-cached-emitter__';
+
+/**
+ * Returns event emitter which could be safely used, to process events from
+ * Telegram native application.
+ */
+export function createEmitter(): EventEmitter {
+  const emitter: EventEmitter = new UtilEventEmitter();
+  const emit: EventEmitter['emit'] = (event: any, ...data: any[]) => {
+    log('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-Web-Apps/tma.js/issues/10
+  window.addEventListener('resize', () => {
+    emitter.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: EventName | string, eventData): void => {
+    log('log', 'Received raw event:', eventType, eventData);
+
+    try {
+      switch (eventType) {
+        case 'viewport_changed':
+          return emit(eventType, viewportChangedPayload.parse(eventData));
+
+        case 'theme_changed':
+          return emit(eventType, themeChangedPayload.parse(eventData));
+
+        case 'popup_closed':
+          // FIXME: Payloads are different on different platforms.
+          //  Issue: https://github.com/Telegram-Web-Apps/tma.js/issues/2
+          if (
+            // Sent on desktop.
+            eventData === undefined
+            // Sent on iOS.
+            || eventData === null
+          ) {
+            return emit(eventType, {});
+          }
+          return emit(eventType, popupClosedPayload.parse(eventData));
+
+        case 'set_custom_style':
+          return emit(eventType, string().parse(eventData));
+
+        case 'qr_text_received':
+          return emit(eventType, qrTextReceivedPayload.parse(eventData));
+
+        case 'clipboard_text_received':
+          return emit(eventType, clipboardTextReceivedPayload.parse(eventData));
+
+        case 'invoice_closed':
+          return emit(eventType, invoiceClosedPayload.parse(eventData));
+
+        case 'phone_requested':
+          return emit('phone_requested', phoneRequestedPayload.parse(eventData));
+
+        case 'custom_method_invoked':
+          return emit('custom_method_invoked', customMethodInvokedPayload.parse(eventData));
+
+        case 'write_access_requested':
+          return emit('write_access_requested', writeAccessRequestedPayload.parse(eventData));
+
+        // Events which have no parameters.
+        case 'main_button_pressed':
+        case 'back_button_pressed':
+        case 'settings_button_pressed':
+        case 'scan_qr_popup_closed':
+          return emit(eventType);
+
+        // All other event listeners will receive unknown type of data.
+        default:
+          return emit(eventType as any, eventData);
+      }
+    } catch (cause) {
+      log('error', 'Error processing event:', cause);
+    }
+  });
+
+  return emitter;
+}
+
+/**
+ * Returns singleton instance of bridge EventEmitter. Also, defines
+ * Telegram event handlers.
+ */
+export function singletonEmitter(): EventEmitter {
+  const wnd: any = window;
+  const cachedEmitter = wnd[CACHED_EMITTER];
+
+  if (cachedEmitter === undefined) {
+    wnd[CACHED_EMITTER] = createEmitter();
+  }
+
+  return wnd[CACHED_EMITTER];
+}

package/src/events/events.ts

@@ -0,0 +1,152 @@
+import type {
+  EventEmitter as UtilEventEmitter,
+  EventName as UtilEventName,
+  EventListener as UtilEventListener,
+  EventParams as UtilEventParams, AnySubscribeListener,
+} from '@tma.js/event-emitter';
+import type { IsNever, Not } from '@tma.js/util-types';
+
+import type {
+  ClipboardTextReceivedPayload,
+  CustomMethodInvokedPayload,
+  InvoiceClosedPayload,
+  PhoneRequestedPayload,
+  PopupClosedPayload,
+  QrTextReceivedPayload,
+  ThemeChangedPayload,
+  ViewportChangedPayload,
+  WriteAccessRequestedPayload,
+} from './payloads.js';
+
+/**
+ * Map where key is known event name, and value is its listener.
+ * @see Documentation https://docs.telegram-mini-apps.com/docs/apps-communication/events
+ */
+export interface Events {
+  /**
+   * User clicked back button.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#back_button_pressed
+   */
+  back_button_pressed: () => void;
+
+  /**
+   * Text was extracted from clipboard.
+   * @param payload - event information.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#clipboard_text_received
+   */
+  clipboard_text_received: (payload: ClipboardTextReceivedPayload) => void;
+
+  /**
+   * Being called whenever custom method was invoked.
+   * @param payload - event payload.
+   * @since 6.9
+   */
+  custom_method_invoked: (payload: CustomMethodInvokedPayload) => void;
+
+  /**
+   * Invoice was closed.
+   * @param payload - invoice close information.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#invoice_closed
+   */
+  invoice_closed: (payload: InvoiceClosedPayload) => void;
+
+  /**
+   * User clicked main button.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#main_button_pressed
+   */
+  main_button_pressed: () => void;
+
+  /**
+   * Application received phone access request status.
+   * @param payload - event payload. - event payload.
+   * @since 6.9
+   */
+  phone_requested: (payload: PhoneRequestedPayload) => void;
+
+  /**
+   * Popup was closed.
+   * @param payload - popup close information.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#main_button_pressed
+   */
+  popup_closed: (payload: PopupClosedPayload) => void;
+
+  /**
+   * Data from QR was extracted.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#qr_text_received
+   */
+  qr_text_received: (payload: QrTextReceivedPayload) => void;
+
+  /**
+   * QR scanner was closed.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#scan_qr_popup_closed
+   */
+  scan_qr_popup_closed: () => void;
+
+  /**
+   * Telegram requested to update current application style.
+   * @param html - `style` tag inner HTML.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#set_custom_style
+   */
+  set_custom_style: (html: string) => void;
+
+  /**
+   * Occurs when the Settings item in context menu is pressed.
+   * @see https://docs.telegram-mini-apps.com/docs/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 - theme information.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#theme_changed
+   */
+  theme_changed: (payload: ThemeChangedPayload) => void;
+
+  /**
+   * Viewport was changed.
+   * @param payload - viewport information.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/events#viewport_changed
+   */
+  viewport_changed: (payload: ViewportChangedPayload) => void;
+
+  /**
+   * Application received write access requests status.
+   * @param payload - event payload.
+   * @since 6.9
+   */
+  write_access_requested: (payload: WriteAccessRequestedPayload) => void;
+}
+
+/**
+ * Any known event name.
+ */
+export type EventName = UtilEventName<Events>;
+
+/**
+ * Parameters of specified event.
+ */
+export type EventParams<E extends EventName> = UtilEventParams<Events[E]>[0];
+
+/**
+ * Returns event listener for specified event name.
+ */
+export type EventListener<E extends EventName> =
+  UtilEventListener<Events[E]>;
+
+/**
+ * Event emitter, based describe events map.
+ */
+export type EventEmitter = UtilEventEmitter<Events>;
+
+/**
+ * Returns true in case, event has parameters.
+ */
+export type EventHasParams<E extends EventName> = Not<IsNever<EventParams<E>>>;
+
+/**
+ * Event listener used in `subscribe` and `unsubscribe` functions.
+ */
+export type GlobalEventListener =
+  | AnySubscribeListener<Events>
+  | ((event: string, data: unknown) => void);

package/src/events/index.ts

@@ -0,0 +1,7 @@
+export type * from './events.js';
+export * from './off.js';
+export * from './on.js';
+export * from './once.js';
+export type * from './payloads.js';
+export * from './subscribe.js';
+export * from './unsubscribe.js';

package/src/events/off.ts

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

package/src/events/on.ts

@@ -0,0 +1,17 @@
+import { singletonEmitter } from './emitter.js';
+import { off } from './off.js';
+
+import type { EventName, EventListener } from './events.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 EventName>(event: E, listener: EventListener<E>): StopListening {
+  singletonEmitter().on(event, listener);
+  return () => off(event, listener);
+}

package/src/events/onTelegramEvent.ts

@@ -0,0 +1,83 @@
+import { json, string } from '@tma.js/parsing';
+
+/**
+ * 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/events/once.ts

@@ -0,0 +1,16 @@
+import { singletonEmitter } from './emitter.js';
+import { off } from './off.js';
+
+import type { EventName, EventListener } from './events.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 EventName>(event: E, listener: EventListener<E>): StopListening {
+  singletonEmitter().once(event, listener);
+  return () => off(event, listener);
+}

package/src/events/parsing.ts

@@ -0,0 +1,94 @@
+import {
+  number,
+  string,
+  boolean,
+  json,
+  rgb,
+} from '@tma.js/parsing';
+
+import type {
+  ClipboardTextReceivedPayload, CustomMethodInvokedPayload,
+  InvoiceClosedPayload, PhoneRequestedPayload,
+  PopupClosedPayload, QrTextReceivedPayload,
+  ThemeChangedPayload,
+  ViewportChangedPayload, WriteAccessRequestedPayload,
+} from './payloads.js';
+
+function isNullOrUndefined(value: unknown): boolean {
+  return value === null || value === undefined;
+}
+
+/**
+ * Parses incoming value as ThemeChangedPayload.
+ */
+export const themeChangedPayload = json<ThemeChangedPayload>({
+  theme_params: json<ThemeChangedPayload['theme_params']>({
+    bg_color: rgb().optional(),
+    text_color: rgb().optional(),
+    hint_color: rgb().optional(),
+    link_color: rgb().optional(),
+    button_color: rgb().optional(),
+    button_text_color: rgb().optional(),
+    secondary_bg_color: rgb().optional(),
+  }),
+});
+
+/**
+ * Parses incoming value as ViewportChangedPayload.
+ * @param value - value to parse.
+ */
+export const viewportChangedPayload = json<ViewportChangedPayload>({
+  height: number(),
+  width: number().optional(isNullOrUndefined).default(() => window.innerWidth),
+  is_state_stable: boolean(),
+  is_expanded: boolean(),
+});
+
+/**
+ * Parses incoming value as PopupClosedPayload.
+ */
+export const popupClosedPayload = json<PopupClosedPayload>({
+  button_id: string().optional(isNullOrUndefined),
+});
+
+/**
+ * Parses incoming value as QrTextReceivedPayload.
+ */
+export const qrTextReceivedPayload = json<QrTextReceivedPayload>({
+  data: string().optional(),
+});
+
+/**
+ * Parses incoming value as InvoiceClosedPayload.
+ */
+export const invoiceClosedPayload = json<InvoiceClosedPayload>({
+  slug: string(),
+  status: string(),
+});
+
+/**
+ * Parses incoming value as clipboard text received payload.
+ */
+export const clipboardTextReceivedPayload = json<ClipboardTextReceivedPayload>({
+  req_id: string(),
+  data: (value) => (value === null ? value : string().optional().parse(value)),
+});
+
+/**
+ * Parses incoming value as WriteAccessRequestedPayload.
+ */
+export const writeAccessRequestedPayload = json<WriteAccessRequestedPayload>({ status: string() });
+
+/**
+ * Parses incoming value as PhoneRequestedPayload.
+ */
+export const phoneRequestedPayload = json<PhoneRequestedPayload>({ status: string() });
+
+/**
+ * Parses incoming value as CustomMethodInvokedPayload.
+ */
+export const customMethodInvokedPayload = json<CustomMethodInvokedPayload>({
+  req_id: string(),
+  result: (value) => value,
+  error: string().optional(),
+});

package/src/events/payloads.ts

@@ -0,0 +1,65 @@
+import type { RGB } from '@tma.js/colors';
+
+import type { RequestId } from '../shared.js';
+
+export interface ClipboardTextReceivedPayload {
+  req_id: RequestId;
+  data?: string | null;
+}
+
+export interface CustomMethodInvokedPayload<R = unknown> {
+  req_id: RequestId;
+  result?: R;
+  error?: string;
+}
+
+export type InvoiceStatus =
+  | 'paid'
+  | 'failed'
+  | 'pending'
+  | 'cancelled'
+  | string;
+
+export interface InvoiceClosedPayload {
+  slug: string;
+  status: InvoiceStatus;
+}
+
+export interface QrTextReceivedPayload {
+  data?: string;
+}
+
+export interface ThemeChangedPayload {
+  theme_params: {
+    bg_color?: RGB;
+    text_color?: RGB;
+    hint_color?: RGB;
+    link_color?: RGB;
+    button_color?: RGB;
+    button_text_color?: RGB;
+    secondary_bg_color?: RGB;
+  };
+}
+
+export interface ViewportChangedPayload {
+  height: number;
+  width: number;
+  is_expanded: boolean;
+  is_state_stable: boolean;
+}
+
+export interface PopupClosedPayload {
+  button_id?: string;
+}
+
+export type PhoneRequestedStatus = 'sent' | string;
+
+export interface PhoneRequestedPayload {
+  status: PhoneRequestedStatus;
+}
+
+export type WriteAccessRequestedStatus = 'allowed' | string;
+
+export interface WriteAccessRequestedPayload {
+  status: WriteAccessRequestedStatus;
+}