scenario

README

todo:

• readme
• tests

Documentation

Index

• Variables
• type Context
  • func NewContext[T any](scenario *Scenario, c tele.Context) (*Context[T], error)
  • func (c *Context[T]) Enter(scene SceneName) error
  • func (c *Context[T]) GetData() T
  • func (c *Context[T]) Leave() error
  • func (c *Context[T]) Reenter() error
  • func (c *Context[T]) SetData(data T)
• type ContextBase
• type Handler
• type Scenario
  • func New(bot *tele.Bot) *Scenario
  • func (s *Scenario) Middleware(next tele.HandlerFunc) tele.HandlerFunc
  • func (s *Scenario) Use(sc Scene) *Scenario
  • func (s *Scenario) WithStore(store Store) *Scenario
• type Scene
• type SceneName
• type Session
• type SessionBase
• type Store
• type TypedScene
• type WizardScene
  • func NewWizard[T any](name SceneName, steps ...WizardStep[T]) *WizardScene[T]
  • func (w *WizardScene[T]) CreateContext(scenario *Scenario, c tele.Context, base *SessionBase) (ContextBase, error)
  • func (w *WizardScene[T]) Enter(c ContextBase) error
  • func (w *WizardScene[T]) Leave(c ContextBase) error
  • func (w *WizardScene[T]) Name() SceneName
  • func (w *WizardScene[T]) OnUpdate(c ContextBase) error
• type WizardStep

Variables

var (
	ErrSessionNotFound = errors.New("session not found")
	ErrSceneNotFound   = errors.New("scene not found")
)

Types

type Context

type Context[T any] struct {
	tele.Context
	Scenario *Scenario
	Session  *Session[T]
	// contains filtered or unexported fields
}

Context wraps tele.Context and carries scene/session helpers. T is the type of data stored in the session.

func NewContext

func NewContext[T any](scenario *Scenario, c tele.Context) (*Context[T], error)

NewContext constructs scene context with existing session loaded from Store. T is the type of data stored in the session.

func (*Context[T]) Enter

func (c *Context[T]) Enter(scene SceneName) error

Enter helpers

func (*Context[T]) GetData

func (c *Context[T]) GetData() T

GetData returns the session data.

func (*Context[T]) Leave

func (c *Context[T]) Leave() error

Leave .

func (*Context[T]) Reenter

func (c *Context[T]) Reenter() error

Reenter .

func (*Context[T]) SetData

func (c *Context[T]) SetData(data T)

SetData sets the session data and marks context as dirty.

type ContextBase

type ContextBase interface {
	tele.Context
	Enter(scene SceneName) error
	Reenter() error
	Leave() error
	// contains filtered or unexported methods
}

ContextBase is the base interface for Context that allows type erasure.

type Handler

type Handler func(ContextBase) error

Handler is a function to process updates inside a scene.

type Scenario

type Scenario struct {
	// contains filtered or unexported fields
}

Scenario routes updates to scenes, stores session and current scene.

func New

func New(bot *tele.Bot) *Scenario

New .

func (*Scenario) Middleware

func (s *Scenario) Middleware(next tele.HandlerFunc) tele.HandlerFunc

Middleware returns a telebot middleware that injects scene context and dispatches to active scene. This middleware creates a typed Context[T] based on the scene's type parameter.

func (*Scenario) Use

func (s *Scenario) Use(sc Scene) *Scenario

func (*Scenario) WithStore

func (s *Scenario) WithStore(store Store) *Scenario

WithStore replaces the default in-memory store with a custom Store (e.g., DB-backed).

type Scene

type Scene interface {
	Name() SceneName
	Enter(ContextBase) error
	OnUpdate(ContextBase) error
	Leave(ContextBase) error
}

Scene defines a simple lifecycle similar to grammy scenes.

type SceneName

type SceneName string

SceneName .

type Session

type Session[T any] struct {
	ChatID    int64     `json:"chat_id" db:"chat_id"`
	UserID    int64     `json:"user_id" db:"user_id"`
	Scene     SceneName `json:"scene" db:"scene"`
	Step      int       `json:"step" db:"step"`
	Data      T         `json:"data" db:"data"`
	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}

Session is per-user (and optionally per-chat) state persisted between updates. T is the type of data stored in this session.

type SessionBase

type SessionBase struct {
	ChatID    int64           `json:"chat_id" db:"chat_id"`
	UserID    int64           `json:"user_id" db:"user_id"`
	Scene     SceneName       `json:"scene" db:"scene"`
	Step      int             `json:"step" db:"step"`
	Data      json.RawMessage `json:"data" db:"data"`
	UpdatedAt time.Time       `json:"updated_at" db:"updated_at"`
}

SessionBase is the base session structure used for storage. It stores Data as json.RawMessage to allow deserialization into different types.

type Store

type Store interface {
	GetSession(ctx context.Context, chatID, userID int64) (*SessionBase, error)
	SetSession(ctx context.Context, sess *SessionBase) error
}

Store abstracts scene/session persistence.

type TypedScene

type TypedScene interface {
	Scene
	// CreateContext creates a typed Context[T] from SessionBase.
	// The returned ContextBase should be of type *Context[T] where T matches the scene's data type.
	CreateContext(scenario *Scenario, c tele.Context, base *SessionBase) (ContextBase, error)
}

TypedScene is a scene that can create a typed context from SessionBase. This allows middleware to create the correct Context[T] type.

type WizardScene

type WizardScene[T any] struct {
	// contains filtered or unexported fields
}

WizardScene is a scene that manages a sequence of steps (wizard pattern). T is the type of data stored in the session.

func NewWizard

func NewWizard[T any](name SceneName, steps ...WizardStep[T]) *WizardScene[T]

NewWizard creates a new wizard scene with typed steps. T is the type of data stored in the session.

func (*WizardScene[T]) CreateContext

func (w *WizardScene[T]) CreateContext(scenario *Scenario, c tele.Context, base *SessionBase) (ContextBase, error)

CreateContext creates a typed Context[T] from SessionBase.

func (*WizardScene[T]) Enter

func (w *WizardScene[T]) Enter(c ContextBase) error

Enter initializes the wizard by setting step to 0.

func (*WizardScene[T]) Leave

func (w *WizardScene[T]) Leave(c ContextBase) error

Leave cleans up the wizard by setting step to -1.

func (*WizardScene[T]) Name

func (w *WizardScene[T]) Name() SceneName

Name returns the scene name.

func (*WizardScene[T]) OnUpdate

func (w *WizardScene[T]) OnUpdate(c ContextBase) error

OnUpdate processes the current step and advances if needed.

type WizardStep

type WizardStep[T any] func(*Context[T]) (advance bool, err error)

WizardStep is a step handler returning whether to advance to next step. T is the type of data stored in the session.