@tma.js/sdk 1.3.0 → 1.4.1

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',

package/src/launch-params/retrieveFromLocation.ts

@@ -1,4 +1,4 @@
-import { parseLaunchParams } from './parseLaunchParams.js';
+import { retrieveFromUrl } from './retrieveFromUrl.js';
 import type { LaunchParams } from './types.js';
 
 /**
@@ -6,5 +6,5 @@ import type { LaunchParams } from './types.js';
  * @throws {Error} window.location.hash contains invalid data.
  */
 export function retrieveFromLocation(): LaunchParams {
-  return parseLaunchParams(window.location.hash.slice(1));
+  return retrieveFromUrl(window.location.href);
 }

package/src/launch-params/retrieveFromPerformance.ts

@@ -1,5 +1,5 @@
 import { getFirstNavigationEntry } from './getFirstNavigationEntry.js';
-import { parseLaunchParams } from './parseLaunchParams.js';
+import { retrieveFromUrl } from './retrieveFromUrl.js';
 import type { LaunchParams } from './types.js';
 
 /**
@@ -14,10 +14,5 @@ export function retrieveFromPerformance(): LaunchParams {
     throw new Error('Unable to get first navigation entry.');
   }
 
-  const hashMatch = navigationEntry.name.match(/#(.*)/);
-  if (!hashMatch) {
-    throw new Error('First navigation entry does not contain hash part.');
-  }
-
-  return parseLaunchParams(hashMatch[1]);
+  return retrieveFromUrl(navigationEntry.name);
 }

package/src/launch-params/retrieveFromUrl.ts

@@ -0,0 +1,19 @@
+import { parseLaunchParams } from '~/launch-params/parseLaunchParams.js';
+import type { LaunchParams } from '~/launch-params/types.js';
+
+/**
+ * Retrieves launch parameters from the specified URL.
+ * @param url - URL to extract launch parameters from.
+ */
+export function retrieveFromUrl(url: string): LaunchParams {
+  const queryParams = url.includes('?')
+    // If URL includes "?", we expect it to possibly contain "#". The reason is TMA allows passing
+    // start parameter via tgWebAppStartParam **query** parameter. Replacing "#" with "&" we
+    // expect merging query parameters with hash parameters and creating complete launch
+    // parameters information.
+    ? url.replace('#', '&').slice(url.indexOf('?') + 1)
+    // Otherwise, we expect specifying launch parameters only in the hash part.
+    : url.slice(url.indexOf('#') + 1);
+
+  return parseLaunchParams(queryParams);
+}

package/src/launch-params/types.ts

@@ -8,9 +8,9 @@ import type { Platform } from '~/types/index.js';
  */
 export interface LaunchParams {
   /**
-   * Current Mini Apps version.
+   * True if Mini App is currently launched in inline mode.
    */
-  version: string;
+  botInline?: boolean;
 
   /**
    * Current launch init data. Can be missing in case, application was launched via
@@ -29,19 +29,24 @@ export interface LaunchParams {
   platform: Platform;
 
   /**
-   * Mini App palette settings.
+   * True if application is required to show the Settings Button.
    */
-  themeParams: ThemeParamsParsed;
+  showSettings?: boolean;
 
   /**
-   * True if Mini App is currently launched in inline mode.
+   * Start parameter passed in the application link.
    */
-  botInline?: boolean;
+  startParam?: string;
 
   /**
-   * True if application is required to show the Settings Button.
+   * Mini App palette settings.
    */
-  showSettings?: boolean;
+  themeParams: ThemeParamsParsed;
+
+  /**
+   * Current Mini Apps version.
+   */
+  version: string;
 }
 
 export interface LaunchData {

package/src/logger/__tests__/Logger.ts

@@ -0,0 +1,107 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+
+import { Logger } from '../Logger';
+
+const now = new Date('2022-11-04T09:09:43.007Z');
+
+afterEach(() => {
+  vi.resetAllMocks();
+});
+
+beforeAll(() => {
+  vi.useFakeTimers().setSystemTime(now);
+});
+
+afterAll(() => {
+  vi.useRealTimers();
+});
+
+it('should not call console methods if logger is disabled', () => {
+  const logger = new Logger('', false);
+  const spy = vi.fn();
+
+  vi.spyOn(console, 'log').mockImplementation(spy);
+  vi.spyOn(console, 'warn').mockImplementation(spy);
+  vi.spyOn(console, 'error').mockImplementation(spy);
+
+  logger.log();
+  logger.warn();
+  logger.error();
+  expect(spy).not.toHaveBeenCalled();
+});
+
+describe('enable', () => {
+  it('should start logging messages into console', () => {
+    const logger = new Logger('', false);
+    const spy = vi.fn();
+
+    vi.spyOn(console, 'log').mockImplementation(spy);
+    logger.log();
+    expect(spy).not.toHaveBeenCalled();
+
+    logger.enable();
+    logger.log();
+    expect(spy).toHaveBeenCalledOnce();
+  });
+});
+
+describe('disable', () => {
+  it('should stop logging messages into console', () => {
+    const logger = new Logger('', true);
+    const spy = vi.fn();
+
+    vi.spyOn(console, 'log').mockImplementation(spy);
+    logger.log();
+    expect(spy).toHaveBeenCalledOnce();
+
+    spy.mockReset();
+
+    logger.disable();
+    logger.log();
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
+
+describe('error', () => {
+  it('should call console.error()', () => {
+    const logger = new Logger('My prefix', true);
+    const spy = vi.fn();
+    vi.spyOn(console, 'error').mockImplementation(spy);
+
+    logger.error('Test');
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy).toHaveBeenCalledWith('[09:09:43.007]', 'My prefix', 'Test');
+  });
+});
+
+describe('log', () => {
+  it('should call console.log()', () => {
+    const logger = new Logger('My prefix', true);
+    const spy = vi.fn();
+    vi.spyOn(console, 'log').mockImplementation(spy);
+
+    logger.log('Test');
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy).toHaveBeenCalledWith('[09:09:43.007]', 'My prefix', 'Test');
+  });
+});
+
+describe('warn', () => {
+  it('should call console.warn()', () => {
+    const logger = new Logger('My prefix', true);
+    const spy = vi.fn();
+    vi.spyOn(console, 'warn').mockImplementation(spy);
+
+    logger.warn('Test');
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy).toHaveBeenCalledWith('[09:09:43.007]', 'My prefix', 'Test');
+  });
+});