From 6756c7806501cc6a55bbf6e48e0beb47e076a0e2 Mon Sep 17 00:00:00 2001 From: Alina Sireneva Date: Wed, 6 Mar 2024 21:20:44 +0300 Subject: [PATCH] docs: updated readmes --- packages/core/README.md | 29 +++++++++++++++++++--- packages/crypto-node/README.md | 2 +- packages/dispatcher/README.md | 6 ++--- packages/file-id/README.md | 2 +- packages/node/README.md | 14 +++++++---- packages/node/typedoc.cjs | 2 +- packages/web/README.md | 44 ++++++++++++++++++++++++++++------ packages/web/typedoc.cjs | 5 +--- 8 files changed, 79 insertions(+), 25 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index b651d5f3..4359df16 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -2,25 +2,48 @@ 📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_core.html) -Basic low-level MTProto implementation and auxiliary utilities. +Platform-agnostic MTProto implementation and auxiliary utilities. ## Features - **MTProto 2.0**: Implements the full MTProto protocol, including all the encryption and serialization - **2FA support**: Provides utilities for 2-step verification - **Hackable**: Bring your own storage, transport, and other components to customize the library to your needs - **Magical**: Handles reconnections, connection pooling, DC redirections and other stuff for you -- **Web support**: Works in the browser with no additional configuration +- **Updates handling**: Implements proper updates handling, including ordering and gap recovery (learn more) +- **High-level**: Includes a high-level API that wrap the MTProto APIs and provide a clean interface +- **Tree-shaking**: You can import just the methods you need, and the rest will not be included into the bundle ## Usage ```ts -import { BaseTelegramClient } from '@mtcute/core' +import { BaseTelegramClient } from '@mtcute/core/client.js' const tg = new BaseTelegramClient({ apiId: 12345, apiHash: '0123456789abcdef0123456789abcdef', + crypto: new MyCryptoProvider(), + storage: new MyStorage(), + transport: () => new MyTransport(), }) tg.call({ _: 'help.getConfig' }) .then(console.log) ``` + +## Usage with high-level API + +```ts +import { TelegramClient } from '@mtcute/core/client.js' + +const tg = new TelegramClient({ + // ... same options as above +}) + +tg.run({ + phone: '+1234567890', + code: () => prompt('Enter the code:'), + password: 'my-password', +}, async (user) => { + console.log(`✨ logged in as ${user.displayName}`) +}) +``` \ No newline at end of file diff --git a/packages/crypto-node/README.md b/packages/crypto-node/README.md index cec1634e..fab03468 100644 --- a/packages/crypto-node/README.md +++ b/packages/crypto-node/README.md @@ -16,7 +16,7 @@ Then, install the package as usual. The native library will be built automatical ## Usage ```typescript -import { TelegramClient } from '@mtcute/client' +import { TelegramClient } from '@mtcute/core' import { NodeNativeCryptoProvider } from '@mtcute/crypto-node' const tg = new TelegramClient({ diff --git a/packages/dispatcher/README.md b/packages/dispatcher/README.md index 1d92b832..68dfcf55 100644 --- a/packages/dispatcher/README.md +++ b/packages/dispatcher/README.md @@ -3,7 +3,7 @@ 📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_dispatcher.html) 🧐 [Guide](https://mtcute.dev/guide/dispatcher/intro.html) -Dispatcher and bot framework based on @mtcute/client. +Dispatcher and bot framework based on @mtcute/core. ## Features - **Straightforward**: Simple and expressive API @@ -15,9 +15,9 @@ Dispatcher and bot framework based on @mtcute/client. ## Usage ```ts -import { NodeTelegramClient, Dispatcher } from '@mtcute/node' +import { TelegramClient, Dispatcher } from '@mtcute/node' -const tg = new NodeTelegramClient({ ... }) +const tg = new TelegramClient({ ... }) const dp = Dispatcher.for(tg) dp.onNewMessage(async (msg) => { diff --git a/packages/file-id/README.md b/packages/file-id/README.md index 04e4929f..c080b07b 100644 --- a/packages/file-id/README.md +++ b/packages/file-id/README.md @@ -2,7 +2,7 @@ 📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_file_id.html) -This package is used internally by `@mtcute/client` to parse, serialize +This package is used internally by `@mtcute/core` to parse, serialize and manipulate TDLib and Bot API compatible File IDs, but can also be used for any other purposes. diff --git a/packages/node/README.md b/packages/node/README.md index fe07677a..2ed08606 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -2,16 +2,20 @@ 📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_node.html) -All-in-one package for NodeJS. Includes support for native crypto addon -(must be installed separately, `@mtcute/crypto-node`), terminal I/O via -`readline` and includes HTML and Markdown parsers. +Node.js support package for mtcute. Includes: +- Support for native crypto addon (must be installed separately, `@mtcute/crypto-node`) +- Terminal I/O via `readline` +- SQLite storage (`@mtcute/sqlite`) +- TCP transport +- `TelegramClient` implementation using the above +- HTML and Markdown parsers ## Usage ```typescript -import { NodeTelegramClient } from '@mtcute/node' +import { TelegramClient } from '@mtcute/node' -const tg = new NodeTelegramClient({ +const tg = new TelegramClient({ apiId: 12345, apiHash: 'abcdef', storage: 'my-account' diff --git a/packages/node/typedoc.cjs b/packages/node/typedoc.cjs index cc62716c..e1f51e65 100644 --- a/packages/node/typedoc.cjs +++ b/packages/node/typedoc.cjs @@ -1,6 +1,6 @@ module.exports = { extends: ['../../.config/typedoc/config.base.cjs'], - entryPoints: ['./index.ts'], + entryPoints: ['./src/index.ts'], externalPattern: [ '../core/**', '../html-parser/**', diff --git a/packages/web/README.md b/packages/web/README.md index fe07677a..8b8b91b1 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -1,17 +1,19 @@ -# @mtcute/node +# @mtcute/web -📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_node.html) +📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_web.html) -All-in-one package for NodeJS. Includes support for native crypto addon -(must be installed separately, `@mtcute/crypto-node`), terminal I/O via -`readline` and includes HTML and Markdown parsers. +Web support package for mtcute. Includes: +- WASM crypto provider +- Websocket transport +- IndexedDB storage +- `TelegramClient` implementation using the above ## Usage ```typescript -import { NodeTelegramClient } from '@mtcute/node' +import { TelegramClient } from '@mtcute/web' -const tg = new NodeTelegramClient({ +const tg = new TelegramClient({ apiId: 12345, apiHash: 'abcdef', storage: 'my-account' @@ -21,3 +23,31 @@ tg.run(async (user) => { console.log(`✨ logged in as ${user.displayName}`) }) ``` + +## Usage with workers + +You can also use this package with web workers to offload most of the heavy lifting to a separate thread: + +```typescript +// worker.ts +import { BaseTelegramClient, TelegramWorker } from '@mtcute/web' + +const client = new BaseTelegramClient({ + apiId: 12345, + apiHash: 'abcdef', + storage: 'my-account' +}) + +new TelegramWorker({ client }) + +// main.ts +import { TelegramClient, TelegramWorkerPort } from '@mtcute/web' + +const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }) // or SharedWorker +const port = new TelegramWorkerPort({ worker }) +const tg = new TelegramClient({ client: port }) + +tg.run({}, async (user) => { + console.log(`✨ logged in as ${user.displayName}`) +}) +``` \ No newline at end of file diff --git a/packages/web/typedoc.cjs b/packages/web/typedoc.cjs index cc62716c..51819f4f 100644 --- a/packages/web/typedoc.cjs +++ b/packages/web/typedoc.cjs @@ -1,10 +1,7 @@ module.exports = { extends: ['../../.config/typedoc/config.base.cjs'], - entryPoints: ['./index.ts'], + entryPoints: ['./src/index.ts'], externalPattern: [ '../core/**', - '../html-parser/**', - '../markdown-parser/**', - '../sqlite/**', ], }