@tma.js/sdk 0.13.2 → 1.0.0

package/src/{components/QRScanner → qr-scanner}/QRScanner.ts

@@ -1,10 +1,15 @@
-import { EventEmitter } from '@tma.js/event-emitter';
-import { postEvent as defaultPostEvent, request, type PostEvent } from '@tma.js/bridge';
-
-import type { Version } from '@tma.js/utils';
-
-import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
-import { State } from '../../state/index.js';
+import {
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  request,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import {
+  createSupportsFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
 
 import type { QRScannerEvents, QRScannerState } from './types.js';
 
@@ -16,7 +21,10 @@ export class QRScanner {
 
   private readonly state: State<QRScannerState>;
 
-  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+  constructor(
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
     this.state = new State({ isOpened: false }, this.ee);
     this.supports = createSupportsFunc(version, {
       close: 'web_app_close_scan_qr_popup',
@@ -73,12 +81,12 @@ export class QRScanner {
   /**
    * Adds new event listener.
    */
-  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+  on = this.ee.on.bind(this.ee);
 
   /**
    * Removes event listener.
    */
-  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+  off = this.ee.off.bind(this.ee);
 
   /**
    * Checks if specified method is supported by current component.

package/src/qr-scanner/index.ts

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

package/src/{components/QRScanner → qr-scanner}/types.ts

@@ -1,4 +1,4 @@
-import type { StateEvents } from '../../state/index.js';
+import type { StateEvents } from '~/state/index.js';
 
 export interface QRScannerState {
   isOpened: boolean;

package/src/state/State.ts

@@ -1,53 +1,67 @@
-import type { EventEmitter } from '@tma.js/event-emitter';
+import type { EventEmitter } from '~/event-emitter/index.js';
+import type { StringKeys } from '~/types/index.js';
 
-import type { StateEvents, StringKeys } from './types.js';
+import type { StateEvents } from './types.js';
 
 /**
  * Represents state which is observable via passed EventEmitter.
  */
 export class State<S extends object> {
-  constructor(private readonly state: S, private readonly ee?: EventEmitter<StateEvents<S>>) {
-  }
-
-  private emit(key: string, value?: unknown) {
-    if (this.ee) {
-      (this.ee as any).emit(key, value);
-    }
+  constructor(
+    private readonly state: S,
+    private readonly ee: Pick<EventEmitter<StateEvents<S>>, 'on' | 'off' | 'emit'>,
+  ) {
   }
 
   private internalSet<K extends StringKeys<S>>(key: K, value: S[K]): boolean {
-    if (this.state[key] === value) {
+    if (this.state[key] === value || value === undefined) {
       return false;
     }
 
     this.state[key] = value;
-    this.emit(`${key}Changed`, value);
+    (this.ee as any).emit(`change:${key}`, value);
 
     return true;
   }
 
+  /**
+   * Returns copy of current state.
+   */
+  clone(): S {
+    return { ...this.state };
+  }
+
+  /**
+   * Sets value by key.
+   * @param key - state key.
+   * @param value - value to set.
+   */
   set<K extends StringKeys<S>>(key: K, value: S[K]): void;
   set(state: Partial<S>): void;
-  set(keyOrState: any, value?: any): void {
+  set(keyOrState: StringKeys<S> | Partial<S>, value?: S[keyof S]): void {
     let didChange = false;
 
     if (typeof keyOrState === 'string') {
-      didChange = this.internalSet(keyOrState as any, value);
+      didChange = this.internalSet(keyOrState, value as any);
     } else {
       // eslint-disable-next-line
       for (const key in keyOrState) {
-        if (this.internalSet(key as any, keyOrState[key])) {
+        if (this.internalSet(key, keyOrState[key] as any)) {
           didChange = true;
         }
       }
     }
 
     if (didChange) {
-      this.emit('changed');
+      (this.ee as any).emit('change');
     }
   }
 
-  get<K extends StringKeys<S>>(key: K): Readonly<S[K]> {
+  /**
+   * Returns value by specified key.
+   * @param key - state key.
+   */
+  get<K extends StringKeys<S>>(key: K): S[K] {
     return this.state[key];
   }
 }

package/src/state/types.ts

@@ -1,12 +1,9 @@
-/**
- * Computes state property changed event.
- */
-export type PropChangedEvent<K extends string> = `${K}Changed`;
+import type { StringKeys } from '~/types/index.js';
 
 /**
- * Returns object string keys.
+ * Computes state property changed event.
  */
-export type StringKeys<T extends object> = Extract<keyof T, string>;
+export type PropChangedEvent<K extends string> = `change:${K}`;
 
 /**
  * Extracts state property type by its computed change event name.
@@ -20,7 +17,7 @@ export type PropertyType<State extends object, Event extends string> = {
  * Value is according listener.
  */
 export type PropChangedEventsMap<State extends object> = {
-  [Event in `${StringKeys<State>}Changed`]: (value: PropertyType<State, Event>) => void;
+  [Event in PropChangedEvent<StringKeys<State>>]: (value: PropertyType<State, Event>) => void;
 };
 
 /**
@@ -30,5 +27,5 @@ export type StateEvents<State extends object> = PropChangedEventsMap<State> & {
   /**
    * Being called whenever any property was updated.
    */
-  changed: () => void;
+  change: () => void;
 };

package/src/storage.ts

@@ -1,5 +1,7 @@
-import type { HeaderColorKey } from '@tma.js/bridge';
-import type { RGB } from '@tma.js/colors';
+import type { HeaderColorKey } from '~/bridge/index.js';
+import type { RGB } from '~/colors/index.js';
+
+// fixme: components-related. Should probably rename
 
 /**
  * Describes storage keys and according values.
@@ -14,8 +16,8 @@ interface StorageParams {
   'main-button': {
     backgroundColor: RGB;
     isEnabled: boolean;
+    isLoaderVisible: boolean;
     isVisible: boolean;
-    isProgressVisible: boolean;
     text: string;
     textColor: RGB;
   };
@@ -25,7 +27,7 @@ interface StorageParams {
     stableHeight: number;
     width: number;
   };
-  'web-app': {
+  'mini-app': {
     backgroundColor: RGB;
     headerColor: HeaderColorKey | RGB;
   };

package/src/supports/createSupportsFunc.ts

@@ -0,0 +1,18 @@
+import type { MiniAppsMethodName } from '~/bridge/index.js';
+import type { Version } from '~/version/index.js';
+
+import { supports } from './supports.js';
+import type { SupportsFunc } from './types.js';
+
+/**
+ * Returns function, which accepts predefined method name and checks if it is supported
+ * via passed schema and version.
+ * @param schema - object which contains methods names and TWA method as a dependency.
+ * @param version - platform version.
+ */
+export function createSupportsFunc<M extends string>(
+  version: Version,
+  schema: Record<M, MiniAppsMethodName>,
+): SupportsFunc<M> {
+  return (method) => supports(schema[method], version);
+}

package/src/supports/createSupportsParamFunc.ts

@@ -0,0 +1,27 @@
+import type { MiniAppsMethodVersionedParams, MiniAppsMethodWithVersionedParams } from '~/bridge/index.js';
+import type { Version } from '~/version/index.js';
+
+import { supports } from './supports.js';
+import type { SupportsFunc } from './types.js';
+
+type HasCheckSupportMethodTuple = {
+  [M in MiniAppsMethodWithVersionedParams]: [M, MiniAppsMethodVersionedParams<M>]
+}[MiniAppsMethodWithVersionedParams];
+
+/**
+ * Returns function, which accepts predefined method name and checks if it is supported
+ * via passed schema and version.
+ * @param schema - object which contains methods names and TWA methods with specified parameter
+ * as a dependency.
+ * @param version - platform version.
+ */
+export function createSupportsParamFunc<P extends string>(
+  version: Version,
+  schema: Record<P, HasCheckSupportMethodTuple>,
+): SupportsFunc<P> {
+  return (method) => {
+    const [tmaMethod, param] = schema[method];
+
+    return supports(tmaMethod, param, version);
+  };
+}

package/src/supports/index.ts

@@ -0,0 +1,4 @@
+export * from './createSupportsFunc.js';
+export * from './createSupportsParamFunc.js';
+export * from './supports.js';
+export * from './types.js';

package/src/supports/supports.ts

@@ -0,0 +1,84 @@
+import {
+  compareVersions,
+  type Version,
+} from '~/version/index.js';
+import type {
+  MiniAppsMethodName,
+  MiniAppsMethodVersionedParams,
+  MiniAppsMethodWithVersionedParams,
+} from '~/bridge/methods/index.js';
+
+/**
+ * Returns true if "a" version is less than or equal to "b" version.
+ * @param a
+ * @param b
+ */
+function versionLessOrEqual(a: Version, b: Version): boolean {
+  return compareVersions(a, b) <= 0;
+}
+
+/**
+ * Returns true in case, passed parameter in specified method is supported.
+ * @param method - method name
+ * @param param - method parameter
+ * @param inVersion - platform version.
+ */
+export function supports<M extends MiniAppsMethodWithVersionedParams>(
+  method: M,
+  param: MiniAppsMethodVersionedParams<M>,
+  inVersion: Version,
+): boolean;
+
+/**
+ * Returns true in case, specified method is supported in passed version.
+ * @param method - method name.
+ * @param inVersion - platform version.
+ */
+export function supports(method: MiniAppsMethodName, inVersion: Version): boolean;
+
+export function supports(
+  method: MiniAppsMethodName,
+  paramOrVersion: Version | string,
+  inVersion?: string,
+): boolean {
+  // Method name, parameter, target version.
+  if (typeof inVersion === 'string') {
+    if (method === 'web_app_open_link') {
+      if (paramOrVersion === 'try_instant_view') {
+        return versionLessOrEqual('6.4', inVersion);
+      }
+    }
+
+    if (method === 'web_app_set_header_color') {
+      if (paramOrVersion === 'color') {
+        return versionLessOrEqual('6.9', inVersion);
+      }
+    }
+  }
+
+  switch (method) {
+    case 'web_app_open_tg_link':
+    case 'web_app_open_invoice':
+    case 'web_app_setup_back_button':
+    case 'web_app_set_background_color':
+    case 'web_app_set_header_color':
+    case 'web_app_trigger_haptic_feedback':
+      return versionLessOrEqual('6.1', paramOrVersion);
+    case 'web_app_open_popup':
+      return versionLessOrEqual('6.2', paramOrVersion);
+    case 'web_app_close_scan_qr_popup':
+    case 'web_app_open_scan_qr_popup':
+    case 'web_app_read_text_from_clipboard':
+      return versionLessOrEqual('6.4', paramOrVersion);
+    case 'web_app_switch_inline_query':
+      return versionLessOrEqual('6.7', paramOrVersion);
+    case 'web_app_invoke_custom_method':
+    case 'web_app_request_write_access':
+    case 'web_app_request_phone':
+      return versionLessOrEqual('6.9', paramOrVersion);
+    case 'web_app_setup_settings_button':
+      return versionLessOrEqual('6.10', paramOrVersion);
+    default:
+      return true;
+  }
+}

package/src/supports/types.ts

@@ -0,0 +1 @@
+export type SupportsFunc<M extends string> = (method: M) => boolean;

package/src/theme-params/ThemeParams.ts

@@ -0,0 +1,131 @@
+import { on } from '~/bridge/index.js';
+import { isColorDark, type RGB } from '~/colors/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+
+import { parseThemeParams } from './parseThemeParams.js';
+import type {
+  ThemeParamsEvents,
+  ThemeParamsParsed,
+  ThemeParamsState,
+} from './types.js';
+
+export class ThemeParams {
+  private readonly ee = new EventEmitter<ThemeParamsEvents>();
+
+  private readonly state: State<ThemeParamsState>;
+
+  constructor(params: ThemeParamsParsed) {
+    this.state = new State(params, this.ee);
+  }
+
+  /**
+   * @since v6.10
+   */
+  get accentTextColor(): RGB | undefined {
+    return this.get('accentTextColor');
+  }
+
+  get backgroundColor(): RGB | undefined {
+    return this.get('backgroundColor');
+  }
+
+  get buttonColor(): RGB | undefined {
+    return this.get('buttonColor');
+  }
+
+  get buttonTextColor(): RGB | undefined {
+    return this.get('buttonTextColor');
+  }
+
+  get destructiveTextColor(): RGB | undefined {
+    return this.get('destructiveTextColor');
+  }
+
+  /**
+   * Retrieves palette color value by its name.
+   * @param key - palette key name.
+   */
+  get(key: Extract<keyof ThemeParamsParsed, string>): RGB | undefined {
+    return this.state.get(key);
+  }
+
+  /**
+   * Returns the copy of the internal state of the current component instance.
+   */
+  getState(): ThemeParamsParsed {
+    return this.state.clone();
+  }
+
+  /**
+   * @since v6.10
+   */
+  get headerBackgroundColor(): RGB | undefined {
+    return this.get('headerBackgroundColor');
+  }
+
+  get hintColor(): RGB | undefined {
+    return this.get('hintColor');
+  }
+
+  /**
+   * Returns true in case, current color scheme is recognized as dark. This
+   * value is calculated according to theme background color.
+   */
+  get isDark(): boolean {
+    return !this.backgroundColor || isColorDark(this.backgroundColor);
+  }
+
+  get linkColor(): RGB | undefined {
+    return this.get('linkColor');
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+
+  get secondaryBackgroundColor(): RGB | undefined {
+    return this.get('secondaryBackgroundColor');
+  }
+
+  /**
+   * @since v6.10
+   */
+  get sectionBackgroundColor(): RGB | undefined {
+    return this.get('sectionBackgroundColor');
+  }
+
+  /**
+   * @since v6.10
+   */
+  get sectionHeaderTextColor(): RGB | undefined {
+    return this.get('sectionHeaderTextColor');
+  }
+
+  /**
+   * Starts listening to theme changes and applies them.
+   * @returns Function to stop listening.
+   */
+  listen() {
+    return on('theme_changed', (event) => {
+      this.state.set(parseThemeParams(event.theme_params));
+    });
+  }
+
+  /**
+   * @since v6.10
+   */
+  get subtitleTextColor(): RGB | undefined {
+    return this.get('subtitleTextColor');
+  }
+
+  get textColor(): RGB | undefined {
+    return this.get('textColor');
+  }
+}

package/src/theme-params/index.ts

@@ -0,0 +1,6 @@
+export * from './parseThemeParams.js';
+export * from './requestThemeParams.js';
+export * from './serializeThemeParams.js';
+export * from './ThemeParams.js';
+export * from './themeParamsParser.js';
+export * from './types.js';

package/src/theme-params/keys.ts

@@ -0,0 +1,24 @@
+/**
+ * Converts palette key from Telegram application to representation used by the package.
+ * @param key - palette key.
+ */
+export function keyToLocal(key: string): string {
+  return key
+    // Replace all "background" strings to "bg".
+    .replace(/(^|_)bg/, (_, prefix) => `${prefix}background`)
+    // Convert camel case to snake case.
+    .replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+
+/**
+ * Converts palette key from local representation to representation sent from the Telegram
+ * application.
+ * @param key - palette key.
+ */
+export function keyToExternal(key: string): string {
+  return key
+    // Convert camel case to snake case.
+    .replace(/[A-Z]/g, (match) => `_${match.toLowerCase()}`)
+    // Replace all "background" strings to "bg".
+    .replace(/(^|_)background/, (_, prefix) => `${prefix}bg`);
+}

package/src/theme-params/parseThemeParams.ts

@@ -0,0 +1,10 @@
+import { themeParamsParser } from './themeParamsParser.js';
+import type { ThemeParamsParsed } from './types.js';
+
+/**
+ * Parses incoming value as theme parameters.
+ * @param value - value to parse.
+ */
+export function parseThemeParams(value: unknown): ThemeParamsParsed {
+  return themeParamsParser().parse(value);
+}

package/src/theme-params/requestThemeParams.ts

@@ -0,0 +1,13 @@
+import { request, type RequestOptions } from '~/bridge/index.js';
+
+import { parseThemeParams } from './parseThemeParams.js';
+import type { ThemeParamsParsed } from './types.js';
+
+/**
+ * Requests current theme parameters from the Telegram application.
+ * @param options - request options.
+ */
+export function requestThemeParams(options: RequestOptions = {}): Promise<ThemeParamsParsed> {
+  return request('web_app_request_theme', 'theme_changed', options)
+    .then(parseThemeParams);
+}

package/src/theme-params/serializeThemeParams.ts

@@ -0,0 +1,20 @@
+import type { RGB } from '~/colors/index.js';
+
+import { keyToExternal } from './keys.js';
+import type { ThemeParamsParsed } from './types.js';
+
+/**
+ * Serializes theme parameters to representation sent from the Telegram application.
+ */
+export function serializeThemeParams(themeParams: ThemeParamsParsed): string {
+  return JSON.stringify(
+    Object
+      .entries(themeParams)
+      .reduce<Record<string, RGB>>((acc, [key, value]) => {
+      if (value) {
+        acc[keyToExternal(key)] = value;
+      }
+      return acc;
+    }, {}),
+  );
+}

package/src/theme-params/themeParamsParser.ts

@@ -0,0 +1,20 @@
+import {
+  createValueParserGenerator,
+  rgb,
+  toRecord,
+} from '~/parsing/index.js';
+
+import { keyToLocal } from './keys.js';
+import type { ThemeParamsParsed } from './types.js';
+
+const rgbOptional = rgb().optional();
+
+export const themeParamsParser = createValueParserGenerator<ThemeParamsParsed>(
+  (value) => Object
+    .entries(toRecord(value))
+    .reduce<ThemeParamsParsed>((acc, [k, v]) => {
+    acc[keyToLocal(k)] = rgbOptional.parse(v);
+    return acc;
+  }, {}),
+  'ThemeParams',
+);

package/src/theme-params/types.ts

@@ -0,0 +1,33 @@
+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

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

package/src/timeout/index.ts

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

package/src/timeout/isTimeoutError.ts

@@ -0,0 +1,9 @@
+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/withTimeout.ts

@@ -0,0 +1,36 @@
+import { TimeoutError } from './TimeoutError.js';
+
+type AnyAsyncFunction = (...args: any[]) => Promise<any>;
+
+/**
+ * Creates promise which rejects after timeout milliseconds.
+ * @param timeout - timeout in milliseconds.
+ */
+function createTimeoutPromise(timeout: number): Promise<void> {
+  return new Promise((_, rej) => {
+    setTimeout(rej, timeout, new TimeoutError(timeout));
+  });
+}
+
+/**
+ * Rejects specified promise in case, it is processed more than timeout seconds.
+ * @param promise - wrapped promise.
+ * @param timeout - timeout in milliseconds.
+ */
+export function withTimeout<P extends Promise<any>>(promise: P, timeout: number): P;
+/**
+ * Wraps async function in function using timeout.
+ * @param func - wrapped function.
+ * @param timeout - async function timeout.
+ */
+export function withTimeout<F extends AnyAsyncFunction>(func: F, timeout: number): F;
+export function withTimeout(funcOrPromise: Promise<any> | AnyAsyncFunction, timeout: number) {
+  if (typeof funcOrPromise === 'function') {
+    return (...args: any[]) => Promise.race([
+      funcOrPromise(...args),
+      createTimeoutPromise(timeout),
+    ]);
+  }
+
+  return Promise.race([funcOrPromise, createTimeoutPromise(timeout)]);
+}