@mtcute/core 0.17.1 → 0.18.0

package/network/client.cjs

@@ -0,0 +1,191 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[mtcute-workspace] CommonJS support is deprecated and will be removed in 0.20.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[mtcute-workspace] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const tl = require("@mtcute/tl");
+const reader_js = require("@mtcute/tl/binary/reader.js");
+const writer_js = require("@mtcute/tl/binary/writer.js");
+const storage = require("../storage/storage.cjs");
+const dcs = require("../utils/dcs.cjs");
+const functionUtils = require("../utils/function-utils.cjs");
+const logger = require("../utils/logger.cjs");
+const typeAssertions = require("../utils/type-assertions.cjs");
+require("@mtcute/tl-runtime");
+const configManager = require("./config-manager.cjs");
+const networkManager = require("./network-manager.cjs");
+class MtClient {
+  constructor(params) {
+    this.params = params;
+    this.log = params.logger ?? new logger.LogManager(void 0, params.platform);
+    if (params.logLevel !== void 0) {
+      this.log.mgr.level = params.logLevel;
+    }
+    this.crypto = params.crypto;
+    this._testMode = Boolean(params.testMode);
+    let dc = params.defaultDcs;
+    if (!dc) {
+      if (params.testMode) {
+        dc = params.useIpv6 ? dcs.defaultTestIpv6Dc : dcs.defaultTestDc;
+      } else {
+        dc = params.useIpv6 ? dcs.defaultProductionIpv6Dc : dcs.defaultProductionDc;
+      }
+    }
+    this._defaultDcs = dc;
+    this._layer = params.overrideLayer ?? tl.tl.LAYER;
+    this._readerMap = params.readerMap ?? reader_js.__tlReaderMap;
+    this._writerMap = params.writerMap ?? writer_js.__tlWriterMap;
+    this._abortController = new AbortController();
+    this.stopSignal = this._abortController.signal;
+    this.storage = new storage.StorageManager({
+      provider: params.storage,
+      log: this.log,
+      readerMap: this._readerMap,
+      writerMap: this._writerMap,
+      platform: params.platform,
+      ...params.storageOptions
+    });
+    this.network = new networkManager.NetworkManager(
+      {
+        apiId: params.apiId,
+        crypto: this.crypto,
+        disableUpdates: params.disableUpdates ?? false,
+        initConnectionOptions: params.initConnectionOptions,
+        layer: this._layer,
+        log: this.log,
+        readerMap: this._readerMap,
+        writerMap: this._writerMap,
+        reconnectionStrategy: params.reconnectionStrategy,
+        storage: this.storage,
+        testMode: Boolean(params.testMode),
+        transport: params.transport,
+        emitError: this.emitError.bind(this),
+        isPremium: false,
+        useIpv6: Boolean(params.useIpv6),
+        enableErrorReporting: params.enableErrorReporting ?? false,
+        onUsable: this.onUsable.emit.bind(this.onUsable),
+        onConnecting: this.onConnecting.emit.bind(this.onConnecting),
+        onNetworkChanged: this.onNetworkChanged.emit.bind(this.onNetworkChanged),
+        onUpdate: this.onUpdate.emit.bind(this.onUpdate),
+        stopSignal: this.stopSignal,
+        platform: params.platform,
+        ...params.network
+      },
+      this._config
+    );
+  }
+  /**
+   * Crypto provider taken from {@link MtClientOptions.crypto}
+   */
+  crypto;
+  /** Storage manager */
+  storage;
+  /**
+   * "Test mode" taken from {@link MtClientOptions.testMode}
+   */
+  _testMode;
+  /**
+   * Primary DCs taken from {@link MtClientOptions.defaultDcs},
+   * loaded from session or changed by other means (like redirecting).
+   */
+  _defaultDcs;
+  /** TL layer used by the client */
+  _layer;
+  /** TL readers map used by the client */
+  _readerMap;
+  /** TL writers map used by the client */
+  _writerMap;
+  _config = new configManager.ConfigManager(async () => {
+    const res = await this.call({ _: "help.getConfig" });
+    if (typeAssertions.isTlRpcError(res)) throw new Error(`Failed to get config: ${res.errorMessage}`);
+    return res;
+  });
+  _emitError;
+  log;
+  network;
+  _abortController;
+  stopSignal;
+  onUsable = new utils.Emitter();
+  onConnecting = new utils.Emitter();
+  onNetworkChanged = new utils.Emitter();
+  onUpdate = new utils.Emitter();
+  emitError(err) {
+    if (this._emitError) {
+      this._emitError(err);
+    } else if (this._connect.finished()) {
+      this.log.error("unhandled error:", err);
+    }
+  }
+  _prepare = functionUtils.asyncResettable(async () => {
+    await this.crypto.initialize?.();
+    await this.storage.load();
+    const primaryDc = await this.storage.dcs.fetch();
+    if (primaryDc !== null) this._defaultDcs = primaryDc;
+  });
+  /**
+   * **ADVANCED**
+   *
+   * Do all the preparations, but don't connect just yet.
+   * Useful when you want to do some preparations before
+   * connecting, like setting up session.
+   *
+   * Call {@link connect} to actually connect.
+   */
+  prepare() {
+    return this._prepare.run();
+  }
+  _connect = functionUtils.asyncResettable(async () => {
+    await this._prepare.run();
+    await this.network.connect(this._defaultDcs);
+  });
+  /**
+   * Initialize the connection to the primary DC.
+   *
+   * You shouldn't usually call this method directly as it is called
+   * implicitly the first time you call {@link call}.
+   */
+  async connect() {
+    return this._connect.run();
+  }
+  /**
+   * Close all connections and finalize the client.
+   */
+  async close() {
+    this.log.debug("closing client");
+    this._config.destroy();
+    await this.network.destroy();
+    await this.storage.save();
+    await this.storage.destroy?.();
+    this._prepare.reset();
+    this._connect.reset();
+    this._abortController.abort();
+    this.log.debug("client closed successfully");
+  }
+  /**
+   * Make an RPC call.
+   *
+   * The connection must have been {@link connect}-ed
+   * before calling this method.
+   *
+   * This method is still quite low-level and you shouldn't use this
+   * when using high-level API provided by `@mtcute/client`.
+   *
+   * @param message  RPC method to call
+   * @param params  Additional call parameters
+   */
+  async call(message, params) {
+    return this.network.call(message, params);
+  }
+  /**
+   * Register an error handler for the client
+   *
+   * @param handler Error handler.
+   */
+  onError(handler) {
+    this._emitError = handler;
+  }
+}
+exports.MtClient = MtClient;

package/network/client.d.cts

@@ -0,0 +1,218 @@
+import { ReconnectionStrategy } from '@fuman/net';
+import { mtp, tl } from '@mtcute/tl';
+import { TlReaderMap, TlWriterMap } from '@mtcute/tl-runtime';
+import { IMtStorageProvider } from '../storage/provider.js';
+import { StorageManagerExtraOptions, StorageManager } from '../storage/storage.js';
+import { MustEqual } from '../types/index.js';
+import { ICorePlatform } from '../types/platform.js';
+import { DcOptions, ICryptoProvider, Logger } from '../utils/index.js';
+import { NetworkManagerExtraParams, RpcCallOptions, NetworkManager } from './network-manager.js';
+import { TelegramTransport } from './transports/abstract.js';
+import { Emitter } from '@fuman/utils';
+import { ConfigManager } from './config-manager.js';
+/** Options for {@link MtClient} */
+export interface MtClientOptions {
+    /**
+     * API ID from my.telegram.org
+     */
+    apiId: number;
+    /**
+     * API hash from my.telegram.org
+     */
+    apiHash: string;
+    /**
+     * Storage to use for this client.
+     */
+    storage: IMtStorageProvider;
+    /** Additional options for the storage manager */
+    storageOptions?: StorageManagerExtraOptions;
+    /**
+     * Cryptography provider to allow delegating
+     * crypto to native addon, worker, etc.
+     */
+    crypto: ICryptoProvider;
+    platform: ICorePlatform;
+    /**
+     * Whether to use IPv6 datacenters
+     * (IPv6 will be preferred when choosing a DC by id)
+     * (default: false)
+     */
+    useIpv6?: boolean;
+    /**
+     * Primary DC to use for initial connection.
+     * This does not mean this will be the only DC used,
+     * nor that this DC will actually be primary, this only
+     * determines the first DC the library will try to connect to.
+     * Can be used to connect to other networks (like test DCs).
+     *
+     * When session already contains primary DC, this parameter is ignored.
+     *
+     * @default  Production DC 2.
+     */
+    defaultDcs?: DcOptions;
+    /**
+     * Whether to connect to test servers.
+     *
+     * If passed, {@link defaultDc} defaults to Test DC 2.
+     *
+     * **Must** be passed if using test servers, even if
+     * you passed custom {@link defaultDc}
+     */
+    testMode?: boolean;
+    /**
+     * Additional options for initConnection call.
+     * `apiId` and `query` are not available and will be ignored.
+     * Omitted values will be filled with defaults
+     */
+    initConnectionOptions?: Partial<Omit<tl.RawInitConnectionRequest, 'apiId' | 'query'>>;
+    /**
+     * Transport to use in the client.
+     *
+     * @default  platform-specific transport: WebSocket on the web, TCP in node
+     */
+    transport: TelegramTransport;
+    /**
+     * Reconnection strategy.
+     *
+     * @default  simple reconnection strategy: first 0ms, then up to 5s (increasing by 1s)
+     */
+    reconnectionStrategy?: ReconnectionStrategy;
+    /**
+     * If true, all API calls will be wrapped with `tl.invokeWithoutUpdates`,
+     * effectively disabling the server-sent events for the clients.
+     * May be useful in some cases.
+     *
+     * @default false
+     */
+    disableUpdates?: boolean;
+    /**
+     * mtcute can send all unknown RPC errors to [danog](https://github.com/danog)'s
+     * [error reporting service](https://report-rpc-error.madelineproto.xyz/).
+     *
+     * This is fully anonymous (except maybe IP) and is only used to improve the library
+     * and developer experience for everyone working with MTProto. This is fully opt-in,
+     * and if you're too paranoid, you can disable it by manually passing `enableErrorReporting: false` to the client.
+     *
+     * @default false
+     */
+    enableErrorReporting?: boolean;
+    /**
+     * Extra parameters for {@link NetworkManager}
+     */
+    network?: NetworkManagerExtraParams;
+    /**
+     * Logger instance for the client.
+     * If not passed, a new one will be created.
+     */
+    logger?: Logger;
+    /**
+     * Set logging level for the client.
+     * Shorthand for `client.log.level = level`.
+     *
+     * See static members of {@link LogManager} for possible values.
+     */
+    logLevel?: number;
+    /**
+     * **EXPERT USE ONLY!**
+     *
+     * Override TL layer used for the connection.
+     *
+     * **Does not** change the schema used.
+     */
+    overrideLayer?: number;
+    /**
+     * **EXPERT USE ONLY**
+     *
+     * Override reader map used for the connection.
+     */
+    readerMap?: TlReaderMap;
+    /**
+     * **EXPERT USE ONLY**
+     *
+     * Override writer map used for the connection.
+     */
+    writerMap?: TlWriterMap;
+}
+/**
+ * Basic MTProto client implementation, only doing the bare minimum
+ * to make RPC calls and receive low-level updates, as well as providing
+ * some APIs to manage that.
+ */
+export declare class MtClient {
+    readonly params: MtClientOptions;
+    /**
+     * Crypto provider taken from {@link MtClientOptions.crypto}
+     */
+    readonly crypto: ICryptoProvider;
+    /** Storage manager */
+    readonly storage: StorageManager;
+    /**
+     * "Test mode" taken from {@link MtClientOptions.testMode}
+     */
+    protected readonly _testMode: boolean;
+    /**
+     * Primary DCs taken from {@link MtClientOptions.defaultDcs},
+     * loaded from session or changed by other means (like redirecting).
+     */
+    _defaultDcs: DcOptions;
+    /** TL layer used by the client */
+    readonly _layer: number;
+    /** TL readers map used by the client */
+    readonly _readerMap: TlReaderMap;
+    /** TL writers map used by the client */
+    readonly _writerMap: TlWriterMap;
+    readonly _config: ConfigManager;
+    private _emitError?;
+    readonly log: Logger;
+    readonly network: NetworkManager;
+    private _abortController;
+    readonly stopSignal: AbortSignal;
+    readonly onUsable: Emitter<void>;
+    readonly onConnecting: Emitter<void>;
+    readonly onNetworkChanged: Emitter<boolean>;
+    readonly onUpdate: Emitter<tl.TypeUpdates>;
+    constructor(params: MtClientOptions);
+    emitError(err: unknown): void;
+    private _prepare;
+    /**
+     * **ADVANCED**
+     *
+     * Do all the preparations, but don't connect just yet.
+     * Useful when you want to do some preparations before
+     * connecting, like setting up session.
+     *
+     * Call {@link connect} to actually connect.
+     */
+    prepare(): Promise<void>;
+    private _connect;
+    /**
+     * Initialize the connection to the primary DC.
+     *
+     * You shouldn't usually call this method directly as it is called
+     * implicitly the first time you call {@link call}.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close all connections and finalize the client.
+     */
+    close(): Promise<void>;
+    /**
+     * Make an RPC call.
+     *
+     * The connection must have been {@link connect}-ed
+     * before calling this method.
+     *
+     * This method is still quite low-level and you shouldn't use this
+     * when using high-level API provided by `@mtcute/client`.
+     *
+     * @param message  RPC method to call
+     * @param params  Additional call parameters
+     */
+    call<T extends tl.RpcMethod>(message: MustEqual<T, tl.RpcMethod>, params?: RpcCallOptions): Promise<tl.RpcCallReturn[T['_']] | mtp.RawMt_rpc_error>;
+    /**
+     * Register an error handler for the client
+     *
+     * @param handler Error handler.
+     */
+    onError(handler: (err: unknown) => void): void;
+}

package/network/client.d.ts

@@ -1,15 +1,15 @@
-import { default as EventEmitter } from 'events';
+import { ReconnectionStrategy } from '@fuman/net';
 import { mtp, tl } from '@mtcute/tl';
 import { TlReaderMap, TlWriterMap } from '@mtcute/tl-runtime';
 import { IMtStorageProvider } from '../storage/provider.js';
 import { StorageManagerExtraOptions, StorageManager } from '../storage/storage.js';
 import { MustEqual } from '../types/index.js';
+import { ICorePlatform } from '../types/platform.js';
 import { DcOptions, ICryptoProvider, Logger } from '../utils/index.js';
-import { ConfigManager } from './config-manager.js';
 import { NetworkManagerExtraParams, RpcCallOptions, NetworkManager } from './network-manager.js';
-import { PersistentConnectionParams } from './persistent-connection.js';
-import { ReconnectionStrategy } from './reconnection.js';
-import { TransportFactory } from './transports/index.js';
+import { TelegramTransport } from './transports/abstract.js';
+import { Emitter } from '@fuman/utils';
+import { ConfigManager } from './config-manager.js';
 /** Options for {@link MtClient} */
 export interface MtClientOptions {
     /**
@@ -31,6 +31,7 @@ export interface MtClientOptions {
      * crypto to native addon, worker, etc.
      */
     crypto: ICryptoProvider;
+    platform: ICorePlatform;
     /**
      * Whether to use IPv6 datacenters
      * (IPv6 will be preferred when choosing a DC by id)
@@ -65,17 +66,17 @@ export interface MtClientOptions {
      */
     initConnectionOptions?: Partial<Omit<tl.RawInitConnectionRequest, 'apiId' | 'query'>>;
     /**
-     * Transport factory to use in the client.
+     * Transport to use in the client.
      *
      * @default  platform-specific transport: WebSocket on the web, TCP in node
      */
-    transport: TransportFactory;
+    transport: TelegramTransport;
     /**
      * Reconnection strategy.
      *
      * @default  simple reconnection strategy: first 0ms, then up to 5s (increasing by 1s)
      */
-    reconnectionStrategy?: ReconnectionStrategy<PersistentConnectionParams>;
+    reconnectionStrategy?: ReconnectionStrategy;
     /**
      * If true, all API calls will be wrapped with `tl.invokeWithoutUpdates`,
      * effectively disabling the server-sent events for the clients.
@@ -86,7 +87,7 @@ export interface MtClientOptions {
     disableUpdates?: boolean;
     /**
      * mtcute can send all unknown RPC errors to [danog](https://github.com/danog)'s
-     * [error reporting service](https://rpc.pwrtelegram.xyz/).
+     * [error reporting service](https://report-rpc-error.madelineproto.xyz/).
      *
      * This is fully anonymous (except maybe IP) and is only used to improve the library
      * and developer experience for everyone working with MTProto. This is fully opt-in,
@@ -137,7 +138,7 @@ export interface MtClientOptions {
  * to make RPC calls and receive low-level updates, as well as providing
  * some APIs to manage that.
  */
-export declare class MtClient extends EventEmitter {
+export declare class MtClient {
     readonly params: MtClientOptions;
     /**
      * Crypto provider taken from {@link MtClientOptions.crypto}
@@ -166,6 +167,10 @@ export declare class MtClient extends EventEmitter {
     readonly network: NetworkManager;
     private _abortController;
     readonly stopSignal: AbortSignal;
+    readonly onUsable: Emitter<void>;
+    readonly onConnecting: Emitter<void>;
+    readonly onNetworkChanged: Emitter<boolean>;
+    readonly onUpdate: Emitter<tl.TypeUpdates>;
     constructor(params: MtClientOptions);
     emitError(err: unknown): void;
     private _prepare;

package/network/client.js

@@ -0,0 +1,186 @@
+import { Emitter } from "@fuman/utils";
+import { tl } from "@mtcute/tl";
+import { __tlReaderMap } from "@mtcute/tl/binary/reader.js";
+import { __tlWriterMap } from "@mtcute/tl/binary/writer.js";
+import { StorageManager } from "../storage/storage.js";
+import { defaultTestIpv6Dc, defaultTestDc, defaultProductionIpv6Dc, defaultProductionDc } from "../utils/dcs.js";
+import { asyncResettable } from "../utils/function-utils.js";
+import { LogManager } from "../utils/logger.js";
+import { isTlRpcError } from "../utils/type-assertions.js";
+import "@mtcute/tl-runtime";
+import { ConfigManager } from "./config-manager.js";
+import { NetworkManager } from "./network-manager.js";
+class MtClient {
+  constructor(params) {
+    this.params = params;
+    this.log = params.logger ?? new LogManager(void 0, params.platform);
+    if (params.logLevel !== void 0) {
+      this.log.mgr.level = params.logLevel;
+    }
+    this.crypto = params.crypto;
+    this._testMode = Boolean(params.testMode);
+    let dc = params.defaultDcs;
+    if (!dc) {
+      if (params.testMode) {
+        dc = params.useIpv6 ? defaultTestIpv6Dc : defaultTestDc;
+      } else {
+        dc = params.useIpv6 ? defaultProductionIpv6Dc : defaultProductionDc;
+      }
+    }
+    this._defaultDcs = dc;
+    this._layer = params.overrideLayer ?? tl.LAYER;
+    this._readerMap = params.readerMap ?? __tlReaderMap;
+    this._writerMap = params.writerMap ?? __tlWriterMap;
+    this._abortController = new AbortController();
+    this.stopSignal = this._abortController.signal;
+    this.storage = new StorageManager({
+      provider: params.storage,
+      log: this.log,
+      readerMap: this._readerMap,
+      writerMap: this._writerMap,
+      platform: params.platform,
+      ...params.storageOptions
+    });
+    this.network = new NetworkManager(
+      {
+        apiId: params.apiId,
+        crypto: this.crypto,
+        disableUpdates: params.disableUpdates ?? false,
+        initConnectionOptions: params.initConnectionOptions,
+        layer: this._layer,
+        log: this.log,
+        readerMap: this._readerMap,
+        writerMap: this._writerMap,
+        reconnectionStrategy: params.reconnectionStrategy,
+        storage: this.storage,
+        testMode: Boolean(params.testMode),
+        transport: params.transport,
+        emitError: this.emitError.bind(this),
+        isPremium: false,
+        useIpv6: Boolean(params.useIpv6),
+        enableErrorReporting: params.enableErrorReporting ?? false,
+        onUsable: this.onUsable.emit.bind(this.onUsable),
+        onConnecting: this.onConnecting.emit.bind(this.onConnecting),
+        onNetworkChanged: this.onNetworkChanged.emit.bind(this.onNetworkChanged),
+        onUpdate: this.onUpdate.emit.bind(this.onUpdate),
+        stopSignal: this.stopSignal,
+        platform: params.platform,
+        ...params.network
+      },
+      this._config
+    );
+  }
+  /**
+   * Crypto provider taken from {@link MtClientOptions.crypto}
+   */
+  crypto;
+  /** Storage manager */
+  storage;
+  /**
+   * "Test mode" taken from {@link MtClientOptions.testMode}
+   */
+  _testMode;
+  /**
+   * Primary DCs taken from {@link MtClientOptions.defaultDcs},
+   * loaded from session or changed by other means (like redirecting).
+   */
+  _defaultDcs;
+  /** TL layer used by the client */
+  _layer;
+  /** TL readers map used by the client */
+  _readerMap;
+  /** TL writers map used by the client */
+  _writerMap;
+  _config = new ConfigManager(async () => {
+    const res = await this.call({ _: "help.getConfig" });
+    if (isTlRpcError(res)) throw new Error(`Failed to get config: ${res.errorMessage}`);
+    return res;
+  });
+  _emitError;
+  log;
+  network;
+  _abortController;
+  stopSignal;
+  onUsable = new Emitter();
+  onConnecting = new Emitter();
+  onNetworkChanged = new Emitter();
+  onUpdate = new Emitter();
+  emitError(err) {
+    if (this._emitError) {
+      this._emitError(err);
+    } else if (this._connect.finished()) {
+      this.log.error("unhandled error:", err);
+    }
+  }
+  _prepare = asyncResettable(async () => {
+    await this.crypto.initialize?.();
+    await this.storage.load();
+    const primaryDc = await this.storage.dcs.fetch();
+    if (primaryDc !== null) this._defaultDcs = primaryDc;
+  });
+  /**
+   * **ADVANCED**
+   *
+   * Do all the preparations, but don't connect just yet.
+   * Useful when you want to do some preparations before
+   * connecting, like setting up session.
+   *
+   * Call {@link connect} to actually connect.
+   */
+  prepare() {
+    return this._prepare.run();
+  }
+  _connect = asyncResettable(async () => {
+    await this._prepare.run();
+    await this.network.connect(this._defaultDcs);
+  });
+  /**
+   * Initialize the connection to the primary DC.
+   *
+   * You shouldn't usually call this method directly as it is called
+   * implicitly the first time you call {@link call}.
+   */
+  async connect() {
+    return this._connect.run();
+  }
+  /**
+   * Close all connections and finalize the client.
+   */
+  async close() {
+    this.log.debug("closing client");
+    this._config.destroy();
+    await this.network.destroy();
+    await this.storage.save();
+    await this.storage.destroy?.();
+    this._prepare.reset();
+    this._connect.reset();
+    this._abortController.abort();
+    this.log.debug("client closed successfully");
+  }
+  /**
+   * Make an RPC call.
+   *
+   * The connection must have been {@link connect}-ed
+   * before calling this method.
+   *
+   * This method is still quite low-level and you shouldn't use this
+   * when using high-level API provided by `@mtcute/client`.
+   *
+   * @param message  RPC method to call
+   * @param params  Additional call parameters
+   */
+  async call(message, params) {
+    return this.network.call(message, params);
+  }
+  /**
+   * Register an error handler for the client
+   *
+   * @param handler Error handler.
+   */
+  onError(handler) {
+    this._emitError = handler;
+  }
+}
+export {
+  MtClient
+};