Phonenumbers/reservations implementation

sdk/communication/azure-communication-phonenumbers/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Release History
 
+
+## 1.3.0b1 (Unreleased)
+
+### Features Added
+- Adds support for the Browse Available Phone Numbers and Reservations APIs.
+  - This adds an alternate way to search and purchase phone numbers that allows customers to select which phone numbers they want to reserve and purchase.
+- Adds support for automated purchases of phone numbers from countries requiring a Do Not Resell agreement.
+  - For more information, refer to: https://learn.microsoft.com/azure/communication-services/concepts/numbers/sub-eligibility-number-capability
+- API version `2025-04-01` is the default.
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
+
 ## 1.2.0 (2025-02-11)
 
 ### Features Added

sdk/communication/azure-communication-phonenumbers/README.md

@@ -85,6 +85,14 @@ Phone numbers can be searched through the search creation API by providing an ar
 
 Phone numbers can also be released using the release API.
 
+#### Browsing and reserving phone numbers
+
+The Browse and Reservations APIs provide an alternate way to acquire phone numbers via a shopping-cart-like experience. This is achieved by splitting the search operation, which finds and reserves numbers using a single LRO, into two separate synchronous steps, Browse and Reservation. 
+
+The browse operation retrieves a random sample of phone numbers that are available for purchase for a given country, with optional filtering criteria to narrow down results. The returned phone numbers are not reserved for any customer.
+
+Reservations represent a collection of phone numbers that are locked by a specific customer and are awaiting purchase. They have an expiration time of 15 minutes after the last modification or 2 hours from creation time. A reservation can include numbers from different countries, in contrast with the Search operation. Customers can Create, Retrieve, Modify (by adding and removing numbers), Delete, and Purchase reservations. Purchasing a reservation is an LRO.
+
 ### SIP routing client
 
 Direct routing feature allows connecting customer-provided telephony infrastructure to Azure Communication Resources. In order to setup routing configuration properly, customer needs to supply the SIP trunk configuration and SIP routing rules for calls. SIP routing client provides the necessary interface for setting this configuration.
@@ -116,6 +124,33 @@ print(result.country_code)
 print(result.phone_number)
 ```
 
+#### Broswing and Reserving Available Phone Numbers
+
+Use the Browse and Reservations API to reserve a phone number
+
+```python
+import uuid
+
+browse_result = await phone_numbers_client.browse_available_phone_numbers(
+    country_code="US",
+    phone_number_type="tollFree"
+)
+number_to_reserve = browse_result.phone_numbers[0]
+
+# The reservation ID needs to be a valid UUID.
+reservation_id = str(uuid.uuid4())
+reservation = await phone_numbers_client.create_or_update_reservation(
+    reservation_id=reservation_id,
+    numbers_to_add=[number_to_reserve]
+)
+
+numbers_with_error = [n for n in reservation.phone_numbers.values() if n.status == "error"]
+if any(numbers_with_error):
+    print("Errors occurred during reservation")
+else:
+    print("Reservation operation completed without errors.")
+```
+
 ### Long Running Operations
 
 The Phone Number Client supports a variety of long running operations that allow indefinite polling time to the functions listed down below.
@@ -182,6 +217,32 @@ poller = phone_numbers_client.begin_update_phone_number_capabilities(
 )
 ```
 
+#### Purchase Reservation
+
+Given an existing and active reservation, purchase the phone numbers in that reservation.
+
+```python
+reservation_id = "<reservation id>"
+poller = phone_numbers_client.begin_purchase_reservation(
+    reservation_id,
+    polling = True
+)
+```
+
+After the LRO finishes processing, the status of each individual number can be validated by retrieving the reservation.
+
+```python
+reservation_id = "<reservation id>"
+reservation = phone_numbers_client.get_reservation(reservation_id)
+
+numbers_with_error = [
+    n for n in reservation.phone_numbers.values() if n.status == "error"]
+if any(numbers_with_error):
+    print("Errors occurred during purchase")
+else:
+    print("Reservation purchase completed without errors.")
+```
+
 ### SipRoutingClient
 
 #### Retrieve SIP trunks and routes

sdk/communication/azure-communication-phonenumbers/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/communication/azure-communication-phonenumbers",
-  "Tag": "python/communication/azure-communication-phonenumbers_a45b7bec94"
+  "Tag": "python/communication/azure-communication-phonenumbers_db3a0ba22d"
 }

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/__init__.py

@@ -23,6 +23,16 @@
     OperatorInformationOptions,
     OperatorInformation,
     OperatorInformationResult,
+    PhoneNumbersBrowseResult,
+    AvailablePhoneNumber,
+    PhoneNumbersReservation,
+    CommunicationError
+)
+
+from ._generated.models._enums import (
+    ReservationStatus,
+    PhoneNumberAvailabilityStatus,
+    PhoneNumberSearchResultError
 )
 
 __all__ = [
@@ -42,5 +52,12 @@
     'OperatorInformationOptions',
     'OperatorInformation',
     'OperatorInformationResult',
-    'PhoneNumbersClient'
+    'PhoneNumbersClient',
+    'PhoneNumbersReservation',
+    'PhoneNumbersBrowseResult',
+    'AvailablePhoneNumber',
+    'CommunicationError',
+    'ReservationStatus',
+    'PhoneNumberAvailabilityStatus',
+    'PhoneNumberSearchResultError',
 ]

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/_api_versions.py

@@ -13,6 +13,7 @@ class ApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     V2023_05_01_PREVIEW = "2023-05-01-preview"
     V2024_03_01_PREVIEW = "2024-03-01-preview"
     V2025_02_11 = "2025-02-11"
+    V2025_04_01 = "2025-04-01"
 
 
-DEFAULT_VERSION = ApiVersion.V2025_02_11
+DEFAULT_VERSION = ApiVersion.V2025_04_01

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/_generated/_client.py

@@ -16,7 +16,7 @@
 
 from . import models as _models
 from ._configuration import PhoneNumbersClientConfiguration
-from ._serialization import Deserializer, Serializer
+from ._utils.serialization import Deserializer, Serializer
 from .operations import PhoneNumbersOperations
 
 
@@ -29,7 +29,7 @@ class PhoneNumbersClient:
     :param endpoint: The communication resource, for example
      https://resourcename.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2025-02-11". Note that overriding this
+    :keyword api_version: Api Version. Default value is "2025-04-01". Note that overriding this
      default value may result in unsupported behavior.
     :paramtype api_version: str
     :keyword int polling_interval: Default waiting time between two polls for LRO operations if no
@@ -41,6 +41,7 @@ def __init__(  # pylint: disable=missing-client-constructor-parameter-credential
     ) -> None:
         _endpoint = "{endpoint}"
         self._config = PhoneNumbersClientConfiguration(endpoint=endpoint, **kwargs)
+
         _policies = kwargs.pop("policies", None)
         if _policies is None:
             _policies = [

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/_generated/_configuration.py

@@ -22,13 +22,13 @@ class PhoneNumbersClientConfiguration:  # pylint: disable=too-many-instance-attr
     :param endpoint: The communication resource, for example
      https://resourcename.communication.azure.com. Required.
     :type endpoint: str
-    :keyword api_version: Api Version. Default value is "2025-02-11". Note that overriding this
+    :keyword api_version: Api Version. Default value is "2025-04-01". Note that overriding this
      default value may result in unsupported behavior.
     :paramtype api_version: str
     """
 
     def __init__(self, endpoint: str, **kwargs: Any) -> None:
-        api_version: str = kwargs.pop("api_version", "2025-02-11")
+        api_version: str = kwargs.pop("api_version", "2025-04-01")
 
         if endpoint is None:
             raise ValueError("Parameter 'endpoint' must not be None.")

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/_generated/_patch.py

@@ -3,6 +3,7 @@
 # Licensed under the MIT License.
 # ------------------------------------
 
+
 """Customize generated code here.
 
 Follow our quickstart for examples: https://aka.ms/azsdk/python/dpcodegen/python/customize

sdk/communication/azure-communication-phonenumbers/azure/communication/phonenumbers/_generated/_utils/__init__.py

@@ -0,0 +1,6 @@
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------