rerout-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c0b86702f8da895a164e119949243826b64a33677c516f410a5284c7d91333c
+  data.tar.gz: 0557d87f5d559532ab23b11c96634e02a7a0887b3aec4a5ab60abc5b61745dcd
+SHA512:
+  metadata.gz: 3deaaaf8a1ca54421f48c6fec592bbfa633411871ecc96f744fcb50ceb7fb278086b211aa03e4d417869bc2091ece0b18ad34ac07db3b31236a213b9c983b937
+  data.tar.gz: 6a9c8ffda128b81176bfdbbf72f9e71078abeb9d6aa0ed2db9f28b87c1c3e2cee5e875b1dbf486bf68ba05234ca1d8455357ef6a20d18d546965298d15bca345

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to the `rerout-rails` gem are documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-20
+
+### Added
+
+- Initial public release.
+- `Rerout::Rails.configure` — initializer-driven configuration with
+  environment-variable fallbacks for `api_key`, `webhook_secret`, and
+  `base_url`.
+- `Rerout::Rails.client` — a process-wide, lazily-built, cached
+  `Rerout::Client`.
+- `Rerout::Rails::WebhookController` — verifies the `X-Rerout-Signature`
+  header and responds `200` / `401` / `400`. CSRF protection is skipped for
+  server-to-server deliveries.
+- `Rerout::Rails::Events` — dispatches verified deliveries through
+  `ActiveSupport::Notifications`: a `rerout.webhook` catch-all plus per-event
+  topics (`rerout.link.created`, `rerout.link.updated`, `rerout.link.deleted`,
+  `rerout.link.clicked`, `rerout.qr.scanned`).
+- `Rerout::Rails::Railtie` — hooks the integration into the Rails boot
+  process.
+- `rails generate rerout:install` — drops `config/initializers/rerout.rb` and
+  mounts the webhook route.
+- `Rerout::Rails::ConfigurationError` raised on missing `api_key` or
+  `webhook_secret`.
+
+[0.1.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/ruby-rails-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codecraft Solutions
+
+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,166 @@
+# rerout-rails
+
+Official Rails integration for the [Rerout](https://rerout.co) API.
+
+Wraps the base [`rerout`](https://rubygems.org/gems/rerout) gem with
+Rails-native ergonomics: a cached, initializer-driven API client, an install
+generator, and a webhook controller that verifies signatures and dispatches
+each delivery through `ActiveSupport::Notifications`.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'rerout-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate rerout:install
+```
+
+Requires Ruby 3.0+ and Rails 7.0+. The `rerout` gem is pulled in
+automatically.
+
+The generator drops `config/initializers/rerout.rb` and mounts the webhook
+route in `config/routes.rb`.
+
+## Configuration
+
+`rails generate rerout:install` writes `config/initializers/rerout.rb`:
+
+```ruby
+Rerout::Rails.configure do |config|
+  config.api_key = ENV.fetch('REROUT_API_KEY', nil)
+  config.webhook_secret = ENV.fetch('REROUT_WEBHOOK_SECRET', nil)
+
+  # config.base_url = 'https://api.rerout.co'
+  # config.timeout = 30
+  # config.signature_tolerance_seconds = 300
+end
+```
+
+`api_key`, `webhook_secret`, and `base_url` fall back to the `REROUT_API_KEY`,
+`REROUT_WEBHOOK_SECRET`, and `REROUT_BASE_URL` environment variables when not
+set explicitly. Keep secrets out of source control — prefer Rails encrypted
+credentials or environment variables.
+
+## API client
+
+`Rerout::Rails.client` is a process-wide, lazily-built `Rerout::Client`. It is
+created once from your configuration and reused across requests — the
+underlying Faraday connection is thread-safe, so sharing one instance is the
+recommended pattern.
+
+```ruby
+class LinksController < ApplicationController
+  def create
+    link = Rerout::Rails.client.links.create(
+      Rerout::CreateLinkInput.new(target_url: params[:target_url])
+    )
+    render json: { short_url: link.short_url }
+  end
+end
+```
+
+`Rerout::Rails.client` raises `Rerout::Rails::ConfigurationError` if `api_key`
+is unset. See the [`rerout` gem README](https://rubygems.org/gems/rerout) for
+the full client surface — `links`, `project`, and `qr` namespaces.
+
+## Webhooks
+
+The install generator mounts the receiver:
+
+```ruby
+# config/routes.rb
+post '/rerout/webhooks', to: 'rerout/rails/webhook#receive', as: :rerout_webhook
+```
+
+Point your Rerout dashboard webhook endpoint at `POST /rerout/webhooks`. The
+controller:
+
+- verifies the `X-Rerout-Signature` header against `webhook_secret` with a
+  constant-time HMAC check (CSRF protection is skipped — webhooks are
+  server-to-server),
+- responds `200` when the signature is valid and the body is a JSON object,
+- responds `401` when the signature is missing, malformed, stale, or wrong,
+- responds `400` when the body is not a JSON object.
+
+To wire it up manually instead of using the generator, add the route above to
+`config/routes.rb` yourself.
+
+## Reacting to events
+
+Every verified delivery is instrumented through
+`ActiveSupport::Notifications`. Subscribe anywhere — an initializer, an
+`ApplicationJob`, a service object:
+
+```ruby
+# Fires for every verified webhook, regardless of event type.
+ActiveSupport::Notifications.subscribe('rerout.webhook') do |event|
+  Rails.logger.info("Rerout webhook: #{event.payload[:event]}")
+end
+
+# Fires only for link.clicked events.
+ActiveSupport::Notifications.subscribe('rerout.link.clicked') do |event|
+  code = event.payload[:body]['code']
+  ClickCounter.increment(code)
+end
+```
+
+The instrumentation payload carries:
+
+- `:event` — the event-type string (e.g. `"link.clicked"`), or `""`.
+- `:body` — the full parsed JSON body as a Hash.
+- `:request` — the `ActionDispatch::Request` that delivered the webhook.
+
+Topics emitted: `rerout.webhook` (catch-all) plus `rerout.link.created`,
+`rerout.link.updated`, `rerout.link.deleted`, `rerout.link.clicked`, and
+`rerout.qr.scanned` for recognised events.
+
+## Webhook signature verification
+
+The controller verifies signatures for you. To verify a signature elsewhere —
+in a background job, a Rack endpoint, a custom controller — use the base SDK
+helper directly:
+
+```ruby
+ok = Rerout::Webhooks.verify_signature(
+  raw_body: request.raw_post,
+  signature_header: request.headers['X-Rerout-Signature'],
+  secret: Rerout::Rails.config.webhook_secret!
+)
+```
+
+The five-minute timestamp tolerance is configurable via
+`config.signature_tolerance_seconds` (`0` disables the staleness check).
+
+## Error handling
+
+API calls through `Rerout::Rails.client` raise `Rerout::Error`, with a stable
+`code`, an HTTP `status`, and `rate_limited?` / `server_error?` flags:
+
+```ruby
+begin
+  Rerout::Rails.client.links.get(params[:code])
+rescue Rerout::Error => e
+  return head(:not_found) if e.code == 'not_found'
+  raise
+end
+```
+
+Misconfiguration (missing `api_key` or `webhook_secret`) raises
+`Rerout::Rails::ConfigurationError`.
+
+## License
+
+MIT — see [LICENSE](LICENSE), a copy of the workspace
+[LICENSE](https://github.com/ModestNerds-Co/rerout-sdks/blob/main/LICENSE).
+
+## Links
+
+- API docs: <https://rerout.co/docs>
+- Source: <https://github.com/ModestNerds-Co/rerout-sdks>

data/lib/generators/rerout/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/base'
+
+module Rerout
+  module Generators
+    # `rails generate rerout:install`
+    #
+    # Drops a `config/initializers/rerout.rb` initializer and appends the
+    # webhook route to `config/routes.rb` so a fresh app is wired up in one
+    # command.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a Rerout initializer and mounts the webhook route.'
+
+      # Copy the commented initializer into the host application.
+      #
+      # @return [void]
+      def create_initializer
+        template 'rerout.rb', 'config/initializers/rerout.rb'
+      end
+
+      # Append the webhook receiver route to `config/routes.rb`.
+      #
+      # @return [void]
+      def add_webhook_route
+        route_line = "post '/rerout/webhooks', " \
+                     "to: 'rerout/rails/webhook#receive', as: :rerout_webhook"
+        route(route_line)
+      end
+
+      # Print next steps.
+      #
+      # @return [void]
+      def print_post_install
+        readme 'POST_INSTALL' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/rerout/templates/POST_INSTALL

@@ -0,0 +1,24 @@
+
+  Rerout is installed.
+
+  1. Set your credentials (environment variables or Rails credentials):
+
+       REROUT_API_KEY=rrk_...
+       REROUT_WEBHOOK_SECRET=whsec_...
+
+  2. Review config/initializers/rerout.rb.
+
+  3. The webhook receiver is mounted at:
+
+       POST /rerout/webhooks   (route name: rerout_webhook)
+
+     Point your Rerout dashboard endpoint at that URL.
+
+  4. Subscribe to delivery events anywhere in your app:
+
+       ActiveSupport::Notifications.subscribe('rerout.webhook') do |event|
+         Rails.logger.info("Rerout webhook: #{event.payload[:event]}")
+       end
+
+  Use the API client with Rerout::Rails.client. Docs: https://rerout.co/docs
+

data/lib/generators/rerout/templates/rerout.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Rerout configuration.
+#
+# Keep real credentials out of source control — prefer Rails encrypted
+# credentials (`Rails.application.credentials`) or environment variables.
+#
+# Docs: https://rerout.co/docs
+Rerout::Rails.configure do |config|
+  # Project API key (`rrk_…`). Required to use `Rerout::Rails.client`.
+  config.api_key = ENV.fetch('REROUT_API_KEY', nil)
+
+  # Endpoint signing secret (`whsec_…`). Required for webhook verification.
+  config.webhook_secret = ENV.fetch('REROUT_WEBHOOK_SECRET', nil)
+
+  # Override the API base URL (staging / self-hosted). Optional.
+  # config.base_url = 'https://api.rerout.co'
+
+  # Per-request timeout in seconds. Optional, defaults to 30.
+  # config.timeout = 30
+
+  # Webhook signature timestamp tolerance in seconds. `0` disables the
+  # staleness check. Optional, defaults to 300.
+  # config.signature_tolerance_seconds = 300
+end
+
+# React to verified webhook deliveries via ActiveSupport::Notifications.
+# `rerout.webhook` fires for every delivery; per-event topics
+# (`rerout.link.clicked`, `rerout.qr.scanned`, …) fire for known events.
+#
+# ActiveSupport::Notifications.subscribe('rerout.link.clicked') do |event|
+#   code = event.payload[:body]['code']
+#   Rails.logger.info("Rerout: link #{code} clicked")
+# end

data/lib/rerout/rails/configuration.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'rerout'
+
+module Rerout
+  module Rails
+    # Holds the `rerout-rails` configuration and lazily builds a process-wide,
+    # cached {Rerout::Client}.
+    #
+    # Configure it from an initializer (the `rerout:install` generator drops
+    # one for you):
+    #
+    #   Rerout::Rails.configure do |config|
+    #     config.api_key = ENV.fetch('REROUT_API_KEY')
+    #     config.webhook_secret = ENV.fetch('REROUT_WEBHOOK_SECRET')
+    #     # config.base_url = 'https://api.rerout.co'
+    #     # config.timeout = 30
+    #     # config.signature_tolerance_seconds = 300
+    #   end
+    #
+    # The client is built once on first access and reused — {Rerout::Client}
+    # wraps a thread-safe Faraday connection, so sharing one instance is the
+    # recommended pattern.
+    class Configuration
+      # @return [String, nil] project API key (`rrk_…`). Required before
+      #   {#client} can be used.
+      attr_accessor :api_key
+
+      # @return [String, nil] endpoint signing secret (`whsec_…`). Required
+      #   for webhook signature verification.
+      attr_accessor :webhook_secret
+
+      # @return [String, nil] override the API base URL.
+      attr_accessor :base_url
+
+      # @return [Integer] per-request timeout in seconds. Default 30.
+      attr_accessor :timeout
+
+      # @return [Integer] webhook signature timestamp tolerance in seconds.
+      #   `0` disables the staleness check. Default 300.
+      attr_accessor :signature_tolerance_seconds
+
+      # @return [String, nil] override the SDK `User-Agent` header.
+      attr_accessor :user_agent
+
+      # @return [String] path the webhook controller is mounted at when the
+      #   generated routes are used. Default `/rerout/webhooks`.
+      attr_accessor :webhook_path
+
+      def initialize
+        @api_key = ENV.fetch('REROUT_API_KEY', nil)
+        @webhook_secret = ENV.fetch('REROUT_WEBHOOK_SECRET', nil)
+        @base_url = ENV.fetch('REROUT_BASE_URL', nil)
+        @timeout = 30
+        @signature_tolerance_seconds = Rerout::Webhooks::DEFAULT_TOLERANCE_SECONDS
+        @user_agent = nil
+        @webhook_path = '/rerout/webhooks'
+        @client = nil
+        @client_mutex = Mutex.new
+      end
+
+      # The process-wide cached {Rerout::Client}, built from this config.
+      #
+      # @return [Rerout::Client]
+      # @raise [Rerout::Rails::ConfigurationError] when `api_key` is unset.
+      def client
+        return @client if @client
+
+        @client_mutex.synchronize do
+          @client ||= build_client
+        end
+      end
+
+      # Drop the cached client. The next {#client} call rebuilds it. Useful
+      # after changing credentials in tests.
+      #
+      # @return [void]
+      def reset_client!
+        @client_mutex.synchronize { @client = nil }
+      end
+
+      # The configured webhook signing secret.
+      #
+      # @return [String]
+      # @raise [Rerout::Rails::ConfigurationError] when unset or blank.
+      def webhook_secret!
+        if webhook_secret.nil? || webhook_secret.to_s.strip.empty?
+          raise ConfigurationError,
+                'Rerout::Rails.config.webhook_secret is required to verify ' \
+                'webhook signatures. Set it in config/initializers/rerout.rb ' \
+                'or via the REROUT_WEBHOOK_SECRET environment variable.'
+        end
+        webhook_secret
+      end
+
+      private
+
+      def build_client
+        if api_key.nil? || api_key.to_s.strip.empty?
+          raise ConfigurationError,
+                'Rerout::Rails.config.api_key is required to build a Rerout ' \
+                'client. Set it in config/initializers/rerout.rb or via the ' \
+                'REROUT_API_KEY environment variable.'
+        end
+
+        Rerout::Client.new(
+          api_key: api_key,
+          base_url: base_url,
+          timeout: timeout,
+          user_agent: user_agent
+        )
+      end
+    end
+
+    # Raised when `rerout-rails` is missing required configuration.
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/rerout/rails/events.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rerout
+  module Rails
+    # Maps Rerout webhook event names onto `ActiveSupport::Notifications` topic
+    # names and dispatches verified deliveries.
+    #
+    # Every verified webhook is instrumented under {CATCH_ALL} (`rerout.webhook`)
+    # so a single subscriber can see everything. Events with a recognised
+    # `event` field are *also* instrumented under a dedicated, more specific
+    # topic so subscribers can listen narrowly.
+    #
+    # Subscribe the Rails way:
+    #
+    #   ActiveSupport::Notifications.subscribe('rerout.link.clicked') do |event|
+    #     code = event.payload[:body]['code']
+    #     Rails.logger.info("link #{code} clicked")
+    #   end
+    #
+    # The instrumentation payload carries:
+    #
+    # - `:event`   — the event-type string (e.g. `"link.clicked"`), or `""`.
+    # - `:body`    — the full parsed JSON body as a Hash.
+    # - `:request` — the `ActionDispatch::Request` that delivered the webhook.
+    module Events
+      # Topic every verified webhook is instrumented under.
+      CATCH_ALL = 'rerout.webhook'
+
+      # Known `event` strings mapped onto their dedicated notification topic.
+      # Events absent from this map still fire {CATCH_ALL}.
+      TOPICS = {
+        'link.created' => 'rerout.link.created',
+        'link.updated' => 'rerout.link.updated',
+        'link.deleted' => 'rerout.link.deleted',
+        'link.clicked' => 'rerout.link.clicked',
+        'qr.scanned' => 'rerout.qr.scanned'
+      }.freeze
+
+      module_function
+
+      # Instrument a verified webhook delivery.
+      #
+      # Fires {CATCH_ALL} unconditionally, then the event-specific topic when
+      # `event` is one of {TOPICS}.
+      #
+      # @param event [String] the event-type string; may be empty.
+      # @param body [Hash] the parsed JSON body.
+      # @param request [ActionDispatch::Request, nil] the delivering request.
+      # @return [void]
+      def dispatch(event:, body:, request: nil)
+        payload = { event: event, body: body, request: request }
+
+        ActiveSupport::Notifications.instrument(CATCH_ALL, payload)
+
+        specific = TOPICS[event]
+        ActiveSupport::Notifications.instrument(specific, payload) if specific
+      end
+
+      # @return [Array<String>] every notification topic this gem can emit.
+      def all_topics
+        [CATCH_ALL, *TOPICS.values]
+      end
+    end
+  end
+end

data/lib/rerout/rails/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Rerout
+  module Rails
+    # Hooks `rerout-rails` into the Rails boot process.
+    #
+    # The railtie keeps the integration zero-config beyond the initializer:
+    # the webhook controller and generators are autoloaded by Rails' standard
+    # `lib/` eager-loading once the gem is in the `Gemfile`.
+    class Railtie < ::Rails::Railtie
+      # Namespaced config accessible as `Rails.application.config.rerout`.
+      config.rerout = Rerout::Rails.config
+
+      # Make `Rerout::Rails::WebhookController` resolvable by the router
+      # without the host app having to require it explicitly.
+      initializer 'rerout.rails.controller' do
+        require 'rerout/rails/webhook_controller'
+      end
+    end
+  end
+end

data/lib/rerout/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Rerout
+  module Rails
+    # Version of the `rerout-rails` gem. Follows semantic versioning and is
+    # released in lockstep with the base `rerout` gem.
+    VERSION = '0.1.0'
+  end
+end

data/lib/rerout/rails/webhook_controller.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'action_controller'
+require 'rerout'
+
+require_relative 'events'
+
+module Rerout
+  module Rails
+    # `ActionController` endpoint that ingests signed Rerout webhooks.
+    #
+    # The `rerout:install` generator mounts it for you. To wire it manually:
+    #
+    #   # config/routes.rb
+    #   post '/rerout/webhooks', to: 'rerout/rails/webhook#receive'
+    #
+    # Behaviour:
+    #
+    # - Verifies the `X-Rerout-Signature` header against the configured
+    #   `webhook_secret` using the base SDK's constant-time HMAC check.
+    # - `200` — signature valid and the body is a JSON object; the delivery is
+    #   dispatched through {Rerout::Rails::Events}.
+    # - `401` — signature missing, malformed, stale, or wrong.
+    # - `400` — signature valid but the body is not a JSON object.
+    #
+    # CSRF protection is skipped — webhooks are server-to-server and carry no
+    # session cookie. Subscribe to {Rerout::Rails::Events} topics to react to
+    # deliveries; do not subclass this controller to add handlers.
+    class WebhookController < ActionController::Base
+      # Header Rerout signs every delivery with.
+      SIGNATURE_HEADER = 'X-Rerout-Signature'
+
+      # Webhooks are unauthenticated server-to-server POSTs — no CSRF token.
+      skip_forgery_protection if respond_to?(:skip_forgery_protection)
+
+      # Verify, parse, and dispatch a single webhook delivery.
+      #
+      # @return [void]
+      def receive
+        raw_body = read_raw_body
+        signature = request.headers[SIGNATURE_HEADER].to_s
+
+        unless signature_valid?(raw_body, signature)
+          return render(json: { error: 'invalid signature' }, status: :unauthorized)
+        end
+
+        body = parse_object(raw_body)
+        if body.nil?
+          return render(json: { error: 'body must be a JSON object' },
+                        status: :bad_request)
+        end
+
+        event = body['event'].is_a?(String) ? body['event'] : ''
+        Events.dispatch(event: event, body: body, request: request)
+
+        render json: { received: true, event: event }, status: :ok
+      end
+
+      private
+
+      def config
+        Rerout::Rails.config
+      end
+
+      # Read the exact request body bytes. `request.body` may already have been
+      # consumed by Rails' params parsing, so rewind first.
+      def read_raw_body
+        body = request.body
+        body.rewind if body.respond_to?(:rewind)
+        body.read.to_s
+      end
+
+      def signature_valid?(raw_body, signature)
+        Rerout::Webhooks.verify_signature(
+          raw_body: raw_body,
+          signature_header: signature,
+          secret: config.webhook_secret!,
+          tolerance_seconds: config.signature_tolerance_seconds
+        )
+      end
+
+      # Parse `raw_body` and return it only when it is a JSON object. Returns
+      # `nil` for non-JSON, JSON arrays, JSON scalars, or an empty body.
+      def parse_object(raw_body)
+        return nil if raw_body.empty?
+
+        parsed = JSON.parse(raw_body)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/rerout/rails.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'rerout'
+
+require_relative 'rails/version'
+require_relative 'rails/configuration'
+require_relative 'rails/events'
+
+module Rerout
+  # Official Rails integration for the Rerout branded-link API.
+  #
+  # Wraps the base {Rerout} SDK with Rails-native ergonomics:
+  #
+  # - {Rerout::Rails.client} — a process-wide {Rerout::Client} built from an
+  #   initializer.
+  # - {Rerout::Rails::WebhookController} — verifies the `X-Rerout-Signature`
+  #   header and instruments an `ActiveSupport::Notifications` event per
+  #   delivery.
+  # - {Rerout::Rails::Events} — the notification topics apps subscribe to.
+  #
+  # @see https://rerout.co
+  # @see https://github.com/ModestNerds-Co/rerout-sdks
+  module Rails
+    class << self
+      # The global {Rerout::Rails::Configuration}.
+      #
+      # @return [Rerout::Rails::Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Yields the configuration for mutation. Call from an initializer.
+      #
+      #   Rerout::Rails.configure do |c|
+      #     c.api_key = ENV.fetch('REROUT_API_KEY')
+      #   end
+      #
+      # @yieldparam config [Rerout::Rails::Configuration]
+      # @return [Rerout::Rails::Configuration]
+      def configure
+        yield(config) if block_given?
+        config
+      end
+
+      # The shared, lazily-built {Rerout::Client}.
+      #
+      # @return [Rerout::Client]
+      # @raise [Rerout::Rails::ConfigurationError] when `api_key` is unset.
+      def client
+        config.client
+      end
+
+      # Replace the configuration wholesale. Mainly a test seam.
+      #
+      # @param configuration [Rerout::Rails::Configuration]
+      # @return [Rerout::Rails::Configuration]
+      attr_writer :config
+
+      # Drop the global configuration and cached client. Test seam.
+      #
+      # @return [void]
+      def reset!
+        @config = nil
+      end
+    end
+  end
+end
+
+# The railtie pulls in Rails' boot machinery — load it only when Rails itself
+# is present so the gem stays usable (config + webhook verification) in plain
+# Ruby contexts and test harnesses.
+require 'rerout/rails/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,200 @@
+--- !ruby/object:Gem::Specification
+name: rerout-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Codecraft Solutions
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rerout
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !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.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+- !ruby/object:Gem::Dependency
+  name: rubocop-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'
+description: |
+  Rails integration for the Rerout API. Wraps the `rerout` gem with a
+  cached, initializer-driven client, an install generator, and a webhook
+  controller that verifies signatures and dispatches each delivery through
+  ActiveSupport::Notifications.
+email:
+- hello@codecraftsolutions.co.za
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/rerout/install_generator.rb
+- lib/generators/rerout/templates/POST_INSTALL
+- lib/generators/rerout/templates/rerout.rb
+- lib/rerout/rails.rb
+- lib/rerout/rails/configuration.rb
+- lib/rerout/rails/events.rb
+- lib/rerout/rails/railtie.rb
+- lib/rerout/rails/version.rb
+- lib/rerout/rails/webhook_controller.rb
+homepage: https://github.com/ModestNerds-Co/rerout-sdks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ModestNerds-Co/rerout-sdks
+  source_code_uri: https://github.com/ModestNerds-Co/rerout-sdks/tree/main/ruby-rails
+  changelog_uri: https://github.com/ModestNerds-Co/rerout-sdks/blob/main/ruby-rails/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ModestNerds-Co/rerout-sdks/issues
+  documentation_uri: https://rerout.co/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Rails integration for the Rerout branded-link API.
+test_files: []