clicksend 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7857a1233302a7bc4a7056dba951907dd525d2c9fa7b1760fda426426a01f82
-  data.tar.gz: 910dbea50624ca6652f1c88ef34fc511df31ed929352225161592122a259d648
+  metadata.gz: 73ecf8d49a2a4fa5ffceef490e0f6ebaeb3ccb903286f5b80f31ae82a1a22d30
+  data.tar.gz: 51cde5f40184bcd8b80b9bcf404076b48b17f9904eb26cb8aab781356980666c
 SHA512:
-  metadata.gz: e2fa280f9073402b2512b9c47b7d49b42a1e7f98983b2ce077b3eb6299cf210ca5c565fc611e8dcceeed72a865dd36f231d579bd1cb28e3c9b5e04f85f7d55ff
-  data.tar.gz: 1af0e0028c6093e4c40b6a1c083c15e1c339cf08d8ac1fe52c614919e5602c42163a20ab757ca214d02f80f74802a82c0c8b92ade79f84bca1681d7c71384e86
+  metadata.gz: 90b530124f465bf299cdc25acf770239f1963c9b87e96cc7a9685d8fbfc1029ec72c050e07e0882d2d7b65bc9244e74dfd36934b30c159f616b2e63151d6f086
+  data.tar.gz: d14f63a3e5a1ba4ee4f862b82902fcae71f079b5a1d55f06bc2b784c474e19612e37078f88f9382ad3ab48ba3f41568158b57f5fb0bd3757af5b03251395033b

data/CHANGELOG.md

@@ -4,6 +4,126 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-10-06
+
+Failure semantics, observability and testing support for production messaging. Mostly additive;
+read "Changed" before upgrading. Two additions are **experimental** and may change in a minor
+release: `Clicksend::Webhook` and `Clicksend::RateLimit`, because both rest on behaviour ClickSend
+doesn't document.
+
+Retry safety is unchanged in principle and stricter in practice. ClickSend has no idempotency key,
+so a send that may already have been processed is never repeated automatically, and such failures
+are now marked as ambiguous. This reduces the risk of duplicate SMS; it is not a guarantee against
+every possible duplicate (for example, a job runner re-running a job after a crash).
+
+### Added
+
+- **Explicit ambiguity.** When a request that is not safe to repeat (such as an SMS send) fails
+  in a way that ClickSend may still have processed, the error is extended with
+  `Clicksend::AmbiguousRequestError`. That covers:
+  - a timeout or reset after the request may have been written;
+  - a 5xx;
+  - an error reported inside a 2xx body;
+  - a 2xx answer the gem can't read, including a send result without a per-message status.
+
+  The error keeps its class, so existing `rescue` clauses still work. `Error#ambiguous?` is the
+  predicate. (A `dup` of the error loses the mark; `clone` and re-raising keep it.)
+- **Request context on errors and responses.** `Error#request` and `Response#request` return a
+  `Clicksend::RequestInfo` with `http_method`, `path` (no query string or fragment), `operation`
+  (e.g. `"sms.deliver"`), `idempotent` and `attempts`. `Response#request` is not a `Data`
+  member, so `Response` equality, `to_h` and pattern matching are unchanged from 1.0.
+- `Error#retryable?`: whether repeating the same request later is both safe and might succeed.
+- **Retry configuration.** `Clicksend::RetryPolicy` is public:
+  `Client.new(retry_policy: RetryPolicy.new(max_retries:, base_delay:, max_delay:, max_retry_after:))`.
+  The rule deciding *which* failures may be retried lives in the connection and cannot be
+  changed by any policy, and the connection enforces the policy's own `max_retries`.
+- **Rate limits (experimental).** `Response#rate_limit` and `APIError#rate_limit` return a
+  `Clicksend::RateLimit` (`limit`, `remaining`, `reset_in`) from the rate-limit headers observed
+  live on `GET /v3/account`. They are nil when ClickSend sends none.
+- **Instrumentation.** `Client.new(instrumenter:)` accepts `ActiveSupport::Notifications` or any
+  object with the same `instrument` signature that yields once. It publishes `request.clicksend`
+  and `retry.clicksend`. Payloads never include credentials, query strings or bodies, and the
+  wrapped methods' paths contain no phone numbers or message text. `Client#request` and
+  `#paginate` take an optional `operation:` label.
+- **Message history.** `sms.history(date_from:, date_to:, to:/from:/status:/message_id:, order:)`
+  returns a page of `Clicksend::SMS::HistoryRecord`, whose `delivered?`, `failed?` and `pending?`
+  follow ClickSend's "SMS error codes" article and are all false when a row can't be classified
+  (e.g. "Completed" with no gateway code, as observed live). ClickSend documents no way to look up
+  a send by your own reference; history, filtered by recipient and matched on `custom_string`, is
+  the closest. The README explains why a missing row is not proof that nothing was sent.
+- **Webhooks (experimental).** `Clicksend::Webhook.parse_receipt`, `.parse_inbound` and `.parse`
+  turn pushed receipts and replies into `SMS::Receipt` and `SMS::InboundMessage`. ClickSend
+  documents no way to authenticate pushes, so there is deliberately no verification method; the
+  README explains how to secure the endpoint. No real push has been captured yet.
+- **Testing.** `require "clicksend/testing"` adds `Clicksend::Testing::FakeAPI`, an in-memory
+  ClickSend you plug in as the transport, covering sends, receipts, replies and the account. It
+  records sent messages and can inject failures, including ambiguous ones with an explicit
+  `processed:` flag. It deliberately doesn't serve history; stub it. Mistakes in stubs surface
+  as `Clicksend::Testing::StubError` (not a `StandardError`), never as a simulated ClickSend
+  failure.
+
+### Changed
+
+Behaviour an existing 1.0 application may notice:
+
+- **Mark-read without a cutoff is no longer retried.** `sms.mark_receipts_read` and
+  `sms.mark_inbound_read` with no `before:` mark *everything* read at the moment ClickSend
+  processes the call. Retrying after an unknown outcome could hide items that arrived in between.
+  With `before:` they are still retried.
+- **Error messages end with the request they came from**, e.g. `HTTP 500 (POST /v3/sms/send)`.
+  Code that matched the exact message text needs updating. `MessageRejected` now carries
+  `#request` too.
+- **Unreadable 2xx answers to sends are ambiguous.** Before, they were plain
+  `MalformedResponseError`s. That covers `deliver` and `deliver_batch`, including a message
+  without a status, which 1.0 reported as a rejection (`MessageRejected` with a nil status, or
+  in `Batch#rejected`).
+- **Custom transports:**
+  - An exception that is not a `Clicksend::Error` becomes a `ConnectionError` that may have been
+    sent. It is ambiguous for a send, retried for idempotent requests, and keeps the original as
+    `#cause`; `rescue MyTransportError` around client calls no longer matches.
+  - Any other `Clicksend::Error` raised by a transport is treated as an unknown outcome.
+  - A response without a valid HTTP status, or an unexpected 1xx/3xx, is ambiguous for a send
+    instead of being a rejection.
+  - Exceptions raised by transports are copied before context is added.
+- **Loggers and instrumenters cannot change a result.** A logger or instrumenter that raises
+  after a request completes is logged and ignored. An instrumenter that never runs the block
+  raises `ConfigurationError`, and one that runs it twice can't send twice.
+- **Configuration:**
+  - `Client.new(max_retries:)` and `retry_policy:` are mutually exclusive. `Client#with` replaces
+    one with the other, and `max_retries: nil` now means the default.
+  - `RetryPolicy.new` validates its arguments (`ConfigurationError`) and returns a frozen policy.
+  - `Client#request(idempotent:)` honours only `true`; other truthy values, such as `1` or
+    `"false"`, no longer make a request retryable.
+
+### Compatibility
+
+- Ruby 3.3 or newer, as before; tested on 3.3, 3.4 and 4.0, with a Ruby head canary in CI.
+- Faraday 2 remains the only runtime dependency. ActiveSupport is used only in this gem's own
+  tests; `instrumenter:` duck-types it.
+- No public method or class from 1.0 was removed. `require "clicksend/testing"` is opt-in and
+  not loaded by `require "clicksend"`.
+
+### Verification
+
+- Unit, integration (local real-socket servers) and contract specs cover the new behaviour.
+  Contract specs check the wrapped operations, the fields the models read, and the documented
+  page-size range against ClickSend's published OpenAPI files.
+- Live checks on 2026-10-06 were read-only: `sms.history` filtered to ClickSend's test number,
+  and the rate-limit headers on `GET /v3/account`. No SMS was sent.
+- **Not verified live:** a webhook push (none has been captured), and a delivery receipt. The
+  test number produced none, as ClickSend's legacy docs say it won't. Both are parsed according
+  to ClickSend's published schemas and archived documentation.
+
+### Documentation
+
+- README: positioning, unknown send outcomes and reconciliation, webhooks, history, background
+  jobs (including at-least-once job runners), instrumentation, and rate limits. Behaviour that
+  ClickSend doesn't document is labelled as inferred or observed.
+- API notes: a review of all 34 of ClickSend's OpenAPI sections plus the archived push
+  documentation; read-only live checks of history and rate-limit headers on 2026-10-06.
+- `design/1.1-audit-and-roadmap.md`: the audit, the decisions taken, the features rejected, and
+  the reviews.
+
 ## [1.0.0] - 2026-10-05
 
 No changes to the library's behaviour or public API since 1.0.0.rc1.
@@ -72,6 +192,7 @@ A rewrite for ClickSend's REST v3 API and modern Ruby. See [MIGRATING.md](MIGRAT
 - Last release of the original gem: send SMS, poll replies and delivery reports, and check
   the balance through ClickSend's v2 API.
 
+[1.1.0]: https://github.com/prayantr/clicksend/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/prayantr/clicksend/compare/v1.0.0.rc1...v1.0.0
 [1.0.0.rc1]: https://github.com/prayantr/clicksend/compare/c99edc5...v1.0.0.rc1
 [0.0.3]: https://github.com/prayantr/clicksend/tree/c99edc5