@puregram/scenes

simple implementation of middleware-based scene management for puregram package

introduction

@puregram/scenes helps you to organize step-by-step handler by providing you needed classes and methods

example

const { Telegram } = require('puregram')

// @puregram/scenes requires @puregram/session
const { SessionManager } = require('@puregram/session')
const { SceneManager, StepScene } = require('@puregram/scenes')

const telegram = Telegram.fromToken(process.env.TOKEN)

const sessionManager = new SessionManager()
const sceneManager = new SceneManager()

telegram.updates.on('message', sessionManager.middleware)

telegram.updates.on('message', sceneManager.middleware)
telegram.updates.on('message', sceneManager.middlewareIntercept) // default scene entry handler

telegram.updates.on('message', (context) => {
  if (/^\/signup$/i.test(context.text)) {
    return context.scene.enter('signup')
  }
})

sceneManager.addScenes([
  new StepScene('signup', [
    (context) => {
      if (context.scene.step.firstTime || !context.hasText()) {
        return context.send('what\'s your name?')
      }

      context.scene.state.firstName = context.text

      return context.scene.step.next()
    },

    (context) => {
      if (context.scene.step.firstTime || !context.hasText()) {
        return context.send('how old are you?')
      }

      context.scene.state.age = Number.parseInt(context.text, 10)

      return context.scene.step.next()
    },

    async (context) => {
      const { firstName, age } = context.scene.state

      await context.send(`you are ${firstName} ${age} years old!`)

      // automatic exit since this is the last scene
      return context.scene.step.next()
    }
  ])
])

telegram.updates.startPolling()

installation

$ yarn add @puregram/scenes
$ npm i -S @puregram/scenes

typescript usage

you can tell @puregram/scenes about actual context type by providing it in the StepScene<T>:

import { CallbackQueryContext } from 'puregram'

new StepScene<CallbackQueryContext>('foo', [])

also, you can change context type on the fly simply by providing new type to the context variable:

import { CallbackQueryContext, MessageContext } from 'puregram'

new StepScene('bar', [
  (context: CallbackQueryContext) => {},
  (context: MessageContext) => {}
])

list of methods & getters

context.scene

step

returns: SceneInterface | undefined

returns current scene step

enter(slug, options?)

returns: Promise<void>

enters to another scene by slug

context.scene.enter('signup')

leave(options?)

returns: Promise<void>

leaves from current scene

context.scene.leave()

reenter()

returns: Promise<void>

reenters into current scene

context.scene.reenter()

reset()

returns: void

resets current scene (deletes it)

context.scene.step

firstTime

returns: boolean

returns true if this entry is the first entry in this scene

if (context.scene.step.firstTime) { /* ... */ }

stepId

returns: number

returns current step ID

current

returns: StepSceneHandler | undefined

returns current step handler

reenter()

returns: Promise<void>

reenters into current step handler

if (value.invalid) {
  return context.scene.step.reenter()
}

go(stepId, options?)

returns: Promise<void>

goes to a specific step by stepId

context.scene.step.go(0)

next(options?)

returns: Promise<void>

goes to the next step

context.scene.step.next()

previous(options?)

returns: Promise<void>

goes to the previous step

context.scene.step.previous()