sendly 3.33.0__tar.gz → 3.35.0__tar.gz

{sendly-3.33.0 → sendly-3.35.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # sendly (Python)
 
+## 3.33.0
+
+### Patch Changes
+
+- **Fixed a runtime `TypeError` on every write method across `contacts`, `campaigns`, `templates`, and `webhooks`.** Those resources called the internal HTTP client with a `json=` keyword, but `HttpClient.request()` / `AsyncHttpClient.request()` only accept `body=`. Every affected call site now passes `body=`, so creates/updates (e.g. `contacts.import_contacts`, `contacts.lookup`, `contacts.bulk_mark_valid`, `campaigns.create`, `templates.create`, `webhooks.create`) send their payloads correctly instead of raising.
+- Reconciled the version to a single source of truth at `3.33.0`: `pyproject.toml`, `sendly.__version__`, and the `User-Agent` header (`SDK_VERSION` in `utils/http.py`, previously `1.0.5`) now all report `sendly-python/3.33.0`.
+
 ## 3.32.0
 
 ### Minor Changes

{sendly-3.33.0 → sendly-3.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendly
-Version: 3.33.0
+Version: 3.35.0
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -406,6 +406,57 @@ print(f"New key: {result['key']}")  # Only shown once!
 client.account.revoke_api_key('key_xxx')
 ```
 
+## Phone Numbers
+
+Search for and buy phone numbers. Prices on available numbers are already
+customer-priced. Requires an API key with the `numbers:read` / `numbers:write`
+scopes.
+
+```python
+# List the countries where numbers are available
+countries = client.numbers.list_countries()
+for country in countries.countries:
+    print(f'{country.code} {country.name}: {country.number_types}')
+
+# Search for available numbers (already customer-priced)
+available = client.numbers.list_available(country='GB', type='mobile')
+for num in available.numbers:
+    print(f'{num.phone_number} — {num.monthly_cost} {num.currency}')
+
+# Optionally filter by a digit pattern
+available = client.numbers.list_available(country='GB', type='mobile', contains='777')
+
+# List the numbers you already own
+owned = client.numbers.list()
+for num in owned.numbers:
+    print(f'{num.phone_number} ({num.status})')
+
+# Buy a number
+chosen = available.numbers[0]
+result = client.numbers.buy(
+    phone_number=chosen.phone_number,
+    country_code='GB',
+    phone_number_type='mobile',
+    monthly_cost=chosen.monthly_cost,
+)
+
+if result.status == 'provisioning':
+    print(f'Provisioning {result.number.phone_number}')
+elif result.status in ('documents_required', 'payment_required'):
+    # Hand the user the hosted Sendly page + code, wait for them to finish,
+    # then call buy() again with the same arguments plus action_code set to
+    # the completed action's code.
+    print(f'Open {result.action.url} and enter code {result.action.code}')
+    # ...later, after the user completes the page...
+    result = client.numbers.buy(
+        phone_number=chosen.phone_number,
+        country_code='GB',
+        phone_number_type='mobile',
+        monthly_cost=chosen.monthly_cost,
+        action_code=result.action.code,
+    )
+```
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -594,6 +645,24 @@ List sent messages.
 
 Get a specific message by ID.
 
+### `client.numbers`
+
+#### `list_countries() -> NumberCountriesResponse`
+
+List the countries where numbers can be searched and purchased.
+
+#### `list_available(country, type, contains=None) -> AvailableNumbersResponse`
+
+Search for available numbers, already customer-priced.
+
+#### `list() -> OwnedNumbersResponse`
+
+List the numbers the account already owns.
+
+#### `buy(phone_number, country_code, phone_number_type, monthly_cost, action_code=None) -> BuyNumberResponse`
+
+Buy a number. Returns `status` of `provisioning`, `documents_required`, or `payment_required`; when documents/payment are required, `action` carries a hosted page URL + code to hand to the user before re-calling with `action_code`.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.33.0 → sendly-3.35.0}/README.md

@@ -371,6 +371,57 @@ print(f"New key: {result['key']}")  # Only shown once!
 client.account.revoke_api_key('key_xxx')
 ```
 
+## Phone Numbers
+
+Search for and buy phone numbers. Prices on available numbers are already
+customer-priced. Requires an API key with the `numbers:read` / `numbers:write`
+scopes.
+
+```python
+# List the countries where numbers are available
+countries = client.numbers.list_countries()
+for country in countries.countries:
+    print(f'{country.code} {country.name}: {country.number_types}')
+
+# Search for available numbers (already customer-priced)
+available = client.numbers.list_available(country='GB', type='mobile')
+for num in available.numbers:
+    print(f'{num.phone_number} — {num.monthly_cost} {num.currency}')
+
+# Optionally filter by a digit pattern
+available = client.numbers.list_available(country='GB', type='mobile', contains='777')
+
+# List the numbers you already own
+owned = client.numbers.list()
+for num in owned.numbers:
+    print(f'{num.phone_number} ({num.status})')
+
+# Buy a number
+chosen = available.numbers[0]
+result = client.numbers.buy(
+    phone_number=chosen.phone_number,
+    country_code='GB',
+    phone_number_type='mobile',
+    monthly_cost=chosen.monthly_cost,
+)
+
+if result.status == 'provisioning':
+    print(f'Provisioning {result.number.phone_number}')
+elif result.status in ('documents_required', 'payment_required'):
+    # Hand the user the hosted Sendly page + code, wait for them to finish,
+    # then call buy() again with the same arguments plus action_code set to
+    # the completed action's code.
+    print(f'Open {result.action.url} and enter code {result.action.code}')
+    # ...later, after the user completes the page...
+    result = client.numbers.buy(
+        phone_number=chosen.phone_number,
+        country_code='GB',
+        phone_number_type='mobile',
+        monthly_cost=chosen.monthly_cost,
+        action_code=result.action.code,
+    )
+```
+
 ## Error Handling
 
 The SDK provides typed exception classes:
@@ -559,6 +610,24 @@ List sent messages.
 
 Get a specific message by ID.
 
+### `client.numbers`
+
+#### `list_countries() -> NumberCountriesResponse`
+
+List the countries where numbers can be searched and purchased.
+
+#### `list_available(country, type, contains=None) -> AvailableNumbersResponse`
+
+Search for available numbers, already customer-priced.
+
+#### `list() -> OwnedNumbersResponse`
+
+List the numbers the account already owns.
+
+#### `buy(phone_number, country_code, phone_number_type, monthly_cost, action_code=None) -> BuyNumberResponse`
+
+Buy a number. Returns `status` of `provisioning`, `documents_required`, or `payment_required`; when documents/payment are required, `action` carries a hosted page URL + code to hand to the user before re-calling with `action_code`.
+
 ## Enterprise
 
 The Enterprise API lets you programmatically manage workspaces, verification, credits, and API keys for multi-tenant platforms. Requires an enterprise master key (`sk_live_v1_master_*`).

{sendly-3.33.0 → sendly-3.35.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sendly"
-version = "3.33.0"
+version = "3.35.0"
 description = "Official Sendly Python SDK for SMS messaging"
 readme = "README.md"
 license = "MIT"

{sendly-3.33.0 → sendly-3.35.0}/sendly/__init__.py

@@ -29,7 +29,7 @@ Async Example:
     >>> asyncio.run(main())
 """
 
-__version__ = "3.32.0"
+__version__ = "3.33.0"
 
 # Main clients
 from .client import AsyncSendly, Sendly
@@ -52,6 +52,7 @@ from .resources.business_upgrade import (
     BusinessUpgradeResource,
 )
 from .resources.media import AsyncMediaResource, MediaResource
+from .resources.numbers import AsyncNumbersResource, NumbersResource
 
 # Types
 from .types import (
@@ -115,6 +116,16 @@ from .types import (
     MessageAnalyticsDataPoint,
     MessageListResponse,
     MessageStatus,
+    # Numbers types
+    AvailableNumber,
+    AvailableNumbersResponse,
+    BuyNumberRef,
+    BuyNumberResponse,
+    NumberAction,
+    NumberCountriesResponse,
+    NumberCountry,
+    OwnedNumber,
+    OwnedNumbersResponse,
     OptInPage,
     PricingTier,
     QuotaSettings,
@@ -251,9 +262,22 @@ __all__ = [
     "CreateLabelRequest",
     "Label",
     "LabelListResponse",
+    # Numbers types
+    "AvailableNumber",
+    "AvailableNumbersResponse",
+    "BuyNumberRef",
+    "BuyNumberResponse",
+    "NumberAction",
+    "NumberCountriesResponse",
+    "NumberCountry",
+    "OwnedNumber",
+    "OwnedNumbersResponse",
     # Media resources
     "MediaResource",
     "AsyncMediaResource",
+    # Numbers resources
+    "NumbersResource",
+    "AsyncNumbersResource",
     # Business upgrade resources
     "BusinessUpgradeResource",
     "AsyncBusinessUpgradeResource",

{sendly-3.33.0 → sendly-3.35.0}/sendly/client.py

@@ -19,6 +19,7 @@ from .resources.enterprise import AsyncEnterpriseResource, EnterpriseResource
 from .resources.labels import AsyncLabelsResource, LabelsResource
 from .resources.media import AsyncMediaResource, MediaResource
 from .resources.messages import AsyncMessagesResource, MessagesResource
+from .resources.numbers import AsyncNumbersResource, NumbersResource
 from .resources.rules import AsyncRulesResource, RulesResource
 from .resources.templates import AsyncTemplatesResource, TemplatesResource
 from .resources.verify import AsyncVerifyResource, VerifyResource
@@ -117,6 +118,7 @@ class Sendly:
         self.campaigns = CampaignsResource(self._http)
         self.contacts = ContactsResource(self._http)
         self.media = MediaResource(self._http)
+        self.numbers = NumbersResource(self._http)
         self.enterprise = EnterpriseResource(self._http)
         self.labels = LabelsResource(self._http)
         self.drafts = DraftsResource(self._http)
@@ -255,6 +257,7 @@ class AsyncSendly:
         self.campaigns = AsyncCampaignsResource(self._http)
         self.contacts = AsyncContactsResource(self._http)
         self.media = AsyncMediaResource(self._http)
+        self.numbers = AsyncNumbersResource(self._http)
         self.enterprise = AsyncEnterpriseResource(self._http)
         self.labels = AsyncLabelsResource(self._http)
         self.drafts = AsyncDraftsResource(self._http)

{sendly-3.33.0 → sendly-3.35.0}/sendly/resources/__init__.py

@@ -8,6 +8,7 @@ from .enterprise import AsyncEnterpriseResource, EnterpriseResource
 from .labels import AsyncLabelsResource, LabelsResource
 from .media import AsyncMediaResource, MediaResource
 from .messages import AsyncMessagesResource, MessagesResource
+from .numbers import AsyncNumbersResource, NumbersResource
 from .rules import AsyncRulesResource, RulesResource
 from .templates import AsyncTemplatesResource, TemplatesResource
 from .verify import AsyncVerifyResource, VerifyResource
@@ -29,6 +30,8 @@ __all__ = [
     "AsyncMediaResource",
     "MessagesResource",
     "AsyncMessagesResource",
+    "NumbersResource",
+    "AsyncNumbersResource",
     "VerifyResource",
     "AsyncVerifyResource",
     "TemplatesResource",

{sendly-3.33.0 → sendly-3.35.0}/sendly/resources/campaigns.py

@@ -54,7 +54,7 @@ class CampaignsResource:
         if template_id:
             body["templateId"] = template_id
 
-        data = self._http.request("POST", "/campaigns", json=body)
+        data = self._http.request("POST", "/campaigns", body=body)
         return self._transform_campaign(data)
 
     def list(
@@ -114,7 +114,7 @@ class CampaignsResource:
         if contact_list_ids is not None:
             body["contactListIds"] = contact_list_ids
 
-        data = self._http.request("PATCH", f"/campaigns/{campaign_id}", json=body)
+        data = self._http.request("PATCH", f"/campaigns/{campaign_id}", body=body)
         return self._transform_campaign(data)
 
     def delete(self, campaign_id: str) -> None:
@@ -159,7 +159,7 @@ class CampaignsResource:
         if timezone:
             body["timezone"] = timezone
 
-        data = self._http.request("POST", f"/campaigns/{campaign_id}/schedule", json=body)
+        data = self._http.request("POST", f"/campaigns/{campaign_id}/schedule", body=body)
         return self._transform_campaign(data)
 
     def cancel(self, campaign_id: str) -> Campaign:
@@ -217,7 +217,7 @@ class AsyncCampaignsResource:
         if template_id:
             body["templateId"] = template_id
 
-        data = await self._http.request("POST", "/campaigns", json=body)
+        data = await self._http.request("POST", "/campaigns", body=body)
         return self._transform_campaign(data)
 
     async def list(
@@ -268,7 +268,7 @@ class AsyncCampaignsResource:
         if contact_list_ids is not None:
             body["contactListIds"] = contact_list_ids
 
-        data = await self._http.request("PATCH", f"/campaigns/{campaign_id}", json=body)
+        data = await self._http.request("PATCH", f"/campaigns/{campaign_id}", body=body)
         return self._transform_campaign(data)
 
     async def delete(self, campaign_id: str) -> None:
@@ -304,7 +304,7 @@ class AsyncCampaignsResource:
         if timezone:
             body["timezone"] = timezone
 
-        data = await self._http.request("POST", f"/campaigns/{campaign_id}/schedule", json=body)
+        data = await self._http.request("POST", f"/campaigns/{campaign_id}/schedule", body=body)
         return self._transform_campaign(data)
 
     async def cancel(self, campaign_id: str) -> Campaign:

{sendly-3.33.0 → sendly-3.35.0}/sendly/resources/contacts.py

@@ -51,7 +51,7 @@ class ContactListsResource:
         if description:
             body["description"] = description
 
-        data = self._http.request("POST", "/contact-lists", json=body)
+        data = self._http.request("POST", "/contact-lists", body=body)
         return self._transform_list(data)
 
     def update(
@@ -68,7 +68,7 @@ class ContactListsResource:
         if description is not None:
             body["description"] = description
 
-        data = self._http.request("PATCH", f"/contact-lists/{list_id}", json=body)
+        data = self._http.request("PATCH", f"/contact-lists/{list_id}", body=body)
         return self._transform_list(data)
 
     def delete(self, list_id: str) -> None:
@@ -84,7 +84,7 @@ class ContactListsResource:
         data = self._http.request(
             "POST",
             f"/contact-lists/{list_id}/contacts",
-            json={"contact_ids": contact_ids},
+            body={"contact_ids": contact_ids},
         )
         return {"added_count": data["added_count"]}
 
@@ -194,7 +194,7 @@ class ContactsResource:
         if metadata:
             body["metadata"] = metadata
 
-        data = self._http.request("POST", "/contacts", json=body)
+        data = self._http.request("POST", "/contacts", body=body)
         return self._transform_contact(data)
 
     def update(
@@ -214,7 +214,7 @@ class ContactsResource:
         if metadata is not None:
             body["metadata"] = metadata
 
-        data = self._http.request("PATCH", f"/contacts/{contact_id}", json=body)
+        data = self._http.request("PATCH", f"/contacts/{contact_id}", body=body)
         return self._transform_contact(data)
 
     def delete(self, contact_id: str) -> None:
@@ -252,7 +252,7 @@ class ContactsResource:
         if ids and list_id:
             raise ValueError("bulk_mark_valid accepts 'ids' OR 'list_id', not both")
         body: Dict[str, Any] = {"ids": ids} if ids else {"listId": list_id}
-        data = self._http.request("POST", "/contacts/bulk-mark-valid", json=body)
+        data = self._http.request("POST", "/contacts/bulk-mark-valid", body=body)
         return BulkMarkValidResponse(cleared=data.get("cleared", 0))
 
     def check_numbers(
@@ -279,7 +279,7 @@ class ContactsResource:
         return self._http.request(
             "POST",
             "/contacts/lookup",
-            json={"listId": list_id, "force": force},
+            body={"listId": list_id, "force": force},
         )
 
     def import_contacts(
@@ -304,7 +304,7 @@ class ContactsResource:
         if opted_in_at:
             body["optedInAt"] = opted_in_at
 
-        data = self._http.request("POST", "/contacts/import", json=body)
+        data = self._http.request("POST", "/contacts/import", body=body)
         return ImportContactsResponse(
             imported=data["imported"],
             skipped_duplicates=data["skippedDuplicates"],
@@ -379,7 +379,7 @@ class AsyncContactListsResource:
         if description:
             body["description"] = description
 
-        data = await self._http.request("POST", "/contact-lists", json=body)
+        data = await self._http.request("POST", "/contact-lists", body=body)
         return self._transform_list(data)
 
     async def update(
@@ -396,7 +396,7 @@ class AsyncContactListsResource:
         if description is not None:
             body["description"] = description
 
-        data = await self._http.request("PATCH", f"/contact-lists/{list_id}", json=body)
+        data = await self._http.request("PATCH", f"/contact-lists/{list_id}", body=body)
         return self._transform_list(data)
 
     async def delete(self, list_id: str) -> None:
@@ -408,7 +408,7 @@ class AsyncContactListsResource:
         data = await self._http.request(
             "POST",
             f"/contact-lists/{list_id}/contacts",
-            json={"contact_ids": contact_ids},
+            body={"contact_ids": contact_ids},
         )
         return {"added_count": data["added_count"]}
 
@@ -495,7 +495,7 @@ class AsyncContactsResource:
         if metadata:
             body["metadata"] = metadata
 
-        data = await self._http.request("POST", "/contacts", json=body)
+        data = await self._http.request("POST", "/contacts", body=body)
         return self._transform_contact(data)
 
     async def update(
@@ -515,7 +515,7 @@ class AsyncContactsResource:
         if metadata is not None:
             body["metadata"] = metadata
 
-        data = await self._http.request("PATCH", f"/contacts/{contact_id}", json=body)
+        data = await self._http.request("PATCH", f"/contacts/{contact_id}", body=body)
         return self._transform_contact(data)
 
     async def delete(self, contact_id: str) -> None:
@@ -544,7 +544,7 @@ class AsyncContactsResource:
             raise ValueError("bulk_mark_valid accepts 'ids' OR 'list_id', not both")
         body: Dict[str, Any] = {"ids": ids} if ids else {"listId": list_id}
         data = await self._http.request(
-            "POST", "/contacts/bulk-mark-valid", json=body
+            "POST", "/contacts/bulk-mark-valid", body=body
         )
         return BulkMarkValidResponse(cleared=data.get("cleared", 0))
 
@@ -562,7 +562,7 @@ class AsyncContactsResource:
         return await self._http.request(
             "POST",
             "/contacts/lookup",
-            json={"listId": list_id, "force": force},
+            body={"listId": list_id, "force": force},
         )
 
     async def import_contacts(
@@ -587,7 +587,7 @@ class AsyncContactsResource:
         if opted_in_at:
             body["optedInAt"] = opted_in_at
 
-        data = await self._http.request("POST", "/contacts/import", json=body)
+        data = await self._http.request("POST", "/contacts/import", body=body)
         return ImportContactsResponse(
             imported=data["imported"],
             skipped_duplicates=data["skippedDuplicates"],

sendly-3.35.0/sendly/resources/numbers.py

@@ -0,0 +1,196 @@
+"""
+Numbers Resource - Search, list, and buy phone numbers
+
+Exposes the public numbers API: discover the countries Sendly sells numbers
+in, search for available numbers, list the numbers you already own, and buy a
+number. Pricing on available numbers is already customer-priced.
+
+When a purchase needs documents or payment, ``buy()`` returns a response whose
+``status`` is ``documents_required`` or ``payment_required`` and whose
+``action`` carries a hosted Sendly page (``url``) plus a short ``code``. Hand
+the user the URL + code; once they complete the page, call ``buy()`` again with
+the SAME arguments PLUS ``action_code`` set to that code. Polling the action to
+completion is the CLI's job, not the SDK's.
+"""
+
+from typing import Any, Dict, Optional
+
+from pydantic import ValidationError as PydanticValidationError
+
+from ..errors import SendlyError
+from ..types import (
+    AvailableNumbersResponse,
+    BuyNumberResponse,
+    NumberCountriesResponse,
+    OwnedNumbersResponse,
+)
+from ..utils.http import AsyncHttpClient, HttpClient
+
+
+class NumbersResource:
+    """Numbers API resource (sync)
+
+    Example:
+        >>> countries = client.numbers.list_countries()
+        >>> available = client.numbers.list_available(country='GB', type='mobile')
+        >>> result = client.numbers.buy(
+        ...     phone_number=available.numbers[0].phone_number,
+        ...     country_code='GB',
+        ...     phone_number_type='mobile',
+        ...     monthly_cost=available.numbers[0].monthly_cost,
+        ... )
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def list_countries(self) -> NumberCountriesResponse:
+        """List the countries where numbers can be searched and purchased."""
+        data = self._http.request(method="GET", path="/numbers/countries")
+        try:
+            return NumberCountriesResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    def list_available(
+        self,
+        country: str,
+        type: str,
+        contains: Optional[str] = None,
+    ) -> AvailableNumbersResponse:
+        """Search for available numbers, already priced for the customer.
+
+        Args:
+            country: ISO 3166-1 alpha-2 country code (e.g. ``GB``).
+            type: Number type to search for (e.g. ``mobile``).
+            contains: Optional digit pattern the number should contain.
+        """
+        params: Dict[str, Any] = {"country": country, "type": type}
+        if contains is not None:
+            params["contains"] = contains
+
+        data = self._http.request(method="GET", path="/numbers/available", params=params)
+        try:
+            return AvailableNumbersResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    def list(self) -> OwnedNumbersResponse:
+        """List the numbers the account already owns."""
+        data = self._http.request(method="GET", path="/numbers")
+        try:
+            return OwnedNumbersResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    def buy(
+        self,
+        phone_number: str,
+        country_code: str,
+        phone_number_type: str,
+        monthly_cost: str,
+        action_code: Optional[str] = None,
+    ) -> BuyNumberResponse:
+        """Buy a number.
+
+        Returns a response whose ``status`` is ``provisioning``,
+        ``documents_required``, or ``payment_required``. When documents or
+        payment are required, the ``action`` field carries a hosted Sendly page
+        URL + a short code; hand them to the user, then call ``buy()`` again
+        with the same arguments plus ``action_code`` set to the code of the
+        completed action.
+
+        Args:
+            phone_number: Number to buy, in E.164 format.
+            country_code: ISO 3166-1 alpha-2 country code.
+            phone_number_type: Number type (e.g. ``mobile``).
+            monthly_cost: Monthly cost as returned by :meth:`list_available`.
+            action_code: Code from a completed documents/payment action.
+        """
+        body: Dict[str, Any] = {
+            "phoneNumber": phone_number,
+            "countryCode": country_code,
+            "phoneNumberType": phone_number_type,
+            "monthlyCost": monthly_cost,
+        }
+        if action_code is not None:
+            body["actionCode"] = action_code
+
+        data = self._http.request(method="POST", path="/numbers/buy", body=body)
+        try:
+            return BuyNumberResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+
+class AsyncNumbersResource:
+    """Numbers API resource (async)"""
+
+    def __init__(self, http: AsyncHttpClient):
+        self._http = http
+
+    async def list_countries(self) -> NumberCountriesResponse:
+        """List the countries where numbers can be searched and purchased."""
+        data = await self._http.request(method="GET", path="/numbers/countries")
+        try:
+            return NumberCountriesResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    async def list_available(
+        self,
+        country: str,
+        type: str,
+        contains: Optional[str] = None,
+    ) -> AvailableNumbersResponse:
+        """Search for available numbers, already priced for the customer."""
+        params: Dict[str, Any] = {"country": country, "type": type}
+        if contains is not None:
+            params["contains"] = contains
+
+        data = await self._http.request(method="GET", path="/numbers/available", params=params)
+        try:
+            return AvailableNumbersResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    async def list(self) -> OwnedNumbersResponse:
+        """List the numbers the account already owns."""
+        data = await self._http.request(method="GET", path="/numbers")
+        try:
+            return OwnedNumbersResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+    async def buy(
+        self,
+        phone_number: str,
+        country_code: str,
+        phone_number_type: str,
+        monthly_cost: str,
+        action_code: Optional[str] = None,
+    ) -> BuyNumberResponse:
+        """Buy a number. See :meth:`NumbersResource.buy`."""
+        body: Dict[str, Any] = {
+            "phoneNumber": phone_number,
+            "countryCode": country_code,
+            "phoneNumberType": phone_number_type,
+            "monthlyCost": monthly_cost,
+        }
+        if action_code is not None:
+            body["actionCode"] = action_code
+
+        data = await self._http.request(method="POST", path="/numbers/buy", body=body)
+        try:
+            return BuyNumberResponse(**data)
+        except PydanticValidationError as e:
+            raise _invalid_response(e) from e
+
+
+def _invalid_response(e: PydanticValidationError) -> SendlyError:
+    """Wrap a pydantic schema error as a SendlyError, matching the SDK's idiom."""
+    return SendlyError(
+        message=f"Invalid API response format: {e}",
+        code="invalid_response",
+        status_code=200,
+    )