@tma.js/bridge 1.4.1 → 2.0.1

package/src/events/events.ts

@@ -1,169 +0,0 @@
-import type {
-  EventEmitter as UtilEventEmitter,
-  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 './parsers/index.js';
-
-/**
- * Map where key is known event name, and value is its listener.
- * @see https://docs.telegram-mini-apps.com/apps-communication/events
- */
-export interface Events {
-  /**
-   * User clicked back button.
-   * @since v6.1
-   * @see https://docs.telegram-mini-apps.com/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/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/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/apps-communication/events#invoice-closed
-   */
-  invoice_closed: (payload: InvoiceClosedPayload) => void;
-
-  /**
-   * User clicked the Main Button.
-   * @see https://docs.telegram-mini-apps.com/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/apps-communication/events#phone-requested
-   */
-  phone_requested: (payload: PhoneRequestedPayload) => void;
-
-  /**
-   * Popup was closed.
-   * @param payload - event payload.
-   * @see https://docs.telegram-mini-apps.com/apps-communication/events#popup-closed
-   */
-  popup_closed: (payload: PopupClosedPayload) => void;
-
-  /**
-   * Parent iframe requested current iframe reload.
-   * @see https://docs.telegram-mini-apps.com/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/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/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/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/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/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/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/apps-communication/events#write-access-requested
-   */
-  write_access_requested: (payload: WriteAccessRequestedPayload) => void;
-}
-
-/**
- * Any known event name.
- */
-export type EventName = keyof 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

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

package/src/events/off.ts

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

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

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

@@ -1,16 +0,0 @@
-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/parsers/clipboardTextReceived.ts

@@ -1,27 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-import type { RequestId } from '../../shared.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)
-    ),
-  });
-}

package/src/events/parsers/customMethodInvoked.ts

@@ -1,26 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-import type { RequestId } from '../../shared.js';
-
-export interface CustomMethodInvokedPayload<R = unknown> {
-  /**
-   * Unique identifier of this invocation.
-   */
-  req_id: RequestId;
-  /**
-   * Method invocation successful result.
-   */
-  result?: R;
-  /**
-   * Method invocation error code.
-   */
-  error?: string;
-}
-
-export function customMethodInvoked() {
-  return json<CustomMethodInvokedPayload>({
-    req_id: string(),
-    result: (value) => value,
-    error: string().optional(),
-  });
-}

package/src/events/parsers/index.ts

@@ -1,9 +0,0 @@
-export * from './clipboardTextReceived.js';
-export * from './customMethodInvoked.js';
-export * from './invoiceClosed.js';
-export * from './phoneRequested.js';
-export * from './popupClosed.js';
-export * from './qrTextReceived.js';
-export * from './theme-changed.js';
-export * from './viewportChanged.js';
-export * from './writeAccessRequested.js';

package/src/events/parsers/invoiceClosed.ts

@@ -1,26 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-export type InvoiceStatus =
-  | 'paid'
-  | 'failed'
-  | 'pending'
-  | 'cancelled'
-  | string;
-
-export interface InvoiceClosedPayload {
-  /**
-   * Passed during the `web_app_open_invoice` method invocation `slug` value.
-   */
-  slug: string;
-  /**
-   * Invoice status
-   */
-  status: InvoiceStatus;
-}
-
-export function invoiceClosed() {
-  return json<InvoiceClosedPayload>({
-    slug: string(),
-    status: string(),
-  });
-}

package/src/events/parsers/phoneRequested.ts

@@ -1,14 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-export type PhoneRequestedStatus = 'sent' | string;
-
-export interface PhoneRequestedPayload {
-  /**
-   * Request status.
-   */
-  status: PhoneRequestedStatus;
-}
-
-export function phoneRequested() {
-  return json<PhoneRequestedPayload>({ status: string() });
-}

package/src/events/parsers/popupClosed.ts

@@ -1,19 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-export interface PopupClosedPayload {
-  /**
-   * Identifier of the clicked button. In case, the popup was closed without clicking any button,
-   * this property will be omitted.
-   */
-  button_id?: string;
-}
-
-export function popupClosed() {
-  return json<PopupClosedPayload>({
-    button_id: (value) => (
-      value === null || value === undefined
-        ? undefined
-        : string().parse(value)
-    ),
-  });
-}

package/src/events/parsers/qrTextReceived.ts

@@ -1,14 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-export interface QrTextReceivedPayload {
-  /**
-   * Data extracted from the QR.
-   */
-  data?: string;
-}
-
-export function qrTextReceived() {
-  return json<QrTextReceivedPayload>({
-    data: string().optional(),
-  });
-}

package/src/events/parsers/theme-changed.ts

@@ -1,58 +0,0 @@
-import { json, rgb, toRecord } from '@tma.js/parsing';
-import type { RGB } from '@tma.js/colors';
-
-export interface ThemeChangedPayload {
-  /**
-   * Map where the key is a theme stylesheet key and value is  the corresponding color in
-   * `#RRGGBB` format.
-   */
-  theme_params: {
-    /**
-     * @since v6.10
-     */
-    accent_text_color?: RGB;
-    bg_color?: RGB;
-    button_color?: RGB;
-    button_text_color?: RGB;
-    /**
-     * @since v6.10
-     */
-    destructive_text_color?: RGB;
-    /**
-     * @since v6.10
-     */
-    header_bg_color?: RGB;
-    hint_color?: RGB;
-    link_color?: RGB;
-    secondary_bg_color?: RGB;
-    /**
-     * @since v6.10
-     */
-    section_bg_color?: RGB;
-    /**
-     * @since v6.10
-     */
-    section_header_text_color?: RGB;
-    /**
-     * @since v6.10
-     */
-    subtitle_text_color?: RGB;
-    text_color?: RGB;
-    [key: string]: RGB | undefined; // Future unknown palette keys.
-  };
-}
-
-export function themeChanged() {
-  return json<ThemeChangedPayload>({
-    theme_params: (value) => {
-      const parser = rgb().optional();
-
-      return Object
-        .entries(toRecord(value))
-        .reduce<Partial<Record<string, RGB>>>((acc, [k, v]) => {
-          acc[k] = parser.parse(v);
-          return acc;
-        }, {});
-    },
-  });
-}

package/src/events/parsers/viewportChanged.ts

@@ -1,33 +0,0 @@
-import { boolean, json, number } from '@tma.js/parsing';
-
-export interface ViewportChangedPayload {
-  /**
-   * The viewport height.
-   */
-  height: number;
-  /**
-   * The viewport width.
-   */
-  width: number;
-  /**
-   * Is the viewport currently expanded.
-   */
-  is_expanded: boolean;
-  /**
-   * Is the viewport current state stable and not going to change in the next moment.
-   */
-  is_state_stable: boolean;
-}
-
-export function viewportChanged() {
-  return json<ViewportChangedPayload>({
-    height: number(),
-    width: (value) => (
-      value === null || value === undefined
-        ? window.innerWidth
-        : number().parse(value)
-    ),
-    is_state_stable: boolean(),
-    is_expanded: boolean(),
-  });
-}

package/src/events/parsers/writeAccessRequested.ts

@@ -1,14 +0,0 @@
-import { json, string } from '@tma.js/parsing';
-
-export type WriteAccessRequestedStatus = 'allowed' | string;
-
-export interface WriteAccessRequestedPayload {
-  /**
-   * Request status.
-   */
-  status: WriteAccessRequestedStatus;
-}
-
-export function writeAccessRequested() {
-  return json<WriteAccessRequestedPayload>({ status: string() });
-}

package/src/events/subscribe.ts

@@ -1,16 +0,0 @@
-import { singletonEmitter } from './emitter.js';
-import { unsubscribe } from './unsubscribe.js';
-
-import type { GlobalEventListener } from './events.js';
-
-type StopListening = () => void;
-
-/**
- * Subscribes to all events sent from the native Telegram application.
- * Returns function used to remove added event listener.
- * @param listener - event listener.
- */
-export function subscribe(listener: GlobalEventListener): StopListening {
-  singletonEmitter().subscribe(listener);
-  return () => unsubscribe(listener);
-}

package/src/events/unsubscribe.ts

@@ -1,11 +0,0 @@
-import { singletonEmitter } from './emitter.js';
-
-import type { GlobalEventListener } from './events.js';
-
-/**
- * Removes global event listener.
- * @param listener - event listener.
- */
-export function unsubscribe(listener: GlobalEventListener): void {
-  singletonEmitter().unsubscribe(listener);
-}

package/src/globals.ts

@@ -1,38 +0,0 @@
-import { Logger } from '@tma.js/logger';
-
-let currentTargetOrigin = 'https://web.telegram.org';
-
-export const logger = new Logger('[Bridge]', false);
-
-/**
- * Sets new debug mode. Enabling debug mode leads to printing
- * additional messages in console, related to the processes
- * inside the package.
- * @param value - should debug mode be enabled.
- */
-export function setDebug(value: boolean): void {
-  if (value) {
-    logger.enable();
-    return;
-  }
-  logger.disable();
-}
-
-/**
- * Sets new global targetOrigin, used by `postEvent` method.
- * Default value is "https://web.telegram.org". You don't need to
- * use this method until you know what you are doing.
- *
- * This method could be used for test purposes.
- * @param value - new target origin.
- */
-export function setTargetOrigin(value: string): void {
-  currentTargetOrigin = value;
-}
-
-/**
- * Returns current global target origin.
- */
-export function targetOrigin(): string {
-  return currentTargetOrigin;
-}

package/src/index.ts

@@ -1,7 +0,0 @@
-export * from './errors/index.js';
-export * from './events/index.js';
-export * from './methods/index.js';
-export * from './env.js';
-export { setDebug, setTargetOrigin } from './globals.js';
-export * from './request.js';
-export * from './supports.js';

package/src/methods/createPostEvent.ts

@@ -1,39 +0,0 @@
-import { isRecord, type Version } from '@tma.js/utils';
-
-import { supports } from '../supports.js';
-import { MethodUnsupportedError, ParameterUnsupportedError } from '../errors/index.js';
-import { postEvent, type PostEvent } from './index.js';
-
-/**
- * Creates function which checks if specified method and parameters are supported. In case,
- * method or parameters are unsupported, an error will be thrown.
- * @param version - Telegram Mini Apps version.
- * @throws {MethodUnsupportedError} Method is unsupported.
- * @throws {ParameterUnsupportedError} Method parameter is unsupported.
- */
-export function createPostEvent(version: Version): PostEvent {
-  return (method: any, params: any) => {
-    // Firstly, check if method itself is supported.
-    if (!supports(method, version)) {
-      throw new MethodUnsupportedError(method, version);
-    }
-
-    // Method could use parameters, which are supported only in specific versions of Telegram
-    // Mini Apps.
-    if (isRecord(params)) {
-      let validateParam: string | undefined;
-
-      if (method === 'web_app_open_link' && 'try_instant_view' in params) {
-        validateParam = 'try_instant_view';
-      } else if (method === 'web_app_set_header_color' && 'color' in params) {
-        validateParam = 'color';
-      }
-
-      if (validateParam && !supports(method, validateParam, version)) {
-        throw new ParameterUnsupportedError(method, validateParam, version);
-      }
-    }
-
-    return postEvent(method, params);
-  };
-}