docs(): update docs

This commit is contained in:
Alexander Bukhalo 2021-01-02 03:10:25 +03:00
parent 03b17a0cdb
commit a6ddfb7d02
7 changed files with 133 additions and 7 deletions

View File

@ -8,7 +8,9 @@ export * as Extra from 'telegraf/extra';
export * from './decorators'; export * from './decorators';
export * from './interfaces'; export * from './interfaces';
export * from './utils';
export * from './telegraf.module'; export * from './telegraf.module';
export { Telegraf } from 'telegraf';
/** /**
* Backward compatibility with versions < 1.4.0, * Backward compatibility with versions < 1.4.0,

View File

@ -8,10 +8,10 @@ slug: /bot-injection
At times you may need to access the native `Telegraf` instance. For example, you may want to connect stage middleware. You can inject the Telegraf by using the `@InjectBot()` decorator as follows: At times you may need to access the native `Telegraf` instance. For example, you may want to connect stage middleware. You can inject the Telegraf by using the `@InjectBot()` decorator as follows:
```typescript ```typescript
import { Injectable } from '@nestjs/common'; import { Injectable } from '@nestjs/common';
import { InjectBot, TelegrafProvider } from 'nestjs-telegraf'; import { InjectBot, TelegrafProvider, Context } from 'nestjs-telegraf';
@Injectable() @Injectable()
export class BotSettingsService { export class BotSettingsService {
constructor(@InjectBot() private bot: TelegrafProvider) {} constructor(@InjectBot() private bot: TelegrafProvider<Context>) {}
} }
``` ```

View File

@ -0,0 +1,31 @@
---
id: error-handling
title: Error handling
sidebar_label: Error handling
slug: /error-handling
---
By default, `nestjs-telegraf` catches all errors using the `Logger` built into NestJS.
Use can disable global errors catch with `disableGlobalCatch`:
```typescript
TelegrafModule.forRoot({
disableGlobalCatch: true,
}),
```
After that you can override errors handling with bot instance `catch` function.
```typescript
import { Injectable } from '@nestjs/common';
import { InjectBot, TelegrafProvider, Context } from 'nestjs-telegraf';
@Injectable()
export class BotSettingsService {
constructor(@InjectBot() private bot: TelegrafProvider<Context>) {
this.bot.catch((err, ctx) => {
console.log(`Ooops, encountered an error for ${ctx.updateType}`, err);
});
}
}
```

View File

@ -11,23 +11,26 @@ By default, the bot receives updates using long-polling and requires no addition
## Webhooks ## Webhooks
If you want to configure a telegram bot webhook, you need to get a middleware from `TelegrafProvider` for connect it in your `main.ts` file. If you want to configure a telegram bot webhook, you need to get a middleware via `getBotToken` helper in your `main.ts` file.
To access it, you must use the `app.get()` method, followed by the provider reference: To access it, you must use the `app.get()` method, followed by the provider reference:
```typescript ```typescript
const telegrafProvider = app.get('TelegrafProvider'); import { getBotToken } from 'nestjs-telegraf';
// ...
const bot = app.get(getBotToken());
``` ```
Now you can connect middleware: Now you can connect middleware:
```typescript ```typescript
app.use(telegrafProvider.webhookCallback('/secret-path')); app.use(bot.webhookCallback('/secret-path'));
``` ```
The last step is to specify launchOptions in `forRoot` method: The last step is to specify launchOptions in `forRoot` method:
```typescript ```typescript
TelegrafModule.forRootAsync({ TelegrafModule.forRootAsync({
imports: [ConfigModule.forFeature(telegrafModuleConfig)], imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({ useFactory: (configService: ConfigService) => ({
token: configService.get<string>('TELEGRAM_BOT_TOKEN'), token: configService.get<string>('TELEGRAM_BOT_TOKEN'),
launchOptions: { launchOptions: {
webhook: { webhook: {

View File

@ -0,0 +1,13 @@
---
id: middlewares
title: Middlewares
sidebar_label: Middlewares
slug: /middlewares
---
`nestjs-telegraf` has support of the Telegraf middleware packages. To use an existing middleware package, simply import it and add it to the middlewares array:
```typescript
TelegrafModule.forRoot({
middlewares: [session()],
}),
```

View File

@ -0,0 +1,74 @@
---
id: multiple-bots
title: Multiple bots
sidebar_label: Multiple bots
slug: /multiple-bots
---
In some cases, you may need to run multiple bots at the same time. This can also be achieved with this module. To work with multiple bots, first create the bots. In this case, bot naming becomes mandatory.
```typescript
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { TelegrafModule } from 'nestjs-telegraf';
@Module({
imports: [
ConfigModule.forRoot(),
TelegrafModule.forRootAsync({
imports: [ConfigModule],
botName: 'cat',
useFactory: (configService: ConfigService) => ({
token: configService.get<string>('CAT_BOT_TOKEN'),
}),
inject: [ConfigService],
}),
TelegrafModule.forRootAsync({
imports: [ConfigModule.forFeature(telegrafModuleConfig)],
botName: 'dog',
useFactory: async (configService: ConfigService) => ({
token: configService.get<string>('DOG_BOT_TOKEN'),
}),
inject: [ConfigService],
}),
],
})
export class AppModule {}
```
:::caution
Please note that you shouldn't have multiple bots without a name, or with the same name, otherwise they will get overridden.
:::
You can also inject the `Bot` for a given bot:
```typescript
import { Injectable } from '@nestjs/common';
import { InjectBot, Telegraf, Context } from 'nestjs-telegraf';
@Injectable()
export class EchoService {
constructor(@InjectBot('cat') private catBot: Telegraf<Context>) {}
}
```
To inject a given `Bot` to a custom provider (for example, factory provider), use the `getBotToken()` function passing the name of the bot as an argument.
```typescript
{
provide: CatsService,
useFactory: (catBot: Telegraf<Context>) => {
return new CatsService(catBot);
},
inject: [getBotToken('cat')],
}
```
Another useful feature of the `nestjs-telegraf` module is the ability to choose which modules should handle updates for each launched bot. By default, module searches for handlers throughout the whole app. To limit this scan to only a subset of modules, use the include property.
```typescript
TelegrafModule.forRootAsync({
imports: [ConfigModule],
botName: 'cat',
useFactory: (configService: ConfigService) => ({
token: configService.get<string>('CAT_BOT_TOKEN'),
include: [CatsModule],
}),
inject: [ConfigService],
}),
```

View File

@ -6,6 +6,9 @@ module.exports = {
'telegraf-methods', 'telegraf-methods',
'bot-injection', 'bot-injection',
'async-configuration', 'async-configuration',
'multiple-bots',
'middlewares',
'error-handling',
], ],
Extras: ['extras/standalone-applications'], Extras: ['extras/standalone-applications'],
'API Reference': ['api-reference/decorators'], 'API Reference': ['api-reference/decorators'],