smswire 0.0.1.pre → 0.1.0

data/lib/smswire/providers/vonage.rb

@@ -0,0 +1,193 @@
+require "bigdecimal"
+require "digest/md5"
+require "openssl"
+
+module Smswire
+  module Providers
+    # Vonage SMS API over REST. No SDK dependency.
+    #
+    #   Smswire.config.providers[:vonage] = {
+    #     api_key: "...", api_secret: "...",
+    #     signature_secret: "...",       # required to verify webhooks
+    #     signature_method: "sha256"     # md5hash (Vonage's default), md5, sha1, sha256, or sha512
+    #   }
+    #
+    # Set the dashboard webhook method to POST. Long messages are billed as
+    # several parts; the receipt keeps the first part's message id, so
+    # delivery receipts for later parts are acknowledged but not matched.
+    # Prices are recorded in the account currency, which the API does not name.
+    # Credentials fall back to Rails.application.credentials.vonage.
+    class Vonage < Base
+      API_URL = "https://rest.nexmo.com/sms/json".freeze
+      SIGNATURE_METHODS = %w[md5hash md5 sha1 sha256 sha512].freeze
+      SIGNATURE_TOLERANCE = 300
+
+      # Send response status codes.
+      PERMANENT_REASONS = {
+        "4" => :authentication,  # Invalid credentials
+        "14" => :authentication, # Invalid signature
+        "32" => :authentication, # Signature and API secret disallowed
+        "6" => :invalid_number,  # Invalid message (unrecognized number prefix)
+        "33" => :invalid_number, # Number de-activated
+        "7" => :unroutable,      # Number barred; may include opt-outs but is not specific to them
+        "29" => :unroutable      # Non-whitelisted destination (demo account)
+      }.freeze
+      THROTTLED_CODES = %w[1].freeze
+      TRANSIENT_CODES = %w[5].freeze
+
+      # Delivery receipt statuses.
+      STATUSES = {
+        "accepted" => :accepted, "buffered" => :sent, "delivered" => :delivered, "expired" => :undelivered,
+        "failed" => :undelivered, "rejected" => :failed, "unknown" => :sent
+      }.freeze
+
+      def deliver(message)
+        response = HTTP.post_form(API_URL, form_for(message), provider: name)
+        handle(response)
+      end
+
+      BALANCE_URL = "https://rest.nexmo.com/account/get-balance".freeze
+
+      def capabilities
+        Set[:status_callbacks, :inbound]
+      end
+
+      def verify_credentials!
+        query = URI.encode_www_form(api_key: credential(:api_key), api_secret: credential(:api_secret))
+        check_credentials_response(HTTP.get("#{BALANCE_URL}?#{query}", provider: name))
+      end
+
+      def form_for(message)
+        raise ConfigurationError, "Vonage requires a from number or sender id" if message.from.blank?
+
+        pairs = [
+          ["api_key", credential(:api_key)], ["api_secret", credential(:api_secret)],
+          ["to", message.to.delete_prefix("+")], ["from", message.from.delete_prefix("+")],
+          ["text", message.body.to_s], ["type", (message.encoding == :ucs2) ? "unicode" : "text"]
+        ]
+        pairs << ["ttl", (message.validity_period.to_i * 1000).to_s] if message.validity_period
+        if (callback = message.status_callback_url || options[:callback])
+          pairs << ["status-report-req", "1"] << ["callback", callback]
+        end
+        pairs
+      end
+
+      # Vonage signs webhook parameters as sorted "&key=value" pairs with
+      # "&" and "=" in values replaced by "_", then hashes with the
+      # signature secret. Timestamps older than five minutes are rejected.
+      def verify_signature!(request, url: nil)
+        params = request.request_parameters.to_h.transform_keys(&:to_s)
+        signature = params.delete("sig").to_s
+        raise SignatureError, "Missing Vonage sig parameter" if signature.empty?
+        if params["timestamp"].present? && (Time.now.to_i - params["timestamp"].to_i).abs > SIGNATURE_TOLERANCE
+          raise SignatureError, "Stale Vonage timestamp"
+        end
+
+        expected = self.class.signature(params, secret: signature_secret, method: signature_method)
+        return if ActiveSupport::SecurityUtils.secure_compare(expected.downcase, signature.downcase)
+
+        raise SignatureError, "Invalid Vonage signature"
+      end
+
+      def self.signature(params, secret:, method:)
+        data = params.sort.map { |key, value| "&#{key}=#{value.to_s.tr("&=", "__")}" }.join
+        if method == "md5hash"
+          Digest::MD5.hexdigest("#{data}#{secret}")
+        else
+          OpenSSL::HMAC.hexdigest(method, secret, data).upcase
+        end
+      end
+
+      def parse_status_callback(request)
+        params = request.request_parameters
+        return nil if params["status"].blank?
+
+        err_code = params["err-code"].to_s
+        StatusUpdate.new(
+          provider_id: params["messageId"],
+          status: STATUSES.fetch(params["status"].to_s, :sent),
+          error_code: (err_code unless err_code.empty? || err_code == "0"),
+          raw: params.to_h
+        )
+      end
+
+      def parse_inbound(request)
+        params = request.request_parameters
+        return nil unless params.key?("text") && params["msisdn"].present?
+
+        Inbound.new(
+          provider_id: params["messageId"],
+          from: international(params["msisdn"]),
+          to: international(params["to"]),
+          body: params["text"].to_s,
+          raw: params.to_h
+        )
+      end
+
+      private
+
+      def handle(response)
+        status = response.code.to_i
+        json = HTTP.parse_json(response.body)
+        raise TransientError.new("Vonage #{status}", provider: name, http_status: status) if status >= 500
+        if status == 429
+          raise ThrottledError.new("Vonage 429", provider: name, http_status: status)
+        end
+
+        parts = Array(json["messages"])
+        failed = parts.find { |part| part["status"].to_s != "0" }
+        return success(parts) if status.between?(200, 299) && parts.any? && failed.nil?
+
+        code = failed&.dig("status")&.to_s
+        detail = "Vonage #{status}#{" (#{code})" if code}: #{failed&.dig("error-text") || response.message}"
+        error_options = {provider: name, provider_code: code, http_status: status, raw: json}
+        if THROTTLED_CODES.include?(code)
+          raise ThrottledError.new(detail, **error_options)
+        elsif TRANSIENT_CODES.include?(code)
+          raise TransientError.new(detail, **error_options)
+        else
+          raise PermanentError.new(detail, reason: PERMANENT_REASONS.fetch(code, :rejected), **error_options)
+        end
+      end
+
+      def success(parts)
+        prices = parts.filter_map { |part| part["message-price"].presence }
+        receipt(
+          provider_id: parts.first["message-id"],
+          status: :accepted,
+          segments: parts.size,
+          price_amount: (prices.sum { |price| BigDecimal(price.to_s) } if prices.any?),
+          raw: {"messages" => parts}
+        )
+      end
+
+      def international(number)
+        number = number.to_s
+        number.match?(/\A\d+\z/) ? "+#{number}" : number
+      end
+
+      def signature_secret
+        credential(:signature_secret)
+      rescue ConfigurationError
+        raise SignatureError, "Set providers[:vonage][:signature_secret] to verify Vonage webhooks"
+      end
+
+      def signature_method
+        method = (options[:signature_method] || rails_credentials&.dig(:signature_method) || "md5hash").to_s
+        raise ConfigurationError, "Unknown Vonage signature_method #{method}" unless SIGNATURE_METHODS.include?(method)
+        method
+      end
+
+      def credential(key)
+        value = options[key] || rails_credentials&.dig(key)
+        raise ConfigurationError, "Missing Vonage #{key}" if value.blank?
+        value
+      end
+
+      def rails_credentials
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        ::Rails.application.credentials.vonage&.to_h&.symbolize_keys
+      end
+    end
+  end
+end

data/lib/smswire/providers.rb

@@ -0,0 +1,38 @@
+module Smswire
+  module Providers
+    @registry = {
+      test: "Smswire::Providers::Test",
+      log: "Smswire::Providers::Log",
+      null: "Smswire::Providers::Null",
+      twilio: "Smswire::Providers::Twilio",
+      telnyx: "Smswire::Providers::Telnyx",
+      vonage: "Smswire::Providers::Vonage"
+    }
+
+    class << self
+      # Register a custom adapter: Smswire::Providers.register(:acme, "AcmeProvider").
+      def register(name, klass)
+        @registry[name.to_sym] = klass
+      end
+
+      def registered
+        @registry.keys
+      end
+
+      def lookup(name)
+        klass = @registry.fetch(name.to_sym) do
+          raise ConfigurationError, "Unknown provider :#{name}. Registered: #{registered.join(", ")}"
+        end
+        klass.is_a?(String) ? klass.constantize : klass
+      end
+
+      def resolve(name = nil)
+        name ||= Smswire.config.default_provider
+        unless name
+          raise ConfigurationError, "No SMS provider configured. Set Smswire.config.default_provider."
+        end
+        lookup(name).new(Smswire.config.provider_options(name), name: name.to_sym)
+      end
+    end
+  end
+end

data/lib/smswire/quiet_hours.rb

@@ -0,0 +1,45 @@
+module Smswire
+  # Quiet-hour windows given as "HH:MM".."HH:MM" in the recipient's local
+  # time. A window whose start is after its end wraps past midnight. The
+  # start is inclusive and the end exclusive.
+  module QuietHours
+    FORMAT = /\A([01]?\d|2[0-3]):([0-5]\d)\z/
+
+    module_function
+
+    # Returns when sending may resume, or nil when +now+ is outside the window.
+    def resume_at(window, time_zone:, now: Time.current)
+      return nil if window.blank?
+
+      start_minute, end_minute = parse(window)
+      local = now.in_time_zone(time_zone)
+      minute = (local.hour * 60) + local.min
+      quiet =
+        if start_minute < end_minute
+          minute >= start_minute && minute < end_minute
+        else
+          minute >= start_minute || minute < end_minute
+        end
+      return nil unless quiet
+
+      resume = local.change(hour: end_minute / 60, min: end_minute % 60)
+      (resume > local) ? resume : resume.advance(days: 1)
+    end
+
+    def parse(window)
+      unless window.is_a?(Range)
+        raise ConfigurationError, "quiet_hours must be a Range like \"21:00\"..\"08:00\", got #{window.inspect}"
+      end
+      [window.begin, window.end].map do |value|
+        match = FORMAT.match(value.to_s) or raise ConfigurationError, "Invalid quiet_hours time #{value.inspect}"
+        (match[1].to_i * 60) + match[2].to_i
+      end
+    end
+
+    def time_zone_for(recipient)
+      zone = recipient&.time_zone
+      zone = ActiveSupport::TimeZone[zone] if zone.is_a?(String)
+      zone || Smswire.config.time_zone
+    end
+  end
+end

data/lib/smswire/rate_limit.rb

@@ -0,0 +1,27 @@
+module Smswire
+  # Per-recipient, per-category sliding-window limits counted from
+  # smswire_deliveries. Failed and suppressed deliveries do not count.
+  # Concurrent sends can briefly exceed the limit by the number of workers.
+  module RateLimit
+    COUNTED = %w[pending queued accepted sent delivered undelivered read].freeze
+
+    module_function
+
+    # Returns when the next send fits the window, or nil when it fits now.
+    def resume_at(message, rule, now: Time.current)
+      max = rule.fetch(:max)
+      per = rule.fetch(:per)
+      unless Smswire.config.persist_deliveries
+        raise ConfigurationError, "Rate limits require persist_deliveries"
+      end
+
+      recent = Delivery.where(to_number: message.to, category: message.category.to_s, status: COUNTED)
+        .where(Delivery.arel_table[:created_at].gt(now - per))
+      count = recent.count
+      return nil if count < max
+
+      oldest = recent.order(:created_at).offset(count - max).pick(:created_at)
+      oldest + per
+    end
+  end
+end

data/lib/smswire/receipt.rb

@@ -0,0 +1,11 @@
+module Smswire
+  # What a provider returns after accepting a message.
+  #
+  # +status+ uses the normalized vocabulary: :queued, :accepted, :sent,
+  # :delivered, :undelivered, :failed, :read.
+  Receipt = Data.define(:provider, :provider_id, :status, :segments, :price_amount, :price_currency, :raw) do
+    def initialize(provider:, provider_id: nil, status: :accepted, segments: nil, price_amount: nil, price_currency: nil, raw: nil)
+      super
+    end
+  end
+end

data/lib/smswire/recipient.rb

@@ -0,0 +1,38 @@
+module Smswire
+  # The resolved target of a message: the phone number as given, plus the
+  # originating record and its time zone when available.
+  Recipient = Data.define(:phone, :record, :time_zone) do
+    def initialize(phone:, record: nil, time_zone: nil)
+      super
+    end
+
+    # Resolution order: Recipient, String, the configured resolver, then
+    # +phone_number+ on the object.
+    def self.resolve(value)
+      case value
+      when Recipient
+        value
+      when String
+        raise UnresolvableRecipient, "Recipient phone number is blank" if value.blank?
+        new(phone: value)
+      when nil
+        raise UnresolvableRecipient, "No recipient given"
+      else
+        phone = phone_for(value)
+        if phone.blank?
+          raise UnresolvableRecipient, "Could not resolve a phone number from #{value.class.name}"
+        end
+        new(phone: phone.to_s, record: value, time_zone: (value.time_zone if value.respond_to?(:time_zone)))
+      end
+    end
+
+    def self.phone_for(value)
+      if (resolver = Smswire.config.recipient_resolver)
+        resolver.call(value)
+      elsif value.respond_to?(:phone_number)
+        value.phone_number
+      end
+    end
+    private_class_method :phone_for
+  end
+end

data/lib/smswire/result.rb

@@ -0,0 +1,40 @@
+module Smswire
+  # The outcome of running a message through the delivery pipeline.
+  #
+  # Statuses:
+  #   :accepted                    provider accepted the message
+  #   :failed                      provider permanently refused it (see +error+)
+  #   :rejected_invalid_number     recipient is not a valid E.164 number
+  #   :rejected_empty_body         no body and no media
+  #   :suppressed_by_interceptor   an interceptor cancelled delivery
+  #   :skipped                     the messenger action did not call +text+
+  #   :duplicate                   an identical message was sent inside the dedupe window
+  #   :rejected_opted_out          the recipient opted out in this consent scope
+  #   :rejected_no_consent         the category requires opt-in and there is none
+  #   :rejected_rate_limited       over the category rate limit, with exceed: :reject
+  #   :deferred_quiet_hours        inside quiet hours; re-enqueued for +resume_at+
+  #   :deferred_rate_limited       over the category rate limit; re-enqueued for +resume_at+
+  #
+  # +delivery+ is the Smswire::Delivery row when persistence is enabled.
+  Result = Data.define(:status, :message, :receipt, :error, :delivery, :resume_at) do
+    def initialize(status:, message: nil, receipt: nil, error: nil, delivery: nil, resume_at: nil)
+      super
+    end
+
+    def accepted? = status == :accepted
+
+    def failed? = status == :failed
+
+    def rejected? = status.to_s.start_with?("rejected_")
+
+    def suppressed? = status == :suppressed_by_interceptor
+
+    def skipped? = status == :skipped
+
+    def duplicate? = status == :duplicate
+
+    def deferred? = status.to_s.start_with?("deferred_")
+
+    def provider_id = receipt&.provider_id
+  end
+end

data/lib/smswire/rspec.rb

@@ -0,0 +1,133 @@
+require "smswire"
+require "rspec/expectations"
+
+module Smswire
+  # RSpec matchers. Load with +require "smswire/rspec"+.
+  #
+  #   expect { order.ship! }.to deliver_sms(to: "+15551234567", body: /shipped/)
+  #   expect { order.ship! }.to deliver_sms.exactly(2).times
+  #   expect { order.ship! }.to have_enqueued_sms(OrderMessenger, :shipped)
+  #
+  # +deliver_sms+ counts deliveries made during the block. Wrap the block
+  # in +perform_enqueued_jobs+ to include deliver_later.
+  module RSpec
+    module Matchers
+      def deliver_sms(**filters)
+        DeliverSms.new(filters)
+      end
+
+      def have_enqueued_sms(messenger = nil, action = nil, **filters)
+        HaveEnqueuedSms.new(messenger, action, filters)
+      end
+
+      module Counting
+        def exactly(count)
+          @expected_count = count
+          self
+        end
+
+        def once = exactly(1)
+
+        def twice = exactly(2)
+
+        def times = self
+
+        def supports_block_expectations? = true
+
+        private
+
+        def count_matches?(actual)
+          @expected_count ? actual == @expected_count : actual.positive?
+        end
+
+        def expectation
+          @expected_count ? "exactly #{@expected_count}" : "at least one"
+        end
+      end
+
+      class DeliverSms
+        include ::RSpec::Matchers::Composable
+        include Counting
+
+        def initialize(filters)
+          @filters = filters
+        end
+
+        def matches?(block)
+          before = Smswire::Testing.deliveries.size
+          block.call
+          @delivered = Smswire::Testing.deliveries.drop(before)
+          @matching = Smswire::Testing.match_deliveries(@delivered, **@filters)
+          count_matches?(@matching.size)
+        end
+
+        def failure_message
+          "expected #{expectation} SMS#{described} to be delivered, got #{@matching.size} " \
+            "(#{@delivered.size} delivered in total)"
+        end
+
+        def failure_message_when_negated
+          "expected no SMS#{described} to be delivered, got #{@matching.size}"
+        end
+
+        def description
+          "deliver #{expectation} SMS#{described}"
+        end
+
+        private
+
+        def described = Smswire::Testing.describe_filters(@filters)
+      end
+
+      class HaveEnqueuedSms
+        include ::RSpec::Matchers::Composable
+        include Counting
+
+        def initialize(messenger, action, filters)
+          @messenger = messenger
+          @action = action
+          @filters = filters
+        end
+
+        def matches?(block)
+          adapter = ActiveJob::Base.queue_adapter
+          unless adapter.respond_to?(:enqueued_jobs)
+            raise ArgumentError, "have_enqueued_sms requires the ActiveJob :test adapter"
+          end
+
+          before = adapter.enqueued_jobs.size
+          block.call
+          entries = Smswire::Testing.enqueued(adapter.enqueued_jobs.drop(before))
+          @matching = Smswire::Testing.match_enqueued(entries, messenger: @messenger, action: @action, **@filters)
+          count_matches?(@matching.size)
+        end
+
+        def failure_message
+          "expected #{expectation} #{label} to be enqueued, got #{@matching.size}"
+        end
+
+        def failure_message_when_negated
+          "expected no #{label} to be enqueued, got #{@matching.size}"
+        end
+
+        def description
+          "enqueue #{expectation} #{label}"
+        end
+
+        private
+
+        def label
+          name = [@messenger, @action].compact.join("#")
+          name.empty? ? "SMS" : name
+        end
+      end
+    end
+  end
+end
+
+if defined?(::RSpec::Core) && ::RSpec.respond_to?(:configure)
+  ::RSpec.configure do |config|
+    config.include Smswire::RSpec::Matchers
+    config.before { Smswire::Testing.clear! }
+  end
+end

data/lib/smswire/segments.rb

@@ -0,0 +1,81 @@
+module Smswire
+  # Encoding and segment calculation for SMS bodies.
+  #
+  # A body that fits the GSM 03.38 alphabet is sent as GSM-7: 160 units in
+  # one segment, 153 per segment when concatenated. Extension-table
+  # characters cost two units. Anything else is sent as UCS-2: 70 units in
+  # one segment, 67 per segment, where characters outside the Basic
+  # Multilingual Plane (most emoji) cost two units. Characters are never
+  # split across segments, so packing is greedy rather than a division.
+  module Segments
+    GSM_BASIC = Set.new(
+      "@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !\"#¤%&'()*+,-./0123456789:;<=>?" \
+      "¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà".chars
+    ).freeze
+    GSM_EXTENDED = Set.new("\f^{}\\[~]|€".chars).freeze
+
+    LIMITS = {
+      gsm7: {single: 160, multi: 153},
+      ucs2: {single: 70, multi: 67}
+    }.freeze
+
+    Analysis = Data.define(:encoding, :units, :segments) do
+      def gsm7? = encoding == :gsm7
+
+      def ucs2? = encoding == :ucs2
+
+      def encoding_label = gsm7? ? "GSM-7" : "UCS-2"
+
+      # Units left before the message needs another segment.
+      def remaining
+        limits = LIMITS.fetch(encoding)
+        capacity = (segments <= 1) ? limits[:single] : segments * limits[:multi]
+        [capacity - units, 0].max
+      end
+    end
+
+    module_function
+
+    def analyze(text)
+      chars = text.to_s.chars
+      encoding = gsm7?(chars) ? :gsm7 : :ucs2
+      costs = chars.map { |char| cost(char, encoding) }
+      units = costs.sum
+      Analysis.new(encoding:, units:, segments: count(costs, units, LIMITS.fetch(encoding)))
+    end
+
+    # Characters that force UCS-2 encoding, in order of appearance.
+    def non_gsm_characters(text)
+      text.to_s.chars.reject { |char| GSM_BASIC.include?(char) || GSM_EXTENDED.include?(char) }.uniq
+    end
+
+    def gsm7?(chars)
+      chars.all? { |char| GSM_BASIC.include?(char) || GSM_EXTENDED.include?(char) }
+    end
+
+    def cost(char, encoding)
+      if encoding == :gsm7
+        GSM_EXTENDED.include?(char) ? 2 : 1
+      else
+        (char.ord > 0xFFFF) ? 2 : 1
+      end
+    end
+
+    def count(costs, units, limits)
+      return 0 if units.zero?
+      return 1 if units <= limits[:single]
+
+      segments = 1
+      used = 0
+      costs.each do |cost|
+        if used + cost > limits[:multi]
+          segments += 1
+          used = cost
+        else
+          used += cost
+        end
+      end
+      segments
+    end
+  end
+end

data/lib/smswire/sender.rb

@@ -0,0 +1,27 @@
+module Smswire
+  # A from-number or messaging service, with the provider that owns it.
+  # +consent_scope+ names the consent program the sender belongs to.
+  Sender = Data.define(:number, :messaging_service, :provider, :consent_scope) do
+    def initialize(number: nil, messaging_service: nil, provider: nil, consent_scope: nil)
+      super
+    end
+
+    def self.resolve(value)
+      case value
+      when nil then new
+      when Sender then value
+      when String then new(number: value)
+      when Symbol
+        options = Smswire.config.senders[value] || Smswire.config.senders[value.to_s]
+        unless options
+          raise ConfigurationError, "Unknown sender :#{value}. Define it in Smswire.config.senders."
+        end
+        options = options.to_h.symbolize_keys
+        new(number: options[:number], messaging_service: options[:messaging_service],
+          provider: options[:provider]&.to_sym, consent_scope: options[:consent_scope]&.to_s)
+      else
+        raise ConfigurationError, "from: must be a phone number String or a sender Symbol, got #{value.class.name}"
+      end
+    end
+  end
+end

data/lib/smswire/status_handler.rb

@@ -0,0 +1,25 @@
+module Smswire
+  # Applies a parsed provider status update to its delivery and notifies
+  # observers. Shared by the webhook endpoints.
+  module StatusHandler
+    module_function
+
+    def call(update, provider:, delivery_id: nil)
+      payload = {provider:, provider_id: update.provider_id, status: update.status, error_code: update.error_code}
+      ActiveSupport::Notifications.instrument("status_update.smswire", payload) do
+        delivery = Delivery.apply_status_update(update, provider:, delivery_id:)
+        payload[:delivery_id] = delivery&.id
+        payload[:delivery_status] = delivery&.status
+        notify_observers(delivery, update) if delivery
+        delivery
+      end
+    end
+
+    def notify_observers(delivery, update)
+      Smswire.config.observers.each do |observer|
+        observer = observer.is_a?(String) ? observer.constantize : observer
+        observer.sms_status_updated(delivery, update) if observer.respond_to?(:sms_status_updated)
+      end
+    end
+  end
+end

data/lib/smswire/status_update.rb

@@ -0,0 +1,8 @@
+module Smswire
+  # A provider's report that a message changed status, parsed from a callback.
+  StatusUpdate = Data.define(:provider_id, :status, :error_code, :error_message, :raw) do
+    def initialize(provider_id:, status:, error_code: nil, error_message: nil, raw: {})
+      super
+    end
+  end
+end