@effect-ak/tg-bot 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   BotPollSettingsTag: () => BotPollSettingsTag,
   BotResponse: () => BotResponse,
   BotRunService: () => BotRunService,
+  BotTgClientTag: () => BotTgClientTag,
   BotUpdateHandlersTag: () => BotUpdateHandlersTag,
   HandleUpdateError: () => HandleUpdateError,
   defineBot: () => defineBot,
@@ -3491,11 +3492,12 @@ var runPromise = (effect, options) => runPromiseExit(effect, options).then((exit
 
 // src/internal/handle-update.ts
 var import_tg_bot_client = require("@effect-ak/tg-bot-client");
-var import_tg_bot_client2 = require("@effect-ak/tg-bot-client");
 
 // src/internal/poll-settings.ts
 var BotUpdateHandlersTag = class extends Tag2("BotUpdateHandlers")() {
 };
+var BotTgClientTag = class extends Tag2("BotTgClient")() {
+};
 var BotPollSettings = class _BotPollSettings extends Class2 {
   static make(input) {
     let batch_size = input.batch_size ?? 10;
@@ -3603,17 +3605,24 @@ var handleEntireBatch = (updates, handlers) => try_({
   })
 );
 var HandleUpdateError = class extends TaggedError("HandleUpdateError") {
+  logInfo() {
+    return {
+      updateId: this.update.update_id,
+      updateKey: Object.keys(this.update).at(1),
+      name: this._tag,
+      ...this.cause instanceof Error && { error: this.cause.message }
+    };
+  }
 };
 var handleOneByOne = (updates, handlers, pollSettings) => forEach3(
   updates,
   (update) => handleOneUpdate(update, handlers).pipe(
     catchAll((error) => {
-      console.log("update handle error", {
-        updateId: update.update_id,
-        updateKey: Object.keys(update).at(1),
-        name: error._tag,
-        ...error.cause instanceof Error ? { error: error.cause.message } : void 0
-      });
+      if (error instanceof HandleUpdateError) {
+        console.warn("update handle error", error.logInfo());
+      } else {
+        console.warn("unknown error", error);
+      }
       return succeed(error);
     })
   ),
@@ -3681,17 +3690,12 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
     }),
     catchAll((error) => {
       handleUpdateError = error;
-      console.log("error", {
-        updateId: updateObject.update_id,
-        updateKey: Object.keys(updateObject).at(1),
-        name: error._tag,
-        ...error.cause instanceof Error ? { error: error.cause.message } : void 0
-      });
+      console.warn("error", error.logInfo());
       return succeed(
         BotResponse.make({
           type: "message",
           text: `Some internal error has happend(${error.name}) while handling this message`,
-          message_effect_id: import_tg_bot_client2.MESSAGE_EFFECTS["\u{1F4A9}"],
+          message_effect_id: import_tg_bot_client.MESSAGE_EFFECTS["\u{1F4A9}"],
           ...updateObject.message?.message_id ? {
             reply_parameters: {
               message_id: updateObject.message?.message_id
@@ -3709,13 +3713,15 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
     return;
   }
   if ("chat" in update && handleResult.response) {
-    const response = yield* (0, import_tg_bot_client.executeTgBotMethod)(
-      `send_${handleResult.response.type}`,
-      {
-        ...handleResult.response,
+    const client = yield* service(BotTgClientTag);
+    const responsePayload = handleResult.response;
+    const response = yield* tryPromise({
+      try: () => client.execute(`send_${responsePayload.type}`, {
+        ...responsePayload,
         chat_id: update.chat.id
-      }
-    );
+      }),
+      catch: (error) => error
+    });
     if (pollSettings.log_level == "debug" && "text") {
       console.debug("bot response", response);
     }
@@ -3724,7 +3730,6 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
 });
 
 // src/service/fetch-updates.ts
-var import_tg_bot_client3 = require("@effect-ak/tg-bot-client");
 var BotFetchUpdatesService = class extends Reference2()(
   "BotFetchUpdatesService",
   {
@@ -3755,6 +3760,7 @@ var FetchUpdatesError = class extends TaggedError("FetchUpdatesError") {
 };
 var _fetchUpdates = (pollState) => gen(function* () {
   const pollSettings = yield* service(BotPollSettingsTag);
+  const client = yield* service(BotTgClientTag);
   if (pollSettings.max_empty_responses && pollState.emptyResponses == pollSettings.max_empty_responses) {
     return yield* fail3(
       new FetchUpdatesError({ name: "TooManyEmptyResponses" })
@@ -3764,9 +3770,12 @@ var _fetchUpdates = (pollState) => gen(function* () {
   if (pollSettings.log_level == "debug") {
     console.debug("getting updates", pollState);
   }
-  const updates = yield* (0, import_tg_bot_client3.executeTgBotMethod)("get_updates", {
-    timeout: pollSettings.poll_timeout,
-    ...updateId ? { offset: updateId } : void 0
+  const updates = yield* tryPromise({
+    try: () => client.execute("get_updates", {
+      timeout: pollSettings.poll_timeout,
+      ...updateId ? { offset: updateId } : void 0
+    }),
+    catch: (error) => error
   }).pipe(andThen((_) => _.sort((_2) => _2.update_id)));
   if (updates.length) {
     console.debug(`got a batch of updates (${updates.length})`);
@@ -3780,9 +3789,14 @@ var _fetchUpdates = (pollState) => gen(function* () {
 var _commitLastBatch = (pollState) => gen(function* () {
   console.log("commit", { pollState });
   if (pollState.lastUpdateId) {
-    return yield* (0, import_tg_bot_client3.executeTgBotMethod)("get_updates", {
-      offset: pollState.lastUpdateId,
-      limit: 0
+    const client = yield* service(BotTgClientTag);
+    const offset = pollState.lastUpdateId;
+    return yield* tryPromise({
+      try: () => client.execute("get_updates", {
+        offset,
+        limit: 0
+      }),
+      catch: (error) => error
     }).pipe(
       andThen(
         andThen(service(BotPollSettingsTag), (pollSettings) => {
@@ -3856,21 +3870,22 @@ var _runBotDaemon = (state) => gen(function* () {
 });
 
 // src/internal/launch.ts
-var import_tg_bot_client4 = require("@effect-ak/tg-bot-client");
+var import_tg_bot_client2 = require("@effect-ak/tg-bot-client");
 var launchBot = (input) => gen(function* () {
   const service2 = yield* service(BotRunService);
-  const contextWithToken = make4(import_tg_bot_client4.TgBotApiToken, input.bot_token);
+  const client = (0, import_tg_bot_client2.makeTgBotClient)({ bot_token: input.bot_token });
+  const contextWithClient = make4(BotTgClientTag, client);
   yield* service2.runBotInBackground.pipe(
     provideService(BotUpdateHandlersTag, input.mode),
     provideService(
       BotPollSettingsTag,
       BotPollSettings.make(input.poll ?? {})
     ),
-    provideContext(contextWithToken)
+    provideContext(contextWithClient)
   );
   const reload = (mode) => service2.runBotInBackground.pipe(
     provideService(BotUpdateHandlersTag, mode),
-    provideContext(contextWithToken),
+    provideContext(contextWithClient),
     runPromise
   );
   return {
@@ -3893,6 +3908,7 @@ var defineBot = (input) => {
   BotPollSettingsTag,
   BotResponse,
   BotRunService,
+  BotTgClientTag,
   BotUpdateHandlersTag,
   HandleUpdateError,
   defineBot,

package/dist/index.d.ts

@@ -1,11 +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 _effect_ak_tg_bot_client from '@effect-ak/tg-bot-client';
-import { TgBotClientError } from '@effect-ak/tg-bot-client';
 import * as Micro from 'effect/Micro';
 import * as Data from 'effect/Data';
 import * as Context from 'effect/Context';
+import { TgBotClient } from '@effect-ak/tg-bot-client';
 
 type BotResult = {
     [K in keyof Api]: K extends `send_${infer R}` ? {
@@ -25,6 +24,9 @@ declare class BotResponse extends BotResponse_base<{
 declare const BotUpdateHandlersTag_base: Context.TagClass<BotUpdateHandlersTag, "BotUpdateHandlers", BotMode>;
 declare class BotUpdateHandlersTag extends BotUpdateHandlersTag_base {
 }
+declare const BotTgClientTag_base: Context.TagClass<BotTgClientTag, "BotTgClient", TgBotClient>;
+declare class BotTgClientTag extends BotTgClientTag_base {
+}
 interface PollSettings {
     log_level: "info" | "debug";
     on_error: "stop" | "continue";
@@ -69,7 +71,7 @@ declare class BatchUpdateResult extends Data.Class<{
     updates: Update[];
 }> {
 }
-declare const handleUpdates: (updates: Update[]) => Micro.Micro<BatchUpdateResult, never, BotUpdateHandlersTag | _effect_ak_tg_bot_client.TgBotApiToken>;
+declare const handleUpdates: (updates: Update[]) => Micro.Micro<BatchUpdateResult, never, BotUpdateHandlersTag | BotTgClientTag>;
 declare const handleEntireBatch: (updates: Update[], handlers: HandleBatchUpdateFunction) => Micro.Micro<BatchUpdateResult, never, never>;
 declare const HandleUpdateError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
     readonly _tag: "HandleUpdateError";
@@ -79,35 +81,33 @@ declare class HandleUpdateError extends HandleUpdateError_base<{
     update: Update;
     cause?: unknown;
 }> {
+    logInfo(): {
+        error?: string;
+        updateId: number;
+        updateKey: string | undefined;
+        name: "HandleUpdateError";
+    };
 }
-declare const handleOneByOne: (updates: Update[], handlers: BotUpdatesHandlers, pollSettings: PollSettings) => Micro.Micro<BatchUpdateResult, never, _effect_ak_tg_bot_client.TgBotApiToken>;
-declare const handleOneUpdate: (updateObject: Update, handlers: BotUpdatesHandlers) => Micro.Micro<HandleUpdateError | undefined, HandleUpdateError | _effect_ak_tg_bot_client.TgBotClientError, _effect_ak_tg_bot_client.TgBotApiToken>;
-
-declare const FetchUpdatesError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "FetchUpdatesError";
-} & Readonly<A>;
-declare class FetchUpdatesError extends FetchUpdatesError_base<{
-    name: "TooManyEmptyResponses" | "NoUpdatesToCommit";
-}> {
-}
+declare const handleOneByOne: (updates: Update[], handlers: BotUpdatesHandlers, pollSettings: PollSettings) => Micro.Micro<BatchUpdateResult, never, BotTgClientTag>;
+declare const handleOneUpdate: (updateObject: Update, handlers: BotUpdatesHandlers) => Micro.Micro<HandleUpdateError | undefined, unknown, BotTgClientTag>;
 
 type BotInstance = Micro.Micro.Success<ReturnType<typeof launchBot>>;
 declare const launchBot: (input: RunBotInput) => Micro.Micro<{
     readonly reload: (mode: BotMode) => Promise<void>;
-    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, _effect_ak_tg_bot_client.TgBotClientError | FetchUpdatesError> | undefined;
+    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
 }, never, never>;
 
 declare const BotRunService_base: Context.ReferenceClass<BotRunService, "BotRunService", {
-    readonly runBotInBackground: Micro.Micro<void, never, BotUpdateHandlersTag | _effect_ak_tg_bot_client.TgBotApiToken>;
-    readonly getFiber: () => Micro.MicroFiber<BatchUpdateResult, TgBotClientError | FetchUpdatesError> | undefined;
+    readonly runBotInBackground: Micro.Micro<void, never, BotUpdateHandlersTag | BotTgClientTag>;
+    readonly getFiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
 }>;
 declare class BotRunService extends BotRunService_base {
 }
 
 declare const runTgChatBot: (input: RunBotInput) => Promise<{
     readonly reload: (mode: BotMode) => Promise<void>;
-    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, _effect_ak_tg_bot_client.TgBotClientError | FetchUpdatesError> | undefined;
+    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
 }>;
 declare const defineBot: (input: BotUpdatesHandlers) => BotUpdatesHandlers;
 
-export { type AvailableUpdateTypes, BatchUpdateResult, type BotBatchMode, type BotInstance, type BotMode, BotPollSettings, BotPollSettingsTag, BotResponse, BotRunService, type BotSingleMode, 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 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 };

package/dist/index.js

@@ -3450,12 +3450,13 @@ var runPromise = (effect, options) => runPromiseExit(effect, options).then((exit
 });
 
 // src/internal/handle-update.ts
-import { executeTgBotMethod } from "@effect-ak/tg-bot-client";
 import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client";
 
 // src/internal/poll-settings.ts
 var BotUpdateHandlersTag = class extends Tag2("BotUpdateHandlers")() {
 };
+var BotTgClientTag = class extends Tag2("BotTgClient")() {
+};
 var BotPollSettings = class _BotPollSettings extends Class2 {
   static make(input) {
     let batch_size = input.batch_size ?? 10;
@@ -3563,17 +3564,24 @@ var handleEntireBatch = (updates, handlers) => try_({
   })
 );
 var HandleUpdateError = class extends TaggedError("HandleUpdateError") {
+  logInfo() {
+    return {
+      updateId: this.update.update_id,
+      updateKey: Object.keys(this.update).at(1),
+      name: this._tag,
+      ...this.cause instanceof Error && { error: this.cause.message }
+    };
+  }
 };
 var handleOneByOne = (updates, handlers, pollSettings) => forEach3(
   updates,
   (update) => handleOneUpdate(update, handlers).pipe(
     catchAll((error) => {
-      console.log("update handle error", {
-        updateId: update.update_id,
-        updateKey: Object.keys(update).at(1),
-        name: error._tag,
-        ...error.cause instanceof Error ? { error: error.cause.message } : void 0
-      });
+      if (error instanceof HandleUpdateError) {
+        console.warn("update handle error", error.logInfo());
+      } else {
+        console.warn("unknown error", error);
+      }
       return succeed(error);
     })
   ),
@@ -3641,12 +3649,7 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
     }),
     catchAll((error) => {
       handleUpdateError = error;
-      console.log("error", {
-        updateId: updateObject.update_id,
-        updateKey: Object.keys(updateObject).at(1),
-        name: error._tag,
-        ...error.cause instanceof Error ? { error: error.cause.message } : void 0
-      });
+      console.warn("error", error.logInfo());
       return succeed(
         BotResponse.make({
           type: "message",
@@ -3669,13 +3672,15 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
     return;
   }
   if ("chat" in update && handleResult.response) {
-    const response = yield* executeTgBotMethod(
-      `send_${handleResult.response.type}`,
-      {
-        ...handleResult.response,
+    const client = yield* service(BotTgClientTag);
+    const responsePayload = handleResult.response;
+    const response = yield* tryPromise({
+      try: () => client.execute(`send_${responsePayload.type}`, {
+        ...responsePayload,
         chat_id: update.chat.id
-      }
-    );
+      }),
+      catch: (error) => error
+    });
     if (pollSettings.log_level == "debug" && "text") {
       console.debug("bot response", response);
     }
@@ -3684,7 +3689,6 @@ var handleOneUpdate = (updateObject, handlers) => gen(function* () {
 });
 
 // src/service/fetch-updates.ts
-import { executeTgBotMethod as executeTgBotMethod2 } from "@effect-ak/tg-bot-client";
 var BotFetchUpdatesService = class extends Reference2()(
   "BotFetchUpdatesService",
   {
@@ -3715,6 +3719,7 @@ var FetchUpdatesError = class extends TaggedError("FetchUpdatesError") {
 };
 var _fetchUpdates = (pollState) => gen(function* () {
   const pollSettings = yield* service(BotPollSettingsTag);
+  const client = yield* service(BotTgClientTag);
   if (pollSettings.max_empty_responses && pollState.emptyResponses == pollSettings.max_empty_responses) {
     return yield* fail3(
       new FetchUpdatesError({ name: "TooManyEmptyResponses" })
@@ -3724,9 +3729,12 @@ var _fetchUpdates = (pollState) => gen(function* () {
   if (pollSettings.log_level == "debug") {
     console.debug("getting updates", pollState);
   }
-  const updates = yield* executeTgBotMethod2("get_updates", {
-    timeout: pollSettings.poll_timeout,
-    ...updateId ? { offset: updateId } : void 0
+  const updates = yield* tryPromise({
+    try: () => client.execute("get_updates", {
+      timeout: pollSettings.poll_timeout,
+      ...updateId ? { offset: updateId } : void 0
+    }),
+    catch: (error) => error
   }).pipe(andThen((_) => _.sort((_2) => _2.update_id)));
   if (updates.length) {
     console.debug(`got a batch of updates (${updates.length})`);
@@ -3740,9 +3748,14 @@ var _fetchUpdates = (pollState) => gen(function* () {
 var _commitLastBatch = (pollState) => gen(function* () {
   console.log("commit", { pollState });
   if (pollState.lastUpdateId) {
-    return yield* executeTgBotMethod2("get_updates", {
-      offset: pollState.lastUpdateId,
-      limit: 0
+    const client = yield* service(BotTgClientTag);
+    const offset = pollState.lastUpdateId;
+    return yield* tryPromise({
+      try: () => client.execute("get_updates", {
+        offset,
+        limit: 0
+      }),
+      catch: (error) => error
     }).pipe(
       andThen(
         andThen(service(BotPollSettingsTag), (pollSettings) => {
@@ -3816,21 +3829,22 @@ var _runBotDaemon = (state) => gen(function* () {
 });
 
 // src/internal/launch.ts
-import { TgBotApiToken } from "@effect-ak/tg-bot-client";
+import { makeTgBotClient } from "@effect-ak/tg-bot-client";
 var launchBot = (input) => gen(function* () {
   const service2 = yield* service(BotRunService);
-  const contextWithToken = make4(TgBotApiToken, input.bot_token);
+  const client = makeTgBotClient({ bot_token: input.bot_token });
+  const contextWithClient = make4(BotTgClientTag, client);
   yield* service2.runBotInBackground.pipe(
     provideService(BotUpdateHandlersTag, input.mode),
     provideService(
       BotPollSettingsTag,
       BotPollSettings.make(input.poll ?? {})
     ),
-    provideContext(contextWithToken)
+    provideContext(contextWithClient)
   );
   const reload = (mode) => service2.runBotInBackground.pipe(
     provideService(BotUpdateHandlersTag, mode),
-    provideContext(contextWithToken),
+    provideContext(contextWithClient),
     runPromise
   );
   return {
@@ -3852,6 +3866,7 @@ export {
   BotPollSettingsTag,
   BotResponse,
   BotRunService,
+  BotTgClientTag,
   BotUpdateHandlersTag,
   HandleUpdateError,
   defineBot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-ak/tg-bot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Telegram Bot runner",
   "license": "MIT",
@@ -34,9 +34,12 @@
     "dist/*.d.ts"
   ],
   "dependencies": {
-    "@effect-ak/tg-bot-client": "1.0.0",
+    "@effect-ak/tg-bot-client": "^1.1.0",
     "@effect-ak/tg-bot-api": "0.9.2"
   },
+  "peerDependencies": {
+    "effect": "^3.12.7"
+  },
   "scripts": {
     "build": "tsup"
   }

package/readme.md

@@ -0,0 +1,500 @@
+# @effect-ak/tg-bot
+
+[![NPM Version](https://img.shields.io/npm/v/%40effect-ak%2Ftg-bot)](https://www.npmjs.com/package/@effect-ak/tg-bot)
+![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot?link=)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Effect-based Telegram bot runner that handles long polling, update processing, and error management automatically.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Single Mode](#single-mode)
+  - [Batch Mode](#batch-mode)
+  - [Bot Response](#bot-response)
+- [Usage Examples](#usage-examples)
+  - [Echo Bot](#echo-bot)
+  - [Command Handler](#command-handler)
+  - [Batch Processing](#batch-processing)
+  - [Using Effect](#using-effectjs)
+  - [Hot Reload](#hot-reload)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [How It Works](#how-it-works)
+- [Error Handling](#error-handling)
+- [Playground](#playground)
+- [Related Packages](#related-packages)
+- [License](#license)
+
+## Features
+
+- **Effect-based**: Built on top of [Effect](https://effect.website/) for powerful functional programming patterns
+- **Two Processing Modes**: Handle updates one-by-one or in batches
+- **Automatic Long Polling**: Manages connection to Telegram servers
+- **Type-Safe Handlers**: Full TypeScript support for all update types
+- **Error Recovery**: Configurable error handling strategies
+- **Concurrent Processing**: Process multiple updates in parallel (up to 10 concurrent handlers)
+- **Hot Reload**: Reload bot handlers without restarting
+- **Built-in Logging**: Configurable logging levels
+- **No Public URL Required**: Uses pull model - run bots anywhere, even in a browser
+
+## Installation
+
+```bash
+npm install @effect-ak/tg-bot effect
+```
+
+```bash
+pnpm add @effect-ak/tg-bot effect
+```
+
+```bash
+yarn add @effect-ak/tg-bot effect
+```
+
+**Note:** `effect` is a peer dependency and must be installed separately.
+
+## Quick Start
+
+```typescript
+import { runTgChatBot, BotResponse } 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}`
+      })
+    }
+  }
+})
+```
+
+## Core Concepts
+
+### Single Mode
+
+In single mode, the bot processes each update individually with a dedicated handler for each update type.
+
+**Available Handlers:**
+- `on_message` - New incoming message
+- `on_edited_message` - Message was edited
+- `on_channel_post` - New channel post
+- `on_edited_channel_post` - Channel post was edited
+- `on_inline_query` - Inline query
+- `on_chosen_inline_result` - Chosen inline result
+- `on_callback_query` - Callback query from inline keyboard
+- `on_shipping_query` - Shipping query
+- `on_pre_checkout_query` - Pre-checkout query
+- `on_poll` - Poll state update
+- `on_poll_answer` - User changed their answer in a poll
+- `on_my_chat_member` - Bot's chat member status changed
+- `on_chat_member` - Chat member status changed
+- `on_chat_join_request` - Request to join chat
+
+### Batch Mode
+
+In batch mode, the bot receives all updates as an array and processes them together.
+
+```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
+    }
+  }
+})
+```
+
+### Bot Response
+
+Handlers return a `BotResponse` object that describes what to send back to the user.
+
+**Creating Responses:**
+
+```typescript
+import { BotResponse } from "@effect-ak/tg-bot"
+
+// Send a message
+BotResponse.make({
+  type: "message",
+  text: "Hello!"
+})
+
+// Send a photo
+BotResponse.make({
+  type: "photo",
+  photo: {
+    file_content: photoBuffer,
+    file_name: "image.jpg"
+  },
+  caption: "Check this out!"
+})
+
+// Ignore update (don't send anything)
+BotResponse.ignore
+```
+
+**Supported Response Types:**
+All Telegram `send_*` methods are supported: `message`, `photo`, `document`, `video`, `audio`, `voice`, `sticker`, `dice`, etc.
+
+## Usage Examples
+
+### Echo Bot
+
+```typescript
+import { runTgChatBot, BotResponse, 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
+      }
+    })
+  }
+})
+
+runTgChatBot({
+  bot_token: "YOUR_BOT_TOKEN",
+  mode: {
+    type: "single",
+    ...ECHO_BOT
+  }
+})
+```
+
+### Command Handler
+
+```typescript
+import { runTgChatBot, BotResponse } 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
+      }
+    }
+  }
+})
+```
+
+### Batch Processing
+
+```typescript
+import { runTgChatBot } from "@effect-ak/tg-bot"
+import { makeTgBotClient } from "@effect-ak/tg-bot-client"
+
+const client = makeTgBotClient({ bot_token: "YOUR_BOT_TOKEN" })
+
+runTgChatBot({
+  bot_token: "YOUR_BOT_TOKEN",
+  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`
+      })
+
+      return true // Continue polling
+    }
+  }
+})
+```
+
+### Using Effect
+
+Advanced usage with Effect for composable async operations:
+
+```typescript
+import { Effect, Micro, pipe } from "effect"
+import { BotResponse, launchBot } from "@effect-ak/tg-bot"
+
+Effect.gen(function* () {
+  const bot = yield* launchBot({
+    bot_token: "YOUR_BOT_TOKEN",
+    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
+        )
+      }
+    }
+  })
+
+  // Access bot fiber for control
+  yield* pipe(
+    Micro.fiberAwait(bot.fiber()!),
+    Effect.andThen(Effect.logInfo("Bot stopped")),
+    Effect.forkDaemon
+  )
+}).pipe(Effect.runPromise)
+```
+
+### Hot Reload
+
+```typescript
+import { Effect } from "effect"
+import { launchBot, BotResponse } 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"
+      })
+    }
+  })
+
+  // Later, reload with new handlers
+  await bot.reload({
+    type: "single",
+    on_message: (msg) => BotResponse.make({
+      type: "message",
+      text: "Version 2 - Hot reloaded!"
+    })
+  })
+}).pipe(Effect.runPromise)
+```
+
+## Configuration
+
+### Poll Settings
+
+Configure how the bot polls for updates:
+
+```typescript
+runTgChatBot({
+  bot_token: "YOUR_BOT_TOKEN",
+  poll: {
+    log_level: "debug",        // "info" | "debug"
+    on_error: "continue",      // "stop" | "continue"
+    batch_size: 50,            // 10-100
+    poll_timeout: 30,          // 2-120 seconds
+    max_empty_responses: 5     // Stop after N empty responses
+  },
+  mode: { /* ... */ }
+})
+```
+
+**Options:**
+
+- `log_level` (default: `"info"`): Logging verbosity
+  - `"info"` - Basic logging (new messages, errors)
+  - `"debug"` - Detailed logging (all updates, responses)
+
+- `on_error` (default: `"stop"`): Error handling strategy
+  - `"stop"` - Stop bot on error
+  - `"continue"` - Continue polling after errors
+
+- `batch_size` (default: `10`): Number of updates to fetch per poll (10-100)
+
+- `poll_timeout` (default: `10`): Long polling timeout in seconds (2-120)
+
+- `max_empty_responses` (default: `undefined`): Stop after N consecutive empty responses (useful for testing)
+
+## API Reference
+
+### `runTgChatBot(input)`
+
+Starts the bot with long polling.
+
+**Parameters:**
+- `bot_token` (string, required): Bot token from @BotFather
+- `mode` (object, required): Bot mode configuration (single or batch)
+- `poll` (object, optional): Polling configuration
+
+**Returns:** `Promise<void>`
+
+### `launchBot(input)`
+
+Launches bot and returns a bot instance for advanced control.
+
+**Returns:** `Micro<BotInstance>`
+- `BotInstance.reload(mode)` - Hot reload handlers
+- `BotInstance.fiber()` - Access underlying Effect fiber
+
+### `defineBot(handlers)`
+
+Helper to define bot handlers with type checking and validation.
+
+**Parameters:**
+- `handlers` (object): Handler functions for different update types
+
+**Returns:** `BotUpdatesHandlers`
+
+### `BotResponse.make(response)`
+
+Creates a bot response.
+
+**Parameters:**
+- `response` (object): Response configuration with `type` and parameters
+
+**Returns:** `BotResponse`
+
+### `BotResponse.ignore`
+
+Singleton instance for ignoring updates (no response).
+
+## How It Works
+
+### Pull Model Architecture
+
+The Telegram bot API supports both **push** and **pull** notification models. This package uses the **pull** model for several key advantages:
+
+- **Run bots anywhere without public URLs:** No need to expose public ports or configure webhooks. You can run bots locally, in a browser, or behind firewalls.
+- **Leverage Telegram's infrastructure:** Telegram stores updates for 24 hours, giving you plenty of time to process them.
+- **Simpler deployment:** No SSL certificates, no webhook configuration, no reverse proxies required.
+
+### Architecture Diagram
+
+```mermaid
+graph TD
+  User[User] -->|Sends message| TgBot[Telegram Bot]
+  TgBot -->|Stores for 24h| Queue[Updates Queue<br/>api.telegram.org/bot/updates]
+
+  subgraph Your Code
+    Runner[Bot Runner<br/>@effect-ak/tg-bot]
+    Handler[Your Handler Function]
+  end
+
+  Runner -->|Long polling| Queue
+  Runner -->|Invokes with update| Handler
+  Handler -->|Returns BotResponse| Runner
+  Runner -->|Sends response| TgBot
+```
+
+**How it works:**
+1. User sends a message to your bot
+2. Telegram stores the update in a queue for 24 hours
+3. Bot runner polls the queue using long polling
+4. Runner invokes your handler function with the update
+5. Handler returns a `BotResponse`
+6. Runner sends the response back to Telegram
+7. Runner tracks the last processed update ID to avoid duplicates
+
+## Error Handling
+
+The bot automatically handles errors at different levels:
+
+### Update Handler Errors
+
+If a handler throws an error, the bot:
+1. Logs the error with update details
+2. Sends an error message to the user (in single mode)
+3. Continues processing other updates (if `on_error: "continue"`)
+
+```typescript
+on_message: (msg) => {
+  if (msg.text === "/error") {
+    throw new Error("Something went wrong!")
+  }
+  // Bot will catch this and send error message to user
+  return BotResponse.make({ type: "message", text: "OK" })
+}
+```
+
+### Batch Handler Errors
+
+In batch mode, returning `false` stops the bot:
+
+```typescript
+on_batch: async (updates) => {
+  try {
+    // Process updates
+    return true // Continue
+  } catch (error) {
+    console.error(error)
+    return false // Stop bot
+  }
+}
+```
+
+### Concurrent Processing
+
+In single mode, up to 10 updates are processed concurrently. If some handlers fail, others continue processing.
+
+## Playground
+
+Develop and test your bot directly in the browser:
+
+**[Chat Bot Playground](https://effect-ak.github.io/telegram-bot-playground/)**
+
+No installation required - perfect for quick prototyping and learning!
+
+## Related Packages
+
+This package is part of the `tg-bot-client` monorepo:
+
+- **[@effect-ak/tg-bot-client](../client)** - Type-safe HTTP client for Telegram Bot API
+- **[@effect-ak/tg-bot-api](../api)** - TypeScript types for Telegram Bot API and Mini Apps
+- **[@effect-ak/tg-bot-codegen](../codegen)** - Code generator that parses official documentation
+
+## License
+
+MIT © [Aleksandr Kondaurov](https://github.com/effect-ak)