telegram_bot_engine 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3d331110ead0fd92e4fee373b4fa5429479116cd9e518a367aea45cdda067df
-  data.tar.gz: cb35bb73052d715549a8146cde0ab25d5d990f7b20840ae28859633ab6265609
+  metadata.gz: 5b3bf5d33786a7847de84d3b85308001301ea88d642d8b8e881341be9bd311d1
+  data.tar.gz: 71a00b7a640dfd91c79b6080a3295ab6621fc938a05504f94c28f9757a655c59
 SHA512:
-  metadata.gz: 7b02b7c338ee4dbd4db036e32e2f77fb909aabe9a64e7ed19e9bb2a82b87ee4c8f3dd321e79772aa52d99dc637f986c02d3d7273d2279be1f6be69e22c638e30
-  data.tar.gz: d0d8c3bc21441fe79c1e7dd14cfd2ca9a452e2733f6fc0d08b478fadb9322a74968b3d0c0f974189bd20803339020409489f8ae960b70bf93b0381923cde285c
+  metadata.gz: 4d892f84a28953e2bc78c157ae9169ba3907e0482b15c79ae3068b2d7c43514d3014ee46ca415e33aaaa94c72d1c9470a9e139066ea816c17844711373d7d18f
+  data.tar.gz: f9154fdc913b4fe766d89a9e5a6fcca88333a192e1e71c233972c0d1335d7641ef0f30fe2554a1ad16e37920c36e5a91b53a3600f7c754f3eb8e74890cd3c2cf

data/README.md

@@ -53,6 +53,10 @@ TelegramBotEngine.configure do |config|
   # Optional: custom messages
   # config.unauthorized_message = "Sorry, you're not authorized to use this bot."
   # config.welcome_message = "Welcome %{username}! Available commands:\n%{commands}"
+
+  # Event logging — logs commands, deliveries, auth failures to the database
+  # config.event_logging = true          # default: true
+  # config.event_retention_days = 30     # default: 30, auto-purges older events
 end
 ```
 
@@ -149,6 +153,35 @@ 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`)
+- **Events** — browsable log of commands, deliveries, and auth failures with filtering by type, action, and chat ID
+
+### Event log
+
+The engine automatically logs operational events to the `telegram_bot_engine_events` table:
+
+| Event type | Actions | When |
+|---|---|---|
+| `command` | `start`, `stop`, `help` | User sends a bot command |
+| `delivery` | `broadcast`, `notify`, `delivered`, `blocked` | Messages are queued or delivered |
+| `auth_failure` | `unauthorized` | Unauthorized user attempts a command |
+
+Events are viewable in the admin UI and can be queried directly:
+
+```ruby
+# Recent command events
+TelegramBotEngine::Event.by_type("command").recent.limit(20)
+
+# Deliveries to a specific chat
+TelegramBotEngine::Event.by_type("delivery").by_chat_id(123456789)
+
+# Events in the last 24 hours
+TelegramBotEngine::Event.since(24.hours.ago)
+
+# Manual purge (automatic purge runs probabilistically)
+TelegramBotEngine::Event.purge_old!
+```
+
+Disable event logging entirely with `config.event_logging = false`.
 
 ## Requirements
 

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    class EventsController < BaseController
+      PER_PAGE = 50
+
+      def index
+        @events = Event.recent
+        @events = @events.by_type(params[:type]) if params[:type].present?
+        @events = @events.by_action(params[:action_name]) if params[:action_name].present?
+        @events = @events.by_chat_id(params[:chat_id]) if params[:chat_id].present?
+
+        @total_count = @events.count
+        @page = [params[:page].to_i, 1].max
+        @events = @events.offset((@page - 1) * PER_PAGE).limit(PER_PAGE)
+        @total_pages = (@total_count.to_f / PER_PAGE).ceil
+      end
+    end
+  end
+end

data/app/jobs/telegram_bot_engine/delivery_job.rb

@@ -11,10 +11,22 @@ module TelegramBotEngine
         text: text,
         **options.symbolize_keys
       )
+
+      TelegramBotEngine::Event.log(
+        event_type: "delivery", action: "delivered",
+        chat_id: chat_id,
+        details: { text_preview: text.to_s[0, 100] }
+      )
     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}")
+
+      TelegramBotEngine::Event.log(
+        event_type: "delivery", action: "blocked",
+        chat_id: chat_id,
+        details: { text_preview: text.to_s[0, 100] }
+      )
     end
   end
 end

data/app/models/telegram_bot_engine/event.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  class Event < ActiveRecord::Base
+    self.table_name = "telegram_bot_engine_events"
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :by_type, ->(type) { where(event_type: type) if type.present? }
+    scope :by_action, ->(action) { where(action: action) if action.present? }
+    scope :by_chat_id, ->(chat_id) { where(chat_id: chat_id) if chat_id.present? }
+    scope :since, ->(time) { where("created_at >= ?", time) }
+
+    validates :event_type, presence: true
+    validates :action, presence: true
+
+    def self.log(event_type:, action:, chat_id: nil, username: nil, details: {})
+      return unless TelegramBotEngine.config.event_logging
+
+      create!(
+        event_type: event_type,
+        action: action,
+        chat_id: chat_id,
+        username: username,
+        details: details
+      )
+
+      purge_old_randomly!
+    end
+
+    def self.purge_old!
+      where("created_at < ?", TelegramBotEngine.config.event_retention_days.days.ago).delete_all
+    end
+
+    def self.purge_old_randomly!
+      purge_old! if rand(100).zero?
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Events</h1>
+  <p class="mt-1 text-sm text-gray-500"><%= @total_count %> total</p>
+</div>
+
+<div class="mb-6 bg-white shadow-sm rounded-lg border border-gray-200 p-6">
+  <%= form_with url: telegram_bot_engine.admin_events_path, method: :get, local: true, class: "flex items-end space-x-4" do %>
+    <div>
+      <label for="type" class="block text-sm font-medium text-gray-700 mb-1">Event Type</label>
+      <select name="type" id="type" class="block rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border">
+        <option value="">All</option>
+        <% %w[command delivery auth_failure subscription_change].each do |t| %>
+          <option value="<%= t %>" <%= "selected" if params[:type] == t %>><%= t %></option>
+        <% end %>
+      </select>
+    </div>
+    <div>
+      <label for="action_name" class="block text-sm font-medium text-gray-700 mb-1">Action</label>
+      <select name="action_name" id="action_name" class="block rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border">
+        <option value="">All</option>
+        <% %w[start stop help broadcast notify delivered blocked failed unauthorized].each do |a| %>
+          <option value="<%= a %>" <%= "selected" if params[:action_name] == a %>><%= a %></option>
+        <% end %>
+      </select>
+    </div>
+    <div>
+      <label for="chat_id" class="block text-sm font-medium text-gray-700 mb-1">Chat ID</label>
+      <input type="text" name="chat_id" id="chat_id" value="<%= params[:chat_id] %>"
+             class="block 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. 12345">
+    </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">
+        Filter
+      </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">Timestamp</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Type</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Action</th>
+        <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">Chat ID</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Details</th>
+      </tr>
+    </thead>
+    <tbody class="bg-white divide-y divide-gray-200">
+      <% @events.each do |event| %>
+        <tr>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+            <%= event.created_at.strftime("%Y-%m-%d %H:%M:%S") %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap">
+            <%
+              badge_colors = {
+                "command" => "bg-blue-100 text-blue-800",
+                "delivery" => "bg-green-100 text-green-800",
+                "auth_failure" => "bg-red-100 text-red-800",
+                "subscription_change" => "bg-yellow-100 text-yellow-800"
+              }
+              color = badge_colors[event.event_type] || "bg-gray-100 text-gray-800"
+            %>
+            <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium <%= color %>">
+              <%= event.event_type %>
+            </span>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
+            <%= event.action %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-600">
+            <%= event.username || "-" %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono">
+            <%= event.chat_id || "-" %>
+          </td>
+          <td class="px-6 py-4 text-sm text-gray-500 max-w-xs truncate" title="<%= event.details.to_json %>">
+            <%= event.details.present? ? event.details.to_json.truncate(80) : "-" %>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @events.empty? %>
+        <tr>
+          <td colspan="6" class="px-6 py-12 text-center text-sm text-gray-500">
+            No events found.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<% if @total_pages > 1 %>
+  <div class="mt-4 flex justify-between items-center">
+    <div class="text-sm text-gray-500">
+      Page <%= @page %> of <%= @total_pages %>
+    </div>
+    <div class="flex space-x-2">
+      <% if @page > 1 %>
+        <%= link_to "Previous", telegram_bot_engine.admin_events_path(type: params[:type], action_name: params[:action_name], chat_id: params[:chat_id], page: @page - 1),
+              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 %>
+      <% if @page < @total_pages %>
+        <%= link_to "Next", telegram_bot_engine.admin_events_path(type: params[:type], action_name: params[:action_name], chat_id: params[:chat_id], page: @page + 1),
+              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>
+  </div>
+<% end %>

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

@@ -22,6 +22,8 @@
               <%= 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 %>
+            <%= link_to "Events", telegram_bot_engine.admin_events_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.include?('events') ? 'text-blue-600 bg-blue-50' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'}" %>
           </div>
         </div>
       </div>

data/config/routes.rb

@@ -6,5 +6,6 @@ TelegramBotEngine::Engine.routes.draw do
     get "dashboard", to: "dashboard#show", as: :dashboard
     resources :subscriptions, only: %i[index update destroy]
     resources :allowlist, only: %i[index create destroy]
+    resources :events, only: %i[index]
   end
 end

data/db/migrate/003_create_telegram_bot_engine_events.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateTelegramBotEngineEvents < ActiveRecord::Migration[7.0]
+  def adapter_type
+    ActiveRecord::Base.connection.adapter_name.downcase.include?("postgresql") ? :jsonb : :json
+  end
+
+  def change
+    create_table :telegram_bot_engine_events do |t|
+      t.string :event_type, null: false
+      t.string :action, null: false
+      t.bigint :chat_id
+      t.string :username
+      t.column :details, adapter_type, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_index :telegram_bot_engine_events, :event_type
+    add_index :telegram_bot_engine_events, :created_at
+    add_index :telegram_bot_engine_events, :chat_id
+  end
+end

data/lib/telegram_bot_engine/configuration.rb

@@ -2,13 +2,16 @@
 
 module TelegramBotEngine
   class Configuration
-    attr_accessor :allowed_usernames, :admin_enabled, :unauthorized_message, :welcome_message
+    attr_accessor :allowed_usernames, :admin_enabled, :unauthorized_message, :welcome_message,
+                  :event_logging, :event_retention_days
 
     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}"
+      @event_logging = true
+      @event_retention_days = 30
     end
   end
 end

data/lib/telegram_bot_engine/subscriber_commands.rb

@@ -22,6 +22,11 @@ module TelegramBotEngine
       )
       subscription.save!
 
+      TelegramBotEngine::Event.log(
+        event_type: "command", action: "start",
+        chat_id: chat["id"], username: from["username"]
+      )
+
       welcome = TelegramBotEngine.config.welcome_message % {
         username: from["first_name"] || from["username"],
         commands: available_commands_text
@@ -33,11 +38,22 @@ module TelegramBotEngine
     def stop!(*)
       subscription = TelegramBotEngine::Subscription.find_by(chat_id: chat["id"])
       subscription&.update(active: false)
+
+      TelegramBotEngine::Event.log(
+        event_type: "command", action: "stop",
+        chat_id: chat["id"], username: from["username"]
+      )
+
       respond_with :message, text: "You've been unsubscribed. Send /start to resubscribe."
     end
 
     # /help - list all available commands
     def help!(*)
+      TelegramBotEngine::Event.log(
+        event_type: "command", action: "help",
+        chat_id: chat["id"], username: from["username"]
+      )
+
       respond_with :message, text: "📋 *Available Commands*\n\n#{available_commands_text}", parse_mode: "Markdown"
     end
 
@@ -46,6 +62,11 @@ module TelegramBotEngine
     def authorize_user!
       return if TelegramBotEngine::Authorizer.authorized?(from["username"])
 
+      TelegramBotEngine::Event.log(
+        event_type: "auth_failure", action: "unauthorized",
+        chat_id: chat["id"], username: from["username"]
+      )
+
       respond_with :message, text: TelegramBotEngine.config.unauthorized_message
       throw :abort
     end

data/lib/telegram_bot_engine/version.rb

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

data/lib/telegram_bot_engine.rb

@@ -23,18 +23,31 @@ module TelegramBotEngine
 
     # Broadcast to all active subscribers via background jobs
     def broadcast(text, **options)
+      subscriber_count = 0
       TelegramBotEngine::Subscription.active.find_each do |subscription|
         TelegramBotEngine::DeliveryJob.perform_later(
           subscription.chat_id,
           text,
           options
         )
+        subscriber_count += 1
       end
+
+      TelegramBotEngine::Event.log(
+        event_type: "delivery", action: "broadcast",
+        details: { subscriber_count: subscriber_count, text_preview: text.to_s[0, 100] }
+      )
     end
 
     # Send to a specific chat via background job
     def notify(chat_id:, text:, **options)
       TelegramBotEngine::DeliveryJob.perform_later(chat_id, text, options)
+
+      TelegramBotEngine::Event.log(
+        event_type: "delivery", action: "notify",
+        chat_id: chat_id,
+        details: { text_preview: text.to_s[0, 100] }
+      )
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: telegram_bot_engine
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - TelegramBotEngine Contributors
@@ -47,17 +47,21 @@ files:
 - 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/events_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/event.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/events/index.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
+- db/migrate/003_create_telegram_bot_engine_events.rb
 - lib/tasks/telegram_bot_engine.rake
 - lib/telegram_bot_engine.rb
 - lib/telegram_bot_engine/authorizer.rb