clicksend 1.1.0 → 1.2.0

data/docs/clicksend-api-notes.md

@@ -13,7 +13,9 @@ Sources:
 - [SMS error codes](https://help.clicksend.com/en/articles/42318-sms-error-codes)
 - Superseded but still informative: the [legacy HTTP v2 docs](https://developers.clicksend.com/docs/http/v2/)
   and the [archived REST v3 docs](https://web.archive.org/web/20220502204655/https://developers.clicksend.com/docs/rest/v3/)
-  (2022), the only sources that list the fields ClickSend pushes to webhook URLs
+  (2022), and help articles that disappeared when ClickSend moved its help centre (around mid-2025,
+  judging by the Wayback Machine, which kept them). Those, and ClickSend's own integrations, are the only sources that list
+  the fields ClickSend pushes to webhook URLs; see `research/1.2-webhooks.md` in the repository
 
 ## Behaviour taken from the documentation
 
@@ -35,8 +37,14 @@ Sources:
 | Idempotency | No idempotency key on any operation (all 34 sections searched) | Sends are never retried after timeouts or 5xx |
 | `THROTTLED` | Application code: "Identical message body recently sent to the same recipient." Window and placement undocumented | Treated as an ordinary rejection; never relied on for deduplication |
 | History search | `GET /v3/sms/history`: `date_from`, `date_to`, `order_by` (`date:asc` default), `page`, `limit`, and `q=field:value` for `status`, `to`, `from`, `subaccount_id`, `message_id`. `custom_string` is **not** a filter | `sms.history` takes one of `to:`, `from:`, `status:`, `message_id:`; match `custom_string` yourself |
-| Webhooks (push) | Automation rules with the `URL` action. Inbound rules: `webhook_type` `post` (form, default), `get` or `json` (format unspecified). Receipts: form-encoded POST according to the archived v3 docs (help 42270 covers inbound rules only). **No payload schema** in the current docs; the archived docs list the fields, matching the poll schemas plus `user_id` and (receipts) `status`. Archived: a non-200 is retried every 10 minutes, 10 times | `Clicksend::Webhook` parses into `SMS::Receipt` / `SMS::InboundMessage` |
-| Webhook authentication | **None documented.** No signature, HMAC or shared secret in any current, archived or help source. Current docs list no source IP addresses; archived help pages (around 2019–2021, no longer published) listed six and said pushes come from a fixed pool | No verification method and no IP allowlisting; README prescribes a secret URL and confirming via the API |
+| Combining search filters | The general "Searching and Sorting" section shows `q=field:value,field2:value`, `AND` by default, and `operator=OR`; searches are "**not** case-sensitive". The history operation itself documents one `field_name:value` and no `operator`, and calls the value "the text or keyword you're searching for" (exact or partial match unstated) | `sms.history` sends one filter; `sms.search_history` re-checks `to` and `custom_string` for exact equality |
+| History retention | Help 43125: message data is kept for four months, then archived and "no longer available to view in the Dashboard, or downloadable from the History page or API". De-identification (on request) obfuscates `to` "in any history downloads" | Another reason an empty history search proves nothing |
+| History consistency | **None documented**: no statement anywhere (current, archived or help) on how soon an accepted send appears in `GET /v3/sms/history` | `search_history` returns rows only; never "not sent" |
+| Cancel one scheduled SMS | `PUT /v3/sms/{message_id}/cancel`, no body; 200 example `response_msg: "Scheduled sms message has been cancelled."`, `data` "deprecated and will return null" (archived 2022: `data: []`, message naming the ID). Answers for an unknown, sent or already-cancelled ID, and idempotency, are **undocumented** | `sms.cancel`, not idempotent: never retried after a timeout or 5xx |
+| Cancel all scheduled SMS | `PUT /v3/sms/cancel-all`; optional body `custom_string` limits it to messages with that value (match semantics undocumented); without it, every scheduled SMS is cancelled. Returns `data.count` | Deliberately not wrapped |
+| Price quote | `POST /v3/sms/price`: "calculate the price of sending messages". The only statement about effects is in the `sms` schema's `date`: it may be empty "in price-calculation responses where no message has actually been sent yet". The example returns a `message_id` | Not wrapped; `client.request` treats it as non-idempotent |
+| Webhooks (push) | Automation rules with the `URL` action. Inbound rules: `webhook_type` `post` (form, default), `get` or `json` (format unspecified; ClickSend's n8n trigger shows a flat JSON object with integer `timestamp`/`user_id`). Receipts: form-encoded POST according to archived help ("the only forwarding format we support is x-www-form-urlencoded"). **No payload schema** in the current docs; archived docs and help list the fields: the poll schemas' names plus `user_id`, `status` (receipts) and legacy duplicates (`message`, `sms`, `originalsenderid`, `originalmessage`, `originalmessageid`, `customstring`, `messageid`). Retries: archived sources disagree (every 10 minutes ×10 with a 30 s timeout, or backoff over hours with a 15 s timeout); nothing current | `Clicksend::Webhook` parses into `SMS::Receipt` / `SMS::InboundMessage`; the extra keys stay in `#raw` |
+| Webhook authentication | **None in the current docs**: no signature, HMAC or shared secret. Archived help (no longer published) suggested HTTPS, a URL token, checking `user_id`, and an allowlist of six source IPs last updated around 2019 | No verification method; README prescribes a secret URL and confirming via the API, and warns against the stale IP list |
 | Request ID | None documented; no spec declares any response header | `Error#request` describes the call instead |
 
 ## Ambiguities and inconsistencies
@@ -145,21 +153,57 @@ the contract specs only, **not** against a live receipt.
 | `GET /v3/sms/history?q=to:%2B61411111111&date_from=…&order_by=date:asc&limit=100` (`sms.history(to:, date_from:)`) | HTTP 200, paginated envelope. Exactly one row, the accepted test-number message from 2026-10-05, so `q=to:` filters and the encoded `+` works. Row: `direction: "out"`, `status: "Completed"`, `status_code: null`, `status_text: null`, `message_parts: 0`, `message_price: "0.0000"`, `custom_string` a String, `date` an Integer, `schedule` a String. The documented fields, plus `contact_id`, `user_id`, `subaccount_id`, `first_name`, `last_name`, `_api_username` |
 | `GET /v3/account` rate-limit headers through `Response#rate_limit` | `limit: 20`, `remaining` and `reset_in` Integers |
 
+### `sms.cancel` check (2026-10-06, protocol B3.7)
+
+Run through the gem (`client.sms.cancel`, `max_retries: 0`) with one scheduled message to the free
+test number `+61411111111` (`schedule:` one hour ahead) and nothing else sent. Every call was
+answered quickly (under 1.1s); the balance was the same before the send, after it, and at the end.
+
+| Step | Live result |
+|---|---|
+| Scheduled send to the test number | HTTP 200, per-message `status: "SUCCESS"`, `message_price: "0.0000"`, `message_parts: 0`, `schedule` one hour ahead |
+| History (`q=message_id:`) at 0s, 5s, 30s, 120s | No row at 0s. From 5s on, one row with status **`Completed`** (not `Scheduled`), `status_code: null` |
+| `PUT /v3/sms/{id}/cancel` on that message, no body | HTTP **404** `{"http_code":404,"response_code":"NOT_FOUND","response_msg":"Record not found.","data":null}`. The gem raised `Clicksend::NotFoundError`, not ambiguous |
+| History after the cancel (0s to 120s) | Still `Completed` |
+| The same cancel again | Same HTTP 404 `NOT_FOUND` envelope |
+| A random well-formed UUID | Same HTTP 404 `NOT_FOUND` envelope |
+| The 2026-10-05 accepted test-number message (`Completed`) | Same HTTP 404 `NOT_FOUND` envelope; history unchanged |
+
+What this shows:
+- A scheduled message to the free test number is **not held**: it is `Completed` within seconds,
+  so the test number can't exercise a successful cancel. The documented `200 SUCCESS` answer is
+  still unobserved live.
+- Cancelling a message that is no longer scheduled answers 404 `NOT_FOUND`, **not** `SUCCESS`, at
+  least for test-number messages. An unknown ID gets the same answer, so a 404 doesn't say which.
+- The path, the bodiless `PUT`, the JSON error envelope and the gem's mapping (typed, not
+  ambiguous, not retried) match the implementation.
+
 ### Still unverified
 
 These need a receipt for a real (non-test) message, existing inbound messages, or the public
 test accounts:
 
 - [ ] A live receipt: its shape and `status_code` type. The free test number produced none.
+- [ ] A successful `sms.cancel` (HTTP 200) and how a cancelled message shows in history. A
+      scheduled message to the free test number completes at once, so this needs a message that
+      ClickSend actually holds, i.e. a paid, scheduled send that is then cancelled.
 - [ ] Inbound timestamp field (`timestamp` or `timestamp_send`); no inbound messages existed
 - [ ] HTTP status and `response_code` for the `nocredit`, `notactive` and `banned` test accounts
 - [ ] Whether mark-read accepts an empty `{}` body. Deliberately not tested, because it would
       mark every unread item read (documented). The gem sends `{}` when `before:` is omitted; the
       request schema allows it.
-- [ ] A real webhook push: its content type, field names and types. Field names come from the
-      poll schemas and the archived docs
+- [ ] A real webhook push: its content type, field names and types (inbound `post`, `get` and
+      `json`, and a receipt), its headers, and how `null` is encoded. Field names come from the poll
+      schemas, archived docs and ClickSend's integrations. `script/webhook_capture.rb` and the
+      capture protocol in `research/1.2-webhooks.md` exist for this
+- [ ] Whether `GET /v3/sms/receipts/{message_id}` finds a receipt on an account with only URL rules
+- [ ] ClickSend's current retry schedule and timeout for pushes
 - [ ] How soon a sent message appears in history, and whether `date_from`/`date_to` are inclusive
 - [ ] Where and when `THROTTLED` is returned
+- [ ] What `PUT /v3/sms/{message_id}/cancel` answers for a second cancel, an already-sent message
+      and an unknown ID (protocol in `research/1.2-api-cancel-quote-history.md`)
+- [ ] Whether `POST /v3/sms/price` changes anything: balance, history, `THROTTLED`, rate limits
+- [ ] Whether history's `q=to:` matches exactly or by substring
 - [ ] Rate limits for endpoints other than `GET /v3/account`
 
 ## Retry safety: the rules and why

data/lib/clicksend/client.rb

@@ -148,7 +148,11 @@ module Clicksend
     #   page = client.paginate("/v3/sms/history", query: {date_from: from.to_i}, limit: 100)
     #   page.auto_paging_each { |message| ... }
     #
+    # @param query [Hash, nil] query parameters, kept for every page
+    # @param page [Integer, nil] the page to fetch (from 1)
+    # @param limit [Integer, nil] items per page, 15 to 100
     # @return [Clicksend::Page]
+    # @raise [ArgumentError] for an invalid query, page or limit
     def paginate(path, query: {}, page: nil, limit: nil, operation: nil)
       Page.fetch(self, path, query: query, page: page, limit: limit, operation: operation)
     end
@@ -171,6 +175,18 @@ module Clicksend
     end
     alias_method :to_s, :inspect
 
+    # A client holds the API key (in its settings and its Authorization
+    # header), so it must never be written to a cache, a job queue or a
+    # session by Marshal or YAML. Marshal checks #marshal_dump first, for
+    # frozen objects too; Psych checks #encode_with.
+    def marshal_dump
+      raise TypeError, "#{self.class.name} contains credentials and can't be marshaled; build a new client instead"
+    end
+
+    def encode_with(_coder)
+      raise TypeError, "#{self.class.name} contains credentials and can't be serialized to YAML; build a new client instead"
+    end
+
     private
 
     # Surrounding whitespace (e.g. a trailing newline from a secrets file) is

data/lib/clicksend/connection.rb

@@ -15,6 +15,15 @@ module Clicksend
   class Connection
     HTTP_METHODS = %i[get post put patch delete].freeze
 
+    # What code outside the gem (a logger, an instrumenter, a retry policy, a
+    # custom transport) raises when it has a bug: StandardError, and also
+    # ScriptError (NotImplementedError from an abstract method, LoadError from
+    # a lazily required exporter). Such a failure must never escape as a
+    # non-Clicksend error after a send was accepted: job runners such as
+    # Sidekiq rescue Exception and would run the job, and the send, again.
+    # Interrupt, SystemExit and NoMemoryError still propagate.
+    FOREIGN_FAILURES = [StandardError, ScriptError].freeze
+
     ERROR_CLASSES = {
       400 => BadRequestError,
       401 => AuthenticationError,
@@ -34,6 +43,11 @@ module Clicksend
     RETRY_ALWAYS = %i[rate_limited not_sent].freeze
     MAY_HAVE_BEEN_PROCESSED = %i[unknown undocumented].freeze
 
+    # The longest delay (seconds, about 68 years) Kernel.sleep accepts on
+    # every platform. A policy delay beyond it can't be waited for (sleep
+    # raises RangeError), so it means "don't retry".
+    MAX_SLEEP = (2**31) - 1
+
     # @param headers [Hash] sent with every request (authentication, User-Agent)
     # @param instrumenter [#instrument] see Clicksend::Instrumentation
     def initialize(transport:, retry_policy:, headers: {}, logger: nil, instrumenter: Instrumentation::Null)
@@ -71,37 +85,72 @@ module Clicksend
     # this, a metrics outage after an accepted send would surface as a
     # non-Clicksend error that a job runner retries: a duplicate SMS.
     #
-    # +state+ moves :pending -> :running -> :done. Only an exception that
-    # arrives once the request is :done can be the instrumenter's own, and
-    # only then is it ignored. Anything raised while the request is :running
-    # propagates: #run turns every failure it can foresee into a
-    # Clicksend::Error, so that is a genuine bug, never something to hide
-    # (hiding it once made #request return nil after an accepted send). A
-    # second call of the block raises instead of sending again.
+    # +state+ moves :pending -> :running -> :done, under a lock because an
+    # instrumenter may run the block on another thread. What it is when
+    # #instrument returns or raises decides the outcome:
+    #
+    # [:done]    the call's result or error. Any other exception can only be
+    #            the instrumenter's, and only then is it ignored.
+    # [:pending] nothing was sent. The block becomes :abandoned, so an
+    #            instrumenter that kept it and calls it later gets a
+    #            ConfigurationError instead of sending.
+    # [:running] the block was left unfinished. An exception that escaped the
+    #            request itself is a genuine bug and propagates: #run turns
+    #            every failure it can foresee into a Clicksend::Error, and
+    #            hiding one once made #request return nil after an accepted
+    #            send. Otherwise the block is still running on another thread
+    #            (or the instrumenter swallowed what it raised), so the
+    #            request may be or may yet be sent: a ConfigurationError,
+    #            ambiguous unless the request is idempotent.
+    #
+    # A second call of the block raises instead of sending again.
     def instrumented(call)
       payload = {http_method: call[:method], path: reported_path(call[:path]), operation: call[:operation], idempotent: call[:idempotent]}
+      lock = Mutex.new
       state = :pending
-      outcome = nil
+      outcome = escaped = failure = nil
       begin
         @instrumenter.instrument("request.clicksend", payload) do
-          raise ConfigurationError, "the instrumenter ran the request block twice; #instrument must yield once" unless state == :pending
+          lock.synchronize do
+            raise ConfigurationError, "the instrumenter ran the request block after #instrument returned; it must yield before returning" if state == :abandoned
+            raise ConfigurationError, "the instrumenter ran the request block twice; #instrument must yield once" unless state == :pending
 
-          state = :running
-          outcome = begin
+            state = :running
+          end
+          result = begin
             yield payload
           rescue Error => e
             e
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            lock.synchronize { escaped = e }
+            raise
           end
-          state = :done
+          lock.synchronize { outcome, state = result, :done }
           # Raise inside the block so ActiveSupport records the exception.
-          outcome.is_a?(Error) ? raise(outcome) : outcome
+          result.is_a?(Error) ? raise(result) : result
         end
       rescue Exception => e # rubocop:disable Lint/RescueException
-        raise unless state == :done && e.is_a?(StandardError) && !e.equal?(outcome)
+        failure = e
+      end
+      final, escaped = lock.synchronize { [(state == :pending) ? (state = :abandoned) : state, escaped] }
 
-        log(:warn) { "instrumenter raised #{e.class.name} for #{call[:method].upcase} #{reported_path(call[:path])}; ignored" }
+      case final
+      when :abandoned
+        raise failure if failure # the instrumenter failed before the request: nothing was sent
+
+        raise ConfigurationError, "the instrumenter did not run the request: #instrument must yield"
+      when :running
+        raise failure if failure&.equal?(escaped)
+
+        error = ConfigurationError.new("the instrumenter returned before the request finished; #instrument must run the block to completion before returning")
+        error.mark_ambiguous! unless call[:idempotent]
+        raise error, cause: failure
+      end
+      if failure && !failure.equal?(outcome)
+        raise failure unless FOREIGN_FAILURES.any? { |kind| failure.is_a?(kind) }
+
+        log(:warn) { "instrumenter raised #{failure.class.name} for #{call[:method].upcase} #{reported_path(call[:path])}; ignored" }
       end
-      raise ConfigurationError, "the instrumenter did not run the request: #instrument must yield" if state == :pending
       raise outcome if outcome.is_a?(Error)
 
       outcome
@@ -151,7 +200,7 @@ module Clicksend
         return [e.dup, :undocumented]
       rescue Error => e
         return [e.dup, :unknown] # any other Clicksend error from a custom transport: outcome unknown
-      rescue => e
+      rescue *FOREIGN_FAILURES => e
         return [wrap_failure(ConnectionError, "The transport failed", e), :unknown]
       end
       log(:info) { "#{call[:method].upcase} #{reported_path(call[:path])} -> #{raw.status} (#{elapsed_ms(started)}ms)" }
@@ -159,9 +208,9 @@ module Clicksend
         interpret(raw)
       rescue MalformedResponseError => e
         [e, :undocumented]
-      rescue => e
-        # A response this gem cannot even read (e.g. a body that is not valid
-        # in its declared charset) is undocumented: ambiguous for a send.
+      rescue *FOREIGN_FAILURES => e
+        # A response this gem cannot even read (e.g. a custom transport's
+        # body that is not a String) is undocumented: ambiguous for a send.
         [wrap_failure(MalformedResponseError, "Could not read ClickSend's response", e), :undocumented]
       end
     end
@@ -209,9 +258,11 @@ module Clicksend
       return unless budget.is_a?(Integer) && attempt < budget
 
       delay = @retry_policy.delay(error: error, attempt: attempt)
+      return if (delay.is_a?(Integer) || delay.is_a?(Rational)) && delay > MAX_SLEEP # Float() would warn
+
       delay = Float(delay) if delay.is_a?(Numeric)
-      delay if delay.is_a?(Float) && delay.finite? && delay >= 0
-    rescue => e
+      delay if delay.is_a?(Float) && delay.between?(0, MAX_SLEEP)
+    rescue *FOREIGN_FAILURES => e
       # A broken policy stops retrying (the safe direction) and keeps the
       # request's own error.
       log(:warn) { "retry policy raised #{e.class.name}; not retrying" }
@@ -226,7 +277,7 @@ module Clicksend
       payload = {http_method: call[:method], path: reported_path(call[:path]), operation: call[:operation], attempt: attempt,
                  delay: delay, error_class: error.class.name, http_status: error_status(error)}
       @instrumenter.instrument("retry.clicksend", payload) {}
-    rescue => e
+    rescue *FOREIGN_FAILURES => e
       log(:warn) { "instrumenter raised #{e.class.name} for retry.clicksend; ignored" }
     end
 
@@ -249,11 +300,15 @@ module Clicksend
 
     # Returns the parsed JSON, nil for an empty body, or the raw String when an
     # error response isn't JSON (e.g. an HTML page from a proxy).
+    #
+    # A body that isn't valid in its declared charset (JSON converts it to
+    # UTF-8 first) is unreadable in the same way, so the status still decides:
+    # a garbled 429 or 503 must stay retryable, and a 400 a rejection.
     def parse_body(raw)
       return nil if raw.body.b.strip.empty?
 
       JSON.parse(raw.body, freeze: true)
-    rescue JSON::ParserError
+    rescue JSON::ParserError, EncodingError
       return raw.body unless success?(raw.status)
 
       raise MalformedResponseError.new(
@@ -296,14 +351,14 @@ module Clicksend
     # the outcome is simply not recorded.
     def record(payload, **outcome)
       payload.update(outcome)
-    rescue
+    rescue *FOREIGN_FAILURES
       nil
     end
 
     # A failing logger must not turn a completed request into an error.
     def log(level)
       @logger&.public_send(level, "[clicksend] #{yield}")
-    rescue
+    rescue *FOREIGN_FAILURES
       nil
     end
 

data/lib/clicksend/errors.rb

@@ -168,17 +168,21 @@ module Clicksend
   # served", so it is treated as not processed (an inference, not a documented
   # guarantee).
   class RateLimitError < ClientError
-    # Seconds to wait before retrying, from the Retry-After header, if any.
+    # Seconds to wait before retrying, from the Retry-After header: a plain
+    # non-negative decimal Integer, or the time left until its HTTP-date (0
+    # if that has passed). Nil when the header is missing or is anything
+    # else ("+5", "-5", "0x10", "1_0", an Array, ...).
     def retry_after
-      value = headers["retry-after"]
-      return if value.nil?
-
-      Integer(value, exception: false)&.then { |seconds| [seconds, 0].max } ||
-        begin
-          [Time.httpdate(value) - Time.now, 0].max
-        rescue ArgumentError
-          nil
-        end
+      value = headers["retry-after"] if headers.is_a?(Hash)
+      value = value.to_s if value.is_a?(Integer) # from a custom transport
+      return unless value.is_a?(String)
+
+      text = value.strip
+      return Integer(text, 10) if text.match?(/\A\d+\z/)
+
+      [Time.httpdate(text) - Time.now, 0].max
+    rescue ArgumentError, RangeError # not an HTTP-date, or not valid in its encoding
+      nil
     end
 
     def retryable?

data/lib/clicksend/instrumentation.rb

@@ -29,6 +29,12 @@ module Clicksend
   # without its query string; for some endpoints it includes a message ID.
   #
   # The instrumenter is called on the caller's thread and must be thread-safe.
+  # For request.clicksend it must run the block exactly once, to completion,
+  # before it returns. If it returns without running it, the call raises
+  # ConfigurationError and the block never sends, even if called later. If
+  # it returns while the block is still running (on another thread), the
+  # call raises a ConfigurationError that, for a request that is not
+  # idempotent, is also a Clicksend::AmbiguousRequestError.
   module Instrumentation
     # The default: runs the block and publishes nothing.
     module Null

data/lib/clicksend/page.rb

@@ -30,8 +30,9 @@ module Clicksend
       if limit && !(limit.is_a?(Integer) && LIMITS.cover?(limit))
         raise ArgumentError, "limit must be an Integer between #{LIMITS.min} and #{LIMITS.max} (ClickSend's documented range)"
       end
+      raise ArgumentError, "query must be a Hash" unless query.nil? || query.is_a?(Hash)
 
-      query = query.transform_keys(&:to_s)
+      query = (query || {}).transform_keys(&:to_s)
       response = client.request(:get, path, query: query.merge("page" => page, "limit" => limit).compact, operation: operation)
       fetch_page = ->(number) { fetch(client, path, query: query, page: number, limit: limit, operation: operation, &build_item) }
       from_response(response, fetch_page, &build_item)
@@ -49,6 +50,10 @@ module Clicksend
       numbers = %w[total per_page current_page last_page].to_h do |key|
         value = Integer(data[key], exception: false) if data[key].is_a?(Integer) || data[key].is_a?(String)
         raise MalformedResponseError.new("Paginated response is missing #{key}", http_status: response.http_status, body: response.body) if value.nil?
+        # Pages are numbered from 1 (the page parameter defaults to 1); counts can be 0.
+        if value < ((key == "current_page") ? 1 : 0)
+          raise MalformedResponseError.new("Paginated response has an invalid #{key}: #{value}", http_status: response.http_status, body: response.body)
+        end
 
         [key.to_sym, value]
       end

data/lib/clicksend/resources/sms.rb

@@ -12,6 +12,13 @@ module Clicksend
       DEFAULT_FIELDS = (MESSAGE_FIELDS - %i[to list_id body]).freeze
       MESSAGE_ID = /\A[A-Za-z0-9-]+\z/
       HISTORY_ORDERS = %i[asc desc].freeze
+      # History stores recipients in E.164 ("+61411111111"); a local or
+      # unprefixed number would not match the rows it is compared with.
+      E164 = /\A\+[1-9]\d{5,14}\z/
+      # Seconds #search_history widens its window by, on each side. ClickSend
+      # doesn't document whether date_from/date_to are inclusive or which clock
+      # history dates come from; a wider window only finds more rows.
+      HISTORY_SEARCH_MARGIN = 300
 
       def initialize(client)
         @client = client
@@ -202,6 +209,76 @@ module Clicksend
         end
       end
 
+      # The history rows ClickSend shows *now* for messages you sent to +to+
+      # with exactly this +custom_string+ since +sent_after+, oldest first.
+      # Meant for the question an AmbiguousRequestError from #deliver leaves
+      # open: did ClickSend accept that message after all?
+      #
+      #   records = client.sms.search_history(to: user.phone, custom_string: "otp:#{attempt.id}", sent_after: started_at)
+      #   records.any? # => true: ClickSend accepted it (see record.status)
+      #                #    false: nothing is known yet; this is NOT proof it wasn't sent
+      #
+      # ClickSend doesn't say how soon an accepted message appears in history,
+      # keeps history for about four months, and can de-identify recipients, so
+      # an empty result never means "not sent". Never resend automatically
+      # because of it.
+      #
+      # Queries GET /v3/sms/history with +q=to:+ and a date window widened by
+      # HISTORY_SEARCH_MARGIN seconds on each side, 100 rows per page (each
+      # page is one request against ClickSend's undocumented rate limits),
+      # then keeps outbound rows whose +to+ and +custom_string+ equal yours:
+      # +custom_string+ is not a documented filter, and ClickSend calls a +q+
+      # value a "text or keyword", not an exact match.
+      #
+      # @param to [String] the recipient, in E.164 ("+61411111111")
+      # @param custom_string [String] the reference you passed to #deliver
+      # @param sent_after [Time, Integer] a time before the send started
+      # @param sent_before [Time, Integer, nil] a time after it ended (default: no upper bound)
+      # @return [Array<Clicksend::SMS::HistoryRecord>] possibly several (a
+      #   reference reused across sends), possibly none
+      def search_history(to:, custom_string:, sent_after:, sent_before: nil)
+        unless to.is_a?(String) && to.match?(E164)
+          raise ArgumentError, "to must be an E.164 number such as \"+61411111111\" (history stores recipients that way), got #{to.inspect}"
+        end
+        raise ArgumentError, "custom_string must be a non-empty String" unless custom_string.is_a?(String) && !custom_string.empty?
+
+        from = unix_time(sent_after, "sent_after")
+        to_time = unix_time(sent_before, "sent_before") unless sent_before.nil?
+        raise ArgumentError, "sent_before must not be earlier than sent_after" if to_time && to_time < from
+
+        history(to: to, date_from: from - HISTORY_SEARCH_MARGIN, date_to: (to_time + HISTORY_SEARCH_MARGIN if to_time), limit: Page::LIMITS.max)
+          .auto_paging_each
+          .select { |record| record.outbound? && record.to == to && record.custom_string == custom_string }
+      end
+
+      # Cancels one scheduled SMS (PUT /v3/sms/{message_id}/cancel). Returns
+      # nil when ClickSend answers SUCCESS; ClickSend's response carries no
+      # data (+data+ is deprecated and always null).
+      #
+      # *Experimental*: the SUCCESS answer is covered by contract specs but
+      # has not been observed live. ClickSend's free test number completes
+      # scheduled messages at once, and cancelling them answered 404
+      # NOT_FOUND (raised as NotFoundError), as did a repeated cancel and an
+      # unknown ID. A NotFoundError therefore doesn't say why, and doesn't
+      # mean the message was sent.
+      #
+      #   message = client.sms.deliver(to: user.phone, body: "Reminder", schedule: Time.now + 3600)
+      #   client.sms.cancel(message.message_id)
+      #
+      # Don't treat "no exception" as "the message will not go out": check
+      # #history(message_id:) for status "Cancelled" when it matters.
+      #
+      # Not retried after a timeout or 5xx (ClickSend documents no idempotency
+      # for it). Such a failure is a Clicksend::AmbiguousRequestError: the
+      # message may or may not have been cancelled. Calling #cancel again
+      # cannot send anything, but may raise even if the first call worked;
+      # #history(message_id:) tells you which.
+      # @return [nil]
+      def cancel(message_id)
+        @client.request(:put, "/v3/sms/#{message_id!(message_id)}/cancel", operation: "sms.cancel")
+        nil
+      end
+
       def inspect
         "#<#{self.class.name}>"
       end

data/lib/clicksend/retry_policy.rb

@@ -29,7 +29,8 @@ module Clicksend
     # @param max_delay [Numeric] seconds; the backoff ceiling never exceeds it
     # @param max_retry_after [Numeric] longest Retry-After (seconds) worth
     #   waiting for; a longer one is raised as RateLimitError instead of
-    #   blocking the caller
+    #   blocking the caller. Even with Float::INFINITY, a wait longer than
+    #   Kernel.sleep accepts (2**31 - 1 seconds) is raised, not retried.
     def initialize(max_retries: 2, base_delay: 0.5, max_delay: 8.0, max_retry_after: 30, random: Random)
       unless max_retries.is_a?(Integer) && max_retries >= 0
         raise ConfigurationError, "max_retries must be a non-negative Integer"
@@ -48,7 +49,9 @@ module Clicksend
 
     # @param error [Clicksend::Error] the failure of attempt number +attempt+
     #   (0-based); already known to be safe to retry
-    # @return [Numeric, nil] seconds to wait before retrying, or nil to give up
+    # @return [Numeric, nil] seconds to wait before retrying, or nil to give up.
+    #   The connection also gives up on anything that is not a number of
+    #   seconds between 0 and 2**31 - 1 (Kernel.sleep's limit).
     def delay(error:, attempt:, **)
       return if attempt >= max_retries
       return backoff(attempt) unless error.is_a?(RateLimitError)

data/lib/clicksend/testing/failure.rb

@@ -13,19 +13,25 @@ module Clicksend
         timeout: [TimeoutError, nil, "Timed out waiting for the response"],
         connection_reset: [ConnectionError, nil, "Connection reset by peer"]
       }.freeze
+      OUTCOMES = (CONNECTION.keys + [:interrupted]).freeze
 
       attr_reader :times
 
       def initialize(outcome, status:, processed:, retry_after:, path:, method:, times:)
         label = outcome ? outcome.inspect : "status: #{status.inspect}"
         if outcome.nil? == status.nil?
-          raise ArgumentError, "fail_next needs an outcome (#{CONNECTION.keys.map(&:inspect).join(", ")}) or status:, not both"
+          raise ArgumentError, "fail_next needs an outcome (#{OUTCOMES.map(&:inspect).join(", ")}) or status:, not both"
         end
         raise ArgumentError, "retry_after: only applies to status: 429" if retry_after && status != 429
 
-        if outcome
+        if outcome == :interrupted
+          # The worker is stopped mid-send: whether ClickSend got the request
+          # first is exactly what the application can't know.
+          @interrupted = true
+          ambiguous = true
+        elsif outcome
           @error_class, @request_sent, @message = CONNECTION.fetch(outcome) do
-            raise ArgumentError, "unknown fail_next outcome #{outcome.inspect}; use one of #{CONNECTION.keys.map(&:inspect).join(", ")} or status:"
+            raise ArgumentError, "unknown fail_next outcome #{outcome.inspect}; use one of #{OUTCOMES.map(&:inspect).join(", ")} or status:"
           end
           ambiguous = @request_sent.nil?
         else
@@ -65,9 +71,14 @@ module Clicksend
         (@path.nil? || @path == request.path) && (@method.nil? || @method == request.http_method)
       end
 
-      # Raises the connection error, or returns the error response.
+      # Raises the connection error or the SimulatedInterrupt, or returns the
+      # error response.
       # @return [Clicksend::Transport::Response]
       def trigger
+        if @interrupted
+          raise SimulatedInterrupt, "Worker interrupted mid-request, #{@processed ? "after" : "before"} ClickSend processed it " \
+            "(simulated by Clicksend::Testing::FakeAPI#fail_next(:interrupted); this models the job runner, not ClickSend)"
+        end
         raise @error_class.new("#{@message} (simulated by Clicksend::Testing::FakeAPI)", request_sent: @request_sent) if @error_class
         return Payloads.error(@status) unless @status == 429