feature(numbers): update number sinch events with OAS spec

Author: marcos-sinch

sinch/domains/numbers/models/v1/internal/update_event_destination_request.py

@@ -6,4 +6,4 @@
 
 
 class UpdateEventDestinationRequest(BaseModelConfigurationRequest):
-    hmac_secret: Optional[StrictStr] = Field(default=None, alias="hmacSecret")
+    hmac_secret: Optional[StrictStr] = Field(default=None, alias="hmacSecret", description="The HMAC secret to be updated for the specified project")

sinch/domains/numbers/sinch_events/v1/events/number_sinch_event.py

@@ -1,31 +1,65 @@
 from datetime import datetime
-from typing import Optional, Union, Literal
+from typing import Literal, Optional, Union
+
 from pydantic import Field, StrictStr
+
 from sinch.domains.numbers.sinch_events.v1.internal import SinchEvent
 
 
 class NumberSinchEvent(SinchEvent):
-    event_id: Optional[StrictStr] = Field(default=None, alias="eventId")
-    timestamp: Optional[datetime] = Field(default=None)
-    project_id: Optional[StrictStr] = Field(default=None, alias="projectId")
-    resource_id: Optional[StrictStr] = Field(default=None, alias="resourceId")
+    event_id: Optional[StrictStr] = Field(
+        default=None, alias="eventId", description="The ID of the event."
+    )
+    timestamp: Optional[datetime] = Field(
+        default=None,
+        description="The date and time when the callback was created and added to the callbacks queue.",
+    )
+    project_id: Optional[StrictStr] = Field(
+        default=None,
+        alias="projectId",
+        description="The ID of the project to which the event belongs.",
+    )
+    resource_id: Optional[StrictStr] = Field(
+        default=None,
+        alias="resourceId",
+        description="The unique identifier of the resource, depending on the resource type. For example, a phone number, a hosting order ID, or a brand ID.",
+    )
     resource_type: Optional[Union[Literal["ACTIVE_NUMBER"], StrictStr]] = (
         Field(default=None, alias="resourceType")
     )
     event_type: Optional[
         Union[
             Literal[
-                "PROVISIONING_TO_CAMPAIGN",
-                "DEPROVISIONING_FROM_CAMPAIGN",
                 "PROVISIONING_TO_SMS_PLATFORM",
                 "DEPROVISIONING_FROM_SMS_PLATFORM",
+                "PROVISIONING_TO_CAMPAIGN",
+                "DEPROVISIONING_FROM_CAMPAIGN",
                 "PROVISIONING_TO_VOICE_PLATFORM",
-                "DEPROVISIONING_TO_VOICE_PLATFORM",
+                "DEPROVISIONING_FROM_VOICE_PLATFORM",
+                "NUMBER_ORDER_PROCESSING",
             ],
             StrictStr,
         ]
-    ] = Field(default=None, alias="eventType")
-    status: Optional[Union[Literal["SUCCEEDED", "FAILED"], StrictStr]] = None
+    ] = Field(
+        default=None, alias="eventType", description="The type of the event."
+    )
+    status: Optional[
+        Union[
+            Literal[
+                "SUCCEEDED",
+                "FAILED",
+                "IN_REVIEW",
+                "BLOCKED",
+                "COMPLETED",
+                "REJECTED",
+                "EXPIRED",
+            ],
+            StrictStr,
+        ]
+    ] = Field(
+        default=None,
+        description="The status of the event or the state transition it represents.",
+    )
     failure_code: Optional[
         Union[
             Literal[
@@ -47,4 +81,13 @@ class NumberSinchEvent(SinchEvent):
             ],
             StrictStr,
         ]
-    ] = Field(default=None, alias="failureCode")
+    ] = Field(
+        default=None,
+        alias="failureCode",
+        description="If the status is FAILED, a failure code will be provided. For numbers provisioning to SMS platform, there won't be any extra `failureCode`, as the result is binary. For campaign provisioning-related failures, refer to the list for the possible values.",
+    )
+    internal_failure_code: Optional[StrictStr] = Field(
+        default=None,
+        alias="internalFailureCode",
+        description="If the status is FAILED, certain processes (eg. number to campaign provisioning) will have an internalFailureCode in the payload. The details of these codes can be found in our dedicated [Provisioning errors](https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors) documentation.",
+    )

tests/unit/domains/numbers/v1/sinch_events/events/test_number_sinch_event_model.py

@@ -69,6 +69,7 @@ def test_number_sinch_event_response_missing_optional_fields_expects_parsed_data
     assert response.event_type is None
     assert response.status is None
     assert response.failure_code is None
+    assert response.internal_failure_code is None
 
 
 def test_number_sinch_event_response_invalid_data_expects_validation_error(invalid_data):