smswire 0.0.1.pre → 0.1.0

data/lib/generators/smswire/provider/templates/test.rb.tt

@@ -0,0 +1,29 @@
+require "test_helper"
+require "webmock/minitest"
+
+class <%= provider_class %>Test < ActiveSupport::TestCase
+  include Smswire::TestHelper
+  include Smswire::ProviderContract
+
+  def contract_provider_name = :<%= file_name %>
+
+  def contract_provider_options = {api_key: "test-key"}
+
+  # Stub the provider API for each contract outcome. Update the error
+  # payloads to the provider's real responses.
+  def stub_contract_send(outcome, message)
+    stub = stub_request(:post, <%= provider_class %>::API_URL)
+    error = ->(status, code) { stub.to_return(status:, body: {error: {code:}}.to_json) }
+    case outcome
+    when :success
+      stub.with(body: hash_including("to" => message.to, "body" => message.body))
+        .to_return(status: 200, body: {id: "msg_1"}.to_json)
+    when :invalid_number then error.call(400, "invalid_number")
+    when :opted_out then error.call(400, "opted_out")
+    when :authentication then stub.to_return(status: 401)
+    when :throttled then stub.to_return(status: 429)
+    when :server_error then stub.to_return(status: 503)
+    when :timeout then stub.to_timeout
+    end
+  end
+end

data/lib/smswire/base.rb

@@ -0,0 +1,123 @@
+require "abstract_controller"
+require "action_view"
+
+module Smswire
+  # Base class for messengers, modeled on ActionMailer::Base.
+  #
+  #   class OrderMessenger < Smswire::Base
+  #     default from: :transactional
+  #
+  #     def shipped(user)
+  #       @order = params[:order]
+  #       text to: user   # renders app/views/order_messenger/shipped.text.erb
+  #     end
+  #   end
+  #
+  #   OrderMessenger.with(order:).shipped(user).deliver_later
+  class Base < AbstractController::Base
+    include AbstractController::Rendering
+    include AbstractController::Logger
+    include AbstractController::Helpers
+    include AbstractController::Translation
+    include AbstractController::Callbacks
+    include ActionView::Layouts
+
+    abstract!
+
+    TEXT_OPTIONS = %i[category provider messaging_service media_urls metadata idempotency_key validity_period consent_scope].freeze
+    DEFAULT_KEYS = (%i[from] + TEXT_OPTIONS - %i[media_urls idempotency_key]).freeze
+
+    class_attribute :default_params, default: {}.freeze
+
+    class << self
+      # Class-level defaults for every message this messenger builds.
+      # Supported keys: from, category, provider, messaging_service,
+      # metadata, validity_period.
+      def default(value = nil)
+        if value
+          unknown = value.keys.map(&:to_sym) - DEFAULT_KEYS
+          raise ArgumentError, "Unknown default(s): #{unknown.join(", ")}" if unknown.any?
+          self.default_params = default_params.merge(value.symbolize_keys).freeze
+        end
+        default_params
+      end
+      alias_method :default_options=, :default
+
+      def with(params)
+        ParameterizedMessenger.new(self, params)
+      end
+
+      def messenger_name
+        controller_path
+      end
+
+      def respond_to_missing?(name, include_all = false)
+        action_methods.include?(name.to_s) || super
+      end
+
+      private
+
+      def method_missing(name, *args, **kwargs, &block)
+        if action_methods.include?(name.to_s)
+          MessageDelivery.new(self, name, args:, kwargs:)
+        else
+          super
+        end
+      end
+    end
+
+    attr_writer :params
+
+    def params
+      @params ||= {}
+    end
+
+    # The message built by the last processed action, or nil when the
+    # action returned without calling +text+.
+    def message
+      @_message if @_message_was_called
+    end
+
+    def process(method_name, *args, **kwargs)
+      @_message_was_called = false
+      @_message = nil
+      super
+    end
+
+    def messenger_name
+      self.class.messenger_name
+    end
+
+    # Build the message for this action. When +body+ is omitted the body is
+    # rendered from app/views/<messenger_name>/<action>.text.erb.
+    def text(to:, body: nil, from: nil, **options)
+      unknown = options.keys - TEXT_OPTIONS
+      raise ArgumentError, "Unknown option(s) for text: #{unknown.join(", ")}" if unknown.any?
+
+      settings = self.class.default_params.merge(options)
+      sender = Sender.resolve(from || settings[:from])
+      recipient = Recipient.resolve(to)
+      content = body.nil? ? render_to_string(action: action_name, formats: [:text]) : body
+
+      @_message_was_called = true
+      @_message = Message.new(
+        to: recipient.phone,
+        recipient:,
+        from: sender.number,
+        messaging_service: settings[:messaging_service] || sender.messaging_service,
+        provider: settings[:provider] || sender.provider,
+        body: BodyFormatter.call(content),
+        media_urls: settings[:media_urls],
+        category: settings[:category],
+        metadata: (settings[:metadata] || {}).merge(params.fetch(:smswire_metadata, {})),
+        validity_period: settings[:validity_period],
+        idempotency_key: settings[:idempotency_key],
+        consent_scope: settings[:consent_scope] || sender.consent_scope,
+        messenger: self.class.name,
+        action: action_name
+      )
+    end
+
+    ActiveSupport.run_load_hooks(:smswire, self)
+  end
+end

data/lib/smswire/body_formatter.rb

@@ -0,0 +1,14 @@
+module Smswire
+  module BodyFormatter
+    module_function
+
+    def call(text, mode = Smswire.config.body_whitespace)
+      text = text.to_s
+      case mode
+      when :squish then text.squish
+      when :preserve then text
+      else text.gsub(/[ \t]+$/, "").gsub(/\n{3,}/, "\n\n").strip
+      end
+    end
+  end
+end

data/lib/smswire/callbacks.rb

@@ -0,0 +1,24 @@
+module Smswire
+  # Builds callback URLs from Smswire.config.callbacks_url and reconstructs
+  # the public URL of an incoming callback for signature checks.
+  module Callbacks
+    module_function
+
+    def status_url(provider, delivery = nil)
+      base = Smswire.config.callbacks_url.presence or return nil
+      url = "#{base.chomp("/")}/status/#{provider}"
+      delivery ? "#{url}?delivery_id=#{delivery.id}" : url
+    end
+
+    # The URL the provider signed. Behind a TLS-terminating proxy the
+    # request may look like plain HTTP, so when callbacks_url is configured
+    # its scheme, host, and port are used with the request path.
+    def request_url(request)
+      base = Smswire.config.callbacks_url.presence or return request.original_url
+      uri = URI(base)
+      origin = "#{uri.scheme}://#{uri.host}"
+      origin += ":#{uri.port}" unless uri.port == uri.default_port
+      origin + request.original_fullpath
+    end
+  end
+end

data/lib/smswire/configuration.rb

@@ -0,0 +1,224 @@
+module Smswire
+  class Configuration
+    WHITESPACE_MODES = %i[strip squish preserve].freeze
+    CONSENT_RULES = %i[allow_unless_opted_out require_opted_in none].freeze
+
+    # Shipped category rules. Settings in +categories+ are merged over these
+    # per key, so overriding one category leaves the others intact.
+    # Marketing quiet hours follow the US federal TCPA window (8am to 9pm
+    # recipient time); some states are stricter.
+    DEFAULT_CATEGORIES = {
+      otp: {consent: :allow_unless_opted_out, store_body: false},
+      transactional: {consent: :allow_unless_opted_out},
+      marketing: {consent: :require_opted_in, quiet_hours: "21:00".."08:00"},
+      compliance: {consent: :none}
+    }.freeze
+
+    DEFAULT_KEYWORDS = {
+      opt_out: %w[STOP STOPALL UNSUBSCRIBE CANCEL END QUIT OPTOUT REVOKE],
+      opt_in: %w[START YES UNSTOP],
+      help: %w[HELP INFO]
+    }.freeze
+
+    # CTIA guidance: the opt-out confirmation names the brand, confirms the
+    # removal, and says no further messages will be sent; the HELP reply
+    # names the brand and a support contact.
+    DEFAULT_KEYWORD_REPLIES = {
+      opt_out: "%{program}: You are unsubscribed and will no longer receive any further messages. Reply START to resubscribe.",
+      opt_in: "%{program}: You are subscribed again. Reply HELP for help, STOP to unsubscribe. Msg & data rates may apply.",
+      help: "%{program}: For help, contact %{contact}. Reply STOP to unsubscribe. Msg & data rates may apply."
+    }.freeze
+    HELP_WITHOUT_CONTACT = "%{program}: Reply STOP to unsubscribe. Msg & data rates may apply.".freeze
+    PHONE_VALIDATORS = %i[auto phonelib e164].freeze
+
+    # Provider name used when a message or sender does not name one.
+    # The Railtie defaults this to :log in development and :test in test.
+    attr_accessor :default_provider
+
+    # Per-provider options, e.g. { twilio: { account_sid: "...", auth_token: "..." } }.
+    attr_accessor :providers
+
+    # Named senders, e.g. { transactional: { number: "+1...", provider: :twilio } }.
+    attr_accessor :senders
+
+    # Callable that turns a recipient object into a phone number string.
+    # When nil, objects responding to +phone_number+ are used.
+    attr_accessor :recipient_resolver
+
+    # ISO 3166 region used to parse numbers written in national format.
+    attr_accessor :default_region
+
+    # :auto uses phonelib when it is loaded, :phonelib requires it, and
+    # :e164 uses the built-in validator (E.164 plus NANP national formats).
+    attr_reader :phone_validator
+
+    attr_accessor :default_category
+
+    # Total attempts for transient errors in Smswire::DeliveryJob,
+    # counting the first.
+    attr_accessor :retry_attempts
+
+    attr_accessor :deliver_later_queue
+
+    # How rendered and literal bodies are cleaned before sending.
+    # :strip removes trailing spaces on each line, collapses three or more
+    # newlines to two, and strips the ends. :squish collapses all
+    # whitespace to single spaces. :preserve leaves the body untouched.
+    attr_reader :body_whitespace
+
+    attr_accessor :interceptors, :observers, :logger
+
+    # Record every send in smswire_deliveries. Requires the engine migrations.
+    attr_accessor :persist_deliveries
+
+    # Identical messages (same messenger, action, recipient, and body, or the
+    # same explicit idempotency_key) inside this window are refused as
+    # :duplicate. nil disables deduplication.
+    attr_accessor :dedupe_window
+
+    # Public base URL where Smswire::Engine is mounted, e.g.
+    # "https://app.example.com/smswire". When set, providers that support
+    # status callbacks are told to post to "<callbacks_url>/status/<provider>".
+    attr_accessor :callbacks_url
+
+    attr_accessor :verify_callback_signatures
+
+    # Store message bodies on deliveries. Overridden per category with
+    # categories: { otp: { store_body: false } }.
+    attr_accessor :store_bodies
+
+    # Per-category settings merged over DEFAULT_CATEGORIES:
+    #   consent:     :allow_unless_opted_out, :require_opted_in, or :none
+    #   quiet_hours: "21:00".."08:00" in the recipient's time zone, or nil
+    #   rate_limit:  { max: 3, per: 1.day, exceed: :defer }  (or :reject)
+    #   store_body:  overrides store_bodies
+    attr_accessor :categories
+
+    # Check consent before sending and record carrier opt-outs. Turn off
+    # only when another system, such as Twilio Advanced Opt-Out, owns consent.
+    attr_accessor :enforce_consent
+
+    # Time zone for quiet hours when the recipient has none. Defaults to
+    # Time.zone.
+    attr_accessor :default_time_zone
+
+    # Inbound keyword sets: { opt_out: [...], opt_in: [...], help: [...] }.
+    attr_accessor :keywords
+
+    # Auto-reply bodies per keyword kind; %{program} is replaced by
+    # program_name. Set a kind to nil to send no reply.
+    attr_accessor :keyword_replies
+
+    attr_accessor :program_name
+
+    # Phone number, email, or URL for customer care, used in HELP replies
+    # as %{contact}. CTIA guidance expects one.
+    attr_accessor :support_contact
+
+    # When true, STOP to any sender opts the number out of every consent
+    # scope, as STOPALL does. The FCC rule applying a revocation to all of a
+    # sender's unrelated messages is delayed to January 31, 2027.
+    attr_accessor :opt_out_all_scopes
+
+    # Development tools served by the engine. Both default to true in
+    # development only. Set them in config/application.rb or an environment
+    # file as config.smswire.show_previews, since preview paths are
+    # registered for autoloading before initializers run.
+    attr_accessor :show_previews, :show_inbox, :preview_paths
+
+    def initialize
+      @default_provider = nil
+      @providers = {}
+      @senders = {}
+      @recipient_resolver = nil
+      @default_region = "US"
+      @phone_validator = :auto
+      @default_category = :transactional
+      @retry_attempts = 5
+      @deliver_later_queue = :default
+      @body_whitespace = :strip
+      @interceptors = []
+      @observers = []
+      @logger = nil
+      @persist_deliveries = true
+      @dedupe_window = 10.minutes
+      @callbacks_url = nil
+      @verify_callback_signatures = true
+      @store_bodies = true
+      @categories = {}
+      @enforce_consent = true
+      @default_time_zone = nil
+      @keywords = DEFAULT_KEYWORDS.transform_values(&:dup)
+      @keyword_replies = DEFAULT_KEYWORD_REPLIES.dup
+      @program_name = nil
+      @support_contact = nil
+      @opt_out_all_scopes = false
+      @show_previews = false
+      @show_inbox = false
+      @preview_paths = []
+    end
+
+    def phone_validator=(value)
+      value = value.to_sym
+      unless PHONE_VALIDATORS.include?(value)
+        raise ConfigurationError, "phone_validator must be one of #{PHONE_VALIDATORS.join(", ")}"
+      end
+      @phone_validator = value
+    end
+
+    def body_whitespace=(value)
+      value = value.to_sym
+      unless WHITESPACE_MODES.include?(value)
+        raise ConfigurationError, "body_whitespace must be one of #{WHITESPACE_MODES.join(", ")}"
+      end
+      @body_whitespace = value
+    end
+
+    def category_options(category)
+      key = category.to_s.to_sym
+      custom = (categories[key] || categories[category.to_s] || {}).to_h.symbolize_keys
+      options = DEFAULT_CATEGORIES.fetch(key, {}).merge(custom)
+      consent = options.fetch(:consent, :allow_unless_opted_out).to_sym
+      unless CONSENT_RULES.include?(consent)
+        raise ConfigurationError, "Unknown consent rule #{consent.inspect} for category #{key}"
+      end
+      options.merge(consent:)
+    end
+
+    def time_zone
+      zone = default_time_zone || Time.zone || "UTC"
+      ActiveSupport::TimeZone[zone] || raise(ConfigurationError, "Unknown time zone #{zone.inspect}")
+    end
+
+    def consent_scopes
+      scopes = senders.values.filter_map { |options| options.to_h.symbolize_keys[:consent_scope]&.to_s }
+      (["default"] + scopes).uniq
+    end
+
+    def keyword_reply(kind)
+      template = keyword_replies[kind.to_sym] or return nil
+      if template.include?("%{contact}") && support_contact.blank?
+        Smswire.logger.warn("[Smswire] Set config.support_contact; HELP replies should include a support contact.")
+        template = HELP_WITHOUT_CONTACT if template == DEFAULT_KEYWORD_REPLIES[:help]
+      end
+      format(template, program: program_name || default_program_name, contact: support_contact.to_s)
+    end
+
+    def store_body?(category)
+      setting = category_options(category)[:store_body]
+      setting.nil? ? store_bodies : setting
+    end
+
+    def default_program_name
+      if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        ::Rails.application.class.module_parent_name.titleize
+      else
+        "our"
+      end
+    end
+
+    def provider_options(name)
+      (providers[name.to_sym] || providers[name.to_s] || {}).to_h.symbolize_keys
+    end
+  end
+end

data/lib/smswire/delivery_job.rb

@@ -0,0 +1,29 @@
+module Smswire
+  # Delivers a messenger action in the background. Transient errors are
+  # retried with polynomial backoff up to Smswire.config.retry_attempts
+  # total attempts. Throttled errors wait for the provider's Retry-After.
+  # Permanent errors are recorded as :failed results and not retried.
+  class DeliveryJob < ActiveJob::Base
+    queue_as { Smswire.config.deliver_later_queue }
+
+    rescue_from TransientError do |error|
+      raise error if executions >= Smswire.config.retry_attempts
+
+      retry_job(wait: retry_wait(error))
+    end
+
+    def perform(messenger_name, action, params, args, kwargs)
+      MessageDelivery.new(messenger_name.constantize, action, args:, kwargs:, params:).deliver_now
+    end
+
+    private
+
+    def retry_wait(error)
+      if error.is_a?(ThrottledError) && error.retry_after
+        error.retry_after.seconds
+      else
+        ((executions**4) + 2).seconds
+      end
+    end
+  end
+end

data/lib/smswire/engine.rb

@@ -0,0 +1,52 @@
+require "rails/engine"
+require "abstract_controller/railties/routes_helpers"
+
+module Smswire
+  # Mount for status callbacks:
+  #
+  #   mount Smswire::Engine => "/smswire"
+  #
+  # Install the migrations with +bin/rails smswire:install:migrations+.
+  class Engine < ::Rails::Engine
+    isolate_namespace Smswire
+
+    ENVIRONMENT_PROVIDERS = {development: :log, test: :test}.freeze
+
+    config.smswire = ActiveSupport::OrderedOptions.new
+
+    # Like Action Mailer: register preview directories for autoloading
+    # before Rails builds its autoload paths. Declared first because Rails
+    # chains an engine's initializers in declaration order.
+    initializer "smswire.preview_paths", before: :set_autoload_paths do |app|
+      options = app.config.smswire
+      development = ::Rails.env.development?
+      options.show_previews = development if options.show_previews.nil?
+      options.show_inbox = development if options.show_inbox.nil?
+      options.preview_paths ||= %w[test/messengers/previews spec/messengers/previews].map { |path| "#{app.root}/#{path}" }
+      app.config.paths.add "smswire/previews", with: options.preview_paths, autoload: true
+    end
+
+    # Runs after config/initializers so app settings win over defaults.
+    initializer "smswire.configure", after: :load_config_initializers do |app|
+      app.config.smswire.each { |key, value| Smswire.config.public_send(:"#{key}=", value) }
+      Smswire.config.default_provider ||= ENVIRONMENT_PROVIDERS[::Rails.env.to_sym]
+      Smswire.config.logger ||= ::Rails.logger
+    end
+
+    config.after_initialize do
+      require_relative "noticed_delivery_method" if defined?(::Noticed::DeliveryMethod)
+    end
+
+    initializer "smswire.log_subscriber" do
+      Smswire::LogSubscriber.attach_to :smswire
+    end
+
+    initializer "smswire.messenger" do |app|
+      ActiveSupport.on_load(:smswire) do
+        self.view_paths = ["#{::Rails.root}/app/views"]
+        extend ::AbstractController::Railties::RoutesHelpers.with(app.routes, false)
+        include app.routes.mounted_helpers
+      end
+    end
+  end
+end

data/lib/smswire/errors.rb

@@ -0,0 +1,59 @@
+module Smswire
+  class Error < StandardError; end
+
+  # Raised for missing or invalid configuration: no provider, unknown sender,
+  # missing credentials. Never retried.
+  class ConfigurationError < Error; end
+
+  # Raised when +text to:+ is given something that cannot produce a phone
+  # number. Raised while building the message so it surfaces in tests.
+  class UnresolvableRecipient < Error; end
+
+  # Raised when a provider callback fails signature verification.
+  class SignatureError < Error; end
+
+  # Base class for errors raised by provider adapters.
+  class DeliveryError < Error
+    attr_reader :provider, :provider_code, :http_status, :raw
+
+    def initialize(message = nil, provider: nil, provider_code: nil, http_status: nil, raw: nil)
+      super(message)
+      @provider = provider
+      @provider_code = provider_code
+      @http_status = http_status
+      @raw = raw
+    end
+  end
+
+  # Network failures, timeouts, and provider 5xx responses. Retried by
+  # Smswire::DeliveryJob and re-raised from +deliver_now+.
+  class TransientError < DeliveryError; end
+
+  # Provider rate limiting. Retried after +retry_after+ seconds when known.
+  class ThrottledError < TransientError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **options)
+      super(message, **options)
+      @retry_after = retry_after
+    end
+  end
+
+  # The provider refused the message and retrying will not help. The
+  # pipeline turns this into a +:failed+ result instead of raising.
+  #
+  # +reason+ is one of :invalid_number, :opted_out, :unroutable,
+  # :authentication, or :rejected.
+  class PermanentError < DeliveryError
+    attr_reader :reason
+
+    def initialize(message = nil, reason: :rejected, **options)
+      super(message, **options)
+      @reason = reason
+    end
+
+    def opted_out?
+      reason == :opted_out
+    end
+  end
+end

data/lib/smswire/http.rb

@@ -0,0 +1,65 @@
+require "net/http"
+require "openssl"
+require "uri"
+require "json"
+
+module Smswire
+  # Minimal HTTP client shared by provider adapters. Network failures are
+  # raised as Smswire::TransientError. Bodies are never logged.
+  module HTTP
+    NETWORK_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+      Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+      EOFError, IOError, SocketError, OpenSSL::SSL::SSLError
+    ].freeze
+
+    module_function
+
+    def post_form(url, pairs, basic_auth: nil, headers: {}, open_timeout: 5, read_timeout: 15, provider: nil)
+      uri = URI(url)
+      request = Net::HTTP::Post.new(uri, {"User-Agent" => "smswire/#{Smswire::VERSION}"}.merge(headers))
+      request.basic_auth(*basic_auth) if basic_auth
+      request.content_type = "application/x-www-form-urlencoded"
+      request.body = URI.encode_www_form(pairs)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout:, read_timeout:) do |http|
+        http.request(request)
+      end
+    rescue *NETWORK_ERRORS => error
+      raise TransientError.new("#{error.class}: #{error.message}", provider:)
+    end
+
+    def post_json(url, payload, headers: {}, open_timeout: 5, read_timeout: 15, provider: nil)
+      uri = URI(url)
+      request = Net::HTTP::Post.new(uri, {"User-Agent" => "smswire/#{Smswire::VERSION}",
+                                          "Accept" => "application/json"}.merge(headers))
+      request.content_type = "application/json"
+      request.body = JSON.generate(payload)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout:, read_timeout:) do |http|
+        http.request(request)
+      end
+    rescue *NETWORK_ERRORS => error
+      raise TransientError.new("#{error.class}: #{error.message}", provider:)
+    end
+
+    def get(url, basic_auth: nil, headers: {}, open_timeout: 5, read_timeout: 15, provider: nil)
+      uri = URI(url)
+      request = Net::HTTP::Get.new(uri, {"User-Agent" => "smswire/#{Smswire::VERSION}",
+                                         "Accept" => "application/json"}.merge(headers))
+      request.basic_auth(*basic_auth) if basic_auth
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout:, read_timeout:) do |http|
+        http.request(request)
+      end
+    rescue *NETWORK_ERRORS => error
+      raise TransientError.new("#{error.class}: #{error.message}", provider:)
+    end
+
+    def parse_json(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/smswire/inbound.rb

@@ -0,0 +1,11 @@
+module Smswire
+  # A received message as parsed by a provider adapter.
+  #
+  # +provider_keyword+ is true when the provider already handled an opt-out
+  # keyword and replied itself, as Twilio Advanced Opt-Out does.
+  Inbound = Data.define(:provider_id, :from, :to, :body, :messaging_service, :provider_keyword, :raw) do
+    def initialize(provider_id:, from:, to:, body:, messaging_service: nil, provider_keyword: false, raw: {})
+      super
+    end
+  end
+end

data/lib/smswire/inbound_handler.rb

@@ -0,0 +1,29 @@
+module Smswire
+  # Records an inbound message once, handles compliance keywords, and
+  # notifies observers. Shared by the webhook endpoint and the development
+  # inbox.
+  module InboundHandler
+    module_function
+
+    # Returns the new Smswire::InboundMessage, or nil for a repeated webhook.
+    def call(inbound, provider:)
+      payload = {provider:, provider_id: inbound.provider_id, from: inbound.from}
+      ActiveSupport::Notifications.instrument("inbound.smswire", payload) do
+        record = InboundMessage.receive(inbound, provider:)
+        payload[:duplicate] = record.nil?
+        if record
+          payload[:keyword] = Keywords.handle(record, inbound, provider:) if Smswire.config.enforce_consent
+          notify_observers(record)
+        end
+        record
+      end
+    end
+
+    def notify_observers(record)
+      Smswire.config.observers.each do |observer|
+        observer = observer.is_a?(String) ? observer.constantize : observer
+        observer.sms_received(record) if observer.respond_to?(:sms_received)
+      end
+    end
+  end
+end