@tma.js/bridge 1.4.0 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Vladislav Kibenko
+Copyright (c) 2025 Vladislav Kibenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,28 +1,59 @@
 # @tma.js/bridge
 
-[code-link]: https://github.com/Telegram-Mini-Apps/tma.js/tree/master/packages/bridge
-
 [code-badge]: https://img.shields.io/badge/source-black?logo=github
 
-[docs-link]: https://docs.telegram-mini-apps.com/packages/typescript/tma-js-bridge
-
 [docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
 
+[link]: https://github.com/Telegram-Mini-Apps/telegram-apps/tree/master/tma.js/bridge
+
+[docs-link]: https://docs.telegram-mini-apps.com/packages/tma-js-bridge
+
 [npm-link]: https://npmjs.com/package/@tma.js/bridge
 
 [npm-badge]: https://img.shields.io/npm/v/@tma.js/bridge?logo=npm
 
 [size-badge]: https://img.shields.io/bundlephobia/minzip/@tma.js/bridge
 
-[![npm-badge]][npm-link]
-![size-badge]
+[![NPM][npm-badge]][npm-link]
+![Size][size-badge]
 [![docs-badge]][docs-link]
-[![code-badge]][code-link]
+[![code-badge]][link]
+
+The lowest level communication layer with Telegram Mini Apps.
+
+This package provides fundamental utilities and types for developing applications on the Telegram
+Mini Apps platform.
+
+While a developer can use this package alone, it's recommended to use a higher-level package
+like [@tma.js/sdk](https://docs.telegram-mini-apps.com/packages/tma-js-sdk).
+
+## Installation
+
+```bash
+pnpm i @tma.js/bridge
+# or
+npm i @tma.js/bridge
+# or
+yarn add @tma.js/bridge
+```
+
+## Usage
+
+Here’s a basic example of how to use this package. For more details, refer to the package complete
+[documentation](https://docs.telegram-mini-apps.com/packages/tma-js-bridge).
+
+```ts
+import { on, postEvent, applyPolyfills } from '@tma.js/bridge';
+
+// The package uses some polyfills, so let's use them.
+applyPolyfills();
 
-Package which provides utilities to simplify communication flow between
-frontend and Telegram native applications. It also solves some across-platform
-data difference problems to protect developers code and save their time.
+// Show the back button, wait for it to be clicked once,
+// then hide it.
+postEvent('web_app_setup_back_button', { is_visible: true });
 
-This library is a part of TypeScript packages ecosystem around Telegram Web
-Apps. You can learn more about this package in this
-[documentation][docs-link].
+const off = on('back_button_pressed', () => {
+  postEvent('web_app_setup_back_button', { is_visible: false });
+  off();
+});
+```

package/dist/dts/applyPolyfills.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Applies polyfills required for stable work of the package:
+ * - `Object.hasOwn` - used by `valibot`
+ */
+export declare function applyPolyfills(): void;

package/dist/dts/base64-url.d.ts

@@ -0,0 +1,24 @@
+import * as E from 'fp-ts/Either';
+export type DecodeBase64UrlError = DOMException;
+/**
+ * Decodes a base-64-url ASCII string.
+ * @param value - the value to decode.
+ * @see Learn more about base64url:
+ * https://herongyang.com/Encoding/Base64URL-Encoding-Algorithm.html
+ * @see Source:
+ * https://developer.mozilla.org/ru/docs/Glossary/Base64#solution_1_–_escaping_the_string_before_encoding_it
+ */
+export declare function decodeBase64UrlFp(value: string): E.Either<DecodeBase64UrlError, string>;
+/**
+ * @see decodeBase64UrlFp
+ */
+export declare const decodeBase64Url: (value: string) => DOMException;
+/**
+ * Creates a base-64-url encoded ASCII string from the passed value.
+ * @param value - the value to encode.
+ * @see Learn more about base64url:
+ * https://herongyang.com/Encoding/Base64URL-Encoding-Algorithm.html
+ * @see Source:
+ * https://developer.mozilla.org/ru/docs/Glossary/Base64#solution_1_–_escaping_the_string_before_encoding_it
+ */
+export declare function encodeBase64Url(value: string): string;

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

@@ -0,0 +1,10 @@
+/**
+ * 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>(value: T): value is T & {
+    TelegramWebviewProxy: {
+        postEvent: (...args: unknown[]) => unknown;
+    };
+};

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

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

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

@@ -0,0 +1,31 @@
+import { BetterPromise, BetterPromiseOptions, TimeoutError } from 'better-promises';
+import { RequestError } from '../utils/request.js';
+import * as TE from 'fp-ts/TaskEither';
+export type isTMAError = Exclude<RequestError, TimeoutError>;
+/**
+ * @see isTMAFp
+ */
+export declare function isTMA(): boolean;
+/**
+ * @see isTMAFp
+ */
+export declare function isTMA(type: 'complete', options?: BetterPromiseOptions): BetterPromise<boolean>;
+/**
+ * Returns true if the current environment is Telegram Mini Apps.
+ *
+ * It uses the `retrieveLaunchParams` function to determine if the environment
+ * contains launch parameters. In case it does, true will be returned.
+ *
+ * In case you need stricter checks, use async override of this function.
+ */
+export declare function isTMAFp(): boolean;
+/**
+ * Returns promise with true if the current environment is Telegram Mini Apps.
+ *
+ * First of all, it checks if the current environment contains traits specific
+ * to the Mini Apps environment. Then, it attempts to call a Mini Apps method
+ * and waits for a response to be received.
+ *
+ * In case you need less strict checks, use sync override of this function.
+ */
+export declare function isTMAFp(type: 'complete', options?: BetterPromiseOptions): TE.TaskEither<isTMAError, boolean>;

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

@@ -0,0 +1,57 @@
+import { LaunchParamsLike } from '@tma.js/transformers';
+import { MethodName, MethodParams } from '../methods/types/index.js';
+/**
+ * Mocks the environment and imitates Telegram Mini Apps behavior.
+ *
+ * We usually use this function in the following cases:
+ * 1. We are developing an application outside the Telegram environment and would like to imitate
+ * the Telegram client in order to re-create the same communication behavior.
+ * 2. We would like to intercept some Telegram Mini Apps methods' calls in order to enhance them
+ * or write a custom behavior. It is extremely useful in some Telegram clients improperly handling
+ * Mini Apps methods' calls and not even responding.
+ *
+ * Note that calling this function in Telegram web clients, the `postMessageImplementation` signal
+ * value will be updated with a new one, enhancing previously set signal value to allow wrapping
+ * the original `window.parent.postMessage` function. In other words, calling `mockTelegramEnv`
+ * function N times, you will effectively wrap previously set implementation N times, so be
+ * careful calling this function several times during a single lifecycle of the app. In case you
+ * would like to avoid such kind of behavior, use the `resetPostMessage` option.
+ */
+export declare function mockTelegramEnv({ launchParams, onEvent, resetPostMessage }?: {
+    /**
+     * Launch parameters to mock. They will be saved in the storage, so the SDK functions could
+     * retrieve them.
+     *
+     * Note that this value must have `tgWebAppData` presented in a raw format as long as you will
+     * need it when retrieving init data in this format. Otherwise, init data may be broken.
+     */
+    launchParams?: (Omit<LaunchParamsLike, 'tgWebAppData'> & {
+        tgWebAppData?: string | URLSearchParams;
+    }) | string | URLSearchParams;
+    /**
+     * Function that will be called if a Mini Apps method call was requested by the mini app.
+     *
+     * It receives a Mini Apps method name along with the passed payload.
+     *
+     * Note that using the `next` function, in non-web environments it uses the
+     * `window.TelegramWebviewProxy.postEvent` method.
+     *
+     * Talking about the web versions of Telegram, the value of `next` is a bit more complex - it
+     * will be equal to the value stored in the `postMessageImpl` signal set previously. By default,
+     * this value contains a function utilizing the `window.parent.postMessage` method.
+     * @param event - event information.
+     * @param next - function to call the original method used to call a Mini Apps method.
+     */
+    onEvent?: (event: {
+        [M in MethodName]: {
+            name: M;
+            params: MethodParams<M>;
+        };
+    }[MethodName] | [string, unknown], next: () => void) => void;
+    /**
+     * Removes all previously set enhancements of the `window.parent.postMessage` function set
+     * by other `mockTelegramEnv` calls.
+     * @default false
+     */
+    resetPostMessage?: boolean;
+}): void;

package/dist/dts/errors.d.ts

@@ -0,0 +1,27 @@
+declare const MethodUnsupportedError_base: import('error-kid').ErrorClass<[method: string, version: string]>;
+export declare class MethodUnsupportedError extends MethodUnsupportedError_base {
+}
+declare const MethodParameterUnsupportedError_base: import('error-kid').ErrorClass<[method: string, param: string, version: string]>;
+export declare class MethodParameterUnsupportedError extends MethodParameterUnsupportedError_base {
+}
+declare const LaunchParamsRetrieveError_base: import('error-kid').ErrorClassWithData<[{
+    source: string;
+    error: unknown;
+}[]], {
+    errors: {
+        source: string;
+        error: unknown;
+    }[];
+}>;
+export declare class LaunchParamsRetrieveError extends LaunchParamsRetrieveError_base {
+}
+declare const InvalidLaunchParamsError_base: import('error-kid').ErrorClass<[launchParams: string, cause: unknown]>;
+export declare class InvalidLaunchParamsError extends InvalidLaunchParamsError_base {
+}
+declare const UnknownEnvError_base: import('error-kid').ErrorClass<[]>;
+export declare class UnknownEnvError extends UnknownEnvError_base {
+}
+declare const InvokeCustomMethodFailedError_base: import('error-kid').ErrorClass<[error: string]>;
+export declare class InvokeCustomMethodFailedError extends InvokeCustomMethodFailedError_base {
+}
+export {};

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

@@ -0,0 +1,58 @@
+import { If, IsNever, IsUndefined, Or } from '@tma.js/toolkit';
+import { Handler } from 'mitt';
+export type WildcardHandler<E> = Handler<{
+    [K in keyof E]: {
+        name: K;
+        payload: If<Or<IsNever<E[K]>, IsUndefined<E[K]>>, never, E[K]>;
+    };
+}[keyof E]>;
+export interface OnFn<E> {
+    /**
+     * Adds a new listener for the specified event.
+     * @param type - event name.
+     * @param handler - event listener.
+     * @param once - should this listener be called only once.
+     * @returns Function to remove bound event listener.
+     */
+    <K extends keyof E>(type: K, handler: Handler<E[K]>, once?: boolean): VoidFunction;
+    /**
+     * Adds a listener to the wildcard event.
+     * @param type - event name.
+     * @param handler - event listener.
+     * @param once - should this listener be called only once.
+     * @returns Function to remove bound event listener.
+     */
+    (type: '*', handler: WildcardHandler<E>, once?: boolean): VoidFunction;
+}
+export interface OffFn<E> {
+    /**
+     * Removes a listener from the specified event.
+     * @param type - event to listen.
+     * @param handler - event listener to remove.
+     * @param once - had this listener to be called only once.
+     */
+    <K extends keyof E>(type: K, handler: Handler<E[K]>, once?: boolean): void;
+    /**
+     * Removes a listener from the wildcard event.
+     * @param type - event to stop listening.
+     * @param handler - event listener to remove.
+     * @param once - should this listener be called only once.
+     */
+    (type: '*', handler: WildcardHandler<E>, once?: boolean): void;
+}
+export interface EmitFn<E> {
+    <K extends keyof E>(type: K, event: E[K]): void;
+    <K extends keyof E>(type: undefined extends E[K] ? K : never): void;
+}
+/**
+ * Creates a new enhanced event emitter.
+ * @param onFirst - a function to call every time when the events map appeared to be empty during
+ * the event listener creation.
+ * @param onEmpty - a function to call every tume when the events map became empty.
+ */
+export declare function createEmitter<E extends object>(onFirst: VoidFunction, onEmpty: VoidFunction): {
+    on: OnFn<E>;
+    off: OffFn<E>;
+    emit: EmitFn<E>;
+    clear: VoidFunction;
+};

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

@@ -0,0 +1,33 @@
+import { EventPayload, EventWithoutPayload, EventWithPayload } from './types/index.js';
+/**
+ * Emits an event without payload sent from the Telegram native application like it was sent in
+ * a default web environment between two iframes.
+ *
+ * It dispatches a new MessageEvent and expects it to be handled via
+ * the `window.addEventListener('message', ...)` call, as a developer would do it to handle
+ * messages sent from the parent iframe.
+ * @param eventType - event name.
+ */
+export declare function emitEvent<E extends EventWithoutPayload>(eventType: E): void;
+/**
+ * Emits an event with payload sent from the Telegram native application like it was sent in
+ * a default web environment between two iframes.
+ *
+ * It dispatches a new MessageEvent and expects it to be handled via
+ * the `window.addEventListener('message', ...)` call, as a developer would do it to handle
+ * messages sent from the parent iframe.
+ * @param eventType - event name.
+ * @param eventData - event payload.
+ */
+export declare function emitEvent<E extends EventWithPayload>(eventType: E, eventData: EventPayload<E>): void;
+/**
+ * Emits an unknown event sent from the Telegram native application like it was sent in a default
+ * web environment between two iframes.
+ *
+ * It dispatches a new MessageEvent and expects it to be handled via
+ * the `window.addEventListener('message', ...)` call, as a developer would do it to handle
+ * messages sent from the parent iframe.
+ * @param eventType - event name.
+ * @param eventData - event payload.
+ */
+export declare function emitEvent<E extends string>(eventType: E, eventData: E extends EventWithoutPayload ? never : E extends EventWithPayload ? EventPayload<E> : unknown): void;

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

@@ -1,11 +1,2 @@
-import type { EventEmitter } from './events.js';
-/**
- * Returns event emitter which could be safely used, to process events from
- * Telegram native application.
- */
-export declare function createEmitter(): EventEmitter;
-/**
- * Returns singleton instance of bridge EventEmitter. Also, defines
- * Telegram event handlers.
- */
-export declare function singletonEmitter(): EventEmitter;
+import { Events } from './types/index.js';
+export declare const on: import('./createEmitter.js').OnFn<Events>, off: import('./createEmitter.js').OffFn<Events>, emit: import('./createEmitter.js').EmitFn<Events>, offAll: VoidFunction;