didww-otp_verification 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95cc4c0b5d246e12eeb76854405106c8ef277a4790dbbfee8620f6984a6074a8
-  data.tar.gz: 5d157aba75750f9b9a605b1d114dfdd289dbc9ea949b3d1d2a0a5636da12c0a9
+  metadata.gz: b8f7f380aca63b49a1e661d0834f16f7d94af7fdacf63e1e54d7ddacac1e8a79
+  data.tar.gz: e1920bc8b4994f0abe90fc7a93b43339a1e5dc2d492983e93625a24b70f23285
 SHA512:
-  metadata.gz: fa0921c7b444d6efaba56f12c050d68b408c98f956a21fd3656c3672eabc8c73415a8d3fb5e16bc9c32f7bbcfca930856d5cc1c80fabc0f98a758e40bfb22d59
-  data.tar.gz: aa033d4b455850aa7ed1c5a79861bfb35a303fd8e677387ebf1d77be9ccb78468cbb5bcc4d7fe1438995a3277faa2eae67c07d689068aa5fa531bd54627cab62
+  metadata.gz: c8867b191e13078948e4427c2b5321b365dd52f79481f5ff4e81f56eae59466f8f0a006c6979030aebc8e6ac1432c1bd6d11f9ac35d9637b7c1a7a7dd104d918
+  data.tar.gz: 330d1aea846c2104f48db034df7eed4af4e15bc47c045c086068db419bcbfffa4271d156f1da818303353d0b6f9ae53ead2c56f4df2159502824023990c3b781

data/CHANGELOG.md

@@ -6,6 +6,29 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html): from 1.0.0 onwards a breaking change
 to the public surface requires a major version.
 
+## [1.1.0] — 2026-10
+
+### Added
+
+- **A User-Agent header.** Every request now sends
+  `User-Agent: didww-verification-ruby/<version>`.
+- **`code_length` on the `sms` and `callout` blocks**, readable via
+  `Verification#sms_code_length`/`#callout_code_length` — the length of the
+  generated code, 4–8 digits, set per application.
+- **`RateLimitedError` (429, `destination_in_cooldown`)**, raised when
+  `start_verification` repeats for the same app and destination inside the
+  API's cooldown window. `#retry_after` reads the `Retry-After` header in
+  seconds (`nil` if missing or unparseable). The SDK never auto-retries it.
+
+### Changed
+
+- Corrected README claims that the verification lifetime is a fixed 120 s /
+  2-minute window: it is the per-app `code_expiry` setting (60–600 s, default
+  300), which `sms_interception_timeout` also equals.
+- A 429 now raises `RateLimitedError`, an `APIError` subclass, instead of the
+  `APIError` base class. `rescue APIError` still catches it, but a strict
+  `e.instance_of?(APIError)` check no longer matches a 429.
+
 ## [1.0.0] — 2026-09
 
 First public release.

data/README.md

@@ -33,7 +33,8 @@ verification.status   # => "pending"
 verification.pending? # => true
 verification.to_h     # => raw response data Hash with string keys
 
-# Report the code the user entered (counts as an attempt; max 3, expires in 2 min)
+# Report the code the user entered (counts as an attempt; max 3, expires per
+# the app's code lifetime)
 result = client.report_verification(
   verification.id, delivery_method: "sms", code: "1234"
 )
@@ -103,11 +104,13 @@ field or as a whole:
 ```ruby
 v.sms_template             # => "Your code is {{CODE}}"
 v.sms_language             # => "en-US"
-v.sms_interception_timeout # => 120
+v.sms_interception_timeout # => 300
+v.sms_code_length          # => 6
 v.sms_app_hash             # => "A1b2C3d4E5f", or nil if none was stored
 v.sms                      # => the raw block, or nil on a callout verification
 
 v.callout_language         # => "de-DE"
+v.callout_code_length      # => 6
 v.callout                  # => the raw block, or nil on an sms verification
 ```
 
@@ -119,8 +122,11 @@ because the two catalogues are separate, a tag honoured on `sms` can still fall
 back on `callout`.
 
 `sms_interception_timeout` is how many seconds a client should keep an on-device
-SMS listener armed. It is a fixed budget, not a countdown, and **not** a deadline
-for the verification — manual entry keeps working until `expires_at`.
+SMS listener armed. It equals the app's configured code lifetime (60–600 s,
+default 300) and is **not** a deadline for the verification itself — manual
+entry keeps working until `expires_at`.
+`sms_code_length`/`callout_code_length` is the length of this verification's
+code, 4–8 digits, set per application (default 6).
 `sms_app_hash` is echoed back only when one was stored, so it reflects what was
 persisted rather than what was requested.
 
@@ -197,6 +203,8 @@ DIDWW::OTPVerification::Client.new(
 ) { |conn| conn.proxy = "http://proxy:3128" }
 ```
 
+Every request carries `User-Agent: didww-verification-ruby/<version>`.
+
 ## Auth modes
 
 | Mode               | Header                                          | Secret   | Notes                              |
@@ -328,7 +336,7 @@ carries `error_code` (switch on it) and `error_detail` (display it). These are
 | `pending`  | no       | `nil` — on its way, or awaiting a report                                                       |
 | `verified` | yes      | `nil`                                                                                          |
 | `failed`   | yes      | `too_many_attempts`, `dispatch_failed`, `stale_dispatch`, `superseded`, `application_deleted`   |
-| `expired`  | yes      | `expired` — past the 2-minute window                                                           |
+| `expired`  | yes      | `expired` — past the application's code lifetime (60–600 s, default 300)                       |
 | `denied`   | yes      | `denied_by_callback`, `denied_missing_callback_url`, `denied_invalid_callback_response`         |
 
 `superseded` means a newer `start_verification` for the same number retired this
@@ -362,6 +370,7 @@ Non-2xx responses raise a typed error under `DIDWW::OTPVerification::Error`:
 | `BalanceInsufficientError` | 402       | `balance_insufficient`                |
 | `NotFoundError`            | 404       | `not_found`                           |
 | `ValidationError`          | 400 / 422 | `parameter_missing` / per-field codes |
+| `RateLimitedError`         | 429       | `destination_in_cooldown`             |
 | `ServerError`              | 5xx       | `internal_error`                      |
 
 Every error carries the API's coded envelope: `#errors` is an array of
@@ -390,6 +399,12 @@ end
 The SDK does **not** auto-retry. If you add `faraday-retry`, exclude `POST`
 (double-charges) and `PATCH` (each report counts against the 3-attempt limit).
 
+A `start_verification` repeated too soon for the same app and destination
+raises `RateLimitedError` (429, `destination_in_cooldown`) — a short per-number
+cooldown (currently 30 s). `#retry_after` gives the wait in seconds (`nil` if
+the `Retry-After` header is missing or unparseable) — wait and call again
+yourself; never auto-retry it.
+
 ## Development
 
 Development is pinned to the Ruby in `.ruby-version`; the gem itself supports

data/lib/didww/otp_verification/client.rb

@@ -21,6 +21,7 @@ module DIDWW
     # Unspecified arguments fall back to DIDWW::OTPVerification.configuration.
     class Client
       API_PREFIX = "/api/v1".freeze
+      USER_AGENT = "didww-verification-ruby/#{VERSION}".freeze
 
       attr_reader :key, :auth_mode, :base_url
 
@@ -110,11 +111,9 @@ module DIDWW
         end
 
         errors = parse_errors(body)
-        raise error_class(response.status).new(
-          status: response.status,
-          errors: errors,
-          response: response
-        )
+        klass = error_class(response.status)
+        extra = (klass == RateLimitedError) ? {retry_after: parse_retry_after(response)} : {}
+        raise klass.new(status: response.status, errors: errors, response: response, **extra)
       end
 
       # Map the {"errors": [{"code", "detail"}]} envelope to ErrorItem objects.
@@ -131,12 +130,20 @@ module DIDWW
         end
       end
 
+      # @return [Integer, nil] the Retry-After header in seconds, nil if
+      #   missing or not a plain non-negative integer (e.g. an HTTP-date).
+      def parse_retry_after(response)
+        value = response.headers["Retry-After"].to_s
+        Integer(value, 10) if value.match?(/\A\d+\z/)
+      end
+
       def error_class(status)
         case status
         when 401 then UnauthorizedError
         when 402 then BalanceInsufficientError
         when 404 then NotFoundError
         when 400, 422 then ValidationError
+        when 429 then RateLimitedError
         when 500..599 then ServerError
         else APIError
         end
@@ -147,6 +154,8 @@ module DIDWW
           conn.request :json
           conn.response :json, content_type: /\bjson$/
           @faraday_block&.call(conn)
+          # After the caller's block, so the block cannot replace it.
+          conn.headers["User-Agent"] = USER_AGENT
           # Auth (signing) must be installed last so it sees the final request
           # bytes/headers/path, after any user middleware from @faraday_block.
           apply_auth(conn)

data/lib/didww/otp_verification/errors.rb

@@ -48,6 +48,20 @@ module DIDWW
     # 400 Bad Request / 422 Unprocessable Content (validation errors in +errors+).
     class ValidationError < APIError; end
 
+    # 429 Too Many Requests (+destination_in_cooldown+ code): a start_verification
+    # for the same app and destination landed within the API's cooldown window.
+    # Never auto-retry this.
+    class RateLimitedError < APIError
+      # @return [Integer, nil] seconds to wait, from the Retry-After header.
+      #   Nil if the header is missing or not a plain integer.
+      attr_reader :retry_after
+
+      def initialize(message = nil, status:, errors: [], response: nil, retry_after: nil)
+        @retry_after = retry_after
+        super(message, status: status, errors: errors, response: response)
+      end
+    end
+
     # 5xx Server Error (+internal_error+ code).
     class ServerError < APIError; end
   end

data/lib/didww/otp_verification/verification.rb

@@ -55,6 +55,12 @@ module DIDWW
         @sms && @sms["interception_timeout"]
       end
 
+      # @return [Integer, nil] the length of this verification's code, 4..8
+      #   (set per application). Only present for the +sms+ method.
+      def sms_code_length
+        @sms && @sms["code_length"]
+      end
+
       # @return [String, nil] SMS Retriever hash, echoed back only when one was
       #   stored on this verification.
       def sms_app_hash
@@ -71,6 +77,12 @@ module DIDWW
         @callout && @callout["language"]
       end
 
+      # @return [Integer, nil] the length of this verification's code, 4..8
+      #   (set per application). Only present for the +callout+ method.
+      def callout_code_length
+        @callout && @callout["code_length"]
+      end
+
       def pending? = status == "pending"
       def verified? = status == "verified"
       def failed? = status == "failed"

data/lib/didww/otp_verification/version.rb

@@ -1,5 +1,5 @@
 module DIDWW
   module OTPVerification
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: didww-otp_verification
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - DIDWW