event_trigger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2c3d6d3c6ba705815ec39d822e4a83d8d832a395b63eb85fd9b149e9cdc4a5e
+  data.tar.gz: 0e5339bc3d82788cdd942d0b7c69f979855379ac5f9c5b7ccde950617b46a9b8
+SHA512:
+  metadata.gz: 399d0f668e2781a691c53bb6bc172ffbfc984656c50dc72e3eeda8831869209f1ac388c42faf6f5c3542bfa6aab9672c02d9c1a5730d7d85a0df4cdbe57f2930
+  data.tar.gz: 24811741cb39d9d792b138445754da696bdb4b514a4f194c4fbbbaed0b2b5854ab9c8a3285bc5ea40415a92182d3f1bf8269ef47d0c0d6d3e319cd65b7803ea6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kamlesh Parmar
+
+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,142 @@
+# EventTrigger
+
+Configurable event-based notification system for Ruby and Rails.
+
+Configure notification providers **once**, then simply call:
+
+```ruby
+EventTrigger.trigger("loan.activated", data: { loan_id: 123, customer_name: "Kamlesh" })
+```
+
+The gem determines automatically which **enabled** providers are
+configured for that event and executes only those providers.
+Anything can be sent in `data:` -- passed through to providers/handlers.
+
+## Features
+
+- Providers: **Slack**, **Email**, **Webhook**, plus custom providers
+- Central `EventTrigger.configure` block (plain Ruby and Rails)
+- Per-provider `enabled` flag + global `config.enabled` kill-switch
+- Per-provider `events` allow-list (`nil`/empty = all events)
+- Simple API: `trigger(name, data:)` + `on(name) { |event| }`
+- Adapter architecture: every provider implements `#deliver(event)`
+- Failure isolation: one provider failing never blocks others
+- Optional logging: triggered / executed / skipped / failed
+- No app-specific business logic -- just events + providers
+
+## Installation
+
+```ruby
+gem "event_trigger"
+```
+
+```sh
+bundle install
+```
+
+Requires Ruby >= 2.6. No runtime dependencies (stdlib only).
+
+## Configuration
+
+```ruby
+EventTrigger.configure do |config|
+  config.enabled = true
+  config.logger = Logger.new($stdout) # optional; nil = silent
+
+  config.slack.enabled = true
+  config.slack.webhook_url = ENV["SLACK_WEBHOOK_URL"]
+  config.slack.events = ["loan.activated", "loan.overdue", "payment.received"]
+
+  config.email.enabled = false
+  config.email.from = ENV["EVENT_TRIGGER_EMAIL_FROM"]
+  config.email.to = "ops@example.com"
+  config.email.events = ["loan.activated", "loan.foreclosed"]
+
+  config.webhook.enabled = true
+  config.webhook.url = ENV["EVENT_TRIGGER_WEBHOOK_URL"]
+  config.webhook.events = ["loan.activated"]
+end
+```
+
+Shortcuts `config.slack_webhook_url=` and `config.email_from=` delegate
+to the per-provider configs.
+
+`events` is an allow-list per provider. `nil` (default) or `[]` means
+**ALL events** — the provider runs for every trigger (as long as it is
+enabled):
+
+```ruby
+config.slack.events = nil  # or [] → all events
+```
+
+### Rails initializer
+
+Copy `examples/initializer.rb` to `config/initializers/event_trigger.rb`.
+A Railtie is shipped so the gem loads cleanly inside Rails.
+
+## Triggering events
+
+```ruby
+EventTrigger.trigger("loan.activated", data: { loan_id: 123, customer_name: "Kamlesh" })
+```
+
+Rules: `loan.activated` with Slack+Email enabled and subscribed runs both;
+`loan.overdue` with only Slack subscribed runs Slack only; with
+`config.enabled = false` nothing runs.
+
+## Handlers
+
+```ruby
+EventTrigger.on("loan.activated") do |event|
+  puts "Loan #{event.payload[:loan_id]} activated"
+end
+```
+
+`event` exposes `#name`, `#payload`, `#timestamp`. Use `off(name)` to
+remove handlers. Handler errors are logged, never raised.
+
+## Providers
+
+Slack posts `{ text: }` to `hooks.slack.com` URLs (error payloads render as
+error plus backtrace lines) and a rich embed (`username: RailsErrorNotifier`,
+Backtrace/Context fields) to other webhook URLs. Email sends via Net::SMTP
+in plain Ruby (or ActionMailer when configured with `mailer`). Webhook POSTs
+`{ event:, payload:, timestamp: }` as JSON.
+
+Custom provider:
+
+```ruby
+class SmsProvider < EventTrigger::Provider
+  def deliver(event)
+    # use config + global_config
+  end
+end
+EventTrigger.register_provider(:sms, SmsProvider)
+EventTrigger.configure { |c| c.for(:sms).enabled = true }
+```
+
+Architecture: EventTrigger -> Event -> Enabled Providers (Slack/Email/Webhook).
+
+## Logging
+
+Set `config.logger`. Logs: event triggered, provider executed, provider
+skipped (disabled / not subscribed), provider failed, handler failed.
+
+## Public API
+
+`configure`, `configuration`, `reset!`, `trigger(name, data:)`, `on`, `off`,
+`register_provider`, `Provider#deliver`, `Registry`, `Dispatcher`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+See `examples/plain_ruby.rb` for a runnable demo.
+
+## License
+
+MIT -- see LICENSE.txt.
+

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+

data/lib/event_trigger/configuration.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module EventTrigger
+  # Per-provider configuration. Every provider (built-in or custom) gets
+  # an instance of this class with its own +enabled+, +events+ and
+  # provider-specific settings stored in +options+.
+  class ProviderConfig
+    attr_accessor :enabled
+    attr_writer :events
+
+    def initialize(enabled: false, events: nil)
+      @enabled = enabled
+      @events = events # nil => subscribed to ALL events
+      @options = {}
+    end
+
+    # List of event names this provider cares about, or nil for "all events".
+    # Always returns strings (or nil).
+    def events
+      return nil if @events.nil?
+
+      Array(@events).map(&:to_s)
+    end
+
+    # True when this provider should run for +event_name+.
+    # nil/empty events list means "all events".
+    def subscribed_to?(event_name)
+      list = events
+      return true if list.nil? || list.empty?
+
+      list.include?(event_name.to_s)
+    end
+
+    # Generic option bag for provider-specific settings
+    # (webhook_url, from, url, ...). Allows:
+    #   config.slack.webhook_url = "..."
+    def method_missing(name, *args)
+      name_str = name.to_s
+      if name_str.end_with?("=")
+        @options[name_str.chomp("=").to_sym] = args.first
+      elsif @options.key?(name)
+        @options[name]
+      elsif args.empty?
+        nil
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      true
+    end
+
+    def options
+      @options.dup
+    end
+
+    def to_h
+      { enabled: enabled, events: events }.merge(@options)
+    end
+  end
+
+  # Global configuration object yielded by EventTrigger.configure.
+  class Configuration
+    attr_accessor :enabled, :logger
+    attr_reader :slack, :email, :webhook
+
+    # Backwards-compatible top-level shortcuts required by the spec:
+    #   config.slack_webhook_url = ENV["SLACK_WEBHOOK_URL"]
+    #   config.email_from = ENV["EVENT_TRIGGER_EMAIL_FROM"]
+    # They delegate to the per-provider configs.
+    def initialize
+      @enabled = true
+      @logger = nil
+      @slack = ProviderConfig.new
+      @email = ProviderConfig.new
+      @webhook = ProviderConfig.new
+      @custom = {}
+    end
+
+    def slack_webhook_url
+      slack.webhook_url
+    end
+
+    def slack_webhook_url=(value)
+      slack.webhook_url = value
+    end
+
+    def email_from
+      email.from
+    end
+
+    def email_from=(value)
+      email.from = value
+    end
+
+    # Access (or lazily create) the config for any provider name,
+    # including future/custom providers:
+    #   config.for(:sms).enabled = true
+    def for(name)
+      key = name.to_sym
+      case key
+      when :slack then slack
+      when :email then email
+      when :webhook then webhook
+      else
+        @custom[key] ||= ProviderConfig.new
+      end
+    end
+    alias provider for
+
+    # All provider configs keyed by name, including custom ones.
+    def providers
+      { slack: slack, email: email, webhook: webhook }.merge(@custom)
+    end
+
+    def enabled?
+      !!@enabled
+    end
+  end
+end

data/lib/event_trigger/defaults.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Default configuration applied when the gem is bundled into an app.
+  #
+  # Runs via the Railtie BEFORE the host app's initializers, so a
+  # user-provided config/initializers/event_trigger.rb can override
+  # anything set here. It also means the gem works out-of-the-box with
+  # zero configuration: this exact block is the default.
+  #
+  #   EventTrigger.configure do |config|
+  #     config.enabled = true
+  #     config.slack.enabled = true
+  #     config.slack.webhook_url = ENV["SLACK_WEBHOOK_URL"]
+  #     config.slack.events = ["loan.activated", "loan.overdue", "payment.received"]
+  #     config.email.enabled = false
+  #     config.email.from = ENV["EVENT_TRIGGER_EMAIL_FROM"]
+  #     ...
+  #   end
+  def self.apply_defaults!(logger: nil)
+    configure do |config|
+      config.enabled = true
+      config.logger ||= logger
+
+      config.slack.enabled = true
+      config.slack.webhook_url ||= ENV["SLACK_WEBHOOK_URL"]
+      config.slack.events = ["loan.activated", "loan.overdue", "payment.received"]
+
+      config.email.enabled = false
+      config.email.from ||= ENV["EVENT_TRIGGER_EMAIL_FROM"]
+      config.email.to ||= ENV["EVENT_TRIGGER_EMAIL_TO"] || "ops@example.com"
+      config.email.events = ["loan.activated", "loan.foreclosed"]
+
+      config.webhook.enabled = false
+      config.webhook.url ||= ENV["EVENT_TRIGGER_WEBHOOK_URL"]
+      # Leave webhook subscribed to nothing until the app opts in.
+      config.webhook.events ||= []
+    end
+  end
+end

data/lib/event_trigger/dispatcher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Fans an Event out to every enabled provider subscribed to that event,
+  # then runs any user-registered handlers (EventTrigger.on).
+  #
+  # Guarantees:
+  # - Global disable (config.enabled == false) => nothing runs.
+  # - Only enabled providers subscribed to the event run.
+  # - Unknown provider names are skipped (with a log line) instead of crashing.
+  # - One provider raising never prevents the others from running;
+  #   failures are logged and swallowed so all providers always run.
+  # - Handler blocks are likewise isolated: a failing handler is logged
+  #   and the rest still run.
+  class Dispatcher
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Returns the list of provider instances that were executed.
+    def dispatch(event, handlers = [])
+      log("event triggered: #{event.name} payload=#{event.payload.inspect}")
+      return [] unless @configuration.enabled?
+
+      executed = []
+      providers_for(event.name).each do |name, provider_config|
+        klass = Registry.fetch(name)
+        if klass.nil?
+          log("provider ':#{name}' has no registered class; skipping")
+          next
+        end
+        unless provider_config.enabled
+          log("provider ':#{name}' skipped (disabled)")
+          next
+        end
+        unless provider_config.subscribed_to?(event.name)
+          log("provider ':#{name}' skipped (not subscribed to '#{event.name}')")
+          next
+        end
+        begin
+          klass.new(config: provider_config, global_config: @configuration).deliver(event)
+          log("provider ':#{name}' executed for '#{event.name}'")
+          executed << name
+        rescue StandardError => e
+          log("provider ':#{name}' failed for '#{event.name}': #{e.class}: #{e.message}")
+        end
+      end
+
+      Array(handlers).each do |handler|
+        begin
+          handler.call(event)
+        rescue StandardError => e
+          log("handler for '#{event.name}' failed: #{e.class}: #{e.message}")
+        end
+      end
+
+      executed
+    end
+
+    private
+
+    def providers_for(_event_name)
+      @configuration.providers
+    end
+
+    def log(message)
+      @configuration.logger&.info("[EventTrigger] #{message}")
+    end
+  end
+end

data/lib/event_trigger/event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Value object representing a single triggered event.
+  # Carries the event +name+ ("loan.activated"), an arbitrary +payload+ hash
+  # (anything the caller passes via data:), and a timestamp.
+  class Event
+    attr_reader :name, :payload, :timestamp
+
+    def initialize(name:, payload: {})
+      @name = name.to_s
+      @payload = symbolize(payload || {})
+      @timestamp = Time.now
+    end
+
+    def [](key)
+      payload[key.to_sym] || payload[key.to_s]
+    end
+
+    def to_h
+      { name: name, payload: payload, timestamp: timestamp }
+    end
+
+    private
+
+    def symbolize(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(k, v), memo|
+        memo[k.to_sym] = v
+      end
+    end
+  end
+end

data/lib/event_trigger/provider.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Common interface every notification provider must implement.
+  #
+  # To add a new provider, subclass this and implement #deliver(event):
+  #
+  #   class SmsProvider < EventTrigger::Provider
+  #     def deliver(event)
+  #       # send SMS using config ...
+  #     end
+  #   end
+  #   EventTrigger.register_provider(:sms, SmsProvider)
+  #
+  # Helpers available to subclasses:
+  #   - #config        -> ProviderConfig for this provider
+  #   - #global_config -> full EventTrigger::Configuration
+  #   - #log(message)  -> write to configured logger, if any
+  class Provider
+    attr_reader :config, :global_config
+
+    def initialize(config:, global_config:)
+      @config = config
+      @global_config = global_config
+    end
+
+    # Deliver the notification for +event+. Must be implemented by subclasses.
+    def deliver(_event)
+      raise NotImplementedError, "#{self.class} must implement #deliver(event)"
+    end
+
+    # Symbolic name derived from class name, e.g. SlackProvider -> :slack.
+    # Custom providers can override .provider_name.
+    def self.provider_name
+      name.to_s.split("::").last.to_s.sub(/Provider\z/, "").downcase.to_sym
+    end
+
+    def provider_name
+      self.class.provider_name
+    end
+
+    protected
+
+    def log(message)
+      logger = global_config.logger
+      logger&.info("[EventTrigger][#{provider_name}] #{message}")
+    end
+  end
+end

data/lib/event_trigger/providers/email_provider.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "../provider"
+
+module EventTrigger
+  module Providers
+    # Sends event notifications via email.
+    #
+    # Works in two modes:
+    # 1. Rails mode -- if ActionMailer is loaded and
+    #    config.email.mailer is set (a mailer class) or
+    #    config.email.delivery_method == :action_mailer, the event is
+    #    delivered through ActionMailer.
+    # 2. Plain-Ruby mode -- otherwise delivered via stdlib Net::SMTP using
+    #    config.email.smtp_settings (+ from/to addresses).
+    #
+    # Config:
+    #   config.email.enabled = true
+    #   config.email.from = "no-reply@example.com"
+    #   config.email.to = "ops@example.com"            # default recipient
+    #   config.email.subject_prefix = "[EventTrigger]" # optional
+    #   config.email.events = ["loan.activated"]
+    #
+    # Per-trigger overrides: EventTrigger.trigger("x", data: { email_to:, email_subject:, ... })
+    class EmailProvider < Provider
+      def self.provider_name
+        :email
+      end
+
+      def deliver(event)
+        from = config.from || global_config.email_from
+        to = event.payload[:email_to] || event.payload["email_to"] || config.to
+        raise Error, "Email `from` is not configured" if from.nil? || from.to_s.strip.empty?
+        raise Error, "Email `to` is not configured" if to.nil? || to.to_s.strip.empty?
+
+        subject = event.payload[:email_subject] || event.payload["email_subject"] ||
+                  build_subject(event)
+        body = build_body(event)
+
+        if action_mailer_delivery?
+          deliver_via_action_mailer(from, to, subject, body, event)
+        else
+          deliver_via_smtp(from, to, subject, body)
+        end
+        log("delivered event '#{event.name}' to #{Array(to).join(', ')}")
+        true
+      end
+
+      private
+
+      def action_mailer_delivery?
+        defined?(ActionMailer::Base) && (config.mailer || config.delivery_method == :action_mailer)
+      end
+
+      def deliver_via_action_mailer(from, to, subject, body, _event)
+        mailer = config.mailer
+        if mailer
+          mailer.event_notification(from, to, subject, body).deliver_now
+        else
+          Class.new(ActionMailer::Base) do
+            def event_notification(from, to, subject, body)
+              mail(from: from, to: to, subject: subject, body: body)
+            end
+          end.event_notification(from, to, subject, body).deliver_now
+        end
+      end
+
+      def deliver_via_smtp(from, to, subject, body)
+        require "net/smtp"
+        settings = smtp_settings
+        message = <<~MSG
+          From: #{from}
+          To: #{Array(to).join(", ")}
+          Subject: #{subject}
+          MIME-Version: 1.0
+          Content-Type: text/plain; charset=UTF-8
+
+          #{body}
+        MSG
+        Net::SMTP.start(
+          settings[:address] || "localhost",
+          settings[:port] || 25,
+          settings[:domain] || "localhost",
+          settings[:user_name],
+          settings[:password],
+          settings[:authentication] || :plain
+        ) do |smtp|
+          smtp.send_message(message, from, Array(to))
+        end
+      end
+
+      def smtp_settings
+        config.smtp_settings || {}
+      end
+
+      def build_subject(event)
+        prefix = config.subject_prefix || "[EventTrigger]"
+        custom = event.payload[:subject] || event.payload["subject"]
+        return custom.to_s if custom
+
+        "#{prefix} #{event.name}"
+      end
+
+      def build_body(event)
+        lines = ["Event: #{event.name}", "Time: #{event.timestamp}", ""]
+        event.payload.each do |k, v|
+          next if [:email_to, :email_subject, "email_to", "email_subject"].include?(k)
+
+          lines << "#{k}: #{v}"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/event_trigger/providers/slack_provider.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+require_relative "../provider"
+
+module EventTrigger
+  module Providers
+    # Sends event notifications to Slack (or any Slack-compatible /
+    # Discord-compatible incoming-webhook URL).
+    #
+    # Config:
+    #   config.slack.enabled = true
+    #   config.slack.webhook_url = ENV["SLACK_WEBHOOK_URL"]
+    #   config.slack.events = ["loan.activated"]
+    #
+    # Payload behaviour:
+    # - Slack incoming webhooks (hooks.slack.com) receive { text: ... }.
+    # - All other URLs (e.g. Discord-style webhooks) receive a rich embed
+    #   payload with error/backtrace/context fields, truncated to stay
+    #   within message limits.
+    class SlackProvider < Provider
+      MAX_TEXT = 1500
+
+      def self.provider_name
+        :slack
+      end
+
+      def deliver(event)
+        url = config.webhook_url || config.url
+        raise Error, "Slack webhook_url is not configured" if url.nil? || url.to_s.strip.empty?
+
+        body = build_payload(url.to_s, event)
+        post_json(url.to_s, body)
+        log("delivered event '#{event.name}'")
+        true
+      end
+
+      private
+
+      def build_payload(url, event)
+        payload = event.payload
+        if url.include?("hooks.slack.com")
+          { text: slack_text(event, payload) }
+        else
+          {
+            username: "RailsErrorNotifier",
+            embeds: [
+              {
+                title: "🚨 Error Occurred",
+                description: embed_description(event, payload),
+                color: 0xFF0000,
+                fields: [
+                  { name: "Event", value: "```\n#{truncate(event.name)}\n```", inline: false },
+                  { name: "Backtrace", value: "```\n#{backtrace_text(payload)}\n```", inline: false },
+                  { name: "Context", value: "```\n#{context_text(payload)}\n```", inline: false }
+                ],
+                timestamp: Time.now.utc.iso8601
+              }
+            ]
+          }
+        end
+      end
+
+      # Slack text format: human summary; falls back to error/backtrace keys
+      # when present, otherwise dumps the generic payload.
+      def slack_text(event, payload)
+        if payload[:error] || payload["error"]
+          err = payload[:error] || payload["error"]
+          bt = payload[:backtrace] || payload["backtrace"]
+          lines = [err.to_s]
+          lines += Array(bt) if bt
+          lines.join("\n")
+        else
+          summary = payload.map { |k, v| "#{k}: #{v}" }.join(", ")
+          summary = event.payload.inspect if summary.empty?
+          "[#{event.name}] #{summary}"
+        end
+      end
+
+      def embed_description(event, payload)
+        err = payload[:error] || payload["error"] || event.name
+        truncate(err.to_s)
+      end
+
+      def backtrace_text(payload)
+        bt = payload[:backtrace] || payload["backtrace"] || ["No backtrace"]
+        truncate_for_discord(Array(bt).first(10).join("\n"))
+      end
+
+      def context_text(payload)
+        ctx = payload[:context] || payload["context"] || payload
+        truncate_for_discord(ctx.inspect)
+      end
+
+      def truncate(str, limit = MAX_TEXT)
+        s = str.to_s
+        s.length > limit ? "#{s[0, limit]}…" : s
+      end
+
+      def truncate_for_discord(str, limit = 1000)
+        truncate(str, limit)
+      end
+
+      def post_json(url, body)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        request = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json")
+        request.body = JSON.generate(body)
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Error, "Slack delivery failed (HTTP #{response.code}): #{response.body}"
+        end
+        response
+      end
+    end
+  end
+end

data/lib/event_trigger/providers/webhook_provider.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "../provider"
+
+module EventTrigger
+  module Providers
+    # POSTs the event as JSON to a configured HTTP endpoint.
+    #
+    # Config:
+    #   config.webhook.enabled = true
+    #   config.webhook.url = "https://example.com/hooks/events"
+    #   config.webhook.headers = { "Authorization" => "Bearer ..." }
+    #   config.webhook.events = ["loan.activated"]
+    class WebhookProvider < Provider
+      def self.provider_name
+        :webhook
+      end
+
+      def deliver(event)
+        url = config.url
+        raise Error, "Webhook url is not configured" if url.nil? || url.to_s.strip.empty?
+
+        post_json(url.to_s, event_to_json(event), headers)
+        log("delivered event '#{event.name}' to #{url}")
+        true
+      end
+
+      private
+
+      def headers
+        { "Content-Type" => "application/json" }.merge(config.headers || {})
+      end
+
+      def event_to_json(event)
+        {
+          event: event.name,
+          payload: stringify(event.payload),
+          timestamp: event.timestamp.to_s
+        }
+      end
+
+      def stringify(hash)
+        hash.each_with_object({}) { |(k, v), m| m[k.to_s] = v }
+      end
+
+      def post_json(url, body, headers)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
+        request.body = JSON.generate(body)
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Error, "Webhook delivery failed (HTTP #{response.code}): #{response.body}"
+        end
+        response
+      end
+    end
+  end
+end

data/lib/event_trigger/railtie.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Rails integration:
+  # 1. Applies safe defaults as soon as the gem is bundled (so the app
+  #    works with zero configuration).
+  # 2. Auto-creates config/initializers/event_trigger.rb in the host app
+  #    when missing, so the user always has an editable copy of the
+  #    default block (no manual `rails generate` step needed). Never
+  #    overwrites an existing file.
+  # 3. Hooks Rails.logger in automatically (unless the app already set one).
+  #
+  # Order: Railtie initializer runs BEFORE the host app's initializers, so
+  # anything in config/initializers/event_trigger.rb wins over these defaults.
+  if defined?(Rails::Railtie)
+    class Railtie < Rails::Railtie
+      generators do
+        require "generators/event_trigger/install_generator" if defined?(Rails::Generators)
+      rescue LoadError
+        nil
+      end
+
+      initializer "event_trigger.configure_rails_defaults", before: :load_environment_config do
+        require "event_trigger" unless defined?(EventTrigger::Dispatcher)
+        EventTrigger.apply_defaults!
+        if defined?(Rails.logger) && Rails.logger && EventTrigger.configuration.logger.nil?
+          EventTrigger.configuration.logger = Rails.logger
+        end
+      end
+
+      # Runs after app initializers are loaded: if the app has no
+      # initializer of its own, write the default one so it exists on
+      # disk for the user to edit. Runs in every env except test (to
+      # keep the test suite hermetic).
+      initializer "event_trigger.ensure_initializer_present", after: :load_environment do
+        next unless defined?(Rails.root) && Rails.root
+        next if Rails.env.test? rescue nil
+
+        begin
+          dest = Rails.root.join("config/initializers/event_trigger.rb")
+          next if File.exist?(dest)
+
+          src_candidates = [
+            File.expand_path("../../generators/event_trigger/templates/event_trigger.rb", __dir__),
+            File.expand_path("../../../generators/event_trigger/templates/event_trigger.rb", __FILE__)
+          ]
+          src = src_candidates.find { |p| File.exist?(p) }
+          next unless src
+
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(src, dest)
+          Rails.logger&.info("[EventTrigger] created #{dest} with defaults (edit to customize)")
+        rescue StandardError
+          nil # never break boot because of the initializer copy
+        end
+      end
+    end
+  end
+end

data/lib/event_trigger/registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module EventTrigger
+  # Maps symbolic provider names (:slack, :email, :webhook, custom...)
+  # to provider classes. Custom providers register via
+  # EventTrigger.register_provider(:name, Klass).
+  module Registry
+    @providers = {}
+
+    class << self
+      def register(name, klass)
+        @providers[name.to_sym] = klass
+      end
+
+      def fetch(name)
+        @providers[name.to_sym]
+      end
+
+      def all
+        @providers.dup
+      end
+
+      def registered?(name)
+        @providers.key?(name.to_sym)
+      end
+
+      # Restore the three built-in providers (used by reset!).
+      def reset!
+        @providers = {}
+        require_relative "providers/slack_provider"
+        require_relative "providers/email_provider"
+        require_relative "providers/webhook_provider"
+        register(:slack, Providers::SlackProvider)
+        register(:email, Providers::EmailProvider)
+        register(:webhook, Providers::WebhookProvider)
+      end
+    end
+  end
+
+  Registry.reset!
+end

data/lib/event_trigger/version.rb

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

data/lib/event_trigger.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "event_trigger/version"
+require_relative "event_trigger/configuration"
+require_relative "event_trigger/event"
+require_relative "event_trigger/registry"
+require_relative "event_trigger/provider"
+require_relative "event_trigger/providers/slack_provider"
+require_relative "event_trigger/providers/email_provider"
+require_relative "event_trigger/providers/webhook_provider"
+require_relative "event_trigger/dispatcher"
+require_relative "event_trigger/defaults"
+require_relative "event_trigger/railtie" if defined?(Rails::Railtie)
+
+module EventTrigger
+  class Error < StandardError; end
+
+  class << self
+    # Central configuration block:
+    #
+    #   EventTrigger.configure do |config|
+    #     config.enabled = true
+    #     config.slack.enabled = true
+    #     config.slack.webhook_url = ENV["SLACK_WEBHOOK_URL"]
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Access (and memoize) the global configuration object.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset configuration + handlers + provider registry to defaults.
+    # Primarily useful for tests.
+    def reset!
+      @configuration = Configuration.new
+      @handlers = Hash.new { |h, k| h[k] = [] }
+      Registry.reset!
+    end
+
+    # Register a handler block for a specific event name:
+    #
+    #   EventTrigger.on("loan.activated") do |event|
+    #     # custom notification logic
+    #   end
+    #
+    # Returns the registered block.
+    def on(event_name, &block)
+      raise ArgumentError, "EventTrigger.on requires a block" unless block_given?
+
+      key = normalize_event_name(event_name)
+      handlers[key] << block
+      block
+    end
+
+    # Remove all handlers for an event (or all events when no name given).
+    def off(event_name = nil)
+      if event_name.nil?
+        @handlers = Hash.new { |h, k| h[k] = [] }
+      else
+        handlers.delete(normalize_event_name(event_name))
+      end
+    end
+
+    # Registered handlers hash: { "event.name" => [proc, ...] }
+    def handlers
+      @handlers ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Register a custom provider class under a symbolic name:
+    #
+    #   class SmsProvider < EventTrigger::Provider; end
+    #   EventTrigger.register_provider(:sms, SmsProvider)
+    def register_provider(name, klass)
+      Registry.register(name, klass)
+    end
+
+    # The main public API:
+    #
+    #   EventTrigger.trigger("loan.activated", data: { loan_id: 123 })
+    #
+    # Builds an EventTrigger::Event and hands it to the Dispatcher,
+    # which fans out to every enabled provider configured for that event.
+    # Returns the Event object.
+    def trigger(event_name, data: {})
+      event = Event.new(name: normalize_event_name(event_name), payload: data || {})
+      Dispatcher.new(configuration).dispatch(event, handlers_for(event.name))
+      event
+    end
+
+    # Handlers registered for a given event name (string).
+    def handlers_for(event_name)
+      handlers[normalize_event_name(event_name)].dup
+    end
+
+    # Normalize event names to strings ("loan.activated").
+    def normalize_event_name(name)
+      name.to_s
+    end
+  end
+end

data/lib/generators/event_trigger/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module EventTrigger
+  module Generators
+    # Copies the default initializer into the host Rails app:
+    #
+    #   rails generate event_trigger:install
+    #
+    # Pass --force to overwrite an existing initializer. The Railtie also
+    # auto-creates this file when missing, so in practice you rarely need
+    # to run the generator by hand.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copy EventTrigger initializer to config/initializers/event_trigger.rb"
+
+      def copy_initializer
+        copy_file "event_trigger.rb",
+                  "config/initializers/event_trigger.rb"
+      end
+    end
+  end
+end

data/lib/generators/event_trigger/templates/event_trigger.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Default EventTrigger configuration for your Rails app.
+# Auto-created by the gem on first boot (and by `rails generate event_trigger:install`).
+# Adjust values for your environment.
+
+EventTrigger.configure do |config|
+  config.enabled = true
+  # Optional logging (defaults to Rails.logger via the gem Railtie).
+  # Set to nil to silence, or Logger.new($stdout) for plain Ruby.
+  # config.logger = Rails.logger
+
+  config.slack.enabled = true
+  config.slack.webhook_url = ENV["SLACK_WEBHOOK_URL"]
+  # Allow-list of events for this provider. nil (or []) = ALL events.
+  # Replace the examples below with your own event names.
+  config.slack.events = ["loan.activated", "loan.overdue", "payment.received"]
+
+  config.email.enabled = false
+  config.email.from = ENV["EVENT_TRIGGER_EMAIL_FROM"]
+  config.email.to = ENV["EVENT_TRIGGER_EMAIL_TO"]
+  # nil (or []) = ALL events.
+  config.email.events = ["loan.activated", "loan.foreclosed"]
+
+  config.webhook.enabled = false
+  config.webhook.url = ENV["EVENT_TRIGGER_WEBHOOK_URL"]
+  # nil (or []) = ALL events.
+  config.webhook.events = ["loan.activated"]
+end

data/sig/event_trigger.rbs

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

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: event_trigger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kamlesh Parmar
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: net-smtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: 'EventTrigger provides a simple event system with pluggable notification
+  providers (Slack, Email, Webhook, custom). Configure providers once, then call EventTrigger.trigger("event.name",
+  data: {...}) and the gem dispatches to the enabled providers configured for that
+  event. Works in plain Ruby and Ruby on Rails.'
+email:
+- malviyak00@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/event_trigger.rb
+- lib/event_trigger/configuration.rb
+- lib/event_trigger/defaults.rb
+- lib/event_trigger/dispatcher.rb
+- lib/event_trigger/event.rb
+- lib/event_trigger/provider.rb
+- lib/event_trigger/providers/email_provider.rb
+- lib/event_trigger/providers/slack_provider.rb
+- lib/event_trigger/providers/webhook_provider.rb
+- lib/event_trigger/railtie.rb
+- lib/event_trigger/registry.rb
+- lib/event_trigger/version.rb
+- lib/generators/event_trigger/install_generator.rb
+- lib/generators/event_trigger/templates/event_trigger.rb
+- sig/event_trigger.rbs
+homepage: https://github.com/mrmalvi/event_trigger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mrmalvi/event_trigger
+  source_code_uri: https://github.com/mrmalvi/event_trigger
+  changelog_uri: https://github.com/mrmalvi/event_trigger/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Configurable event-based notification system for Ruby and Rails.
+test_files: []