docs: add real readme

This commit is contained in:
Igor Kamyshev 2019-07-16 18:56:02 +03:00
parent 7df14bcfe9
commit d2a79f8de1
2 changed files with 151 additions and 3 deletions

142
README.md
View File

@ -8,6 +8,146 @@ Integrate [telegraf.js](https://telegraf.js.org/) to [NestJS](https://nestjs.com
`yarn add nest-telegram` `yarn add nest-telegram`
## Setup
### Add TelegramModule to your app
```ts
import { TelegramModule, TelegramModuleOptionsFactory } from 'nest-telegram'
// In real app, please, don't store token in source code
class TelegramOptionsFactory implements TelegramModuleOptionsFactory {
createOptions(): TelegramModuleOptions {
return {
token: 'TelegramToken#1213',
sitePublicUrl: 'https://my-site.com',
}
}
}
@Module({
imports: [
TelegramModule.fromFactory({,
useClass: TelegramOptionsFactory,
}),
UtilsModule,
],
})
export class MyModule implements NestModule {
constructor(
private readonly moduleRef: ModuleRef,
private readonly telegramBot: TelegramBot,
) {}
onModuleInit() {
const isDev = process.env.NODE_ENV === 'development'
this.telegramBot.init(this.moduleRef)
if (isDev) {
// in dev mode, we can't use webhook
this.telegramBot.startPolling()
}
}
// ...
}
```
### Add custom middleware to your app
```ts
import { TelegramBot } from 'nest-telegram'
import { NestFactory } from '@nestjs/core'
import { AppModule } from '@app/app.module'
async function bootstrap() {
const isDev = process.env.NODE_ENV === 'development'
const app = await NestFactory.create(AppModule)
const bot = app.get(TelegramBot)
if (!isDev) {
app.use(bot.getMiddleware('hook-path'))
}
await app.listen(3000)
}
bootstrap()
```
## Usage ## Usage
blah-blah-blah Now, you can decorate any method with `TelegramActionHandler`.
Example:
```ts
import { Injectable } from '@nestjs/common'
import { Context, PipeContext, TelegramActionHandler } from 'nest-telegram'
@Injectable()
export class HelpActions {
@TelegramActionHandler({ onStart: true })
async start(ctx: Context) {
await ctx.reply('Hello!')
}
}
```
Available actions for decorator:
+ `onStart` {boolean}, it triggers on `/start` command.
+ `command` {string}, it triggers on any command, e.g. — `@TelegramActionHandler({ command: '/help' })`.
+ `message` {string|RegExp}, it triggers on text message matching RegExp or string.
Also, you can write Transformators for context (like Pipes in NestJS). Example:
```ts
import { Injectable } from '@nestjs/common'
import { ContextTransformer, Context } from 'nest-telegram'
@Injectable()
class CurrentSender implements ContextTransformer<TokenPayloadModel> {
async transform(ctx: Context) {
const user = // get user from DB
return {
login: user.login,
isManager: user.isManager,
}
}
}
@Injectable()
export class SomethingActions {
@TelegramActionHandler({ command: '/say' })
async say(
ctx: Context,
// apply this transformer like this
@PipeContext(CurrentSender) user: TokenPayloadModel,
) {
const { login } = user
// now you can use `login`
await ctx.reply(`Hello, ${login}`)
}
}
```
Also, you can write `Catchers` for exceptions (like Filters in NestJS). Example:
```js
import { TelegramErrorHandler, TelegramCatch, Context } from 'nest-telegram'
@TelegramCatch(MyExecption)
export class MyCatcher
implements TelegramErrorHandler<MyExecption> {
public async catch(ctx: Context, exception: MyExecption) {
await ctx.reply(exception.message)
}
}
```
Stay tuned, stable release is coming. 🤓

View File

@ -28,7 +28,7 @@ export class TelegramBot {
this.bot = new Telegraf(token) this.bot = new Telegraf(token)
} }
public init(ref: ModuleRef) { public init(ref: ModuleRef, devMode: boolean = false) {
this.ref = ref this.ref = ref
const handlers = this.createHandlers() const handlers = this.createHandlers()
@ -36,6 +36,10 @@ export class TelegramBot {
this.setupOnStart(handlers) this.setupOnStart(handlers)
this.setupOnMessage(handlers) this.setupOnMessage(handlers)
this.setupOnCommand(handlers) this.setupOnCommand(handlers)
if (devMode) {
this.startPolling()
}
} }
public getMiddleware(path: string) { public getMiddleware(path: string) {
@ -54,7 +58,11 @@ export class TelegramBot {
} }
public startPolling() { public startPolling() {
try {
this.bot.startPolling() this.bot.startPolling()
} catch (e) {
// okay, never mind
}
} }
private createHandlers(): Handler[] { private createHandlers(): Handler[] {