feat: complete SipConfiguration attributes for API 2026-04-16

CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## Unreleased
+## [4.1.0] - 2026-05-04
+
+### Added
+- Complete the API 2026-04-16 `SipConfiguration` attribute set: `enabledSipRegistration`, `useDidInRuri`, `cnamLookup`, `networkProtocolPriority`, `diversionInjectMode`, plus the server-generated read-only `incomingAuthUsername` / `incomingAuthPassword`.
+- `SipConfiguration#toString` and `CredentialsAndIpAuthenticationMethod#toString` redact credential fields with `[FILTERED]` so default logging / debugger / unhandled exception traces never expose plaintext credentials. Wire payload is unaffected.
+- `SipConfiguration` auto-cascades server-enforced field dependencies on assignment: `setEnabledSipRegistration(true)` clears `host` / `port`, `setEnabledSipRegistration(false)` forces `useDidInRuri = false`, and `setHost(<non-null>)` flips both. Jackson populates the private fields via reflection during deserialization, so server responses are not clobbered.
 
 ### Breaking Changes
 - Renamed `Order#isCancelled` to `Order#isCanceled` for wire-format consistency

README.md

@@ -254,6 +254,49 @@ client.voiceInTrunks().update(created);
 client.voiceInTrunks().delete(created.getId());
 ```
 
+#### SIP Registration (2026-04-16)
+
+A Voice In Trunk can also authenticate inbound calls via SIP registration
+credentials generated by DIDWW. The SDK auto-cascades the dependent fields
+the server requires:
+
+* `setEnabledSipRegistration(true)` clears any previously-set `host` /
+  `port` (the server rejects them with 422 otherwise);
+* `setHost(<non-null>)` flips `enabledSipRegistration` to `false` and
+  forces `useDidInRuri = false` so the server accepts the disable PATCH.
+
+The server generates `incomingAuthUsername` and `incomingAuthPassword` and
+surfaces them in the response when SIP registration is enabled (read-only
+— the SDK exposes only getters).
+
+```java
+SipConfiguration sip = new SipConfiguration();
+sip.setEnabledSipRegistration(true);
+sip.setUseDidInRuri(true);
+sip.setCnamLookup(true);
+
+VoiceInTrunk trunk = new VoiceInTrunk();
+trunk.setName("Office (registered)");
+trunk.setConfiguration(sip);
+SipConfiguration created = (SipConfiguration)
+        client.voiceInTrunks().create(trunk).getData().getConfiguration();
+// created.getIncomingAuthUsername() — server-generated
+// created.getIncomingAuthPassword() — server-generated
+```
+
+To disable SIP registration on an existing trunk, just set `host` — the
+cascade flips `enabledSipRegistration` and `useDidInRuri` to `false`
+automatically:
+
+```java
+SipConfiguration disable = new SipConfiguration();
+disable.setHost("sip.example.com");
+
+VoiceInTrunk update = new VoiceInTrunk().withId("trunk-uuid");
+update.setConfiguration(disable);
+client.voiceInTrunks().update(update);
+```
+
 ### Voice In Trunk Groups
 
 ```java

build.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 }
 
 group = "com.didww"
-version = "4.0.0"
+version = "4.1.0"
 
 java {
     sourceCompatibility = JavaVersion.VERSION_11

examples/README.md

@@ -42,6 +42,7 @@ DIDWW_API_KEY=your_api_key ./gradlew runExample -PexampleClass=com.didww.example
 | [`com.didww.examples.UploadFileExample`](src/main/java/com/didww/examples/UploadFileExample.java) | Creates (or reads) a file, encrypts it, and uploads to `encrypted_files`. |
 | [`com.didww.examples.IdentityAddressProofsExample`](src/main/java/com/didww/examples/IdentityAddressProofsExample.java) | Creates identity and address, encrypts and uploads files, attaches proofs to both. |
 | [`com.didww.examples.VoiceInTrunkGroupsExample`](src/main/java/com/didww/examples/VoiceInTrunkGroupsExample.java) | CRUD for trunk groups with trunk relationships. |
+| [`com.didww.examples.VoiceInTrunkSipRegistrationExample`](src/main/java/com/didww/examples/VoiceInTrunkSipRegistrationExample.java) | End-to-end SIP registration flow: create with `enabledSipRegistration=true`, rename, disable by setting `host`, re-enable by toggling the flag. The SDK keeps the dependent fields (`host`, `port`, `useDidInRuri`) aligned with the server's validation rules automatically. |
 | [`com.didww.examples.VoiceOutTrunksExample`](src/main/java/com/didww/examples/VoiceOutTrunksExample.java) | CRUD for voice out trunks (requires account config). |
 | [`com.didww.examples.DidTrunkAssignmentExample`](src/main/java/com/didww/examples/DidTrunkAssignmentExample.java) | Demonstrates exclusive trunk/trunk group assignment on DIDs. |
 | [`com.didww.examples.DidReservationsExample`](src/main/java/com/didww/examples/DidReservationsExample.java) | Creates, lists, finds and deletes DID reservations. |

examples/src/main/java/com/didww/examples/VoiceInTrunkSipRegistrationExample.java

@@ -0,0 +1,92 @@
+package com.didww.examples;
+
+import com.didww.sdk.DidwwClient;
+import com.didww.sdk.resource.VoiceInTrunk;
+import com.didww.sdk.resource.configuration.SipConfiguration;
+import com.didww.sdk.resource.enums.CliFormat;
+import com.didww.sdk.resource.enums.Codec;
+import com.didww.sdk.resource.enums.TransportProtocol;
+
+import java.util.Arrays;
+
+/**
+ * End-to-end SIP registration flow on /voice_in_trunks (API 2026-04-16):
+ * create with sip_registration enabled → rename → disable by setting host
+ * → re-enable by toggling the flag. Demonstrates how the SDK keeps the
+ * dependent fields (host, port, useDidInRuri) aligned with the server's
+ * validation rules. The sandbox trunk is left in place after the script
+ * completes.
+ *
+ * Usage: DIDWW_API_KEY=xxx ./gradlew runExample -PexampleClass=com.didww.examples.VoiceInTrunkSipRegistrationExample
+ */
+public class VoiceInTrunkSipRegistrationExample {
+
+    public static void main(String[] args) {
+        DidwwClient client = ExampleClientFactory.fromEnv();
+        System.out.println("=== Java SDK — SIP registration flow ===");
+
+        // 1) Create with sip_registration enabled.
+        System.out.println("\n[1/4] Create with sip_registration enabled...");
+        SipConfiguration sip = new SipConfiguration();
+        sip.setEnabledSipRegistration(true);
+        sip.setUseDidInRuri(true);
+        sip.setCnamLookup(false);
+        sip.setCodecIds(Arrays.asList(Codec.PCMU, Codec.PCMA));
+        sip.setTransportProtocolId(TransportProtocol.UDP);
+
+        VoiceInTrunk trunk = new VoiceInTrunk();
+        trunk.setName("java-sip-registration-" + System.currentTimeMillis());
+        trunk.setPriority(1);
+        trunk.setWeight(100);
+        trunk.setCliFormat(CliFormat.E164);
+        trunk.setRingingTimeout(30);
+        trunk.setConfiguration(sip);
+
+        VoiceInTrunk created = client.voiceInTrunks().create(trunk).getData();
+        String trunkId = created.getId();
+        SipConfiguration cfg1 = (SipConfiguration) created.getConfiguration();
+        System.out.println("  id=" + trunkId);
+        System.out.println("  incomingAuthUsername=" + cfg1.getIncomingAuthUsername());
+        System.out.println("  incomingAuthPassword=" + cfg1.getIncomingAuthPassword());
+
+        // 2) Rename — single-field PATCH.
+        System.out.println("\n[2/4] Rename trunk...");
+        VoiceInTrunk rename = new VoiceInTrunk().withId(trunkId);
+        rename.setName("java-renamed-" + System.currentTimeMillis());
+        client.voiceInTrunks().update(rename);
+        System.out.println("  name=" + rename.getName());
+
+        // 3) Disable sip_registration by setting host.
+        System.out.println("\n[3/4] Disable by setting host...");
+        SipConfiguration disable = new SipConfiguration();
+        disable.setHost("203.0.113.10");
+        VoiceInTrunk update = new VoiceInTrunk().withId(trunkId);
+        update.setConfiguration(disable);
+        client.voiceInTrunks().update(update);
+        SipConfiguration cfg3 = (SipConfiguration) client.voiceInTrunks().find(trunkId).getData().getConfiguration();
+        System.out.println("  enabledSipRegistration=" + cfg3.getEnabledSipRegistration());
+        System.out.println("  useDidInRuri=" + cfg3.getUseDidInRuri());
+        System.out.println("  host=" + cfg3.getHost());
+        System.out.println("  incomingAuthUsername=" + cfg3.getIncomingAuthUsername());
+
+        // 4) Re-enable sip_registration. The SDK should send host=null / port=null
+        //    on the wire so the server clears the values it had persisted.
+        System.out.println("\n[4/4] Re-enable by toggling enabledSipRegistration...");
+        SipConfiguration reEnable = new SipConfiguration();
+        reEnable.setEnabledSipRegistration(true);
+        reEnable.setUseDidInRuri(true);
+        VoiceInTrunk update4 = new VoiceInTrunk().withId(trunkId);
+        update4.setConfiguration(reEnable);
+        try {
+            client.voiceInTrunks().update(update4);
+            SipConfiguration cfg4 = (SipConfiguration) client.voiceInTrunks().find(trunkId).getData().getConfiguration();
+            System.out.println("  enabledSipRegistration=" + cfg4.getEnabledSipRegistration());
+            System.out.println("  host=" + cfg4.getHost());
+            System.out.println("  incomingAuthUsername=" + cfg4.getIncomingAuthUsername());
+            System.out.println("\n=== PASS — trunk " + trunkId + " left in sandbox ===");
+        } catch (Exception e) {
+            System.out.println("  ✗ FAIL: " + e.getMessage());
+            System.out.println("\n=== FAIL at re-enable — trunk " + trunkId + " left in sandbox ===");
+        }
+    }
+}

src/main/java/com/didww/sdk/internal/Redact.java

@@ -0,0 +1,20 @@
+package com.didww.sdk.internal;
+
+/**
+ * Shared helpers for masking sensitive credential values in default
+ * {@code toString} / debugger / log output. The wire format is never
+ * affected — only Stringer-style methods route through these helpers.
+ */
+public final class Redact {
+
+    private Redact() {}
+
+    /**
+     * Returns {@code "[FILTERED]"} for any non-null input and {@code "null"}
+     * otherwise. The {@code "null"} passthrough avoids leaking
+     * "this field was set" information when the value is genuinely unset.
+     */
+    public static String mask(String value) {
+        return value == null ? "null" : "[FILTERED]";
+    }
+}

src/main/java/com/didww/sdk/resource/authenticationmethod/CredentialsAndIpAuthenticationMethod.java

@@ -1,5 +1,6 @@
 package com.didww.sdk.resource.authenticationmethod;
 
+import com.didww.sdk.internal.Redact;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.Getter;
@@ -28,4 +29,20 @@ public class CredentialsAndIpAuthenticationMethod extends AuthenticationMethod {
     public String getType() {
         return "credentials_and_ip";
     }
+
+    /**
+     * Override toString() so default logging / debugger inspection / unhandled
+     * exception traces never leak server-generated credentials. The wire
+     * payload is unaffected — Jackson serializes the real values (or strips
+     * them via the WRITE_ONLY access modifier on incoming requests).
+     */
+    @Override
+    public String toString() {
+        return "CredentialsAndIpAuthenticationMethod("
+                + "allowedSipIps=" + allowedSipIps
+                + ", techPrefix=" + techPrefix
+                + ", username=" + Redact.mask(username)
+                + ", password=" + Redact.mask(password)
+                + ")";
+    }
 }

src/main/java/com/didww/sdk/resource/configuration/SipConfiguration.java

@@ -1,8 +1,11 @@
 package com.didww.sdk.resource.configuration;
 
+import com.didww.sdk.internal.Redact;
 import com.didww.sdk.resource.enums.*;
 import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.Setter;
 
@@ -15,10 +18,21 @@ public class SipConfiguration extends TrunkConfiguration {
     @JsonProperty("username")
     private String username;
 
+    // host / port / enabledSipRegistration use manual setters that propagate
+    // server-enforced field dependencies (API 2026-04-16). Lombok would
+    // otherwise generate plain setters from the class-level @Setter, which
+    // would skip the cascade. Jackson deserializes into the private fields
+    // directly via reflection (no setter present), so server responses
+    // bypass the cascade on the way in — exactly what we want, since
+    // server data is already internally consistent.
+    @Setter(AccessLevel.NONE)
     @JsonProperty("host")
+    @JsonInclude(JsonInclude.Include.ALWAYS)
     private String host;
 
+    @Setter(AccessLevel.NONE)
     @JsonProperty("port")
+    @JsonInclude(JsonInclude.Include.ALWAYS)
     private Integer port;
 
     @JsonProperty("codec_ids")
@@ -102,9 +116,112 @@ public class SipConfiguration extends TrunkConfiguration {
     @JsonProperty("diversion_relay_policy")
     private DiversionRelayPolicy diversionRelayPolicy;
 
+    @JsonProperty("diversion_inject_mode")
+    private DiversionInjectMode diversionInjectMode;
+
+    @JsonProperty("network_protocol_priority")
+    private NetworkProtocolPriority networkProtocolPriority;
+
+    /**
+     * Whether SIP registration is enabled. When {@code true} the server
+     * generates {@code incoming_auth_username} / {@code incoming_auth_password}
+     * and the trunk's {@code host} and {@code port} must be left blank. When
+     * disabling sip registration on an existing trunk, the same PATCH must
+     * also set {@code host} to a non-blank value and {@code use_did_in_ruri}
+     * to {@code false}, or the server returns 422. (API 2026-04-16)
+     */
+    @Setter(AccessLevel.NONE)
+    @JsonProperty("enabled_sip_registration")
+    private Boolean enabledSipRegistration;
+
+    @JsonProperty("use_did_in_ruri")
+    private Boolean useDidInRuri;
+
+    @JsonProperty("cnam_lookup")
+    private Boolean cnamLookup;
+
+    /**
+     * Server-generated SIP authentication username, returned in responses
+     * when {@code enabledSipRegistration} is {@code true}. Read-only; the API
+     * rejects any write attempt with HTTP 400 "Param not allowed". (API 2026-04-16)
+     */
+    @JsonProperty(value = "incoming_auth_username", access = JsonProperty.Access.WRITE_ONLY)
+    @Setter(AccessLevel.PRIVATE)
+    private String incomingAuthUsername;
+
+    /**
+     * Server-generated SIP authentication password, returned in responses
+     * when {@code enabledSipRegistration} is {@code true}. Read-only; the API
+     * rejects any write attempt with HTTP 400 "Param not allowed". (API 2026-04-16)
+     */
+    @JsonProperty(value = "incoming_auth_password", access = JsonProperty.Access.WRITE_ONLY)
+    @Setter(AccessLevel.PRIVATE)
+    private String incomingAuthPassword;
+
+    /**
+     * Setting host to a non-null value cascades enabledSipRegistration and
+     * useDidInRuri to false because the server requires those states
+     * whenever host is present (API 2026-04-16).
+     */
+    public void setHost(String host) {
+        if (host != null) {
+            this.enabledSipRegistration = false;
+            this.useDidInRuri = false;
+        }
+        this.host = host;
+    }
+
+    public void setPort(Integer port) {
+        this.port = port;
+    }
+
+    /**
+     * Setting enabledSipRegistration cascades dependent fields:
+     * <ul>
+     * <li>true  -> nullify host / port and emit them as {@code null} on the
+     * wire (host/port must be blank when sip_registration is on). The wire
+     * emission fires unconditionally so PATCH against an existing trunk that
+     * already has host/port set server-side is told to clear them.</li>
+     * <li>false -> force useDidInRuri = false (must be disabled when
+     * sip_registration is disabled).</li>
+     * </ul>
+     */
+    public void setEnabledSipRegistration(Boolean enabledSipRegistration) {
+        if (Boolean.TRUE.equals(enabledSipRegistration)) {
+            // Always emit host: null and port: null on the wire so a PATCH
+            // against an existing trunk that already has them persisted on
+            // the server side is told to clear them.
+            this.host = null;
+            this.port = null;
+        } else if (Boolean.FALSE.equals(enabledSipRegistration)) {
+            this.useDidInRuri = false;
+        }
+        this.enabledSipRegistration = enabledSipRegistration;
+    }
+
     @Override
     @JsonIgnore
     public String getType() {
         return "sip_configurations";
     }
+
+    /**
+     * Override toString() so default logging / debugger inspection / unhandled
+     * exception traces never leak SIP credentials. The wire payload is
+     * unaffected — Jackson serializes the real values (or strips read-only
+     * ones via @JsonProperty WRITE_ONLY).
+     */
+    @Override
+    public String toString() {
+        return "SipConfiguration("
+                + "username=" + username
+                + ", host=" + host
+                + ", port=" + port
+                + ", authPassword=" + Redact.mask(authPassword)
+                + ", enabledSipRegistration=" + enabledSipRegistration
+                + ", useDidInRuri=" + useDidInRuri
+                + ", incomingAuthUsername=" + Redact.mask(incomingAuthUsername)
+                + ", incomingAuthPassword=" + Redact.mask(incomingAuthPassword)
+                + ")";
+    }
 }

src/main/java/com/didww/sdk/resource/enums/DiversionInjectMode.java

@@ -0,0 +1,8 @@
+package com.didww.sdk.resource.enums;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public enum DiversionInjectMode {
+    @JsonProperty("none") NONE,
+    @JsonProperty("did_number") DID_NUMBER;
+}

src/main/java/com/didww/sdk/resource/enums/NetworkProtocolPriority.java

@@ -0,0 +1,11 @@
+package com.didww.sdk.resource.enums;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public enum NetworkProtocolPriority {
+    @JsonProperty("force_ipv4") FORCE_IPV4,
+    @JsonProperty("force_ipv6") FORCE_IPV6,
+    @JsonProperty("any") ANY,
+    @JsonProperty("prefer_ipv4") PREFER_IPV4,
+    @JsonProperty("prefer_ipv6") PREFER_IPV6;
+}