@tma.js/sdk 1.5.3 → 2.0.1

package/dist/dts/components/ThemeParams/ThemeParams.d.ts

@@ -0,0 +1,53 @@
+import { WithTrackableState } from '../../classes/WithTrackableState.js';
+import { RGB } from '../../colors/types.js';
+import { RemoveEventListenerFn } from '../../events/types.js';
+import { ThemeParamsParsed, ThemeParamsState } from './types.js';
+
+/**
+ * @see Usage: https://docs.telegram-mini-apps.com/platform/theming
+ * @see API: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/components/theme-params
+ */
+export declare class ThemeParams extends WithTrackableState<ThemeParamsState> {
+    /**
+     * @since v6.10
+     */
+    get accentTextColor(): RGB | undefined;
+    get bgColor(): RGB | undefined;
+    get buttonColor(): RGB | undefined;
+    get buttonTextColor(): RGB | undefined;
+    get destructiveTextColor(): RGB | undefined;
+    /**
+     * Returns the copy of the internal state of the current component instance.
+     */
+    getState(): ThemeParamsParsed;
+    /**
+     * @since v6.10
+     */
+    get headerBgColor(): RGB | undefined;
+    get hintColor(): RGB | undefined;
+    /**
+     * @returns True in case, current color scheme is recognized as dark. This
+     * value is calculated according to theme bg color.
+     */
+    get isDark(): boolean;
+    get linkColor(): RGB | undefined;
+    get secondaryBgColor(): RGB | undefined;
+    /**
+     * @since v6.10
+     */
+    get sectionBgColor(): RGB | undefined;
+    /**
+     * @since v6.10
+     */
+    get sectionHeaderTextColor(): RGB | undefined;
+    /**
+     * Starts listening to the external theme changes and applies them.
+     * @returns Function to stop listening.
+     */
+    listen(): RemoveEventListenerFn;
+    /**
+     * @since v6.10
+     */
+    get subtitleTextColor(): RGB | undefined;
+    get textColor(): RGB | undefined;
+}

package/dist/dts/components/ThemeParams/initThemeParams.d.ts

@@ -0,0 +1,7 @@
+import { ThemeParams } from './ThemeParams.js';
+
+/**
+ * @returns A new initialized instance of the `ThemeParams` class.
+ * @see ThemeParams
+ */
+export declare const initThemeParams: import('../../index.js').InitComponentFn<"themeParams", ThemeParams, import('./types.js').ThemeParamsParsed>;

package/dist/dts/components/ThemeParams/keys.d.ts

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

package/dist/dts/components/{theme-params → ThemeParams/parsing}/parseThemeParams.d.ts

@@ -1,4 +1,5 @@
-import type { ThemeParamsParsed } from './types.js';
+import { ThemeParamsParsed } from '../types.js';
+
 /**
  * Parses incoming value as theme parameters.
  * @param value - value to parse.

package/dist/dts/components/{theme-params → ThemeParams/parsing}/serializeThemeParams.d.ts

@@ -1,4 +1,5 @@
-import type { ThemeParamsParsed } from './types.js';
+import { ThemeParamsParsed } from '../types.js';
+
 /**
  * Serializes theme parameters to representation sent from the Telegram application.
  */

package/dist/dts/components/ThemeParams/parsing/themeParams.d.ts

@@ -0,0 +1,4 @@
+import { ValueParserGenerator } from '../../../parsing/createValueParserGenerator.js';
+import { ThemeParamsParsed } from '../types.js';
+
+export declare const themeParams: ValueParserGenerator<ThemeParamsParsed>;

package/dist/dts/components/ThemeParams/requestThemeParams.d.ts

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

package/dist/dts/components/ThemeParams/types.d.ts

@@ -0,0 +1,29 @@
+import { StateEvents } from '../../classes/State/types.js';
+import { RGB } from '../../colors/types.js';
+
+export type ThemeParamsKey = 'accentTextColor' | 'bgColor' | 'buttonColor' | 'buttonTextColor' | 'destructiveTextColor' | 'headerBgColor' | 'hintColor' | 'linkColor' | 'secondaryBgColor' | 'sectionBgColor' | 'sectionHeaderTextColor' | 'subtitleTextColor' | 'textColor';
+/**
+ * Application [theme parameters](https://docs.telegram-mini-apps.com/platform/theming).
+ * Defines palette used by the Telegram application.
+ */
+export interface ThemeParamsParsed {
+    [key: ThemeParamsKey | string]: RGB | undefined;
+}
+/**
+ * ThemeParams internal state.
+ */
+export interface ThemeParamsState extends ThemeParamsParsed {
+}
+/**
+ * ThemeParams trackable events.
+ */
+export interface ThemeParamsEvents extends StateEvents<ThemeParamsState> {
+}
+/**
+ * ThemeParams event name.
+ */
+export type ThemeParamsEventName = keyof ThemeParamsEvents;
+/**
+ * ThemeParams event listener.
+ */
+export type ThemeParamsEventListener<E extends ThemeParamsEventName> = ThemeParamsEvents[E];

package/dist/dts/components/{utils → Utils}/Utils.d.ts

@@ -1,15 +1,17 @@
-import type { PostEvent } from '../../bridge/methods/postEvent.js';
-import type { SupportsFunc } from '../../supports/types.js';
-import type { CreateRequestIdFunc } from '../../types/request-id.js';
-import type { Version } from '../../version/types.js';
+import { WithSupports } from '../../classes/WithSupports.js';
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { CreateRequestIdFn } from '../../request-id/types.js';
+import { SupportsFn } from '../../supports/types.js';
+import { Version } from '../../version/types.js';
+
 /**
- * Provides common Mini Apps functionality not covered by other system components.
+ * @see API: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/components/utils
  */
-export declare class Utils {
+export declare class Utils extends WithSupports<'readTextFromClipboard'> {
     private readonly version;
     private readonly createRequestId;
     private readonly postEvent;
-    constructor(version: Version, createRequestId: CreateRequestIdFunc, postEvent?: PostEvent);
+    constructor(version: Version, createRequestId: CreateRequestIdFn, postEvent: PostEvent);
     /**
      * Opens a link in an external browser. The Mini App will not be closed.
      *
@@ -34,12 +36,8 @@ export declare class Utils {
      * - 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'>;
+    supportsParam: SupportsFn<'openLink.tryInstantView'>;
 }

package/dist/dts/components/Utils/initUtils.d.ts

@@ -0,0 +1,7 @@
+import { Utils } from './Utils.js';
+
+/**
+ * @returns A new initialized instance of the `Utils` class.
+ * @see Utils
+ */
+export declare const initUtils: import('../../index.js').InitComponentFn<"version", Utils, never>;

package/dist/dts/components/Viewport/Viewport.d.ts

@@ -0,0 +1,77 @@
+import { WithTrackableState } from '../../classes/WithTrackableState.js';
+import { RemoveEventListenerFn } from '../../events/types.js';
+import { ExecuteWithOptions } from '../../types/index.js';
+import { ViewportProps, ViewportState } from './types.js';
+
+/**
+ * @see Usage: https://docs.telegram-mini-apps.com/platform/viewport
+ * @see API: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/components/viewport
+ */
+export declare class Viewport extends WithTrackableState<ViewportState> {
+    private readonly postEvent;
+    constructor({ postEvent, stableHeight, height, width, isExpanded }: ViewportProps);
+    /**
+     * Requests viewport information from the Telegram application and updates current Viewport
+     * instance.
+     * @param options - options to request fresh data.
+     */
+    sync(options?: ExecuteWithOptions): Promise<void>;
+    /**
+     * 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.
+     *
+     * @see stableHeight
+     */
+    get height(): number;
+    /**
+     * 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 application 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.
+     *
+     * @see height
+     */
+    get stableHeight(): number;
+    /**
+     * Starts listening to viewport changes and applies them.
+     * @returns Function to stop listening.
+     */
+    listen(): RemoveEventListenerFn;
+    /**
+     * 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;
+    /**
+     * Current visible area width.
+     */
+    get width(): number;
+    /**
+     * 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;
+    /**
+     * True if the current viewport height is stable and is not going to change in the next moment.
+     */
+    get isStable(): boolean;
+}

package/dist/dts/components/Viewport/initViewport.d.ts

@@ -0,0 +1,8 @@
+import { Viewport } from './Viewport.js';
+import { ViewportState } from './types.js';
+
+/**
+ * @returns A promise with a new initialized instance of the `Viewport` class.
+ * @see Viewport
+ */
+export declare const initViewport: import('../../misc/createComponentInitFn/types.js').InitComponentFn<"platform", Promise<Viewport>, ViewportState>;

package/dist/dts/components/Viewport/initViewportFromRequest.d.ts

@@ -0,0 +1,10 @@
+import { Viewport } from './Viewport.js';
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { ExecuteWithTimeout } from '../../types/index.js';
+
+/**
+ * Creates new Viewport instance using Mini Apps method.
+ * @param postEvent - function to call Mini Apps method.
+ * @param options - additional execution options.
+ */
+export declare function initViewportFromRequest(postEvent: PostEvent, options?: ExecuteWithTimeout): Promise<Viewport>;

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

@@ -1,4 +1,5 @@
-import type { RequestSimpleOptions } from '../../bridge/request.js';
+import { ExecuteWithOptions } from '../../types/index.js';
+
 export interface RequestViewportResult {
     height: number;
     isStateStable: boolean;
@@ -9,4 +10,4 @@ export interface RequestViewportResult {
  * Requests viewport actual information from the Telegram application.
  * @param options - request options.
  */
-export declare function requestViewport(options?: RequestSimpleOptions<'web_app_request_viewport'>): Promise<RequestViewportResult>;
+export declare function requestViewport(options?: ExecuteWithOptions): Promise<RequestViewportResult>;

package/dist/dts/components/Viewport/types.d.ts

@@ -0,0 +1,35 @@
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { StateEvents } from '../../classes/State/types.js';
+
+/**
+ * Viewport constructor properties.
+ */
+export interface ViewportProps {
+    height: number;
+    width: number;
+    stableHeight: number;
+    isExpanded: boolean;
+    postEvent: PostEvent;
+}
+/**
+ * Viewport internal state.
+ */
+export interface ViewportState {
+    height: number;
+    isExpanded: boolean;
+    stableHeight: number;
+    width: number;
+}
+/**
+ * Viewport trackable events.
+ */
+export interface ViewportEvents extends StateEvents<ViewportState> {
+}
+/**
+ * Viewport event name.
+ */
+export type ViewportEventName = keyof ViewportEvents;
+/**
+ * Viewport event listener.
+ */
+export type ViewportEventListener<E extends ViewportEventName> = ViewportEvents[E];

package/dist/dts/css-vars/bindMiniAppCSSVars.d.ts

@@ -0,0 +1,29 @@
+import { ThemeParams } from '../components/ThemeParams/ThemeParams.js';
+import { MiniApp } from '../components/MiniApp/MiniApp.js';
+import { CleanupFn } from '../types/index.js';
+
+export interface GetMiniAppCSSVarNameFn {
+    /**
+     * @param property - MiniApp property.
+     * @returns Computed complete CSS variable name.
+     */
+    (property: 'bg' | 'header'): string;
+}
+/**
+ * Creates CSS variables connected with the MiniApps class instance background and header colors
+ * based on the passed MiniApp and ThemeParams instances.
+ *
+ * Created variables by default:
+ * - `--tg-bg-color`
+ * - `--tg-header-color`
+ *
+ * Variables are being automatically updated in case, corresponding MiniApp and ThemeParams
+ * properties were updated.
+ *
+ * @param miniApp - MiniApp instance.
+ * @param themeParams - ThemeParams instance.
+ * @param getVarName - function, returning complete CSS variable name for the specified
+ * MiniApp property.
+ * @returns Function to stop updating variables.
+ */
+export declare function bindMiniAppCSSVars(miniApp: MiniApp, themeParams: ThemeParams, getVarName?: GetMiniAppCSSVarNameFn): CleanupFn;

package/dist/dts/css-vars/bindThemeParamsCSSVars.d.ts

@@ -0,0 +1,29 @@
+import { ThemeParams } from '../components/ThemeParams/ThemeParams.js';
+import { CleanupFn } from '../types/index.js';
+
+export interface GetThemeParamsCSSVarNameFn {
+    /**
+     * @param property - ThemeParams property.
+     * @returns Computed complete CSS variable name.
+     */
+    (property: string): string;
+}
+/**
+ * Creates CSS variables connected with the passed instance of the ThemeParams class.
+ *
+ * By default, created CSS variables names are following the pattern "--tg-theme-{name}", where
+ * {name} is a theme parameters key name converted from camel case to kebab case.
+ *
+ * Example:
+ * --tg-theme-bg-color
+ * --tg-theme-secondary-text-color
+ *
+ * Variables are being automatically updated in case, corresponding properties updated in
+ * the passed ThemeParams instance.
+ *
+ * @param themeParams - ThemeParams instance.
+ * @param getCSSVarName - function, returning complete CSS variable name for the specified
+ * ThemeParams property.
+ * @returns Function to stop updating variables.
+ */
+export declare function bindThemeParamsCSSVars(themeParams: ThemeParams, getCSSVarName?: GetThemeParamsCSSVarNameFn): CleanupFn;

package/dist/dts/css-vars/bindViewportCSSVars.d.ts

@@ -0,0 +1,32 @@
+import { Viewport } from '../components/Viewport/Viewport.js';
+import { CleanupFn } from '../types/index.js';
+
+export interface GetViewportCSSVarNameFn {
+    /**
+     * @param property - Viewport property.
+     * @returns Computed complete CSS variable name.
+     */
+    (property: 'width' | 'height' | 'stable-height'): string;
+}
+/**
+ * Accepts Viewport instance and sets CSS variables connected with viewport
+ * sizes.
+ *
+ * Be careful using this function as long as it can impact application
+ * performance. Viewport size is changing rather often, this makes CSS
+ * variables update, which leads to possible layout redraw.
+ *
+ * Variables:
+ * - `--tg-viewport-height`
+ * - `--tg-viewport-width`
+ * - `--tg-viewport-stable-height`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed Viewport instance.
+ *
+ * @param viewport - Viewport instance.
+ * @param getCSSVarName - function, returning complete CSS variable name for the specified
+ * Viewport property.
+ * @returns Function to stop updating variables.
+ */
+export declare function bindViewportCSSVars(viewport: Viewport, getCSSVarName?: GetViewportCSSVarNameFn): CleanupFn;

package/dist/dts/{css → css-vars}/setCSSVar.d.ts

@@ -1,5 +1,5 @@
 /**
- * Sets CSS variable.
+ * Sets CSS variable globally.
  * @param name - variable name.
  * @param value - variable value.
  */

package/dist/dts/debug/debug.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from '../logger/Logger.js';
+
+export declare const logger: Logger;
+/**
+ * Sets new debug mode. Enabling debug mode leads to printing additional messages in the console,
+ * related to the processes inside the package.
+ * @param enable - should debug be enabled.
+ */
+export declare function setDebug(enable: boolean): void;
+/**
+ * Logs info message into the console.
+ * @param args - additional arguments.
+ */
+export declare function log(...args: any[]): void;

package/dist/dts/{bridge/env → env}/hasExternalNotify.d.ts

@@ -1,12 +1,10 @@
-type WithExternalNotify<T> = T & {
-    external: {
-        notify: (...args: any) => any;
-    };
-};
 /**
  * Returns true in case, passed value contains path `external.notify` property and `notify` is a
  * function.
  * @param value - value to check.
  */
-export declare function hasExternalNotify<T extends {}>(value: T): value is WithExternalNotify<T>;
-export {};
+export declare function hasExternalNotify<T extends object>(value: T): value is (T & {
+    external: {
+        notify: (...args: any) => any;
+    };
+});

package/dist/dts/{bridge/env → env}/hasWebviewProxy.d.ts

@@ -1,12 +1,10 @@
-type WithWebviewProxy<T> = T & {
-    TelegramWebviewProxy: {
-        postEvent: (...args: any) => any;
-    };
-};
 /**
  * Returns true in case, passed value contains path `TelegramWebviewProxy.postEvent` property and
  * `postEvent` is a function.
  * @param value - value to check.
  */
-export declare function hasWebviewProxy<T extends {}>(value: T): value is WithWebviewProxy<T>;
-export {};
+export declare function hasWebviewProxy<T extends {}>(value: T): value is (T & {
+    TelegramWebviewProxy: {
+        postEvent: (...args: any) => any;
+    };
+});

package/dist/dts/env/initWeb.d.ts

@@ -0,0 +1,11 @@
+interface CleanupFn {
+    (): void;
+}
+/**
+ * Performs initialization process in the web version of Telegram.
+ * @returns Function, which performs cleanup removing all created elements and listeners.
+ * @param acceptCustomStyles - true if SDK should accept styles sent from the Telegram web
+ * application. This option is only used in web versions of Telegram. Default: false.
+ */
+export declare function initWeb(acceptCustomStyles?: boolean): CleanupFn;
+export {};

package/dist/dts/env/isSSR.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns True, if current environment is server.
+ */
+export declare function isSSR(): boolean;

package/dist/dts/{misc → env}/isTMA.d.ts

@@ -1,4 +1,4 @@
 /**
  * Returns true in case, current environment is Telegram Mini Apps.
  */
-export declare function isTMA(): boolean;
+export declare function isTMA(): Promise<boolean>;

package/dist/dts/errors/SDKError.d.ts

@@ -0,0 +1,9 @@
+import { ErrorType } from './errors.js';
+
+/**
+ * Error used across the SDK.
+ */
+export declare class SDKError extends Error {
+    readonly type: ErrorType;
+    constructor(type: ErrorType, message?: string, cause?: unknown);
+}

package/dist/dts/errors/createError.d.ts

@@ -0,0 +1,10 @@
+import { SDKError } from './SDKError.js';
+import { ErrorType } from './errors.js';
+
+/**
+ * Creates new error using specified type and message.
+ * @param type - error code.
+ * @param message - error message.
+ * @param cause - original error.
+ */
+export declare function createError(type: ErrorType, message: string, cause?: unknown): SDKError;

package/dist/dts/errors/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Specified Mini Apps method is unsupported.
+ */
+export declare const ERR_METHOD_UNSUPPORTED = "ERR_METHOD_UNSUPPORTED";
+/**
+ * Specified Mini Apps method parameter is unsupported.
+ */
+export declare const ERR_METHOD_PARAMETER_UNSUPPORTED = "ERR_METHOD_PARAMETER_UNSUPPORTED";
+/**
+ * Current environment is not Telegram application.
+ */
+export declare const ERR_UNKNOWN_ENV = "ERR_UNKNOWN_ENV";
+/**
+ * Telegram application returned and error while invoking custom method.
+ */
+export declare const ERR_INVOKE_CUSTOM_METHOD_RESPONSE = "ERR_INVOKE_CUSTOM_METHOD_RESPONSE";
+/**
+ * Timeout reached.
+ */
+export declare const ERR_TIMED_OUT = "ERR_TIMED_OUT";
+/**
+ * Value has unexpected type.
+ */
+export declare const ERR_UNEXPECTED_TYPE = "ERR_UNEXPECTED_TYPE";
+/**
+ * Something went wrong during value parsing.
+ */
+export declare const ERR_PARSE = "ERR_PARSE";
+/**
+ * Navigation entries list is empty.
+ */
+export declare const ERR_NAVIGATION_HISTORY_EMPTY = "ERR_NAVIGATION_LIST_EMPTY";
+/**
+ * Navigation entries cursor is invalid.
+ */
+export declare const ERR_NAVIGATION_INDEX_INVALID = "ERR_NAVIGATION_CURSOR_INVALID";
+/**
+ * Navigation entries item is invalid.
+ */
+export declare const ERR_NAVIGATION_ITEM_INVALID = "ERR_NAVIGATION_ITEM_INVALID";
+/**
+ * SSR component initialization failed.
+ */
+export declare const ERR_SSR_INIT = "ERR_SSR_INIT";
+/**
+ * Server side called postEvent.
+ */
+export declare const ERR_SSR_POST_EVENT = "ERR_SSR_POST_EVENT";
+/**
+ * Path starts from the invalid base.
+ */
+export declare const ERR_INVALID_PATH_BASE = "ERR_INVALID_PATH_BASE";
+export type ErrorType = typeof ERR_METHOD_UNSUPPORTED | typeof ERR_METHOD_PARAMETER_UNSUPPORTED | typeof ERR_UNKNOWN_ENV | typeof ERR_INVOKE_CUSTOM_METHOD_RESPONSE | typeof ERR_TIMED_OUT | typeof ERR_PARSE | typeof ERR_UNEXPECTED_TYPE | typeof ERR_NAVIGATION_HISTORY_EMPTY | typeof ERR_NAVIGATION_INDEX_INVALID | typeof ERR_NAVIGATION_ITEM_INVALID | typeof ERR_SSR_INIT | typeof ERR_SSR_POST_EVENT | typeof ERR_INVALID_PATH_BASE;

package/dist/dts/errors/isSDKError.d.ts

@@ -0,0 +1,7 @@
+import { SDKError } from './SDKError.js';
+
+/**
+ * @returns True, if passed value is an instance of SDKError.
+ * @param value - value to check.
+ */
+export declare function isSDKError(value: unknown): value is SDKError;

package/dist/dts/errors/isSDKErrorOfType.d.ts

@@ -0,0 +1,8 @@
+import { ErrorType } from './errors.js';
+
+/**
+ * Returns true if passed value is an SDK error of specified type.
+ * @param value - value to check.
+ * @param type - error type.
+ */
+export declare function isSDKErrorOfType(value: unknown, type: ErrorType): boolean;