@tma.js/sdk 1.0.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tma.js/sdk",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "TypeScript Source Development Kit for Telegram Mini Apps client application.",
   "author": "Vladislav Kibenko <wolfram.deus@gmail.com>",
   "homepage": "https://github.com/Telegram-Mini-Apps/tma.js#readme",

package/src/bridge/events/parsers/phoneRequested.ts

@@ -1,6 +1,6 @@
 import { json, string } from '~/parsing/index.js';
 
-export type PhoneRequestedStatus = 'sent' | string;
+export type PhoneRequestedStatus = 'sent' | 'cancelled' | string;
 
 export interface PhoneRequestedPayload {
   /**

package/src/bridge/index.ts

@@ -2,4 +2,5 @@ export * from './env/index.js';
 export * from './errors/index.js';
 export * from './events/index.js';
 export * from './methods/index.js';
+export * from './invoke-custom-method.js';
 export * from './request.js';

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

@@ -0,0 +1,56 @@
+import type { ExecuteWithOptions } from '~/types/index.js';
+
+import type { CustomMethodName, CustomMethodParams } from './methods/index.js';
+import { request } from './request.js';
+
+/**
+ * Invokes known custom method. Returns method execution result.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param requestId - request identifier.
+ * @param options - additional options.
+ */
+export async function invokeCustomMethod<M extends CustomMethodName>(
+  method: M,
+  params: CustomMethodParams<M>,
+  requestId: string,
+  options?: ExecuteWithOptions,
+): Promise<unknown>;
+
+/**
+ * Invokes unknown custom method. Returns method execution result.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param requestId - request identifier.
+ * @param options - additional options.
+ */
+export function invokeCustomMethod(
+  method: string,
+  params: object,
+  requestId: string,
+  options?: ExecuteWithOptions,
+): Promise<unknown>;
+
+export async function invokeCustomMethod(
+  method: string,
+  params: object,
+  requestId: string,
+  options: ExecuteWithOptions = {},
+): Promise<unknown> {
+  const { result, error } = await request(
+    'web_app_invoke_custom_method',
+    {
+      method,
+      params,
+      req_id: requestId,
+    },
+    'custom_method_invoked',
+    options,
+  );
+
+  if (error) {
+    throw new Error(error);
+  }
+
+  return result;
+}

package/src/bridge/methods/custom-methods.ts

@@ -0,0 +1,68 @@
+import type { RequestId } from '~/types/index.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 interface CustomMethodsParams {
+  /**
+   * Deletes storage values by their keys.
+   */
+  deleteStorageValues: {
+    keys: string | string[]
+  };
+
+  /**
+   * Gets current user contact in case, Mini has access to it.
+   */
+  getRequestedContact: {};
+
+  /**
+   * Gets all registered storage keys.
+   */
+  getStorageKeys: {};
+
+  /**
+   * Gets storage values by their keys.
+   */
+  getStorageValues: {
+    keys: string | string[]
+  };
+
+  /**
+   * Saves value by specified key in the storage.
+   */
+  saveStorageValue: {
+    key: string;
+    value: string;
+  };
+}
+
+/**
+ * Known custom method name.
+ */
+export type CustomMethodName = keyof CustomMethodsParams;
+
+/**
+ * Custom method parameters.
+ */
+export type CustomMethodParams<M extends CustomMethodName> = CustomMethodsParams[M];
+
+export type AnyInvokeCustomMethodParams =
+  | CreateInvokeCustomMethodParams<string, any>
+  | {
+  [M in CustomMethodName]: CreateInvokeCustomMethodParams<M, CustomMethodParams<M>>
+}[CustomMethodName];

package/src/bridge/methods/index.ts

@@ -1,6 +1,6 @@
 export * from './createPostEvent.js';
+export * from './custom-methods.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/bridge/methods/methods.ts

@@ -1,8 +1,8 @@
 import type { RGB } from '~/colors/index.js';
 import type { IsNever, Not, RequestId, UnionKeys } from '~/types/index.js';
 
+import type { AnyInvokeCustomMethodParams } from './custom-methods.js';
 import type { AnyHapticFeedbackParams } from './haptic.js';
-import type { AnyInvokeCustomMethodParams } from './invoke-custom-method.js';
 import type { PopupParams } from './popup.js';
 
 /**
@@ -78,7 +78,6 @@ export interface MiniAppsMethods {
    */
   web_app_expand: CreateParams;
 
-  // TODO: 'getRequestedContact'. https://telegram.org/js/telegram-web-app.js
   /**
    * Invokes custom method.
    * @since v6.9
@@ -173,7 +172,6 @@ export interface MiniAppsMethods {
    */
   web_app_ready: CreateParams;
 
-  // TODO: Check if it is right. It probably requests other user phone.
   /**
    * Requests access to current user's phone.
    * @since v6.9
@@ -219,13 +217,13 @@ export interface MiniAppsMethods {
    * @see https://docs.telegram-mini-apps.com/platform/apps-communication/methods#web-app-set-header-color
    */
   web_app_set_header_color: CreateParams<
-  | {
+    | {
     /**
      * The Mini App header color key.
      */
     color_key: HeaderColorKey
   }
-  | {
+    | {
     /**
      * Color in RGB format.
      * @since v6.9

package/src/bridge/request.ts

@@ -1,6 +1,6 @@
 import { isRecord } from '~/misc/index.js';
 import { withTimeout } from '~/timeout/index.js';
-import type { And, If, IsNever } from '~/types/index.js';
+import type { And, ExecuteWithOptions, If, IsNever } from '~/types/index.js';
 
 import {
   type MiniAppsEventHasParams,
@@ -14,7 +14,6 @@ import {
   type MiniAppsMethodName,
   type MiniAppsMethodParams,
   type MiniAppsNonEmptyMethodName,
-  type PostEvent,
   postEvent as defaultPostEvent,
 } from './methods/index.js';
 
@@ -45,17 +44,7 @@ type EventWithRequestId = {
   >;
 }[MiniAppsEventName];
 
-export interface RequestOptions {
-  /**
-   * Bridge postEvent method.
-   * @default Global postEvent method.
-   */
-  postEvent?: PostEvent;
-
-  /**
-   * Execution timeout.
-   */
-  timeout?: number;
+export interface RequestOptions extends ExecuteWithOptions {
 }
 
 export interface RequestOptionsAdvanced<EventPayload> extends RequestOptions {
@@ -149,37 +138,39 @@ export function request(
     ? 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;
+  const execute = () => {
+    return 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 (requestId && (!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);
       }
+    });
+  };
 
-      // 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;
+  return typeof timeout === 'number' ? withTimeout(execute, timeout) : execute();
 }

package/src/cloud-storage/CloudStorage.ts

@@ -1,7 +1,6 @@
 import {
+  invokeCustomMethod,
   postEvent as defaultPostEvent,
-  request,
-  type RequestOptions,
 } from '~/bridge/index.js';
 import {
   array,
@@ -12,18 +11,9 @@ import {
   createSupportsFunc,
   type SupportsFunc,
 } from '~/supports/index.js';
-import type { CreateRequestIdFunc } from '~/types/index.js';
+import type { CreateRequestIdFunc, ExecuteWithTimeout } from '~/types/index.js';
 import type { Version } from '~/version/index.js';
 
-type WiredRequestOptions = Omit<RequestOptions, 'postEvent'>;
-
-interface Methods {
-  deleteStorageValues: { keys: string | string[] };
-  getStorageValues: { keys: string | string[] };
-  getStorageKeys: {};
-  saveStorageValue: { key: string; value: string };
-}
-
 function objectFromKeys<K extends string, V>(keys: K[], value: V): Record<K, V> {
   return keys.reduce<Record<K, V>>((acc, key) => {
     acc[key] = value;
@@ -45,51 +35,36 @@ export class CloudStorage {
     });
   }
 
-  /**
-   * Invokes custom method related to CloudStorage.
-   * @param method - method name.
-   * @param params - method parameters.
-   * @param options - execution options.
-   */
-  private async invokeCustomMethod<M extends keyof Methods>(
-    method: M,
-    params: Methods[M],
-    options: WiredRequestOptions = {},
-  ): Promise<unknown> {
-    const { result, error } = await request(
-      'web_app_invoke_custom_method',
-      { method, params, req_id: this.createRequestId() },
-      'custom_method_invoked',
-      { ...options, postEvent: this.postEvent },
-    );
-
-    if (error) {
-      throw new Error(error);
-    }
-
-    return result;
-  }
-
   /**
    * Deletes specified key or keys from the cloud storage.
    * @param keyOrKeys - key or keys to delete.
    * @param options - request execution options.
    */
-  async delete(keyOrKeys: string | string[], options?: WiredRequestOptions): Promise<void> {
+  async delete(keyOrKeys: string | string[], options: ExecuteWithTimeout = {}): Promise<void> {
     const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
     if (keys.length === 0) {
       return;
     }
 
-    await this.invokeCustomMethod('deleteStorageValues', { keys }, options);
+    await invokeCustomMethod(
+      'deleteStorageValues',
+      { keys },
+      this.createRequestId(),
+      { ...options, postEvent: this.postEvent },
+    );
   }
 
   /**
    * Returns list of all keys presented in the cloud storage.
    * @param options - request execution options.
    */
-  async getKeys(options?: WiredRequestOptions): Promise<string[]> {
-    const result = await this.invokeCustomMethod('getStorageKeys', {}, options);
+  async getKeys(options: ExecuteWithTimeout = {}): Promise<string[]> {
+    const result = await invokeCustomMethod(
+      'getStorageKeys',
+      {},
+      this.createRequestId(),
+      { ...options, postEvent: this.postEvent },
+    );
 
     return array().of(string()).parse(result);
   }
@@ -102,7 +77,7 @@ export class CloudStorage {
    */
   get<K extends string>(
     keys: K[],
-    options?: WiredRequestOptions,
+    options?: ExecuteWithTimeout,
   ): Promise<Record<K, string>>;
 
   /**
@@ -112,11 +87,11 @@ export class CloudStorage {
    * @return Value of the specified key. In case, key was not created previously, function
    * will return empty string.
    */
-  get(key: string, options?: WiredRequestOptions): Promise<string>;
+  get(key: string, options?: ExecuteWithTimeout): Promise<string>;
 
   async get(
     keyOrKeys: string | string[],
-    options?: WiredRequestOptions,
+    options: ExecuteWithTimeout = {},
   ): Promise<string | Record<string, string>> {
     const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
     if (keys.length === 0) {
@@ -126,9 +101,12 @@ export class CloudStorage {
     const schema = json(
       objectFromKeys(keys, string()),
     );
-    const result = await this
-      .invokeCustomMethod('getStorageValues', { keys }, options)
-      .then((data) => schema.parse(data));
+    const result = await invokeCustomMethod(
+      'getStorageValues',
+      { keys },
+      this.createRequestId(),
+      { ...options, postEvent: this.postEvent },
+    ).then((data) => schema.parse(data));
 
     return Array.isArray(keyOrKeys) ? result : result[keyOrKeys];
   }
@@ -139,17 +117,22 @@ export class CloudStorage {
    * @param value - storage value.
    * @param options - request execution options.
    */
-  async set(key: string, value: string, options?: WiredRequestOptions): Promise<void> {
-    await this.invokeCustomMethod('saveStorageValue', { key, value }, options);
+  async set(key: string, value: string, options: ExecuteWithTimeout = {}): Promise<void> {
+    await invokeCustomMethod(
+      'saveStorageValue',
+      { key, value },
+      this.createRequestId(),
+      { ...options, postEvent: this.postEvent },
+    );
   }
 
   /**
    * Checks if specified method is supported by current component.
    */
   supports: SupportsFunc<
-  | 'delete'
-  | 'get'
-  | 'getKeys'
-  | 'set'
+    | 'delete'
+    | 'get'
+    | 'getKeys'
+    | 'set'
   >;
 }

package/src/index.ts

@@ -6,6 +6,7 @@ export {
 export {
   createPostEvent,
   isIframe,
+  invokeCustomMethod,
   on,
   off,
   once,
@@ -35,13 +36,11 @@ export {
   type PhoneRequestedStatus,
   type PostEvent,
   type RequestOptions,
+  type RequestOptionsAdvanced,
   type SwitchInlineQueryChatType,
   type WriteAccessRequestedStatus,
 } from './bridge/index.js';
-export {
-  classNames,
-  mergeClassNames,
-} from './classnames/index.js';
+export { classNames, mergeClassNames } from './classnames/index.js';
 export {
   ClosingBehavior,
   type ClosingBehaviorEventListener,
@@ -104,10 +103,7 @@ export {
   type MiniAppEvents,
   type MiniAppProps,
 } from './mini-app/index.js';
-export {
-  isTMA,
-  isRecord,
-} from './misc/index.js';
+export { isTMA, isRecord } from './misc/index.js';
 export {
   getHash,
   HashNavigator,
@@ -134,6 +130,12 @@ export {
   type QRScannerEventName,
   type QRScannerEvents,
 } from './qr-scanner/index.js';
+export {
+  SettingsButton,
+  type SettingsButtonEventName,
+  type SettingsButtonEventListener,
+  type SettingsButtonEvents,
+} from './settings-button/index.js';
 export { supports } from './supports/index.js';
 export {
   parseThemeParams,
@@ -147,15 +149,10 @@ export {
   type ThemeParamsKey,
   type ThemeParamsParsed,
 } from './theme-params/index.js';
-export type {
-  RequestId,
-  CreateRequestIdFunc,
-} from './types/index.js';
+export { withTimeout, TimeoutError, isTimeoutError } from './timeout/index.js';
+export type { RequestId, CreateRequestIdFunc } from './types/index.js';
 export { Utils } from './utils/index.js';
-export {
-  compareVersions,
-  type Version,
-} from './version/index.js';
+export { compareVersions, type Version } from './version/index.js';
 export {
   requestViewport,
   Viewport,
@@ -165,7 +162,4 @@ export {
   type ViewportEventListener,
   type ViewportEvents,
 } from './viewport/index.js';
-export {
-  setTargetOrigin,
-  setDebug,
-} from './globals.js';
+export { setTargetOrigin, setDebug } from './globals.js';

package/src/init/creators/createMiniApp.ts

@@ -2,6 +2,7 @@ import { MiniApp } from '~/mini-app/index.js';
 import { getStorageValue, saveStorageValue } from '~/storage.js';
 import type { PostEvent } from '~/bridge/index.js';
 import type { RGB } from '~/colors/index.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
 import type { Version } from '~/version/index.js';
 
 /**
@@ -11,6 +12,7 @@ import type { Version } from '~/version/index.js';
  * @param backgroundColor - web app background color.
  * @param version - platform version.
  * @param botInline - is Mini App launched in inline mode.
+ * @param createRequestId - function which generates request identifiers.
  * @param postEvent - Bridge postEvent function
  */
 export function createMiniApp(
@@ -18,6 +20,7 @@ export function createMiniApp(
   backgroundColor: RGB,
   version: Version,
   botInline: boolean,
+  createRequestId: CreateRequestIdFunc,
   postEvent: PostEvent,
 ): MiniApp {
   const {
@@ -30,6 +33,7 @@ export function createMiniApp(
     backgroundColor: stateBackgroundColor,
     version,
     botInline,
+    createRequestId,
     postEvent,
   });
 

package/src/init/creators/createSettingsButton.ts

@@ -0,0 +1,25 @@
+import { SettingsButton } from '~/settings-button/index.js';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import type { PostEvent } from '~/bridge/index.js';
+
+/**
+ * Creates SettingsButton instance using last locally saved data also saving each state in
+ * the storage.
+ * @param isPageReload - was current page reloaded.
+ * @param version - platform version.
+ * @param postEvent - Bridge postEvent function
+ */
+export function createSettingsButton(
+  isPageReload: boolean,
+  version: string,
+  postEvent: PostEvent,
+): SettingsButton {
+  const { isVisible = false } = isPageReload ? getStorageValue('settings-button') || {} : {};
+  const component = new SettingsButton(isVisible, version, postEvent);
+
+  component.on('change', () => {
+    saveStorageValue('settings-button', { isVisible: component.isVisible });
+  });
+
+  return component;
+}

package/src/init/creators/createViewport.ts

@@ -3,6 +3,15 @@ import { requestViewport, Viewport } from '~/viewport/index.js';
 import type { PostEvent } from '~/bridge/index.js';
 import type { Platform } from '~/types/index.js';
 
+/**
+ * Returns true in case, specified platform supports calling Mini Apps
+ * "web_app_request_viewport" method.
+ * @param platform - platform identifier.
+ */
+function isRequestSupportedPlatform(platform: Platform): boolean {
+  return !['macos', 'web', 'weba'].includes(platform);
+}
+
 /**
  * Attempts to create Viewport instance using known parameters and local storage.
  * @param isPageReload - was page reloaded.
@@ -14,7 +23,7 @@ function tryCreate(
   platform: Platform,
   postEvent: PostEvent,
 ): Viewport | null {
-  if (isPageReload || platform === 'macos' || platform === 'web' || platform === 'weba') {
+  if (isPageReload || !isRequestSupportedPlatform(platform)) {
     return new Viewport({
       height: window.innerHeight,
       isExpanded: true,
@@ -73,10 +82,12 @@ export function createViewportSync(
     }),
   );
 
-  viewport.sync({ postEvent, timeout: 100 }).catch((e) => {
-    // eslint-disable-next-line no-console
-    console.error('Unable to actualize viewport state', e);
-  });
+  if (isRequestSupportedPlatform(platform)) {
+    viewport.sync({ postEvent, timeout: 100 }).catch((e) => {
+      // eslint-disable-next-line no-console
+      console.error('Unable to actualize viewport state', e);
+    });
+  }
 
   return viewport;
 }

package/src/init/creators/index.ts

@@ -3,5 +3,6 @@ export * from './createClosingBehavior.js';
 export * from './createMainButton.js';
 export * from './createMiniApp.js';
 export * from './createRequestIdGenerator.js';
+export * from './createSettingsButton.js';
 export * from './createThemeParams.js';
 export * from './createViewport.js';