@tma.js/sdk 0.13.2 → 1.0.0

package/src/init/types.ts

@@ -1,99 +1,81 @@
-import type { PostEvent } from '@tma.js/bridge';
-import type { LaunchParams } from '@tma.js/launch-params';
-
-import type {
-  BackButton,
-  ClosingBehaviour,
-  CloudStorage,
-  HapticFeedback,
-  InitData,
-  MainButton,
-  Popup,
-  QRScanner,
-  ThemeParams,
-  Viewport,
-  WebApp,
-} from '../components/index.js';
+import type { BackButton } from '~/back-button/index.js';
+import type { PostEvent } from '~/bridge/index.js';
+import type { ClosingBehavior } from '~/closing-behavior/index.js';
+import type { CloudStorage } from '~/cloud-storage/index.js';
+import type { HapticFeedback } from '~/haptic-feedback/index.js';
+import type { InitData } from '~/init-data/index.js';
+import type { Invoice } from '~/invoice/index.js';
+import type { MainButton } from '~/main-button/index.js';
+import type { MiniApp } from '~/mini-app/index.js';
+import type { Popup } from '~/popup/index.js';
+import type { QRScanner } from '~/qr-scanner/index.js';
+import type { ThemeParams } from '~/theme-params/index.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
+import type { Utils } from '~/utils/index.js';
+import type { Viewport } from '~/viewport/index.js';
 
 export interface InitResult {
   backButton: BackButton;
-  closingBehavior: ClosingBehaviour;
+  closingBehavior: ClosingBehavior;
   cloudStorage: CloudStorage;
-  haptic: HapticFeedback;
+  createRequestId: CreateRequestIdFunc;
+  hapticFeedback: HapticFeedback;
   initData?: InitData;
   initDataRaw?: string;
+  invoice: Invoice;
   mainButton: MainButton;
+  miniApp: MiniApp;
   popup: Popup;
   postEvent: PostEvent;
   qrScanner: QRScanner;
   themeParams: ThemeParams;
+  utils: Utils;
   viewport: Viewport;
-  webApp: WebApp;
 }
 
 export interface InitCSSVarsSpecificOption {
   /**
-   * Enables theme parameters CSS variables:
-   * - `--tg-theme-bg-color`
-   * - `--tg-theme-button-color`
-   * - `--tg-theme-button-text-color`
-   * - `--tg-theme-hint-color`
-   * - `--tg-theme-link-color`
-   * - `--tg-theme-secondary-bg-color`
-   * - `--tg-theme-text-color`
-   *
-   * @see bindThemeCSSVariables
+   * Enables theme parameters CSS variables.
+   * @see bindThemeCSSVars
+   * @default false
    */
-  themeParams?: true;
+  themeParams?: boolean;
 
   /**
-   * Enables viewport CSS variables:
-   * - `--tg-viewport-height`
-   * - `--tg-viewport-stable-height`
-   *
-   * @see bindViewportCSSVariables
+   * Enables viewport CSS variables.
+   * @see bindViewportCSSVars
+   * @default false
    */
-  viewport?: true;
+  viewport?: boolean;
 
   /**
-   * Enables web app CSS variables:
-   * - `--tg-bg-color`
-   * - `--tg-header-color`
-   *
-   * @see bindWebAppVariables
+   * Enables mini app CSS variables.
+   * @see bindMiniAppCSSVars
+   * @default false
    */
-  webApp?: true;
+  miniApp?: boolean;
 }
 
 export type InitCSSVarsOption = boolean | InitCSSVarsSpecificOption;
 
 export interface InitOptions {
   /**
-   * @deprecated Use acceptCustomStyles
+   * True if synchronization must be performed asynchronously. This allows init function to
+   * perform async operations. One of them is the actual viewport state retrieving from the
+   * Telegram application. Otherwise, viewport state will be retrieved later.
+   * @default false
    */
-  acceptScrollbarStyle?: boolean;
+  async?: boolean;
 
   /**
-   * Should SDK accept styles sent from the Telegram web application.
-   * This option is only used in Web versions of Telegram.
-   *
-   * @default true
+   * True if SDK should accept styles sent from the Telegram web application. This option is only
+   * used in web versions of Telegram.
+   * @default false
    */
   acceptCustomStyles?: boolean;
 
   /**
-   * Should SDK throw an error in case, unsupported by current version of
-   * Mini App method was called. It is highly recommended not to disable this
-   * feature as long as it helps developer to find issues related to usage
-   * of unsupported methods.
-   *
-   * @default true
-   */
-  checkCompat?: boolean;
-
-  /**
-   * Should SDK create global CSS variables related to current Telegram
-   * application colors.
+   * Should SDK create global CSS variables related to current Telegram application colors.
    *
    * Possible values:
    * - `false` - no CSS variables will be created.
@@ -103,31 +85,4 @@ export interface InitOptions {
    * @default false
    */
   cssVars?: InitCSSVarsOption;
-
-  /**
-   * Enable debug mode.
-   *
-   * @default false
-   */
-  debug?: boolean;
-
-  /**
-   * Launch parameters presented as query parameters or already parsed
-   * object. In case, this value is not specified, init
-   * function will try to retrieve launch parameters from window.location.hash
-   * via retrieveLaunchParams function.
-   */
-  launchParams?: string | URLSearchParams | LaunchParams;
-
-  /**
-   * Sets new targetOrigin, used by bridge's `postEvent` function.
-   * @see setTargetOrigin
-   */
-  targetOrigin?: string;
-
-  /**
-   * Initialization process timeout.
-   * @default 1000
-   */
-  timeout?: number;
 }

package/src/init-data/InitData.ts

@@ -0,0 +1,96 @@
+import type {
+  Chat,
+  ChatType,
+  InitDataParsed,
+  User,
+} from './types.js';
+
+/**
+ * Class which is responsible for displaying Mini Apps init data.
+ */
+export class InitData {
+  constructor(private readonly initData: InitDataParsed) {
+  }
+
+  /**
+   * @see InitDataParsed.authDate
+   */
+  get authDate(): Date {
+    return this.initData.authDate;
+  }
+
+  /**
+   * @see InitDataParsed.canSendAfter
+   */
+  get canSendAfter(): number | undefined {
+    return this.initData.canSendAfter;
+  }
+
+  /**
+   * Date after which it is allowed to call
+   * the [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
+   */
+  get canSendAfterDate(): Date | undefined {
+    const { canSendAfter } = this;
+
+    return canSendAfter === undefined
+      ? undefined
+      : new Date(this.authDate.getTime() + canSendAfter * 1000);
+  }
+
+  /**
+   * @see InitDataParsed.chat
+   */
+  get chat(): Chat | undefined {
+    return this.initData.chat;
+  }
+
+  /**
+   * @see InitDataParsed.chatType
+   */
+  get chatType(): ChatType | undefined {
+    return this.initData.chatType;
+  }
+
+  /**
+   * @see InitDataParsed.chatInstance
+   */
+  get chatInstance(): string | undefined {
+    return this.initData.chatInstance;
+  }
+
+  /**
+   * @see InitDataParsed.hash
+   */
+  get hash(): string {
+    return this.initData.hash;
+  }
+
+  /**
+   * @see InitDataParsed.queryId
+   */
+  get queryId(): string | undefined {
+    return this.initData.queryId;
+  }
+
+  /**
+   * @see InitDataParsed.receiver
+   */
+  get receiver(): User | undefined {
+    return this.initData.receiver;
+  }
+
+  /**
+   * @see InitDataParsed.startParam
+   */
+  get startParam(): string | undefined {
+    return this.initData.startParam;
+  }
+
+  /**
+   * @see InitDataParsed.user
+   */
+  get user(): User | undefined {
+    return this.initData.user;
+  }
+}

package/src/init-data/chatParser.ts

@@ -0,0 +1,19 @@
+import { json, number, string } from '~/parsing/index.js';
+
+import type { Chat } from './types.js';
+
+/**
+ * Returns parser used to parse chat data.
+ */
+export function chatParser() {
+  return json<Chat>({
+    id: number(),
+    type: string(),
+    title: string(),
+    photoUrl: {
+      type: string().optional(),
+      from: 'photo_url',
+    },
+    username: string().optional(),
+  }, 'Chat');
+}

package/src/init-data/index.ts

@@ -0,0 +1,6 @@
+export * from './chatParser.js';
+export * from './InitData.js';
+export * from './initDataParser.js';
+export * from './parseInitData.js';
+export * from './types.js';
+export * from './userParser.js';

package/src/init-data/initDataParser.ts

@@ -0,0 +1,41 @@
+import { date, number, searchParams, string } from '~/parsing/index.js';
+
+import { chatParser } from './chatParser.js';
+import type { InitDataParsed } from './types.js';
+import { userParser } from './userParser.js';
+
+/**
+ * Returns parser used to parse init data, presented as search params.
+ */
+export function initDataParser() {
+  return searchParams<InitDataParsed>({
+    authDate: {
+      type: date(),
+      from: 'auth_date',
+    },
+    canSendAfter: {
+      type: number().optional(),
+      from: 'can_send_after',
+    },
+    chat: chatParser().optional(),
+    chatInstance: {
+      type: string().optional(),
+      from: 'chat_instance',
+    },
+    chatType: {
+      type: string().optional(),
+      from: 'chat_type',
+    },
+    hash: string(),
+    queryId: {
+      type: string().optional(),
+      from: 'query_id',
+    },
+    receiver: userParser().optional(),
+    startParam: {
+      type: string().optional(),
+      from: 'start_param',
+    },
+    user: userParser().optional(),
+  }, 'InitData');
+}

package/src/init-data/parseInitData.ts

@@ -0,0 +1,10 @@
+import { initDataParser } from './initDataParser.js';
+import type { InitDataParsed } from './types.js';
+
+/**
+ * Parses incoming value as init data.
+ * @param value - value to parse.
+ */
+export function parseInitData(value: unknown): InitDataParsed {
+  return initDataParser().parse(value);
+}

package/src/init-data/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Known type of chat.
+ */
+export type ChatType =
+  | 'sender'
+  | 'private'
+  | 'group'
+  | 'supergroup'
+  | 'channel'
+  | string;
+
+/**
+ * Describes Telegram Mini Apps [User](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#user) type.
+ */
+export interface User {
+  /**
+   * True, if this user added the bot to the attachment menu.
+   */
+  addedToAttachmentMenu?: boolean;
+
+  /**
+   * True, if this user allowed the bot to message them.
+   */
+  allowsWriteToPm?: boolean;
+
+  /**
+   * First name of the user or bot.
+   */
+  firstName: string;
+
+  /**
+   * A unique identifier for the user or bot.
+   */
+  id: number;
+
+  /**
+   * True, if this user is a bot. Returned in the `receiver` field only.
+   * @see InitDataParsed.receiver
+   */
+  isBot?: boolean;
+
+  /**
+   * True, if this user is a Telegram Premium user.
+   */
+  isPremium?: boolean;
+
+  /**
+   * Last name of the user or bot.
+   */
+  lastName?: string;
+
+  /**
+   * [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) of the user's language.
+   * Returns in user field only.
+   */
+  languageCode?: string;
+
+  /**
+   * URL of the user’s profile photo. The photo can be in .jpeg or .svg
+   * formats. Only returned for Mini Apps launched from the attachment menu.
+   */
+  photoUrl?: string;
+
+  /**
+   * Username of the user or bot.
+   */
+  username?: string;
+}
+
+/**
+ * Describes Telegram Mini Apps [Chat](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#chat) type.
+ */
+export interface Chat {
+  /**
+   * Unique identifier for this chat.
+   */
+  id: number;
+
+  /**
+   * URL of the chat’s photo. The photo can be in .jpeg or .svg formats.
+   * Only returned for Mini Apps launched from the attachment menu.
+   */
+  photoUrl?: string;
+
+  /**
+   * Type of chat.
+   */
+  type: 'group' | 'supergroup' | 'channel' | string;
+
+  /**
+   * Title of the chat.
+   */
+  title: string;
+
+  /**
+   * Username of the chat.
+   */
+  username?: string;
+}
+
+/**
+ * Describes Telegram Mini Apps [InitData](https://docs.telegram-mini-apps.com/platform/launch-parameters/init-data#parameters-list)
+ * type.
+ */
+export interface InitDataParsed {
+  /**
+   * Init data generation date.
+   */
+  authDate: Date;
+
+  /**
+   * The number of seconds after which a message can be sent via the method [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery).
+   */
+  canSendAfter?: number;
+
+  /**
+   * 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.
+   */
+  chat?: Chat;
+
+  /**
+   * The type of chat from which Mini App was opened.
+   */
+  chatType?: ChatType;
+
+  /**
+   * A global identifier indicating the chat from which Mini App was opened. Returned only for
+   * applications opened by direct link.
+   */
+  chatInstance?: string;
+
+  /**
+   * A hash of all passed parameters, which the bot server can use to
+   * check their [validity](https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app).
+   */
+  hash: string;
+
+  /**
+   * A unique identifier for the Mini App session, required for sending
+   * messages via the [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
+   */
+  queryId?: string;
+
+  /**
+   * 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.
+   */
+  receiver?: User;
+
+  /**
+   * The value of the `startattach` parameter, passed via link. Only returned for
+   * Mini Apps when launched from the attachment menu via link.
+   */
+  startParam?: string;
+
+  /**
+   * An object containing data about the current user.
+   */
+  user?: User;
+}

package/src/init-data/userParser.ts

@@ -0,0 +1,45 @@
+import { boolean, json, number, string } from '~/parsing/index.js';
+
+import type { User } from './types.js';
+
+/**
+ * Returns parser used to parse user data.
+ */
+export function userParser() {
+  return json<User>({
+    addedToAttachmentMenu: {
+      type: boolean().optional(),
+      from: 'added_to_attachment_menu',
+    },
+    allowsWriteToPm: {
+      type: boolean().optional(),
+      from: 'allows_write_to_pm',
+    },
+    firstName: {
+      type: string(),
+      from: 'first_name',
+    },
+    id: number(),
+    isBot: {
+      type: boolean().optional(),
+      from: 'is_bot',
+    },
+    isPremium: {
+      type: boolean().optional(),
+      from: 'is_premium',
+    },
+    languageCode: {
+      type: string().optional(),
+      from: 'language_code',
+    },
+    lastName: {
+      type: string().optional(),
+      from: 'last_name',
+    },
+    photoUrl: {
+      type: string().optional(),
+      from: 'photo_url',
+    },
+    username: string().optional(),
+  }, 'User');
+}

package/src/invoice/Invoice.ts

@@ -0,0 +1,123 @@
+import {
+  type InvoiceStatus,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  request,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import {
+  createSupportsFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
+
+import type { InvoiceEvents, InvoiceState } from './types.js';
+
+/**
+ * Extracts invoice slug from URL.
+ * @param url - url to extract slug from.
+ */
+function slugFromUrl(url: string): string {
+  const { hostname, pathname } = new URL(url, window.location.href);
+  if (hostname !== 't.me') {
+    throw new Error(`Incorrect hostname: ${hostname}`);
+  }
+
+  // Valid examples:
+  // "/invoice/my-slug"
+  // "/$my-slug"
+  const match = pathname.match(/^\/(\$|invoice\/)([A-Za-z0-9\-_=]+)$/);
+
+  if (match === null) {
+    // eslint-disable-next-line no-template-curly-in-string
+    throw new Error('Link pathname has incorrect format. Expected to receive "/invoice/{slug}" or "/${slug}"');
+  }
+  return match[2];
+}
+
+/**
+ * Controls currently displayed invoice.
+ */
+export class Invoice {
+  private readonly ee = new EventEmitter<InvoiceEvents>();
+
+  private readonly state: State<InvoiceState>;
+
+  constructor(
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({ isOpened: false }, this.ee);
+    this.supports = createSupportsFunc(version, { open: 'web_app_open_invoice' });
+  }
+
+  private set isOpened(value) {
+    this.state.set('isOpened', value);
+  }
+
+  /**
+   * True if invoice is currently opened.
+   */
+  get isOpened(): boolean {
+    return this.state.get('isOpened');
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+
+  /**
+   * Opens an invoice using its slug.
+   * @param slug - invoice slug.
+   * @throws {Error} Invoice is already opened.
+   */
+  open(slug: string): Promise<InvoiceStatus>;
+
+  /**
+   * Opens an invoice using its url. It expects passing link in full format, with hostname "t.me".
+   * @param url - invoice URL.
+   * @param type - value type.
+   * @throws {Error} Invoice is already opened.
+   */
+  open(url: string, type: 'url'): Promise<InvoiceStatus>;
+
+  async open(urlOrSlug: string, type?: 'url'): Promise<InvoiceStatus> {
+    if (this.isOpened) {
+      throw new Error('Invoice is already opened');
+    }
+
+    const slug = type ? slugFromUrl(urlOrSlug) : urlOrSlug;
+
+    this.isOpened = true;
+
+    try {
+      const result = await request(
+        'web_app_open_invoice',
+        { slug },
+        'invoice_closed',
+        {
+          postEvent: this.postEvent,
+          capture(data) {
+            return slug === data.slug;
+          },
+        },
+      );
+
+      return result.status;
+    } finally {
+      this.isOpened = false;
+    }
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'open'>;
+}

package/src/invoice/index.ts

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

package/src/invoice/types.ts

@@ -0,0 +1,11 @@
+import type { StateEvents } from '~/state/index.js';
+
+export interface InvoiceState {
+  isOpened: boolean;
+}
+
+export type InvoiceEvents = StateEvents<InvoiceState>;
+
+export type InvoiceEventName = keyof InvoiceEvents;
+
+export type InvoiceEventListener<E extends InvoiceEventName> = InvoiceEvents[E];