@tma.js/bridge 1.3.2

package/src/request.ts

@@ -0,0 +1,171 @@
+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,
+  MethodName,
+  MethodParams,
+  NonEmptyMethodName,
+} from './methods/params.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,
+    never
+  >;
+}[MethodName];
+
+/**
+ * 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,
+    never
+  >;
+}[EventName];
+
+export interface RequestOptions {
+  /**
+   * Bridge postEvent method.
+   * @default Global postEvent method.
+   */
+  postEvent?: PostEvent;
+
+  /**
+   * Execution timeout.
+   */
+  timeout?: number;
+}
+
+export interface RequestOptionsAdvanced<EventPayload> extends RequestOptions {
+  /**
+   * Should return true in case, this event should be captured. If not specified,
+   * request is not skipping captured events.
+   */
+  capture?: If<IsNever<EventPayload>, () => boolean, (payload: EventPayload) => boolean>;
+}
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, event with specified in method request identifier
+ * was captured.
+ * @param method - method to execute.
+ * @param params - method parameters.
+ * @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[],
+  options?: RequestOptions,
+): Promise<EventParams<Event>>;
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, specified event was captured.
+ * @param method - method to execute.
+ * @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>>;
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, specified event was captured.
+ * @param method - method to execute
+ * @param params - method parameters.
+ * @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(
+  method: MethodName,
+  eventOrParams: EventName | EventName[] | EventParams<any>,
+  eventOrOptions?: EventName | EventName[] | RequestOptions | RequestOptionsAdvanced<any>,
+  options?: RequestOptions | RequestOptionsAdvanced<any>,
+): Promise<any> {
+  let executionOptions: RequestOptions | RequestOptionsAdvanced<any> | undefined;
+  let methodParams: EventParams<any> | undefined;
+  let events: EventName[];
+  let requestId: string | undefined;
+
+  if (typeof eventOrParams === 'string' || Array.isArray(eventOrParams)) {
+    // Override: [method, event, options?]
+    events = Array.isArray(eventOrParams) ? eventOrParams : [eventOrParams] as EventName[];
+    executionOptions = eventOrOptions as (RequestOptionsAdvanced<any> | undefined);
+  } else {
+    // Override: [method, params, event, options?]
+    methodParams = eventOrParams as EventParams<any>;
+    events = Array.isArray(eventOrOptions) ? eventOrOptions : [eventOrOptions] as EventName[];
+    executionOptions = options;
+  }
+
+  // In case, method parameters were passed, and they contained request identifier, we should store
+  // it and wait for the event with this identifier to occur.
+  if (isRecord(methodParams) && typeof methodParams.req_id === 'string') {
+    requestId = methodParams.req_id;
+  }
+
+  const { postEvent = defaultPostEvent, timeout } = executionOptions || {};
+  const capture = executionOptions && 'capture' in executionOptions
+    ? executionOptions.capture
+    : null;
+
+  const promise = new Promise((res, rej) => {
+    // Iterate over each event and create event listener.
+    const stoppers = events.map((ev) => on(ev, (data?) => {
+      // If request identifier was specified, we are waiting for event with the same value
+      // to occur.
+      if (typeof requestId === 'string' && (!isRecord(data) || data.req_id !== requestId)) {
+        return;
+      }
+
+      if (typeof capture === 'function' && !capture(data)) {
+        return;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      stopListening();
+      res(data);
+    }));
+
+    // Function which removes all event listeners.
+    const stopListening = () => stoppers.forEach((stop) => stop());
+
+    try {
+      // We are wrapping this call in try catch, because it can throw errors in case,
+      // compatibility check was enabled. We want an error to be captured by promise, not by
+      // another one external try catch.
+      postEvent(method as any, methodParams);
+    } catch (e) {
+      stopListening();
+      rej(e);
+    }
+  });
+
+  return typeof timeout === 'number' ? withTimeout(promise, timeout) : promise;
+}

package/src/shared.ts

@@ -0,0 +1,5 @@
+/**
+ * Request identifier which should be generated locally. Native Telegram application
+ * uses it to generate a response to called method.
+ */
+export type RequestId = string;

package/src/supports.ts

@@ -0,0 +1,99 @@
+import { compareVersions, type Version } from '@tma.js/utils';
+
+import type {
+  HasCheckSupportMethodParam,
+  HasCheckSupportMethodName,
+  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.
+ */
+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 [];
+}
+
+/**
+ * Returns true in case, passed parameter in specified method is supported.
+ * @param method - method name
+ * @param param - method parameter
+ * @param inVersion - platform version.
+ */
+export function supports<M extends HasCheckSupportMethodName>(
+  method: M,
+  param: HasCheckSupportMethodParam<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,
+  inVersion?: string,
+): boolean {
+  // Method name, parameter, target version.
+  if (typeof inVersion === 'string') {
+    if (method === 'web_app_open_link') {
+      if (paramOrVersion === 'try_instant_view') {
+        return lessOrEqual('6.4', inVersion);
+      }
+    }
+
+    if (method === 'web_app_set_header_color') {
+      if (paramOrVersion === 'color') {
+        return lessOrEqual('6.9', inVersion);
+      }
+    }
+  }
+
+  // Method name, target version.
+  switch (method) {
+    case 'web_app_open_tg_link':
+    case 'web_app_open_invoice':
+    case 'web_app_setup_back_button':
+    case 'web_app_set_background_color':
+    case 'web_app_set_header_color':
+    case 'web_app_trigger_haptic_feedback':
+      return lessOrEqual('6.1', paramOrVersion);
+    case 'web_app_open_popup':
+      return lessOrEqual('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);
+    case 'web_app_invoke_custom_method':
+    case 'web_app_request_write_access':
+    case 'web_app_request_phone':
+      return lessOrEqual('6.9', paramOrVersion);
+    default:
+      return true;
+  }
+}