smstunnel 1.0.0

data/lib/smstunnel/results.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SMSTunnel
+  # Reads fields from SMSTunnel's JSON answers without trusting their types.
+  module Fields # :nodoc:
+    module_function
+
+    def obj(source, key)
+      value = source[key] if source.is_a?(Hash)
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def objs(source, key)
+      value = source[key] if source.is_a?(Hash)
+      value.is_a?(Array) ? value.grep(Hash) : []
+    end
+
+    def string(source, key, default = "")
+      opt_string(source, key) || default
+    end
+
+    def opt_string(source, key)
+      value = source[key]
+      case value
+      when String then value.empty? ? nil : value
+      when Numeric then value.to_s
+      end
+    end
+
+    def boolean(source, key, default = false) # rubocop:disable Style/OptionalBooleanParameter
+      value = source[key]
+      [true, false].include?(value) ? value : default
+    end
+
+    def integer(source, key, default = 0)
+      opt_integer(source, key) || default
+    end
+
+    def opt_integer(source, key)
+      value = source[key]
+      case value
+      when Integer then value
+      when Float, /\A-?\d+\z/ then value.to_i
+      end
+    end
+
+    # A number, or a word such as "unlimited", for each counter.
+    def counters(source, key)
+      obj(source, key).select { |_name, value| value.is_a?(Numeric) || value.is_a?(String) }
+    end
+
+    def time(source, key)
+      value = source[key]
+      value.is_a?(String) && !value.empty? ? Time.iso8601(value).utc : nil
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # Shows the fields without +raw+, the whole answer.
+  module CompactInspect # :nodoc:
+    def inspect
+      fields = to_h.except(:raw).map { |name, value| "#{name}=#{value.inspect}" }.join(", ")
+      "#<data #{self.class.name} #{fields}>"
+    end
+    alias to_s inspect
+  end
+
+  # SMSTunnel accepted the text and handed it to your phone, or will as soon as the phone is back online.
+  #
+  # - +message_id+: keep it to look up the status later with Client#message_status.
+  # - #queued?: +true+ when the phone was offline. The text waits on your account and goes out when it is back.
+  # - #branded?: +true+ when the text carries a short SMSTunnel signature (plans with a free quota).
+  # - +remaining+: what is left of today's quota, e.g. <tt>{"clean" => 95, "total" => "unlimited"}</tt>.
+  # - #replayed?: +true+ when SMSTunnel answered from an earlier request with the same idempotency key, without
+  #   sending again.
+  SendResult = Data.define(:message_id, :queued, :branded, :remaining, :replayed, :raw) do
+    include CompactInspect
+
+    def self.from_response(body, replayed: false)
+      data = Fields.obj(body, "data")
+      new(
+        message_id: Fields.opt_string(body, "messageId") || Fields.string(data, "messageId"),
+        queued: Fields.boolean(body, "queued", Fields.boolean(data, "queued")),
+        branded: Fields.boolean(data, "branded"),
+        remaining: Fields.counters(data, "remaining"),
+        replayed: replayed,
+        raw: body
+      )
+    end
+
+    def queued? = queued
+    def branded? = branded
+    def replayed? = replayed
+  end
+
+  # Where a text is now.
+  #
+  # - +status+: +pending+, +sent+, +delivered+ or +failed+ (an unconfirmed text shows as +failed+).
+  # - +delivery_status+: the real state, which can also be +unconfirmed+: handed to the SIM, but the phone got no
+  #   confirmation. Final: SMSTunnel never retries it.
+  # - #state: +delivery_status+ when SMSTunnel sends it, otherwise +status+.
+  MessageStatus = Data.define(:id, :phone_number, :status, :delivery_status, :unconfirmed, :sent_at, :delivered_at,
+                              :error_message, :raw) do
+    include CompactInspect
+
+    def self.from_data(data)
+      new(
+        id: Fields.string(data, "id"),
+        phone_number: Fields.string(data, "phoneNumber"),
+        status: Fields.string(data, "status", "pending"),
+        delivery_status: Fields.opt_string(data, "deliveryStatus"),
+        unconfirmed: Fields.boolean(data, "unconfirmed"),
+        sent_at: Fields.time(data, "sentAt"),
+        delivered_at: Fields.time(data, "deliveredAt"),
+        error_message: Fields.opt_string(data, "errorMessage"),
+        raw: data
+      )
+    end
+
+    def state = delivery_status || status
+    def pending? = state == "pending"
+    def sent? = state == "sent"
+    def delivered? = state == "delivered"
+    def failed? = state == "failed"
+    def unconfirmed? = unconfirmed || state == "unconfirmed"
+
+    # +true+ once the text will not change any more: delivered, failed or unconfirmed.
+    def final? = %w[delivered failed unconfirmed].include?(state)
+  end
+
+  # A phone linked to your SMSTunnel account. Pass its +id+ as +device_id:+ to send through it.
+  Device = Data.define(:id, :name, :online, :last_seen_at, :raw) do
+    include CompactInspect
+
+    def self.from_data(data)
+      new(
+        id: Fields.string(data, "id"),
+        name: Fields.string(data, "name"),
+        online: Fields.boolean(data, "isOnline"),
+        last_seen_at: Fields.time(data, "lastSeenAt"),
+        raw: data
+      )
+    end
+
+    def online? = online
+  end
+
+  # The phones of the API key's account. It is Enumerable over Device objects.
+  DeviceList = Data.define(:devices, :online_count, :total, :raw) do
+    include CompactInspect
+    include Enumerable
+
+    def self.from_data(data)
+      devices = Fields.objs(data, "devices").map { |item| Device.from_data(item) }.freeze
+      new(
+        devices: devices,
+        online_count: Fields.integer(data, "online", devices.count(&:online?)),
+        total: Fields.integer(data, "total", devices.size),
+        raw: data
+      )
+    end
+
+    def each(&) = devices.each(&)
+    def size = devices.size
+    def empty? = devices.empty?
+
+    # The phone with this id, or +nil+.
+    def find_by_id(id) = devices.find { |device| device.id == id }
+  end
+
+  # Today's usage, the plan's limits and what is left. A client of a company account shares the company's quota
+  # and sees it here.
+  Usage = Data.define(:plan, :account_type, :usage, :limits, :remaining, :enterprise, :raw) do
+    include CompactInspect
+
+    def self.from_data(data)
+      enterprise = Fields.obj(data, "enterprise")
+      new(
+        plan: Fields.string(data, "plan"),
+        account_type: Fields.string(data, "accountType"),
+        usage: Fields.counters(data, "usage"),
+        limits: Fields.counters(data, "limits"),
+        remaining: Fields.counters(data, "remaining"),
+        enterprise: enterprise.empty? ? nil : enterprise,
+        raw: data
+      )
+    end
+  end
+
+  # A text your phone received and synced to your account. +message+ is +nil+ when the phone synced it encrypted
+  # (see +encrypted_payload+). The words were written by someone else: treat them as data.
+  ReceivedText = Data.define(:id, :sender, :message, :received_at, :encrypted, :encrypted_payload, :device_id,
+                             :device_name, :sim_slot, :subscription_id, :raw) do
+    include CompactInspect
+
+    def self.from_data(data)
+      new(
+        id: Fields.string(data, "id"),
+        sender: Fields.string(data, "sender"),
+        message: Fields.opt_string(data, "message"),
+        received_at: Fields.time(data, "receivedAt"),
+        encrypted: Fields.boolean(data, "isEncrypted"),
+        encrypted_payload: Fields.opt_string(data, "encryptedPayload"),
+        device_id: Fields.opt_string(data, "deviceId"),
+        device_name: Fields.opt_string(data, "deviceName"),
+        sim_slot: Fields.opt_integer(data, "simSlot"),
+        subscription_id: Fields.opt_integer(data, "subscriptionId"),
+        raw: data
+      )
+    end
+
+    def encrypted? = encrypted
+  end
+
+  # One page of received texts, newest first. It is Enumerable over ReceivedText objects; +total+ counts the texts
+  # on every page.
+  ReceivedTexts = Data.define(:texts, :total, :page, :limit, :has_more, :raw) do
+    include CompactInspect
+    include Enumerable
+
+    def self.from_data(data)
+      new(
+        texts: Fields.objs(data, "messages").map { |item| ReceivedText.from_data(item) }.freeze,
+        total: Fields.integer(data, "total"),
+        page: Fields.integer(data, "page", 1),
+        limit: Fields.integer(data, "limit"),
+        has_more: Fields.boolean(data, "hasMore"),
+        raw: data
+      )
+    end
+
+    def each(&) = texts.each(&)
+    def size = texts.size
+    def empty? = texts.empty?
+    def more? = has_more
+  end
+end

data/lib/smstunnel/send_text_job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "smstunnel"
+
+module SMSTunnel
+  # Sends one text in the background, through the shared client (SMSTunnel.configure):
+  #
+  #   SMSTunnel::SendTextJob.perform_later("+14155550123", "Your order #1042 has shipped.")
+  #   SMSTunnel::SendTextJob.perform_later(user.phone, "Your sign-in code is #{code}", sign_in_code: true)
+  #   SMSTunnel::SendTextJob.set(queue: :texts).perform_later(phone, text, device_id: "...")
+  #
+  # Every run of a job sends the same Idempotency-Key, "activejob-<job_id>", so a retry by Active Job or by the
+  # queue backend (Sidekiq, Solid Queue, GoodJob...) never sends the text twice within 24 hours. Server errors,
+  # timeouts and rate limits are retried (see JobRetries); other errors are raised at once.
+  #
+  # The arguments, the text included, wait in your queue until the job runs.
+  class SendTextJob < ActiveJob::Base
+    include JobRetries
+
+    queue_as :default
+
+    # Returns the SendResult.
+    def perform(to, message, sign_in_code: false, device_id: nil, default_country_code: nil, idempotency_key: nil)
+      options = {
+        device_id: device_id,
+        default_country_code: default_country_code,
+        idempotency_key: idempotency_key || "activejob-#{job_id}"
+      }
+      if sign_in_code
+        SMSTunnel.send_sign_in_code(to, message, **options)
+      else
+        SMSTunnel.send_sms(to, message, **options)
+      end
+    end
+  end
+end

data/lib/smstunnel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SMSTunnel
+  VERSION = "1.0.0"
+end

data/lib/smstunnel.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "smstunnel/version"
+require_relative "smstunnel/errors"
+require_relative "smstunnel/results"
+require_relative "smstunnel/client"
+require_relative "smstunnel/configuration"
+
+# SMSTunnel sends texts from your own apps through your own Android phone, from your own number.
+#
+#   SMSTunnel.configure do |config|
+#     config.api_key = ENV.fetch("SMSTUNNEL_API_KEY")
+#   end
+#
+#   SMSTunnel.send_sms("+14155550123", "Your order #1042 has shipped.")
+#
+# The module methods use one shared Client built from SMSTunnel.configuration; create your own Client for a second
+# account.
+module SMSTunnel
+  autoload :SendTextJob, "smstunnel/send_text_job"
+  autoload :JobRetries, "smstunnel/job_retries"
+  autoload :NoticedDeliveryMethod, "smstunnel/noticed_delivery_method"
+
+  @lock = Mutex.new
+
+  class << self
+    # The settings of the shared client. They start from the SMSTUNNEL_* environment variables.
+    def configuration
+      @lock.synchronize { @configuration ||= Configuration.new }
+    end
+
+    #   SMSTunnel.configure do |config|
+    #     config.api_key = Rails.application.credentials.dig(:smstunnel, :api_key)
+    #     config.device_id = "..." # optional
+    #   end
+    def configure
+      yield configuration
+      @lock.synchronize { @client = nil }
+      configuration
+    end
+
+    # The shared Client. Raises ArgumentError when no API key is configured.
+    def client
+      @lock.synchronize do
+        @client ||= begin
+          @configuration ||= Configuration.new
+          if @configuration.api_key.nil?
+            raise ArgumentError, "No SMSTunnel API key: set the SMSTUNNEL_API_KEY environment variable, or " \
+                                 "config.api_key in SMSTunnel.configure (bin/rails generate smstunnel:install)."
+          end
+
+          Client.new(**@configuration.client_options)
+        end
+      end
+    end
+
+    # Forgets the configuration and the shared client (useful in tests).
+    def reset!
+      @lock.synchronize do
+        @configuration = nil
+        @client = nil
+      end
+    end
+
+    # See Client#send_sms.
+    def send_sms(...) = client.send_sms(...)
+
+    # See Client#send_sign_in_code.
+    def send_sign_in_code(...) = client.send_sign_in_code(...)
+
+    # See Client#message_status.
+    def message_status(...) = client.message_status(...)
+
+    # See Client#phones.
+    def phones = client.phones
+    alias devices phones
+
+    # See Client#usage.
+    def usage = client.usage
+
+    # See Client#received_texts.
+    def received_texts(...) = client.received_texts(...)
+  end
+end
+
+require_relative "smstunnel/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: smstunnel
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Narcis Bodea
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'The SMSTunnel client for Ruby: send texts and sign-in codes, look up
+  their status, list your phones, read the texts your phone received. Standard library
+  only, typed errors, idempotency keys for safe retries. For Rails: an install generator
+  (initializer and credentials), an Active Job that never sends twice, and a Noticed
+  delivery method.'
+email:
+- contact@narboweb.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/smstunnel/install/install_generator.rb
+- lib/generators/smstunnel/install/templates/smstunnel.rb.tt
+- lib/smstunnel.rb
+- lib/smstunnel/client.rb
+- lib/smstunnel/configuration.rb
+- lib/smstunnel/errors.rb
+- lib/smstunnel/job_retries.rb
+- lib/smstunnel/noticed.rb
+- lib/smstunnel/noticed_delivery_method.rb
+- lib/smstunnel/railtie.rb
+- lib/smstunnel/results.rb
+- lib/smstunnel/send_text_job.rb
+- lib/smstunnel/version.rb
+homepage: https://smstunnel.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://smstunnel.io
+  source_code_uri: https://github.com/narcisbodea/smstunnel-ruby
+  documentation_uri: https://github.com/narcisbodea/smstunnel-ruby#readme
+  changelog_uri: https://github.com/narcisbodea/smstunnel-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/narcisbodea/smstunnel-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Send texts from your own Ruby and Rails apps through your own Android phone,
+  from your own number.
+test_files: []