smswire 0.0.1.pre → 0.1.0

data/lib/smswire/interceptors/allowlist.rb

@@ -0,0 +1,36 @@
+module Smswire
+  module Interceptors
+    # Staging safety: only listed numbers receive messages.
+    #
+    #   Smswire.register_interceptor(
+    #     Smswire::Interceptors::Allowlist.new(numbers: ENV.fetch("SMS_ALLOWLIST", "").split(","))
+    #   )
+    #
+    # Other recipients are suppressed, or with +redirect_to:+ rerouted to
+    # that number with the original recipient prefixed to the body.
+    class Allowlist
+      attr_reader :numbers, :redirect_to
+
+      def initialize(numbers:, redirect_to: nil)
+        @numbers = Array(numbers).filter_map { |number| PhoneNumber.normalize(number.to_s.strip) }.to_set
+        @redirect_to = redirect_to && (PhoneNumber.normalize(redirect_to) or
+          raise ConfigurationError, "Invalid redirect_to number #{redirect_to.inspect}")
+      end
+
+      def allowed?(number)
+        numbers.include?(number)
+      end
+
+      def delivering_sms(message)
+        return if allowed?(message.to)
+
+        if redirect_to
+          message.body = "[to #{message.to}] #{message.body}"
+          message.to = redirect_to
+        else
+          message.cancel!
+        end
+      end
+    end
+  end
+end

data/lib/smswire/keyword_messenger.rb

@@ -0,0 +1,12 @@
+module Smswire
+  # Sends keyword auto-replies. Uses the :compliance category, which skips
+  # consent checks so the opt-out confirmation reaches an opted-out number.
+  class KeywordMessenger < Base
+    def reply(phone, kind, from: nil, messaging_service: nil, provider: nil)
+      body = Smswire.config.keyword_reply(kind) or return
+
+      text to: phone, body:, category: :compliance, from: (from unless messaging_service),
+        messaging_service:, provider: provider&.to_sym
+    end
+  end
+end

data/lib/smswire/keywords.rb

@@ -0,0 +1,51 @@
+module Smswire
+  # Detects STOP / START / HELP style keywords in inbound messages, updates
+  # consent, and sends the configured auto-reply.
+  #
+  # A keyword matches only when it is the whole message, ignoring case,
+  # spaces, and surrounding punctuation, so "Opt out." matches OPTOUT and
+  # "stop all" matches STOPALL. Free-text requests such as "please stop
+  # texting me" are recorded but not matched; see docs/guides/compliance.md.
+  module Keywords
+    STORED = {opt_out: "stop", opt_in: "start", help: "help"}.freeze
+
+    module_function
+
+    # Returns [kind, word] or nil.
+    def classify(body)
+      word = body.to_s.strip.gsub(/\A[^[:alnum:]]+|[^[:alnum:]]+\z/, "").gsub(/[[:space:]-]+/, "").upcase
+      return nil if word.empty?
+
+      Smswire.config.keywords.each do |kind, words|
+        return [kind.to_sym, word] if words.map { |candidate| candidate.upcase.delete(" -") }.include?(word)
+      end
+      nil
+    end
+
+    def handle(record, inbound, provider:)
+      kind, word = classify(record.body)
+      return nil unless kind
+
+      phone = record.from_number
+      scope = Consent.scope_for_sender(number: record.to_number, messaging_service: record.messaging_service)
+      case kind
+      when :opt_out
+        if word == "STOPALL" || Smswire.config.opt_out_all_scopes
+          Consent.opt_out_everywhere!(phone, source: :keyword, keyword: word)
+        else
+          Consent.opt_out!(phone, scope:, source: :keyword, keyword: word)
+        end
+      when :opt_in
+        Consent.opt_in!(phone, scope:, source: :keyword, keyword: word)
+      end
+
+      unless inbound.provider_keyword
+        KeywordMessenger.reply(phone, kind.to_s, from: record.to_number,
+          messaging_service: record.messaging_service, provider: provider.to_s).deliver_later
+      end
+
+      record.update!(keyword: STORED.fetch(kind), handled_at: Time.current)
+      kind
+    end
+  end
+end

data/lib/smswire/log_subscriber.rb

@@ -0,0 +1,57 @@
+module Smswire
+  # Logs deliveries, rejections, and status updates. Phone numbers are
+  # masked and bodies are never logged.
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def deliver(event)
+      payload = event.payload
+      route = "#{payload[:messenger]}##{payload[:action]} to #{mask(payload[:to])} via #{payload[:provider]}"
+      if (error = payload[:exception_object])
+        warn { "SMS #{route} raised #{error.class}: #{error.message} (#{event.duration.round(1)}ms)" }
+      else
+        info do
+          "SMS #{route}: #{payload[:status]} #{payload[:provider_id]} " \
+            "(#{payload[:segments]} segment(s), #{event.duration.round(1)}ms)"
+        end
+      end
+    end
+
+    def reject(event)
+      payload = event.payload
+      until_time = payload[:resume_at] ? " until #{payload[:resume_at].utc.iso8601}" : ""
+      info { "SMS #{payload[:messenger]}##{payload[:action]} to #{mask(payload[:to])} not sent: #{payload[:reason]}#{until_time}" }
+    end
+
+    def status_update(event)
+      payload = event.payload
+      if payload[:delivery_id]
+        info do
+          "SMS status #{payload[:provider]} #{payload[:provider_id]}: #{payload[:status]} " \
+            "(delivery #{payload[:delivery_id]} now #{payload[:delivery_status]})"
+        end
+      else
+        warn { "SMS status #{payload[:provider]} #{payload[:provider_id]}: #{payload[:status]} for unknown delivery" }
+      end
+    end
+
+    def inbound(event)
+      payload = event.payload
+      info do
+        keyword = payload[:keyword] ? " keyword #{payload[:keyword]}" : ""
+        "SMS received via #{payload[:provider]} from #{mask(payload[:from])}#{keyword}#{" (duplicate webhook)" if payload[:duplicate]}"
+      end
+    end
+
+    def logger
+      Smswire.logger
+    end
+
+    private
+
+    def mask(number)
+      number = number.to_s
+      return number if number.length < 8
+
+      "#{number[0, 2]}#{"*" * (number.length - 6)}#{number[-4..]}"
+    end
+  end
+end

data/lib/smswire/message.rb

@@ -0,0 +1,72 @@
+require "digest"
+
+module Smswire
+  # A single outbound SMS. Built by Smswire::Base#text and passed through
+  # the pipeline. Interceptors may change any attribute before delivery.
+  class Message
+    attr_accessor :to, :from, :body, :media_urls, :messaging_service, :provider,
+      :category, :metadata, :validity_period, :messenger, :action, :recipient, :consent_scope
+    attr_reader :raw_to
+
+    # Set by the pipeline when Smswire.config.callbacks_url is configured.
+    attr_accessor :status_callback_url
+    attr_writer :idempotency_key
+
+    def initialize(to:, body:, from: nil, media_urls: [], messaging_service: nil, provider: nil,
+      category: nil, metadata: {}, validity_period: nil, idempotency_key: nil,
+      messenger: nil, action: nil, recipient: nil, consent_scope: nil)
+      @to = to
+      @raw_to = to
+      @from = from
+      @body = body
+      @media_urls = Array(media_urls)
+      @messaging_service = messaging_service
+      @provider = provider&.to_sym
+      @category = (category || Smswire.config.default_category)&.to_sym
+      @metadata = metadata || {}
+      @validity_period = validity_period
+      @idempotency_key = idempotency_key
+      @messenger = messenger
+      @action = action&.to_s
+      @recipient = recipient
+      @consent_scope = (consent_scope || "default").to_s
+      @perform_deliveries = true
+    end
+
+    def perform_deliveries?
+      @perform_deliveries
+    end
+
+    def cancel!
+      @perform_deliveries = false
+    end
+
+    def analysis
+      Segments.analyze(body)
+    end
+
+    def segments = analysis.segments
+
+    def encoding = analysis.encoding
+
+    def idempotency_key
+      @idempotency_key || Digest::SHA256.hexdigest([messenger, action, to, body].join("\u0000"))[0, 32]
+    end
+
+    # Fix the key to the current content, so interceptors that rewrite the
+    # body do not change which message this is.
+    def lock_idempotency_key!
+      @idempotency_key = idempotency_key
+    end
+
+    # Attributes safe to log or instrument. Never includes the body.
+    def to_log_h
+      {messenger:, action:, to:, from:, messaging_service:, provider:, category:,
+       segments:, encoding:, media_count: media_urls.size}
+    end
+
+    def inspect
+      "#<#{self.class.name} #{messenger}##{action} to=#{to.inspect} segments=#{segments} encoding=#{encoding}>"
+    end
+  end
+end

data/lib/smswire/message_delivery.rb

@@ -0,0 +1,69 @@
+require "delegate"
+
+module Smswire
+  # A lazy handle on a messenger action, like ActionMailer::MessageDelivery.
+  # The action runs on first access to the message, on +deliver_now+, or
+  # inside the job for +deliver_later+.
+  class MessageDelivery < Delegator
+    def initialize(messenger_class, action, args: [], kwargs: {}, params: {})
+      @messenger_class = messenger_class
+      @action = action
+      @args = args
+      @kwargs = kwargs
+      @params = params
+      @processed_messenger = nil
+    end
+
+    def __getobj__
+      processed_messenger.message
+    end
+
+    def __setobj__(_object)
+      raise NotImplementedError, "MessageDelivery cannot be reassigned"
+    end
+
+    def message
+      __getobj__
+    end
+
+    def processed?
+      !@processed_messenger.nil?
+    end
+
+    # Run the pipeline now and return a Smswire::Result. A deferred result
+    # (quiet hours or rate limit) enqueues the action again for +resume_at+,
+    # so arguments must then be serializable by ActiveJob.
+    def deliver_now
+      message = processed_messenger.message
+      return Result.new(status: :skipped) if message.nil?
+
+      result = Pipeline.call(message)
+      enqueue(wait_until: result.resume_at) if result.deferred? && result.resume_at
+      result
+    end
+
+    # Enqueue Smswire::DeliveryJob. The action runs again inside the job,
+    # so arguments and params must be serializable by ActiveJob.
+    def deliver_later(wait: nil, wait_until: nil, queue: nil, priority: nil)
+      if processed?
+        raise Error, "#{@messenger_class.name}##{@action} was accessed before deliver_later. " \
+          "Changes made to the message would be lost; call deliver_later without reading it first."
+      end
+
+      enqueue(wait:, wait_until:, queue:, priority:)
+    end
+
+    private
+
+    def enqueue(**options)
+      DeliveryJob.set(options.compact).perform_later(@messenger_class.name, @action.to_s, @params, @args, @kwargs)
+    end
+
+    def processed_messenger
+      @processed_messenger ||= @messenger_class.new.tap do |messenger|
+        messenger.params = @params
+        messenger.process(@action, *@args, **@kwargs)
+      end
+    end
+  end
+end

data/lib/smswire/noticed_delivery_method.rb

@@ -0,0 +1,54 @@
+# Loaded by Smswire::Engine when Noticed is present.
+module Noticed
+  module DeliveryMethods
+    # Sends a Noticed notification through a Smswire messenger, so
+    # templates, consent, quiet hours, deduplication, persistence, retries,
+    # and status tracking all apply.
+    #
+    #   class OrderShippedNotifier < Noticed::Event
+    #     deliver_by :smswire do |config|
+    #       config.messenger = "OrderMessenger"
+    #       config.action = :shipped
+    #       # Optional:
+    #       # config.args   = -> { [recipient] }                # default
+    #       # config.kwargs = -> { {} }
+    #       # config.params = -> { {order: record} }            # default: the event params
+    #       # config.sms_queue, config.sms_priority             # for Smswire::DeliveryJob
+    #       # config.wait, config.queue, config.if, ...         # Noticed's own job options
+    #     end
+    #   end
+    #
+    # The messenger receives the event params plus +notification+, +record+,
+    # and +recipient+. Each Smswire::Delivery records the Noticed
+    # notification and event ids in its metadata.
+    class Smswire < DeliveryMethod
+      required_options :messenger, :action
+
+      def deliver
+        messenger = fetch_constant(:messenger)
+        action = evaluate_option(:action).to_sym
+        args = evaluate_option(:args) || [recipient]
+        kwargs = evaluate_option(:kwargs) || {}
+
+        ::Smswire::MessageDelivery.new(messenger, action, args: Array(args), kwargs:, params: messenger_params)
+          .deliver_later(**job_options)
+      end
+
+      private
+
+      def messenger_params
+        base = evaluate_option(:params) || event.params || {}
+        base.to_h.symbolize_keys.merge(
+          notification:, record: event.record, recipient:,
+          smswire_metadata: {"noticed_notification_id" => notification.id, "noticed_event_id" => event.id}
+        )
+      end
+
+      # Noticed reads wait, wait_until, queue, and priority for its own job,
+      # which already applies any delay, so Smswire's job takes separate keys.
+      def job_options
+        {queue: evaluate_option(:sms_queue), priority: evaluate_option(:sms_priority)}.compact
+      end
+    end
+  end
+end

data/lib/smswire/parameterized_messenger.rb

@@ -0,0 +1,24 @@
+module Smswire
+  # Returned by Smswire::Base.with(params). Actions called on it build a
+  # MessageDelivery whose messenger instance sees +params+.
+  class ParameterizedMessenger
+    def initialize(messenger, params)
+      @messenger = messenger
+      @params = params
+    end
+
+    def respond_to_missing?(name, include_all = false)
+      @messenger.action_methods.include?(name.to_s) || super
+    end
+
+    private
+
+    def method_missing(name, *args, **kwargs, &block)
+      if @messenger.action_methods.include?(name.to_s)
+        MessageDelivery.new(@messenger, name, args:, kwargs:, params: @params)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/smswire/phone_number.rb

@@ -0,0 +1,65 @@
+module Smswire
+  # E.164 normalization.
+  #
+  # With phonelib loaded (or +phone_validator = :phonelib+) any region's
+  # national format is supported. The built-in fallback accepts
+  # international numbers written with + or 00, and national numbers for
+  # North American Numbering Plan regions.
+  module PhoneNumber
+    E164 = /\A\+[1-9]\d{6,14}\z/
+    NANP = /\A\+1[2-9]\d{2}[2-9]\d{6}\z/
+    NANP_REGIONS = %w[US CA AG AI AS BB BM BS DM DO GD GU JM KN KY LC MP MS PR SX TC TT VC VG VI].freeze
+    SEPARATORS = /[\s\-.()\/]/
+
+    module_function
+
+    # Returns the E.164 string, or nil when the input is not a valid number.
+    def normalize(raw, region: Smswire.config.default_region)
+      return nil if raw.blank?
+
+      if use_phonelib?
+        parsed = ::Phonelib.parse(raw.to_s, region)
+        parsed.valid? ? parsed.e164 : nil
+      else
+        fallback(raw.to_s, region.to_s.upcase)
+      end
+    end
+
+    def valid?(raw, **options)
+      !normalize(raw, **options).nil?
+    end
+
+    def use_phonelib?
+      case Smswire.config.phone_validator
+      when :e164 then false
+      when :phonelib
+        require "phonelib" unless defined?(::Phonelib)
+        true
+      else
+        defined?(::Phonelib) ? true : false
+      end
+    end
+
+    def fallback(raw, region)
+      compact = raw.strip.gsub(SEPARATORS, "")
+      return nil unless compact.match?(/\A\+?\d+\z/)
+
+      candidate =
+        if compact.start_with?("+")
+          compact
+        elsif compact.start_with?("00")
+          "+#{compact.delete_prefix("00")}"
+        elsif NANP_REGIONS.include?(region)
+          case compact.length
+          when 10 then "+1#{compact}"
+          when 11 then compact.start_with?("1") ? "+#{compact}" : nil
+          end
+        end
+
+      return nil unless candidate&.match?(E164)
+      return nil if candidate.start_with?("+1") && !candidate.match?(NANP)
+
+      candidate
+    end
+  end
+end

data/lib/smswire/pipeline.rb

@@ -0,0 +1,114 @@
+module Smswire
+  # Runs a message through normalize, validate, claim, intercept, send,
+  # record, and observe.
+  #
+  # Returns a Smswire::Result. Permanent provider errors become a :failed
+  # result. Transient errors and configuration errors propagate so the
+  # caller (or Smswire::DeliveryJob) can retry or fail loudly. When
+  # persistence is enabled, each claimed message has a Smswire::Delivery row
+  # that a retry reuses, so a message is never recorded twice.
+  class Pipeline
+    def self.call(message)
+      new(message).call
+    end
+
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+
+    def call
+      normalized = PhoneNumber.normalize(message.to)
+      return reject(:rejected_invalid_number) unless normalized
+      message.to = normalized
+
+      return reject(:rejected_empty_body) if message.body.blank? && message.media_urls.empty?
+
+      rule = Smswire.config.category_options(message.category)
+      if (status = consent_rejection(rule))
+        return reject(status)
+      end
+      if (resume_at = QuietHours.resume_at(rule[:quiet_hours], time_zone: QuietHours.time_zone_for(message.recipient)))
+        return defer(:deferred_quiet_hours, resume_at)
+      end
+      if rule[:rate_limit] && (resume_at = RateLimit.resume_at(message, rule[:rate_limit]))
+        return reject(:rejected_rate_limited) if rule[:rate_limit][:exceed]&.to_sym == :reject
+        return defer(:deferred_rate_limited, resume_at)
+      end
+
+      provider = Providers.resolve(message.provider)
+      message.lock_idempotency_key!
+
+      delivery = nil
+      if Smswire.config.persist_deliveries
+        delivery = Delivery.claim_for(message, provider: provider.name)
+        return reject(:duplicate) unless delivery
+        message.status_callback_url ||= Callbacks.status_url(provider.name, delivery) if provider.capabilities.include?(:status_callbacks)
+      end
+
+      run_interceptors
+      unless message.perform_deliveries?
+        delivery&.record_suppression!(message)
+        return finish(Result.new(status: :suppressed_by_interceptor, message:, delivery:))
+      end
+
+      deliver(provider, delivery)
+    end
+
+    private
+
+    def deliver(provider, delivery)
+      payload = message.to_log_h.merge(provider: provider.name, delivery_id: delivery&.id)
+      receipt = ActiveSupport::Notifications.instrument("deliver.smswire", payload) do
+        provider.deliver(message).tap do |r|
+          payload[:provider_id] = r.provider_id
+          payload[:status] = r.status
+        end
+      end
+      delivery&.record_receipt!(receipt, message)
+      status = (receipt.status == :failed) ? :failed : :accepted
+      finish(Result.new(status:, message:, receipt:, delivery:))
+    rescue PermanentError => error
+      delivery&.record_failure!(error, message)
+      if error.opted_out? && Smswire.config.enforce_consent
+        Consent.opt_out!(message.to, scope: message.consent_scope, source: :carrier)
+      end
+      finish(Result.new(status: :failed, message:, error:, delivery:))
+    rescue TransientError => error
+      delivery&.release!(error)
+      raise
+    end
+
+    def consent_rejection(rule)
+      return nil if rule[:consent] == :none || !Smswire.config.enforce_consent
+
+      status = Consent.status_for(message.to, scope: message.consent_scope)
+      return :rejected_opted_out if status == "opted_out"
+      :rejected_no_consent if rule[:consent] == :require_opted_in && status != "opted_in"
+    end
+
+    def defer(status, resume_at)
+      ActiveSupport::Notifications.instrument("reject.smswire", message.to_log_h.merge(reason: status, resume_at:))
+      finish(Result.new(status:, message:, resume_at:))
+    end
+
+    def reject(status)
+      ActiveSupport::Notifications.instrument("reject.smswire", message.to_log_h.merge(reason: status))
+      finish(Result.new(status:, message:))
+    end
+
+    def finish(result)
+      Smswire.config.observers.each { |observer| resolve(observer).delivered_sms(result) }
+      result
+    end
+
+    def run_interceptors
+      Smswire.config.interceptors.each { |interceptor| resolve(interceptor).delivering_sms(message) }
+    end
+
+    def resolve(hook)
+      hook.is_a?(String) ? hook.constantize : hook
+    end
+  end
+end

data/lib/smswire/preview.rb

@@ -0,0 +1,54 @@
+require "active_support/core_ext/class/subclasses"
+
+module Smswire
+  # Previews for messengers, like ActionMailer::Preview. Put them in
+  # test/messengers/previews (or spec/messengers/previews) and open
+  # <mount>/previews in development.
+  #
+  #   class OrderMessengerPreview < Smswire::Preview
+  #     def shipped
+  #       OrderMessenger.with(order: Order.first).shipped(User.first)
+  #     end
+  #   end
+  #
+  # Each public method returns a MessageDelivery. Nothing is sent.
+  class Preview
+    class << self
+      def all
+        load_previews
+        descendants.reject { |preview| preview.name.nil? }.sort_by(&:preview_name)
+      end
+
+      def find(preview_name)
+        all.find { |preview| preview.preview_name == preview_name }
+      end
+
+      def preview_name
+        name.delete_suffix("Preview").underscore
+      end
+
+      def messages
+        public_instance_methods(false).map(&:to_s).sort
+      end
+
+      def message_exists?(name)
+        messages.include?(name.to_s)
+      end
+
+      # Runs the preview method and returns the built Smswire::Message, or
+      # nil when the action did not call +text+. Interceptors are not run.
+      def call(name)
+        delivery = new.public_send(name)
+        delivery.respond_to?(:message) ? delivery.message : delivery
+      end
+
+      private
+
+      def load_previews
+        Smswire.config.preview_paths.each do |path|
+          Dir["#{path}/**/*_preview.rb"].sort.each { |file| require file }
+        end
+      end
+    end
+  end
+end