@tma.js/sdk 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tma.js/sdk",
-  "version": "1.2.0",
+  "version": "1.3.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/index.ts

@@ -154,6 +154,7 @@ export type { RequestId, CreateRequestIdFunc } from './types/index.js';
 export { Utils } from './utils/index.js';
 export { compareVersions, type Version } from './version/index.js';
 export {
+  isStableViewportPlatform,
   requestViewport,
   Viewport,
   type RequestViewportResult,

package/src/init/creators/createViewport.ts

@@ -1,53 +1,19 @@
 import { getStorageValue, saveStorageValue } from '~/storage.js';
-import { requestViewport, Viewport } from '~/viewport/index.js';
+import {
+  isStableViewportPlatform,
+  requestViewport,
+  Viewport,
+  type ViewportProps,
+} 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.
- * @param platform - platform identifier.
- * @param postEvent - Bridge postEvent function.
- */
-function tryCreate(
-  isPageReload: boolean,
-  platform: Platform,
-  postEvent: PostEvent,
-): Viewport | null {
-  if (isPageReload || !isRequestSupportedPlatform(platform)) {
-    return new Viewport({
-      height: window.innerHeight,
-      isExpanded: true,
-      postEvent,
-      stableHeight: window.innerHeight,
-      width: window.innerWidth,
-    });
-  }
-
-  const state = getStorageValue('viewport');
-  if (state) {
-    return new Viewport({ ...state, postEvent });
-  }
-
-  return null;
-}
-
-/**
- * Synchronizes specified Viewport instance with Telegram application and always saves its state
- * in local storage.
- * @param viewport - Viewport instance.
+ * Creates new bound instance of the Viewport component.
+ * @param props - properties to create new instance.
  */
-function bind(viewport: Viewport): Viewport {
-  viewport.listen();
+function instantiate(props: ViewportProps): Viewport {
+  const viewport = new Viewport(props);
 
   // TODO: Should probably use throttle for height.
   viewport.on('change', () => saveStorageValue('viewport', {
@@ -57,59 +23,72 @@ function bind(viewport: Viewport): Viewport {
     width: viewport.width,
   }));
 
+  viewport.listen();
+
   return viewport;
 }
 
 /**
- * Creates Viewport instance using its actual state from the storage. Otherwise, creates it
- * with default parameters.
+ * Creates Viewport instance using its actual state from the Telegram application.
  * @param isPageReload - was page reloaded.
  * @param platform - platform identifier.
  * @param postEvent - Bridge postEvent function.
+ * @param complete - is initialization complete.
  */
-export function createViewportSync(
+export function createViewport(
   isPageReload: boolean,
   platform: Platform,
   postEvent: PostEvent,
-): Viewport {
-  const viewport = bind(
-    tryCreate(isPageReload, platform, postEvent) || new Viewport({
-      width: 0,
-      height: 0,
-      isExpanded: false,
-      postEvent,
-      stableHeight: 0,
-    }),
-  );
+  complete: boolean,
+): Viewport | Promise<Viewport> {
+  // If page was reloaded, we expect viewport to be restored from the storage.
+  const state = isPageReload ? getStorageValue('viewport') : null;
+  if (state) {
+    return instantiate({ ...state, postEvent });
+  }
 
-  if (isRequestSupportedPlatform(platform)) {
-    viewport.sync({ postEvent, timeout: 100 }).catch((e) => {
-      // eslint-disable-next-line no-console
-      console.error('Unable to actualize viewport state', e);
+  // If platform has a stable viewport, it means we could instantiate Viewport using
+  // the window global object properties.
+  if (isStableViewportPlatform(platform)) {
+    return instantiate({
+      height: window.innerHeight,
+      isExpanded: true,
+      postEvent,
+      stableHeight: window.innerHeight,
+      width: window.innerWidth,
     });
   }
 
-  return viewport;
-}
-
-/**
- * Creates Viewport instance using its actual state from the Telegram application.
- * @param isPageReload - was page reloaded.
- * @param platform - platform identifier.
- * @param postEvent - Bridge postEvent function.
- */
-export async function createViewportAsync(
-  isPageReload: boolean,
-  platform: Platform,
-  postEvent: PostEvent,
-): Promise<Viewport> {
-  return bind(
-    tryCreate(isPageReload, platform, postEvent)
-    || await requestViewport({ postEvent, timeout: 100 })
-      .then(({ height, isStateStable, ...rest }) => new Viewport({
+  // If initialization is complete, we have to create Viewport instance using its actual
+  // state from the Telegram application.
+  if (complete) {
+    return requestViewport({
+      postEvent,
+      timeout: 5000,
+    })
+      .then(({ height, isStateStable, ...rest }) => instantiate({
         ...rest,
         height,
         stableHeight: isStateStable ? height : 0,
-      })),
-  );
+      }));
+  }
+
+  // Otherwise we have no sources to get viewport properties from. In this case we just
+  // return some "empty" Viewport instance and synchronize it in the background.
+  const viewport = instantiate({
+    width: 0,
+    height: 0,
+    isExpanded: false,
+    postEvent,
+    stableHeight: 0,
+  });
+
+  /* c8 ignore start */
+  viewport.sync({ postEvent, timeout: 5000 }).catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error('Unable to actualize viewport state', e);
+  });
+  /* c8 ignore stop */
+
+  return viewport;
 }

package/src/init/init.ts

@@ -7,9 +7,10 @@ import {
   createClosingBehavior,
   createMainButton,
   createMiniApp,
-  createRequestIdGenerator, createSettingsButton,
-  createThemeParams, createViewportAsync,
-  createViewportSync,
+  createRequestIdGenerator,
+  createSettingsButton,
+  createThemeParams,
+  createViewport,
 } from '~/init/creators/index.js';
 import { processCSSVars } from '~/init/css/index.js';
 import { InitData } from '~/init-data/index.js';
@@ -21,13 +22,16 @@ import { Utils } from '~/utils/index.js';
 
 import type { InitOptions, InitResult } from './types.js';
 
-type ComputedInitResult<O> = O extends { async: true } ? Promise<InitResult> : InitResult;
+type ComputedInitResult<O> = O extends { async: true } | { complete: true }
+  ? Promise<InitResult>
+  : InitResult;
 
 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,
+    complete = async,
     cssVars = false,
     acceptCustomStyles = false,
   } = options;
@@ -99,12 +103,9 @@ export function init(options: InitOptions = {}): InitResult | Promise<InitResult
         : {}),
     };
 
-    const viewport = async
-      ? createViewportAsync(isPageReload, platform, postEvent)
-      : createViewportSync(isPageReload, platform, postEvent);
-
-    if (viewport instanceof Promise) {
-      return viewport.then((vp) => {
+    const viewport = createViewport(isPageReload, platform, postEvent, complete);
+    if (viewport instanceof Promise || complete) {
+      return Promise.resolve(viewport).then((vp) => {
         processCSSVars(
           cssVars,
           result.miniApp,
@@ -112,10 +113,7 @@ export function init(options: InitOptions = {}): InitResult | Promise<InitResult
           vp,
         );
 
-        return {
-          ...result,
-          viewport: vp,
-        };
+        return { ...result, viewport: vp };
       });
     }
 
@@ -128,7 +126,7 @@ export function init(options: InitOptions = {}): InitResult | Promise<InitResult
 
     return { ...result, viewport };
   } catch (e) {
-    if (async) {
+    if (complete) {
       return Promise.reject(e);
     }
     throw e;

package/src/init/types.ts

@@ -62,10 +62,7 @@ export type InitCSSVarsOption = boolean | InitCSSVarsSpecificOption;
 
 export interface InitOptions {
   /**
-   * True if synchronization must be performed asynchronously. This allows init function to
-   * perform async operations. One of them is the actual viewport state retrieving from the
-   * Telegram application. Otherwise, viewport state will be retrieved later.
-   * @default false
+   * @deprecated This option name was considered inappropriate. Use `complete` instead.
    */
   async?: boolean;
 
@@ -87,4 +84,11 @@ export interface InitOptions {
    * @default false
    */
   cssVars?: InitCSSVarsOption;
+
+  /**
+   * True if initialization must be performed completely. This includes retrieving some components
+   * state from the Telegram application, and as a result, this makes initialization asynchronous.
+   * @default false
+   */
+  complete?: boolean;
 }

package/src/mini-app/contactParser.ts

@@ -17,7 +17,7 @@ export const contactParser = searchParams<RequestedContact>({
       from: 'first_name',
     },
     lastName: {
-      type: string(),
+      type: string().optional(),
       from: 'last_name',
     },
   }),

package/src/mini-app/types.ts

@@ -31,7 +31,7 @@ export interface RequestedContact {
     userId: number;
     phoneNumber: string;
     firstName: string;
-    lastName: string;
+    lastName?: string;
   };
   authDate: Date;
   hash: string;

package/src/types/platform.ts

@@ -7,8 +7,8 @@ export type Platform =
   | 'ios'
   | 'macos'
   | 'tdesktop'
-  | 'web'
-  | 'weba'
   | 'unigram'
   | 'unknown'
+  | 'web'
+  | 'weba'
   | string;

package/src/viewport/index.ts

@@ -1,3 +1,4 @@
+export * from './isStableViewportPlatform.js';
 export * from './requestViewport.js';
 export * from './types.js';
 export * from './Viewport.js';

package/src/viewport/isStableViewportPlatform.ts

@@ -0,0 +1,10 @@
+import type { Platform } from '~/types/index.js';
+
+/**
+ * Returns true if specified platform has stable viewport. Stable means not changing from time to
+ * time.
+ * @param platform - platform identifier.
+ */
+export function isStableViewportPlatform(platform: Platform): boolean {
+  return ['macos', 'tdesktop', 'unigram', 'web', 'weba'].includes(platform);
+}