@tma.js/bridge 2.3.2 → 4.0.0-rc.0

package/dist/dts/logger.d.ts

@@ -0,0 +1,29 @@
+export interface Logger {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Enables or disables debug mode. In debug mode, the package logs every outgoing method call
+ * and every incoming event.
+ * @param value - should the debug mode be enabled.
+ */
+export declare function setDebug(value: boolean): void;
+/**
+ * @returns True if the debug mode is enabled.
+ */
+export declare function isDebug(): boolean;
+/**
+ * Replaces the package logger. Pass nothing to restore the default one.
+ * @param value - logger to use.
+ */
+export declare function setLogger(value?: Logger): void;
+/**
+ * @returns The current package logger.
+ */
+export declare function getLogger(): Logger;
+/**
+ * Logs a message only in debug mode.
+ * @param args - values to log.
+ */
+export declare function debugLog(...args: unknown[]): void;

package/dist/dts/mockTelegramEnv.d.ts

@@ -0,0 +1,55 @@
+import { LaunchParams } from './launch-params.js';
+import { MethodName, MethodParams } from './types/index.js';
+/**
+ * Mini Apps method call intercepted by `mockTelegramEnv`.
+ */
+export type MockedMethodCall = {
+    [M in MethodName]: {
+        name: M;
+        params: [MethodParams<M>] extends [never] ? undefined : MethodParams<M>;
+    };
+}[MethodName] | {
+    name: string & {};
+    params: unknown;
+};
+export interface MockTelegramEnvOptions {
+    /**
+     * Launch parameters to mock. They are saved in the session storage, so the launch parameters
+     * retrieving functions return them.
+     */
+    launchParams?: string | URLSearchParams | LaunchParams;
+    /**
+     * Function called whenever the mini app calls a Mini Apps method. Use `emitEvent` to respond
+     * to the call as the Telegram client would do.
+     * @param call - called method name and its parameters.
+     * @param next - function passing the call to the original transport, if there is one.
+     */
+    onMethod?: (call: MockedMethodCall, next: VoidFunction) => void;
+}
+/**
+ * Mocks the environment to imitate the Telegram client.
+ *
+ * Use it to develop the app outside Telegram, or to intercept method calls in Telegram, for
+ * example, to fix a client not responding to some method.
+ *
+ * Outside iframes, calls are intercepted by defining `window.TelegramWebviewProxy`, so method
+ * calls performed by other libraries (e.g. the official SDK) are intercepted too. In Telegram Web
+ * (iframe), only calls performed by this package are intercepted.
+ * @param options - mock options.
+ * @returns Function reverting the mocked method calls handling. Launch parameters stay saved.
+ * When mocking several times, revert in the reverse order.
+ * @example
+ * mockTelegramEnv({
+ *   launchParams: {
+ *     tgWebAppPlatform: 'tdesktop',
+ *     tgWebAppVersion: '9.0',
+ *     tgWebAppThemeParams: { bg_color: '#ffffff' },
+ *   },
+ *   onMethod({ name }) {
+ *     if (name === 'web_app_request_theme') {
+ *       emitEvent('theme_changed', { theme_params: { bg_color: '#ffffff' } });
+ *     }
+ *   },
+ * });
+ */
+export declare function mockTelegramEnv({ launchParams, onMethod }?: MockTelegramEnvOptions): VoidFunction;

package/dist/dts/post-event.d.ts

@@ -0,0 +1,40 @@
+import { MethodArgs, MethodName } from './types/index.js';
+/**
+ * Sets the target origin used to post messages to the parent window in Telegram Web clients.
+ *
+ * You don't need to change it until you know what you are doing.
+ * @param origin - target origin. Default: `https://web.telegram.org`.
+ */
+export declare function setTargetOrigin(origin: string): void;
+/**
+ * @returns The target origin used to post messages to the parent window.
+ */
+export declare function getTargetOrigin(): string;
+export type PostMessageFn = (message: string, targetOrigin: string) => void;
+/**
+ * Replaces the function posting messages to the parent window in Telegram Web clients.
+ * @param fn - function to use.
+ * @returns Function restoring the previous implementation.
+ * @internal
+ */
+export declare function setPostMessage(fn: PostMessageFn): VoidFunction;
+/**
+ * @returns The current function posting messages to the parent window.
+ * @internal
+ */
+export declare function getPostMessage(): PostMessageFn;
+export type PostEventFn = <M extends MethodName>(method: M, ...args: MethodArgs<M>) => void;
+/**
+ * Calls a Mini Apps method.
+ *
+ * Depending on the environment, the method is sent:
+ * - via `window.parent.postMessage` in Telegram Web clients;
+ * - via `window.TelegramWebviewProxy.postEvent` in Telegram for iOS, macOS, Android and Desktop;
+ * - via `window.external.notify` in Telegram for Windows Phone.
+ *
+ * @param method - method name.
+ * @param args - method parameters.
+ * @throws {UnknownEnvError} The current environment is not a Telegram Mini App.
+ * @see https://docs.telegram-mini-apps.com/platform/methods
+ */
+export declare const postEvent: PostEventFn;

package/dist/dts/request.d.ts

@@ -0,0 +1,98 @@
+import { TimeoutError } from './errors.js';
+import { PostEventFn } from './post-event.js';
+import { Result } from './result.js';
+import { EventListenerPayload, EventName, MethodName, MethodNameWithRequiredParams, MethodParams } from './types/index.js';
+type AnyEventName = EventName | EventName[];
+/**
+ * Value captured by the `request` function. For a list of tracked events, it also contains
+ * the event name.
+ */
+export type RequestResult<E extends AnyEventName> = E extends (infer U extends EventName)[] ? {
+    [K in U]: {
+        event: K;
+        payload: EventListenerPayload<K>;
+    };
+}[U] : E extends EventName ? EventListenerPayload<E> : never;
+export interface RequestOptions<E extends AnyEventName> {
+    /**
+     * Function returning true if the received event should be captured. If omitted, the first
+     * tracked event is captured.
+     */
+    capture?: (value: RequestResult<E>) => boolean;
+    /**
+     * Time in milliseconds to wait for the event. When reached, the request fails with
+     * `TimeoutError`.
+     */
+    timeout?: number;
+    /**
+     * Signal to abort the request. When aborted, the request is rejected with `signal.reason`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Custom function to call the method.
+     */
+    postEvent?: PostEventFn;
+}
+/**
+ * Options of the `request` function. The `params` option is required only if the method
+ * requires parameters.
+ */
+export type RequestFnOptions<M extends MethodName, E extends AnyEventName> = RequestOptions<E> & ([MethodParams<M>] extends [never] ? {
+    params?: never;
+} : M extends MethodNameWithRequiredParams ? {
+    params: MethodParams<M>;
+} : {
+    params?: MethodParams<M>;
+});
+export type RequestFnArgs<M extends MethodName, E extends AnyEventName> = M extends MethodNameWithRequiredParams ? [options: RequestFnOptions<M, E>] : [options?: RequestFnOptions<M, E>];
+/**
+ * Calls a Mini Apps method and waits for the specified event (or one of the events) to occur.
+ *
+ * Listeners are added before the method is called, so events emitted synchronously are
+ * captured too.
+ *
+ * The request is rejected with `signal.reason` if it was aborted, and with the error thrown by
+ * `postEvent` or the `capture` option.
+ * @param method - method name.
+ * @param events - event or events to wait for.
+ * @param args - additional options.
+ * @returns For a single event, its payload. For a list of events, an object with the captured
+ * event name and payload. If the timeout was reached, `TimeoutError`.
+ * @example
+ * const result = await safeRequest('web_app_request_phone', 'phone_requested', { timeout: 5000 });
+ * if (!result.ok) {
+ *   console.log('The user didn\'t respond in time');
+ * }
+ */
+export declare function safeRequest<M extends MethodName, E extends AnyEventName>(method: M, events: E, ...args: RequestFnArgs<M, E>): Promise<Result<TimeoutError, RequestResult<E>>>;
+/**
+ * Calls a Mini Apps method and waits for the specified event (or one of the events) to occur.
+ *
+ * Throwing version of `safeRequest`.
+ * @param method - method name.
+ * @param events - event or events to wait for.
+ * @param args - additional options.
+ * @returns For a single event, its payload. For a list of events, an object with the captured
+ * event name and payload.
+ * @throws {TimeoutError} The timeout was reached.
+ * @example
+ * const { button_id } = await request('web_app_open_popup', 'popup_closed', {
+ *   params: { title: 'Hello', message: 'World', buttons: [{ id: 'ok', type: 'ok' }] },
+ * });
+ * @example
+ * const result = await request('web_app_request_phone', ['phone_requested'], { timeout: 5000 });
+ */
+export declare function request<M extends MethodName, E extends AnyEventName>(method: M, events: E, ...args: RequestFnArgs<M, E>): Promise<RequestResult<E>>;
+/**
+ * @returns A new unique request identifier. Use it for methods requiring the `req_id` parameter.
+ */
+export declare function createRequestId(): string;
+/**
+ * @returns Function to use in the `request` function `capture` option to capture the event
+ * with the specified request identifier.
+ * @param reqId - request identifier.
+ */
+export declare function captureSameReq(reqId: string): (payload: {
+    req_id: string;
+}) => boolean;
+export {};

package/dist/dts/result.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Result of an operation which can fail with one of the known errors. Unlike a thrown error,
+ * the error type here is checked by the compiler.
+ */
+export type Result<E, T> = {
+    ok: false;
+    error: E;
+} | {
+    ok: true;
+    data: T;
+};
+/**
+ * @returns A successful result.
+ * @param data - result data.
+ */
+export declare function ok<T>(data: T): {
+    ok: true;
+    data: T;
+};
+/**
+ * @returns A failed result.
+ * @param error - result error.
+ */
+export declare function err<E>(error: E): {
+    ok: false;
+    error: E;
+};
+/**
+ * @returns Result data.
+ * @param result - result to unwrap.
+ * @throws The result error, if the result is failed.
+ */
+export declare function unwrap<E extends Error, T>(result: Result<E, T>): T;
+/**
+ * Creates a throwing version of a function returning a result. The created function accepts
+ * the same arguments and returns the result data, or throws the result error.
+ *
+ * Generic functions lose their type parameters when wrapped, so write their throwing versions
+ * manually using `unwrap`.
+ * @param fn - function returning a result, or a promise of it.
+ * @example
+ * export const createStartParam = throwing(safeCreateStartParam);
+ */
+export declare function throwing<A extends unknown[], E extends Error, T>(fn: (...args: A) => Promise<Result<E, T>>): (...args: A) => Promise<T>;
+export declare function throwing<A extends unknown[], E extends Error, T>(fn: (...args: A) => Result<E, T>): (...args: A) => T;

package/dist/dts/start-param.d.ts

@@ -1,52 +1,46 @@
-import { either as E, json as J } from 'fp-ts';
-import { DecodeBase64UrlError } from './base64-url.js';
+import { StartParamTooLongError } from './errors.js';
+import { Result } from './result.js';
 /**
- * Creates a safe start parameter value. If the value is not a string, the
- * function applies JSON.stringify to it, so make sure you are not passing an
- * object with circular references.
- *
- * @param value - value to create start parameter from.
- * @see Learn more about start parameter:
- * https://docs.telegram-mini-apps.com/platform/start-parameter
- */
-export declare function createStartParamFp(value: unknown): E.Either<Error, string>;
-/**
- * @see createStartParamFp
- */
-export declare const createStartParam: ((value: unknown) => string) & {};
-/**
- * @see decodeStartParamFp
- */
-export declare function decodeStartParam<T>(value: string, parse: (value: string) => T): T;
-/**
- * @see decodeStartParamFp
+ * Encodes a string to base64url.
+ * @param value - value to encode.
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-5
  */
-export declare function decodeStartParam(value: string, as: 'json'): J.Json;
+export declare function encodeBase64Url(value: string): string;
 /**
- * @see decodeStartParamFp
+ * Decodes a base64url string.
+ * @param value - value to decode.
+ * @throws {DOMException} The value is not a valid base64url string.
+ * @throws {TypeError} The decoded value is not a valid UTF-8 string.
  */
-export declare function decodeStartParam(value: string): string;
+export declare function decodeBase64Url(value: string): string;
 /**
- * Decodes a start parameter using a custom parser.
- * @param value - a start parameter value.
- * @param parse - a custom value parser.
+ * @returns True if the value can be used to create a start parameter.
+ * @param value - value to check.
  */
-export declare function decodeStartParamFp<L, R>(value: string, parse: (value: string) => E.Either<L, R>): E.Either<L | DecodeBase64UrlError, R>;
+export declare function isSafeToCreateStartParam(value: string): boolean;
 /**
- * Decodes a start parameter assuming that the result is a JSON value.
- * @param value - a start parameter value.
- * @param as - result kind.
+ * Creates a start parameter from the value. Non-string values are converted to JSON.
+ * @param value - value to encode.
+ * @returns Start parameter, or `StartParamTooLongError` if the encoded value exceeds 512
+ * characters.
+ * @see https://docs.telegram-mini-apps.com/platform/start-parameter
  */
-export declare function decodeStartParamFp(value: string, as: 'json'): E.Either<SyntaxError | DecodeBase64UrlError, J.Json>;
+export declare function safeCreateStartParam(value: unknown): Result<StartParamTooLongError, string>;
 /**
- * Decodes a start parameter and returns its decoded representation.
- * @param value - a value to decode.
+ * Creates a start parameter from the value. Non-string values are converted to JSON.
+ *
+ * Throwing version of `safeCreateStartParam`.
+ * @param value - value to encode.
+ * @throws {StartParamTooLongError} The encoded value exceeds 512 characters.
+ * @see https://docs.telegram-mini-apps.com/platform/start-parameter
  */
-export declare function decodeStartParamFp(value: string): E.Either<DecodeBase64UrlError, string>;
+export declare const createStartParam: (value: unknown) => string;
 /**
- * @returns True if the passed value is safe to be used to create a start parameter value from it.
- * If true is returned, the value can be safely passed to the `createStartParam` function.
- * @param value - value to check.
- * @see createStartParam
+ * Decodes a start parameter created with `createStartParam`.
+ * @param value - start parameter.
+ * @param parse - `json` to parse the decoded value as JSON, or a custom parser.
+ * @throws {DOMException} The value is not a valid base64url string.
  */
-export declare function isSafeToCreateStartParam(value: string): boolean;
+export declare function decodeStartParam(value: string): string;
+export declare function decodeStartParam(value: string, parse: 'json'): unknown;
+export declare function decodeStartParam<T>(value: string, parse: (value: string) => T): T;

package/dist/dts/theme-params.d.ts

@@ -0,0 +1,10 @@
+import { GenericSchema } from 'valibot';
+import { ThemeParams } from './types/index.js';
+/**
+ * Schema of a raw theme parameters object.
+ */
+export declare const ThemeParamsSchema: GenericSchema<unknown, ThemeParams>;
+/**
+ * Schema of theme parameters in the JSON format.
+ */
+export declare const ThemeParamsJsonSchema: GenericSchema<unknown, ThemeParams>;

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

@@ -0,0 +1,61 @@
+/**
+ * Color in the `#RRGGBB` format.
+ */
+export type RGB = `#${string}`;
+/**
+ * Telegram Mini Apps platform version, e.g. `6.10` or `9.1`.
+ */
+export type Version = string;
+/**
+ * Telegram application platform identifier.
+ */
+export type Platform = 'android' | 'android_x' | 'ios' | 'macos' | 'tdesktop' | 'weba' | 'webk' | 'unigram' | 'unknown' | string;
+/**
+ * Theme parameters. Keys are snake-cased color names, values are colors in the `#RRGGBB` format.
+ * @see https://docs.telegram-mini-apps.com/platform/theming
+ */
+export interface ThemeParams {
+    /**
+     * @since v6.10
+     */
+    accent_text_color?: RGB;
+    bg_color?: RGB;
+    /**
+     * @since v7.10
+     */
+    bottom_bar_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 v7.6
+     */
+    section_separator_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    subtitle_text_color?: RGB;
+    text_color?: RGB;
+    /**
+     * Keys unknown at the moment of the package release.
+     */
+    [key: string]: RGB | undefined;
+}

package/dist/dts/{events/types → types}/events.d.ts

@@ -1,6 +1,20 @@
-import { If, IsNever, Maybe } from '@tma.js/toolkit';
-import { RGB } from '@tma.js/types';
-import { BiometryAuthRequestStatus, BiometryTokenUpdateStatus, BiometryType, EmojiStatusAccessRequestedStatus, EmojiStatusFailedError, FullScreenErrorStatus, HomeScreenStatus, InvoiceStatus, PhoneRequestedStatus, SafeAreaInsets, WriteAccessRequestedStatus } from './misc.js';
+import { ThemeParams } from './common.js';
+export type InvoiceStatus = 'paid' | 'failed' | 'pending' | 'cancelled' | string;
+export type PhoneRequestedStatus = 'sent' | 'cancelled' | string;
+export type EmojiStatusAccessRequestedStatus = 'allowed' | string;
+export type EmojiStatusFailedError = 'SUGGESTED_EMOJI_INVALID' | 'USER_DECLINED' | string;
+export type WriteAccessRequestedStatus = 'allowed' | string;
+export type BiometryType = 'finger' | 'face' | string;
+export type BiometryTokenUpdateStatus = 'updated' | 'removed' | 'failed' | string;
+export type BiometryAuthRequestStatus = 'failed' | 'authorized' | string;
+export type FullScreenErrorStatus = 'ALREADY_FULLSCREEN' | 'UNSUPPORTED' | string;
+export interface SafeAreaInsets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+export type HomeScreenStatus = 'unsupported' | 'unknown' | 'added' | 'missed' | string;
 type WithReqId<T = {}> = T & {
     /**
      * Unique request identifier.
@@ -187,7 +201,7 @@ export interface Events {
          * A boolean that indicates whether the device is providing orientation data in
          * absolute values.
          */
-        absolute?: Maybe<boolean>;
+        absolute?: boolean | null;
         /**
          * The rotation around the Z-axis, measured in radians.
          */
@@ -289,7 +303,7 @@ export interface Events {
      * @see https://docs.telegram-mini-apps.com/platform/events#file-download-requested
      */
     file_download_requested: {
-        status?: Maybe<'downloading' | string>;
+        status?: 'downloading' | string | null;
     };
     /**
      * App entered or exited fullscreen mode.
@@ -409,8 +423,8 @@ export interface Events {
         available: false;
     } | {
         available: true;
-        access_requested?: Maybe<boolean>;
-        access_granted?: Maybe<boolean>;
+        access_requested?: boolean | null;
+        access_granted?: boolean | null;
     };
     /**
      * Location-related functionality availability status was retrieved.
@@ -432,31 +446,31 @@ export interface Events {
         /**
        * Altitude above sea level in meters.
        */
-        altitude?: Maybe<number>;
+        altitude?: number | null;
         /**
        * The direction the device is moving in degrees.
        */
-        course?: Maybe<number>;
+        course?: number | null;
         /**
        * The speed of the device in m/s.
        */
-        speed?: Maybe<number>;
+        speed?: number | null;
         /**
        * Accuracy of the latitude and longitude values in meters.
        */
-        horizontal_accuracy?: Maybe<number>;
+        horizontal_accuracy?: number | null;
         /**
        * Accuracy of the altitude value in meters.
        */
-        vertical_accuracy?: Maybe<number>;
+        vertical_accuracy?: number | null;
         /**
        * Accuracy of the course value in degrees.
        */
-        course_accuracy?: Maybe<number>;
+        course_accuracy?: number | null;
         /**
        * Accuracy of the speed value in m/s.
        */
-        speed_accuracy?: Maybe<number>;
+        speed_accuracy?: number | null;
     };
     /**
      * A user clicked the Main Button.
@@ -519,6 +533,23 @@ export interface Events {
      * @see https://docs.telegram-mini-apps.com/platform/events#reload-iframe
      */
     reload_iframe: never;
+    /**
+     * Failed to share a chat requested via the `web_app_request_chat` method.
+     * @since v9.6
+     * @see https://docs.telegram-mini-apps.com/platform/events#requested-chat-failed
+     */
+    requested_chat_failed: {
+        /**
+         * Occurred error.
+         */
+        error: string;
+    };
+    /**
+     * A chat requested via the `web_app_request_chat` method was shared.
+     * @since v9.6
+     * @see https://docs.telegram-mini-apps.com/platform/events#requested-chat-sent
+     */
+    requested_chat_sent: never;
     /**
      * Occurs whenever the device's safe area insets change
      * (e.g., due to orientation change or screen adjustments).
@@ -613,44 +644,7 @@ export interface Events {
          * corresponding color in
          * `#RRGGBB` format.
          */
-        theme_params: {
-            /**
-             * @since v6.10
-             */
-            accent_text_color?: RGB;
-            /**
-             * @since 7.10
-             */
-            bottom_bar_bg_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;
-        };
+        theme_params: ThemeParams;
     };
     /**
      * Occurs whenever the viewport has been changed. For example, when the user
@@ -712,10 +706,35 @@ export type EventName = keyof Events;
  * Payload of the specified Mini Apps event.
  */
 export type EventPayload<E extends EventName> = Events[E];
-export type EventWithoutPayload = {
-    [E in EventName]: If<IsNever<EventPayload<E>>, E, never>;
+/**
+ * Events having no payload.
+ */
+export type EventNameWithoutPayload = {
+    [E in EventName]: [EventPayload<E>] extends [never] ? E : never;
 }[EventName];
-export type EventWithPayload = {
-    [E in EventName]: undefined extends EventPayload<E> ? never : E;
+/**
+ * Events having payload.
+ */
+export type EventNameWithPayload = Exclude<EventName, EventNameWithoutPayload>;
+/**
+ * Value passed to event listeners. Events without payload produce `undefined`.
+ */
+export type EventListenerPayload<E extends EventName> = [EventPayload<E>] extends [never] ? undefined : EventPayload<E>;
+/**
+ * Listener of the specified Mini Apps event.
+ */
+export type EventListener<E extends EventName> = (payload: EventListenerPayload<E>) => void;
+/**
+ * Any Mini Apps event with its payload.
+ */
+export type AnyEvent = {
+    [E in EventName]: {
+        name: E;
+        payload: EventListenerPayload<E>;
+    };
 }[EventName];
+/**
+ * Listener of all Mini Apps events.
+ */
+export type AnyEventListener = (event: AnyEvent) => void;
 export {};

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

@@ -0,0 +1,5 @@
+export type * from './common.js';
+export type * from './events.js';
+export type * from './haptic-feedback.js';
+export type * from './methods.js';
+export type * from './popup.js';