airgram-dev v2.2.2

Airgram

Awesome wrapper for TDLib (TypeScript/JavaScript, NodeJS).

You may also be interested in:

• MTProto implementation
• Version for browsers

Features

• Strictly typed;
• Documentation out of the box;
• Supports models;
• Built on middleware;
• Authorization helper;

All TDLib classes and methods are described and have suitable wrappers in There are only two differences:

• All parameter names are represent in "camelCase".
• Parameter @type renamed to _.

Requirements

• TDLib v1.4.0
• NodeJS

Documentation

• Installation
• Getting started
• Configuration
• Api reference
• Authorization
• Middleware
• Getting updates

• TDLib methods
• TDLib input types
• TDLib output types

Installation

1. Build TDLib library according the instruction.
2. Install Airgram:

# npm
npm install airgram

# yarn
yarn add airgram

Getting started

Please check out an example.

Basic usage:

import { Airgram, Auth, prompt } from 'airgram'

const airgram = new Airgram({
  apiId: Number(process.env.APP_ID!),
  apiHash: process.env.APP_HASH!,
  logVerbosityLevel: 2
})

const auth = new Auth(airgram)

auth.use({
  code: () => prompt(`Please enter the secret code:\n`),
  phoneNumber: () => prompt(`Please enter your phone number:\n`)
})

// Call Telegram method
airgram.api.getMe().then((response) => {
  console.info(response)
})

// Getting all updates
airgram.updates.use(({ update }, next) => {
  if(update) {
    console.log(`"${update._}" ${JSON.stringify(update)}`)
  }
  return next()
})

// Get only new message updates
airgram.updates.on('updateNewMessage', ({ update }, next) => {
  console.info(update)
  return next
})

Configuration

This section describes the options you can pass to Airgram constructor:

import { Airgram } from 'airgram'

const airgram = new Airgram({
  // options
})

TDLib options

Other options

API reference

This section describes public API of an Airgram instance:

Authorization

As a bot

Just specify a secret token by Auth constructor:

import { Airgram, Auth } from 'airgram'

const airgram = new Airgram(/* options */)

new Auth(airgram, {
  token: 'xxx'
})

As a user

Airgram provides component Auth, which implements basic logic for authorization or registration new Telegram accounts. User just needs to specify the phone number, secret code and some other data, if necessary.

import { Airgram, Auth } from 'airgram'

const airgram = new Airgram()
const auth = new Auth(airgram)

auth.use({
  phoneNumber: '+1234567890',
  firstName: 'John',
  lastName: 'Smith'
})

Method auth.use() takes config:

type AuthAnswer = string | (() => string) | (() => Promise<string>)

interface AuthDialog {
  code?: AuthAnswer
  firstName?: AuthAnswer
  lastName?: AuthAnswer,
  phoneNumber?: AuthAnswer
  password?: AuthAnswer
}

You can use helper prompt to communicate with user by the command line:

import { prompt } from 'airgram'

auth.use({
  code: () => prompt(`Please enter the secret code:\n`),
  phoneNumber: () => prompt(`Please enter your phone number:\n`)
})

Authorization callback

If you want to ensure the code will execute only after successful authorization, you can use auth.ready() method:

auth.ready().then(() => {
  console.log('Success!')
})

// or pass callback
auth.ready(() => {
  console.log('Success!')
})

Middleware

Middleware is a chain of callback functions, which are called before a request is send to TDLib. Middleware allows you modify requests and responses to add some additional logic. Middlewares also are using to handle updates.

This is a scaffolding for middleware function:

import { UPDATE } from '@airgram/api'

airgram.use((ctx, next) => {
  
  // Add some code here
  
  return next()
})

// You can pass an array of predicates: `['updateNewChat', 'updateSupergroup']`
airgram.on(UPDATE.updateNewChat, (ctx, next) => {
  
  // Add some code here
  
  return next()
})

Tip: in the example above we took predicate's value from the UPDATE directory instead of using string value updateNewChat, because this way protects us from typos and we can use IDE autocomplete.

Function takes 2 arguments: ctx and next.

ctx

Argument ctx contains an object with the following structure:

You can extend default context by define contextFactory:

import { Airgram, createContext, User } from 'airgram'
import { UPDATE } from '@airgram/api'

interface Context extends Context {
  getUser (id: number): User | void
  setUser (id: number, user: User): void
}

const userMap: Map<number, User> = new Map()

const contextFactory: ContextFactory = () => {
  return (options: ContextOptions): Context => ({
    ...createContext(options),
    getUser (id: number): User | void {
      return userMap.get(id)
    },
    setUser (id: number, user: User): void {
      userMap.set(id, user)
    }
  })
}

const airgram = new Airgram<Context>({
  contextFactory
})

airgram.updates.on(UPDATE.updateUser, ({ setUser, update }, next) => {
  setUser(update.user.id, update.user)
  return next()
})

airgram.updates.on(UPDATE.updateNewMessage, async ({ getUser, update }) => {
  const user = getUser(update.message.senderUserId)

  if (!user) {
    throw new Error('Unknown user')
  }

  console.log(`${user.username}: ${JSON.stringify(update.message)}`)
})

Since middlewares are meant to be composed, they need an easy way to send metadata about the request down the chain of middleware. To accomplish this, each middleware context has a state object. The state is read by using ctx.getState() and written using ctx.setState(newState) or ctx.setState((prevState) => newState). The API of setState is meant to be similar to React's one. For example:

airgram.use(({ setState }, next) => {
  setState({ foo: 'bar' })
  return next()
})

airgram.use(async ({ getState }) => {
  console.log(`foo = ${getState().foo}`);
  // output: foo = bar
})

Each state can be set by the last argument of the request:

// We can set starting state by the last argument
airgram.api.getChats({limit: 10}, {log: true})

airgram.on('getChats', async ({ _, getState }, next) => {
  if(!getState().log) {
    return next()
  }
  const start = new Date()
  await next()
  const time = new Date() - start;
  console.log(`Request "${_}" took ${time} to complete.`);
})

next

The second argument next is a function which runs the next handler.

Function next() returns a promise Promise<any>, so we can use the next handlers result inside of our middleware:

airgram.use(async (ctx, next) => {
  const start = new Date()
  const { request } = ctx
  const result = await next()
  console.log(`Method: ${request.method}, params: ${JSON.stringify(request.params)}, result: ${JSON.stringify(result)}, ${new Date() - start}ms`)
})

Class as a middleware

Sometimes middleware may be pretty complicated or you want to reuse the code. In this case the most suitable way is to create new class (or use existing) and pass it to use() or on() methods.

Your class must have a middleware() factory method:

class MiddlewareClass {
  handle(ctx) {
    // do some work
  }
  
  middleware() {
    return (ctx, next) => {
      this.handle(ctx)
      return next()
    }
  }
}

airgram.use(new MiddlewareClass())

All methods describes here.

Getting updates

Use methods airgram.updates.use() and airgram.updates.on() to handle updates. It works almost the same as airgram.use() and airgram.on(), but there are two differences:

1. By using airgram.updates.use() and airgram.updates.on() methods, callbacks won't be called for requests;
2. Improved typings for updates.

License

The source code is licensed under GPL v3. License is available here.