Wrappergram

Простая, минималистичная, кодогенерируемая обёртка Telegram Bot API для TypeScript. Wrappergram предоставляет минимальный, типобезопасный слой над Telegram Bot API с поддержкой загрузки файлов. Предназначен для лёгких сценариев — браузер, serverless-среды, или ситуации, где полноценный фреймворк вроде GramIO избыточен.

Установка

npm

npm install wrappergram

yarn

yarn add wrappergram

pnpm

pnpm add wrappergram

bun

bun install wrappergram

Быстрый старт

import { Telegram, getUpdates } from "wrappergram";

const telegram = new Telegram(process.env.BOT_TOKEN as string);

for await (const update of getUpdates(telegram)) {
    if (update.message?.from) {
        await telegram.api.sendMessage({
            chat_id: update.message.from.id,
            text: "Hi! Thanks for the message",
        });
    }
}

API

Класс Telegram

Основной класс. Каждый метод Telegram Bot API доступен через типобезопасный прокси api.

import { Telegram } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

// Методы без обязательных параметров
const me = await telegram.api.getMe();

// Методы с обязательными параметрами
const response = await telegram.api.sendMessage({
    chat_id: "@gramio_forum",
    text: "Hello, world!",
});

if (!response.ok) console.error("Something went wrong");
else console.log(`Message id: ${response.result.message_id}`);

Свойство api возвращает сырой ответ Telegram API:

// Успех:
{ ok: true, result: T }

// Ошибка:
{ ok: false, error_code: number, description: string }

Параметры

const telegram = new Telegram("BOT_TOKEN", {
    // Свой API-сервер (по умолчанию: "https://api.telegram.org/bot")
    baseURL: "https://my-custom-server.com/bot",

    // Свои параметры fetch
    requestOptions: {
        headers: { "X-Custom-Header": "value" },
        signal: AbortSignal.timeout(30000),
    },
});

getUpdates — Long polling

Асинхронный генератор для получения обновлений через long polling.

import { Telegram, getUpdates } from "wrappergram";

const telegram = new Telegram(process.env.BOT_TOKEN as string);

for await (const update of getUpdates(telegram)) {
    console.log(update);
}

WARNING

Используйте getUpdates только один раз в коде. Множественные вызовы приводят к дублированию запросов getUpdates к Telegram API.

Загрузка файлов

Wrappergram реэкспортирует MediaUpload и MediaInput из @gramio/files для работы с файлами.

MediaUpload

import { Telegram, MediaUpload } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

// Из локального файла
await telegram.api.sendPhoto({
    chat_id: "@gramio_forum",
    photo: MediaUpload.path("./cute-cat.png"),
});

// Из URL
await telegram.api.sendPhoto({
    chat_id: 123456,
    photo: MediaUpload.url("https://example.com/image.png"),
});

// Из буфера
await telegram.api.sendDocument({
    chat_id: 123456,
    document: MediaUpload.buffer(myBuffer, "data.bin"),
});

// Из текстового содержимого
await telegram.api.sendDocument({
    chat_id: 123456,
    document: MediaUpload.text("Hello world", "hello.txt"),
});

MediaInput

Используйте MediaInput для sendMediaGroup и подобных методов:

import { Telegram, MediaInput, MediaUpload } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

await telegram.api.sendMediaGroup({
    chat_id: 123456,
    media: [
        MediaInput.document(
            MediaUpload.url("https://example.com/file.pdf")
        ),
        MediaInput.document(MediaUpload.path("./package.json")),
    ],
});

Клавиатуры

Для inline и reply клавиатур установите @gramio/keyboards:

import { Telegram } from "wrappergram";
import { InlineKeyboard } from "@gramio/keyboards";

const telegram = new Telegram("BOT_TOKEN");

await telegram.api.sendMessage({
    chat_id: "@gramio_forum",
    text: "Hello!",
    reply_markup: new InlineKeyboard().url(
        "GitHub",
        "https://github.com/gramiojs/wrappergram"
    ),
});

Типы

Wrappergram реэкспортирует все типы Telegram Bot API из @gramio/types:

import type { TelegramMessage, TelegramUpdate } from "wrappergram";