telegram_bot_engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6328e735752f40d861612353af4506231c527650bb1af06eb41e555266a57d6e
+  data.tar.gz: bbf440a730524d681420d2c65f9835a7c13e5250042c5d5f32d7ca1797a9803c
+SHA512:
+  metadata.gz: e3addc87463489304620537db0c299cce2825e5a82239eafbc1a0fffad91bd806f8453893fb79ed79cb133501e8b07be035de481380cb0d94fcfa18f28d8a405
+  data.tar.gz: 8aa8eb624f5d29d562186d9888c3027886f65f11417e6f34a480bd5dca607a446ff4ea224ecb56c18238b179946ad9dcba2f863d262c690104db0c02e50ba2cd

data/README.md

@@ -0,0 +1,135 @@
+# TelegramBotEngine
+
+A mountable Rails engine that adds subscriber management, authorization, broadcasting, and an admin UI on top of the [`telegram-bot`](https://github.com/telegram-bot-rb/telegram-bot) gem (v0.16.x).
+
+The `telegram-bot` gem handles all Telegram protocol concerns (API client, webhook ingestion, controller/command routing, callback queries, session, async delivery, and testing). This engine adds the persistence and management layer that `telegram-bot` deliberately doesn't provide.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "telegram_bot_engine"
+```
+
+Install migrations:
+
+```bash
+bin/rails telegram_bot_engine:install:migrations
+bin/rails db:migrate
+```
+
+## Configuration
+
+### Bot token
+
+Following `telegram-bot`'s convention, configure via Rails credentials:
+
+```yaml
+# config/credentials.yml.enc
+telegram:
+  bot:
+    token: "YOUR_BOT_TOKEN"
+    username: "your_bot"
+```
+
+### Engine configuration
+
+```ruby
+# config/initializers/telegram_bot_engine.rb
+TelegramBotEngine.configure do |config|
+  # Authorization: only these Telegram usernames can /start and subscribe.
+  config.allowed_usernames = %w[alice bob charlie]
+  # OR dynamic:
+  # config.allowed_usernames = -> { MyModel.pluck(:telegram_username) }
+  # OR managed via admin UI:
+  # config.allowed_usernames = :database
+  # OR open access (no allowlist):
+  # config.allowed_usernames = nil
+
+  # Optional: disable admin UI
+  # config.admin_enabled = false
+
+  # Optional: custom messages
+  # config.unauthorized_message = "Sorry, you're not authorized to use this bot."
+  # config.welcome_message = "Welcome %{username}! Available commands:\n%{commands}"
+end
+```
+
+### Webhook controller
+
+Create a controller inheriting from `telegram-bot`'s `UpdatesController` and include the engine's concern:
+
+```ruby
+# app/controllers/telegram_webhook_controller.rb
+class TelegramWebhookController < Telegram::Bot::UpdatesController
+  include TelegramBotEngine::SubscriberCommands
+  # Provides: start!, stop!, help! with authorization and subscription management.
+
+  # Add your own commands:
+  def status!(*)
+    respond_with :message, text: "All systems operational"
+  end
+end
+```
+
+### Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  telegram_webhook TelegramWebhookController
+
+  # Mount admin UI (protect with your own authentication)
+  authenticate :user, ->(u) { u.admin? } do
+    mount TelegramBotEngine::Engine, at: "/telegram/admin"
+  end
+end
+```
+
+### Set webhook
+
+```bash
+bin/rails telegram:bot:set_webhook
+```
+
+## Usage
+
+### Broadcasting
+
+```ruby
+# Broadcast to all active subscribers
+TelegramBotEngine.broadcast("Deployment complete!")
+
+# With Markdown formatting
+TelegramBotEngine.broadcast(
+  "*Deploy complete*\nVersion: `v2.3.4`",
+  parse_mode: "Markdown"
+)
+```
+
+### Direct messaging
+
+```ruby
+TelegramBotEngine.notify(
+  chat_id: 123456789,
+  text: "Your report is ready."
+)
+```
+
+### Admin UI
+
+When mounted, the engine provides a web interface for:
+- **Dashboard** — bot info, subscription counts
+- **Subscriptions** — list, activate/deactivate, delete
+- **Allowlist** — add/remove usernames (when `config.allowed_usernames = :database`)
+
+## Requirements
+
+- Ruby >= 3.3.0
+- Rails >= 7.0
+- `telegram-bot` ~> 0.16
+
+## License
+
+MIT

data/app/controllers/telegram_bot_engine/admin/allowlist_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    class AllowlistController < BaseController
+      before_action :require_database_mode!
+
+      def index
+        @allowed_users = AllowedUser.order(:username)
+      end
+
+      def create
+        AllowedUser.create!(allowed_user_params)
+        redirect_to admin_allowlist_index_path, notice: "Username added to allowlist."
+      rescue ActiveRecord::RecordInvalid => e
+        redirect_to admin_allowlist_index_path, alert: e.message
+      end
+
+      def destroy
+        allowed_user = AllowedUser.find(params[:id])
+        allowed_user.destroy!
+        redirect_to admin_allowlist_index_path, notice: "Username removed from allowlist."
+      end
+
+      private
+
+      def allowed_user_params
+        params.require(:allowed_user).permit(:username, :note)
+      end
+
+      def require_database_mode!
+        unless TelegramBotEngine.config.allowed_usernames == :database
+          redirect_to admin_dashboard_path, alert: "Allowlist management is only available in database mode."
+        end
+      end
+    end
+  end
+end

data/app/controllers/telegram_bot_engine/admin/base_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    class BaseController < ActionController::Base
+      layout "telegram_bot_engine/admin/layouts/application"
+
+      before_action :check_admin_enabled!
+
+      private
+
+      def check_admin_enabled!
+        raise ActionController::RoutingError, "Not Found" unless TelegramBotEngine.config.admin_enabled
+      end
+    end
+  end
+end

data/app/controllers/telegram_bot_engine/admin/dashboard_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    class DashboardController < BaseController
+      def show
+        @total_subscriptions = Subscription.count
+        @active_subscriptions = Subscription.active.count
+        @inactive_subscriptions = @total_subscriptions - @active_subscriptions
+        @bot_username = bot_username
+      end
+
+      private
+
+      def bot_username
+        Telegram.bot.username
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/app/controllers/telegram_bot_engine/admin/subscriptions_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    class SubscriptionsController < BaseController
+      def index
+        @subscriptions = Subscription.order(created_at: :desc)
+      end
+
+      def update
+        subscription = Subscription.find(params[:id])
+        subscription.update!(active: !subscription.active)
+        redirect_to admin_subscriptions_path, notice: "Subscription #{subscription.active ? 'activated' : 'deactivated'}."
+      end
+
+      def destroy
+        subscription = Subscription.find(params[:id])
+        subscription.destroy!
+        redirect_to admin_subscriptions_path, notice: "Subscription deleted."
+      end
+    end
+  end
+end

data/app/jobs/telegram_bot_engine/delivery_job.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class DeliveryJob < ApplicationJob
+    queue_as :default
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+    def perform(chat_id, text, options = {})
+      Telegram.bot.send_message(
+        chat_id: chat_id,
+        text: text,
+        **options.symbolize_keys
+      )
+    rescue Telegram::Bot::Forbidden
+      # User blocked the bot - deactivate subscription
+      TelegramBotEngine::Subscription.where(chat_id: chat_id).update_all(active: false)
+      Rails.logger.info("[TelegramBotEngine] Deactivated subscription for blocked chat: #{chat_id}")
+    end
+  end
+end

data/app/models/telegram_bot_engine/allowed_user.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class AllowedUser < ActiveRecord::Base
+    self.table_name = "telegram_bot_engine_allowed_users"
+
+    validates :username, presence: true, uniqueness: true
+  end
+end

data/app/models/telegram_bot_engine/subscription.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class Subscription < ActiveRecord::Base
+    self.table_name = "telegram_bot_engine_subscriptions"
+
+    scope :active, -> { where(active: true) }
+
+    validates :chat_id, presence: true, uniqueness: true
+  end
+end

data/app/views/telegram_bot_engine/admin/allowlist/index.html.erb

@@ -0,0 +1,71 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Allowlist</h1>
+  <p class="mt-1 text-sm text-gray-500">Manage authorized Telegram usernames</p>
+</div>
+
+<div class="mb-6 bg-white shadow-sm rounded-lg border border-gray-200 p-6">
+  <h2 class="text-sm font-medium text-gray-700 mb-4">Add Username</h2>
+  <%= form_with url: telegram_bot_engine.admin_allowlist_index_path, method: :post, class: "flex items-end space-x-4" do |f| %>
+    <div class="flex-1">
+      <label for="allowed_user_username" class="block text-sm font-medium text-gray-700 mb-1">Username</label>
+      <input type="text" name="allowed_user[username]" id="allowed_user_username" required
+             class="block w-full rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border"
+             placeholder="telegram_username">
+    </div>
+    <div class="flex-1">
+      <label for="allowed_user_note" class="block text-sm font-medium text-gray-700 mb-1">Note (optional)</label>
+      <input type="text" name="allowed_user[note]" id="allowed_user_note"
+             class="block w-full rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border"
+             placeholder="e.g. Tom - developer">
+    </div>
+    <div>
+      <button type="submit"
+              class="inline-flex items-center px-4 py-2 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:ring-2 focus:ring-offset-2 focus:ring-blue-500">
+        Add
+      </button>
+    </div>
+  <% end %>
+</div>
+
+<div class="bg-white shadow-sm rounded-lg border border-gray-200 overflow-hidden">
+  <table class="min-w-full divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Username</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Note</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Added</th>
+        <th class="px-6 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">Actions</th>
+      </tr>
+    </thead>
+    <tbody class="bg-white divide-y divide-gray-200">
+      <% @allowed_users.each do |user| %>
+        <tr>
+          <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900">
+            @<%= user.username %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+            <%= user.note || "-" %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+            <%= user.created_at.strftime("%Y-%m-%d %H:%M") %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-right text-sm">
+            <%= button_to "Remove",
+                  telegram_bot_engine.admin_allowlist_path(user),
+                  method: :delete,
+                  data: { turbo_confirm: "Remove @#{user.username} from the allowlist?" },
+                  class: "inline-flex items-center px-3 py-1.5 border border-red-300 rounded text-xs font-medium text-red-700 bg-white hover:bg-red-50" %>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @allowed_users.empty? %>
+        <tr>
+          <td colspan="4" class="px-6 py-12 text-center text-sm text-gray-500">
+            No usernames in the allowlist yet.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/telegram_bot_engine/admin/dashboard/show.html.erb

@@ -0,0 +1,41 @@
+<div class="mb-8">
+  <h1 class="text-2xl font-bold text-gray-900">Dashboard</h1>
+</div>
+
+<% if @bot_username %>
+  <div class="mb-6 bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+    <h2 class="text-sm font-medium text-gray-500 uppercase tracking-wider mb-2">Bot</h2>
+    <p class="text-lg font-semibold text-gray-900">@<%= @bot_username %></p>
+    <a href="https://t.me/<%= @bot_username %>" target="_blank" rel="noopener"
+       class="text-sm text-blue-600 hover:text-blue-800">
+      t.me/<%= @bot_username %>
+    </a>
+  </div>
+<% end %>
+
+<div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+  <div class="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+    <h3 class="text-sm font-medium text-gray-500 uppercase tracking-wider">Total Subscriptions</h3>
+    <p class="mt-2 text-3xl font-bold text-gray-900"><%= @total_subscriptions %></p>
+  </div>
+
+  <div class="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+    <h3 class="text-sm font-medium text-gray-500 uppercase tracking-wider">Active</h3>
+    <p class="mt-2 text-3xl font-bold text-green-600"><%= @active_subscriptions %></p>
+  </div>
+
+  <div class="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+    <h3 class="text-sm font-medium text-gray-500 uppercase tracking-wider">Inactive</h3>
+    <p class="mt-2 text-3xl font-bold text-gray-400"><%= @inactive_subscriptions %></p>
+  </div>
+</div>
+
+<div class="flex space-x-4">
+  <%= link_to "Manage Subscriptions", telegram_bot_engine.admin_subscriptions_path,
+        class: "inline-flex items-center px-4 py-2 border border-gray-300 rounded-md shadow-sm text-sm font-medium text-gray-700 bg-white hover:bg-gray-50" %>
+
+  <% if TelegramBotEngine.config.allowed_usernames == :database %>
+    <%= link_to "Manage Allowlist", telegram_bot_engine.admin_allowlist_index_path,
+          class: "inline-flex items-center px-4 py-2 border border-gray-300 rounded-md shadow-sm text-sm font-medium text-gray-700 bg-white hover:bg-gray-50" %>
+  <% end %>
+</div>

data/app/views/telegram_bot_engine/admin/layouts/application.html.erb

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Telegram Bot Engine Admin</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <%= csrf_meta_tags %>
+</head>
+<body class="bg-gray-50 min-h-screen">
+  <nav class="bg-white shadow-sm border-b border-gray-200">
+    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+      <div class="flex justify-between h-16">
+        <div class="flex items-center space-x-8">
+          <span class="text-xl font-bold text-gray-900">Telegram Bot Engine</span>
+          <div class="flex space-x-4">
+            <%= link_to "Dashboard", telegram_bot_engine.admin_dashboard_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path == telegram_bot_engine.admin_dashboard_path || request.path == telegram_bot_engine.admin_root_path ? 'text-blue-600 bg-blue-50' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'}" %>
+            <%= link_to "Subscriptions", telegram_bot_engine.admin_subscriptions_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.include?('subscriptions') ? 'text-blue-600 bg-blue-50' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'}" %>
+            <% if TelegramBotEngine.config.allowed_usernames == :database %>
+              <%= link_to "Allowlist", telegram_bot_engine.admin_allowlist_index_path,
+                    class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.include?('allowlist') ? 'text-blue-600 bg-blue-50' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'}" %>
+            <% end %>
+          </div>
+        </div>
+      </div>
+    </div>
+  </nav>
+
+  <main class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+    <% if notice %>
+      <div class="mb-4 p-4 rounded-md bg-green-50 border border-green-200">
+        <p class="text-sm text-green-800"><%= notice %></p>
+      </div>
+    <% end %>
+
+    <% if alert %>
+      <div class="mb-4 p-4 rounded-md bg-red-50 border border-red-200">
+        <p class="text-sm text-red-800"><%= alert %></p>
+      </div>
+    <% end %>
+
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/telegram_bot_engine/admin/subscriptions/index.html.erb

@@ -0,0 +1,63 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Subscriptions</h1>
+  <p class="mt-1 text-sm text-gray-500"><%= @subscriptions.count %> total</p>
+</div>
+
+<div class="bg-white shadow-sm rounded-lg border border-gray-200 overflow-hidden">
+  <table class="min-w-full divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Username</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">First Name</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Chat ID</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Status</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Subscribed</th>
+        <th class="px-6 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">Actions</th>
+      </tr>
+    </thead>
+    <tbody class="bg-white divide-y divide-gray-200">
+      <% @subscriptions.each do |subscription| %>
+        <tr>
+          <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900">
+            <%= subscription.username || "-" %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-600">
+            <%= subscription.first_name || "-" %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono">
+            <%= subscription.chat_id %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap">
+            <% if subscription.active? %>
+              <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 text-green-800">Active</span>
+            <% else %>
+              <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-gray-100 text-gray-800">Inactive</span>
+            <% end %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+            <%= subscription.created_at.strftime("%Y-%m-%d %H:%M") %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-right text-sm space-x-2">
+            <%= button_to subscription.active? ? "Deactivate" : "Activate",
+                  telegram_bot_engine.admin_subscription_path(subscription),
+                  method: :patch,
+                  class: "inline-flex items-center px-3 py-1.5 border border-gray-300 rounded text-xs font-medium #{subscription.active? ? 'text-yellow-700 hover:bg-yellow-50' : 'text-green-700 hover:bg-green-50'} bg-white" %>
+            <%= button_to "Delete",
+                  telegram_bot_engine.admin_subscription_path(subscription),
+                  method: :delete,
+                  data: { turbo_confirm: "Are you sure you want to delete this subscription?" },
+                  class: "inline-flex items-center px-3 py-1.5 border border-red-300 rounded text-xs font-medium text-red-700 bg-white hover:bg-red-50" %>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @subscriptions.empty? %>
+        <tr>
+          <td colspan="6" class="px-6 py-12 text-center text-sm text-gray-500">
+            No subscriptions yet.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+TelegramBotEngine::Engine.routes.draw do
+  scope module: :admin, as: :admin do
+    root to: "dashboard#show"
+    get "dashboard", to: "dashboard#show", as: :dashboard
+    resources :subscriptions, only: %i[index update destroy]
+    resources :allowlist, only: %i[index create destroy]
+  end
+end

data/db/migrate/001_create_telegram_bot_engine_subscriptions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateTelegramBotEngineSubscriptions < ActiveRecord::Migration[7.0]
+  def change
+    create_table :telegram_bot_engine_subscriptions do |t|
+      t.bigint :chat_id, null: false
+      t.bigint :user_id
+      t.string :username
+      t.string :first_name
+      t.boolean :active, default: true
+      t.jsonb :metadata, default: {}
+
+      t.timestamps
+    end
+
+    add_index :telegram_bot_engine_subscriptions, :chat_id, unique: true
+    add_index :telegram_bot_engine_subscriptions, :active
+    add_index :telegram_bot_engine_subscriptions, :username
+  end
+end

data/db/migrate/002_create_telegram_bot_engine_allowed_users.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CreateTelegramBotEngineAllowedUsers < ActiveRecord::Migration[7.0]
+  def change
+    create_table :telegram_bot_engine_allowed_users do |t|
+      t.string :username, null: false
+      t.string :note
+
+      t.timestamps
+    end
+
+    add_index :telegram_bot_engine_allowed_users, :username, unique: true
+  end
+end

data/lib/tasks/telegram_bot_engine.rake

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Standard Rails engine tasks are provided automatically.
+# Custom rake tasks for telegram_bot_engine can be added here.

data/lib/telegram_bot_engine/authorizer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class Authorizer
+    def self.authorized?(username)
+      return true if TelegramBotEngine.config.allowed_usernames.nil?
+
+      allowed = resolve_allowed_usernames
+      allowed.map(&:downcase).include?(username&.downcase)
+    end
+
+    private
+
+    def self.resolve_allowed_usernames
+      config = TelegramBotEngine.config.allowed_usernames
+
+      case config
+      when Array
+        config
+      when Proc
+        config.call
+      when :database
+        TelegramBotEngine::AllowedUser.pluck(:username)
+      else
+        []
+      end
+    end
+  end
+end

data/lib/telegram_bot_engine/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class Configuration
+    attr_accessor :allowed_usernames, :admin_enabled, :unauthorized_message, :welcome_message
+
+    def initialize
+      @allowed_usernames = nil
+      @admin_enabled = true
+      @unauthorized_message = "Sorry, you're not authorized to use this bot."
+      @welcome_message = "Welcome %{username}! Available commands:\n%{commands}"
+    end
+  end
+end

data/lib/telegram_bot_engine/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace TelegramBotEngine
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+  end
+end

data/lib/telegram_bot_engine/subscriber_commands.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module SubscriberCommands
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :authorize_user!
+    end
+
+    # /start - create subscription if authorized
+    def start!(*)
+      subscription = TelegramBotEngine::Subscription.find_or_initialize_by(
+        chat_id: chat["id"]
+      )
+      subscription.assign_attributes(
+        user_id: from["id"],
+        username: from["username"],
+        first_name: from["first_name"],
+        active: true
+      )
+      subscription.save!
+
+      welcome = TelegramBotEngine.config.welcome_message % {
+        username: from["first_name"] || from["username"],
+        commands: available_commands_text
+      }
+      respond_with :message, text: welcome
+    end
+
+    # /stop - deactivate subscription
+    def stop!(*)
+      subscription = TelegramBotEngine::Subscription.find_by(chat_id: chat["id"])
+      subscription&.update(active: false)
+      respond_with :message, text: "You've been unsubscribed. Send /start to resubscribe."
+    end
+
+    # /help - list all available commands
+    def help!(*)
+      respond_with :message, text: "📋 *Available Commands*\n\n#{available_commands_text}", parse_mode: "Markdown"
+    end
+
+    private
+
+    def authorize_user!
+      return if TelegramBotEngine::Authorizer.authorized?(from["username"])
+
+      respond_with :message, text: TelegramBotEngine.config.unauthorized_message
+      throw :abort
+    end
+
+    # Auto-generates command list from public methods ending with !
+    def available_commands_text
+      commands = self.class.public_instance_methods(false)
+                     .select { |m| m.to_s.end_with?("!") }
+                     .map { |m| "/#{m.to_s.delete_suffix('!')}" }
+
+      all_commands = ["/start", "/stop", "/help"] | commands
+      all_commands.join("\n")
+    end
+  end
+end

data/lib/telegram_bot_engine/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  VERSION = "0.1.0"
+end

data/lib/telegram_bot_engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "telegram/bot"
+require "telegram_bot_engine/version"
+require "telegram_bot_engine/configuration"
+require "telegram_bot_engine/authorizer"
+require "telegram_bot_engine/subscriber_commands"
+require "telegram_bot_engine/engine"
+
+module TelegramBotEngine
+  class << self
+    def configure
+      yield(config)
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # Broadcast to all active subscribers via background jobs
+    def broadcast(text, **options)
+      TelegramBotEngine::Subscription.active.find_each do |subscription|
+        TelegramBotEngine::DeliveryJob.perform_later(
+          subscription.chat_id,
+          text,
+          options
+        )
+      end
+    end
+
+    # Send to a specific chat via background job
+    def notify(chat_id:, text:, **options)
+      TelegramBotEngine::DeliveryJob.perform_later(chat_id, text, options)
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: telegram_bot_engine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TelegramBotEngine Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: telegram-bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: A mountable Rails engine that adds subscriber persistence, authorization,
+  broadcasting, and an admin UI on top of the telegram-bot gem.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/controllers/telegram_bot_engine/admin/allowlist_controller.rb
+- app/controllers/telegram_bot_engine/admin/base_controller.rb
+- app/controllers/telegram_bot_engine/admin/dashboard_controller.rb
+- app/controllers/telegram_bot_engine/admin/subscriptions_controller.rb
+- app/jobs/telegram_bot_engine/delivery_job.rb
+- app/models/telegram_bot_engine/allowed_user.rb
+- app/models/telegram_bot_engine/subscription.rb
+- app/views/telegram_bot_engine/admin/allowlist/index.html.erb
+- app/views/telegram_bot_engine/admin/dashboard/show.html.erb
+- app/views/telegram_bot_engine/admin/layouts/application.html.erb
+- app/views/telegram_bot_engine/admin/subscriptions/index.html.erb
+- config/routes.rb
+- db/migrate/001_create_telegram_bot_engine_subscriptions.rb
+- db/migrate/002_create_telegram_bot_engine_allowed_users.rb
+- lib/tasks/telegram_bot_engine.rake
+- lib/telegram_bot_engine.rb
+- lib/telegram_bot_engine/authorizer.rb
+- lib/telegram_bot_engine/configuration.rb
+- lib/telegram_bot_engine/engine.rb
+- lib/telegram_bot_engine/subscriber_commands.rb
+- lib/telegram_bot_engine/version.rb
+homepage: https://github.com/landovsky/telegram-bot-channels-gem
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails engine for Telegram bot subscriber management, authorization, broadcasting,
+  and admin UI
+test_files: []