didww-otp_verification 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f7f380aca63b49a1e661d0834f16f7d94af7fdacf63e1e54d7ddacac1e8a79
-  data.tar.gz: e1920bc8b4994f0abe90fc7a93b43339a1e5dc2d492983e93625a24b70f23285
+  metadata.gz: 2d642797b509a6a3a07315a163ac283086e3877a7d6304f88fb968995ad16f09
+  data.tar.gz: 6656b36bd906929a5397887573d1d1b40ed29fb3cecbe8add71ec5cc2355934d
 SHA512:
-  metadata.gz: c8867b191e13078948e4427c2b5321b365dd52f79481f5ff4e81f56eae59466f8f0a006c6979030aebc8e6ac1432c1bd6d11f9ac35d9637b7c1a7a7dd104d918
-  data.tar.gz: 330d1aea846c2104f48db034df7eed4af4e15bc47c045c086068db419bcbfffa4271d156f1da818303353d0b6f9ae53ead2c56f4df2159502824023990c3b781
+  metadata.gz: c994241bc5f386def42788c2bc6d7b6fbad3050784de09a396252046343df7fa16cd8c6066df35a2168cbb101fffec56f2dded64d2a5d7ff82204e5c40e1683a
+  data.tar.gz: 8e3313f28b2c2327b5e73d31ba4b24d574981f89a4878089e584924dbc395035e1b86ea24c0a3d7622b68733e2bf1da8f26db6ea50e6c86828bf1f659a46cea0

data/CHANGELOG.md

@@ -6,6 +6,82 @@ 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.3.0] — 2026-11
+
+### Added
+
+- **`destination_prefix_rate_limited` error code**, raised as `RateLimitedError`
+  (429) from `start_verification` when there are too many verifications to a
+  number range. `#retry_after` carries the `Retry-After` wait in seconds; do not
+  retry it automatically.
+- **`channel_blocked` error code.** A start can be refused with a 422 carrying it
+  when the account can't use the requested delivery method. Contact DIDWW
+  support.
+
+## [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

data/README.md

@@ -65,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"}}
 )
 ```
 
@@ -82,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(
@@ -96,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
@@ -106,11 +132,17 @@ v.sms_template             # => "Your code is {{CODE}}"
 v.sms_language             # => "en-US"
 v.sms_interception_timeout # => 300
 v.sms_code_length          # => 6
-v.sms_app_hash             # => "A1b2C3d4E5f", or nil if none was stored
+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
 ```
 
@@ -127,8 +159,16 @@ 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.
+`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
 
@@ -167,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`.
@@ -273,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`
@@ -335,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`   |
+| `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`         |
+| `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)
 
@@ -370,7 +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`             |
+| `RateLimitedError`         | 429       | `destination_in_cooldown`, `rate_limit_*`, `volume_limit_reached`, `destination_prefix_rate_limited` |
 | `ServerError`              | 5xx       | `internal_error`                      |
 
 Every error carries the API's coded envelope: `#errors` is an array of
@@ -394,21 +473,38 @@ rescue DIDWW::OTPVerification::ValidationError => e
 end
 ```
 
+`channel_blocked` (422): the account can't use the requested delivery method.
+No verification is created; contact DIDWW support.
+
 ## Retries
 
 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.
+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.
+- `destination_prefix_rate_limited`: too many verifications to this number range;
+  try again later. Wait `Retry-After` before starting another one, and show the
+  user "Too many verification requests right now. Please try again later."
+
+`#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

@@ -50,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
 
@@ -85,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.

data/lib/didww/otp_verification/errors.rb

@@ -48,8 +48,11 @@ 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.
+    # 429 Too Many Requests. +code+ says which limit was hit:
+    # +destination_in_cooldown+ (this destination was requested too recently),
+    # a +rate_limit_*+ request limit, +volume_limit_reached+ (a daily or
+    # monthly limit; +retry_after+ can be days), or +destination_prefix_rate_limited+
+    # (too many verifications to this number range; wait +retry_after+).
     # Never auto-retry this.
     class RateLimitedError < APIError
       # @return [Integer, nil] seconds to wait, from the Retry-After header.

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

@@ -61,10 +61,40 @@ module DIDWW
         @sms && @sms["code_length"]
       end
 
-      # @return [String, nil] SMS Retriever hash, echoed back only when one was
-      #   stored on this verification.
+      # @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
@@ -83,6 +113,25 @@ module DIDWW
         @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.1.0"
+    VERSION = "1.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: didww-otp_verification
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.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:
   - - ">="