ultra-telegram-framework 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Dzola
+
+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,174 @@
+# 🚀 Ultra Telegram Framework (UTF)
+
+[![Bot API 10.0](https://img.shields.io/badge/Bot%20API-10.0-blue.svg?logo=telegram)](https://core.telegram.org/bots/api)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
+[![Google Apps Script](https://img.shields.io/badge/Google%20Apps%20Script-powered-orange.svg?logo=google-apps-script)](https://developers.google.com/apps-script/)
+[![Documentation](https://img.shields.io/badge/docs-TypeDoc-blue.svg?logo=readthedocs)](https://volodymyrdzola.github.io/ultra-tg-framework/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Ultra Telegram Framework (UTF)** is a modern, lightweight, and strongly typed Telegram Bot API framework built for **TypeScript**.
+
+Designed with flexibility in mind, UTF features a unique **adapter-based architecture** that allows your bot to run seamlessly across various environments — from classic Node.js servers to Serverless Edge functions and Google Apps Script — without rewriting your core logic.
+
+---
+
+## ✨ Why Choose UTF?
+
+### 🌍 Write Once, Run Anywhere
+UTF provides dedicated API clients optimized for specific runtimes:
+- **`NodeApiClient`** — Node.js 18+ with native `fetch` and Webhook Reply optimizations.
+- **`WebApiClient`** — Universal client for Edge runtimes (Cloudflare Workers, Vercel Edge, Deno, Bun).
+- **`GasApiClient`** — Exclusive adapter for **Google Apps Script** using `UrlFetchApp`.
+
+### 🔘 Declarative Inline Menus
+Build interactive, multi-page menus with the page-based `InlineMenu` system. Define pages with `.page()` and button actions with `.action()`, with automatic state management and navigation.
+
+### 🤖 AI-Ready & Streaming Support
+The `ctx.replyWithDraft()` method lets you stream "thinking" indicators for LLM responses with built-in rate-limit protection and auto-debouncing.
+
+### 🛡️ 100% Type-Safe
+Exhaustive TypeScript typings for **all** Telegram Bot API 10.0 objects, methods, and parameters. Rich IDE autocompletion and compile-time error checking.
+
+### 🎭 Built-in Scenes & Sessions
+Manage multi-step flows with `WizardScene`, `Stage`, and `SceneManager`. Multiple session storage adapters included: `MemoryStorage`, `PropertiesStorage`, `CacheStorage`, and the exclusive `GasHybridStorage`.
+
+### 🔋 Batteries Included
+No external plugins needed. Scenes, sessions, inline menus, keyboards, and error handling are all part of the core framework.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ultra-tg-framework
+```
+
+---
+
+## 🏁 Quick Start
+
+### Example 1: Node.js (Polling)
+
+The fastest way to get started. No server setup required.
+
+```typescript
+import { TelegramBot, NodeApiClient } from 'ultra-tg-framework';
+
+const bot = new TelegramBot(new NodeApiClient('YOUR_BOT_TOKEN'));
+
+bot.command('start', async (ctx) => {
+  await ctx.reply('Hello! I am an Ultra Telegram Framework bot 🚀');
+});
+
+bot.on('text', async (ctx) => {
+  await ctx.reply(`You said: ${ctx.text}`);
+});
+
+bot.launch()
+  .then(() => console.log('Bot is running...'))
+  .catch(console.error);
+```
+
+### Example 2: Google Apps Script (Webhook)
+
+Deploy your bot for free on Google's infrastructure:
+
+```typescript
+import { TelegramBot, GasApiClient } from 'ultra-tg-framework';
+
+const bot = new TelegramBot(new GasApiClient('YOUR_BOT_TOKEN'));
+
+bot.command('start', async (ctx) => {
+  await ctx.reply('Hello from Google Apps Script! ☁️');
+});
+
+globalThis.doPost = (e: GoogleAppsScript.Events.DoPost) => {
+  if (e?.postData?.contents) {
+    const update = JSON.parse(e.postData.contents);
+    bot.handleUpdate(update);
+  }
+};
+```
+
+### Example 3: Cloudflare Workers (Edge)
+
+Global low-latency deployment:
+
+```typescript
+import { TelegramBot, WebApiClient } from 'ultra-tg-framework';
+
+export default {
+  async fetch(request: Request, env: any, ctx: ExecutionContext) {
+    if (request.method !== 'POST') {
+      return new Response('Bot is running ⚡');
+    }
+
+    const update = await request.json();
+    const bot = new TelegramBot(new WebApiClient(env.BOT_TOKEN));
+
+    bot.command('start', async (ctx) => {
+      await ctx.reply('Hello from the Edge! 🌍⚡');
+    });
+
+    ctx.waitUntil(bot.handleUpdate(update));
+    return new Response('OK');
+  }
+};
+```
+
+---
+
+## 🧰 Key Features at a Glance
+
+| Feature | Description |
+| :--- | :--- |
+| **Context Helpers** | `ctx.reply()`, `ctx.editMessage()`, `ctx.answerCbQuery()`, `ctx.replyWithPhoto()`, and 30+ more. |
+| **Smart `ctx.text`** | Returns message text OR media caption — works universally. |
+| **`ctx.payload`** | Command arguments (e.g., `/start ref_123` → `"ref_123"`). |
+| **InlineKeyboard** | Fluent builder: `.text()`, `.url()`, `.webApp()`, `.menu()`, `.pay()`, `.game()`. |
+| **ReplyKeyboard** | `.text()`, `.requestContact()`, `.requestLocation()`, `.oneTime()`, `.resized()`. |
+| **InlineMenu** | Page-based menus with automatic navigation, back buttons, and state management. |
+| **WizardScene** | Linear step-by-step dialogues with `ctx.scene.next()`, `leave()`, `selectStep()`. |
+| **Session Storage** | `MemoryStorage`, `PropertiesStorage`, `CacheStorage`, `GasHybridStorage`. |
+| **Error Handling** | Built-in `bot.catch()` and middleware-based error boundaries. |
+| **AI Drafts** | `ctx.replyWithDraft()` for streaming LLM responses with rate-limit protection. |
+| **Paid Media** | `ctx.replyWithPaidMedia()` for Telegram Stars ⭐️ monetization. |
+| **Games** | `ctx.replyWithGame()`, `ctx.setGameScore()`, `ctx.getGameHighScores()`. |
+| **Payments** | `ctx.replyWithInvoice()`, `ctx.answerShippingQuery()`, `ctx.answerPreCheckoutQuery()`. |
+
+---
+
+## 📚 Documentation & Guides
+
+Explore the detailed guides in our [Wiki](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki):
+
+### 🚀 Getting Started
+- **[Migrating to UTF](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Migrating-to-UTF)** — Step-by-step guide for upgrading from grammY, Telegraf, or legacy scripts.
+- **[Architecture](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Architecture)** — Understand the adapter-based design and the four architectural layers.
+- **[Local Dev (Polling vs Webhooks)](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Local-Dev)** — Best practices for running and testing your bot locally.
+
+### ☁️ Deployment
+- **[Deploy to GAS](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Deploy-to-GAS)** — Comprehensive tutorial for Google Apps Script deployment with `esbuild` and `clasp`.
+- **[Deploy to Edge](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Edge-Computing)** — Cloudflare Workers, Deno Deploy, and Bun examples.
+
+### 🧠 Framework Deep Dive
+- **[Core (TelegramBot)](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Core)** — The bot entry point, lifecycle, and initialization.
+- **[Context](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Context)** — Complete API reference for the `ctx` object with all 40+ helper methods.
+- **[Composer & Routing](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Composer)** — `.command()`, `.on()`, `.action()`, type narrowing, and modular sub-routers.
+- **[Middleware](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Middleware)** — The "onion" model, context hydration, and chain control.
+- **[Sessions & Storage](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Session)** — Memory, GAS Cache, Hybrid, and custom storage adapters.
+- **[Error Handling](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Error-Handling)** — `bot.catch()`, middleware boundaries, and Telegram-specific error patterns.
+
+### 🧰 UI & Tools
+- **[Inline Menus](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Inline-Menus)** — Page-based declarative menus with navigation and back buttons.
+- **[Wizard Scenes](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Wizard-Scenes)** — Multi-step forms and conversational flows.
+- **[Handling Files](https://github.com/VolodymyrDzola/ultra-tg-framework/wiki/Handling-Files)** — Working with Telegram files, downloads, and Google Drive integration.
+
+### 🔗 Resources
+- **[TypeDoc API Reference](https://volodymyrdzola.github.io/ultra-tg-framework/)** — Auto-generated TypeScript API documentation for all classes, methods, and types.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/VolodymyrDzola/ultra-tg-framework?tab=MIT-1-ov-file) file for details.

package/dist/adapters/gas.d.ts

@@ -0,0 +1,10 @@
+import { BaseTelegramClient } from '../core/base-api';
+export declare class GasApiClient extends BaseTelegramClient {
+    /**
+     * Sends a request to the Telegram API.
+     * @param method - method name
+     * @param payload - parameters object
+     * @returns `Promise<T>`
+     */
+    callApi<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+}

package/dist/adapters/gas.js

@@ -0,0 +1,90 @@
+// src/adapters/gas.ts
+import { BaseTelegramClient } from '../core/base-api';
+export class GasApiClient extends BaseTelegramClient {
+    /**
+     * Sends a request to the Telegram API.
+     * @param method - method name
+     * @param payload - parameters object
+     * @returns `Promise<T>`
+     */
+    async callApi(method, payload = {}) {
+        const url = `${this.baseUrl}/${method}`;
+        let fileIndex = 0;
+        const files = {};
+        /**
+         * Recursive function to find files in nested objects.
+         * @param value - value to process
+         * @returns `unknown`
+         */
+        const extractFiles = (value) => {
+            if (value == null)
+                return value;
+            if (typeof value === 'object' && typeof value.getBytes === 'function') {
+                const attachName = `file_attach_${fileIndex++}`;
+                files[attachName] = value;
+                return `attach://${attachName}`;
+            }
+            if (Array.isArray(value)) {
+                return value.map(extractFiles);
+            }
+            if (typeof value === 'object') {
+                const processedObj = {};
+                for (const [k, v] of Object.entries(value)) {
+                    processedObj[k] = extractFiles(v);
+                }
+                return processedObj;
+            }
+            return value;
+        };
+        const processedPayload = {};
+        for (const [key, value] of Object.entries(payload)) {
+            processedPayload[key] = extractFiles(value);
+        }
+        const hasFiles = Object.keys(files).length > 0;
+        let options;
+        if (hasFiles) {
+            const multipartPayload = { ...files };
+            for (const [key, value] of Object.entries(processedPayload)) {
+                if (value == null)
+                    continue;
+                if (typeof value === 'object') {
+                    multipartPayload[key] = JSON.stringify(value);
+                }
+                else {
+                    multipartPayload[key] = String(value);
+                }
+            }
+            options = {
+                method: 'post',
+                payload: multipartPayload,
+                muteHttpExceptions: true,
+            };
+        }
+        else {
+            options = {
+                method: 'post',
+                contentType: 'application/json',
+                payload: JSON.stringify(processedPayload),
+                muteHttpExceptions: true,
+            };
+        }
+        const response = UrlFetchApp.fetch(url, options);
+        const statusCode = response.getResponseCode();
+        const contentText = response.getContentText();
+        if (statusCode !== 200) {
+            let errorData;
+            try {
+                errorData = JSON.parse(contentText);
+            }
+            catch {
+                throw new Error(`HTTP Error ${statusCode}: ${contentText}`);
+            }
+            throw new Error(`Telegram API Error ${statusCode}: ${errorData.description}`);
+        }
+        const data = JSON.parse(contentText);
+        if (!data.ok) {
+            throw new Error(`Telegram Logic Error: ${data.description}`);
+        }
+        return data.result;
+    }
+}

package/dist/adapters/node.d.ts

@@ -0,0 +1,52 @@
+import { BaseTelegramClient } from '../core/base-api';
+/**
+ * Shape of a captured webhook reply payload.
+ */
+export interface WebhookReplyPayload {
+    method: string;
+    [key: string]: unknown;
+}
+export declare class NodeApiClient extends BaseTelegramClient {
+    /**
+     * Stores the first API call as a JSON payload for webhook reply optimization.
+     * When set, this payload should be returned as the HTTP response body
+     * instead of making a separate fetch request to Telegram.
+     */
+    private _webhookReply;
+    private _useWebhookReply;
+    /**
+     * Enable webhook reply mode.
+     * Call this BEFORE `handleUpdate()` to capture the first text-only API call
+     * as a JSON payload instead of sending it via fetch.
+     *
+     * **⚠️ Important trade-off:** When a call is captured, the corresponding
+     * `ctx.reply()` / `ctx.api.*` method returns an **empty object** `{}` instead
+     * of the real Telegram response. This means you **cannot** rely on the return
+     * value (e.g., `msg.message_id` will be `undefined`).
+     *
+     * Use this only when you don't need the return value of the first API call.
+     *
+     * @example
+     * ```ts
+     * app.post('/webhook', async (req, res) => {
+     *   client.enableWebhookReply();
+     *   await bot.handleUpdate(req.body);
+     *
+     *   const reply = client.consumeWebhookReply();
+     *   if (reply) {
+     *     res.json(reply);
+     *   } else {
+     *     res.json({ ok: true });
+     *   }
+     * });
+     * ```
+     */
+    enableWebhookReply(): void;
+    /**
+     * Retrieve and clear the captured webhook reply payload.
+     * Returns `null` if no payload was captured (e.g., the first call had files,
+     * or no API calls were made during this update).
+     */
+    consumeWebhookReply(): WebhookReplyPayload | null;
+    callApi<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+}

package/dist/adapters/node.js

@@ -0,0 +1,150 @@
+// src/adapters/node.ts
+import { BaseTelegramClient } from '../core/base-api';
+export class NodeApiClient extends BaseTelegramClient {
+    constructor() {
+        super(...arguments);
+        /**
+         * Stores the first API call as a JSON payload for webhook reply optimization.
+         * When set, this payload should be returned as the HTTP response body
+         * instead of making a separate fetch request to Telegram.
+         */
+        this._webhookReply = null;
+        this._useWebhookReply = false;
+    }
+    /**
+     * Enable webhook reply mode.
+     * Call this BEFORE `handleUpdate()` to capture the first text-only API call
+     * as a JSON payload instead of sending it via fetch.
+     *
+     * **⚠️ Important trade-off:** When a call is captured, the corresponding
+     * `ctx.reply()` / `ctx.api.*` method returns an **empty object** `{}` instead
+     * of the real Telegram response. This means you **cannot** rely on the return
+     * value (e.g., `msg.message_id` will be `undefined`).
+     *
+     * Use this only when you don't need the return value of the first API call.
+     *
+     * @example
+     * ```ts
+     * app.post('/webhook', async (req, res) => {
+     *   client.enableWebhookReply();
+     *   await bot.handleUpdate(req.body);
+     *
+     *   const reply = client.consumeWebhookReply();
+     *   if (reply) {
+     *     res.json(reply);
+     *   } else {
+     *     res.json({ ok: true });
+     *   }
+     * });
+     * ```
+     */
+    enableWebhookReply() {
+        this._useWebhookReply = true;
+        this._webhookReply = null;
+    }
+    /**
+     * Retrieve and clear the captured webhook reply payload.
+     * Returns `null` if no payload was captured (e.g., the first call had files,
+     * or no API calls were made during this update).
+     */
+    consumeWebhookReply() {
+        const reply = this._webhookReply;
+        this._webhookReply = null;
+        this._useWebhookReply = false;
+        return reply;
+    }
+    async callApi(method, payload = {}) {
+        const url = `${this.baseUrl}/${method}`;
+        let fileIndex = 0;
+        const files = {};
+        const extractFiles = (value) => {
+            if (value == null)
+                return value;
+            let isFile = false;
+            let blobValue = null;
+            if (value instanceof Blob) {
+                isFile = true;
+                blobValue = value;
+            }
+            else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+                isFile = true;
+                blobValue = new Blob([value]);
+            }
+            if (isFile && blobValue) {
+                const attachName = `file_attach_${fileIndex++}`;
+                files[attachName] = blobValue;
+                return `attach://${attachName}`;
+            }
+            if (Array.isArray(value)) {
+                return value.map(extractFiles);
+            }
+            if (typeof value === 'object') {
+                const processedObj = {};
+                for (const [k, v] of Object.entries(value)) {
+                    processedObj[k] = extractFiles(v);
+                }
+                return processedObj;
+            }
+            return value;
+        };
+        const processedPayload = {};
+        for (const [key, value] of Object.entries(payload)) {
+            processedPayload[key] = extractFiles(value);
+        }
+        const hasFiles = Object.keys(files).length > 0;
+        // Webhook Reply optimization: capture the first text-only call
+        if (this._useWebhookReply && !hasFiles) {
+            this._useWebhookReply = false; // Only the first call
+            this._webhookReply = { method, ...processedPayload };
+            console.warn(`[UTF] ⚡ Webhook Reply captured: ${method}. ` +
+                `The return value of this API call is an empty object. ` +
+                `Do not use the returned value (e.g., msg.message_id will be undefined).`);
+            return {};
+        }
+        let requestOptions;
+        if (hasFiles) {
+            const form = new FormData();
+            for (const [key, file] of Object.entries(files)) {
+                form.append(key, file, `${key}.file`);
+            }
+            for (const [key, value] of Object.entries(processedPayload)) {
+                if (value == null)
+                    continue;
+                if (typeof value === 'object') {
+                    form.append(key, JSON.stringify(value));
+                }
+                else {
+                    form.append(key, String(value));
+                }
+            }
+            requestOptions = {
+                method: 'POST',
+                body: form,
+            };
+        }
+        else {
+            requestOptions = {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(processedPayload),
+            };
+        }
+        const response = await fetch(url, requestOptions);
+        if (!response.ok) {
+            const textData = await response.text();
+            let jsonData;
+            try {
+                jsonData = JSON.parse(textData);
+            }
+            catch {
+                throw new Error(`Telegram HTTP Error ${response.status}: ${textData}`);
+            }
+            throw new Error(`Telegram API Error [${method}] ${response.status}: ${jsonData.description}`);
+        }
+        const data = (await response.json());
+        if (!data.ok) {
+            throw new Error(`Telegram Logic Error [${method}]: ${data.description}`);
+        }
+        return data.result;
+    }
+}

package/dist/adapters/web.d.ts

@@ -0,0 +1,4 @@
+import { BaseTelegramClient } from '../core/base-api';
+export declare class WebApiClient extends BaseTelegramClient {
+    callApi<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+}

package/dist/adapters/web.js

@@ -0,0 +1,90 @@
+// src/adapters/web.ts
+import { BaseTelegramClient } from '../core/base-api';
+export class WebApiClient extends BaseTelegramClient {
+    async callApi(method, payload = {}) {
+        const url = `${this.baseUrl}/${method}`;
+        let fileIndex = 0;
+        const files = {};
+        const extractFiles = (value) => {
+            if (value == null)
+                return value;
+            let isFile = false;
+            let blobValue = null;
+            if (value instanceof Blob) {
+                isFile = true;
+                blobValue = value;
+            }
+            else if (typeof globalThis !== 'undefined' &&
+                globalThis.Buffer &&
+                globalThis.Buffer.isBuffer(value)) {
+                isFile = true;
+                blobValue = new Blob([value]);
+            }
+            if (isFile && blobValue) {
+                const attachName = `file_attach_${fileIndex++}`;
+                files[attachName] = blobValue;
+                return `attach://${attachName}`;
+            }
+            if (Array.isArray(value)) {
+                return value.map(extractFiles);
+            }
+            if (typeof value === 'object') {
+                const processedObj = {};
+                for (const [k, v] of Object.entries(value)) {
+                    processedObj[k] = extractFiles(v);
+                }
+                return processedObj;
+            }
+            return value;
+        };
+        const processedPayload = {};
+        for (const [key, value] of Object.entries(payload)) {
+            processedPayload[key] = extractFiles(value);
+        }
+        const hasFiles = Object.keys(files).length > 0;
+        let requestOptions;
+        if (hasFiles) {
+            const form = new FormData();
+            for (const [key, file] of Object.entries(files)) {
+                form.append(key, file, `${key}.file`);
+            }
+            for (const [key, value] of Object.entries(processedPayload)) {
+                if (value == null)
+                    continue;
+                if (typeof value === 'object') {
+                    form.append(key, JSON.stringify(value));
+                }
+                else {
+                    form.append(key, String(value));
+                }
+            }
+            requestOptions = {
+                method: 'POST',
+                body: form,
+            };
+        }
+        else {
+            requestOptions = {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(processedPayload),
+            };
+        }
+        const response = await fetch(url, requestOptions);
+        if (!response.ok) {
+            const textData = await response.text();
+            try {
+                const jsonData = JSON.parse(textData);
+                throw new Error(`Telegram API Error [${method}] ${response.status}: ${jsonData.description}`);
+            }
+            catch {
+                throw new Error(`Telegram HTTP Error ${response.status}: ${textData}`);
+            }
+        }
+        const data = (await response.json());
+        if (!data.ok) {
+            throw new Error(`Telegram Logic Error [${method}]: ${data.description}`);
+        }
+        return data.result;
+    }
+}

package/dist/core/base-api.d.ts

@@ -0,0 +1,40 @@
+import { TelegramBotApi } from '../types/telegram';
+/**
+ * Shape of a Telegram API error response (non-2xx HTTP status).
+ */
+export interface TelegramErrorResponse {
+    ok: false;
+    description: string;
+    error_code: number;
+}
+/**
+ * Shape of a successful Telegram API response envelope.
+ */
+export interface TelegramApiResponse<T = unknown> {
+    ok: boolean;
+    description?: string;
+    result: T;
+}
+/**
+ * Abstract core describing the transport layer.
+ */
+export declare abstract class BaseTelegramClient {
+    protected readonly baseUrl: string;
+    /**
+     * Creates a new client instance.
+     * @param token Your bot's token
+     */
+    constructor(token: string);
+    /**
+     * Request method implemented by each platform.
+     * @param method Method name
+     * @param payload Parameters object
+     * @returns `Promise<T>`
+     */
+    abstract callApi<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * Proxy that "pretends" to be a full TelegramBotApi implementation.
+     * @returns `TelegramBotApi`
+     */
+    get raw(): TelegramBotApi;
+}

package/dist/core/base-api.js

@@ -0,0 +1,26 @@
+/**
+ * Abstract core describing the transport layer.
+ */
+export class BaseTelegramClient {
+    /**
+     * Creates a new client instance.
+     * @param token Your bot's token
+     */
+    constructor(token) {
+        this.baseUrl = `https://api.telegram.org/bot${token}`;
+    }
+    /**
+     * Proxy that "pretends" to be a full TelegramBotApi implementation.
+     * @returns `TelegramBotApi`
+     */
+    get raw() {
+        return new Proxy({}, {
+            get: (target, method) => {
+                if (typeof method !== 'string' || method === 'then') {
+                    return Reflect.get(target, method);
+                }
+                return (params = {}) => this.callApi(method, params);
+            }
+        });
+    }
+}