telnyx 3.8.0__tar.gz → 3.10.0__tar.gz

telnyx-3.10.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "3.10.0"
+}

{telnyx-3.8.0 → telnyx-3.10.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.10.0 (2025-10-29)
+
+Full Changelog: [v3.9.0...v3.10.0](https://github.com/team-telnyx/telnyx-python/compare/v3.9.0...v3.10.0)
+
+### Features
+
+* ENGDESK-45429 - Add sip_region documentation for dial and transfer command ([59adfcd](https://github.com/team-telnyx/telnyx-python/commit/59adfcd68a21d12dc85aa969564b048fc325b384))
+* ENGDESK-46399 - Add sip_call_id filter for retreiving recordings ([16958a6](https://github.com/team-telnyx/telnyx-python/commit/16958a6ed43f725e0dd8923d85c6d2740b93769f))
+
+
+### Bug Fixes
+
+* **client:** close streams without requiring full consumption ([8e32050](https://github.com/team-telnyx/telnyx-python/commit/8e320501ca64eae389e2eb33b861cec09f284eff))
+
+## 3.9.0 (2025-10-27)
+
+Full Changelog: [v3.8.0...v3.9.0](https://github.com/team-telnyx/telnyx-python/compare/v3.8.0...v3.9.0)
+
+### Features
+
+* **webhooks:** Implement custom Telnyx webhook verification ([#2](https://github.com/team-telnyx/telnyx-python/issues/2)) ([51e8440](https://github.com/team-telnyx/telnyx-python/commit/51e8440992c3b413d6c91ee5fc33578bc21c27d6))
+
 ## 3.8.0 (2025-10-21)
 
 Full Changelog: [v3.7.0...v3.8.0](https://github.com/team-telnyx/telnyx-python/compare/v3.7.0...v3.8.0)

{telnyx-3.8.0 → telnyx-3.10.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.3
 Name: telnyx
-Version: 3.8.0
-Summary: The official Python library for the telnyx API
+Version: 3.10.0
+Summary: Telnyx API SDK for global Voice, SMS, MMS, WhatsApp, Fax, Wireless IoT, SIP Trunking, and Call Control.
 Project-URL: Homepage, https://github.com/team-telnyx/telnyx-python
 Project-URL: Repository, https://github.com/team-telnyx/telnyx-python
 Author-email: Telnyx <support@telnyx.com>
 License: MIT
+Keywords: api,communications,connectivity,fax,iot,mms,sip,sms,telephony,telnyx,trunking,voice,voip,whatsapp
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
@@ -32,6 +33,7 @@ Provides-Extra: aiohttp
 Requires-Dist: aiohttp; extra == 'aiohttp'
 Requires-Dist: httpx-aiohttp>=0.1.9; extra == 'aiohttp'
 Provides-Extra: webhooks
+Requires-Dist: pynacl>=1.5.0; extra == 'webhooks'
 Requires-Dist: standardwebhooks; extra == 'webhooks'
 Description-Content-Type: text/markdown
 

{telnyx-3.8.0 → telnyx-3.10.0}/pyproject.toml

@@ -1,12 +1,16 @@
 [project]
 name = "telnyx"
-version = "3.8.0"
-description = "The official Python library for the telnyx API"
+version = "3.10.0"
+description = "Telnyx API SDK for global Voice, SMS, MMS, WhatsApp, Fax, Wireless IoT, SIP Trunking, and Call Control."
 dynamic = ["readme"]
 license = "MIT"
 authors = [
 { name = "Telnyx", email = "support@telnyx.com" },
 ]
+keywords = [
+  "telnyx", "voice", "sms", "mms", "whatsapp", "fax", "iot", "sip", 
+  "trunking", "voip", "telephony", "api", "communications", "connectivity"
+]
 dependencies = [
     "httpx>=0.23.0, <1",
     "pydantic>=1.9.0, <3",
@@ -40,7 +44,7 @@ Repository = "https://github.com/team-telnyx/telnyx-python"
 
 [project.optional-dependencies]
 aiohttp = ["aiohttp", "httpx_aiohttp>=0.1.9"]
-webhooks = ["standardwebhooks"]
+webhooks = ["standardwebhooks", "pynacl>=1.5.0"]
 
 [tool.rye]
 managed = true

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/_streaming.py

@@ -57,9 +57,8 @@ class Stream(Generic[_T]):
         for sse in iterator:
             yield process_data(data=sse.json(), cast_to=cast_to, response=response)
 
-        # Ensure the entire stream is consumed
-        for _sse in iterator:
-            ...
+        # As we might not fully consume the response stream, we need to close it explicitly
+        response.close()
 
     def __enter__(self) -> Self:
         return self
@@ -121,9 +120,8 @@ class AsyncStream(Generic[_T]):
         async for sse in iterator:
             yield process_data(data=sse.json(), cast_to=cast_to, response=response)
 
-        # Ensure the entire stream is consumed
-        async for _sse in iterator:
-            ...
+        # As we might not fully consume the response stream, we need to close it explicitly
+        await response.aclose()
 
     async def __aenter__(self) -> Self:
         return self

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "telnyx"
-__version__ = "3.8.0"  # x-release-please-version
+__version__ = "3.10.0"  # x-release-please-version

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/resources/__init__.py

@@ -224,7 +224,7 @@ from .portouts import (
     PortoutsResourceWithStreamingResponse,
     AsyncPortoutsResourceWithStreamingResponse,
 )
-from .webhooks import WebhooksResource, AsyncWebhooksResource
+from .webhooks import TelnyxWebhook, WebhooksResource, AsyncWebhooksResource, TelnyxWebhookVerificationError
 from .wireless import (
     WirelessResource,
     AsyncWirelessResource,
@@ -1237,6 +1237,8 @@ __all__ = [
     "AsyncOAuthGrantsResourceWithStreamingResponse",
     "WebhooksResource",
     "AsyncWebhooksResource",
+    "TelnyxWebhook",
+    "TelnyxWebhookVerificationError",
     "AccessIPAddressResource",
     "AsyncAccessIPAddressResource",
     "AccessIPAddressResourceWithRawResponse",

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/resources/calls/actions.py

@@ -3120,6 +3120,7 @@ class ActionsResource(SyncAPIResource):
         sip_auth_password: str | Omit = omit,
         sip_auth_username: str | Omit = omit,
         sip_headers: Iterable[SipHeaderParam] | Omit = omit,
+        sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"] | Omit = omit,
         sip_transport_protocol: Literal["UDP", "TCP", "TLS"] | Omit = omit,
         sound_modifications: SoundModificationsParam | Omit = omit,
         target_leg_client_state: str | Omit = omit,
@@ -3241,6 +3242,8 @@ class ActionsResource(SyncAPIResource):
           sip_headers: SIP headers to be added to the SIP INVITE. Currently only User-to-User header is
               supported.
 
+          sip_region: Defines the SIP region to be used for the call.
+
           sip_transport_protocol: Defines SIP transport protocol to be used on the call.
 
           sound_modifications: Use this field to modify sound effects, for example adjust the pitch.
@@ -3305,6 +3308,7 @@ class ActionsResource(SyncAPIResource):
                     "sip_auth_password": sip_auth_password,
                     "sip_auth_username": sip_auth_username,
                     "sip_headers": sip_headers,
+                    "sip_region": sip_region,
                     "sip_transport_protocol": sip_transport_protocol,
                     "sound_modifications": sound_modifications,
                     "target_leg_client_state": target_leg_client_state,
@@ -6365,6 +6369,7 @@ class AsyncActionsResource(AsyncAPIResource):
         sip_auth_password: str | Omit = omit,
         sip_auth_username: str | Omit = omit,
         sip_headers: Iterable[SipHeaderParam] | Omit = omit,
+        sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"] | Omit = omit,
         sip_transport_protocol: Literal["UDP", "TCP", "TLS"] | Omit = omit,
         sound_modifications: SoundModificationsParam | Omit = omit,
         target_leg_client_state: str | Omit = omit,
@@ -6486,6 +6491,8 @@ class AsyncActionsResource(AsyncAPIResource):
           sip_headers: SIP headers to be added to the SIP INVITE. Currently only User-to-User header is
               supported.
 
+          sip_region: Defines the SIP region to be used for the call.
+
           sip_transport_protocol: Defines SIP transport protocol to be used on the call.
 
           sound_modifications: Use this field to modify sound effects, for example adjust the pitch.
@@ -6550,6 +6557,7 @@ class AsyncActionsResource(AsyncAPIResource):
                     "sip_auth_password": sip_auth_password,
                     "sip_auth_username": sip_auth_username,
                     "sip_headers": sip_headers,
+                    "sip_region": sip_region,
                     "sip_transport_protocol": sip_transport_protocol,
                     "sound_modifications": sound_modifications,
                     "target_leg_client_state": target_leg_client_state,

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/resources/calls/calls.py

@@ -113,6 +113,7 @@ class CallsResource(SyncAPIResource):
         sip_auth_password: str | Omit = omit,
         sip_auth_username: str | Omit = omit,
         sip_headers: Iterable[SipHeaderParam] | Omit = omit,
+        sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"] | Omit = omit,
         sip_transport_protocol: Literal["UDP", "TCP", "TLS"] | Omit = omit,
         sound_modifications: SoundModificationsParam | Omit = omit,
         stream_bidirectional_codec: StreamBidirectionalCodec | Omit = omit,
@@ -276,6 +277,8 @@ class CallsResource(SyncAPIResource):
           sip_headers: SIP headers to be added to the SIP INVITE request. Currently only User-to-User
               header is supported.
 
+          sip_region: Defines the SIP region to be used for the call.
+
           sip_transport_protocol: Defines SIP transport protocol to be used on the call.
 
           sound_modifications: Use this field to modify sound effects, for example adjust the pitch.
@@ -372,6 +375,7 @@ class CallsResource(SyncAPIResource):
                     "sip_auth_password": sip_auth_password,
                     "sip_auth_username": sip_auth_username,
                     "sip_headers": sip_headers,
+                    "sip_region": sip_region,
                     "sip_transport_protocol": sip_transport_protocol,
                     "sound_modifications": sound_modifications,
                     "stream_bidirectional_codec": stream_bidirectional_codec,
@@ -496,6 +500,7 @@ class AsyncCallsResource(AsyncAPIResource):
         sip_auth_password: str | Omit = omit,
         sip_auth_username: str | Omit = omit,
         sip_headers: Iterable[SipHeaderParam] | Omit = omit,
+        sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"] | Omit = omit,
         sip_transport_protocol: Literal["UDP", "TCP", "TLS"] | Omit = omit,
         sound_modifications: SoundModificationsParam | Omit = omit,
         stream_bidirectional_codec: StreamBidirectionalCodec | Omit = omit,
@@ -659,6 +664,8 @@ class AsyncCallsResource(AsyncAPIResource):
           sip_headers: SIP headers to be added to the SIP INVITE request. Currently only User-to-User
               header is supported.
 
+          sip_region: Defines the SIP region to be used for the call.
+
           sip_transport_protocol: Defines SIP transport protocol to be used on the call.
 
           sound_modifications: Use this field to modify sound effects, for example adjust the pitch.
@@ -755,6 +762,7 @@ class AsyncCallsResource(AsyncAPIResource):
                     "sip_auth_password": sip_auth_password,
                     "sip_auth_username": sip_auth_username,
                     "sip_headers": sip_headers,
+                    "sip_region": sip_region,
                     "sip_transport_protocol": sip_transport_protocol,
                     "sound_modifications": sound_modifications,
                     "stream_bidirectional_codec": stream_bidirectional_codec,

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/resources/recordings/recordings.py

@@ -108,7 +108,7 @@ class RecordingsResource(SyncAPIResource):
               Consolidated filter parameter (deepObject style). Originally:
               filter[conference_id], filter[created_at][gte], filter[created_at][lte],
               filter[call_leg_id], filter[call_session_id], filter[from], filter[to],
-              filter[connection_id]
+              filter[connection_id], filter[sip_call_id]
 
           page: Consolidated page parameter (deepObject style). Originally: page[size],
               page[number]
@@ -250,7 +250,7 @@ class AsyncRecordingsResource(AsyncAPIResource):
               Consolidated filter parameter (deepObject style). Originally:
               filter[conference_id], filter[created_at][gte], filter[created_at][lte],
               filter[call_leg_id], filter[call_session_id], filter[from], filter[to],
-              filter[connection_id]
+              filter[connection_id], filter[sip_call_id]
 
           page: Consolidated page parameter (deepObject style). Originally: page[size],
               page[number]

telnyx-3.10.0/src/telnyx/resources/webhooks.py

@@ -0,0 +1,182 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+import json
+from typing import Mapping, cast
+from datetime import datetime, timezone
+
+from .._models import construct_type
+from .._resource import SyncAPIResource, AsyncAPIResource
+from .._exceptions import TelnyxError
+from ..types.unwrap_webhook_event import UnwrapWebhookEvent
+from ..types.unsafe_unwrap_webhook_event import UnsafeUnwrapWebhookEvent
+
+__all__ = ["WebhooksResource", "AsyncWebhooksResource", "TelnyxWebhook", "TelnyxWebhookVerificationError"]
+
+
+class TelnyxWebhookVerificationError(TelnyxError):
+    """Raised when webhook verification fails."""
+    pass
+
+
+class TelnyxWebhook:
+    """
+    Telnyx webhook verification following the standardwebhooks pattern.
+    
+    This class provides ED25519 signature verification for Telnyx webhooks
+    using the same interface pattern as the standardwebhooks library.
+    """
+    
+    def __init__(self, key: str | bytes):
+        """
+        Initialize the webhook verifier with a public key.
+        
+        Args:
+            key: The public key for verification (hex string or bytes)
+        """
+        try:
+            from nacl.signing import VerifyKey
+        except ImportError as exc:
+            raise TelnyxError("You need to install `pynacl` to verify Telnyx webhooks") from exc
+        
+        # Convert key to bytes if it's a string
+        if isinstance(key, str):
+            try:
+                key = bytes.fromhex(key)  # Convert from hex string to bytes
+            except ValueError as exc:
+                raise TelnyxWebhookVerificationError(f"Invalid key format: {key!r}") from exc
+        
+        self._verify_key = VerifyKey(key)
+    
+    def verify(self, payload: str, headers: Mapping[str, str]) -> None:
+        """
+        Verify a webhook payload and headers.
+        
+        Args:
+            payload: The webhook payload string
+            headers: The webhook headers
+            
+        Raises:
+            TelnyxWebhookVerificationError: If verification fails
+        """
+        try:
+            from nacl.exceptions import BadSignatureError
+        except ImportError as exc:
+            raise TelnyxError("You need to install `pynacl` to verify Telnyx webhooks") from exc
+        
+        # Extract required headers (case-insensitive lookup)
+        signature_header = headers.get("Telnyx-Signature-Ed25519") or headers.get("telnyx-signature-ed25519")
+        timestamp_header = headers.get("Telnyx-Timestamp") or headers.get("telnyx-timestamp")
+        user_agent = headers.get("User-Agent") or headers.get("user-agent", "")
+
+        # Validate required headers
+        if not signature_header:
+            raise TelnyxWebhookVerificationError("Missing required header: Telnyx-Signature-Ed25519")
+        
+        if not timestamp_header:
+            raise TelnyxWebhookVerificationError("Missing required header: Telnyx-Timestamp")
+
+        # Verify User-Agent if present (optional security check)
+        if user_agent and "telnyx-webhooks" not in user_agent.lower():
+            raise TelnyxWebhookVerificationError(f"Unexpected User-Agent: {user_agent}")
+
+        # Validate timestamp format and prevent replay attacks
+        try:
+            webhook_time = int(timestamp_header)
+            current_time = int(datetime.now(timezone.utc).timestamp())
+            
+            # Allow 5 minutes tolerance
+            if abs(current_time - webhook_time) > 300:
+                raise TelnyxWebhookVerificationError(
+                    f"Webhook timestamp too old or too new: {timestamp_header}"
+                )
+        except ValueError as exc:
+            raise TelnyxWebhookVerificationError(
+                f"Invalid timestamp format: {timestamp_header}"
+            ) from exc
+
+        # Decode the signature from hex
+        try:
+            signature = bytes.fromhex(signature_header)
+        except ValueError as exc:
+            raise TelnyxWebhookVerificationError(
+                f"Invalid signature format: {signature_header}"
+            ) from exc
+
+        # Create the signed payload: timestamp + payload
+        signed_payload = timestamp_header.encode('utf-8') + payload.encode('utf-8')
+
+        # Verify the signature
+        try:
+            self._verify_key.verify(signed_payload, signature)
+        except BadSignatureError as exc:
+            raise TelnyxWebhookVerificationError("Invalid webhook signature") from exc
+
+
+class WebhooksResource(SyncAPIResource):
+    def unsafe_unwrap(self, payload: str) -> UnsafeUnwrapWebhookEvent:
+        return cast(
+            UnsafeUnwrapWebhookEvent,
+            construct_type(
+                type_=UnsafeUnwrapWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )
+
+    def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
+        if key is None:
+            key = self._client.public_key
+            if key is None:
+                raise ValueError(
+                    "Cannot verify a webhook without a key on either the client's public_key or passed in as an argument"
+                )
+
+        if not isinstance(headers, dict):
+            headers = dict(headers)
+
+        # Use Telnyx-specific webhook verification following standardwebhooks pattern
+        webhook = TelnyxWebhook(key)
+        webhook.verify(payload, headers)
+
+        return cast(
+            UnwrapWebhookEvent,
+            construct_type(
+                type_=UnwrapWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )
+
+
+class AsyncWebhooksResource(AsyncAPIResource):
+    def unsafe_unwrap(self, payload: str) -> UnsafeUnwrapWebhookEvent:
+        return cast(
+            UnsafeUnwrapWebhookEvent,
+            construct_type(
+                type_=UnsafeUnwrapWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )
+
+    def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
+        if key is None:
+            key = self._client.public_key
+            if key is None:
+                raise ValueError(
+                    "Cannot verify a webhook without a key on either the client's public_key or passed in as an argument"
+                )
+
+        if not isinstance(headers, dict):
+            headers = dict(headers)
+
+        # Use Telnyx-specific webhook verification following standardwebhooks pattern
+        webhook = TelnyxWebhook(key)
+        webhook.verify(payload, headers)
+
+        return cast(
+            UnwrapWebhookEvent,
+            construct_type(
+                type_=UnwrapWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/types/call_dial_params.py

@@ -219,6 +219,9 @@ class CallDialParams(TypedDict, total=False):
     Currently only User-to-User header is supported.
     """
 
+    sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"]
+    """Defines the SIP region to be used for the call."""
+
     sip_transport_protocol: Literal["UDP", "TCP", "TLS"]
     """Defines SIP transport protocol to be used on the call."""
 

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/types/calls/action_transfer_params.py

@@ -164,6 +164,9 @@ class ActionTransferParams(TypedDict, total=False):
     Currently only User-to-User header is supported.
     """
 
+    sip_region: Literal["US", "Europe", "Canada", "Australia", "Middle East"]
+    """Defines the SIP region to be used for the call."""
+
     sip_transport_protocol: Literal["UDP", "TCP", "TLS"]
     """Defines SIP transport protocol to be used on the call."""
 

{telnyx-3.8.0 → telnyx-3.10.0}/src/telnyx/types/recording_list_params.py

@@ -13,7 +13,7 @@ class RecordingListParams(TypedDict, total=False):
 
     Originally: filter[conference_id], filter[created_at][gte],
     filter[created_at][lte], filter[call_leg_id], filter[call_session_id],
-    filter[from], filter[to], filter[connection_id]
+    filter[from], filter[to], filter[connection_id], filter[sip_call_id]
     """
 
     page: Page
@@ -61,6 +61,12 @@ class Filter(_FilterReservedKeywords, total=False):
 
     created_at: FilterCreatedAt
 
+    sip_call_id: str
+    """
+    If present, recordings will be filtered to those with a matching `sip_call_id`
+    attribute. Matching is case-sensitive
+    """
+
     to: str
     """
     If present, recordings will be filtered to those with a matching `to` attribute

{telnyx-3.8.0 → telnyx-3.10.0}/tests/api_resources/calls/test_actions.py

@@ -2269,6 +2269,7 @@ class TestActions:
                     "value": "value",
                 }
             ],
+            sip_region="Canada",
             sip_transport_protocol="TLS",
             sound_modifications={
                 "octaves": 0.1,
@@ -4588,6 +4589,7 @@ class TestAsyncActions:
                     "value": "value",
                 }
             ],
+            sip_region="Canada",
             sip_transport_protocol="TLS",
             sound_modifications={
                 "octaves": 0.1,

{telnyx-3.8.0 → telnyx-3.10.0}/tests/api_resources/test_calls.py

@@ -113,6 +113,7 @@ class TestCalls:
                     "value": "12345",
                 }
             ],
+            sip_region="Canada",
             sip_transport_protocol="TLS",
             sound_modifications={
                 "octaves": 0.1,
@@ -333,6 +334,7 @@ class TestAsyncCalls:
                     "value": "12345",
                 }
             ],
+            sip_region="Canada",
             sip_transport_protocol="TLS",
             sound_modifications={
                 "octaves": 0.1,

{telnyx-3.8.0 → telnyx-3.10.0}/tests/api_resources/test_recordings.py

@@ -83,6 +83,7 @@ class TestRecordings:
                     "lte": "2019-03-29T11:10:00Z",
                 },
                 "from": "1234567890",
+                "sip_call_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
                 "to": "1234567890",
             },
             page={
@@ -224,6 +225,7 @@ class TestAsyncRecordings:
                     "lte": "2019-03-29T11:10:00Z",
                 },
                 "from": "1234567890",
+                "sip_call_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
                 "to": "1234567890",
             },
             page={