Merge pull request #27 from didww/feat/api-2026-04-16

Add API version 2026-04-16 support

Author: Fivell

.gitignore

@@ -0,0 +1,24 @@
+# Claude AI
+.claude/
+
+# Coverage
+coverage.out
+
+# Compiled example binaries (go build artifacts)
+address_verifications
+did_groups
+did_history
+dids
+emergency_calling_services
+emergency_requirement_validations
+emergency_requirements
+emergency_verifications
+exports
+identities
+orders
+orders_emergency
+shared_capacity_groups
+voice_in_trunk_groups
+voice_out_trunks
+/emergency_scenario
+/did_trunk_assignment

README.md

@@ -15,9 +15,12 @@ This SDK implements JSON:API serialization and deserialization without external
 Read more https://doc.didww.com/api
 
 This SDK targets DIDWW API v3 documentation version:
-[https://doc.didww.com/api3/2022-05-10/index.html](https://doc.didww.com/api3/2022-05-10/index.html)
+[https://doc.didww.com/api3/2026-04-16/index.html](https://doc.didww.com/api3/2026-04-16/index.html)
 
-The client sends the `X-DIDWW-API-Version: 2022-05-10` header with each request.
+The client sends the `X-DIDWW-API-Version: 2026-04-16` header with each request.
+
+Version **3.x** targets API version `2026-04-16`.
+Version **2.x** (branch `release-2`) targets API version `2022-05-10`.
 
 ## Requirements
 
@@ -29,6 +32,11 @@ The client sends the `X-DIDWW-API-Version: 2022-05-10` header with each request.
 go get github.com/didww/didww-api-3-go-sdk
 ```
 
+**Note on module path:** This module intentionally does not use a `/v3` suffix,
+following the same convention established in v2. The major version is bumped in
+`go.mod` and tagged releases, but the import path stays
+`github.com/didww/didww-api-3-go-sdk` for backward compatibility.
+
 ## Usage
 
 ```go
@@ -161,8 +169,14 @@ proofTypes, _ := client.ProofTypes().List(ctx, nil)
 // Public Keys
 publicKeys, _ := client.PublicKeys().List(ctx, nil)
 
-// Requirements
-requirements, _ := client.Requirements().List(ctx, nil)
+// Address Requirements
+requirements, _ := client.AddressRequirements().List(ctx, nil)
+
+// Emergency Requirements (2026-04-16)
+emergReqs, _ := client.EmergencyRequirements().List(ctx, nil)
+
+// DID History (2026-04-16)
+history, _ := client.DIDHistory().List(ctx, nil)
 
 // Supporting Document Templates
 templates, _ := client.SupportingDocumentTemplates().List(ctx, nil)
@@ -232,19 +246,32 @@ created, _ := client.VoiceInTrunkGroups().Create(ctx, group)
 > **Note:** Voice Out Trunks require additional account configuration. Contact DIDWW support to enable.
 > The `replace_cli` and `randomize_cli` values of `OnCliMismatchAction` also require account configuration.
 
+Voice Out Trunks use a polymorphic `AuthenticationMethod` (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 `TwilioAccountSid`.
+- **`ip_only`** -- read-only; can only be configured by DIDWW staff upon request. Cannot be set via the API.
+
 ```go
-import "github.com/didww/didww-api-3-go-sdk/resource/enums"
+import (
+    "github.com/didww/didww-api-3-go-sdk/resource/authenticationmethod"
+    "github.com/didww/didww-api-3-go-sdk/resource/enums"
+)
 
+// 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.VoiceOutTrunk{
-    Name:                "My Outbound Trunk",
-    AllowedSipIPs:       []string{"0.0.0.0/0"},
-    AllowedRtpIPs:       []string{"0.0.0.0/0"},
-    DstPrefixes:         []string{},
+    Name: "My Outbound Trunk",
+    AuthenticationMethod: &authenticationmethod.CredentialsAndIp{
+        AllowedSipIPs: []string{"203.0.113.0/24"},
+    },
     DefaultDstAction:    enums.DefaultDstActionAllowAll,
     OnCliMismatchAction: enums.OnCliMismatchActionRejectCall,
     MediaEncryptionMode: enums.MediaEncryptionModeDisabled,
 }
 created, _ := client.VoiceOutTrunks().Create(ctx, trunk)
+// created.AuthenticationMethod.(*authenticationmethod.CredentialsAndIp).Username -- server-generated
+// created.AuthenticationMethod.(*authenticationmethod.CredentialsAndIp).Password -- server-generated
 ```
 
 ### Orders
@@ -335,14 +362,41 @@ verification := &didww.AddressVerification{
 created, _ := client.AddressVerifications().Create(ctx, verification)
 ```
 
+### Emergency Services (2026-04-16)
+
+```go
+// List emergency requirements filtered by country
+params := didww.NewQueryParams().Filter("country.id", "country-uuid")
+reqs, _ := client.EmergencyRequirements().List(ctx, params)
+
+// Create emergency verification
+verification := &didww.EmergencyVerification{
+    AddressID:  "address-uuid",
+    IdentityID: "identity-uuid",
+    DIDIDs:     []string{"did-uuid"},
+}
+created, _ := client.EmergencyVerifications().Create(ctx, verification)
+
+// List emergency calling services
+services, _ := client.EmergencyCallingServices().List(ctx, nil)
+```
+
+### DID History (2026-04-16)
+
+```go
+// List DID history entries
+params := didww.NewQueryParams().Filter("did.id", "did-uuid")
+history, _ := client.DIDHistory().List(ctx, params)
+```
+
 ### Exports
 
 ```go
 import "github.com/didww/didww-api-3-go-sdk/resource/enums"
 
 export := &didww.Export{
     ExportType: enums.ExportTypeCdrIn,
-    Filters:    map[string]interface{}{"year": 2025, "month": 1},
+    Filters:    map[string]interface{}{"from": "2026-04-01 00:00:00", "to": "2026-04-16 00:00:00"},
 }
 created, _ := client.Exports().Create(ctx, export)
 ```
@@ -439,6 +493,7 @@ updated, _ := client.VoiceInTrunks().Update(ctx, trunk)
 | Available DID | `available_did_order_items` |
 | Reservation DID | `reservation_did_order_items` |
 | Capacity | `capacity_order_items` |
+| Emergency | `emergency_order_items` |
 | Generic (response only) | `generic_order_items` |
 
 ## Error Handling
@@ -478,7 +533,9 @@ if err != nil {
 | AvailableDID | `client.AvailableDIDs()` | list, find |
 | ProofType | `client.ProofTypes()` | list, find |
 | PublicKey | `client.PublicKeys()` | list |
-| Requirement | `client.Requirements()` | list, find |
+| AddressRequirement | `client.AddressRequirements()` | list, find |
+| EmergencyRequirement | `client.EmergencyRequirements()` | list, find |
+| DIDHistory | `client.DIDHistory()` | list |
 | SupportingDocumentTemplate | `client.SupportingDocumentTemplates()` | list, find |
 | Balance | `client.Balance()` | find |
 | DID | `client.DIDs()` | list, find, update, delete |
@@ -490,14 +547,17 @@ if err != nil {
 | CapacityPool | `client.CapacityPools()` | list, find, update |
 | SharedCapacityGroup | `client.SharedCapacityGroups()` | list, find, create, update, delete |
 | Order | `client.Orders()` | list, find, create, delete |
-| Export | `client.Exports()` | list, find, create |
+| Export | `client.Exports()` | list, find, create, update |
 | Address | `client.Addresses()` | list, find, create, update, delete |
-| AddressVerification | `client.AddressVerifications()` | list, find, create |
+| AddressVerification | `client.AddressVerifications()` | list, find, create, update |
+| EmergencyCallingService | `client.EmergencyCallingServices()` | list, find, delete |
+| EmergencyVerification | `client.EmergencyVerifications()` | list, find, create, update |
+| EmergencyRequirementValidation | `client.EmergencyRequirementValidations()` | create |
 | Identity | `client.Identities()` | list, find, create, update, delete |
 | EncryptedFile | `client.EncryptedFiles()` | list, find, delete |
 | PermanentSupportingDocument | `client.PermanentSupportingDocuments()` | create |
 | Proof | `client.Proofs()` | create |
-| RequirementValidation | `client.RequirementValidations()` | create |
+| AddressRequirementValidation | `client.AddressRequirementValidations()` | create |
 | StockKeepingUnit | include on `DIDGroups` | — |
 | QtyBasedPricing | include on `CapacityPools` | — |
 
@@ -509,9 +569,22 @@ if err != nil {
 The SDK distinguishes between date-only and datetime fields:
 
 - **Datetime fields** are deserialized as `time.Time` (UTC) when always present, or `*time.Time` when optional (nil if the API omits the value):
-  - All `CreatedAt` fields — `time.Time`, present on most resources
-  - Expiry fields — `*time.Time`: `DID.ExpiresAt`, `Proof.ExpiresAt`, `EncryptedFile.ExpireAt`; `DIDReservation.ExpireAt` is `time.Time` (always present)
-- **Date-only fields** (`Identity.BirthDate`, `CapacityPool.RenewDate`, order item `BilledFrom`/`BilledTo`) remain as `string` in `"YYYY-MM-DD"` format — Go has no separate date-only type, so the raw string avoids timezone ambiguity.
+  - `CreatedAt` — `time.Time`, present on most resources
+  - `ExpiresAt` — `*time.Time`: `DID`, `DIDReservation`, `Proof`, `EncryptedFile`
+  - `ActivatedAt` — `*time.Time`: `EmergencyCallingService` (nullable)
+  - `CanceledAt` — `*time.Time`: `EmergencyCallingService` (nullable)
+- **Date-only fields** remain as `string` in `"YYYY-MM-DD"` format — Go has no separate date-only type, so the raw string avoids timezone ambiguity:
+  - `Identity.BirthDate`
+  - `CapacityPool.RenewDate`, `EmergencyCallingService.RenewDate` (nullable)
+  - Order item `BilledFrom` / `BilledTo`
+- **String fields** (not numeric):
+  - `EmergencyRequirement.EstimateSetupTime` — e.g. `"7-14 days"`, `"1"`
+  - `EmergencyRequirement.RequirementRestrictionMessage` — nullable
+
+**Important changes from previous API versions:**
+- `ExpiresAt` replaces `ExpireAt` on `DIDReservation` and `EncryptedFile`
+- `RenewDate` is a date-only string, NOT a `time.Time`
+- `EstimateSetupTime` is a string, NOT an integer
 
 ```go
 did, _ := client.DIDs().Find(ctx, "uuid")
@@ -528,6 +601,7 @@ The SDK provides enum types in `github.com/didww/didww-api-3-go-sdk/resource/enu
 
 `CallbackMethod`, `IdentityType`, `OrderStatus`, `ExportType`, `ExportStatus`, `CliFormat`,
 `OnCliMismatchAction`\*, `MediaEncryptionMode`, `DefaultDstAction`, `VoiceOutTrunkStatus`,
+`EmergencyCallingServiceStatus`, `EmergencyVerificationStatus`, `DiversionRelayPolicy`,
 `TransportProtocol`, `Codec`, `RxDtmfFormat`, `TxDtmfFormat`, `SstRefreshMethod`,
 `ReroutingDisconnectCode`, `Feature`, `AreaLevel`, `AddressVerificationStatus`, `StirShakenMode`
 

address_verifications_test.go

@@ -29,7 +29,7 @@ func TestAddressVerificationsCreate(t *testing.T) {
 	})
 
 	cbURL := "http://example.com"
-	cbMethod := "GET"
+	cbMethod := "get"
 	av, err := server.client.AddressVerifications().Create(context.Background(), &resource.AddressVerification{
 		CallbackURL:    &cbURL,
 		CallbackMethod: &cbMethod,
@@ -63,6 +63,47 @@ func TestAddressVerificationsFind(t *testing.T) {
 	assert.Nil(t, av.RejectReasons)
 }
 
+func TestAddressVerificationsUpdateExternalReferenceID(t *testing.T) {
+	server, capturedBodyPtr := captureRequestBody(t, map[string]testRoute{
+		"PATCH /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e": {status: http.StatusOK, fixture: "address_verifications/update.json"},
+	})
+
+	extRef := "ext-ref-123"
+	av, err := server.client.AddressVerifications().Update(context.Background(), &resource.AddressVerification{
+		ID:                  "c8e004b0-87ec-4987-b4fb-ee89db099f0e",
+		ExternalReferenceID: &extRef,
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, "c8e004b0-87ec-4987-b4fb-ee89db099f0e", av.ID)
+	require.NotNil(t, av.ExternalReferenceID)
+	assert.Equal(t, "ext-ref-123", *av.ExternalReferenceID)
+
+	assertRequestJSON(t, *capturedBodyPtr, "address_verifications/update_request.json")
+}
+
+func TestAddressVerificationsUpdateExternalReferenceIDFromLoaded(t *testing.T) {
+	server, capturedBodyPtr := captureRequestBody(t, map[string]testRoute{
+		"GET /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e":   {status: http.StatusOK, fixture: "address_verifications/show.json"},
+		"PATCH /v3/address_verifications/c8e004b0-87ec-4987-b4fb-ee89db099f0e": {status: http.StatusOK, fixture: "address_verifications/update.json"},
+	})
+
+	av, err := server.client.AddressVerifications().Find(context.Background(), "c8e004b0-87ec-4987-b4fb-ee89db099f0e")
+	require.NoError(t, err)
+
+	extRef := "ext-ref-123"
+	av.ExternalReferenceID = &extRef
+
+	av, err = server.client.AddressVerifications().Update(context.Background(), av)
+	require.NoError(t, err)
+
+	assert.Equal(t, "c8e004b0-87ec-4987-b4fb-ee89db099f0e", av.ID)
+	require.NotNil(t, av.ExternalReferenceID)
+	assert.Equal(t, "ext-ref-123", *av.ExternalReferenceID)
+
+	assertRequestJSON(t, *capturedBodyPtr, "address_verifications/update_request.json")
+}
+
 func TestAddressVerificationsFindRejected(t *testing.T) {
 	_, client := newTestServer(t, map[string]testRoute{
 		"GET /v3/address_verifications/429e6d4e-2ee9-4953-aa98-0b3ac07f0f96": {status: http.StatusOK, fixture: "address_verifications/show_rejected.json"},

client.go

@@ -171,11 +171,11 @@ func (c *Client) Proofs() *Repository[resource.Proof] { return NewRepository[res
 func (c *Client) ProofTypes() *Repository[resource.ProofType] {
 	return NewRepository[resource.ProofType](c)
 }
-func (c *Client) Requirements() *Repository[resource.Requirement] {
-	return NewRepository[resource.Requirement](c)
+func (c *Client) AddressRequirements() *Repository[resource.AddressRequirement] {
+	return NewRepository[resource.AddressRequirement](c)
 }
-func (c *Client) RequirementValidations() *Repository[resource.RequirementValidation] {
-	return NewRepository[resource.RequirementValidation](c)
+func (c *Client) AddressRequirementValidations() *Repository[resource.AddressRequirementValidation] {
+	return NewRepository[resource.AddressRequirementValidation](c)
 }
 func (c *Client) Exports() *Repository[resource.Export] { return NewRepository[resource.Export](c) }
 func (c *Client) CapacityPools() *Repository[resource.CapacityPool] {
@@ -199,6 +199,21 @@ func (c *Client) PermanentSupportingDocuments() *Repository[resource.PermanentSu
 func (c *Client) NanpaPrefixes() *Repository[resource.NanpaPrefix] {
 	return NewRepository[resource.NanpaPrefix](c)
 }
+func (c *Client) EmergencyCallingServices() *Repository[resource.EmergencyCallingService] {
+	return NewRepository[resource.EmergencyCallingService](c)
+}
+func (c *Client) EmergencyVerifications() *Repository[resource.EmergencyVerification] {
+	return NewRepository[resource.EmergencyVerification](c)
+}
+func (c *Client) EmergencyRequirementValidations() *Repository[resource.EmergencyRequirementValidation] {
+	return NewRepository[resource.EmergencyRequirementValidation](c)
+}
+func (c *Client) EmergencyRequirements() *Repository[resource.EmergencyRequirement] {
+	return NewRepository[resource.EmergencyRequirement](c)
+}
+func (c *Client) DIDHistory() *Repository[resource.DIDHistory] {
+	return NewRepository[resource.DIDHistory](c)
+}
 func (c *Client) VoiceOutTrunkRegenerateCredentials() *Repository[resource.VoiceOutTrunkRegenerateCredential] {
 	return NewRepository[resource.VoiceOutTrunkRegenerateCredential](c)
 }

client_test.go

@@ -44,7 +44,7 @@ func TestClientSendsCorrectHeaders(t *testing.T) {
 	assert.Equal(t, "application/vnd.api+json", receivedAccept)
 	assert.Equal(t, "test-api-key", receivedAPIKey)
 	assert.Equal(t, apiVersion, receivedAPIVersion)
-	assert.Equal(t, "didww-go-sdk/1.0.0", receivedUserAgent)
+	assert.Equal(t, "didww-go-sdk/3.0.0-dev", receivedUserAgent)
 }
 
 func TestClientHandlesHTTPErrors(t *testing.T) {

did_groups_test.go

@@ -60,7 +60,7 @@ func TestDIDGroupsFindWithIncludedRequirement(t *testing.T) {
 		"GET /v3/did_groups/2187c36d-28fb-436f-8861-5a0f5b5a3ee1": {status: http.StatusOK, fixture: "did_groups/show_with_requirement.json"},
 	})
 
-	params := NewQueryParams().Include("requirement")
+	params := NewQueryParams().Include("address_requirement")
 	group, err := client.DIDGroups().Find(context.Background(), "2187c36d-28fb-436f-8861-5a0f5b5a3ee1", params)
 	require.NoError(t, err)
 
@@ -70,15 +70,15 @@ func TestDIDGroupsFindWithIncludedRequirement(t *testing.T) {
 	assert.False(t, group.IsMetered)
 	assert.True(t, group.AllowAdditionalChannels)
 
-	// Verify included requirement
-	require.NotNil(t, group.Requirement)
-	assert.Equal(t, "8da1e0b2-047c-4baf-9c57-57143f09b9ce", group.Requirement.ID)
-	assert.Equal(t, "Any", group.Requirement.IdentityType)
-	assert.Equal(t, "WorldWide", group.Requirement.PersonalAreaLevel)
-	assert.Equal(t, "Country", group.Requirement.BusinessAreaLevel)
-	assert.Equal(t, "City", group.Requirement.AddressAreaLevel)
-	assert.Equal(t, 1, group.Requirement.PersonalProofQty)
-	assert.Equal(t, 1, group.Requirement.BusinessProofQty)
-	assert.Equal(t, 1, group.Requirement.AddressProofQty)
-	assert.False(t, group.Requirement.ServiceDescriptionRequired)
+	// Verify included address_requirement
+	require.NotNil(t, group.AddressRequirement)
+	assert.Equal(t, "8da1e0b2-047c-4baf-9c57-57143f09b9ce", group.AddressRequirement.ID)
+	assert.Equal(t, "any", group.AddressRequirement.IdentityType)
+	assert.Equal(t, "world_wide", group.AddressRequirement.PersonalAreaLevel)
+	assert.Equal(t, "country", group.AddressRequirement.BusinessAreaLevel)
+	assert.Equal(t, "city", group.AddressRequirement.AddressAreaLevel)
+	assert.Equal(t, 1, group.AddressRequirement.PersonalProofQty)
+	assert.Equal(t, 1, group.AddressRequirement.BusinessProofQty)
+	assert.Equal(t, 1, group.AddressRequirement.AddressProofQty)
+	assert.False(t, group.AddressRequirement.ServiceDescriptionRequired)
 }