@tma.js/bridge 1.3.11 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tma.js/bridge",
-  "version": "1.3.11",
+  "version": "1.4.0",
   "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",
@@ -41,7 +41,7 @@
     "@tma.js/colors": "0.0.5",
     "@tma.js/event-emitter": "0.1.0",
     "@tma.js/logger": "0.0.5",
-    "@tma.js/parsing": "0.1.3",
+    "@tma.js/parsing": "1.0.0",
     "@tma.js/util-types": "0.0.3",
     "@tma.js/utils": "0.5.6"
   },
@@ -59,7 +59,6 @@
     "typecheck": "tsc --noEmit -p tsconfig.build.json",
     "build": "pnpm run build:default && pnpm run build:iife",
     "build:default": "vite build --config vite.config.ts",
-    "build:iife": "vite build --config vite.iife.config.ts",
-    "rollup": "pnpm run typecheck && pnpm run build"
+    "build:iife": "vite build --config vite.iife.config.ts"
   }
 }

package/src/errors/MethodUnsupportedError.ts

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

package/src/errors/ParameterUnsupportedError.ts

@@ -0,0 +1,13 @@
+import type { Version } from '@tma.js/utils';
+
+import type { MethodName } from '../methods/index.js';
+
+/**
+ * Error thrown in case, unsupported parameter was used.
+ */
+export class ParameterUnsupportedError extends Error {
+  constructor(method: MethodName, 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/errors/index.ts

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

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

@@ -4,7 +4,7 @@ import {
   boolean,
   json,
   rgb,
-  createValueParserGen,
+  createValueParserGenerator,
 } from '@tma.js/parsing';
 
 import type {
@@ -22,22 +22,30 @@ function isNullOrUndefined(value: unknown): boolean {
 const rgbOptional = rgb().optional();
 const num = number();
 
-const windowWidthParser = createValueParserGen((value) => (value === null || value === undefined
-  ? window.innerWidth
-  : num.parse(value)));
+const windowWidthParser = createValueParserGenerator(
+  (value) => (value === null || value === undefined
+    ? window.innerWidth
+    : num.parse(value)),
+);
 
 /**
  * Parses incoming value as ThemeChangedPayload.
  */
 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

@@ -3,14 +3,13 @@ import {
   hasExternalNotify,
   hasWebviewProxy,
 } from '../env.js';
-import { targetOrigin as globalTargetOrigin } from '../globals.js';
-
+import { logger, targetOrigin as globalTargetOrigin } from '../globals.js';
 import type {
   EmptyMethodName,
   MethodName,
   MethodParams,
   NonEmptyMethodName,
-} from './params.js';
+} from './methods.js';
 
 interface PostEventOptions {
   /**
@@ -30,8 +29,7 @@ export type PostEvent = typeof postEvent;
  * @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.
+ * @throws {Error} Bridge could not determine current environment and possible way to send event.
  */
 export function postEvent<E extends NonEmptyMethodName>(
   eventType: E,
@@ -44,8 +42,7 @@ export function postEvent<E extends NonEmptyMethodName>(
  * 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.
+ * @throws {Error} Bridge could not determine current environment and possible way to send event.
  */
 export function postEvent(eventType: EmptyMethodName, options?: PostEventOptions): void;
 
@@ -74,6 +71,8 @@ export function postEvent(
   }
   const { targetOrigin = globalTargetOrigin() } = postOptions;
 
+  logger.log(`Calling method "${eventType}"`, eventData);
+
   // Telegram Web.
   if (isIframe()) {
     window.parent.postMessage(JSON.stringify({
@@ -95,8 +94,7 @@ export function postEvent(
     return;
   }
 
-  // Otherwise current environment is unknown, and we are not able to send
-  // event.
+  // 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.',
   );

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;
   }