@tma.js/sdk 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tma.js/sdk",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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",
@@ -47,7 +47,7 @@
   },
   "scripts": {
     "test": "vitest --run",
-    "lint": "eslint src/**/*",
+    "lint": "eslint src",
     "lint:fix": "pnpm run lint --fix",
     "typecheck": "tsc --noEmit -p tsconfig.build.json",
     "build": "pnpm run build:default && pnpm run build:iife",

package/src/__tests__/globals.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  logger,
+  setDebug,
+  setTargetOrigin,
+  targetOrigin,
+} from '../globals';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('logger', () => {
+  it('should log message in case, debug mode is enabled. Otherwise no output should be shown', () => {
+    const spy = vi
+      .spyOn(console, 'log')
+      .mockImplementation(() => {
+      });
+
+    logger.log(123);
+    expect(spy).not.toHaveBeenCalled();
+
+    setDebug(true);
+    logger.log('Some log');
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    setDebug(false);
+    logger.log('Another log');
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('setTargetOrigin', () => {
+  it('should return set value via targetOrigin() function', () => {
+    setTargetOrigin('my test');
+    expect(targetOrigin()).toEqual('my test');
+  });
+});

package/src/back-button/__tests__/BackButton.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { BackButton } from '../BackButton';
+
+describe('hide', () => {
+  it('should call "web_app_setup_back_button" method with "is_visible" equal to false', () => {
+    const postEvent = vi.fn();
+    const backButton = new BackButton(false, '', postEvent);
+
+    expect(postEvent).toHaveBeenCalledTimes(0);
+    backButton.hide();
+    expect(postEvent).toHaveBeenCalledTimes(1);
+    expect(postEvent).toHaveBeenCalledWith('web_app_setup_back_button', { is_visible: false });
+  });
+
+  it('should emit "isVisibleChanged" event with false value', () => {
+    const backButton = new BackButton(true, '', vi.fn());
+    const listener = vi.fn();
+
+    backButton.on('change:isVisible', listener);
+    expect(listener).toHaveBeenCalledTimes(0);
+    backButton.hide();
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith(false);
+  });
+});
+
+describe('show', () => {
+  it('should call "web_app_setup_back_button" method with "is_visible" equal to true', () => {
+    const postEvent = vi.fn();
+    const backButton = new BackButton(false, '', postEvent);
+
+    expect(postEvent).toHaveBeenCalledTimes(0);
+    backButton.show();
+    expect(postEvent).toHaveBeenCalledTimes(1);
+    expect(postEvent).toHaveBeenCalledWith('web_app_setup_back_button', { is_visible: true });
+  });
+
+  it('should emit "isVisibleChanged" event with true value', () => {
+    const backButton = new BackButton(false, '', vi.fn());
+    const listener = vi.fn();
+
+    backButton.on('change:isVisible', listener);
+    expect(listener).toHaveBeenCalledTimes(0);
+    backButton.show();
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith(true);
+  });
+});
+
+// FIXME
+// it('on', () => {
+//   it('"click" event', () => {
+//    it('should add event listener to bridge\'s '
+//       + '"back_button_pressed" event', () => {
+//       const on = vi.fn();
+//       const backButton = new BackButton({ on } as any, '');
+//       const listener = vi.fn();
+//
+//       expect(on).toHaveBeenCalledTimes(0);
+//       backButton.on('click', listener);
+//       expect(on).toHaveBeenCalledTimes(1);
+//       expect(on).toHaveBeenCalledWith('back_button_pressed', listener);
+//     });
+//   });
+// });
+
+describe('off', () => {
+  // FIXME
+  // it('"click" event', () => {
+  //  it('should remove event listener from bridge\'s '
+  //     + '"back_button_pressed" event', () => {
+  //     const on = vi.fn();
+  //     const off = vi.fn();
+  //     const backButton = new BackButton({ on, off } as any, '');
+  //     const listener = vi.fn();
+  //
+  //     expect(on).toHaveBeenCalledTimes(0);
+  //     backButton.on('click', listener);
+  //     expect(on).toHaveBeenCalledTimes(1);
+  //     expect(on).toHaveBeenCalledWith('back_button_pressed', listener);
+  //
+  //     // TODO: We should probably emit back_button_pressed event to
+  //     //  make sure, listener was removed.
+  //
+  //     expect(off).toHaveBeenCalledTimes(0);
+  //     backButton.off('click', listener);
+  //     expect(off).toHaveBeenCalledTimes(1);
+  //     expect(off).toHaveBeenCalledWith('back_button_pressed', listener);
+  //   });
+  // });
+
+  describe('"isVisibleChanged" event', () => {
+    it('should remove event listener from event', () => {
+      const listener = vi.fn();
+      const backButton = new BackButton(false, '', vi.fn());
+
+      backButton.on('change:isVisible', listener);
+
+      expect(listener).toHaveBeenCalledTimes(0);
+      backButton.show();
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      backButton.off('change:isVisible', listener);
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      backButton.hide();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+describe('supports', () => {
+  describe('show / hide', () => {
+    it('should return true in case, BackButton version is 6.1 or higher. False, otherwise', () => {
+      const backButton1 = new BackButton(false, '6.0');
+      expect(backButton1.supports('show')).toBe(false);
+      expect(backButton1.supports('hide')).toBe(false);
+
+      const backButton2 = new BackButton(false, '6.1');
+      expect(backButton2.supports('show')).toBe(true);
+      expect(backButton2.supports('hide')).toBe(true);
+
+      const backButton3 = new BackButton(false, '6.2');
+      expect(backButton3.supports('show')).toBe(true);
+      expect(backButton3.supports('hide')).toBe(true);
+    });
+  });
+});

package/src/bridge/__tests__/request.ts

@@ -0,0 +1,236 @@
+/* eslint-disable */
+import {
+  expect,
+  it,
+  vi,
+  SpyInstance,
+  beforeEach,
+  afterEach,
+  describe,
+  beforeAll,
+  afterAll,
+} from 'vitest';
+
+import { request } from '../request';
+import { type PostEvent, postEvent as globalPostEvent } from '../methods/postEvent';
+import { createWindow } from '../../../test-utils/createWindow';
+import { dispatchWindowMessageEvent } from '../../../test-utils/dispatchWindowMessageEvent';
+
+vi.mock('../methods/postEvent.js', async () => {
+  const { postEvent: actualPostEvent } = await vi
+    .importActual('../methods/postEvent.js') as { postEvent: PostEvent };
+
+  return {
+    postEvent: vi.fn(actualPostEvent),
+  };
+});
+
+let windowSpy: SpyInstance<[], Window & typeof globalThis>;
+
+beforeAll(() => {
+  vi.useFakeTimers();
+});
+
+afterAll(() => {
+  vi.useRealTimers();
+});
+
+beforeEach(() => {
+  windowSpy = createWindow({ env: 'iframe' });
+});
+
+afterEach(() => {
+  windowSpy.mockRestore();
+});
+
+function emptyCatch() {
+
+}
+
+describe('options', () => {
+  describe('timeout', () => {
+    it('should throw an error in case, timeout was reached', () => {
+      const promise = request('web_app_request_phone', 'phone_requested', {
+        timeout: 1000,
+      });
+
+      vi.advanceTimersByTime(1500);
+
+      return promise.catch(emptyCatch).finally(() => {
+        expect(promise).rejects.toEqual(new Error('Async call timeout exceeded. Timeout: 1000'));
+      });
+    });
+
+    it('should not throw an error in case, data was received before timeout', () => {
+      const promise = request('web_app_request_phone', 'phone_requested', {
+        timeout: 1000,
+      });
+
+      vi.advanceTimersByTime(500);
+      dispatchWindowMessageEvent('phone_requested', { status: 'allowed' });
+      vi.advanceTimersByTime(1000);
+
+      return promise.catch(emptyCatch).finally(() => {
+        expect(promise).resolves.toStrictEqual({ status: 'allowed' });
+      });
+    });
+  });
+
+  describe('postEvent', () => {
+    it('should use specified postEvent property', () => {
+      const postEvent = vi.fn();
+      request('web_app_request_phone', 'phone_requested', { postEvent });
+      expect(postEvent).toHaveBeenCalledWith('web_app_request_phone', undefined);
+    });
+
+    it('should use global postEvent function if according property was not specified', () => {
+      request('web_app_request_phone', 'phone_requested');
+      expect(globalPostEvent).toHaveBeenCalledWith('web_app_request_phone', undefined);
+    });
+
+    it('should reject promise in case, postEvent threw an error', () => {
+      const promise = request('web_app_request_phone', 'phone_requested', {
+        postEvent: () => {
+          throw new Error('Nope!');
+        },
+      });
+      expect(promise).rejects.toStrictEqual(Error('Nope!'));
+    });
+  });
+
+  describe('capture', () => {
+    it('should capture an event in case, capture method returned true', () => {
+      const promise = request('web_app_request_phone', 'phone_requested', {
+        timeout: 1000,
+        capture: ({ status }) => status === 'allowed',
+      });
+
+      vi.advanceTimersByTime(500);
+      dispatchWindowMessageEvent('phone_requested', { status: 'allowed' });
+      vi.advanceTimersByTime(1000);
+
+      return promise.catch(emptyCatch).finally(() => {
+        expect(promise).resolves.toStrictEqual({ status: 'allowed' });
+      });
+    });
+
+    it('should not capture an event in case, capture method returned false', () => {
+      const promise = request('web_app_request_phone', 'phone_requested', {
+        timeout: 500,
+        capture: ({ status }) => status === 'allowed',
+      });
+
+      dispatchWindowMessageEvent('phone_requested', { status: 'declined' });
+      vi.advanceTimersByTime(1000);
+
+      return promise.catch(emptyCatch).finally(() => {
+        expect(promise).rejects.toEqual(new Error('Async call timeout exceeded. Timeout: 500'));
+      });
+    });
+  });
+});
+
+describe('with request id', () => {
+  it('should ignore event with the different request id', () => {
+    const promise = request('web_app_read_text_from_clipboard', { req_id: 'a' }, 'clipboard_text_received', {
+      timeout: 1000,
+    });
+
+    dispatchWindowMessageEvent('clipboard_text_received', { req_id: 'b' });
+    vi.advanceTimersByTime(1500);
+
+    return promise.catch(emptyCatch).finally(() => {
+      expect(promise).rejects.toEqual(new Error('Async call timeout exceeded. Timeout: 1000'));
+    });
+  });
+
+  it('should capture event with the same request id', () => {
+    const promise = request('web_app_read_text_from_clipboard', { req_id: 'a' }, 'clipboard_text_received', {
+      timeout: 1000,
+    });
+
+    dispatchWindowMessageEvent('clipboard_text_received', {
+      req_id: 'a',
+      data: 'from clipboard',
+    });
+    vi.advanceTimersByTime(1500);
+
+    return promise.catch(emptyCatch).finally(() => {
+      expect(promise).resolves.toStrictEqual({
+        req_id: 'a',
+        data: 'from clipboard',
+      });
+    });
+  });
+});
+
+describe('multiple events', () => {
+  describe('no params', () => {
+    it('should handle any of the specified events', () => {
+      const promise = request(
+        'web_app_request_phone',
+        ['phone_requested', 'write_access_requested'],
+        { timeout: 1000 },
+      );
+      const promise2 = request(
+        'web_app_request_phone',
+        ['phone_requested', 'write_access_requested'],
+        { timeout: 1000 },
+      );
+
+      dispatchWindowMessageEvent('phone_requested', { status: 'allowed' });
+      dispatchWindowMessageEvent('write_access_requested', { status: 'declined' });
+      vi.advanceTimersByTime(1500);
+
+      return Promise
+        .all([promise, promise2])
+        .catch(emptyCatch)
+        .finally(() => {
+          expect(promise).resolves.toStrictEqual({ status: 'allowed' });
+          expect(promise2).resolves.toStrictEqual({ status: 'declined' });
+        });
+    });
+  });
+
+  describe('with params', () => {
+    it('should handle any of the specified events', () => {
+      const promise = request(
+        'web_app_data_send',
+        { data: 'abc' },
+        ['phone_requested', 'write_access_requested'],
+        { timeout: 1000 },
+      );
+      const promise2 = request(
+        'web_app_data_send',
+        { data: 'abc' },
+        ['phone_requested', 'write_access_requested'],
+        { timeout: 1000 },
+      );
+
+      dispatchWindowMessageEvent('phone_requested', { status: 'allowed' });
+      dispatchWindowMessageEvent('write_access_requested', { status: 'declined' });
+      vi.advanceTimersByTime(1500);
+
+      return Promise
+        .all([promise, promise2])
+        .catch(emptyCatch)
+        .finally(() => {
+          expect(promise).resolves.toStrictEqual({ status: 'allowed' });
+          expect(promise2).resolves.toStrictEqual({ status: 'declined' });
+        });
+    });
+  });
+});
+
+// it('no params methods', () => {
+//  it('should properly handle ')
+// });
+
+// it('with request id', () => {
+//   const promise = request('web_app_read_text_from_clipboard', { req_id: 'a' }, 'clipboard_text_received');
+//
+//   dispatchWindowEvent('clipboard_text_received', { req_id: 'b' });
+//   expect(promise).resolves.toHaveLength(0);
+//   dispatchWindowEvent('clipboard_text_received', { req_id: 'a' });
+//   expect(promise).resolves.toHaveLength(1);
+// });

package/src/bridge/env/__tests__/hasExternalNotify.ts

@@ -0,0 +1,15 @@
+import { expect, it } from 'vitest';
+
+import { hasExternalNotify } from '../hasExternalNotify.js';
+
+it('should return true if passed object contains path property "external.notify" and "notify" is a function property.', () => {
+  expect(hasExternalNotify({})).toBe(false);
+  expect(hasExternalNotify({ external: {} })).toBe(false);
+  expect(hasExternalNotify({ external: { notify: [] } })).toBe(false);
+  expect(hasExternalNotify({
+    external: {
+      notify: () => {
+      },
+    },
+  })).toBe(true);
+});

package/src/bridge/env/__tests__/hasWebviewProxy.ts

@@ -0,0 +1,15 @@
+import { expect, it } from 'vitest';
+
+import { hasWebviewProxy } from '../hasWebviewProxy.js';
+
+it('should return true if passed object contains path property "TelegramWebviewProxy.postEvent" and "postEvent" is a function property.', () => {
+  expect(hasWebviewProxy({})).toBe(false);
+  expect(hasWebviewProxy({ TelegramWebviewProxy: {} })).toBe(false);
+  expect(hasWebviewProxy({ TelegramWebviewProxy: { postEvent: [] } })).toBe(false);
+  expect(hasWebviewProxy({
+    TelegramWebviewProxy: {
+      postEvent: () => {
+      },
+    },
+  })).toBe(true);
+});

package/src/bridge/env/__tests__/isIframe.ts

@@ -0,0 +1,30 @@
+import { afterAll, afterEach, expect, it, vi } from 'vitest';
+
+import { isIframe } from '../isIframe.js';
+
+const windowSpy = vi.spyOn(window, 'window', 'get');
+
+afterEach(() => {
+  windowSpy.mockReset();
+});
+
+afterAll(() => {
+  windowSpy.mockRestore();
+});
+
+it('should return true in case window.self !== window.top. Otherwise, false.', () => {
+  windowSpy.mockImplementation(() => ({ self: 900, top: 1000 }) as any);
+  expect(isIframe()).toBe(true);
+
+  windowSpy.mockImplementation(() => ({ self: 900, top: 900 }) as any);
+  expect(isIframe()).toBe(false);
+});
+
+it('should return true in case window.self getter threw an error', () => {
+  windowSpy.mockImplementation(() => ({
+    get self() {
+      throw new Error();
+    },
+  }) as any);
+  expect(isIframe()).toBe(true);
+});

package/src/bridge/events/__tests__/createEmitter.ts

@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createWindow, type WindowSpy } from '../../../../test-utils/createWindow';
+import { dispatchWindowMessageEvent } from '../../../../test-utils/dispatchWindowMessageEvent';
+import { createEmitter } from '../createEmitter';
+import type { MiniAppsEventName, MiniAppsEventParams } from '../events';
+
+type TestCase<E extends MiniAppsEventName> =
+  | [input: any, expected: MiniAppsEventParams<E>]
+  | MiniAppsEventParams<E>;
+
+type TestCases = {
+  [E in MiniAppsEventName]: MiniAppsEventParams<E> extends undefined
+    ? [E]
+    : [E, TestCase<E> | TestCase<E>[]];
+}[MiniAppsEventName][];
+
+let windowSpy: WindowSpy;
+
+beforeEach(() => {
+  windowSpy = createWindow({
+    innerWidth: 1920,
+    innerHeight: 1080,
+  });
+});
+
+afterEach(() => {
+  windowSpy.mockRestore();
+});
+
+it('should emit "viewport_changed" event in case, window changed its size', () => {
+  const emitter = createEmitter();
+  const spy = vi.fn();
+
+  emitter.on('viewport_changed', spy);
+
+  window.dispatchEvent(new CustomEvent('resize'));
+
+  expect(spy).toHaveBeenCalledTimes(1);
+  expect(spy).toHaveBeenCalledWith({
+    width: 1920,
+    height: 1080,
+    is_state_stable: true,
+    is_expanded: true,
+  });
+});
+
+describe('events handling', () => {
+  const testCases: TestCases = [
+    ['viewport_changed', {
+      height: 120,
+      width: 300,
+      is_expanded: true,
+      is_state_stable: false,
+    }],
+    ['theme_changed', {
+      theme_params: {
+        bg_color: '#aabbdd',
+        text_color: '#113322',
+        hint_color: '#132245',
+        link_color: '#133322',
+        button_color: '#a23135',
+        button_text_color: '#aa213f',
+      },
+    }],
+    ['popup_closed', [
+      [{ button_id: 'ok' }, { button_id: 'ok' }],
+      [{ button_id: null }, {}],
+      [{ button_id: undefined }, {}],
+      [null, {}],
+      [undefined, {}],
+    ]],
+    ['set_custom_style', '.scroll {}'],
+    ['qr_text_received', { data: 'some QR data' }],
+    ['main_button_pressed'],
+    ['back_button_pressed'],
+    ['settings_button_pressed'],
+    ['scan_qr_popup_closed'],
+    ['clipboard_text_received', {
+      req_id: 'request id',
+      data: 'clipboard value',
+    }],
+    ['invoice_closed', { slug: '&&*Sh1j213kx', status: 'PAID' }],
+    ['phone_requested', { status: 'sent' }],
+    ['custom_method_invoked', [
+      [{ req_id: '1', result: 'My result' }],
+      [{ req_id: '2', error: 'Something is wrong' }],
+    ]],
+    ['write_access_requested', { status: 'allowed' }],
+    ['unknown_event', [
+      ['hello', 'hello'],
+      [{ there: true }, { there: true }],
+    ]] as any,
+  ];
+
+  testCases.forEach(([event, inputOrCaseOrCases]) => {
+    it(`should correctly handle "${event}" event data`, () => {
+      const spy = vi.fn();
+      const emitter = createEmitter();
+
+      emitter.on(event, spy);
+
+      // No expected data to be passed to listener.
+      if (inputOrCaseOrCases === undefined) {
+        dispatchWindowMessageEvent(event);
+        expect(spy).toBeCalledWith();
+        return;
+      }
+
+      // Input is equal to expected result.
+      if (!Array.isArray(inputOrCaseOrCases)) {
+        dispatchWindowMessageEvent(event, inputOrCaseOrCases);
+        expect(spy).toBeCalledWith(inputOrCaseOrCases);
+        return;
+      }
+
+      // Input differs from expected result.
+      if (!Array.isArray(inputOrCaseOrCases[0])) {
+        const [input, expected] = inputOrCaseOrCases;
+        dispatchWindowMessageEvent(event, input);
+        expect(spy).toBeCalledWith(expected);
+        return;
+      }
+
+      // List of cases.
+      inputOrCaseOrCases.forEach(([input, expected = input]) => {
+        dispatchWindowMessageEvent(event, input);
+        expect(spy).toBeCalledWith(expected);
+      });
+    });
+  });
+
+  it('should not emit event in case, it contains incorrect payload', () => {
+    const spy = vi.fn();
+    const emitter = createEmitter();
+
+    emitter.on('viewport_changed', spy);
+
+    dispatchWindowMessageEvent('viewport_changed', 'broken data');
+
+    expect(spy).not.toBeCalled();
+  });
+});

package/src/bridge/events/__tests__/off.ts

@@ -0,0 +1,34 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+import { createWindow, type WindowSpy } from '../../../../test-utils/createWindow';
+import { dispatchWindowMessageEvent } from '../../../../test-utils/dispatchWindowMessageEvent';
+import { off } from '../off';
+import { on } from '../on';
+
+let windowSpy: WindowSpy;
+
+beforeEach(() => {
+  windowSpy = createWindow();
+});
+
+afterEach(() => {
+  windowSpy.mockRestore();
+});
+
+it('should remove listener', () => {
+  const listener = vi.fn();
+  const emit = () => dispatchWindowMessageEvent('viewport_changed', {
+    height: 123,
+    width: 321,
+    is_expanded: false,
+    is_state_stable: false,
+  });
+
+  on('viewport_changed', listener);
+  emit();
+  expect(listener).toHaveBeenCalledTimes(1);
+
+  off('viewport_changed', listener);
+  emit();
+  expect(listener).toHaveBeenCalledTimes(1);
+});