@tma.js/sdk 0.13.3 → 1.0.1

package/dist/dts/{components/BackButton → back-button}/BackButton.d.ts

@@ -1,11 +1,13 @@
-import { type PostEvent } from '@tma.js/bridge';
-import type { Version } from '@tma.js/utils';
-import { type SupportsFunc } from '../../supports.js';
+import { type PostEvent } from '../bridge/index.js';
+import { EventEmitter } from '../event-emitter/index.js';
+import { type SupportsFunc } from '../supports/index.js';
+import type { Version } from '../version/index.js';
+import type { BackButtonEvents } from './types.js';
+type Emitter = EventEmitter<BackButtonEvents>;
 /**
- * Class which controls the back button displayed in the header
- * of the Mini App in the Telegram interface. It is mostly used in case, when
- * you want to provide a way to go bach in routing history or "rollback" some
- * action.
+ * Class which controls the back button displayed in the header of the Mini App in the Telegram
+ * interface. It is mostly used in case, when you want to provide a way to go bach in routing
+ * history or "rollback" some action.
  */
 export declare class BackButton {
     private readonly postEvent;
@@ -26,13 +28,13 @@ export declare class BackButton {
      * @param event - event name.
      * @param listener - event listener.
      */
-    on: typeof this.ee.on;
+    on: Emitter['on'];
     /**
      * Removes event listener.
      * @param event - event name.
      * @param listener - event listener.
      */
-    off: typeof this.ee.off;
+    off: Emitter['off'];
     /**
      * Shows the BackButton.
      */
@@ -42,3 +44,4 @@ export declare class BackButton {
      */
     supports: SupportsFunc<'show' | 'hide'>;
 }
+export {};

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

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

package/dist/dts/{components/BackButton → back-button}/types.d.ts

@@ -1,9 +1,10 @@
-import type { StateEvents } from '../../state/index.js';
+import type { MiniAppsEventListener } from '../bridge/index.js';
+import type { StateEvents } from '../state/index.js';
 export interface BackButtonState {
     isVisible: boolean;
 }
 export interface BackButtonEvents extends StateEvents<BackButtonState> {
-    click: () => void;
+    click: MiniAppsEventListener<'main_button_pressed'>;
 }
 export type BackButtonEventName = keyof BackButtonEvents;
 export type BackButtonEventListener<E extends BackButtonEventName> = BackButtonEvents[E];

package/dist/dts/bridge/env/hasExternalNotify.d.ts

@@ -0,0 +1,12 @@
+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 {};

package/dist/dts/bridge/env/hasWebviewProxy.d.ts

@@ -0,0 +1,12 @@
+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 {};

package/dist/dts/bridge/env/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hasExternalNotify.js';
+export * from './hasWebviewProxy.js';
+export * from './isIframe.js';

package/dist/dts/bridge/env/isIframe.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns true in case, current environment is iframe.
+ * @see https://stackoverflow.com/a/326076
+ */
+export declare function isIframe(): boolean;

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

@@ -0,0 +1,8 @@
+import type { Version } from '../../version/index.js';
+import type { MiniAppsMethodName } from '../methods/index.js';
+/**
+ * Error thrown in case, unsupported method was called.
+ */
+export declare class MethodUnsupportedError extends Error {
+    constructor(method: MiniAppsMethodName, version: Version);
+}

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

@@ -0,0 +1,8 @@
+import type { Version } from '../../version/index.js';
+import type { MiniAppsMethodName } from '../methods/index.js';
+/**
+ * Error thrown in case, unsupported parameter was used.
+ */
+export declare class ParameterUnsupportedError extends Error {
+    constructor(method: MiniAppsMethodName, param: string, version: Version);
+}

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

@@ -0,0 +1,2 @@
+export * from './MethodUnsupportedError.js';
+export * from './ParameterUnsupportedError.js';

package/dist/dts/bridge/events/createEmitter.d.ts

@@ -0,0 +1,6 @@
+import type { MiniAppsEventEmitter } from './events.js';
+/**
+ * Returns event emitter which could be safely used, to process events from
+ * Telegram native application.
+ */
+export declare function createEmitter(): MiniAppsEventEmitter;

package/dist/dts/bridge/events/events.d.ts

@@ -0,0 +1,130 @@
+import type { AnySubscribeListener, EventEmitter, EventListener, EventParams } from '../../event-emitter/index.js';
+import type { IsNever, Not } from '../../types/index.js';
+import type { ClipboardTextReceivedPayload, CustomMethodInvokedPayload, InvoiceClosedPayload, PhoneRequestedPayload, PopupClosedPayload, QrTextReceivedPayload, ThemeChangedPayload, ViewportChangedPayload, WriteAccessRequestedPayload } from './parsers/index.js';
+/**
+ * Map where key is known event name, and value is its listener.
+ * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events
+ */
+export interface MiniAppsEvents {
+    /**
+     * User clicked back button.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#back-button-pressed
+     */
+    back_button_pressed: () => void;
+    /**
+     * Telegram application attempted to extract text from clipboard.
+     * @param payload - event payload.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#clipboard-text-received
+     */
+    clipboard_text_received: (payload: ClipboardTextReceivedPayload) => void;
+    /**
+     * Custom method invocation completed.
+     * @param payload - event payload.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#custom-method-invoked
+     */
+    custom_method_invoked: (payload: CustomMethodInvokedPayload) => void;
+    /**
+     * An invoice was closed.
+     * @param payload - invoice close information.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#invoice-closed
+     */
+    invoice_closed: (payload: InvoiceClosedPayload) => void;
+    /**
+     * User clicked the Main Button.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#main-button-pressed
+     */
+    main_button_pressed: () => void;
+    /**
+     * Application received phone access request status.
+     * @param payload - event payload.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#phone-requested
+     */
+    phone_requested: (payload: PhoneRequestedPayload) => void;
+    /**
+     * Popup was closed.
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#popup-closed
+     */
+    popup_closed: (payload: PopupClosedPayload) => void;
+    /**
+     * Parent iframe requested current iframe reload.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#reload-iframe
+     */
+    reload_iframe: () => void;
+    /**
+     * The QR scanner scanned some QR and extracted its content.
+     * @param payload - event payload.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#qr-text-received
+     */
+    qr_text_received: (payload: QrTextReceivedPayload) => void;
+    /**
+     * QR scanner was closed.
+     * @since v6.4
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#scan-qr-popup-closed
+     */
+    scan_qr_popup_closed: () => void;
+    /**
+     * The event which is usually sent by the Telegram web application. Its payload represents
+     * `<style/>` tag html content, a developer could use. The stylesheet described in the payload
+     * will help the developer to stylize the app scrollbar (but he is still able to do it himself).
+     * @param html - `style` tag inner HTML.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#set-custom-style
+     */
+    set_custom_style: (html: string) => void;
+    /**
+     * Occurs when the Settings Button was pressed.
+     * @since v6.1
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#settings-button-pressed
+     */
+    settings_button_pressed: () => void;
+    /**
+     * Occurs whenever theme settings are changed in the user's Telegram app
+     * (including switching to night mode).
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#theme-changed
+     */
+    theme_changed: (payload: ThemeChangedPayload) => void;
+    /**
+     * Occurs whenever the viewport has been changed. For example, when the user started
+     * dragging the application or called the expansion method.
+     * @param payload - event payload.
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#viewport-changed
+     */
+    viewport_changed: (payload: ViewportChangedPayload) => void;
+    /**
+     * Application received write access request status.
+     * @param payload - event payload.
+     * @since v6.9
+     * @see https://docs.telegram-mini-apps.com/platform/apps-communication/events#write-access-requested
+     */
+    write_access_requested: (payload: WriteAccessRequestedPayload) => void;
+}
+/**
+ * Any known event name.
+ */
+export type MiniAppsEventName = keyof MiniAppsEvents;
+/**
+ * Parameters of specified event.
+ */
+export type MiniAppsEventParams<E extends MiniAppsEventName> = EventParams<MiniAppsEvents[E]>[0];
+/**
+ * Returns event listener for specified event name.
+ */
+export type MiniAppsEventListener<E extends MiniAppsEventName> = EventListener<MiniAppsEvents[E]>;
+/**
+ * Event emitter, based describe events map.
+ */
+export type MiniAppsEventEmitter = EventEmitter<MiniAppsEvents>;
+/**
+ * Returns true in case, event has parameters.
+ */
+export type MiniAppsEventHasParams<E extends MiniAppsEventName> = Not<IsNever<MiniAppsEventParams<E>>>;
+/**
+ * Event listener used in `subscribe` and `unsubscribe` functions.
+ */
+export type MiniAppsGlobalEventListener = AnySubscribeListener<MiniAppsEvents> | ((event: string, data: unknown) => void);

package/dist/dts/bridge/events/index.d.ts

@@ -0,0 +1,9 @@
+export * from './createEmitter.js';
+export * from './events.js';
+export * from './off.js';
+export * from './on.js';
+export * from './once.js';
+export * from './parsers/index.js';
+export * from './singletonEmitter.js';
+export * from './subscribe.js';
+export * from './unsubscribe.js';

package/dist/dts/bridge/events/off.d.ts

@@ -0,0 +1,7 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+/**
+ * Removes listener from specified event.
+ * @param event - event to listen.
+ * @param listener - event listener.
+ */
+export declare function off<E extends MiniAppsEventName>(event: E, listener: MiniAppsEventListener<E>): void;

package/dist/dts/bridge/events/on.d.ts

@@ -0,0 +1,10 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+type StopListening = () => void;
+/**
+ * Adds new listener to the specified event. Returns handler
+ * which allows to stop listening to event.
+ * @param event - event name.
+ * @param listener - event listener.
+ */
+export declare function on<E extends MiniAppsEventName>(event: E, listener: MiniAppsEventListener<E>): StopListening;
+export {};

package/dist/dts/bridge/events/onTelegramEvent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Adds listener to window "message" event assuming, that this event could
+ * be sent by Telegram native application. Calls passed callback with event
+ * type and data.
+ * @param cb - callback to call.
+ */
+export declare function onTelegramEvent(cb: (eventType: string, eventData: unknown) => void): void;

package/dist/dts/bridge/events/once.d.ts

@@ -0,0 +1,9 @@
+import type { MiniAppsEventListener, MiniAppsEventName } from './events.js';
+type StopListening = () => void;
+/**
+ * Works the same as "on" method, but after catching the event, will remove event listener.
+ * @param event - event name.
+ * @param listener - event listener.
+ */
+export declare function once<E extends MiniAppsEventName>(event: E, listener: MiniAppsEventListener<E>): StopListening;
+export {};

package/dist/dts/bridge/events/parsers/clipboardTextReceived.d.ts

@@ -0,0 +1,13 @@
+import type { RequestId } from '../../../types/index.js';
+export interface ClipboardTextReceivedPayload {
+    /**
+     * Passed during the `web_app_read_text_from_clipboard` method invocation `req_id` value.
+     */
+    req_id: RequestId;
+    /**
+     * Data extracted from the clipboard. The returned value will have the type `string` only in
+     * the case, application has access to the clipboard.
+     */
+    data?: string | null;
+}
+export declare function clipboardTextReceived(): import('../../../parsing/index.js').ValueParser<ClipboardTextReceivedPayload, false>;

package/dist/dts/bridge/events/parsers/customMethodInvoked.d.ts

@@ -0,0 +1,16 @@
+import type { RequestId } from '../../../types/index.js';
+export interface CustomMethodInvokedPayload<R = unknown> {
+    /**
+     * Unique identifier of this invocation.
+     */
+    req_id: RequestId;
+    /**
+     * Method invocation successful result.
+     */
+    result?: R;
+    /**
+     * Method invocation error code.
+     */
+    error?: string;
+}
+export declare function customMethodInvoked(): import('../../../parsing/index.js').ValueParser<CustomMethodInvokedPayload<unknown>, false>;

package/dist/dts/bridge/events/parsers/index.d.ts

@@ -0,0 +1,9 @@
+export * from './clipboardTextReceived.js';
+export * from './customMethodInvoked.js';
+export * from './invoiceClosed.js';
+export * from './phoneRequested.js';
+export * from './popupClosed.js';
+export * from './qrTextReceived.js';
+export * from './theme-changed.js';
+export * from './viewportChanged.js';
+export * from './writeAccessRequested.js';

package/dist/dts/bridge/events/parsers/invoiceClosed.d.ts

@@ -0,0 +1,12 @@
+export type InvoiceStatus = 'paid' | 'failed' | 'pending' | 'cancelled' | string;
+export interface InvoiceClosedPayload {
+    /**
+     * Passed during the `web_app_open_invoice` method invocation `slug` value.
+     */
+    slug: string;
+    /**
+     * Invoice status
+     */
+    status: InvoiceStatus;
+}
+export declare function invoiceClosed(): import('../../../parsing/index.js').ValueParser<InvoiceClosedPayload, false>;

package/dist/dts/bridge/events/parsers/phoneRequested.d.ts

@@ -0,0 +1,8 @@
+export type PhoneRequestedStatus = 'sent' | string;
+export interface PhoneRequestedPayload {
+    /**
+     * Request status.
+     */
+    status: PhoneRequestedStatus;
+}
+export declare function phoneRequested(): import('../../../parsing/index.js').ValueParser<PhoneRequestedPayload, false>;

package/dist/dts/bridge/events/parsers/popupClosed.d.ts

@@ -0,0 +1,8 @@
+export interface PopupClosedPayload {
+    /**
+     * Identifier of the clicked button. In case, the popup was closed without clicking any button,
+     * this property will be omitted.
+     */
+    button_id?: string;
+}
+export declare function popupClosed(): import('../../../parsing/index.js').ValueParser<PopupClosedPayload, false>;

package/dist/dts/bridge/events/parsers/qrTextReceived.d.ts

@@ -0,0 +1,7 @@
+export interface QrTextReceivedPayload {
+    /**
+     * Data extracted from the QR.
+     */
+    data?: string;
+}
+export declare function qrTextReceived(): import('../../../parsing/index.js').ValueParser<QrTextReceivedPayload, false>;

package/dist/dts/bridge/events/parsers/theme-changed.d.ts

@@ -0,0 +1,42 @@
+import type { RGB } from '../../../colors/index.js';
+export interface ThemeChangedPayload {
+    /**
+     * Map where the key is a theme stylesheet key and value is  the corresponding color in
+     * `#RRGGBB` format.
+     */
+    theme_params: {
+        /**
+         * @since v6.10
+         */
+        accent_text_color?: RGB;
+        bg_color?: RGB;
+        button_color?: RGB;
+        button_text_color?: RGB;
+        /**
+         * @since v6.10
+         */
+        destructive_text_color?: RGB;
+        /**
+         * @since v6.10
+         */
+        header_bg_color?: RGB;
+        hint_color?: RGB;
+        link_color?: RGB;
+        secondary_bg_color?: RGB;
+        /**
+         * @since v6.10
+         */
+        section_bg_color?: RGB;
+        /**
+         * @since v6.10
+         */
+        section_header_text_color?: RGB;
+        /**
+         * @since v6.10
+         */
+        subtitle_text_color?: RGB;
+        text_color?: RGB;
+        [key: string]: RGB | undefined;
+    };
+}
+export declare function themeChanged(): import('../../../parsing/index.js').ValueParser<ThemeChangedPayload, false>;

package/dist/dts/bridge/events/parsers/viewportChanged.d.ts

@@ -0,0 +1,19 @@
+export interface ViewportChangedPayload {
+    /**
+     * The viewport height.
+     */
+    height: number;
+    /**
+     * The viewport width.
+     */
+    width: number;
+    /**
+     * Is the viewport currently expanded.
+     */
+    is_expanded: boolean;
+    /**
+     * Is the viewport current state stable and not going to change in the next moment.
+     */
+    is_state_stable: boolean;
+}
+export declare function viewportChanged(): import('../../../parsing/index.js').ValueParser<ViewportChangedPayload, false>;

package/dist/dts/bridge/events/parsers/writeAccessRequested.d.ts

@@ -0,0 +1,8 @@
+export type WriteAccessRequestedStatus = 'allowed' | string;
+export interface WriteAccessRequestedPayload {
+    /**
+     * Request status.
+     */
+    status: WriteAccessRequestedStatus;
+}
+export declare function writeAccessRequested(): import('../../../parsing/index.js').ValueParser<WriteAccessRequestedPayload, false>;

package/dist/dts/bridge/events/singletonEmitter.d.ts

@@ -0,0 +1,6 @@
+import type { MiniAppsEventEmitter } from '../../bridge/index.js';
+/**
+ * Returns singleton instance of bridge EventEmitter. Also, defines
+ * Telegram event handlers.
+ */
+export declare function singletonEmitter(): MiniAppsEventEmitter;

package/dist/dts/bridge/events/subscribe.d.ts

@@ -0,0 +1,9 @@
+import type { MiniAppsGlobalEventListener } from './events.js';
+type StopListening = () => void;
+/**
+ * Subscribes to all events sent from the native Telegram application.
+ * Returns function used to remove added event listener.
+ * @param listener - event listener.
+ */
+export declare function subscribe(listener: MiniAppsGlobalEventListener): StopListening;
+export {};

package/dist/dts/bridge/events/unsubscribe.d.ts

@@ -0,0 +1,6 @@
+import type { MiniAppsGlobalEventListener } from './events.js';
+/**
+ * Removes global event listener.
+ * @param listener - event listener.
+ */
+export declare function unsubscribe(listener: MiniAppsGlobalEventListener): void;

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

@@ -0,0 +1,5 @@
+export * from './env/index.js';
+export * from './errors/index.js';
+export * from './events/index.js';
+export * from './methods/index.js';
+export * from './request.js';

package/dist/dts/bridge/methods/createPostEvent.d.ts

@@ -0,0 +1,10 @@
+import type { Version } from '../../version/index.js';
+import { type PostEvent } from './postEvent.js';
+/**
+ * Creates function which checks if specified method and parameters are supported. In case,
+ * method or parameters are unsupported, an error will be thrown.
+ * @param version - Telegram Mini Apps version.
+ * @throws {MethodUnsupportedError} Method is unsupported.
+ * @throws {ParameterUnsupportedError} Method parameter is unsupported.
+ */
+export declare function createPostEvent(version: Version): PostEvent;

package/dist/dts/bridge/methods/haptic.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Generic type which creates new types of haptic feedback.
+ */
+type CreateHapticFeedbackParams<T extends string, P> = {
+    type: T;
+} & P;
+/**
+ * Style of impact occurred haptic event.
+ * - `light`, indicates a collision between small or lightweight UI objects,
+ * - `medium`, indicates a collision between medium-sized or medium-weight UI objects,
+ * - `heavy`, indicates a collision between large or heavyweight UI objects,
+ * - `rigid`, indicates a collision between hard or inflexible UI objects,
+ * - `soft`, indicates a collision between soft or flexible UI objects.
+ */
+export type ImpactHapticFeedbackStyle = 'light' | 'medium' | 'heavy' | 'rigid' | 'soft';
+/**
+ * Type of notification occurred type event.
+ * - `error`, indicates that a task or action has failed,
+ * - `success`, indicates that a task or action has completed successfully,
+ * - `warning`, indicates that a task or action produced a warning.
+ */
+export type NotificationHapticFeedbackType = 'error' | 'success' | 'warning';
+/**
+ * `impactOccurred` haptic feedback.
+ */
+export type ImpactHapticFeedbackParams = CreateHapticFeedbackParams<'impact', {
+    impact_style: ImpactHapticFeedbackStyle;
+}>;
+/**
+ * `notificationOccurred` haptic feedback.
+ */
+export type NotificationHapticFeedbackParams = CreateHapticFeedbackParams<'notification', {
+    notification_type: NotificationHapticFeedbackType;
+}>;
+/**
+ * `selectionChanged` haptic feedback.
+ */
+export type SelectionHapticFeedbackParams = CreateHapticFeedbackParams<'selection_change', {}>;
+export type AnyHapticFeedbackParams = ImpactHapticFeedbackParams | NotificationHapticFeedbackParams | SelectionHapticFeedbackParams;
+export {};

package/dist/dts/bridge/methods/index.d.ts

@@ -0,0 +1,6 @@
+export * from './createPostEvent.js';
+export * from './haptic.js';
+export * from './invoke-custom-method.js';
+export * from './methods.js';
+export * from './popup.js';
+export * from './postEvent.js';

package/dist/dts/bridge/methods/invoke-custom-method.d.ts

@@ -0,0 +1,24 @@
+import type { RequestId } from '../../types/index.js';
+interface CreateInvokeCustomMethodParams<M extends string, Params extends object> {
+    /**
+     * Unique request identifier.
+     */
+    req_id: RequestId;
+    /**
+     * Method name.
+     */
+    method: M;
+    /**
+     * Method specific parameters.
+     */
+    params: Params;
+}
+export type AnyInvokeCustomMethodParams = CreateInvokeCustomMethodParams<'deleteStorageValues', {
+    keys: string | string[];
+}> | CreateInvokeCustomMethodParams<'getStorageValues', {
+    keys: string | string[];
+}> | CreateInvokeCustomMethodParams<'getStorageKeys', {}> | CreateInvokeCustomMethodParams<'saveStorageValue', {
+    key: string;
+    value: string;
+}> | CreateInvokeCustomMethodParams<string, any>;
+export {};