clicksend 1.0.0 → 1.1.0

data/lib/clicksend/testing/payloads.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Clicksend
+  module Testing
+    # Builds ClickSend-shaped JSON responses for FakeAPI.
+    # @api private
+    module Payloads
+      BASE_URL = "https://rest.clicksend.com"
+      USER_ID = 1
+      SUBACCOUNT_ID = 1
+      ERRORS = {
+        400 => ["BAD_REQUEST", "Bad request."],
+        401 => ["UNAUTHORIZED", "Authorization failed."],
+        403 => ["FORBIDDEN", "Forbidden."],
+        404 => ["NOT_FOUND", "Resource not found."],
+        405 => ["METHOD_NOT_ALLOWED", "Method not allowed."],
+        429 => ["HTTP_TOO_MANY_REQUESTS", "Too many attempts."],
+        500 => ["INTERNAL_SERVER_ERROR", "Internal server error."]
+      }.freeze
+      LIMITS = Page::LIMITS
+
+      module_function
+
+      # @return [Clicksend::Transport::Response]
+      def respond(status, body, headers = {})
+        Transport::Response.new(status: status, headers: {"content-type" => "application/json"}.merge(headers).freeze, body: JSON.generate(body))
+      end
+
+      def ok(message, data)
+        respond(200, {"http_code" => 200, "response_code" => "SUCCESS", "response_msg" => message, "data" => data})
+      end
+
+      def error(status, response_code = nil, response_msg = nil, headers = {})
+        code, msg = ERRORS.fetch(status, ["ERROR", "Simulated HTTP #{status}."])
+        respond(status, {"http_code" => status, "response_code" => response_code || code, "response_msg" => response_msg || msg, "data" => nil}, headers)
+      end
+
+      # ClickSend's pagination envelope. Out-of-range +limit+ and +page+ values
+      # are clamped (ClickSend's handling of them is undocumented). An empty
+      # list has +last_page+ 0, as observed live.
+      def page(items, path, query, message)
+        limit = (Integer(query["limit"], 10, exception: false) || LIMITS.min).clamp(LIMITS.min, LIMITS.max)
+        number = [Integer(query["page"], 10, exception: false) || 1, 1].max
+        last = (items.size + limit - 1) / limit
+        slice = items[(number - 1) * limit, limit] || []
+        first = (number - 1) * limit + 1 unless slice.empty?
+        ok(message, {
+          "total" => items.size, "per_page" => limit, "current_page" => number, "last_page" => last,
+          "next_page_url" => ("#{BASE_URL}#{path}?page=#{number + 1}" if number < last),
+          "prev_page_url" => ("#{BASE_URL}#{path}?page=#{number - 1}" if number > 1),
+          "from" => first, "to" => (first + slice.size - 1 if first), "data" => slice
+        })
+      end
+
+      # An estimate (one part per 160 characters), not ClickSend's rule, which
+      # depends on the encoding and on concatenation headers.
+      def parts(body)
+        [(body.length + 159) / 160, 1].max
+      end
+
+      def accepted(message, id, now, price)
+        parts = parts(message["body"])
+        {
+          "direction" => "out", "date" => now.to_i, "to" => message["to"], "body" => message["body"],
+          "from" => message["from"], "schedule" => Integer(message["schedule"], exception: false) || now.to_i,
+          "message_id" => id, "message_parts" => parts, "message_price" => format("%.4f", Rational(price) * parts),
+          "from_email" => message["from_email"], "list_id" => message["list_id"],
+          "custom_string" => message["custom_string"] || "", "contact_id" => nil, "user_id" => USER_ID,
+          "subaccount_id" => SUBACCOUNT_ID, "is_shared_system_number" => false, "country" => message["country"],
+          "carrier" => "", "status" => "SUCCESS"
+        }.freeze
+      end
+
+      # The minimal shape ClickSend returns for a message it did not accept.
+      def rejected(message, id, status)
+        {
+          "to" => message["to"], "body" => message["body"], "from" => message["from"], "schedule" => "",
+          "message_id" => id, "custom_string" => message["custom_string"] || "", "is_shared_system_number" => false,
+          "status" => status
+        }
+      end
+
+      def currency(name)
+        {"currency_name_short" => name}
+      end
+    end
+  end
+end

data/lib/clicksend/testing/records.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Clicksend
+  module Testing
+    # A message the FakeAPI accepted (per-message status "SUCCESS"), as
+    # submitted. +to+ is nil for a message sent to a contact list
+    # (+list_id+); +scheduled_at+ is the (UTC) time it was scheduled for, or
+    # nil; +sent_at+ is the (UTC) time the fake accepted it.
+    SentMessage = Data.define(:message_id, :to, :from, :body, :custom_string, :list_id, :scheduled_at, :country, :sent_at)
+
+    # Raised when test code given to the FakeAPI (a #stub block, or the
+    # +clock:+) raises a StandardError or ScriptError, i.e. has a bug. It is
+    # deliberately not a StandardError, so the client does not report it as a
+    # ClickSend failure (connection error, retry, "ambiguous" send): a typo in
+    # a stub must fail the test, not satisfy it. Other exceptions (Ctrl-C,
+    # timeouts, assertion failures) are never converted.
+    class StubError < Exception # rubocop:disable Lint/InheritException
+    end
+
+    # A request the FakeAPI received, recorded whatever its outcome.
+    #
+    # +http_method+ is a lower-case Symbol; +query+ has String keys and values, as
+    # ClickSend would receive them; +body+ is the parsed JSON (deep-frozen), or
+    # nil. Headers are never recorded: they carry the credentials.
+    Request = Data.define(:http_method, :path, :query, :body)
+  end
+end

data/lib/clicksend/testing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "uri"
+require_relative "../clicksend"
+require_relative "testing/records"
+require_relative "testing/payloads"
+require_relative "testing/failure"
+require_relative "testing/fake_api"
+
+module Clicksend
+  # Test support: an in-memory ClickSend. Not loaded by +require "clicksend"+.
+  #
+  #   require "clicksend/testing"
+  #
+  # Clicksend::Testing::FakeAPI is a *transport*, so the code under test uses a
+  # real Clicksend::Client: argument validation, error mapping, retry and
+  # ambiguity rules and models are the production code paths. Only the HTTP
+  # exchange is replaced. It does no I/O and sends nothing.
+  #
+  # An RSpec example. The application code sends one-time codes. When a send
+  # is ambiguous it never sends again; it reports the outcome as unknown (and
+  # might hand it to a reconciliation job):
+  #
+  #   class OtpSender
+  #     def initialize(sms:) = @sms = sms
+  #
+  #     def call(phone:, code:, ref:)
+  #       @sms.deliver(to: phone, body: "Your code is #{code}", custom_string: ref)
+  #       :sent
+  #     rescue Clicksend::AmbiguousRequestError
+  #       :unknown
+  #     end
+  #   end
+  #
+  #   require "clicksend/testing"
+  #
+  #   RSpec.describe OtpSender do
+  #     let(:fake) { Clicksend::Testing::FakeAPI.new }
+  #     let(:sender) { OtpSender.new(sms: fake.client.sms) }
+  #
+  #     it "sends the code" do
+  #       expect(sender.call(phone: "+61411111111", code: "481516", ref: "otp:42")).to eq(:sent)
+  #       expect(fake.sent_messages.map { |m| [m.to, m.custom_string] }).to eq([["+61411111111", "otp:42"]])
+  #     end
+  #
+  #     it "surfaces a rejected number" do
+  #       fake.reject(to: "+61400000000", status: "INVALID_RECIPIENT")
+  #       expect { sender.call(phone: "+61400000000", code: "1", ref: "otp:43") }.to raise_error(Clicksend::MessageRejected)
+  #     end
+  #
+  #     # Both ambiguous cases must lead to the same, safe behaviour.
+  #     [true, false].each do |processed|
+  #       it "never sends twice when the outcome is unknown (processed: #{processed})" do
+  #         fake.fail_next(:timeout, processed: processed, path: "/v3/sms/send")
+  #
+  #         expect(sender.call(phone: "+61411111111", code: "481516", ref: "otp:42")).to eq(:unknown)
+  #         expect(fake.requests.count { |r| r.path == "/v3/sms/send" }).to eq(1)
+  #         expect(fake.sent_messages.size).to eq(processed ? 1 : 0)
+  #       end
+  #     end
+  #
+  #     it "reads delivery receipts" do
+  #       message = fake.client.sms.deliver(to: "+61411111111", body: "Hi")
+  #       fake.add_receipt(for: fake.sent_messages.last, status_code: 301, error_text: "Expired")
+  #
+  #       expect(fake.client.sms.receipt(message.message_id)).to be_failed
+  #     end
+  #   end
+  #
+  # History is not served (see FakeAPI). To test a reconciliation step, stub
+  # it with the rows the scenario needs, for example none:
+  #
+  #   fake.stub(:get, "/v3/sms/history") do |_request|
+  #     {"data" => {"total" => 0, "per_page" => 15, "current_page" => 1, "last_page" => 0, "data" => []}}
+  #   end
+  #
+  # It also works as a development "dry run" transport, which is why the
+  # client has no +dry_run:+ flag; nothing leaves the process:
+  #
+  #   client = Clicksend::Client.new(username: "dev", api_key: "dev", transport: Clicksend::Testing::FakeAPI.new)
+  #
+  # A FakeAPI keeps every request in memory until #reset!, so a long-running
+  # process should reset it from time to time.
+  module Testing
+  end
+end

data/lib/clicksend/version.rb

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

data/lib/clicksend/webhook.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Clicksend
+  # Parses delivery receipts and inbound SMS that ClickSend pushes to your URL.
+  # Pure functions over params your web framework has already decoded; no I/O.
+  #
+  # *Experimental*: ClickSend's current docs define no push payload, and no
+  # real push has been captured for this gem yet. This API may change in a
+  # minor release.
+  #
+  # ClickSend pushes through automation rules with the +URL+ action. Inbound
+  # rules POST a form (the default), GET with a query string, or POST JSON, by
+  # the rule's +webhook_type+; ClickSend does not document the JSON field
+  # names, and this assumes they are the same. Receipt pushes are form-encoded
+  # according to the archived v3 docs. The field names come from the poll
+  # schemas (+sms_receipt+, +inbound_sms+), which match the archived push
+  # docs. According to those, pushes also carry +user_id+ and, on receipts,
+  # +status+ ("Delivered"/"Undelivered"); those stay in +raw+.
+  #
+  # ClickSend documents no signing or authentication for pushes: no HMAC,
+  # signature or secret, and no current list of source IP addresses (archived
+  # help pages once listed some; they can't be checked today, so don't
+  # allowlist by IP). Treat anyone who knows the URL as able to forge one, so:
+  # - put an unguessable secret in the URL path and compare it in constant time
+  #   (it will appear in access logs: restrict who reads them);
+  # - use HTTPS;
+  # - treat the event as a hint; a receipt can probably be confirmed with
+  #   <tt>client.sms.receipt(event.message_id)</tt> (not yet verified for
+  #   accounts with only URL rules);
+  # - process idempotently: several matching rules may each push, and (per the
+  #   archived docs) a non-200 is retried every 10 minutes, 10 times. Key inbound
+  #   messages on +message_id+, and receipts on +message_id+ and +status_code+:
+  #   non-final codes (200, 300) mean one message can get several receipts;
+  # - answer 200 quickly and do the work in a job.
+  #
+  # Prefer one URL per rule type with #parse_receipt / #parse_inbound; #parse
+  # guesses the type from the fields present.
+  #
+  # Pass the body params, not params merged with route params, so your secret
+  # does not end up in +raw+. +raw+ is the payload with String keys, minus
+  # Rails' "controller", "action" and "format", frozen.
+  #
+  # Rails (route: <tt>post "clicksend/:secret/receipts", to: "clicksend#receipt"</tt>):
+  #
+  #   def receipt
+  #     secret = Rails.application.credentials.clicksend_webhook_secret
+  #     return head(:not_found) unless ActiveSupport::SecurityUtils.secure_compare(params[:secret].to_s, secret)
+  #
+  #     receipt = Clicksend::Webhook.parse_receipt(request.request_parameters)
+  #     ConfirmReceiptJob.perform_later(receipt.message_id, receipt.status_code) # idempotent on both
+  #     head :ok
+  #   rescue Clicksend::Webhook::InvalidPayload
+  #     head :bad_request
+  #   end
+  #
+  # Rails' +params+ (ActionController::Parameters) is also accepted: the gem
+  # calls +to_unsafe_h+, which is safe here because only known fields are read
+  # into frozen models (nothing is mass-assigned).
+  #
+  # Rack / Sinatra (use +request.GET+ for a +get+ inbound rule, or
+  # <tt>JSON.parse(request.body.read)</tt> for +json+):
+  #
+  #   post "/clicksend/:secret/inbound" do
+  #     halt 404 unless Rack::Utils.secure_compare(params["secret"].to_s, ENV.fetch("CLICKSEND_WEBHOOK_SECRET"))
+  #     message = Clicksend::Webhook.parse_inbound(request.POST)
+  #     InboundJob.perform_async(message.message_id, message.raw)
+  #     200
+  #   rescue Clicksend::Webhook::InvalidPayload
+  #     400
+  #   end
+  #
+  # Because the endpoint is unauthenticated, payloads with more than
+  # MAX_FIELDS keys, a key or String value over MAX_BYTES bytes, a value that
+  # is not a scalar (Hash, Array, uploaded file, ...) or text that is not
+  # valid UTF-8 are rejected.
+  module Webhook
+    # Raised for anything that is not a usable push. The message names fields,
+    # never their values (bodies and phone numbers are personal data).
+    class InvalidPayload < Error; end
+
+    MAX_FIELDS = 64
+    MAX_BYTES = 10_000
+    RAILS_ROUTING_KEYS = %w[controller action format].freeze
+    SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+    # Fields the models read; they must be scalars. Other fields that are not
+    # (e.g. the copy Rails' ParamsWrapper nests into a JSON request, or a
+    # field ClickSend may add) are left out of +raw+ instead of failing.
+    READ_FIELDS = %w[
+      message_id status_code status_text error_code error_text custom_string message_type subaccount_id
+      timestamp_send timestamp from to body original_body original_message_id
+    ].freeze
+    private_constant :RAILS_ROUTING_KEYS, :SCALARS, :READ_FIELDS
+
+    module_function
+
+    # @return [Clicksend::SMS::Receipt, Clicksend::SMS::InboundMessage]
+    # @raise [InvalidPayload] also when the type cannot be told from the fields
+    def parse(params)
+      payload = normalize(params)
+      if payload.key?("from") && payload.key?("body") && !payload.key?("status_code")
+        inbound(payload)
+      elsif payload.key?("status_code") && !payload.key?("body")
+        receipt(payload)
+      else
+        raise InvalidPayload, "cannot tell whether this is a delivery receipt or an inbound message; use parse_receipt or parse_inbound"
+      end
+    end
+
+    # Requires +message_id+ and an integer +status_code+.
+    # @return [Clicksend::SMS::Receipt]
+    def parse_receipt(params)
+      receipt(normalize(params))
+    end
+
+    # Requires +message_id+, a non-empty +from+ and a String +body+ (may be empty).
+    # @return [Clicksend::SMS::InboundMessage]
+    def parse_inbound(params)
+      inbound(normalize(params))
+    end
+
+    def receipt(payload)
+      message_id!(payload)
+      raise InvalidPayload, "delivery receipt: status_code is missing or not an integer" unless Model.integer(payload["status_code"])
+
+      SMS::Receipt.from_api(payload)
+    end
+
+    def inbound(payload)
+      message_id!(payload)
+      from = payload["from"]
+      raise InvalidPayload, "inbound message: from is missing or not a non-empty String" unless from.is_a?(String) && !from.empty?
+      raise InvalidPayload, "inbound message: body is missing or not a String" unless payload["body"].is_a?(String)
+
+      SMS::InboundMessage.from_api(payload)
+    end
+
+    # message_id is interpolated into API paths when the event is confirmed.
+    def message_id!(payload)
+      return if payload["message_id"].is_a?(String) && payload["message_id"].match?(Resources::SMS::MESSAGE_ID)
+
+      raise InvalidPayload, "message_id is missing or not a ClickSend message ID"
+    end
+
+    def normalize(params)
+      params = params.to_unsafe_h if !params.is_a?(Hash) && params.respond_to?(:to_unsafe_h)
+      raise InvalidPayload, "expected a Hash of params, got #{params.class}" unless params.is_a?(Hash)
+      raise InvalidPayload, "payload has more than #{MAX_FIELDS} fields" if params.size > MAX_FIELDS
+
+      params.each_with_object({}) do |(key, value), payload|
+        raise InvalidPayload, "payload keys must be Strings or Symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+
+        key = utf8!(key.to_s)
+        next if RAILS_ROUTING_KEYS.include?(key)
+        raise InvalidPayload, "payload has the same key as both a String and a Symbol" if payload.key?(key)
+        unless SCALARS.any? { |type| value.is_a?(type) }
+          next unless READ_FIELDS.include?(key)
+
+          raise InvalidPayload, "#{key} must be a String, number, boolean or null"
+        end
+        if key.bytesize > MAX_BYTES || (value.is_a?(String) && value.bytesize > MAX_BYTES)
+          raise InvalidPayload, "payload has a key or value longer than #{MAX_BYTES} bytes"
+        end
+
+        payload[key] = value.is_a?(String) ? utf8!(value) : value
+      end.freeze
+    end
+
+    # Rack may hand over form values as binary Strings; ClickSend sends UTF-8.
+    # Anything that is not valid UTF-8 is rejected rather than passed on to
+    # break JSON encoding or logging later.
+    def utf8!(value)
+      text = (value.encoding == Encoding::BINARY) ? value.dup.force_encoding(Encoding::UTF_8) : value.encode(Encoding::UTF_8)
+      raise InvalidPayload, "payload has a value that is not valid UTF-8" unless text.valid_encoding?
+
+      text.frozen? ? text : text.dup.freeze
+    rescue EncodingError
+      raise InvalidPayload, "payload has a value that is not valid UTF-8"
+    end
+
+    private_class_method :receipt, :inbound, :message_id!, :normalize, :utf8!
+  end
+end

data/lib/clicksend.rb

@@ -2,6 +2,8 @@
 
 require_relative "clicksend/version"
 require_relative "clicksend/errors"
+require_relative "clicksend/rate_limit"
+require_relative "clicksend/instrumentation"
 require_relative "clicksend/transport"
 require_relative "clicksend/response"
 require_relative "clicksend/retry_policy"
@@ -14,6 +16,8 @@ require_relative "clicksend/sms/message"
 require_relative "clicksend/sms/batch"
 require_relative "clicksend/sms/receipt"
 require_relative "clicksend/sms/inbound_message"
+require_relative "clicksend/sms/history_record"
+require_relative "clicksend/webhook"
 require_relative "clicksend/resources/sms"
 require_relative "clicksend/client"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clicksend
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Amit Solanki
@@ -50,18 +50,27 @@ files:
 - lib/clicksend/client.rb
 - lib/clicksend/connection.rb
 - lib/clicksend/errors.rb
+- lib/clicksend/instrumentation.rb
 - lib/clicksend/model.rb
 - lib/clicksend/page.rb
+- lib/clicksend/rate_limit.rb
 - lib/clicksend/resources/account.rb
 - lib/clicksend/resources/sms.rb
 - lib/clicksend/response.rb
 - lib/clicksend/retry_policy.rb
 - lib/clicksend/sms/batch.rb
+- lib/clicksend/sms/history_record.rb
 - lib/clicksend/sms/inbound_message.rb
 - lib/clicksend/sms/message.rb
 - lib/clicksend/sms/receipt.rb
+- lib/clicksend/testing.rb
+- lib/clicksend/testing/failure.rb
+- lib/clicksend/testing/fake_api.rb
+- lib/clicksend/testing/payloads.rb
+- lib/clicksend/testing/records.rb
 - lib/clicksend/transport.rb
 - lib/clicksend/version.rb
+- lib/clicksend/webhook.rb
 homepage: https://github.com/prayantr/clicksend
 licenses:
 - MIT