@effect-ak/tg-bot-client 0.6.4 → 1.1.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

@@ -0,0 +1,209 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MESSAGE_EFFECTS: () => MESSAGE_EFFECTS,
+  TG_BOT_API_URL: () => TG_BOT_API_URL,
+  TgBotClientError: () => TgBotClientError,
+  executeTgBotMethod: () => executeTgBotMethod,
+  getBaseUrl: () => getBaseUrl,
+  getFile: () => getFile,
+  getFileBytes: () => getFileBytes,
+  isFileContent: () => isFileContent,
+  isMessageEffect: () => isMessageEffect,
+  isTgBotApiResponse: () => isTgBotApiResponse,
+  makePayload: () => makePayload,
+  makeTgBotClient: () => makeTgBotClient,
+  messageEffectIdCodes: () => messageEffectIdCodes,
+  snakeToCamel: () => snakeToCamel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+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";
+
+// src/const.ts
+var TG_BOT_API_URL = "https://api.telegram.org";
+var MESSAGE_EFFECTS = {
+  "\u{1F525}": "5104841245755180586",
+  "\u{1F44D}": "5107584321108051014",
+  "\u{1F44E}": "5104858069142078462",
+  "\u2764\uFE0F": "5159385139981059251",
+  "\u{1F389}": "5046509860389126442",
+  "\u{1F4A9}": "5046589136895476101"
+};
+var messageEffectIdCodes = Object.keys(
+  MESSAGE_EFFECTS
+);
+var isMessageEffect = (input) => {
+  return typeof input === "string" && input in MESSAGE_EFFECTS;
+};
+
+// src/config.ts
+var getBaseUrl = (config) => {
+  return config?.baseUrl ?? TG_BOT_API_URL;
+};
+
+// src/utils.ts
+var snakeToCamel = (str) => {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+};
+
+// src/execute.ts
+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 }
+    });
+  }
+  let response;
+  try {
+    response = await httpResponse.json();
+  } catch {
+    throw new TgBotClientError({
+      cause: { _tag: "NotJsonResponse", response: httpResponse }
+    });
+  }
+  if (!isTgBotApiResponse(response)) {
+    throw new TgBotClientError({
+      cause: { _tag: "UnexpectedResponse", response }
+    });
+  }
+  if (!httpResponse.ok) {
+    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;
+  const result = new FormData();
+  for (const [key, value] of entries) {
+    if (!value) continue;
+    if (typeof value != "object") {
+      result.append(key, `${value}`);
+    } else if (isFileContent(value)) {
+      result.append(key, new Blob([value.file_content]), value.file_name);
+    } else {
+      result.append(key, JSON.stringify(value));
+    }
+  }
+  return result;
+};
+
+// src/client-file.ts
+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) {
+    throw new TgBotClientError({
+      cause: {
+        _tag: "UnableToGetFile",
+        cause: "File path not defined"
+      }
+    });
+  }
+  const file_name = file_path.replaceAll("/", "-");
+  const baseUrl = getBaseUrl(config);
+  const botToken = config.botToken;
+  const url = `${baseUrl}/file/bot${botToken}/${file_path}`;
+  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,
+    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
+function makeTgBotClient(config) {
+  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: (input) => getFile(input, { config: tgConfig, execute })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MESSAGE_EFFECTS,
+  TG_BOT_API_URL,
+  TgBotClientError,
+  executeTgBotMethod,
+  getBaseUrl,
+  getFile,
+  getFileBytes,
+  isFileContent,
+  isMessageEffect,
+  isTgBotApiResponse,
+  makePayload,
+  makeTgBotClient,
+  messageEffectIdCodes,
+  snakeToCamel
+});

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+import { Api } from '@effect-ak/tg-bot-api';
+
+interface TgBotConfig {
+    botToken: string;
+    baseUrl?: string;
+}
+declare const getBaseUrl: (config?: Pick<TgBotConfig, "baseUrl">) => string;
+
+declare function executeTgBotMethod<M extends keyof Api>(params: {
+    config: TgBotConfig;
+    method: M;
+    input: Parameters<Api[M]>[0];
+}): Promise<ReturnType<Api[M]>>;
+declare const makePayload: (body: object) => FormData | undefined;
+
+interface GetFile {
+    fileId: string;
+    type?: string;
+}
+interface FileBytes {
+    content: ArrayBuffer;
+    file_name: string;
+    base64String: () => string;
+}
+interface FileContext {
+    config: TgBotConfig;
+    execute: <M extends keyof Api>(method: M, input: Parameters<Api[M]>[0]) => Promise<ReturnType<Api[M]>>;
+}
+declare const getFileBytes: (fileId: string, context: FileContext) => Promise<FileBytes>;
+declare const getFile: (input: GetFile, context: FileContext) => Promise<File>;
+
+interface TgBotClient {
+    readonly execute: <M extends keyof Api>(method: M, input: Parameters<Api[M]>[0]) => Promise<ReturnType<Api[M]>>;
+    readonly getFile: (input: GetFile) => Promise<File>;
+}
+interface MakeTgClient {
+    bot_token: string;
+    base_url?: string;
+}
+declare function makeTgBotClient(config: MakeTgClient): TgBotClient;
+
+type ErrorReason = {
+    _tag: "NotOkResponse";
+    errorCode?: number;
+    details?: string;
+} | {
+    _tag: "UnexpectedResponse";
+    response: unknown;
+} | {
+    _tag: "ClientInternalError";
+    cause: unknown;
+} | {
+    _tag: "UnableToGetFile";
+    cause: unknown;
+} | {
+    _tag: "BotHandlerError";
+    cause: unknown;
+} | {
+    _tag: "NotJsonResponse";
+    response: unknown;
+};
+declare class TgBotClientError extends Error {
+    readonly _tag = "TgBotClientError";
+    readonly cause: ErrorReason;
+    constructor(options: {
+        cause: ErrorReason;
+    });
+}
+
+interface FileContent {
+    file_content: Uint8Array<ArrayBuffer>;
+    file_name: string;
+}
+declare const isFileContent: (input: unknown) => input is FileContent;
+interface TgBotApiResponseSchema {
+    ok: boolean;
+    error_code?: number;
+    description?: string;
+    result?: unknown;
+}
+declare const isTgBotApiResponse: (input: unknown) => input is TgBotApiResponseSchema;
+
+declare const TG_BOT_API_URL = "https://api.telegram.org";
+declare const MESSAGE_EFFECTS: {
+    readonly "\uD83D\uDD25": "5104841245755180586";
+    readonly "\uD83D\uDC4D": "5107584321108051014";
+    readonly "\uD83D\uDC4E": "5104858069142078462";
+    readonly "\u2764\uFE0F": "5159385139981059251";
+    readonly "\uD83C\uDF89": "5046509860389126442";
+    readonly "\uD83D\uDCA9": "5046589136895476101";
+};
+type MessageEffect = keyof typeof MESSAGE_EFFECTS;
+declare const messageEffectIdCodes: MessageEffect[];
+declare const isMessageEffect: (input: unknown) => input is MessageEffect;
+
+declare const snakeToCamel: (str: string) => string;
+
+export { type FileBytes, type FileContent, type GetFile, MESSAGE_EFFECTS, type MakeTgClient, type MessageEffect, TG_BOT_API_URL, type TgBotApiResponseSchema, type TgBotClient, TgBotClientError, type TgBotConfig, executeTgBotMethod, getBaseUrl, getFile, getFileBytes, isFileContent, isMessageEffect, isTgBotApiResponse, makePayload, makeTgBotClient, messageEffectIdCodes, snakeToCamel };