@effect-ak/tg-bot-client 0.5.3 → 0.6.0

package/dist/webapp.d.ts

@@ -0,0 +1,391 @@
+type BindOrUnbindEventHandler = <K extends keyof EventHandlers>(eventName: K, handler: EventHandlers[K]) => void;
+type EventHandlers = {
+    activated: () => void;
+    deactivated: () => void;
+    themeChanged: () => void;
+    viewportChanged: (options: {
+        isStateStable: boolean;
+    }) => void;
+    safeAreaChanged: () => void;
+    contentSafeAreaChanged: () => void;
+    mainButtonClicked: () => void;
+    backButtonClicked: () => void;
+    settingsButtonClicked: () => void;
+    invoiceClosed: (options: {
+        url: string;
+        status: "paid" | "cancelled" | "failed" | "pending";
+    }) => void;
+    popupClosed: (options: {
+        button_id: string | null;
+    }) => void;
+    qrTextReceived: (options: {
+        data: string;
+    }) => void;
+    scanQrPopupClosed: () => void;
+    clipboardTextReceived: (options: {
+        data: string;
+    }) => void;
+    writeAccessRequested: (options: {
+        status: "allowed" | "cancelled";
+    }) => void;
+    biometricManagerUpdated: () => void;
+    biometricAuthRequested: (options: {
+        isAuthenticated: boolean;
+        biometricToken: string | null;
+    }) => void;
+    biometricTokenUpdated: (options: {
+        isUpdated: boolean;
+    }) => void;
+    fullscreenChanged: () => void;
+    fullscreenFailed: (options: {
+        error: "UNSUPPORTED" | "ALREADY_FULLSCREEN";
+    }) => void;
+    homeScreenAdded: () => void;
+    homeScreenChecked: (options: {
+        status: "unsupported" | "unknown" | "added" | "missed";
+    }) => void;
+    accelerometerStarted: () => void;
+    accelerometerStopped: () => void;
+    accelerometerChanged: () => void;
+    accelerometerFailed: (options: {
+        error: "UNSUPPORTED";
+    }) => void;
+    deviceOrientationStarted: () => void;
+    deviceOrientationStopped: () => void;
+    deviceOrientationChanged: () => void;
+    deviceOrientationFailed: (options: {
+        error: "UNSUPPORTED";
+    }) => void;
+    gyroscopeStarted: () => void;
+    gyroscopeStopped: () => void;
+    gyroscopeChanged: () => void;
+    gyroscopeFailed: (options: {
+        error: "UNSUPPORTED";
+    }) => void;
+    locationManagerUpdated: () => void;
+    locationRequested: (options: {
+        locationData: LocationData;
+    }) => void;
+    shareMessageSent: () => void;
+    shareMessageFailed: (options: {
+        error: "UNSUPPORTED" | "MESSAGE_EXPIRED" | "MESSAGE_SEND_FAILED" | "USER_DECLINED" | "UNKNOWN_ERROR";
+    }) => void;
+    emojiStatusSet: () => void;
+    emojiStatusFailed: (options: {
+        error: "UNSUPPORTED" | "SUGGESTED_EMOJI_INVALID" | "DURATION_INVALID" | "USER_DECLINED" | "SERVER_ERROR" | "UNKNOWN_ERROR";
+    }) => void;
+    emojiStatusAccessRequested: (options: {
+        status: "allowed" | "cancelled";
+    }) => void;
+    fileDownloadRequested: (options: {
+        status: "downloading" | "cancelled";
+    }) => void;
+};
+
+interface WebApp {
+    initData: string;
+    initDataUnsafe: WebAppInitData;
+    version: string;
+    platform: string;
+    colorScheme: string;
+    themeParams: ThemeParams;
+    isActive: boolean;
+    isExpanded: boolean;
+    viewportHeight: number;
+    viewportStableHeight: number;
+    headerColor: string;
+    backgroundColor: string;
+    bottomBarColor: string;
+    isClosingConfirmationEnabled: boolean;
+    isVerticalSwipesEnabled: boolean;
+    isFullscreen: boolean;
+    isOrientationLocked: boolean;
+    safeAreaInset: SafeAreaInset;
+    contentSafeAreaInset: ContentSafeAreaInset;
+    BackButton: BackButton;
+    MainButton: BottomButton;
+    SecondaryButton: BottomButton;
+    SettingsButton: SettingsButton;
+    HapticFeedback: HapticFeedback;
+    CloudStorage: CloudStorage;
+    BiometricManager: BiometricManager;
+    Accelerometer: Accelerometer;
+    DeviceOrientation: DeviceOrientation;
+    Gyroscope: Gyroscope;
+    LocationManager: LocationManager;
+    DeviceStorage: DeviceStorage;
+    SecureStorage: SecureStorage;
+    isVersionAtLeast: (version: string) => boolean;
+    setHeaderColor: (color: string) => void;
+    setBackgroundColor: (color: string) => void;
+    setBottomBarColor: (color: string) => void;
+    enableClosingConfirmation: () => void;
+    disableClosingConfirmation: () => void;
+    enableVerticalSwipes: () => void;
+    disableVerticalSwipes: () => void;
+    requestFullscreen: () => void;
+    exitFullscreen: () => void;
+    lockOrientation: () => void;
+    unlockOrientation: () => void;
+    addToHomeScreen: () => void;
+    checkHomeScreenStatus: (callback?: (status: "unsupported" | "unknown" | "added" | "missed") => void) => void;
+    onEvent: BindOrUnbindEventHandler;
+    offEvent: BindOrUnbindEventHandler;
+    sendData: (data: string) => void;
+    switchInlineQuery: (query: string, chat_type?: "users" | "bots" | "groups" | "channels") => void;
+    openLink: (url: string, options?: {
+        try_instant_view: boolean;
+    }) => void;
+    openTelegramLink: (url: string) => void;
+    openInvoice: (url: string, callback?: (invoiceStatus: unknown) => void) => void;
+    shareToStory: (mediaUrl: string, options?: StoryShareParams) => void;
+    shareMessage: (msg_id: number, options?: (isSent: boolean) => void) => void;
+    setEmojiStatus: (custom_emoj_id: string, params?: EmojiStatusParams, callback?: (isStatusSet: boolean) => void) => void;
+    requestEmojiStatusAccess: (url: string, callback?: (invoiceStatus: unknown) => void) => void;
+    downloadFile: (params: DownloadFileParams, callback?: (isAccepted: boolean) => void) => void;
+    showPopup: (params: PopupParams, callback?: (buttonId: string) => void) => void;
+    showAlert: (message: string, callback?: () => void) => void;
+    showConfirm: (message: string, callback?: (isOk: boolean) => void) => void;
+    showScanQrPopup: (params: ScanQrPopupParams, callback?: (data: string) => boolean) => void;
+    closeScanQrPopup: () => void;
+    readTextFromClipboard: (callback?: (text: string) => void) => void;
+    requestWriteAccess: (callback?: (isGranted: boolean) => void) => void;
+    requestContact: (callback?: (isShared: boolean) => void) => void;
+    ready: () => void;
+    expand: () => void;
+    close: () => void;
+}
+interface Accelerometer {
+    isStarted: boolean;
+    x: number;
+    y: number;
+    z: number;
+    start: (params: AccelerometerStartParams, callback?: (isStarted: boolean) => void) => Accelerometer;
+    stop: (callback?: (isStopped: boolean) => void) => Accelerometer;
+}
+interface AccelerometerStartParams {
+    refresh_rate?: number;
+}
+interface BackButton {
+    isVisible: boolean;
+    onClick: EventHandlers["backButtonClicked"];
+    offClick: EventHandlers["backButtonClicked"];
+    show: () => BackButton;
+    hide: () => BackButton;
+}
+interface BiometricAuthenticateParams {
+    reason?: string;
+}
+interface BiometricManager {
+    isInited: boolean;
+    isBiometricAvailable: boolean;
+    biometricType: "finger" | "face" | "unknown";
+    isAccessRequested: boolean;
+    isAccessGranted: boolean;
+    isBiometricTokenSaved: boolean;
+    deviceId: string;
+    init: (callback?: () => void) => BiometricManager;
+    requestAccess: (params: BiometricRequestAccessParams, callback?: (isGranted: boolean) => void) => BiometricManager;
+    authenticate: (params: BiometricAuthenticateParams, callback?: (isAuthenticated: boolean) => void) => BiometricManager;
+    updateBiometricToken: (token: string, callback?: (isTokenUpdated: boolean) => void) => BiometricManager;
+    openSettings: () => BiometricManager;
+}
+interface BiometricRequestAccessParams {
+    reason?: string;
+}
+interface BottomButton {
+    type: string;
+    text: string;
+    color: string;
+    textColor: string;
+    isVisible: boolean;
+    isActive: boolean;
+    hasShineEffect: boolean;
+    position: string;
+    isProgressVisible: boolean;
+    setText: (text: string) => BottomButton;
+    onClick: (callback: () => void) => BottomButton;
+    offClick: (callback: () => void) => BottomButton;
+    show: () => BottomButton;
+    hide: () => BottomButton;
+    enable: () => BottomButton;
+    disable: () => BottomButton;
+    showProgress: (callback: (leaveActive: boolean) => void) => BottomButton;
+    hideProgress: () => BottomButton;
+    setParams: (params: {
+        text: string;
+        color: string;
+        has_shine_effect: boolean;
+        position: unknown;
+        is_active: boolean;
+        is_visible: boolean;
+    }) => BottomButton;
+}
+interface CloudStorage {
+    setItem: (key: string, value: string, callback?: (error: unknown | null) => void) => CloudStorage;
+    getItem: (key: string, callback: (error: unknown | null, value: string | null) => void) => CloudStorage;
+    getItems: (keys: string[], callback: (error: string | null, values: Record<string, string> | null) => void) => CloudStorage;
+    removeItem: (key: string, callback?: (error: string | null, isDeleted: boolean) => void) => CloudStorage;
+    removeItems: (keys: string[], callback?: (error: string | null, isDeleted: boolean) => void) => CloudStorage;
+    getKeys: (callback: (error: string | null, keys: string[] | null) => void) => CloudStorage;
+}
+interface ContentSafeAreaInset {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+interface DeviceOrientation {
+    isStarted: boolean;
+    absolute: boolean;
+    alpha: number;
+    beta: number;
+    gamma: number;
+    start: (params: DeviceOrientationStartParams, callback?: (isTracking: boolean) => void) => void;
+    stop: (callback?: (isStopped: boolean) => void) => void;
+}
+interface DeviceOrientationStartParams {
+    refresh_rate?: number;
+    need_absolute?: boolean;
+}
+interface DeviceStorage {
+    setItem: (key: string, value: string, callback?: (error: unknown | null, isStored: boolean) => void) => DeviceStorage;
+    getItem: (key: string, callback: (error: unknown | null, value: string | null) => void) => DeviceStorage;
+    removeItem: (key: string, callback?: (error: unknown | null, isRemoved: boolean) => void) => DeviceStorage;
+    clear: (callback?: (error: unknown | null, isCleared: boolean) => void) => DeviceStorage;
+}
+interface DownloadFileParams {
+    url: string;
+    file_name: string;
+}
+interface EmojiStatusParams {
+    duration?: number;
+}
+interface Gyroscope {
+    isStarted: boolean;
+    x: number;
+    y: number;
+    z: number;
+    start: (params: GyroscopeStartParams, callback?: (isTracking: boolean) => void) => void;
+    stop: (callback?: (isStopped: boolean) => void) => void;
+}
+interface GyroscopeStartParams {
+    refresh_rate?: number;
+}
+interface HapticFeedback {
+    impactOccurred: (style: "light" | "medium" | "heavy" | "rigid" | "soft") => void;
+    notificationOccurred: (type: "error" | "success" | "warning") => void;
+    selectionChanged: () => HapticFeedback;
+}
+interface LocationData {
+    latitude: number;
+    longitude: number;
+    altitude: number;
+    course: number;
+    speed: number;
+    horizontal_accuracy: number;
+    vertical_accuracy: number;
+    course_accuracy: number;
+    speed_accuracy: number;
+}
+interface LocationManager {
+    isInited: boolean;
+    isLocationAvailable: boolean;
+    isAccessRequested: boolean;
+    isAccessGranted: boolean;
+    init: (callback?: () => void) => LocationManager;
+    getLocation: (callback: (location: LocationData | null) => void) => LocationManager;
+    openSettings: () => LocationManager;
+}
+interface PopupButton {
+    id?: string;
+    type?: "OK" | "Close" | "Cancel";
+    text?: string;
+}
+interface PopupParams {
+    message: string;
+    title?: string;
+    buttons?: PopupButton[];
+}
+interface SafeAreaInset {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+interface ScanQrPopupParams {
+    text?: string;
+}
+interface SecureStorage {
+    setItem: (key: string, value: string, callback?: (error: unknown | null, isStored: boolean) => void) => SecureStorage;
+    getItem: (key: string, callback: (error: unknown | null, value: string | null, canBeRestored: boolean) => void) => SecureStorage;
+    restoreItem: (key: string, callback?: (error: unknown | null, value: string | null) => void) => SecureStorage;
+    removeItem: (key: string, callback?: (error: unknown | null, isRemoved: boolean) => void) => SecureStorage;
+    clear: (callback?: (error: unknown | null, isCleared: boolean) => void) => SecureStorage;
+}
+interface SettingsButton {
+    isVisible: boolean;
+    onClick: (callback: () => void) => SettingsButton;
+    offClick: (callback: () => void) => SettingsButton;
+    show: () => SettingsButton;
+    hide: () => SettingsButton;
+}
+interface StoryShareParams {
+    text?: string;
+    widget_link?: StoryWidgetLink;
+}
+interface StoryWidgetLink {
+    url: string;
+    name?: string;
+}
+interface ThemeParams {
+    bg_color?: string;
+    text_color?: string;
+    hint_color?: string;
+    link_color?: string;
+    button_color?: string;
+    button_text_color?: string;
+    secondary_bg_color?: string;
+    header_bg_color?: string;
+    bottom_bar_bg_color?: string;
+    accent_text_color?: string;
+    section_bg_color?: string;
+    section_header_text_color?: string;
+    section_separator_color?: string;
+    subtitle_text_color?: string;
+    destructive_text_color?: string;
+}
+interface WebAppChat {
+    id: number;
+    type: "group" | "supergroup" | "channel";
+    title: string;
+    username?: string;
+    photo_url?: "in";
+}
+interface WebAppInitData {
+    auth_date: number;
+    hash: string;
+    signature: string;
+    query_id?: string;
+    user?: WebAppUser;
+    receiver?: WebAppUser;
+    chat?: WebAppChat;
+    chat_type?: string;
+    chat_instance?: string;
+    start_param?: string;
+    can_send_after?: number;
+}
+interface WebAppUser {
+    id: number;
+    first_name: string;
+    is_bot?: boolean;
+    last_name?: string;
+    username?: string;
+    language_code?: string;
+    is_premium?: boolean;
+    added_to_attachment_menu?: boolean;
+    allows_write_to_pm?: boolean;
+    photo_url?: "in";
+}
+
+export type { Accelerometer, AccelerometerStartParams, BackButton, BiometricAuthenticateParams, BiometricManager, BiometricRequestAccessParams, BottomButton, CloudStorage, ContentSafeAreaInset, DeviceOrientation, DeviceOrientationStartParams, DeviceStorage, DownloadFileParams, EmojiStatusParams, Gyroscope, GyroscopeStartParams, HapticFeedback, LocationData, LocationManager, PopupButton, PopupParams, SafeAreaInset, ScanQrPopupParams, SecureStorage, SettingsButton, StoryShareParams, StoryWidgetLink, ThemeParams, WebApp, WebAppChat, WebAppInitData, WebAppUser };

package/dist/webapp.js

@@ -0,0 +1 @@
+"use strict";var m=Object.defineProperty;var t=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var b=(r,o,p,f)=>{if(o&&typeof o=="object"||typeof o=="function")for(let e of x(o))!a.call(r,e)&&e!==p&&m(r,e,{get:()=>o[e],enumerable:!(f=t(o,e))||f.enumerable});return r};var c=r=>b(m({},"__esModule",{value:!0}),r);var d={};module.exports=c(d);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-ak/tg-bot-client",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "homepage": "https://effect-ak.github.io/telegram-bot-playground/",
   "author": {
     "name": "Aleksandr Kondaurov",
@@ -9,19 +9,24 @@
   "publishConfig": {
     "access": "public"
   },
-  "description": "Telegram bot client",
+  "description": "TypeScript types for Telegram Bot Api and Telegram.Webapp",
   "files": [
-    "dist/index.js",
-    "dist/index.mjs",
-    "dist/index.d.ts"
+    "dist/*.js",
+    "dist/*.mjs",
+    "dist/*.d.ts"
   ],
   "keywords": [
-    "telegram",
-    "telegram bot api"
+    "telegram typescript types",
+    "telegram bot api client",
+    "telegram webapp"
   ],
   "repository": {
+    "type": "git",
     "url": "https://github.com/effect-ak/tg-bot-client"
   },
+  "bugs": {
+    "url": "https://github.com/effect-ak/tg-bot-client/issues"
+  },
   "license": "MIT",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -31,6 +36,16 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
+    },
+    "./bot": {
+      "types": "./dist/bot.d.ts",
+      "require": "./dist/bot.js",
+      "import": "./dist/bot.mjs"
+    },
+    "./webapp": {
+      "types": "./dist/webapp.d.ts",
+      "require": "./dist/webapp.js",
+      "import": "./dist/webapp.mjs"
     }
   },
   "devDependencies": {
@@ -44,6 +59,9 @@
     "typescript": "^5.8.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.1.1",
-    "effect": "^3.14.7"
+    "effect": "3.12.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.12.0"
   }
 }

package/readme.md

@@ -1,20 +1,19 @@
 [![NPM Version](https://img.shields.io/npm/v/%40effect-ak%2Ftg-bot-client)](https://www.npmjs.com/package/@effect-ak/tg-bot-client)
+![Telegram Bot API](https://img.shields.io/badge/BotApi-9.0-blue?link=)
+![Telegram WebApp](https://img.shields.io/badge/Telegram.WebApp-9.0-blue?link=)
 [![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-blue.svg)](https://effect-ak.github.io/telegram-bot-api/)
-![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40effect-ak%2Ftg-bot-client)
-![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot-client)
-
-
+![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40effect-ak%2Ftg-bot-client?link=)
+![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot-client?link=)
 
 ## Motivation
+**Telegram** does not offer an official TypeScript **SDK** for their **API** but they provide documentation in HTML format.
 
-The official documentation is available as a comprehensive [HTML page](https://core.telegram.org/bots/api), providing basic navigation. While functional, relying solely on this format can be somewhat inconvenient during bot **development**.
-
-This client facilitates interaction with the **Telegram Bot API**. It was created primarily because **Telegram** does not offer an official TypeScript **SDK** for their **API**.
+This package aims to parse official documentation of [Bot Api](https://core.telegram.org/bots/api) and [Telegram.Webapp](https://core.telegram.org/bots/api)  and generate **TypeScript types**!
 
 ## Highlights:
 - **[Client](#client)**: Light TypeScript client
 - **Complete and Up-to-Date Telegram Bot API**: The entire API is generated from [the official documentation](https://core.telegram.org/bots/api) using a [code generator](./codegen/main.ts), ensuring this client remains in sync and supports every method and type provided by the **Telegram Bot API**.
-- **[Types for Webapps](#webapps-typings)** Types that describe `Telegram.WebApp`
+- **[Types for Webapps](#webapps-typings)** Types that describe `Telegram.WebApp`. Created by [code generator](./codegen/main.ts) as well.
 - **[ChatBot runner](#chatbot-runner)**: Focus on the logic of your chat bot
 - **Type Mapping**: Types from the documentation are converted to TypeScript types:
   - `Integer` → `number`
@@ -33,7 +32,7 @@ const client = makeTgBotClient({
 });
 ```
 
-### Executing api methods
+### Executing api methods (Promise based)
 
 `client` has an `execute` method which requires two arguments
 
@@ -57,6 +56,8 @@ await client.execute("send_message", {
 #### 2. Sending a Dice
 
 ```typescript
+import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client"
+
 await client.execute("send_dice", {
   chat_id: "???", // replace ??? with the chat number
   emoji: "🎲"
@@ -66,6 +67,8 @@ await client.execute("send_dice", {
 #### 3. Sending a Document
 
 ```typescript
+import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client"
+
 await client.execute("send_document", {
   chat_id: "???", // replace ??? with the chat number
   message_effect_id: MESSAGE_EFFECTS["🎉"],
@@ -93,6 +96,22 @@ const file =
   });
 ```
 
+### Executing api methods (Effect based)
+
+If you want to use [Effect](https://effect.website/) instead of `Promise`:
+```typescript
+import { executeTgBotMethod, TgBotApiToken } from "@effect-ak/tg-bot-client";
+import { Effect } from "effect";
+
+executeTgBotMethod("send_message", {
+  text: "hello",
+  chat_id: config.chat_id
+}).pipe(
+  Effect.provideService(TgBotApiToken, 'your-token-from-bot-father'),
+  Effect.runPromiseExit
+)
+```
+
 ## ChatBot runner
 
 ### How this library helps
@@ -113,24 +132,13 @@ Take a look at examples [here](example)
 
 ### Setup Instructions
 
-1. **Create a `config.json` File**
-
-   In the root of your project, create a `config.json` file with the following content:
-
-   ```json
-   {
-     "bot-token": "your-token"
-   }
-   ```
-
-   Replace `"your-token"` with your actual Telegram bot token.
-
-2. **Create `bot.js` and Implement Your Bot's Logic**
+1. **Create `bot.js` and Implement Your Bot's Logic**
 
-   Create a file named `bot.js` and add your bot's logic as shown below:
+   Create a file (for example `bot.js`) and add your bot's logic as shown below:
 
    ```typescript
-   import { MESSAGE_EFFECTS, runTgChatBot, BotResponse, defineBot } from "@effect-ak/tg-bot-client"
+   import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client"
+   import { runTgChatBot, BotResponse, defineBot } from "@effect-ak/tg-bot-client/bot"
 
    const BOT = defineBot({
       on_message: (msg) => {
@@ -153,7 +161,7 @@ Take a look at examples [here](example)
    })
 
    runTgChatBot({
-     type: "fromJsonFile",
+     bot_token: "your-token" // PUT YOUR TOKEN HERE
      mode: {
       type: "single",
       ...BOT
@@ -161,7 +169,7 @@ Take a look at examples [here](example)
    })
    ```
 
-3. **Run the Bot**
+2. **Run the Bot**
 
    To start your chatbot, execute the following command in your terminal:
 
@@ -205,10 +213,10 @@ graph TD
 
 Telegram provides a big [html](https://core.telegram.org/bots/webapps) page that describes `Telegram.WebApp`
 
-`@effect-ak/tg-bot-client` levereges scrapper's functionality to generate TypeScript types.
+`@effect-ak/tg-bot-client` leverages scrapper's functionality to generate TypeScript types.
 
 ```typescript
-import { TgWebApp } from "@effect-ak/tg-bot-client";
+import type { WebApp } from "@effect-ak/tg-bot-client/webapp";
 
 interface Telegram {
   WebApp: TgWebApp