@kilnjs/telegram

Telegram messages for KilnJS, as a module core is given rather than one it contains.

The bot API over fetch, and nothing else: no SDK and no dependency. Every method is a POST of JSON to a URL with the token in it, and a package that wraps that is a package to keep current for no reason.

Install

yarn add @kilnjs/telegram

import { telegram } from "@kilnjs/telegram";

export default {
  modules: [telegram()],
} satisfies AppConfig;

import { Telegram } from "@kilnjs/telegram";

await Telegram.send({ text: "Deploy finished", silent: true });

Settings

| | | | | --- | --- | --- | | token | TELEGRAM_BOT_TOKEN | required. Issued by BotFather, and the only credential there is | | chat | TELEGRAM_CHAT_ID | where a message goes when the call does not say | | parse | TELEGRAM_PARSE_MODE | HTML. Or MarkdownV2, or none | | api | TELEGRAM_API_URL | the bot API, overridable for a self-hosted one | | timeout | TELEGRAM_TIMEOUT_MS | 10000. How long a call may take before it is given up on: fetch has no limit of its own, and this sits on an alerting path | | driver | TELEGRAM_DRIVER | bot, and memory in a test run | | silent | TELEGRAM_SILENT | false. Delivered without a notification | | preview | TELEGRAM_PREVIEW | false. Whether a link in the text unfurls | | protect | TELEGRAM_PROTECT | false. Whether a message may be forwarded or saved | | thread | TELEGRAM_THREAD_ID | the topic inside a forum group | | retries | TELEGRAM_RETRIES | 0. Attempts after a call that did not arrive | | retryDelay | TELEGRAM_RETRY_DELAY_MS | 500, doubling after each attempt |

A message with no chat in the call and no default configured is refused here rather than sent to whichever chat happened to be last.

Every per-message field has a default here, and a call still overrides it: silent, preview, protect, thread and parse are declared once for a server whose messages are all alerts, and named in the call where one is not.

Retries are off unless something asks for them. A message Telegram read and refused is refused again, so only a call that never arrived, a 429 and a 5xx are sent a second time.

What it gets right

ok: false is a failure. Telegram answers a refused message with HTTP 200 and ok: false, and a client that only checked the status would report success. Both are checked, and the description Telegram gave is what reaches the log.

Link previews are off. An alert that unfurls a link is an alert with somebody else's image in it. Pass preview: true in the call, or declare it once in telegram({ preview: true }).

A test run sends nothing. Every message is recorded instead, and sentMessages() is what a suite asserts against. No token is needed for that, and none is reached. driver: "memory" is the same thing anywhere else, for a staging deployment that should not message a real chat.

Beyond a message

Telegram.call(method, payload) is the whole bot API, for the hundred methods this package does not wrap:

await Telegram.call("sendDocument", { chat_id: chat, document: url });

It is not recorded in a test run, because what it does is not known here: a suite that calls it is asking for the call to happen.

Development

yarn verify   # ts:check, lint, build, exports:check, test