@effect-ak/tg-bot 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   BotTgClientTag: () => BotTgClientTag,
   BotUpdateHandlersTag: () => BotUpdateHandlersTag,
   HandleUpdateError: () => HandleUpdateError,
+  createBotContext: () => createBotContext,
   defineBot: () => defineBot,
   extractUpdate: () => extractUpdate,
   handleEntireBatch: () => handleEntireBatch,
@@ -2656,6 +2657,26 @@ var BotResponse = class _BotResponse extends TaggedClass("BotResponse") {
   static ignore = new _BotResponse({});
 };
 
+// src/internal/bot-context.ts
+var extractCommand = (update) => {
+  if (typeof update !== "object" || update === null) return void 0;
+  const u = update;
+  if (!u.entities || !u.text) return void 0;
+  const entity = u.entities.find((e) => e.type === "bot_command");
+  if (!entity) return void 0;
+  return u.text.slice(entity.offset, entity.offset + entity.length);
+};
+var createBotContext = (update) => {
+  const command = extractCommand(update);
+  return {
+    command,
+    reply: (text, options) => BotResponse.make({ type: "message", text, ...options }),
+    replyWithDocument: (document, options) => BotResponse.make({ type: "document", document, ...options }),
+    replyWithPhoto: (photo, options) => BotResponse.make({ type: "photo", photo, ...options }),
+    ignore: BotResponse.ignore
+  };
+};
+
 // ../../node_modules/.pnpm/effect@3.12.0/node_modules/effect/dist/esm/Effectable.js
 var EffectPrototype2 = EffectPrototype;
 
@@ -3547,6 +3568,36 @@ var BotPollSettingsTag = class extends Reference2()(
 };
 
 // src/internal/handle-update.ts
+var isGuardedHandler = (handler) => typeof handler === "object" && handler !== null && "handle" in handler;
+var executeSingleGuard = async (guard, update, ctx) => {
+  const input = { update, ctx };
+  if (guard.match) {
+    const matched = await guard.match(input);
+    if (!matched) return null;
+  }
+  return await guard.handle(input);
+};
+var executeGuards = async (guards, update, ctx) => {
+  for (const guard of guards) {
+    const result = await executeSingleGuard(guard, update, ctx);
+    if (result !== null) return result;
+  }
+  return BotResponse.ignore;
+};
+var executeHandler = (handler, update, ctx) => {
+  if (typeof handler === "function") {
+    return handler(update);
+  }
+  if (Array.isArray(handler)) {
+    return executeGuards(handler, update, ctx);
+  }
+  if (isGuardedHandler(handler)) {
+    return executeSingleGuard(handler, update, ctx).then(
+      (r) => r ?? BotResponse.ignore
+    );
+  }
+  return BotResponse.ignore;
+};
 var extractUpdate = (input) => {
   for (const [field, value] of Object.entries(input)) {
     if (field == "update_id") {
@@ -3650,8 +3701,8 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
       })
     );
   }
-  const updateHandler = handlers[`on_${update.type}`];
-  if (!updateHandler) {
+  const handler = handlers[`on_${update.type}`];
+  if (!handler) {
     return yield* fail3(
       new HandleUpdateError({
         name: "HandlerNotDefined",
@@ -3666,9 +3717,10 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
       message: `${update.text.slice(0, 5)}...`
     });
   }
+  const ctx = createBotContext(update);
   let handleUpdateError;
   const handleResult = yield* try_({
-    try: () => updateHandler(update),
+    try: () => executeHandler(handler, update, ctx),
     catch: (error) => new HandleUpdateError({
       name: "BotHandlerError",
       update: updateObject,
@@ -3871,20 +3923,28 @@ var _runBotDaemon = (state) => gen(function* () {
 
 // src/internal/launch.ts
 var import_tg_bot_client2 = require("@effect-ak/tg-bot-client");
+var extractMode = (input) => {
+  if (input.mode === "batch") {
+    return { type: "batch", on_batch: input.on_batch };
+  }
+  const { bot_token, mode, poll, ...handlers } = input;
+  return { type: "single", ...handlers };
+};
 var launchBot = (input) => gen(function* () {
   const service2 = yield* service(BotRunService);
   const client = (0, import_tg_bot_client2.makeTgBotClient)({ bot_token: input.bot_token });
   const contextWithClient = make4(BotTgClientTag, client);
+  const mode = extractMode(input);
   yield* service2.runBotInBackground.pipe(
-    provideService(BotUpdateHandlersTag, input.mode),
+    provideService(BotUpdateHandlersTag, mode),
     provideService(
       BotPollSettingsTag,
       BotPollSettings.make(input.poll ?? {})
     ),
     provideContext(contextWithClient)
   );
-  const reload = (mode) => service2.runBotInBackground.pipe(
-    provideService(BotUpdateHandlersTag, mode),
+  const reload = (mode2) => service2.runBotInBackground.pipe(
+    provideService(BotUpdateHandlersTag, mode2),
     provideContext(contextWithClient),
     runPromise
   );
@@ -3911,6 +3971,7 @@ var defineBot = (input) => {
   BotTgClientTag,
   BotUpdateHandlersTag,
   HandleUpdateError,
+  createBotContext,
   defineBot,
   extractUpdate,
   handleEntireBatch,

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as effect_Types from 'effect/Types';
 import { Api, Update } from '@effect-ak/tg-bot-api';
-import * as effect_Cause from 'effect/Cause';
-import * as Micro from 'effect/Micro';
-import * as Data from 'effect/Data';
 import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
 import { TgBotClient } from '@effect-ak/tg-bot-client';
+import * as effect_Cause from 'effect/Cause';
+import * as Micro from 'effect/Micro';
 
 type BotResult = {
     [K in keyof Api]: K extends `send_${infer R}` ? {
@@ -41,9 +41,15 @@ declare const BotPollSettingsTag_base: Context.ReferenceClass<BotPollSettings, "
 declare class BotPollSettingsTag extends BotPollSettingsTag_base {
 }
 
-interface RunBotInput {
+type RunBotInput = RunBotInputSingle | RunBotInputBatch;
+interface RunBotInputSingle extends BotUpdatesHandlers {
+    bot_token: string;
+    mode: "single";
+    poll?: Partial<PollSettings>;
+}
+interface RunBotInputBatch extends HandleBatchUpdateFunction {
     bot_token: string;
-    mode: BotMode;
+    mode: "batch";
     poll?: Partial<PollSettings>;
 }
 type ExtractedUpdate<K extends AvailableUpdateTypes> = {
@@ -51,8 +57,27 @@ type ExtractedUpdate<K extends AvailableUpdateTypes> = {
 } & Update[K];
 type AvailableUpdateTypes = Exclude<keyof Update, "update_id">;
 type HandleUpdateFunction<U> = (update: U) => BotResponse | PromiseLike<BotResponse>;
+interface BotContext {
+    readonly command: string | undefined;
+    readonly reply: (text: string, options?: Omit<BotResponseParams<"message">, "text" | "type">) => BotResponse;
+    readonly replyWithDocument: (document: BotResponseParams<"document">["document"], options?: Omit<BotResponseParams<"document">, "document" | "type">) => BotResponse;
+    readonly replyWithPhoto: (photo: BotResponseParams<"photo">["photo"], options?: Omit<BotResponseParams<"photo">, "photo" | "type">) => BotResponse;
+    readonly ignore: BotResponse;
+}
+type BotResponseParams<T extends string> = Extract<Parameters<typeof BotResponse.make>[0], {
+    type: T;
+}>;
+interface HandlerInput<U> {
+    readonly update: U;
+    readonly ctx: BotContext;
+}
+interface GuardedHandler<U> {
+    readonly match?: (input: HandlerInput<U>) => boolean | PromiseLike<boolean>;
+    readonly handle: (input: HandlerInput<U>) => BotResponse | PromiseLike<BotResponse>;
+}
+type UpdateHandler<U> = HandleUpdateFunction<U> | GuardedHandler<U> | GuardedHandler<U>[];
 type BotUpdatesHandlers = {
-    readonly [K in AvailableUpdateTypes as `on_${K}`]?: HandleUpdateFunction<NonNullable<Update[K]>>;
+    [K in AvailableUpdateTypes as `on_${K}`]?: UpdateHandler<NonNullable<Update[K]>>;
 };
 interface HandleBatchUpdateFunction {
     readonly on_batch: (update: Update[]) => boolean | PromiseLike<boolean>;
@@ -65,6 +90,8 @@ interface BotBatchMode extends HandleBatchUpdateFunction {
 }
 type BotMode = BotSingleMode | BotBatchMode;
 
+declare const createBotContext: (update: unknown) => BotContext;
+
 declare const extractUpdate: <U extends AvailableUpdateTypes>(input: Update) => ExtractedUpdate<U> | undefined;
 declare class BatchUpdateResult extends Data.Class<{
     hasErrors: boolean;
@@ -110,4 +137,4 @@ declare const runTgChatBot: (input: RunBotInput) => Promise<{
 }>;
 declare const defineBot: (input: BotUpdatesHandlers) => BotUpdatesHandlers;
 
-export { type AvailableUpdateTypes, BatchUpdateResult, type BotBatchMode, type BotInstance, type BotMode, BotPollSettings, BotPollSettingsTag, BotResponse, BotRunService, type BotSingleMode, BotTgClientTag, BotUpdateHandlersTag, type BotUpdatesHandlers, type ExtractedUpdate, type HandleBatchUpdateFunction, HandleUpdateError, type HandleUpdateFunction, type PollSettings, type RunBotInput, defineBot, extractUpdate, handleEntireBatch, handleOneByOne, handleOneUpdate, handleUpdates, launchBot, runTgChatBot };
+export { type AvailableUpdateTypes, BatchUpdateResult, type BotBatchMode, type BotContext, type BotInstance, type BotMode, BotPollSettings, BotPollSettingsTag, BotResponse, BotRunService, type BotSingleMode, BotTgClientTag, BotUpdateHandlersTag, type BotUpdatesHandlers, type ExtractedUpdate, type GuardedHandler, type HandleBatchUpdateFunction, HandleUpdateError, type HandleUpdateFunction, type HandlerInput, type PollSettings, type RunBotInput, type RunBotInputBatch, type RunBotInputSingle, type UpdateHandler, createBotContext, defineBot, extractUpdate, handleEntireBatch, handleOneByOne, handleOneUpdate, handleUpdates, launchBot, runTgChatBot };

package/dist/index.js

@@ -2615,6 +2615,26 @@ var BotResponse = class _BotResponse extends TaggedClass("BotResponse") {
   static ignore = new _BotResponse({});
 };
 
+// src/internal/bot-context.ts
+var extractCommand = (update) => {
+  if (typeof update !== "object" || update === null) return void 0;
+  const u = update;
+  if (!u.entities || !u.text) return void 0;
+  const entity = u.entities.find((e) => e.type === "bot_command");
+  if (!entity) return void 0;
+  return u.text.slice(entity.offset, entity.offset + entity.length);
+};
+var createBotContext = (update) => {
+  const command = extractCommand(update);
+  return {
+    command,
+    reply: (text, options) => BotResponse.make({ type: "message", text, ...options }),
+    replyWithDocument: (document, options) => BotResponse.make({ type: "document", document, ...options }),
+    replyWithPhoto: (photo, options) => BotResponse.make({ type: "photo", photo, ...options }),
+    ignore: BotResponse.ignore
+  };
+};
+
 // ../../node_modules/.pnpm/effect@3.12.0/node_modules/effect/dist/esm/Effectable.js
 var EffectPrototype2 = EffectPrototype;
 
@@ -3506,6 +3526,36 @@ var BotPollSettingsTag = class extends Reference2()(
 };
 
 // src/internal/handle-update.ts
+var isGuardedHandler = (handler) => typeof handler === "object" && handler !== null && "handle" in handler;
+var executeSingleGuard = async (guard, update, ctx) => {
+  const input = { update, ctx };
+  if (guard.match) {
+    const matched = await guard.match(input);
+    if (!matched) return null;
+  }
+  return await guard.handle(input);
+};
+var executeGuards = async (guards, update, ctx) => {
+  for (const guard of guards) {
+    const result = await executeSingleGuard(guard, update, ctx);
+    if (result !== null) return result;
+  }
+  return BotResponse.ignore;
+};
+var executeHandler = (handler, update, ctx) => {
+  if (typeof handler === "function") {
+    return handler(update);
+  }
+  if (Array.isArray(handler)) {
+    return executeGuards(handler, update, ctx);
+  }
+  if (isGuardedHandler(handler)) {
+    return executeSingleGuard(handler, update, ctx).then(
+      (r) => r ?? BotResponse.ignore
+    );
+  }
+  return BotResponse.ignore;
+};
 var extractUpdate = (input) => {
   for (const [field, value] of Object.entries(input)) {
     if (field == "update_id") {
@@ -3609,8 +3659,8 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
       })
     );
   }
-  const updateHandler = handlers[`on_${update.type}`];
-  if (!updateHandler) {
+  const handler = handlers[`on_${update.type}`];
+  if (!handler) {
     return yield* fail3(
       new HandleUpdateError({
         name: "HandlerNotDefined",
@@ -3625,9 +3675,10 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
       message: `${update.text.slice(0, 5)}...`
     });
   }
+  const ctx = createBotContext(update);
   let handleUpdateError;
   const handleResult = yield* try_({
-    try: () => updateHandler(update),
+    try: () => executeHandler(handler, update, ctx),
     catch: (error) => new HandleUpdateError({
       name: "BotHandlerError",
       update: updateObject,
@@ -3830,20 +3881,28 @@ var _runBotDaemon = (state) => gen(function* () {
 
 // src/internal/launch.ts
 import { makeTgBotClient } from "@effect-ak/tg-bot-client";
+var extractMode = (input) => {
+  if (input.mode === "batch") {
+    return { type: "batch", on_batch: input.on_batch };
+  }
+  const { bot_token, mode, poll, ...handlers } = input;
+  return { type: "single", ...handlers };
+};
 var launchBot = (input) => gen(function* () {
   const service2 = yield* service(BotRunService);
   const client = makeTgBotClient({ bot_token: input.bot_token });
   const contextWithClient = make4(BotTgClientTag, client);
+  const mode = extractMode(input);
   yield* service2.runBotInBackground.pipe(
-    provideService(BotUpdateHandlersTag, input.mode),
+    provideService(BotUpdateHandlersTag, mode),
     provideService(
       BotPollSettingsTag,
       BotPollSettings.make(input.poll ?? {})
     ),
     provideContext(contextWithClient)
   );
-  const reload = (mode) => service2.runBotInBackground.pipe(
-    provideService(BotUpdateHandlersTag, mode),
+  const reload = (mode2) => service2.runBotInBackground.pipe(
+    provideService(BotUpdateHandlersTag, mode2),
     provideContext(contextWithClient),
     runPromise
   );
@@ -3869,6 +3928,7 @@ export {
   BotTgClientTag,
   BotUpdateHandlersTag,
   HandleUpdateError,
+  createBotContext,
   defineBot,
   extractUpdate,
   handleEntireBatch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-ak/tg-bot",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Telegram Bot runner",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "effect": "^3.12.7"
   },
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "typecheck": "tsc"
   }
 }

package/readme.md

@@ -60,21 +60,17 @@ yarn add @effect-ak/tg-bot effect
 ## Quick Start
 
 ```typescript
-import { runTgChatBot, BotResponse } from "@effect-ak/tg-bot"
+import { runTgChatBot } from "@effect-ak/tg-bot"
 
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
-  mode: {
-    type: "single",
-    on_message: (message) => {
-      if (!message.text) return BotResponse.ignore
-
-      return BotResponse.make({
-        type: "message",
-        text: `You said: ${message.text}`
-      })
+  mode: "single",
+  on_message: [
+    {
+      match: ({ update }) => !!update.text,
+      handle: ({ update, ctx }) => ctx.reply(`You said: ${update.text}`)
     }
-  }
+  ]
 })
 ```
 
@@ -84,6 +80,31 @@ runTgChatBot({
 
 In single mode, the bot processes each update individually with a dedicated handler for each update type.
 
+**Handler Format (v2 with guards):**
+
+```typescript
+on_message: [
+  {
+    match: ({ update, ctx }) => ctx.command === "/start",  // optional filter
+    handle: ({ update, ctx }) => ctx.reply("Welcome!")     // handler
+  },
+  {
+    match: ({ update }) => !!update.text,
+    handle: ({ ctx }) => ctx.reply("Got your message!")
+  },
+  {
+    handle: ({ ctx }) => ctx.ignore  // fallback (no match = always runs)
+  }
+]
+```
+
+**Context helpers:**
+- `ctx.reply(text, options?)` - Send a message
+- `ctx.replyWithDocument(document, options?)` - Send a document
+- `ctx.replyWithPhoto(photo, options?)` - Send a photo
+- `ctx.command` - Parsed command (e.g., "/start", "/help")
+- `ctx.ignore` - Skip response
+
 **Available Handlers:**
 - `on_message` - New incoming message
 - `on_edited_message` - Message was edited
@@ -100,6 +121,15 @@ In single mode, the bot processes each update individually with a dedicated hand
 - `on_chat_member` - Chat member status changed
 - `on_chat_join_request` - Request to join chat
 
+**Legacy format (v1 - still supported):**
+
+```typescript
+on_message: (message) => {
+  if (!message.text) return BotResponse.ignore
+  return BotResponse.make({ type: "message", text: "Hello!" })
+}
+```
+
 ### Batch Mode
 
 In batch mode, the bot receives all updates as an array and processes them together.
@@ -107,13 +137,11 @@ In batch mode, the bot receives all updates as an array and processes them toget
 ```typescript
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
-  mode: {
-    type: "batch",
-    on_batch: async (updates) => {
-      console.log(`Processing ${updates.length} updates`)
-      // Process updates...
-      return true // Continue polling
-    }
+  mode: "batch",
+  on_batch: async (updates) => {
+    console.log(`Processing ${updates.length} updates`)
+    // Process updates...
+    return true // Continue polling
   }
 })
 ```
@@ -155,66 +183,45 @@ All Telegram `send_*` methods are supported: `message`, `photo`, `document`, `vi
 ### Echo Bot
 
 ```typescript
-import { runTgChatBot, BotResponse, defineBot } from "@effect-ak/tg-bot"
+import { runTgChatBot, defineBot } from "@effect-ak/tg-bot"
 
 const ECHO_BOT = defineBot({
-  on_message: (message) => {
-    if (!message.text) return BotResponse.ignore
-
-    return BotResponse.make({
-      type: "message",
-      text: message.text,
-      reply_parameters: {
-        message_id: message.message_id
-      }
-    })
-  }
+  on_message: [
+    {
+      match: ({ update }) => !!update.text,
+      handle: ({ update, ctx }) => ctx.reply(update.text!)
+    }
+  ]
 })
 
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
-  mode: {
-    type: "single",
-    ...ECHO_BOT
-  }
+  mode: "single",
+  ...ECHO_BOT
 })
 ```
 
 ### Command Handler
 
 ```typescript
-import { runTgChatBot, BotResponse } from "@effect-ak/tg-bot"
+import { runTgChatBot } from "@effect-ak/tg-bot"
 import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client"
 
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
-  mode: {
-    type: "single",
-    on_message: (msg) => {
-      const command = msg.entities?.find(e => e.type === "bot_command")
-      const commandText = command
-        ? msg.text?.slice(command.offset, command.length)
-        : undefined
-
-      switch (commandText) {
-        case "/start":
-          return BotResponse.make({
-            type: "message",
-            text: "Welcome! Send me any message.",
-            message_effect_id: MESSAGE_EFFECTS["🎉"]
-          })
-
-        case "/help":
-          return BotResponse.make({
-            type: "message",
-            text: "Available commands:\n/start - Start bot\n/help - Show help"
-          })
-
-        default:
-          return BotResponse.ignore
-      }
+  mode: "single",
+  on_message: [
+    {
+      match: ({ ctx }) => ctx.command === "/start",
+      handle: ({ ctx }) => ctx.reply("Welcome! Send me any message.", {
+        message_effect_id: MESSAGE_EFFECTS["🎉"]
+      })
+    },
+    {
+      match: ({ ctx }) => ctx.command === "/help",
+      handle: ({ ctx }) => ctx.reply("Available commands:\n/start - Start bot\n/help - Show help")
     }
-  }
+  ]
 })
 ```
 
@@ -228,24 +235,22 @@ const client = makeTgBotClient({ bot_token: "YOUR_BOT_TOKEN" })
 
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
+  mode: "batch",
   poll: {
     batch_size: 100,
     poll_timeout: 60
   },
-  mode: {
-    type: "batch",
-    on_batch: async (updates) => {
-      const messages = updates
-        .map(u => u.message)
-        .filter(m => m != null)
-
-      await client.execute("send_message", {
-        chat_id: "ADMIN_CHAT_ID",
-        text: `Processed ${messages.length} messages`
-      })
+  on_batch: async (updates) => {
+    const messages = updates
+      .map(u => u.message)
+      .filter(m => m != null)
+
+    await client.execute("send_message", {
+      chat_id: "ADMIN_CHAT_ID",
+      text: `Processed ${messages.length} messages`
+    })
 
-      return true // Continue polling
-    }
+    return true // Continue polling
   }
 })
 ```
@@ -256,32 +261,24 @@ Advanced usage with Effect for composable async operations:
 
 ```typescript
 import { Effect, Micro, pipe } from "effect"
-import { BotResponse, launchBot } from "@effect-ak/tg-bot"
+import { launchBot } from "@effect-ak/tg-bot"
 
 Effect.gen(function* () {
   const bot = yield* launchBot({
     bot_token: "YOUR_BOT_TOKEN",
+    mode: "single",
     poll: {
       log_level: "debug"
     },
-    mode: {
-      type: "single",
-      on_message: (message) => {
-        if (!message.text) return BotResponse.ignore
-
-        // Use Effect for async operations
-        return pipe(
-          Effect.sleep("2 seconds"),
-          Effect.andThen(() =>
-            BotResponse.make({
-              type: "message",
-              text: "Delayed response!"
-            })
-          ),
-          Effect.runPromise
-        )
+    on_message: [
+      {
+        match: ({ update }) => !!update.text,
+        handle: async ({ ctx }) => {
+          await Effect.sleep("2 seconds").pipe(Effect.runPromise)
+          return ctx.reply("Delayed response!")
+        }
       }
-    }
+    ]
   })
 
   // Access bot fiber for control
@@ -296,30 +293,31 @@ Effect.gen(function* () {
 ### Hot Reload
 
 ```typescript
-import { Effect } from "effect"
-import { launchBot, BotResponse } from "@effect-ak/tg-bot"
+import { runTgChatBot } from "@effect-ak/tg-bot"
 
-Effect.gen(function* () {
-  const bot = yield* launchBot({
-    bot_token: "YOUR_BOT_TOKEN",
-    mode: {
-      type: "single",
-      on_message: (msg) => BotResponse.make({
-        type: "message",
-        text: "Version 1"
-      })
+const bot = await runTgChatBot({
+  bot_token: "YOUR_BOT_TOKEN",
+  mode: "single",
+  on_message: [
+    {
+      match: ({ update }) => !!update.text,
+      handle: ({ ctx }) => ctx.reply("Version 1")
     }
-  })
+  ]
+})
 
-  // Later, reload with new handlers
-  await bot.reload({
+// Later, reload with new handlers
+setTimeout(() => {
+  bot.reload({
     type: "single",
-    on_message: (msg) => BotResponse.make({
-      type: "message",
-      text: "Version 2 - Hot reloaded!"
-    })
+    on_message: [
+      {
+        match: ({ update }) => !!update.text,
+        handle: ({ ctx }) => ctx.reply("Version 2 - Hot reloaded!")
+      }
+    ]
   })
-}).pipe(Effect.runPromise)
+}, 5000)
 ```
 
 ## Configuration
@@ -331,6 +329,7 @@ Configure how the bot polls for updates:
 ```typescript
 runTgChatBot({
   bot_token: "YOUR_BOT_TOKEN",
+  mode: "single",  // or "batch"
   poll: {
     log_level: "debug",        // "info" | "debug"
     on_error: "continue",      // "stop" | "continue"
@@ -338,7 +337,7 @@ runTgChatBot({
     poll_timeout: 30,          // 2-120 seconds
     max_empty_responses: 5     // Stop after N empty responses
   },
-  mode: { /* ... */ }
+  on_message: [/* ... */]  // handlers at top level
 })
 ```
 
@@ -366,10 +365,12 @@ Starts the bot with long polling.
 
 **Parameters:**
 - `bot_token` (string, required): Bot token from @BotFather
-- `mode` (object, required): Bot mode configuration (single or batch)
+- `mode` (`"single"` | `"batch"`, required): Processing mode
 - `poll` (object, optional): Polling configuration
+- `on_message`, `on_callback_query`, etc. (optional): Update handlers (for single mode)
+- `on_batch` (required for batch mode): Batch handler function
 
-**Returns:** `Promise<void>`
+**Returns:** `Promise<BotInstance>`
 
 ### `launchBot(input)`
 
@@ -450,13 +451,19 @@ If a handler throws an error, the bot:
 3. Continues processing other updates (if `on_error: "continue"`)
 
 ```typescript
-on_message: (msg) => {
-  if (msg.text === "/error") {
-    throw new Error("Something went wrong!")
+on_message: [
+  {
+    match: ({ ctx }) => ctx.command === "/error",
+    handle: () => {
+      throw new Error("Something went wrong!")
+      // Bot will catch this and send error message to user
+    }
+  },
+  {
+    match: ({ update }) => !!update.text,
+    handle: ({ ctx }) => ctx.reply("OK")
   }
-  // Bot will catch this and send error message to user
-  return BotResponse.make({ type: "message", text: "OK" })
-}
+]
 ```
 
 ### Batch Handler Errors