@tma.js/bridge 1.3.2

package/src/events/subscribe.ts

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

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

@@ -0,0 +1,44 @@
+import { log as utilLog } from '@tma.js/logger';
+
+let currentDebug = false;
+let currentTargetOrigin = 'https://web.telegram.org';
+
+/**
+ * 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 {
+  currentDebug = value;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Logs message in case, debug mode is enabled.
+ * @param level - log level
+ * @param args - values to print.
+ */
+export const log: typeof utilLog = (level, ...args) => {
+  if (currentDebug) {
+    utilLog(level, '[Bridge]', ...args);
+  }
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+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/haptic.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic type which creates new types of haptic feedback.
+ */
+type CreateHapticFeedbackParams<T extends string, P> = { type: T } & P;
+
+/**
+ * Style of impact occurred haptic event.
+ * - `light`, indicates a collision between small or lightweight UI objects,
+ * - `medium`, indicates a collision between medium-sized or medium-weight UI objects,
+ * - `heavy`, indicates a collision between large or heavyweight UI objects,
+ * - `rigid`, indicates a collision between hard or inflexible UI objects,
+ * - `soft`, indicates a collision between soft or flexible UI objects.
+ */
+export type ImpactHapticFeedbackStyle =
+  | 'light'
+  | 'medium'
+  | 'heavy'
+  | 'rigid'
+  | 'soft';
+
+/**
+ * Type of notification occurred type event.
+ * - `error`, indicates that a task or action has failed,
+ * - `success`, indicates that a task or action has completed successfully,
+ * - `warning`, indicates that a task or action produced a warning.
+ */
+export type NotificationHapticFeedbackType = 'error' | 'success' | 'warning';
+
+/**
+ * `impactOccurred` haptic feedback.
+ */
+export type ImpactHapticFeedbackParams = CreateHapticFeedbackParams<'impact', {
+  impact_style: ImpactHapticFeedbackStyle;
+}>;
+
+/**
+ * `notificationOccurred` haptic feedback.
+ */
+export type NotificationHapticFeedbackParams = CreateHapticFeedbackParams<'notification', {
+  notification_type: NotificationHapticFeedbackType;
+}>;
+
+/**
+ * `selectionChanged` haptic feedback.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type SelectionHapticFeedbackParams = CreateHapticFeedbackParams<'selection_change', {}>;
+
+export type AnyHapticFeedbackParams =
+  | ImpactHapticFeedbackParams
+  | NotificationHapticFeedbackParams
+  | SelectionHapticFeedbackParams;

package/src/methods/index.ts

@@ -0,0 +1,5 @@
+export type * from './haptic.js';
+export type * from './invoke-custom-method.js';
+export type * from './params.js';
+export type * from './popup.js';
+export * from './postEvent.js';

package/src/methods/invoke-custom-method.ts

@@ -0,0 +1,25 @@
+import type { RequestId } from '../shared.js';
+
+interface CreateInvokeCustomMethodParams<M extends string, Params extends object> {
+  /**
+   * Unique request identifier.
+   */
+  req_id: RequestId;
+
+  /**
+   * Method name.
+   */
+  method: M;
+
+  /**
+   * Method specific parameters.
+   */
+  params: Params;
+}
+
+export type AnyInvokeCustomMethodParams =
+  | CreateInvokeCustomMethodParams<'deleteStorageValues', { keys: string | string[] }>
+  | CreateInvokeCustomMethodParams<'getStorageValues', { keys: string | string[] }>
+  | CreateInvokeCustomMethodParams<'getStorageKeys', {}>
+  | CreateInvokeCustomMethodParams<'saveStorageValue', { key: string, value: string }>
+  | CreateInvokeCustomMethodParams<string, any>;

package/src/methods/params.ts

@@ -0,0 +1,245 @@
+import type { RGB } from '@tma.js/colors';
+import type { IsNever, Not, UnionKeys } from '@tma.js/util-types';
+
+import type { PopupParams } from './popup.js';
+import type { AnyHapticFeedbackParams } from './haptic.js';
+import type { RequestId } from '../shared.js';
+import type { AnyInvokeCustomMethodParams } from './invoke-custom-method.js';
+
+/**
+ * Color key which could be used tot update header color.
+ */
+export type HeaderColorKey = 'bg_color' | 'secondary_bg_color';
+
+type CreateParams<P = never, SupportCheckKey extends UnionKeys<P> = never> = {
+  params: P;
+  supportCheckKey: SupportCheckKey;
+};
+
+/**
+ * Describes list of events and their parameters that could be posted by
+ * Bridge.
+ * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods
+ */
+export interface MethodsParams {
+  /**
+   * Notifies parent iframe about current frame is ready.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#iframe_ready
+   * @since 6.0
+   */
+  iframe_ready: CreateParams;
+
+  /**
+   * Closes WebApp.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_close
+   * @since 6.0
+   */
+  web_app_close: CreateParams;
+
+  /**
+   * Closes QR scanner.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_close_scan_qr_popup
+   * @since 6.4
+   */
+  web_app_close_scan_qr_popup: CreateParams;
+
+  /**
+   * Sends data to bot.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_data_send
+   * @since 6.0
+   */
+  web_app_data_send: CreateParams<{ data: string }>;
+
+  /**
+   * Expands Web App.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_expand
+   * @since 6.0
+   */
+  web_app_expand: CreateParams;
+
+  /**
+   * Invokes custom method.
+   * @since 6.9
+   */
+  web_app_invoke_custom_method: CreateParams<AnyInvokeCustomMethodParams>;
+
+  /**
+   * Opens new invoice.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_invoice
+   * @since 6.1
+   */
+  web_app_open_invoice: CreateParams<{ slug: string }>;
+
+  /**
+   * Opens link in default browser. Doesn't close application.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_link
+   * @since 6.0
+   */
+  web_app_open_link: CreateParams<{
+    url: string,
+
+    // TODO: Add to docs.
+    /**
+     * Link will be opened in Instant View mode if possible.
+     * @see https://instantview.telegram.org/
+     * @since 6.4
+     */
+    try_instant_view?: boolean;
+  }, 'try_instant_view'>;
+
+  /**
+   * Opens new popup.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_popup
+   * @since 6.2
+   */
+  web_app_open_popup: CreateParams<PopupParams>;
+
+  /**
+   * Opens QR scanner.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_scan_qr_popup
+   * @since 6.4
+   */
+  web_app_open_scan_qr_popup: CreateParams<{ text?: string }>;
+
+  /**
+   * Opens link which has format like "https://t.me/*".
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_open_tg_link
+   * @since 6.1
+   */
+  web_app_open_tg_link: CreateParams<{ path_full: string }>;
+
+  /**
+   * Reads text from clipboard.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_read_text_from_clipboard
+   * @since 6.4
+   */
+  web_app_read_text_from_clipboard: CreateParams<{ req_id: RequestId }>;
+
+  /**
+   * Notifies Telegram about current application is ready to be shown.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_ready
+   * @since 6.0
+   */
+  web_app_ready: CreateParams;
+
+  /**
+   * Requests access to current user's phone.
+   * @since 6.9
+   */
+  web_app_request_phone: CreateParams;
+
+  /**
+   * Requests current theme from Telegram.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_request_theme
+   * @since 6.0
+   */
+  web_app_request_theme: CreateParams;
+
+  /**
+   * Requests current viewport information from Telegram.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_request_viewport
+   * @since 6.0
+   */
+  web_app_request_viewport: CreateParams;
+
+  /**
+   * Requests write message access to current user.
+   * @since 6.9
+   */
+  web_app_request_write_access: CreateParams;
+
+  /**
+   * Updates current background color.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_set_background_color
+   * @since 6.1
+   */
+  web_app_set_background_color: CreateParams<{ color: string }>;
+
+  /**
+   * Updates current header color.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_set_header_color
+   * @since 6.1
+   */
+  web_app_set_header_color: CreateParams<
+    | { color_key: HeaderColorKey }
+    | {
+    /**
+     * @since 6.9
+     */
+    color: RGB
+  }, 'color'>;
+
+  /**
+   * Updates current information about back button.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_back_button
+   * @since 6.1
+   */
+  web_app_setup_back_button: CreateParams<{ is_visible: boolean }>;
+
+  /**
+   * Changes current closing confirmation requirement status.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_closing_behavior
+   * @since 6.0
+   */
+  web_app_setup_closing_behavior: CreateParams<{ need_confirmation: boolean }>;
+
+  /**
+   * Updates current information about main button.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_setup_main_button
+   * @since 6.0
+   */
+  web_app_setup_main_button: CreateParams<{
+    is_visible?: boolean;
+    is_active?: boolean;
+    is_progress_visible?: boolean;
+    text?: string;
+    color?: string;
+    text_color?: string;
+  }>;
+
+  /**
+   * Generates haptic feedback event.
+   * @see https://docs.telegram-mini-apps.com/docs/apps-communication/methods#web_app_trigger_haptic_feedback
+   * @since 6.1
+   */
+  web_app_trigger_haptic_feedback: CreateParams<AnyHapticFeedbackParams>;
+}
+
+/**
+ * Any post-available event name.
+ */
+export type MethodName = keyof MethodsParams;
+
+/**
+ * Returns parameters for specified post-available event.
+ */
+export type MethodParams<E extends MethodName> = MethodsParams[E]['params'];
+
+/**
+ * Returns true in case, method has parameters.
+ */
+export type MethodHasParams<M extends MethodName> = Not<IsNever<MethodParams<M>>>;
+
+/**
+ * Any post-available event name which does not require arguments.
+ */
+export type EmptyMethodName = {
+  [E in MethodName]: IsNever<MethodParams<E>> extends true ? E : never;
+}[MethodName];
+
+/**
+ * Any post-available event name which require arguments.
+ */
+export type NonEmptyMethodName = Exclude<MethodName, EmptyMethodName>;
+
+/**
+ * Method names which could be used in supportsParam method.
+ */
+export type HasCheckSupportMethodName = {
+  [E in MethodName]: IsNever<MethodsParams[E]['supportCheckKey']> extends true ? never : E;
+}[MethodName];
+
+/**
+ * Method parameter which can be checked via support method.
+ */
+export type HasCheckSupportMethodParam<M extends HasCheckSupportMethodName> = MethodsParams[M]['supportCheckKey'];

package/src/methods/popup.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+   */
+  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.
+   */
+  buttons: PopupButton[];
+}
+
+/**
+ * Describes the native popup button.
+ * @see https://core.telegram.org/bots/webapps#popupbutton
+ */
+export type PopupButton = {
+  /**
+   * Identifier of the button, 0-64 characters.
+   */
+  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/methods/postEvent.ts

@@ -0,0 +1,103 @@
+import {
+  isIframe,
+  hasExternalNotify,
+  hasWebviewProxy,
+} from '../env.js';
+import { targetOrigin as globalTargetOrigin } from '../globals.js';
+
+import type {
+  EmptyMethodName,
+  MethodName,
+  MethodParams,
+  NonEmptyMethodName,
+} from './params.js';
+
+interface PostEventOptions {
+  /**
+   * Origin used while posting message. This option is only used in case,
+   * current environment is browser (Web version of Telegram) and could
+   * be used for test purposes.
+   * @default 'https://web.telegram.org'
+   */
+  targetOrigin?: string;
+}
+
+export type PostEvent = typeof postEvent;
+
+/**
+ * Sends event to native application which launched Web App. This function
+ * accepts only events, which require arguments.
+ * @param eventType - event name.
+ * @param params - event parameters.
+ * @param options - posting options.
+ * @throws {Error} Bridge could not determine current
+ * environment and possible way to send event.
+ */
+export function postEvent<E extends NonEmptyMethodName>(
+  eventType: E,
+  params: MethodParams<E>,
+  options?: PostEventOptions,
+): void;
+
+/**
+ * Sends event to native application which launched Web App. This function
+ * accepts only events, which require arguments.
+ * @param eventType - event name.
+ * @param options - posting options.
+ * @throws {Error} Bridge could not determine current
+ * environment and possible way to send event.
+ */
+export function postEvent(eventType: EmptyMethodName, options?: PostEventOptions): void;
+
+export function postEvent(
+  eventType: MethodName,
+  paramsOrOptions?: MethodParams<MethodName> | PostEventOptions,
+  options?: PostEventOptions,
+): void {
+  let postOptions: PostEventOptions = {};
+  let eventData: any;
+
+  if (paramsOrOptions === undefined && options === undefined) {
+    // Parameters and options were not passed.
+    postOptions = {};
+  } else if (paramsOrOptions !== undefined && options !== undefined) {
+    // Both parameters and options passed.
+    postOptions = options;
+    eventData = paramsOrOptions;
+  } else if (paramsOrOptions !== undefined) {
+    // Only parameters were passed.
+    if ('targetOrigin' in paramsOrOptions) {
+      postOptions = paramsOrOptions;
+    } else {
+      eventData = paramsOrOptions;
+    }
+  }
+  const { targetOrigin = globalTargetOrigin() } = postOptions;
+
+  // Telegram Web.
+  if (isIframe()) {
+    window.parent.postMessage(JSON.stringify({
+      eventType,
+      eventData,
+    }), targetOrigin);
+    return;
+  }
+
+  // Telegram for Windows Phone or Android.
+  if (hasExternalNotify(window)) {
+    window.external.notify(JSON.stringify({ eventType, eventData }));
+    return;
+  }
+
+  // Telegram for iOS and macOS.
+  if (hasWebviewProxy(window)) {
+    window.TelegramWebviewProxy.postEvent(eventType, JSON.stringify(eventData));
+    return;
+  }
+
+  // Otherwise current environment is unknown, and we are not able to send
+  // event.
+  throw new Error(
+    'Unable to determine current environment and possible way to send event.',
+  );
+}