didww-otp_verification 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95cc4c0b5d246e12eeb76854405106c8ef277a4790dbbfee8620f6984a6074a8
-  data.tar.gz: 5d157aba75750f9b9a605b1d114dfdd289dbc9ea949b3d1d2a0a5636da12c0a9
+  metadata.gz: 9ff9c9fc68b3da5a2d330d5ddc3ef599f65feb79674fe93d302c393dabe6d5b3
+  data.tar.gz: 639dc28bfb09c2af89e98ec9845c0a5fb422d09b21e9e717b30cd6f28039b387
 SHA512:
-  metadata.gz: fa0921c7b444d6efaba56f12c050d68b408c98f956a21fd3656c3672eabc8c73415a8d3fb5e16bc9c32f7bbcfca930856d5cc1c80fabc0f98a758e40bfb22d59
-  data.tar.gz: aa033d4b455850aa7ed1c5a79861bfb35a303fd8e677387ebf1d77be9ccb78468cbb5bcc4d7fe1438995a3277faa2eae67c07d689068aa5fa531bd54627cab62
+  metadata.gz: 7de05b4e0d44499d58f885db44190a09c199a014091efbce7060c2127fccd23c3ef2981832a298ed5ab52720a5de135e6f32b7eb4ffd1f859da77854c0bddb99
+  data.tar.gz: dca7699a26fc3dee4e717470be7d778cd0591acffb282ec70be84e8b880c963023cec1a8ae54f80f199238bac3913f97eb7a6d5223dfe15b79115ed08bb7f337

data/CHANGELOG.md

@@ -6,6 +6,93 @@ 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.2.0] — 2026-10
+
+### Added
+
+- **`custom:` on `start_verification`**, up to 4096 characters of free text sent
+  as top-level `data.custom` and delivered unchanged to your callback server in
+  the `verification_request` body (the key is absent when unset). It is not
+  returned in API responses. A longer value is refused with the new
+  `custom_too_long` error code.
+- **`sms: {autofill: ...}`** with type `app_hash`, `domain` or `none`.
+  `Verification#sms_autofill` reads back the stored marker, `app_hash` or
+  `domain`, whose `value` is the hash or the domain. New error codes
+  `autofill_invalid` and `sms_domain_not_configured`.
+- **`template_group` in the `sms:` and `callout:` options**, to pick a template
+  group instead of the application's default. New readers
+  `Verification#sms_template_group`/`#callout_template_group`,
+  `#sms_template_group_used`/`#callout_template_group_used` and
+  `#sms_template_fallback_reason`/`#callout_template_fallback_reason`; the last
+  is an open set (`language_missing`, `version_pending`, `version_rejected`,
+  `audio_not_ready`, `group_missing`). An unknown group is refused with the new
+  `template_group_not_found` error code.
+- **Secret rotation support in callback verification.** During a secret
+  rotation the service also sends an `x-signature-previous` header, signed with
+  the previous secret. `CallbackVerifier#valid?` takes an optional
+  `previous_signature:` and accepts the callback when either signature matches
+  the configured secret. `RailsCallbackVerifier` reads the header itself.
+  Upgrade the SDK before rotating a secret.
+- **New 429 error codes:** `rate_limit_per_ip` (too many requests from this IP
+  address), `rate_limit_failed_auth` (too many failed authentication attempts
+  from this IP address), `rate_limit_per_account` (too many requests for this
+  account), `rate_limit_public_per_account` (too many public requests for this
+  account) and `volume_limit_reached` (the application reached its daily or
+  monthly verification limit; `Retry-After` can be days, so surface it instead
+  of retrying). All raise `RateLimitedError`.
+- **New outcome codes:** `application_paused` and `destination_country_disabled`
+  (status `denied`).
+
+### Changed
+
+- **`destination_not_supported_for_channel` is now an outcome, not a 422.** A
+  start for a number with no supported country, no delivery for the requested
+  method, or in a blocked range returns `201` with status `failed` and this
+  `error_code`. Code that rescued the 422 now gets a failed verification
+  instead. The error code stays in the list for compatibility.
+
+- **Supported Ruby is now 3.3+** (`required_ruby_version >= 3.3.0`). Ruby 3.1
+  went EOL on 2025-03-26 and 3.2 on 2026-03-31. CI tests 3.3, 3.4 and 4.0.
+
+### Deprecated
+
+- **The `sms: {app_hash: ...}` option and `Verification#sms_app_hash`.** Use
+  `autofill`. The option is sent as `autofill: {type: "app_hash", value: ...}`
+  with a `:deprecated` warning; passing it together with a non-nil `autofill`
+  raises `ArgumentError`.
+- **The `stale_dispatch` outcome code.** The service no longer sends it and
+  reports these verifications as `dispatch_failed`. It stays documented so
+  existing matches keep working, and will be dropped from the docs in the next
+  major version.
+
+### Docs
+
+- A Testing section on the sandbox environment, which sends nothing and gives
+  a predefined result only for the reserved test numbers.
+
+## [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"
 )
@@ -64,15 +65,23 @@ reads only the block matching `delivery_method` and ignores the others.
 | Field       | Description                                                                                                                                                                   |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `languages` | Preferred template languages as BCP 47 tags, most preferred first. Matched exactly, so the region subtag is required — `"pl"` does not match `pl-PL`. Unmatched tags fall back to `en-US`. |
-| `app_hash`  | Android SMS Retriever hash: exactly 11 characters of `[A-Za-z0-9+/]`. The delivered message is then prefixed with `<#> ` and the hash appended as its last token, so the handset can auto-fill the code. Omit it on every other platform. |
+| `autofill`  | Auto-fill marker for the delivered message. `{type: "app_hash", value: "..."}` is the Android SMS Retriever hash: exactly 11 characters of `[A-Za-z0-9+/]`. The message is then prefixed with `<#> ` and the hash appended as its last token, so the handset can auto-fill the code. `{type: "domain"}` adds a domain-bound line for the application's configured SMS domain. `{type: "none"}` explicitly asks for no marker. Omit it to use the application default. |
+| `template_group` | Name of one of your template groups, used instead of the application's default. |
 
-`app_hash` is here because a Ruby backend often starts the verification on behalf
+`autofill` is here because a Ruby backend often starts the verification on behalf
 of an Android app — the hash identifies that app, so only the app can compute it.
+`{type: "domain"}` takes no `value`; on an application with no SMS domain it is
+refused with `sms_domain_not_configured`. A malformed `autofill` is refused with
+`autofill_invalid`.
+The former `app_hash:` key still works as a deprecated alias for
+`autofill: {type: "app_hash", value: ...}` (it prints a deprecation warning
+when Ruby's `:deprecated` warnings are enabled). Passing both with non-nil values
+raises `ArgumentError`; `autofill: nil` counts as absent.
 
 ```ruby
 client.start_verification(
   destination: "+4915112345678", delivery_method: "sms",
-  sms: {languages: ["en-US"], app_hash: "A1b2C3d4E5f"}
+  sms: {languages: ["en-US"], autofill: {type: "app_hash", value: "A1b2C3d4E5f"}}
 )
 ```
 
@@ -81,6 +90,10 @@ client.start_verification(
 | Field       | Description                                                                                                                                                                   |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `languages` | Preferred announcement languages — the same tags, order and matching rules as the `sms:` ones, so the same list is valid for either method. It is not shared between them, though: each method reads only its own block, so the list goes under `callout:` here and under `sms:` there. The catalogues are separate too, so a tag that has a message template but no recording is accepted and falls back to `en-US`. |
+| `template_group` | Name of one of your template groups, as for `sms:`. |
+
+An unknown `template_group` on either method is refused with
+`template_group_not_found`.
 
 ```ruby
 client.start_verification(
@@ -95,6 +108,20 @@ API ships it. The cost of that is no typo protection: an unrecognized option is
 ignored rather than rejected, and a misspelled key returns `201` with the
 defaults applied, not an error.
 
+### `custom:`
+
+Optional free text, up to 4096 characters, sent as top-level `data.custom` (an
+empty string counts as absent). It is not returned by the API; it reaches your
+callback server as `data.custom` in the `verification_request` body; the key is
+absent when unset. A longer value is refused with `custom_too_long`.
+
+```ruby
+client.start_verification(
+  destination: "+4915112345678", delivery_method: "sms",
+  custom: "order-42"
+)
+```
+
 ### Reading a method block back
 
 The response carries the block for the method that was used, readable field by
@@ -103,11 +130,19 @@ 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_app_hash             # => "A1b2C3d4E5f", or nil if none was stored
+v.sms_interception_timeout # => 300
+v.sms_code_length          # => 6
+v.sms_autofill             # => {"type" => "app_hash", "value" => "A1b2C3d4E5f"}, or nil
+v.sms_template_group       # => "checkout", or nil if none applied
+v.sms_template_group_used  # => true
+v.sms_template_fallback_reason # => nil, or e.g. "language_missing"
 v.sms                      # => the raw block, or nil on a callout verification
 
 v.callout_language         # => "de-DE"
+v.callout_code_length      # => 6
+v.callout_template_group   # => "checkout", or nil if none applied
+v.callout_template_group_used # => true
+v.callout_template_fallback_reason # => nil, or e.g. "audio_not_ready"
 v.callout                  # => the raw block, or nil on an sms verification
 ```
 
@@ -119,10 +154,21 @@ 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_app_hash` is echoed back only when one was stored, so it reflects what was
-persisted rather than what was requested.
+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_autofill` is echoed back only when a hash or domain marker was stored, so it
+reflects what was persisted rather than what was requested; for `domain`, `value`
+is the domain. `sms_app_hash` is a deprecated reader derived from it: the `value`
+when the type is `app_hash`, otherwise `nil`.
+`*_template_group_used` is true when the group's template was used. When it is
+false, `*_template_fallback_reason` says why: `language_missing`,
+`version_pending`, `version_rejected`, `audio_not_ready` or `group_missing` (the
+group no longer exists; `*_template_group` is then `nil`). Both are false/`nil`
+when no template group applies at all. Like error codes, the reasons are an open
+set of plain strings.
 
 ### Address by phone number
 
@@ -161,6 +207,15 @@ DIDWW::OTPVerification.configure do |c|
 end
 ```
 
+## Testing
+
+The sandbox sends no real SMS and places no real calls. Only the reserved test
+numbers give a predefined result, such as delivered, failed or expired; a
+delivered one has a fixed code. Any other number is never delivered to, and its
+verification ends as failed. The test numbers, their outcomes and the code to
+submit are listed in
+[Testing on sandbox](https://doc.didww.com/otp-verification/testing.html).
+
 ## Configuration
 
 Set global defaults; every field is overridable per `Client`.
@@ -197,6 +252,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                              |
@@ -265,15 +322,35 @@ ok = verifier.valid?(
   content_type: request.content_type,
   body:         request.raw_post,         # RAW body bytes — do not re-serialize
   timestamp:    request.headers["x-timestamp"],
-  signature:    signature
+  signature:    signature,
+  previous_signature: request.headers["x-signature-previous"]  # optional
 )
 
 render json: { action: ok ? "allow" : "deny" }
 ```
 
+The `verification_request` body carries the `custom` value you passed to
+`start_verification` as `data.custom` (absent when unset). When the verification
+is started from a mobile app, that value is client-controlled: validate it
+against your own records rather than trusting it.
+
 The verifier also enforces a 5-minute timestamp window (configurable via
 `tolerance:`) to reject replays.
 
+### Rotating the application secret
+
+While a rotated-out secret is still valid, DIDWW also sends an
+`x-signature-previous` header: the same signature computed with the previous
+secret. The verifier accepts a callback when either the `Authorization`
+signature or `previous_signature` matches the secret you configured. A receiver
+can therefore switch from the old secret to the new one at any point during the
+grace period, with no failed callbacks. Without the header the verifier behaves
+as before.
+
+Upgrade the SDK before you rotate a secret, because an older version ignores
+`x-signature-previous` and rejects callbacks signed with the new secret while
+the old one is configured.
+
 ### Rails
 
 `RailsCallbackVerifier` pulls every signed field off an `ActionDispatch`
@@ -327,13 +404,23 @@ 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                                                           |
-| `denied`   | yes      | `denied_by_callback`, `denied_missing_callback_url`, `denied_invalid_callback_response`         |
+| `failed`   | yes      | `too_many_attempts`, `dispatch_failed`, `superseded`, `application_deleted`, `destination_not_supported_for_channel`, `stale_dispatch` (deprecated) |
+| `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`, `application_paused`, `destination_country_disabled` |
 
 `superseded` means a newer `start_verification` for the same number retired this
 one — only the newest verification per number stays active.
 
+Some starts are refused as an outcome rather than an error: a `201` whose status
+is `denied` (`application_paused`, `destination_country_disabled`) or `failed`
+(`destination_not_supported_for_channel`: the number has no supported country,
+can't be reached by this delivery method, or is in a blocked range). Earlier
+versions returned the last one as a `422`; that code stays in the error list for
+compatibility only.
+
+`stale_dispatch` is deprecated: the service no longer sends it and reports these
+verifications as `dispatch_failed`.
+
 ```ruby
 v = client.get_verification(id)
 
@@ -362,6 +449,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`, `rate_limit_*`, `volume_limit_reached` |
 | `ServerError`              | 5xx       | `internal_error`                      |
 
 Every error carries the API's coded envelope: `#errors` is an array of
@@ -390,10 +478,27 @@ 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 429 raises `RateLimitedError`, and its code says which limit was hit:
+
+- `destination_in_cooldown`: a verification for this destination was requested
+  too recently.
+- `rate_limit_per_ip`: too many requests from this IP address.
+- `rate_limit_failed_auth`: too many failed authentication attempts from this
+  IP address.
+- `rate_limit_per_account`: too many requests for this account.
+- `rate_limit_public_per_account`: too many public requests for this account.
+- `volume_limit_reached`: the application reached its daily or monthly
+  verification limit. `Retry-After` can be long (days) — surface it to the
+  user instead of retrying. Contact support to raise the limit.
+
+`#retry_after` gives the wait in seconds (`nil` if the `Retry-After` header is
+missing or unparseable) — wait that long before trying again yourself; never
+auto-retry it.
+
 ## Development
 
 Development is pinned to the Ruby in `.ruby-version`; the gem itself supports
-3.1+.
+3.3+.
 
 ```sh
 bundle install

data/lib/didww/otp_verification/callback_verifier.rb

@@ -19,7 +19,8 @@ module DIDWW
     #   verifier.valid?(
     #     method: "POST", path: "/callbacks/didww",
     #     content_type: "application/json", body: raw_body,
-    #     timestamp: request.headers["x-timestamp"], signature: signature
+    #     timestamp: request.headers["x-timestamp"], signature: signature,
+    #     previous_signature: request.headers["x-signature-previous"]
     #   )
     class CallbackVerifier
       # @param tolerance [Integer] max allowed clock skew, in seconds (server uses 5 minutes).
@@ -41,16 +42,21 @@ module DIDWW
         [key, signature]
       end
 
-      # @return [Boolean] true when both the timestamp is fresh and the
-      #   signature matches (constant-time comparison).
-      def valid?(method:, path:, content_type:, body:, timestamp:, signature:)
+      # @param previous_signature [String, nil] the `x-signature-previous` header, sent
+      #   during a secret rotation and signed with the previous secret. Ignored when absent.
+      # @return [Boolean] true when the timestamp is fresh and the signature, or the
+      #   previous signature, matches (constant-time comparison).
+      def valid?(method:, path:, content_type:, body:, timestamp:, signature:, previous_signature: nil)
         return false if Util.blank?(signature)
         return false unless fresh?(timestamp)
 
         expected = @signer.sign(
           method:, path:, content_type:, body:, timestamp: timestamp
         )
-        secure_compare(expected, signature)
+        # Both comparisons always run, so timing does not reveal which header matched.
+        current = secure_compare(expected, signature)
+        previous = secure_compare(expected, previous_signature)
+        current || previous
       end
 
       private
@@ -63,6 +69,7 @@ module DIDWW
 
       # Constant-time string comparison via the audited stdlib implementation.
       def secure_compare(a, b)
+        return false if b.nil?
         return false unless a.bytesize == b.bytesize
 
         OpenSSL.fixed_length_secure_compare(a, b)

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
 
@@ -49,10 +50,21 @@ module DIDWW
       # reads only the block matching +delivery_method+ and ignores the others.
       # An unrecognized option is ignored rather than rejected, so a typo there
       # fails silently. Methods with no options of their own take no keyword.
-      def start_verification(destination:, delivery_method:, sms: nil, callout: nil)
+      #
+      # +custom+ is free text (up to 4096 characters) delivered to your
+      # callback server as +data.custom+; it is not part of the response.
+      #
+      # The +sms+ key +app_hash+ is deprecated: it is sent as
+      # <tt>autofill: {type: "app_hash", value: ...}</tt> with a deprecation
+      # warning. Passing it together with +autofill+ raises ArgumentError,
+      # because the API rejects that combination. Both apply only when
+      # +delivery_method+ is +sms+, the only method that reads +autofill+.
+      def start_verification(destination:, delivery_method:, sms: nil, callout: nil, custom: nil)
         data = {destination:, delivery_method:}
+        data[:custom] = custom unless custom.nil?
         data[:sms] = sms unless sms.nil?
         data[:callout] = callout unless callout.nil?
+        data[:sms] = migrate_app_hash(data[:sms]) if delivery_method.to_s == "sms" && data[:sms].is_a?(Hash)
         request(:post, "#{API_PREFIX}/verifications", data)
       end
 
@@ -84,6 +96,26 @@ module DIDWW
 
       private
 
+      # Maps the deprecated sms +app_hash+ onto +autofill+ on a copy, so the
+      # caller's hash is left alone.
+      def migrate_app_hash(sms)
+        keys = [:app_hash, "app_hash"].select { |k| sms.key?(k) }
+        return sms if keys.empty?
+
+        # A nil hash counts as absent, as the API always treated it.
+        key = keys.find { |k| !sms[k].nil? }
+        return sms.except(*keys) unless key
+        # A nil autofill counts as absent too, as the API treats it.
+        autofill_keys = [:autofill, "autofill"].select { |k| sms.key?(k) }
+        if autofill_keys.any? { |k| !sms[k].nil? }
+          raise ArgumentError, "sms: pass either autofill or the deprecated app_hash, not both"
+        end
+
+        warn "DIDWW::OTPVerification: sms app_hash is deprecated; " \
+          "use sms: {autofill: {type: \"app_hash\", value: ...}}", category: :deprecated, uplevel: 2
+        sms.except(*keys, *autofill_keys).merge(autofill: {type: "app_hash", value: sms[key]})
+      end
+
       # Percent-encode a value for use as a single URL path segment. Notably
       # turns a leading "+" into "%2B" so it survives proxies that would
       # otherwise decode "+" to a space in the path.
@@ -110,11 +142,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 +161,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 +185,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,22 @@ module DIDWW
     # 400 Bad Request / 422 Unprocessable Content (validation errors in +errors+).
     class ValidationError < APIError; end
 
+    # 429 Too Many Requests. +code+ says which limit was hit:
+    # +destination_in_cooldown+ (this destination was requested too recently),
+    # a +rate_limit_*+ request limit, or +volume_limit_reached+ (a daily or
+    # monthly limit; +retry_after+ can be days).
+    # 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/rails.rb

@@ -47,7 +47,8 @@ module DIDWW
           content_type: request.content_type,
           body: request.raw_post,
           timestamp: request.headers["x-timestamp"],
-          signature: signature
+          signature: signature,
+          previous_signature: request.headers["x-signature-previous"]
         )
       end
     end

data/lib/didww/otp_verification/verification.rb

@@ -55,10 +55,46 @@ module DIDWW
         @sms && @sms["interception_timeout"]
       end
 
-      # @return [String, nil] SMS Retriever hash, echoed back only when one was
-      #   stored on this verification.
+      # @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 [Hash, nil] the stored autofill marker, +{"type", "value"}+ with
+      #   type +app_hash+ (value: the hash) or +domain+ (value: the domain);
+      #   +nil+ unless one was stored on this verification.
+      def sms_autofill
+        @sms && @sms["autofill"]
+      end
+
+      # @deprecated Use {#sms_autofill}.
+      # @return [String, nil] the SMS Retriever hash, when the stored autofill
+      #   is of type +app_hash+.
       def sms_app_hash
-        @sms && @sms["app_hash"]
+        autofill = sms_autofill
+        return @sms && @sms["app_hash"] unless autofill
+
+        autofill["value"] if autofill["type"] == "app_hash"
+      end
+
+      # @return [String, nil] the template group applied; nil when none applies
+      #   or it no longer exists. Only present for the +sms+ method.
+      def sms_template_group
+        @sms && @sms["template_group"]
+      end
+
+      # @return [Boolean, nil] true when the group's template was used. Only
+      #   present for the +sms+ method.
+      def sms_template_group_used
+        @sms && @sms["template_group_used"]
+      end
+
+      # @return [String, nil] why the group's template was not used, e.g.
+      #   +language_missing+ (an open set); nil when it was or when no group
+      #   applies. Only present for the +sms+ method.
+      def sms_template_fallback_reason
+        @sms && @sms["template_fallback_reason"]
       end
 
       # The tag the announcement is played in: the first requested language the
@@ -71,6 +107,31 @@ 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
+
+      # @return [String, nil] the template group applied; nil when none applies
+      #   or it no longer exists. Only present for the +callout+ method.
+      def callout_template_group
+        @callout && @callout["template_group"]
+      end
+
+      # @return [Boolean, nil] true when the group's template was used. Only
+      #   present for the +callout+ method.
+      def callout_template_group_used
+        @callout && @callout["template_group_used"]
+      end
+
+      # @return [String, nil] why the group's template was not used, e.g.
+      #   +audio_not_ready+ (an open set); nil when it was or when no group
+      #   applies. Only present for the +callout+ method.
+      def callout_template_fallback_reason
+        @callout && @callout["template_fallback_reason"]
+      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.2.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.2.0
 platform: ruby
 authors:
 - DIDWW
@@ -85,7 +85,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="