plugin

Documentation

Overview

Package plugin provides the public SDK for PaperValet plugins. External plugins build against this package. Internal packages should use the type aliases in internal/interfaces.

Index

• Variables
• type Command
• type CommandContext
  • func (c *CommandContext) ArgCount() int
  • func (c *CommandContext) Context() context.Context
  • func (c *CommandContext) Delete() error
  • func (c *CommandContext) Edit(text string) error
  • func (c *CommandContext) GetArg(index int) string
  • func (c *CommandContext) GetArgs() string
  • func (c *CommandContext) HasArg(arg string) bool
  • func (c *CommandContext) Reply(text string) error
  • func (c *CommandContext) ResolvePeer() (tg.InputPeerClass, error)
  • func (c *CommandContext) Typing() error
• type CommandError
  • func (e *CommandError) Error() string
  • func (e *CommandError) Unwrap() error
• type Emitter
• type Handler
• type Logger
• type Manager
• type MessageEvent
• type Middleware
• type PeerResolver
• type Plugin
• type PluginInfo
• type PluginMetadata
• type PluginStatus
  • func (s PluginStatus) String() string
• type RegistryProvider
• type Session
• type SessionContext
  • func NewSessionContext(s *Session, ctx context.Context) *SessionContext
  • func (s *SessionContext) Ctx() context.Context
  • func (s *SessionContext) Delete(key string)
  • func (s *SessionContext) Get(key string) (any, bool)
  • func (s *SessionContext) Set(key string, value any)

Variables

var ErrNoMessage = &CommandError{Code: "NO_MESSAGE", Message: "no message in context"}

Types

type Command

type Command struct {
	Name        string
	Aliases     []string
	Description string
	Usage       string
	Plugin      string
	Category    string
	OwnerOnly   bool
	Hidden      bool
	RateLimit   int
	Handler     Handler
}

Command represents a registered command.

type CommandContext

type CommandContext struct {
	Command      string
	Args         []string
	RawArgs      string
	Message      *MessageEvent
	Session      *SessionContext
	API          *tg.Client
	PeerResolver PeerResolver
	Emitter      Emitter
	PluginName   string
	StartTime    time.Time
	Metadata     map[string]any
	Ctx          context.Context
	Logger       Logger
}

CommandContext is passed to every command handler.

func (*CommandContext) ArgCount

func (c *CommandContext) ArgCount() int

func (*CommandContext) Context

func (c *CommandContext) Context() context.Context

func (*CommandContext) Delete

func (c *CommandContext) Delete() error

func (*CommandContext) Edit

func (c *CommandContext) Edit(text string) error

func (*CommandContext) GetArg

func (c *CommandContext) GetArg(index int) string

func (*CommandContext) GetArgs

func (c *CommandContext) GetArgs() string

func (*CommandContext) HasArg

func (c *CommandContext) HasArg(arg string) bool

func (*CommandContext) Reply

func (c *CommandContext) Reply(text string) error

func (*CommandContext) ResolvePeer

func (c *CommandContext) ResolvePeer() (tg.InputPeerClass, error)

func (*CommandContext) Typing

func (c *CommandContext) Typing() error

type CommandError

type CommandError struct {
	Code    string
	Message string
	Err     error
}

func (*CommandError) Error

func (e *CommandError) Error() string

func (*CommandError) Unwrap

func (e *CommandError) Unwrap() error

type Emitter

type Emitter interface {
	Emit(ctx context.Context, eventType string, data any) error
}

Emitter is the subset of the event bus that plugins/commands need.

type Handler

type Handler func(ctx *CommandContext) error

Handler is the signature for command handlers.

type Logger

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Warn(msg string, keysAndValues ...any)
	Error(msg string, keysAndValues ...any)
	Named(name string) Logger
	With(keysAndValues ...any) Logger
}

Logger is the minimal logging interface for plugins.

type Manager

type Manager interface {
	RegisterPlugin(p Plugin) error
	RegisterCommand(cmd *Command) error
	UnregisterCommand(name string)
	UnregisterPlugin(name string)
	Commands() RegistryProvider
	GetInfo(name string) (PluginInfo, bool)
	GetAllInfo() []PluginInfo
	Emit(ctx context.Context, eventType string, data any) error
	InitAll(ctx context.Context) error
	StartAll(ctx context.Context) error
	StopAll(ctx context.Context) error
}

Manager is the plugin manager interface exposed to external plugins.

type MessageEvent

type MessageEvent struct {
	Update    tg.UpdatesClass
	Message   *tg.Message
	Text      string
	UserID    int64
	ChatID    int64
	IsOut     bool
	IsReply   bool
	ReplyToID int
	Entities  []tg.MessageEntityClass
	Media     tg.MessageMediaClass
	Date      int
	PeerID    tg.PeerClass
	Raw       any
}

MessageEvent represents a processed message event.

type Middleware

type Middleware func(next Handler) Handler

Middleware wraps a handler.

type PeerResolver

type PeerResolver interface {
	ResolveFromChatID(ctx context.Context, chatID int64) (tg.InputPeerClass, error)
	ResolveUserInChannel(ctx context.Context, channelPeer tg.InputChannelClass, userID int64) (tg.InputPeerClass, error)
	ResolveUserFromMessage(ctx context.Context, peer tg.InputPeerClass, msgID int, userID int64) (tg.InputPeerClass, error)
	ResolveUsername(ctx context.Context, username string) (tg.InputPeerClass, error)
}

PeerResolver resolves chat/user IDs to InputPeer.

type Plugin

type Plugin interface {
	Name() string
	Description() string
	Init(ctx context.Context, mgr Manager) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

Plugin is the interface all plugins must implement.

type PluginInfo

type PluginInfo struct {
	Name        string
	Description string
	Status      PluginStatus
}

PluginInfo holds plugin metadata.

type PluginMetadata

type PluginMetadata struct {
	Name        string
	Description string
	Version     string
	Author      string
	MinVersion  string
}

PluginMetadata holds plugin metadata for external .so plugins. External plugins export this as `var Metadata *PluginMetadata`.

type PluginStatus

type PluginStatus int

PluginStatus represents plugin lifecycle state.

const (
	StatusInactive PluginStatus = iota
	StatusActive
	StatusError
)

func (PluginStatus) String

func (s PluginStatus) String() string

type RegistryProvider

type RegistryProvider interface {
	Get(name string) (*Command, bool)
	GetAll() map[string]*Command
	GetByPlugin(plugin string) map[string]*Command
	GetPrefix() string
	GetPrefixes() []string
}

RegistryProvider provides command registry access.

type Session

type Session struct {
	UserID    int64
	ChatID    int64
	State     string
	Data      map[string]any
	Timestamp int64
}

Session holds per-(user,chat) conversation state.

type SessionContext

type SessionContext struct {
	Session *Session
	Context context.Context
	Data    map[string]any
}

SessionContext wraps a Session with a request context.

func NewSessionContext

func NewSessionContext(s *Session, ctx context.Context) *SessionContext

NewSessionContext creates a new SessionContext.

func (*SessionContext) Ctx

func (s *SessionContext) Ctx() context.Context

func (*SessionContext) Delete

func (s *SessionContext) Delete(key string)

func (*SessionContext) Get

func (s *SessionContext) Get(key string) (any, bool)

func (*SessionContext) Set

func (s *SessionContext) Set(key string, value any)