hooksmith 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef153cc049df6fb2994b69e8e7fc5a260c1cb57262a7157871b36baf38aff34d
+  data.tar.gz: a0fb98c2d45e68e4adca1bbd0fc9a3ed44747cff6aa8f56b78ef1bcc6222d4d3
+SHA512:
+  metadata.gz: 7bfdc41f3a150ebb6c9ee9685ee22f3d8d3eabbd0314dbb0a42b855f41ead9a3277d0fe8049aef6b05034c6efa540cd17a5d017906b5432000af3f8532a7513b
+  data.tar.gz: bcd1dd3624624bdfcc288591b1cfde025c3ccfce80f71fcbc649ee8119b2f143bf00c5edc899c7db3b4acf0572d0ebbd802909663a3231c215c645971ceb4b95

data/.rubocop.yml

@@ -0,0 +1,419 @@
+AllCops:
+  NewCops: enable
+
+# Style
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - 'db/schema.rb'
+    - 'db/migrate/*'
+Style/AsciiComments:
+  Enabled: false
+Style/BisectedAttrAccessor:
+  Enabled: true
+Style/CaseLikeIf:
+  Enabled: true
+Style/ClassEqualityComparison:
+  Enabled: true
+Style/CollectionCompact:
+  Enabled: true
+Style/CombinableLoops:
+  Enabled: true
+Style/ConcatArrayLiterals:
+  Enabled: true
+Style/ConditionalAssignment:
+  EnforcedStyle: assign_to_condition
+Style/DirEmpty:
+  Enabled: true
+Style/DocumentDynamicEvalDefinition:
+  Enabled: true
+Style/EmptyMethod:
+  EnforcedStyle: compact
+Style/EmptyHeredoc:
+  Enabled: true
+Style/EndlessMethod:
+  Enabled: true
+  EnforcedStyle: disallow
+Style/EnvHome:
+  Enabled: true
+Style/ExactRegexpMatch:
+  Enabled: true
+Style/FetchEnvVar:
+  Enabled: true
+Style/FileEmpty:
+  Enabled: true
+Style/FileRead:
+  Enabled: true
+Style/FileWrite:
+  Enabled: true
+Style/HashAsLastArrayItem:
+  Enabled: true
+Style/HashConversion:
+  Enabled: true
+Style/HashEachMethods:
+  Enabled: true
+Style/HashExcept:
+  Enabled: true
+Style/HashLikeCase:
+  Enabled: true
+Style/HashSyntax:
+  EnforcedShorthandSyntax: always
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Style/IfWithBooleanLiteralBranches:
+  Enabled: true
+Style/InPatternThen:
+  Enabled: true
+Style/KeywordParametersOrder:
+  Enabled: true
+Style/MagicCommentFormat:
+  Enabled: true
+Style/MapCompactWithConditionalBlock:
+  Enabled: true
+Style/MapToHash:
+  Enabled: true
+Style/MapToSet:
+  Enabled: true
+Style/MinMaxComparison:
+  Enabled: true
+Style/NegatedIfElseCondition:
+  Enabled: true
+Style/NumberedParameters:
+  Enabled: true
+  EnforcedStyle: disallow
+Style/OperatorMethodCall:
+  Enabled: true
+Style/QuotedSymbols:
+  Enabled: true
+Style/RedundantArgument:
+  Enabled: true
+Style/RedundantAssignment:
+  Enabled: true
+Style/RedundantDoubleSplatHashBraces:
+  Enabled: true
+Style/RedundantEach:
+  Enabled: true
+Style/RedundantFetchBlock:
+  Enabled: true
+Style/RedundantInitialize:
+  Enabled: true
+Style/RedundantSelfAssignment:
+  Enabled: false
+Style/RedundantSelfAssignmentBranch:
+  Enabled: true
+Style/RedundantStringEscape:
+  Enabled: true
+Style/ReturnNilInPredicateMethodDefinition:
+  Enabled: true
+Style/SoleNestedConditional:
+  Enabled: true
+Style/StringChars:
+  Enabled: true
+Style/StringConcatenation:
+  Enabled: true
+Style/SwapValues:
+  Enabled: true
+Style/YAMLFileRead:
+  Enabled: true
+Style/AmbiguousEndlessMethodDefinition:
+  Enabled: true
+Style/ArgumentsForwarding:
+  Enabled: true
+Style/ArrayIntersect:
+  Enabled: true
+Style/BitwisePredicate:
+  Enabled: true
+Style/CombinableDefined:
+  Enabled: true
+Style/ComparableClamp:
+  Enabled: true
+Style/DataInheritance:
+  Enabled: true
+Style/DigChain:
+  Enabled: true
+Style/FileNull:
+  Enabled: true
+Style/FileTouch:
+  Enabled: true
+Style/HashSlice:
+  Enabled: true
+Style/ItAssignment:
+  Enabled: true
+Style/KeywordArgumentsMerging:
+  Enabled: true
+Style/MapIntoArray:
+  Enabled: true
+Style/MultilineInPatternThen:
+  Enabled: true
+Style/NestedFileDirname:
+  Enabled: true
+Style/NilLambda:
+  Enabled: true
+Style/NumberedParametersLimit:
+  Enabled: true
+Style/ObjectThen:
+  Enabled: true
+Style/OpenStructUse:
+  Enabled: true
+Style/RedundantArrayConstructor:
+  Enabled: true
+Style/RedundantConstantBase:
+  Enabled: true
+Style/RedundantCurrentDirectoryInPath:
+  Enabled: true
+Style/RedundantFilterChain:
+  Enabled: true
+Style/RedundantFormat:
+  Enabled: true
+Style/RedundantHeredocDelimiterQuotes:
+  Enabled: true
+Style/RedundantInterpolationUnfreeze:
+  Enabled: true
+Style/RedundantLineContinuation:
+  Enabled: true
+Style/RedundantRegexpArgument:
+  Enabled: true
+Style/RedundantRegexpConstructor:
+  Enabled: true
+Style/SafeNavigationChainLength:
+  Enabled: true
+Style/SelectByRegexp:
+  Enabled: true
+Style/SendWithLiteralMethodName:
+  Enabled: true
+Style/SingleLineDoEndBlock:
+  Enabled: true
+Style/SuperArguments:
+  Enabled: true
+Style/SuperWithArgsParentheses:
+  Enabled: true
+
+# Metrics
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/AbcSize:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CollectionLiteralLength:
+  Enabled: true
+
+# Layout
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+Layout/EmptyLineAfterGuardClause:
+  Enabled: true
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'Gemfile'
+Layout/BeginEndAlignment:
+  Enabled: true
+  EnforcedStyleAlignWith: start_of_line
+Layout/CommentIndentation:
+  Enabled: true
+Layout/DotPosition:
+  EnforcedStyle: leading
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+Layout/LineContinuationSpacing:
+  Enabled: true
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+Layout/SpaceBeforeBrackets:
+  Enabled: true
+Layout/LineContinuationLeadingSpace:
+  Enabled: true
+
+# Lint
+Lint/AmbiguousAssignment:
+  Enabled: true
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: true
+Lint/AmbiguousRange:
+  Enabled: true
+Lint/ArrayLiteralInRegexp:
+  Enabled: true
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+Lint/ConstantDefinitionInBlock:
+  Enabled: true
+Lint/ConstantOverwrittenInRescue:
+  Enabled: true
+Lint/ConstantReassignment:
+  Enabled: true
+Lint/CopDirectiveSyntax:
+  Enabled: true
+Lint/DeprecatedConstants:
+  Enabled: true
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: false
+Lint/DuplicateBranch:
+  Enabled: true
+Lint/DuplicateElsifCondition:
+  Enabled: true
+Lint/DuplicateMagicComment:
+  Enabled: true
+Lint/DuplicateMatchPattern:
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement:
+  Enabled: true
+Lint/DuplicateRequire:
+  Enabled: true
+Lint/DuplicateRescueException:
+  Enabled: true
+Lint/DuplicateSetElement:
+  Enabled: true
+Lint/EmptyBlock:
+  Enabled: false
+Lint/EmptyClass:
+  Enabled: true
+  AllowComments: true
+Lint/EmptyConditionalBody:
+  Enabled: true
+Lint/EmptyFile:
+  Enabled: true
+Lint/EmptyInPattern:
+  Enabled: true
+  AllowComments: true
+Lint/FloatComparison:
+  Enabled: true
+Lint/HashNewWithKeywordArgumentsAsDefault:
+  Enabled: true
+Lint/IdentityComparison:
+  Enabled: true
+Lint/IncompatibleIoSelectWithFiberScheduler:
+  Enabled: true
+Lint/ItWithoutArgumentsInBlock:
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock:
+  Enabled: true
+Lint/LiteralAssignmentInCondition:
+  Enabled: true
+Lint/MissingSuper:
+  Enabled: false
+Lint/MixedCaseRange:
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: true
+Lint/NonAtomicFileOperation:
+  Enabled: true
+Lint/NumberedParameterAssignment:
+  Enabled: true
+Lint/NumericOperationWithConstantResult:
+  Enabled: true
+Lint/OrAssignmentToConstant:
+  Enabled: true
+Lint/RaiseException:
+  Enabled: true
+Lint/RedundantDirGlobSort:
+  Enabled: true
+Lint/RedundantRegexpQuantifiers:
+  Enabled: true
+Lint/RedundantSafeNavigation:
+  Enabled: true
+Lint/RedundantTypeConversion:
+  Enabled: true
+Lint/RefinementImportMethods:
+  Enabled: true
+Lint/RequireRangeParentheses:
+  Enabled: true
+Lint/RequireRelativeSelfPath:
+  Enabled: true
+Lint/SelfAssignment:
+  Enabled: true
+Lint/SharedMutableDefault:
+  Enabled: true
+Lint/StructNewOverride:
+  Enabled: true
+Lint/SuppressedExceptionInNumberConversion:
+  Enabled: true
+Lint/SymbolConversion:
+  Enabled: true
+  EnforcedStyle: strict
+Lint/ToEnumArguments:
+  Enabled: true
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+Lint/TripleQuotes:
+  Enabled: true
+Lint/UnescapedBracketInRegexp:
+  Enabled: true
+Lint/UnexpectedBlockArity:
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator:
+  Enabled: true
+Lint/UnreachableLoop:
+  Enabled: true
+Lint/UselessConstantScoping:
+  Enabled: true
+Lint/UselessDefined:
+  Enabled: true
+Lint/UselessMethodDefinition:
+  Enabled: true
+Lint/UselessNumericOperation:
+  Enabled: true
+Lint/UselessRescue:
+  Enabled: true
+Lint/UselessRuby2Keywords:
+  Enabled: true
+
+# Bundler
+Bundler/OrderedGems:
+  Enabled: true
+
+# Gemspec
+Gemspec/AddRuntimeDependency:
+  Enabled: true
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: false
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+Gemspec/RequireMFA:
+  Enabled: false
+
+# Naming
+Naming/BlockForwarding:
+  Enabled: true
+  EnforcedStyle: explicit
+Naming/PredicateName:
+  Enabled: false
+
+# Security
+Security/CompoundHash:
+  Enabled: true
+Security/IoMethods:
+  Enabled: true
+
+Layout/HashAlignment:
+  EnforcedColonStyle: key
+  EnforcedHashRocketStyle: key
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_first_argument 
+
+Layout/BlockAlignment:
+  EnforcedStyleAlignWith: start_of_block  # or 'start_of_line' or 'either'
+
+Layout/ArrayAlignment:
+  EnforcedStyle: with_first_element
+
+Layout/MultilineBlockLayout:
+  Enabled: true
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: keyword

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-12
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 gregoryrivage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Hooksmith
+
+**Hooksmith** is a modular, Rails-friendly gem for processing webhooks. It allows you to register multiple processors for different providers and events, ensuring that only one processor handles a given payload. If multiple processors qualify, an error is raised to avoid ambiguous behavior.
+
+## Features
+
+- **DSL for Registration:** Group processors by provider and event.
+- **Flexible Dispatcher:** Dynamically selects the appropriate processor based on payload conditions.
+- **Rails Integration:** Automatically configures with Rails using a Railtie.
+- **Lightweight Logging:** Built-in logging that can be switched to `Rails.logger` when in a Rails environment.
+- **Tested with Minitest:** 100% branch coverage for robust behavior.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hooksmith', '~> 0.1.0'
+```
+
+Then execute:
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install hooksmith
+```
+
+## Usage
+
+### Configuration
+
+Configure your webhook processors in an initializer (e.g., `config/initializers/hooksmith.rb`):
+
+```ruby
+Hooksmith.configure do |config|
+  config.provider(:stripe) do |stripe|
+    stripe.register(:charge_succeeded, Stripe::Processor::ChargeSucceeded::Tenant)
+    stripe.register(:charge_succeeded, Stripe::Processor::ChargeSucceeded::Landlord)
+  end
+
+  config.provider(:paypal) do |paypal|
+    paypal.register(:payment_received, Paypal::Processor::PaymentReceived)
+  end
+end
+```
+
+## Implementing a Processor
+Create a processor by inheriting from `Hooksmith::Processor::Base`:
+
+```ruby
+module Stripe
+  module Processor
+    module ChargeSucceeded
+      class Tenant < Hooksmith::Processor::Base
+        # Only handle events with a tenant_payment_id.
+        def can_handle?(payload)
+          payload.dig("metadata", "tenant_payment_id").present?
+        end
+
+        def process!
+          tenant_payment_id = payload.dig("metadata", "tenant_payment_id")
+          # Add your business logic here (e.g., update database records).
+          puts "Processed tenant payment: #{tenant_payment_id}"
+        end
+      end
+    end
+  end
+end
+```
+
+## Dispatching a Webhook
+
+Use the dispatcher in your webhook controller:
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def receive
+    provider = params[:provider] || "stripe"
+    event    = params[:event]    || "charge_succeeded"
+    payload  = params[:data]     # Adjust extraction as needed
+
+    Hooksmith::Dispatcher.new(provider: provider, event: event, payload: payload).run!
+    head :ok
+  rescue Hooksmith::MultipleProcessorsError => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  rescue StandardError => e
+    render json: { error: e.message }, status: :internal_server_error
+  end
+end
+```
+
+## Testing
+The gem includes a full test suite using Minitest with 100% branch coverage. See the test/ directory for examples. You can run the tests with:
+
+```
+bundle exec rake test
+```
+
+If you want to check test coverage, you can integrate SimpleCov by adding the following at the top of your test/test_helper.rb:
+
+```ruby
+require "simplecov"
+SimpleCov.start
+```
+
+Then run the tests to generate a coverage report.
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/gregorypreve/hooksmith.
+
+
+## License
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/hooksmith/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Provides a DSL for registering webhook processors by provider and event.
+#
+module Hooksmith
+  # Configuration holds the registry of all processors.
+  class Configuration
+    # @return [Hash] a registry mapping provider symbols to arrays of processor entries.
+    attr_reader :registry
+
+    def initialize
+      # Registry structure: { provider_symbol => [{ event: event_symbol, processor: ProcessorClass }, ...] }
+      @registry = Hash.new { |hash, key| hash[key] = [] }
+    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
+    def provider(provider_name)
+      provider_config = ProviderConfig.new(provider_name)
+      yield(provider_config)
+      registry[provider_name.to_sym].concat(provider_config.entries)
+    end
+
+    # Direct registration of a processor.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param event [Symbol, String] the event name
+    # @param processor_class [Class] the processor class
+    def register_processor(provider, event, processor_class)
+      registry[provider.to_sym] << { event: event.to_sym, processor: processor_class }
+    end
+
+    # Returns all processor entries for a given provider and event.
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param event [Symbol, String] the event name
+    # @return [Array<Hash>] the array of matching entries.
+    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.
+    #
+    # @param event [Symbol, String] the event name.
+    # @param processor_class [Class] the processor class.
+    def register(event, processor_class)
+      entries << { event: event.to_sym, processor: processor_class }
+    end
+  end
+end

data/lib/hooksmith/dispatcher.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  # Dispatcher routes incoming webhook payloads to the appropriate processor.
+  #
+  # @example Dispatch a webhook event:
+  #   Hooksmith::Dispatcher.new(provider: :stripe, event: :charge_succeeded, payload: payload).run!
+  #
+  class Dispatcher
+    # Initializes a new Dispatcher.
+    #
+    # @param provider [Symbol, String] the provider (e.g., :stripe)
+    # @param event [Symbol, String] the event (e.g., :charge_succeeded)
+    # @param payload [Hash] the webhook payload data.
+    def initialize(provider:, event:, payload:)
+      @provider = provider.to_sym
+      @event    = event.to_sym
+      @payload  = payload
+    end
+
+    # Runs the dispatcher.
+    #
+    # Instantiates each processor registered for the given provider and event,
+    # then selects the ones that can handle the payload using the can_handle? method.
+    # - If no processors qualify, logs a warning.
+    # - If more than one qualifies, raises MultipleProcessorsError.
+    # - Otherwise, processes the event with the single matching processor.
+    #
+    # @raise [MultipleProcessorsError] if multiple processors qualify.
+    def run!
+      # Fetch all processors registered for this provider and event.
+      entries = Hooksmith.configuration.processors_for(@provider, @event)
+
+      # Instantiate each processor and filter by condition.
+      matching_processors = entries.map do |entry|
+        processor = entry[:processor].new(@payload)
+        processor if processor.can_handle?(@payload)
+      end.compact
+
+      if matching_processors.empty?
+        Hooksmith.logger.warn("No processor registered for #{@provider} event #{@event} could handle the payload")
+        return
+      end
+
+      # If more than one processor qualifies, raise an error.
+      raise MultipleProcessorsError.new(@provider, @event, @payload) if matching_processors.size > 1
+
+      # Exactly one matching processor.
+      matching_processors.first.process!
+    rescue StandardError => e
+      Hooksmith.logger.error("Error processing #{@provider} event #{@event}: #{e.message}")
+      raise e
+    end
+  end
+
+  # Raised when multiple processors can handle the same event.
+  class MultipleProcessorsError < StandardError
+    # Initializes the error with details about the provider, event, and payload.
+    #
+    # @param provider [Symbol] the provider name.
+    # @param event [Symbol] the event name.
+    # @param payload [Hash] the webhook payload.
+    def initialize(provider, event, payload)
+      super("Multiple processors found for #{provider} event #{event}. Payload: #{payload}")
+    end
+  end
+end

data/lib/hooksmith/logger.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'singleton'
+
+module Hooksmith
+  # A lightweight logger for Hooksmith.
+  #
+  # Uses Ruby's standard Logger under the hood and can be configured to use Rails.logger.
+  class Logger
+    include Singleton
+
+    # Initializes the logger.
+    def initialize
+      @logger = ::Logger.new($stdout)
+      @logger.level = ::Logger::INFO
+    end
+
+    # Logs an info message.
+    #
+    # @param msg [String] the message.
+    def info(msg)
+      @logger.info(msg)
+    end
+
+    # Logs a warning message.
+    #
+    # @param msg [String] the message.
+    def warn(msg)
+      @logger.warn(msg)
+    end
+
+    # Logs an error message.
+    #
+    # @param msg [String] the message.
+    def error(msg)
+      @logger.error(msg)
+    end
+
+    # Logs a debug message.
+    #
+    # @param msg [String] the message.
+    def debug(msg)
+      @logger.debug(msg)
+    end
+  end
+end

data/lib/hooksmith/processor/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hooksmith
+  module Processor
+    # Base class for all webhook processors.
+    #
+    # Processors should inherit from this class and implement the process! method.
+    #
+    # @abstract
+    class Base
+      # @return [Hash] the payload for the webhook.
+      attr_reader :payload
+
+      # Initializes the processor with a payload.
+      #
+      # @param payload [Hash] the webhook payload.
+      def initialize(payload)
+        @payload = payload
+      end
+
+      # Checks if the processor can handle the payload.
+      # Override this method in subclasses if conditional processing is needed.
+      #
+      # @param payload [Hash] the webhook payload.
+      # @return [Boolean] true if the processor can handle the payload.
+      def can_handle?(_payload)
+        true
+      end
+
+      # Process the webhook.
+      # Must be implemented by subclasses.
+      #
+      # @raise [NotImplementedError] if not implemented.
+      def process!
+        raise NotImplementedError, 'Implement process! in your processor'
+      end
+    end
+  end
+end

data/lib/hooksmith/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+if defined?(Rails)
+  module Hooksmith
+    # Railtie integration for Hooksmith.
+    #
+    # This file allows Hooksmith to integrate seamlessly with a Rails application.
+    class Railtie < Rails::Railtie
+      initializer 'hooksmith.configure_rails_initialization' do |_|
+        Hooksmith.logger.info('Hooksmith initialized in Rails')
+        # Optionally set the gem logger to use Rails.logger if available.
+        if defined?(Rails.logger) && Rails.logger
+          Hooksmith::Logger.instance.instance_variable_set(:@logger, Rails.logger)
+        end
+      end
+    end
+  end
+end

data/lib/hooksmith/version.rb

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

data/lib/hooksmith.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'hooksmith/version'
+require 'hooksmith/configuration'
+require 'hooksmith/dispatcher'
+require 'hooksmith/logger'
+require 'hooksmith/processor/base'
+require 'hooksmith/railtie' if defined?(Rails)
+
+# Main entry point for the Hooksmith gem.
+#
+# @example Basic usage:
+#   Hooksmith.configure do |config|
+#     config.provider(:stripe) do |stripe|
+#       stripe.register(:charge_succeeded, MyStripeProcessor)
+#     end
+#   end
+#
+#   Hooksmith::Dispatcher.new(provider: :stripe, event: :charge_succeeded, payload: payload).run!
+#
+module Hooksmith
+  # Returns the configuration instance.
+  # @return [Configuration] the configuration instance.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Yields the configuration to a block.
+  # @yieldparam config [Configuration]
+  def self.configure
+    yield(configuration)
+  end
+
+  # Returns the gem's logger instance.
+  # @return [Logger] the logger instance.
+  def self.logger
+    Logger.instance
+  end
+end

data/sig/hooksmith.rbs

@@ -0,0 +1,4 @@
+module Hooksmith
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: hooksmith
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- gregoryrivage
+bindir: exe
+cert_chain: []
+date: 2025-03-12 00:00:00.000000000 Z
+dependencies: []
+description: Hooksmith is a gem that allows you to handle webhooks in your Rails application.
+email:
+- gregory@rivage.immo
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/hooksmith.rb
+- lib/hooksmith/configuration.rb
+- lib/hooksmith/dispatcher.rb
+- lib/hooksmith/logger.rb
+- lib/hooksmith/processor/base.rb
+- lib/hooksmith/railtie.rb
+- lib/hooksmith/version.rb
+- sig/hooksmith.rbs
+homepage: https://github.com/gregoryrivage/hooksmith
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/gregoryrivage/hooksmith
+  source_code_uri: https://github.com/gregoryrivage/hooksmith
+  changelog_uri: https://github.com/gregoryrivage/hooksmith/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Hooksmith is a gem that allows you to handle webhooks in your Rails application.
+test_files: []