@tma.js/sdk 2.7.0 → 3.0.1

package/dist/dts/features/ClosingBehavior/ClosingBehavior.d.ts

@@ -0,0 +1,51 @@
+import { Computed } from '@tma.js/signals';
+import { PostEventError } from '@tma.js/bridge';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { WithStateRestore } from '../../fn-options/withStateRestore.js';
+import { WithPostEvent } from '../../fn-options/withPostEvent.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import * as E from 'fp-ts/Either';
+export interface ClosingBehaviorState {
+    isConfirmationEnabled: boolean;
+}
+export interface ClosingBehaviorOptions extends WithStateRestore<ClosingBehaviorState>, WithPostEvent, SharedFeatureOptions {
+}
+export declare class ClosingBehavior {
+    constructor({ postEvent, storage, isTma, isPageReload }: ClosingBehaviorOptions);
+    /**
+     * Signal indicating if closing confirmation dialog is currently enabled.
+     */
+    readonly isConfirmationEnabled: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Mounts the component restoring its state.
+     */
+    readonly mountFp: WithChecksFp<() => void, false>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, false>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+    /**
+     * Disables the closing confirmation dialog.
+     */
+    readonly disableConfirmationFp: WithChecksFp<() => E.Either<PostEventError, void>, false>;
+    /**
+     * @see disableConfirmationFp
+     */
+    readonly disableConfirmation: WithChecks<() => void, false>;
+    /**
+     * Enables the closing confirmation dialog.
+     */
+    readonly enableConfirmationFp: WithChecksFp<() => E.Either<PostEventError, void>, false>;
+    /**
+     * @see enableConfirmationFp
+     */
+    readonly enableConfirmation: WithChecks<() => void, false>;
+}

package/dist/dts/features/ClosingBehavior/exports.d.ts

@@ -0,0 +1,2 @@
+export { ClosingBehavior, type ClosingBehaviorOptions, type ClosingBehaviorState, } from './ClosingBehavior.js';
+export { closingBehavior } from './instance.js';

package/dist/dts/features/ClosingBehavior/instance.d.ts

@@ -0,0 +1,2 @@
+import { ClosingBehavior } from './ClosingBehavior.js';
+export declare const closingBehavior: ClosingBehavior;

package/dist/dts/features/CloudStorage/CloudStorage.d.ts

@@ -0,0 +1,90 @@
+import { Computed } from '@tma.js/signals';
+import { InvokeCustomMethodFpOptions, RequestError } from '@tma.js/bridge';
+import { BetterPromise } from 'better-promises';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithInvokeCustomMethod } from '../../fn-options/withInvokeCustomMethod.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import * as TE from 'fp-ts/TaskEither';
+type CloudStorageTask<T> = TE.TaskEither<RequestError, T>;
+export interface CloudStorageOptions extends WithVersion, WithInvokeCustomMethod, SharedFeatureOptions {
+}
+/**
+ * @since Mini Apps v6.9
+ */
+export declare class CloudStorage {
+    constructor({ version, isTma, invokeCustomMethod }: CloudStorageOptions);
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Deletes specified key or keys from the cloud storage.
+     * @param keyOrKeys - key or keys to delete.
+     * @param options - request execution options.
+     * @since Mini Apps v6.9
+     */
+    readonly deleteItemFp: WithChecksFp<(keyOrKeys: string | string[], options?: InvokeCustomMethodFpOptions) => CloudStorageTask<void>, true>;
+    readonly deleteItem: WithChecks<(keyOrKeys: string | string[], options?: InvokeCustomMethodFpOptions) => BetterPromise<void>, true>;
+    /**
+     * Gets a single key value from the cloud storage.
+     * @param key - a key to get.
+     * @param options - request execution options.
+     * @returns A key value as a string.
+     * @since Mini Apps v6.9
+     */
+    readonly getItemFp: WithChecksFp<(key: string, options?: InvokeCustomMethodFpOptions) => CloudStorageTask<string>, true>;
+    /**
+     * @see getItemFp
+     */
+    readonly getItem: WithChecks<{
+        <K extends string>(keys: K[], options?: InvokeCustomMethodFpOptions): BetterPromise<Record<K, string>>;
+        (key: string, options?: InvokeCustomMethodFpOptions): BetterPromise<string>;
+    }, true>;
+    /**
+     * Gets multiple keys' values from the cloud storage.
+     * @param keys - keys list.
+     * @param options - request execution options.
+     * @returns A map, where a key is one of the specified in the `keys` argument,
+     * and a value is a corresponding storage value if an array of keys was passed.
+     * @since Mini Apps v6.9
+     */
+    readonly getItemsFp: WithChecksFp<(<K extends string>(keys: K[], options?: InvokeCustomMethodFpOptions) => CloudStorageTask<Record<K, string>>), true>;
+    /**
+     * @see getItemsFp
+     */
+    readonly getItems: WithChecks<(<K extends string>(keys: K[], options?: InvokeCustomMethodFpOptions) => BetterPromise<Record<K, string>>), true>;
+    /**
+     * Returns a list of all keys presented in the cloud storage.
+     * @param options - request execution options.
+     * @since Mini Apps v6.9
+     */
+    readonly getKeysFp: WithChecksFp<(options?: InvokeCustomMethodFpOptions) => CloudStorageTask<string[]>, true>;
+    /**
+     * @see getKeysFp
+     */
+    readonly getKeys: WithChecks<(options?: InvokeCustomMethodFpOptions) => BetterPromise<string[]>, true>;
+    /**
+     * Saves the specified value by a key.
+     * @param key - storage key.
+     * @param value - storage value.
+     * @param options - request execution options.
+     * @since Mini Apps v6.9
+     */
+    readonly setItemFp: WithChecksFp<(key: string, value: string, options?: InvokeCustomMethodFpOptions) => CloudStorageTask<void>, true>;
+    /**
+     * @see setItemFp
+     */
+    readonly setItem: WithChecks<(key: string, value: string, options?: InvokeCustomMethodFpOptions) => BetterPromise<void>, true>;
+    /**
+     * Clears the cloud storage.
+     * @param options - additional options.
+     * @since Mini Apps v6.9
+     */
+    readonly clearFp: WithChecksFp<(options?: InvokeCustomMethodFpOptions) => CloudStorageTask<void>, true>;
+    /**
+     * @see clearFp
+     */
+    readonly clear: WithChecks<(options?: InvokeCustomMethodFpOptions) => BetterPromise<void>, true>;
+}
+export {};

package/dist/dts/features/CloudStorage/exports.d.ts

@@ -0,0 +1,2 @@
+export { CloudStorage, type CloudStorageOptions } from './CloudStorage.js';
+export { cloudStorage } from './instance.js';

package/dist/dts/features/CloudStorage/instance.d.ts

@@ -0,0 +1,2 @@
+import { CloudStorage } from './CloudStorage.js';
+export declare const cloudStorage: CloudStorage;

package/dist/dts/features/HapticFeedback/HapticFeedback.d.ts

@@ -0,0 +1,57 @@
+import { Computed } from '@tma.js/signals';
+import { ImpactHapticFeedbackStyle, NotificationHapticFeedbackType, PostEventError } from '@tma.js/bridge';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { WithChecksFp, WithChecks } from '../../with-checks/withChecksFp.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithPostEvent } from '../../fn-options/withPostEvent.js';
+import * as E from 'fp-ts/Either';
+type HapticFeedbackEither = E.Either<PostEventError, void>;
+export interface HapticFeedbackOptions extends WithVersion, WithPostEvent, SharedFeatureOptions {
+}
+/**
+ * @since Mini Apps v6.1
+ */
+export declare class HapticFeedback {
+    constructor({ postEvent, isTma, version }: HapticFeedbackOptions);
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * A method that tells if an impact occurred. The Telegram app may play the
+     * appropriate haptics based on style value passed.
+     * @param style - impact style.
+     * @since Mini Apps v6.1
+     */
+    impactOccurredFp: WithChecksFp<(style: ImpactHapticFeedbackStyle) => HapticFeedbackEither, true>;
+    /**
+     * @see impactOccurredFp
+     */
+    impactOccurred: WithChecks<(style: ImpactHapticFeedbackStyle) => void, true>;
+    /**
+     * 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.
+     * @since Mini Apps v6.1
+     */
+    notificationOccurredFp: WithChecksFp<(type: NotificationHapticFeedbackType) => HapticFeedbackEither, true>;
+    /**
+     * @see notificationOccurredFp
+     */
+    notificationOccurred: WithChecks<(type: NotificationHapticFeedbackType) => void, true>;
+    /**
+     * 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.
+     * @since Mini Apps v6.1
+     */
+    selectionChangedFp: WithChecksFp<() => HapticFeedbackEither, true>;
+    /**
+     * @see selectionChangedFp
+     */
+    selectionChanged: WithChecks<() => void, true>;
+}
+export {};

package/dist/dts/features/HapticFeedback/exports.d.ts

@@ -0,0 +1,2 @@
+export { HapticFeedback, type HapticFeedbackOptions } from './HapticFeedback.js';
+export { hapticFeedback } from './instance.js';

package/dist/dts/features/HapticFeedback/instance.d.ts

@@ -0,0 +1,2 @@
+import { HapticFeedback } from './HapticFeedback.js';
+export declare const hapticFeedback: HapticFeedback;

package/dist/dts/features/InitData/InitData.d.ts

@@ -0,0 +1,84 @@
+import { Computed } from '@tma.js/signals';
+import { InitData as InitDataType } from '@tma.js/types';
+import * as E from 'fp-ts/Either';
+import * as O from 'fp-ts/Option';
+export interface InitDataOptions<Err> {
+    /**
+     * Retrieves init data from the current environment.
+     */
+    retrieveInitData: () => E.Either<Err, O.Option<{
+        raw: string;
+        obj: InitDataType;
+    }>>;
+}
+export declare class InitData<Err extends Error> {
+    constructor({ retrieveInitData }: InitDataOptions<Err>);
+    private fromState;
+    private readonly _state;
+    private readonly _raw;
+    /**
+     * Complete component state.
+     */
+    readonly state: Computed<InitDataType | undefined>;
+    /**
+     * @see InitDataType.auth_date
+     */
+    readonly authDate: Computed<Date | undefined>;
+    /**
+     * @see InitDataType.can_send_after
+     */
+    readonly canSendAfter: Computed<number | undefined>;
+    /**
+     * Date after which it is allowed to call
+     * the [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
+     */
+    readonly canSendAfterDate: Computed<Date | undefined>;
+    /**
+     * @see InitDataType.chat
+     */
+    readonly chat: Computed<import('@tma.js/types').Chat | undefined>;
+    /**
+     * @see InitDataType.chat_type
+     */
+    readonly chatType: Computed<string | undefined>;
+    /**
+     * @see InitDataType.chat_instance
+     */
+    readonly chatInstance: Computed<string | undefined>;
+    /**
+     * @see InitDataType.hash
+     */
+    readonly hash: Computed<string | undefined>;
+    /**
+     * @see InitDataType.query_id
+     */
+    readonly queryId: Computed<string | undefined>;
+    /**
+     * Raw representation of init data.
+     */
+    readonly raw: Computed<string | undefined>;
+    /**
+     * @see InitDataType.receiver
+     */
+    readonly receiver: Computed<import('@tma.js/types').User | undefined>;
+    /**
+     * @see InitDataType.signature
+     */
+    readonly signature: Computed<string | undefined>;
+    /**
+     * @see InitDataType.start_param
+     */
+    readonly startParam: Computed<string | undefined>;
+    /**
+     * @see InitDataType.user
+     */
+    readonly user: Computed<import('@tma.js/types').User | undefined>;
+    /**
+     * Restores the component state.
+     */
+    readonly restoreFp: () => E.Either<Err, void>;
+    /**
+     * @see restoreFp
+     */
+    readonly restore: () => void;
+}

package/dist/dts/features/InitData/exports.d.ts

@@ -0,0 +1,2 @@
+export { InitData, type InitDataOptions } from './InitData.js';
+export { initData } from './instance.js';

package/dist/dts/features/InitData/instance.d.ts

@@ -0,0 +1,2 @@
+import { InitData } from './InitData.js';
+export declare const initData: InitData<import('@tma.js/bridge').RetrieveLaunchParamsError>;

package/dist/dts/features/Invoice/Invoice.d.ts

@@ -0,0 +1,54 @@
+import { Computed } from '@tma.js/signals';
+import { InvoiceStatus, RequestError } from '@tma.js/bridge';
+import { BetterPromise } from 'better-promises';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { AsyncOptions } from '../../types.js';
+import { ConcurrentCallError, InvalidArgumentsError } from '../../errors.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithRequest } from '../../fn-options/withRequest.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import * as TE from 'fp-ts/TaskEither';
+type InvoiceTask<E, T> = TE.TaskEither<RequestError | ConcurrentCallError | E, T>;
+export interface InvoiceOptions extends WithVersion, WithRequest, SharedFeatureOptions {
+}
+/**
+ * @since Mini Apps v6.1
+ */
+export declare class Invoice {
+    constructor({ version, request, isTma }: InvoiceOptions);
+    /**
+     * Signal indicating if any invoice is currently opened.
+     */
+    readonly isOpened: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Opens an invoice using its slug or URL.
+     * @param slug - invoice slug.
+     * @param options - additional options.
+     * @since Mini Apps v6.1
+     * @example
+     * const status = await invoice.openSlug('kJNFS331');
+     */
+    readonly openSlugFp: WithChecksFp<(slug: string, options?: AsyncOptions) => InvoiceTask<never, InvoiceStatus>, true>;
+    /**
+     * @see openSlugFp
+     */
+    readonly openSlug: WithChecks<(slug: string, options?: AsyncOptions) => BetterPromise<InvoiceStatus>, true>;
+    /**
+     * Opens an invoice using its URL.
+     * @param url - invoice URL.
+     * @param options - additional options.
+     * @since Mini Apps v6.1
+     * @example
+     * const status = await invoice.openUrl('https://t.me/$kJNFS331');
+     */
+    readonly openUrlFp: WithChecksFp<(url: string, options?: AsyncOptions) => (InvoiceTask<InvalidArgumentsError, InvoiceStatus>), true>;
+    /**
+     * @see openUrlFp
+     */
+    readonly openUrl: WithChecks<(url: string, options?: AsyncOptions) => BetterPromise<InvoiceStatus>, true>;
+}
+export {};

package/dist/dts/features/Invoice/exports.d.ts

@@ -0,0 +1,2 @@
+export { Invoice, type InvoiceOptions } from './Invoice.js';
+export { invoice } from './instance.js';

package/dist/dts/features/Invoice/instance.d.ts

@@ -0,0 +1,2 @@
+import { Invoice } from './Invoice.js';
+export declare const invoice: Invoice;

package/dist/dts/features/LocationManager/LocationManager.d.ts

@@ -0,0 +1,74 @@
+import { Computed } from '@tma.js/signals';
+import { RequestError, PostEventError } from '@tma.js/bridge';
+import { BetterPromise } from 'better-promises';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { AsyncOptions } from '../../types.js';
+import { LocationManagerOptions, LocationManagerRequestLocationResponse, LocationManagerState } from './types.js';
+import * as E from 'fp-ts/Either';
+import * as TE from 'fp-ts/TaskEither';
+/**
+ * @since Mini Apps v8.0
+ */
+export declare class LocationManager {
+    constructor({ version, request, postEvent, storage, isTma, isPageReload, }: LocationManagerOptions);
+    /**
+     * Complete location manager state.
+     */
+    readonly state: Computed<LocationManagerState>;
+    /**
+     * Signal indicating whether the location data tracking is currently available.
+     */
+    readonly isAvailable: Computed<boolean>;
+    /**
+     * Signal indicating whether the user has granted the app permission to track location data.
+     */
+    readonly isAccessGranted: Computed<boolean>;
+    /**
+     * Signal indicating whether the app has previously requested permission to track location data.
+     */
+    readonly isAccessRequested: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Opens the location access settings for bots. Useful when you need to request location access
+     * from users who haven't granted it yet.
+     *
+     * Note that this method can be called only in response to user interaction with the Mini App
+     * interface (e.g., a click inside the Mini App or on the main button).
+     * @since Mini Apps v8.0
+     */
+    readonly openSettingsFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see openSettingsFp
+     */
+    readonly openSettings: WithChecks<() => void, true>;
+    /**
+     * Requests location data.
+     * @since Mini Apps v8.0
+     * @returns Promise with location data or null it access was not granted.
+     */
+    readonly requestLocationFp: WithChecksFp<(options?: AsyncOptions) => (TE.TaskEither<RequestError, LocationManagerRequestLocationResponse | null>), true>;
+    /**
+     * @see requestLocationFp
+     */
+    readonly requestLocation: WithChecks<(options?: AsyncOptions) => BetterPromise<LocationManagerRequestLocationResponse | null>, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v8.0
+     */
+    readonly mountFp: WithChecksFp<(options?: AsyncOptions) => TE.TaskEither<RequestError, void>, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<(options?: AsyncOptions) => BetterPromise<void>, true>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+}

package/dist/dts/features/LocationManager/exports.d.ts

@@ -0,0 +1,3 @@
+export { LocationManager } from './LocationManager.js';
+export { locationManager } from './instance.js';
+export type { LocationManagerOptions, LocationManagerRequestLocationResponse, LocationManagerState, } from './types.js';

package/dist/dts/features/LocationManager/instance.d.ts

@@ -0,0 +1,2 @@
+import { LocationManager } from './LocationManager.js';
+export declare const locationManager: LocationManager;

package/dist/dts/features/LocationManager/types.d.ts

@@ -0,0 +1,65 @@
+import { Maybe } from '@tma.js/toolkit';
+import { WithStateRestore } from '../../fn-options/withStateRestore.js';
+import { WithRequest } from '../../fn-options/withRequest.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithPostEvent } from '../../fn-options/withPostEvent.js';
+export interface LocationManagerRequestLocationResponse {
+    /**
+     * Latitude in degrees.
+     */
+    latitude: number;
+    /**
+     * Longitude in degrees.
+     */
+    longitude: number;
+    /**
+     * Altitude above sea level in meters.
+     */
+    altitude?: Maybe<number>;
+    /**
+     * The direction the device is moving in degrees.
+     */
+    course?: Maybe<number>;
+    /**
+     * The speed of the device in m/s.
+     */
+    speed?: Maybe<number>;
+    /**
+     * Accuracy of the latitude and longitude values in meters.
+     */
+    horizontal_accuracy?: Maybe<number>;
+    /**
+     * Accuracy of the altitude value in meters.
+     */
+    vertical_accuracy?: Maybe<number>;
+    /**
+     * Accuracy of the course value in degrees.
+     */
+    course_accuracy?: Maybe<number>;
+    /**
+     * Accuracy of the speed value in m/s.
+     */
+    speed_accuracy?: Maybe<number>;
+}
+export interface LocationManagerState {
+    /**
+     * If true, indicates that location data tracking is available on the current device.
+     */
+    available: boolean;
+    /**
+     * Indicates whether the app has previously requested permission to track location data.
+     */
+    accessRequested: boolean;
+    /**
+     * Indicates whether the user has granted the app permission to track location data.
+     *
+     * If false and `accessRequested` is true may indicate that:
+     *
+     * - The user has simply canceled the permission popup.
+     * - The user has denied the app permission to track location data.
+     */
+    accessGranted: boolean;
+}
+export interface LocationManagerOptions extends WithStateRestore<LocationManagerState>, WithRequest, WithVersion, WithPostEvent, SharedFeatureOptions {
+}