clicksend 1.0.0 → 1.1.0

data/README.md

@@ -1,37 +1,58 @@
 # clicksend
 
-A focused, idiomatic Ruby client for ClickSend messaging: sending SMS (single and batch),
-delivery receipts, replies and account balance, over ClickSend's REST v3 API.
-
-It is **not** a replacement for ClickSend's official, full-API SDK and doesn't try to be.
-Every other ClickSend endpoint can still be reached through the same client with
-[`client.request`](#calling-other-clicksend-endpoints).
-
-> **Unofficial.** Community-maintained; not affiliated with or endorsed by ClickSend.
->
-> **Status:** `1.0.0`, a rewrite of the 2014 `0.0.x` gem.
-> Upgrading? Read [MIGRATING.md](MIGRATING.md). The namespace changed from `ClickSend` to **`Clicksend`**.
+[![CI](https://github.com/prayantr/clicksend/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/prayantr/clicksend/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/clicksend)](https://rubygems.org/gems/clicksend)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+A focused, idiomatic Ruby client for production messaging workloads on ClickSend's REST v3 API:
+single and batch SMS, delivery receipts and replies (polled or pushed), message history and
+account balance.
+
+It is **not** another complete ClickSend SDK. ClickSend's official SDK wins on breadth. This gem
+concentrates on the messaging core and on what running it in production needs:
+- Timeouts are on by default, and errors are typed and say which request failed.
+- A message ClickSend refuses inside an HTTP 200 response is reported as an error, not
+  silently treated as sent.
+- Retries are designed to avoid sending a duplicate SMS. A missed retry is recoverable; a
+  duplicate SMS is not. When a send's outcome is unknown, the error says so
+  ([`AmbiguousRequestError`](#when-a-sends-outcome-is-unknown)), and history can help you check.
+- Instrumentation for ActiveSupport::Notifications, an in-memory fake ClickSend for your
+  tests, and parsers for ClickSend's webhooks.
+
+Endpoints it doesn't wrap are one [`client.request`](#calling-other-clicksend-endpoints) away,
+through the same safe request path ([which client should I use?](#which-client-should-i-use)).
 
 ```ruby
+require "clicksend"
+
 client = Clicksend::Client.new(username: ENV["CLICKSEND_USERNAME"], api_key: ENV["CLICKSEND_API_KEY"])
 
-message = client.sms.deliver(to: "+61411111111", body: "Your code is 481516", from: "Acme")
+message = client.sms.deliver(to: "+61411111111", body: "Your code is 481516")
 message.message_id # => "1ABC3200-C38C-6308-BE4B-C7C51D01DCF0"
 ```
 
+> **Stable (1.x)**. Unofficial: not affiliated with ClickSend.
+>
+> Upgrading from the 2014 `0.0.x` gem? Read [MIGRATING.md](MIGRATING.md). The namespace changed
+> from `ClickSend` to **`Clicksend`**.
+
 ## Contents
 
 - [Which client should I use?](#which-client-should-i-use)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Sending SMS](#sending-sms)
+- [When a send's outcome is unknown](#when-a-sends-outcome-is-unknown)
 - [Delivery receipts and replies](#delivery-receipts-and-replies)
+- [Webhooks](#webhooks)
+- [Message history](#message-history)
 - [Account balance](#account-balance)
 - [Pagination](#pagination)
 - [Errors](#errors)
-- [Timeouts and retries](#timeouts-and-retries)
+- [Timeouts, retries and rate limits](#timeouts-retries-and-rate-limits)
+- [Background jobs](#background-jobs)
 - [Calling other ClickSend endpoints](#calling-other-clicksend-endpoints)
-- [Logging and thread safety](#logging-and-thread-safety)
+- [Logging, instrumentation and thread safety](#logging-instrumentation-and-thread-safety)
 - [Testing your application](#testing-your-application)
 - [What is covered](#what-is-covered)
 - [Using it alongside the official SDK](#using-it-alongside-the-official-sdk)
@@ -42,27 +63,33 @@ message.message_id # => "1ABC3200-C38C-6308-BE4B-C7C51D01DCF0"
 
 | You want to… | Use |
 |---|---|
-| Send SMS from a Ruby app and track delivery and replies, with safe defaults | **this gem** |
-| Call the occasional ClickSend endpoint this gem doesn't wrap (price a message, cancel a scheduled one, list templates or history) from the same client | **this gem's [`client.request`](#calling-other-clicksend-endpoints)** |
+| Send SMS from a Ruby app and track delivery and replies, with safe defaults, typed errors, instrumentation and a test fake | **this gem** |
+| Call the occasional ClickSend endpoint this gem doesn't wrap (price a message, cancel a scheduled one, list templates) with the same authentication, timeouts, retry rules and errors | **this gem's [`client.request`](#calling-other-clicksend-endpoints)** |
 | Work with large parts of the API (email, campaigns, contacts, numbers, automations, subaccounts, and so on) with generated models for each | ClickSend's official SDK, [`clicksend_client`](https://rubygems.org/gems/clicksend_client) |
 
 The two gems can be used side by side ([namespaces differ](#using-it-alongside-the-official-sdk)).
 
-How they differ for the messaging core:
+Comparison with ClickSend's official SDK (`clicksend_client` 6.0.2, September 2026). This is
+a snapshot; the official SDK may have changed since.
 
-| | `clicksend` (this gem) | `clicksend_client` (official, 6.x) |
+| | `clicksend` (this gem) | `clicksend_client` 6.0.2 |
 |---|---|---|
 | Scope | SMS, receipts, replies, balance; `client.request` for anything else | Most of the API, generated from OpenAPI |
 | Timeouts | On by default (30s read, 5s connect) | Off by default (`timeout = 0`) |
-| Retries | Built in; never re-sends a message that may already have reached ClickSend | None |
+| Retries | Built in; designed not to re-send a message that may already have reached ClickSend | None |
 | A message refused inside an HTTP 200 | `deliver` raises `MessageRejected`; `deliver_batch` exposes `#rejected` | Left for you to check |
+| Errors | Typed by status, with the failed request, `retryable?` and `ambiguous?` | One `ApiError` with status, headers and body |
 | Pagination | `auto_paging_each` | Manual `page`/`limit` |
-| Configuration | Immutable client instances | Global `Configuration.default` |
+| Webhooks | `Clicksend::Webhook` parses receipts and replies | Not covered |
+| Testing | `Clicksend::Testing::FakeAPI`, an in-memory ClickSend | Not covered |
+| Instrumentation | ActiveSupport::Notifications events, without personal data | Not covered (debug mode prints credentials and bodies) |
+| Configuration | Immutable client instances | Global `Configuration.default` (per-instance possible) |
 | Runtime dependencies | Faraday 2 | Typhoeus (libcurl) |
 
 ## Installation
 
-Requires Ruby 3.3 or newer.
+Requires Ruby 3.3 or newer. Tested on Ruby 3.3, 3.4 and 4.0; support for a Ruby ends in a minor
+release after its end of life.
 
 ```sh
 gem install clicksend
@@ -96,9 +123,11 @@ A missing credential raises `Clicksend::ConfigurationError` straight away, not o
 | `timeout` | `30` | Seconds to wait for a response |
 | `open_timeout` | `5` | Seconds to wait for the connection |
 | `max_retries` | `2` | Retries for failures that are safe to retry; `0` disables them |
+| `retry_policy` | `RetryPolicy.new` | Backoff timing and retry budget ([details](#timeouts-retries-and-rate-limits)); instead of `max_retries` |
 | `logger` | `nil` | Any object with `#info`/`#warn`, e.g. `Rails.logger` |
+| `instrumenter` | none | e.g. `ActiveSupport::Notifications` ([events](#logging-instrumentation-and-thread-safety)) |
 | `base_url` | `https://rest.clicksend.com` | HTTPS only (HTTP is allowed for `localhost`) |
-| `adapter` | Net::HTTP | Faraday adapter, e.g. `[:net_http_persistent, {pool_size: 5}]` |
+| `adapter` | Net::HTTP | Faraday adapter; for persistent connections see [thread safety](#logging-instrumentation-and-thread-safety) |
 | `transport` | Faraday | Replaces the HTTP layer entirely (see [Testing](#testing-your-application)) |
 
 Clients are immutable. `with` returns a copy with some settings changed. That is useful for
@@ -124,7 +153,7 @@ CLICKSEND = Clicksend::Client.new(logger: Rails.logger)
 ```ruby
 message = client.sms.deliver(
   to: "+61411111111",              # E.164
-  body: "Your code is 481516",     # ClickSend detects Unicode and splits long messages
+  body: "Your code is 481516",     # long messages are split; Unicode needs the account's "Autodetect" setting
   from: "Acme",                    # optional: alpha tag, dedicated number or verified own number
   schedule: Time.now + 3600,       # optional: Time or Unix timestamp
   custom_string: "otp:user-42"     # optional: echoed back in receipts and replies
@@ -173,16 +202,57 @@ batch.total_price  # => "0.2376"
 ```
 
 `deliver_batch` never raises when only some messages fail; check `#rejected`.
-Each message needs `body` and exactly one of `to` or `list_id`.
+Each message needs `body` and exactly one of `to` or `list_id`. ClickSend doesn't document that
+results come back in request order, so match them to your own records by `custom_string`
+(or `to`), not by position.
+
+## When a send's outcome is unknown
+
+ClickSend's send endpoint accepts no idempotency key. If the connection drops or times out after
+the request was written, or ClickSend answers with a 5xx, the message may or may not have been
+accepted. The gem never retries such a send. It raises the error extended with
+`Clicksend::AmbiguousRequestError`:
+
+```ruby
+begin
+  client.sms.deliver(to: user.phone, body: text, custom_string: "otp:#{attempt.id}")
+rescue Clicksend::AmbiguousRequestError => e
+  e.class          # => Clicksend::TimeoutError (or ServerError, ConnectionError, MalformedResponseError,
+                   #    or any APIError ClickSend reported inside a 2xx answer)
+  e.request        # => #<Clicksend::RequestInfo POST /v3/sms/send operation="sms.deliver" idempotent=false attempts=1>
+  e.retryable?     # => false
+  # Decide before sending again: check history (below), or let the user ask for a new code.
+end
+```
+
+It is still the error class it was, so `rescue Clicksend::TimeoutError` keeps working.
+Failures the gem treats as not processed (a refused connection, a 429, a 4xx response, or a
+message ClickSend refused) are not ambiguous. Apart from the refused connection, that is an
+inference from ClickSend's documentation and observed behaviour, not a guarantee. An error ClickSend reports inside a 2xx
+answer is ambiguous whatever its code, because that behaviour is undocumented.
+
+To check, look the message up in [history](#message-history) by recipient and match your own
+`custom_string`:
+
+```ruby
+sent = client.sms.history(to: user.phone, date_from: started_at - 60)
+  .auto_paging_each.find { |record| record.custom_string == "otp:#{attempt.id}" }
+```
+
+ClickSend doesn't document how soon a sent message appears in history, so **a message missing
+from history is not proof that it wasn't sent**. Whether to resend is your decision: for a login
+code, letting the user request another is usually safer than resending automatically.
 
 ## Delivery receipts and replies
 
-ClickSend can push receipts and replies to a webhook, or you can poll for them. Polling
-needs rules with the **POLL** action for SMS receipts and inbound SMS. You can set these up
-in the dashboard or through the
-[automations API](https://developers.clicksend.com/docs/automations/sms).
+ClickSend can push receipts and replies to a [webhook](#webhooks), or you can poll for them.
+Polling needs rules with the **POLL** action for SMS receipts and inbound SMS. You can set these
+up in the dashboard or through the
+[automations API](https://developers.clicksend.com/docs/automations/sms). ClickSend's test
+numbers produced no receipt in our live check, and ClickSend's legacy v2 docs say none are generated.
 
 ```ruby
+started_at = Time.now
 client.sms.receipts.auto_paging_each do |receipt|
   receipt.message_id     # matches Message#message_id
   receipt.custom_string
@@ -190,24 +260,103 @@ client.sms.receipts.auto_paging_each do |receipt|
   receipt.failed?        # status_code 301 (see receipt.status_text / error_code)
   receipt.pending?       # status_code 200 or 300 (not final yet)
 end
-client.sms.mark_receipts_read(before: Time.now)
+client.sms.mark_receipts_read(before: started_at)
 
 client.sms.inbound.auto_paging_each do |reply|
   reply.from
   reply.body
   reply.original_message_id  # the message this replies to
 end
-client.sms.mark_inbound_read(before: Time.now)       # or every unread reply, with no argument
+client.sms.mark_inbound_read(before: started_at)     # or every unread reply, with no argument
 client.sms.mark_inbound_message_read(reply.message_id) # just one
 ```
 
 Status codes follow ClickSend's
 [SMS error codes](https://help.clicksend.com/en/articles/42318-sms-error-codes) article.
-`client.sms.receipt(message_id)` fetches a single receipt, including receipts already marked read.
+`client.sms.receipt(message_id)` fetches a single receipt, including receipts already marked read
+(as ClickSend documents).
+
+> These lists contain only **unread** items, and listing doesn't mark anything read. If you mark
+> items read while paging through them, later pages shift and you will skip some. Process the
+> pages first, then call `mark_*_read(before:)` with the time you started (not "now": a receipt
+> reported after you listed would also be covered by a later cutoff). Without `before:`,
+> ClickSend marks *everything* read, including items that arrived after you listed them, so that
+> form is never retried. There is no way to mark a single receipt read.
+
+## Webhooks
+
+ClickSend pushes receipts and replies to your URL through automation rules with the **URL**
+action. `Clicksend::Webhook` turns a push into the same models polling returns:
 
-> These lists contain only **unread** items. If you mark items read while paging through
-> them, later pages shift and you will skip some. Process the pages first, then call
-> `mark_*_read(before:)` with the time you started.
+```ruby
+# config/routes.rb: post "clicksend/:secret/receipts", to: "clicksend_webhooks#receipt"
+class ClicksendWebhooksController < ActionController::API
+  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) # => Clicksend::SMS::Receipt
+    TrackDeliveryJob.perform_later(receipt.message_id, receipt.status_code) # idempotent on both
+    head :ok
+  rescue Clicksend::Webhook::InvalidPayload
+    head :bad_request
+  end
+end
+```
+
+`Webhook.parse_inbound(params)` returns a `Clicksend::SMS::InboundMessage`, and `Webhook.parse`
+works out which of the two it was given. Pass the body parameters, not the route ones, so your
+secret isn't kept in `#raw`.
+
+> **Experimental.** ClickSend doesn't document the push format, and no real push has been captured
+> for this gem yet: the field names come from ClickSend's polling API and archived docs. The
+> `Clicksend::Webhook` API may change in a minor release.
+
+**ClickSend documents no way to authenticate webhooks.** There is no documented signature, shared
+secret or HMAC. ClickSend's current documentation lists no source IP addresses; archived help pages
+(around 2019–2021, no longer published) listed some and said pushes come from a fixed pool. That
+list can't be checked against today's infrastructure, so this gem doesn't support or recommend IP
+allowlisting. Treat anyone who learns the URL as able to send a fake receipt. This gem therefore
+offers no "verify" method. Instead:
+- put an unguessable secret in the URL, compare it in constant time, and use HTTPS. A secret in the
+  path appears in access logs (Rails logs the path, and proxies and APM tools often keep it), so
+  restrict who can read them, and filter `body`, `from` and `to` with `filter_parameter_logging`;
+- treat a push as a hint. A receipt can probably be confirmed with `client.sms.receipt(message_id)`
+  (not yet verified for an account with only URL rules), at one API call per check. An
+  inbound message can't be fetched by its ID through any wrapped or verified endpoint; the closest
+  check is `client.sms.history(from: number)`. Be careful acting on unconfirmed replies such as
+  "STOP";
+- handle pushes idempotently. Several rules can match, and (according to ClickSend's archived docs)
+  a non-200 answer is retried every 10 minutes, up to 10 times. Key inbound messages on
+  `message_id`. Key receipts on `message_id` **and** `status_code`: ClickSend's gateway codes include
+  states that aren't final (200, 300), so one message can legitimately produce more than one
+  receipt, and deduplicating on `message_id` alone could discard the final 201 or 301. When
+  receipts for a message disagree, prefer a final code;
+- answer 200 quickly and do the work in a job.
+
+Inbound rules post form fields by default, or use a query string (`webhook_type: "get"`) or JSON
+(`"json"`); for JSON, pass `JSON.parse(request.raw_post)` or Rails' parsed body parameters. Receipt
+pushes are form-encoded according to ClickSend's archived docs. The parsers use the field names of
+the polling API, which match the archived push documentation, and reject payloads with too many
+fields, oversized or non-UTF-8 values, or nested values in the fields they read. Pass a plain
+Hash of the body parameters rather than Rails' `params`, which also holds route parameters.
+
+## Message history
+
+```ruby
+client.sms.history(date_from: Time.now - 86_400, to: "+61411111111").auto_paging_each do |record|
+  record.direction      # "out" (sent) or "in" (received)
+  record.status         # "Sent", "Completed", "Failed", "Scheduled", ... (history statuses)
+  record.status_code    # the gateway code receipts use: 201 delivered, 301 failed; may be nil
+  record.custom_string
+end
+```
+
+For this endpoint ClickSend documents a single `q=field:value` filter. Its general search
+documentation also describes several comma-separated fields with an `operator`, but not for history,
+and that hasn't been verified here. So `history` takes at most one of `to:`, `from:`, `status:` and
+`message_id:`, plus `date_from:`, `date_to:` and `order:` (`:asc` or `:desc`). `custom_string` isn't
+a documented filter; match it yourself.
 
 ## Account balance
 
@@ -242,11 +391,11 @@ client.sms.receipts.auto_paging_each.first(250)  # stops fetching after 250 item
 Every error is a `Clicksend::Error`:
 
 ```
-Clicksend::Error
+Clicksend::Error              #request #retryable? #ambiguous?
 ├── ConfigurationError        missing credentials, invalid options
 ├── ConnectionError           no response: DNS, refused, TLS, reset   #request_may_have_been_sent?
 │   └── TimeoutError
-├── APIError                  #http_status #response_code #response_msg #headers #body
+├── APIError                  #http_status #response_code #response_msg #headers #body #rate_limit
 │   ├── ClientError           other 4xx
 │   │   ├── BadRequestError       400
 │   │   ├── AuthenticationError   401
@@ -255,15 +404,29 @@ Clicksend::Error
 │   │   └── RateLimitError        429   #retry_after
 │   └── ServerError           5xx
 ├── MalformedResponseError    not JSON, or missing documented fields
-└── MessageRejected           deliver: the message was refused   #status #result
+├── MessageRejected           deliver: the message was refused   #status #result
+└── Webhook::InvalidPayload   a push that can't be parsed
+
+Clicksend::AmbiguousRequestError (module)   extended onto any of the above when the outcome is unknown
 ```
 
+- `#request` is a `Clicksend::RequestInfo`: `http_method`, `path` (never the query string),
+  `operation` (e.g. `"sms.deliver"`), `idempotent` and `attempts`. The error message ends with
+  it: `HTTP 500 (POST /v3/sms/send)`.
+- `#retryable?` is true when repeating the same request later is safe *and* might work: a 429, a
+  connection that never reached ClickSend, or a timeout or 5xx on a request that is safe to
+  repeat. It is false for every ambiguous error, every other 4xx, and `MessageRejected`. (A
+  `THROTTLED` rejection means an identical message just went to the same recipient.)
+- `#ambiguous?` is true when a request that is not safe to repeat may have been processed. See
+  [When a send's outcome is unknown](#when-a-sends-outcome-is-unknown).
+
 `response_code` is ClickSend's application code, for example `INVALID_RECIPIENT`,
 `INSUFFICIENT_CREDIT` or `COUNTRY_NOT_ENABLED`; see the
 [list](https://developers.clicksend.com/docs/#application-status-codes). Errors keep the
-original exception as `#cause`, and their messages never include your credentials.
+original exception as `#cause`, and their messages never include your credentials, query
+strings or bodies.
 
-## Timeouts and retries
+## Timeouts, retries and rate limits
 
 Timeouts are always on (`timeout: 30`, `open_timeout: 5`). Failed requests are retried
 up to `max_retries` times, with exponential backoff and jitter, **only when retrying cannot
@@ -271,41 +434,111 @@ send something twice**:
 
 | Failure | Retried for |
 |---|---|
-| 429 Too Many Requests (waits for `Retry-After` if it is 30s or less) | every request: ClickSend did not process it |
+| 429 Too Many Requests (waits for `Retry-After` if it is 30s or less) | every request: documented as "cannot be served" |
 | Connection refused, DNS failure, connect timeout | every request: it never reached ClickSend |
-| Read timeout, connection reset, 5xx | idempotent requests only: `GET`s and the gem's mark-read calls |
+| Read timeout, connection reset, TLS error, 5xx | idempotent requests only: `GET`s, mark-read calls with `before:`, and marking one reply read |
+| An error reported inside a 2xx body; any other 4xx | never |
 
-ClickSend doesn't publish its rate limits. In testing on 2026-10-05, `GET /v3/account` allowed
-20 requests per roughly 60 seconds and answered 429 with `Retry-After` values of 20–39 seconds.
-A wait longer than 30 seconds isn't attempted; you get the `RateLimitError` and its `#retry_after`
-instead.
+A 429 is documented by ClickSend as a request that "cannot be served", so it is treated as not
+processed. That is an inference from the documentation, not a guarantee. When the gem can't tell
+whether a failure happened before or after the request was sent, it assumes after. A missed
+retry is recoverable; a duplicate SMS is not.
 
-Two more cases are never retried. An error that ClickSend reports only inside a 2xx
-response body is undocumented behaviour, so nothing is known about whether the request was
-processed. And when the gem can't tell whether a failure happened before or after the
-request was sent, it assumes after. A missed retry is recoverable; a duplicate SMS is not.
+The rules above are fixed. What you can tune is the timing and the budget:
 
-ClickSend's send endpoint has no idempotency key. So a send that times out is **not**
-retried, and you get a `Clicksend::TimeoutError` whose `request_may_have_been_sent?` is
-`true`. The message may or may not have gone out. Before sending again, check with your own
-`custom_string`:
+```ruby
+client = Clicksend::Client.new(
+  retry_policy: Clicksend::RetryPolicy.new(
+    max_retries: 3,        # default 2
+    base_delay: 0.5,       # seconds; the first backoff is 0.25-0.5s, doubling each time
+    max_delay: 8.0,        # cap on the backoff
+    max_retry_after: 10    # wait for a Retry-After of at most 10s (default 30); longer raises RateLimitError
+  )
+)
+```
+
+Any object with `max_retries` and `delay(error:, attempt:)` can be a policy. It is only asked
+about failures that are safe to retry, so no policy can make a send repeat.
+
+**Rate limits.** ClickSend doesn't publish its rate limits. In testing, `GET /v3/account` allowed
+20 requests per roughly 60 seconds, sent `x-ratelimit-limit`, `x-ratelimit-remaining` and
+`ratelimit-reset` headers, and answered 429 with `Retry-After` values of 20-39 seconds. Those
+headers are undocumented, but when they are present you can read them (**experimental**:
+`Clicksend::RateLimit` may change in a minor release if ClickSend changes the headers):
 
 ```ruby
-history = client.paginate("/v3/sms/history", query: {date_from: started_at.to_i})
-already_sent = history.auto_paging_each.any? { |m| m["custom_string"] == "otp:user-42" }
+response = client.request(:get, "/v3/account")
+response.rate_limit  # => #<data Clicksend::RateLimit limit=20, remaining=19, reset_in=60>, or nil
+response.request     # => #<Clicksend::RequestInfo GET /v3/account ... attempts=1>
+
+begin
+  client.account.fetch
+rescue Clicksend::RateLimitError => e
+  e.retry_after      # => 39
+  e.rate_limit       # the same fields, from the 429 response
+end
 ```
 
 These retries happen inside the gem. The default Net::HTTP adapter does no retrying of its
 own: Faraday sets `max_retries = 0`, and a test pins this. If you pass a different `adapter:`,
 check whether that library retries requests by itself.
 
+## Background jobs
+
+Job frameworks retry failed jobs, which can undo the gem's care about duplicates. Two rules keep a
+send job as safe as the gem can make it:
+- **Never let an ambiguous send be retried**, and make sure nothing after it raises.
+- **Other failed sends may be retried.** The gem treats them as not processed: refused
+  connections, 429s, 4xx responses and per-message rejections. For 4xx and rejections that is
+  how ClickSend behaves in practice, not something it documents.
+
+```ruby
+class SendSmsJob < ApplicationJob
+  self.log_arguments = false # don't put phone numbers or message text in job logs
+
+  # Rails checks these from the bottom up, so the more specific rule comes last.
+  retry_on Clicksend::Error, attempts: 5, wait: :polynomially_longer # treated as not processed
+  discard_on Clicksend::MessageRejected                               # ClickSend refused the message itself
+
+  def perform(notification_id)
+    notification = Notification.find(notification_id)
+    CLICKSEND.sms.deliver(to: notification.phone, body: notification.text, custom_string: "notification:#{notification_id}")
+  rescue Clicksend::AmbiguousRequestError
+    # The message may have gone out. Hand over to a reconciliation step, and make sure nothing
+    # here raises: an exception would make the job runner retry the send.
+    begin
+      ReconcileSmsJob.perform_later(notification_id) # e.g. checks sms.history for the reference
+    rescue => e
+      Rails.logger.error("SMS for notification #{notification_id}: outcome unknown, reconciliation not enqueued (#{e.class})")
+    end
+  end
+end
+```
+
+Ambiguous errors are rescued inside `perform`, so `retry_on` only sees errors the gem treats as
+not processed. When `retry_on` gives up, Rails re-raises the error and your queue backend may
+retry the job again.
+
+**Never wrap a send in `Timeout.timeout`.** It interrupts the thread at an arbitrary point, which can
+be after ClickSend has already received the message, and raises a plain `Timeout::Error`. That isn't
+a `Clicksend::Error` and isn't marked ambiguous, so neither the gem nor the recipe above can tell
+that the message may have gone out, and a job runner will retry the job and may send it twice. Use
+the client's own timeouts instead (for a job, e.g. `CLICKSEND.with(timeout: 10)`): a read timeout
+then raises an ambiguous `Clicksend::TimeoutError` that the recipe handles.
+
+**Job runners are at-least-once.** If a worker is killed or shut down mid-send (Sidekiq's default
+shutdown timeout, 25s, is shorter than the gem's 30s read timeout), the job runs again and the
+gem never sees the first attempt's outcome. If a duplicate matters, record that a send is in
+flight before calling `deliver`, and reconcile instead of sending when a job finds that record
+already there. The gem can't do this for you: only your database knows which jobs started.
+
 ## Calling other ClickSend endpoints
 
 This gem wraps a small part of ClickSend's API on purpose. Everything else is available through
 the same request path: same authentication, timeouts, retry rules, errors and parsing.
 
 ```ruby
-response = client.request(:post, "/v3/sms/price", body: {messages: [{to: "+61411111111", body: "Hi"}]}, idempotent: true)
+response = client.request(:post, "/v3/sms/price", body: {messages: [{to: "+61411111111", body: "Hi"}]}, operation: "sms.price")
 response.data           # the envelope's "data" (frozen Hash/Array)
 response.response_code  # => "SUCCESS"
 response.http_status; response.headers; response.body
@@ -314,16 +547,18 @@ client.request(:put, "/v3/sms/#{message_id}/cancel")
 client.request(:get, "/v3/sms/templates", query: {page: 2})
 
 # Any paginated list, as raw Hashes:
-client.paginate("/v3/sms/history", query: {date_from: (Time.now - 7 * 86_400).to_i}).auto_paging_each { |sms| ... }
+client.paginate("/v3/sms/templates").auto_paging_each { |template| ... }
 ```
 
 - Write paths exactly as in ClickSend's [API reference](https://developers.clicksend.com/docs/), starting with `/v3/`.
   Full URLs are rejected, so your credentials can't be sent to another host.
 - Pass `body:` as a Hash or Array. It is sent as JSON. `query:` values that are `nil` are left out.
+- `operation:` is an optional label for logs and [instrumentation](#logging-instrumentation-and-thread-safety).
 - Only `GET` requests are treated as idempotent. ClickSend also uses `POST` and `PUT` for actions like sending
-  and buying credit. Pass `idempotent: true` only for calls that are safe to repeat.
+  and buying credit. Pass `idempotent: true` only for calls that are safe to repeat. A non-idempotent call
+  whose outcome is unknown raises an error extended with `Clicksend::AmbiguousRequestError`, as a send does.
 
-## Logging and thread safety
+## Logging, instrumentation and thread safety
 
 With `logger:`, every HTTP attempt logs one line, plus a warning for each retry:
 
@@ -334,13 +569,123 @@ With `logger:`, every HTTP attempt logs one line, plus a warning for each retry:
 
 Lines never contain credentials, query strings, request bodies or response bodies.
 
-A `Clicksend::Client` is frozen after construction and holds no mutable state. The default
-Net::HTTP adapter opens a connection per request. Share one client across threads, Puma
-workers and Sidekiq jobs.
+With `instrumenter:`, the gem publishes events. Any object with
+`instrument(name, payload) { |payload| ... }` works; that is `ActiveSupport::Notifications`'
+signature, so in Rails:
+
+```ruby
+CLICKSEND = Clicksend::Client.new(logger: Rails.logger, instrumenter: ActiveSupport::Notifications)
+
+ActiveSupport::Notifications.subscribe("request.clicksend") do |event|
+  event.payload
+  # => {http_method: :post, path: "/v3/sms/send", operation: "sms.deliver", idempotent: false,
+  #     attempts: 1, http_status: 200, response_code: "SUCCESS", ambiguous: false}
+  StatsD.distribution("clicksend.request", event.duration, tags: ["operation:#{event.payload[:operation]}"])
+end
+```
+
+| Event | When | Payload |
+|---|---|---|
+| `request.clicksend` | around each call, retries included | `http_method`, `path`, `operation`, `idempotent`; on completion `attempts`, `http_status` (nil without a response), `response_code`, `ambiguous`. ActiveSupport adds `exception` on failure |
+| `retry.clicksend` | before each retry | `http_method`, `path`, `operation`, `attempt` (1 for the first retry), `delay`, `error_class`, `http_status` |
+
+Payloads never contain credentials, headers, query strings or bodies, and the wrapped methods' paths
+contain no phone numbers or message text. Paths and `operation:` labels you pass to `client.request`
+are reported as you wrote them, minus any query string or fragment. (An exception object attached
+by ActiveSupport carries the response body of an API error, as `#body` does.)
+
+**OpenTelemetry and other generic HTTP instrumentation.** Auto-instrumentation of Faraday or
+Net::HTTP (for example `opentelemetry-instrumentation-faraday`) works below this gem and records the
+full request URL, query string included. `sms.history(to: ...)` sends `q=to:+61...`, so recipients'
+phone numbers can end up in your traces. Configure that instrumentation to drop or sanitise URLs and
+query strings, or exclude ClickSend's host from it. ClickSend-specific tracing built on this gem's
+`request.clicksend` events doesn't have the problem, because those payloads never contain a query
+string. A dedicated adapter that does this (`clicksend-opentelemetry`) is planned but not released.
+
+A `Clicksend::Client` is frozen after construction and holds no mutable state. Share one client
+across threads, Puma workers and Sidekiq jobs. Loggers and instrumenters are called on the calling
+thread and must be thread-safe.
+
+The default Net::HTTP adapter opens a connection per request, which costs a TCP and TLS handshake
+each time. For high volumes, the `faraday-net_http_persistent` gem reuses connections:
+
+```ruby
+threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i # every thread that shares this client
+CLICKSEND = Clicksend::Client.new(adapter: [:net_http_persistent, {pool_size: threads}])
+```
+
+The pool must be **at least as large as the number of threads sharing the client** (Puma's
+threads, Sidekiq's concurrency). A thread that can't get a connection in time fails with a
+timeout, and the gem can't tell that nothing was sent, so a send fails as ambiguous. With this
+adapter, a refused connection or connect timeout is also reported as possibly sent. Neither case
+sends anything twice, but both can leave a message unsent that the default adapter would have
+retried. Build the client once (`with` creates a new pool), and note that this adapter isn't part
+of this gem's test suite.
 
 ## Testing your application
 
-**Stub HTTP.** Requests go through Net::HTTP by default, so [WebMock](https://github.com/bblimke/webmock) works:
+**Use the in-memory ClickSend.** `require "clicksend/testing"` (not loaded by default) adds
+`Clicksend::Testing::FakeAPI`. It replaces only the HTTP exchange, so your code runs against a
+real `Clicksend::Client`: argument validation, errors, retry rules and models are the production
+code paths. Nothing is sent and no network is used.
+
+```ruby
+require "clicksend/testing"
+
+fake = Clicksend::Testing::FakeAPI.new
+client = fake.client # a real Clicksend::Client using the fake; retries don't wait
+
+client.sms.deliver(to: "+61411111111", body: "Your code is 481516", custom_string: "otp:42")
+fake.sent_messages.map { |m| [m.to, m.custom_string] } # => [["+61411111111", "otp:42"]]
+fake.requests.last.path                                # => "/v3/sms/send" (headers are never kept)
+
+fake.reject(to: "+61400000000", status: "INVALID_RECIPIENT") # deliver raises MessageRejected
+fake.add_receipt(for: fake.sent_messages.last, status_code: 201)
+fake.add_inbound(reply_to: fake.sent_messages.last, body: "STOP")
+fake.stub(:get, "/v3/sms/templates") { |request| {"data" => {"data" => []}} } # any other endpoint
+fake.reset!
+```
+
+In your app, inject `fake.client` where you would use your real client. If your code builds its
+own client, give it the fake as its transport, with placeholder credentials and a retry policy
+that doesn't wait:
+
+```ruby
+Clicksend::Client.new(username: "test", api_key: "test", transport: fake,
+  retry_policy: Clicksend::RetryPolicy.new(base_delay: 0, max_delay: 0))
+```
+
+**Simulate failures, including the ambiguous ones.** For outcomes where it matters you must say
+whether ClickSend processed the request before the failure, which is exactly the question your
+code has to cope with:
+
+```ruby
+fake.fail_next(:timeout, processed: true)   # accepted, response lost: deliver raises AmbiguousRequestError, one message recorded
+fake.fail_next(:timeout, processed: false)  # never processed: same error, nothing recorded
+fake.fail_next(:connection_reset, processed: true)
+fake.fail_next(status: 500, processed: false)
+fake.fail_next(:connection_refused)         # never sent: the gem retries it transparently
+fake.fail_next(status: 429, retry_after: 0) # rate limited: retried
+fake.fail_next(status: 401)
+fake.fail_next(:timeout, processed: true, path: "/v3/sms/send", times: 2) # only matching requests
+```
+
+The fake also serves receipts, replies (marked read as ClickSend documents; whether the cutoff is
+inclusive is the fake's guess) and the account. Exceptions raised by your stub blocks surface as
+`Clicksend::Testing::StubError`, never as a simulated ClickSend failure.
+
+It deliberately **doesn't serve history**: ClickSend doesn't say how soon a sent message appears
+there, and an always-current fake history would let a "not in history, so resend" rule pass its
+tests and send twice in production. Stub `GET /v3/sms/history` with the rows each test needs.
+
+The fake simplifies, so don't let your tests depend on these:
+- Recipients that aren't 6 to 15 digits (optionally after `+`) get `INVALID_RECIPIENT`; ClickSend's
+  own rules decide in reality. It never answers `THROTTLED`, and test numbers always succeed.
+- The balance never changes, and message parts are estimated.
+
+It can stand in as a development "dry run" transport too.
+
+**Stub HTTP.** Requests go through Net::HTTP by default, so [WebMock](https://github.com/bblimke/webmock) also works:
 
 ```ruby
 stub_request(:post, "https://rest.clicksend.com/v3/sms/send")
@@ -350,25 +695,14 @@ stub_request(:post, "https://rest.clicksend.com/v3/sms/send")
   }.to_json)
 ```
 
-**Use ClickSend's test numbers.** These include `+61411111111`, `+14055555555` and `+447777777777`;
-see the [full list](https://developers.clicksend.com/docs/testing). Nothing is sent or charged.
-A test number only returns `SUCCESS` if its country is enabled for your account. Otherwise
-ClickSend answers with the per-message status `COUNTRY_NOT_ENABLED`, which `deliver` raises as
-`MessageRejected`.
+**Use ClickSend's test numbers** for checks against the real API. These include `+61411111111`,
+`+14055555555` and `+447777777777`; see the [full list](https://developers.clicksend.com/docs/testing).
+Nothing is sent or charged, and no delivery receipt is generated. A test number only returns
+`SUCCESS` if its country is enabled for your account. Otherwise ClickSend answers with the
+per-message status `COUNTRY_NOT_ENABLED`, which `deliver` raises as `MessageRejected`.
 
-**Replace the transport.** For tests that shouldn't touch HTTP at all, pass any object that
-responds to `call(method, path, query:, body:, headers:)` and returns a
-`Clicksend::Transport::Response`:
-
-```ruby
-FakeTransport = Struct.new(:responses) do
-  def call(method, path, query:, body:, headers:) = responses.shift
-end
-
-client = Clicksend::Client.new(username: "u", api_key: "k", transport: FakeTransport.new([
-  Clicksend::Transport::Response.new(status: 200, headers: {}, body: '{"data":{"balance":"5.00"}}')
-]))
-```
+**Write your own transport** if you need to: any object that responds to
+`call(method, path, query:, body:, headers:)` and returns a `Clicksend::Transport::Response`.
 
 ## What is covered
 
@@ -377,7 +711,10 @@ client = Clicksend::Client.new(username: "u", api_key: "k", transport: FakeTrans
 | Send SMS (single, batch, lists, scheduled) | `POST /v3/sms/send` | `sms.deliver`, `sms.deliver_batch` |
 | Delivery receipts | `GET /v3/sms/receipts[/{id}]`, `PUT /v3/sms/receipts-read` | `sms.receipts`, `sms.receipt`, `sms.mark_receipts_read` |
 | Replies (inbound SMS) | `GET /v3/sms/inbound`, `PUT /v3/sms/inbound-read[/{id}]` | `sms.inbound`, `sms.mark_inbound_read`, `sms.mark_inbound_message_read` |
+| Message history | `GET /v3/sms/history` | `sms.history` |
+| Pushed receipts and replies (webhooks) | automation rules with the URL action | `Clicksend::Webhook` |
 | Account balance | `GET /v3/account` | `account.fetch` |
+| Testing without the network | | `Clicksend::Testing::FakeAPI` |
 | RCS | sent through `/v3/sms/send` once ClickSend enables it on your account | `sms.deliver` |
 | Everything else | [API reference](https://developers.clicksend.com/docs/) | `client.request`, `client.paginate` |