@tma.js/bridge 1.4.1 → 2.0.1

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

@@ -0,0 +1,3 @@
+export type * from './events.js';
+export type * from './listening.js';
+export type * from './misc.js';

package/dist/dts/events/types/listening.d.ts

@@ -0,0 +1,5 @@
+import { Handler } from 'mitt';
+import { WildcardHandler } from '../createEmitter.js';
+import { EventName, EventPayload, Events } from './index.js';
+export type EventListener<E extends EventName> = Handler<EventPayload<E>>;
+export type SubscribeListener = WildcardHandler<Events>;

package/dist/dts/events/types/misc.d.ts

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

package/dist/dts/globals.d.ts

@@ -1,22 +1,53 @@
-import { Logger } from '@tma.js/logger';
-export declare const logger: Logger;
+import { Logger } from '@tma.js/toolkit';
 /**
- * Sets new debug mode. Enabling debug mode leads to printing
- * additional messages in console, related to the processes
- * inside the package.
- * @param value - should debug mode be enabled.
+ * The current debug mode state.
+ *
+ * To update the value, use the `setDebug` function.
+ * @see setDebug
+ */
+export declare const debug: import('@tma.js/signals').Computed<boolean>;
+/**
+ * Sets the package debug mode.
+ *
+ * Enabling debug mode leads to printing additional messages in the console related to the
+ * processes inside the package.
+ * @param value - enable debug mode.
  */
 export declare function setDebug(value: boolean): void;
 /**
- * Sets new global targetOrigin, used by `postEvent` method.
- * Default value is "https://web.telegram.org". You don't need to
- * use this method until you know what you are doing.
+ * The current target origin used by the `postEvent` method.
+ *
+ * You don't need to override this value until you know what you are doing.
+ * To update the value, use the `setTargetOrigin` function.
+ * @default 'https://web.telegram.org'
+ * @see setTargetOrigin
+ */
+export declare const targetOrigin: import('@tma.js/signals').Computed<string>;
+/**
+ * Sets a new target origin that is being used when calling the `postEvent` function in Telegram
+ * web versions.
+ *
+ * You don't need to override this value until you know what you are doing.
+ * @param origin - allowed target origin value.
+ * @see _targetOrigin
+ */
+export declare function setTargetOrigin(origin: string): void;
+/**
+ * Signal containing a custom implementation of the method to post a message to the parent
+ * window. We usually use it to send a message in web versions of Telegram.
  *
- * This method could be used for test purposes.
- * @param value - new target origin.
+ * @default A function behaving like the `window.parent.postMessage` method.
+ */
+export declare const postMessageImpl: import('@tma.js/signals').Signal<{
+    (message: any, targetOrigin: string, transfer?: Transferable[]): void;
+    (message: any, options?: WindowPostMessageOptions): void;
+}>;
+/**
+ * The package logger. You can override this value in order to use your own implementation.
  */
-export declare function setTargetOrigin(value: string): void;
+export declare const logger: import('@tma.js/signals').Signal<Logger>;
 /**
- * Returns current global target origin.
+ * Resets the package global values. Normally, you don't use this function in your application.
+ * We are using it only for test purposes.
  */
-export declare function targetOrigin(): string;
+export declare function resetGlobals(): void;

package/dist/dts/index.d.ts

@@ -1,7 +1,24 @@
-export * from './errors/index.js';
-export * from './events/index.js';
-export * from './methods/index.js';
-export * from './env.js';
-export { setDebug, setTargetOrigin } from './globals.js';
-export * from './request.js';
-export * from './supports.js';
+export { hasWebviewProxy } from './env/hasWebviewProxy.js';
+export { isIframe } from './env/isIframe.js';
+export { isTMA, isTMAFp, type isTMAError } from './env/isTMA.js';
+export { mockTelegramEnv } from './env/mockTelegramEnv.js';
+export { emitEvent } from './events/emitEvent.js';
+export { off, offAll, on } from './events/emitter.js';
+export type { EventListener, SubscribeListener, Events, WriteAccessRequestedStatus, EmojiStatusAccessRequestedStatus, BiometryAuthRequestStatus, BiometryTokenUpdateStatus, BiometryType, EmojiStatusFailedError, EventName, EventPayload, EventWithoutPayload, EventWithPayload, PhoneRequestedStatus, FullScreenErrorStatus, HomeScreenStatus, InvoiceStatus, SafeAreaInsets, } from './events/types/index.js';
+export { captureSameReq } from './methods/captureSameReq.js';
+export { createPostEvent, type CreatePostEventMode, type OnUnsupportedFn, } from './methods/createPostEvent.js';
+export { postEvent, postEventFp, type PostEventFn, type PostEventFpFn, type PostEventError, } from './methods/postEvent.js';
+export { postMessage, type PostMessage } from './methods/postMessage.js';
+export { supports } from './methods/supports.js';
+export type { AnyHapticFeedbackParams, AnyInvokeCustomMethodParams, CreateMethodParams, CustomMethodName, ImpactHapticFeedbackParams, ImpactHapticFeedbackStyle, CustomMethodsParams, CustomMethodParams, MethodName, MethodVersionedParams, NotificationHapticFeedbackParams, NotificationHapticFeedbackType, Methods, SelectionHapticFeedbackParams, MethodNameWithOptionalParams, MethodNameWithoutParams, MethodNameWithRequiredParams, MethodNameWithVersionedParams, MethodParams, PopupParams, BackgroundColor, BottomBarColor, HeaderColorKey, PopupButton, OpenLinkBrowser, SecondaryButtonPosition, SwitchInlineQueryChatType, } from './methods/types/index.js';
+export { compareVersions } from './utils/compareVersions.js';
+export { invokeCustomMethod, invokeCustomMethodFp, type InvokeCustomMethodFn, type InvokeCustomMethodOptions, type InvokeCustomMethodFpFn, type InvokeCustomMethodError, type InvokeCustomMethodFpOptions, } from './utils/invokeCustomMethod.js';
+export { request, requestFp, type RequestCaptureEventFn, type RequestCaptureEventsFn, type RequestCaptureFn, type RequestCaptureFnEventsPayload, type RequestFn, type RequestOptions, type RequestResult, type RequestError, type RequestFpOptions, type RequestFpFn, } from './utils/request.js';
+export { applyPolyfills } from './applyPolyfills.js';
+export { decodeBase64Url, encodeBase64Url, decodeBase64UrlFp, type DecodeBase64UrlError, } from './base64-url.js';
+export { LaunchParamsRetrieveError, InvalidLaunchParamsError, InvokeCustomMethodFailedError, MethodParameterUnsupportedError, MethodUnsupportedError, UnknownEnvError, } from './errors.js';
+export { setDebug, debug, resetGlobals, postMessageImpl, logger, setTargetOrigin, targetOrigin, } from './globals.js';
+export { retrieveLaunchParams, retrieveRawInitData, retrieveRawInitDataFp, retrieveRawLaunchParams, retrieveRawLaunchParamsFp, retrieveLaunchParamsFp, type RetrieveLaunchParamsError, type RetrieveLaunchParamsResult, type RetrieveRawInitDataError, type RetrieveRawLaunchParamsError, } from './launch-params.js';
+export { createStartParam, createStartParamFp, decodeStartParam, decodeStartParamFp, isSafeToCreateStartParam, } from './start-param.js';
+export { createLogger, deepSnakeToCamelObjKeys, type Logger, type LoggerFn, type LoggerForceFn, type LoggerOptions, type LogLevel, } from '@tma.js/toolkit';
+export { CancelledError, TimeoutError, } from 'better-promises';

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

@@ -0,0 +1,32 @@
+import { LaunchParamsGenType, ParseLaunchParamsQueryError } from '@tma.js/transformers';
+import { LaunchParamsRetrieveError } from './errors.js';
+import * as E from 'fp-ts/Either';
+import * as O from 'fp-ts/Option';
+export type RetrieveRawInitDataError = RetrieveRawLaunchParamsError;
+export type RetrieveRawLaunchParamsError = LaunchParamsRetrieveError;
+export type RetrieveLaunchParamsError = RetrieveRawLaunchParamsError | ParseLaunchParamsQueryError;
+export type RetrieveLaunchParamsResult = LaunchParamsGenType;
+/**
+ * @returns Launch parameters from any known source.
+ */
+export declare const retrieveLaunchParamsFp: () => E.Either<RetrieveLaunchParamsError, RetrieveLaunchParamsResult>;
+/**
+ * @see retrieveLaunchParamsFp
+ */
+export declare const retrieveLaunchParams: () => RetrieveLaunchParamsResult;
+/**
+ * @returns Raw init data from any known source.
+ */
+export declare const retrieveRawInitDataFp: () => E.Either<RetrieveRawInitDataError, O.Option<string>>;
+/**
+ * @see retrieveRawInitDataFp
+ */
+export declare const retrieveRawInitData: () => string | undefined;
+/**
+ * @returns Launch parameters in a raw format from any known source.
+ */
+export declare function retrieveRawLaunchParamsFp(): E.Either<RetrieveRawLaunchParamsError, string>;
+/**
+ * @see retrieveRawLaunchParamsFp
+ */
+export declare const retrieveRawLaunchParams: () => string;

package/dist/dts/methods/captureSameReq.d.ts

@@ -0,0 +1,10 @@
+type CaptureSameReqFn = (payload: {
+    req_id: string;
+}) => boolean;
+/**
+ * Returns a function which can be used in `request` function `capture` property to capture
+ * the event with the same request identifier.
+ * @param reqId - request identifier.
+ */
+export declare function captureSameReq(reqId: string): CaptureSameReqFn;
+export {};

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

@@ -1,10 +1,30 @@
-import { type Version } from '@tma.js/utils';
-import { type PostEvent } from './index.js';
+import { Version } from '@tma.js/types';
+import { PostEventFn } from './postEvent.js';
+import { MethodName, MethodNameWithVersionedParams, MethodVersionedParams } from './types/index.js';
+export type OnUnsupportedFn = (data: {
+    version: Version;
+} & ({
+    method: MethodName;
+} | {
+    [M in MethodNameWithVersionedParams]: {
+        method: M;
+        param: MethodVersionedParams<M>;
+    };
+}[MethodNameWithVersionedParams])) => void;
+export type CreatePostEventMode = 'strict' | 'non-strict';
 /**
- * Creates function which checks if specified method and parameters are supported. In case,
- * method or parameters are unsupported, an error will be thrown.
+ * Creates a function that checks if the specified method and parameters are supported.
+ *
+ * If the method or parameters are unsupported, the `onUnsupported` function will be called.
+ *
+ * If `strict` or `non-strict` value was passed as the second argument, the function
+ * will create its own `onUnsupported` function with behavior depending on the value passed.
+ *
+ * - Passing `strict` will make the function to throw a `MethodParameterUnsupportedError`
+ * or a `MethodUnsupportedError` error.
+ * - Passing `non-strict` will just warn you about something being unsupported.
+ *
  * @param version - Telegram Mini Apps version.
- * @throws {MethodUnsupportedError} Method is unsupported.
- * @throws {ParameterUnsupportedError} Method parameter is unsupported.
+ * @param onUnsupportedOrMode - function or strict mode. Default: `strict`
  */
-export declare function createPostEvent(version: Version): PostEvent;
+export declare function createPostEvent(version: Version, onUnsupportedOrMode?: OnUnsupportedFn | CreatePostEventMode): PostEventFn;

package/dist/dts/methods/postEvent.d.ts

@@ -1,29 +1,35 @@
-import type { EmptyMethodName, MethodParams, NonEmptyMethodName } from './methods.js';
-interface PostEventOptions {
-    /**
-     * Origin used while posting message. This option is only used in case,
-     * current environment is browser (Web version of Telegram) and could
-     * be used for test purposes.
-     * @default 'https://web.telegram.org'
-     */
-    targetOrigin?: string;
-}
-export type PostEvent = typeof postEvent;
+import { UnknownEnvError } from '../errors.js';
+import { MethodNameWithOptionalParams, MethodNameWithoutParams, MethodNameWithRequiredParams, MethodParams } from './types/index.js';
+import * as E from 'fp-ts/Either';
+export type PostEventError = UnknownEnvError;
+export type PostEventFn = typeof postEvent;
+export type PostEventFpFn = typeof postEventFp;
 /**
- * Sends event to native application which launched Mini App. This function
- * accepts only events, which require arguments.
- * @param eventType - event name.
- * @param params - event parameters.
- * @param options - posting options.
- * @throws {Error} Bridge could not determine current environment and possible way to send event.
+ * @see postEventFp
  */
-export declare function postEvent<E extends NonEmptyMethodName>(eventType: E, params: MethodParams<E>, options?: PostEventOptions): void;
+export declare function postEvent<Method extends MethodNameWithRequiredParams>(method: Method, params: MethodParams<Method>): void;
 /**
- * Sends event to native application which launched Mini App. This function
- * accepts only events, which require arguments.
- * @param eventType - event name.
- * @param options - posting options.
- * @throws {Error} Bridge could not determine current environment and possible way to send event.
+ * @see postEventFp
  */
-export declare function postEvent(eventType: EmptyMethodName, options?: PostEventOptions): void;
-export {};
+export declare function postEvent(method: MethodNameWithoutParams): void;
+/**
+ * @see postEventFp
+ */
+export declare function postEvent<Method extends MethodNameWithOptionalParams>(method: Method, params?: MethodParams<Method>): void;
+/**
+ * Calls Mini Apps methods requiring parameters.
+ * @param method - method name.
+ * @param params - options along with params.
+ */
+export declare function postEventFp<Method extends MethodNameWithRequiredParams>(method: Method, params: MethodParams<Method>): E.Either<PostEventError, void>;
+/**
+ * Calls Mini Apps methods accepting no parameters at all.
+ * @param method - method name.
+ */
+export declare function postEventFp(method: MethodNameWithoutParams): E.Either<PostEventError, void>;
+/**
+ * Calls Mini Apps methods accepting optional parameters.
+ * @param method - method name.
+ * @param params - options along with params.
+ */
+export declare function postEventFp<Method extends MethodNameWithOptionalParams>(method: Method, params?: MethodParams<Method>): E.Either<PostEventError, void>;

package/dist/dts/methods/postMessage.d.ts

@@ -0,0 +1,7 @@
+export type PostMessage = typeof window.parent.postMessage;
+/**
+ * Posts a message to the parent window. We usually use it to send a message in web versions of
+ * Telegram.
+ * @param args - `window.parent.postMessage` arguments.
+ */
+export declare const postMessage: PostMessage;

package/dist/dts/methods/supports.d.ts

@@ -0,0 +1,15 @@
+import { Version } from '@tma.js/types';
+import { MethodName, MethodNameWithVersionedParams, MethodVersionedParams } from './types/index.js';
+/**
+ * Returns true in case, passed parameter in specified method is supported.
+ * @param method - method name
+ * @param param - method parameter
+ * @param inVersion - platform version.
+ */
+export declare function supports<M extends MethodNameWithVersionedParams>(method: M, param: MethodVersionedParams<M>, inVersion: Version): boolean;
+/**
+ * Returns true in case, specified method is supported in a passed version.
+ * @param method - method name.
+ * @param inVersion - platform version.
+ */
+export declare function supports(method: MethodName, inVersion: Version): boolean;

package/dist/dts/methods/types/custom-method.d.ts

@@ -0,0 +1,59 @@
+interface CreateInvokeCustomMethodParams<M extends string, Params extends object> {
+    /**
+     * Unique request identifier.
+     */
+    req_id: string;
+    /**
+     * Method name.
+     */
+    method: M;
+    /**
+     * Method specific parameters.
+     */
+    params: Params;
+}
+export interface CustomMethodsParams {
+    /**
+     * Deletes storage values using their keys.
+     */
+    deleteStorageValues: {
+        keys: string | string[];
+    };
+    /**
+     * Returns the current server time.
+     */
+    getCurrentTime: {};
+    /**
+     * Gets the current user contact in case, the mini app has access to it.
+     */
+    getRequestedContact: {};
+    /**
+     * Gets all registered storage keys.
+     */
+    getStorageKeys: {};
+    /**
+     * Gets storage values using their keys.
+     */
+    getStorageValues: {
+        keys: string | string[];
+    };
+    /**
+     * Saves a value using specified key in the storage.
+     */
+    saveStorageValue: {
+        key: string;
+        value: string;
+    };
+}
+/**
+ * Known custom method name.
+ */
+export type CustomMethodName = keyof CustomMethodsParams;
+/**
+ * Custom method parameters.
+ */
+export type CustomMethodParams<M extends CustomMethodName> = CustomMethodsParams[M];
+export type AnyInvokeCustomMethodParams = CreateInvokeCustomMethodParams<string, any> | {
+    [M in CustomMethodName]: CreateInvokeCustomMethodParams<M, CustomMethodParams<M>>;
+}[CustomMethodName];
+export {};

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

@@ -0,0 +1,6 @@
+export type * from './custom-method.js';
+export type * from './haptic-feedback.js';
+export type * from './methods.js';
+export type * from './misc.js';
+export type * from './popup.js';
+export type { CreateMethodParams } from './utils.js';