@tma.js/sdk 0.13.3 → 1.0.0

package/dist/dts/state/State.d.ts

@@ -1,16 +1,28 @@
-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 } from './types.js';
 /**
  * Represents state which is observable via passed EventEmitter.
  */
 export declare class State<S extends object> {
     private readonly state;
-    private readonly ee?;
-    constructor(state: S, ee?: EventEmitter<StateEvents<S>> | undefined);
-    private emit;
+    private readonly ee;
+    constructor(state: S, ee: Pick<EventEmitter<StateEvents<S>>, 'on' | 'off' | 'emit'>);
     private internalSet;
-    set<K extends keyof S>(key: K, value: S[K]): void;
+    /**
+     * Returns copy of current state.
+     */
+    clone(): S;
+    /**
+     * 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;
-    get<K extends keyof S>(key: K): Readonly<S[K]>;
-    getState(): S;
+    /**
+     * Returns value by specified key.
+     * @param key - state key.
+     */
+    get<K extends StringKeys<S>>(key: K): S[K];
 }

package/dist/dts/state/types.d.ts

@@ -1,11 +1,8 @@
+import type { StringKeys } from '../types/index.js';
 /**
  * Computes state property changed event.
  */
-export type PropChangedEvent<K extends string> = `${K}Changed`;
-/**
- * Returns object string keys.
- */
-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.
  */
@@ -17,7 +14,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;
 };
 /**
  * Creates map with all events emitted by state.
@@ -26,5 +23,5 @@ export type StateEvents<State extends object> = PropChangedEventsMap<State> & {
     /**
      * Being called whenever any property was updated.
      */
-    changed: () => void;
+    change: () => void;
 };

package/dist/dts/storage.d.ts

@@ -1,5 +1,5 @@
-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';
 /**
  * Describes storage keys and according values.
  */
@@ -13,8 +13,8 @@ interface StorageParams {
     'main-button': {
         backgroundColor: RGB;
         isEnabled: boolean;
+        isLoaderVisible: boolean;
         isVisible: boolean;
-        isProgressVisible: boolean;
         text: string;
         textColor: RGB;
     };
@@ -24,7 +24,7 @@ interface StorageParams {
         stableHeight: number;
         width: number;
     };
-    'web-app': {
+    'mini-app': {
         backgroundColor: RGB;
         headerColor: HeaderColorKey | RGB;
     };

package/dist/dts/supports/createSupportsFunc.d.ts

@@ -0,0 +1,10 @@
+import type { MiniAppsMethodName } from '../bridge/index.js';
+import type { Version } from '../version/index.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 declare function createSupportsFunc<M extends string>(version: Version, schema: Record<M, MiniAppsMethodName>): SupportsFunc<M>;

package/dist/dts/supports/createSupportsParamFunc.d.ts

@@ -0,0 +1,15 @@
+import type { MiniAppsMethodVersionedParams, MiniAppsMethodWithVersionedParams } from '../bridge/index.js';
+import type { Version } from '../version/index.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 declare function createSupportsParamFunc<P extends string>(version: Version, schema: Record<P, HasCheckSupportMethodTuple>): SupportsFunc<P>;
+export {};

package/dist/dts/supports/index.d.ts

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

package/dist/dts/supports/supports.d.ts

@@ -0,0 +1,15 @@
+import { type Version } from '../version/index.js';
+import type { MiniAppsMethodName, MiniAppsMethodVersionedParams, MiniAppsMethodWithVersionedParams } from '../bridge/methods/index.js';
+/**
+ * Returns true in case, passed parameter in specified method is supported.
+ * @param method - method name
+ * @param param - method parameter
+ * @param inVersion - platform version.
+ */
+export declare 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 declare function supports(method: MiniAppsMethodName, inVersion: Version): boolean;

package/dist/dts/supports/types.d.ts

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

package/dist/dts/theme-params/ThemeParams.d.ts

@@ -0,0 +1,62 @@
+import { type RGB } from '../colors/index.js';
+import type { ThemeParamsEvents, ThemeParamsParsed } from './types.js';
+export declare class ThemeParams {
+    private readonly ee;
+    private readonly state;
+    constructor(params: ThemeParamsParsed);
+    /**
+     * @since v6.10
+     */
+    get accentTextColor(): RGB | undefined;
+    get backgroundColor(): RGB | undefined;
+    get buttonColor(): RGB | undefined;
+    get buttonTextColor(): RGB | undefined;
+    get destructiveTextColor(): RGB | undefined;
+    /**
+     * Retrieves palette color value by its name.
+     * @param key - palette key name.
+     */
+    get(key: Extract<keyof ThemeParamsParsed, string>): RGB | undefined;
+    /**
+     * Returns the copy of the internal state of the current component instance.
+     */
+    getState(): ThemeParamsParsed;
+    /**
+     * @since v6.10
+     */
+    get headerBackgroundColor(): RGB | undefined;
+    get hintColor(): RGB | undefined;
+    /**
+     * Returns true in case, current color scheme is recognized as dark. This
+     * value is calculated according to theme background color.
+     */
+    get isDark(): boolean;
+    get linkColor(): RGB | undefined;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends `change:${string}` | "change">(event: E, listener: import('../event-emitter/index.js').EventListener<ThemeParamsEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends `change:${string}` | "change">(event: E, listener: import('../event-emitter/index.js').EventListener<ThemeParamsEvents[E]>) => void;
+    get secondaryBackgroundColor(): RGB | undefined;
+    /**
+     * @since v6.10
+     */
+    get sectionBackgroundColor(): RGB | undefined;
+    /**
+     * @since v6.10
+     */
+    get sectionHeaderTextColor(): RGB | undefined;
+    /**
+     * Starts listening to theme changes and applies them.
+     * @returns Function to stop listening.
+     */
+    listen(): () => void;
+    /**
+     * @since v6.10
+     */
+    get subtitleTextColor(): RGB | undefined;
+    get textColor(): RGB | undefined;
+}

package/dist/dts/theme-params/index.d.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/dist/dts/theme-params/keys.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts palette key from Telegram application to representation used by the package.
+ * @param key - palette key.
+ */
+export declare function keyToLocal(key: string): string;
+/**
+ * Converts palette key from local representation to representation sent from the Telegram
+ * application.
+ * @param key - palette key.
+ */
+export declare function keyToExternal(key: string): string;

package/dist/dts/theme-params/parseThemeParams.d.ts

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

package/dist/dts/theme-params/requestThemeParams.d.ts

@@ -0,0 +1,7 @@
+import { type RequestOptions } from '../bridge/index.js';
+import type { ThemeParamsParsed } from './types.js';
+/**
+ * Requests current theme parameters from the Telegram application.
+ * @param options - request options.
+ */
+export declare function requestThemeParams(options?: RequestOptions): Promise<ThemeParamsParsed>;

package/dist/dts/theme-params/serializeThemeParams.d.ts

@@ -0,0 +1,5 @@
+import type { ThemeParamsParsed } from './types.js';
+/**
+ * Serializes theme parameters to representation sent from the Telegram application.
+ */
+export declare function serializeThemeParams(themeParams: ThemeParamsParsed): string;

package/dist/dts/theme-params/themeParamsParser.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeParamsParsed } from './types.js';
+export declare const themeParamsParser: import('../parsing/index.js').ValueParserGenerator<ThemeParamsParsed>;

package/dist/dts/theme-params/types.d.ts

@@ -0,0 +1,14 @@
+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/dist/dts/timeout/TimeoutError.d.ts

@@ -0,0 +1,3 @@
+export declare class TimeoutError extends Error {
+    constructor(timeout: number);
+}

package/dist/dts/timeout/index.d.ts

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

package/dist/dts/timeout/isTimeoutError.d.ts

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

package/dist/dts/timeout/withTimeout.d.ts

@@ -0,0 +1,14 @@
+type AnyAsyncFunction = (...args: any[]) => Promise<any>;
+/**
+ * Rejects specified promise in case, it is processed more than timeout seconds.
+ * @param promise - wrapped promise.
+ * @param timeout - timeout in milliseconds.
+ */
+export declare 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 declare function withTimeout<F extends AnyAsyncFunction>(func: F, timeout: number): F;
+export {};

package/dist/dts/types/index.d.ts

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

package/dist/dts/types/platform.d.ts

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

package/dist/dts/types/request-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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/dist/dts/types/utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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/dist/dts/utils/Utils.d.ts

@@ -0,0 +1,45 @@
+import { type PostEvent } from '../bridge/index.js';
+import { 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 declare class Utils {
+    private readonly version;
+    private readonly createRequestId;
+    private readonly postEvent;
+    constructor(version: Version, createRequestId: CreateRequestIdFunc, postEvent?: PostEvent);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * 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/dist/dts/utils/index.d.ts

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

package/dist/dts/version/compareVersions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function compareVersions(a: string, b: string): number;

package/dist/dts/version/index.d.ts

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

package/dist/dts/version/types.d.ts

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

package/dist/dts/{components/Viewport → viewport}/Viewport.d.ts

@@ -1,39 +1,20 @@
-import { type RequestOptions, type PostEvent } from '@tma.js/bridge';
-export interface RequestViewportResult {
-    height: number;
-    isStateStable: boolean;
-    isExpanded: boolean;
-    width: number;
-}
+import { type RequestOptions } from '../bridge/index.js';
+import type { ViewportEvents, ViewportProps } from './types.js';
 /**
  * Contains information about current WebApp device viewport, its dimensions
  * and state.
  */
 export declare class Viewport {
+    private readonly ee;
+    private readonly state;
     private readonly postEvent;
+    constructor(props: ViewportProps);
     /**
-     * Requests fresh information about current viewport.
-     * FIXME: Be careful using this function in desktop version of Telegram as
-     *  long as method web_app_request_viewport does not work on `macos` platform.
-     * @see Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/5
-     * @param options - method options.
-     */
-    static request(options?: RequestOptions): Promise<RequestViewportResult>;
-    /**
-     * Synchronizes specified instance of Viewport with the actual value in the native
-     * application.
-     * @param viewport - Viewport instance.
+     * Request viewport information from the Telegram application and updates current Viewport
+     * instance.
+     * @param options - options to request fresh data.
      */
-    static sync(viewport: Viewport): void;
-    /**
-     * Returns initialized instance of Viewport which is synchronized with
-     * its actual state in Mini Apps.
-     * @param options - method options.
-     */
-    static synced(options?: RequestOptions): Promise<Viewport>;
-    private readonly ee;
-    private readonly state;
-    constructor(height: number, width: number, stableHeight: number, isExpanded: boolean, postEvent?: PostEvent);
+    sync(options?: RequestOptions): Promise<void>;
     /**
      * The current height of the visible area of the Mini App.
      *
@@ -49,10 +30,6 @@ export declare class Viewport {
      * 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.
-     *
-     * @see init
-     * @see expand
-     * @see stableHeight
      */
     get height(): number;
     /**
@@ -68,12 +45,13 @@ export declare class Viewport {
      * 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.
-     *
-     * @see init
-     * @see expand
-     * @see height
      */
     get stableHeight(): number;
+    /**
+     * Starts listening to viewport changes and applies them.
+     * @returns Function to stop listening.
+     */
+    listen(): () => void;
     /**
      * 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
@@ -100,9 +78,9 @@ export declare class Viewport {
     /**
      * Adds new event listener.
      */
-    on: typeof this.ee.on;
+    on: <E extends "change" | "change:height" | "change:width" | "change:isExpanded" | "change:stableHeight">(event: E, listener: import('../event-emitter/index.js').EventListener<ViewportEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
     /**
      * Removes event listener.
      */
-    off: typeof this.ee.off;
+    off: <E extends "change" | "change:height" | "change:width" | "change:isExpanded" | "change:stableHeight">(event: E, listener: import('../event-emitter/index.js').EventListener<ViewportEvents[E]>) => void;
 }

package/dist/dts/viewport/index.d.ts

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

package/dist/dts/viewport/requestViewport.d.ts

@@ -0,0 +1,12 @@
+import { 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 declare function requestViewport(options?: RequestOptions): Promise<RequestViewportResult>;

package/dist/dts/{components/Viewport → viewport}/types.d.ts

@@ -1,4 +1,12 @@
-import type { StateEvents } from '../../state/index.js';
+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;

package/dist/dts/viewport/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Formats value to make it stay in bounds [0, +Inf).
+ * @param value - value to format.
+ */
+export declare function truncate(value: number): number;