telegram_bot_engine 0.3.4 → 0.6.0

data/app/views/telegram_bot_engine/admin/bots/edit.html.erb

@@ -0,0 +1,69 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Edit Bot</h1>
+  <p class="mt-1 text-sm text-gray-500 font-mono"><%= @bot.slug %></p>
+</div>
+
+<div class="bg-white shadow-sm rounded-lg border border-gray-200 p-6 max-w-2xl mb-6">
+  <%= form_with url: telegram_bot_engine.admin_bot_path(@bot), method: :patch, class: "space-y-4" do %>
+    <div>
+      <label for="bot_name" class="block text-sm font-medium text-gray-700 mb-1">Name</label>
+      <input type="text" name="bot[name]" id="bot_name" value="<%= @bot.name %>" 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">
+    </div>
+    <div>
+      <label for="bot_slug" class="block text-sm font-medium text-gray-700 mb-1">Slug</label>
+      <input type="text" name="bot[slug]" id="bot_slug" value="<%= @bot.slug %>" 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 font-mono">
+    </div>
+    <div>
+      <label for="bot_purpose" class="block text-sm font-medium text-gray-700 mb-1">Purpose (optional)</label>
+      <input type="text" name="bot[purpose]" id="bot_purpose" value="<%= @bot.purpose %>"
+             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">
+    </div>
+    <div class="flex items-center space-x-2">
+      <input type="hidden" name="bot[active]" value="0">
+      <input type="checkbox" name="bot[active]" id="bot_active" value="1" <%= "checked" if @bot.active %>
+             class="h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500">
+      <label for="bot_active" class="text-sm text-gray-700">Active</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <input type="hidden" name="bot[default]" value="0">
+      <input type="checkbox" name="bot[default]" id="bot_default" value="1" <%= "checked" if @bot.default %>
+             class="h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500">
+      <label for="bot_default" class="text-sm text-gray-700">Default bot</label>
+    </div>
+    <div class="flex items-center space-x-3 pt-2">
+      <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">
+        Save
+      </button>
+      <%= link_to "Cancel", telegram_bot_engine.admin_bots_path, class: "text-sm text-gray-600 hover:text-gray-900" %>
+    </div>
+  <% end %>
+</div>
+
+<div class="bg-white shadow-sm rounded-lg border border-gray-200 p-6 max-w-2xl mb-6">
+  <h2 class="text-sm font-medium text-gray-700 mb-1">Rotate token</h2>
+  <p class="text-xs text-gray-500 mb-4">Replaces the stored token and invalidates the cached client immediately (token-rotation safe). Current token: <span class="font-mono"><%= @bot.token.to_s.length > 4 ? "••••#{@bot.token.to_s.last(4)}" : "set" %></span></p>
+  <%= form_with url: telegram_bot_engine.rotate_token_admin_bot_path(@bot), method: :patch, class: "flex items-end space-x-3" do %>
+    <div class="flex-1">
+      <label for="token" class="block text-sm font-medium text-gray-700 mb-1">New token</label>
+      <input type="password" name="token" id="token" required autocomplete="off"
+             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 font-mono"
+             placeholder="123456:ABC-DEF...">
+    </div>
+    <button type="submit"
+            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">
+      Rotate
+    </button>
+  <% end %>
+</div>
+
+<% unless @bot.default? %>
+  <div class="max-w-2xl">
+    <%= button_to "Delete this bot", telegram_bot_engine.admin_bot_path(@bot),
+          method: :delete,
+          data: { turbo_confirm: "Delete bot \"#{@bot.name}\" and its subscribers/allowlist?" },
+          class: "inline-flex items-center px-4 py-2 border border-red-300 rounded-md text-sm font-medium text-red-700 bg-white hover:bg-red-50" %>
+  </div>
+<% end %>

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

@@ -0,0 +1,70 @@
+<div class="mb-6 flex items-center justify-between">
+  <div>
+    <h1 class="text-2xl font-bold text-gray-900">Bots</h1>
+    <p class="mt-1 text-sm text-gray-500"><%= @bots.count %> total</p>
+  </div>
+  <%= link_to "Add Bot", telegram_bot_engine.new_admin_bot_path,
+        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" %>
+</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">Name</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Slug</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Purpose</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Token</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">Webhook</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">
+      <% @bots.each do |bot| %>
+        <tr>
+          <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900"><%= bot.name %></td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono"><%= bot.slug %></td>
+          <td class="px-6 py-4 text-sm text-gray-600"><%= bot.purpose.presence || "-" %></td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono">
+            <%= bot.token.to_s.length > 4 ? "••••#{bot.token.to_s.last(4)}" : "set" %>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap space-x-1">
+            <% if bot.default? %>
+              <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800">Default</span>
+            <% end %>
+            <% if bot.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">
+            <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-gray-100 text-gray-700">
+              Secret set
+            </span>
+            <span class="block text-xs text-gray-400 mt-1">registers in Phase 3</span>
+          </td>
+          <td class="px-6 py-4 whitespace-nowrap text-right text-sm space-x-2">
+            <%= link_to "Edit", telegram_bot_engine.edit_admin_bot_path(bot),
+                  class: "inline-flex items-center px-3 py-1.5 border border-gray-300 rounded text-xs font-medium text-gray-700 bg-white hover:bg-gray-50" %>
+            <% unless bot.default? %>
+              <%= button_to "Delete", telegram_bot_engine.admin_bot_path(bot),
+                    method: :delete,
+                    data: { turbo_confirm: "Delete bot \"#{bot.name}\" and its subscribers/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" %>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @bots.empty? %>
+        <tr>
+          <td colspan="7" class="px-6 py-12 text-center text-sm text-gray-500">
+            No bots yet. <%= link_to "Add one", telegram_bot_engine.new_admin_bot_path, class: "text-blue-600 hover:text-blue-800" %>.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/telegram_bot_engine/admin/bots/new.html.erb

@@ -0,0 +1,53 @@
+<div class="mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Add Bot</h1>
+</div>
+
+<div class="bg-white shadow-sm rounded-lg border border-gray-200 p-6 max-w-2xl">
+  <%= form_with url: telegram_bot_engine.admin_bots_path, method: :post, class: "space-y-4" do %>
+    <div>
+      <label for="bot_name" class="block text-sm font-medium text-gray-700 mb-1">Name</label>
+      <input type="text" name="bot[name]" id="bot_name" value="<%= @bot.name %>" 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="Assistant">
+    </div>
+    <div>
+      <label for="bot_slug" class="block text-sm font-medium text-gray-700 mb-1">Slug</label>
+      <input type="text" name="bot[slug]" id="bot_slug" value="<%= @bot.slug %>" 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 font-mono"
+             placeholder="assistant">
+      <p class="mt-1 text-xs text-gray-500">Stable handle used by the app (e.g. <code>Bot.resolve("assistant")</code>). Cannot collide.</p>
+    </div>
+    <div>
+      <label for="bot_purpose" class="block text-sm font-medium text-gray-700 mb-1">Purpose (optional)</label>
+      <input type="text" name="bot[purpose]" id="bot_purpose" value="<%= @bot.purpose %>"
+             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="Ops alerts from the assistant">
+    </div>
+    <div>
+      <label for="bot_token" class="block text-sm font-medium text-gray-700 mb-1">Token</label>
+      <input type="password" name="bot[token]" id="bot_token" required autocomplete="off"
+             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 font-mono"
+             placeholder="123456:ABC-DEF...">
+      <p class="mt-1 text-xs text-gray-500">Stored as-is until ActiveRecord Encryption keys are provisioned (docs/0001 §6). Rotate later from the bot's edit page.</p>
+    </div>
+    <div class="flex items-center space-x-2">
+      <input type="hidden" name="bot[active]" value="0">
+      <input type="checkbox" name="bot[active]" id="bot_active" value="1" <%= "checked" if @bot.active %>
+             class="h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500">
+      <label for="bot_active" class="text-sm text-gray-700">Active</label>
+    </div>
+    <div class="flex items-center space-x-2">
+      <input type="hidden" name="bot[default]" value="0">
+      <input type="checkbox" name="bot[default]" id="bot_default" value="1" <%= "checked" if @bot.default %>
+             class="h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500">
+      <label for="bot_default" class="text-sm text-gray-700">Default bot <span class="text-gray-400">(promoting this demotes the current default)</span></label>
+    </div>
+    <div class="flex items-center space-x-3 pt-2">
+      <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">
+        Create Bot
+      </button>
+      <%= link_to "Cancel", telegram_bot_engine.admin_bots_path, class: "text-sm text-gray-600 hover:text-gray-900" %>
+    </div>
+  <% end %>
+</div>

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

@@ -2,7 +2,43 @@
   <h1 class="text-2xl font-bold text-gray-900">Dashboard</h1>
 </div>
 
-<% if @bot_username %>
+<% if @bots.any? %>
+  <div class="mb-6 bg-white rounded-lg shadow-sm border border-gray-200 overflow-hidden">
+    <div class="flex items-center justify-between px-6 py-4 border-b border-gray-200">
+      <h2 class="text-sm font-medium text-gray-500 uppercase tracking-wider">Bots</h2>
+      <%= link_to "Manage", telegram_bot_engine.admin_bots_path, class: "text-sm text-blue-600 hover:text-blue-800" %>
+    </div>
+    <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">Name</th>
+          <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Slug</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-right text-xs font-medium text-gray-500 uppercase tracking-wider">Active Subscribers</th>
+        </tr>
+      </thead>
+      <tbody class="bg-white divide-y divide-gray-200">
+        <% @bots.each do |bot| %>
+          <tr>
+            <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900"><%= bot.name %></td>
+            <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono"><%= bot.slug %></td>
+            <td class="px-6 py-4 whitespace-nowrap space-x-1">
+              <% if bot.default? %>
+                <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800">Default</span>
+              <% end %>
+              <% if bot.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-right text-sm font-semibold text-gray-900"><%= @bot_active_counts[bot] %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% elsif @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>
@@ -31,6 +67,9 @@
 </div>
 
 <div class="flex space-x-4">
+  <%= link_to "Manage Bots", telegram_bot_engine.admin_bots_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" %>
+
   <%= 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" %>
 

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

@@ -29,6 +29,17 @@
              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>
+    <% if @bots.any? %>
+      <div>
+        <label for="bot_id" class="block text-sm font-medium text-gray-700 mb-1">Bot</label>
+        <select name="bot_id" id="bot_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">
+          <option value="">All</option>
+          <% @bots.each do |bot| %>
+            <option value="<%= bot.id %>" <%= "selected" if params[:bot_id].to_s == bot.id.to_s %>><%= bot.name %></option>
+          <% end %>
+        </select>
+      </div>
+    <% end %>
     <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">
@@ -103,11 +114,11 @@
     </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),
+        <%= link_to "Previous", telegram_bot_engine.admin_events_path(type: params[:type], action_name: params[:action_name], chat_id: params[:chat_id], bot_id: params[:bot_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),
+        <%= link_to "Next", telegram_bot_engine.admin_events_path(type: params[:type], action_name: params[:action_name], chat_id: params[:chat_id], bot_id: params[:bot_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>

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

@@ -16,6 +16,8 @@
           <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 "Bots", telegram_bot_engine.admin_bots_path,
+                  class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.include?('bots') ? '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 %>

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

@@ -3,12 +3,30 @@
   <p class="mt-1 text-sm text-gray-500"><%= @subscriptions.count %> total</p>
 </div>
 
+<% if @bots.any? %>
+  <div class="mb-6 bg-white shadow-sm rounded-lg border border-gray-200 p-4">
+    <%= form_with url: telegram_bot_engine.admin_subscriptions_path, method: :get, local: true, class: "flex items-end space-x-3" do %>
+      <div>
+        <label for="bot_id" class="block text-sm font-medium text-gray-700 mb-1">Bot</label>
+        <select name="bot_id" id="bot_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">
+          <option value="">All bots</option>
+          <% @bots.each do |bot| %>
+            <option value="<%= bot.id %>" <%= "selected" if params[:bot_id].to_s == bot.id.to_s %>><%= bot.name %></option>
+          <% end %>
+        </select>
+      </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">Filter</button>
+    <% end %>
+  </div>
+<% end %>
+
 <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">Bot</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>
@@ -24,6 +42,9 @@
           <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.bot&.slug || "default" %>
+          </td>
           <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 font-mono">
             <%= subscription.chat_id %>
           </td>
@@ -53,7 +74,7 @@
 
       <% if @subscriptions.empty? %>
         <tr>
-          <td colspan="6" class="px-6 py-12 text-center text-sm text-gray-500">
+          <td colspan="7" class="px-6 py-12 text-center text-sm text-gray-500">
             No subscriptions yet.
           </td>
         </tr>

data/config/routes.rb

@@ -4,6 +4,9 @@ TelegramBotEngine::Engine.routes.draw do
   scope module: :admin, as: :admin do
     root to: "dashboard#show"
     get "dashboard", to: "dashboard#show", as: :dashboard
+    resources :bots, except: %i[show] do
+      member { patch :rotate_token }
+    end
     resources :subscriptions, only: %i[index update destroy]
     resources :allowlist, only: %i[index create destroy]
     resources :events, only: %i[index]

data/db/migrate/004_create_telegram_bot_engine_bots.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateTelegramBotEngineBots < ActiveRecord::Migration[7.0]
+  def change
+    create_table :telegram_bot_engine_bots do |t|
+      t.string  :name,           null: false
+      t.string  :slug,           null: false
+      t.string  :purpose
+      t.string  :token,          null: false                 # encrypted at rest once keys are provisioned (docs/0001 §6)
+      t.string  :webhook_secret, null: false                 # per-bot inbound secret path segment
+      t.boolean :active,         null: false, default: true
+      t.boolean :default,        null: false, default: false # exactly one row true (enforced in the model)
+
+      t.timestamps
+    end
+
+    add_index :telegram_bot_engine_bots, :slug, unique: true
+    add_index :telegram_bot_engine_bots, :webhook_secret, unique: true
+    add_index :telegram_bot_engine_bots, :active
+  end
+end

data/db/migrate/005_add_bot_to_telegram_bot_engine_subscriptions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Per-bot subscribers (docs/0001 §3.4): a chat can now subscribe to more than one bot,
+# so global chat_id uniqueness becomes (bot_id, chat_id) uniqueness.
+#
+# Additive + rollback-safe: bot_id is nullable and there is NO data backfill. Back-compat
+# is handled at the read layer (Subscription.for_bot(default_bot) folds nil-bot_id rows in),
+# so a rolled-back gem that knows nothing about bot_id still reads every row (docs/0001 §9).
+#
+# A partial unique index on (chat_id WHERE bot_id IS NULL) preserves the duplicate guard the
+# old global unique index gave the pre-multi-bot (default-bot) population — composite unique
+# indexes treat NULL bot_id as distinct, so that set would otherwise lose DB-level protection.
+#
+# Explicit up/down so a rollback faithfully restores the original UNIQUE(chat_id) index
+# instead of silently leaving it non-unique (the default `change` inverse would).
+class AddBotToTelegramBotEngineSubscriptions < ActiveRecord::Migration[7.0]
+  DEFAULT_BOT_UNIQUE = "index_tbe_subscriptions_on_chat_id_default_bot"
+
+  def up
+    add_column :telegram_bot_engine_subscriptions, :bot_id, :bigint
+    add_index :telegram_bot_engine_subscriptions, :bot_id
+
+    remove_index :telegram_bot_engine_subscriptions, :chat_id # drop the global UNIQUE(chat_id)
+    add_index :telegram_bot_engine_subscriptions, :chat_id    # keep a non-unique lookup index
+    add_index :telegram_bot_engine_subscriptions, %i[bot_id chat_id], unique: true
+    add_index :telegram_bot_engine_subscriptions, :chat_id, unique: true,
+              where: "bot_id IS NULL", name: DEFAULT_BOT_UNIQUE
+  end
+
+  def down
+    remove_index :telegram_bot_engine_subscriptions, name: DEFAULT_BOT_UNIQUE
+    remove_index :telegram_bot_engine_subscriptions, column: %i[bot_id chat_id]
+    remove_index :telegram_bot_engine_subscriptions, :chat_id
+    add_index :telegram_bot_engine_subscriptions, :chat_id, unique: true # restore original guard
+    remove_index :telegram_bot_engine_subscriptions, :bot_id
+    remove_column :telegram_bot_engine_subscriptions, :bot_id
+  end
+end

data/db/migrate/006_add_bot_to_telegram_bot_engine_allowed_users.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Per-bot allowlist (docs/0001 §3.5): an AllowedUser may be scoped to a bot. A nil bot_id
+# is a GLOBAL allow entry that applies to every bot — exactly today's behavior, so existing
+# rows (all nil) keep authorizing as before. Additive + nullable.
+#
+# Partial unique index on (username WHERE bot_id IS NULL) preserves the duplicate guard the
+# old global unique(username) index gave global entries (NULLs are distinct in the composite
+# index). Explicit up/down so rollback restores the original UNIQUE(username) faithfully.
+class AddBotToTelegramBotEngineAllowedUsers < ActiveRecord::Migration[7.0]
+  GLOBAL_UNIQUE = "index_tbe_allowed_users_on_username_global"
+
+  def up
+    add_column :telegram_bot_engine_allowed_users, :bot_id, :bigint
+    add_index :telegram_bot_engine_allowed_users, :bot_id
+
+    remove_index :telegram_bot_engine_allowed_users, :username # drop the global UNIQUE(username)
+    add_index :telegram_bot_engine_allowed_users, :username    # keep a non-unique lookup index
+    add_index :telegram_bot_engine_allowed_users, %i[bot_id username], unique: true
+    add_index :telegram_bot_engine_allowed_users, :username, unique: true,
+              where: "bot_id IS NULL", name: GLOBAL_UNIQUE
+  end
+
+  def down
+    remove_index :telegram_bot_engine_allowed_users, name: GLOBAL_UNIQUE
+    remove_index :telegram_bot_engine_allowed_users, column: %i[bot_id username]
+    remove_index :telegram_bot_engine_allowed_users, :username
+    add_index :telegram_bot_engine_allowed_users, :username, unique: true # restore original guard
+    remove_index :telegram_bot_engine_allowed_users, :bot_id
+    remove_column :telegram_bot_engine_allowed_users, :bot_id
+  end
+end

data/db/migrate/007_add_bot_to_telegram_bot_engine_events.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Per-bot event log (docs/0001 §3.8): tag delivery events with the bot that produced
+# them so the events admin screen can be scoped per bot. Nullable + additive; command
+# events (start/stop/help) stay nil until the inbound dispatcher knows the bot (Phase 3).
+class AddBotToTelegramBotEngineEvents < ActiveRecord::Migration[7.0]
+  def change
+    add_column :telegram_bot_engine_events, :bot_id, :bigint
+    add_index :telegram_bot_engine_events, :bot_id
+  end
+end

data/db/migrate/008_add_webhook_id_to_telegram_bot_engine_bots.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# Decouple the inbound ROUTING key from the bearer SECRET (security hardening, docs/0001
+# §3.6/§3.7). Previously the webhook URL embedded `webhook_secret`, which Rails logs verbatim
+# in request lines and SQL binds — leaking the secret_token to any log reader. `webhook_id` is
+# a stable, NON-secret public id that goes in the URL path; `webhook_secret` now lives ONLY in
+# the X-Telegram-Bot-Api-Secret-Token header. Additive + backfilled; uses update_columns via an
+# anonymous model so no Bot callbacks/validations fire during the migration.
+class AddWebhookIdToTelegramBotEngineBots < ActiveRecord::Migration[7.0]
+  def up
+    add_column :telegram_bot_engine_bots, :webhook_id, :string
+
+    seam = Class.new(ActiveRecord::Base) { self.table_name = "telegram_bot_engine_bots" }
+    seam.reset_column_information
+    seam.where(webhook_id: nil).find_each do |row|
+      row.update_columns(webhook_id: SecureRandom.hex(16))
+    end
+
+    change_column_null :telegram_bot_engine_bots, :webhook_id, false
+    add_index :telegram_bot_engine_bots, :webhook_id, unique: true
+  end
+
+  def down
+    remove_index :telegram_bot_engine_bots, :webhook_id
+    remove_column :telegram_bot_engine_bots, :webhook_id
+  end
+end

data/lib/telegram_bot_engine/authorizer.rb

@@ -2,16 +2,17 @@
 
 module TelegramBotEngine
   class Authorizer
-    def self.authorized?(username)
+    # Authorizes an inbound command username. `bot: nil` ⇒ global behavior, unchanged
+    # (docs/0001 §3.5). When a bot is given in :database mode, both global (nil bot_id)
+    # and that bot's own allow entries apply.
+    def self.authorized?(username, bot: nil)
       return true if TelegramBotEngine.config.allowed_usernames.nil?
 
-      allowed = resolve_allowed_usernames
+      allowed = resolve_allowed_usernames(bot)
       allowed.map(&:downcase).include?(username&.downcase)
     end
 
-    private
-
-    def self.resolve_allowed_usernames
+    def self.resolve_allowed_usernames(bot = nil)
       config = TelegramBotEngine.config.allowed_usernames
 
       case config
@@ -20,10 +21,13 @@ module TelegramBotEngine
       when Proc
         config.call
       when :database
-        TelegramBotEngine::AllowedUser.pluck(:username)
+        scope = bot ? TelegramBotEngine::AllowedUser.for_bot(bot) : TelegramBotEngine::AllowedUser.all
+        scope.pluck(:username)
       else
         []
       end
     end
+
+    private_class_method :resolve_allowed_usernames
   end
 end

data/lib/telegram_bot_engine/configuration.rb

@@ -3,7 +3,9 @@
 module TelegramBotEngine
   class Configuration
     attr_accessor :allowed_usernames, :admin_enabled, :unauthorized_message, :welcome_message,
-                  :event_logging, :event_retention_days
+                  :event_logging, :event_retention_days,
+                  # Phase 3 — webhook registrar (§3.6) + inbound dispatcher (§3.7)
+                  :webhook_base_url, :webhook_mount_path, :dispatch_controller, :auto_register_webhooks
 
     def initialize
       @allowed_usernames = nil
@@ -12,6 +14,11 @@ module TelegramBotEngine
       @welcome_message = "Welcome %{username}! Available commands:\n%{commands}"
       @event_logging = true
       @event_retention_days = 30
+
+      @webhook_base_url = nil               # host public https base, e.g. "https://app.example.com"
+      @webhook_mount_path = "/telegram/bot" # MUST match `mount TelegramBotEngine::Dispatch, at:`
+      @dispatch_controller = nil            # host UpdatesController (String/class) incl. SubscriberCommands
+      @auto_register_webhooks = true        # (un)register webhooks on Bot save/destroy when base_url present
     end
   end
 end

data/lib/telegram_bot_engine/dispatch.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "action_dispatch"
+require "active_support/security_utils"
+
+module TelegramBotEngine
+  # The single inbound webhook endpoint for ALL bots (docs/0001 §3.7). The host app mounts
+  # this once: `mount TelegramBotEngine::Dispatch, at: config.webhook_mount_path`. For
+  # `POST <mount>/:webhook_secret` it resolves the Bot by its secret path segment, validates
+  # the X-Telegram-Bot-Api-Secret-Token header (telegram-bot 0.16 does NOT — docs/0001 §9),
+  # then hands off to the host's UpdatesController via `dispatch(bot.client, update, request)`.
+  class Dispatch
+    SECRET_TOKEN_HEADER = "HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN"
+    # The resolved Bot record is exposed to the controller here so SubscriberCommands can
+    # scope inbound /start·/stop to the bot the update arrived for.
+    ENV_BOT_KEY = "telegram_bot_engine.bot"
+
+    def self.call(env)
+      new.call(env)
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      return respond(405, "method not allowed") unless request.post?
+
+      bot = resolve_bot(request)
+      return respond(404, "unknown bot") unless bot
+      return respond(403, "invalid secret token") unless valid_secret_token?(request, bot)
+
+      controller = dispatch_controller
+      return respond(503, "dispatch_controller not configured") unless controller
+
+      begin
+        update = request.request_parameters
+      rescue ActionDispatch::Http::Parameters::ParseError
+        return respond(400, "bad request")
+      end
+
+      request.set_header(ENV_BOT_KEY, bot)
+      controller.dispatch(bot.client, update, request)
+      respond(200, "")
+    end
+
+    private
+
+    def resolve_bot(request)
+      # Route on the NON-secret webhook_id path segment; the secret_token is validated from the
+      # header only (docs/0001 §3.7) so the credential never reaches request/SQL logs.
+      webhook_id = request.path_info.to_s.split("/").reject(&:empty?).last
+      return nil if webhook_id.blank?
+
+      TelegramBotEngine::Bot.active.find_by(webhook_id: webhook_id)
+    end
+
+    def valid_secret_token?(request, bot)
+      provided = request.get_header(SECRET_TOKEN_HEADER).to_s
+      return false if provided.empty?
+
+      ActiveSupport::SecurityUtils.secure_compare(provided, bot.webhook_secret.to_s)
+    end
+
+    def dispatch_controller
+      target = TelegramBotEngine.config.dispatch_controller
+      return nil if target.blank?
+
+      target.respond_to?(:dispatch) ? target : target.to_s.constantize
+    end
+
+    def respond(status, body)
+      [status, { "Content-Type" => "text/plain; charset=utf-8" }, [body]]
+    end
+  end
+end