Merge pull request #77 from pusher/native-push

Basic native push

Author: jpatel531

README.md

@@ -150,22 +150,66 @@ pusher.trigger_batch([
 ])
 ```
 
-#### Event Buffer
+## Push Notifications (BETA)
 
-Version 1.0.0 of the library introduced support for event buffering. The purpose of this functionality is to ensure that events that are triggered during whilst a client is offline for a short period of time will still be delivered upon reconnection.
+Pusher now allows sending native notifications to iOS and Android devices. Check out the [documentation](https://pusher.com/docs/push_notifications) for information on how to set up push notifications on Android and iOS. There is no additional setup required to use it with this library. It works out of the box wit the same Pusher instance. All you need are the same pusher credentials.
 
-**Note: this requires your Pusher application to be on a cluster that has the Event Buffer capability.**
+### Sending native pushes
 
-As part of this the trigger function now returns a set of event_id values for each event triggered on a channel. These can then be used by the client to tell the Pusher service the last event it has received. If additional events have been triggered after that event ID the service has the opportunity to provide the client with those IDs.
+The native notifications API is hosted at `nativepushclient-cluster1.pusher.com` and only accepts https requests.
 
-##### Example
+You can send pushes by using the `notify` method, either globally or on the instance. The method takes two parameters:
+
+- `interests`: An Array of strings which represents the interests your devices are subscribed to. These are akin to channels in the DDN with less of an epehemeral nature. Note that currently, you can only send to _one_ interest.
+- `data`: The content of the notification represented by a Hash. You must supply either the `gcm` or `apns` key. For a detailed list of the acceptable keys, take a look at the [docs](https://pusher.com/docs/push_notifications#payload).
+
+Example:
 
 ```python
-events = pusher.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")
+data = {
+  'apns': {
+    'priority': 5,
+    'aps': {
+      'alert': {
+        'body': 'tada'
+      }
+    }
+  }
+}
 
-#=> {'event_ids': {'another_channel': 'eudhq17zrhfbwc', 'a_channel': 'eudhq17zrhfbtn'}}
+pusher.notify(["my-favourite-interest"], data)
 ```
 
+### Errors
+
+Push notification requests, once submitted to the service are executed asynchronously. To make reporting errors easier, you can supply a `webhook_url` field in the body of the request. This will be used by the service to send a webhook to the supplied URL if there are errors.
+
+You may also supply a `webhook_level` field in the body, which can either be INFO or DEBUG. It defaults to INFO - where INFO only reports customer facing errors, while DEBUG reports all errors.
+
+For example:
+
+```python
+data = {
+  "apns": {
+    "aps": {
+      "alert": {
+        "body": "hello"
+      }
+    }
+  },
+  'gcm': {
+    'notification': {
+      "title": "hello",
+      "icon": "icon"
+    }
+  },
+  "webhook_url": "http://yolo.com",
+  "webhook_level": "INFO"
+}
+```
+
+**NOTE:** This is currently a BETA feature and there might be minor bugs and issues. Changes to the API will be kept to a minimum, but changes are expected. If you come across any bugs or issues, please do get in touch via [support](support@pusher.com) or create an issue here.
+
 Querying Application State
 -----------------
 

pusher/config.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+from .util import ensure_text, app_id_re
+
+import six
+
+class Config(object):
+
+	def __init__(self, app_id, key, secret, ssl=True, host=None, port=None, timeout=5, cluster=None,
+								json_encoder=None, json_decoder=None, backend=None, **backend_options):
+		if backend is None:
+	  		from .requests import RequestsBackend
+	  		backend = RequestsBackend
+
+		self._app_id = ensure_text(app_id, "app_id")
+		if not app_id_re.match(self._app_id):
+	  		raise ValueError("Invalid app id")
+
+		self._key = ensure_text(key, "key")
+		self._secret = ensure_text(secret, "secret")
+
+		if not isinstance(ssl, bool):
+  			raise TypeError("SSL should be a boolean")
+		self._ssl = ssl
+
+		if port and not isinstance(port, six.integer_types):
+  			raise TypeError("port should be an integer")
+		self._port = port or (443 if ssl else 80)
+
+		if not isinstance(timeout, six.integer_types):
+	  		raise TypeError("timeout should be an integer")
+		self._timeout = timeout
+		self._json_encoder = json_encoder
+		self._json_decoder = json_decoder
+
+		self.http = backend(self, **backend_options)
+
+	@property
+	def app_id(self):
+	    return self._app_id
+
+	@property
+	def key(self):
+	    return self._key
+
+	@property
+	def secret(self):
+	    return self._secret
+
+	@property
+	def host(self):
+	    return self._host
+
+	@property
+	def port(self):
+	    return self._port
+
+	@property
+	def timeout(self):
+	    return self._timeout
+
+	@property
+	def ssl(self):
+	    return self._ssl
+
+	@property
+	def scheme(self):
+	    return 'https' if self.ssl else 'http'

pusher/http.py

@@ -43,6 +43,8 @@ def make_query_string(params):
 def process_response(status, body):
     if status == 200:
         return json.loads(body)
+    if status == 202:
+        return True
     elif status == 400:
         raise PusherBadRequest(body)
     elif status == 401:

pusher/notification_client.py

@@ -0,0 +1,90 @@
+from .config import Config
+from .http import POST, Request, request_method
+from .util import ensure_text
+
+DEFAULT_HOST = "yolo.ngrok.io"
+RESTRICTED_GCM_KEYS = ['to', 'registration_ids']
+API_PREFIX = 'customer_api'
+API_VERSION = 'v1'
+GCM_TTL = 241920
+WEBHOOK_LEVELS = ['INFO', 'DEBUG', '']
+
+class NotificationClient(Config):
+
+	def __init__(self, app_id, key, secret, ssl=True, host=None, port=None, timeout=5, cluster=None,
+				 json_encoder=None, json_decoder=None, backend=None, **backend_options):
+
+		super(NotificationClient, self).__init__(
+			app_id, key, secret, ssl,
+			host, port, timeout, cluster,
+			json_encoder, json_decoder, backend,
+			**backend_options)
+
+		if host:
+			self._host = ensure_text(host, "host")
+		else:
+			self._host = DEFAULT_HOST
+
+
+	@request_method
+	def notify(self, interests, notification):
+		if not isinstance(interests, list) and not isinstance(interests, set):
+			raise TypeError("Interests must be a list or a set")
+
+		if len(interests) is not 1:
+			raise ValueError("Currently sending to more than one interest is unsupported")
+
+		if not isinstance(notification, dict):
+			raise TypeError("Notification must be a dictionary")
+
+		params = {
+			'interests': interests,
+		}
+		params.update(notification)
+		self.validate_notification(params)
+		path =  "/%s/%s/apps/%s/notifications" % (API_PREFIX, API_VERSION, self.app_id)
+		return Request(self, POST, path, params)
+
+	def validate_notification(self, notification):
+		gcm_payload = notification.get('gcm')
+
+		if not gcm_payload and not notification.get('apns') :
+			raise ValueError("Notification must have fields APNS or GCM")
+
+		if gcm_payload:
+			for restricted_key in RESTRICTED_GCM_KEYS:
+				gcm_payload.pop(restricted_key, None)
+
+			ttl = gcm_payload.get('time_to_live')
+			if ttl:
+				if not isinstance(ttl, int):
+					raise ValueError("GCM time_to_live must be an int")
+
+				if not (0 <= ttl <= GCM_TTL):
+					raise ValueError("GCM time_to_live must be between 0 and 241920 (4 weeks)")
+
+			gcm_payload_notification = gcm_payload.get('notification')
+			if gcm_payload_notification:
+				title = gcm_payload_notification.get('title')
+				icon = gcm_payload_notification.get('icon')
+				if not isinstance(title, str):
+					raise ValueError("GCM notification title is required must be a string")
+
+				if not isinstance(icon, str):
+					raise ValueError("GCM notification icon is required must be a string")
+
+				if len(title) is 0:
+					raise ValueError("GCM notification title must not be empty")
+
+				if len(icon) is 0:
+					raise ValueError("GCM notification icon must not be empty")
+
+		webhook_url = notification.get('webhook_url')
+		webhook_level = notification.get('webhook_level')
+
+		if webhook_level:
+			if not webhook_url:
+				raise ValueError("webhook_level cannot be used without a webhook_url")
+
+			if not webhook_level in WEBHOOK_LEVELS:
+				raise ValueError("webhook_level must be either INFO or DEBUG. Blank will default to INFO")

pusher/pusher.py

@@ -4,7 +4,9 @@
                         division)
 from pusher.http import GET, POST, Request, request_method
 from pusher.signature import sign, verify
-from pusher.util import ensure_text, validate_channel, validate_socket_id, app_id_re, pusher_url_re, channel_name_re
+from pusher.util import ensure_text, validate_channel, validate_socket_id, pusher_url_re, channel_name_re
+from pusher.config import Config
+from pusher.notification_client import NotificationClient
 
 import collections
 import hashlib
@@ -17,7 +19,7 @@
 def join_attributes(attributes):
     return six.text_type(',').join(attributes)
 
-class Pusher(object):
+class Pusher(Config):
     """Client for the Pusher HTTP API.
 
     This client supports various backend adapters to support various http
@@ -36,41 +38,25 @@ class Pusher(object):
     :param backend_options: additional backend
     """
     def __init__(self, app_id, key, secret, ssl=True, host=None, port=None, timeout=5, cluster=None,
-                 json_encoder=None, json_decoder=None, backend=None, **backend_options):
-
-        if backend is None:
-            from pusher.requests import RequestsBackend
-            backend = RequestsBackend
-
-        self._app_id = ensure_text(app_id, "app_id")
-        if not app_id_re.match(self._app_id):
-            raise ValueError("Invalid app id")
-
-        self._key = ensure_text(key, "key")
-        self._secret = ensure_text(secret, "secret")
-
-        if not isinstance(ssl, bool):
-            raise TypeError("SSL should be a boolean")
-        self._ssl = ssl
-
+                 json_encoder=None, json_decoder=None, backend=None, notification_host=None,
+                 notification_ssl=True, **backend_options):
+        super(Pusher, self).__init__(
+            app_id, key, secret, ssl,
+            host, port, timeout, cluster,
+            json_encoder, json_decoder, backend,
+            **backend_options)
         if host:
             self._host = ensure_text(host, "host")
         elif cluster:
             self._host = six.text_type("api-%s.pusher.com") % ensure_text(cluster, "cluster")
         else:
             self._host = six.text_type("api.pusherapp.com")
 
-        if port and not isinstance(port, six.integer_types):
-            raise TypeError("port should be an integer")
-        self._port = port or (443 if ssl else 80)
-
-        if not isinstance(timeout, six.integer_types):
-            raise TypeError("timeout should be an integer")
-        self._timeout = timeout
-        self._json_encoder = json_encoder
-        self._json_decoder = json_decoder
-
-        self.http = backend(self, **backend_options)
+        self._notification_client = NotificationClient(
+            app_id, key, secret, notification_ssl,
+            notification_host, port, timeout, cluster,
+            json_encoder, json_decoder, backend,
+            **backend_options)
 
     @classmethod
     def from_url(cls, url, **options):
@@ -116,7 +102,7 @@ def from_env(cls, env='PUSHER_URL', **options):
         val = os.environ.get(env)
         if not val:
             raise Exception("Environment variable %s not found" % env)
-        
+
         return cls.from_url(val, **options)
 
     @request_method
@@ -126,7 +112,7 @@ def trigger(self, channels, event_name, data, socket_id=None):
 
         http://pusher.com/docs/rest_api#method-post-event
         '''
-        
+
         if isinstance(channels, six.string_types):
             channels = [channels]
 
@@ -280,36 +266,11 @@ def validate_webhook(self, key, signature, body):
         return body_data
 
     @property
-    def app_id(self):
-        return self._app_id
-
-    @property
-    def key(self):
-        return self._key
-
-    @property
-    def secret(self):
-        return self._secret
-
-    @property
-    def host(self):
-        return self._host
-
-    @property
-    def port(self):
-        return self._port
-
-    @property
-    def timeout(self):
-        return self._timeout
+    def notification_client(self):
+        return self._notification_client
 
-    @property
-    def ssl(self):
-        return self._ssl
-
-    @property
-    def scheme(self):
-        return 'https' if self.ssl else 'http'
+    def notify(self, interest, notification):
+        self._notification_client.notify(interest, notification)
 
     def _data_to_string(self, data):
         if isinstance(data, six.string_types):