@tma.js/sdk 1.1.0 → 1.2.0

package/dist/dts/bridge/events/parsers/phoneRequested.d.ts

@@ -1,4 +1,4 @@
-export type PhoneRequestedStatus = 'sent' | string;
+export type PhoneRequestedStatus = 'sent' | 'cancelled' | string;
 export interface PhoneRequestedPayload {
     /**
      * Request status.

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

@@ -2,4 +2,5 @@ export * from './env/index.js';
 export * from './errors/index.js';
 export * from './events/index.js';
 export * from './methods/index.js';
+export * from './invoke-custom-method.js';
 export * from './request.js';

package/dist/dts/bridge/invoke-custom-method.d.ts

@@ -0,0 +1,18 @@
+import type { ExecuteWithOptions } from '../types/index.js';
+import type { CustomMethodName, CustomMethodParams } from './methods/index.js';
+/**
+ * Invokes known custom method. Returns method execution result.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param requestId - request identifier.
+ * @param options - additional options.
+ */
+export declare function invokeCustomMethod<M extends CustomMethodName>(method: M, params: CustomMethodParams<M>, requestId: string, options?: ExecuteWithOptions): Promise<unknown>;
+/**
+ * Invokes unknown custom method. Returns method execution result.
+ * @param method - method name.
+ * @param params - method parameters.
+ * @param requestId - request identifier.
+ * @param options - additional options.
+ */
+export declare function invokeCustomMethod(method: string, params: object, requestId: string, options?: ExecuteWithOptions): Promise<unknown>;

package/dist/dts/bridge/methods/custom-methods.d.ts

@@ -0,0 +1,56 @@
+import type { RequestId } from '../../types/index.js';
+interface CreateInvokeCustomMethodParams<M extends string, Params extends object> {
+    /**
+     * Unique request identifier.
+     */
+    req_id: RequestId;
+    /**
+     * Method name.
+     */
+    method: M;
+    /**
+     * Method specific parameters.
+     */
+    params: Params;
+}
+export interface CustomMethodsParams {
+    /**
+     * Deletes storage values by their keys.
+     */
+    deleteStorageValues: {
+        keys: string | string[];
+    };
+    /**
+     * Gets current user contact in case, Mini has access to it.
+     */
+    getRequestedContact: {};
+    /**
+     * Gets all registered storage keys.
+     */
+    getStorageKeys: {};
+    /**
+     * Gets storage values by their keys.
+     */
+    getStorageValues: {
+        keys: string | string[];
+    };
+    /**
+     * Saves value by 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/bridge/methods/index.d.ts

@@ -1,6 +1,6 @@
 export * from './createPostEvent.js';
+export * from './custom-methods.js';
 export * from './haptic.js';
-export * from './invoke-custom-method.js';
 export * from './methods.js';
 export * from './popup.js';
 export * from './postEvent.js';

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

@@ -1,7 +1,7 @@
 import type { RGB } from '../../colors/index.js';
 import type { IsNever, Not, RequestId, UnionKeys } from '../../types/index.js';
+import type { AnyInvokeCustomMethodParams } from './custom-methods.js';
 import type { AnyHapticFeedbackParams } from './haptic.js';
-import type { AnyInvokeCustomMethodParams } from './invoke-custom-method.js';
 import type { PopupParams } from './popup.js';
 /**
  * Color key which could be used to update header color.

package/dist/dts/bridge/request.d.ts

@@ -1,6 +1,6 @@
-import type { And, If, IsNever } from '../types/index.js';
+import type { And, ExecuteWithOptions, If, IsNever } from '../types/index.js';
 import { type MiniAppsEventHasParams, type MiniAppsEventName, type MiniAppsEventParams } from './events/index.js';
-import { type MiniAppsEmptyMethodName, type MiniAppsMethodAcceptParams, type MiniAppsMethodName, type MiniAppsMethodParams, type MiniAppsNonEmptyMethodName, type PostEvent } from './methods/index.js';
+import { type MiniAppsEmptyMethodName, type MiniAppsMethodAcceptParams, type MiniAppsMethodName, type MiniAppsMethodParams, type MiniAppsNonEmptyMethodName } from './methods/index.js';
 /**
  * Names of methods, which require passing "req_id" parameter.
  */
@@ -17,16 +17,7 @@ type EventWithRequestId = {
         req_id: string;
     } ? true : false>, E, never>;
 }[MiniAppsEventName];
-export interface RequestOptions {
-    /**
-     * Bridge postEvent method.
-     * @default Global postEvent method.
-     */
-    postEvent?: PostEvent;
-    /**
-     * Execution timeout.
-     */
-    timeout?: number;
+export interface RequestOptions extends ExecuteWithOptions {
 }
 export interface RequestOptionsAdvanced<EventPayload> extends RequestOptions {
     /**

package/dist/dts/cloud-storage/CloudStorage.d.ts

@@ -1,37 +1,29 @@
-import { postEvent as defaultPostEvent, type RequestOptions } from '../bridge/index.js';
+import { postEvent as defaultPostEvent } from '../bridge/index.js';
 import { type SupportsFunc } from '../supports/index.js';
-import type { CreateRequestIdFunc } from '../types/index.js';
+import type { CreateRequestIdFunc, ExecuteWithTimeout } from '../types/index.js';
 import type { Version } from '../version/index.js';
-type WiredRequestOptions = Omit<RequestOptions, 'postEvent'>;
 export declare class CloudStorage {
     private readonly createRequestId;
     private readonly postEvent;
     constructor(version: Version, createRequestId: CreateRequestIdFunc, postEvent?: typeof defaultPostEvent);
-    /**
-     * Invokes custom method related to CloudStorage.
-     * @param method - method name.
-     * @param params - method parameters.
-     * @param options - execution options.
-     */
-    private invokeCustomMethod;
     /**
      * Deletes specified key or keys from the cloud storage.
      * @param keyOrKeys - key or keys to delete.
      * @param options - request execution options.
      */
-    delete(keyOrKeys: string | string[], options?: WiredRequestOptions): Promise<void>;
+    delete(keyOrKeys: string | string[], options?: ExecuteWithTimeout): Promise<void>;
     /**
      * Returns list of all keys presented in the cloud storage.
      * @param options - request execution options.
      */
-    getKeys(options?: WiredRequestOptions): Promise<string[]>;
+    getKeys(options?: ExecuteWithTimeout): Promise<string[]>;
     /**
      * Returns map, where key is one of the specified in keys argument, and value is according
      * storage value.
      * @param keys - keys list.
      * @param options - request execution options.
      */
-    get<K extends string>(keys: K[], options?: WiredRequestOptions): Promise<Record<K, string>>;
+    get<K extends string>(keys: K[], options?: ExecuteWithTimeout): Promise<Record<K, string>>;
     /**
      * Returns value of the specified key.
      * @param key - cloud storage key.
@@ -39,17 +31,16 @@ export declare class CloudStorage {
      * @return Value of the specified key. In case, key was not created previously, function
      * will return empty string.
      */
-    get(key: string, options?: WiredRequestOptions): Promise<string>;
+    get(key: string, options?: ExecuteWithTimeout): Promise<string>;
     /**
      * Saves specified value by key.
      * @param key - storage key.
      * @param value - storage value.
      * @param options - request execution options.
      */
-    set(key: string, value: string, options?: WiredRequestOptions): Promise<void>;
+    set(key: string, value: string, options?: ExecuteWithTimeout): Promise<void>;
     /**
      * Checks if specified method is supported by current component.
      */
     supports: SupportsFunc<'delete' | 'get' | 'getKeys' | 'set'>;
 }
-export {};

package/dist/dts/index.d.ts

@@ -1,6 +1,6 @@
 export { BackButton, type BackButtonEventName, type BackButtonEventListener, } from './back-button/index.js';
-export { createPostEvent, isIframe, on, off, once, postEvent, request, subscribe, unsubscribe, MethodUnsupportedError, ParameterUnsupportedError, type HeaderColorKey, type InvoiceStatus, type ImpactHapticFeedbackStyle, type MiniAppsMethodName, type MiniAppsEventName, type MiniAppsEventParams, type MiniAppsEventListener, type MiniAppsGlobalEventListener, type MiniAppsEmptyMethodName, type MiniAppsMethodAcceptParams, type MiniAppsMethodParams, type MiniAppsNonEmptyMethodName, type MiniAppsMethods, type MiniAppsEventEmitter, type MiniAppsEventHasParams, type MiniAppsEvents, type NotificationHapticFeedbackType, type PhoneRequestedStatus, type PostEvent, type RequestOptions, type SwitchInlineQueryChatType, type WriteAccessRequestedStatus, } from './bridge/index.js';
-export { classNames, mergeClassNames, } from './classnames/index.js';
+export { createPostEvent, isIframe, invokeCustomMethod, on, off, once, postEvent, request, subscribe, unsubscribe, MethodUnsupportedError, ParameterUnsupportedError, type HeaderColorKey, type InvoiceStatus, type ImpactHapticFeedbackStyle, type MiniAppsMethodName, type MiniAppsEventName, type MiniAppsEventParams, type MiniAppsEventListener, type MiniAppsGlobalEventListener, type MiniAppsEmptyMethodName, type MiniAppsMethodAcceptParams, type MiniAppsMethodParams, type MiniAppsNonEmptyMethodName, type MiniAppsMethods, type MiniAppsEventEmitter, type MiniAppsEventHasParams, type MiniAppsEvents, type NotificationHapticFeedbackType, type PhoneRequestedStatus, type PostEvent, type RequestOptions, type RequestOptionsAdvanced, type SwitchInlineQueryChatType, type WriteAccessRequestedStatus, } from './bridge/index.js';
+export { classNames, mergeClassNames } from './classnames/index.js';
 export { ClosingBehavior, type ClosingBehaviorEventListener, type ClosingBehaviorEventName, type ClosingBehaviorEvents, } from './closing-behavior/index.js';
 export { CloudStorage } from './cloud-storage/index.js';
 export { isRGB, isRGBShort, isColorDark, toRGB, type RGB, type RGBShort, } from './colors/index.js';
@@ -11,15 +11,16 @@ export { Invoice, type InvoiceEvents, type InvoiceEventListener, type InvoiceEve
 export { launchParamsParser, parseLaunchParams, retrieveLaunchData, serializeLaunchParams, type LaunchParams, type LaunchData, } from './launch-params/index.js';
 export { MainButton, type MainButtonParams, type MainButtonProps, type MainButtonEvents, type MainButtonEventName, type MainButtonEventListener, } from './main-button/index.js';
 export { MiniApp, type MiniAppHeaderColor, type MiniAppEventName, type MiniAppEventListener, type MiniAppEvents, type MiniAppProps, } from './mini-app/index.js';
-export { isTMA, isRecord, } from './misc/index.js';
+export { isTMA, isRecord } from './misc/index.js';
 export { getHash, HashNavigator, Navigator, type NavigationEntry, type NavigatorConEntry, type NavigatorOptions, type HashNavigatorOptions, type HashNavigatorEventsMap, type HashNavigatorEventListener, type HashNavigatorEventName, } from './navigation/index.js';
 export { Popup, type PopupEventName, type PopupEventListener, type PopupEvents, type OpenPopupOptions, type OpenPopupOptionsButton, } from './popup/index.js';
 export { QRScanner, type QRScannerEventListener, type QRScannerEventName, type QRScannerEvents, } from './qr-scanner/index.js';
 export { SettingsButton, type SettingsButtonEventName, type SettingsButtonEventListener, type SettingsButtonEvents, } from './settings-button/index.js';
 export { supports } from './supports/index.js';
 export { parseThemeParams, requestThemeParams, serializeThemeParams, themeParamsParser, ThemeParams, type ThemeParamsEventListener, type ThemeParamsEventName, type ThemeParamsEvents, type ThemeParamsKey, type ThemeParamsParsed, } from './theme-params/index.js';
-export type { RequestId, CreateRequestIdFunc, } from './types/index.js';
+export { withTimeout, TimeoutError, isTimeoutError } from './timeout/index.js';
+export type { RequestId, CreateRequestIdFunc } from './types/index.js';
 export { Utils } from './utils/index.js';
-export { compareVersions, type Version, } from './version/index.js';
+export { compareVersions, type Version } from './version/index.js';
 export { requestViewport, Viewport, type RequestViewportResult, type ViewportProps, type ViewportEventName, type ViewportEventListener, type ViewportEvents, } from './viewport/index.js';
-export { setTargetOrigin, setDebug, } from './globals.js';
+export { setTargetOrigin, setDebug } from './globals.js';

package/dist/dts/init/creators/createMiniApp.d.ts

@@ -1,6 +1,7 @@
 import { MiniApp } from '../../mini-app/index.js';
 import type { PostEvent } from '../../bridge/index.js';
 import type { RGB } from '../../colors/index.js';
+import type { CreateRequestIdFunc } from '../../types/index.js';
 import type { Version } from '../../version/index.js';
 /**
  * Creates MiniApp instance using last locally saved data also saving each state in
@@ -9,6 +10,7 @@ import type { Version } from '../../version/index.js';
  * @param backgroundColor - web app background color.
  * @param version - platform version.
  * @param botInline - is Mini App launched in inline mode.
+ * @param createRequestId - function which generates request identifiers.
  * @param postEvent - Bridge postEvent function
  */
-export declare function createMiniApp(isPageReload: boolean, backgroundColor: RGB, version: Version, botInline: boolean, postEvent: PostEvent): MiniApp;
+export declare function createMiniApp(isPageReload: boolean, backgroundColor: RGB, version: Version, botInline: boolean, createRequestId: CreateRequestIdFunc, postEvent: PostEvent): MiniApp;

package/dist/dts/mini-app/MiniApp.d.ts

@@ -1,7 +1,8 @@
 import { type PhoneRequestedStatus, type SwitchInlineQueryChatType, type WriteAccessRequestedStatus } from '../bridge/index.js';
 import { type RGB } from '../colors/index.js';
 import { type SupportsFunc } from '../supports/index.js';
-import type { MiniAppEvents, MiniAppHeaderColor, MiniAppProps } from './types.js';
+import type { ExecuteWithTimeout } from '../types/index.js';
+import type { MiniAppEvents, MiniAppHeaderColor, MiniAppProps, RequestedContact } from './types.js';
 /**
  * Provides common Mini Apps functionality not covered by other system components.
  */
@@ -10,7 +11,14 @@ export declare class MiniApp {
     private readonly state;
     private readonly botInline;
     private readonly postEvent;
+    private readonly createRequestId;
+    private requestingPhoneAccess;
+    private requestingWriteAccess;
     constructor(props: MiniAppProps);
+    /**
+     * Attempts to get requested contact.
+     */
+    private getRequestedContact;
     /**
      * The Mini App background color.
      */
@@ -31,6 +39,14 @@ export declare class MiniApp {
      * True if current Mini App background color recognized as dark.
      */
     get isDark(): boolean;
+    /**
+     * True if phone access is currently being requested.
+     */
+    get isRequestingPhoneAccess(): boolean;
+    /**
+     * True if write access is currently being requested.
+     */
+    get isRequestingWriteAccess(): boolean;
     /**
      * Adds new event listener.
      */
@@ -50,13 +66,27 @@ export declare class MiniApp {
      */
     ready(): void;
     /**
-     * Requests current user phone access.
+     * Requests current user contact information. In contrary to requestPhoneAccess, this method
+     * returns promise with contact information that rejects in case, user denied access, or request
+     * failed.
+     * @param options - additional options.
+     */
+    requestContact({ timeout }?: ExecuteWithTimeout): Promise<RequestedContact>;
+    /**
+     * Requests current user phone access. Method returns promise, which resolves
+     * status of the request. In case, user accepted the request, Mini App bot will receive
+     * the according notification.
+     *
+     * To obtain the retrieved information instead, utilize the requestContact method.
+     * @param options - additional options.
+     * @see requestContact
      */
-    requestPhoneAccess(): Promise<PhoneRequestedStatus>;
+    requestPhoneAccess(options?: ExecuteWithTimeout): Promise<PhoneRequestedStatus>;
     /**
      * Requests write message access to current user.
+     * @param options - additional options.
      */
-    requestWriteAccess(): Promise<WriteAccessRequestedStatus>;
+    requestWriteAccess(options?: ExecuteWithTimeout): Promise<WriteAccessRequestedStatus>;
     /**
      * A method used to send data to the bot. When this method called, a service message sent to
      * the bot containing the data of the length up to 4096 bytes, and the Mini App closed. See the

package/dist/dts/mini-app/contactParser.d.ts

@@ -0,0 +1,2 @@
+import type { RequestedContact } from './types.js';
+export declare const contactParser: import('../parsing/index.js').ValueParser<RequestedContact, false>;

package/dist/dts/mini-app/types.d.ts

@@ -1,12 +1,14 @@
 import type { HeaderColorKey, PostEvent } from '../bridge/index.js';
 import type { RGB } from '../colors/index.js';
 import type { StateEvents } from '../state/index.js';
+import type { CreateRequestIdFunc } from '../types/index.js';
 import type { Version } from '../version/index.js';
 export interface MiniAppProps {
     headerColor: MiniAppHeaderColor;
     backgroundColor: RGB;
     version: Version;
     botInline: boolean;
+    createRequestId: CreateRequestIdFunc;
     postEvent?: PostEvent;
 }
 export type MiniAppHeaderColor = HeaderColorKey | RGB;
@@ -17,3 +19,13 @@ export interface MiniAppState {
 export type MiniAppEvents = StateEvents<MiniAppState>;
 export type MiniAppEventName = keyof MiniAppEvents;
 export type MiniAppEventListener<E extends MiniAppEventName> = MiniAppEvents[E];
+export interface RequestedContact {
+    contact: {
+        userId: number;
+        phoneNumber: string;
+        firstName: string;
+        lastName: string;
+    };
+    authDate: Date;
+    hash: string;
+}

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

@@ -1,3 +1,4 @@
 export * from './isTimeoutError.js';
+export * from './sleep.js';
 export * from './TimeoutError.js';
 export * from './withTimeout.js';

package/dist/dts/timeout/sleep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Awaits for specified amount of time.
+ * @param duration - duration to await.
+ */
+export declare function sleep(duration: number): Promise<void>;

package/dist/dts/timeout/withTimeout.d.ts

@@ -1,14 +1,7 @@
-type AnyAsyncFunction = (...args: any[]) => Promise<any>;
 /**
- * Rejects specified promise in case, it is processed more than timeout seconds.
- * @param promise - wrapped promise.
- * @param timeout - timeout in milliseconds.
+ * Accepts specified function and instantly executes. It waits for timeout milliseconds for
+ * it to complete and throws an error in case, deadline was reached.
+ * @param func - function to execute.
+ * @param timeout - completion timeout.
  */
-export declare function withTimeout<P extends Promise<any>>(promise: P, timeout: number): P;
-/**
- * Wraps async function in function using timeout.
- * @param func - wrapped function.
- * @param timeout - async function timeout.
- */
-export declare function withTimeout<F extends AnyAsyncFunction>(func: F, timeout: number): F;
-export {};
+export declare function withTimeout<T>(func: () => Promise<T>, timeout: number): Promise<T>;

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

@@ -1,3 +1,4 @@
+export * from './methods.js';
 export * from './platform.js';
 export * from './request-id.js';
 export * from './utils.js';

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

@@ -0,0 +1,15 @@
+import type { PostEvent } from '../bridge/index.js';
+export interface ExecuteWithTimeout {
+    /**
+     * Timeout to execute method.
+     */
+    timeout?: number;
+}
+export interface ExecuteWithPostEvent {
+    /**
+     * postEvent function to use to call Telegram Mini Apps methods.
+     */
+    postEvent?: PostEvent;
+}
+export interface ExecuteWithOptions extends ExecuteWithTimeout, ExecuteWithPostEvent {
+}