didww-v3 5.3.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c780bc13f7f052f1733482ee69b37994b6bd8c9926a498857947faf23865c8d2
-  data.tar.gz: 22be4b92ea6dd9616dc2e67b77b51b3305876b51b6fed40cba6ce7abb8d015e5
+  metadata.gz: 9cdeedbb317141c84de28bbedb4f652b858793e257d8d84f70155b08fc54623c
+  data.tar.gz: c48319beb5292ef53595e7905d4ac62ff0e59685bcb57eb48c2f7e6efbb7bd3e
 SHA512:
-  metadata.gz: 0c80b1331067374890afec7505eeff625af09f4c36d6e093585483005091c56db11cfd36a4a6ba62547c3e3a300d9b7acc37d78502c8db45f8a91f6cf86c9b83
-  data.tar.gz: 549b86aadb2a060b2ed3ae5f84e4d9f0140c012080087ee84b7feb800137957b0726f39c347a1574ea1109e09e8d39b875b2f416389e8633f4cd008f092ca44a
+  metadata.gz: 42be04280b6673a827de5f4bc680f032f28d72437137d081455f2168aa02e92d3861b7fc842e6c70406e6495d1f377745f90a23ead254fdf0a5a6caf40417d63
+  data.tar.gz: e6aeccf261500d0307c5cbc7eae427880a853d008ce28639ff2512daa1ea1cb40c54962b3d0f972f7e3ea0a73274bc40a6a8a57b9df45689b9c0ddfb83987acb

data/.gitignore

@@ -10,3 +10,10 @@
 
 # rspec failure tracking
 .rspec_status
+
+# claude settings (local-only, per-developer)
+.claude/
+
+# build artifacts
+/*.gem
+

data/CHANGELOG.md

@@ -4,6 +4,74 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.1.0] - 2026-05-04
+### Added
+- Complete the 2026-04-16 `SipConfiguration` attribute set that was missed during the 2026-04-16 rollout (and is not present in the public Postman collection — server form is the source of truth):
+  - `enabled_sip_registration` (bool) — enables SIP registration; the API generates `incoming_auth_*` credentials when set true and requires `port` to be blank.
+  - `use_did_in_ruri` (bool) — uses DID number in R-URI; requires SIP registration to be enabled.
+  - `network_protocol_priority` (string enum) — `force_ipv4` / `force_ipv6` / `any` / `prefer_ipv4` / `prefer_ipv6`. Constants exposed as `NETWORK_PROTOCOL_PRIORITY_*` and `NETWORK_PROTOCOL_PRIORITIES`.
+  - `diversion_inject_mode` (string enum) — `none` / `did_number`. Constants exposed as `DIVERSION_INJECT_MODE_*` and `DIVERSION_INJECT_MODES`.
+  - `cnam_lookup` (bool) — enables CNAM resolution for inbound calls.
+- `SipConfiguration#incoming_auth_username` and `#incoming_auth_password` — read-only server-generated SIP authentication credentials returned on `voice_in_trunks` when `enabled_sip_registration` is true.
+- `ComplexObject::Base.property` accepts `read_only: true`. Read-only attributes are still parsed from server responses but are stripped from the JSON:API write payload, so round-tripping a loaded configuration through PATCH no longer triggers `400 Param not allowed`.
+- `ComplexObject::Base.property` accepts `sensitive: true`. The default `#inspect` representation redacts those values with `[FILTERED]` so credentials never leak through default logging / REPL / unhandled exception output. Marked as sensitive: `SipConfiguration#auth_password`, `SipConfiguration#incoming_auth_username/password`, and `AuthenticationMethod::CredentialsAndIp#username/password`.
+- `SipConfiguration` auto-cascades dependent fields whose constraints are server-enforced when set via property setters: `enabled_sip_registration = true` clears `host`/`port` (when previously set), `enabled_sip_registration = false` forces `use_did_in_ruri = false`, and assigning a non-blank `host` flips both flags. Constructor / `[]=` assignments bypass the cascade so server responses deserialize as-is.
+
+## [6.0.0] - 2026-04-24
+Support for DIDWW API version **2026-04-16**. The gem now sends `X-DIDWW-API-Version: 2026-04-16` with every request by default. Users staying on API `2022-05-10` should pin to the [`2022-05-10`](https://github.com/didww/didww-v3-ruby/tree/2022-05-10) branch (5.x).
+
+### Breaking Changes
+- Default `X-DIDWW-API-Version` header is now `2026-04-16`.
+- Resource `requirement_validations` renamed to `address_requirement_validations`.
+- Resource `requirements` renamed to `address_requirements`.
+- `AddressRequirementValidation#requirement` relationship renamed to `address_requirement`.
+- `DidGroup#requirement` relationship renamed to `address_requirement`.
+- `DidReservation#expire_at` renamed to `expires_at`.
+- `EncryptedFile#expire_at` renamed to `expires_at`.
+- `AddressVerification#reject_reasons` is now an array of strings.
+- Dropped `sms_out` from `DidGroup` features.
+- `EncryptedFile` POST now accepts a single file per request.
+- `Export` year/month filters replaced with `from`/`to` datetime range (`from` inclusive, `to` exclusive).
+- `VoiceInTrunk` SIP configuration gains `diversion_relay_policy`.
+- Attribute values standardized to lowercase `snake_case` (status/area-level enums, etc.).
+- `Order#cancelled?` renamed to `canceled?`; `Order::STATUS_CANCELLED` → `STATUS_CANCELED` to match wire format (`status: "canceled"`).
+- `VoiceOutTrunk`: flat credentials (`username`/`password`/`auth_type`) replaced with a polymorphic `authentication_method` relationship. Supported types: `CredentialsAuthenticationMethod`, `IpAuthenticationMethod`, `CredentialsAndIpAuthenticationMethod`, `TwilioAuthenticationMethod`, and `GenericAuthenticationMethod` (forward-compatible fallback).
+- `DidGroup`: removed `features_human` and `FEATURES` constant.
+
+### Added
+- New resource `DidHistory` (`/v3/did_history`) with `meta.billing_cycles_count_changed`.
+- New resource `EmergencyRequirement` (`/v3/emergency_requirements`).
+- New resource `EmergencyRequirementValidation` (`/v3/emergency_requirement_validations`).
+- New resource `EmergencyCallingService` (`/v3/emergency_calling_services`) with `address` has-one relationship.
+- New resource `EmergencyVerification` (`/v3/emergency_verifications`).
+- `external_reference_id` attribute on `Address`, `AddressVerification`, `Export`, `EmergencyVerification`, `Order`, `PermanentSupportingDocument`, `Proof`, `SharedCapacityGroup`, `VoiceInTrunkGroup`, `VoiceInTrunk`, `VoiceOutTrunk`.
+- PATCH support for `external_reference_id` on `/v3/address_verifications/:id`, `/v3/exports/:id`, `/v3/emergency_verifications/:id`.
+- `VoiceOutTrunk`: `emergency_enable_all`, `rtp_timeout`, `emergency_dids` has-many relationship, status predicate helpers.
+- `Did`: `emergency_enabled`, `emergency_calling_service` / `emergency_verification` / `identity` has-one relationships, PATCH support for unassigning `emergency_calling_service`.
+- `Identity`: `birth_country` has-one relationship.
+- `DidGroup`: new features `p2p`, `a2p`, `emergency`, `cnam_out`; `service_restrictions` attribute.
+- `AddressVerification`: `reject_comment` attribute.
+- `Order`: new `EmergencyOrderItem` complex object.
+- Status predicate helpers on `VoiceOutTrunk`, `EmergencyCallingService`, `AddressVerification`, `EmergencyVerification`, and `Order`.
+- `Export` exposes `STATUS_PENDING` and `STATUS_PROCESSING`.
+- `randomize_cli` added to `OnCliMismatchAction` constants.
+- Examples for all new 2026-04-16 resources and an end-to-end `emergency_scenario` example.
+
+### Changed
+- Unknown `authentication_method` types are wrapped in `Generic` for forward compatibility.
+- Resource-level meta support for `EmergencyCallingService` and `EmergencyRequirement`.
+- `ExportFilters` from/to semantics clarified (from=inclusive, to=exclusive).
+- Examples: fixtures use RFC 5737 documentation IPs (`203.0.113.0/24`); `SecureRandom.hex(4)` used for random IDs.
+- Shared rspec examples extracted for PATCH `external_reference_id` and requirement validations POST→204.
+
+### Fixed
+- Declare `has_one :address` on `EmergencyCallingService` to mirror server.
+- `features_human` falls back to raw key for unknown features (superseded by removal in 6.0).
+
+## [5.3.1]
+### Fixed
+- Correct `VoiceOutTrunk` constant wire values to match API responses.
+
 ## [5.3.0]
 ### Added
 - `DIDWW::Client.customize_connection` to allow customizing the Faraday connection (e.g. proxy, timeouts, custom middleware).

data/README.md

@@ -16,15 +16,17 @@ This SDK uses [json_api_client](https://github.com/JsonApiClient/json_api_client
 
 Read more https://doc.didww.com/api
 
-This SDK sends the `X-DIDWW-API-Version: 2022-05-10` header with every request by default.
+## API Version
 
-Gem Versions **4.X.X** and branch [master](https://github.com/didww/didww-v3-ruby) are intended to use with DIDWW API 3 version [2022-05-10](https://doc.didww.com/api3/2022-05-10/index.html).
+This SDK sends the `X-DIDWW-API-Version: 2026-04-16` header with every request by default.
 
-Gem Versions **3.X.X** and branch [release-3](https://github.com/didww/didww-v3-ruby/tree/release-3) are intended to use with DIDWW API 3 version [2021-12-15](https://doc.didww.com/api3/2021-12-15/index.html).
-
-Gem Versions **2.X.X** and branch [release-2](https://github.com/didww/didww-v3-ruby/tree/release-2) are intended to use with DIDWW API 3 version [2021-04-19](https://doc.didww.com/api3/2021-04-19/index.html).
-
-Gem Versions **1.X.X** and branch [release-1](https://github.com/didww/didww-v3-ruby/tree/release-1) are intended to use with DIDWW API 3 version [2017-09-18](https://doc.didww.com/api3/2017-09-18/index.html).
+| Gem Version | Branch | DIDWW API Version |
+|-------------|--------|-------------------|
+| **6.x** | [`master`](https://github.com/didww/didww-v3-ruby) | [`2026-04-16`](https://doc.didww.com/api3/2026-04-16/index.html) |
+| **5.x** | [`2022-05-10`](https://github.com/didww/didww-v3-ruby/tree/2022-05-10) | [`2022-05-10`](https://doc.didww.com/api3/2022-05-10/index.html) |
+| **3.x** | [`release-3`](https://github.com/didww/didww-v3-ruby/tree/release-3) | [`2021-12-15`](https://doc.didww.com/api3/2021-12-15/index.html) |
+| **2.x** | [`release-2`](https://github.com/didww/didww-v3-ruby/tree/release-2) | [`2021-04-19`](https://doc.didww.com/api3/2021-04-19/index.html) |
+| **1.x** | [`release-1`](https://github.com/didww/didww-v3-ruby/tree/release-1) | [`2017-09-18`](https://doc.didww.com/api3/2017-09-18/index.html) |
 
 ## Installation
 
@@ -132,7 +134,7 @@ end
 
 ### API Version
 
-The SDK sends `X-DIDWW-API-Version: 2022-05-10` by default. You can override it per block:
+The SDK sends `X-DIDWW-API-Version: 2026-04-16` by default. You can override it per block (e.g., to pin to a previous API version during migration):
 
 ```ruby
 DIDWW::Client.with_api_version('2022-05-10') do
@@ -203,6 +205,70 @@ trunk = DIDWW::Client.voice_in_trunks.new(
 trunk.save
 ```
 
+#### SIP Registration (2026-04-16)
+
+A Voice In Trunk can also be configured to authenticate inbound calls
+via SIP registration credentials generated by DIDWW. The SDK
+auto-cascades the dependent fields the server requires:
+
+* setting `enabled_sip_registration = true` clears any previously-set
+  `host` / `port` (the server rejects them with 422 otherwise);
+* setting `host` to a non-blank value flips `enabled_sip_registration`
+  back to `false` and forces `use_did_in_ruri = false` so the server
+  accepts the disable PATCH.
+
+DIDWW generates `incoming_auth_username` and `incoming_auth_password`
+and surfaces them in the response when SIP registration is enabled.
+
+```ruby
+trunk = DIDWW::Client.voice_in_trunks.new(
+  name: 'Office (registered)',
+  configuration: DIDWW::ComplexObject::SipConfiguration.new.tap do |c|
+    c.enabled_sip_registration = true
+    c.use_did_in_ruri          = true
+    c.cnam_lookup              = true
+  end
+)
+trunk.save
+# trunk.configuration.incoming_auth_username -- server-generated
+# trunk.configuration.incoming_auth_password -- server-generated
+```
+
+To disable SIP registration on an existing trunk, just set `host` —
+the cascade flips `enabled_sip_registration` to `false` and
+`use_did_in_ruri` to `false` automatically:
+
+```ruby
+trunk.configuration = DIDWW::ComplexObject::SipConfiguration.new.tap do |c|
+  c.host = 'sip.example.com'
+end
+trunk.save
+```
+
+### Voice Out Trunks
+
+Voice Out Trunks use a polymorphic `authentication_method` (2026-04-16). Three types are supported:
+
+- **`credentials_and_ip`** -- default method; `username` and `password` are server-generated and returned in the response.
+- **`twilio`** -- requires a `twilio_account_sid`.
+- **`ip_only`** -- read-only; can only be configured by DIDWW staff upon request. Cannot be set via the API.
+
+```ruby
+# NOTE: 203.0.113.0/24 is RFC 5737 TEST-NET-3 documentation space.
+# Replace with the real CIDR of your SIP infrastructure.
+trunk = DIDWW::Client.voice_out_trunks.new(
+  name: 'My Outbound Trunk',
+  on_cli_mismatch_action: 'reject_call',
+  authentication_method: DIDWW::ComplexObject::AuthenticationMethod::CredentialsAndIp.new(
+    allowed_sip_ips: ['203.0.113.0/24']
+  )
+)
+
+trunk.save
+# trunk.authentication_method.username -- server-generated
+# trunk.authentication_method.password -- server-generated
+```
+
 ### Orders
 
 ```ruby
@@ -219,16 +285,141 @@ order = DIDWW::Client.orders.new(
 order.save
 ```
 
+### Emergency Services
+
+```ruby
+# List emergency requirements with filters
+requirements = DIDWW::Client.emergency_requirements
+               .includes(:country, :did_group_type)
+               .all
+
+# Filter by country
+requirements = DIDWW::Client.emergency_requirements
+               .where('country.id': 'country-uuid')
+               .all
+
+requirements.each do |req|
+  puts req.identity_type
+  puts req.address_area_level
+  puts req.estimate_setup_time        # e.g. "7-14 days"
+  puts req.requirement_restriction_message
+end
+
+# Create an emergency verification
+verification = DIDWW::Client.emergency_verifications.new(
+  address: DIDWW::Resource::Address.load(id: 'address-uuid'),
+  emergency_calling_service:
+    DIDWW::Resource::EmergencyCallingService.load(id: 'ecs-uuid'),
+  dids: [DIDWW::Resource::Did.load(id: 'did-uuid')],
+  external_reference_id: 'my-ref-123'
+)
+
+if verification.save
+  puts "Created: #{verification.id} (status: #{verification.status})"
+else
+  puts "Errors: #{verification.errors.full_messages}"
+end
+
+# List emergency calling services
+services = DIDWW::Client.emergency_calling_services
+           .includes(:country, :did_group_type, :dids)
+           .all
+
+services.each do |svc|
+  puts "#{svc.name} — #{svc.status}"
+end
+
+# Cancel (destroy) an emergency calling service
+svc = DIDWW::Client.emergency_calling_services.find('uuid').first
+svc.destroy
+```
+
+### DID History
+
+```ruby
+# List recent DID history events (retained for the last 90 days)
+events = DIDWW::Client.did_history.all
+
+events.each do |event|
+  puts "#{event.created_at.iso8601}  #{event.did_number}  #{event.action}  via #{event.method}"
+end
+
+# Filter by action
+assigned = DIDWW::Client.did_history
+           .where(action: DIDWW::Resource::DidHistory::ACTION_ASSIGNED)
+           .all
+
+# Filter by DID number
+per_number = DIDWW::Client.did_history
+             .where(did_number: '12125551234')
+             .all
+
+# Filter by date range
+seven_days_ago = (Time.now - 7 * 24 * 60 * 60).iso8601
+recent = DIDWW::Client.did_history
+         .where(created_at_gteq: seven_days_ago)
+         .all
+```
+
+## Error Handling
+
+The SDK uses [json_api_client](https://github.com/JsonApiClient/json_api_client) which raises exceptions for HTTP-level errors. Validation errors from the API are returned on the resource's `errors` collection after a failed `save`.
+
+```ruby
+# Validation errors (422 Unprocessable Entity)
+trunk = DIDWW::Client.voice_in_trunks.new(name: '')
+unless trunk.save
+  trunk.errors.full_messages.each do |msg|
+    puts "Validation error: #{msg}"
+  end
+end
+
+# HTTP errors (404, 401, 500, etc.)
+begin
+  DIDWW::Client.dids.find('nonexistent-uuid')
+rescue JsonApiClient::Errors::NotFound => e
+  puts "Not found: #{e.message}"
+rescue JsonApiClient::Errors::AccessDenied => e
+  puts "Access denied: #{e.message}"
+rescue JsonApiClient::Errors::ServerError => e
+  puts "Server error: #{e.message}"
+rescue JsonApiClient::Errors::ConnectionError => e
+  puts "Connection error: #{e.message}"
+end
+```
+
+## Dirty Tracking
+
+The SDK (via `json_api_client`) tracks which attributes have been modified. When you call `save` on a fetched resource, the resulting PATCH request sends only the changed attributes, avoiding unintended overwrites of server-side values.
+
+```ruby
+did = DIDWW::Client.dids.find('uuid').first
+did.description = 'Updated'
+did.save
+# PATCH payload includes only "description", not all attributes
+```
+
 ## Date and Datetime Fields
 
 The SDK distinguishes between date-only and datetime fields:
 
 - **Datetime fields** — deserialized as `Time`:
-  - All `created_at` fields — present on most resources (`EncryptedFile` has no `created_at`)
-  - Expiry fields: `Did#expires_at`, `DidReservation#expire_at`, `Proof#expires_at`, `EncryptedFile#expire_at`
+  - `created_at` — present on most resources
+  - `expires_at` — `Did`, `DidReservation`, `Proof`, `EncryptedFile` (nullable)
+  - `activated_at` — `EmergencyCallingService` (nullable)
+  - `canceled_at` — `EmergencyCallingService` (nullable)
 - **Date-only fields** — deserialized as `Date`:
   - `Identity#birth_date`
-- **Date-only fields kept as strings** (`CapacityPool#renew_date`) remain as `String`.
+- **Date-only fields kept as strings** — remain as `String`:
+  - `CapacityPool#renew_date`, `EmergencyCallingService#renew_date` — `"YYYY-MM-DD"` (nullable)
+- **String fields** (not numeric):
+  - `EmergencyRequirement#estimate_setup_time` — e.g. `"7-14 days"`, `"1"`
+  - `EmergencyRequirement#requirement_restriction_message` — nullable
+
+**Important changes from previous API versions:**
+- `expire_at` renamed to `expires_at` on `DidReservation` and `EncryptedFile`
+- `renew_date` is a date-only string, NOT a datetime
+- `estimate_setup_time` is a string, NOT an integer
 
 ```ruby
 did = DIDWW::Client.dids.find("uuid").first
@@ -283,6 +474,18 @@ class WebhooksController < ApplicationController
 end
 ```
 
+## Enums
+
+The SDK provides constants for all API option fields. These are defined as constants on their respective modules/classes:
+
+`CallbackMethod`, `IdentityType`, `OrderStatus`, `ExportType`, `ExportStatus`, `CliFormat`,
+`OnCliMismatchAction`\*, `MediaEncryptionMode`, `DefaultDstAction`, `VoiceOutTrunkStatus`,
+`EmergencyCallingServiceStatus`, `EmergencyVerificationStatus`, `DiversionRelayPolicy`,
+`TransportProtocol`, `Codec`, `RxDtmfFormat`, `TxDtmfFormat`, `SstRefreshMethod`,
+`ReroutingDisconnectCode`, `Feature`, `AreaLevel`, `AddressVerificationStatus`, `StirShakenMode`
+
+\* `REPLACE_CLI` and `RANDOMIZE_CLI` require additional account configuration. Contact DIDWW support to enable these values.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/didww-v3.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'activesupport'
   spec.add_dependency 'faraday'
+  spec.add_dependency 'faraday-multipart'
   spec.add_dependency 'json_api_client', '1.23.0'
   spec.add_dependency 'http'
   spec.add_dependency 'down'

data/examples/README.md

@@ -34,7 +34,8 @@ DIDWW_API_KEY=your_api_key ruby examples/orders_nanpa.rb
 | [`regions.rb`](regions.rb) | Lists regions with filters/includes and fetches a specific region. |
 | [`did_groups.rb`](did_groups.rb) | Fetches DID groups with included SKUs and shows group details. |
 | [`dids.rb`](dids.rb) | Updates DID routing/capacity by assigning trunk and capacity pool. |
-| [`exports.rb`](exports.rb) | Lists CDR exports and their details. |
+| [`did_history.rb`](did_history.rb) | Lists DID ownership history (last 90 days, 2026-04-16). |
+| [`exports.rb`](exports.rb) | Creates and lists CDR exports, with 2026-04-16 external_reference_id. |
 
 ### Voice In (Inbound)
 | Script | Description |
@@ -77,7 +78,18 @@ DIDWW_API_KEY=your_api_key ruby examples/orders_nanpa.rb
 ### Compliance & Verification
 | Script | Description |
 |---|---|
-| [`identities_and_proofs.rb`](identities_and_proofs.rb) | Creates identities, addresses, and demonstrates proof workflow. |
+| [`identities_and_proofs.rb`](identities_and_proofs.rb) | Creates identities, addresses, and demonstrates proof workflow (2026-04-16 birth_country). |
+| [`address_verifications.rb`](address_verifications.rb) | Lists address verifications with 2026-04-16 reject_comment / external_reference_id. |
+
+### Emergency Services (2026-04-16)
+| Script | Description |
+|---|---|
+| [`emergency_requirements.rb`](emergency_requirements.rb) | Lists emergency service requirements per country/did_group_type. |
+| [`emergency_calling_services.rb`](emergency_calling_services.rb) | Lists and cancels customer emergency calling services. |
+| [`emergency_verifications.rb`](emergency_verifications.rb) | Lists and creates emergency verifications. |
+| [`emergency_requirement_validations.rb`](emergency_requirement_validations.rb) | Pre-validates an emergency order triple (requirement + address + identity). |
+| [`orders_emergency.rb`](orders_emergency.rb) | Inspects server-created Emergency orders and `emergency_order_items`. |
+| [`emergency_scenario.rb`](emergency_scenario.rb) | End-to-end: find DID → check requirements → validate → create verification → get service. |
 
 ## Troubleshooting
 

data/examples/address_verifications.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# Lists Address Verifications (with 2026-04-16 reject_comment / external_reference_id).
+#
+# AddressVerification ties an address to one or more DIDs and a set of
+# supporting documents so DIDWW compliance can approve or reject the
+# declaration. 2026-04-16 adds:
+#   * reject_comment        — free-form comment accompanying a rejection
+#   * external_reference_id — customer-supplied reference (max 100 chars)
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/address_verifications.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+puts '=== Address Verifications ==='
+verifications = DIDWW::Client.address_verifications
+                .includes(:address, :dids)
+                .all
+puts "Found #{verifications.size} address verifications"
+
+verifications.first(5).each do |av|
+  puts "\nVerification: #{av.id}"
+  puts "  Reference: #{av.reference}"
+  puts "  Status: #{av.status}"
+  puts "  External Reference: #{av.external_reference_id}" if av.external_reference_id
+  puts "  Service description: #{av.service_description}"  if av.service_description
+  puts "  Address: #{av.address&.id}"
+  puts "  DIDs: #{av.dids.map(&:number).join(', ')}" if av.dids&.any?
+  if av.rejected?
+    puts "  Reject reasons: #{Array(av.reject_reasons).join(', ')}"
+    puts "  Reject comment: #{av.reject_comment}" if av.reject_comment
+  end
+end
+
+# Filter: only rejected verifications
+puts "\n=== Rejected verifications ==="
+rejected = DIDWW::Client.address_verifications
+           .where(status: DIDWW::Resource::AddressVerification::STATUS_REJECTED)
+           .all
+puts "Found #{rejected.size} rejected verifications"
+rejected.first(3).each do |av|
+  puts "  #{av.reference}: #{av.reject_comment || Array(av.reject_reasons).join(', ')}"
+end
+
+puts "\nAvailable statuses: #{DIDWW::Resource::AddressVerification::STATUSES.join(', ')}"

data/examples/did_groups.rb

@@ -24,7 +24,9 @@ did_groups.first(3).each do |did_group|
   puts "  Area: #{did_group.area_name}"
   puts "  Prefix: #{did_group.prefix}"
   puts "  Metered: #{did_group.is_metered}"
-  puts "  Features: #{did_group.features_human}"
+  puts "  Features: #{did_group.features.join(', ')}" # 2026-04-16 adds p2p / a2p / emergency / cnam_out
+  puts "  Allow additional channels: #{did_group.allow_additional_channels}" # 2026-04-16
+  puts "  Service restrictions: #{did_group.service_restrictions}" if did_group.service_restrictions # 2026-04-16
 
   if did_group.stock_keeping_units && !did_group.stock_keeping_units.empty?
     puts '  SKUs:'

data/examples/did_history.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# Lists DID ownership history (2026-04-16).
+# Records are retained for the last 90 days only.
+#
+# Server-side filters supported:
+#   did_number (eq), action (eq), method (eq),
+#   created_at_gteq, created_at_lteq
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/did_history.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# List most recent DID history events (server sorts by created_at desc)
+puts '=== Recent DID History ==='
+events = DIDWW::Client.did_history.all
+puts "Found #{events.size} events in the last 90 days"
+
+events.first(10).each do |event|
+  puts "#{event.created_at.iso8601}  #{event.did_number.ljust(16)}  #{event.action.ljust(28)}  via #{event.method}"
+end
+
+# Filter by action
+puts "\n=== Only 'assigned' events ==="
+assigned = DIDWW::Client.did_history
+           .where(action: DIDWW::Resource::DidHistory::ACTION_ASSIGNED)
+           .all
+puts "Found #{assigned.size} assignments"
+
+# Filter by a specific DID number
+if (first_event = events.first)
+  number = first_event.did_number
+  puts "\n=== History for DID #{number} ==="
+  per_number = DIDWW::Client.did_history
+               .where(did_number: number)
+               .all
+  per_number.each do |event|
+    puts "#{event.created_at.iso8601}  #{event.action}  via #{event.method}"
+  end
+end
+
+# Filter by date range (last 7 days)
+seven_days_ago = (Time.now - 7 * 24 * 60 * 60).iso8601
+puts "\n=== History since #{seven_days_ago} ==="
+recent = DIDWW::Client.did_history
+         .where(created_at_gteq: seven_days_ago)
+         .all
+puts "Found #{recent.size} events in the last 7 days"
+
+puts "\nAvailable actions: #{DIDWW::Resource::DidHistory::ACTIONS.join(', ')}"
+puts "Available methods: #{DIDWW::Resource::DidHistory::METHODS.join(', ')}"

data/examples/dids.rb

@@ -11,9 +11,10 @@ DIDWW::Client.configure do |client|
   client.api_mode = :sandbox
 end
 
-# Get the last ordered DID
+# Get the last ordered DID (include 2026-04-16 emergency relationships)
 puts '=== Finding last ordered DID ==='
 dids = DIDWW::Client.dids
+        .includes(:identity, :emergency_calling_service, :emergency_verification)
         .all
 
 if dids.empty?
@@ -23,6 +24,11 @@ end
 
 did = dids.first
 puts "Selected DID: #{did.id}"
+puts "  Number: #{did.number}"
+puts "  Emergency enabled: #{did.emergency_enabled}"                       if did.respond_to?(:emergency_enabled)
+puts "  Emergency Calling Service: #{did.emergency_calling_service&.id}"   if did.emergency_calling_service
+puts "  Emergency Verification:    #{did.emergency_verification&.id}"      if did.emergency_verification
+puts "  Identity: #{did.identity&.id}"                                     if did.identity
 
 # Get last SIP trunk
 puts "\n=== Finding SIP trunk ==="

data/examples/emergency_calling_services.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# Lists and cancels customer Emergency Calling Services (2026-04-16).
+#
+# An EmergencyCallingService represents a customer's 911/112 subscription
+# attached to one or more DIDs. It ties an address, identity, DID group type
+# and country together with a pricing snapshot (meta.setup_price, meta.monthly_price).
+#
+# Supported operations: index, show, destroy (cancel).
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/emergency_calling_services.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+puts '=== Emergency Calling Services ==='
+services = DIDWW::Client.emergency_calling_services
+           .includes(:country, :did_group_type, :dids)
+           .all
+puts "Found #{services.size} emergency calling services"
+
+services.first(5).each do |svc|
+  puts "\nService: #{svc.id}"
+  puts "  Name: #{svc.name}"
+  puts "  Reference: #{svc.reference}"
+  puts "  Status: #{svc.status}"
+  puts "  Country: #{svc.country&.name}"
+  puts "  DID Group Type: #{svc.did_group_type&.name}"
+  puts "  Activated: #{svc.activated_at}"
+  puts "  Canceled: #{svc.canceled_at}"  if svc.canceled_at
+  puts "  Renews: #{svc.renew_date}"     if svc.renew_date
+  puts "  Attached DIDs: #{svc.dids.map(&:number).join(', ')}" if svc.dids&.any?
+  if svc.meta
+    puts "  Setup price:   #{svc.meta[:setup_price]}"   if svc.meta[:setup_price]
+    puts "  Monthly price: #{svc.meta[:monthly_price]}" if svc.meta[:monthly_price]
+  end
+end
+
+# Filter by status
+puts "\n=== Only active emergency calling services ==="
+active = DIDWW::Client.emergency_calling_services
+         .where(status: 'active')
+         .all
+puts "Found #{active.size} active services"
+
+# Cancel a service (destroy) — uncomment to try:
+#
+# if (svc = services.find { |s| s.status == 'active' })
+#   puts "\nCancelling service #{svc.id}..."
+#   if svc.destroy
+#     puts 'Service canceled'
+#   else
+#     puts "Error: #{svc.errors.full_messages}"
+#   end
+# end
+
+puts "\nAvailable statuses: #{DIDWW::Resource::EmergencyCallingService::STATUSES.join(', ')}"

data/examples/emergency_requirement_validations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# Validates an emergency calling service order before placing it (2026-04-16).
+#
+# EmergencyRequirementValidation is a write-only endpoint: POST the
+# intended (emergency_requirement, address, identity) triple and the server
+# either returns 204 No Content (OK to order) or JSONAPI errors describing
+# what the customer must fix (missing address fields, wrong identity type,
+# unsupported area level, etc.).
+#
+# Usage: DIDWW_API_KEY=your_api_key ruby examples/emergency_requirement_validations.rb
+
+require 'bundler/setup'
+require 'didww'
+
+DIDWW::Client.configure do |client|
+  client.api_key  = ENV.fetch('DIDWW_API_KEY') { abort 'Please set DIDWW_API_KEY' }
+  client.api_mode = :sandbox
+end
+
+# Pick any emergency requirement + address + identity from your account.
+requirement = DIDWW::Client.emergency_requirements.all.first
+address     = DIDWW::Client.addresses.all.first
+identity    = DIDWW::Client.identities.all.first
+
+abort 'No emergency_requirements found on this account' unless requirement
+abort 'No addresses found on this account'               unless address
+abort 'No identities found on this account'              unless identity
+
+puts 'Validating order setup with:'
+puts "  Emergency Requirement: #{requirement.id}"
+puts "  Address:               #{address.id}"
+puts "  Identity:              #{identity.id}"
+
+validation = DIDWW::Client.emergency_requirement_validation.new(
+  relationships: {
+    emergency_requirement: requirement,
+    address: address,
+    identity: identity
+  }
+)
+
+if validation.save
+  puts "\nValidation passed — this combination can be used to order emergency calling."
+else
+  puts "\nValidation failed:"
+  validation.errors.full_messages.each { |msg| puts "  * #{msg}" }
+end