python changes for orgs api uptake

CHANGES.md

@@ -3,6 +3,150 @@ twilio-python Changelog
 
 Here you can see the full list of changes between each twilio-python release.
 
+[2024-12-05] Version 9.3.8
+--------------------------
+**Api**
+- Add optional parameter `intelligence_service` to `transcription`
+- Updated `phone_number_sid` to be populated for sip trunking terminating calls.
+
+**Numbers**
+- Add Update Hosted Number Order V2 API endpoint
+- Update Port in docs
+
+**Twiml**
+- Add optional parameter `intelligence_service` to `<Transcription>`
+- Add support for new `<ConversationRelay>` and `<Assistant>` noun
+- Add `events` attribute to `<Dial>` verb
+
+
+[2024-11-15] Version 9.3.7
+--------------------------
+**Library - Chore**
+- [PR #819](https://github.com/twilio/twilio-python/pull/819): use older verison of aiohttp_retry. Thanks to [@sbansla](https://github.com/sbansla)!
+
+**Api**
+- Added `ivr-virtual-agent-custom-voices` and `ivr-virtual-agent-genai` to `usage_record` API.
+- Add open-api file tag to realtime_transcriptions
+
+**Taskrouter**
+- Add `api-tag` property to workers reservation
+- Add `api-tag` property to task reservation
+
+
+[2024-10-25] Version 9.3.6
+--------------------------
+**Library - Chore**
+- [PR #818](https://github.com/twilio/twilio-python/pull/818): removing unavailable references from init files. Thanks to [@tiwarishubham635](https://github.com/tiwarishubham635)!
+
+
+[2024-10-24] Version 9.3.5
+--------------------------
+**Conversations**
+- Expose ConversationWithParticipants resource that allows creating a conversation with participants
+
+
+[2024-10-17] Version 9.3.4
+--------------------------
+**Api**
+- Add response key `country` to fetch AvailablePhoneNumber resource by specific country.
+
+**Messaging**
+- Make library and doc public for requestManagedCert Endpoint
+
+
+[2024-10-03] Version 9.3.3
+--------------------------
+**Library - Chore**
+- [PR #816](https://github.com/twilio/twilio-python/pull/816): add assistants init files. Thanks to [@tiwarishubham635](https://github.com/tiwarishubham635)!
+
+**Messaging**
+- Add A2P external campaign CnpMigration flag
+
+**Numbers**
+- Add address sid to portability API
+
+**Verify**
+- Add `SnaClientToken` optional parameter on Verification check.
+- Add `EnableSnaClientToken` optional parameter for Verification creation.
+
+
+[2024-09-25] Version 9.3.2
+--------------------------
+**Accounts**
+- Update docs and mounts.
+- Change library visibility to public
+- Enable consent and contact bulk upsert APIs in prod.
+
+**Serverless**
+- Add is_plugin parameter in deployments api to check if it is plugins deployment
+
+
+[2024-09-18] Version 9.3.1
+--------------------------
+**Library - Chore**
+- [PR #813](https://github.com/twilio/twilio-python/pull/813): add static init file to iam domain. Thanks to [@tiwarishubham635](https://github.com/tiwarishubham635)!
+
+**Intelligence**
+- Remove public from operator_type
+- Update operator_type to include general-availablity and deprecated
+
+**Numbers**
+- Remove beta flag for bundle clone API
+
+
+[2024-09-05] Version 9.3.0
+--------------------------
+**Iam**
+- updated library_visibility public for new public apikeys
+
+**Numbers**
+- Add new field in Error Codes for Regulatory Compliance.
+- Change typing of Port In Request date_created field to date_time instead of date **(breaking change)**
+
+
+[2024-08-26] Version 9.2.4
+--------------------------
+**Library - Chore**
+- [PR #810](https://github.com/twilio/twilio-python/pull/810): add license identifier to project metadata. Thanks to [@mschoettle](https://github.com/mschoettle)!
+- [PR #808](https://github.com/twilio/twilio-python/pull/808): preview iam removal. Thanks to [@manisha1997](https://github.com/manisha1997)!
+- [PR #807](https://github.com/twilio/twilio-python/pull/807): update intersphinx_mapping. Thanks to [@tiwarishubham635](https://github.com/tiwarishubham635)!
+- [PR #804](https://github.com/twilio/twilio-python/pull/804): add init file. Thanks to [@manisha1997](https://github.com/manisha1997)!
+
+**Api**
+- Update documentation of `error_code` and `error_message` on the Message resource.
+- Remove generic parameters from `transcription` resource
+- Added public documentation for Payload Data retrieval API
+
+**Flex**
+- Adding update Flex User api
+
+**Insights**
+- Added 'branded', 'business_profile' and 'voice_integrity' fields in List Call Summary
+
+**Intelligence**
+- Add `words` array information to the Sentences v2 entity.
+- Add `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining`, and `X-Rate-Limit-Config` headers for Operator Results.
+- Change the path parameter when fetching an `/OperatorType/{}` from `sid<EY>` to `string` to support searching by SID or by name
+- Add `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining`, and `X-Rate-Limit-Config` headers for Transcript and Service endpoints.
+
+**Messaging**
+- Adds two new channel senders api to add/remove channel senders to/from a messaging service
+- Extend ERC api to accept an optional attribute in request body to indicate CNP migration for an ERC
+
+**Numbers**
+- Modify visibility to public in bundle clone API
+- Add `port_date` field to Port In Request and Port In Phone Numbers Fetch APIs
+- Change properties docs for port in phone numbers api
+- Add is_test body param to the Bundle Create API
+- Change properties docs for port in api
+
+**Trusthub**
+- Add new field in themeSetId in compliance_inquiry.
+
+**Verify**
+- Update `custom_code_enabled` description on verification docs
+
+
 [2024-07-02] Version 9.2.3
 --------------------------
 **Intelligence**

README.md

@@ -86,6 +86,13 @@ After a brief delay, you will receive the text message on your phone.
 > **Warning**
 > It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
 
+## OAuth Feature for Twilio APIs
+We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.
+
+API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/public_oauth.py)
+
+Organisation API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/organization_api_calls.py)
+
 ## Use the helper library
 
 ### API Credentials

docs/conf.py

@@ -203,4 +203,4 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

examples/organization_api_calls.py

@@ -0,0 +1,28 @@
+import os
+
+from twilio.rest import Client
+from twilio.credential.orgs_credential_provider import OrgsCredentialProvider
+
+API_KEY = os.environ.get("TWILIO_API_KEY")
+API_SECRET = os.environ.get("TWILIO_API_SECRET")
+ACCOUNT_SID = os.environ.get("TWILIO_ACCOUNT_SID")
+CLIENT_ID = os.environ.get("TWILIO_CLIENT_ID")
+CLIENT_SECRET = os.environ.get("TWILIO_CLIENT_SECRET")
+ORGS_SID = os.environ.get("TWILIO_ORGS_SID")
+
+
+def example(self=None):
+    """
+    Some example usage of fetching accounts within an organization
+    """
+    self.client = Client(
+        username=API_KEY,
+        password=API_SECRET,
+        account_sid=ACCOUNT_SID,
+        credential_provider= OrgsCredentialProvider(CLIENT_ID, CLIENT_SECRET)
+    )
+    accounts = self.client.preview_iam.organization(organization_sid=ORGS_SID).accounts.stream()
+    self.assertIsNotNone(accounts)
+
+if __name__ == "__main__":
+    example()

examples/public_oauth.py

@@ -0,0 +1,35 @@
+import os
+
+from twilio.rest import Client
+from twilio.credential.client_credential_provider import ClientCredentialProvider
+
+API_KEY = os.environ.get("TWILIO_API_KEY")
+API_SECRET = os.environ.get("TWILIO_API_SECRET")
+ACCOUNT_SID = os.environ.get("TWILIO_ACCOUNT_SID")
+CLIENT_ID = os.environ.get("TWILIO_CLIENT_ID")
+CLIENT_SECRET = os.environ.get("TWILIO_CLIENT_SECRET")
+ORGS_SID = os.environ.get("TWILIO_ORGS_SID")
+FROM_NUMBER = os.environ.get("TWILIO_FROM_NUMBER")
+TO_NUMBER = os.environ.get("TWILIO_TO_NUMBER")
+
+
+def example(self=None):
+    """
+    Some example usage of fetching accounts within an organization
+    """
+    self.client = Client(
+        username=API_KEY,
+        password=API_SECRET,
+        account_sid=ACCOUNT_SID,
+        credential_provider= ClientCredentialProvider(CLIENT_ID, CLIENT_SECRET)
+    )
+    msg = self.client.messages.create(
+        to=self.to_number, from_=self.from_number, body="hello world"
+    )
+    self.assertEqual(msg.to, self.to_number)
+    self.assertEqual(msg.from_, self.from_number)
+    self.assertEqual(msg.body, "hello world")
+    self.assertIsNotNone(msg.sid)
+
+if __name__ == "__main__":
+    example()

requirements.txt

@@ -2,5 +2,5 @@ pygments>=2.7.4 # not directly required, pinned by Snyk to avoid a vulnerability
 requests>=2.31.0
 PyJWT>=2.0.0, <3.0.0
 aiohttp>=3.9.4
-aiohttp-retry>=2.8.3
+aiohttp-retry==2.8.3
 certifi>=2023.7.22 # not directly required, pinned by Snyk to avoid a vulnerability

setup.cfg

@@ -3,6 +3,7 @@ universal = 1
 
 [metadata]
 description-file = README.md
+license = MIT
 
 [flake8]
 exclude = ./twilio/rest,./twilio/twiml,./tests/integration

setup.py

@@ -13,7 +13,7 @@
 
 setup(
     name="twilio",
-    version="9.2.3",
+    version="9.3.8",
     description="Twilio API client and TwiML generator",
     author="Twilio",
     help_center="https://www.twilio.com/help/contact",
@@ -24,7 +24,7 @@
         "requests >= 2.0.0",
         "PyJWT >= 2.0.0, < 3.0.0",
         "aiohttp>=3.8.4",
-        "aiohttp-retry>=2.8.3",
+        "aiohttp-retry==2.8.3",
     ],
     packages=find_packages(exclude=["tests", "tests.*"]),
     include_package_data=True,

twilio/__init__.py

@@ -1,2 +1,2 @@
-__version_info__ = ("9", "2", "3")
+__version_info__ = ("9", "3", "8")
 __version__ = ".".join(__version_info__)

twilio/auth_strategy/auth_strategy.py

@@ -0,0 +1,19 @@
+from twilio.auth_strategy.auth_type import AuthType
+from abc import abstractmethod
+
+
+class AuthStrategy(object):
+    def __init__(self, auth_type: AuthType):
+        self._auth_type = auth_type
+
+    @property
+    def auth_type(self) -> AuthType:
+        return self._auth_type
+
+    @abstractmethod
+    def get_auth_string(self) -> str:
+        """Return the authentication string."""
+
+    @abstractmethod
+    def requires_authentication(self) -> bool:
+        """Return True if authentication is required, else False."""

twilio/auth_strategy/auth_type.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class AuthType(Enum):
+    ORGS_TOKEN = "orgs_stoken"
+    NO_AUTH = "noauth"
+    BASIC = "basic"
+    API_KEY = "api_key"
+    CLIENT_CREDENTIALS = "client_credentials"
+
+    def __str__(self):
+        return self.value

twilio/auth_strategy/no_auth_strategy.py

@@ -0,0 +1,13 @@
+from auth_type import AuthType
+from twilio.auth_strategy.auth_strategy import AuthStrategy
+
+
+class NoAuthStrategy(AuthStrategy):
+    def __init__(self):
+        super().__init__(AuthType.NO_AUTH)
+
+    def get_auth_string(self) -> str:
+        return ""
+
+    def requires_authentication(self) -> bool:
+        return False

twilio/auth_strategy/token_auth_strategy.py

@@ -0,0 +1,53 @@
+import jwt
+import threading
+import logging
+from datetime import datetime
+
+from twilio.auth_strategy.auth_type import AuthType
+from twilio.auth_strategy.auth_strategy import AuthStrategy
+from twilio.http.token_manager import TokenManager
+
+
+class TokenAuthStrategy(AuthStrategy):
+    def __init__(self, token_manager: TokenManager):
+        super().__init__(AuthType.ORGS_TOKEN)
+        self.token_manager = token_manager
+        self.token = None
+        self.lock = threading.Lock()
+        logging.basicConfig(level=logging.INFO)
+        self.logger = logging.getLogger(__name__)
+
+    def get_auth_string(self) -> str:
+        self.fetch_token()
+        return f"Bearer {self.token}"
+
+    def requires_authentication(self) -> bool:
+        return True
+
+    def fetch_token(self):
+        if self.token is None or self.token == "" or self.is_token_expired(self.token):
+            with self.lock:
+                if (
+                    self.token is None
+                    or self.token == ""
+                    or self.is_token_expired(self.token)
+                ):
+                    self.logger.info("New token fetched for accessing organization API")
+                    self.token = self.token_manager.fetch_access_token()
+
+    def is_token_expired(self, token):
+        try:
+            decoded = jwt.decode(token, options={"verify_signature": False})
+            exp = decoded.get("exp")
+
+            if exp is None:
+                return True  # No expiration time present, consider it expired
+
+            # Check if the expiration time has passed
+            return datetime.fromtimestamp(exp) < datetime.utcnow()
+
+        except jwt.DecodeError:
+            return True  # Token is invalid
+        except Exception as e:
+            print(f"An error occurred: {e}")
+            return True