@vbotma/sdk 3.1.8

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

@@ -0,0 +1,65 @@
+import { Maybe } from '@vbotma/toolkit';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { WithPostEvent } from '../../fn-options/withPostEvent.js';
+import { WithRequest } from '../../fn-options/withRequest.js';
+import { WithStateRestore } from '../../fn-options/withStateRestore.js';
+import { WithVersion } from '../../fn-options/withVersion.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 {
+}

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

@@ -0,0 +1,214 @@
+import { PostEventError } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { RGB } from '@vbotma/types';
+import { either as E } from 'fp-ts';
+import { ButtonOptions } from '../../composables/Button.js';
+import { MaybeAccessor } from '../../types.js';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+type MainButtonEither = E.Either<PostEventError, void>;
+export interface MainButtonState {
+    isVisible: boolean;
+    bgColor?: RGB;
+    hasShineEffect: boolean;
+    isEnabled: boolean;
+    isLoaderVisible: boolean;
+    text: string;
+    textColor?: RGB;
+}
+export interface MainButtonOptions extends Omit<ButtonOptions<MainButtonState, 'web_app_setup_main_button'>, 'initialState' | 'method' | 'payload' | 'version'> {
+    /**
+     * Default values for different kinds of the button properties.
+     */
+    defaults: {
+        bgColor: MaybeAccessor<RGB>;
+        textColor: MaybeAccessor<RGB>;
+    };
+}
+export declare class MainButton {
+    constructor({ defaults, ...options }: MainButtonOptions);
+    /**
+     * The button background color.
+     */
+    readonly bgColor: Computed<RGB>;
+    /**
+     * True if the button has a shining effect.
+     */
+    readonly hasShineEffect: Computed<boolean>;
+    /**
+     * True if the button is clickable.
+     */
+    readonly isEnabled: Computed<boolean>;
+    /**
+     * True if the button loader is visible.
+     */
+    readonly isLoaderVisible: Computed<boolean>;
+    /**
+     * True if the button is visible.
+     */
+    readonly isVisible: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * The complete button state.
+     */
+    readonly state: Computed<MainButtonState>;
+    /**
+     * The button displayed text.
+     */
+    readonly text: Computed<string>;
+    /**
+     * The button text color.
+     *
+     * Note that this value is computed based on the external defaults. For
+     * example, if not explicitly set, this value may be equal to one of theme
+     * params colors.
+     */
+    readonly textColor: Computed<RGB>;
+    /**
+     * Shows the button.
+     */
+    readonly showFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see showFp
+     */
+    readonly show: WithChecks<() => void, false>;
+    /**
+     * Hides the button.
+     */
+    readonly hideFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see hideFp
+     */
+    readonly hide: WithChecks<() => void, false>;
+    /**
+     * Enables the button.
+     */
+    readonly enableFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see enableFp
+     */
+    readonly enable: WithChecks<() => void, false>;
+    /**
+     * Enables the button.
+     */
+    readonly enableShineEffectFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see enableShineEffectFp
+     */
+    readonly enableShineEffect: WithChecks<() => void, false>;
+    /**
+     * Disables the button.
+     */
+    readonly disableFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see disableFp
+     */
+    readonly disable: WithChecks<() => void, false>;
+    /**
+     * Enables the button.
+     */
+    readonly disableShineEffectFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see disableShineEffectFp
+     */
+    readonly disableShineEffect: WithChecks<() => void, false>;
+    /**
+     * Updates the button background color.
+     */
+    readonly setBgColorFp: WithChecksFp<(value: RGB) => MainButtonEither, false>;
+    /**
+     * @see setBgColorFp
+     */
+    readonly setBgColor: WithChecks<(value: RGB) => void, false>;
+    /**
+     * Updates the button text color.
+     */
+    readonly setTextColorFp: WithChecksFp<(value: RGB) => MainButtonEither, false>;
+    /**
+     * @see setTextColorFp
+     */
+    readonly setTextColor: WithChecks<(value: RGB) => void, false>;
+    /**
+     * Updates the button text.
+     */
+    readonly setTextFp: WithChecksFp<(value: string) => MainButtonEither, false>;
+    /**
+     * @see setTextFp
+     */
+    readonly setText: WithChecks<(value: string) => void, false>;
+    /**
+     * Shows the button loader.
+     */
+    readonly showLoaderFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see showLoaderFp
+     */
+    readonly showLoader: WithChecks<() => void, false>;
+    /**
+     * Hides the button loader.
+     */
+    readonly hideLoaderFp: WithChecksFp<() => MainButtonEither, false>;
+    /**
+     * @see hideLoaderFp
+     */
+    readonly hideLoader: WithChecks<() => void, false>;
+    /**
+     * Updates the button state.
+     * @param state - updates to apply.
+     * @example
+     * button.setParams({
+     *   text: 'Submit',
+     *   isEnabled: true,
+     *   hasShineEffect: true,
+     * });
+     */
+    readonly setParamsFp: WithChecksFp<(state: Partial<MainButtonState>) => MainButtonEither, false>;
+    readonly setParams: WithChecks<(state: Partial<MainButtonState>) => void, false>;
+    /**
+     * Mounts the component restoring its state.
+     */
+    readonly mountFp: WithChecksFp<() => void, false>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, false>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+    /**
+     * 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, false>;
+    /**
+     * @see onClickFp
+     */
+    readonly onClick: WithChecks<(listener: VoidFunction, once?: boolean) => VoidFunction, false>;
+    /**
+     * 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, false>;
+    /**
+     * @see offClickFp
+     */
+    readonly offClick: WithChecks<(listener: VoidFunction, once?: boolean) => void, false>;
+}
+export {};

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

@@ -0,0 +1,2 @@
+export { mainButton } from './instance.js';
+export { type MainButtonOptions, MainButton, type MainButtonState } from './MainButton.js';

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

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

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

@@ -0,0 +1,192 @@
+import { PostEventError, EventPayload } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { KnownThemeParamsKey, RGB, ThemeParams } from '@vbotma/types';
+import { either as E } from 'fp-ts';
+import { CSSVarsBoundError, UnknownThemeParamsKeyError } from '../../errors.js';
+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 { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+type AnyColor = RGB | KnownThemeParamsKey | string;
+export interface MiniAppState {
+    bgColor: AnyColor;
+    bottomBarColor: AnyColor;
+    headerColor: AnyColor;
+    isActive: boolean;
+}
+export interface MiniAppGetCssVarNameFn {
+    /**
+     * @param property - mini app property.
+     * @returns Computed complete CSS variable name.
+     */
+    (property: 'bgColor' | 'bottomBarColor' | 'headerColor'): string;
+}
+type WithListeners<Handlers extends string, Payload> = {
+    [K in Handlers]: (listener: (payload: Payload) => void) => void;
+};
+export interface MiniAppOptions extends WithPostEvent, WithVersion, WithStateRestore<MiniAppState>, WithListeners<'onVisibilityChanged' | 'offVisibilityChanged', EventPayload<'visibility_changed'>>, SharedFeatureOptions {
+    /**
+     * The current theme parameters.
+     */
+    theme: Computed<ThemeParams>;
+}
+/**
+ * @since Mini Apps v6.1
+ */
+export declare class MiniApp {
+    constructor({ storage, isPageReload, version, postEvent, isTma, theme, onVisibilityChanged, offVisibilityChanged, }: MiniAppOptions);
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * True if the current Mini App background color is recognized as dark.
+     */
+    readonly isDark: Computed<boolean>;
+    /**
+     * Signal indicating if the mini app is currently active.
+     */
+    readonly isActive: Computed<boolean>;
+    /**
+     * Complete component state.
+     */
+    readonly state: Computed<MiniAppState>;
+    /**
+     * True if the CSS variables are currently bound.
+     */
+    readonly isCssVarsBound: Computed<boolean>;
+    /**
+     * Creates CSS variables connected with the mini app.
+     *
+     * Default variables:
+     * - `--tg-bg-color`
+     * - `--tg-header-color`
+     * - `--tg-bottom-bar-color`
+     *
+     * Variables are being automatically updated if theme parameters were changed.
+     *
+     * @param getCSSVarName - function, returning complete CSS variable name for the specified
+     * mini app key.
+     * @returns Function to stop updating variables.
+     * @example Using no arguments
+     * miniApp.bindCssVars();
+     * @example Using custom CSS vars generator
+     * miniApp.bindCssVars(key => `--my-prefix-${key}`);
+     */
+    readonly bindCssVarsFp: WithChecksFp<(getCssVarName?: MiniAppGetCssVarNameFn) => E.Either<CSSVarsBoundError, VoidFunction>, false>;
+    readonly bindCssVars: WithChecks<(getCssVarName?: MiniAppGetCssVarNameFn) => VoidFunction, false>;
+    /**
+     * Signal indicating if the component is mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Mounts the component.
+     *
+     * This function restores the component state and is automatically saving it in the local storage
+     * if it changed.
+     * @since Mini Apps v6.1
+     */
+    readonly mountFp: WithChecksFp<() => void, false>;
+    /**
+     * @see mount
+     */
+    readonly mount: WithChecks<() => void, false>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+    /**
+     * The Mini App background color.
+     *
+     * Represents an RGB color, or theme parameters key, like "bg_color", "secondary_bg_color", etc.
+     *
+     * Note that using a theme parameters key, background color becomes bound to the current
+     * theme parameters, making it automatically being updated whenever theme parameters change.
+     * In order to remove this bind, use an explicit RGB color.
+     */
+    readonly bgColor: Computed<AnyColor>;
+    /**
+     * RGB representation of the background color.
+     *
+     * This value requires the Theme Params component to be mounted to extract a valid RGB value
+     * of the color key.
+     */
+    readonly bgColorRgb: Computed<RGB | undefined>;
+    /**
+     * Updates the mini app background color.
+     * @since Mini Apps v6.1
+     */
+    readonly setBgColorFp: WithChecksFp<(color: AnyColor) => E.Either<PostEventError | UnknownThemeParamsKeyError, void>, true>;
+    /**
+     * @see setBgColorFp
+     */
+    readonly setBgColor: WithChecks<(color: AnyColor) => void, true>;
+    /**
+     * The Mini App header color.
+     */
+    readonly headerColor: Computed<AnyColor>;
+    /**
+     * RGB representation of the header color.
+     *
+     * This value requires the Theme Params component to be mounted to extract a valid RGB value
+     * of the color key.
+     */
+    readonly headerColorRgb: Computed<RGB | undefined>;
+    /**
+     * Updates the mini app header color.
+     * @since Mini Apps v6.1
+     */
+    readonly setHeaderColorFp: WithChecksFp<(color: AnyColor) => E.Either<PostEventError | UnknownThemeParamsKeyError, void>, true, 'rgb'>;
+    /**
+     * @see setHeaderColorFp
+     */
+    readonly setHeaderColor: WithChecks<(color: AnyColor) => void, true, 'rgb'>;
+    /**
+     * The Mini App bottom bar background color.
+     */
+    readonly bottomBarColor: Computed<AnyColor>;
+    /**
+     * RGB representation of the bottom bar background color.
+     *
+     * This value requires the Theme Params component to be mounted to extract a valid RGB value
+     * of the color key.
+     */
+    readonly bottomBarColorRgb: Computed<RGB | undefined>;
+    /**
+     * Updates the mini app bottom bar bg color.
+     * @since Mini Apps v7.10
+     */
+    readonly setBottomBarColorFp: WithChecksFp<(color: AnyColor) => E.Either<PostEventError | UnknownThemeParamsKeyError, void>, true>;
+    /**
+     * @see setBottomBarColorFp
+     */
+    readonly setBottomBarColor: WithChecks<(color: AnyColor) => void, true>;
+    /**
+     * Closes the Mini App.
+     * @param returnBack - should the client return to the previous activity.
+     */
+    readonly closeFp: WithChecksFp<(returnBack?: boolean) => E.Either<PostEventError, void>, false>;
+    /**
+     * @see closeFp
+     */
+    readonly close: WithChecks<(returnBack?: boolean) => void, false>;
+    /**
+     * Informs the Telegram app that the Mini App is ready to be displayed.
+     *
+     * It is recommended to call this method as early as possible, as soon as all
+     * essential interface elements loaded.
+     *
+     * Once this method is called, the loading placeholder is hidden and the Mini
+     * App shown.
+     *
+     * If the method is not called, the placeholder will be hidden only when the
+     * page was fully loaded.
+     */
+    readonly readyFp: WithChecksFp<() => E.Either<PostEventError, void>, false>;
+    /**
+     * @see readyFp
+     */
+    readonly ready: WithChecks<() => void, false>;
+}
+export {};

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

@@ -0,0 +1,2 @@
+export { type MiniAppState, MiniApp, type MiniAppOptions, type MiniAppGetCssVarNameFn, } from './MiniApp.js';
+export { miniApp } from './instance.js';

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

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

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

@@ -0,0 +1,21 @@
+import { UnknownEnvError } from '@vbotma/bridge';
+import { BetterPromise } from 'better-promises';
+import { taskEither as TE } from 'fp-ts';
+import { NotificationOptions, SendNotificationOptions } from './types.js';
+/**
+ * Notification feature class.
+ * @since v9.2
+ */
+export declare class Notification {
+    constructor({}: NotificationOptions);
+    /**
+     * Sends a notification to the native app.
+     * @param options - notification options including message, optional title, and optional type (defaults to 'default')
+     * @since v9.2
+     */
+    readonly sendFp: (options: SendNotificationOptions) => TE.TaskEither<UnknownEnvError, void>;
+    /**
+     * @see sendFp
+     */
+    readonly send: (options: SendNotificationOptions) => BetterPromise<void>;
+}

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

@@ -0,0 +1,3 @@
+export type { NotificationOptions, NotificationType, SendNotificationOptions, } from './types.js';
+export { Notification } from './Notification.js';
+export { notification } from './instance.js';

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

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

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

@@ -0,0 +1,19 @@
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+export interface NotificationOptions extends SharedFeatureOptions {
+}
+export type NotificationType = 'default' | 'info' | 'success' | 'warning' | 'error';
+export interface SendNotificationOptions {
+    /**
+     * The message content to display.
+     */
+    message: string;
+    /**
+     * Optional title for the notification.
+     */
+    title?: string;
+    /**
+     * The type of notification.
+     * @default 'default'
+     */
+    type?: NotificationType;
+}

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

@@ -0,0 +1,56 @@
+import { RequestError } from '@vbotma/bridge';
+import { Computed } from '@vbotma/signals';
+import { BetterPromise } from 'better-promises';
+import { taskEither as TE } from 'fp-ts';
+import { ConcurrentCallError, InvalidArgumentsError } from '../../errors.js';
+import { ShowOptions } from './types.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { WithRequest } from '../../fn-options/withRequest.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithChecksFp, WithChecks } from '../../with-checks/withChecksFp.js';
+export interface PopupOptions extends SharedFeatureOptions, WithVersion, WithRequest {
+}
+/**
+ * @since Mini Apps v6.2
+ */
+export declare class Popup {
+    constructor({ version, isTma, request }: PopupOptions);
+    /**
+     * Signal indicating if any popup is currently opened.
+     */
+    readonly isOpened: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * A method that shows a native popup described by the `params` argument.
+     * The promise will be resolved when the popup is closed. Resolved value will have
+     * an identifier of the pressed button.
+     *
+     * If a user clicked outside the popup or clicked the top right popup close
+     * button, null will be resolved.
+     *
+     * @param options - popup parameters.
+     * @since Mini Apps v6.2
+     * @example
+     * fn.pipe(
+     *   popup.showFp({
+     *     title: 'Confirm action',
+     *     message: 'Do you really want to buy this burger?',
+     *     buttons: [
+     *       { id: 'yes', text: 'Yes' },
+     *       { id: 'no', type: 'destructive', text: 'No' },
+     *     ],
+     *   }),
+     *   TE.map(buttonId => {
+     *     console.log('User clicked a button with ID', buttonId);
+     *   }),
+     * );
+     */
+    readonly showFp: WithChecksFp<(options: ShowOptions) => TE.TaskEither<RequestError | InvalidArgumentsError | ConcurrentCallError, string | undefined>, true>;
+    /**
+     * @see showFp
+     */
+    readonly show: WithChecks<(options: ShowOptions) => BetterPromise<string | undefined>, true>;
+}

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

@@ -0,0 +1,3 @@
+export { popup } from './instance.js';
+export { Popup, type PopupOptions } from './Popup.js';
+export type { ShowOptions, ShowOptionsButton } from './types.js';

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

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

package/dist/dts/features/Popup/prepareParams.d.ts

@@ -0,0 +1,9 @@
+import { PopupParams } from '@vbotma/bridge';
+import { either as E } from 'fp-ts';
+import { InvalidArgumentsError } from '../../errors.js';
+import { ShowOptions } from './types.js';
+/**
+ * Prepares popup parameters before sending them to native app.
+ * @param params - popup parameters.
+ */
+export declare function prepareParams(params: ShowOptions): E.Either<InvalidArgumentsError, PopupParams>;

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

@@ -0,0 +1,54 @@
+import { AsyncOptions } from '../../types.js';
+/**
+ * This object describes the native popup.
+ * @see https://core.telegram.org/bots/webapps#popupparams
+ */
+export interface ShowOptions extends AsyncOptions {
+    /**
+     * The text to be displayed in the popup title, 0-64 characters.
+     * @default ""
+     */
+    title?: string;
+    /**
+     * The message to be displayed in the body of the popup, 1-256 characters.
+     */
+    message: string;
+    /**
+     * List of buttons to be displayed in the popup, 1-3 buttons.
+     * @default [{ type: 'close' }]
+     */
+    buttons?: ShowOptionsButton[];
+}
+/**
+ * This object describes the native popup button.
+ * @see https://core.telegram.org/bots/webapps#popupbutton
+ */
+export type ShowOptionsButton = {
+    /**
+     * Identifier of the button, 0-64 characters.
+     * @default ""
+     */
+    id?: string;
+} & ({
+    /**
+     * Type of the button:
+     * - `default`, a button with the default style;
+     * - `destructive`, a button with a style that indicates a destructive
+     * action (e.g. "Remove", "Delete", etc.).
+     *
+     * @default "default"
+     */
+    type?: 'default' | 'destructive';
+    /**
+     * The text to be displayed on the button, 0-64 characters.
+     */
+    text: string;
+} | {
+    /**
+     * Type of the button:
+     * - `ok`, a button with the localized text "OK";
+     * - `close`, a button with the localized text "Close";
+     * - `cancel`, a button with the localized text "Cancel".
+     */
+    type: 'ok' | 'close' | 'cancel';
+});