@effect-ak/tg-bot-client 1.3.4 → 1.4.1

package/package.json

@@ -2,20 +2,25 @@
   "name": "@effect-ak/tg-bot-client",
   "type": "module",
   "description": "Type-safe HTTP client for Telegram Bot API",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "license": "MIT",
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "telegram-bot-api",
+    "http-client",
+    "typescript"
+  ],
   "author": {
     "name": "Aleksandr Kondaurov",
     "email": "kondaurov.dev@gmail.com"
   },
+  "homepage": "https://tg-bot-sdk.website",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kondaurovDev/tg-bot-client",
+    "url": "https://github.com/kondaurovDev/tg-bot-sdk",
     "directory": "packages/client"
   },
-  "bugs": {
-    "url": "https://github.com/effect-ak/tg-bot-client/issues"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -27,10 +32,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./dist/*": "./dist/*"
   },
   "dependencies": {
-    "@effect-ak/tg-bot-api": "^1.3.0"
+    "@effect-ak/tg-bot-api": "^1.3.1"
   },
   "scripts": {
     "build": "tsup",

package/readme.md

@@ -1,294 +1,43 @@
 # @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)
+![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot-client)
 
 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
+  bot_token: "YOUR_BOT_TOKEN"
 })
 
-// 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:
+## Features
 
-- **[@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
+- **Type-Safe** — full TypeScript support with types from official documentation
+- **Lightweight** — minimal dependencies
+- **Complete API Coverage** — all Bot API methods supported
+- **File Handling** — simplified upload and download
+- **Message Effects** — built-in constants
 
-## Contributing
+## Documentation
 
-Contributions are welcome! Please check out the [issues](https://github.com/effect-ak/tg-bot-client/issues) or submit a pull request.
+Full documentation, usage examples, and error handling: **[tg-bot-sdk.website](https://tg-bot-sdk.website)**
 
 ## License
 
-MIT © [Aleksandr Kondaurov](https://github.com/effect-ak)
+MIT

package/src/client.ts

@@ -1,35 +1,75 @@
-import type { Api } from "@effect-ak/tg-bot-api"
-import { executeTgBotMethod, type ExecuteMethod } from "./execute"
-import { getFile as getFileImpl, type TgFile } from "./client-file"
-import { TG_BOT_API_URL } from "./const"
+import { executeTgBotMethod, type ExecuteMethod, type ClientResult } from "./execute"
 
-export interface TgBotClient {
-  readonly config: Required<TgClientConfig>
-  readonly execute: ExecuteMethod
-  readonly getFile: (input: { fileId: string; type?: string }) => Promise<TgFile>
-}
+const TG_BOT_API_URL = "https://api.telegram.org"
 
 export interface TgClientConfig {
   bot_token: string
   base_url?: string
 }
 
+export interface TgFile {
+  readonly content: ArrayBuffer
+  readonly file_name: string
+  readonly base64String: () => string
+  readonly file: () => File
+}
+
+export interface TgBotClient {
+  readonly config: Required<TgClientConfig>
+  readonly execute: ExecuteMethod
+  readonly getFile: (input: { fileId: string; type?: string }) => Promise<ClientResult<TgFile>>
+}
+
 export function makeTgBotClient(config: TgClientConfig): TgBotClient {
   const tgConfig = {
     bot_token: config.bot_token,
     base_url: config.base_url ?? TG_BOT_API_URL
   }
 
-  const execute = <M extends keyof Api>(
-    method: M,
-    input: Parameters<Api[M]>[0]
-  ) => executeTgBotMethod({
-    config: tgConfig, method, input
-  })
+  const execute: ExecuteMethod = (method, input) =>
+    executeTgBotMethod({
+      config: tgConfig, method, input: input as any
+    })
+
+  const getFile = async (params: { fileId: string; type?: string }): Promise<ClientResult<TgFile>> => {
+    const response = await execute("get_file", { file_id: params.fileId })
+
+    if (!response.ok) return response
+
+    const file_path = response.data.file_path
+
+    if (!file_path || file_path.length === 0) {
+      return {
+        ok: false,
+        error: { _tag: "UnableToGetFile", cause: "File path not defined" }
+      }
+    }
+
+    const file_name = file_path.replaceAll("/", "-")
+    const url = `${tgConfig.base_url}/file/bot${tgConfig.bot_token}/${file_path}`
+
+    let content: ArrayBuffer
+    try {
+      content = await fetch(url).then((_) => _.arrayBuffer())
+    } catch (cause) {
+      return { ok: false, error: { _tag: "UnableToGetFile", cause } }
+    }
+
+    const base64String = () => Buffer.from(content).toString("base64")
+    const file = () =>
+      new File([content], file_name, {
+        ...(params.type ? { type: params.type } : {})
+      })
+
+    return {
+      ok: true,
+      data: { content, file_name, base64String, file }
+    }
+  }
 
   return {
     config: tgConfig,
     execute,
-    getFile: (input) => getFileImpl({ ...input, config: tgConfig, execute })
+    getFile
   }
 }

package/src/execute.ts

@@ -1,14 +1,87 @@
 import type { Api } from "@effect-ak/tg-bot-api"
 
-import { TgBotClientError } from "./errors"
-import { isFileContent, isTgBotApiResponse } from "./guards"
-import { snakeToCamel } from "./utils"
 import type { TgClientConfig } from "./client"
 
+// --- result ---
+
+export type ClientErrorReason =
+  | { _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 }
+
+export type ClientResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ClientErrorReason }
+
+// --- guards ---
+
+export interface FileContent {
+  file_content: Uint8Array<ArrayBuffer>
+  file_name: string
+}
+
+const isFileContent = (input: unknown): input is FileContent =>
+  typeof input == "object" &&
+  input != null &&
+  "file_content" in input &&
+  input.file_content instanceof Uint8Array &&
+  "file_name" in input &&
+  typeof input.file_name == "string"
+
+interface TgBotApiResponseSchema {
+  ok: boolean
+  error_code?: number
+  description?: string
+  result?: unknown
+}
+
+const isTgBotApiResponse = (
+  input: unknown
+): input is TgBotApiResponseSchema =>
+  typeof input == "object" &&
+  input != null &&
+  "ok" in input &&
+  typeof input.ok == "boolean"
+
+// --- message effects ---
+
+export const MESSAGE_EFFECTS = {
+  "🔥": "5104841245755180586",
+  "👍": "5107584321108051014",
+  "👎": "5104858069142078462",
+  "❤️": "5159385139981059251",
+  "🎉": "5046509860389126442",
+  "💩": "5046589136895476101"
+} as const
+
+export type MessageEffect = keyof typeof MESSAGE_EFFECTS
+
+export const messageEffectIdCodes = Object.keys(
+  MESSAGE_EFFECTS
+) as MessageEffect[]
+
+const isMessageEffect = (input: unknown): input is MessageEffect => {
+  return typeof input === "string" && input in MESSAGE_EFFECTS
+}
+
+// --- execute ---
+
+const snakeToCamel = (str: string): string => {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase())
+}
+
+type WithMessageEffect<T> =
+  T extends { message_effect_id?: string }
+    ? Omit<T, "message_effect_id"> & { message_effect_id?: MessageEffect | (string & {}) }
+    : T
+
 export type ExecuteMethod = <M extends keyof Api>(
   method: M,
-  input: Parameters<Api[M]>[0]
-) => Promise<ReturnType<Api[M]>>
+  input: WithMessageEffect<Parameters<Api[M]>[0]>
+) => Promise<ClientResult<ReturnType<Api[M]>>>
 
 export async function executeTgBotMethod<M extends keyof Api>(
   params: {
@@ -16,8 +89,13 @@ export async function executeTgBotMethod<M extends keyof Api>(
     method: M
     input: Parameters<Api[M]>[0]
   }
-): Promise<ReturnType<Api[M]>> {
-  const { config, method, input } = params
+): Promise<ClientResult<ReturnType<Api[M]>>> {
+  const { config, method } = params
+  let { input } = params
+
+  if ("message_effect_id" in input && isMessageEffect(input.message_effect_id)) {
+    input = { ...input, message_effect_id: MESSAGE_EFFECTS[input.message_effect_id] }
+  }
 
   let httpResponse: Response
   try {
@@ -29,37 +107,32 @@ export async function executeTgBotMethod<M extends keyof Api>(
       }
     )
   } catch (cause) {
-    throw new TgBotClientError({
-      cause: { _tag: "ClientInternalError", cause }
-    })
+    return { ok: false, error: { _tag: "ClientInternalError", cause } }
   }
 
   let response: unknown
   try {
     response = await httpResponse.json()
   } catch {
-    throw new TgBotClientError({
-      cause: { _tag: "NotJsonResponse", response: httpResponse }
-    })
+    return { ok: false, error: { _tag: "NotJsonResponse", response: httpResponse } }
   }
 
   if (!isTgBotApiResponse(response)) {
-    throw new TgBotClientError({
-      cause: { _tag: "UnexpectedResponse", response }
-    })
+    return { ok: false, error: { _tag: "UnexpectedResponse", response } }
   }
 
   if (!httpResponse.ok) {
-    throw new TgBotClientError({
-      cause: {
+    return {
+      ok: false,
+      error: {
         _tag: "NotOkResponse",
         ...(response.error_code ? { errorCode: response.error_code } : {}),
         ...(response.description ? { details: response.description } : {})
       }
-    })
+    }
   }
 
-  return response.result as ReturnType<Api[M]>
+  return { ok: true, data: response.result as ReturnType<Api[M]> }
 }
 
 export const makePayload = (body: object): FormData | undefined => {

package/src/index.ts

@@ -1,7 +1,24 @@
-export * from "./execute"
-export * from "./client-file"
-export * from "./client"
-export * from "./errors"
-export * from "./guards"
-export * from "./const"
-export * from "./utils"
+export {
+  MESSAGE_EFFECTS,
+  messageEffectIdCodes,
+  makePayload,
+  executeTgBotMethod
+} from "./execute"
+
+export type {
+  ClientResult,
+  ClientErrorReason,
+  FileContent,
+  MessageEffect,
+  ExecuteMethod
+} from "./execute"
+
+export {
+  makeTgBotClient
+} from "./client"
+
+export type {
+  TgBotClient,
+  TgClientConfig,
+  TgFile
+} from "./client"