v2: runtime-agnostic TypeScript rewrite

[yagop]

Draft WPI

• Design & rationale: redesign/ARCHITECTURE.md.
• Migrating from v1: redesign/MIGRATION.md.
• Readme: README.md.

[yagop]

Code review against master (merge base 827d89d). Full suite of unit tests, typecheck, lint:core, and check:edge all pass locally. Below are the actionable findings; the rest of the rewrite looks solid.

Findings

[P2] Context.chat / Context.from miss several Update variants — src/core/context.ts:69-104

The chat getter handles 9 of the 16+ variants that actually carry a chat, omitting business_message, edited_business_message, deleted_business_messages, guest_message, message_reaction_count, chat_boost, and removed_chat_boost (all generated types with a chat field). The from getter has analogous gaps (business_connection.user, business_message, managed_bot.user, etc.). The result is that bot.on("business_message", ctx => ctx.reply(...)) (and similar) will throw "ctx.reply: cannot infer a chat id from this update" for an update that does carry a chat — and the docstring on line 65 enumerates the supported types as if the omission were intentional, hiding the gap.

Strongly recommend a typed resolver table keyed by UpdateType so a new generator variant becomes a compile error here instead of a silent undefined:

const chatOf: {
  [K in UpdateType]: (u: Extract<Update, Record<K, unknown>>) => Chat | undefined;
} = {
  message:                 (u) => u.message.chat,
  business_message:        (u) => u.business_message.chat,
  // ...one row per UpdateType, including explicit () => undefined rows
};

Extract<Update, Record<K, unknown>> narrows each row to its single variant, so wrong field paths are also compile errors. The generator's existing _AssertNever exhaustiveness check on UpdateType makes this watertight.

[P3] Webhook earlyAck silently drops handler errors when no bot.catch() is registered — src/core/webhook.ts:107-110

const work = Promise.resolve(bot.handleUpdate(update)).catch(() => {
  /* swallowed: handleUpdate has its own error boundary */
});

The comment ("handleUpdate has its own error boundary") is only true when the user registered bot.catch(); Bot.handleUpdate (src/core/bot.ts:103-110) rethrows otherwise. In fastAck/waitUntil mode a handler bug becomes invisible — no log, no surfaced error. At minimum the swallow should log() the error, or the comment should state the bot.catch() requirement.

[P3] RateLimiter per-chat buckets are never evicted — src/core/ratelimiter.ts:79-86

if (!bucket) { bucket = new TokenBucket(...); this.chats.set(key, bucket); }

The chats Map grows without bound for the life of the Transport. For a long-lived bot interacting with many distinct chats (support bot, inline mode, etc.) under rateLimit.perChat, this leaks one TokenBucket per unique chat id forever. Consider a TTL/size cap on the map.

[P3] TokenBucket.take can briefly oversell under concurrent takes — src/core/ratelimiter.ts:42-50

When two take() calls both see tokens < 1, both compute the same waitMs() from the same refill(), both await delay(wait), and on resume both call refill() and both decrement — tokens goes to -1. The math self-corrects on the next call (longer wait), but under burst contention the configured rate can be transiently exceeded. If a strict ceiling matters, decrement optimistically before awaiting, or recheck tokens >= 1 after the wait.

[P3] Context.from ignores poll_answer.voter_chat — src/core/context.ts:96

PollAnswer (src/types/schemas.ts:596-602) has both user? and voter_chat?; for anonymous chat votes only voter_chat is set. from returns poll_answer.user unconditionally, so it is undefined for legitimate poll answers. Worth a comment or a fallback so consumers do not assume from is always set when the variant is handled.

Verdict

needs attention — one P2 (the Context getter gaps are a real defect that breaks ctx.reply for several update types the rest of the library explicitly supports), plus a handful of low-severity items.

Human Reviewer Callouts (Non-Blocking)

• This change introduces backwards-incompatible public schema/API/contract changes: Full v2 from-scratch rewrite. No v1 compatibility: no TelegramBot class, no default export, no EventEmitter, single-argument methods, ESM-only, structured fields are plain objects (no JSON.stringify at call sites), bare strings are always file_id/URL (no options.filepath). Migration guide in redesign/MIGRATION.md. The package name is intentionally retained (node-telegram-bot-api v2.0.0-alpha.0).
• This change changes a dependency (or the lockfile): package-lock.json deleted, bun.lock added; toolchain switched to Bun. New devDependencies: @biomejs/biome, @types/node, bun, tsx, typescript. All prior runtime/production dependencies removed (the library is now zero-dep at runtime).
• This change modifies auth/permission behavior: Webhook authentication is via X-Telegram-Bot-Api-Secret-Token constant-time compare in webhookCallback (src/core/webhook.ts); when secretToken is unset, NO authentication is performed on incoming webhooks (documented as a required-in-production setting).
• This change changes configuration defaults: Retry/backoff/timeout defaults introduced (maxRetries: 2, retryBackoffMs: 300, timeoutMs: 30_000, maxRetryAfterMs: 60_000); default request body format is now always form-encoded (x-www-form-urlencoded / multipart/form-data); long-poll default timeout: 30, retry: true, maxBackoffMs: 60_000.