@effect-ak/tg-bot-client 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,294 @@
+# @effect-ak/tg-bot-client
+
+[![NPM Version](https://img.shields.io/npm/v/%40effect-ak%2Ftg-bot-client)](https://www.npmjs.com/package/@effect-ak/tg-bot-client)
+![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40effect-ak%2Ftg-bot-client?link=)
+![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot-client?link=)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Type-safe HTTP client for Telegram Bot API with complete TypeScript support.
+
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+  - [Sending Messages](#sending-messages)
+  - [Sending Files](#sending-files)
+  - [Downloading Files](#downloading-files)
+  - [Using Message Effects](#using-message-effects)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Configuration](#configuration)
+- [Related Packages](#related-packages)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Motivation
+
+**Telegram** does not offer an official TypeScript **SDK** for their **API** but they provide documentation in HTML format.
+
+This package provides a lightweight, type-safe HTTP client that uses types generated from the [official Telegram Bot API documentation](https://core.telegram.org/bots/api), ensuring it stays in sync with the latest API updates.
+
+## Features
+
+- **Type-Safe**: Full TypeScript support with types generated from official documentation
+- **Lightweight**: Minimal dependencies
+- **Complete API Coverage**: All Bot API methods are supported
+- **Smart Type Conversion**: Automatic mapping of Telegram types to TypeScript:
+  - `Integer` → `number`
+  - `True` → `boolean`
+  - `String or Number` → `string | number`
+  - Enumerated types → Union of literal types (e.g., `"private" | "group" | "supergroup" | "channel"`)
+- **File Handling**: Simplified file upload and download
+- **Message Effects**: Built-in constants for message effects
+- **Custom Base URL**: Support for custom Telegram Bot API servers
+
+## Installation
+
+```bash
+npm install @effect-ak/tg-bot-client
+```
+
+```bash
+pnpm add @effect-ak/tg-bot-client
+```
+
+```bash
+yarn add @effect-ak/tg-bot-client
+```
+
+## Quick Start
+
+```typescript
+import { makeTgBotClient } from "@effect-ak/tg-bot-client"
+
+const client = makeTgBotClient({
+  bot_token: "YOUR_BOT_TOKEN" // Token from @BotFather
+})
+
+// Send a message
+await client.execute("send_message", {
+  chat_id: "123456789",
+  text: "Hello, World!"
+})
+```
+
+## Usage Examples
+
+### Sending Messages
+
+#### Basic Text Message
+
+```typescript
+await client.execute("send_message", {
+  chat_id: "123456789",
+  text: "Hello from TypeScript!"
+})
+```
+
+#### Message with Formatting
+
+```typescript
+await client.execute("send_message", {
+  chat_id: "123456789",
+  text: "*Bold* _italic_ `code`",
+  parse_mode: "Markdown"
+})
+```
+
+#### Message with Inline Keyboard
+
+```typescript
+await client.execute("send_message", {
+  chat_id: "123456789",
+  text: "Choose an option:",
+  reply_markup: {
+    inline_keyboard: [
+      [
+        { text: "Option 1", callback_data: "opt_1" },
+        { text: "Option 2", callback_data: "opt_2" }
+      ]
+    ]
+  }
+})
+```
+
+### Sending Files
+
+#### Sending a Dice
+
+```typescript
+await client.execute("send_dice", {
+  chat_id: "123456789",
+  emoji: "🎲"
+})
+```
+
+#### Sending a Document
+
+```typescript
+await client.execute("send_document", {
+  chat_id: "123456789",
+  document: {
+    file_content: new TextEncoder().encode("Hello from file!"),
+    file_name: "hello.txt"
+  },
+  caption: "Simple text file"
+})
+```
+
+#### Sending a Photo
+
+```typescript
+await client.execute("send_photo", {
+  chat_id: "123456789",
+  photo: {
+    file_content: photoBuffer,
+    file_name: "image.jpg"
+  },
+  caption: "Check out this photo!"
+})
+```
+
+### Downloading Files
+
+To download a file from Telegram servers, use the `getFile` method. It handles both the API call and file download in one step:
+
+```typescript
+// Get file by file_id (from a message, for example)
+const file = await client.getFile({
+  file_id: "AgACAgIAAxkBAAI..."
+})
+
+// file is a standard File object
+console.log(file.name) // filename.jpg
+console.log(file.size) // file size in bytes
+
+// Read file contents
+const arrayBuffer = await file.arrayBuffer()
+const text = await file.text()
+const blob = await file.blob()
+```
+
+### Using Message Effects
+
+The library includes built-in constants for message effects:
+
+```typescript
+import { MESSAGE_EFFECTS } from "@effect-ak/tg-bot-client"
+
+await client.execute("send_message", {
+  chat_id: "123456789",
+  text: "Message with fire effect!",
+  message_effect_id: MESSAGE_EFFECTS["🔥"]
+})
+```
+
+Available effects:
+- `MESSAGE_EFFECTS["🔥"]` - Fire
+- `MESSAGE_EFFECTS["👍"]` - Thumbs up
+- `MESSAGE_EFFECTS["👎"]` - Thumbs down
+- `MESSAGE_EFFECTS["❤️"]` - Heart
+- `MESSAGE_EFFECTS["🎉"]` - Party
+- `MESSAGE_EFFECTS["💩"]` - Poop
+
+## Error Handling
+
+The client throws `TgBotClientError` for all errors:
+
+```typescript
+import { TgBotClientError } from "@effect-ak/tg-bot-client"
+
+try {
+  await client.execute("send_message", {
+    chat_id: "invalid",
+    text: "Test"
+  })
+} catch (error) {
+  if (error instanceof TgBotClientError) {
+    console.error("Error type:", error.cause._tag)
+
+    switch (error.cause._tag) {
+      case "NotOkResponse":
+        console.error("API error:", error.cause.errorCode, error.cause.details)
+        break
+      case "UnexpectedResponse":
+        console.error("Unexpected response:", error.cause.response)
+        break
+      case "ClientInternalError":
+        console.error("Internal error:", error.cause.cause)
+        break
+      case "UnableToGetFile":
+        console.error("File download error:", error.cause.cause)
+        break
+      case "NotJsonResponse":
+        console.error("Invalid JSON response:", error.cause.response)
+        break
+    }
+  }
+}
+```
+
+## API Reference
+
+### `makeTgBotClient(config)`
+
+Creates a new Telegram Bot API client.
+
+**Parameters:**
+- `config.bot_token` (string, required): Your bot token from @BotFather
+- `config.base_url` (string, optional): Custom API base URL (default: `https://api.telegram.org`)
+
+**Returns:** `TgBotClient`
+
+### `client.execute(method, input)`
+
+Executes a Telegram Bot API method.
+
+**Parameters:**
+- `method` (string): API method name in snake_case (e.g., `"send_message"`, `"get_updates"`)
+- `input` (object): Method parameters as defined in Telegram Bot API
+
+**Returns:** `Promise<ApiResponse>` - Typed response based on the method
+
+**Note:** Method names use snake_case (e.g., `send_message`) instead of camelCase for better readability and consistency with the Telegram API documentation.
+
+### `client.getFile(input)`
+
+Downloads a file from Telegram servers.
+
+**Parameters:**
+- `input.file_id` (string): File identifier from a message
+
+**Returns:** `Promise<File>` - Standard [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object
+
+## Configuration
+
+### Custom Base URL
+
+If you're running your own Telegram Bot API server:
+
+```typescript
+const client = makeTgBotClient({
+  bot_token: "YOUR_BOT_TOKEN",
+  base_url: "https://your-custom-server.com"
+})
+```
+
+## Related Packages
+
+This package is part of the `tg-bot-client` monorepo:
+
+- **[@effect-ak/tg-bot-api](../api)** - TypeScript types for Telegram Bot API and Mini Apps
+- **[@effect-ak/tg-bot](../bot)** - Effect-based bot runner for building Telegram bots
+- **[@effect-ak/tg-bot-codegen](../codegen)** - Code generator that parses official documentation
+
+## Contributing
+
+Contributions are welcome! Please check out the [issues](https://github.com/effect-ak/tg-bot-client/issues) or submit a pull request.
+
+## License
+
+MIT © [Aleksandr Kondaurov](https://github.com/effect-ak)

package/dist/index.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,52 +15,42 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  ClientFileService: () => ClientFileService,
   MESSAGE_EFFECTS: () => MESSAGE_EFFECTS,
   TG_BOT_API_URL: () => TG_BOT_API_URL,
-  TgBotApiBaseUrl: () => TgBotApiBaseUrl,
-  TgBotApiToken: () => TgBotApiToken,
   TgBotClientError: () => TgBotClientError,
   executeTgBotMethod: () => executeTgBotMethod,
+  getBaseUrl: () => getBaseUrl,
+  getFile: () => getFile,
+  getFileBytes: () => getFileBytes,
   isFileContent: () => isFileContent,
   isMessageEffect: () => isMessageEffect,
   isTgBotApiResponse: () => isTgBotApiResponse,
-  isTgBotApiUpdate: () => isTgBotApiUpdate,
   makePayload: () => makePayload,
   makeTgBotClient: () => makeTgBotClient,
-  messageEffectIdCodes: () => messageEffectIdCodes
+  messageEffectIdCodes: () => messageEffectIdCodes,
+  snakeToCamel: () => snakeToCamel
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/execute.ts
-var String = __toESM(require("effect/String"), 1);
-var Micro = __toESM(require("effect/Micro"), 1);
-
 // src/errors.ts
-var Data = __toESM(require("effect/Data"), 1);
-var TgBotClientError = class extends Data.TaggedError("TgBotClientError") {
+var TgBotClientError = class extends Error {
+  _tag = "TgBotClientError";
+  cause;
+  constructor(options) {
+    super(`TgBotClientError: ${options.cause._tag}`);
+    this.cause = options.cause;
+    this.name = "TgBotClientError";
+  }
 };
 
 // src/guards.ts
 var isFileContent = (input) => typeof input == "object" && input != null && "file_content" in input && input.file_content instanceof Uint8Array && "file_name" in input && typeof input.file_name == "string";
 var isTgBotApiResponse = (input) => typeof input == "object" && input != null && "ok" in input && typeof input.ok == "boolean";
-var isTgBotApiUpdate = (input) => typeof input == "object" && input != null && "update_id" in input && typeof input.update_id == "number";
-
-// src/config.ts
-var Context = __toESM(require("effect/Context"), 1);
 
 // src/const.ts
 var TG_BOT_API_URL = "https://api.telegram.org";
@@ -82,53 +70,58 @@ var isMessageEffect = (input) => {
 };
 
 // src/config.ts
-var TgBotApiBaseUrl = class extends Context.Reference()(
-  "TgBotApiBaseUrl",
-  { defaultValue: () => TG_BOT_API_URL }
-) {
+var getBaseUrl = (config) => {
+  return config?.baseUrl ?? TG_BOT_API_URL;
 };
-var TgBotApiToken = class extends Context.Tag("TgBotApiToken")() {
+
+// src/utils.ts
+var snakeToCamel = (str) => {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
 };
 
 // src/execute.ts
-var executeTgBotMethod = (method, input) => Micro.gen(function* () {
-  const botToken = yield* Micro.service(TgBotApiToken);
-  const baseUrl = yield* Micro.service(TgBotApiBaseUrl);
-  const httpResponse = yield* Micro.tryPromise({
-    try: () => fetch(`${baseUrl}/bot${botToken}/${String.snakeToCamel(method)}`, {
-      body: makePayload(input) ?? null,
-      method: "POST"
-    }),
-    catch: (cause) => new TgBotClientError({
+async function executeTgBotMethod(params) {
+  const { config, method, input } = params;
+  const baseUrl = getBaseUrl(config);
+  const botToken = config.botToken;
+  let httpResponse;
+  try {
+    httpResponse = await fetch(
+      `${baseUrl}/bot${botToken}/${snakeToCamel(method)}`,
+      {
+        body: makePayload(input) ?? null,
+        method: "POST"
+      }
+    );
+  } catch (cause) {
+    throw new TgBotClientError({
       cause: { _tag: "ClientInternalError", cause }
-    })
-  });
-  const response = yield* Micro.tryPromise({
-    try: () => httpResponse.json(),
-    catch: () => new TgBotClientError({
+    });
+  }
+  let response;
+  try {
+    response = await httpResponse.json();
+  } catch {
+    throw new TgBotClientError({
       cause: { _tag: "NotJsonResponse", response: httpResponse }
-    })
-  });
+    });
+  }
   if (!isTgBotApiResponse(response)) {
-    return yield* Micro.fail(
-      new TgBotClientError({
-        cause: { _tag: "UnexpectedResponse", response }
-      })
-    );
+    throw new TgBotClientError({
+      cause: { _tag: "UnexpectedResponse", response }
+    });
   }
   if (!httpResponse.ok) {
-    return yield* Micro.fail(
-      new TgBotClientError({
-        cause: {
-          _tag: "NotOkResponse",
-          ...response.error_code ? { errorCode: response.error_code } : void 0,
-          ...response.description ? { details: response.description } : void 0
-        }
-      })
-    );
+    throw new TgBotClientError({
+      cause: {
+        _tag: "NotOkResponse",
+        ...response.error_code ? { errorCode: response.error_code } : {},
+        ...response.description ? { details: response.description } : {}
+      }
+    });
   }
   return response.result;
-});
+}
 var makePayload = (body) => {
   const entries = Object.entries(body);
   if (entries.length == 0) return void 0;
@@ -147,84 +140,70 @@ var makePayload = (body) => {
 };
 
 // src/client-file.ts
-var Micro2 = __toESM(require("effect/Micro"), 1);
-var Context2 = __toESM(require("effect/Context"), 1);
-var ClientFileService = class _ClientFileService extends Context2.Tag("ClientFileService")() {
-  static live = () => {
-    return _ClientFileService.context({
-      getFile
-    });
-  };
-};
-var getFile = ({ fileId, type }) => getFileBytes(fileId).pipe(
-  Micro2.andThen(
-    ({ content, file_name }) => new File([content], file_name, {
-      ...type ? { type } : void 0
-    })
-  )
-);
-var getFileBytes = (fileId) => Micro2.gen(function* () {
-  const response = yield* executeTgBotMethod("get_file", { file_id: fileId });
+var getFileBytes = async (fileId, context) => {
+  const { config, execute } = context;
+  const response = await execute("get_file", { file_id: fileId });
   const file_path = response.file_path;
-  if (!file_path || file_path.length == 0) {
-    return yield* Micro2.fail(
-      new TgBotClientError({
-        cause: {
-          _tag: "UnableToGetFile",
-          cause: "File path not defined"
-        }
-      })
-    );
+  if (!file_path || file_path.length === 0) {
+    throw new TgBotClientError({
+      cause: {
+        _tag: "UnableToGetFile",
+        cause: "File path not defined"
+      }
+    });
   }
   const file_name = file_path.replaceAll("/", "-");
-  const baseUrl = yield* Micro2.service(TgBotApiBaseUrl);
-  const botToken = yield* Micro2.service(TgBotApiToken);
+  const baseUrl = getBaseUrl(config);
+  const botToken = config.botToken;
   const url = `${baseUrl}/file/bot${botToken}/${file_path}`;
-  const content = yield* Micro2.tryPromise({
-    try: () => fetch(url).then((_) => _.arrayBuffer()),
-    catch: (cause) => new TgBotClientError({
+  let content;
+  try {
+    content = await fetch(url).then((_) => _.arrayBuffer());
+  } catch (cause) {
+    throw new TgBotClientError({
       cause: { _tag: "UnableToGetFile", cause }
-    })
-  });
+    });
+  }
+  const base64String = () => Buffer.from(content).toString("base64");
   return {
     content,
-    file_name
+    file_name,
+    base64String
   };
-});
+};
+var getFile = async (input, context) => {
+  const { content, file_name } = await getFileBytes(input.fileId, context);
+  return new File([content], file_name, {
+    ...input.type ? { type: input.type } : {}
+  });
+};
 
 // src/client.ts
-var Micro3 = __toESM(require("effect/Micro"), 1);
-var Context3 = __toESM(require("effect/Context"), 1);
 function makeTgBotClient(config) {
-  return createEffect(config).pipe(Micro3.runSync);
-}
-var createEffect = ({ bot_token }) => Micro3.gen(function* () {
-  const file = yield* Micro3.service(ClientFileService);
-  const context = Context3.make(TgBotApiToken, bot_token);
-  const execute = (method, input) => executeTgBotMethod(method, input).pipe(
-    Micro3.provideContext(context),
-    Micro3.runPromise
-  );
-  const getFile2 = (input) => file.getFile(input).pipe(Micro3.provideContext(context), Micro3.runPromise);
+  const tgConfig = {
+    botToken: config.bot_token,
+    ...config.base_url ? { baseUrl: config.base_url } : {}
+  };
+  const execute = (method, input) => executeTgBotMethod({ config: tgConfig, method, input });
   return {
     execute,
-    getFile: getFile2
+    getFile: (input) => getFile(input, { config: tgConfig, execute })
   };
-}).pipe(Micro3.provideContext(ClientFileService.live()));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ClientFileService,
   MESSAGE_EFFECTS,
   TG_BOT_API_URL,
-  TgBotApiBaseUrl,
-  TgBotApiToken,
   TgBotClientError,
   executeTgBotMethod,
+  getBaseUrl,
+  getFile,
+  getFileBytes,
   isFileContent,
   isMessageEffect,
   isTgBotApiResponse,
-  isTgBotApiUpdate,
   makePayload,
   makeTgBotClient,
-  messageEffectIdCodes
+  messageEffectIdCodes,
+  snakeToCamel
 });