@tma.js/bridge 1.3.12 → 1.4.1

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

package/dist/dts/events/parsing.d.ts

@@ -1,38 +0,0 @@
-import type { ClipboardTextReceivedPayload, CustomMethodInvokedPayload, InvoiceClosedPayload, PhoneRequestedPayload, PopupClosedPayload, QrTextReceivedPayload, ThemeChangedPayload, ViewportChangedPayload, WriteAccessRequestedPayload } from './payloads.js';
-/**
- * Parses incoming value as ThemeChangedPayload.
- */
-export declare const themeChangedPayload: import("@tma.js/parsing").ValueParser<ThemeChangedPayload, false>;
-/**
- * Parses incoming value as ViewportChangedPayload.
- * @param value - value to parse.
- */
-export declare const viewportChangedPayload: import("@tma.js/parsing").ValueParser<ViewportChangedPayload, false>;
-/**
- * Parses incoming value as PopupClosedPayload.
- */
-export declare const popupClosedPayload: import("@tma.js/parsing").ValueParser<PopupClosedPayload, false>;
-/**
- * Parses incoming value as QrTextReceivedPayload.
- */
-export declare const qrTextReceivedPayload: import("@tma.js/parsing").ValueParser<QrTextReceivedPayload, false>;
-/**
- * Parses incoming value as InvoiceClosedPayload.
- */
-export declare const invoiceClosedPayload: import("@tma.js/parsing").ValueParser<InvoiceClosedPayload, false>;
-/**
- * Parses incoming value as clipboard text received payload.
- */
-export declare const clipboardTextReceivedPayload: import("@tma.js/parsing").ValueParser<ClipboardTextReceivedPayload, false>;
-/**
- * Parses incoming value as WriteAccessRequestedPayload.
- */
-export declare const writeAccessRequestedPayload: import("@tma.js/parsing").ValueParser<WriteAccessRequestedPayload, false>;
-/**
- * Parses incoming value as PhoneRequestedPayload.
- */
-export declare const phoneRequestedPayload: import("@tma.js/parsing").ValueParser<PhoneRequestedPayload, false>;
-/**
- * Parses incoming value as CustomMethodInvokedPayload.
- */
-export declare const customMethodInvokedPayload: import("@tma.js/parsing").ValueParser<CustomMethodInvokedPayload<unknown>, false>;

package/dist/dts/events/payloads.d.ts

@@ -1,98 +0,0 @@
-import type { RGB } from '@tma.js/colors';
-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 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 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 interface QrTextReceivedPayload {
-    /**
-     * Data extracted from the QR.
-     */
-    data?: string;
-}
-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;
-    };
-}
-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 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 type PhoneRequestedStatus = 'sent' | string;
-export interface PhoneRequestedPayload {
-    /**
-     * Request status.
-     */
-    status: PhoneRequestedStatus;
-}
-export type WriteAccessRequestedStatus = 'allowed' | string;
-export interface WriteAccessRequestedPayload {
-    /**
-     * Request status.
-     */
-    status: WriteAccessRequestedStatus;
-}

package/src/events/parsing.ts

@@ -1,104 +0,0 @@
-import {
-  number,
-  string,
-  boolean,
-  json,
-  rgb,
-  createValueParserGenerator,
-} 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;
-}
-
-const rgbOptional = rgb().optional();
-const num = number();
-
-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({
-    bg_color: rgbOptional,
-    text_color: rgbOptional,
-    hint_color: rgbOptional,
-    link_color: rgbOptional,
-    button_color: rgbOptional,
-    button_text_color: rgbOptional,
-    secondary_bg_color: rgbOptional,
-  }),
-});
-
-/**
- * Parses incoming value as ViewportChangedPayload.
- * @param value - value to parse.
- */
-export const viewportChangedPayload = json<ViewportChangedPayload>({
-  height: number(),
-  width: windowWidthParser(),
-  is_state_stable: boolean(),
-  is_expanded: boolean(),
-});
-
-/**
- * Parses incoming value as PopupClosedPayload.
- */
-export const popupClosedPayload = json<PopupClosedPayload>({
-  button_id: string({ isEmpty: isNullOrUndefined }).optional(),
-});
-
-/**
- * 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(),
-});