refactor: migrate handlers to plugins architecture

Author: GrantBirki

docs/design.md

@@ -32,7 +32,7 @@ Note: The `hooks` gem name is already taken on RubyGems, so this project is name
 
 2. **Plugin Architecture**
 
-   * **Team Handlers**: `class MyHandler < Hooks::Handlers::Base`
+   * **Team Handlers**: `class MyHandler < Hooks::Plugins::Handlers::Base`
      * Must implement `#call(payload:, headers:, config:)` method
      * `payload`: parsed request body (JSON Hash or raw String)
      * `headers`: HTTP headers as Hash with string keys
@@ -142,7 +142,7 @@ lib/hooks/
 │   ├── logger_factory.rb     # Structured JSON logger + context enrichment
 │
 ├── handlers/
-│   └── base.rb               # `Hooks::Handlers::Base` interface: defines #call
+│   └── base.rb               # `Hooks::Plugins::Handlers::Base` interface: defines #call
 │
 ├── plugins/
 │   ├── lifecycle.rb          # `Hooks::Plugins::Lifecycle` hooks (on_request, response, error)
@@ -520,12 +520,12 @@ The health endpoint provides comprehensive status information for load balancers
 
 ### Core Classes
 
-#### `Hooks::Handlers::Base`
+#### `Hooks::Plugins::Handlers::Base`
 
 Base class for all webhook handlers.
 
 ```ruby
-class MyHandler < Hooks::Handlers::Base
+class MyHandler < Hooks::Plugins::Handlers::Base
   # @param payload [Hash, String] Parsed request body or raw string
   # @param headers [Hash<String, String>] HTTP headers
   # @param config [Hash] Merged endpoint configuration

lib/hooks.rb

@@ -2,9 +2,8 @@
 
 require_relative "hooks/version"
 require_relative "hooks/core/builder"
-require_relative "hooks/handlers/base"
 
-# Load all plugins (request validators, lifecycle hooks, etc.)
+# Load all plugins (auth plugins, handler plugins, lifecycle hooks, etc.)
 Dir[File.join(__dir__, "hooks/plugins/**/*.rb")].sort.each do |file|
   require file
 end

lib/hooks/app/api.rb

@@ -5,8 +5,8 @@
 require "securerandom"
 require_relative "helpers"
 require_relative "auth/auth"
-require_relative "../handlers/base"
-require_relative "../handlers/default"
+require_relative "../plugins/handlers/base"
+require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
 

lib/hooks/app/endpoints/catchall.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "grape"
-require_relative "../../handlers/default"
+require_relative "../../plugins/handlers/default"
 require_relative "../helpers"
 
 module Hooks

lib/hooks/app/helpers.rb

@@ -92,8 +92,8 @@ def load_handler(handler_class_name, handler_dir)
           handler_class = Object.const_get(handler_class_name)
 
           # Security: Ensure the loaded class inherits from the expected base class
-          unless handler_class < Hooks::Handlers::Base
-            error!("handler class must inherit from Hooks::Handlers::Base", 400)
+          unless handler_class < Hooks::Plugins::Handlers::Base
+            error!("handler class must inherit from Hooks::Plugins::Handlers::Base", 400)
           end
 
           handler_class.new

lib/hooks/handlers/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Handlers
+      # Base class for all webhook handlers
+      #
+      # All custom handlers must inherit from this class and implement the #call method
+      class Base
+        # Process a webhook request
+        #
+        # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
+        # @param headers [Hash<String, String>] HTTP headers
+        # @param config [Hash] Merged endpoint configuration including opts section
+        # @return [Hash, String, nil] Response body (will be auto-converted to JSON)
+        # @raise [NotImplementedError] if not implemented by subclass
+        def call(payload:, headers:, config:)
+          raise NotImplementedError, "Handler must implement #call method"
+        end
+
+        # Short logger accessor for all subclasses
+        # @return [Hooks::Log] Logger instance
+        #
+        # Provides a convenient way for handlers to log messages without needing
+        # to reference the full Hooks::Log namespace.
+        #
+        # @example Logging an error in an inherited class
+        #   log.error("oh no an error occured")
+        def log
+          Hooks::Log.instance
+        end
+      end
+    end
+  end
+end

lib/hooks/plugins/handlers/base.rb

@@ -2,7 +2,7 @@
 
 # Default handler when no custom handler is found
 # This handler simply acknowledges receipt of the webhook and shows a few of the built-in features
-class DefaultHandler < Hooks::Handlers::Base
+class DefaultHandler < Hooks::Plugins::Handlers::Base
   def call(payload:, headers:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")

lib/hooks/handlers/default.rb lib/hooks/plugins/handlers/default.rblib/hooks/handlers/default.rb renamed to lib/hooks/plugins/handlers/default.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Example handler for GitHub webhooks
-class GithubHandler < Hooks::Handlers::Base
+class GithubHandler < Hooks::Plugins::Handlers::Base
   # Process GitHub webhook
   #
   # @param payload [Hash, String] GitHub webhook payload

spec/acceptance/plugins/handlers/github_handler.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class OktaHandler < Hooks::Handlers::Base
+class OktaHandler < Hooks::Plugins::Handlers::Base
   def call(payload:, headers:, config:)
     return {
       status: "success"