clicksend 1.1.0 → 1.2.0

data/lib/clicksend/testing/fake_api.rb

@@ -10,16 +10,24 @@ module Clicksend
     #   fake.sent_messages.last.custom_string # => "otp:42"
     #
     # It emulates these endpoints, with ClickSend's response shapes:
-    # POST /v3/sms/send, GET /v3/account, and receipts and inbound (list, one
-    # receipt, mark read). Anything else answers 404 unless #stub-bed.
+    # POST /v3/sms/send, GET /v3/account, receipts and inbound (list, one
+    # receipt, mark read), and cancelling a scheduled message. Anything else
+    # answers 404 unless #stub-bed.
     #
-    # It deliberately does not serve GET /v3/sms/history. ClickSend doesn't
-    # say how soon a sent message appears there, and an always-up-to-date fake
-    # history would let a "not in history, so resend" rule pass its tests and
-    # then send twice in production. To test reconciliation code, #stub the
-    # history rows your scenario needs, including none. Recipients can be rejected (#reject), failures
-    # injected (#fail_next) and receipts and replies seeded (#add_receipt,
-    # #add_inbound).
+    # It deliberately does not serve GET /v3/sms/history by itself. ClickSend
+    # doesn't say how soon a sent message appears there, and an always-up-to-
+    # date fake history would let a "not in history, so resend" rule pass its
+    # tests and then send twice in production. To test reconciliation code,
+    # say what history shows with #stub_history, including nothing.
+    #
+    # Cancelling (PUT /v3/sms/{message_id}/cancel) succeeds for a message the
+    # fake accepted with a schedule still in the future. ClickSend doesn't
+    # document its answer for any other message (unknown, already sent, already
+    # cancelled), so the fake raises Testing::StubError for those: #stub the
+    # answer your test assumes.
+    #
+    # Recipients can be rejected (#reject), failures injected (#fail_next) and
+    # receipts and replies seeded (#add_receipt, #add_inbound).
     #
     # Simplifications, so tests don't come to depend on them:
     # - the balance never changes; +message_parts+ is an estimate (one per
@@ -44,6 +52,8 @@ module Clicksend
       # failures) is not a mistake in the fake's setup and passes through as is.
       MISTAKES = [StandardError, ScriptError].freeze
       STATUS_TEXTS = {200 => "Sent", 201 => "Delivered", 300 => "Retrying", 301 => "Failed"}.freeze
+      # The history statuses ClickSend documents for outbound messages.
+      HISTORY_STATUSES = %w[Queued Completed Scheduled WaitApproval Failed Cancelled CancelledAfterReview Sent].freeze
       ROUTES = [
         [:post, %r{\A/v3/sms/send\z}, :send_sms],
         [:get, %r{\A/v3/account\z}, :account],
@@ -52,9 +62,10 @@ module Clicksend
         [:put, %r{\A/v3/sms/receipts-read\z}, :mark_receipts_read],
         [:get, %r{\A/v3/sms/inbound\z}, :list_inbound],
         [:put, %r{\A/v3/sms/inbound-read\z}, :mark_inbound_read],
-        [:put, %r{\A/v3/sms/inbound-read/([A-Za-z0-9-]+)\z}, :mark_inbound_message_read]
+        [:put, %r{\A/v3/sms/inbound-read/([A-Za-z0-9-]+)\z}, :mark_inbound_message_read],
+        [:put, %r{\A/v3/sms/([A-Za-z0-9-]+)/cancel\z}, :cancel_sms]
       ].freeze
-      private_constant :DECIMAL, :RECIPIENT, :MISTAKES, :STATUS_TEXTS, :ROUTES
+      private_constant :DECIMAL, :RECIPIENT, :MISTAKES, :STATUS_TEXTS, :HISTORY_STATUSES, :ROUTES
 
       # @param balance [String] the account balance, as ClickSend's decimal String
       # @param currency [String] e.g. "AUD"
@@ -72,6 +83,7 @@ module Clicksend
         @clock = clock
         @lock = Mutex.new
         @outbox = [] # [SentMessage, accepted payload]
+        @cancelled = {} # message_id => SentMessage
         @requests = []
         @receipts = []
         @latest_receipts = {} # message_id => payload
@@ -84,11 +96,15 @@ module Clicksend
       # A real Clicksend::Client using this fake, with the production retry
       # rules but no backoff delay. A 429's Retry-After is still honoured
       # (injected 429s default to 0 seconds).
-      # @param overrides [Hash] any Client.new option
+      # @param overrides [Hash] any Client.new option. As with Client.new,
+      #   +max_retries:+ and +retry_policy:+ together raise ConfigurationError.
       # @return [Clicksend::Client]
       def client(**overrides)
-        retries = overrides.key?(:max_retries) ? {max_retries: overrides.delete(:max_retries)} : {}
-        defaults = {username: "test", api_key: "test", transport: self, retry_policy: RetryPolicy.new(**retries, base_delay: 0, max_delay: 0)}
+        defaults = {username: "test", api_key: "test", transport: self}
+        unless overrides.key?(:retry_policy)
+          retries = {max_retries: overrides.delete(:max_retries)}.compact
+          defaults[:retry_policy] = RetryPolicy.new(**retries, base_delay: 0, max_delay: 0)
+        end
         Client.new(**defaults.merge(overrides))
       end
 
@@ -98,17 +114,25 @@ module Clicksend
         @lock.synchronize { @outbox.map(&:first) }.freeze
       end
 
+      # Scheduled messages cancelled through PUT /v3/sms/{message_id}/cancel,
+      # in the order they were cancelled. They stay in #sent_messages: ClickSend
+      # accepted them.
+      # @return [Array<SentMessage>] a frozen snapshot
+      def cancelled_messages
+        @lock.synchronize { @cancelled.values }.freeze
+      end
+
       # Every request received, oldest first, including failed ones.
       # @return [Array<Request>] a frozen snapshot
       def requests
         @lock.synchronize { @requests.dup }.freeze
       end
 
-      # Forgets messages, requests, receipts, inbound messages, rejection
+      # Forgets messages, cancellations, requests, receipts, inbound messages, rejection
       # rules, pending failures and stubs. Constructor settings are kept.
       # @return [self]
       def reset!
-        @lock.synchronize { [@outbox, @requests, @receipts, @latest_receipts, @inbound, @rules, @failures, @stubs].each(&:clear) }
+        @lock.synchronize { [@outbox, @cancelled, @requests, @receipts, @latest_receipts, @inbound, @rules, @failures, @stubs].each(&:clear) }
         self
       end
 
@@ -136,10 +160,20 @@ module Clicksend
       #   fake.fail_next(status: 500, processed: false)
       #   fake.fail_next(status: 429, retry_after: 0)      # never processed
       #   fake.fail_next(status: 401)                      # any 4xx; never processed
+      #   fake.fail_next(:interrupted, processed: true)    # the worker is stopped mid-send
       #
       # +processed:+ is required exactly when the outcome is ambiguous (a read
-      # timeout, a reset or a 5xx): with +true+ the request is handled first (a
-      # send is recorded), then the failure is returned; with +false+ it is not.
+      # timeout, a reset, a 5xx or an interruption): with +true+ the request is
+      # handled first (a send is recorded), then the failure is returned; with
+      # +false+ it is not.
+      #
+      # +:interrupted+ is not a ClickSend failure. It models your job runner
+      # stopping the worker during the call (Sidekiq's shutdown raising
+      # Sidekiq::Shutdown into busy threads, for example) by raising
+      # SimulatedInterrupt, which is not a StandardError: the client lets it
+      # through untouched and never retries it. Use it to test what the next
+      # run of the job does, e.g. that an in-flight marker stops it sending
+      # again.
       #
       # @param path [String, nil] only requests to this exact path
       # @param method [Symbol, nil] only requests with this HTTP method
@@ -168,6 +202,28 @@ module Clicksend
         self
       end
 
+      # Says what GET /v3/sms/history shows from now on: exactly +messages+
+      # (SentMessages from #sent_messages), each with history status +status+,
+      # in the order given, or nothing at all. Every history request gets these
+      # rows, whatever its q, date or order parameters: you are stating what
+      # ClickSend shows for the query your code makes, at that point in your
+      # scenario. Call it again to change what history shows. Rows have
+      # ClickSend's history shape as observed live (status_code null).
+      #
+      #   fake.stub_history                                     # nothing (yet)
+      #   fake.stub_history(fake.sent_messages.last)            # this message, "Sent"
+      #   fake.stub_history(message, status: "Cancelled")
+      # @return [self]
+      def stub_history(*messages, status: "Sent")
+        messages.each { |message| sent_message!(message, "messages") }
+        unless HISTORY_STATUSES.include?(status)
+          raise ArgumentError, "status must be one of ClickSend's outbound history statuses (#{HISTORY_STATUSES.join(", ")}), got #{status.inspect}"
+        end
+
+        rows = messages.map { |message| Payloads.history_row(message, status, @message_price) }.freeze
+        stub(:get, "/v3/sms/history") { |request| Payloads.page(rows, request.path, request.query, "Here are your history.") }
+      end
+
       # Seeds a delivery receipt, unread. Pass +message_id:+, or +for:+ a
       # SentMessage to take its message_id, custom_string and send time.
       #
@@ -242,6 +298,7 @@ module Clicksend
       # ignored and never stored: they hold the credentials.
       # @return [Clicksend::Transport::Response]
       # @raise [Clicksend::ConnectionError] for injected connection failures
+      # @raise [SimulatedInterrupt] for fail_next(:interrupted)
       def call(method, path, query: nil, body: nil, headers: nil)
         request = build_request(method, path, query, body)
         failure, stub = @lock.synchronize do
@@ -375,6 +432,18 @@ module Clicksend
         Payloads.ok("Inbound messages have been marked as read.", entries.size)
       end
 
+      def cancel_sms(_request, message_id)
+        sent, = @outbox.find { |message, _| message.message_id == message_id }
+        if sent&.scheduled_at && sent.scheduled_at > now && !@cancelled.key?(message_id)
+          @cancelled[message_id] = sent
+          return Payloads.ok("Scheduled sms message has been cancelled.", nil)
+        end
+
+        raise StubError, "ClickSend doesn't document its answer to cancelling a message that is not scheduled for the future " \
+          "(unknown, already sent or already cancelled), so the FakeAPI won't guess: " \
+          "stub PUT /v3/sms/#{message_id}/cancel with the answer your test assumes"
+      end
+
       def mark_read(entries, request, message)
         body = request.body.nil? ? {} : request.body
         cutoff = body["date_before"] if body.is_a?(Hash)

data/lib/clicksend/testing/minitest.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../testing"
+require_relative "sms_expectations"
+
+module Clicksend
+  module Testing
+    # Minitest assertions over a FakeAPI's sent messages. Opt-in (never
+    # loaded by +require "clicksend"+); include them where you need them:
+    #
+    #   require "clicksend/testing/minitest"
+    #
+    #   class ActiveSupport::TestCase # or Minitest::Test
+    #     include Clicksend::Testing::MinitestAssertions
+    #   end
+    #
+    #   assert_sms_sent fake, to: "+61411111111", body: /481516/, custom_string: "otp:42"
+    #   assert_sms_sent fake, to: "+61411111111", count: 2
+    #   assert_no_sms_sent fake, to: "+61422222222"
+    #   assert_no_sms_sent fake
+    #
+    # They match the attributes of SentMessage (to, body, custom_string,
+    # from, list_id, scheduled_at, country, message_id, sent_at) with +===+,
+    # so Strings, Regexps and procs work. "Sent" means accepted
+    # (fake.sent_messages): rejected recipients don't count.
+    module MinitestAssertions
+      # Asserts that exactly +count+ sent messages match every given
+      # attribute. The default count is 1: a second matching message is the
+      # duplicate this assertion is there to catch.
+      # @return [Array<SentMessage>] the matching messages
+      def assert_sms_sent(fake, count: 1, **attributes)
+        clicksend_assert_sms_count(fake, count, attributes, "assert_sms_sent")
+      end
+
+      # Asserts that no message was sent or, given attributes, that none of
+      # the sent messages matches them.
+      # @return [true]
+      def assert_no_sms_sent(fake, **attributes)
+        clicksend_assert_sms_count(fake, 0, attributes, "assert_no_sms_sent")
+        true
+      end
+
+      private
+
+      def clicksend_assert_sms_count(fake, count, attributes, name)
+        SmsExpectations.check_attributes!(attributes, name)
+        SmsExpectations.check_count!(count, name)
+        sent = SmsExpectations.sent_messages(fake, name)
+        matched = SmsExpectations.matching(sent, attributes)
+        assert(matched.size == count, -> { SmsExpectations.count_failure(attributes, count, matched, sent) })
+        matched
+      end
+    end
+  end
+end

data/lib/clicksend/testing/payloads.rb

@@ -71,6 +71,21 @@ module Clicksend
         }.freeze
       end
 
+      # A GET /v3/sms/history row for a message the fake accepted, in the shape
+      # observed live: no gateway code or text, +schedule+ a String.
+      def history_row(sent, status, price)
+        parts = parts(sent.body)
+        {
+          "direction" => "out", "date" => sent.sent_at.to_i, "to" => sent.to, "body" => sent.body, "status" => status,
+          "from" => sent.from, "schedule" => (sent.scheduled_at || sent.sent_at).to_i.to_s, "status_code" => nil,
+          "status_text" => nil, "error_code" => nil, "error_text" => nil, "message_id" => sent.message_id,
+          "message_parts" => parts, "message_price" => format("%.4f", Rational(price) * parts), "from_email" => nil,
+          "list_id" => sent.list_id, "custom_string" => sent.custom_string || "", "contact_id" => nil, "user_id" => USER_ID,
+          "subaccount_id" => SUBACCOUNT_ID, "country" => sent.country, "carrier" => "", "first_name" => nil,
+          "last_name" => nil, "_api_username" => "test"
+        }.freeze
+      end
+
       # The minimal shape ClickSend returns for a message it did not accept.
       def rejected(message, id, status)
         {

data/lib/clicksend/testing/records.rb

@@ -9,7 +9,9 @@ module Clicksend
     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
+    # +clock:+) raises a StandardError or ScriptError, i.e. has a bug, or when
+    # a test asks the fake for an answer ClickSend doesn't document (such as
+    # cancelling a message that is not scheduled), which it must #stub. 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,
@@ -17,6 +19,20 @@ module Clicksend
     class StubError < Exception # rubocop:disable Lint/InheritException
     end
 
+    # Raised by FakeAPI#fail_next(:interrupted, processed: ...): the job
+    # runner stopping the worker in the middle of a send, before or after
+    # ClickSend processed it. It models your job runner (Sidekiq's shutdown
+    # raising Sidekiq::Shutdown into busy threads, a deploy's SIGTERM, a
+    # timeout), not anything ClickSend does.
+    #
+    # Like those, it is not a StandardError, so the client lets it through
+    # untouched: it is never retried, never wrapped in a Clicksend::Error and
+    # never reported as ambiguous. It is not an ::Interrupt either, so a test
+    # that doesn't rescue it fails like any other example instead of
+    # stopping the test run.
+    class SimulatedInterrupt < 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

data/lib/clicksend/testing/rspec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require_relative "../testing"
+require_relative "sms_expectations"
+
+module Clicksend
+  module Testing
+    # RSpec matchers over a FakeAPI's sent messages. Opt-in, from your
+    # spec_helper (never loaded by +require "clicksend"+):
+    #
+    #   require "clicksend/testing/rspec"
+    #
+    # which includes them in every example group (with rspec-core; otherwise
+    # include Clicksend::Testing::RSpecMatchers yourself).
+    #
+    #   expect(fake).to have_sent_sms(to: "+61411111111", body: /481516/, custom_string: "otp:42")
+    #   expect(fake).to have_sent_sms(to: "+61411111111").twice
+    #   expect(fake).not_to have_sent_sms(to: "+61422222222")
+    #   expect(fake).to have_sent_no_sms
+    #
+    # They match the attributes of SentMessage (to, body, custom_string,
+    # from, list_id, scheduled_at, country, message_id, sent_at) with +===+,
+    # so Strings, Regexps, procs and composable matchers work. "Sent" means
+    # accepted (fake.sent_messages): rejected recipients don't count.
+    #
+    # Without a count, have_sent_sms expects exactly one matching message:
+    # a second one is the duplicate these matchers are there to catch.
+    module RSpecMatchers
+      # Passes when exactly one sent message (or the chained count) matches
+      # every given attribute. Negated, passes when none matches.
+      # @return [HaveSentSms]
+      def have_sent_sms(**attributes)
+        HaveSentSms.new(attributes)
+      end
+
+      # Passes when no message was sent or, given attributes, none of the
+      # sent messages matches them.
+      # @return [HaveSentSms]
+      def have_sent_no_sms(**attributes)
+        HaveSentSms.new(attributes, count: 0, name: "have_sent_no_sms")
+      end
+
+      # The matcher behind #have_sent_sms and #have_sent_no_sms.
+      class HaveSentSms
+        include ::RSpec::Matchers::Composable
+
+        def initialize(attributes, count: nil, name: "have_sent_sms")
+          SmsExpectations.check_attributes!(attributes, name)
+          @attributes = attributes
+          @count = count
+          @name = name
+          @fixed = !count.nil?
+        end
+
+        # @return [self]
+        def once = exactly(1)
+
+        # @return [self]
+        def twice = exactly(2)
+
+        # +exactly(n).times+, or just +times(n)+.
+        # @return [self]
+        def exactly(count)
+          raise ArgumentError, "#{@name} takes no count; use have_sent_sms(...).exactly(n).times" if @fixed
+
+          SmsExpectations.check_count!(count, @name)
+          @count = count
+          self
+        end
+
+        # @return [self]
+        def times(count = nil)
+          return exactly(count) unless count.nil?
+          raise ArgumentError, "use have_sent_sms(...).times(n) or .exactly(n).times" if @count.nil?
+
+          self
+        end
+
+        def matches?(fake)
+          evaluate(fake)
+          @matched.size == expected_count
+        end
+
+        def does_not_match?(fake)
+          if @fixed || !@count.nil?
+            raise ArgumentError, "#{@name}#{" with a count" unless @fixed} can't be negated: " \
+              "say how many you expect, e.g. to have_sent_sms(...).exactly(0).times"
+          end
+
+          evaluate(fake)
+          @matched.empty?
+        end
+
+        def failure_message
+          SmsExpectations.count_failure(@attributes, expected_count, @matched, @sent)
+        end
+
+        def failure_message_when_negated
+          SmsExpectations.count_failure(@attributes, 0, @matched, @sent)
+        end
+
+        def description
+          return "have sent no #{SmsExpectations.subject(@attributes)}" if expected_count.zero?
+
+          "have sent exactly #{expected_count} #{SmsExpectations.subject(@attributes)}"
+        end
+
+        private
+
+        def expected_count = @count || 1
+
+        def evaluate(fake)
+          @sent = SmsExpectations.sent_messages(fake, @name)
+          @matched = SmsExpectations.matching(@sent, @attributes)
+        end
+      end
+    end
+  end
+end
+
+if defined?(RSpec.configure)
+  RSpec.configure { |config| config.include(Clicksend::Testing::RSpecMatchers) }
+end

data/lib/clicksend/testing/sms_expectations.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../testing"
+
+module Clicksend
+  module Testing
+    # The matching and failure output shared by the RSpec matchers
+    # (clicksend/testing/rspec) and the Minitest assertions
+    # (clicksend/testing/minitest). Framework-free.
+    # @api private
+    module SmsExpectations
+      ATTRIBUTES = SentMessage.members.freeze
+      # Failure output lists at most this many messages...
+      MAX_LISTED = 10
+      # ...and shortens longer values to this many characters.
+      MAX_VALUE_LENGTH = 60
+
+      module_function
+
+      # @return [Array<SentMessage>]
+      def sent_messages(fake, helper)
+        return fake.sent_messages if fake.is_a?(FakeAPI)
+
+        raise ArgumentError, "#{helper} expects a Clicksend::Testing::FakeAPI (the fake itself, not fake.client " \
+          "or fake.sent_messages), got #{fake.class}"
+      end
+
+      # Keys must be SentMessage attributes: a typo must fail the test, not
+      # match everything.
+      def check_attributes!(attributes, helper)
+        unknown = attributes.keys - ATTRIBUTES
+        return if unknown.empty?
+
+        raise ArgumentError, "#{helper}: unknown attribute#{"s" if unknown.size > 1} #{unknown.map(&:inspect).join(", ")}; " \
+          "use #{ATTRIBUTES.join(", ")}"
+      end
+
+      def check_count!(count, helper)
+        raise ArgumentError, "#{helper}: the count must be a non-negative Integer, got #{count.inspect}" unless count.is_a?(Integer) && count >= 0
+      end
+
+      # Each expected value is matched with +===+, so Strings, Regexps,
+      # Ranges, classes, procs and RSpec's composable matchers all work.
+      # @return [Array<SentMessage>]
+      def matching(messages, attributes)
+        messages.select { |message| attributes.all? { |key, expected| expected === message.public_send(key) } }
+      end
+
+      # "SMS matching to: "+61411111111", body: /code/" or "SMS".
+      def subject(attributes)
+        return "SMS" if attributes.empty?
+
+        "SMS matching #{attributes.map { |key, value| "#{key}: #{describe_value(value)}" }.join(", ")}"
+      end
+
+      # The failure when +count+ messages were expected and +matched+ were found.
+      def count_failure(attributes, count, matched, messages)
+        expectation = count.zero? ? "no #{subject(attributes)}" : "exactly #{count} #{subject(attributes)}"
+        "expected #{expectation} to have been sent, but #{matched.size} matched.\n#{listing(messages, attributes)}"
+      end
+
+      # "No SMS was sent." or "3 SMS sent:" and one line per message (at
+      # most MAX_LISTED).
+      def listing(messages, attributes)
+        return "No SMS was sent." if messages.empty?
+
+        lines = messages.first(MAX_LISTED).each_with_index.map { |message, index| "  #{index + 1}. #{line(message, attributes)}" }
+        lines << "  ... and #{messages.size - MAX_LISTED} more" if messages.size > MAX_LISTED
+        "#{messages.size} SMS sent:\n#{lines.join("\n")}"
+      end
+
+      # One message on one line: recipient (or list_id), custom_string and
+      # body, then any other attribute the expectation names.
+      def line(message, attributes)
+        keys = [message.to.nil? ? :list_id : :to, :custom_string, :body] | attributes.keys
+        keys.map { |key| "#{key}: #{show(message.public_send(key))}" }.join(", ")
+      end
+
+      def describe_value(value)
+        value.respond_to?(:description) ? value.description : show(value)
+      end
+
+      # A long String is cut, with the "..." outside its quotes.
+      def show(value)
+        return value.inspect unless value.is_a?(String) && value.length > MAX_VALUE_LENGTH
+
+        "#{value[0, MAX_VALUE_LENGTH].inspect}..."
+      end
+    end
+  end
+end

data/lib/clicksend/testing.rb

@@ -83,6 +83,12 @@ module Clicksend
   #
   # A FakeAPI keeps every request in memory until #reset!, so a long-running
   # process should reset it from time to time.
+  #
+  # Assertions for test frameworks are separate, opt-in files, and this gem
+  # depends on neither framework: +require "clicksend/testing/rspec"+ adds
+  # +have_sent_sms+ and +have_sent_no_sms+ (Clicksend::Testing::RSpecMatchers),
+  # +require "clicksend/testing/minitest"+ adds +assert_sms_sent+ and
+  # +assert_no_sms_sent+ (Clicksend::Testing::MinitestAssertions).
   module Testing
   end
 end

data/lib/clicksend/transport.rb

@@ -21,11 +21,16 @@ module Clicksend
 
     # The default transport, built on Faraday 2.
     class Faraday
-      # Failures that can only happen while connecting, before the request is
-      # written, so the request cannot have reached ClickSend. Deliberately
-      # narrow: TLS errors and unreachable-host errors can also occur after
-      # the request was sent, so they count as "may have been sent".
-      NOT_SENT_ERRORS = ["Errno::ECONNREFUSED", "SocketError", "Net::OpenTimeout"].freeze
+      # Failures that can only happen before the request is written, so the
+      # request cannot have reached ClickSend: connecting (refused, DNS,
+      # connect or TLS-handshake timeout) and, with adapter:
+      # :net_http_persistent, waiting for a pooled connection
+      # (ConnectionPool::TimeoutError, raised by the checkout that precedes
+      # everything else). Matched by name, so no adapter is required.
+      # Deliberately narrow: TLS errors and unreachable or downed hosts can
+      # also occur after the request was sent, so they count as "may have
+      # been sent".
+      NOT_SENT_ERRORS = ["Errno::ECONNREFUSED", "SocketError", "Net::OpenTimeout", "ConnectionPool::TimeoutError"].freeze
 
       # @param adapter [Symbol, Array, nil] a Faraday adapter name, optionally
       #   with arguments (e.g. +[:net_http_persistent, {pool_size: 5}]+).
@@ -46,7 +51,7 @@ module Clicksend
           body: response.body.to_s
         )
       rescue ::Faraday::TimeoutError => e
-        raise Clicksend::TimeoutError, "Timed out waiting for ClickSend: #{e.message}"
+        raise Clicksend::TimeoutError.new("Timed out waiting for ClickSend: #{e.message}", request_sent: not_sent?(e) ? false : nil)
       rescue ::Faraday::ConnectionFailed, ::Faraday::SSLError => e
         raise translate_connection_failure(e)
       end
@@ -54,10 +59,25 @@ module Clicksend
       private
 
       def translate_connection_failure(error)
+        error_class = (failure_cause(error)&.class&.name == "Net::OpenTimeout") ? Clicksend::TimeoutError : Clicksend::ConnectionError
+        error_class.new("Could not reach ClickSend: #{error.message}", request_sent: not_sent?(error) ? false : nil)
+      end
+
+      def not_sent?(error)
+        cause = failure_cause(error)
+        !cause.nil? && cause.class.ancestors.any? { |klass| NOT_SENT_ERRORS.include?(klass.name) }
+      end
+
+      # The exception the adapter wrapped. net-http-persistent reports a
+      # refused connection (only ever raised by connect(2), never once the
+      # request is being written) as a Net::HTTP::Persistent::Error raised
+      # in its rescue of the Errno, so for that class the Errno, its #cause,
+      # is what happened. Its other errors ("host down: ...") keep their
+      # own cause, which is not in NOT_SENT_ERRORS.
+      def failure_cause(error)
         cause = error.wrapped_exception || error.cause
-        not_sent = cause && cause.class.ancestors.any? { |klass| NOT_SENT_ERRORS.include?(klass.name) }
-        error_class = (cause&.class&.name == "Net::OpenTimeout") ? Clicksend::TimeoutError : Clicksend::ConnectionError
-        error_class.new("Could not reach ClickSend: #{error.message}", request_sent: not_sent ? false : nil)
+        persistent = defined?(::Net::HTTP::Persistent::Error) && cause.is_a?(::Net::HTTP::Persistent::Error)
+        persistent ? cause.cause : cause
       end
     end
   end

data/lib/clicksend/version.rb

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

data/lib/clicksend/webhook.rb

@@ -10,27 +10,33 @@ module Clicksend
   #
   # 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+.
+  # the rule's +webhook_type+. Receipt rules have no +webhook_type+; archived
+  # ClickSend help says pushes are form-encoded. The field names are those of
+  # the poll schemas (+sms_receipt+, +inbound_sms+), which an archived
+  # ClickSend help article and ClickSend's own n8n and Power Automate
+  # integrations also use. Those sources show pushes also carry +user_id+,
+  # +status+ ("Delivered"/"Undelivered", receipts) and legacy duplicates such
+  # as +message+, +sms+, +originalsenderid+, +messageid+ and +customstring+;
+  # these stay in +raw+. A JSON push may send numbers (+timestamp+,
+  # +user_id+) as JSON integers; both forms are accepted.
   #
-  # 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
+  # ClickSend's current docs describe no signing or authentication for
+  # pushes: no HMAC, signature or shared secret. (An archived help article
+  # listed six source IP addresses; it is no longer published, so do not rely
+  # on it.) Treat anyone who knows the URL as able to forge one, so:
+  # - put an unguessable secret in the URL and compare it in constant time
   #   (it will appear in access logs: restrict who reads them);
-  # - use HTTPS;
+  # - use HTTPS (archived help: a valid certificate chain is required);
   # - 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;
+  # - process idempotently: several matching rules may each push, and a
+  #   non-200 or slow answer is retried (archived pages disagree on the
+  #   schedule: every 10 minutes 10 times, or backing off over hours). An
+  #   inbound message_id is unique, but one sent message may get more than
+  #   one receipt (the pending codes 200 and 300 "can update at any time"), so
+  #   key receipts on message_id and status_code, and never let a pending
+  #   status replace a final one;
   # - answer 200 quickly and do the work in a job.
   #
   # Prefer one URL per rule type with #parse_receipt / #parse_inbound; #parse