Draft: feat: rewrite library in TypeScript with Zod runtime typing

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,8 +4,9 @@ For example, if your PR passes all tests, you would mark the option as so:
 - [x] All tests pass
 Note the 'x' in between the square brackets '[]'
 -->
-- [ ] All tests pass
-- [ ] I have run `npm run doc`
+- [ ] All unit tests pass (`npm run test:node:unit`)
+- [ ] All integration tests pass (`npm run test:node:integration`)
+- [ ] `npm run typecheck` is clean
 
 ### Description
 
@@ -21,3 +22,65 @@ For example,
 * Issue #1: https://github.com/yagop/node-telegram-bot-api/issues/1
 * Telegram Bot API - Getting updates: https://core.telegram.org/bots/api#getting-updates
 -->
+
+---
+
+### Running the test suite
+
+The project ships two test layers and supports both the Node.js native test
+runner and Bun. All scripts assume `npm install` (or `bun install`) has been
+run first.
+
+#### Unit tests
+
+Pure unit tests with no network. Safe to run anywhere — no token required.
+
+```bash
+npm run test:node:unit     # Node — node:test runner via tsx
+npm run test:bun:unit      # Bun — bun:test runner
+```
+
+#### Integration tests
+
+Hit `api.telegram.org` directly. Tests that would mutate irreversible bot
+configuration (e.g. `logOut`, `close`, `deleteWebHook`, `setMyName`,
+`setMyProfilePhoto`, `deleteStickerSet`, …) are deliberately skipped.
+
+**Required environment variables**
+
+| Var | Purpose |
+| --- | --- |
+| `NODE_TELEGRAM_TOKEN` | Bot token (or `TEST_TELEGRAM_TOKEN` as fallback). Create one via [@BotFather](https://t.me/BotFather). |
+| `TEST_GROUP_ID` | Chat id where the bot can send messages (group or private). |
+| `TEST_USER_ID` | A user id the bot can resolve in `TEST_GROUP_ID`. |
+
+**Optional**
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `TEST_STICKER_SET_NAME` | `pusheen` | Name of a public sticker set used in sticker tests. |
+| `TEST_CUSTOM_EMOJI_ID` | _(unset)_ | A custom emoji id; the related test is skipped if unset. |
+
+```bash
+NODE_TELEGRAM_TOKEN="<your-bot-token>" \
+TEST_GROUP_ID="-1001234567890" \
+TEST_USER_ID="123456789" \
+  npm run test:node:integration
+
+# Bun equivalent
+NODE_TELEGRAM_TOKEN="<your-bot-token>" \
+TEST_GROUP_ID="-1001234567890" \
+TEST_USER_ID="123456789" \
+  npm run test:bun:integration
+```
+
+> **Tip:** add the bot to a private test group, grab its id with
+> [`@RawDataBot`](https://t.me/RawDataBot) (or any update logger), and
+> use that id for `TEST_GROUP_ID`. `TEST_GROUP_ID` accepts the canonical
+> negative form (`-100…`) or a positive number — the suite normalizes it.
+
+#### Typecheck
+
+```bash
+npm run typecheck          # tsc --noEmit
+```

.github/workflows/ci.yml

@@ -0,0 +1,106 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main, feat/typescript]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      run_integration:
+        description: "Run integration tests against api.telegram.org (requires TEST_TELEGRAM_TOKEN secret)"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+# Cancel in-progress runs for the same PR/branch when a new commit is pushed.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci || npm install --no-audit --no-fund
+      - name: tsc --noEmit
+        run: npx tsc --noEmit
+
+  unit-node:
+    name: Unit tests (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["18", "20", "22"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - name: Install dependencies
+        run: npm ci || npm install --no-audit --no-fund
+      - name: Run unit tests
+        run: npm run test:node:unit
+
+  unit-bun:
+    name: Unit tests (Bun)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          # Bun 1.2+ ships with node:test compatibility, which our suite uses.
+          bun-version: latest
+      - name: Install dependencies
+        run: bun install --frozen-lockfile || bun install
+      - name: Run unit tests with Bun
+        run: npm run test:bun:unit
+
+  build:
+    name: Build (dist)
+    runs-on: ubuntu-latest
+    needs: typecheck
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci || npm install --no-audit --no-fund
+      - name: Build
+        run: npm run build
+      - name: Verify dist artefacts
+        run: |
+          test -f dist/index.js
+          test -f dist/index.d.ts
+          test -f dist/telegram.js
+          test -f dist/telegram.d.ts
+
+  integration:
+    name: Integration tests (api.telegram.org)
+    runs-on: ubuntu-latest
+    needs: typecheck
+    if: github.event_name == 'workflow_dispatch' && inputs.run_integration
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci || npm install --no-audit --no-fund
+      - name: Run integration tests
+        env:
+          TEST_TELEGRAM_TOKEN: ${{ secrets.TEST_TELEGRAM_TOKEN }}
+        run: npm run test:node:integration

.gitignore

@@ -2,9 +2,12 @@ node_modules
 coverage/
 npm-debug.log
 .package.json
-package-lock.json
 output.md
 output/
 lib/
 lib-doc/
-.DS_Store
+.DS_Store
+dist
+.claude
+.env
+.vscode

CHANGELOG.md

@@ -5,6 +5,44 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][Unreleased]
 
+## [1.0.0] — 2026-05-10
+
+### Rewritten in TypeScript
+
+The library has been rewritten from JavaScript to TypeScript with Zod runtime type validation.
+
+### Added
+
+- **TypeScript** — full type coverage for all API methods, options, and responses
+- **Zod schemas** — runtime validation of Telegram Bot API payloads, exported for reuse (`src/types/schemas.ts`)
+- **ESM** — the package is now ESM-only (`"type": "module"`); `require()` is no longer supported
+- `TelegramBotOptions` type exported from the main entrypoint
+- Type exports: `ChatId`, `ParseMode`, `MessageEntity`, `ReplyMarkup`, `ReplyParameters`, `LinkPreviewOptions`, `SuggestedPostPrice`, `SuggestedPostInfo`, `SuggestedPostParameters`, and all Zod-inferred API types
+- Node.js native test runner replaces Mocha
+- `sendLivePhoto` method
+
+### Changed
+
+- `src/telegram.js` → `src/telegram.ts` (full rewrite)
+- `src/telegramPolling.js` → `src/polling.ts`
+- `src/telegramWebHook.js` → `src/webhook.ts`
+- `src/errors.js` → `src/errors.ts`
+- `src/utils.js` → `src/utils.ts`
+- `test/` rewritten in TypeScript with `node:test` assertions
+- Build output: `lib/` → `dist/`
+
+### Removed
+
+- CJS support — `require('node-telegram-bot-api')` no longer works; use `import`
+- Mocha test infrastructure (`test/mocha.opts`, legacy `test/telegram.js`)
+- Legacy `lib/` output directory
+- `_deprecatedMessageTypes` (`new_chat_participant`, `left_chat_participant`)
+- Legacy param `thumb` replace with `thumbnail`
+
+### Fixed
+
+- String errors now include timestamps in console output
+
 ## [0.68.0][0.68.0] - 2026-04-05
 
 Added:

appveyor.yml

@@ -0,0 +1,21 @@
+version: "{build}"
+
+environment:
+  matrix:
+    - nodejs_version: "22"
+    - nodejs_version: "20"
+    - nodejs_version: "18"
+
+platform: x64
+
+install:
+  - ps: Install-Product node $env:nodejs_version x64
+  - node --version
+  - npm --version
+  - npm ci
+
+test_script:
+  - npm run typecheck
+  - npm run test:node:unit
+
+build: off

doc/api.md

@@ -218,7 +218,7 @@ Emits `message` when a message arrives.
 | [options.polling] | <code>Boolean</code> \| <code>Object</code> | <code>false</code> | Set true to enable polling or set options.  If a WebHook has been set, it will be deleted automatically. |
 | [options.polling.timeout] | <code>String</code> \| <code>Number</code> | <code>10</code> | *Deprecated. Use `options.polling.params` instead*.  Timeout in seconds for long polling. |
 | [options.testEnvironment] | <code>Boolean</code> | <code>false</code> | Set true to  work with test enviroment. When working with the test environment, you may use HTTP links without TLS to test your Web App. |
-| [options.polling.interval] | <code>String</code> \| <code>Number</code> | <code>300</code> | Interval between requests in miliseconds |
+| [options.polling.interval] | <code>String</code> \| <code>Number</code> | <code>300</code> | Interval between requests in milliseconds |
 | [options.polling.autoStart] | <code>Boolean</code> | <code>true</code> | Start polling immediately |
 | [options.polling.params] | <code>Object</code> |  | Parameters to be used in polling API requests.  See https://core.telegram.org/bots/api#getupdates for more information. |
 | [options.polling.params.timeout] | <code>Number</code> | <code>10</code> | Timeout in seconds for long polling. |