@tma.js/sdk 0.11.3

package/dist/types/state/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Computes state property changed event.
+ */
+export type PropChangedEvent<K extends string> = `${K}Changed`;
+/**
+ * Returns object string keys.
+ */
+export type StringKeys<T extends object> = Extract<keyof T, string>;
+/**
+ * Extracts state property type by its computed change event name.
+ */
+export type PropertyType<State extends object, Event extends string> = {
+    [Key in StringKeys<State>]: Event extends PropChangedEvent<Key> ? State[Key] : never;
+}[StringKeys<State>];
+/**
+ * Creates map, where key is event name which is used, when state property was changed.
+ * Value is according listener.
+ */
+export type PropChangedEventsMap<State extends object> = {
+    [Event in `${StringKeys<State>}Changed`]: (value: PropertyType<State, Event>) => void;
+};
+/**
+ * Creates map with all events emitted by state.
+ */
+export type StateEvents<State extends object> = PropChangedEventsMap<State> & {
+    /**
+     * Being called whenever any property was updated.
+     */
+    changed: () => void;
+};

package/dist/types/storage.d.ts

@@ -0,0 +1,48 @@
+import type { HeaderColorKey } from '@tma.js/bridge';
+import type { RGB } from '@tma.js/colors';
+/**
+ * Describes storage keys and according values.
+ */
+interface StorageParams {
+    'back-button': {
+        isVisible: boolean;
+    };
+    'closing-behavior': {
+        isConfirmationNeeded: boolean;
+    };
+    'main-button': {
+        backgroundColor: RGB;
+        isEnabled: boolean;
+        isVisible: boolean;
+        isProgressVisible: boolean;
+        text: string;
+        textColor: RGB;
+    };
+    viewport: {
+        height: number;
+        isExpanded: boolean;
+        stableHeight: number;
+        width: number;
+    };
+    'web-app': {
+        backgroundColor: RGB;
+        headerColor: HeaderColorKey | RGB;
+    };
+    'launch-params': string;
+}
+/**
+ * Key which could be used to store data in storage.
+ */
+type StorageKey = keyof StorageParams;
+/**
+ * Saves value in sessionStorage.
+ * @param key - storage key.
+ * @param value - storage value.
+ */
+export declare function saveStorageValue<K extends StorageKey>(key: K, value: StorageParams[K]): void;
+/**
+ * Extracts value from the sessionStorage.
+ * @param key - storage key.
+ */
+export declare function getStorageValue<K extends StorageKey>(key: K): StorageParams[K] | null;
+export {};

package/dist/types/supports.d.ts

@@ -0,0 +1,22 @@
+import type { Version } from '@tma.js/utils';
+import { type MethodName, type HasCheckSupportMethodName, type HasCheckSupportMethodParam } from '@tma.js/bridge';
+export type SupportsFunc<M extends string> = (method: M) => boolean;
+type HasCheckSupportMethodTuple = {
+    [M in HasCheckSupportMethodName]: [M, HasCheckSupportMethodParam<M>];
+}[HasCheckSupportMethodName];
+/**
+ * Returns function, which accepts predefined method name and checks if it is supported
+ * via passed schema and version.
+ * @param schema - object which contains methods names and TWA method as a dependency.
+ * @param version - platform version.
+ */
+export declare function createSupportsFunc<M extends string>(version: Version, schema: Record<M, MethodName>): SupportsFunc<M>;
+/**
+ * Returns function, which accepts predefined method name and checks if it is supported
+ * via passed schema and version.
+ * @param schema - object which contains methods names and TWA methods with specified parameter
+ * as a dependency.
+ * @param version - platform version.
+ */
+export declare function createSupportsParamFunc<P extends string>(version: Version, schema: Record<P, HasCheckSupportMethodTuple>): SupportsFunc<P>;
+export {};

package/dist/types/theme-params.d.ts

@@ -0,0 +1,18 @@
+import type { RGB } from '@tma.js/colors';
+/**
+ * Application theme parameters. Defines palette used by the Telegram application.
+ */
+export interface ThemeParamsType {
+    backgroundColor?: RGB;
+    buttonColor?: RGB;
+    buttonTextColor?: RGB;
+    hintColor?: RGB;
+    linkColor?: RGB;
+    secondaryBackgroundColor?: RGB;
+    textColor?: RGB;
+}
+/**
+ * Parses incoming value as theme parameters.
+ * @param value - value to parse.
+ */
+export declare function parseThemeParams(value: unknown): ThemeParamsType;

package/dist/types/types.d.ts

@@ -0,0 +1,14 @@
+import type { PostEvent as BridgePostEvent } from '@tma.js/bridge';
+export type PostEvent = BridgePostEvent;
+/**
+ * Color scheme.
+ */
+export type ColorScheme = 'dark' | 'light';
+/**
+ * Native Telegram application identifier.
+ */
+export type Platform = 'android' | 'android_x' | 'ios' | 'macos' | 'tdesktop' | 'web' | 'weba' | 'unigram' | 'unknown' | string;
+/**
+ * Function which generates unique request identifiers.
+ */
+export type CreateRequestIdFunc = () => string;

package/dist/types/url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts passed URL to its full form.
+ * @param url - URL to format.
+ * @throws {Error} URL protocol is not supported by OS, or link has not allowed
+ * protocol.
+ */
+export declare function formatURL(url: string): string;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tma.js/sdk",
+  "version": "0.11.3",
+  "description": "TypeScript Source Development Kit for Telegram Web Apps client application.",
+  "author": "Vladislav Kibenko <wolfram.deus@gmail.com>",
+  "homepage": "https://github.com/Telegram-Mini-Apps/tma.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:Telegram-Mini-Apps/tma.js.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Telegram-Mini-Apps/tma.js/issues"
+  },
+  "keywords": [
+    "telegram-mini-apps",
+    "typescript",
+    "sdk"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/lib/index.cjs",
+  "browser": "dist/lib/browser.js",
+  "module": "dist/lib/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/lib/index.mjs",
+      "require": "./dist/lib/index.cjs",
+      "default": "./dist/lib/index.cjs"
+    },
+    "./*": {
+      "types": "./dist/types/*.d.ts",
+      "import": "./dist/lib/*.mjs",
+      "require": "./dist/lib/*.cjs",
+      "default": "./dist/lib/*.cjs"
+    }
+  },
+  "dependencies": {
+    "@tma.js/bridge": "1.3.2",
+    "@tma.js/colors": "0.0.2",
+    "@tma.js/init-data": "0.2.14",
+    "@tma.js/utils": "0.5.2",
+    "@tma.js/util-types": "0.0.2",
+    "@tma.js/parsing": "0.0.2",
+    "@tma.js/event-emitter": "0.0.2"
+  },
+  "devDependencies": {
+    "tsconfig": "0.0.2",
+    "eslint-config-custom": "0.1.0",
+    "jest-config-custom": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint -c .eslintrc.cjs src/**/* __tests__/**/*",
+    "build": "rimraf dist && rollup --config rollup.config.js"
+  }
+}

package/src/components/BackButton/BackButton.ts

@@ -0,0 +1,90 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { on, off, postEvent as defaultPostEvent, type PostEvent } from '@tma.js/bridge';
+
+import type { Version } from '@tma.js/utils';
+
+import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+import { State } from '../../state/index.js';
+
+import type { BackButtonEvents, BackButtonState, BackButtonEventListener } from './types.js';
+
+/**
+ * Class which controls the back button displayed in the header
+ * of the Web App in the Telegram interface. It is mostly used in case, when
+ * you want to provide a way to go bach in routing history or "rollback" some
+ * action.
+ */
+export class BackButton {
+  private readonly ee = new EventEmitter<BackButtonEvents>();
+
+  private readonly state: State<BackButtonState>;
+
+  constructor(
+    isVisible: boolean,
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({ isVisible }, this.ee);
+    this.supports = createSupportsFunc(version, {
+      show: 'web_app_setup_back_button',
+      hide: 'web_app_setup_back_button',
+    });
+  }
+
+  private set isVisible(visible: boolean) {
+    this.state.set('isVisible', visible);
+    this.postEvent('web_app_setup_back_button', { is_visible: visible });
+  }
+
+  /**
+   * True if BackButton is currently visible.
+   */
+  get isVisible(): boolean {
+    return this.state.get('isVisible');
+  }
+
+  /**
+   * Hides the BackButton.
+   */
+  hide(): void {
+    this.isVisible = false;
+  }
+
+  /**
+   * Adds event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  on: typeof this.ee.on = (event, listener) => {
+    if (event === 'click') {
+      return on('back_button_pressed', listener as BackButtonEventListener<'click'>);
+    }
+
+    this.ee.on(event, listener);
+  };
+
+  /**
+   * Removes event listener.
+   * @param event - event name.
+   * @param listener - event listener.
+   */
+  off: typeof this.ee.off = (event, listener) => {
+    if (event === 'click') {
+      return off('back_button_pressed', listener as BackButtonEventListener<'click'>);
+    }
+
+    this.ee.off(event, listener);
+  };
+
+  /**
+   * Shows the BackButton.
+   */
+  show(): void {
+    this.isVisible = true;
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'show' | 'hide'>;
+}

package/src/components/BackButton/index.ts

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

package/src/components/BackButton/types.ts

@@ -0,0 +1,13 @@
+import type { StateEvents } from '../../state/index.js';
+
+export interface BackButtonState {
+  isVisible: boolean;
+}
+
+export interface BackButtonEvents extends StateEvents<BackButtonState> {
+  click: () => void;
+}
+
+export type BackButtonEventName = keyof BackButtonEvents;
+
+export type BackButtonEventListener<E extends BackButtonEventName> = BackButtonEvents[E];

package/src/components/ClosingBehaviour/ClosingBehaviour.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { postEvent as defaultPostEvent, type PostEvent } from '@tma.js/bridge';
+
+import { State } from '../../state/index.js';
+
+import type { ClosingBehaviourEvents, ClosingBehaviourState } from './types.js';
+
+/**
+ * Component responsible for controlling current closing confirmation
+ * status.
+ */
+export class ClosingBehaviour {
+  private readonly ee = new EventEmitter<ClosingBehaviourEvents>();
+
+  private readonly state: State<ClosingBehaviourState>;
+
+  constructor(
+    isConfirmationNeeded: boolean,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({ isConfirmationNeeded }, this.ee);
+  }
+
+  private set isConfirmationNeeded(value: boolean) {
+    this.state.set('isConfirmationNeeded', value);
+    this.postEvent('web_app_setup_closing_behavior', { need_confirmation: value });
+  }
+
+  /**
+   * Returns true, if the confirmation dialog enabled while the user is trying
+   * to close the Web App.
+   */
+  get isConfirmationNeeded(): boolean {
+    return this.state.get('isConfirmationNeeded');
+  }
+
+  /**
+   * Disables the confirmation dialog while the user is trying to close the
+   * Web App.
+   */
+  disableConfirmation(): void {
+    this.isConfirmationNeeded = false;
+  }
+
+  /**
+   * Enables the confirmation dialog while the user is trying to close the
+   * Web App.
+   */
+  enableConfirmation(): void {
+    this.isConfirmationNeeded = true;
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+}

package/src/components/ClosingBehaviour/index.ts

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

package/src/components/ClosingBehaviour/types.ts

@@ -0,0 +1,12 @@
+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/src/components/CloudStorage/CloudStorage.ts

@@ -0,0 +1,135 @@
+import {
+  postEvent as defaultPostEvent,
+  request,
+  type RequestOptions,
+} from '@tma.js/bridge';
+import { array, json, string } from '@tma.js/parsing';
+
+import type { Version } from '@tma.js/utils';
+
+import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+
+import type { CreateRequestIdFunc } from '../../types.js';
+
+type WiredRequestOptions = Omit<RequestOptions, 'postEvent'>;
+
+interface Methods {
+  deleteStorageValues: { keys: string | string[] };
+  getStorageValues: { keys: string | string[] };
+  getStorageKeys: {};
+  saveStorageValue: { key: string; value: string };
+}
+
+const stringArray = array().of(string());
+
+function objectFromKeys<K extends string, V>(keys: K[], value: V): Record<K, V> {
+  return keys.reduce<Record<K, V>>((acc, key) => {
+    acc[key] = value;
+    return acc;
+  }, {} as Record<K, V>);
+}
+
+export class CloudStorage {
+  constructor(
+    version: Version,
+    private readonly createRequestId: CreateRequestIdFunc,
+    private readonly postEvent = defaultPostEvent,
+  ) {
+    this.supports = createSupportsFunc(version, {
+      deleteKeys: 'web_app_invoke_custom_method',
+      getKeys: 'web_app_invoke_custom_method',
+      getValues: 'web_app_invoke_custom_method',
+      saveValue: 'web_app_invoke_custom_method',
+    });
+  }
+
+  /**
+   * Invokes custom method related to CloudStorage.
+   * @param method - method name.
+   * @param params - method parameters.
+   * @param options - execution options.
+   */
+  private async invokeCustomMethod<M extends keyof Methods>(
+    method: M,
+    params: Methods[M],
+    options: WiredRequestOptions = {},
+  ): Promise<unknown> {
+    const { result, error } = await request(
+      'web_app_invoke_custom_method',
+      { method, params, req_id: this.createRequestId() },
+      'custom_method_invoked',
+      { ...options, postEvent: this.postEvent },
+    );
+
+    if (error) {
+      throw new Error(typeof error === 'string' ? error : `Unknown error: ${JSON.stringify(error)}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Deletes specified keys from the CloudStorage.
+   * @param keys - keys list.
+   * @param options - request execution options.
+   */
+  async deleteKeys(keys: string[], options?: WiredRequestOptions): Promise<void> {
+    if (keys.length === 0) {
+      return;
+    }
+
+    await this.invokeCustomMethod('deleteStorageValues', { keys }, options);
+  }
+
+  /**
+   * Returns list of all keys presented in CloudStorage.
+   * @param options - request execution options.
+   */
+  async getKeys(options?: WiredRequestOptions): Promise<string[]> {
+    const result = await this.invokeCustomMethod('getStorageKeys', {}, options);
+
+    return stringArray.parse(result);
+  }
+
+  /**
+   * 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.
+   */
+  async getValues<K extends string>(
+    keys: K[],
+    options?: WiredRequestOptions,
+  ): Promise<Record<K, string>> {
+    if (keys.length === 0) {
+      return objectFromKeys(keys, '');
+    }
+
+    const schema = json<Record<K, string>>(
+      objectFromKeys(keys, string()) as any, // fixme
+    );
+    const result = await this.invokeCustomMethod('getStorageValues', { keys }, options);
+
+    return schema.parse(result);
+  }
+
+  /**
+   * Saves specified value by key.
+   * @param key - storage key.
+   * @param value - storage value.
+   * @param options - request execution options.
+   */
+  async saveValue(key: string, value: string, options?: WiredRequestOptions): Promise<void> {
+    await this.invokeCustomMethod('saveStorageValue', { key, value }, options);
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<
+    | 'deleteKeys'
+    | 'getKeys'
+    | 'getValues'
+    | 'saveValue'
+  >;
+}

package/src/components/CloudStorage/index.ts

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

package/src/components/HapticFeedback/HapticFeedback.ts

@@ -0,0 +1,62 @@
+import type { Version } from '@tma.js/utils';
+import {
+  postEvent as defaultPostEvent,
+  type PostEvent,
+  type ImpactHapticFeedbackStyle,
+  type NotificationHapticFeedbackType,
+} from '@tma.js/bridge';
+
+import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
+
+/**
+ * Class which controls haptic feedback. It allows calling different types of
+ * haptic notifications which usually occur after user interaction with
+ * application.
+ */
+export class HapticFeedback {
+  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+    this.supports = createSupportsFunc(version, {
+      impactOccurred: 'web_app_trigger_haptic_feedback',
+      notificationOccurred: 'web_app_trigger_haptic_feedback',
+      selectionChanged: 'web_app_trigger_haptic_feedback',
+    });
+  }
+
+  /**
+   * A method tells that an impact occurred. The Telegram app may play the
+   * appropriate haptics based on style value passed.
+   * @param style - impact style.
+   */
+  impactOccurred(style: ImpactHapticFeedbackStyle): void {
+    this.postEvent('web_app_trigger_haptic_feedback', { type: 'impact', impact_style: style });
+  }
+
+  /**
+   * A method tells that a task or action has succeeded, failed, or produced
+   * a warning. The Telegram app may play the appropriate haptics based on
+   * type value passed.
+   * @param type - notification type.
+   */
+  notificationOccurred(type: NotificationHapticFeedbackType): void {
+    this.postEvent('web_app_trigger_haptic_feedback', {
+      type: 'notification',
+      notification_type: type,
+    });
+  }
+
+  /**
+   * A method tells that the user has changed a selection. The Telegram app
+   * may play the appropriate haptics.
+   *
+   * Do not use this feedback when the user makes or confirms a selection;
+   * use it only when the selection changes.
+   */
+  selectionChanged(): void {
+    this.postEvent('web_app_trigger_haptic_feedback', { type: 'selection_change' });
+  }
+
+  /**
+   * Checks if specified method is supported by current component.
+   */
+  supports: SupportsFunc<'impactOccurred' | 'notificationOccurred' | 'selectionChanged'>;
+}

package/src/components/HapticFeedback/index.ts

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