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

package/README.md

@@ -1,59 +1,180 @@
 # @tma.js/bridge
 
-[code-badge]: https://img.shields.io/badge/source-black?logo=github
+Communication layer between a Telegram Mini App and the Telegram client. It has no runtime
+dependencies and works together with the official SDK
+([telegram-web-app.js](https://telegram.org/js/telegram-web-app.js)) loaded on the same page.
 
-[docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
+```bash
+pnpm i @tma.js/bridge
+```
 
-[link]: https://github.com/Telegram-Mini-Apps/tma.js/tree/master/tma.js/bridge
+## Calling methods
 
-[docs-link]: https://docs.telegram-mini-apps.com/packages/tma-js-bridge
+```ts
+import { postEvent } from '@tma.js/bridge';
 
-[npm-link]: https://npmjs.com/package/@tma.js/bridge
+postEvent('web_app_ready');
+postEvent('web_app_setup_back_button', { is_visible: true });
+```
 
-[npm-badge]: https://img.shields.io/npm/v/@tma.js/bridge?logo=npm
+Method names and parameters are typed. `postEvent` throws `UnknownEnvError` if the app was
+opened outside Telegram.
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/@tma.js/bridge
+To make sure the method is supported by the current Telegram client, create a checked function:
 
-[![NPM][npm-badge]][npm-link]
-![Size][size-badge]
-[![docs-badge]][docs-link]
-[![code-badge]][link]
+```ts
+import { createPostEvent, retrieveLaunchParams } from '@tma.js/bridge';
 
-The lowest level communication layer with Telegram Mini Apps.
+const postEvent = createPostEvent(retrieveLaunchParams().tgWebAppVersion);
+// Throws MethodUnsupportedError in Mini Apps versions lower than 6.2.
+postEvent('web_app_open_popup', { title: 'Hi', message: 'Hello', buttons: [{ id: 'ok', type: 'ok' }] });
+```
 
-This package provides fundamental utilities and types for developing applications on the Telegram
-Mini Apps platform.
+Pass `'non-strict'` or a function as the second argument to warn or handle unsupported calls
+yourself. Use `supports` and `getReleaseVersion` for manual checks.
 
-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).
+## Listening to events
 
-## Installation
+```ts
+import { onEvent, offEvent, onAnyEvent } from '@tma.js/bridge';
 
-```bash
-pnpm i @tma.js/bridge
-# or
-npm i @tma.js/bridge
-# or
-yarn add @tma.js/bridge
+const stop = onEvent('viewport_changed', ({ height, is_expanded }) => {
+  console.log(height, is_expanded);
+});
+stop();
+
+onEvent('back_button_pressed', () => history.back(), { once: true });
+onEvent('theme_changed', console.log, { signal: abortController.signal });
+onAnyEvent(({ name, payload }) => console.log(name, payload));
 ```
 
-## Usage
+## Requests
 
-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).
+`request` calls a method and waits for an event:
 
 ```ts
-import { on, postEvent, applyPolyfills } from '@tma.js/bridge';
+import { request, createRequestId, captureSameReq } from '@tma.js/bridge';
 
-// The package uses some polyfills, so let's use them.
-applyPolyfills();
+const { button_id } = await request('web_app_open_popup', 'popup_closed', {
+  params: { title: 'Hi', message: 'Hello', buttons: [{ id: 'ok', type: 'ok' }] },
+});
 
-// Show the back button, wait for it to be clicked once,
-// then hide it.
-postEvent('web_app_setup_back_button', { is_visible: true });
+// Waiting for one of several events.
+const { event, payload } = await request(
+  'web_app_request_fullscreen',
+  ['fullscreen_changed', 'fullscreen_failed'],
+  { timeout: 5000, signal },
+);
+
+// Capturing the event related to the request.
+const reqId = createRequestId();
+const { data } = await request('web_app_read_text_from_clipboard', 'clipboard_text_received', {
+  params: { req_id: reqId },
+  capture: captureSameReq(reqId),
+});
+```
+
+Custom methods have a dedicated helper:
+
+```ts
+import { invokeCustomMethod } from '@tma.js/bridge';
+
+const keys = await invokeCustomMethod('getStorageKeys', {});
+```
+
+## Handling errors
+
+Functions failing with expected errors have a `safe` counterpart returning the error instead of
+throwing it. The error type is a union of all possible errors, so the compiler knows what to
+handle:
 
-const off = on('back_button_pressed', () => {
-  postEvent('web_app_setup_back_button', { is_visible: false });
-  off();
+```ts
+import { matchError, safeInvokeCustomMethod } from '@tma.js/bridge';
+
+const result = await safeInvokeCustomMethod('getStorageKeys', {}, { timeout: 5000 });
+if (!result.ok) {
+  // Compilation fails if any error is left unhandled.
+  return matchError(result.error, {
+    InvokeCustomMethodFailedError: e => console.error('Method failed:', e.data.error),
+    TimeoutError: () => console.error('No response from Telegram'),
+  });
+}
+const keys = result.data;
+```
+
+| Function                   | Safe counterpart               | Errors                                           |
+|----------------------------|--------------------------------|--------------------------------------------------|
+| `request`                  | `safeRequest`                  | `TimeoutError`                                   |
+| `invokeCustomMethod`       | `safeInvokeCustomMethod`       | `InvokeCustomMethodFailedError`, `TimeoutError`  |
+| `parseLaunchParams`        | `safeParseLaunchParams`        | `InvalidLaunchParamsError`                       |
+| `retrieveLaunchParams`     | `safeRetrieveLaunchParams`     | `LaunchParamsRetrieveError`                      |
+| `retrieveRawLaunchParams`  | `safeRetrieveRawLaunchParams`  | `LaunchParamsRetrieveError`                      |
+| `retrieveRawInitData`      | `safeRetrieveRawInitData`      | `LaunchParamsRetrieveError`                      |
+| `createStartParam`         | `safeCreateStartParam`         | `StartParamTooLongError`                         |
+
+Environment and usage errors are always thrown: `UnknownEnvError` when the app is opened outside
+Telegram, and `MethodUnsupportedError` or `MethodParameterUnsupportedError` from functions created
+with `createPostEvent`. Aborted requests are rejected with `signal.reason`, as other abortable APIs
+are.
+
+## Environment
+
+```ts
+import {
+  isTMA,
+  isTMAAsync,
+  retrieveLaunchParams,
+  retrieveRawInitData,
+} from '@tma.js/bridge';
+
+isTMA(); // Synchronous check based on environment traits.
+await isTMAAsync(); // Asks the Telegram client and waits for a response.
+
+const { tgWebAppPlatform, tgWebAppVersion, tgWebAppThemeParams } = retrieveLaunchParams();
+const initData = retrieveRawInitData(); // Send it to your server.
+```
+
+Launch parameters are looked up in the URL, the navigation entry, and the session storage
+(including the one written by the official SDK), so they survive page reloads.
+
+## Mocking
+
+`mockTelegramEnv` imitates the Telegram client. Outside iframes, it defines
+`window.TelegramWebviewProxy`, so calls made by other libraries, including the official SDK, are
+intercepted too. In Telegram Web (iframe), only calls made by this package are intercepted.
+
+```ts
+import { emitEvent, mockTelegramEnv } from '@tma.js/bridge';
+
+const restore = mockTelegramEnv({
+  launchParams: {
+    tgWebAppPlatform: 'tdesktop',
+    tgWebAppVersion: '9.0',
+    tgWebAppThemeParams: { bg_color: '#17212b', text_color: '#f5f5f5' },
+  },
+  onMethod({ name }, next) {
+    if (name === 'web_app_request_theme') {
+      return emitEvent('theme_changed', { theme_params: { bg_color: '#17212b' } });
+    }
+    next();
+  },
 });
 ```
+
+## Start parameter
+
+```ts
+import { createStartParam, decodeStartParam } from '@tma.js/bridge';
+
+const param = createStartParam({ page: 'product', id: 42 });
+decodeStartParam(param, 'json'); // { page: 'product', id: 42 }
+```
+
+## Debugging
+
+```ts
+import { setDebug, setLogger } from '@tma.js/bridge';
+
+setDebug(true); // Logs outgoing methods and incoming events.
+setLogger(myLogger); // { log, warn, error }
+```

package/dist/dts/env.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Window properties used by the Telegram clients and the official SDK to communicate with
+ * a mini app.
+ */
+export interface TelegramWindow {
+    /**
+     * Telegram for iOS, macOS, Android and Telegram Desktop.
+     */
+    TelegramWebviewProxy?: {
+        postEvent: (eventType: string, eventData: string) => void;
+    };
+    /**
+     * Telegram for Windows Phone.
+     */
+    external?: {
+        notify?: (message: string) => void;
+    };
+    Telegram?: {
+        WebView?: {
+            receiveEvent?: ReceiveEventFn;
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+    TelegramGameProxy?: {
+        receiveEvent?: ReceiveEventFn;
+        [key: string]: unknown;
+    };
+    TelegramGameProxy_receiveEvent?: ReceiveEventFn;
+}
+export type ReceiveEventFn = (eventType: string, eventData?: unknown) => void;
+/**
+ * @returns The current window with Telegram-specific properties typed.
+ */
+export declare function telegramWindow(): Window & TelegramWindow;
+/**
+ * @returns True if the current environment is an iframe. Telegram Web clients open mini apps
+ * in an iframe.
+ * @see https://stackoverflow.com/a/326076
+ */
+export declare function isIframe(): boolean;
+/**
+ * @returns True if the `window.TelegramWebviewProxy.postEvent` function exists. Native Telegram
+ * clients define it to receive method calls.
+ */
+export declare function hasWebviewProxy(): boolean;
+/**
+ * @returns True if the current environment looks like a Telegram Mini App: the Telegram webview
+ * proxy is defined, or launch parameters are available.
+ *
+ * Use `isTMAAsync` for a stricter check.
+ */
+export declare function isTMA(): boolean;
+/**
+ * Checks if the current environment is a Telegram Mini App by calling a method and waiting for
+ * the Telegram client response.
+ * @param options - additional options.
+ */
+export declare function isTMAAsync(options?: {
+    /**
+     * Time in milliseconds to wait for the response.
+     * @default 100
+     */
+    timeout?: number;
+    /**
+     * Signal to abort the check.
+     */
+    signal?: AbortSignal;
+}): Promise<boolean>;

package/dist/dts/errors.d.ts

@@ -1,10 +1,30 @@
-declare const MethodUnsupportedError_base: import('error-kid').ErrorClass<[method: string, version: string]>;
+declare const UnknownEnvError_base: import('error-kid').ErrorClass<[], "UnknownEnvError">;
+/**
+ * Thrown when the current environment provides no known way to communicate with the Telegram
+ * client. Usually, it means the app was opened outside Telegram.
+ */
+export declare class UnknownEnvError extends /* @__PURE__ */ UnknownEnvError_base {
+}
+declare const MethodUnsupportedError_base: import('error-kid').ErrorClassWithData<[method: string, version: string], {
+    method: string;
+    version: string;
+}, "MethodUnsupportedError">;
+/**
+ * Thrown when a method is not supported in the current Mini Apps version.
+ */
 export declare class MethodUnsupportedError extends /* @__PURE__ */ MethodUnsupportedError_base {
 }
-declare const MethodParameterUnsupportedError_base: import('error-kid').ErrorClass<[method: string, param: string, version: string]>;
+declare const MethodParameterUnsupportedError_base: import('error-kid').ErrorClassWithData<[method: string, param: string, version: string], {
+    method: string;
+    param: string;
+    version: string;
+}, "MethodParameterUnsupportedError">;
+/**
+ * Thrown when a method parameter is not supported in the current Mini Apps version.
+ */
 export declare class MethodParameterUnsupportedError extends /* @__PURE__ */ MethodParameterUnsupportedError_base {
 }
-declare const LaunchParamsRetrieveError_base: import('error-kid').ErrorClassWithData<[{
+declare const LaunchParamsRetrieveError_base: import('error-kid').ErrorClassWithData<[errors: {
     source: string;
     error: unknown;
 }[]], {
@@ -12,16 +32,42 @@ declare const LaunchParamsRetrieveError_base: import('error-kid').ErrorClassWith
         source: string;
         error: unknown;
     }[];
-}>;
+}, "LaunchParamsRetrieveError">;
+/**
+ * Thrown when launch parameters can't be found in any known source.
+ */
 export declare class LaunchParamsRetrieveError extends /* @__PURE__ */ LaunchParamsRetrieveError_base {
 }
-declare const InvalidLaunchParamsError_base: import('error-kid').ErrorClass<[launchParams: string, cause: unknown]>;
+declare const InvalidLaunchParamsError_base: import('error-kid').ErrorClassWithData<[_value: string, cause?: unknown], {
+    value: string;
+}, "InvalidLaunchParamsError">;
+/**
+ * Thrown when a value doesn't represent valid launch parameters.
+ */
 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]>;
+declare const InvokeCustomMethodFailedError_base: import('error-kid').ErrorClassWithData<[error: string], {
+    error: string;
+}, "InvokeCustomMethodFailedError">;
+/**
+ * Thrown when a custom method invocation completed with an error.
+ */
 export declare class InvokeCustomMethodFailedError extends /* @__PURE__ */ InvokeCustomMethodFailedError_base {
 }
+declare const TimeoutError_base: import('error-kid').ErrorClassWithData<[timeout: number], {
+    timeout: number;
+}, "TimeoutError">;
+/**
+ * Thrown when an operation didn't complete in time.
+ */
+export declare class TimeoutError extends /* @__PURE__ */ TimeoutError_base {
+}
+declare const StartParamTooLongError_base: import('error-kid').ErrorClassWithData<[length: number], {
+    length: number;
+}, "StartParamTooLongError">;
+/**
+ * Thrown when a value is too long to be used as a start parameter.
+ */
+export declare class StartParamTooLongError extends /* @__PURE__ */ StartParamTooLongError_base {
+}
 export {};

package/dist/dts/events.d.ts

@@ -0,0 +1,64 @@
+import { AnyEventListener, EventListener, EventName, EventPayload } from './types/index.js';
+export interface OnOptions {
+    /**
+     * Remove the listener after the first call.
+     */
+    once?: boolean;
+    /**
+     * Signal removing the listener when aborted.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Arguments following the event name when emitting the event.
+ */
+export type EmitEventArgs<E extends EventName> = [EventPayload<E>] extends [never] ? [] : [payload: EventPayload<E>];
+/**
+ * Schema of a message sent by Telegram Web clients via `window.postMessage`.
+ */
+export declare const MiniAppsMessageSchema: import('valibot').SchemaWithPipe<readonly [import('valibot').StringSchema<undefined>, import('valibot').ParseJsonAction<string, undefined, undefined>, import('valibot').LooseObjectSchema<{
+    readonly eventType: import('valibot').StringSchema<undefined>;
+    readonly eventData: import('valibot').OptionalSchema<import('valibot').UnknownSchema, undefined>;
+}, undefined>]>;
+/**
+ * Adds a listener of the specified Mini Apps event. Adding the same listener twice has no
+ * effect.
+ * @param event - event name.
+ * @param listener - event listener.
+ * @param options - additional options.
+ * @returns Function removing the listener.
+ * @see https://docs.telegram-mini-apps.com/platform/events
+ */
+export declare function onEvent<E extends EventName>(event: E, listener: EventListener<E>, options?: OnOptions): VoidFunction;
+/**
+ * Removes a listener of the specified Mini Apps event.
+ * @param event - event name.
+ * @param listener - event listener.
+ */
+export declare function offEvent<E extends EventName>(event: E, listener: EventListener<E>): void;
+/**
+ * Adds a listener of all Mini Apps events. Adding the same listener twice has no effect.
+ * @param listener - events listener.
+ * @param options - additional options.
+ * @returns Function removing the listener.
+ */
+export declare function onAnyEvent(listener: AnyEventListener, options?: OnOptions): VoidFunction;
+/**
+ * Removes a listener of all Mini Apps events.
+ * @param listener - events listener.
+ */
+export declare function offAnyEvent(listener: AnyEventListener): void;
+/**
+ * Removes all event listeners and stops receiving events from the Telegram client.
+ */
+export declare function offAll(): void;
+/**
+ * Emits an event as if it was sent by the Telegram client. Use it to imitate the Telegram
+ * client, for example, in the `mockTelegramEnv` function `onEvent` option.
+ *
+ * The event is delivered the same way a real Telegram client would deliver it, so other
+ * libraries (e.g. the official SDK) receive it too.
+ * @param event - event name.
+ * @param args - event payload.
+ */
+export declare function emitEvent<E extends EventName>(event: E, ...args: EmitEventArgs<E>): void;

package/dist/dts/index.d.ts

@@ -1,26 +1,14 @@
-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 { off, offAll, on } from './events/emitter.js';
-export { emitEvent } from './events/emitEvent.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 { getReleaseVersion } from './methods/getReleaseVersion.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 { request2, request2Fp, type Request2CaptureEventFn, type Request2CaptureEventsFn, type Request2CaptureFn, type Request2CaptureFnEventsPayload, type Request2Fn, type Request2Options, type Request2Result, type Request2Error, type Request2FpOptions, type Request2FpFn, } from './utils/request2.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 DeepConvertSnakeKeysToCamelCase, type Logger, type LoggerFn, type LoggerForceFn, type LoggerOptions, type LogLevel, } from '@tma.js/toolkit';
-export { CancelledError, TimeoutError, } from 'better-promises';
+export { matchError } from 'error-kid';
+export { hasWebviewProxy, isIframe, isTMA, isTMAAsync } from './env.js';
+export { InvalidLaunchParamsError, InvokeCustomMethodFailedError, LaunchParamsRetrieveError, MethodParameterUnsupportedError, MethodUnsupportedError, StartParamTooLongError, TimeoutError, UnknownEnvError, } from './errors.js';
+export { emitEvent, offAll, offAnyEvent, offEvent, onAnyEvent, onEvent, type EmitEventArgs, type OnOptions, } from './events.js';
+export { invokeCustomMethod, safeInvokeCustomMethod, type InvokeCustomMethodOptions, } from './invokeCustomMethod.js';
+export { parseLaunchParams, retrieveLaunchParams, retrieveRawInitData, retrieveRawLaunchParams, safeParseLaunchParams, safeRetrieveLaunchParams, safeRetrieveRawInitData, safeRetrieveRawLaunchParams, serializeLaunchParams, type LaunchParams, } from './launch-params.js';
+export { getLogger, isDebug, setDebug, setLogger, type Logger } from './logger.js';
+export { mockTelegramEnv, type MockedMethodCall, type MockTelegramEnvOptions, } from './mockTelegramEnv.js';
+export { getTargetOrigin, postEvent, setTargetOrigin, type PostEventFn } from './post-event.js';
+export { captureSameReq, createRequestId, request, safeRequest, type RequestFnArgs, type RequestFnOptions, type RequestOptions, type RequestResult, } from './request.js';
+export { createStartParam, decodeBase64Url, decodeStartParam, encodeBase64Url, isSafeToCreateStartParam, safeCreateStartParam, } from './start-param.js';
+export { err, ok, type Result, throwing, unwrap } from './result.js';
+export { compareVersions, createPostEvent, getReleaseVersion, supports, type MethodNameWithVersionedParams, type MethodVersionedParam, type OnUnsupportedFn, } from './versions.js';
+export type * from './types/index.js';

package/dist/dts/invokeCustomMethod.d.ts

@@ -0,0 +1,33 @@
+import { InvokeCustomMethodFailedError, TimeoutError } from './errors.js';
+import { RequestOptions } from './request.js';
+import { Result } from './result.js';
+import { CustomMethodName, CustomMethodParams } from './types/index.js';
+export interface InvokeCustomMethodOptions extends Omit<RequestOptions<'custom_method_invoked'>, 'capture'> {
+    /**
+     * Request identifier. Generated automatically if omitted.
+     */
+    requestId?: string;
+}
+/**
+ * Invokes a custom method and returns its result.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param options - additional options.
+ * @returns Method result, or one of the errors:
+ * - `InvokeCustomMethodFailedError`: the method returned an error;
+ * - `TimeoutError`: the timeout was reached.
+ */
+export declare function safeInvokeCustomMethod<M extends CustomMethodName>(method: M, params: CustomMethodParams<M>, options?: InvokeCustomMethodOptions): Promise<Result<InvokeCustomMethodFailedError | TimeoutError, unknown>>;
+export declare function safeInvokeCustomMethod(method: string, params: object, options?: InvokeCustomMethodOptions): Promise<Result<InvokeCustomMethodFailedError | TimeoutError, unknown>>;
+/**
+ * Invokes a custom method and returns its result.
+ *
+ * Throwing version of `safeInvokeCustomMethod`.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param options - additional options.
+ * @throws {InvokeCustomMethodFailedError} The method returned an error.
+ * @throws {TimeoutError} The timeout was reached.
+ */
+export declare function invokeCustomMethod<M extends CustomMethodName>(method: M, params: CustomMethodParams<M>, options?: InvokeCustomMethodOptions): Promise<unknown>;
+export declare function invokeCustomMethod(method: string, params: object, options?: InvokeCustomMethodOptions): Promise<unknown>;

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

@@ -1,31 +1,113 @@
-import { LaunchParamsGenType, ParseLaunchParamsQueryError } from '@tma.js/transformers';
-import { either as E, option as O } from 'fp-ts';
-import { LaunchParamsRetrieveError } from './errors.js';
-export type RetrieveRawInitDataError = RetrieveRawLaunchParamsError;
-export type RetrieveRawLaunchParamsError = LaunchParamsRetrieveError;
-export type RetrieveLaunchParamsError = RetrieveRawLaunchParamsError | ParseLaunchParamsQueryError;
-export type RetrieveLaunchParamsResult = LaunchParamsGenType;
+import { InvalidLaunchParamsError, LaunchParamsRetrieveError } from './errors.js';
+import { Result } from './result.js';
+import { Platform, ThemeParams, Version } from './types/index.js';
 /**
- * @returns Launch parameters from any known source.
+ * Launch parameters passed by the Telegram client to the mini app.
+ * @see https://docs.telegram-mini-apps.com/platform/launch-parameters
  */
-export declare function retrieveLaunchParamsFp(): E.Either<RetrieveLaunchParamsError, RetrieveLaunchParamsResult>;
+export interface LaunchParams {
+    /**
+     * True if the mini app was launched in inline mode.
+     */
+    tgWebAppBotInline?: boolean;
+    /**
+     * Init data in the raw format. Pass it to your server to authorize the user.
+     * @see https://docs.telegram-mini-apps.com/platform/init-data
+     */
+    tgWebAppData?: string;
+    /**
+     * Default theme colors.
+     */
+    tgWebAppDefaultColors?: ThemeParams;
+    /**
+     * True if the mini app was launched in fullscreen mode.
+     */
+    tgWebAppFullscreen?: boolean;
+    /**
+     * Telegram client platform.
+     */
+    tgWebAppPlatform: Platform;
+    /**
+     * True if the Settings Button should be displayed.
+     */
+    tgWebAppShowSettings?: boolean;
+    /**
+     * Start parameter passed in the mini app link.
+     * @see https://docs.telegram-mini-apps.com/platform/start-parameter
+     */
+    tgWebAppStartParam?: string;
+    /**
+     * Theme parameters.
+     */
+    tgWebAppThemeParams: ThemeParams;
+    /**
+     * Mini Apps version supported by the Telegram client.
+     */
+    tgWebAppVersion: Version;
+}
 /**
- * @see retrieveLaunchParamsFp
+ * Parses launch parameters from their query representation.
+ * @param value - launch parameters query.
+ * @returns Launch parameters, or `InvalidLaunchParamsError` if the value doesn't represent
+ * valid launch parameters.
  */
-export declare const retrieveLaunchParams: () => RetrieveLaunchParamsResult;
+export declare function safeParseLaunchParams(value: string | URLSearchParams): Result<InvalidLaunchParamsError, LaunchParams>;
 /**
- * @returns Raw init data from any known source.
+ * Parses launch parameters from their query representation.
+ *
+ * Throwing version of `safeParseLaunchParams`.
+ * @param value - launch parameters query.
+ * @throws {InvalidLaunchParamsError} The value doesn't represent valid launch parameters.
  */
-export declare function retrieveRawInitDataFp(): E.Either<RetrieveRawInitDataError, O.Option<string>>;
+export declare const parseLaunchParams: (value: string | URLSearchParams) => LaunchParams;
 /**
- * @see retrieveRawInitDataFp
+ * Converts launch parameters to their query representation.
+ * @param value - launch parameters.
  */
-export declare function retrieveRawInitData(): string | undefined;
+export declare function serializeLaunchParams(value: LaunchParams): string;
 /**
- * @returns Launch parameters in a raw format from any known source.
+ * Saves launch parameters to the session storage, so they could be retrieved after the page
+ * reload.
+ * @param value - launch parameters query.
  */
-export declare function retrieveRawLaunchParamsFp(): E.Either<RetrieveRawLaunchParamsError, string>;
+export declare function saveLaunchParams(value: string): void;
 /**
- * @see retrieveRawLaunchParamsFp
+ * Retrieves launch parameters in the raw format from any known source and saves them in
+ * the session storage.
+ * @returns Launch parameters, or `LaunchParamsRetrieveError` if they were not found.
  */
-export declare const retrieveRawLaunchParams: (() => string) & {};
+export declare function safeRetrieveRawLaunchParams(): Result<LaunchParamsRetrieveError, string>;
+/**
+ * Retrieves launch parameters in the raw format from any known source and saves them in
+ * the session storage.
+ *
+ * Throwing version of `safeRetrieveRawLaunchParams`.
+ * @throws {LaunchParamsRetrieveError} Launch parameters were not found.
+ */
+export declare const retrieveRawLaunchParams: () => string;
+/**
+ * Retrieves launch parameters from any known source.
+ * @returns Launch parameters, or `LaunchParamsRetrieveError` if they were not found.
+ */
+export declare function safeRetrieveLaunchParams(): Result<LaunchParamsRetrieveError, LaunchParams>;
+/**
+ * Retrieves launch parameters from any known source.
+ *
+ * Throwing version of `safeRetrieveLaunchParams`.
+ * @throws {LaunchParamsRetrieveError} Launch parameters were not found.
+ */
+export declare const retrieveLaunchParams: () => LaunchParams;
+/**
+ * Retrieves init data in the raw format. Pass it to your server to authorize the user.
+ * @returns Init data (`undefined` if it is missing in launch parameters), or
+ * `LaunchParamsRetrieveError` if launch parameters were not found.
+ */
+export declare function safeRetrieveRawInitData(): Result<LaunchParamsRetrieveError, string | undefined>;
+/**
+ * Retrieves init data in the raw format. Pass it to your server to authorize the user.
+ *
+ * Throwing version of `safeRetrieveRawInitData`.
+ * @returns Init data, or `undefined` if it is missing in launch parameters.
+ * @throws {LaunchParamsRetrieveError} Launch parameters were not found.
+ */
+export declare const retrieveRawInitData: () => string | undefined;