Class BaseBotClientAbstract

constructor

• new BaseBotClient(token: string, options?: BotOptions): BaseBotClient

  Constructs a new BaseBotClient.

  Parameters

  • token: string

    Telegram bot token received from BotFather. Must follow format <bot_id>:<secret_token>.

  • options: BotOptions = {}

    Configuration options for the client including custom fetch or local API server URL.

  Returns BaseBotClient

  Throws

  When the token is empty or invalid.

ReadonlyapiRoot

Readonlyoptions

Readonlytoken

configureRetry

• configureRetry(options: Partial<RetryOptions>): this

  Dynamically configures or updates the auto-retry and flood control settings.

  Parameters

  • options: Partial<RetryOptions>

    Partial retry options to update.

  Returns this

  This client instance for chaining.

  Example

  bot.configureRetry({
    maxRetryAttempts: 5,
    minDelaySeconds: 2,
  });
  Copy

onApiError

• onApiError(hook: ApiErrorHookFn, tag?: string): this

  Registers an observer invoked whenever a Bot API request finally fails.

  Hooks run in registration order right before the TelegramApiError is thrown, after retries are exhausted. Observers cannot alter the error; exceptions inside a hook are swallowed and logged. Useful for alerting and metrics plugins.

  Parameters

  • hook: ApiErrorHookFn

    Callback receiving the method name and the final error.

  • Optionaltag: string

    Optional owner tag for grouped removal via BaseBotClient.removeHooksByTag.

  Returns this

  This client instance for chaining.

  Example

  bot.onApiError((method, error) => {
    console.error(`${method} failed: ${error.description}`);
  });
  Copy

removeHooksByTag

• removeHooksByTag(tag: string): number

  Removes every request transform, response transform, and API error hook registered with the given owner tag.

  Parameters

  • tag: string

    Owner tag previously passed when registering hooks.

  Returns number

  The number of hooks removed.

  Example

  bot.removeHooksByTag("my-plugin");
  Copy

request

• request<T>(method: string, payload?: Record<string, unknown>): Promise<T>

  Core request dispatcher to execute any raw Telegram Bot API endpoint.

  Automatically serializes JSON objects or multipart FormData when file buffers / InputFile are present. Handles HTTP 429 rate-limiting (honoring retry_after) and HTTP 5xx retries with exponential backoff, sharing a single retry budget across both so that repeated 429s cannot retry forever or starve genuine 5xx retries.

  Type Parameters

  • T

    The expected return payload type from Telegram.

  Parameters

  • method: string

    The Bot API method name (e.g. "sendMessage", "getMe", "setWebhook").

  • payload: Record<string, unknown> = {}

    Key-value parameters corresponding to the API method fields.

  Returns Promise<T>

  Resolves with the unwrapped result field returned by Telegram.

  Throws

  TelegramApiError When Telegram returns ok: false, HTTP 4xx, or after retry exhaustion on 429/5xx/network errors.

  Example

  const user = await bot.request<User>("getMe");
  console.log(`Bot username: @${user.username}`);
  Copy

sleep

• sleep(seconds: number): Promise<void>

  Helper utility to pause asynchronous execution for a given number of seconds.

  Used internally during retry delays and rate-limit backoff.

  Parameters

  • seconds: number

    Duration in seconds to pause execution.

  Returns Promise<void>

  Promise that resolves once the specified duration elapses.

  Example

  await bot.sleep(2); // Pauses execution for 2 seconds
  Copy

transformRequest

• transformRequest(hook: RequestTransformFn, tag?: string): this

  Registers a hook invoked before every outgoing Bot API request.

  Hooks run in registration order and may mutate the payload. Intended for plugins that need to observe or decorate all API traffic (logging, metrics, throttling signals, test mocks).

  Parameters

  • hook: RequestTransformFn

    Callback receiving the method name and the mutable payload.

  • Optionaltag: string

    Optional owner tag; all hooks sharing a tag can be removed together via BaseBotClient.removeHooksByTag.

  Returns this

  This client instance for chaining.

  Example

  bot.transformRequest((method, payload) => {
    console.log(`Calling ${method}`);
    payload["protect_content"] = true;
  });
  Copy

transformResponse

• transformResponse(hook: ResponseTransformFn, tag?: string): this

  Registers a hook invoked with every successful Bot API response.

  Hooks run in registration order. Returning a value replaces the result for subsequent hooks and the caller; returning undefined keeps it unchanged. Useful for response logging, caching, or normalization plugins.

  Parameters

  • hook: ResponseTransformFn

    Callback receiving the method name and the unwrapped result.

  • Optionaltag: string

    Optional owner tag for grouped removal via BaseBotClient.removeHooksByTag.

  Returns this

  This client instance for chaining.

  Example

  bot.transformResponse((method, result) => {
    console.log(`${method} succeeded`);
  });
  Copy