smstunnel 1.0.0

data/lib/smstunnel/client.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module SMSTunnel
+  # Sends texts from your own apps through your own Android phone, from your own number.
+  #
+  #   client = SMSTunnel::Client.new(api_key: ENV.fetch("SMSTUNNEL_API_KEY"))
+  #   result = client.send_sms("+14155550123", "Your order #1042 has shipped.")
+  #   result.message_id
+  #
+  # Every call raises an APIError subclass when SMSTunnel answers with an error, and ConnectionError (TimeoutError)
+  # when no answer comes back. One call sends one text to one number; nothing is ever retried automatically. A
+  # client keeps no connection open between calls and is safe to share between threads.
+  class Client
+    DEFAULT_BASE_URL = "https://smstunnel.io"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    BASE_URL_FORMAT = %r{\Ahttps?://[^/\s?#]+(/[^\s?#]*)?\z}i
+    IDEMPOTENCY_KEY_FORMAT = /\A[\x20-\x7E]{1,255}\z/
+    USER_AGENT = "smstunnel-ruby/#{VERSION} (Ruby #{RUBY_VERSION})".freeze
+    NETWORK_ERRORS = [
+      SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError
+    ].freeze
+    private_constant :BASE_URL_FORMAT, :IDEMPOTENCY_KEY_FORMAT, :NETWORK_ERRORS
+
+    attr_reader :base_url, :timeout, :open_timeout, :device_id, :default_country_code
+
+    # - +api_key+: an API key from your SMSTunnel dashboard (Apps → Add an app). Keep it in your credentials or an
+    #   environment variable, never in your code.
+    # - +device_id+: send every text through this phone (Phones → copy its ID) unless a call names another one;
+    #   +nil+ lets SMSTunnel pick one of yours.
+    # - +default_country_code+: e.g. "+40". Completes numbers written without + or 00; a call can override it.
+    # - +base_url+: change it only for a test server.
+    # - +timeout+: seconds to wait for an answer; +open_timeout+: seconds to connect.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                   device_id: nil, default_country_code: nil)
+      @api_key = api_key.to_s.strip
+      if @api_key.empty?
+        raise ArgumentError,
+              "An SMSTunnel API key is required. Create one in your SMSTunnel dashboard: Apps → Add an app."
+      end
+
+      @base_url = base_url.to_s.strip.sub(%r{/+\z}, "")
+      unless BASE_URL_FORMAT.match?(@base_url)
+        raise ArgumentError, %(The SMSTunnel base URL must look like https://smstunnel.io (got "#{base_url}").)
+      end
+
+      @timeout = seconds(timeout, "timeout")
+      @open_timeout = seconds(open_timeout, "open_timeout")
+      @device_id = blank_to_nil(device_id)
+      @default_country_code = blank_to_nil(default_country_code)
+    end
+
+    # Sends one text to one number, from your phone. Returns a SendResult.
+    #
+    # - +to+: the number as a String, in international format: "+14155550123".
+    # - +message+: up to 1600 characters (10 joined SMS).
+    # - +device_id+: send through this phone instead of the client's default.
+    # - +default_country_code+: e.g. "+49", for a number written without + or 00. It always wins over the phone's own.
+    # - +idempotency_key+: up to 255 printable ASCII characters, e.g. "order-1042-shipped". A retry with the same key
+    #   within 24 hours gets the first answer back instead of a second text.
+    #
+    # Raises ArgumentError, before sending anything, when the number or the text is empty or the number is not a
+    # String.
+    def send_sms(to, message, device_id: nil, default_country_code: nil, idempotency_key: nil)
+      send_text("/api/v1/sms/send", to, message, device_id, default_country_code, idempotency_key)
+    end
+
+    # Sends a sign-in or verification code. The text must contain the code, 4 to 10 digits standing on their own
+    # ("Your sign-in code is 482913", or "123-456"); SMSTunnel refuses it otherwise (BadRequestError). Up to 320
+    # characters. It counts against the separate sign-in code quota. Same options as #send_sms.
+    def send_sign_in_code(to, message, device_id: nil, default_country_code: nil, idempotency_key: nil)
+      send_text("/api/v1/sms/send-2fa", to, message, device_id, default_country_code, idempotency_key)
+    end
+
+    # Where a text is now (a MessageStatus). Needs a key with the +sms:read+ permission (new keys have it).
+    # Raises NotFoundError when the key's account has no such text.
+    def message_status(message_id)
+      id = message_id.to_s.strip
+      raise ArgumentError, "The message id is empty." if id.empty?
+
+      body, = request(:get, "/api/v1/sms/status/#{URI.encode_uri_component(id)}")
+      MessageStatus.from_data(Fields.obj(body, "data"))
+    end
+
+    # The phones linked to the key's account, and which are online (a DeviceList).
+    def phones
+      body, = request(:get, "/api/v1/devices")
+      DeviceList.from_data(Fields.obj(body, "data"))
+    end
+    alias devices phones
+
+    # Today's usage, the plan's limits and what is left (a Usage).
+    def usage
+      body, = request(:get, "/api/v1/account/usage")
+      Usage.from_data(Fields.obj(body, "data"))
+    end
+
+    # Texts your phone received, newest first (a ReceivedTexts page).
+    #
+    # Needs a key you allowed to read received texts (+sms:inbox+, a separate opt-in per key: "Can also read
+    # received texts"); other keys get a PermissionError with +code+ PERMISSION_REQUIRED. The phone syncs only texts
+    # that arrive after syncing is turned on in the app.
+    #
+    # - +limit+: texts per page (default 50, at most 100); +page+: from 1.
+    # - +since+: only texts newer than this (a Time, Date or ISO 8601 String).
+    # - +phone+: only texts from this sender; +device_id+: only texts this phone received.
+    def received_texts(limit: nil, page: nil, since: nil, phone: nil, device_id: nil)
+      query = {}
+      query["limit"] = Integer(limit).to_s unless limit.nil?
+      query["page"] = Integer(page).to_s unless page.nil?
+      query["since"] = iso8601(since) unless since.nil?
+      query["phone"] = phone.to_s.strip if blank_to_nil(phone)
+      query["deviceId"] = device_id.to_s.strip if blank_to_nil(device_id)
+      body, = request(:get, "/api/v1/sms/received", query: query)
+      ReceivedTexts.from_data(Fields.obj(body, "data"))
+    end
+
+    def inspect
+      "#<SMSTunnel::Client base_url=#{base_url.inspect} device_id=#{device_id.inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def send_text(path, to, message, device_id, default_country_code, idempotency_key)
+      body = send_body(to, message, device_id, default_country_code)
+      key = idempotency_header(idempotency_key)
+      answer, headers = request(:post, path, body: body, idempotency_key: key)
+      SendResult.from_response(answer, replayed: headers["idempotent-replayed"].to_s.casecmp?("true"))
+    end
+
+    def send_body(to, message, device_id, default_country_code)
+      body = { "to" => recipient(to), "message" => text(message) }
+      device = blank_to_nil(device_id) || @device_id
+      body["deviceId"] = device if device
+      country_code = blank_to_nil(default_country_code) || @default_country_code
+      body["defaultCountryCode"] = country_code if country_code
+      body
+    end
+
+    def recipient(to)
+      unless to.respond_to?(:to_str)
+        raise ArgumentError, "The recipient number must be a String in international format, " \
+                             "e.g. \"+14155550123\" (got #{to.class})."
+      end
+      number = to.to_str.strip
+      raise ArgumentError, "The recipient number is empty." if number.empty?
+
+      number
+    end
+
+    def text(message)
+      raise ArgumentError, "The text must be a String." unless message.respond_to?(:to_str)
+      raise ArgumentError, "The text is empty." if message.to_str.strip.empty?
+
+      message.to_str
+    end
+
+    def idempotency_header(key)
+      return nil if key.nil?
+
+      value = key.to_s
+      return value if IDEMPOTENCY_KEY_FORMAT.match?(value)
+
+      raise ArgumentError,
+            "The idempotency key must be 1 to 255 printable ASCII characters (a UUID or \"order-1042-shipped\")."
+    end
+
+    def request(method, path, query: nil, body: nil, idempotency_key: nil)
+      uri = URI.parse(@base_url + path)
+      uri.query = URI.encode_www_form(query) if query && !query.empty?
+
+      http_request = (method == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
+      http_request["X-API-Key"] = @api_key
+      http_request["Accept"] = "application/json"
+      http_request["User-Agent"] = USER_AGENT
+      http_request["Idempotency-Key"] = idempotency_key if idempotency_key
+      if body
+        http_request["Content-Type"] = "application/json"
+        http_request.body = JSON.generate(body)
+      end
+
+      handle(perform(uri, http_request))
+    end
+
+    def perform(uri, http_request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      http.ssl_timeout = @open_timeout
+      http.max_retries = 0 # Net::HTTP never retries a POST anyway; GETs are not retried either.
+      http.start { |connection| connection.request(http_request) }
+    rescue Net::OpenTimeout => e
+      raise TimeoutError, "Could not reach SMSTunnel at #{origin}: no connection within #{@open_timeout} s " \
+                          "(#{e.class})."
+    rescue Timeout::Error => e
+      raise TimeoutError, "SMSTunnel at #{origin} did not answer within #{@timeout} s (#{e.class}). The request " \
+                          "may have arrived: retry a send only with the same idempotency key."
+    rescue *NETWORK_ERRORS => e
+      raise ConnectionError, "Could not reach SMSTunnel at #{origin}: #{e.message} (#{e.class})."
+    end
+
+    def handle(response)
+      status = response.code.to_i
+      headers = {}
+      response.each_header { |name, value| headers[name.downcase] = value }
+      body = decode(response.body)
+
+      raise redirect_error(status, body, headers) if (300..399).cover?(status)
+      raise APIError.from_response(status, body, headers) unless (200..299).cover?(status)
+      unless body.is_a?(Hash)
+        raise APIError.new("SMSTunnel answered with something that is not JSON.",
+                           status: status, body: body, headers: headers)
+      end
+      raise APIError.from_response(status, body, headers) if body["success"] == false
+
+      [body, headers]
+    end
+
+    def redirect_error(status, body, headers)
+      location = headers["location"]
+      message = if location
+                  "SMSTunnel answered with a redirect to #{location}. Set base_url to that address."
+                else
+                  "SMSTunnel answered with a redirect (#{status})."
+                end
+      APIError.new(message, status: status, body: body, headers: headers)
+    end
+
+    def decode(raw)
+      return nil if raw.nil?
+
+      body = raw.dup.force_encoding(Encoding::UTF_8)
+      return nil if body.strip.empty?
+
+      JSON.parse(body, freeze: true)
+    rescue JSON::ParserError
+      body
+    end
+
+    def iso8601(value)
+      case value
+      when String
+        raise ArgumentError, "since is empty." if value.strip.empty?
+
+        value.strip
+      else
+        raise ArgumentError, "since must be a Time, a Date or an ISO 8601 String." unless value.respond_to?(:to_time)
+
+        value.to_time.utc.iso8601(3)
+      end
+    end
+
+    def seconds(value, name)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ArgumentError, "#{name} must be a number of seconds above 0 (got #{value.inspect})."
+    end
+
+    def blank_to_nil(value)
+      return nil if value.nil?
+
+      text = value.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    def origin
+      uri = URI.parse(@base_url)
+      "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.port == uri.default_port}"
+    end
+  end
+end

data/lib/smstunnel/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SMSTunnel
+  # The settings behind SMSTunnel.client. Each one starts from an environment variable, when it is set:
+  #
+  # - +api_key+: +SMSTUNNEL_API_KEY+ (required). Keep it out of your code.
+  # - +device_id+: +SMSTUNNEL_DEVICE_ID+. Send through this phone; without it SMSTunnel picks one of yours.
+  # - +default_country_code+: +SMSTUNNEL_DEFAULT_COUNTRY_CODE+, e.g. "+40": completes numbers written without
+  #   + or 00.
+  # - +base_url+: +SMSTUNNEL_BASE_URL+, default https://smstunnel.io. Change it only for a test server.
+  # - +timeout+ (seconds for an answer, default 30) and +open_timeout+ (seconds to connect, default 10).
+  class Configuration
+    attr_accessor :api_key, :base_url, :device_id, :default_country_code, :timeout, :open_timeout
+
+    def initialize(env = ENV)
+      @api_key = presence(env["SMSTUNNEL_API_KEY"])
+      @base_url = presence(env["SMSTUNNEL_BASE_URL"]) || Client::DEFAULT_BASE_URL
+      @device_id = presence(env["SMSTUNNEL_DEVICE_ID"])
+      @default_country_code = presence(env["SMSTUNNEL_DEFAULT_COUNTRY_CODE"])
+      @timeout = Client::DEFAULT_TIMEOUT
+      @open_timeout = Client::DEFAULT_OPEN_TIMEOUT
+    end
+
+    # The keyword arguments for Client.new.
+    def client_options
+      {
+        api_key: api_key,
+        base_url: base_url,
+        device_id: device_id,
+        default_country_code: default_country_code,
+        timeout: timeout,
+        open_timeout: open_timeout
+      }
+    end
+
+    def inspect
+      "#<SMSTunnel::Configuration api_key=#{api_key ? "[set]" : "nil"} base_url=#{base_url.inspect} " \
+        "device_id=#{device_id.inspect} default_country_code=#{default_country_code.inspect}>"
+    end
+
+    private
+
+    def presence(value)
+      value = value.to_s.strip
+      value.empty? ? nil : value
+    end
+  end
+end

data/lib/smstunnel/errors.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SMSTunnel
+  # The base of every exception this gem raises when a call does not go through. Rescue it to handle them all.
+  class Error < StandardError; end
+
+  # SMSTunnel could not be reached at all: DNS, TLS, a refused connection. No answer came back.
+  class ConnectionError < Error; end
+
+  # No answer within the timeout. The request may have reached SMSTunnel, so a text may have gone out: retry a send
+  # only with the same idempotency key.
+  class TimeoutError < ConnectionError; end
+
+  # SMSTunnel answered, but with an error.
+  #
+  # - +status+: the HTTP status.
+  # - +code+: SMSTunnel's own code when it sends one, such as +PERMISSION_REQUIRED+ or +IDEMPOTENCY_KEY_REUSED+.
+  # - +message+: what went wrong, in SMSTunnel's words.
+  # - +body+: the decoded answer (a Hash), the raw text when it was not JSON, or +nil+ when it was empty.
+  # - +headers+: the response headers, names in lower case.
+  class APIError < Error
+    FALLBACK = "SMSTunnel returned error: %<status>s"
+    ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"', "&#39;" => "'", "&nbsp;" => " " }.freeze
+    private_constant :FALLBACK, :ENTITIES
+
+    attr_reader :status, :code, :body, :headers
+
+    def initialize(message = nil, status: nil, code: nil, body: nil, headers: {})
+      @status = status
+      @code = code
+      @body = body
+      @headers = headers.to_h.transform_keys { |name| name.to_s.downcase }.freeze
+      super(message || format(FALLBACK, status: status))
+    end
+
+    # With +PERMISSION_REQUIRED+: the permission the key lacks, such as +sms:inbox+.
+    def permission
+      value = body["permission"] if body.is_a?(Hash)
+      value.is_a?(String) ? value : nil
+    end
+
+    # Seconds to wait before trying again, when SMSTunnel says (the +Retry-After+ header of a 429 or 409), or +nil+.
+    def retry_after
+      value = headers["retry-after"].to_s.strip
+      return nil if value.empty?
+      return Float(value) if value.match?(/\A\d+(\.\d+)?\z/)
+
+      [Time.httpdate(value) - Time.now, 0.0].max
+    rescue ArgumentError
+      nil
+    end
+
+    class << self
+      # The exception that matches the status: BadRequestError (400, 422), AuthenticationError (401),
+      # PermissionError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx).
+      def from_response(status, body, headers = {})
+        error_class_for(status).new(message_of(body, status), status: status, code: code_of(body), body: body,
+                                                              headers: headers)
+      end
+
+      private
+
+      def error_class_for(status)
+        return ServerError if (500..599).cover?(status)
+
+        {
+          400 => BadRequestError, 401 => AuthenticationError, 403 => PermissionError, 404 => NotFoundError,
+          409 => ConflictError, 422 => BadRequestError, 429 => RateLimitError
+        }.fetch(status, APIError)
+      end
+
+      def message_of(body, status)
+        case body
+        when String then text_of(body) || format(FALLBACK, status: status)
+        when Hash then hash_message(body) || format(FALLBACK, status: status)
+        else format(FALLBACK, status: status)
+        end
+      end
+
+      # A proxy's error page, say: its words without the markup, at most 300 characters.
+      def text_of(body)
+        text = body.gsub(/<[^>]*>/, " ").gsub(/&(?:amp|lt|gt|quot|#39|nbsp);/, ENTITIES).gsub(/\s+/, " ").strip
+        text.empty? ? nil : text[0, 300]
+      end
+
+      def hash_message(body)
+        message = body["message"]
+        message = message.grep(String).join("; ") if message.is_a?(Array)
+        return message if message.is_a?(String) && !message.empty?
+
+        error = body["error"]
+        error.is_a?(String) && !error.empty? ? error : nil
+      end
+
+      def code_of(body)
+        code = body["code"] if body.is_a?(Hash)
+        code.is_a?(String) ? code : nil
+      end
+    end
+  end
+
+  # 400 or 422: SMSTunnel refused the request, for example a number it cannot read, a sign-in code text without a
+  # code (+No valid verification code found+), or an idempotency key reused for a different text
+  # (+IDEMPOTENCY_KEY_REUSED+). Fix the request; retrying it unchanged gets the same answer.
+  class BadRequestError < APIError; end
+
+  # 401: the API key is wrong, was deleted or expired, or its account is suspended. Check it in your SMSTunnel
+  # dashboard (Apps).
+  class AuthenticationError < APIError; end
+
+  # 403: the key is valid but may not do this. Either it lacks a permission (+code+ is +PERMISSION_REQUIRED+ and
+  # #permission names it, e.g. +sms:inbox+ for received texts), or the plan does not include the feature.
+  class PermissionError < APIError; end
+
+  # 404: no such text or phone for this key.
+  class NotFoundError < APIError; end
+
+  # 409: a request with the same idempotency key is still being processed (+IDEMPOTENCY_KEY_IN_PROGRESS+). Retry in
+  # a moment with the same key to get its result.
+  class ConflictError < APIError; end
+
+  # 429: too many requests (sending allows 30 a minute per key) or a daily limit is reached. Wait #retry_after
+  # seconds before trying again.
+  class RateLimitError < APIError; end
+
+  # 5xx: a problem on SMSTunnel's side. The text may have been created: retry a send only with the same idempotency
+  # key.
+  class ServerError < APIError; end
+end

data/lib/smstunnel/job_retries.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "smstunnel"
+
+module SMSTunnel
+  # The retry rules of SendTextJob and NoticedDeliveryMethod. Include it in your own Active Job classes too, but only
+  # in jobs whose sends carry an idempotency key, since a retry after a timeout or a 5xx must not send a text twice:
+  #
+  #   class OrderShippedTextJob < ApplicationJob
+  #     include SMSTunnel::JobRetries
+  #
+  #     def perform(order)
+  #       SMSTunnel.send_sms(order.phone, "Your order ##{order.number} has shipped.",
+  #                          idempotency_key: "order-#{order.id}-shipped")
+  #     end
+  #   end
+  #
+  # - ServerError (5xx) and ConnectionError (including TimeoutError): retried with growing waits.
+  # - ConflictError (409, the first request with the same key is still running): retried after 5 seconds.
+  # - RateLimitError (429): retried after SMSTunnel's Retry-After (60 seconds when it does not say).
+  #
+  # A job runs at most ATTEMPTS times; then the error is raised. Other errors are raised at once: a wrong key
+  # (AuthenticationError), a missing permission (PermissionError), a number SMSTunnel cannot read (BadRequestError).
+  module JobRetries
+    extend ActiveSupport::Concern
+
+    ATTEMPTS = 5
+
+    included do
+      retry_on SMSTunnel::ServerError, SMSTunnel::ConnectionError, wait: :polynomially_longer, attempts: ATTEMPTS
+      retry_on SMSTunnel::ConflictError, wait: 5, attempts: ATTEMPTS
+
+      rescue_from SMSTunnel::RateLimitError do |error|
+        raise error if executions >= ATTEMPTS
+
+        retry_job(wait: (error.retry_after || 60).clamp(1, 3600), error: error)
+      end
+    end
+  end
+end

data/lib/smstunnel/noticed.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Makes +deliver_by :smstunnel+ available in Noticed notifiers. Inside a Rails app the gem's Railtie does this for
+# you; elsewhere, +require "smstunnel/noticed"+ after Noticed is loaded.
+require_relative "noticed_delivery_method"
+
+module Noticed
+  module DeliveryMethods # :nodoc:
+    Smstunnel = SMSTunnel::NoticedDeliveryMethod unless const_defined?(:Smstunnel, false) && !autoload?(:Smstunnel)
+  end
+end

data/lib/smstunnel/noticed_delivery_method.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "smstunnel"
+
+begin
+  require "noticed"
+rescue LoadError
+  raise LoadError, 'SMSTunnel::NoticedDeliveryMethod needs the noticed gem: add `gem "noticed"` to your Gemfile.'
+end
+
+module SMSTunnel
+  # Delivers Noticed notifications as texts from your own phone, one text per recipient.
+  #
+  #   class OrderShippedNotifier < Noticed::Event
+  #     deliver_by :smstunnel do |config|
+  #       config.phone = -> { recipient.phone }
+  #       config.message = -> { "Your order ##{params[:order].number} has shipped." }
+  #     end
+  #   end
+  #
+  # Options (each one a value, a lambda run in the notification's context, or the name of a notifier method):
+  #
+  # - +phone+ (required): the recipient's number, a String in international format.
+  # - +message+ (required): the text.
+  # - +device_id+, +default_country_code+: as for Client#send_sms; they default to SMSTunnel.configure.
+  # - +sign_in_code+: +true+ sends the text as a sign-in code (Client#send_sign_in_code).
+  # - +api_key+: a different account's key than SMSTunnel.configure's.
+  # - +idempotency_key+: defaults to "noticed-<notification id>-<delivery method name>" ("noticed-<job id>" for
+  #   ephemeral notifications), so a retried delivery never sends the text twice.
+  # - +error_handler+: a lambda that gets the error when SMSTunnel refuses the text (400, 401, 403, 404), run in
+  #   the notification's context. Without it, the error is raised.
+  #
+  # Rate limits, server errors and timeouts are retried like SendTextJob (see JobRetries).
+  class NoticedDeliveryMethod < ::Noticed::DeliveryMethod
+    include JobRetries
+
+    required_options :phone, :message
+
+    def perform(delivery_method_name, notification, **options)
+      @delivery_method_name = delivery_method_name
+      super
+    end
+
+    def deliver
+      send_text
+    rescue BadRequestError, AuthenticationError, PermissionError, NotFoundError => e
+      handler = config[:error_handler]
+      raise unless handler
+
+      notification.instance_exec(e, &handler)
+    end
+
+    private
+
+    def send_text
+      options = {
+        device_id: evaluate_option(:device_id),
+        default_country_code: evaluate_option(:default_country_code),
+        idempotency_key: idempotency_key
+      }
+      if evaluate_option(:sign_in_code)
+        client.send_sign_in_code(phone, text, **options)
+      else
+        client.send_sms(phone, text, **options)
+      end
+    end
+
+    def phone
+      value = evaluate_option(:phone)
+      return value unless value.to_s.strip.empty?
+
+      raise ArgumentError, "deliver_by :smstunnel: the phone number is empty for #{recipient.class} " \
+                           "#{recipient.try(:id).inspect}. Skip such recipients with config.if = " \
+                           "-> { recipient.phone.present? }."
+    end
+
+    def text = evaluate_option(:message)
+
+    def idempotency_key
+      key = evaluate_option(:idempotency_key)
+      return key.to_s unless key.to_s.strip.empty?
+
+      if notification.respond_to?(:persisted?) && notification.persisted?
+        "noticed-#{notification.id}-#{@delivery_method_name}"
+      else
+        "noticed-#{job_id}"
+      end
+    end
+
+    def client
+      api_key = evaluate_option(:api_key)
+      return SMSTunnel.client if api_key.to_s.strip.empty?
+
+      Client.new(**SMSTunnel.configuration.client_options, api_key: api_key)
+    end
+  end
+end

data/lib/smstunnel/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SMSTunnel
+  # Loaded only inside a Rails app. It registers +deliver_by :smstunnel+ for Noticed without loading anything at
+  # boot: the delivery method is loaded the first time a notification uses it.
+  class Railtie < ::Rails::Railtie
+    initializer "smstunnel.noticed" do
+      delivery_methods = ::Noticed::DeliveryMethods if defined?(::Noticed::DeliveryMethods)
+      if delivery_methods && !delivery_methods.const_defined?(:Smstunnel, false)
+        delivery_methods.autoload(:Smstunnel, File.expand_path("noticed.rb", __dir__))
+      end
+    end
+  end
+end