@tma.js/sdk 0.13.3 → 1.0.1

package/src/bridge/events/parsers/customMethodInvoked.ts

@@ -0,0 +1,25 @@
+import { json, string } from '~/parsing/index.js';
+import type { RequestId } from '~/types/index.js';
+
+export interface CustomMethodInvokedPayload<R = unknown> {
+  /**
+   * Unique identifier of this invocation.
+   */
+  req_id: RequestId;
+  /**
+   * Method invocation successful result.
+   */
+  result?: R;
+  /**
+   * Method invocation error code.
+   */
+  error?: string;
+}
+
+export function customMethodInvoked() {
+  return json<CustomMethodInvokedPayload>({
+    req_id: string(),
+    result: (value) => value,
+    error: string().optional(),
+  });
+}

package/src/bridge/events/parsers/index.ts

@@ -0,0 +1,9 @@
+export * from './clipboardTextReceived.js';
+export * from './customMethodInvoked.js';
+export * from './invoiceClosed.js';
+export * from './phoneRequested.js';
+export * from './popupClosed.js';
+export * from './qrTextReceived.js';
+export * from './theme-changed.js';
+export * from './viewportChanged.js';
+export * from './writeAccessRequested.js';

package/src/bridge/events/parsers/invoiceClosed.ts

@@ -0,0 +1,26 @@
+import { json, string } from '~/parsing/index.js';
+
+export type InvoiceStatus =
+  | 'paid'
+  | 'failed'
+  | 'pending'
+  | 'cancelled'
+  | string;
+
+export interface InvoiceClosedPayload {
+  /**
+   * Passed during the `web_app_open_invoice` method invocation `slug` value.
+   */
+  slug: string;
+  /**
+   * Invoice status
+   */
+  status: InvoiceStatus;
+}
+
+export function invoiceClosed() {
+  return json<InvoiceClosedPayload>({
+    slug: string(),
+    status: string(),
+  });
+}

package/src/bridge/events/parsers/phoneRequested.ts

@@ -0,0 +1,14 @@
+import { json, string } from '~/parsing/index.js';
+
+export type PhoneRequestedStatus = 'sent' | string;
+
+export interface PhoneRequestedPayload {
+  /**
+   * Request status.
+   */
+  status: PhoneRequestedStatus;
+}
+
+export function phoneRequested() {
+  return json<PhoneRequestedPayload>({ status: string() });
+}

package/src/bridge/events/parsers/popupClosed.ts

@@ -0,0 +1,19 @@
+import { json, string } from '~/parsing/index.js';
+
+export interface PopupClosedPayload {
+  /**
+   * Identifier of the clicked button. In case, the popup was closed without clicking any button,
+   * this property will be omitted.
+   */
+  button_id?: string;
+}
+
+export function popupClosed() {
+  return json<PopupClosedPayload>({
+    button_id: (value) => (
+      value === null || value === undefined
+        ? undefined
+        : string().parse(value)
+    ),
+  });
+}

package/src/bridge/events/parsers/qrTextReceived.ts

@@ -0,0 +1,14 @@
+import { json, string } from '~/parsing/index.js';
+
+export interface QrTextReceivedPayload {
+  /**
+   * Data extracted from the QR.
+   */
+  data?: string;
+}
+
+export function qrTextReceived() {
+  return json<QrTextReceivedPayload>({
+    data: string().optional(),
+  });
+}

package/src/bridge/events/parsers/theme-changed.ts

@@ -0,0 +1,58 @@
+import { json, rgb, toRecord } from '~/parsing/index.js';
+import type { RGB } from '~/colors/index.js';
+
+export interface ThemeChangedPayload {
+  /**
+   * Map where the key is a theme stylesheet key and value is  the corresponding color in
+   * `#RRGGBB` format.
+   */
+  theme_params: {
+    /**
+     * @since v6.10
+     */
+    accent_text_color?: RGB;
+    bg_color?: RGB;
+    button_color?: RGB;
+    button_text_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    destructive_text_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    header_bg_color?: RGB;
+    hint_color?: RGB;
+    link_color?: RGB;
+    secondary_bg_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    section_bg_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    section_header_text_color?: RGB;
+    /**
+     * @since v6.10
+     */
+    subtitle_text_color?: RGB;
+    text_color?: RGB;
+    [key: string]: RGB | undefined; // Future unknown palette keys.
+  };
+}
+
+export function themeChanged() {
+  return json<ThemeChangedPayload>({
+    theme_params: (value) => {
+      const parser = rgb().optional();
+
+      return Object
+        .entries(toRecord(value))
+        .reduce<Partial<Record<string, RGB>>>((acc, [k, v]) => {
+        acc[k] = parser.parse(v);
+        return acc;
+      }, {});
+    },
+  });
+}

package/src/bridge/events/parsers/viewportChanged.ts

@@ -0,0 +1,33 @@
+import { boolean, json, number } from '~/parsing/index.js';
+
+export interface ViewportChangedPayload {
+  /**
+   * The viewport height.
+   */
+  height: number;
+  /**
+   * The viewport width.
+   */
+  width: number;
+  /**
+   * Is the viewport currently expanded.
+   */
+  is_expanded: boolean;
+  /**
+   * Is the viewport current state stable and not going to change in the next moment.
+   */
+  is_state_stable: boolean;
+}
+
+export function viewportChanged() {
+  return json<ViewportChangedPayload>({
+    height: number(),
+    width: (value) => (
+      value === null || value === undefined
+        ? window.innerWidth
+        : number().parse(value)
+    ),
+    is_state_stable: boolean(),
+    is_expanded: boolean(),
+  });
+}

package/src/bridge/events/parsers/writeAccessRequested.ts

@@ -0,0 +1,14 @@
+import { json, string } from '~/parsing/index.js';
+
+export type WriteAccessRequestedStatus = 'allowed' | string;
+
+export interface WriteAccessRequestedPayload {
+  /**
+   * Request status.
+   */
+  status: WriteAccessRequestedStatus;
+}
+
+export function writeAccessRequested() {
+  return json<WriteAccessRequestedPayload>({ status: string() });
+}

package/src/bridge/events/singletonEmitter.ts

@@ -0,0 +1,19 @@
+import { createEmitter } from '~/bridge/events/createEmitter.js';
+import type { MiniAppsEventEmitter } from '~/bridge/index.js';
+
+const CACHED_EMITTER = 'telegram-mini-apps-cached-emitter';
+
+/**
+ * Returns singleton instance of bridge EventEmitter. Also, defines
+ * Telegram event handlers.
+ */
+export function singletonEmitter(): MiniAppsEventEmitter {
+  const wnd: any = window;
+  const cachedEmitter = wnd[CACHED_EMITTER];
+
+  if (cachedEmitter === undefined) {
+    wnd[CACHED_EMITTER] = createEmitter();
+  }
+
+  return wnd[CACHED_EMITTER];
+}

package/src/bridge/events/subscribe.ts

@@ -0,0 +1,15 @@
+import type { MiniAppsGlobalEventListener } from './events.js';
+import { singletonEmitter } from './singletonEmitter.js';
+import { unsubscribe } from './unsubscribe.js';
+
+type StopListening = () => void;
+
+/**
+ * Subscribes to all events sent from the native Telegram application.
+ * Returns function used to remove added event listener.
+ * @param listener - event listener.
+ */
+export function subscribe(listener: MiniAppsGlobalEventListener): StopListening {
+  singletonEmitter().subscribe(listener);
+  return () => unsubscribe(listener);
+}

package/src/bridge/events/unsubscribe.ts

@@ -0,0 +1,10 @@
+import type { MiniAppsGlobalEventListener } from './events.js';
+import { singletonEmitter } from './singletonEmitter.js';
+
+/**
+ * Removes global event listener.
+ * @param listener - event listener.
+ */
+export function unsubscribe(listener: MiniAppsGlobalEventListener): void {
+  singletonEmitter().unsubscribe(listener);
+}

package/src/bridge/index.ts

@@ -0,0 +1,5 @@
+export * from './env/index.js';
+export * from './errors/index.js';
+export * from './events/index.js';
+export * from './methods/index.js';
+export * from './request.js';

package/src/bridge/methods/createPostEvent.ts

@@ -0,0 +1,40 @@
+import { isRecord } from '~/misc/index.js';
+import { supports } from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
+
+import { type PostEvent, postEvent } from './postEvent.js';
+import { MethodUnsupportedError, ParameterUnsupportedError } from '../errors/index.js';
+
+/**
+ * Creates function which checks if specified method and parameters are supported. In case,
+ * method or parameters are unsupported, an error will be thrown.
+ * @param version - Telegram Mini Apps version.
+ * @throws {MethodUnsupportedError} Method is unsupported.
+ * @throws {ParameterUnsupportedError} Method parameter is unsupported.
+ */
+export function createPostEvent(version: Version): PostEvent {
+  return (method: any, params: any) => {
+    // Firstly, check if method itself is supported.
+    if (!supports(method, version)) {
+      throw new MethodUnsupportedError(method, version);
+    }
+
+    // Method could use parameters, which are supported only in specific versions of Telegram
+    // Mini Apps.
+    if (isRecord(params)) {
+      let validateParam: string | undefined;
+
+      if (method === 'web_app_open_link' && 'try_instant_view' in params) {
+        validateParam = 'try_instant_view';
+      } else if (method === 'web_app_set_header_color' && 'color' in params) {
+        validateParam = 'color';
+      }
+
+      if (validateParam && !supports(method, validateParam, version)) {
+        throw new ParameterUnsupportedError(method, validateParam, version);
+      }
+    }
+
+    return postEvent(method, params);
+  };
+}

package/src/bridge/methods/haptic.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic type which creates new types of haptic feedback.
+ */
+type CreateHapticFeedbackParams<T extends string, P> = { type: T } & P;
+
+/**
+ * Style of impact occurred haptic event.
+ * - `light`, indicates a collision between small or lightweight UI objects,
+ * - `medium`, indicates a collision between medium-sized or medium-weight UI objects,
+ * - `heavy`, indicates a collision between large or heavyweight UI objects,
+ * - `rigid`, indicates a collision between hard or inflexible UI objects,
+ * - `soft`, indicates a collision between soft or flexible UI objects.
+ */
+export type ImpactHapticFeedbackStyle =
+  | 'light'
+  | 'medium'
+  | 'heavy'
+  | 'rigid'
+  | 'soft';
+
+/**
+ * Type of notification occurred type event.
+ * - `error`, indicates that a task or action has failed,
+ * - `success`, indicates that a task or action has completed successfully,
+ * - `warning`, indicates that a task or action produced a warning.
+ */
+export type NotificationHapticFeedbackType = 'error' | 'success' | 'warning';
+
+/**
+ * `impactOccurred` haptic feedback.
+ */
+export type ImpactHapticFeedbackParams = CreateHapticFeedbackParams<'impact', {
+  impact_style: ImpactHapticFeedbackStyle;
+}>;
+
+/**
+ * `notificationOccurred` haptic feedback.
+ */
+export type NotificationHapticFeedbackParams = CreateHapticFeedbackParams<'notification', {
+  notification_type: NotificationHapticFeedbackType;
+}>;
+
+/**
+ * `selectionChanged` haptic feedback.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type SelectionHapticFeedbackParams = CreateHapticFeedbackParams<'selection_change', {}>;
+
+export type AnyHapticFeedbackParams =
+  | ImpactHapticFeedbackParams
+  | NotificationHapticFeedbackParams
+  | SelectionHapticFeedbackParams;

package/src/bridge/methods/index.ts

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

package/src/bridge/methods/invoke-custom-method.ts

@@ -0,0 +1,25 @@
+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 type AnyInvokeCustomMethodParams =
+  | CreateInvokeCustomMethodParams<'deleteStorageValues', { keys: string | string[] }>
+  | CreateInvokeCustomMethodParams<'getStorageValues', { keys: string | string[] }>
+  | CreateInvokeCustomMethodParams<'getStorageKeys', {}>
+  | CreateInvokeCustomMethodParams<'saveStorageValue', { key: string, value: string }>
+  | CreateInvokeCustomMethodParams<string, any>;