@suaveplan/telegram-client - Telegram Bot API client — send/edit/delete messages, media, inline + custom keyboards, typed errors, injectable fetch + clock, OTel instrumented

Telegram Bot API client: send/edit/delete messages, six media variants, inline + custom keyboards, typed errors, injectable fetch + clock, and OpenTelemetry counters/histograms on every code path. Runtime-agnostic (works in Bun, Node, Deno, browsers).

Documentation tree

telegram-bot-client — TelegramBotClient is the public, runtime-agnostic Telegram Bot API client. It wraps the handful of Bot API endpoints…
- telegram-bot-client — TelegramBotClient is the public, runtime-agnostic Telegram Bot API client. It wraps the handful of Bot API endpoints…
errors — Defines the namespaced, frozen error-code registry and the typed TelegramClientError class used by every runtime fail…
- telegram-client-error — Defines the namespaced, frozen error-code registry and the typed TelegramClientError class used by every runtime fail…
types — Defines the Zod schema that validates TelegramBotConfig at the public construction boundary of TelegramBotClient. T…
- telegram-bot-config — Defines the Zod schema that validates TelegramBotConfig at the public construction boundary of TelegramBotClient. T…
build-bodies — Pure, side-effect-free helpers that translate the camelCase public message / reply-markup shape used by callers into th…
classify-error — Pure helpers that turn an outgoing-protocol failure (HTTP status + Telegram description + parsed body) into a stable…

Installation

bun add @suaveplan/telegram-client

Quick Start

import { createTelegramBotClient } from "@suaveplan/telegram-client";

const bot = createTelegramBotClient({ token: process.env.TELEGRAM_TOKEN! });

const sent = await bot.sendMessage({
  chatId: 12345,
  text: "Hello",
  parseMode: "HTML",
});

console.log(sent.messageId);

Modules

Module	Path	Description
Client	src/core/telegram-bot-client/telegram-bot-client.md	`TelegramBotClient` class, factory, OTel metrics
Body Builders	src/utils/build-bodies.md	Pure camelCase → snake_case translators
Error Classifier	src/utils/classify-error.md	Pure status + retry-after classifier
Errors	src/errors/telegram-client-error.md	Code registry + typed error class
Config Schema	src/types/telegram-bot-config.md	Zod validation at the boundary
Types	src/types/telegram-client.types.md	Public type surface

Subpath Exports

import { createTelegramBotClient } from "@suaveplan/telegram-client";
import {
  TELEGRAM_CLIENT_CODES,
  TelegramClientError,
} from "@suaveplan/telegram-client/errors";
import type { TelegramMessage } from "@suaveplan/telegram-client/types";

Error Codes

Code	When
`TELEGRAM_CLIENT.CONFIG_MISSING`	Config rejected by Zod schema (missing token, invalid URL, etc.)
`TELEGRAM_CLIENT.TIMEOUT`	Request aborted before completion
`TELEGRAM_CLIENT.AUTH_ERROR`	Telegram returned HTTP 401
`TELEGRAM_CLIENT.RATE_LIMITED`	Telegram returned HTTP 429 (`context.retryAfterMs` set if parseable)
`TELEGRAM_CLIENT.CHAT_NOT_FOUND`	HTTP 404, or HTTP 400 with `chat not found` / `channel not found`
`TELEGRAM_CLIENT.BOT_BLOCKED`	HTTP 403 with `bot was blocked` / `user is deactivated`
`TELEGRAM_CLIENT.FORBIDDEN`	Other HTTP 403, or HTTP 400 with `not enough rights` / `forbidden`
`TELEGRAM_CLIENT.API_ERROR`	Catch-all for unclassified Telegram failures

OTel Instruments

Counter telegram_client.request.total — keyed by { method, outcome }
Histogram telegram_client.request.duration_ms — keyed by { method, outcome }
outcome ∈ { "success", "error", "timeout" }

Call resetTelegramClientMetrics() from tests after replacing the global MeterProvider so each test sees a fresh meter.

Verification

Tests use injected fetch / clock — no mocks, no network.
100% istanbul coverage on touched modules.