didww-v3 6.0.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aa466258f09ae99e535c21caeec5d0e274fe77288dd99adb4161e426e7eb45c
-  data.tar.gz: 8c35e66178155231aa3d3fbe8fc9907f22f6aabaacfbad406b926adb093bbb92
+  metadata.gz: 9cdeedbb317141c84de28bbedb4f652b858793e257d8d84f70155b08fc54623c
+  data.tar.gz: c48319beb5292ef53595e7905d4ac62ff0e59685bcb57eb48c2f7e6efbb7bd3e
 SHA512:
-  metadata.gz: 8cb5d98d5d0bc28a2c082fe730f0bb314e7e812d75d5326f502149d4c6b645fd876069113f9271ee3f9ac77ac052aa49573b8e1c2d8f79ff9fefb445a8df764e
-  data.tar.gz: ab528d899547eac431d54968f117a8fb1426a8d520fd7ce6660d9730f0f7981ba32df7ef5e2ee00c87d619be7af2d0c0b1746c20b2691266bf7c61b7f8ed885f
+  metadata.gz: 42be04280b6673a827de5f4bc680f032f28d72437137d081455f2168aa02e92d3861b7fc842e6c70406e6495d1f377745f90a23ead254fdf0a5a6caf40417d63
+  data.tar.gz: e6aeccf261500d0307c5cbc7eae427880a853d008ce28639ff2512daa1ea1cb40c54962b3d0f972f7e3ea0a73274bc40a6a8a57b9df45689b9c0ddfb83987acb

data/CHANGELOG.md

@@ -4,6 +4,19 @@ 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).
 

data/README.md

@@ -205,6 +205,46 @@ 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:

data/examples/voice_in_trunks.rb

@@ -41,3 +41,68 @@ if !trunks.empty?
   puts "  Description: #{specific_trunk.description}"
   puts "  Created at: #{specific_trunk.created_at}"
 end
+
+# 2026-04-16 — surface the API 2026-04-16 SIP-registration-related attributes when
+# the trunk uses a SIP configuration. `incoming_auth_username` /
+# `incoming_auth_password` are server-generated and only present when
+# `enabled_sip_registration` is true.
+sip_trunk = trunks.find { |t| t.configuration.is_a?(DIDWW::ComplexObject::SipConfiguration) }
+if sip_trunk
+  puts "\n=== SIP Configuration (2026-04-16 attributes) ==="
+  config = sip_trunk.configuration
+  puts "Trunk: #{sip_trunk.name}"
+  puts "  enabled_sip_registration:  #{config.enabled_sip_registration.inspect}"
+  puts "  use_did_in_ruri:           #{config.use_did_in_ruri.inspect}"
+  puts "  network_protocol_priority: #{config.network_protocol_priority.inspect}"
+  puts "  diversion_relay_policy:    #{config.diversion_relay_policy.inspect}"
+  puts "  diversion_inject_mode:     #{config.diversion_inject_mode.inspect}"
+  puts "  cnam_lookup:               #{config.cnam_lookup.inspect}"
+  if config.enabled_sip_registration
+    puts "  incoming_auth_username:    #{config.incoming_auth_username.inspect}"
+    puts "  incoming_auth_password:    #{config.incoming_auth_password.inspect}"
+  else
+    puts '  (incoming_auth credentials only appear when SIP registration is enabled)'
+  end
+end
+
+# Example: create a new SIP trunk with SIP registration enabled. The server
+# generates `incoming_auth_username` / `incoming_auth_password` and returns
+# them in the response. They are READ-ONLY — sending them on POST/PATCH
+# returns 400 Param not allowed; the SDK strips them from write payloads.
+#
+# Server-side rules to keep in mind:
+#   * When `enabled_sip_registration: true`, `host` and `port` MUST be left
+#     blank (the server will register inbound and pick the host itself).
+#   * When DISABLING SIP registration on an existing trunk, you must
+#     simultaneously set `host` to a non-blank value and `use_did_in_ruri`
+#     to `false` in the same PATCH — otherwise the server returns 422.
+#
+# Uncomment to actually create a trunk in your sandbox account:
+#
+# new_trunk = DIDWW::Resource::VoiceInTrunk.new(
+#   name: "SIP-registration trunk #{Time.now.to_i}",
+#   priority: 1,
+#   weight: 100,
+#   cli_format: 'e164',
+#   ringing_timeout: 30,
+#   configuration: DIDWW::ComplexObject::SipConfiguration.new(
+#     # NOTE: do NOT set `host` here — the server requires it to be blank
+#     # when enabled_sip_registration is true.
+#     enabled_sip_registration: true,
+#     use_did_in_ruri: true,
+#     cnam_lookup: false,
+#     diversion_relay_policy: 'as_is',
+#     diversion_inject_mode: 'did_number',
+#     network_protocol_priority: 'prefer_ipv4',
+#     codec_ids: [9, 7],
+#     transport_protocol_id: 1
+#   )
+# )
+# created = new_trunk.save
+# if created
+#   puts "Created trunk #{new_trunk.id}"
+#   puts "  incoming_auth_username: #{new_trunk.configuration.incoming_auth_username}"
+#   puts "  incoming_auth_password: #{new_trunk.configuration.incoming_auth_password}"
+# else
+#   puts "Errors: #{new_trunk.errors.full_messages}"
+# end

data/lib/didww/complex_objects/authentication_methods/credentials_and_ip.rb

@@ -12,8 +12,8 @@ module DIDWW
         # only in responses; they cannot be set from the client on create.
         property :allowed_sip_ips, type: :strings
         property :tech_prefix, type: :string
-        property :username, type: :string
-        property :password, type: :string
+        property :username, type: :string, sensitive: true
+        property :password, type: :string, sensitive: true
       end
     end
   end

data/lib/didww/complex_objects/base.rb

@@ -13,6 +13,8 @@ module DIDWW
 
         def property(name, options = {})
           schema.add(name, options)
+          read_only_attributes << name.to_s if options[:read_only]
+          sensitive_attributes << name.to_s if options[:sensitive]
           define_method(name.to_sym) { self[name] }
           define_method("#{name}=".to_sym) { |val| self[name] = val }
         end
@@ -21,6 +23,22 @@ module DIDWW
           @schema ||= JsonApiClient::Schema.new
         end
 
+        # Names of attributes that the server returns but does not accept on
+        # write. Excluded from `as_json` so that round-tripping a resource
+        # through PATCH does not echo them back and trigger 400 Param not
+        # allowed.
+        def read_only_attributes
+          @read_only_attributes ||= []
+        end
+
+        # Names of attributes whose values are credentials/secrets. The wire
+        # format is unchanged — `as_json` still emits the real values — but
+        # `#inspect` redacts them so default logging / error reports / REPL
+        # echoes never leak credentials downstream.
+        def sensitive_attributes
+          @sensitive_attributes ||= []
+        end
+
         # Type casting for JsonApiClient parser/setters
         def cast(value, default)
           case value
@@ -77,14 +95,29 @@ module DIDWW
       end
 
       # When we represent this resource for serialization (create/update), we do so
-      # with this implementation
+      # with this implementation. Read-only attributes are excluded — the server
+      # rejects them with 400 Param not allowed.
       def as_json(*)
+        excluded = self.class.read_only_attributes
         { type: type }.with_indifferent_access.tap do |h|
-          h[:attributes] = attributes.as_json
+          h[:attributes] = attributes.as_json.reject { |k, _| excluded.include?(k.to_s) }
         end
       end
 
       def as_json_api(*); as_json end
+
+      # Redacts sensitive attribute values so credentials never leak into
+      # default logs / REPL output / error reports. The on-the-wire payload
+      # is unaffected (see `#as_json`).
+      FILTERED = '[FILTERED]'.freeze
+      def inspect
+        sensitive = self.class.sensitive_attributes
+        formatted = attributes.map do |k, v|
+          display = sensitive.include?(k.to_s) && !v.nil? ? FILTERED : v
+          "#{k}=#{display.inspect}"
+        end
+        "#<#{self.class.name} #{formatted.join(' ')}>"
+      end
     end
   end
 end

data/lib/didww/complex_objects/configurations/sip_configuration.rb

@@ -18,7 +18,7 @@ module DIDWW
         # Nullable: No
         # Description: Optional authorization user for the SIP server
 
-        property :auth_password, type: :string
+        property :auth_password, type: :string, sensitive: true
         # Type: String
         # Nullable: No
         # Description: Optional authorization password for the SIP server
@@ -180,6 +180,54 @@ module DIDWW
         # See DIVERSION_RELAY_POLICIES for available values.
         # In API v3.4 this attribute was named `diversion_relay_mode`.
 
+        property :diversion_inject_mode, type: :string
+        # Type: String
+        # Nullable: No
+        # Description: Diversion header injection mode. See
+        # DIVERSION_INJECT_MODES for available values. (API 2026-04-16)
+
+        property :network_protocol_priority, type: :string
+        # Type: String
+        # Nullable: No
+        # Description: SIP network protocol priority. See
+        # NETWORK_PROTOCOL_PRIORITIES for available values. (API 2026-04-16)
+
+        property :enabled_sip_registration, type: :boolean
+        # Type: Boolean
+        # Nullable: No
+        # Description: Enables SIP registration. When true the API generates
+        # `incoming_auth_username` / `incoming_auth_password`; the trunk's
+        # `host` and `port` must be left blank. When disabling sip
+        # registration on an existing trunk, the same PATCH must also set
+        # `host` to a non-blank value and `use_did_in_ruri` to false, or
+        # the server returns 422. (API 2026-04-16)
+
+        property :use_did_in_ruri, type: :boolean
+        # Type: Boolean
+        # Nullable: No
+        # Description: When true, the trunk's R-URI uses the DID number.
+        # Requires `enabled_sip_registration` to be true. (API 2026-04-16)
+
+        property :cnam_lookup, type: :boolean
+        # Type: Boolean
+        # Nullable: No
+        # Description: Enables CNAM resolution for inbound calls on this
+        # trunk. (API 2026-04-16)
+
+        property :incoming_auth_username, type: :string, read_only: true, sensitive: true
+        # Type: String
+        # Nullable: Yes
+        # Description: Server-generated SIP authentication username, returned in
+        #   responses when `enabled_sip_registration` is true. Read-only; the API
+        #   rejects any write attempt with 400 Param not allowed. (API 2026-04-16)
+
+        property :incoming_auth_password, type: :string, read_only: true, sensitive: true
+        # Type: String
+        # Nullable: Yes
+        # Description: Server-generated SIP authentication password, returned in
+        #   responses when `enabled_sip_registration` is true. Read-only; the API
+        #   rejects any write attempt with 400 Param not allowed. (API 2026-04-16)
+
         DIVERSION_RELAY_POLICY_NONE = 'none'
         DIVERSION_RELAY_POLICY_AS_IS = 'as_is'
         DIVERSION_RELAY_POLICY_SIP = 'sip'
@@ -192,6 +240,28 @@ module DIDWW
           DIVERSION_RELAY_POLICY_TEL
         ].freeze
 
+        DIVERSION_INJECT_MODE_NONE = 'none'
+        DIVERSION_INJECT_MODE_DID_NUMBER = 'did_number'
+
+        DIVERSION_INJECT_MODES = [
+          DIVERSION_INJECT_MODE_NONE,
+          DIVERSION_INJECT_MODE_DID_NUMBER
+        ].freeze
+
+        NETWORK_PROTOCOL_PRIORITY_FORCE_IPV4 = 'force_ipv4'
+        NETWORK_PROTOCOL_PRIORITY_FORCE_IPV6 = 'force_ipv6'
+        NETWORK_PROTOCOL_PRIORITY_ANY = 'any'
+        NETWORK_PROTOCOL_PRIORITY_PREFER_IPV4 = 'prefer_ipv4'
+        NETWORK_PROTOCOL_PRIORITY_PREFER_IPV6 = 'prefer_ipv6'
+
+        NETWORK_PROTOCOL_PRIORITIES = [
+          NETWORK_PROTOCOL_PRIORITY_FORCE_IPV4,
+          NETWORK_PROTOCOL_PRIORITY_FORCE_IPV6,
+          NETWORK_PROTOCOL_PRIORITY_ANY,
+          NETWORK_PROTOCOL_PRIORITY_PREFER_IPV4,
+          NETWORK_PROTOCOL_PRIORITY_PREFER_IPV6
+        ].freeze
+
         MEDIA_ENCRYPTION_MODES = [
                                    'disabled',
                                    'srtp_sdes',
@@ -257,6 +327,58 @@ module DIDWW
         def transport_protocol
           TRANSPORT_PROTOCOLS[transport_protocol_id]
         end
+
+        # Auto-cascade for server-enforced field dependencies (2026-04-16).
+        #
+        # The server validates these combinations and rejects mismatches with
+        # 422; the SDK fixes them up at assignment time so user code never has
+        # to track the full server-side rule set. Future server-required
+        # cascades are added here without the caller needing to know.
+        #
+        # Rules:
+        #   * `enabled_sip_registration = true`  => host = nil, port = nil
+        #     (server requires both blank when registration is enabled)
+        #   * `enabled_sip_registration = false` => use_did_in_ruri = false
+        #     (server requires use_did_in_ruri disabled when sip_registration is)
+        #   * `host = <non-nil>` => enabled_sip_registration = false,
+        #     use_did_in_ruri = false (host requires sip_registration disabled,
+        #     which in turn requires use_did_in_ruri disabled)
+        #
+        # Constructor-time `[]=` assignments bypass these setters intentionally
+        # so that responses returned from the server (e.g. a fixture with
+        # `enabled_sip_registration: true` AND `host: nil`) deserialize as-is.
+        def enabled_sip_registration=(val)
+          case val
+          when true
+            # Clear host/port only if they were already set — never emit a
+            # spurious `host: null` on a fresh config, which would otherwise
+            # widen every PATCH/POST body. If the trunk had a host, we have
+            # to send `host: null` explicitly so the server clears it.
+            self[:host] = nil if attributes.key?('host') && !self[:host].nil?
+            self[:port] = nil if attributes.key?('port') && !self[:port].nil?
+          when false
+            # Server requires use_did_in_ruri = false whenever sip_registration
+            # is disabled. Always emit it on the wire so the server's check
+            # passes regardless of the prior state of the field.
+            self[:use_did_in_ruri] = false
+          else
+            # `nil` (or any non-bool) — caller is unsetting the field. No
+            # cascade: dependent fields stay as the caller left them.
+          end
+          self[:enabled_sip_registration] = val
+        end
+
+        def host=(val)
+          unless val.nil?
+            # Setting host implies sip_registration is disabled (server-side
+            # validation), which in turn implies use_did_in_ruri = false.
+            # Always emit both on the wire so the server's checks pass
+            # without the caller having to know the rule set.
+            self[:enabled_sip_registration] = false
+            self[:use_did_in_ruri] = false
+          end
+          self[:host] = val
+        end
       end
     end
   end

data/lib/didww/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module DIDWW
-  VERSION = '6.0.0'.freeze
+  VERSION = '6.1.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: didww-v3
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.1.0
 platform: ruby
 authors:
 - Alex Korobeinikov