@telepilotco/tdl

This fork of bannerets/tdl does not change source code,
but modifies Github Actions build pipeline to extend environments that are supported.

Following environments are supported:
- [x] linux-x64-glibc
- [x] linux-x64-musl
- [x] linux-arm64-glibc
- [x] linux-arm64-musl
- [ ] win-x64 - disabled due to https://github.com/telepilotco/tdl/issues/4
- [x] darwin-x64
- [x] darwin-arm64

tdl

tdl is a fairly simple JavaScript wrapper for [TDLib][] (Telegram Database library),
a library to create [Telegram][] clients or bots.

TDLib version 1.5.0 or newer is required.

[TDLib]: https://github.com/tdlib/td
[Telegram]: https://telegram.org/

- Requirements
- Installation
- Getting started
- API
- Types
- Other JavaScript runtimes
- Possible errors

Requirements

- Node.js v12.11.0 or newer (>= v16 recommended)
- The tdjson shared library (libtdjson.so on Linux, libtdjson.dylib on macOS, tdjson.dll on Windows)
- In some cases, a C++ compiler and Python installed to build the node addon[^1]

[^1]: tdl is packaged with pre-built addons for Windows (x86_64), GNU/Linux (x86_64, glibc >= 2.17), and macOS (x86_64, aarch64). If a pre-built binary is not available for your system, then the node addon will be built using node-gyp, requiring Python and a C++ toolchain (C++14 is required) to be installed (on Windows, MSVS or Build Tools). Pass --build-from-source to never use the pre-built binaries. Note that macOS aarch64 binaries aren't tested.

Installation

1. Build TDLib (https://github.com/tdlib/td#building) or install pre-built
libraries
2. Run npm install tdl
3. (optional) If you use TypeScript, types for TDLib are installed separately,
see the Types section

To use tdl, you need to get TDLib first. The tdjson shared library should be
present in the system search paths (otherwise the path to libtdjson can be
specified manually).

> Note: When building TDLib, the libraries can be installed into the system
> using cmake --install . (optionally specify the --prefix option, the
> default is /usr/local) after TDLib has been built successfully. This command
> may require sudo.

$3

Instead of building TDLib from source, you can possibly install pre-built TDLib libraries distributed through the prebuilt-tdlib npm package. To install prebuilt-tdlib for e.g. TDLib v1.8.19, run npm install prebuilt-tdlib@td-1.8.19 (the available versions of prebuilt-tdlib can be found by running npm info prebuilt-tdlib dist-tags). An example of using libraries from prebuilt-tdlib is present in the section below. The supported systems are x86_64 GNU/Linux, x86_64 & arm64 macOS, and x86_64 Windows. See the README of [prebuilt-tdlib][] for additional information.

[prebuilt-tdlib]: packages/prebuilt-tdlib/README.md

Getting started

``javascript
const tdl = require('tdl')

// If libtdjson is not present in the system search paths, the path to the
// libtdjson shared library can be set manually, e.g.:
// tdl.configure({ tdjson: '/usr/local/lib/libtdjson.dylib' })
// The library directory can be set separate from the library name,
// example to search for libtdjson in the directory of the current script:
// tdl.configure({ libdir: __dirname })

// Instead of building TDLib yourself, the aforementioned prebuilt-tdlib can be used as follows:
// const { getTdjson } = require('prebuilt-tdlib')
// tdl.configure({ tdjson: getTdjson() })

const client = tdl.createClient({
apiId: 2222, // Your api_id
apiHash: '0123456789abcdef0123456789abcdef' // Your api_hash
})
// Passing apiId and apiHash is mandatory, these values can be obtained at https://my.telegram.org/

client.on('error', console.error)

// Aside of receiving responses to your requests, the server can push to you
// events called "updates" which ar received as follows:
client.on('update', update => {
console.log('Got update:', update)
})

async function main () {
// Log in to a Telegram account. By default, with no arguments, this function will
// ask for phone number etc. in the console. Instead of logging in as a user,
// it's also possible to log in as a bot using client.loginAsBot('').
await client.login()

// Invoke a TDLib method. The information regarding TDLib method list and
// documentation is below this code block.
const me = await client.invoke({ _: 'getMe' })
console.log('My user:', me)

// Invoke some other TDLib method.
const chats = await client.invoke({
_: 'getChats',
chat_list: { _: 'chatListMain' },
limit: 10
})
console.log('A part of my chat list:', chats)

// Close the instance so that TDLib exits gracefully and the JS runtime can finish the process.
await client.close()
}

main().catch(console.error)
`

The API list of TDLib methods, which are called using client.invoke, can be found at, e.g.:
- https://core.telegram.org/tdlib/docs/annotated.html (possibly outdated)
- or in the [td_api.tl][] file in the TDLib repository.

[td_api.tl]: https://github.com/tdlib/td/blob/2589c3fd46925f5d57e4ec79233cd1bd0f5d0c09/td/generate/scheme/td_api.tl

In the TDLib documentation, the bytes type means a base64-encoded string.
int64 accepts either a number or a string, pass string for large numbers.
int32, int53, and double are the number JS type. If TypeScript types are
installed, note that the types are annotated with jsdoc comments, and the
documentation can be browsed directly in the .d.ts file or in the
autocompletion menu.

See also https://core.telegram.org/tdlib/getting-started for some basic
information on how to use TDLib (tdl handles the authorization part with
client.login). Note that the TDLib JSON interface actually sends a @type
field, but tdl renames it to _.

Some short examples are available in the examples/ directory.

API

> Note: A more exhaustive documentation is available in the
> TypeScript typings file.

#### tdl.configure(options: TDLibConfiguration) => void

Configure several parameters such as libtdjson name or verbosity level. This
function should be called before tdl.createClient or tdl.execute.

`javascript
tdl.configure({
// Path to the library. By default, it is 'tdjson.dll' on Windows,
// 'libtdjson.dylib' on macOS, or 'libtdjson.so' otherwise.
tdjson: 'libtdjson.so',
// Path to the library directory. By default, it is empty string.
libdir: '/usr/local/lib',
// Verbosity level of TDLib. By default, it is 2.
verbosityLevel: 3,
// Experimental option. Disabled by default.
useNewTdjsonInterface: false
})
`

Some examples:
- tdl.configure({ tdjson: '/root/libtdjson.so', verbosityLevel: 5 })
- tdl.configure({ tdjson: 'libtdjson.dylib.1.8.6', libdir: '/usr/local/lib' })
- tdl.configure({ libdir: __dirname })
- tdl.configure({ tdjson: require('prebuilt-tdlib').getTdjson() })

The path concatenation of libdir + tdjson is directly passed to
[dlopen][dlopen] (Unix) or [LoadLibrary][LoadLibraryW] (Windows). Check your
OS documentation to find out where the shared library will be searched for.

#### tdl.createClient(options: ClientOptions) => Client

Create a TDLib client.

`javascript
const client = tdl.createClient({
apiId: 2222, // Your api_id
apiHash: '0123456789abcdef0123456789abcdef' // Your api_hash
// ... other options ...
})
`

The interface of the options that can be passed here:

`typescript
type ClientOptions = {
apiId: number, // Can be obtained at https://my.telegram.org
apiHash: string, // Can be obtained at https://my.telegram.org
databaseDirectory: string, // Relative path (defaults to '_td_database')
filesDirectory: string, // Relative path (defaults to '_td_files')
databaseEncryptionKey: string, // Optional key for database encryption
useTestDc: boolean, // Use test telegram server (defaults to false)
tdlibParameters: Object, // Raw TDLib parameters
// Advanced options:
bare: boolean,
skipOldUpdates: boolean
}
`

Of these fields, only apiId and apiHash are required. Any other field can be
omitted.

The tdlibParameters option is described in
https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1tdlib_parameters.html.

By default, in tdl, tdlibParameters is set to:

`javascript
tdlibParameters: {
use_message_database: true,
use_secret_chats: false,
system_language_code: 'en',
application_version: '1.0',
device_model: 'Unknown device',
system_version: 'Unknown',
enable_storage_optimizer: true,
api_id: options.apiId,
api_hash: options.apiHash,
database_directory: options.databaseDirectory,
files_directory: options.filesDirectory,
use_test_dc: options.useTestDc
}
`

In a real application, you probably want to change device_model and other
parameters.

#### client.login(fn?: () => LoginDetails) => Promise

Log in to your Telegram account.

`javascript
await client.login()
`

By default, tdl asks the user for the phone number, auth code, and 2FA
password (if needed) in the console. You can override the defaults with custom
functions, for example:

`javascript
// Example
await client.login(() => ({
getPhoneNumber: retry => retry
? Promise.reject('Invalid phone number')
: Promise.resolve('+9996620001'),
getAuthCode: retry => retry
? Promise.reject('Invalid auth code')
: Promise.resolve('22222'),
getPassword: (passwordHint, retry) => retry
? Promise.reject('Invalid password')
: Promise.resolve('abcdef'),
getName: () => Promise.resolve({ firstName: 'John', lastName: 'Doe' })
}))
`

The getName function is called if the user is not signed up.

client.login supports only a subset of authentication methods available on
Telegram. It is possible (and advisable for larger apps) not to use the
client.login helper and implement the authorization process manually, handling
authorizationStateWaitPhoneNumber and other updates.

This function accepts the following interface:

`typescript
type LoginDetails = {
type?: 'user',
getPhoneNumber?: (retry?: boolean) => Promise,
getEmailAddress?: () => Promise,
getEmailCode?: () => Promise,
confirmOnAnotherDevice?: (link: string) => void,
getAuthCode?: (retry?: boolean) => Promise,
getPassword?: (passwordHint: string, retry?: boolean) => Promise,
getName?: () => Promise<{ firstName: string, lastName?: string }>
} | {
type: 'bot',
getToken: (retry?: boolean) => Promise
}
// Note that client.login accepts a function that returns the object, not the
// object directly. The function will not be called if the client is already
// authorized.
declare function login (fn?: () => LoginDetails): Promise
`

getEmailAddress and getEmailCode are called in TDLib >= v1.8.6 only.

#### client.loginAsBot(token: string | (() => string | Promise)) => Promise

Instead of logging in as a user, you can log in as a bot by token.

`javascript
await client.loginAsBot('YOUR_BOT_TOKEN') // Enter your token from @BotFather
`

#### client.on(event: string, callback: Function) => Client

Attach an event listener to receive updates and other events.

`javascript
function onUpdate (update) {
console.log('New update:', update)
}
client.on('update', onUpdate)
client.on('error', console.error)
`

Ideally, you should always have a listener on client.on('error').
There is no default listener, all errors will be ignored otherwise.

You can consider using reactive libraries like RxJS or most.js for convenient
event processing.

Some other rarely-used events also exist and are described in the TypeScript
interface.

client.addListener is an alias for client.on.

#### client.once(event: string, callback: Function) => Client

Attach a one-time listener.

#### client.off(event: string, listener: Function, once?: boolean) => Client

Remove an event listener.

`javascript
const listener = u => {
console.log('New update:', u)
if (u?.authorization_state?._ === 'authorizationStateReady')
client.off('update', listener) // Removes the listener
}
client.on('update', listener)
`

client.removeListener is an alias for client.off.

#### client.invoke(query: Object) => Promise