hooksmith 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80476ba099d00e9dfefb14d1b05d696a4b5cef3eb655e6f145c334e86fcf1ac
-  data.tar.gz: 4c1e6ae0d6cdfe4e1a013e2028b446912a636b295d949d499801e83ce4a640c8
+  metadata.gz: 82cacda1d785736b14476d699c2d18e90d65036f2b4e291d03dd2b393a907d14
+  data.tar.gz: 65407cf717e2e3ac6edede0392ed319250b3e0c06fc61dc0d730fd82fafead3c
 SHA512:
-  metadata.gz: 0c004376be79241af2a779aa9eeafe4bd4075d09ab45da029d8c9d88ed6faa2d1248652b160ac0761a107c7e0ddddec81a41cec8ed1f5e147f1e6f43d8dd9ca0
-  data.tar.gz: c555b8226888a88774fb0fd97bd3b57a1741a35bdd615d462bbd479786ab6a1aede0875a070cb9fcbc0d76f4b3ad6ac85256ff023dd2d9e9ccd552fcd8d928fe
+  metadata.gz: bbd5f49b4248a597997816a03c0e9624c93ec3fe8185837398564360a16663defe758463ba2528f1af38e53e0816fadf1b61d5243591835f8b84cd9c822a7f40
+  data.tar.gz: b13ef16ba8d73c011c410ca838575f9a4eb8b3bdc58560b392cf88350f8520d0752a7081e556dc649fa5e6ad89441e975bde9e57085717b98356516a6e801f81

data/README.md

@@ -48,6 +48,52 @@ Hooksmith.configure do |config|
 end
 ```
 
+### Persisting Webhook Events (Optional)
+
+Hooksmith can optionally persist incoming webhook events to your database. Configure it with your own ActiveRecord model and mapping logic.
+
+1) Create a model in your app (example):
+
+```ruby
+class WebhookEvent < ApplicationRecord
+  self.table_name = 'webhook_events'
+end
+```
+
+2) Example migration (customize fields as needed):
+
+```ruby
+create_table :webhook_events do |t|
+  t.string   :provider
+  t.string   :event
+  t.jsonb    :payload
+  t.datetime :received_at
+  t.timestamps
+  t.index    :event
+  t.index    :received_at
+end
+```
+
+3) Configure Hooksmith to record events:
+
+```ruby
+Hooksmith.configure do |config|
+  config.event_store do |store|
+    store.enabled = true
+    store.model_class_name = 'WebhookEvent' # your model class
+    store.record_timing = :before # :before, :after, or :both
+    store.mapper = ->(provider:, event:, payload:) {
+      {
+        provider: provider.to_s,
+        event: event.to_s,
+        payload:,
+        received_at: (Time.respond_to?(:current) ? Time.current : Time.now)
+      }
+    }
+  end
+end
+```
+
 ## Implementing a Processor
 Create a processor by inheriting from `Hooksmith::Processor::Base`:
 

data/lib/hooksmith/config/event_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Config
+    # EventStore holds settings for optional event persistence.
+    class EventStore
+      # Whether persistence is enabled.
+      attr_accessor :enabled
+      # Class name of the model used to persist events. Must respond to .create!(attrs)
+      attr_accessor :model_class_name
+      # Proc to map provider/event/payload to attributes persisted
+      attr_accessor :mapper
+      # When to record: :before, :after, or :both
+      attr_accessor :record_timing
+
+      def initialize
+        @enabled = false
+        # No default model in the gem; applications should provide their own model
+        @model_class_name = nil
+        @record_timing = :before
+        @mapper = default_mapper
+      end
+
+      def model_class
+        return nil if model_class_name.nil?
+
+        Object.const_get(model_class_name)
+      rescue NameError
+        nil
+      end
+
+      private
+
+      def default_mapper
+        lambda do |provider:, event:, payload:|
+          now = Time.respond_to?(:current) ? Time.current : Time.now
+          {
+            provider: provider.to_s,
+            event: event.to_s,
+            payload:,
+            received_at: now
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hooksmith/config/provider.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Config
+    # Provider is used internally by the DSL to collect processor registrations.
+    class Provider
+      # @return [Symbol, String] the provider name.
+      attr_reader :provider
+      # @return [Array<Hash>] list of entries registered.
+      attr_reader :entries
+
+      def initialize(provider)
+        @provider = provider
+        @entries = []
+      end
+
+      # Registers a processor for a specific event.
+      #
+      # @param event [Symbol, String] the event name.
+      # @param processor_class_name [String] the processor class name.
+      def register(event, processor_class_name)
+        entries << { event: event.to_sym, processor: processor_class_name }
+      end
+    end
+  end
+end

data/lib/hooksmith/configuration.rb

@@ -7,18 +7,21 @@ module Hooksmith
   class Configuration
     # @return [Hash] a registry mapping provider symbols to arrays of processor entries.
     attr_reader :registry
+    # @return [Hooksmith::Config::EventStore] configuration for event persistence
+    attr_reader :event_store_config
 
     def initialize
       # Registry structure: { provider_symbol => [{ event: event_symbol, processor: ProcessorClass }, ...] }
       @registry = Hash.new { |hash, key| hash[key] = [] }
+      @event_store_config = Hooksmith::Config::EventStore.new
     end
 
     # Groups registrations under a specific provider.
     #
     # @param provider_name [Symbol, String] the provider name (e.g., :stripe)
-    # @yield [ProviderConfig] a block yielding a ProviderConfig object
+    # @yield [Hooksmith::Config::Provider] a block yielding a Provider object
     def provider(provider_name)
-      provider_config = ProviderConfig.new(provider_name)
+      provider_config = Hooksmith::Config::Provider.new(provider_name)
       yield(provider_config)
       registry[provider_name.to_sym].concat(provider_config.entries)
     end
@@ -40,26 +43,23 @@ module Hooksmith
     def processors_for(provider, event)
       registry[provider.to_sym].select { |entry| entry[:event] == event.to_sym }
     end
-  end
-
-  # ProviderConfig is used internally by the DSL to collect processor registrations.
-  class ProviderConfig
-    # @return [Symbol, String] the provider name.
-    attr_reader :provider
-    # @return [Array<Hash>] list of entries registered.
-    attr_reader :entries
-
-    def initialize(provider)
-      @provider = provider
-      @entries = []
-    end
 
-    # Registers a processor for a specific event.
+    # Configure event store persistence.
     #
-    # @param event [Symbol, String] the event name.
-    # @param processor_class_name [String] the processor class name.
-    def register(event, processor_class_name)
-      entries << { event: event.to_sym, processor: processor_class_name }
+    # @yield [Hooksmith::Config::EventStore] a block yielding an EventStore object
+    # @example
+    #   Hooksmith.configure do |config|
+    #     config.event_store do |store|
+    #       store.enabled = true
+    #       store.model_class_name = 'MyApp::WebhookEvent'
+    #       store.record_timing = :before # or :after, or :both
+    #       store.mapper = ->(provider:, event:, payload:) {
+    #         { provider:, event: event.to_s, payload:, received_at: (Time.respond_to?(:current) ? Time.current : Time.now) }
+    #       }
+    #     end
+    #   end
+    def event_store
+      yield(@event_store_config)
     end
   end
 end

data/lib/hooksmith/dispatcher.rb

@@ -28,6 +28,9 @@ module Hooksmith
     #
     # @raise [MultipleProcessorsError] if multiple processors qualify.
     def run!
+      # Optionally record the incoming event before processing.
+      Hooksmith::EventRecorder.record!(provider: @provider, event: @event, payload: @payload, timing: :before)
+
       # Fetch all processors registered for this provider and event.
       entries = Hooksmith.configuration.processors_for(@provider, @event)
 
@@ -46,7 +49,12 @@ module Hooksmith
       raise MultipleProcessorsError.new(@provider, @event, @payload) if matching_processors.size > 1
 
       # Exactly one matching processor.
-      matching_processors.first.process!
+      result = matching_processors.first.process!
+
+      # Optionally record the event after successful processing.
+      Hooksmith::EventRecorder.record!(provider: @provider, event: @event, payload: @payload, timing: :after)
+
+      result
     rescue StandardError => e
       Hooksmith.logger.error("Error processing #{@provider} event #{@event}: #{e.message}")
       raise e

data/lib/hooksmith/event_recorder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Records webhook events to a configurable persistence model.
+  #
+  # This recorder is resilient: failures to persist are logged and do not
+  # impact the main processing flow.
+  module EventRecorder
+    module_function
+
+    # Record an event if the event store is enabled.
+    #
+    # @param provider [Symbol, String]
+    # @param event [Symbol, String]
+    # @param payload [Hash]
+    # @param timing [Symbol] one of :before or :after
+    def record!(provider:, event:, payload:, timing: :before)
+      config = Hooksmith.configuration.event_store_config
+      return unless config.enabled
+      return unless record_for_timing?(config, timing)
+
+      model_class = config.model_class
+      unless model_class
+        Hooksmith.logger.warn("Event store enabled but model '#{config.model_class_name}' not found")
+        return
+      end
+
+      attributes = safe_map(config, provider:, event:, payload:)
+      model_class.create!(attributes)
+    rescue StandardError => e
+      Hooksmith.logger.error("Failed to record webhook event: #{e.message}")
+    end
+
+    # Determine whether to record depending on the configured timing.
+    def record_for_timing?(config, timing)
+      case config.record_timing
+      when :both then true
+      when :before then timing == :before
+      when :after then timing == :after
+      end
+    end
+    private_class_method :record_for_timing?
+
+    # Safely map attributes using the configured mapper.
+    def safe_map(config, provider:, event:, payload:)
+      mapper = config.mapper
+      mapper.call(provider:, event:, payload:)
+    rescue StandardError => e
+      Hooksmith.logger.error("Event mapper raised: #{e.message}")
+      {}
+    end
+    private_class_method :safe_map
+  end
+end

data/lib/hooksmith/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hooksmith
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/hooksmith.rb

@@ -2,8 +2,11 @@
 
 require 'hooksmith/version'
 require 'hooksmith/configuration'
+require 'hooksmith/config/provider'
+require 'hooksmith/config/event_store'
 require 'hooksmith/dispatcher'
 require 'hooksmith/logger'
+require 'hooksmith/event_recorder'
 require 'hooksmith/processor/base'
 require 'hooksmith/railtie' if defined?(Rails)
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hooksmith
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - gregoryrivage
 bindir: exe
 cert_chain: []
-date: 2025-03-13 00:00:00.000000000 Z
+date: 2025-09-05 00:00:00.000000000 Z
 dependencies: []
 description: Hooksmith is a gem that allows you to handle webhooks in your Rails application.
   It provides a simple and flexible way to receive, validate, and process webhooks
@@ -27,10 +27,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- hooksmith-0.1.0.gem
 - lib/hooksmith.rb
+- lib/hooksmith/config/event_store.rb
+- lib/hooksmith/config/provider.rb
 - lib/hooksmith/configuration.rb
 - lib/hooksmith/dispatcher.rb
+- lib/hooksmith/event_recorder.rb
 - lib/hooksmith/logger.rb
 - lib/hooksmith/processor/base.rb
 - lib/hooksmith/railtie.rb