@tma.js/sdk 0.13.3 → 1.0.1

package/dist/dts/init-data/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Known type of chat.
+ */
+export type ChatType = 'sender' | 'private' | 'group' | 'supergroup' | 'channel' | string;
+/**
+ * Describes Telegram Mini Apps [User](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#user) type.
+ */
+export interface User {
+    /**
+     * True, if this user added the bot to the attachment menu.
+     */
+    addedToAttachmentMenu?: boolean;
+    /**
+     * True, if this user allowed the bot to message them.
+     */
+    allowsWriteToPm?: boolean;
+    /**
+     * First name of the user or bot.
+     */
+    firstName: string;
+    /**
+     * A unique identifier for the user or bot.
+     */
+    id: number;
+    /**
+     * True, if this user is a bot. Returned in the `receiver` field only.
+     * @see InitDataParsed.receiver
+     */
+    isBot?: boolean;
+    /**
+     * True, if this user is a Telegram Premium user.
+     */
+    isPremium?: boolean;
+    /**
+     * Last name of the user or bot.
+     */
+    lastName?: string;
+    /**
+     * [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) of the user's language.
+     * Returns in user field only.
+     */
+    languageCode?: string;
+    /**
+     * URL of the user’s profile photo. The photo can be in .jpeg or .svg
+     * formats. Only returned for Mini Apps launched from the attachment menu.
+     */
+    photoUrl?: string;
+    /**
+     * Username of the user or bot.
+     */
+    username?: string;
+}
+/**
+ * Describes Telegram Mini Apps [Chat](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#chat) type.
+ */
+export interface Chat {
+    /**
+     * Unique identifier for this chat.
+     */
+    id: number;
+    /**
+     * URL of the chat’s photo. The photo can be in .jpeg or .svg formats.
+     * Only returned for Mini Apps launched from the attachment menu.
+     */
+    photoUrl?: string;
+    /**
+     * Type of chat.
+     */
+    type: 'group' | 'supergroup' | 'channel' | string;
+    /**
+     * Title of the chat.
+     */
+    title: string;
+    /**
+     * Username of the chat.
+     */
+    username?: string;
+}
+/**
+ * Describes Telegram Mini Apps [InitData](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#parameters-list)
+ * type.
+ */
+export interface InitDataParsed {
+    /**
+     * Init data generation date.
+     */
+    authDate: Date;
+    /**
+     * The number of seconds after which a message can be sent via the method [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery).
+     */
+    canSendAfter?: number;
+    /**
+     * An object containing data about the chat where the bot was launched via
+     * the attachment menu. Returned for supergroups, channels and group
+     * chats – only for Mini Apps launched via the attachment menu.
+     */
+    chat?: Chat;
+    /**
+     * The type of chat from which Mini App was opened.
+     */
+    chatType?: ChatType;
+    /**
+     * A global identifier indicating the chat from which Mini App was opened. Returned only for
+     * applications opened by direct link.
+     */
+    chatInstance?: string;
+    /**
+     * A hash of all passed parameters, which the bot server can use to
+     * check their [validity](https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app).
+     */
+    hash: string;
+    /**
+     * A unique identifier for the Mini App session, required for sending
+     * messages via the [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
+     */
+    queryId?: string;
+    /**
+     * An object containing data about the chat partner of the current user in
+     * the chat where the bot was launched via the attachment menu.
+     * Returned only for private chats and only for Mini Apps launched
+     * via the attachment menu.
+     */
+    receiver?: User;
+    /**
+     * The value of the `startattach` parameter, passed via link. Only returned for
+     * Mini Apps when launched from the attachment menu via link.
+     */
+    startParam?: string;
+    /**
+     * An object containing data about the current user.
+     */
+    user?: User;
+}

package/dist/dts/init-data/userParser.d.ts

@@ -0,0 +1,5 @@
+import type { User } from './types.js';
+/**
+ * Returns parser used to parse user data.
+ */
+export declare function userParser(): import('../parsing/index.js').ValueParser<User, false>;

package/dist/dts/invoice/Invoice.d.ts

@@ -0,0 +1,43 @@
+import { type InvoiceStatus, type PostEvent } from '../bridge/index.js';
+import { type SupportsFunc } from '../supports/index.js';
+import type { Version } from '../version/index.js';
+import type { InvoiceEvents } from './types.js';
+/**
+ * Controls currently displayed invoice.
+ */
+export declare class Invoice {
+    private readonly postEvent;
+    private readonly ee;
+    private readonly state;
+    constructor(version: Version, postEvent?: PostEvent);
+    private set isOpened(value);
+    /**
+     * True if invoice is currently opened.
+     */
+    get isOpened(): boolean;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<InvoiceEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<InvoiceEvents[E]>) => void;
+    /**
+     * Opens an invoice using its slug.
+     * @param slug - invoice slug.
+     * @throws {Error} Invoice is already opened.
+     */
+    open(slug: string): Promise<InvoiceStatus>;
+    /**
+     * Opens an invoice using its url. It expects passing link in full format, with hostname "t.me".
+     * @param url - invoice URL.
+     * @param type - value type.
+     * @throws {Error} Invoice is already opened.
+     */
+    open(url: string, type: 'url'): Promise<InvoiceStatus>;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'open'>;
+}

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

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

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

@@ -0,0 +1,7 @@
+import type { StateEvents } from '../state/index.js';
+export interface InvoiceState {
+    isOpened: boolean;
+}
+export type InvoiceEvents = StateEvents<InvoiceState>;
+export type InvoiceEventName = keyof InvoiceEvents;
+export type InvoiceEventListener<E extends InvoiceEventName> = InvoiceEvents[E];

package/dist/dts/launch-params/computeLaunchData.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchData } from './types.js';
+/**
+ * Computes launch data information. Extracts both previous and current launch parameters
+ * to compute current list of them. Additionally, computes if page was reloaded.
+ */
+export declare function computeLaunchData(): LaunchData;

package/dist/dts/launch-params/computePageReload.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Determines if current page was reloaded.
+ * @returns Boolean if function was able to compute any valid value. Null in case, no
+ * navigation entries were found.
+ */
+export declare function computePageReload(): boolean | null;

package/dist/dts/launch-params/getFirstNavigationEntry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the first navigation entry from window.performance.
+ * @returns First navigation entry or null, in case performance functionality is not supported
+ * or navigation entry was not found.
+ */
+export declare function getFirstNavigationEntry(): PerformanceNavigationTiming | null;

package/dist/dts/launch-params/index.d.ts

@@ -0,0 +1,12 @@
+export * from './computeLaunchData.js';
+export * from './computePageReload.js';
+export * from './getFirstNavigationEntry.js';
+export * from './launchParamsParser.js';
+export * from './parseLaunchParams.js';
+export * from './retrieveCurrent.js';
+export * from './retrieveFromLocation.js';
+export * from './retrieveFromPerformance.js';
+export * from './retrieveLaunchData.js';
+export * from './serializeLaunchParams.js';
+export * from './storage.js';
+export * from './types.js';

package/dist/dts/launch-params/launchParamsParser.d.ts

@@ -0,0 +1,5 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Returns parser used to parse launch params.
+ */
+export declare function launchParamsParser(): import('../parsing/index.js').ValueParser<LaunchParams, false>;

package/dist/dts/launch-params/parseLaunchParams.d.ts

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

package/dist/dts/launch-params/retrieveCurrent.d.ts

@@ -0,0 +1,5 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Attempts to retrieve launch parameters using every known way.
+ */
+export declare function retrieveCurrent(): LaunchParams | null;

package/dist/dts/launch-params/retrieveFromLocation.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Attempts to extract launch parameters from the current window location hash.
+ * @throws {Error} window.location.hash contains invalid data.
+ */
+export declare function retrieveFromLocation(): LaunchParams;

package/dist/dts/launch-params/retrieveFromPerformance.d.ts

@@ -0,0 +1,8 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Attempts to read launch parameters using window.performance data.
+ * @throws {Error} Unable to get first navigation entry.
+ * @throws {Error} First navigation entry does not contain hash part.
+ * @throws {TypeError} Unable to parse value.
+ */
+export declare function retrieveFromPerformance(): LaunchParams;

package/dist/dts/launch-params/retrieveLaunchData.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchData } from './types.js';
+/**
+ * Returns launch data information. Function ignores passed options in case, it was already
+ * called. It caches the last returned value.
+ */
+export declare function retrieveLaunchData(): LaunchData;

package/dist/dts/launch-params/serializeLaunchParams.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Converts launch parameters to its initial representation.
+ * @param value - launch parameters.
+ */
+export declare function serializeLaunchParams(value: LaunchParams): string;

package/dist/dts/launch-params/storage.d.ts

@@ -0,0 +1,13 @@
+import type { LaunchParams } from './types.js';
+/**
+ * Attempts to extract launch parameters directly from the session storage.
+ * @returns Launch parameters in case, they were stored before or null, if there is no launch
+ * parameters key in the session storage.
+ * @throws {Error} Data stored in the session storage is invalid.
+ */
+export declare function retrieveFromStorage(): LaunchParams | null;
+/**
+ * Saves specified launch parameters in the session storage.
+ * @param value - launch params to save.
+ */
+export declare function saveToStorage(value: LaunchParams): void;

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

@@ -0,0 +1,48 @@
+import type { InitDataParsed } from '../init-data/index.js';
+import type { ThemeParamsParsed } from '../theme-params/index.js';
+import type { Platform } from '../types/index.js';
+/**
+ * Telegram Mini Apps launch parameters.
+ * @see https://docs.telegram-mini-apps.com/platform/launch-parameters/common-information
+ */
+export interface LaunchParams {
+    /**
+     * Current Mini Apps version.
+     */
+    version: string;
+    /**
+     * Current launch init data. Can be missing in case, application was launched via
+     * KeyboardButton.
+     */
+    initData?: InitDataParsed;
+    /**
+     * The same as initData but in initial, raw format.
+     */
+    initDataRaw?: string;
+    /**
+     * Current Telegram application identifier.
+     */
+    platform: Platform;
+    /**
+     * Mini App palette settings.
+     */
+    themeParams: ThemeParamsParsed;
+    /**
+     * True if Mini App is currently launched in inline mode.
+     */
+    botInline?: boolean;
+    /**
+     * True if application is required to show the Settings Button.
+     */
+    showSettings?: boolean;
+}
+export interface LaunchData {
+    /**
+     * Was current application reloaded.
+     */
+    isPageReload: boolean;
+    /**
+     * Current application launch parameters.
+     */
+    launchParams: LaunchParams;
+}

package/dist/dts/logger/Logger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Message log level.
+ */
+export type LogLevel = 'log' | 'error' | 'warn';
+export declare class Logger {
+    private readonly prefix;
+    private enabled;
+    constructor(prefix: string, enabled: boolean);
+    /**
+     * Prints message into a console in case, logger is currently enabled.
+     * @param level - log level.
+     * @param args - arguments.
+     */
+    private print;
+    /**
+     * Disables the logger.
+     */
+    disable(): void;
+    /**
+     * Prints error message into a console.
+     * @param args
+     */
+    error(...args: any[]): void;
+    /**
+     * Enables the logger.
+     */
+    enable(): void;
+    /**
+     * Prints log message into a console.
+     * @param args
+     */
+    log(...args: any[]): void;
+    /**
+     * Prints warning message into a console.
+     * @param args
+     */
+    warn(...args: any[]): void;
+}

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

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

package/dist/dts/main-button/MainButton.d.ts

@@ -0,0 +1,104 @@
+import { EventEmitter } from '../event-emitter/index.js';
+import type { RGB } from '../colors/index.js';
+import type { MainButtonEvents, MainButtonParams, MainButtonProps } from './types.js';
+type Emitter = EventEmitter<MainButtonEvents>;
+/**
+ * Controls the main button, which is displayed at the bottom
+ * of the Mini App in the Telegram interface.
+ */
+export declare class MainButton {
+    private readonly ee;
+    private readonly state;
+    private readonly postEvent;
+    constructor(props: MainButtonProps);
+    /**
+     * Sends current local state to Telegram application.
+     */
+    private commit;
+    private set isEnabled(value);
+    /**
+     * True if the Main Button is currently enabled.
+     */
+    get isEnabled(): boolean;
+    private set isLoaderVisible(value);
+    /**
+     * True if the Main Button loader is currently visible.
+     */
+    get isLoaderVisible(): boolean;
+    private set isVisible(value);
+    /**
+     * True if the Main Button is currently visible.
+     */
+    get isVisible(): boolean;
+    /**
+     * The Main Button background color.
+     */
+    get backgroundColor(): RGB;
+    /**
+     * The Main Button text.
+     */
+    get text(): string;
+    /**
+     * The Main Button text color.
+     */
+    get textColor(): RGB;
+    /**
+     * Disables the Main Button.
+     */
+    disable(): this;
+    /**
+     * Enables the Main Button.
+     */
+    enable(): this;
+    /**
+     * Hides the Main Button.
+     */
+    hide(): this;
+    /**
+     * Hides the Main Button loader.
+     */
+    hideLoader(): this;
+    /**
+     * Adds new event listener.
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    on: Emitter['on'];
+    /**
+     * Removes event listener.
+     * @param event - event name.
+     * @param listener - event listener.
+     */
+    off: Emitter['off'];
+    /**
+     * Shows the Main Button. Note that opening the Mini App from the attachment menu hides the
+     * main button until the user interacts with the Mini App interface.
+     */
+    show(): this;
+    /**
+     * A method to show a loading indicator on the Main Button. It is recommended to display
+     * loader if the action tied to the button may take a long time.
+     */
+    showLoader(): this;
+    /**
+     * Sets new Main Button text. Minimal length for text is 1 symbol, and maximum is 64 symbols.
+     * @param text - new text.
+     */
+    setText(text: string): this;
+    /**
+     * Sets new Main Button text color.
+     * @param textColor - new text color.
+     */
+    setTextColor(textColor: RGB): this;
+    /**
+     * Updates current Main Button color.
+     * @param backgroundColor - color to set.
+     */
+    setBackgroundColor(backgroundColor: RGB): this;
+    /**
+     * Allows setting multiple Main Button parameters.
+     * @param params - Main Button parameters.
+     */
+    setParams(params: MainButtonParams): this;
+}
+export {};

package/dist/dts/main-button/index.d.ts

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

package/dist/dts/main-button/types.d.ts

@@ -0,0 +1,20 @@
+import type { PostEvent } from '../bridge/index.js';
+import type { RGB } from '../colors/index.js';
+import type { StateEvents } from '../state/index.js';
+export interface MainButtonParams {
+    backgroundColor?: RGB;
+    isEnabled?: boolean;
+    isLoaderVisible?: boolean;
+    isVisible?: boolean;
+    text?: string;
+    textColor?: RGB;
+}
+export interface MainButtonProps extends Required<MainButtonParams> {
+    postEvent?: PostEvent;
+}
+export type MainButtonState = Required<MainButtonParams>;
+export interface MainButtonEvents extends StateEvents<MainButtonState> {
+    click: () => void;
+}
+export type MainButtonEventName = keyof MainButtonEvents;
+export type MainButtonEventListener<E extends MainButtonEventName> = MainButtonEvents[E];

package/dist/dts/mini-app/MiniApp.d.ts

@@ -0,0 +1,99 @@
+import { type PhoneRequestedStatus, type SwitchInlineQueryChatType, type WriteAccessRequestedStatus } from '../bridge/index.js';
+import { type RGB } from '../colors/index.js';
+import { type SupportsFunc } from '../supports/index.js';
+import type { MiniAppEvents, MiniAppHeaderColor, MiniAppProps } from './types.js';
+/**
+ * Provides common Mini Apps functionality not covered by other system components.
+ */
+export declare class MiniApp {
+    private readonly ee;
+    private readonly state;
+    private readonly botInline;
+    private readonly postEvent;
+    constructor(props: MiniAppProps);
+    /**
+     * The Mini App background color.
+     */
+    get backgroundColor(): RGB;
+    /**
+     * Closes the Mini App.
+     */
+    close(): void;
+    /**
+     * The Mini App header color. Could either be a header color key or RGB color.
+     */
+    get headerColor(): MiniAppHeaderColor;
+    /**
+     * True if Mini App is currently launched in bot inline mode.
+     */
+    get isBotInline(): boolean;
+    /**
+     * True if current Mini App background color recognized as dark.
+     */
+    get isDark(): boolean;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends "change" | "change:backgroundColor" | "change:headerColor">(event: E, listener: import('../event-emitter/index.js').EventListener<MiniAppEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends "change" | "change:backgroundColor" | "change:headerColor">(event: E, listener: import('../event-emitter/index.js').EventListener<MiniAppEvents[E]>) => void;
+    /**
+     * Informs the Telegram app that the Mini App is ready to be displayed.
+     *
+     * It is recommended to call this method as early as possible, as soon as all essential
+     * interface elements loaded. Once this method called, the loading placeholder is hidden
+     * and the Mini App shown.
+     *
+     * If the method not called, the placeholder will be hidden only when the page fully loaded.
+     */
+    ready(): void;
+    /**
+     * Requests current user phone access.
+     */
+    requestPhoneAccess(): Promise<PhoneRequestedStatus>;
+    /**
+     * Requests write message access to current user.
+     */
+    requestWriteAccess(): Promise<WriteAccessRequestedStatus>;
+    /**
+     * A method used to send data to the bot. When this method called, a service message sent to
+     * the bot containing the data of the length up to 4096 bytes, and the Mini App closed. See the
+     * field `web_app_data` in the class [Message](https://core.telegram.org/bots/api#message).
+     *
+     * This method is only available for Mini Apps launched via a Keyboard button.
+     * @param data - data to send to bot.
+     * @throws {Error} data has incorrect size.
+     */
+    sendData(data: string): void;
+    /**
+     * Updates current Mini App header color.
+     * @param color - color key or RGB color.
+     */
+    setHeaderColor(color: MiniAppHeaderColor): void;
+    /**
+     * Updates current Mini App background color.
+     * @param color - RGB color.
+     */
+    setBackgroundColor(color: RGB): void;
+    /**
+     * Checks if specified method is supported by current component.
+     */
+    supports: SupportsFunc<'requestWriteAccess' | 'requestPhoneAccess' | 'switchInlineQuery' | 'setHeaderColor' | 'setBackgroundColor'>;
+    /**
+     * Checks if specified method parameter is supported by current component.
+     */
+    supportsParam: SupportsFunc<'setHeaderColor.color'>;
+    /**
+     * Inserts the bot's username and the specified inline query in the current chat's input field.
+     * Query may be empty, in which case only the bot's username will be inserted. The client prompts
+     * the user to choose a specific chat, then opens that chat and inserts the bot's username and
+     * the specified inline query in the input field.
+     * @param text - text which should be inserted in the input after the current bot name. Max
+     * length is 256 symbols.
+     * @param chatTypes - List of chat types which could be chosen to send the message. Could be
+     * empty list.
+     */
+    switchInlineQuery(text: string, chatTypes?: SwitchInlineQueryChatType[]): void;
+}

package/dist/dts/mini-app/index.d.ts

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

package/dist/dts/mini-app/types.d.ts

@@ -0,0 +1,19 @@
+import type { HeaderColorKey, PostEvent } from '../bridge/index.js';
+import type { RGB } from '../colors/index.js';
+import type { StateEvents } from '../state/index.js';
+import type { Version } from '../version/index.js';
+export interface MiniAppProps {
+    headerColor: MiniAppHeaderColor;
+    backgroundColor: RGB;
+    version: Version;
+    botInline: boolean;
+    postEvent?: PostEvent;
+}
+export type MiniAppHeaderColor = HeaderColorKey | RGB;
+export interface MiniAppState {
+    backgroundColor: RGB;
+    headerColor: MiniAppHeaderColor;
+}
+export type MiniAppEvents = StateEvents<MiniAppState>;
+export type MiniAppEventName = keyof MiniAppEvents;
+export type MiniAppEventListener<E extends MiniAppEventName> = MiniAppEvents[E];

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

@@ -0,0 +1,2 @@
+export * from './isRecord.js';
+export * from './isTMA.js';

package/dist/dts/misc/isRecord.d.ts

@@ -0,0 +1,5 @@
+/**
+ * States that passed value is Record and not Array.
+ * @param value - value to check.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/dts/misc/isTMA.d.ts

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