@vbotma/bridge 2.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @vbotma/bridge
+
+[code-badge]: https://img.shields.io/badge/source-black?logo=github
+
+[docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
+
+[link]: https://github.com/Telegram-Mini-Apps/tma.js/tree/master/tma.js/bridge
+
+[docs-link]: https://docs.vbot-mini-apps.com/packages/tma-js-bridge
+
+[npm-link]: https://npmjs.com/package/@vbotma/bridge
+
+[npm-badge]: https://img.shields.io/npm/v/@vbotma/bridge?logo=npm
+
+[size-badge]: https://img.shields.io/bundlephobia/minzip/@vbotma/bridge
+
+[![NPM][npm-badge]][npm-link]
+![Size][size-badge]
+[![docs-badge]][docs-link]
+[![code-badge]][link]
+
+The lowest level communication layer with VBot 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 [@vbotma/sdk](https://docs.vbot-mini-apps.com/packages/tma-js-sdk).
+
+## Installation
+
+```bash
+pnpm i @vbotma/bridge
+# or
+npm i @vbotma/bridge
+# or
+yarn add @vbotma/bridge
+```
+
+## Usage
+
+Here’s a basic example of how to use this package. For more details, refer to the package complete
+[documentation](https://docs.vbot-mini-apps.com/packages/tma-js-bridge).
+
+```ts
+import { on, postEvent, applyPolyfills } from '@vbotma/bridge';
+
+// The package uses some polyfills, so let's use them.
+applyPolyfills();
+
+// Show the back button, wait for it to be clicked once,
+// then hide it.
+postEvent('web_app_setup_back_button', { is_visible: true });
+
+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 { either as E } from 'fp-ts';
+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) => string) & {};
+/**
+ * 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 `VBotWebviewProxy.postEvent` property and
+ * `postEvent` is a function.
+ * @param value - value to check.
+ */
+export declare function hasWebviewProxy<T>(value: T): value is T & {
+    VBotWebviewProxy: {
+        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/isVBMA.d.ts

@@ -0,0 +1,31 @@
+import { BetterPromise, BetterPromiseOptions, TimeoutError } from 'better-promises';
+import { taskEither as TE } from 'fp-ts';
+import { Request2Error } from '../utils/request2.js';
+export type isVBMAError = Exclude<Request2Error, TimeoutError>;
+/**
+ * @see isVBMAFp
+ */
+export declare function isVBMA(): boolean;
+/**
+ * @see isVBMAFp
+ */
+export declare function isVBMA(type: 'complete', options?: BetterPromiseOptions): BetterPromise<boolean>;
+/**
+ * Returns true if the current environment is VBot 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 isVBMAFp(): boolean;
+/**
+ * Returns promise with true if the current environment is VBot 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 isVBMAFp(type: 'complete', options?: BetterPromiseOptions): TE.TaskEither<isVBMAError, boolean>;

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

@@ -0,0 +1,60 @@
+import { LaunchParamsLike } from '@vbotma/transformers';
+import { MethodName, MethodParams } from '../methods/types/index.js';
+/**
+ * Mocks the environment and imitates VBot Mini Apps behavior.
+ *
+ * We usually use this function in the following cases:
+ * 1. We are developing an application outside the VBot environment and would like to imitate
+ * the VBot client in order to re-create the same communication behavior.
+ * 2. We would like to intercept some VBot Mini Apps methods' calls in order to enhance them
+ * or write a custom behavior. It is extremely useful in some VBot 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 `mockVBotEnv`
+ * 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 mockVBotEnv({ 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 `vbWebAppData` 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, 'vbWebAppData'> & {
+        vbWebAppData?: 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.VBotWebviewProxy.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] | {
+        name: string;
+        params: unknown;
+    }, next: () => void) => void;
+    /**
+     * Removes all previously set enhancements of the `window.parent.postMessage` function set
+     * by other `mockVBotEnv` 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 /* @__PURE__ */ MethodUnsupportedError_base {
+}
+declare const MethodParameterUnsupportedError_base: import('error-kid').ErrorClass<[method: string, param: string, version: string]>;
+export declare class MethodParameterUnsupportedError extends /* @__PURE__ */ MethodParameterUnsupportedError_base {
+}
+declare const LaunchParamsRetrieveError_base: import('error-kid').ErrorClassWithData<[{
+    source: string;
+    error: unknown;
+}[]], {
+    errors: {
+        source: string;
+        error: unknown;
+    }[];
+}>;
+export declare class LaunchParamsRetrieveError extends /* @__PURE__ */ LaunchParamsRetrieveError_base {
+}
+declare const InvalidLaunchParamsError_base: import('error-kid').ErrorClass<[launchParams: string, cause: unknown]>;
+export declare class InvalidLaunchParamsError extends /* @__PURE__ */ InvalidLaunchParamsError_base {
+}
+declare const UnknownEnvError_base: import('error-kid').ErrorClass<[]>;
+export declare class UnknownEnvError extends /* @__PURE__ */ UnknownEnvError_base {
+}
+declare const InvokeCustomMethodFailedError_base: import('error-kid').ErrorClass<[error: string]>;
+export declare class InvokeCustomMethodFailedError extends /* @__PURE__ */ InvokeCustomMethodFailedError_base {
+}
+export {};

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

@@ -0,0 +1,58 @@
+import { If, IsNever, IsUndefined, Or } from '@vbotma/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

@@ -0,0 +1,2 @@
+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;