Refactoring & functionality improvement for sampling

.changeset/seven-drinks-hammer.md

@@ -0,0 +1,5 @@
+---
+"@iqai/mcp-telegram": patch
+---
+
+- Adds more sampling listeners, more env config options

.env.sample

@@ -0,0 +1,156 @@
+# ==============================================================================
+# REQUIRED CONFIGURATION
+# ==============================================================================
+
+# Your Telegram bot token from @BotFather
+# Get this by messaging @BotFather on Telegram and creating a new bot
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# ==============================================================================
+# SAMPLING CONFIGURATION
+# ==============================================================================
+
+# Master switch to enable/disable AI sampling entirely
+# Set to false to use only core MCP tools (send/receive messages, etc.)
+# Default: true
+SAMPLING_ENABLED=true
+
+# ------------------------------------------------------------------------------
+# Response Triggers
+# ------------------------------------------------------------------------------
+
+# Only respond when bot is mentioned in groups (e.g., @yourbotname hello)
+# Always responds in direct messages regardless of this setting
+# Default: true
+SAMPLING_MENTION_ONLY=true
+
+# Whether to respond to direct/private messages
+# Default: true
+SAMPLING_RESPOND_TO_DMS=true
+
+# ------------------------------------------------------------------------------
+# Access Control
+# ------------------------------------------------------------------------------
+
+# Comma-separated list of allowed chat IDs/usernames
+# Empty means all chats are allowed
+# Supports both numeric IDs (-1001234567890) and usernames (@mychannel)
+# Example: SAMPLING_ALLOWED_CHATS=-1001234567890,@mychannel,@anotherchat
+SAMPLING_ALLOWED_CHATS=
+
+# Comma-separated list of blocked chat IDs/usernames
+# Example: SAMPLING_BLOCKED_CHATS=-1001111111111,@spamchannel
+SAMPLING_BLOCKED_CHATS=
+
+# Comma-separated list of allowed user IDs (numeric only)
+# Empty means all users are allowed
+# Example: SAMPLING_ALLOWED_USERS=123456789,987654321
+SAMPLING_ALLOWED_USERS=
+
+# Comma-separated list of blocked user IDs (numeric only)
+# Example: SAMPLING_BLOCKED_USERS=111111111,222222222
+SAMPLING_BLOCKED_USERS=
+
+# Comma-separated list of admin user IDs (numeric only)
+# These users can use admin commands like /config
+# Example: SAMPLING_ADMIN_USERS=123456789
+SAMPLING_ADMIN_USERS=
+
+# ------------------------------------------------------------------------------
+# Message Type Handlers
+# ------------------------------------------------------------------------------
+
+# Enable/disable processing of different message types
+# Default: true for text, false for others (to avoid unwanted processing)
+SAMPLING_ENABLE_TEXT=true
+SAMPLING_ENABLE_PHOTO=false
+SAMPLING_ENABLE_DOCUMENT=false
+SAMPLING_ENABLE_VOICE=false
+SAMPLING_ENABLE_VIDEO=false
+SAMPLING_ENABLE_STICKER=false
+SAMPLING_ENABLE_LOCATION=false
+SAMPLING_ENABLE_CONTACT=false
+SAMPLING_ENABLE_POLL=false
+
+# ------------------------------------------------------------------------------
+# Response Behavior
+# ------------------------------------------------------------------------------
+
+# Maximum tokens for AI responses
+# Default: 1000
+SAMPLING_MAX_TOKENS=1000
+
+# Show typing indicator while processing
+# Default: true
+SAMPLING_SHOW_TYPING=true
+
+# Silent mode - log messages but don't respond (useful for debugging)
+# Default: false
+SAMPLING_SILENT_MODE=false
+
+# ------------------------------------------------------------------------------
+# Rate Limiting
+# ------------------------------------------------------------------------------
+
+# Maximum requests per user per minute
+# Default: 10
+SAMPLING_RATE_LIMIT_USER=10
+
+# Maximum requests per chat per minute
+# Default: 20
+SAMPLING_RATE_LIMIT_CHAT=20
+
+# ------------------------------------------------------------------------------
+# Message Filtering
+# ------------------------------------------------------------------------------
+
+# Minimum message length to process
+# Default: 1
+SAMPLING_MIN_MESSAGE_LENGTH=1
+
+# Maximum message length to process
+# Default: 1000
+SAMPLING_MAX_MESSAGE_LENGTH=1000
+
+# Comma-separated list of keywords that must be present in messages
+# Empty means no keyword filtering
+# Example: SAMPLING_KEYWORD_TRIGGERS=help,support,question
+SAMPLING_KEYWORD_TRIGGERS=
+
+# Ignore messages starting with / (bot commands)
+# Default: true
+SAMPLING_IGNORE_COMMANDS=true
+
+# ==============================================================================
+# EXAMPLE CONFIGURATIONS
+# ==============================================================================
+
+# Example 1: Tools-only mode (no AI sampling)
+# SAMPLING_ENABLED=false
+
+# Example 2: High-security environment
+# SAMPLING_ALLOWED_CHATS=-1001234567890,@trustedchannel
+# SAMPLING_ADMIN_USERS=123456789
+# SAMPLING_BLOCKED_USERS=999999999
+
+# Example 3: Support bot configuration
+# SAMPLING_KEYWORD_TRIGGERS=help,support,issue,problem
+# SAMPLING_RATE_LIMIT_USER=5
+# SAMPLING_ENABLE_PHOTO=true
+# SAMPLING_ENABLE_DOCUMENT=true
+
+# Example 4: Development/testing
+# SAMPLING_SILENT_MODE=true
+# SAMPLING_RATE_LIMIT_USER=100
+# SAMPLING_RATE_LIMIT_CHAT=200
+
+# Example 5: Media-focused bot
+# SAMPLING_ENABLE_PHOTO=true
+# SAMPLING_ENABLE_VIDEO=true
+# SAMPLING_ENABLE_STICKER=true
+# SAMPLING_ENABLE_VOICE=true
+
+# Example 6: Text-only with strict filtering
+# SAMPLING_MIN_MESSAGE_LENGTH=10
+# SAMPLING_MAX_MESSAGE_LENGTH=500
+# SAMPLING_KEYWORD_TRIGGERS=question,help

.gitignore

@@ -6,4 +6,5 @@ node_modules/
 
 # OS-specific
 .DS_Store
-Thumbs.db
+Thumbs.db
+.env