@gramio/tdlight

Type compatibility layer for tdlight-telegram-bot-api — a self-hosted fork of the Telegram Bot API server that adds extra methods, extra object fields, and an experimental user mode.

This package is types only. It augments @gramio/types (via TypeScript declaration merging) so bot.api.* and the response objects gain tdlight's surface. There is no runtime — import it for its side-effect, then point your bot at a tdlight server with api.baseURL.

npm install @gramio/tdlight
# bun add @gramio/tdlight · pnpm add @gramio/tdlight · yarn add @gramio/tdlight

Entry points

Declaration merging is global per import, so the surface is split by mode — pick the smallest one you need:

Import	Adds	Use when
@gramio/tdlight	object fields + bot-capable methods (ping, getChatMembers, getMessageInfo, proxies…), scheduling params, deleteMessages range	A normal bot token against a tdlight server (the safe default — no user-only methods polluting bot.api)
@gramio/tdlight/all	everything above plus user-only methods (searchMessages, votePoll, getChats, the auth flow…)	A userbot (/user{token}), which uses both surfaces
@gramio/tdlight/user	object fields + only the user-only methods	You want just the user-only delta

import { Bot } from "gramio";
import "@gramio/tdlight"; // bot surface

const bot = new Bot(process.env.BOT_TOKEN as string, {
  api: { baseURL: "http://localhost:8081/bot" }, // your tdlight server
});

const delay = await bot.api.ping();                                   // number
const admins = await bot.api.getChatMembers({ chat_id: -100123, filter: "admins" });
const file = await bot.api.sendDocument({ chat_id: 1, document: "file_id", send_at: "online" });

import { Bot } from "gramio";
import "@gramio/tdlight/all"; // userbot surface

// user token comes from the login flow (see "User mode" below)
const userbot = new Bot(USER_TOKEN, {
  api: { baseURL: "http://localhost:8081/user" }, // note the /user prefix
});

const hits = await userbot.api.searchMessages({ query: "invoice" }); // TelegramMessage[]
await userbot.api.votePoll({ chat_id: -100123, message_id: 42, option_ids: [0] });

What it adds

• New objects: AuthorizationState, CallbackQueryAnswer, TdlightProxy (exported from every entry).
• Object fields: User/Chat get is_verified/is_scam/is_fake (+ is_deleted/user_status/last_seen on User, distance on Chat); Message gets views/forwards/is_scheduled/scheduled_at; chat members get joined_date/inviter.
• Scheduling: send_at (number | "online") and repeat_period on the send/copy/forward family.
• Methods: the bot-capable and user-only methods listed above.

Method-name traps (why we don't follow the OpenAPI spec)

The tdlight server routes on the lowercased method name from its C++ source (Client.cpp), and several names in the published OpenAPI spec are wrong — they would 404. This package types the real routes:

Use this	Not this (404s)
votePoll	setPollAnswer
getMemoryStats	optimizeMemory
addChatMembers (plural)	addChatMember
getParticipants (alias of getChatMembers)	—

getMemoryStats, toggleGroupInvites, and reportChat are accepted by the server but are no-ops / unimplemented on current builds (see their JSDoc).

User mode

User mode (/user{token}) requires a server started with --allow-users (and --allow-users-registration for registerUser). Login is not a regular method: it is an empty-method POST to /user{token}/ with phone_number, then authCode → authPassword → optional registerUser. A runtime login helper is out of scope for this types-only package (planned separately); for now bot.api.authCode/authPassword/registerUser are typed for once you have a user token.

Known limitations

• deleteMessages range form: @gramio/types types message_ids as required, and declaration merging cannot relax a required field. The range fields start/end are typed on DeleteMessagesParams, but a range-only call still type-requires message_ids — pass []. The clean fix belongs upstream in @gramio/types.
• This package tracks tdlight's delta; it assumes a recent tdlight build (whose serializers already emit modern Bot API fields). It does not change any standard Bot API types.

License

MIT