@tma.js/sdk 0.13.3 → 1.0.1

package/dist/dts/navigation/HashNavigator/HashNavigator.d.ts

@@ -0,0 +1,43 @@
+import type { HashNavigatorEventsMap, HashNavigatorOptions } from './types.js';
+import { Navigator } from '../Navigator/index.js';
+import type { NavigatorConEntry, PerformGoOptions, PerformPushOptions, PerformReplaceOptions } from '../Navigator/types.js';
+export declare class HashNavigator extends Navigator<Promise<void>> {
+    /**
+     * Creates navigator from current window location hash.
+     * @param options - options passed to constructor.
+     */
+    static fromLocation(options?: HashNavigatorOptions): HashNavigator;
+    private readonly ee;
+    private attached;
+    constructor(entries: NavigatorConEntry[], entriesCursor: number, options?: HashNavigatorOptions);
+    /**
+     * Handles window "popstate" event.
+     * @param state - event state.
+     */
+    private onPopState;
+    protected performGo(options: PerformGoOptions): Promise<void>;
+    protected performPush({ before, after }: PerformPushOptions): Promise<void>;
+    protected performReplace(options: PerformReplaceOptions): Promise<void>;
+    /**
+     * Synchronizes current navigator state with browser history.
+     */
+    private syncHistory;
+    private emitChanged;
+    /**
+     * Attaches current navigator to the browser history allowing navigator to manipulate it.
+     */
+    attach(): Promise<void>;
+    back: () => Promise<void>;
+    /**
+     * Detaches current navigator from the browser history.
+     */
+    detach(): void;
+    /**
+     * Adds new event listener.
+     */
+    on: <E extends "change">(event: E, listener: import('../../event-emitter/index.js').EventListener<HashNavigatorEventsMap[E]>) => import('../../event-emitter/index.js').RemoveEventListener;
+    /**
+     * Removes event listener.
+     */
+    off: <E extends "change">(event: E, listener: import('../../event-emitter/index.js').EventListener<HashNavigatorEventsMap[E]>) => void;
+}

package/dist/dts/navigation/HashNavigator/drop.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Drops current browser history switching browser history cursor to the first one entry.
+ */
+export declare function drop(): Promise<void>;

package/dist/dts/navigation/HashNavigator/go.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Performs window.history.go operation waiting for it to be completed.
+ * @param delta - history change delta.
+ */
+export declare function go(delta: number): Promise<boolean>;

package/dist/dts/navigation/HashNavigator/index.d.ts

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

package/dist/dts/navigation/HashNavigator/types.d.ts

@@ -0,0 +1,34 @@
+import type { HashNavigator } from './HashNavigator.js';
+import type { NavigatorOptions } from '../Navigator/index.js';
+import type { NavigationEntry } from '../Navigator/types.js';
+export type HashNavigatorOptions = Omit<NavigatorOptions, 'loggerPrefix'>;
+interface ChangeEventPayload {
+    /**
+     * Navigator instance.
+     */
+    navigator: HashNavigator;
+    /**
+     * Previous navigation state.
+     */
+    from: NavigationEntry;
+    /**
+     * Current navigation state.
+     */
+    to: NavigationEntry;
+}
+export interface HashNavigatorEventsMap {
+    /**
+     * Being called whenever current history changes.
+     * @param event - generated event.
+     */
+    change: (event: ChangeEventPayload) => void;
+}
+/**
+ * Navigator event name.
+ */
+export type HashNavigatorEventName = keyof HashNavigatorEventsMap;
+/**
+ * Navigator event listener.
+ */
+export type HashNavigatorEventListener<E extends HashNavigatorEventName> = HashNavigatorEventsMap[E];
+export {};

package/dist/dts/navigation/Navigator/Navigator.d.ts

@@ -0,0 +1,104 @@
+import { Logger } from '../../logger/index.js';
+import type { AnyEntry, NavigationEntry, NavigatorConEntry, NavigatorOptions, PerformGoOptions, PerformPushOptions, PerformReplaceOptions } from './types.js';
+/**
+ * Represents basic navigator implementation which uses only memory to store and control
+ * navigation state.
+ */
+export declare abstract class Navigator<T> {
+    protected entriesCursor: number;
+    protected logger: Logger;
+    protected readonly entries: NavigationEntry[];
+    constructor(entries: NavigatorConEntry[], entriesCursor: number, { debug, loggerPrefix, }: NavigatorOptions);
+    protected abstract performGo(options: PerformGoOptions): T;
+    protected abstract performPush(options: PerformPushOptions): T;
+    protected abstract performReplace(options: PerformReplaceOptions): T;
+    /**
+     * Converts entry to the navigation entry.
+     * @param entry - entry data
+     */
+    private formatEntry;
+    /**
+     * Current entry.
+     */
+    protected get entry(): NavigationEntry;
+    /**
+     * Goes back in history.
+     */
+    back(): T;
+    /**
+     * Current entries cursor.
+     */
+    get cursor(): number;
+    /**
+     * True if navigator can go back.
+     */
+    get canGoBack(): boolean;
+    /**
+     * True if navigator can go forward.
+     */
+    get canGoForward(): boolean;
+    /**
+     * Goes forward in history.
+     */
+    forward(): T;
+    /**
+     * Moves entries cursor by specified delta.
+     * @param delta - cursor delta.
+     */
+    go(delta: number): T;
+    /**
+     * Returns copy of navigator entries.
+     */
+    getEntries(): NavigationEntry[];
+    /**
+     * Current hash.
+     * @example
+     * "", "#", "#hash"
+     */
+    get hash(): string;
+    /**
+     * Pushes new entry. Method replaces all entries after the current one with the inserted.
+     * @param entry - entry data.
+     *
+     * @example Pushing absolute pathname.
+     * push("/absolute-path"); // "/absolute-path"
+     *
+     * @example Pushing relative pathname.
+     * // Pushing relative path replaces N last path parts, where N is pushed pathname parts count.
+     * // Pushing empty path is recognized as relative, but not replacing the last pathname part.
+     * push("relative"); // "/home/root" -> "/home/relative"
+     *
+     * @example Pushing query parameters.
+     * push("/absolute?my-param=1"); // "/home" -> "/absolute?my-param=1"
+     * push("relative?my-param=1"); // "/home/root" -> "/home/relative?my-param=1"
+     * push("?my-param=1"); // "/home" -> "/home?my-param=1"
+     *
+     * @example Pushing hash.
+     * push("#my-hash"); // "/home" -> "/home#my-hash"
+     * push("johny#my-hash"); // "/home/root" -> "/home/johny#my-hash"
+     */
+    push(entry: AnyEntry): T;
+    /**
+     * Current full path including pathname, query parameters and hash.
+     */
+    get path(): string;
+    /**
+     * Current pathname.
+     * @example
+     * "/", "/abc"
+     */
+    get pathname(): string;
+    /**
+     * Replaces current entry. Has the same logic as `push` method.
+     * @param entry - entry data.
+     * @see push
+     * @returns True if changes were done.
+     */
+    replace(entry: AnyEntry): T;
+    /**
+     * Current query parameters.
+     * @example
+     * "", "?", "?a=1"
+     */
+    get search(): string;
+}

package/dist/dts/navigation/Navigator/index.d.ts

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

package/dist/dts/navigation/Navigator/types.d.ts

@@ -0,0 +1,44 @@
+export interface NavigationEntry {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+export type NavigatorConEntry = Partial<NavigationEntry>;
+/**
+ * Entry information is allowed to be used in `push` and `replace` Navigator methods.
+ * Should be either path or object partially describing it.
+ */
+export type AnyEntry = string | Partial<NavigationEntry>;
+export type PerformGoOptions = {
+    updated: false;
+    delta: number;
+} | {
+    updated: true;
+    delta: number;
+    before: NavigationEntry;
+    after: NavigationEntry;
+};
+export interface PerformPushOptions {
+    before: NavigationEntry;
+    after: NavigationEntry;
+}
+export type PerformReplaceOptions = {
+    updated: false;
+    entry: NavigationEntry;
+} | {
+    updated: true;
+    before: NavigationEntry;
+    after: NavigationEntry;
+};
+export interface NavigatorOptions {
+    /**
+     * Should navigator display debug messages.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Prefix used for logger.
+     * @default 'Navigator'
+     */
+    loggerPrefix?: string;
+}

package/dist/dts/navigation/ensurePrefix.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ensures, that specified value starts with the specified prefix. If it doesn't, function appends
+ * prefix.
+ * @param value - value to check.
+ * @param prefix - prefix to add.
+ */
+export declare function ensurePrefix(value: string, prefix: string): string;

package/dist/dts/navigation/getHash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns string after first met "#" symbol.
+ * @param value - string to take hash part from.
+ *
+ * @example No hash.
+ * getHash('/path'); // null
+ *
+ * @example Has hash.
+ * getHash('/path#abc'); // 'abc'
+ *
+ * @example Has double hash.
+ * getHash('/path#abc#another'); // 'abc#another'
+ */
+export declare function getHash(value: string): string | null;

package/dist/dts/navigation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ensurePrefix.js';
+export * from './getHash.js';
+export * from './HashNavigator/index.js';
+export * from './Navigator/index.js';

package/dist/dts/parsing/ArrayValueParser.d.ts

@@ -0,0 +1,18 @@
+import type { AnyParser } from './types.js';
+import type { ParseResult, ValueParserOverrides } from './ValueParser.js';
+import { ValueParser } from './ValueParser.js';
+export type OfResult<BaseClass, ItemType, IsOptional extends boolean> = ArrayParserType<BaseClass, ItemType, IsOptional>;
+export interface ArrayParserOverrides<BaseClass, ItemType, IsOptional extends boolean> extends ValueParserOverrides<BaseClass, ItemType[], IsOptional> {
+    /**
+     * Specifies parser for each array item.
+     * @param parser - item parser.
+     */
+    of<Item>(parser: AnyParser<Item>): OfResult<BaseClass, Item, IsOptional>;
+}
+export type ArrayParserType<BaseClass, ItemType, IsOptional extends boolean> = Omit<BaseClass, keyof ArrayParserOverrides<any, any, any>> & ArrayParserOverrides<BaseClass, ItemType, IsOptional>;
+export declare class ArrayValueParser<ItemType, IsOptional extends boolean> extends ValueParser<unknown[], IsOptional> {
+    private itemParser;
+    constructor(itemParser: AnyParser<ItemType>, isOptional: IsOptional, type?: string);
+    parse(value: unknown): ParseResult<ItemType[], IsOptional>;
+    of<Item>(itemParser: AnyParser<Item>): OfResult<this, Item, IsOptional>;
+}

package/dist/dts/parsing/ParseError.d.ts

@@ -0,0 +1,22 @@
+interface Options {
+    /**
+     * Type name.
+     */
+    type?: string;
+    /**
+     * Original occurred error.
+     */
+    cause?: unknown;
+}
+/**
+ * Error thrown in case, there was an error during parsing.
+ */
+export declare class ParseError extends Error {
+    readonly value: unknown;
+    /**
+     * Parser name.
+     */
+    readonly type?: string;
+    constructor(value: unknown, { cause, type }?: Options);
+}
+export {};

package/dist/dts/parsing/ParseSchemaFieldError.d.ts

@@ -0,0 +1,17 @@
+interface Options {
+    /**
+     * Type name.
+     */
+    type?: string;
+    /**
+     * Original occurred error.
+     */
+    cause?: unknown;
+}
+/**
+ * Error thrown in case, there was an error during parse.
+ */
+export declare class ParseSchemaFieldError extends Error {
+    constructor(field: string, { cause, type }?: Options);
+}
+export {};

package/dist/dts/parsing/ValueParser.d.ts

@@ -0,0 +1,36 @@
+import type { If } from '../types/index.js';
+import type { Parser } from './types.js';
+/**
+ * Result of "parse" function.
+ */
+export type ParseResult<ResultType, IsOptional extends boolean> = ResultType | If<IsOptional, undefined, never>;
+/**
+ * Result of "optional" function in ValueParser.
+ */
+export type OptionalResult<BaseClass, ResultType> = ValueParserType<BaseClass, ResultType, true>;
+export interface ValueParserOverrides<BaseClass, ResultType, IsOptional extends boolean> {
+    /**
+     * Parses incoming value applying parsing function passed via constructor.
+     * @param value - value to parse.
+     */
+    parse(value: unknown): ParseResult<ResultType, IsOptional>;
+    /**
+     * Marks this parser result as optional. This makes the parser to check if passed value
+     * is empty. If so, parser will return undefined value instead of passing it to the actual
+     * parser.
+     */
+    optional(): OptionalResult<BaseClass, ResultType>;
+}
+/**
+ * Describes generated ValueParser interface. Shortly saying, this type overrides BaseClass
+ * properties defined in ValueParser.
+ */
+export type ValueParserType<BaseClass, ResultType, IsOptional extends boolean> = Omit<BaseClass, keyof ValueParserOverrides<any, any, any>> & ValueParserOverrides<BaseClass, ResultType, IsOptional>;
+export declare class ValueParser<ResultType, IsOptional extends boolean> {
+    protected parser: Parser<ResultType>;
+    protected isOptional: IsOptional;
+    protected type?: string | undefined;
+    constructor(parser: Parser<ResultType>, isOptional: IsOptional, type?: string | undefined);
+    parse(value: unknown): ParseResult<ResultType, IsOptional>;
+    optional(): OptionalResult<this, ResultType>;
+}

package/dist/dts/parsing/createValueParserGenerator.d.ts

@@ -0,0 +1,9 @@
+import type { Parser } from './types.js';
+import { ValueParser } from './ValueParser.js';
+export type ValueParserGenerator<T> = () => ValueParser<T, false>;
+/**
+ * Creates function which generates new scalar value parser based on the specified one.
+ * @param parser - parser to use as basic.
+ * @param type - type name.
+ */
+export declare function createValueParserGenerator<T>(parser: Parser<T>, type?: string): ValueParserGenerator<T>;

package/dist/dts/parsing/index.d.ts

@@ -0,0 +1,10 @@
+export * from './ArrayValueParser.js';
+export * from './createValueParserGenerator.js';
+export * from './parseBySchema.js';
+export * from './ParseError.js';
+export * from './parsers/index.js';
+export * from './ParseSchemaFieldError.js';
+export * from './toRecord.js';
+export * from './types.js';
+export * from './unexpectedTypeError.js';
+export * from './ValueParser.js';

package/dist/dts/parsing/parseBySchema.d.ts

@@ -0,0 +1,8 @@
+import type { Schema } from './types.js';
+/**
+ * Parses external value by specified schema. Functions iterates over each schema field
+ * and uses getField function to get its value from the external source.
+ * @param schema - object schema.
+ * @param getField - function which gets external value by its field name.
+ */
+export declare function parseBySchema<T>(schema: Schema<T>, getField: (field: string) => unknown): T;

package/dist/dts/parsing/parsers/array.d.ts

@@ -0,0 +1,6 @@
+import { ArrayValueParser } from '../ArrayValueParser.js';
+/**
+ * Parses incoming value as an array.
+ * @param type - parser type name.
+ */
+export declare function array(type?: string): ArrayValueParser<unknown, false>;

package/dist/dts/parsing/parsers/boolean.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns parser to parse value as boolean.
+ */
+export declare const boolean: import("../createValueParserGenerator.js").ValueParserGenerator<boolean>;

package/dist/dts/parsing/parsers/date.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns parser to parse value as Date.
+ */
+export declare const date: import("../createValueParserGenerator.js").ValueParserGenerator<Date>;

package/dist/dts/parsing/parsers/index.d.ts

@@ -0,0 +1,8 @@
+export * from './array.js';
+export * from './boolean.js';
+export * from './date.js';
+export * from './json.js';
+export * from './number.js';
+export * from './rgb.js';
+export * from './searchParams.js';
+export * from './string.js';

package/dist/dts/parsing/parsers/json.d.ts

@@ -0,0 +1,8 @@
+import type { Schema } from '../types.js';
+import { ValueParser } from '../ValueParser.js';
+/**
+ * Creates new Json parser according to passed schema.
+ * @param schema - object schema.
+ * @param type - parser type name.
+ */
+export declare function json<T>(schema: Schema<T>, type?: string): ValueParser<T, false>;

package/dist/dts/parsing/parsers/number.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns parser to parse value as number.
+ */
+export declare const number: import("../createValueParserGenerator.js").ValueParserGenerator<number>;

package/dist/dts/parsing/parsers/rgb.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns parser to parse value as RGB color.
+ */
+export declare const rgb: import("../createValueParserGenerator.js").ValueParserGenerator<`#${string}`>;

package/dist/dts/parsing/parsers/searchParams.d.ts

@@ -0,0 +1,8 @@
+import type { Schema } from '../types.js';
+import { ValueParser } from '../ValueParser.js';
+/**
+ * Creates new search params parser according to passed schema.
+ * @param schema - object schema.
+ * @param type - parser type name.
+ */
+export declare function searchParams<T>(schema: Schema<T>, type?: string): ValueParser<T, false>;

package/dist/dts/parsing/parsers/string.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns parser to parse value as string.
+ */
+export declare const string: import("../createValueParserGenerator.js").ValueParserGenerator<string>;

package/dist/dts/parsing/toRecord.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts value to record.
+ * @param value - value to convert.
+ * @throws {Error} Value passed as a string does not represent JSON object.
+ * @throws {Error} Value is not convertable.
+ */
+export declare function toRecord(value: unknown): Record<string, unknown>;

package/dist/dts/parsing/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Represents any known parser.
+ */
+export type AnyParser<T> = Parser<T> | {
+    parse: Parser<T>;
+};
+/**
+ * Detailed schema field options.
+ */
+export interface SchemaFieldDetailed<T> {
+    /**
+     * Source property name.
+     * @default Original property name in schema.
+     */
+    from?: string;
+    /**
+     * Function which should parse incoming value and return expected type.
+     */
+    type: AnyParser<T>;
+}
+/**
+ * Function which parses incoming value.
+ */
+export type Parser<T> = (value: unknown) => T;
+/**
+ * Object schema definition.
+ */
+export type Schema<T> = {
+    [K in keyof T]: AnyParser<T[K]> | SchemaFieldDetailed<T[K]>;
+};

package/dist/dts/parsing/unexpectedTypeError.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Creates instance of TypeError stating, that value has unexpected type.
+ */
+export declare function unexpectedTypeError(): TypeError;

package/dist/dts/{components/Popup → popup}/Popup.d.ts

@@ -1,7 +1,7 @@
-import { type PostEvent } from '@tma.js/bridge';
-import type { Version } from '@tma.js/utils';
-import { type SupportsFunc } from '../../supports.js';
-import type { PopupParams } from './types.js';
+import { type PostEvent } from '../bridge/index.js';
+import { type SupportsFunc } from '../supports/index.js';
+import type { Version } from '../version/index.js';
+import type { OpenPopupOptions, PopupEvents } from './types.js';
 /**
  * Controls currently displayed application popup. It allows developers to
  * open new custom popups and detect popup-connected events.
@@ -11,18 +11,19 @@ export declare class Popup {
     private readonly ee;
     private readonly state;
     constructor(version: Version, postEvent?: PostEvent);
+    private set isOpened(value);
     /**
-     * Shows whether popup is currently opened.
+     * True if popup is currently opened.
      */
     get isOpened(): boolean;
     /**
      * Adds new event listener.
      */
-    on: typeof this.ee.on;
+    on: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<PopupEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
     /**
      * Removes event listener.
      */
-    off: typeof this.ee.off;
+    off: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<PopupEvents[E]>) => void;
     /**
      * A method that shows a native popup described by the `params` argument.
      * Promise will be resolved when popup is closed. Resolved value will have
@@ -33,10 +34,10 @@ export declare class Popup {
      *
      * FIXME: In desktop, this function may work incorrectly.
      *  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/7
-     * @param params - popup parameters.
+     * @param options - popup parameters.
      * @throws {Error} Popup is already opened.
      */
-    open(params: PopupParams): Promise<string | null>;
+    open(options: OpenPopupOptions): Promise<string | null>;
     /**
      * Checks if specified method is supported by current component.
      */

package/dist/dts/popup/index.d.ts

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

package/dist/dts/popup/preparePopupParams.d.ts

@@ -0,0 +1,7 @@
+import type { PopupParams as BridgePopupParams } from '../bridge/index.js';
+import type { OpenPopupOptions } from './types.js';
+/**
+ * Prepares popup parameters before sending them to native app.
+ * @param params - popup parameters.
+ */
+export declare function preparePopupParams(params: OpenPopupOptions): BridgePopupParams;

package/dist/dts/{components/Popup → popup}/types.d.ts

@@ -1,4 +1,4 @@
-import type { StateEvents } from '../../state/index.js';
+import type { StateEvents } from '../state/index.js';
 export interface PopupState {
     isOpened: boolean;
 }
@@ -9,7 +9,7 @@ export type PopupEventListener<E extends PopupEventName> = PopupEvents[E];
  * This object describes the native popup.
  * @see https://core.telegram.org/bots/webapps#popupparams
  */
-export interface PopupParams {
+export interface OpenPopupOptions {
     /**
      * The text to be displayed in the popup title, 0-64 characters.
      * @default ""
@@ -23,13 +23,13 @@ export interface PopupParams {
      * List of buttons to be displayed in the popup, 1-3 buttons.
      * @default [{type: 'close'}]
      */
-    buttons?: PopupButton[];
+    buttons?: OpenPopupOptionsButton[];
 }
 /**
  * This object describes the native popup button.
  * @see https://core.telegram.org/bots/webapps#popupbutton
  */
-export type PopupButton = {
+export type OpenPopupOptionsButton = {
     /**
      * Identifier of the button, 0-64 characters.
      * @default ""

package/dist/dts/{components/QRScanner → qr-scanner}/QRScanner.d.ts

@@ -1,6 +1,7 @@
-import { type PostEvent } from '@tma.js/bridge';
-import type { Version } from '@tma.js/utils';
-import { type SupportsFunc } from '../../supports.js';
+import { type PostEvent } from '../bridge/index.js';
+import { type SupportsFunc } from '../supports/index.js';
+import type { Version } from '../version/index.js';
+import type { QRScannerEvents } from './types.js';
 /**
  * Provides QR scanner functionality.
  */
@@ -28,11 +29,11 @@ export declare class QRScanner {
     /**
      * Adds new event listener.
      */
-    on: typeof this.ee.on;
+    on: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<QRScannerEvents[E]>) => import('../event-emitter/index.js').RemoveEventListener;
     /**
      * Removes event listener.
      */
-    off: typeof this.ee.off;
+    off: <E extends "change" | "change:isOpened">(event: E, listener: import('../event-emitter/index.js').EventListener<QRScannerEvents[E]>) => void;
     /**
      * Checks if specified method is supported by current component.
      */

package/dist/dts/qr-scanner/index.d.ts

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

package/dist/dts/{components/QRScanner → qr-scanner}/types.d.ts

@@ -1,4 +1,4 @@
-import type { StateEvents } from '../../state/index.js';
+import type { StateEvents } from '../state/index.js';
 export interface QRScannerState {
     isOpened: boolean;
 }