@tma.js/sdk 0.13.3 → 1.0.0

package/src/bridge/request.ts

@@ -0,0 +1,185 @@
+import { isRecord } from '~/misc/index.js';
+import { withTimeout } from '~/timeout/index.js';
+import type { And, If, IsNever } from '~/types/index.js';
+
+import {
+  type MiniAppsEventHasParams,
+  type MiniAppsEventName,
+  type MiniAppsEventParams,
+  on,
+} from './events/index.js';
+import {
+  type MiniAppsEmptyMethodName,
+  type MiniAppsMethodAcceptParams,
+  type MiniAppsMethodName,
+  type MiniAppsMethodParams,
+  type MiniAppsNonEmptyMethodName,
+  type PostEvent,
+  postEvent as defaultPostEvent,
+} from './methods/index.js';
+
+/**
+ * Names of methods, which require passing "req_id" parameter.
+ */
+type MethodWithRequestId = {
+  [M in MiniAppsMethodName]: If<
+    And<
+      MiniAppsMethodAcceptParams<M>,
+      MiniAppsMethodParams<M> extends { req_id: string } ? true : false
+    >,
+    M,
+    never
+  >;
+}[MiniAppsMethodName];
+
+/**
+ * Names of events, which contain "req_id" parameter.
+ */
+type EventWithRequestId = {
+  [E in MiniAppsEventName]: If<
+    And<MiniAppsEventHasParams<E>, MiniAppsEventParams<E> extends {
+      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 RequestOptionsAdvanced<EventPayload> extends RequestOptions {
+  /**
+   * Should return true in case, this event should be captured. If not specified,
+   * request is not skipping captured events.
+   */
+  capture?: If<IsNever<EventPayload>, () => boolean, (payload: EventPayload) => boolean>;
+}
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, event with specified in method request identifier
+ * was captured.
+ * @param method - method to execute.
+ * @param params - method parameters.
+ * @param event - event or events to listen.
+ * @param options - additional execution options.
+ */
+export function request<M extends MethodWithRequestId, E extends EventWithRequestId>(
+  method: M,
+  params: MiniAppsMethodParams<M>,
+  event: E | E[],
+  options?: RequestOptions,
+): Promise<MiniAppsEventParams<E>>;
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, specified event was captured.
+ * @param method - method to execute.
+ * @param event - event or events to listen.
+ * @param options - additional execution options.
+ */
+export function request<M extends MiniAppsEmptyMethodName, E extends MiniAppsEventName>(
+  method: M,
+  event: E | E[],
+  options?: RequestOptionsAdvanced<MiniAppsEventParams<E>>,
+): Promise<MiniAppsEventParams<E>>;
+
+/**
+ * Calls specified TWA method and captures one of the specified events. Returns promise
+ * which will be resolved in case, specified event was captured.
+ * @param method - method to execute
+ * @param params - method parameters.
+ * @param event - event or events to listen
+ * @param options - additional execution options.
+ */
+export function request<M extends MiniAppsNonEmptyMethodName, E extends MiniAppsEventName>(
+  method: M,
+  params: MiniAppsMethodParams<M>,
+  event: E | E[],
+  options?: RequestOptionsAdvanced<MiniAppsEventParams<E>>,
+): Promise<MiniAppsEventParams<E>>;
+
+export function request(
+  method: MiniAppsMethodName,
+  eventOrParams: MiniAppsEventName | MiniAppsEventName[] | MiniAppsEventParams<any>,
+  eventOrOptions?:
+    | MiniAppsEventName
+    | MiniAppsEventName[]
+    | RequestOptions
+    | RequestOptionsAdvanced<any>,
+  options?: RequestOptions | RequestOptionsAdvanced<any>,
+): Promise<any> {
+  let executionOptions: RequestOptions | RequestOptionsAdvanced<any> | undefined;
+  let methodParams: MiniAppsEventParams<any> | undefined;
+  let events: MiniAppsEventName[];
+  let requestId: string | undefined;
+
+  if (typeof eventOrParams === 'string' || Array.isArray(eventOrParams)) {
+    // Override: [method, event, options?]
+    events = Array.isArray(eventOrParams) ? eventOrParams : [eventOrParams] as MiniAppsEventName[];
+    executionOptions = eventOrOptions as (RequestOptionsAdvanced<any> | undefined);
+  } else {
+    // Override: [method, params, event, options?]
+    methodParams = eventOrParams as MiniAppsEventParams<any>;
+    events = Array.isArray(eventOrOptions)
+      ? eventOrOptions
+      : [eventOrOptions] as MiniAppsEventName[];
+    executionOptions = options;
+  }
+
+  // In case, method parameters were passed, and they contained request identifier, we should store
+  // it and wait for the event with this identifier to occur.
+  if (isRecord(methodParams) && typeof methodParams.req_id === 'string') {
+    requestId = methodParams.req_id;
+  }
+
+  const { postEvent = defaultPostEvent, timeout } = executionOptions || {};
+  const capture = executionOptions && 'capture' in executionOptions
+    ? executionOptions.capture
+    : null;
+
+  const promise = new Promise((res, rej) => {
+    // Iterate over each event and create event listener.
+    const stoppers = events.map((ev) => on(ev, (data?) => {
+      // If request identifier was specified, we are waiting for event with the same value
+      // to occur.
+      if (typeof requestId === 'string' && (!isRecord(data) || data.req_id !== requestId)) {
+        return;
+      }
+
+      if (typeof capture === 'function' && !capture(data)) {
+        return;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      stopListening();
+      res(data);
+    }));
+
+    // Function which removes all event listeners.
+    const stopListening = () => stoppers.forEach((stop) => stop());
+
+    try {
+      // We are wrapping this call in try catch, because it can throw errors in case,
+      // compatibility check was enabled. We want an error to be captured by promise, not by
+      // another one external try catch.
+      postEvent(method as any, methodParams);
+    } catch (e) {
+      stopListening();
+      rej(e);
+    }
+  });
+
+  return typeof timeout === 'number' ? withTimeout(promise, timeout) : promise;
+}

package/src/classnames/classNames.ts

@@ -0,0 +1,34 @@
+/**
+ * Inserts a space between a and b in case both of them are
+ * non-empty strings.
+ * @param a
+ * @param b
+ */
+function space(a: string, b: string): string {
+  return a + (a.length > 0 && b.length > 0 ? ` ${b}` : b);
+}
+
+/**
+ * Function which joins passed values with space following these rules:
+ * 1. If value is non-empty string, it will be added to output.
+ * 2. If value is object, only those keys will be added, which values are truthy.
+ * 3. All other values are ignored.
+ *
+ * You can find this function to similar one from package {@link https://www.npmjs.com/package/classnames|classnames}.
+ * @param values - values array.
+ */
+export function classNames(...values: any[]): string {
+  return values.reduce<string>((acc, value) => {
+    let formattedValue = '';
+
+    if (typeof value === 'string') {
+      formattedValue = value;
+    } else if (typeof value === 'object' && value !== null) {
+      formattedValue = Object
+        .entries(value)
+        .reduce<string>((valueAcc, [className, enable]) => (enable ? space(valueAcc, className) : valueAcc), '');
+    }
+
+    return space(acc, formattedValue);
+  }, '');
+}

package/src/classnames/index.ts

@@ -0,0 +1,2 @@
+export * from './classNames.js';
+export * from './mergeClassNames.js';

package/src/classnames/mergeClassNames.ts

@@ -0,0 +1,68 @@
+import { classNames } from './classNames.js';
+
+type FilterUnion<U> = Exclude<U, number | string | null | undefined | any[] | boolean>;
+
+/**
+ * Returns union keys removing those, which values are not strings.
+ */
+type UnionFilteredKeys<U> = U extends U
+  ? {
+    [K in keyof U]: U[K] extends string ? K : never
+  }[keyof U]
+  : never;
+
+/**
+ * Returns union required keys.
+ */
+type UnionRequiredKeys<U> = U extends U
+  ? {
+    [K in UnionFilteredKeys<U>]-?: ({} extends { [P in K]: U[K] } ? never : K)
+  }[UnionFilteredKeys<U>]
+  : never;
+
+/**
+ * Returns union optional keys.
+ */
+type UnionOptionalKeys<U> = Exclude<UnionFilteredKeys<U>, UnionRequiredKeys<U>>;
+
+type MergeClassNames<Tuple extends any[]> = Tuple[number] extends infer Union
+  ? FilterUnion<Union> extends infer UnionFiltered
+    ? {
+      [K in UnionRequiredKeys<UnionFiltered>]: string;
+    } & {
+      [K in UnionOptionalKeys<UnionFiltered>]?: string;
+    }
+    : never
+  : never;
+
+/**
+ * Returns true in case, passed value is Record.
+ * @param value
+ */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(null);
+}
+
+/**
+ * Merges 2 sets of parameters. Function expects passing an array of objects with values, which
+ * could be passed to `classNames` function. As the result, it returns an object with keys
+ * from all objects with merged values.
+ * @see classNames
+ */
+export function mergeClassNames<T extends any[]>(...partials: T): MergeClassNames<T> {
+  return partials.reduce<MergeClassNames<T>>((acc, partial) => {
+    if (!isObject(partial)) {
+      return acc;
+    }
+
+    Object.entries(partial).forEach(([key, value]) => {
+      const className = classNames((acc as any)[key], value);
+
+      if (className.length > 0) {
+        (acc as any)[key] = className;
+      }
+    });
+
+    return acc;
+  }, {} as MergeClassNames<T>);
+}

package/src/{components/ClosingBehaviour/ClosingBehaviour.ts → closing-behavior/ClosingBehavior.ts}

@@ -1,18 +1,20 @@
-import { EventEmitter } from '@tma.js/event-emitter';
-import { postEvent as defaultPostEvent, type PostEvent } from '@tma.js/bridge';
+import { type PostEvent, postEvent as defaultPostEvent } from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
 
-import { State } from '../../state/index.js';
-
-import type { ClosingBehaviourEvents, ClosingBehaviourState } from './types.js';
+import type {
+  ClosingBehaviorEvents,
+  ClosingBehaviorState,
+} from './types.js';
 
 /**
  * Component responsible for controlling current closing confirmation
  * status.
  */
-export class ClosingBehaviour {
-  private readonly ee = new EventEmitter<ClosingBehaviourEvents>();
+export class ClosingBehavior {
+  private readonly ee = new EventEmitter<ClosingBehaviorEvents>();
 
-  private readonly state: State<ClosingBehaviourState>;
+  private readonly state: State<ClosingBehaviorState>;
 
   constructor(
     isConfirmationNeeded: boolean,
@@ -53,10 +55,10 @@ export class ClosingBehaviour {
   /**
    * 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/closing-behavior/index.ts

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

package/src/closing-behavior/types.ts

@@ -0,0 +1,12 @@
+import type { StateEvents } from '~/state/index.js';
+
+export interface ClosingBehaviorState {
+  isConfirmationNeeded: boolean;
+}
+
+export type ClosingBehaviorEvents = StateEvents<ClosingBehaviorState>;
+
+export type ClosingBehaviorEventName = keyof ClosingBehaviorEvents;
+
+export type ClosingBehaviorEventListener<E extends ClosingBehaviorEventName> =
+  ClosingBehaviorEvents[E];

package/src/{components/CloudStorage → cloud-storage}/CloudStorage.ts

@@ -2,14 +2,18 @@ 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';
+} from '~/bridge/index.js';
+import {
+  array,
+  json,
+  string,
+} from '~/parsing/index.js';
+import {
+  createSupportsFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { CreateRequestIdFunc } from '~/types/index.js';
+import type { Version } from '~/version/index.js';
 
 type WiredRequestOptions = Omit<RequestOptions, 'postEvent'>;
 
@@ -36,10 +40,10 @@ export class CloudStorage {
     private readonly postEvent = defaultPostEvent,
   ) {
     this.supports = createSupportsFunc(version, {
-      deleteKeys: 'web_app_invoke_custom_method',
+      delete: 'web_app_invoke_custom_method',
+      get: 'web_app_invoke_custom_method',
       getKeys: 'web_app_invoke_custom_method',
-      getValues: 'web_app_invoke_custom_method',
-      saveValue: 'web_app_invoke_custom_method',
+      set: 'web_app_invoke_custom_method',
     });
   }
 
@@ -62,18 +66,19 @@ export class CloudStorage {
     );
 
     if (error) {
-      throw new Error(typeof error === 'string' ? error : `Unknown error: ${JSON.stringify(error)}`);
+      throw new Error(error);
     }
 
     return result;
   }
 
   /**
-   * Deletes specified keys from the CloudStorage.
-   * @param keys - keys list.
+   * Deletes specified key or keys from the cloud storage.
+   * @param keyOrKeys - key or keys to delete.
    * @param options - request execution options.
    */
-  async deleteKeys(keys: string[], options?: WiredRequestOptions): Promise<void> {
+  async delete(keyOrKeys: string | string[], options?: WiredRequestOptions): Promise<void> {
+    const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
     if (keys.length === 0) {
       return;
     }
@@ -82,7 +87,7 @@ export class CloudStorage {
   }
 
   /**
-   * Returns list of all keys presented in CloudStorage.
+   * Returns list of all keys presented in the cloud storage.
    * @param options - request execution options.
    */
   async getKeys(options?: WiredRequestOptions): Promise<string[]> {
@@ -97,20 +102,37 @@ export class CloudStorage {
    * @param keys - keys list.
    * @param options - request execution options.
    */
-  async getValues<K extends string>(
+  get<K extends string>(
     keys: K[],
     options?: WiredRequestOptions,
-  ): Promise<Record<K, string>> {
+  ): Promise<Record<K, string>>;
+
+  /**
+   * Returns value of the specified key.
+   * @param key - cloud storage key.
+   * @param options - request execution options.
+   * @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>;
+
+  async get(
+    keyOrKeys: string | string[],
+    options?: WiredRequestOptions,
+  ): Promise<string | Record<string, string>> {
+    const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
     if (keys.length === 0) {
-      return objectFromKeys(keys, '');
+      return objectFromKeys<string, string>(keys, '');
     }
 
-    const schema = json<Record<K, string>>(
-      objectFromKeys(keys, string()) as any, // fixme
+    const schema = json(
+      objectFromKeys(keys, string()),
     );
-    const result = await this.invokeCustomMethod('getStorageValues', { keys }, options);
+    const result = await this
+      .invokeCustomMethod('getStorageValues', { keys }, options)
+      .then((data) => schema.parse(data));
 
-    return schema.parse(result);
+    return Array.isArray(keyOrKeys) ? result : result[keyOrKeys];
   }
 
   /**
@@ -119,7 +141,7 @@ export class CloudStorage {
    * @param value - storage value.
    * @param options - request execution options.
    */
-  async saveValue(key: string, value: string, options?: WiredRequestOptions): Promise<void> {
+  async set(key: string, value: string, options?: WiredRequestOptions): Promise<void> {
     await this.invokeCustomMethod('saveStorageValue', { key, value }, options);
   }
 
@@ -127,9 +149,9 @@ export class CloudStorage {
    * Checks if specified method is supported by current component.
    */
   supports: SupportsFunc<
-    | 'deleteKeys'
-    | 'getKeys'
-    | 'getValues'
-    | 'saveValue'
+  | 'delete'
+  | 'get'
+  | 'getKeys'
+  | 'set'
   >;
 }

package/src/colors/index.ts

@@ -0,0 +1,5 @@
+export * from './isColorDark.js';
+export * from './isRGB.js';
+export * from './isRGBShort.js';
+export * from './toRGB.js';
+export * from './types.js';

package/src/colors/isColorDark.ts

@@ -0,0 +1,22 @@
+import { toRGB } from './toRGB.js';
+
+/**
+ * Returns true in case, the color is recognized as dark.
+ * @param color - color in any format acceptable by toRGB function.
+ * @see toRGB
+ */
+export function isColorDark(color: string): boolean {
+  // Convert color to RGB.
+  const rgb = toRGB(color);
+
+  // Real formula: hsp = Math.sqrt(0.299 * r * r + 0.587 * g * g + 0.114 * b * b)
+  // See: https://stackoverflow.com/a/596243
+  const hsp = Math.sqrt(
+    [0.299, 0.587, 0.114].reduce<number>((acc, modifier, idx) => {
+      // Extract part of #RRGGBB pattern and convert it to DEC.
+      const dec = parseInt(rgb.slice(1 + idx * 2, 1 + (idx + 1) * 2), 16);
+      return acc + dec * dec * modifier;
+    }, 0),
+  );
+  return hsp < 120;
+}

package/src/colors/isRGB.ts

@@ -0,0 +1,9 @@
+import type { RGB } from './types.js';
+
+/**
+ * Returns true in case, passed value has #RRGGBB format.
+ * @param value - value to check.
+ */
+export function isRGB(value: string): value is RGB {
+  return /^#[\da-f]{6}$/i.test(value);
+}

package/src/colors/isRGBShort.ts

@@ -0,0 +1,9 @@
+import type { RGBShort } from './types.js';
+
+/**
+ * Returns true in case, passed value has #RGB format.
+ * @param value - value to check.
+ */
+export function isRGBShort(value: string): value is RGBShort {
+  return /^#[\da-f]{3}$/i.test(value);
+}

package/src/colors/toRGB.ts

@@ -0,0 +1,49 @@
+import { isRGB } from './isRGB.js';
+import { isRGBShort } from './isRGBShort.js';
+import type { RGB } from './types.js';
+
+/**
+ * Converts passed value to #RRGGBB format. Accepts following color formats:
+ * - `#RGB`
+ * - `#RRGGBB`
+ * - `rgb(1,2,3)`
+ * - `rgba(1,2,3,4)`
+ * @param value - value to convert.
+ * @throws {Error} Passed value does not satisfy any of known RGB formats.
+ */
+export function toRGB(value: string): RGB {
+  // Remove all spaces.
+  const clean = value.replace(/\s/g, '').toLowerCase();
+
+  // Value already has required format.
+  if (isRGB(clean)) {
+    return clean;
+  }
+
+  // Convert from #RGB.
+  if (isRGBShort(clean)) {
+    let color = '#';
+
+    for (let i = 0; i < 3; i += 1) {
+      color += clean[1 + i].repeat(2);
+    }
+    return color as RGB;
+  }
+
+  // Example valid values: rgb(0,3,10) rgba(32,114,8,0)
+  const match = clean.match(/^rgb\((\d{1,3}),(\d{1,3}),(\d{1,3})\)$/)
+    || clean.match(/^rgba\((\d{1,3}),(\d{1,3}),(\d{1,3}),\d{1,3}\)$/);
+
+  // In case, this didn't work as well, we can't extract RGB color from passed
+  // text.
+  if (match === null) {
+    throw new Error(`Value "${value}" does not satisfy any of known RGB formats.`);
+  }
+
+  // Otherwise, take R, G and B components, convert to hex and create #RRGGBB
+  // string.
+  return match.slice(1).reduce((acc, component) => {
+    const formatted = parseInt(component, 10).toString(16);
+    return acc + (formatted.length === 1 ? '0' : '') + formatted;
+  }, '#') as RGB;
+}

package/src/colors/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Color in format #RGB.
+ */
+export type RGBShort = `#${string}`;
+
+/**
+ * Color in format #RRGGBB.
+ */
+export type RGB = `#${string}`;