More endpoints (#65)

* Rename some internal methods.

* Implement get_recording

* Test for get_recording

* Add submit_sms_conversion and some logging.

* Add submit_sms_conversion docs to the README

* Use pytz  timezone.

* It's important to add tests.

* Attempt to publish coverage info.

* Get Travis to run with coverage on.

* Add coverage badge to README

Author: judy2k

.travis.yml

@@ -10,4 +10,7 @@ install:
   - make install
 
 script:
-  - make test
+  - make coverage
+
+after_success:
+  - coveralls

Makefile

@@ -1,4 +1,8 @@
 .PHONY: test install requirements release release-test
+
+coverage:
+	pytest -v --cov
+
 test:
 	pytest -v
 

README.md

@@ -1,7 +1,9 @@
 Nexmo Client Library for Python
 ===============================
 
-[![PyPI version](https://badge.fury.io/py/nexmo.svg)](https://badge.fury.io/py/nexmo) [![Build Status](https://api.travis-ci.org/Nexmo/nexmo-python.svg?branch=master)](https://travis-ci.org/Nexmo/nexmo-python)
+[![PyPI version](https://badge.fury.io/py/nexmo.svg)](https://badge.fury.io/py/nexmo)
+[![Build Status](https://api.travis-ci.org/Nexmo/nexmo-python.svg?branch=master)](https://travis-ci.org/Nexmo/nexmo-python)
+[![Coverage Status](https://coveralls.io/repos/github/Nexmo/nexmo-python/badge.svg?branch=master)](https://coveralls.io/github/Nexmo/nexmo-python?branch=master)
 
 This is the Python client library for Nexmo's API. To use it you'll
 need a Nexmo account. Sign up [for free at nexmo.com][signup].
@@ -78,6 +80,15 @@ else:
 
 Docs: [https://docs.nexmo.com/messaging/sms-api/api-reference#request](https://docs.nexmo.com/messaging/sms-api/api-reference#request?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library)
 
+### Tell Nexmo the SMS was received
+
+The following submits a successful conversion to Nexmo with the current timestamp. This feature must
+be enabled on your account first.
+
+```python
+response = client.submit_sms_conversion(message_id)
+```
+
 
 ## Voice API
 

nexmo/__init__.py

@@ -1,9 +1,12 @@
+from datetime import datetime
+import logging
 from platform import python_version
 
 import hashlib
 import hmac
 import jwt
 import os
+import pytz
 import requests
 import sys
 import time
@@ -12,11 +15,15 @@
 
 if sys.version_info[0] == 3:
     string_types = (str, bytes)
+    from urllib.parse import urlparse
 else:
+    from urlparse import urlparse
     string_types = (unicode, str)
 
 __version__ = '2.0.0'
 
+logger = logging.getLogger('nexmo')
+
 
 class Error(Exception):
     pass
@@ -133,6 +140,24 @@ def send_ussd_prompt_message(self, params=None, **kwargs):
     def send_2fa_message(self, params=None, **kwargs):
         return self.post(self.host, '/sc/us/2fa/json', params or kwargs)
 
+    def submit_sms_conversion(self, message_id, delivered=True, timestamp=None):
+        """
+        Notify Nexmo that an SMS was successfully received.
+
+        :param message_id: The `message-id` str returned by the send_message call.
+        :param delivered: A `bool` indicating that the message was or was not successfully delivered.
+        :param timestamp: A `datetime` object containing the time the SMS arrived.
+        :return: The parsed response from the server. On success, the bytestring b'OK'
+        """
+        params = {
+            'message-id': message_id,
+            'delivered': delivered,
+            'timestamp': timestamp or datetime.now(pytz.utc),
+        }
+        # Ensure timestamp is a string:
+        _format_date_param(params, 'timestamp')
+        return self.post(self.api_host, '/conversions/sms', params)
+
     def send_event_alert_message(self, params=None, **kwargs):
         return self.post(self.host, '/sc/us/alert/json', params or kwargs)
 
@@ -226,31 +251,35 @@ def delete_application(self, application_id):
         return self.delete(self.api_host, '/v1/applications/' + application_id)
 
     def create_call(self, params=None, **kwargs):
-        return self.__post('/v1/calls', params or kwargs)
+        return self._jwt_signed_post('/v1/calls', params or kwargs)
 
     def get_calls(self, params=None, **kwargs):
-        return self.__get('/v1/calls', params or kwargs)
+        return self._jwt_signed_get('/v1/calls', params or kwargs)
 
     def get_call(self, uuid):
-        return self.__get('/v1/calls/' + uuid)
+        return self._jwt_signed_get('/v1/calls/' + uuid)
 
     def update_call(self, uuid, params=None, **kwargs):
-        return self.__put('/v1/calls/' + uuid, params or kwargs)
+        return self._jwt_signed_put('/v1/calls/' + uuid, params or kwargs)
 
     def send_audio(self, uuid, params=None, **kwargs):
-        return self.__put('/v1/calls/' + uuid + '/stream', params or kwargs)
+        return self._jwt_signed_put('/v1/calls/' + uuid + '/stream', params or kwargs)
 
     def stop_audio(self, uuid):
-        return self.__delete('/v1/calls/' + uuid + '/stream')
+        return self._jwt_signed_delete('/v1/calls/' + uuid + '/stream')
 
     def send_speech(self, uuid, params=None, **kwargs):
-        return self.__put('/v1/calls/' + uuid + '/talk', params or kwargs)
+        return self._jwt_signed_put('/v1/calls/' + uuid + '/talk', params or kwargs)
 
     def stop_speech(self, uuid):
-        return self.__delete('/v1/calls/' + uuid + '/talk')
+        return self._jwt_signed_delete('/v1/calls/' + uuid + '/talk')
 
     def send_dtmf(self, uuid, params=None, **kwargs):
-        return self.__put('/v1/calls/' + uuid + '/dtmf', params or kwargs)
+        return self._jwt_signed_put('/v1/calls/' + uuid + '/dtmf', params or kwargs)
+
+    def get_recording(self, url):
+        hostname = urlparse(url).hostname
+        return self.parse(hostname, requests.get(url, headers=self._headers()))
 
     def check_signature(self, params):
         params = dict(params)
@@ -286,28 +315,28 @@ def get(self, host, request_uri, params=None):
         uri = 'https://' + host + request_uri
 
         params = dict(params or {}, api_key=self.api_key, api_secret=self.api_secret)
-
+        logger.debug("GET to %r with params %r", uri, params)
         return self.parse(host, requests.get(uri, params=params, headers=self.headers))
 
     def post(self, host, request_uri, params):
         uri = 'https://' + host + request_uri
 
         params = dict(params, api_key=self.api_key, api_secret=self.api_secret)
-
+        logger.debug("POST to %r with params %r", uri, params)
         return self.parse(host, requests.post(uri, data=params, headers=self.headers))
 
     def put(self, host, request_uri, params):
         uri = 'https://' + host + request_uri
 
         params = dict(params, api_key=self.api_key, api_secret=self.api_secret)
-
+        logger.debug("PUT to %r with params %r", uri, params)
         return self.parse(host, requests.put(uri, json=params, headers=self.headers))
 
     def delete(self, host, request_uri):
         uri = 'https://' + host + request_uri
 
         params = dict(api_key=self.api_key, api_secret=self.api_secret)
-
+        logger.debug("DELETE to %r with params %r", uri, params)
         return self.parse(host, requests.delete(uri, params=params, headers=self.headers))
 
     def parse(self, host, response):
@@ -316,37 +345,40 @@ def parse(self, host, response):
         elif response.status_code == 204:
             return None
         elif 200 <= response.status_code < 300:
-            return response.json()
+            if response.headers.get('content-type') == 'application/json':
+                return response.json()
+            else:
+                return response.content
         elif 400 <= response.status_code < 500:
+            logger.warn("Client error: %s %r", response.status_code, response.content)
             message = "{code} response from {host}".format(code=response.status_code, host=host)
-
             raise ClientError(message)
         elif 500 <= response.status_code < 600:
+            logger.warn("Server error: %s %r", response.status_code, response.content)
             message = "{code} response from {host}".format(code=response.status_code, host=host)
-
             raise ServerError(message)
 
-    def __get(self, request_uri, params=None):
+    def _jwt_signed_get(self, request_uri, params=None):
         uri = 'https://' + self.api_host + request_uri
 
-        return self.parse(self.api_host, requests.get(uri, params=params or {}, headers=self.__headers()))
+        return self.parse(self.api_host, requests.get(uri, params=params or {}, headers=self._headers()))
 
-    def __post(self, request_uri, params):
+    def _jwt_signed_post(self, request_uri, params):
         uri = 'https://' + self.api_host + request_uri
 
-        return self.parse(self.api_host, requests.post(uri, json=params, headers=self.__headers()))
+        return self.parse(self.api_host, requests.post(uri, json=params, headers=self._headers()))
 
-    def __put(self, request_uri, params):
+    def _jwt_signed_put(self, request_uri, params):
         uri = 'https://' + self.api_host + request_uri
 
-        return self.parse(self.api_host, requests.put(uri, json=params, headers=self.__headers()))
+        return self.parse(self.api_host, requests.put(uri, json=params, headers=self._headers()))
 
-    def __delete(self, request_uri):
+    def _jwt_signed_delete(self, request_uri):
         uri = 'https://' + self.api_host + request_uri
 
-        return self.parse(self.api_host, requests.delete(uri, headers=self.__headers()))
+        return self.parse(self.api_host, requests.delete(uri, headers=self._headers()))
 
-    def __headers(self):
+    def _headers(self):
         iat = int(time.time())
 
         payload = dict(self.auth_params)
@@ -358,3 +390,19 @@ def __headers(self):
         token = jwt.encode(payload, self.private_key, algorithm='RS256')
 
         return dict(self.headers, Authorization=b'Bearer ' + token)
+
+
+def _format_date_param(params, key, format='%Y-%m-%d %H:%M:%S'):
+    """
+    Utility function to convert datetime values to strings.
+
+    If the value is already a str, or is not in the dict, no change is made.
+
+    :param params: A `dict` of params that may contain a `datetime` value.
+    :param key: The datetime value to be converted to a `str`
+    :param format: The `strftime` format to be used to format the date. The default value is '%Y-%m-%d %H:%M:%S'
+    """
+    if key in params:
+        param = params[key]
+        if hasattr(param, 'strftime'):
+            params[key] = param.strftime(format)

requirements.txt

@@ -2,3 +2,4 @@
 pytest==3.1.2
 pytest-cov==2.5.1
 responses==0.5.1
+coveralls

setup.py

@@ -15,7 +15,11 @@
       license='MIT',
       packages=['nexmo'],
       platforms=['any'],
-      install_requires=['requests', 'PyJWT[crypto]'],
+      install_requires=[
+          'requests',
+          'PyJWT[crypto]',
+          'pytz',
+      ],
       tests_require=['cryptography'],
       classifiers=[
           'Programming Language :: Python',

tests/test_nexmo.py

@@ -7,6 +7,12 @@
 import nexmo
 from util import *
 
+import sys
+if sys.version_info[0] == 3:
+    bytes_type = bytes 
+else:
+    bytes_type = str
+
 
 @responses.activate
 def test_send_ussd_push_message(client, dummy_data):
@@ -171,3 +177,11 @@ def test_client_can_make_application_requests_without_api_key(dummy_data):
 
     client = nexmo.Client(application_id='myid', private_key=dummy_data.private_key)
     client.create_call("123455")
+
+
+@responses.activate
+def test_get_recording(client, dummy_data):
+    stub_bytes(responses.GET, 'https://api.nexmo.com/v1/files/d6e47a2e-3414-11e8-8c2c-2f8b643ed957')
+
+    assert isinstance(client.get_recording('https://api.nexmo.com/v1/files/d6e47a2e-3414-11e8-8c2c-2f8b643ed957'), bytes_type)
+    assert request_user_agent() == dummy_data.user_agent

tests/test_sms.py

@@ -39,3 +39,11 @@ def test_server_error(client):
     with pytest.raises(nexmo.ServerError) as excinfo:
         client.send_message({})
     excinfo.match(r'500 response from rest.nexmo.com')
+
+@responses.activate
+def test_submit_sms_conversion(client):
+    responses.add(responses.POST, 'https://api.nexmo.com/conversions/sms', status=200, body=b'OK')
+
+    client.submit_sms_conversion('a-message-id')
+    assert 'message-id=a-message-id' in request_body()
+    assert 'timestamp' in request_body()

tests/util.py

@@ -34,6 +34,9 @@ def stub(method, url):
     responses.add(method, url, body='{"key":"value"}', status=200, content_type='application/json')
 
 
+def stub_bytes(method, url):
+    responses.add(method, url, body=b'THISISANMP3', status=200)
+
 def assert_re(pattern, string):
     __tracebackhide__ = True
     if not re.search(pattern, string):