@zero-bot.net/tg-bot-api 1.2.0 → 1.5.0

package/README.md

@@ -2,130 +2,149 @@
 
 <div align="center">
 
-Node.js module to interact with the official [Telegram Bot API](https://core.telegram.org/bots/api).
+A lightweight, dependency-light Node.js library for the [Telegram Bot API](https://core.telegram.org/bots/api).
 
-
-[![Bot API](https://img.shields.io/badge/Bot%20API-v.3-00aced.svg?style=flat-square&logo=telegram)](https://core.telegram.org/bots/api)
+[![Bot API](https://img.shields.io/badge/Bot%20API-v.10.3-00aced.svg?style=flat-square&logo=telegram)](https://core.telegram.org/bots/api)
 [![npm package](https://img.shields.io/npm/v/@zero-bot.net/tg-bot-api?logo=npm&style=flat-square)](https://www.npmjs.org/package/@zero-bot.net/tg-bot-api)
-[![Build Status](https://img.shields.io/travis/ZeroBot-net/tg-bot-api/master?style=flat-square&logo=travis)](https://travis-ci.org/ZeroBot-net/tg-bot-api)
-[![Coverage Status](https://img.shields.io/codecov/c/github/ZeroBot-net/tg-bot-api?style=flat-square&logo=codecov)](https://codecov.io/gh/ZeroBot-net/tg-bot-api)
-
-[![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬%20Telegram-Channel-blue.svg?style=flat-square)](https://telegram.me/node_telegram_bot_api)
-[![https://t.me/+nc3A9Hs1S81mYzdk](https://img.shields.io/badge/💬%20Telegram-Group-blue.svg?style=flat-square)](https://t.me/+nc3A9Hs1S81mYzdk)
-[![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬%20Telegram-Yago_Perez-blue.svg?style=flat-square)](https://telegram.me/Yago_Perez)
 
 </div>
 
+## ✨ Features
+
+- **202 methods** — full Telegram Bot API 10.3 coverage
+- **No build step** — ships native CommonJS, runs on Node.js 18+
+- **Small dependency tree** — file-type detection and MIME lookup are built in
+- **Built-in TypeScript definitions**
+- **Both update modes** — long polling *and* webhooks (with a built-in HTTP(S) server)
+- Rich Messages, Ephemeral Messages, Guest Mode, Business Accounts
+- Gifts, Stars & Payments, Checklists, Media Polls, Live Photos, Stories
+- Communities, Managed Bots, Suggested Posts, and more
+
 ## 📦 Install
 
 ```sh
 npm i @zero-bot.net/tg-bot-api
 ```
 
-<br/>
-
-> ✍️ **Note:** If you use Typescript you can install this package that contains type definitions for this library
->```sh
->npm install --save-dev @types/@zero-bot.net/tg-bot-api
->```
-
 ## 🚀 Usage
 
 ```js
 const TelegramBot = require('@zero-bot.net/tg-bot-api');
 
-// replace the value below with the Telegram token you receive from @BotFather
 const token = 'YOUR_TELEGRAM_BOT_TOKEN';
 
-// Create a bot that uses 'polling' to fetch new updates
-const bot = new TelegramBot(token, {polling: true});
+// Polling mode
+const bot = new TelegramBot(token, { polling: true });
 
-// Matches "/echo [whatever]"
 bot.onText(/\/echo (.+)/, (msg, match) => {
-  // 'msg' is the received Message from Telegram
-  // 'match' is the result of executing the regexp above on the text content
-  // of the message
-
-  const chatId = msg.chat.id;
-  const resp = match[1]; // the captured "whatever"
-
-  // send back the matched "whatever" to the chat
-  bot.sendMessage(chatId, resp);
+  bot.sendMessage(msg.chat.id, match[1]);
 });
 
-// Listen for any kind of message. There are different kinds of
-// messages.
 bot.on('message', (msg) => {
-  const chatId = msg.chat.id;
+  console.log(msg.chat.id, msg.text);
+});
+```
+
+### Sending files
+
+`sendPhoto`, `sendDocument`, `sendAudio`, ... accept a **local path**, a
+**stream**, a **Buffer**, a **URL**, or a **`file_id`**:
+
+```js
+await bot.sendPhoto(chatId, './cat.png');          // path
+await bot.sendPhoto(chatId, buffer);               // Buffer (type auto-detected)
+await bot.sendPhoto(chatId, 'https://x/y.png');    // URL
+await bot.sendPhoto(chatId, fileId);               // previously uploaded file
+```
 
-  // send a message to the chat acknowledging receipt of their message
-  bot.sendMessage(chatId, 'Received your message');
+### Webhooks
+
+```js
+const bot = new TelegramBot(token, {
+  webHook: { port: 8443, host: '0.0.0.0', healthEndpoint: '/healthz' },
 });
+
+bot.on('message', (msg) => bot.sendMessage(msg.chat.id, 'hi'));
+await bot.setWebHook('https://example.com:8443');
 ```
 
-## 📚 Documentation
+### Error handling
 
-* [Usage][usage]
-* [Examples][examples]
-* [Tutorials][tutorials]
-* [Help Information][help]
-* API Reference: ([api-release](../master/doc/api.md) / [development][api-dev] / [experimental][api-experimental])
-* [Contributing to the Project][contributing]
-* [Experimental Features][experimental]
+All API errors are `errors.TelegramError` (code `ETELEGRAM`) and carry the raw
+server `response`. Transport failures are `errors.FatalError` (code `EFATAL`)
+with the original error preserved as `.cause`.
 
-_**Note**: Development is done against the **development** branch.
-Code for the latest release resides on the **master** branch.
-Experimental features reside on the **experimental** branch._
+```js
+const { TelegramError } = require('@zero-bot.net/tg-bot-api');
 
+bot.on('polling_error', (err) => {
+  if (err instanceof TelegramError) console.error(err.response.body);
+  else console.error(err.message, err.cause);
+});
+```
 
-## 💭 Community
+## ⚡ Performance & latency
+
+Warm (keep-alive) requests take **20–80ms**. Cold connections pay DNS + TCP +
+TLS **plus Node's 250ms IPv6 fallback window** — that is what pushes a request
+to 200–600ms. Ranked fixes:
+
+1. **Host near Telegram** (EU/US) — RTT drops from ~200ms to ~10–30ms. No code.
+2. **Self-hosted Bot API server** — biggest win for media; files never leave
+   your machine:
+   ```js
+   const bot = new TelegramBot(token, { baseApiUrl: 'http://127.0.0.1:8081' });
+   ```
+3. **Remove the IPv6 fallback penalty** (up to −250ms per connection):
+   ```js
+   TelegramBot.applyNetworkTuning();          // ipv4-first + 100ms fallback window
+   // or: new TelegramBot(token, { ipv4First: true });
+   ```
+4. **Pre-warm the connection** so the first request is not a cold start:
+   ```js
+   const bot = new TelegramBot(token, { prewarm: true });
+   // or: await bot.preheat();
+   ```
+5. **Tune polling** for instant updates:
+   `{ polling: { params: { timeout: 30 }, interval: 50 } }`.
+6. **Fewer round-trips** — batch with `sendMediaGroup` / `forwardMessages` /
+   `copyMessages`, and reuse `file_id`s instead of re-uploading.
+
+Keep-alive is enabled by default (`forever: true`); tune the pool if needed:
 
-We thank all the developers in the Open-Source community who continuously
-take their time and effort in advancing this project.
-See our [list of contributors][contributors].
+```js
+new TelegramBot(token, {
+  request: {
+    agentOptions: { keepAlive: true, keepAliveMsecs: 10000, maxSockets: 64 },
+  },
+});
+```
 
-We have a [Telegram channel][tg-channel] where we post updates on
-the Project. Head over and subscribe!
+## 📚 Documentation
 
-We also have a [Telegram  group][tg-group] to discuss issues related to this library.
+- [`doc/usage.md`](doc/usage.md) — full usage guide
+- [`doc/api.md`](doc/api.md) — API reference (generated from `src/telegram.js`)
+- [`doc/help.md`](doc/help.md) — FAQs and common pitfalls
+- [`examples/`](examples/) — runnable examples
 
-Some things built using this library that might interest you:
+## 🧪 Development
 
-* [tgfancy](https://github.com/GochoMugo/tgfancy): A fancy, higher-level wrapper for Telegram Bot API
-* [@zero-bot.net/tg-bot-api-middleware](https://github.com/idchlife/@zero-bot.net/tg-bot-api-middleware): Middleware for @zero-bot.net/tg-bot-api
-* [teleirc](https://github.com/FruitieX/teleirc): A simple Telegram ↔ IRC gateway
-* [bot-brother](https://github.com/SerjoPepper/bot-brother): Node.js library to help you easily create telegram bots
-* [redbot](https://github.com/guidone/node-red-contrib-chatbot): A Node-RED plugin to create telegram bots visually
-* [node-telegram-keyboard-wrapper](https://github.com/alexandercerutti/node-telegram-keyboard-wrapper): A wrapper to improve keyboards structures creation through a more easy-to-see way (supports Inline Keyboards, Reply Keyboard, Remove Keyboard and Force Reply)
-* [beetube-bot](https://github.com/kodjunkie/beetube-bot): A telegram bot for music, videos, movies, EDM tracks, torrent downloads, files and more.
-* [telegram-inline-calendar](https://github.com/VDS13/telegram-inline-calendar): Date and time picker and inline calendar for Node.js telegram bots.
-* [telegram-captcha](https://github.com/VDS13/telegram-captcha): Telegram bot to protect Telegram groups from automatic bots.
+```sh
+npm test          # offline mocha test suite
+npm run lint      # eslint
+npm run doc       # regenerate doc/api.md
+```
 
+Requires Node.js >= 18.
 
 ## 👥 Contributors
 
-<p align="center">
-  <a href="https://github.com/ZeroBot-net/tg-bot-api/graphs/contributors">
-    <img src="https://contrib.rocks/image?repo=ZeroBot-net/tg-bot-api" />
-  </a>
-</p>
+<a href="https://github.com/ZeroBot-net/tg-bot-api/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=ZeroBot-net/tg-bot-api" />
+</a>
 
 ## License
 
 **The MIT License (MIT)**
 
-Copyright © 2019 Yago
 Copyright © 2026 Grandpa EJ
-
-[usage]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/usage.md
-[examples]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/examples
-[help]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/help.md
-[tutorials]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/tutorials.md
-[api-dev]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/api.md
-[api-release]:https://github.com/ZeroBot-net/tg-bot-api/tree/release/doc/api.md
-[api-experimental]:https://github.com/ZeroBot-net/tg-bot-api/tree/experimental/doc/api.md
-[contributing]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/CONTRIBUTING.md
-[contributors]:https://github.com/ZeroBot-net/tg-bot-api/graphs/contributors
-[experimental]:https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/experimental.md
-[tg-channel]:https://telegram.me/node_telegram_bot_api
-[tg-group]:https://t.me/+nc3A9Hs1S81mYzdk

package/index.js

@@ -1,13 +1,7 @@
 /**
- * If running on Nodejs 5.x and below, we load the transpiled code.
- * Otherwise, we use the ES6 code.
- * We are deprecating support for Node.js v5.x and below.
+ * @zero-bot.net/tg-bot-api
+ *
+ * CommonJS entry point. The library ships native ES2020 source (no build or
+ * transpile step), so this simply re-exports it.
  */
-const majorVersion = parseInt(process.versions.node.split('.')[0], 10);
-if (majorVersion <= 5) {
-  const deprecate = require('./src/utils').deprecate;
-  deprecate('Node.js v5.x and below will no longer be supported in the future');
-  module.exports = require('./lib/telegram');
-} else {
-  module.exports = require('./src/telegram');
-}
+module.exports = require('./src/telegram');

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@zero-bot.net/tg-bot-api",
-  "version": "1.2.0",
-  "description": "Telegram Bot API",
+  "version": "1.5.0",
+  "description": "Lightweight, dependency-light Telegram Bot API library for Node.js",
   "main": "./index.js",
-  "types": "./lib/telegram.d.ts",
+  "types": "./src/telegram.d.ts",
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
   "directories": {
     "example": "examples",
     "test": "test"
@@ -17,60 +25,34 @@
     "zero-bot.net"
   ],
   "scripts": {
-    "gen-doc": "echo 'WARNING: `npm run gen-doc` is deprecated. Use `npm run doc` instead.' && npm run doc",
     "doc": "jsdoc2md --files src/telegram.js --template doc/api.hbs > doc/api.md",
-    "build": "babel -d ./lib src",
-    "prepublishOnly": "npm run build && npm run gen-doc",
-    "eslint": "eslint ./src ./test ./examples",
-    "mocha": "mocha",
-    "pretest": "npm run build",
-    "test": "npm run eslint && istanbul cover ./node_modules/mocha/bin/_mocha"
+    "lint": "eslint .",
+    "test": "mocha",
+    "test:watch": "mocha --watch",
+    "prepublishOnly": "npm run lint && npm test && npm run doc"
   },
   "author": "ZeroBot",
   "license": "MIT",
   "engines": {
-    "node": ">=0.12"
+    "node": ">=18"
   },
   "dependencies": {
     "@zero-bot.net/request": "^1.2.1",
-    "array.prototype.findindex": "^2.2.4",
-    "bl": "^7.0.12",
     "debug": "^4.4.3",
     "eventemitter3": "^5.0.4",
-    "file-type": "^22.1.0",
-    "mime": "^4.1.0",
     "pump": "^3.0.4"
   },
   "devDependencies": {
-    "babel-cli": "^6.26.0",
-    "babel-eslint": "^10.1.0",
-    "babel-plugin-transform-class-properties": "^6.24.1",
-    "babel-plugin-transform-es2015-destructuring": "^6.23.0",
-    "babel-plugin-transform-es2015-parameters": "^6.24.1",
-    "babel-plugin-transform-es2015-shorthand-properties": "^6.24.1",
-    "babel-plugin-transform-es2015-spread": "^6.22.0",
-    "babel-plugin-transform-object-rest-spread": "^6.26.0",
-    "babel-plugin-transform-strict-mode": "^6.24.1",
-    "babel-preset-es2015": "^6.24.1",
-    "babel-register": "^6.26.0",
-    "concat-stream": "^2.0.0",
     "eslint": "^10.10.0",
-    "eslint-config-airbnb": "^19.0.4",
-    "eslint-plugin-mocha": "^12.0.2",
-    "is": "^3.3.2",
-    "is-ci": "^4.1.0",
-    "istanbul": "^1.1.0-alpha.1",
     "jsdoc-to-markdown": "^9.1.3",
-    "mocha": "^12.0.1",
-    "mocha-lcov-reporter": "^1.3.0",
-    "node-static": "^0.7.11"
+    "mocha": "^12.0.1"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ZeroBot-net/tg-bot-api.git"
+    "url": "git+https://github.com/ZeroBot-net/tg-bot-api.git"
   },
   "bugs": {
     "url": "https://github.com/ZeroBot-net/tg-bot-api/issues"
   },
   "homepage": "https://github.com/ZeroBot-net/tg-bot-api"
-}
+}

package/src/errors.js

@@ -19,6 +19,33 @@ exports.BaseError = class BaseError extends Error {
 };
 
 
+/**
+ * Build a readable message from an arbitrary thrown value. Handles the common
+ * case where a non-`Error` or an `AggregateError` has an empty `message`, which
+ * previously produced a blank `EFATAL:` error.
+ * @private
+ * @param  {*} data
+ * @return {String}
+ */
+function describeError(data) {
+  if (typeof data === 'string') return data;
+  if (data === null || data === undefined) return String(data);
+  if (data instanceof Error) {
+    if (data.errors && data.errors.length) {
+      const nested = data.errors.map(describeError).join('; ');
+      return data.message ? `${data.message} (${nested})` : nested;
+    }
+    const label = data.code || data.name || 'Error';
+    return data.message ? `${label}: ${data.message}` : String(label);
+  }
+  if (typeof data.message === 'string' && data.message) return data.message;
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return String(data);
+  }
+}
+
 exports.FatalError = class FatalError extends exports.BaseError {
   /**
    * Fatal Error. Error code is `"EFATAL"`.
@@ -28,9 +55,12 @@ exports.FatalError = class FatalError extends exports.BaseError {
    */
   constructor(data) {
     const error = (typeof data === 'string') ? null : data;
-    const message = error ? error.message : data;
-    super('EFATAL', message);
-    if (error) this.stack = error.stack;
+    super('EFATAL', describeError(data));
+    if (error) {
+      this.stack = error.stack || this.stack;
+      // Preserve the original error for programmatic inspection & logging.
+      this.cause = error;
+    }
   }
 };
 

package/src/fileTypes.js

@@ -0,0 +1,188 @@
+/**
+ * Zero-dependency file type detection and MIME lookup.
+ *
+ * Replaces the `file-type` and `mime` packages so the library installs with a
+ * minimal, fully CommonJS dependency tree and no ESM/CJS interop surprises.
+ *
+ * @module fileTypes
+ * @private
+ */
+
+/**
+ * Magic-byte signatures for the file formats that can be uploaded through the
+ * Telegram Bot API. Each entry is `{ ext, mime, bytes? , ascii?, offset? }`.
+ */
+const SIGNATURES = [
+  { bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], ext: 'png', mime: 'image/png' },
+  { bytes: [0xff, 0xd8, 0xff], ext: 'jpg', mime: 'image/jpeg' },
+  { ascii: 'GIF87a', ext: 'gif', mime: 'image/gif' },
+  { ascii: 'GIF89a', ext: 'gif', mime: 'image/gif' },
+  { ascii: 'RIFF', ext: 'webp', mime: 'image/webp', tail: { offset: 8, ascii: 'WEBP' } },
+  { ascii: 'RIFF', ext: 'wav', mime: 'audio/wav', tail: { offset: 8, ascii: 'WAVE' } },
+  { ascii: 'RIFF', ext: 'avi', mime: 'video/x-msvideo', tail: { offset: 8, ascii: 'AVI ' } },
+  { bytes: [0x42, 0x4d], ext: 'bmp', mime: 'image/bmp' },
+  { ascii: 'II*\u0000', ext: 'tiff', mime: 'image/tiff' },
+  { ascii: 'MM\u0000*', ext: 'tiff', mime: 'image/tiff' },
+  { ascii: '%PDF', ext: 'pdf', mime: 'application/pdf' },
+  { bytes: [0x50, 0x4b, 0x03, 0x04], ext: 'zip', mime: 'application/zip' },
+  { bytes: [0x1f, 0x8b], ext: 'gz', mime: 'application/gzip' },
+  { bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07], ext: 'rar', mime: 'application/x-rar-compressed' },
+  { bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], ext: '7z', mime: 'application/x-7z-compressed' },
+  { ascii: 'ID3', ext: 'mp3', mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xfb], ext: 'mp3', mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xf3], ext: 'mp3', mime: 'audio/mpeg' },
+  { bytes: [0xff, 0xf2], ext: 'mp3', mime: 'audio/mpeg' },
+  { ascii: 'OggS', ext: 'ogg', mime: 'audio/ogg' },
+  { ascii: 'fLaC', ext: 'flac', mime: 'audio/flac' },
+  { bytes: [0x1a, 0x45, 0xdf, 0xa3], ext: 'webm', mime: 'video/webm' },
+  { ascii: 'MThd', ext: 'mid', mime: 'audio/midi' },
+  { ascii: '{\\rtf', ext: 'rtf', mime: 'application/rtf' },
+];
+
+/** ISO-BMFF brands (`ftyp` box) mapped to a container extension + MIME type. */
+const FTYP_BRANDS = {
+  'M4A ': { ext: 'm4a', mime: 'audio/mp4' },
+  'M4V ': { ext: 'm4v', mime: 'video/x-m4v' },
+  'qt  ': { ext: 'mov', mime: 'video/quicktime' },
+  '3gp4': { ext: '3gp', mime: 'video/3gpp' },
+  '3gp5': { ext: '3gp', mime: 'video/3gpp' },
+};
+
+/**
+ * Common filename extensions mapped to their MIME type. Used when an explicit
+ * content type is not provided for a path/stream upload.
+ */
+const EXTENSION_MIME = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+  tiff: 'image/tiff',
+  tif: 'image/tiff',
+  svg: 'image/svg+xml',
+  heic: 'image/heic',
+  ico: 'image/x-icon',
+  mp3: 'audio/mpeg',
+  m4a: 'audio/mp4',
+  aac: 'audio/aac',
+  ogg: 'audio/ogg',
+  oga: 'audio/ogg',
+  opus: 'audio/opus',
+  wav: 'audio/wav',
+  flac: 'audio/flac',
+  mp4: 'video/mp4',
+  m4v: 'video/x-m4v',
+  mov: 'video/quicktime',
+  avi: 'video/x-msvideo',
+  webm: 'video/webm',
+  mkv: 'video/x-matroska',
+  '3gp': 'video/3gpp',
+  pdf: 'application/pdf',
+  zip: 'application/zip',
+  gz: 'application/gzip',
+  tgz: 'application/gzip',
+  tar: 'application/x-tar',
+  rar: 'application/x-rar-compressed',
+  '7z': 'application/x-7z-compressed',
+  txt: 'text/plain',
+  csv: 'text/csv',
+  html: 'text/html',
+  htm: 'text/html',
+  css: 'text/css',
+  js: 'application/javascript',
+  json: 'application/json',
+  xml: 'application/xml',
+  md: 'text/markdown',
+  rtf: 'application/rtf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  epub: 'application/epub+zip',
+  apk: 'application/vnd.android.package-archive',
+  tgs: 'application/x-tgsticker',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+};
+
+/**
+ * Compare a byte sequence against the buffer at the given offset.
+ * @private
+ */
+function matchesBytes(buffer, bytes, offset = 0) {
+  if (buffer.length < offset + bytes.length) return false;
+  for (let i = 0; i < bytes.length; i += 1) {
+    if (buffer[offset + i] !== bytes[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Compare an ASCII sequence against the buffer at the given offset.
+ * @private
+ */
+function matchesAscii(buffer, ascii, offset = 0) {
+  if (buffer.length < offset + ascii.length) return false;
+  for (let i = 0; i < ascii.length; i += 1) {
+    if (buffer[offset + i] !== ascii.charCodeAt(i)) return false;
+  }
+  return true;
+}
+
+/**
+ * Detect the file type of a Buffer from its magic bytes.
+ *
+ * @param  {Buffer} buffer Data to inspect
+ * @return {Object|null} `{ ext, mime }` when recognized, otherwise `null`
+ */
+function detectFileType(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 3) {
+    return null;
+  }
+
+  for (const sig of SIGNATURES) {
+    const headMatches = sig.bytes
+      ? matchesBytes(buffer, sig.bytes)
+      : matchesAscii(buffer, sig.ascii);
+
+    if (!headMatches) continue;
+
+    if (sig.tail && !matchesAscii(buffer, sig.tail.ascii, sig.tail.offset)) {
+      continue;
+    }
+
+    return { ext: sig.ext, mime: sig.mime };
+  }
+
+  // ISO Base Media File Format (mp4/m4a/mov/3gp) — 'ftyp' box at offset 4.
+  if (buffer.length >= 12 && matchesAscii(buffer, 'ftyp', 4)) {
+    const brand = buffer.toString('ascii', 8, 12);
+    return FTYP_BRANDS[brand] || { ext: 'mp4', mime: 'video/mp4' };
+  }
+
+  return null;
+}
+
+/**
+ * Look up a MIME type by filename or extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ *
+ * @param  {String} filename File name or extension (with or without a dot)
+ * @return {String} MIME type
+ */
+function lookupMime(filename) {
+  if (!filename || typeof filename !== 'string') {
+    return 'application/octet-stream';
+  }
+  const match = /\.([a-z0-9]+)$/i.exec(filename);
+  const ext = (match ? match[1] : filename).toLowerCase();
+  return EXTENSION_MIME[ext] || 'application/octet-stream';
+}
+
+module.exports = { detectFileType, lookupMime };

package/src/network.js

@@ -0,0 +1,47 @@
+/**
+ * Optional, opt-in network tuning that removes the most common latency
+ * penalties when talking to the Telegram Bot API over a fresh connection.
+ *
+ * The biggest offender is Node's "happy eyeballs" behaviour: on networks with
+ * broken or absent IPv6 it waits `autoSelectFamilyAttemptTimeout` (250ms by
+ * default) before falling back to IPv4 — on *every* new connection. Preferring
+ * IPv4 and shortening that window can cut 100–250ms off cold requests.
+ *
+ * These helpers mutate process-global Node settings, so they are never applied
+ * automatically — call `applyNetworkTuning()` once at startup, or pass
+ * `{ ipv4First: true }` to the `TelegramBot` constructor.
+ *
+ * @module network
+ */
+
+/**
+ * Apply latency-oriented network defaults.
+ *
+ * @param  {Object} [options]
+ * @param  {Boolean} [options.ipv4First=true] Prefer IPv4 when resolving hosts
+ *   (`dns.setDefaultResultOrder('ipv4first')`).
+ * @param  {Number} [options.autoSelectFamilyAttemptTimeout=100] Milliseconds to
+ *   wait for an IPv6 connection before falling back to IPv4 (Node default: 250).
+ * @return {Object} The applied settings.
+ */
+function applyNetworkTuning(options = {}) {
+  const ipv4First = options.ipv4First !== false;
+  const autoSelectFamilyAttemptTimeout = typeof options.autoSelectFamilyAttemptTimeout === 'number'
+    ? options.autoSelectFamilyAttemptTimeout
+    : 100;
+
+  const dns = require('dns');
+  const net = require('net');
+
+  if (ipv4First && typeof dns.setDefaultResultOrder === 'function') {
+    dns.setDefaultResultOrder('ipv4first');
+  }
+
+  if (typeof net.setDefaultAutoSelectFamilyAttemptTimeout === 'function') {
+    net.setDefaultAutoSelectFamilyAttemptTimeout(autoSelectFamilyAttemptTimeout);
+  }
+
+  return { ipv4First, autoSelectFamilyAttemptTimeout };
+}
+
+module.exports = { applyNetworkTuning };