smswire 0.0.1.pre → 0.1.0

data/lib/smswire/provider_contract.rb

@@ -0,0 +1,158 @@
+require "rack/mock"
+require "action_dispatch"
+
+module Smswire
+  # Minitest contract every provider adapter must pass. Include it in a
+  # test case that also has Smswire::TestHelper and WebMock, and define the
+  # hooks below. Tests for optional capabilities run only when the adapter
+  # declares them.
+  #
+  #   class AcmeProviderContractTest < ActiveSupport::TestCase
+  #     include Smswire::TestHelper
+  #     include Smswire::ProviderContract
+  #
+  #     def contract_provider_name = :acme
+  #     def contract_provider_options = {api_key: "test"}
+  #     def stub_contract_send(outcome, message) = ...       # WebMock stub; see OUTCOMES
+  #     def contract_status_request(provider_id:, status:, signed: true) = ...   # with :status_callbacks
+  #     def contract_inbound_request(from:, to:, body:, signed: true) = ...      # with :inbound
+  #   end
+  #
+  # +stub_contract_send+ must stub the provider API for +outcome+ and return
+  # the WebMock stub. For :success it should also match the message's
+  # recipient and body. +status+ is :delivered or :undelivered. Define
+  # +contract_reports_opt_outs?+ as false when the provider cannot report an
+  # opt-out when sending. Request
+  # hooks return an ActionDispatch::Request, built with +contract_request+.
+  module ProviderContract
+    OUTCOMES = %i[success invalid_number opted_out authentication throttled server_error timeout].freeze
+    STATUSES = %i[queued accepted sent delivered undelivered failed read].freeze
+    CAPABILITIES = %i[mms status_callbacks inbound messaging_services scheduling].freeze
+
+    # Return false when the provider has no send-time error that
+    # specifically means the recipient opted out. The suite then skips the
+    # :opted_out outcome rather than accept a guess.
+    def contract_reports_opt_outs? = true
+
+    # The message the suite sends. Override to use one of your messengers.
+    def contract_message
+      Message.new(to: "+14155552671", from: "+15005550006", body: "Smswire contract check", messenger: "ContractMessenger",
+        action: "check")
+    end
+
+    def contract_provider
+      Providers.lookup(contract_provider_name).new(contract_provider_options, name: contract_provider_name)
+    end
+
+    def contract_request(url, body: nil, params: nil, headers: {})
+      env = Rack::MockRequest.env_for(url, :method => "POST", :input => body || Rack::Utils.build_query(params || {}),
+        "CONTENT_TYPE" => body ? "application/json" : "application/x-www-form-urlencoded")
+      headers.each { |key, value| env["HTTP_#{key.upcase.tr("-", "_")}"] = value }
+      ActionDispatch::Request.new(env)
+    end
+
+    def test_contract_declares_known_capabilities
+      assert_empty contract_provider.capabilities.to_a - CAPABILITIES
+    end
+
+    def test_contract_delivers_and_returns_a_receipt
+      message = contract_message
+      stub = stub_contract_send(:success, message)
+      receipt = contract_provider.deliver(message)
+
+      assert_requested stub
+      assert_equal contract_provider_name, receipt.provider
+      assert receipt.provider_id.present?, "receipt needs the provider message id"
+      assert_includes STATUSES, receipt.status
+      assert(receipt.segments.nil? || receipt.segments.positive?)
+    end
+
+    def test_contract_delivers_through_the_pipeline
+      message = contract_message
+      stub_contract_send(:success, message)
+      providers = Smswire.config.providers.merge(contract_provider_name => contract_provider_options)
+      result = contract_with_config(default_provider: contract_provider_name, providers:) do
+        message.provider = contract_provider_name
+        Pipeline.call(message)
+      end
+
+      assert result.accepted?, "expected accepted, got #{result.status} #{result.error&.message}"
+      if Smswire.config.persist_deliveries
+        assert_equal result.provider_id, result.delivery.reload.provider_id
+        assert_equal contract_provider_name.to_s, result.delivery.provider
+      end
+    end
+
+    def test_contract_maps_permanent_errors_to_reasons
+      expected = {invalid_number: :invalid_number, opted_out: :opted_out, authentication: :authentication}
+      expected.delete(:opted_out) unless contract_reports_opt_outs?
+      expected.each do |outcome, reason|
+        message = contract_message
+        stub_contract_send(outcome, message)
+        error = assert_raises(PermanentError, "#{outcome} should be permanent") { contract_provider.deliver(message) }
+        assert_equal reason, error.reason, "#{outcome} should map to #{reason}"
+        assert_equal contract_provider_name, error.provider
+        WebMock.reset!
+      end
+    end
+
+    def test_contract_raises_retryable_errors
+      {throttled: ThrottledError, server_error: TransientError, timeout: TransientError}.each do |outcome, klass|
+        message = contract_message
+        stub_contract_send(outcome, message)
+        assert_raises(klass, "#{outcome} should raise #{klass}") { contract_provider.deliver(message) }
+        WebMock.reset!
+      end
+    end
+
+    def test_contract_parses_and_verifies_status_callbacks
+      skip "no :status_callbacks capability" unless contract_provider.capabilities.include?(:status_callbacks)
+
+      %i[delivered undelivered].each do |status|
+        request = contract_status_request(provider_id: "contract-#{status}", status:)
+        contract_provider.verify_signature!(request, url: request.original_url)
+        update = contract_provider.parse_status_callback(request)
+        assert_equal "contract-#{status}", update.provider_id
+        assert_equal status, update.status
+      end
+
+      forged = contract_status_request(provider_id: "contract-forged", status: :delivered, signed: false)
+      assert_raises(SignatureError) { contract_provider.verify_signature!(forged, url: forged.original_url) }
+    end
+
+    def test_contract_parses_and_verifies_inbound_messages
+      skip "no :inbound capability" unless contract_provider.capabilities.include?(:inbound)
+
+      request = contract_inbound_request(from: "+14155552671", to: "+15005550006", body: "STOP")
+      contract_provider.verify_signature!(request, url: request.original_url)
+      inbound = contract_provider.parse_inbound(request)
+      assert inbound.provider_id.present?
+      assert_equal ["+14155552671", "+15005550006", "STOP"], [inbound.from, inbound.to, inbound.body]
+      if contract_provider.capabilities.include?(:status_callbacks)
+        assert_nil contract_provider.parse_status_callback(request), "inbound messages must not parse as status updates"
+      end
+
+      forged = contract_inbound_request(from: "+14155552671", to: "+15005550006", body: "STOP", signed: false)
+      assert_raises(SignatureError) { contract_provider.verify_signature!(forged, url: forged.original_url) }
+    end
+
+    def test_contract_status_callbacks_are_not_inbound_messages
+      capabilities = contract_provider.capabilities
+      skip "needs both :status_callbacks and :inbound" unless capabilities.superset?(Set[:status_callbacks, :inbound])
+
+      request = contract_status_request(provider_id: "contract-status", status: :delivered)
+      assert_nil contract_provider.parse_inbound(request)
+    end
+
+    private
+
+    def contract_with_config(**overrides)
+      config = Smswire.config
+      previous = overrides.keys.to_h { |key| [key, config.public_send(key)] }
+      overrides.each { |key, value| config.public_send(:"#{key}=", value) }
+      yield
+    ensure
+      previous&.each { |key, value| config.public_send(:"#{key}=", value) }
+    end
+  end
+end

data/lib/smswire/providers/base.rb

@@ -0,0 +1,66 @@
+module Smswire
+  module Providers
+    # Adapter contract. Subclasses implement +deliver(message)+ and return a
+    # Smswire::Receipt, raising Smswire::TransientError,
+    # Smswire::ThrottledError, or Smswire::PermanentError on failure.
+    class Base
+      attr_reader :options, :name
+
+      def initialize(options = {}, name: nil)
+        @options = options.to_h.symbolize_keys
+        @name = name || self.class.name.demodulize.underscore.to_sym
+      end
+
+      def deliver(message)
+        raise NotImplementedError, "#{self.class.name} must implement #deliver"
+      end
+
+      def capabilities
+        Set.new
+      end
+
+      # Make one authenticated, read-only call to the provider. Returns true,
+      # raises ConfigurationError when credentials are rejected or missing,
+      # or TransientError when the provider cannot be reached. Returns nil
+      # for adapters that cannot check.
+      def verify_credentials!
+        nil
+      end
+
+      # Raise Smswire::SignatureError unless +request+ was signed by the
+      # provider. +url+ is the public URL the provider posted to.
+      def verify_signature!(request, url:)
+        raise NotImplementedError, "#{self.class.name} does not support callbacks"
+      end
+
+      # Return a Smswire::Inbound for an inbound message webhook.
+      def parse_inbound(request)
+        raise NotImplementedError, "#{self.class.name} does not support inbound messages"
+      end
+
+      # [body, content_type] to answer an inbound webhook with, or nil for 204.
+      def inbound_response
+        nil
+      end
+
+      # Return a Smswire::StatusUpdate for a status callback request.
+      def parse_status_callback(request)
+        raise NotImplementedError, "#{self.class.name} does not support status callbacks"
+      end
+
+      private
+
+      def check_credentials_response(response)
+        status = response.code.to_i
+        return true if status.between?(200, 299)
+        raise TransientError.new("#{name} returned #{status}", provider: name, http_status: status) if status >= 500
+
+        raise ConfigurationError, "#{name} rejected the configured credentials (HTTP #{status})"
+      end
+
+      def receipt(**attributes)
+        Receipt.new(provider: name, **attributes)
+      end
+    end
+  end
+end

data/lib/smswire/providers/log.rb

@@ -0,0 +1,23 @@
+require "securerandom"
+
+module Smswire
+  module Providers
+    # Writes messages, including the body, to Smswire.logger instead of
+    # sending them. The default provider in development.
+    class Log < Base
+      def verify_credentials! = true
+
+      def deliver(message)
+        analysis = message.analysis
+        sender = message.from || message.messaging_service || "(none)"
+        lines = ["[Smswire] SMS to #{message.to} from #{sender} via #{message.messenger}##{message.action}",
+          "[Smswire] #{analysis.segments} segment(s), #{analysis.encoding_label}, #{analysis.units} units"]
+        lines << "[Smswire] media: #{message.media_urls.join(", ")}" if message.media_urls.any?
+        lines << message.body.to_s
+        Smswire.logger.info(lines.join("\n"))
+
+        receipt(provider_id: "log-#{SecureRandom.hex(8)}", status: :accepted, segments: analysis.segments)
+      end
+    end
+  end
+end

data/lib/smswire/providers/null.rb

@@ -0,0 +1,12 @@
+module Smswire
+  module Providers
+    # Accepts and discards every message.
+    class Null < Base
+      def verify_credentials! = true
+
+      def deliver(message)
+        receipt(status: :accepted, segments: message.segments)
+      end
+    end
+  end
+end

data/lib/smswire/providers/telnyx.rb

@@ -0,0 +1,178 @@
+require "base64"
+require "bigdecimal"
+require "json"
+require "openssl"
+
+module Smswire
+  module Providers
+    # Telnyx Messaging API v2 over REST. No SDK dependency.
+    #
+    #   Smswire.config.providers[:telnyx] = {
+    #     api_key: "KEY...",
+    #     public_key: "base64 key from Mission Control > Keys & Credentials",
+    #     messaging_profile_id: "..."   # optional default; senders may set messaging_service
+    #   }
+    #
+    # A sender's +messaging_service+ is sent as +messaging_profile_id+.
+    # Credentials fall back to Rails.application.credentials.telnyx.
+    # Telnyx does not accept a validity period here, so it is ignored.
+    class Telnyx < Base
+      API_URL = "https://api.telnyx.com/v2/messages".freeze
+      SIGNATURE_TOLERANCE = 300
+      ED25519_SPKI_PREFIX = ["302a300506032b6570032100"].pack("H*").freeze
+
+      PERMANENT_REASONS = {
+        "40300" => :opted_out,       # Blocked: recipient replied STOP
+        "40310" => :invalid_number,  # Invalid 'to' address
+        "40012" => :invalid_number,  # Invalid destination number
+        "40001" => :unroutable,      # Not routable (landline or non-SMS)
+        "40305" => :rejected,        # Invalid 'from' address
+        "40013" => :rejected,        # Invalid source number
+        "40311" => :authentication,  # Invalid profile secret
+        "40313" => :authentication   # Missing profile secret
+      }.freeze
+      TRANSIENT_CODES = %w[40006 40008].freeze          # Recipient unavailable, undeliverable
+      THROTTLED_CODES = %w[40002 40011 40016 40018].freeze # Spam throttle and carrier throughput limits
+
+      STATUSES = {
+        "queued" => :queued, "sending" => :accepted, "sent" => :sent, "delivered" => :delivered,
+        "delivery_unconfirmed" => :sent, "sending_failed" => :failed, "delivery_failed" => :undelivered,
+        "expired" => :undelivered
+      }.freeze
+
+      def deliver(message)
+        response = HTTP.post_json(API_URL, payload_for(message),
+          headers: {"Authorization" => "Bearer #{credential(:api_key)}"}, provider: name)
+        handle(response)
+      end
+
+      BALANCE_URL = "https://api.telnyx.com/v2/balance".freeze
+
+      def capabilities
+        Set[:mms, :status_callbacks, :inbound, :messaging_services]
+      end
+
+      def verify_credentials!
+        check_credentials_response(HTTP.get(BALANCE_URL, headers: {"Authorization" => "Bearer #{credential(:api_key)}"}, provider: name))
+      end
+
+      def payload_for(message)
+        profile = message.messaging_service || options[:messaging_profile_id]
+        if message.from.blank? && profile.blank?
+          raise ConfigurationError, "Telnyx requires a from number or messaging_profile_id"
+        end
+
+        {
+          to: message.to,
+          from: message.from.presence,
+          messaging_profile_id: profile.presence,
+          text: message.body.presence,
+          media_urls: message.media_urls.presence,
+          webhook_url: message.status_callback_url || options[:webhook_url]
+        }.compact
+      end
+
+      # Ed25519 over "<telnyx-timestamp>|<raw body>", checked against the
+      # account public key, rejecting timestamps older than five minutes.
+      def verify_signature!(request, url: nil)
+        signature = request.headers["telnyx-signature-ed25519"].to_s
+        timestamp = request.headers["telnyx-timestamp"].to_s
+        raise SignatureError, "Missing Telnyx signature headers" if signature.empty? || timestamp.empty?
+        raise SignatureError, "Stale Telnyx timestamp" if (Time.now.to_i - timestamp.to_i).abs > SIGNATURE_TOLERANCE
+
+        verified = public_key.verify(nil, Base64.decode64(signature), "#{timestamp}|#{request.raw_post}")
+        raise SignatureError, "Invalid Telnyx signature" unless verified
+      rescue OpenSSL::PKey::PKeyError, ArgumentError
+        raise SignatureError, "Invalid Telnyx signature"
+      end
+
+      def parse_status_callback(request)
+        event_type, payload = event(request)
+        return nil unless %w[message.sent message.finalized].include?(event_type)
+
+        recipient = Array(payload["to"]).first || {}
+        error = Array(payload["errors"]).first || {}
+        StatusUpdate.new(
+          provider_id: payload["id"],
+          status: STATUSES.fetch(recipient["status"].to_s, :accepted),
+          error_code: error["code"]&.to_s,
+          error_message: error["title"] || error["detail"],
+          raw: payload
+        )
+      end
+
+      def parse_inbound(request)
+        event_type, payload = event(request)
+        return nil unless event_type == "message.received"
+
+        Inbound.new(
+          provider_id: payload["id"],
+          from: payload.dig("from", "phone_number"),
+          to: Array(payload["to"]).first&.dig("phone_number"),
+          body: payload["text"].to_s,
+          messaging_service: payload["messaging_profile_id"],
+          raw: payload
+        )
+      end
+
+      private
+
+      def handle(response)
+        status = response.code.to_i
+        json = HTTP.parse_json(response.body)
+        return success(json["data"] || {}) if status.between?(200, 299)
+
+        error = Array(json["errors"]).first || {}
+        code = error["code"]&.to_s
+        detail = "Telnyx #{status}#{" (#{code})" if code}: #{error["title"] || error["detail"] || response.message}"
+        error_options = {provider: name, provider_code: code, http_status: status, raw: json}
+
+        if status == 429 || THROTTLED_CODES.include?(code)
+          retry_after = response["Retry-After"]&.to_i
+          raise ThrottledError.new(detail, retry_after: retry_after&.positive? ? retry_after : nil, **error_options)
+        elsif status >= 500 || TRANSIENT_CODES.include?(code)
+          raise TransientError.new(detail, **error_options)
+        elsif status == 401 || (status == 403 && code.nil?)
+          raise PermanentError.new(detail, reason: :authentication, **error_options)
+        else
+          raise PermanentError.new(detail, reason: PERMANENT_REASONS.fetch(code, :rejected), **error_options)
+        end
+      end
+
+      def success(data)
+        recipient = Array(data["to"]).first || {}
+        cost = data["cost"] || {}
+        receipt(
+          provider_id: data["id"],
+          status: STATUSES.fetch(recipient["status"].to_s, :queued),
+          segments: data["parts"]&.to_i,
+          price_amount: (BigDecimal(cost["amount"].to_s) if cost["amount"].present?),
+          price_currency: cost["currency"],
+          raw: data
+        )
+      end
+
+      def event(request)
+        data = JSON.parse(request.raw_post.to_s)["data"] || {}
+        [data["event_type"], data["payload"] || {}]
+      rescue JSON::ParserError
+        [nil, {}]
+      end
+
+      def public_key
+        @public_key ||= OpenSSL::PKey.read(ED25519_SPKI_PREFIX + Base64.decode64(credential(:public_key)))
+      end
+
+      def credential(key)
+        value = options[key] || rails_credentials&.dig(key)
+        raise ConfigurationError, "Missing Telnyx #{key}" if value.blank?
+        value
+      end
+
+      def rails_credentials
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        ::Rails.application.credentials.telnyx&.to_h&.symbolize_keys
+      end
+    end
+  end
+end

data/lib/smswire/providers/test.rb

@@ -0,0 +1,59 @@
+require "securerandom"
+
+module Smswire
+  module Providers
+    # Records messages in memory. The default provider in the test
+    # environment.
+    #
+    #   Smswire::Providers::Test.deliveries  # => [#<Smswire::Message ...>]
+    #   Smswire::Providers::Test.fail_next(Smswire::PermanentError.new("nope", reason: :opted_out))
+    class Test < Base
+      @deliveries = []
+      @failures = []
+      @mutex = Mutex.new
+
+      class << self
+        attr_reader :mutex
+
+        def deliveries
+          mutex.synchronize { @deliveries.dup }
+        end
+
+        def record(message)
+          mutex.synchronize { @deliveries << message }
+        end
+
+        # Raise +error+ on the next delivery instead of recording it.
+        def fail_next(error)
+          mutex.synchronize { @failures << error }
+        end
+
+        def next_failure
+          mutex.synchronize { @failures.shift }
+        end
+
+        def clear!
+          mutex.synchronize do
+            @deliveries.clear
+            @failures.clear
+          end
+        end
+      end
+
+      def verify_credentials! = true
+
+      def deliver(message)
+        if (error = self.class.next_failure)
+          raise error
+        end
+
+        self.class.record(message)
+        receipt(provider_id: "SMtest#{SecureRandom.hex(12)}", status: :accepted, segments: message.segments)
+      end
+
+      def capabilities
+        Set[:mms]
+      end
+    end
+  end
+end

data/lib/smswire/providers/twilio.rb

@@ -0,0 +1,167 @@
+require "bigdecimal"
+require "base64"
+
+module Smswire
+  module Providers
+    # Twilio Programmable Messaging over the REST API. No SDK dependency.
+    #
+    #   Smswire.config.providers[:twilio] = {
+    #     account_sid: "AC...", auth_token: "...",
+    #     status_callback: "https://app.example.com/sms/status"  # optional
+    #   }
+    #
+    # Credentials fall back to Rails.application.credentials.twilio.
+    class Twilio < Base
+      API_BASE = "https://api.twilio.com/2010-04-01".freeze
+
+      PERMANENT_REASONS = {
+        21211 => :invalid_number,  # Invalid 'To' number
+        21214 => :invalid_number,  # 'To' number cannot be reached
+        21217 => :invalid_number,  # Phone number does not appear to be valid
+        21614 => :invalid_number,  # 'To' number is not a valid mobile number
+        21610 => :opted_out,       # Recipient replied STOP
+        21408 => :unroutable,      # Permission to send to this region not enabled
+        21612 => :unroutable,      # Cannot route to this number
+        21606 => :unroutable,      # 'From' number is not SMS capable
+        20003 => :authentication   # Authentication failed
+      }.freeze
+
+      STATUSES = {
+        "queued" => :queued, "scheduled" => :queued, "accepted" => :accepted,
+        "sending" => :accepted, "sent" => :sent, "delivered" => :delivered,
+        "undelivered" => :undelivered, "failed" => :failed, "read" => :read,
+        "receiving" => :accepted, "received" => :delivered, "canceled" => :failed
+      }.freeze
+
+      def deliver(message)
+        response = HTTP.post_form(messages_url, form_for(message), basic_auth: [account_sid, auth_token], provider: name)
+        handle(response)
+      end
+
+      def capabilities
+        Set[:mms, :status_callbacks, :inbound, :messaging_services]
+      end
+
+      def verify_credentials!
+        url = "#{options.fetch(:api_base, API_BASE)}/Accounts/#{account_sid}.json"
+        check_credentials_response(HTTP.get(url, basic_auth: [account_sid, auth_token], provider: name))
+      end
+
+      def form_for(message)
+        pairs = [["To", message.to]]
+        if message.messaging_service
+          pairs << ["MessagingServiceSid", message.messaging_service]
+        elsif message.from
+          pairs << ["From", message.from]
+        else
+          raise ConfigurationError, "Twilio requires a from number or messaging_service"
+        end
+        pairs << ["Body", message.body] if message.body.present?
+        message.media_urls.each { |url| pairs << ["MediaUrl", url] }
+        pairs << ["ValidityPeriod", message.validity_period.to_i.to_s] if message.validity_period
+        callback = message.status_callback_url || options[:status_callback]
+        pairs << ["StatusCallback", callback] if callback
+        pairs
+      end
+
+      # Twilio signs callbacks with HMAC-SHA1 over the full URL followed by
+      # each POST parameter's name and value, sorted by name.
+      def verify_signature!(request, url:)
+        signature = request.headers["X-Twilio-Signature"].to_s
+        data = url + request.request_parameters.sort.map { |key, value| "#{key}#{value}" }.join
+        expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA1", auth_token, data))
+        return if signature.present? && ActiveSupport::SecurityUtils.secure_compare(expected, signature)
+
+        raise SignatureError, "Invalid X-Twilio-Signature"
+      end
+
+      def parse_status_callback(request)
+        params = request.request_parameters
+        raw_status = (params["MessageStatus"] || params["SmsStatus"]).to_s
+        return nil if raw_status.empty? || raw_status == "received"
+
+        StatusUpdate.new(
+          provider_id: params["MessageSid"] || params["SmsSid"],
+          status: STATUSES.fetch(raw_status, :accepted),
+          error_code: params["ErrorCode"].presence,
+          error_message: params["ErrorMessage"].presence,
+          raw: params.to_h
+        )
+      end
+
+      def parse_inbound(request)
+        params = request.request_parameters
+        return nil unless params.key?("Body") && params["From"].present?
+
+        Inbound.new(
+          provider_id: params["MessageSid"] || params["SmsSid"],
+          from: params["From"],
+          to: params["To"],
+          body: params["Body"].to_s,
+          messaging_service: params["MessagingServiceSid"].presence,
+          provider_keyword: params["OptOutType"].present?,
+          raw: params.to_h
+        )
+      end
+
+      # Empty TwiML, so Twilio sends no reply of its own.
+      def inbound_response
+        ['<?xml version="1.0" encoding="UTF-8"?><Response></Response>', "text/xml"]
+      end
+
+      private
+
+      def handle(response)
+        status = response.code.to_i
+        json = HTTP.parse_json(response.body)
+        return success(json) if status.between?(200, 299)
+
+        code = json["code"]
+        detail = "Twilio #{status}#{" (#{code})" if code}: #{json["message"] || response.message}"
+        error_options = {provider: name, provider_code: code&.to_s, http_status: status, raw: json}
+
+        case status
+        when 429
+          retry_after = response["Retry-After"]&.to_i
+          raise ThrottledError.new(detail, retry_after: retry_after&.positive? ? retry_after : nil, **error_options)
+        when 500..599
+          raise TransientError.new(detail, **error_options)
+        when 401, 403
+          raise PermanentError.new(detail, reason: :authentication, **error_options)
+        else
+          raise PermanentError.new(detail, reason: PERMANENT_REASONS.fetch(code, :rejected), **error_options)
+        end
+      end
+
+      def success(json)
+        receipt(
+          provider_id: json["sid"],
+          status: STATUSES.fetch(json["status"].to_s, :accepted),
+          segments: json["num_segments"]&.to_i,
+          price_amount: (BigDecimal(json["price"].to_s).abs if json["price"].present?),
+          price_currency: json["price_unit"],
+          raw: json
+        )
+      end
+
+      def messages_url
+        "#{options.fetch(:api_base, API_BASE)}/Accounts/#{account_sid}/Messages.json"
+      end
+
+      def account_sid = credential(:account_sid)
+
+      def auth_token = credential(:auth_token)
+
+      def credential(key)
+        value = options[key] || rails_credentials&.dig(key)
+        raise ConfigurationError, "Missing Twilio #{key}" if value.blank?
+        value
+      end
+
+      def rails_credentials
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        ::Rails.application.credentials.twilio&.to_h&.symbolize_keys
+      end
+    end
+  end
+end