@tma.js/sdk 1.2.1 → 1.4.0

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/init-data/__tests__/InitData.ts

@@ -0,0 +1,98 @@
+import { expect, it } from 'vitest';
+
+import { InitData } from '../InitData';
+
+it('should return fields specified in constructor', () => {
+  const authDate = new Date(123);
+  const data1 = new InitData({ authDate, hash: 'hash' });
+  expect(data1.authDate).toBe(authDate);
+  expect(data1.canSendAfter).toBeUndefined();
+  expect(data1.chat).toBeUndefined();
+  expect(data1.chatType).toBeUndefined();
+  expect(data1.chatInstance).toBeUndefined();
+  expect(data1.hash).toBe('hash');
+  expect(data1.queryId).toBeUndefined();
+  expect(data1.receiver).toBeUndefined();
+  expect(data1.startParam).toBeUndefined();
+  expect(data1.user).toBeUndefined();
+
+  const canSendAfter = 1;
+  const data2 = new InitData({
+    authDate,
+    canSendAfter,
+    chat: {
+      id: 999,
+      photoUrl: 'photo',
+      type: 'group',
+      title: 'Title',
+    },
+    chatType: 'sender',
+    chatInstance: 'abc',
+    hash: 'joke',
+    queryId: 'query id',
+    receiver: {
+      id: 1000,
+      photoUrl: 'receiver photo',
+      firstName: 'a',
+      lastName: 'b',
+      username: 'c',
+      isBot: false,
+      isPremium: false,
+      languageCode: 'en',
+    },
+    startParam: 'param',
+    user: {
+      id: 2000,
+      photoUrl: 'user photo',
+      firstName: 'a',
+      lastName: 'b',
+      username: 'c',
+      languageCode: 'en',
+    },
+  });
+  expect(data2.authDate).toBe(authDate);
+  expect(data2.canSendAfter).toBe(canSendAfter);
+  expect(data2.chat).toStrictEqual({
+    id: 999,
+    photoUrl: 'photo',
+    type: 'group',
+    title: 'Title',
+  });
+  expect(data2.chatType).toBe('sender');
+  expect(data2.chatInstance).toBe('abc');
+  expect(data2.hash).toBe('joke');
+  expect(data2.queryId).toBe('query id');
+  expect(data2.receiver).toStrictEqual({
+    id: 1000,
+    photoUrl: 'receiver photo',
+    firstName: 'a',
+    lastName: 'b',
+    username: 'c',
+    isBot: false,
+    isPremium: false,
+    languageCode: 'en',
+  });
+  expect(data2.startParam).toBe('param');
+  expect(data2.user).toStrictEqual({
+    id: 2000,
+    photoUrl: 'user photo',
+    firstName: 'a',
+    lastName: 'b',
+    username: 'c',
+    languageCode: 'en',
+  });
+});
+
+it('should have canSendAfterData equal to authDate + canSendAfter seconds', () => {
+  const authDate = new Date();
+  const initData = new InitData({
+    authDate,
+    hash: 'abc',
+    canSendAfter: 32000,
+  });
+
+  expect(initData.canSendAfter).toBe(32000);
+  expect(initData.canSendAfterDate).toStrictEqual(
+    new Date(authDate.getTime() + 32000000),
+  );
+});

package/src/init-data/__tests__/chatParser.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+
+import { chatParser } from '../chatParser';
+
+describe('id', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(
+      () => chatParser().parse({
+        type: 'group chat',
+        title: 'My chat',
+      }),
+    ).toThrow();
+  });
+
+  it('should parse source property as number and pass it to the "id" property', () => {
+    expect(
+      chatParser().parse({
+        id: 882,
+        type: 'group chat',
+        title: 'My chat',
+      }),
+    ).toMatchObject({
+      id: 882,
+    });
+  });
+});
+
+describe('type', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(
+      () => chatParser().parse({
+        id: 223,
+        title: 'My chat',
+      }),
+    ).toThrow();
+  });
+
+  it('should parse source property as number and pass it to the "type" property', () => {
+    expect(
+      chatParser().parse({
+        id: 882,
+        type: 'group chat',
+        title: 'My chat',
+      }),
+    ).toMatchObject({
+      type: 'group chat',
+    });
+  });
+});
+
+describe('title', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(
+      () => chatParser().parse({
+        id: 223,
+        type: 'group chat',
+      }),
+    ).toThrow();
+  });
+
+  it('should parse source property as number and pass it to the "title" property', () => {
+    expect(
+      chatParser().parse({
+        id: 882,
+        type: 'group chat',
+        title: 'My chat',
+      }),
+    ).toMatchObject({
+      title: 'My chat',
+    });
+  });
+});
+
+describe('photo_url', () => {
+  it('should parse source property as number and pass it to the "photoUrl" property', () => {
+    expect(
+      chatParser().parse({
+        id: 882,
+        type: 'group chat',
+        title: 'My chat',
+        photo_url: 'https://image.com',
+      }),
+    ).toMatchObject({
+      photoUrl: 'https://image.com',
+    });
+  });
+});
+
+describe('username', () => {
+  it('should parse source property as number and pass it to the "username" property', () => {
+    expect(
+      chatParser().parse({
+        id: 882,
+        type: 'group chat',
+        title: 'My chat',
+        username: 'Johny Bravo',
+      }),
+    ).toMatchObject({
+      username: 'Johny Bravo',
+    });
+  });
+});

package/src/init-data/__tests__/initDataParser.ts

@@ -0,0 +1,136 @@
+import { toSearchParams } from 'test-utils';
+import { describe, expect, it } from 'vitest';
+
+import { initDataParser } from '../initDataParser';
+
+describe('auth_date', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(() => initDataParser().parse(toSearchParams({ hash: 'abcd' }))).toThrow();
+  });
+
+  it('should parse source property as Date and pass it to the "authDate" property', () => {
+    expect(initDataParser().parse(toSearchParams({ auth_date: 1, hash: 'abcd' }))).toMatchObject({
+      authDate: new Date(1000),
+    });
+  });
+});
+
+describe('can_send_after', () => {
+  it('should parse source property as Date and pass it to the "canSendAfter" property', () => {
+    expect(
+      initDataParser().parse(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+        can_send_after: 8882,
+      })),
+    ).toMatchObject({
+      canSendAfter: 8882,
+    });
+  });
+});
+
+describe('chat', () => {
+  it('should parse source property as Chat and pass it to the "chat" property', () => {
+    expect(
+      initDataParser().parse(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+        chat: {
+          id: 5,
+          type: 'group chat',
+          title: 'My Chat',
+          photo_url: 'https://johny.com',
+          username: 'Johny Chat',
+        },
+      })),
+    ).toMatchObject({
+      chat: {
+        id: 5,
+        type: 'group chat',
+        title: 'My Chat',
+        photoUrl: 'https://johny.com',
+        username: 'Johny Chat',
+      },
+    });
+  });
+});
+
+describe('hash', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(
+      () => initDataParser().parse(toSearchParams({
+        auth_date: 1,
+      })),
+    ).toThrow();
+  });
+
+  it('should parse source property as string and pass it to the "hash" property', () => {
+    expect(
+      initDataParser().parse(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+      })),
+    ).toMatchObject({
+      hash: 'abcd',
+    });
+  });
+});
+
+[
+  ['chat_instance', 'chatInstance'],
+  ['chat_type', 'chatType'],
+  ['query_id', 'queryId'],
+  ['start_param', 'startParam'],
+].forEach(([from, to]) => {
+  describe(from, () => {
+    it(`should parse source property as string and pass it to the "${to}" property`, () => {
+      expect(
+        initDataParser().parse(toSearchParams({
+          auth_date: 1,
+          hash: 'abcd',
+          [from]: 'my custom property',
+        })),
+      ).toMatchObject({
+        [to]: 'my custom property',
+      });
+    });
+  });
+});
+
+['user', 'receiver'].forEach((property) => {
+  describe(property, () => {
+    it('should parse source property as User and pass it to the property with the same name', () => {
+      expect(
+        initDataParser().parse(toSearchParams({
+          auth_date: 1,
+          hash: 'abcd',
+          [property]: {
+            added_to_attachment_menu: true,
+            allows_write_to_pm: false,
+            first_name: 'Johny',
+            id: 333,
+            is_bot: false,
+            is_premium: true,
+            language_code: 'en',
+            last_name: 'Bravo',
+            photo_url: 'https://johny.com',
+            username: 'johnybravo',
+          },
+        })),
+      ).toMatchObject({
+        [property]: {
+          addedToAttachmentMenu: true,
+          allowsWriteToPm: false,
+          firstName: 'Johny',
+          id: 333,
+          isBot: false,
+          isPremium: true,
+          languageCode: 'en',
+          lastName: 'Bravo',
+          photoUrl: 'https://johny.com',
+          username: 'johnybravo',
+        },
+      });
+    });
+  });
+});

package/src/init-data/__tests__/parseInitData.ts

@@ -0,0 +1,136 @@
+import { toSearchParams } from 'test-utils';
+import { describe, expect, it } from 'vitest';
+
+import { parseInitData } from '../parseInitData';
+
+describe('auth_date', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(() => parseInitData(toSearchParams({ hash: 'abcd' }))).toThrow();
+  });
+
+  it('should parse source property as Date and pass it to the "authDate" property', () => {
+    expect(parseInitData(toSearchParams({ auth_date: 1, hash: 'abcd' }))).toMatchObject({
+      authDate: new Date(1000),
+    });
+  });
+});
+
+describe('can_send_after', () => {
+  it('should parse source property as Date and pass it to the "canSendAfter" property', () => {
+    expect(
+      parseInitData(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+        can_send_after: 8882,
+      })),
+    ).toMatchObject({
+      canSendAfter: 8882,
+    });
+  });
+});
+
+describe('chat', () => {
+  it('should parse source property as Chat and pass it to the "chat" property', () => {
+    expect(
+      parseInitData(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+        chat: {
+          id: 5,
+          type: 'group chat',
+          title: 'My Chat',
+          photo_url: 'https://johny.com',
+          username: 'Johny Chat',
+        },
+      })),
+    ).toMatchObject({
+      chat: {
+        id: 5,
+        type: 'group chat',
+        title: 'My Chat',
+        photoUrl: 'https://johny.com',
+        username: 'Johny Chat',
+      },
+    });
+  });
+});
+
+describe('hash', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(
+      () => parseInitData(toSearchParams({
+        auth_date: 1,
+      })),
+    ).toThrow();
+  });
+
+  it('should parse source property as string and pass it to the "hash" property', () => {
+    expect(
+      parseInitData(toSearchParams({
+        auth_date: 1,
+        hash: 'abcd',
+      })),
+    ).toMatchObject({
+      hash: 'abcd',
+    });
+  });
+});
+
+[
+  ['chat_instance', 'chatInstance'],
+  ['chat_type', 'chatType'],
+  ['query_id', 'queryId'],
+  ['start_param', 'startParam'],
+].forEach(([from, to]) => {
+  describe(from, () => {
+    it(`should parse source property as string and pass it to the "${to}" property`, () => {
+      expect(
+        parseInitData(toSearchParams({
+          auth_date: 1,
+          hash: 'abcd',
+          [from]: 'my custom property',
+        })),
+      ).toMatchObject({
+        [to]: 'my custom property',
+      });
+    });
+  });
+});
+
+['user', 'receiver'].forEach((property) => {
+  describe(property, () => {
+    it('should parse source property as User and pass it to the property with the same name', () => {
+      expect(
+        parseInitData(toSearchParams({
+          auth_date: 1,
+          hash: 'abcd',
+          [property]: {
+            added_to_attachment_menu: true,
+            allows_write_to_pm: false,
+            first_name: 'Johny',
+            id: 333,
+            is_bot: false,
+            is_premium: true,
+            language_code: 'en',
+            last_name: 'Bravo',
+            photo_url: 'https://johny.com',
+            username: 'johnybravo',
+          },
+        })),
+      ).toMatchObject({
+        [property]: {
+          addedToAttachmentMenu: true,
+          allowsWriteToPm: false,
+          firstName: 'Johny',
+          id: 333,
+          isBot: false,
+          isPremium: true,
+          languageCode: 'en',
+          lastName: 'Bravo',
+          photoUrl: 'https://johny.com',
+          username: 'johnybravo',
+        },
+      });
+    });
+  });
+});

package/src/init-data/__tests__/userParser.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import { userParser } from '../userParser';
+
+describe('first_name', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(() => userParser().parse({ id: 123 })).toThrow();
+  });
+
+  it('should parse source property as string and pass it to the "firstName" property', () => {
+    expect(
+      userParser().parse({ id: 123, first_name: 'Pavel' }),
+    ).toMatchObject({
+      firstName: 'Pavel',
+    });
+  });
+});
+
+describe('id', () => {
+  it('should throw an error in case, this property is missing', () => {
+    expect(() => userParser().parse({ first_name: 'Pavel' })).toThrow();
+  });
+
+  it('should parse source property as number and pass it to the "id" property', () => {
+    expect(
+      userParser().parse({
+        id: 123,
+        first_name: 'Pavel',
+      }),
+    ).toMatchObject({
+      id: 123,
+    });
+  });
+});
+
+// Check optional booleans.
+[
+  ['added_to_attachment_menu', 'addedToAttachmentMenu'],
+  ['allows_write_to_pm', 'allowsWriteToPm'],
+  ['is_bot', 'isBot'],
+  ['is_premium', 'isPremium'],
+].forEach(([from, to]) => {
+  describe(from, () => {
+    it(`should parse source property as boolean and pass it to the "${to}" property`, () => {
+      expect(
+        userParser().parse({
+          id: 123,
+          first_name: 'Pavel',
+          [from]: false,
+        }),
+      ).toMatchObject({
+        [to]: false,
+      });
+
+      expect(
+        () => userParser().parse({
+          id: 123,
+          first_name: 'Pavel',
+          [from]: 'non-boolean',
+        }),
+      ).toThrow();
+    });
+  });
+});
+
+// Check optional strings.
+[
+  ['language_code', 'languageCode'],
+  ['last_name', 'lastName'],
+  ['photo_url', 'photoUrl'],
+  ['username', 'username'],
+].forEach(([from, to]) => {
+  describe(from, () => {
+    it(`should parse source property as string and pass it to the "${to}" property`, () => {
+      expect(
+        userParser().parse({
+          id: 123,
+          first_name: 'Pavel',
+          [from]: 'my custom property',
+        }),
+      ).toMatchObject({
+        [to]: 'my custom property',
+      });
+
+      expect(
+        () => userParser().parse({
+          id: 123,
+          first_name: 'Pavel',
+          [from]: {
+            key: 'cant parse it',
+          },
+        }),
+      ).toThrow();
+    });
+  });
+});

package/src/launch-params/__tests__/retrieveFromUrl.ts

@@ -0,0 +1,19 @@
+import { expect, it } from 'vitest';
+import { retrieveFromUrl } from '../retrieveFromUrl';
+
+it('should return launch parameters based on hash only in case, URL does not contain the query part', () => {
+  expect(retrieveFromUrl('#tgWebAppPlatform=tdesktop&tgWebAppVersion=7.0&tgWebAppThemeParams=%7B%7D')).toEqual({
+    platform: 'tdesktop',
+    version: '7.0',
+    themeParams: {},
+  });
+});
+
+it('should return launch parameters based on query params and hash in case, URL contains both parts', () => {
+  expect(retrieveFromUrl('?tgWebAppStartParam=900#tgWebAppPlatform=tdesktop&tgWebAppVersion=7.0&tgWebAppThemeParams=%7B%7D')).toEqual({
+    platform: 'tdesktop',
+    version: '7.0',
+    themeParams: {},
+    startParam: '900',
+  });
+});

package/src/launch-params/index.ts

@@ -6,6 +6,7 @@ export * from './parseLaunchParams.js';
 export * from './retrieveCurrent.js';
 export * from './retrieveFromLocation.js';
 export * from './retrieveFromPerformance.js';
+export * from './retrieveFromUrl.js';
 export * from './retrieveLaunchData.js';
 export * from './serializeLaunchParams.js';
 export * from './storage.js';

package/src/launch-params/launchParamsParser.ts

@@ -29,6 +29,10 @@ export function launchParamsParser() {
       type: boolean().optional(),
       from: 'tgWebAppShowSettings',
     },
+    startParam: {
+      type: string().optional(),
+      from: 'tgWebAppStartParam',
+    },
     themeParams: {
       type: themeParamsParser(),
       from: 'tgWebAppThemeParams',