@tma.js/sdk 1.4.3 → 1.4.6

package/src/theme-params/types.ts

@@ -1,33 +0,0 @@
-import type { RGB } from '~/colors/index.js';
-import type { StateEvents } from '~/state/index.js';
-
-export type ThemeParamsKey =
-  | 'accentTextColor'
-  | 'backgroundColor'
-  | 'buttonColor'
-  | 'buttonTextColor'
-  | 'destructiveTextColor'
-  | 'headerBackgroundColor'
-  | 'hintColor'
-  | 'linkColor'
-  | 'secondaryBackgroundColor'
-  | 'sectionBackgroundColor'
-  | 'sectionHeaderTextColor'
-  | 'subtitleTextColor'
-  | 'textColor';
-
-/**
- * Application [theme parameters](https://docs.telegram-mini-apps.com/platform/functionality/theming).
- * Defines palette used by the Telegram application.
- */
-export interface ThemeParamsParsed {
-  [key: ThemeParamsKey | string]: RGB | undefined;
-}
-
-export type ThemeParamsState = ThemeParamsParsed;
-
-export type ThemeParamsEvents = StateEvents<ThemeParamsState>;
-
-export type ThemeParamsEventName = keyof ThemeParamsEvents;
-
-export type ThemeParamsEventListener<E extends ThemeParamsEventName> = ThemeParamsEvents[E];

package/src/timeout/TimeoutError.ts

@@ -1,6 +0,0 @@
-export class TimeoutError extends Error {
-  constructor(timeout: number) {
-    super(`Async call timeout exceeded. Timeout: ${timeout}`);
-    Object.setPrototypeOf(this, TimeoutError.prototype);
-  }
-}

package/src/timeout/__tests__/isTimeoutError.ts

@@ -1,9 +0,0 @@
-import { expect, it } from 'vitest';
-
-import { isTimeoutError } from '../isTimeoutError';
-import { TimeoutError } from '../TimeoutError';
-
-it('should return true if passed value is instance of TimeoutError', () => {
-  expect(isTimeoutError(null)).toBe(false);
-  expect(isTimeoutError(new TimeoutError(1000))).toBe(true);
-});

package/src/timeout/__tests__/withTimeout.ts

@@ -1,28 +0,0 @@
-import { afterAll, beforeAll, expect, it, vi } from 'vitest';
-
-import { TimeoutError, withTimeout } from '../index';
-
-beforeAll(() => {
-  vi.useFakeTimers();
-});
-
-afterAll(() => {
-  vi.useRealTimers();
-});
-
-it('should throw an error in case timeout reached', () => {
-  const promise = withTimeout(() => new Promise((res) => {
-    setTimeout(res, 500);
-  }), 100);
-
-  Promise.resolve().then(() => vi.advanceTimersByTime(500));
-  expect(promise).rejects.toStrictEqual(new TimeoutError(100));
-}, 1000);
-
-it('should return resolved value by wrapped function', () => {
-  const promise = withTimeout(() => new Promise((res) => {
-    res('I am fine');
-  }), 100);
-
-  expect(promise).resolves.toBe('I am fine');
-}, 1000);

package/src/timeout/index.ts

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

package/src/timeout/isTimeoutError.ts

@@ -1,9 +0,0 @@
-import { TimeoutError } from './TimeoutError.js';
-
-/**
- * Returns true in case, passed value is TimeoutError.
- * @param value - checked value.
- */
-export function isTimeoutError(value: unknown): value is TimeoutError {
-  return value instanceof TimeoutError;
-}

package/src/timeout/sleep.ts

@@ -1,10 +0,0 @@
-/**
- * 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,24 +0,0 @@
-import { TimeoutError } from './TimeoutError.js';
-
-/**
- * Creates promise which rejects after timeout milliseconds.
- * @param timeout - timeout in milliseconds.
- */
-function createTimeoutPromise(timeout: number): Promise<never> {
-  return new Promise((_, rej) => {
-    setTimeout(rej, timeout, new TimeoutError(timeout));
-  });
-}
-
-/**
- * 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<T>(func: () => Promise<T>, timeout: number): Promise<T> {
-  return Promise.race([
-    func(),
-    createTimeoutPromise(timeout),
-  ]);
-}

package/src/types/index.ts

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

package/src/types/methods.ts

@@ -1,18 +0,0 @@
-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/src/types/platform.ts

@@ -1,14 +0,0 @@
-/**
- * Telegram application platform name.
- */
-export type Platform =
-  | 'android'
-  | 'android_x'
-  | 'ios'
-  | 'macos'
-  | 'tdesktop'
-  | 'unigram'
-  | 'unknown'
-  | 'web'
-  | 'weba'
-  | string;

package/src/types/request-id.ts

@@ -1,10 +0,0 @@
-/**
- * Request identifier which should be generated locally. Native Telegram application
- * uses it to generate a response to called method.
- */
-export type RequestId = string;
-
-/**
- * Function which generates unique request identifiers.
- */
-export type CreateRequestIdFunc = () => RequestId;

package/src/types/utils.ts

@@ -1,50 +0,0 @@
-/**
- * Returns true in case, T is never.
- */
-export type IsNever<T> = [T] extends [never] ? true : false;
-
-/**
- * Represents classic "if" condition.
- */
-export type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
-
-/**
- * Represents classic "not" bitwise operation.
- */
-export type Not<Cond extends boolean> = If<Cond, false, true>;
-
-/**
- * Represents classic "and" bitwise operation.
- */
-export type And<A extends boolean, B extends boolean> = A extends true
-  ? B extends true
-    ? true
-    : false
-  : false;
-
-/**
- * Represents classic "or" bitwise operation.
- */
-export type Or<A extends boolean, B extends boolean> = A extends true
-  ? true
-  : (B extends true ? true : false);
-
-/**
- * True if value includes undefined.
- */
-export type HasUndefined<T> = undefined extends T ? true : false;
-
-/**
- * Returns true if specified property in type is marked as optional.
- */
-export type IsOptional<Type, Key extends keyof Type> = {} extends Pick<Type, Key> ? true : false;
-
-/**
- * Returns union object keys.
- */
-export type UnionKeys<T> = T extends T ? keyof T : never;
-
-/**
- * Returns object string keys.
- */
-export type StringKeys<T extends object> = Extract<keyof T, string>;

package/src/utils/Utils.ts

@@ -1,107 +0,0 @@
-import {
-  type PostEvent,
-  postEvent as defaultPostEvent,
-  request,
-} from '~/bridge/index.js';
-import {
-  createSupportsFunc,
-  createSupportsParamFunc,
-  supports,
-  type SupportsFunc,
-} from '~/supports/index.js';
-import type { CreateRequestIdFunc } from '~/types/index.js';
-import type { Version } from '~/version/index.js';
-
-/**
- * Provides common Mini Apps functionality not covered by other system components.
- */
-export class Utils {
-  constructor(
-    private readonly version: Version,
-    private readonly createRequestId: CreateRequestIdFunc,
-    private readonly postEvent: PostEvent = defaultPostEvent,
-  ) {
-    this.supports = createSupportsFunc(version, {
-      readTextFromClipboard: 'web_app_read_text_from_clipboard',
-    });
-
-    this.supportsParam = createSupportsParamFunc(version, {
-      'openLink.tryInstantView': ['web_app_open_link', 'try_instant_view'],
-    });
-  }
-
-  /**
-   * Opens a link in an external browser. The Mini App will not be closed.
-   *
-   * Note that this method can be called only in response to the user
-   * interaction with the Mini App interface (e.g. click inside the Mini App
-   * or on the main button).
-   * @param url - URL to be opened.
-   * @param tryInstantView
-   */
-  openLink(url: string, tryInstantView?: boolean): void {
-    const formattedUrl = new URL(url, window.location.href).toString();
-
-    // If method is not supported, we are doing it in legacy way.
-    if (!supports('web_app_open_link', this.version)) {
-      window.open(formattedUrl, '_blank');
-      return;
-    }
-
-    // Otherwise, do it normally.
-    this.postEvent('web_app_open_link', {
-      url: formattedUrl,
-      ...(typeof tryInstantView === 'boolean' ? { try_instant_view: tryInstantView } : {}),
-    });
-  }
-
-  /**
-   * Opens a Telegram link inside Telegram app. The Mini App will be closed. It expects passing
-   * link in full format, with hostname "t.me".
-   * @param url - URL to be opened.
-   * @throws {Error} URL has not allowed hostname.
-   */
-  openTelegramLink(url: string): void {
-    const {
-      hostname,
-      pathname,
-      search,
-    } = new URL(url, window.location.href);
-
-    if (hostname !== 't.me') {
-      throw new Error(`URL has not allowed hostname: ${hostname}. Only "t.me" is allowed`);
-    }
-
-    if (!supports('web_app_open_tg_link', this.version)) {
-      window.location.href = url;
-      return;
-    }
-
-    this.postEvent('web_app_open_tg_link', { path_full: pathname + search });
-  }
-
-  /**
-   * Reads text from clipboard and returns string or null. null is returned
-   * in cases:
-   * - Value in clipboard is not text
-   * - Access to clipboard is not allowed
-   */
-  readTextFromClipboard(): Promise<string | null> {
-    return request(
-      'web_app_read_text_from_clipboard',
-      { req_id: this.createRequestId() },
-      'clipboard_text_received',
-      { postEvent: this.postEvent },
-    ).then(({ data = null }) => data);
-  }
-
-  /**
-   * Checks if specified method is supported by current component.
-   */
-  supports: SupportsFunc<'readTextFromClipboard'>;
-
-  /**
-   * Checks if specified method parameter is supported by current component.
-   */
-  supportsParam: SupportsFunc<'openLink.tryInstantView'>;
-}

package/src/utils/index.ts

@@ -1 +0,0 @@
-export * from './Utils.js';

package/src/version/__tests__/compareVersions.ts

@@ -1,19 +0,0 @@
-import { expect, it } from 'vitest';
-
-import { compareVersions } from '../compareVersions';
-
-it('should return 1 in case "a" is greater than "b"', () => {
-  expect(compareVersions('6.1', '6.0')).toBe(1);
-  expect(compareVersions('6.1', '6')).toBe(1);
-});
-
-it('should return 0 in case "a" is equal to "b"', () => {
-  expect(compareVersions('6', '6')).toBe(0);
-  expect(compareVersions('6', '6.0')).toBe(0);
-  expect(compareVersions('6.0', '6')).toBe(0);
-});
-
-it('should return -1 in case "a" is lower than "b"', () => {
-  expect(compareVersions('5', '6.0')).toBe(-1);
-  expect(compareVersions('6.0', '6.1')).toBe(-1);
-});

package/src/version/compareVersions.ts

@@ -1,28 +0,0 @@
-/**
- * Returns 1 in case, version "a" is greater than "b".
- * Returns 0 in case, version "a" equal to "b".
- * Returns -1 in case, version "a" is lower than "b".
- * @param a - first version.
- * @param b - second version.
- */
-export function compareVersions(a: string, b: string): number {
-  // Split both of the version by dot.
-  const aParts = a.split('.');
-  const bParts = b.split('.');
-
-  // Compute maximum length.
-  const len = Math.max(aParts.length, bParts.length);
-
-  // Iterate over each part of version and compare them. In case, part is
-  // missing, assume its value is equal to 0.
-  for (let i = 0; i < len; i += 1) {
-    const aVal = parseInt(aParts[i] || '0', 10);
-    const bVal = parseInt(bParts[i] || '0', 10);
-
-    if (aVal === bVal) {
-      continue;
-    }
-    return aVal > bVal ? 1 : -1;
-  }
-  return 0;
-}

package/src/version/index.ts

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

package/src/version/types.ts

@@ -1,4 +0,0 @@
-/**
- * Telegram Mini Apps version in format like "\d+.\d+".
- */
-export type Version = string;

package/src/viewport/Viewport.ts

@@ -1,171 +0,0 @@
-import {
-  on,
-  type PostEvent,
-  postEvent as defaultPostEvent,
-  type RequestOptions,
-} from '~/bridge/index.js';
-import { EventEmitter } from '~/event-emitter/index.js';
-import { State } from '~/state/index.js';
-import { requestViewport } from '~/viewport/requestViewport.js';
-
-import type {
-  ViewportEvents,
-  ViewportProps,
-  ViewportState,
-} from './types.js';
-import { truncate } from './utils.js';
-
-/**
- * Contains information about current WebApp device viewport, its dimensions
- * and state.
- */
-export class Viewport {
-  private readonly ee = new EventEmitter<ViewportEvents>();
-
-  private readonly state: State<ViewportState>;
-
-  private readonly postEvent: PostEvent;
-
-  constructor(props: ViewportProps) {
-    const {
-      height,
-      isExpanded,
-      width,
-      stableHeight,
-      postEvent = defaultPostEvent,
-    } = props;
-    this.postEvent = postEvent;
-    this.state = new State({
-      height: truncate(height),
-      isExpanded,
-      stableHeight: truncate(stableHeight),
-      width: truncate(width),
-    }, this.ee);
-  }
-
-  /**
-   * Request viewport information from the Telegram application and updates current Viewport
-   * instance.
-   * @param options - options to request fresh data.
-   */
-  sync(options?: RequestOptions): Promise<void> {
-    return requestViewport(options).then(({ height, isExpanded, width, isStateStable }) => {
-      this.state.set({
-        height,
-        width,
-        isExpanded,
-        stableHeight: isStateStable ? height : this.state.get('stableHeight'),
-      });
-    });
-  }
-
-  /**
-   * The current height of the visible area of the Mini App.
-   *
-   * The application can display just the top part of the Mini App, with its
-   * lower part remaining outside the screen area. From this position, the
-   * user can "pull" the Mini App to its maximum height, while the bot can do
-   * the same by calling `expand` method. As the position of the Mini App
-   * changes, the current height value of the visible area will be updated
-   * in real time.
-   *
-   * Please note that the refresh rate of this value is not sufficient
-   * to smoothly follow the lower border of the window. It should not be
-   * used to pin interface elements to the bottom of the visible area. It's
-   * more appropriate to use the value of the `stableHeight`
-   * field for this purpose.
-   */
-  get height(): number {
-    return this.state.get('height');
-  }
-
-  /**
-   * The height of the visible area of the Mini App in its last stable state.
-   *
-   * The application can display just the top part of the Mini App, with its
-   * lower part remaining outside the screen area. From this position,
-   * the user can "pull" the Mini App to its maximum height, while the bot can
-   * do the same by calling `expand` method.
-   *
-   * Unlike the value of `height`, the value of `stableHeight`
-   * does not change as the position of the Mini App changes with user
-   * gestures or during animations. The value of `stableHeight`
-   * will be updated after all gestures and animations are completed and
-   * the Mini App reaches its final size.
-   */
-  get stableHeight(): number {
-    return this.state.get('stableHeight');
-  }
-
-  /**
-   * Starts listening to viewport changes and applies them.
-   * @returns Function to stop listening.
-   */
-  listen() {
-    return on('viewport_changed', (event) => {
-      const {
-        height,
-        width,
-        is_expanded: isExpanded,
-        is_state_stable: isStateStable,
-      } = event;
-      const state: Partial<ViewportState> = {
-        height: truncate(height),
-        isExpanded,
-        width: truncate(width),
-      };
-
-      if (isStateStable) {
-        state.stableHeight = state.height;
-      }
-
-      this.state.set(state);
-    });
-  }
-
-  /**
-   * Returns true if the Mini App is expanded to the maximum available height.
-   * Otherwise, if the Mini App occupies part of the screen and can be expanded
-   * to the full height using `expand` method.
-   * @see expand
-   */
-  get isExpanded(): boolean {
-    return this.state.get('isExpanded');
-  }
-
-  /**
-   * Current viewport width.
-   */
-  get width(): number {
-    return this.state.get('width');
-  }
-
-  /**
-   * A method that expands the Mini App to the maximum available height. To
-   * find out if the Mini App is expanded to the maximum height, refer to the
-   * value of the `isExpanded`.
-   * @see isExpanded
-   */
-  expand(): void {
-    this.postEvent('web_app_expand');
-    this.state.set('isExpanded', true);
-  }
-
-  /**
-   * Returns true in case current viewport height is stable and is not going to
-   * change in the next moment.
-   */
-  get isStable(): boolean {
-    return this.stableHeight === this.height;
-  }
-
-  /**
-   * Adds new event listener.
-   */
-  on = this.ee.on.bind(this.ee);
-
-  /**
-   * Removes event listener.
-   */
-  off = this.ee.off.bind(this.ee);
-}

package/src/viewport/__tests__/isStableViewportPlatform.ts

@@ -1,15 +0,0 @@
-import { expect, it } from 'vitest';
-
-import { isStableViewportPlatform } from '../isStableViewportPlatform';
-
-['macos', 'tdesktop', 'unigram', 'web', 'weba'].forEach((platform) => {
-  it(`should return true if passed platform is "${platform}"`, () => {
-    expect(isStableViewportPlatform(platform)).toBe(true);
-  });
-});
-
-['unknown', 'android', 'android_x'].forEach((platform) => {
-  it(`should return false if passed platform is "${platform}"`, () => {
-    expect(isStableViewportPlatform(platform)).toBe(false);
-  });
-});

package/src/viewport/__tests__/utils.ts

@@ -1,12 +0,0 @@
-import { expect, it } from 'vitest';
-
-import { truncate } from '../utils';
-
-it('should return zero if value is less than 0', () => {
-  expect(truncate(-1)).toBe(0);
-});
-
-it('should return value if it is equals to or higher than 0', () => {
-  expect(truncate(0)).toBe(0);
-  expect(truncate(20)).toBe(20);
-});

package/src/viewport/index.ts

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

package/src/viewport/isStableViewportPlatform.ts

@@ -1,10 +0,0 @@
-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);
-}

package/src/viewport/requestViewport.ts

@@ -1,23 +0,0 @@
-import { request, type RequestOptions } from '~/bridge/index.js';
-
-export interface RequestViewportResult {
-  height: number;
-  isStateStable: boolean;
-  isExpanded: boolean;
-  width: number;
-}
-
-/**
- * Requests viewport actual information from the Telegram application.
- * @param options - request options.
- */
-export async function requestViewport(options?: RequestOptions): Promise<RequestViewportResult> {
-  const data = await request('web_app_request_viewport', 'viewport_changed', options);
-
-  return {
-    height: data.height,
-    width: data.width,
-    isExpanded: data.is_expanded,
-    isStateStable: data.is_state_stable,
-  };
-}

package/src/viewport/types.ts

@@ -1,23 +0,0 @@
-import type { PostEvent } from '~/bridge/index.js';
-import type { StateEvents } from '~/state/index.js';
-
-export interface ViewportProps {
-  height: number;
-  width: number;
-  stableHeight: number;
-  isExpanded: boolean;
-  postEvent?: PostEvent;
-}
-
-export interface ViewportState {
-  height: number;
-  isExpanded: boolean;
-  stableHeight: number;
-  width: number;
-}
-
-export type ViewportEvents = StateEvents<ViewportState>;
-
-export type ViewportEventName = keyof ViewportEvents;
-
-export type ViewportEventListener<E extends ViewportEventName> = ViewportEvents[E];