@tma.js/bridge 1.3.12 → 1.4.0

package/src/events/emitter.ts

@@ -95,6 +95,7 @@ export function createEmitter(): EventEmitter {
         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.

package/src/events/events.ts

@@ -1,8 +1,8 @@
 import type {
   EventEmitter as UtilEventEmitter,
-  EventName as UtilEventName,
   EventListener as UtilEventListener,
-  EventParams as UtilEventParams, AnySubscribeListener,
+  EventParams as UtilEventParams,
+  AnySubscribeListener,
 } from '@tma.js/event-emitter';
 import type { IsNever, Not } from '@tma.js/util-types';
 
@@ -74,6 +74,12 @@ export interface Events {
    */
   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.
@@ -133,7 +139,7 @@ export interface Events {
 /**
  * Any known event name.
  */
-export type EventName = UtilEventName<Events>;
+export type EventName = keyof Events;
 
 /**
  * Parameters of specified event.
@@ -143,8 +149,7 @@ 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]>;
+export type EventListener<E extends EventName> = UtilEventListener<Events[E]>;
 
 /**
  * Event emitter, based describe events map.

package/src/events/parsing.ts

@@ -33,13 +33,19 @@ const windowWidthParser = createValueParserGenerator(
  */
 export const themeChangedPayload = json<ThemeChangedPayload>({
   theme_params: json({
+    accent_text_color: rgbOptional,
     bg_color: rgbOptional,
-    text_color: rgbOptional,
-    hint_color: rgbOptional,
-    link_color: rgbOptional,
     button_color: rgbOptional,
     button_text_color: rgbOptional,
+    destructive_text_color: rgbOptional,
+    header_bg_color: rgbOptional,
+    hint_color: rgbOptional,
+    link_color: rgbOptional,
     secondary_bg_color: rgbOptional,
+    section_bg_color: rgbOptional,
+    section_header_text_color: rgbOptional,
+    subtitle_text_color: rgbOptional,
+    text_color: rgbOptional,
   }),
 });
 

package/src/events/payloads.ts

@@ -54,19 +54,28 @@ export interface QrTextReceivedPayload {
   data?: string;
 }
 
+export type ThemeParamsKey =
+  | 'accent_text_color'
+  | 'bg_color'
+  | 'button_color'
+  | 'button_text_color'
+  | 'destructive_text_color'
+  | 'header_bg_color'
+  | 'hint_color'
+  | 'link_color'
+  | 'secondary_bg_color'
+  | 'section_header_text_color'
+  | 'section_bg_color'
+  | 'subtitle_text_color'
+  | 'text_color';
+
 export interface ThemeChangedPayload {
   /**
    * Map where the key is a theme stylesheet key and value is  the corresponding color in
    * `#RRGGBB` format.
    */
   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;
+    [Key in ThemeParamsKey]?: RGB;
   };
 }
 

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './errors/index.js';
 export * from './events/index.js';
 export * from './methods/index.js';
 export * from './env.js';

package/src/methods/createPostEvent.ts

@@ -0,0 +1,39 @@
+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);
+  };
+}

package/src/methods/index.ts

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

package/src/methods/{params.ts → methods.ts}

@@ -16,22 +16,33 @@ export type HeaderColorKey = 'bg_color' | 'secondary_bg_color';
  */
 export type SwitchInlineQueryChatType = 'users' | 'bots' | 'groups' | 'channels';
 
-type CreateParams<P = never, SupportCheckKey extends UnionKeys<P> = never> = {
-  params: P;
-  supportCheckKey: SupportCheckKey;
-};
+interface CreateParams<Params = undefined, VersionedParam extends UnionKeys<Params> = never> {
+  params: Params;
+  versionedParams: VersionedParam;
+}
 
 /**
  * Describes list of events and their parameters that could be posted by Bridge.
  * @see https://docs.telegram-mini-apps.com/apps-communication/methods
  */
-export interface MethodsParams {
+export interface Methods {
   /**
    * Notifies parent iframe about the current frame is ready. This method is only used in the Web
    * version of Telegram. As a result, Mini App will receive `set_custom_style` event.
    * @see https://docs.telegram-mini-apps.com/apps-communication/methods#iframe-ready
    */
-  iframe_ready: CreateParams;
+  iframe_ready: CreateParams<{
+    /**
+     * True, if current Mini App supports native reloading.
+     */
+    reload_supported?: boolean;
+  } | undefined>;
+
+  /**
+   * Notifies parent iframe about the current iframe is going to reload.
+   * @see https://docs.telegram-mini-apps.com/apps-communication/methods#iframe-will-reload
+   */
+  iframe_will_reload: CreateParams;
 
   /**
    * Closes Mini App.
@@ -319,40 +330,44 @@ export interface MethodsParams {
 }
 
 /**
- * Any post-available event name.
+ * Any Telegram Mini Apps known method name.
  */
-export type MethodName = keyof MethodsParams;
+export type MethodName = keyof Methods;
 
 /**
  * Returns parameters for specified post-available event.
  */
-export type MethodParams<E extends MethodName> = MethodsParams[E]['params'];
+export type MethodParams<M extends MethodName> = Methods[M]['params'];
 
 /**
- * Returns true in case, method has parameters.
+ * True if specified method accepts parameters.
  */
-export type MethodHasParams<M extends MethodName> = Not<IsNever<MethodParams<M>>>;
+export type MethodAcceptParams<M extends MethodName> =
+  Not<IsNever<Exclude<MethodParams<M>, undefined>>>;
 
 /**
  * Any post-available event name which does not require arguments.
  */
 export type EmptyMethodName = {
-  [E in MethodName]: IsNever<MethodParams<E>> extends true ? E : never;
+  [M in MethodName]: undefined extends MethodParams<M> ? M : never;
 }[MethodName];
 
 /**
  * Any post-available event name which require arguments.
  */
-export type NonEmptyMethodName = Exclude<MethodName, EmptyMethodName>;
+export type NonEmptyMethodName = {
+  [M in MethodName]: MethodAcceptParams<M> extends true ? M : never;
+}[MethodName];
 
 /**
- * Method names which could be used in supportsParam method.
+ * Method names which have versioned params.
  */
-export type HasCheckSupportMethodName = {
-  [E in MethodName]: IsNever<MethodsParams[E]['supportCheckKey']> extends true ? never : E;
+export type MethodWithVersionedParams = {
+  [M in MethodName]: IsNever<Methods[M]['versionedParams']> extends true ? never : M;
 }[MethodName];
 
 /**
- * Method parameter which can be checked via support method.
+ * Method parameters which appear only in the specific Telegram Mini Apps version.
  */
-export type HasCheckSupportMethodParam<M extends HasCheckSupportMethodName> = MethodsParams[M]['supportCheckKey'];
+export type MethodVersionedParams<M extends MethodWithVersionedParams> =
+  Methods[M]['versionedParams'];

package/src/methods/postEvent.ts

@@ -9,7 +9,7 @@ import type {
   MethodName,
   MethodParams,
   NonEmptyMethodName,
-} from './params.js';
+} from './methods.js';
 
 interface PostEventOptions {
   /**

package/src/request.ts

@@ -1,24 +1,24 @@
 import { withTimeout, isRecord } from '@tma.js/utils';
-
 import type { And, If, IsNever } from '@tma.js/util-types';
 
 import { postEvent as defaultPostEvent, type PostEvent } from './methods/postEvent.js';
 import { on, type EventName, type EventParams, type EventHasParams } from './events/index.js';
 
 import type {
-  EmptyMethodName, MethodHasParams,
+  EmptyMethodName,
+  MethodAcceptParams,
   MethodName,
   MethodParams,
   NonEmptyMethodName,
-} from './methods/params.js';
+} from './methods/methods.js';
 
 /**
  * Names of methods, which require passing "req_id" parameter.
  */
-type MethodNameWithRequestId = {
-  [Method in MethodName]: If<
-    And<MethodHasParams<Method>, MethodParams<Method> extends { req_id: string } ? true : false>,
-    Method,
+type MethodWithRequestId = {
+  [M in MethodName]: If<
+    And<MethodAcceptParams<M>, MethodParams<M> extends { req_id: string } ? true : false>,
+    M,
     never
   >;
 }[MethodName];
@@ -26,10 +26,10 @@ type MethodNameWithRequestId = {
 /**
  * Names of events, which contain "req_id" parameter.
  */
-type EventNameWithRequestId = {
-  [Event in EventName]: If<
-    And<EventHasParams<Event>, EventParams<Event> extends { req_id: string } ? true : false>,
-    Event,
+type EventWithRequestId = {
+  [E in EventName]: If<
+    And<EventHasParams<E>, EventParams<E> extends { req_id: string } ? true : false>,
+    E,
     never
   >;
 }[EventName];
@@ -64,15 +64,12 @@ export interface RequestOptionsAdvanced<EventPayload> extends RequestOptions {
  * @param event - event or events to listen.
  * @param options - additional execution options.
  */
-export function request<
-  Method extends MethodNameWithRequestId,
-  Event extends EventNameWithRequestId,
->(
-  method: Method,
-  params: MethodParams<Method>,
-  event: Event | Event[],
+export function request<M extends MethodWithRequestId, E extends EventWithRequestId>(
+  method: M,
+  params: MethodParams<M>,
+  event: E | E[],
   options?: RequestOptions,
-): Promise<EventParams<Event>>;
+): Promise<EventParams<E>>;
 
 /**
  * Calls specified TWA method and captures one of the specified events. Returns promise
@@ -81,11 +78,11 @@ export function request<
  * @param event - event or events to listen.
  * @param options - additional execution options.
  */
-export function request<Method extends EmptyMethodName, Event extends EventName>(
-  method: Method,
-  event: Event | Event[],
-  options?: RequestOptionsAdvanced<EventParams<Event>>,
-): Promise<EventParams<Event>>;
+export function request<M extends EmptyMethodName, E extends EventName>(
+  method: M,
+  event: E | E[],
+  options?: RequestOptionsAdvanced<EventParams<E>>,
+): Promise<EventParams<E>>;
 
 /**
  * Calls specified TWA method and captures one of the specified events. Returns promise
@@ -95,12 +92,12 @@ export function request<Method extends EmptyMethodName, Event extends EventName>
  * @param event - event or events to listen
  * @param options - additional execution options.
  */
-export function request<Method extends NonEmptyMethodName, Event extends EventName>(
-  method: Method,
-  params: MethodParams<Method>,
-  event: Event | Event[],
-  options?: RequestOptionsAdvanced<EventParams<Event>>,
-): Promise<EventParams<Event>>;
+export function request<M extends NonEmptyMethodName, E extends EventName>(
+  method: M,
+  params: MethodParams<M>,
+  event: E | E[],
+  options?: RequestOptionsAdvanced<EventParams<E>>,
+): Promise<EventParams<E>>;
 
 export function request(
   method: MethodName,

package/src/supports.ts

@@ -1,40 +1,18 @@
 import { compareVersions, type Version } from '@tma.js/utils';
 
 import type {
-  HasCheckSupportMethodParam,
-  HasCheckSupportMethodName,
+  MethodVersionedParams,
+  MethodWithVersionedParams,
   MethodName,
-  MethodParams,
-  NonEmptyMethodName,
 } from './methods/index.js';
 
-function lessOrEqual(a: Version, b: Version): boolean {
-  return compareVersions(a, b) <= 0;
-}
-
 /**
- * By specified method and parameters extracts properties which could be used by
- * supports function as TWA method parameter.
- * @param method - TWA method.
- * @param params - method parameters.
+ * Returns true if "a" version is less than or equal to "b" version.
+ * @param a
+ * @param b
  */
-export function detectSupportParams<M extends NonEmptyMethodName>(
-  method: M,
-  params: MethodParams<M>,
-): HasCheckSupportMethodParam<HasCheckSupportMethodName>[] {
-  if (method === 'web_app_open_link') {
-    if ('try_instant_view' in params) {
-      return ['try_instant_view'];
-    }
-  }
-
-  if (method === 'web_app_set_header_color') {
-    if ('color' in params) {
-      return ['color'];
-    }
-  }
-
-  return [];
+function versionLessOrEqual(a: Version, b: Version): boolean {
+  return compareVersions(a, b) <= 0;
 }
 
 /**
@@ -43,17 +21,19 @@ export function detectSupportParams<M extends NonEmptyMethodName>(
  * @param param - method parameter
  * @param inVersion - platform version.
  */
-export function supports<M extends HasCheckSupportMethodName>(
+export function supports<M extends MethodWithVersionedParams>(
   method: M,
-  param: HasCheckSupportMethodParam<M>,
+  param: MethodVersionedParams<M>,
   inVersion: Version,
 ): boolean;
+
 /**
  * Returns true in case, specified method is supported in passed version.
  * @param method - method name.
  * @param inVersion - platform version.
  */
 export function supports(method: MethodName, inVersion: Version): boolean;
+
 export function supports(
   method: MethodName,
   paramOrVersion: Version | string,
@@ -63,18 +43,17 @@ export function supports(
   if (typeof inVersion === 'string') {
     if (method === 'web_app_open_link') {
       if (paramOrVersion === 'try_instant_view') {
-        return lessOrEqual('6.4', inVersion);
+        return versionLessOrEqual('6.4', inVersion);
       }
     }
 
     if (method === 'web_app_set_header_color') {
       if (paramOrVersion === 'color') {
-        return lessOrEqual('6.9', inVersion);
+        return versionLessOrEqual('6.9', inVersion);
       }
     }
   }
 
-  // Method name, target version.
   switch (method) {
     case 'web_app_open_tg_link':
     case 'web_app_open_invoice':
@@ -82,21 +61,21 @@ export function supports(
     case 'web_app_set_background_color':
     case 'web_app_set_header_color':
     case 'web_app_trigger_haptic_feedback':
-      return lessOrEqual('6.1', paramOrVersion);
+      return versionLessOrEqual('6.1', paramOrVersion);
     case 'web_app_open_popup':
-      return lessOrEqual('6.2', paramOrVersion);
+      return versionLessOrEqual('6.2', paramOrVersion);
     case 'web_app_close_scan_qr_popup':
     case 'web_app_open_scan_qr_popup':
     case 'web_app_read_text_from_clipboard':
-      return lessOrEqual('6.4', paramOrVersion);
+      return versionLessOrEqual('6.4', paramOrVersion);
     case 'web_app_switch_inline_query':
-      return lessOrEqual('6.7', paramOrVersion);
+      return versionLessOrEqual('6.7', paramOrVersion);
     case 'web_app_invoke_custom_method':
     case 'web_app_request_write_access':
     case 'web_app_request_phone':
-      return lessOrEqual('6.9', paramOrVersion);
+      return versionLessOrEqual('6.9', paramOrVersion);
     case 'web_app_setup_settings_button':
-      return lessOrEqual('6.10', paramOrVersion);
+      return versionLessOrEqual('6.10', paramOrVersion);
     default:
       return true;
   }