@tma.js/sdk 0.13.3 → 1.0.0

package/src/types/index.ts

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

package/src/types/platform.ts

@@ -0,0 +1,14 @@
+/**
+ * Telegram application platform name.
+ */
+export type Platform =
+  | 'android'
+  | 'android_x'
+  | 'ios'
+  | 'macos'
+  | 'tdesktop'
+  | 'web'
+  | 'weba'
+  | 'unigram'
+  | 'unknown'
+  | string;

package/src/types/request-id.ts

@@ -0,0 +1,10 @@
+/**
+ * Request identifier which should be generated locally. Native Telegram application
+ * uses it to generate a response to called method.
+ */
+export type RequestId = string;
+
+/**
+ * Function which generates unique request identifiers.
+ */
+export type CreateRequestIdFunc = () => RequestId;

package/src/types/utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Returns true in case, T is never.
+ */
+export type IsNever<T> = [T] extends [never] ? true : false;
+
+/**
+ * Represents classic "if" condition.
+ */
+export type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
+
+/**
+ * Represents classic "not" bitwise operation.
+ */
+export type Not<Cond extends boolean> = If<Cond, false, true>;
+
+/**
+ * Represents classic "and" bitwise operation.
+ */
+export type And<A extends boolean, B extends boolean> = A extends true
+  ? B extends true
+    ? true
+    : false
+  : false;
+
+/**
+ * Represents classic "or" bitwise operation.
+ */
+export type Or<A extends boolean, B extends boolean> = A extends true
+  ? true
+  : (B extends true ? true : false);
+
+/**
+ * True if value includes undefined.
+ */
+export type HasUndefined<T> = undefined extends T ? true : false;
+
+/**
+ * Returns true if specified property in type is marked as optional.
+ */
+export type IsOptional<Type, Key extends keyof Type> = {} extends Pick<Type, Key> ? true : false;
+
+/**
+ * Returns union object keys.
+ */
+export type UnionKeys<T> = T extends T ? keyof T : never;
+
+/**
+ * Returns object string keys.
+ */
+export type StringKeys<T extends object> = Extract<keyof T, string>;

package/src/utils/Utils.ts

@@ -0,0 +1,107 @@
+import {
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  request,
+} from '~/bridge/index.js';
+import {
+  createSupportsFunc,
+  createSupportsParamFunc,
+  supports,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
+import type { Version } from '~/version/index.js';
+
+/**
+ * Provides common Mini Apps functionality not covered by other system components.
+ */
+export class Utils {
+  constructor(
+    private readonly version: Version,
+    private readonly createRequestId: CreateRequestIdFunc,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.supports = createSupportsFunc(version, {
+      readTextFromClipboard: 'web_app_read_text_from_clipboard',
+    });
+
+    this.supportsParam = createSupportsParamFunc(version, {
+      'openLink.tryInstantView': ['web_app_open_link', 'try_instant_view'],
+    });
+  }
+
+  /**
+   * Opens a link in an external browser. The Mini App will not be closed.
+   *
+   * Note that this method can be called only in response to the user
+   * interaction with the Mini App interface (e.g. click inside the Mini App
+   * or on the main button).
+   * @param url - URL to be opened.
+   * @param tryInstantView
+   */
+  openLink(url: string, tryInstantView?: boolean): void {
+    const formattedUrl = new URL(url, window.location.href).toString();
+
+    // If method is not supported, we are doing it in legacy way.
+    if (!supports('web_app_open_link', this.version)) {
+      window.open(formattedUrl, '_blank');
+      return;
+    }
+
+    // Otherwise, do it normally.
+    this.postEvent('web_app_open_link', {
+      url: formattedUrl,
+      ...(typeof tryInstantView === 'boolean' ? { try_instant_view: tryInstantView } : {}),
+    });
+  }
+
+  /**
+   * Opens a Telegram link inside Telegram app. The Mini App will be closed. It expects passing
+   * link in full format, with hostname "t.me".
+   * @param url - URL to be opened.
+   * @throws {Error} URL has not allowed hostname.
+   */
+  openTelegramLink(url: string): void {
+    const {
+      hostname,
+      pathname,
+      search,
+    } = new URL(url, window.location.href);
+
+    if (hostname !== 't.me') {
+      throw new Error(`URL has not allowed hostname: ${hostname}. Only "t.me" is allowed`);
+    }
+
+    if (!supports('web_app_open_tg_link', this.version)) {
+      window.location.href = url;
+      return;
+    }
+
+    this.postEvent('web_app_open_tg_link', { path_full: pathname + search });
+  }
+
+  /**
+   * Reads text from clipboard and returns string or null. null is returned
+   * in cases:
+   * - Value in clipboard is not text
+   * - Access to clipboard is not allowed
+   */
+  readTextFromClipboard(): Promise<string | null> {
+    return request(
+      'web_app_read_text_from_clipboard',
+      { req_id: this.createRequestId() },
+      'clipboard_text_received',
+      { postEvent: this.postEvent },
+    ).then(({ data = null }) => data);
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'readTextFromClipboard'>;
+
+  /**
+   * Checks if specified method parameter is supported by current component.
+   */
+  supportsParam: SupportsFunc<'openLink.tryInstantView'>;
+}

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './Utils.js';

package/src/version/compareVersions.ts

@@ -0,0 +1,28 @@
+/**
+ * Returns 1 in case, version "a" is greater than "b".
+ * Returns 0 in case, version "a" equal to "b".
+ * Returns -1 in case, version "a" is lower than "b".
+ * @param a - first version.
+ * @param b - second version.
+ */
+export function compareVersions(a: string, b: string): number {
+  // Split both of the version by dot.
+  const aParts = a.split('.');
+  const bParts = b.split('.');
+
+  // Compute maximum length.
+  const len = Math.max(aParts.length, bParts.length);
+
+  // Iterate over each part of version and compare them. In case, part is
+  // missing, assume its value is equal to 0.
+  for (let i = 0; i < len; i += 1) {
+    const aVal = parseInt(aParts[i] || '0', 10);
+    const bVal = parseInt(bParts[i] || '0', 10);
+
+    if (aVal === bVal) {
+      continue;
+    }
+    return aVal > bVal ? 1 : -1;
+  }
+  return 0;
+}

package/src/version/index.ts

@@ -0,0 +1,2 @@
+export * from './compareVersions.js';
+export * from './types.js';

package/src/version/types.ts

@@ -0,0 +1,4 @@
+/**
+ * Telegram Mini Apps version in format like "\d+.\d+".
+ */
+export type Version = string;

package/src/{components/Viewport → viewport}/Viewport.ts

@@ -1,100 +1,40 @@
-import { EventEmitter } from '@tma.js/event-emitter';
-import { on, postEvent as defaultPostEvent, request, type RequestOptions, type PostEvent } from '@tma.js/bridge';
-
-import { State } from '../../state/index.js';
-
-import type { ViewportEvents, ViewportState } from './types.js';
-
-export interface RequestViewportResult {
-  height: number;
-  isStateStable: boolean;
-  isExpanded: boolean;
-  width: number;
-}
-
-/**
- * Formats value to make it stay in bounds [0, +Inf).
- * @param value - value to format.
- */
-function truncate(value: number): number {
-  return value < 0 ? 0 : value;
-}
+import {
+  on,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  type RequestOptions,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import { requestViewport } from '~/viewport/requestViewport.js';
+
+import type {
+  ViewportEvents,
+  ViewportProps,
+  ViewportState,
+} from './types.js';
+import { truncate } from './utils.js';
 
 /**
  * Contains information about current WebApp device viewport, its dimensions
  * and state.
  */
 export class Viewport {
-  /**
-   * Requests fresh information about current viewport.
-   * FIXME: Be careful using this function in desktop version of Telegram as
-   *  long as method web_app_request_viewport does not work on `macos` platform.
-   * @see Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/5
-   * @param options - method options.
-   */
-  static async request(options: RequestOptions = {}): Promise<RequestViewportResult> {
-    const { timeout = 1000, ...restOptions } = options;
-    const {
-      is_expanded: isExpanded,
-      is_state_stable: isStateStable,
-      ...rest
-    } = await request('web_app_request_viewport', 'viewport_changed', {
-      ...restOptions,
-      timeout,
-    });
-
-    return { ...rest, isExpanded, isStateStable };
-  }
-
-  /**
-   * Synchronizes specified instance of Viewport with the actual value in the native
-   * application.
-   * @param viewport - Viewport instance.
-   */
-  static sync(viewport: Viewport): void {
-    on('viewport_changed', (event) => {
-      const {
-        height,
-        width,
-        is_expanded: isExpanded,
-        is_state_stable: isStateStable,
-      } = event;
-      const formattedHeight = truncate(height);
-
-      viewport.state.set({
-        height: formattedHeight,
-        isExpanded,
-        width: truncate(width),
-        stableHeight: isStateStable ? formattedHeight : undefined,
-      });
-    });
-  }
-
-  /**
-   * Returns initialized instance of Viewport which is synchronized with
-   * its actual state in Mini Apps.
-   * @param options - method options.
-   */
-  static async synced(options: RequestOptions = {}): Promise<Viewport> {
-    const { height, isExpanded, width } = await this.request(options);
-    const viewport = new Viewport(height, width, height, isExpanded, options.postEvent);
-
-    this.sync(viewport);
-
-    return viewport;
-  }
-
   private readonly ee = new EventEmitter<ViewportEvents>();
 
   private readonly state: State<ViewportState>;
 
-  constructor(
-    height: number,
-    width: number,
-    stableHeight: number,
-    isExpanded: boolean,
-    private readonly postEvent: PostEvent = defaultPostEvent,
-  ) {
+  private readonly postEvent: PostEvent;
+
+  constructor(props: ViewportProps) {
+    const {
+      height,
+      isExpanded,
+      width,
+      stableHeight,
+      postEvent = defaultPostEvent,
+    } = props;
+    this.postEvent = postEvent;
     this.state = new State({
       height: truncate(height),
       isExpanded,
@@ -103,6 +43,22 @@ export class Viewport {
     }, this.ee);
   }
 
+  /**
+   * Request viewport information from the Telegram application and updates current Viewport
+   * instance.
+   * @param options - options to request fresh data.
+   */
+  sync(options?: RequestOptions): Promise<void> {
+    return requestViewport(options).then(({ height, isExpanded, width, isStateStable }) => {
+      this.state.set({
+        height,
+        width,
+        isExpanded,
+        stableHeight: isStateStable ? height : this.state.get('stableHeight'),
+      });
+    });
+  }
+
   /**
    * The current height of the visible area of the Mini App.
    *
@@ -118,10 +74,6 @@ export class Viewport {
    * used to pin interface elements to the bottom of the visible area. It's
    * more appropriate to use the value of the `stableHeight`
    * field for this purpose.
-   *
-   * @see init
-   * @see expand
-   * @see stableHeight
    */
   get height(): number {
     return this.state.get('height');
@@ -140,15 +92,37 @@ export class Viewport {
    * gestures or during animations. The value of `stableHeight`
    * will be updated after all gestures and animations are completed and
    * the Mini App reaches its final size.
-   *
-   * @see init
-   * @see expand
-   * @see height
    */
   get stableHeight(): number {
     return this.state.get('stableHeight');
   }
 
+  /**
+   * Starts listening to viewport changes and applies them.
+   * @returns Function to stop listening.
+   */
+  listen() {
+    return on('viewport_changed', (event) => {
+      const {
+        height,
+        width,
+        is_expanded: isExpanded,
+        is_state_stable: isStateStable,
+      } = event;
+      const state: Partial<ViewportState> = {
+        height: truncate(height),
+        isExpanded,
+        width: truncate(width),
+      };
+
+      if (isStateStable) {
+        state.stableHeight = state.height;
+      }
+
+      this.state.set(state);
+    });
+  }
+
   /**
    * Returns true if the Mini App is expanded to the maximum available height.
    * Otherwise, if the Mini App occupies part of the screen and can be expanded
@@ -173,8 +147,8 @@ export class Viewport {
    * @see isExpanded
    */
   expand(): void {
-    this.state.set('isExpanded', true);
     this.postEvent('web_app_expand');
+    this.state.set('isExpanded', true);
   }
 
   /**
@@ -188,10 +162,10 @@ export class Viewport {
   /**
    * Adds new event listener.
    */
-  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+  on = this.ee.on.bind(this.ee);
 
   /**
    * Removes event listener.
    */
-  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+  off = this.ee.off.bind(this.ee);
 }

package/src/viewport/index.ts

@@ -0,0 +1,3 @@
+export * from './requestViewport.js';
+export * from './types.js';
+export * from './Viewport.js';

package/src/viewport/requestViewport.ts

@@ -0,0 +1,23 @@
+import { request, type RequestOptions } from '~/bridge/index.js';
+
+export interface RequestViewportResult {
+  height: number;
+  isStateStable: boolean;
+  isExpanded: boolean;
+  width: number;
+}
+
+/**
+ * Requests viewport actual information from the Telegram application.
+ * @param options - request options.
+ */
+export async function requestViewport(options?: RequestOptions): Promise<RequestViewportResult> {
+  const data = await request('web_app_request_viewport', 'viewport_changed', options);
+
+  return {
+    height: data.height,
+    width: data.width,
+    isExpanded: data.is_expanded,
+    isStateStable: data.is_state_stable,
+  };
+}

package/src/{components/Viewport → viewport}/types.ts

@@ -1,4 +1,13 @@
-import type { StateEvents } from '../../state/index.js';
+import type { PostEvent } from '~/bridge/index.js';
+import type { StateEvents } from '~/state/index.js';
+
+export interface ViewportProps {
+  height: number;
+  width: number;
+  stableHeight: number;
+  isExpanded: boolean;
+  postEvent?: PostEvent;
+}
 
 export interface ViewportState {
   height: number;

package/src/viewport/utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Formats value to make it stay in bounds [0, +Inf).
+ * @param value - value to format.
+ */
+export function truncate(value: number): number {
+  return value < 0 ? 0 : value;
+}

package/dist/dts/components/BackButton/index.d.ts

@@ -1,2 +0,0 @@
-export * from './BackButton.js';
-export type { BackButtonEventListener, BackButtonEventName, BackButtonEvents } from './types.js';

package/dist/dts/components/ClosingBehaviour/index.d.ts

@@ -1,2 +0,0 @@
-export * from './ClosingBehaviour.js';
-export type { ClosingBehaviourEventName, ClosingBehaviourEventListener, ClosingBehaviourEvents, } from './types.js';

package/dist/dts/components/ClosingBehaviour/types.d.ts

@@ -1,7 +0,0 @@
-import type { StateEvents } from '../../state/index.js';
-export interface ClosingBehaviourState {
-    isConfirmationNeeded: boolean;
-}
-export type ClosingBehaviourEvents = StateEvents<ClosingBehaviourState>;
-export type ClosingBehaviourEventName = keyof ClosingBehaviourEvents;
-export type ClosingBehaviourEventListener<E extends ClosingBehaviourEventName> = ClosingBehaviourEvents[E];

package/dist/dts/components/InitData/InitData.d.ts

@@ -1,60 +0,0 @@
-import type { Chat, ChatType, InitData as InitDataType, User } from '@tma.js/init-data';
-/**
- * Class which is responsible for displaying Mini Apps init data.
- */
-export declare class InitData {
-    private readonly state;
-    constructor(authDate: Date, hash: string, options?: Omit<InitDataType, 'authDate' | 'hash'>);
-    /**
-     * Init data generation date.
-     */
-    get authDate(): Date;
-    /**
-     * Date after which a message can be sent via the
-     * [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
-     */
-    get canSendAfter(): Date | null;
-    /**
-     * An object containing data about the chat where the bot was launched via the attachment
-     * menu. Returned for supergroups, channels and group chats – only for Mini Apps launched via
-     * the attachment menu.
-     */
-    get chat(): Chat | null;
-    /**
-     * The type of chat from which Mini App was opened.
-     */
-    get chatType(): ChatType | null;
-    /**
-     * A global identifier indicating the chat from which Mini App was opened. Returned only for
-     * applications opened by direct link.
-     */
-    get chatInstance(): string | null;
-    /**
-     * A hash of all passed parameters, which the bot server can use to
-     * check their validity.
-     * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app
-     */
-    get hash(): string;
-    /**
-     * A unique identifier for the Mini App session, required for sending
-     * messages via the `answerWebAppQuery` method.
-     * @see https://core.telegram.org/bots/api#answerwebappquery
-     */
-    get queryId(): string | null;
-    /**
-     * An object containing data about the chat partner of the current
-     * user in the chat where the bot was launched via the attachment menu.
-     * Returned only for private chats and only for Mini Apps launched
-     * via the attachment menu.
-     */
-    get receiver(): User | null;
-    /**
-     * The value of the `startattach` parameter, passed via link. Only
-     * returned for Mini Apps when launched from the attachment menu via link.
-     */
-    get startParam(): string | null;
-    /**
-     * An object containing data about the current user.
-     */
-    get user(): User | null;
-}

package/dist/dts/components/InitData/index.d.ts

@@ -1 +0,0 @@
-export * from './InitData.js';