@vbotma/sdk 3.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vladislav Kibenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @vbotma/sdk
+
+[code-badge]: https://img.shields.io/badge/source-black?logo=github
+
+[docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
+
+[link]: https://github.com/Telegram-Mini-Apps/tma.js/tree/master/tma.js/sdk
+
+[docs-link]: https://docs.vbot-mini-apps.com/packages/tma-js-sdk
+
+[npm-link]: https://npmjs.com/package/@vbotma/sdk
+
+[npm-badge]: https://img.shields.io/npm/v/@vbotma/sdk?logo=npm
+
+[size-badge]: https://img.shields.io/bundlephobia/minzip/@vbotma/sdk
+
+[![NPM][npm-badge]][npm-link]
+![Size][size-badge]
+[![docs-badge]][docs-link]
+[![code-badge]][link]
+
+Made from scratch TypeScript library for seamless communication with VBot Mini Apps
+functionality.
+
+The code of this library is designed to simplify the process of developers interacting with Telegram
+Mini Apps. It consists of several individual components, each responsible for a specific aspect of
+the VBot Mini Apps ecosystem.
+
+Before you begin using the SDK, we highly recommend familiarizing yourself with the Telegram Mini
+Apps [documentation](https://docs.vbot-mini-apps.com/platform/about)
+to grasp the fundamental concepts of the platform.
+
+## Installation
+
+```bash
+# pnpm
+pnpm i @vbotma/sdk
+
+# yarn
+yarn add @vbotma/sdk
+
+# npm
+npm i @vbotma/sdk
+```
+
+## Usage Example
+
+```typescript
+import { init, backButton } from '@vbotma/sdk';
+
+// Initialize all library dependencies.
+init();
+
+// Mount all required components used across the application.
+// This will lead to components' state restoration.
+backButton.mount();
+backButton.onClick(() => {
+  window.history.back();
+});
+```
+
+## Documentation
+
+You can find complete documentation over the library [here](https://docs.vbot-mini-apps.com/packages/tma-js-sdk).

package/dist/dts/composables/AsyncMountable.d.ts

@@ -0,0 +1,44 @@
+import { taskEither as TE } from 'fp-ts';
+import { AsyncOptions, MaybeAccessor } from '../types.js';
+export interface AsyncMountableOptions<S, E> {
+    /**
+     * A function to retrieve the initial state.
+     * @param options - additional options.
+     */
+    initialState: (options?: AsyncOptions) => TE.TaskEither<E, S>;
+    /**
+     * @returns True if the current page was reloaded.
+     */
+    isPageReload: MaybeAccessor<boolean>;
+    /**
+     * A function to call whenever the component was mounted.
+     * @param state - restored state.
+     */
+    onMounted?: (state: S) => void;
+    /**
+     * A function to call whenever the component was unmounted.
+     */
+    onUnmounted?: VoidFunction;
+    /**
+     * Attempts to restore previously saved component state. This function
+     * will only be called if the current page was reloaded.
+     */
+    restoreState: () => (S | undefined);
+}
+export declare class AsyncMountable<S extends object, E> {
+    constructor({ initialState, onMounted, restoreState, onUnmounted, isPageReload, }: AsyncMountableOptions<S, E>);
+    private readonly _isMounted;
+    /**
+     * Signal indicating if the component is mounted.
+     */
+    readonly isMounted: import('@vbotma/signals').Computed<boolean>;
+    /**
+     * Mounts the component restoring its state and calling required side effects.
+     * @param options - additional execution options.
+     */
+    readonly mount: (options?: AsyncOptions) => TE.TaskEither<E, void>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+}

package/dist/dts/composables/Button.d.ts

@@ -0,0 +1,140 @@
+import { PostEventError, MethodName, MethodParams } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { either as E } from 'fp-ts';
+import { SharedFeatureOptions } from '../fn-options/sharedFeatureOptions.js';
+import { WithPostEvent } from '../fn-options/withPostEvent.js';
+import { WithStateRestore } from '../fn-options/withStateRestore.js';
+import { WithVersion } from '../fn-options/withVersion.js';
+import { WithChecksFp, WithChecks } from '../with-checks/withChecksFp.js';
+type ButtonEither = E.Either<PostEventError, void>;
+type BoolFields<S> = {
+    [K in keyof S]-?: S[K] extends boolean ? K : never;
+}[keyof S];
+export interface ButtonOptions<S, M extends MethodName> extends SharedFeatureOptions, WithStateRestore<S>, WithPostEvent, WithVersion {
+    /**
+     * The initial button state.
+     */
+    initialState: S;
+    /**
+     * Removes a component click listener.
+     * @param listener - a listener to remove.
+     * @param once - should the listener be called only once.
+     */
+    offClick: (listener: VoidFunction, once?: boolean) => void;
+    /**
+     * Adds a component click listener.
+     * @returns A function to remove listener.
+     * @param listener - a listener to add.
+     * @param once - should the listener be called only once.
+     */
+    onClick: (listener: VoidFunction, once?: boolean) => VoidFunction;
+    /**
+     * A Mini Apps method to commit changes.
+     */
+    method: M;
+    /**
+     * A function to create method payload.
+     * @param state
+     */
+    payload: (state: S) => MethodParams<M>;
+}
+export declare class Button<S extends object, M extends MethodName> {
+    constructor({ isTma, storage, onClick, offClick, initialState, isPageReload, postEvent, payload, method, version, }: ButtonOptions<S, M>);
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Complete button state.
+     */
+    readonly state: Computed<S>;
+    /**
+     * @returns A computed based on the specified state and its related key.
+     * @param key - a key to use.
+     */
+    stateGetter<K extends keyof S>(key: K): Computed<S[K]>;
+    /**
+     * @returns A setter with checks for the specified key.
+     * @param key
+     */
+    readonly stateSetters: <K extends keyof S>(key: K) => [
+        throwing: WithChecks<(value: S[K]) => void, true>,
+        fp: WithChecksFp<(value: S[K]) => ButtonEither, true>
+    ];
+    /**
+     * @returns Setters with checks to set a specified boolean key.
+     * @param key
+     */
+    readonly stateBoolSetters: <K extends BoolFields<S>>(key: K) => [
+        setFalse: [
+            throwing: WithChecks<() => void, true>,
+            fp: WithChecksFp<() => ButtonEither, true>
+        ],
+        setTrue: [
+            throwing: WithChecks<() => void, true>,
+            fp: WithChecksFp<() => ButtonEither, true>
+        ]
+    ];
+    /**
+     * Updates the button state.
+     */
+    readonly setStateFp: WithChecksFp<(state: Partial<S>) => ButtonEither, true>;
+    /**
+     * @see setStateFp
+     */
+    readonly setState: WithChecks<(state: Partial<S>) => void, true>;
+    /**
+     * Adds a new button listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @returns A function to remove bound listener.
+     * @example
+     * const off = button.onClick(() => {
+     *   console.log('User clicked the button');
+     *   off();
+     * });
+     */
+    readonly onClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * @see onClickFp
+     */
+    readonly onClick: WithChecks<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * Removes the button click listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @example
+     * function listener() {
+     *   console.log('User clicked the button');
+     *   button.offClick(listener);
+     * }
+     * button.onClick(listener);
+     */
+    readonly offClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * @see offClickFp
+     */
+    readonly offClick: WithChecks<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v6.1
+     */
+    readonly mountFp: WithChecksFp<() => void, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, true>;
+    /**
+     * Unmounts the component.
+     *
+     * Note that this function does not remove listeners added via the `onClick`
+     * function, so you have to remove them on your own.
+     * @see onClick
+     */
+    readonly unmount: () => void;
+}
+export {};

package/dist/dts/composables/Mountable.d.ts

@@ -0,0 +1,43 @@
+import { either as E } from 'fp-ts';
+import { MaybeAccessor } from '../types.js';
+export interface MountableOptions<S, Err> {
+    /**
+     * A state to use if the `restoreState` function returned falsy value or
+     * `isPageReload` returned false.
+     */
+    initialState: S | (() => E.Either<Err, S>);
+    /**
+     * @returns True if the current page was reloaded.
+     */
+    isPageReload: MaybeAccessor<boolean>;
+    /**
+     * A function to call whenever the component was mounted.
+     * @param state - restored state.
+     */
+    onMounted?: (state: S) => void;
+    /**
+     * A function to call whenever the component was unmounted.
+     */
+    onUnmounted?: VoidFunction;
+    /**
+     * Attempts to restore previously saved component state. This function
+     * will only be called if the current page was reloaded.
+     */
+    restoreState: () => (S | undefined);
+}
+export declare class Mountable<S extends object, Err = never> {
+    constructor({ onMounted, restoreState, initialState, onUnmounted, isPageReload, }: MountableOptions<S, Err>);
+    private readonly _isMounted;
+    /**
+     * Signal indicating if the component is mounted.
+     */
+    readonly isMounted: import('@vbotma/signals').Computed<boolean>;
+    /**
+     * Mounts the component restoring its state and calling required side effects.
+     */
+    readonly mount: () => E.Either<Err, void>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+}

package/dist/dts/composables/Stateful.d.ts

@@ -0,0 +1,35 @@
+import { Computed, Signal } from '@vbotma/signals';
+export interface StatefulOptions<S> {
+    /**
+     * The initial state.
+     */
+    initialState: S;
+    /**
+     * A function to call whenever the state changes.
+     * @param state - updated state.
+     */
+    onChange: (state: S) => void;
+}
+export declare class Stateful<S extends object> {
+    constructor({ initialState, onChange }: StatefulOptions<S>);
+    protected readonly _state: Signal<S>;
+    /**
+     * The current state.
+     */
+    readonly state: Computed<S>;
+    /**
+     * Creates a computed signal based on the state.
+     * @param key - a state key to use as a source.
+     */
+    getter<K extends keyof S>(key: K): Computed<S[K]>;
+    /**
+     * Updates the state.
+     * @param state - updates to apply.
+     */
+    readonly setState: (state: Partial<S>) => void;
+    /**
+     * @returns True if specified payload will update the state.
+     * @param state
+     */
+    hasDiff(state: Partial<S>): boolean;
+}

package/dist/dts/errors.d.ts

@@ -0,0 +1,51 @@
+import { BaseIssue } from 'valibot';
+declare const ValidationError_base: import('error-kid').ErrorClassWithData<[input: unknown, issues: BaseIssue<any>[]], {
+    input: unknown;
+    issues: BaseIssue<any>[];
+}>;
+export declare class ValidationError extends /* #__PURE__ */ ValidationError_base {
+}
+declare const CSSVarsBoundError_base: import('error-kid').ErrorClass<[]>;
+export declare class CSSVarsBoundError extends /* #__PURE__ */ CSSVarsBoundError_base {
+}
+declare const DeviceStorageMethodError_base: import('error-kid').ErrorClassWithData<[error: string], {
+    error: string;
+}>;
+export declare class DeviceStorageMethodError extends /* #__PURE__ */ DeviceStorageMethodError_base {
+}
+declare const SecureStorageMethodError_base: import('error-kid').ErrorClassWithData<[error: string], {
+    error: string;
+}>;
+export declare class SecureStorageMethodError extends /* #__PURE__ */ SecureStorageMethodError_base {
+}
+declare const NotAvailableError_base: import('error-kid').ErrorClass<[message: string]>;
+export declare class NotAvailableError extends /* #__PURE__ */ NotAvailableError_base {
+}
+declare const InvalidEnvError_base: import('error-kid').ErrorClass<[message?: string | undefined]>;
+export declare class InvalidEnvError extends /* #__PURE__ */ InvalidEnvError_base {
+}
+declare const FunctionUnavailableError_base: import('error-kid').ErrorClass<[message?: string | undefined]>;
+export declare class FunctionUnavailableError extends /* #__PURE__ */ FunctionUnavailableError_base {
+}
+declare const InvalidArgumentsError_base: import('error-kid').ErrorClass<[message: string, cause?: unknown]>;
+export declare class InvalidArgumentsError extends /* #__PURE__ */ InvalidArgumentsError_base {
+}
+declare const ConcurrentCallError_base: import('error-kid').ErrorClass<[message: string]>;
+export declare class ConcurrentCallError extends /* #__PURE__ */ ConcurrentCallError_base {
+}
+declare const SetEmojiStatusError_base: import('error-kid').ErrorClass<[error: string]>;
+export declare class SetEmojiStatusError extends /* #__PURE__ */ SetEmojiStatusError_base {
+}
+declare const AccessDeniedError_base: import('error-kid').ErrorClass<[message: string]>;
+export declare class AccessDeniedError extends /* #__PURE__ */ AccessDeniedError_base {
+}
+declare const FullscreenFailedError_base: import('error-kid').ErrorClass<[message: string]>;
+export declare class FullscreenFailedError extends /* #__PURE__ */ FullscreenFailedError_base {
+}
+declare const ShareMessageError_base: import('error-kid').ErrorClass<[error: string]>;
+export declare class ShareMessageError extends /* #__PURE__ */ ShareMessageError_base {
+}
+declare const UnknownThemeParamsKeyError_base: import('error-kid').ErrorClass<[key: string]>;
+export declare class UnknownThemeParamsKeyError extends /* #__PURE__ */ UnknownThemeParamsKeyError_base {
+}
+export {};

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

@@ -0,0 +1,96 @@
+import { PostEventError } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { either as E } from 'fp-ts';
+import { ButtonOptions } from '../../composables/Button.js';
+import { WithChecksFp, WithChecks } from '../../with-checks/withChecksFp.js';
+export interface BackButtonState {
+    isVisible: boolean;
+}
+export type BackButtonOptions = Omit<ButtonOptions<BackButtonState, 'web_app_setup_back_button'>, 'method' | 'payload' | 'initialState'>;
+/**
+ * @since Mini Apps v6.1
+ */
+export declare class BackButton {
+    constructor(options: BackButtonOptions);
+    /**
+     * Signal indicating if the component is currently visible.
+     */
+    readonly isVisible: 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>;
+    /**
+     * Hides the button.
+     * @since Mini Apps v6.1
+     */
+    readonly hideFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see hideFp
+     */
+    readonly hide: WithChecks<() => void, true>;
+    /**
+     * Shows the button.
+     * @since Mini Apps v6.1
+     */
+    readonly showFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see showFp
+     */
+    readonly show: WithChecks<() => void, true>;
+    /**
+     * Adds a new button listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @returns A function to remove bound listener.
+     * @since Mini Apps v6.1
+     * @example
+     * const off = button.onClick(() => {
+     *   console.log('User clicked the button');
+     *   off();
+     * });
+     */
+    readonly onClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * @see onClickFp
+     */
+    readonly onClick: WithChecks<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * Removes the button click listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @since Mini Apps v6.1
+     * @example
+     * function listener() {
+     *   console.log('User clicked the button');
+     *   button.offClick(listener);
+     * }
+     * button.onClick(listener);
+     */
+    readonly offClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * @see offClickFp
+     */
+    readonly offClick: WithChecks<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v6.1
+     */
+    readonly mountFp: WithChecksFp<() => void, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, true>;
+    /**
+     * Unmounts the component.
+     *
+     * Note that this function does not remove listeners added via the `onClick`
+     * function, so you have to remove them on your own.
+     * @see onClick
+     */
+    readonly unmount: () => void;
+}

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

@@ -0,0 +1,2 @@
+export { BackButton, type BackButtonState, type BackButtonOptions } from './BackButton.js';
+export { backButton } from './instance.js';

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

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

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

@@ -0,0 +1,121 @@
+import { RequestError, PostEventError, BiometryAuthRequestStatus, BiometryTokenUpdateStatus } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { BetterPromise } from 'better-promises';
+import { either as E, taskEither as TE } from 'fp-ts';
+import { BiometryAuthenticateOptions, BiometryOptions, BiometryRequestAccessOptions, BiometryState, BiometryUpdateTokenOptions } from './types.js';
+import { AsyncOptions } from '../../types.js';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+type BiometryTask<T> = TE.TaskEither<RequestError, T>;
+interface AuthenticateResult {
+    /**
+     * Authentication status.
+     */
+    status: BiometryAuthRequestStatus;
+    /**
+     * Token from the local secure storage saved previously.
+     */
+    token?: string;
+}
+/**
+ * @since Mini Apps v7.2
+ */
+export declare class Biometry {
+    constructor({ version, request, postEvent, storage, onInfoReceived, offInfoReceived, isTma, isPageReload, }: BiometryOptions);
+    /**
+     * Signal indicating if biometry is available.
+     */
+    readonly isAvailable: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Signal indicating if the component is mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Complete component state.
+     */
+    readonly state: Computed<BiometryState>;
+    /**
+     * Attempts to authenticate a user using biometrics and fetch a previously stored secure token.
+     * @param options - method options.
+     * @since Mini Apps v7.2
+     * @returns Token from the local secure storage saved previously or undefined.
+     * @example
+     * const { status, token } = await biometry.authenticate({
+     *   reason: 'Authenticate to open wallet',
+     * });
+     */
+    readonly authenticateFp: WithChecksFp<(options?: BiometryAuthenticateOptions) => BiometryTask<{
+        /**
+         * Authentication status.
+         */
+        status: BiometryAuthRequestStatus;
+        /**
+         * Token from the local secure storage saved previously.
+         */
+        token?: string;
+    }>, true>;
+    /**
+     * @see authenticateFp
+     */
+    readonly authenticate: WithChecks<(options?: BiometryAuthenticateOptions) => BetterPromise<AuthenticateResult>, true>;
+    /**
+     * Opens the biometric access settings for bots. Useful when you need to request biometrics
+     * access to 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 v7.2
+     */
+    readonly openSettingsFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see openSettingsFp
+     */
+    readonly openSettings: WithChecks<() => void, true>;
+    /**
+     * Requests permission to use biometrics.
+     * @since Mini Apps v7.2
+     * @returns Promise with true, if access was granted.
+     * @example
+     * const accessGranted = await biometry.requestAccess({
+     *   reason: 'Authenticate to open wallet',
+     * });
+     */
+    readonly requestAccessFp: WithChecksFp<(options?: BiometryRequestAccessOptions) => BiometryTask<boolean>, true>;
+    /**
+     * @see requestAccessFp
+     */
+    readonly requestAccess: WithChecks<(options?: BiometryRequestAccessOptions) => BetterPromise<boolean>, true>;
+    /**
+     * Updates the biometric token in a secure storage on the device.
+     * @since Mini Apps v7.2
+     * @returns Promise with `true`, if token was updated.
+     * @example Setting a new token
+     * biometry.updateToken({
+     *   token: 'abcdef',
+     * })
+     * @example Deleting the token
+     * biometry.updateToken();
+     */
+    readonly updateTokenFp: WithChecksFp<(options?: BiometryUpdateTokenOptions) => BiometryTask<BiometryTokenUpdateStatus>, true>;
+    /**
+     * @see updateTokenFp
+     */
+    readonly updateToken: WithChecks<(options?: BiometryUpdateTokenOptions) => BetterPromise<BiometryTokenUpdateStatus>, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v7.2
+     */
+    readonly mountFp: WithChecksFp<(options?: AsyncOptions) => BiometryTask<void>, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<(options?: AsyncOptions) => BetterPromise<void>, true>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+}
+export {};

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

@@ -0,0 +1,3 @@
+export { Biometry } from './Biometry.js';
+export { biometry } from './instance.js';
+export type { BiometryState, BiometryUpdateTokenOptions, BiometryAuthenticateOptions, BiometryRequestAccessOptions, } from './types.js';

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

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