telegram-bot-raw 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Zhukov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# [telegram-bot-raw](https://www.npmjs.com/package/telegram-bot-raw) npm package
+
+![npm version](https://img.shields.io/npm/v/telegram-bot-raw)
+![npm license](https://img.shields.io/npm/l/telegram-bot-raw)
+![node.js version](https://img.shields.io/badge/node-%E2%89%A5_18-brightgreen)
+![npm type definitions](https://img.shields.io/npm/types/telegram-bot-raw)
+
+This package provides a minimal abstraction over the Telegram Bot API, closely
+follows the official specification without adding extra layers or hidden
+behavior.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Supported Bot API](#supported-bot-api)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Calling API Methods](#calling-api-methods)
+  - [Optional Parameters](#optional-parameters)
+  - [Methods Without Parameters](#methods-without-parameters)
+  - [InputFile Object](#inputfile-object)
+  - [Return Values](#return-values)
+  - [Error Handling](#error-handling)
+- [Api Class Reference](#api-class-reference)
+  - [Constructor](#constructor)
+  - [Properties](#properties)
+  - [Static Properties](#static-properties)
+  - [Static Methods](#static-methods)
+- [License](#license)
+
+## Features
+
+- Low-level API wrapper with minimal overhead
+- Full control over API requests and parameters
+- Promise-based interface
+- Full TypeScript definitions
+- Zero dependencies
+
+## Requirements
+
+**Node.js v18** or higher.
+
+## Supported Bot API
+
+This package supports Telegram Bot API version 9.5 (released March 1, 2026).
+
+See the [Telegram Bot API documentation](https://core.telegram.org/bots/api).
+
+## Installation
+
+```sh
+npm install telegram-bot-raw
+```
+
+## Quick Start
+
+```js
+import { Api } from 'telegram-bot-raw';
+
+// Create an API client instance
+const botToken = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11';
+const api = new Api(botToken);
+
+// Get the bot's name (returns a BotName object)
+const botName = await api.getMyName();
+
+// Send a message to the user #123456789
+const response = await api.sendMessage({
+  chat_id: 123456789,
+  text: `Greetings from <b>${botName.name}</b>!`,
+  parse_mode: 'HTML'
+});
+
+// Log the sent message object
+console.log('Sent message:', response);
+```
+
+## Usage
+
+### Calling API Methods
+
+Each Telegram Bot API method is exposed as a method of the `Api` class with the
+same name and parameters. For example, the Bot API method `setMyName` which
+accepts two string parameters `name` and `language_code` can be called as
+follows:
+
+```js
+await api.setMyName({
+  name: 'マイちゃんボット',
+  language_code: 'jp'
+});
+```
+
+To call an undocumented Bot API method, use the static `call` method, passing
+your `Api` instance, the name of the API method, and an optional object with the
+API call parameters. The following example uses fictitious undocumented API
+methods:
+
+```js
+const api = new Api('123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11');
+const userId = 123456789;
+
+if (await Api.call(api, 'isUserWombat', { user_id: userId })) {
+  await Api.call(api, 'markUserAsCute', {
+    user_id: userId,
+    reason: 'wombat'
+  });
+}
+```
+
+### Optional Parameters
+
+If all parameters are optional, the argument can be omitted. The following calls
+are equivalent:
+
+```js
+await api.deleteWebhook({ drop_pending_updates: undefined });
+await api.deleteWebhook({});
+await api.deleteWebhook();
+```
+
+### Methods Without Parameters
+
+API methods that do not accept parameters should be called without arguments:
+
+```js
+await api.logOut();
+```
+
+### InputFile Object
+
+In this library, `InputFile` is an alias of the native Node.js `File` class from
+`node:buffer`:
+
+```js
+import { readFileSync } from 'node:fs';
+import { InputFile } from 'telegram-bot-raw';
+
+const buffer = readFileSync('photo.png');
+const file = new InputFile([buffer], 'photo.png');
+
+await api.setMyProfilePhoto({ photo: file });
+```
+
+See the
+[File class documentation](https://nodejs.org/api/buffer.html#class-file).
+
+### Return Values
+
+All methods return a `Promise` that resolves to the result defined in the
+[Telegram Bot API documentation](https://core.telegram.org/bots/api).
+
+### Error Handling
+
+If a request fails, an `ApiError` is thrown:
+
+```js
+import { ApiError } from 'telegram-bot-raw';
+
+const params = {
+  user_id: 123456789,
+  chat_id: 987654321
+};
+
+try {
+  await api.forwardMessage(params);
+}
+catch (error) {
+  if (error instanceof ApiError) {
+    console.error('Error code:', error.code);
+    console.error('Error message:', error.message);
+  }
+}
+```
+
+`error.code` and `error.message` contain the `error_code` and `description`
+response values, respectively.
+
+## `Api` Class Reference
+
+### Constructor
+
+```ts
+new Api(botToken: string)
+```
+- `botToken`: Telegram bot token.
+
+### Properties
+
+```ts
+keepAlive: boolean
+```
+
+Enables or disables HTTP keep-alive for requests to `api.telegram.org`.
+
+The default value is `false`.
+
+---
+
+```ts
+timeout: number
+```
+
+Sets request timeout:
+- `> 0` &ndash; timeout in milliseconds,
+- `0` &ndash; no timeout,
+- other values are treated as `0`.
+
+If the timeout is exceeded, an `AbortError` is thrown:
+
+```js
+api.timeout = 5000;
+
+const params = {
+  message_id: 123456789,
+  chat_id: 987654321,
+  from_chat_id: -987654321,
+};
+
+try {
+  await api.banChatMember(params);
+}
+catch (error) {
+  if (error.name === 'AbortError')
+    console.error('Server is not responding.');
+  else
+    throw error;
+}
+```
+
+The default value is `0`.
+
+---
+
+```ts
+transport: ApiTransport | null
+```
+
+Sets a function responsible for making HTTP requests to the Telegram Bot API:
+
+```ts
+function(url: string, init: RequestInit): Promise<Response>
+```
+
+**Parameters:**
+
+- `url` &ndash; the full request URL.
+- `init` &ndash; request options, including method, headers, etc.
+
+**Returns:**
+
+- A `Promise` that resolves to a `Response` object.
+
+This can be used for logging, simulating server requests, and other tasks:
+
+```js
+api.transport = (url, init) => {
+  const method = init.method ?? 'GET';
+  console.log(`${method}:`, url);
+  return fetch(url, init);
+}
+```
+
+- If `transport` is a `Function`, it will be used to send all API requests.
+- If `transport` is `null`, the built-in implementation is used.
+- Other values are treated as `null`.
+
+The default value is `null`.
+
+---
+
+### Static Properties
+
+```ts
+version: string
+```
+
+Returns the version of the Telegram Bot API supported by the library:
+
+```js
+console.log(Api.version);  // '9.5'
+```
+
+### Static Methods
+
+```ts
+call<T>(api: Api, method: string, params?: Record<string, any>): Promise<T>
+```
+
+Calls an arbitrary API method.
+
+**Parameters:**
+
+- `api` &ndash; an `Api` instance.
+- `method` &ndash; the API method name.
+- `params` &ndash; the API method parameters, if present.
+
+**Returns:**
+
+- A `Promise` that resolves to the value returned by the server.
+
+See an example of calling undocumented methods in the
+[Calling API Methods](#calling-api-methods) section.
+
+The `call` method may throw an exception, see the
+[Error Handling](#error-handling) section.
+
+## License
+
+- MIT