@tma.js/sdk 1.0.2 → 1.2.0

package/src/init/init.ts

@@ -7,7 +7,7 @@ import {
   createClosingBehavior,
   createMainButton,
   createMiniApp,
-  createRequestIdGenerator,
+  createRequestIdGenerator, createSettingsButton,
   createThemeParams, createViewportAsync,
   createViewportSync,
 } from '~/init/creators/index.js';
@@ -23,7 +23,9 @@ import type { InitOptions, InitResult } from './types.js';
 
 type ComputedInitResult<O> = O extends { async: true } ? Promise<InitResult> : InitResult;
 
-export function init<O extends InitOptions>(options: O): ComputedInitResult<O> {
+export function init(): InitResult;
+export function init<O extends InitOptions>(options: O): ComputedInitResult<O>;
+export function init(options: InitOptions = {}): InitResult | Promise<InitResult> {
   const {
     async = false,
     cssVars = false,
@@ -79,11 +81,13 @@ export function init<O extends InitOptions>(options: O): ComputedInitResult<O> {
         themeParams.backgroundColor || '#ffffff',
         version,
         botInline,
+        createRequestId,
         postEvent,
       ),
       popup: new Popup(version, postEvent),
       postEvent,
       qrScanner: new QRScanner(version, postEvent),
+      settingsButton: createSettingsButton(isPageReload, version, postEvent),
       themeParams: createThemeParams(themeParams),
       utils: new Utils(version, createRequestId, postEvent),
       ...(initData
@@ -112,7 +116,7 @@ export function init<O extends InitOptions>(options: O): ComputedInitResult<O> {
           ...result,
           viewport: vp,
         };
-      }) as ComputedInitResult<O>;
+      });
     }
 
     processCSSVars(
@@ -122,10 +126,10 @@ export function init<O extends InitOptions>(options: O): ComputedInitResult<O> {
       viewport,
     );
 
-    return { ...result, viewport } as ComputedInitResult<O>;
+    return { ...result, viewport };
   } catch (e) {
     if (async) {
-      return Promise.reject(e) as unknown as ComputedInitResult<O>;
+      return Promise.reject(e);
     }
     throw e;
   }

package/src/init/types.ts

@@ -9,6 +9,7 @@ import type { MainButton } from '~/main-button/index.js';
 import type { MiniApp } from '~/mini-app/index.js';
 import type { Popup } from '~/popup/index.js';
 import type { QRScanner } from '~/qr-scanner/index.js';
+import type { SettingsButton } from '~/settings-button/index.js';
 import type { ThemeParams } from '~/theme-params/index.js';
 import type { CreateRequestIdFunc } from '~/types/index.js';
 import type { Utils } from '~/utils/index.js';
@@ -28,6 +29,7 @@ export interface InitResult {
   popup: Popup;
   postEvent: PostEvent;
   qrScanner: QRScanner;
+  settingsButton: SettingsButton;
   themeParams: ThemeParams;
   utils: Utils;
   viewport: Viewport;

package/src/mini-app/MiniApp.ts

@@ -1,4 +1,5 @@
 import {
+  invokeCustomMethod,
   type PhoneRequestedStatus,
   type PostEvent,
   postEvent as defaultPostEvent,
@@ -18,11 +19,14 @@ import {
   createSupportsParamFunc,
   type SupportsFunc,
 } from '~/supports/index.js';
+import { sleep, withTimeout } from '~/timeout/index.js';
+import type { CreateRequestIdFunc, ExecuteWithTimeout } from '~/types/index.js';
 
+import { contactParser } from './contactParser.js';
 import type {
   MiniAppEvents,
   MiniAppHeaderColor, MiniAppProps,
-  MiniAppState,
+  MiniAppState, RequestedContact,
 } from './types.js';
 
 /**
@@ -37,6 +41,12 @@ export class MiniApp {
 
   private readonly postEvent: PostEvent;
 
+  private readonly createRequestId: CreateRequestIdFunc;
+
+  private requestingPhoneAccess = false;
+
+  private requestingWriteAccess = false;
+
   constructor(props: MiniAppProps) {
     const {
       postEvent = defaultPostEvent,
@@ -44,6 +54,7 @@ export class MiniApp {
       backgroundColor,
       version,
       botInline,
+      createRequestId,
     } = props;
 
     const isSupported = createSupportsFunc(version, {
@@ -56,6 +67,7 @@ export class MiniApp {
 
     this.postEvent = postEvent;
     this.botInline = botInline;
+    this.createRequestId = createRequestId;
     this.supports = (method) => {
       if (!isSupported(method)) {
         return false;
@@ -66,7 +78,6 @@ export class MiniApp {
       if (method === 'switchInlineQuery' && !botInline) {
         return false;
       }
-
       return true;
     };
 
@@ -76,6 +87,22 @@ export class MiniApp {
     });
   }
 
+  /**
+   * Attempts to get requested contact.
+   */
+  private async getRequestedContact(): Promise<RequestedContact> {
+    return invokeCustomMethod(
+      'getRequestedContact',
+      {},
+      this.createRequestId(),
+      {
+        postEvent: this.postEvent,
+        timeout: 10000,
+      },
+    )
+      .then((data) => contactParser.parse(data));
+  }
+
   /**
    * The Mini App background color.
    */
@@ -111,6 +138,20 @@ export class MiniApp {
     return isColorDark(this.backgroundColor);
   }
 
+  /**
+   * True if phone access is currently being requested.
+   */
+  get isRequestingPhoneAccess(): boolean {
+    return this.requestingPhoneAccess;
+  }
+
+  /**
+   * True if write access is currently being requested.
+   */
+  get isRequestingWriteAccess(): boolean {
+    return this.requestingWriteAccess;
+  }
+
   /**
    * Adds new event listener.
    */
@@ -135,25 +176,95 @@ export class MiniApp {
   }
 
   /**
-   * Requests current user phone access.
+   * Requests current user contact information. In contrary to requestPhoneAccess, this method
+   * returns promise with contact information that rejects in case, user denied access, or request
+   * failed.
+   * @param options - additional options.
    */
-  requestPhoneAccess(): Promise<PhoneRequestedStatus> {
-    return request(
-      'web_app_request_phone',
-      'phone_requested',
-      { postEvent: this.postEvent },
-    ).then((data) => data.status);
+  async requestContact({ timeout = 5000 }: ExecuteWithTimeout = {}): Promise<RequestedContact> {
+    // First of all, let's try to get the requested contact. Probably, we already requested
+    // it before.
+    try {
+      return await this.getRequestedContact();
+    } catch (e) { /* empty */
+    }
+
+    // Then, request access to user's phone.
+    const status = await this.requestPhoneAccess();
+    if (status !== 'sent') {
+      throw new Error('Access denied.');
+    }
+
+    // Expected deadline.
+    const deadlineAt = Date.now() + timeout;
+
+    // Time to wait before executing the next request.
+    let sleepTime = 50;
+
+    return withTimeout(async () => {
+      // We are trying to retrieve the requested contact until deadline was reached.
+      while (Date.now() < deadlineAt) {
+        try {
+          // eslint-disable-next-line no-await-in-loop
+          return await this.getRequestedContact();
+        } catch (e) { /* empty */
+        }
+
+        // Sleep for some time.
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(sleepTime);
+
+        // Increase the sleep time not to kill the backend service.
+        sleepTime += 50;
+      }
+
+      throw new Error('Unable to retrieve requested contact.');
+    }, timeout);
+  }
+
+  /**
+   * Requests current user phone access. Method returns promise, which resolves
+   * status of the request. In case, user accepted the request, Mini App bot will receive
+   * the according notification.
+   *
+   * To obtain the retrieved information instead, utilize the requestContact method.
+   * @param options - additional options.
+   * @see requestContact
+   */
+  requestPhoneAccess(options: ExecuteWithTimeout = {}): Promise<PhoneRequestedStatus> {
+    if (this.requestingPhoneAccess) {
+      throw new Error('Phone access is already being requested.');
+    }
+    this.requestingPhoneAccess = true;
+
+    return request('web_app_request_phone', 'phone_requested', {
+      ...options,
+      postEvent: this.postEvent,
+    })
+      .then((data) => data.status)
+      .finally(() => {
+        this.requestingPhoneAccess = false;
+      });
   }
 
   /**
    * Requests write message access to current user.
+   * @param options - additional options.
    */
-  requestWriteAccess(): Promise<WriteAccessRequestedStatus> {
-    return request(
-      'web_app_request_write_access',
-      'write_access_requested',
-      { postEvent: this.postEvent },
-    ).then((data) => data.status);
+  requestWriteAccess(options: ExecuteWithTimeout = {}): Promise<WriteAccessRequestedStatus> {
+    if (this.requestingWriteAccess) {
+      throw new Error('Write access is already being requested.');
+    }
+    this.requestingWriteAccess = true;
+
+    return request('web_app_request_write_access', 'write_access_requested', {
+      ...options,
+      postEvent: this.postEvent,
+    })
+      .then((data) => data.status)
+      .finally(() => {
+        this.requestingWriteAccess = false;
+      });
   }
 
   /**
@@ -203,11 +314,11 @@ export class MiniApp {
    * Checks if specified method is supported by current component.
    */
   supports: SupportsFunc<
-  | 'requestWriteAccess'
-  | 'requestPhoneAccess'
-  | 'switchInlineQuery'
-  | 'setHeaderColor'
-  | 'setBackgroundColor'
+    | 'requestWriteAccess'
+    | 'requestPhoneAccess'
+    | 'switchInlineQuery'
+    | 'setHeaderColor'
+    | 'setBackgroundColor'
   >;
 
   /**

package/src/mini-app/contactParser.ts

@@ -0,0 +1,29 @@
+import { date, json, number, searchParams, string } from '~/parsing/index.js';
+
+import type { RequestedContact } from './types.js';
+
+export const contactParser = searchParams<RequestedContact>({
+  contact: json({
+    userId: {
+      type: number(),
+      from: 'user_id',
+    },
+    phoneNumber: {
+      type: string(),
+      from: 'phone_number',
+    },
+    firstName: {
+      type: string(),
+      from: 'first_name',
+    },
+    lastName: {
+      type: string(),
+      from: 'last_name',
+    },
+  }),
+  authDate: {
+    type: date(),
+    from: 'auth_date',
+  },
+  hash: string(),
+});

package/src/mini-app/types.ts

@@ -1,6 +1,7 @@
 import type { HeaderColorKey, PostEvent } from '~/bridge/index.js';
 import type { RGB } from '~/colors/index.js';
 import type { StateEvents } from '~/state/index.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
 import type { Version } from '~/version/index.js';
 
 export interface MiniAppProps {
@@ -8,6 +9,7 @@ export interface MiniAppProps {
   backgroundColor: RGB;
   version: Version;
   botInline: boolean;
+  createRequestId: CreateRequestIdFunc;
   postEvent?: PostEvent;
 }
 
@@ -23,3 +25,14 @@ export type MiniAppEvents = StateEvents<MiniAppState>;
 export type MiniAppEventName = keyof MiniAppEvents;
 
 export type MiniAppEventListener<E extends MiniAppEventName> = MiniAppEvents[E];
+
+export interface RequestedContact {
+  contact: {
+    userId: number;
+    phoneNumber: string;
+    firstName: string;
+    lastName: string;
+  };
+  authDate: Date;
+  hash: string;
+}

package/src/settings-button/SettingsButton.ts

@@ -0,0 +1,85 @@
+import {
+  off,
+  on,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import { createSupportsFunc, type SupportsFunc } from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
+
+import type { SettingsButtonEvents, SettingsButtonState } from './types.js';
+
+type Emitter = EventEmitter<SettingsButtonEvents>;
+
+export class SettingsButton {
+  private readonly ee: Emitter = new EventEmitter();
+
+  private readonly state: State<SettingsButtonState>;
+
+  constructor(
+    isVisible: boolean,
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({ isVisible }, this.ee);
+    this.supports = createSupportsFunc(version, {
+      show: 'web_app_setup_settings_button',
+      hide: 'web_app_setup_settings_button',
+    });
+  }
+
+  private set isVisible(visible: boolean) {
+    this.state.set('isVisible', visible);
+    this.postEvent('web_app_setup_settings_button', { is_visible: visible });
+  }
+
+  /**
+   * True if SettingsButton is currently visible.
+   */
+  get isVisible(): boolean {
+    return this.state.get('isVisible');
+  }
+
+  /**
+   * Hides the SettingsButton.
+   */
+  hide(): void {
+    this.isVisible = false;
+  }
+
+  /**
+   * Adds event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  on: Emitter['on'] = (event, listener) => (
+    event === 'click'
+      ? on('settings_button_pressed', listener)
+      : this.ee.on(event, listener)
+  );
+
+  /**
+   * Removes event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  off: Emitter['off'] = (event, listener) => (
+    event === 'click'
+      ? off('settings_button_pressed', listener)
+      : this.ee.off(event, listener)
+  );
+
+  /**
+   * Shows the SettingsButton.
+   */
+  show(): void {
+    this.isVisible = true;
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'show' | 'hide'>;
+}

package/src/settings-button/index.ts

@@ -0,0 +1,2 @@
+export * from './SettingsButton.js';
+export * from './types.js';

package/src/settings-button/types.ts

@@ -0,0 +1,15 @@
+import type { MiniAppsEventListener } from '~/bridge/index.js';
+import type { StateEvents } from '~/state/index.js';
+
+export interface SettingsButtonState {
+  isVisible: boolean;
+}
+
+export interface SettingsButtonEvents extends StateEvents<SettingsButtonState> {
+  click: MiniAppsEventListener<'settings_button_pressed'>;
+}
+
+export type SettingsButtonEventName = keyof SettingsButtonEvents;
+
+export type SettingsButtonEventListener<E extends SettingsButtonEventName> =
+  SettingsButtonEvents[E];

package/src/storage.ts

@@ -21,6 +21,9 @@ interface StorageParams {
     text: string;
     textColor: RGB;
   };
+  'settings-button': {
+    isVisible: boolean
+  };
   viewport: {
     height: number;
     isExpanded: boolean;

package/src/timeout/index.ts

@@ -1,3 +1,4 @@
 export * from './isTimeoutError.js';
+export * from './sleep.js';
 export * from './TimeoutError.js';
 export * from './withTimeout.js';

package/src/timeout/sleep.ts

@@ -0,0 +1,10 @@
+/**
+ * Awaits for specified amount of time.
+ * @param duration - duration to await.
+ */
+export function sleep(duration: number): Promise<void> {
+  // eslint-disable-next-line no-await-in-loop,@typescript-eslint/no-loop-func
+  return new Promise((res) => {
+    setTimeout(res, duration);
+  });
+}

package/src/timeout/withTimeout.ts

@@ -1,36 +1,24 @@
 import { TimeoutError } from './TimeoutError.js';
 
-type AnyAsyncFunction = (...args: any[]) => Promise<any>;
-
 /**
  * Creates promise which rejects after timeout milliseconds.
  * @param timeout - timeout in milliseconds.
  */
-function createTimeoutPromise(timeout: number): Promise<void> {
+function createTimeoutPromise(timeout: number): Promise<never> {
   return new Promise((_, rej) => {
     setTimeout(rej, timeout, new TimeoutError(timeout));
   });
 }
 
 /**
- * Rejects specified promise in case, it is processed more than timeout seconds.
- * @param promise - wrapped promise.
- * @param timeout - timeout in milliseconds.
+ * Accepts specified function and instantly executes. It waits for timeout milliseconds for
+ * it to complete and throws an error in case, deadline was reached.
+ * @param func - function to execute.
+ * @param timeout - completion timeout.
  */
-export function withTimeout<P extends Promise<any>>(promise: P, timeout: number): P;
-/**
- * Wraps async function in function using timeout.
- * @param func - wrapped function.
- * @param timeout - async function timeout.
- */
-export function withTimeout<F extends AnyAsyncFunction>(func: F, timeout: number): F;
-export function withTimeout(funcOrPromise: Promise<any> | AnyAsyncFunction, timeout: number) {
-  if (typeof funcOrPromise === 'function') {
-    return (...args: any[]) => Promise.race([
-      funcOrPromise(...args),
-      createTimeoutPromise(timeout),
-    ]);
-  }
-
-  return Promise.race([funcOrPromise, createTimeoutPromise(timeout)]);
+export function withTimeout<T>(func: () => Promise<T>, timeout: number): Promise<T> {
+  return Promise.race([
+    func(),
+    createTimeoutPromise(timeout),
+  ]);
 }

package/src/types/index.ts

@@ -1,3 +1,4 @@
+export * from './methods.js';
 export * from './platform.js';
 export * from './request-id.js';
 export * from './utils.js';

package/src/types/methods.ts

@@ -0,0 +1,18 @@
+import type { PostEvent } from '~/bridge/index.js';
+
+export interface ExecuteWithTimeout {
+  /**
+   * Timeout to execute method.
+   */
+  timeout?: number;
+}
+
+export interface ExecuteWithPostEvent {
+  /**
+   * postEvent function to use to call Telegram Mini Apps methods.
+   */
+  postEvent?: PostEvent;
+}
+
+export interface ExecuteWithOptions extends ExecuteWithTimeout, ExecuteWithPostEvent {
+}

package/dist/dts/bridge/methods/invoke-custom-method.d.ts

@@ -1,24 +0,0 @@
-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 type AnyInvokeCustomMethodParams = CreateInvokeCustomMethodParams<'deleteStorageValues', {
-    keys: string | string[];
-}> | CreateInvokeCustomMethodParams<'getStorageValues', {
-    keys: string | string[];
-}> | CreateInvokeCustomMethodParams<'getStorageKeys', {}> | CreateInvokeCustomMethodParams<'saveStorageValue', {
-    key: string;
-    value: string;
-}> | CreateInvokeCustomMethodParams<string, any>;
-export {};

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

@@ -1,25 +0,0 @@
-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 type AnyInvokeCustomMethodParams =
-  | CreateInvokeCustomMethodParams<'deleteStorageValues', { keys: string | string[] }>
-  | CreateInvokeCustomMethodParams<'getStorageValues', { keys: string | string[] }>
-  | CreateInvokeCustomMethodParams<'getStorageKeys', {}>
-  | CreateInvokeCustomMethodParams<'saveStorageValue', { key: string, value: string }>
-  | CreateInvokeCustomMethodParams<string, any>;