teleproto 1.225.0 → 1.225.2

package/{LICENSE.txt → LICENSE}

@@ -1,10 +1,7 @@
 MIT License
 
-Copyright (c) 2025 sanyok12345. All rights reserved.
-
-This project, teleproto, is an independent work originally derived from GramJS.
-GramJS is an open source project licensed under the MIT License.
-Portions of teleproto are adapted from GramJS and remain subject to the MIT terms.
+Copyright (c) 2019 GramJS
+Copyright (c) 2025-present sanyok12345
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -22,4 +19,4 @@ 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.
+SOFTWARE.

package/README.md

@@ -1,150 +1,115 @@
-# teleproto
+[![npm](https://img.shields.io/npm/v/teleproto)](https://www.npmjs.com/package/teleproto)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](./LICENSE)
 
-<p align="center">
-  <img src="https://img.shields.io/npm/v/teleproto" alt="npm version">
-  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="node version">
-  <img src="https://img.shields.io/badge/language-TypeScript-3178c6" alt="typescript">
-  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license">
-  <a href="https://t.me/teleproto"><img src="https://img.shields.io/badge/Telegram-Chat-26A5E4?logo=telegram" alt="telegram chat"></a>
-</p>
+This project was forked from the open source GramJS project in 2025 and is now developed independently.
 
-Modern Telegram MTProto client for Node.js, written in TypeScript.
-`teleproto` is a high-performance fork of GramJS focused on clean API ergonomics, runtime reliability, and up-to-date Telegram layers.
+This README is just a fast *quick start*. Ongoing discussion happens in the [Telegram chat](https://t.me/teleproto).
 
-## Features
+# What is teleproto?
 
-- **MTProto-first**: Full Telegram API access through high-level client methods and raw `Api` calls.
-- **TypeScript-friendly**: Strong typings across client methods, events, sessions, and TL objects.
-- **Session options**: Use `StringSession` for portability or `StoreSession` for local persistence.
-- **Event system**: Handle updates with builders like `NewMessage`, `EditedMessage`, `CallbackQuery`, and more.
-- **Examples included**: Ready-to-run scripts in `teleproto_examples`.
+teleproto is a TypeScript client for Telegram's MTProto API — the same protocol Telegram's own apps speak. Through it, your code gets the full account surface: userbots, multi-account automation, file transfer, raw TL invocation when you need it. If you only need to push notifications from a bot, the official Bot API is simpler; teleproto exists for everything *beyond* that.
 
-## Installation
+# Installing teleproto
 
-```bash 
-npm i teleproto
-```
+    % npm install teleproto
+
+Pure JavaScript, no native build step — installs cleanly on Alpine, ARM, and serverless runtimes.
 
-## Quick Start
+# Connecting to Telegram
 
-1. Open https://my.telegram.org
-2. Create an app in **API development tools**
-3. Copy your `api_id` and `api_hash`
+You need an `api_id` and `api_hash` from <https://my.telegram.org>. Then:
 
 ```ts
 import { TelegramClient } from "teleproto";
 import { StringSession } from "teleproto/sessions";
-import readline from "readline";
+import { createInterface } from "node:readline/promises";
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
 
-const apiId = 123456;
-const apiHash = "0123456789abcdef0123456789abcdef";
+const apiId = 0;     // from https://my.telegram.org
+const apiHash = "";  // from https://my.telegram.org
 const session = new StringSession("");
 
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout,
+const client = new TelegramClient(session, apiId, apiHash, {
+  connectionRetries: 5,
 });
 
-const ask = (q: string) =>
-  new Promise<string>((resolve) => rl.question(q, resolve));
-
-async function main() {
-  const client = new TelegramClient(session, apiId, apiHash, {
-    connectionRetries: 5,
-  });
-
-  await client.start({
-    phoneNumber: async () => await ask("Phone number: "),
-    password: async () => await ask("2FA password (if enabled): "),
-    phoneCode: async () => await ask("Code from Telegram: "),
-    onError: (err) => console.error(err),
-  });
-
-  console.log("Connected as:", (await client.getMe())?.username || "unknown");
-  console.log("String session:\n", client.session.save());
+await client.start({
+  phoneNumber: () => rl.question("Phone: "),
+  password:    () => rl.question("2FA password: "),
+  phoneCode:   () => rl.question("Code: "),
+  onError: console.error,
+});
 
-  await client.sendMessage("me", { message: "Hello from teleproto!" });
-  await client.disconnect();
-  rl.close();
-}
+console.log(await client.getMe());
+console.log("Session string:", client.session.save());
 
-main().catch(console.error);
+rl.close();
 ```
 
-## Sessions
-
-Use `StringSession` when you want to store auth as a single string:
+The session string is your saved login. Drop it back into `new StringSession(saved)` next time and skip the auth flow entirely.
 
-```ts
-import { StringSession } from "teleproto/sessions";
-const session = new StringSession("");
-```
+# Sending and receiving
 
-Use `StoreSession` when you want local folder-based persistence:
-
-```ts
-import { StoreSession } from "teleproto/sessions";
-const session = new StoreSession("teleproto_session");
-```
-
-## Events
+Send a message, listen for incoming ones:
 
 ```ts
 import { NewMessage } from "teleproto/events";
 
+await client.sendMessage("me", { message: "hello from teleproto" });
+
 client.addEventHandler(
-  async (event) => {
-    const text = event.message.message || "";
-    if (/^hello$/i.test(text.trim())) {
-      await event.message.reply({ message: "Hi there!" });
-    }
-  },
-  new NewMessage({})
+  (event) => console.log(event.message.message),
+  new NewMessage({}),
 );
 ```
 
-## Raw API
+# Raw MTProto API
+
+Every method in Telegram's TL schema is callable directly through `Api.*`. teleproto follows the schema layer-for-layer, so what Telegram adds is usually available here within days.
 
 ```ts
 import { Api } from "teleproto";
 
-const result = await client.invoke(
-  new Api.help.GetConfig()
-);
-console.log(result);
+const config = await client.invoke(new Api.help.GetConfig());
 ```
 
-## Examples
+# Versioning
 
-Practical scripts are available in `teleproto_examples`:
+teleproto uses a three-part version `MAJOR.LAYER.PATCH`:
 
-- `print_updates.ts`
-- `print_messages.ts`
-- `replier.ts`
-- `interactive_terminal.ts`
+- **MAJOR** — bumped on breaking API changes in teleproto itself.
+- **LAYER** — the Telegram TL schema layer the release ships against
+  (e.g. `1.225.x` ships layer 225).
+- **PATCH** — fixes and non-breaking improvements within the same layer.
 
-Run any example from the project root:
+This stays compatible with npm's range syntax:
 
-```bash
-npx ts-node --transpile-only teleproto_examples/print_updates.ts
-```
+- `^1.225.0` accepts new layers and patches — recommended default.
+- `~1.225.0` sticks to layer 225 only; useful if you depend on
+  schema specifics that newer layers might change.
+- `1.225.1` is an exact pin.
+
+# Examples
+
+Runnable scripts live in [teleproto_examples/](teleproto_examples/):
+
+- `print_updates.ts` — log every update the client receives
+- `print_messages.ts` — listen for new messages only
+- `replier.ts` — auto-reply pattern for bots and userbots
+- `interactive_terminal.ts` — REPL against a live client
 
-## Community
+Each is self-contained. Set your credentials at the top and run:
 
-- [Telegram Chat](https://t.me/teleproto) — questions, discussions, updates
-- [GitHub Issues](https://github.com/sanyok12345/teleproto/issues) — bug reports and feature requests
+    % npx ts-node --transpile-only teleproto_examples/print_updates.ts
 
-## Support the project ☕
+# Code contributions
 
-If teleproto saves you time or powers your product — consider buying me a coffee.
-Every donation keeps the lights on and the commits flowing.
+Please see [CONTRIBUTING.md][1].
 
-| Network | Address |
-|---------|---------|
-|  **TON** | `sanyok12345.ton` |
-|  **TRX** | `TXCtN1UrxST9ovq5tDN3Zb96eNF4164nK5` |
-|  **SOL** | `B3XcKmAR9aG2nBiWSMDe76GGa55hPNgLQ92QR2SjRR6F` |
+# License
 
-## License
+teleproto is distributed under the [MIT License][2].
 
-MIT
+[1]: ./CONTRIBUTING.md
+[2]: ./LICENSE

package/Version.d.ts

@@ -1 +1 @@
-export declare const version = "1.225.0";
+export declare const version = "1.225.2";

package/Version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
-exports.version = "1.225.0";
+exports.version = "1.225.2";

package/client/TelegramClient.d.ts

@@ -353,30 +353,6 @@ export declare class TelegramClient extends TelegramBaseClient {
      * ```
      */
     downloadFile(inputLocation: Api.TypeInputFileLocation, fileParams?: downloadMethods.DownloadFileParams): Promise<string | Buffer<ArrayBufferLike> | undefined>;
-    /**
-     * Iterates over a file download, yielding chunks of the file.
-     * This method can be used to stream files in a more convenient way, since it offers more control (pausing, resuming, etc.)
-     * @param iterFileParams - {@link IterDownloadFunction}
-     * @return a Buffer downloaded from the inputFile.
-     * @example
-     * ```ts
-     * const photo = message.photo;
-     * for await (const chunk of client.iterDownload({
-     *       file: new Api.InputPhotoFileLocation({
-     *          id: photo.id,
-     *          accessHash: photo.accessHash,
-     *          fileReference: photo.fileReference,
-     *          thumbSize: size.type
-     *      }),
-     *      offset: start,
-     *      limit: end,
-     *      requestSize:2048*1024
-     * )){
-     *     console.log("Downloaded chunk of size",chunk.length);
-     * };
-     * ```
-     */
-    iterDownload(iterFileParams: downloadMethods.IterDownloadFunction): downloadMethods.DirectDownloadIter;
     /**
      * Downloads the profile photo from the given user,chat or channel.<br/>
      * This method will return an empty buffer in case of no profile photo.
@@ -1133,8 +1109,6 @@ export declare class TelegramClient extends TelegramBaseClient {
     /** @hidden */
     _getDownloadConcurrency(fileSize: number): Promise<number>;
     /** @hidden */
-    _removeSender(dcId: number): void;
-    /** @hidden */
     _getResponseMessage(req: any, result: any, inputChat: any): Api.TypeMessage | Map<number, Api.Message> | (Api.Message | undefined)[] | undefined;
     /** @hidden */
     static get events(): any;

package/client/TelegramClient.js

@@ -433,32 +433,6 @@ class TelegramClient extends telegramBaseClient_1.TelegramBaseClient {
     downloadFile(inputLocation, fileParams = {}) {
         return downloadMethods.downloadFile(this, inputLocation, fileParams);
     }
-    /**
-     * Iterates over a file download, yielding chunks of the file.
-     * This method can be used to stream files in a more convenient way, since it offers more control (pausing, resuming, etc.)
-     * @param iterFileParams - {@link IterDownloadFunction}
-     * @return a Buffer downloaded from the inputFile.
-     * @example
-     * ```ts
-     * const photo = message.photo;
-     * for await (const chunk of client.iterDownload({
-     *       file: new Api.InputPhotoFileLocation({
-     *          id: photo.id,
-     *          accessHash: photo.accessHash,
-     *          fileReference: photo.fileReference,
-     *          thumbSize: size.type
-     *      }),
-     *      offset: start,
-     *      limit: end,
-     *      requestSize:2048*1024
-     * )){
-     *     console.log("Downloaded chunk of size",chunk.length);
-     * };
-     * ```
-     */
-    iterDownload(iterFileParams) {
-        return downloadMethods.iterDownload(this, iterFileParams);
-    }
     //region download
     /**
      * Downloads the profile photo from the given user,chat or channel.<br/>
@@ -1183,7 +1157,6 @@ class TelegramClient extends telegramBaseClient_1.TelegramBaseClient {
                 client: this,
                 securityChecks: this._securityChecks,
                 autoReconnectCallback: this._handleReconnect.bind(this),
-                _exportedSenderPromises: this._exportedSenderPromises,
                 reconnectRetries: this._reconnectRetries,
             });
         }
@@ -1225,12 +1198,12 @@ class TelegramClient extends telegramBaseClient_1.TelegramBaseClient {
         this._log.info(`Reconnecting to new data center ${newDc}`);
         const DC = await this.getDC(newDc);
         this.session.setDC(newDc, DC.ipAddress, DC.port);
-        // authKey's are associated with a server, which has now changed
-        // so it's not valid anymore. Set to undefined to force recreating it.
         await this._sender.authKey.setKey(undefined);
         this.session.setAuthKey(undefined);
         this.session.save();
         this._isSwitchingDc = true;
+        await this._filePool.purge();
+        await this._apiSenderPool.purge();
         await this._disconnect();
         this._sender = undefined;
         return await this.connect();
@@ -1332,10 +1305,6 @@ class TelegramClient extends telegramBaseClient_1.TelegramBaseClient {
         return fileSize > 20 * 1024 * 1024 ? largeLimit : smallLimit;
     }
     /** @hidden */
-    _removeSender(dcId) {
-        delete this._borrowedSenderPromises[dcId];
-    }
-    /** @hidden */
     _getResponseMessage(req, result, inputChat) {
         return parseMethods._getResponseMessage(this, req, result, inputChat);
     }

package/client/downloads.d.ts

@@ -1,119 +1,29 @@
 import { Api } from "../tl";
 import type { TelegramClient } from "./TelegramClient";
 import { EntityLike, OutFile, ProgressCallback } from "../define";
-import { RequestIter } from "../requestIter";
 import bigInt from "big-integer";
-/**
- * progress callback that will be called each time a new chunk is downloaded.
- */
 export interface progressCallback {
-    (
-    /** How much was downloaded */
-    downloaded: bigInt.BigInteger, 
-    /** Full size of the file to be downloaded */
-    fullSize: bigInt.BigInteger, 
-    /** other args to be passed if needed */
-    ...args: any[]): void;
-    /** When this value is set to true the download will stop */
+    (downloaded: bigInt.BigInteger, fullSize: bigInt.BigInteger, ...args: any[]): void;
     isCanceled?: boolean;
-    /** Does nothing for now. */
     acceptsBuffer?: boolean;
 }
 export interface DownloadFileParams {
-    /**
-     * The output file path, directory,buffer, or stream-like object.
-     * If the path exists and is a file, it will be overwritten.
-
-     * If the file path is `undefined` or `Buffer`, then the result
-     will be saved in memory and returned as `Buffer`.
-     */
     outputFile?: OutFile;
-    /** The dcId that the file belongs to. Used to borrow a sender from that DC. The library should handle this for you */
     dcId?: number;
-    /** The file size that is about to be downloaded, if known.<br/>
-     Only used if ``progressCallback`` is specified. */
     fileSize?: bigInt.BigInteger;
-    /** How much to download in each chunk. The larger the less requests to be made. (max is 512kb). */
     partSizeKb?: number;
-    /** Progress callback accepting one param. (progress :number) which is a float between 0 and 1 */
     progressCallback?: progressCallback;
     msgData?: [EntityLike, number];
 }
-/**
- * contains optional download params for profile photo.
- */
 export interface DownloadProfilePhotoParams {
-    /** Whether to download the big version or the small one of the photo */
     isBig?: boolean;
     outputFile?: OutFile;
 }
-export interface DirectDownloadIterInterface {
-    fileLocation: Api.TypeInputFileLocation;
-    dcId: number;
-    offset: bigInt.BigInteger;
-    stride: number;
-    chunkSize: number;
-    requestSize: number;
-    fileSize: number;
-    msgData: number;
-}
-export interface IterDownloadFunction {
-    file?: Api.TypeMessageMedia | Api.TypeInputFile | Api.TypeInputFileLocation;
-    offset?: bigInt.BigInteger;
-    stride?: number;
-    limit?: number;
-    chunkSize?: number;
-    requestSize: number;
-    fileSize?: bigInt.BigInteger;
-    dcId?: number;
-    msgData?: [EntityLike, number];
-}
-export declare class DirectDownloadIter extends RequestIter {
-    protected request?: Api.upload.GetFile;
-    private _sender?;
-    private _timedOut;
-    protected _stride?: number;
-    protected _chunkSize?: number;
-    protected _lastPart?: Buffer;
-    protected buffer: Buffer[] | undefined;
-    _init({ fileLocation, dcId, offset, stride, chunkSize, requestSize, fileSize, msgData, }: DirectDownloadIterInterface): Promise<void>;
-    _loadNextChunk(): Promise<boolean | undefined>;
-    _request(): Promise<Buffer>;
-    close(): Promise<void>;
-    [Symbol.asyncIterator](): AsyncIterator<Buffer, any, undefined>;
-}
-export declare class GenericDownloadIter extends DirectDownloadIter {
-    _loadNextChunk(): Promise<boolean | undefined>;
-}
-/** @hidden */
-export declare function iterDownload(client: TelegramClient, { file, offset, stride, limit, chunkSize, requestSize, fileSize, dcId, msgData, }: IterDownloadFunction): DirectDownloadIter;
 /** @hidden */
-export declare function downloadFile(client: TelegramClient, inputLocation: Api.TypeInputFileLocation, { outputFile, partSizeKb, fileSize, progressCallback, dcId, msgData, }: DownloadFileParams): Promise<string | Buffer<ArrayBufferLike> | undefined>;
-/**
- * All of these are optional and will be calculated automatically if not specified.
- */
+export declare function downloadFile(client: TelegramClient, inputLocation: Api.TypeInputFileLocation, { outputFile, partSizeKb, fileSize, progressCallback, dcId, }: DownloadFileParams): Promise<Buffer | string | undefined>;
 export interface DownloadMediaInterface {
-    /**
-     * The output file location, if left undefined this method will return a buffer
-     */
     outputFile?: OutFile;
-    /**
-     * Which thumbnail size from the document or photo to download, instead of downloading the document or photo itself.<br/>
-     <br/>
-     If it's specified but the file does not have a thumbnail, this method will return `undefined`.<br/>
-     <br/>
-     The parameter should be an integer index between ``0`` and ``sizes.length``.<br/>
-     ``0`` will download the smallest thumbnail, and ``sizes.length - 1`` will download the largest thumbnail.<br/>
-     <br/>
-     You can also pass the `Api.PhotoSize` instance to use.  Alternatively, the thumb size type `string` may be used.<br/>
-     <br/>
-     In short, use ``thumb=0`` if you want the smallest thumbnail and ``thumb=sizes.length`` if you want the largest thumbnail.
-     */
     thumb?: number | Api.TypePhotoSize;
-    /**
-     *  A callback function accepting two parameters:
-     * ``(received bytes, total)``.
-     */
     progressCallback?: ProgressCallback;
 }
 /** @hidden */
@@ -121,9 +31,9 @@ export declare function downloadMedia(client: TelegramClient, messageOrMedia: Ap
 /** @hidden */
 export declare function _downloadDocument(client: TelegramClient, doc: Api.MessageMediaDocument | Api.TypeDocument, outputFile: OutFile | undefined, date: number, thumb?: number | string | Api.TypePhotoSize, progressCallback?: ProgressCallback, msgData?: [EntityLike, number]): Promise<Buffer | string | undefined>;
 /** @hidden */
-export declare function _downloadContact(client: TelegramClient, media: Api.MessageMediaContact, args: DownloadMediaInterface): Promise<Buffer>;
+export declare function _downloadContact(_client: TelegramClient, _media: Api.MessageMediaContact, _args: DownloadMediaInterface): Promise<Buffer>;
 /** @hidden */
-export declare function _downloadWebDocument(client: TelegramClient, media: Api.WebDocument | Api.WebDocumentNoProxy, args: DownloadMediaInterface): Promise<Buffer>;
+export declare function _downloadWebDocument(_client: TelegramClient, _media: Api.WebDocument | Api.WebDocumentNoProxy, _args: DownloadMediaInterface): Promise<Buffer>;
 /** @hidden */
 export declare function _downloadCachedPhotoSize(size: Api.PhotoCachedSize | Api.PhotoStrippedSize, outputFile?: OutFile): Promise<string | Buffer<ArrayBufferLike> | undefined>;
 /** @hidden */