mytglib

mytglib 是对 @mtcute/node 登录流程的轻量封装，提供 Android/iOS 客户端配置、手机号与代理检查、验证码登录、结果消息解析和设备模型生成。

环境

• Node.js 20+
• 执行登录或代理检查时，需要一个可连接 Telegram 主 DC 的 HTTP 或 SOCKS5 代理

安装当前仓库依赖：

npm install

构建

生成供发布和包根入口使用的 ESM 产物：

npm run build

构建结果位于 dist/index.js。Webpack 会打包本仓库源码，使用 Terser 压缩，并对标识符和字符串数组进行混淆；@mtcute/node 等运行时依赖保持为外部 ESM 依赖，不会重复打入产物。构建不生成 source map，发布包仅包含 dist、README.md、package.json 和许可证文件。

离线示例

无需网络即可检查手机号解析、随机设备参数、验证码设置和消息映射：

npm run example:inspect
npm run example:inspect -- "+1 (202) 555-0123"

实现位于 examples/inspect-config.js。

初始化与登录

完整示例位于 examples/login.js。先查看所需环境变量：

npm run example:login -- --help

以 HTTP 代理运行 Android 登录：

TG_PHONE="+12025550123" \
TG_PROXY_HOST="127.0.0.1" \
TG_PROXY_PORT="8080" \
TG_PROXY_TYPE="http" \
TG_DEVICE_TOKEN="your-device-token" \
npm run example:login

示例按服务端响应处理邮箱设置、邮箱验证码、手机验证码和新账号注册。reCAPTCHA 出现时会显示 action 与 siteKey，并等待输入外部移动端求解器返回的 token。

基本 API

下面是常见的短信验证码登录路径；邮箱设置、新账号注册等完整分支见 examples/login.js。

import { resolve } from "node:path";
import { CoreClient, getCallMessage } from "mytglib";

const abortController = new AbortController();
const core = new CoreClient({
  clientType: "android",
  phone: "+12025550123",
  proxy: { type: "http", host: "127.0.0.1", port: 8080 },
  sessionDirPath: resolve("telegram-sessions"),
  timeout: 30_000,
  maxRetryCount: 0,
  abortSignal: abortController.signal,
  deviceTokenResolver: async () => ({ token: "your-device-token" }),
  recaptchaMobileTokenResolver: async () => ({
    token: process.env.TG_RECAPTCHA_TOKEN,
  }),
});

try {
  await core.init();

  let response = await core.sendCode();
  console.log(getCallMessage(response));

  if (response._ === "auth.sentCode") {
    response = await core.verifyPhoneCode({ phoneCode: "12345" });
    console.log(getCallMessage(response));
  } else if (response._ === "auth.sentCodeSuccess") {
    response = response.authorization;
  }

  if (response._ !== "auth.authorization") {
    throw new Error(`Login did not complete: ${response._}`);
  }

  const config = await core.client.call({ _: "help.getConfig" });
  console.log(config.thisDc);
} finally {
  await core.destroy();
}

deviceTokenResolver 和 recaptchaMobileTokenResolver 必须返回包含非空字符串 token 字段的对象，对象可保留求解服务返回的 errorMessage、message 等附加字段。无有效 token 时会抛出 TypeError，其 cause 是 resolver 返回的完整结果，调用方可据此读取附加错误信息；reCAPTCHA token 最长为 16,384 个字符。

timeout、maxRetryCount 和 abortSignal 是所有 mytglib 登录 RPC 的统一调用参数。timeout 默认为 30000，必须是正安全整数毫秒；maxRetryCount 默认为 0，必须是非负安全整数；abortSignal 默认为 undefined，传入时必须是 AbortSignal。客户端创建后会通过原始 TelegramClient.withParams() 生成 core.client，登录流程和通过 core.client.call() 发出的请求都会使用这些参数。它们只作用于 RPC，不处理 connect() 超时，也不会取消正在进行的 connect()。

sessionDirPath 是必传的会话主目录。路径已存在时必须是目录；路径不存在时会在初始化过程中递归创建。init() 会按照 <主目录>/<+手机号>/<+手机号>.session 创建 SQLite 会话文件，然后依次解析设备 token 并连接客户端。连接成功后可通过 core.sessionFilePath 直接取得当前客户端使用的 SQLite 文件路径；连接前该属性为 null。登录相关公共异步方法均返回原始 Telegram TL 响应。core.rawClient 保存原始 TelegramClient，只负责 connect()、notifyLoggedIn() 和 destroy()；core.client 保存 withParams() 返回的 RPC Proxy。core.destroy() 始终销毁 rawClient，不会在 @mtcute/node 0.31.0 的包装对象上调用 destroy()，从而避免私有字段错误。无论成功或失败，都应在 finally 中调用 core.destroy()，永久关闭连接、定时器和存储资源。销毁成功后两个客户端引用都会恢复为 null，SQLite 文件路径仍保留在 core.sessionFilePath 上。

sendEmailCode()、verifyEmailCode()、verifyPhoneCode() 和 register() 会直接向 onLog 发出 started、completed 或 failed 事件。失败事件的 error 保留 Telegram RPC 错误的 code、text 和 message，方法本身也会原样抛出错误；验证码等调用参数不会写入日志。

代理检查

import { checkProxy } from "mytglib";

const result = await checkProxy({
  clientType: "android",
  proxy: "socks5://user:[email protected]:1080",
  timeoutMs: 12_000,
});

console.log(result);

checkProxy 会并行检查所选平台的全部五个 Telegram 主 DC，并关闭每个已建立的连接。

测试

npm test
npm run test:coverage