DEVEXP-1303: OAS-Synchro Numbers

.github/CODEOWNERS

@@ -1,2 +1,2 @@
 # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
-*       @matsk-sinch @Dovchik @krogers0607 @asein-sinch @JPPortier
+*       @matsk-sinch @asein-sinch @JPPortier @rpredescu-sinch

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

@@ -12,7 +12,10 @@
 
 
 class ListActiveNumbersRequest(BaseModelConfigurationRequest):
-    region_code: StrictStr = Field(alias="regionCode")
+    region_code: StrictStr = Field(
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
+    )
     number_type: NumberType = Field(alias="type")
     page_size: Optional[StrictInt] = Field(default=None, alias="pageSize")
     capabilities: Optional[conlist(CapabilityType)] = Field(default=None)

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

@@ -11,7 +11,10 @@
 
 
 class ListAvailableNumbersRequest(BaseModelConfigurationRequest):
-    region_code: StrictStr = Field(alias="regionCode")
+    region_code: StrictStr = Field(
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
+    )
     number_type: NumberType = Field(alias="type")
     page_size: Optional[StrictInt] = Field(default=None, alias="size")
     capabilities: Optional[conlist(CapabilityType)] = Field(default=None)

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

@@ -5,4 +5,7 @@
 
 
 class NumberRequest(BaseModelConfigurationRequest):
-    phone_number: StrictStr = Field(alias="phoneNumber")
+    phone_number: StrictStr = Field(
+        alias="phoneNumber",
+        description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
+    )

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

@@ -11,7 +11,10 @@
 
 
 class RentAnyNumberRequest(BaseModelConfigurationRequest):
-    region_code: StrictStr = Field(alias="regionCode")
+    region_code: StrictStr = Field(
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
+    )
     number_type: NumberType = Field(alias="type")
     number_pattern: Optional[Dict[str, Any]] = Field(
         default=None, alias="numberPattern"

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

@@ -9,7 +9,10 @@
 
 
 class RentNumberRequest(BaseModelConfigurationRequest):
-    phone_number: StrictStr = Field(alias="phoneNumber")
+    phone_number: StrictStr = Field(
+        alias="phoneNumber",
+        description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
+    )
     # Accepts only dictionary input, not Pydantic models
     sms_configuration: Optional[Dict] = Field(
         default=None, alias="smsConfiguration"

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

@@ -9,7 +9,10 @@
 
 
 class UpdateNumberConfigurationRequest(BaseModelConfigurationRequest):
-    phone_number: StrictStr = Field(alias="phoneNumber")
+    phone_number: StrictStr = Field(
+        alias="phoneNumber",
+        description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
+    )
     display_name: Optional[StrictStr] = Field(
         default=None, alias="displayName"
     )

sinch/domains/numbers/models/v1/response/active_number.py

@@ -14,13 +14,19 @@
 
 class ActiveNumber(BaseModelConfigurationResponse):
     phone_number: Optional[StrictStr] = Field(
-        default=None, alias="phoneNumber"
+        default=None,
+        alias="phoneNumber",
+        description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
     )
     project_id: Optional[StrictStr] = Field(default=None, alias="projectId")
     display_name: Optional[StrictStr] = Field(
         default=None, alias="displayName"
     )
-    region_code: Optional[StrictStr] = Field(default=None, alias="regionCode")
+    region_code: Optional[StrictStr] = Field(
+        default=None,
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
+    )
     type: Optional[NumberType] = Field(default=None)
     capabilities: Optional[conlist(CapabilityType)] = Field(default=None)
     money: Optional[Money] = Field(default=None)

sinch/domains/numbers/models/v1/response/available_number.py

@@ -9,9 +9,15 @@
 
 class AvailableNumber(BaseModelConfigurationResponse):
     phone_number: Optional[StrictStr] = Field(
-        default=None, alias="phoneNumber"
+        default=None,
+        alias="phoneNumber",
+        description="Phone number in E.164 format with leading '+'. Example: '+12025550134'.",
+    )
+    region_code: Optional[StrictStr] = Field(
+        default=None,
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
     )
-    region_code: Optional[StrictStr] = Field(default=None, alias="regionCode")
     type: Optional[NumberType] = Field(default=None)
     capability: Optional[conlist(CapabilityType)] = Field(default=None)
     setup_price: Optional[Money] = Field(default=None, alias="setupPrice")

sinch/domains/numbers/models/v1/response/available_region.py

@@ -7,6 +7,10 @@
 
 
 class AvailableRegion(BaseModelConfigurationResponse):
-    region_code: Optional[StrictStr] = Field(default=None, alias="regionCode")
+    region_code: Optional[StrictStr] = Field(
+        default=None,
+        alias="regionCode",
+        description="ISO 3166-1 alpha-2 country code. Example: US, GB or SE.",
+    )
     region_name: Optional[StrictStr] = Field(default=None, alias="regionName")
     types: Optional[conlist(NumberType)] = Field(default=None)

sinch/domains/numbers/models/v1/shared/__init__.py

@@ -21,6 +21,9 @@
 from sinch.domains.numbers.models.v1.shared.sms_configuration import (
     SmsConfiguration,
 )
+from sinch.domains.numbers.models.v1.shared.sms_configuration_base import (
+    SmsConfigurationBase,
+)
 from sinch.domains.numbers.models.v1.shared.voice_configuration_est import (
     VoiceConfigurationEST,
 )
@@ -41,6 +44,7 @@
     "ScheduledVoiceProvisioningFAX",
     "ScheduledVoiceProvisioningRTC",
     "SmsConfiguration",
+    "SmsConfigurationBase",
     "VoiceConfigurationEST",
     "VoiceConfigurationRTC",
     "VoiceConfigurationFAX",

sinch/domains/numbers/models/v1/shared/sms_configuration.py

@@ -1,14 +1,14 @@
 from typing import Optional
-from pydantic import StrictStr, Field
-from sinch.domains.numbers.models.v1.internal.base import (
-    BaseModelConfigurationResponse,
+from pydantic import Field
+from sinch.domains.numbers.models.v1.shared.scheduled_sms_provisioning import (
+    ScheduledSmsProvisioning,
+)
+from sinch.domains.numbers.models.v1.shared.sms_configuration_base import (
+    SmsConfigurationBase,
 )
-from sinch.domains.numbers.models.v1.shared import ScheduledSmsProvisioning
 
 
-class SmsConfiguration(BaseModelConfigurationResponse):
-    service_plan_id: StrictStr = Field(alias="servicePlanId")
-    campaign_id: Optional[StrictStr] = Field(default=None, alias="campaignId")
+class SmsConfiguration(SmsConfigurationBase):
     scheduled_provisioning: Optional[ScheduledSmsProvisioning] = Field(
         default=None, alias="scheduledProvisioning"
     )

sinch/domains/numbers/models/v1/shared/sms_configuration_base.py

@@ -0,0 +1,10 @@
+from typing import Optional
+from pydantic import StrictStr, Field
+from sinch.domains.numbers.models.v1.internal.base import (
+    BaseModelConfigurationResponse,
+)
+
+
+class SmsConfigurationBase(BaseModelConfigurationResponse):
+    service_plan_id: StrictStr = Field(alias="servicePlanId")
+    campaign_id: Optional[StrictStr] = Field(default=None, alias="campaignId")

sinch/domains/numbers/virtual_numbers.py

@@ -69,7 +69,7 @@ def list(
         """
         Search for all active virtual numbers associated with a certain project.
 
-        :param region_code: ISO 3166-1 alpha-2 country code of the phone number.
+        :param region_code: ISO 3166-1 alpha-2 country code. Example: US, GB or SE.
         :type region_code: str
 
         :param number_type: Type of number (e.g., "MOBILE", "LOCAL", "TOLL_FREE").
@@ -159,23 +159,19 @@ def update(
         Make updates to the configuration of your virtual number.
         Update the display name, change the currency type, or reconfigure for either SMS and/or Voice.
 
-        :param phone_number: The phone number in E.164 format with leading +.
+        :param phone_number: Phone number in E.164 format with leading '+'. Example: '+12025550134'.
         :type phone_number: str
 
         :param display_name: The display name for the virtual number.
         :type display_name: Optional[str]
 
-        :param sms_configuration: A dictionary defining the SMS configuration. Including fields such as::
-
-                                  - ``service_plan_id`` (str): The service plan ID.
-                                  - ``campaign_id`` (Optional[str]): The campaign ID.
+        :param sms_configuration: A dictionary defining the SMS configuration, including fields such as: ``service_plan_id`` (str), ``campaign_id`` (optional, required for US 10DLC).
         :type sms_configuration: Optional[SmsConfigurationDict]
 
         :param voice_configuration: A dictionary defining the Voice configuration. Supported types include::
-
-                                    - ``VoiceConfigurationRTCDict``: type 'RTC' with an ``app_id`` field.
-                                    - ``VoiceConfigurationESTDict``: type 'EST' with a ``trunk_id`` field.
-                                    - ``VoiceConfigurationFAXDict``: type 'FAX' with a ``service_id`` field.
+            - ``VoiceConfigurationRTCDict``: type ``'RTC'`` with an ``app_id`` field.
+            - ``VoiceConfigurationESTDict``: type ``'EST'`` with a ``trunk_id`` field.
+            - ``VoiceConfigurationFAXDict``: type ``'FAX'`` with a ``service_id`` field.
         :type voice_configuration: Optional[VoiceConfigurationDict]
 
         :param callback_url: The callback URL for the virtual number.
@@ -197,9 +193,9 @@ def update(
 
     def get(self, phone_number: str, **kwargs) -> ActiveNumber:
         """
-        List of configuration settings for your virtual number.
+        Get the configuration settings for your virtual number.
 
-        :param phone_number: The phone number in E.164 format with leading +.
+        :param phone_number: Phone number in E.164 format with leading '+'. Example: '+12025550134'.
         :type phone_number: str
 
         :param kwargs: Additional parameters for the request.
@@ -216,7 +212,7 @@ def release(self, phone_number: str, **kwargs) -> ActiveNumber:
         """
         Release virtual numbers you no longer need from your project.
 
-        :param phone_number: The phone number in E.164 format with leading +.
+        :param phone_number: Phone number in E.164 format with leading '+'. Example: '+12025550134'.
         :type phone_number: str
 
         :param kwargs: Additional parameters for the request.
@@ -235,7 +231,7 @@ def check_availability(
         """
         Enter a specific phone number to check availability.
 
-        :param phone_number: The phone number in E.164 format with leading ``+``.
+        :param phone_number: Phone number in E.164 format with leading '+'. Example: '+12025550134'.
         :type phone_number: str
 
         :param kwargs: Additional parameters for the request.
@@ -291,16 +287,11 @@ def rent(
         """
         Rent a virtual number to use with SMS, Voice, or both products.
 
-        :param phone_number: The phone number in E.164 format with leading ``+``.
+        :param phone_number: Phone number in E.164 format with leading '+'. Example: '+12025550134'.
         :type phone_number: str
-        :param sms_configuration: A dictionary defining the SMS configuration.
-            Include the following fields::
-
-            - ``service_plan_id`` (str): The service plan ID.
-            - ``campaign_id`` (Optional[str]): The campaign ID.
+        :param sms_configuration: A dictionary defining the SMS configuration, including fields such as: ``service_plan_id`` (str), ``campaign_id`` (optional, required for US 10DLC).
         :type sms_configuration: Optional[SmsConfigurationDict]
         :param voice_configuration: A dictionary defining the Voice configuration. Supported types include::
-
             - ``VoiceConfigurationRTCDict``: type ``'RTC'`` with an ``app_id`` field.
             - ``VoiceConfigurationESTDict``: type ``'EST'`` with a ``trunk_id`` field.
             - ``VoiceConfigurationFAXDict``: type ``'FAX'`` with a ``service_id`` field.
@@ -377,43 +368,35 @@ def rent_any(
         Search for and activate an available Sinch virtual number all in one API call.
         Currently, the ``rent_any`` operation works only for US 10DLC numbers.
 
-        :param region_code: ISO 3166-1 alpha-2 country code of the phone number.
+        :param region_code: ISO 3166-1 alpha-2 country code. Example: US, GB or SE.
         :type region_code: str
 
         :param number_type: Type of number (e.g., ``"MOBILE"``, ``"LOCAL"``, ``"TOLL_FREE"``). Defaults to ``"MOBILE"``.
         :type number_type: NumberType
 
-        :param number_pattern: A dictionary defining the specific sequence of digits to search for.
-        Include fields such as::
-                                    - ``pattern`` (str): The specific sequence of digits.
-                                    - ``search_pattern`` (str):
-                                            The pattern to apply (e.g., ``"START"``, ``"CONTAINS"``, ``"END"``).
+        :param number_pattern: Optional dict with ``pattern`` (str) and ``search_pattern`` (e.g., ``"START"``, ``"CONTAINS"``, ``"END"``).
         :type number_pattern: Optional[NumberPatternDict]
 
         :param capabilities: Capabilities required for the number (e.g., ``["SMS", "VOICE"]``).
-        :type capabilities: Optional[CapabilityType]
-
-        :param sms_configuration: A dictionary defining the SMS configuration. Includes fields such as::
+        :type capabilities: Optional[List[CapabilityType]]
 
-                                  - ``service_plan_id`` (str): The service plan ID.
-                                  - ``campaign_id`` (Optional[str]): The campaign ID.
+        :param sms_configuration: A dictionary defining the SMS configuration, including fields such as: ``service_plan_id`` (str), ``campaign_id`` (optional, required for US 10DLC).
         :type sms_configuration: Optional[SmsConfigurationDict]
 
         :param voice_configuration: A dictionary defining the Voice configuration. Supported types include::
-
-                                   - ``VoiceConfigurationRTCDict``: type ``'RTC'`` with an ``app_id`` field.
-                                   - ``VoiceConfigurationESTDict``: type ``'EST'`` with a ``trunk_id`` field.
-                                   - ``VoiceConfigurationFAXDict``: type ``'FAX'`` with a ``service_id`` field.
+            - ``VoiceConfigurationRTCDict``: type ``'RTC'`` with an ``app_id`` field.
+            - ``VoiceConfigurationESTDict``: type ``'EST'`` with a ``trunk_id`` field.
+            - ``VoiceConfigurationFAXDict``: type ``'FAX'`` with a ``service_id`` field.
         :type voice_configuration: Optional[VoiceConfigurationDict]
 
         :param callback_url: The callback URL to receive notifications.
-        :type callback_url: str
+        :type callback_url: Optional[str]
 
         :param kwargs: Additional parameters for the request.
         :type kwargs: dict
 
         :returns: A response object with the activated number and its details.
-        :rtype: RentAnyNumberRequest
+        :rtype: ActiveNumber
 
         For detailed documentation, visit: https://developers.sinch.com
         """
@@ -441,7 +424,7 @@ def search_for_available_numbers(
         """
         Search for available virtual numbers for you to rent using a variety of parameters to filter results.
 
-        :param region_code: ISO 3166-1 alpha-2 country code of the phone number.
+        :param region_code: ISO 3166-1 alpha-2 country code. Example: US, GB or SE.
         :type region_code: str
 
         :param number_type: Type of number (e.g., ``"MOBILE"``, ``"LOCAL"``, ``"TOLL_FREE"``).