Merge lp:~ralsina/ubuntu-push/merge-automatic into lp:ubuntu-push

[Roberto Alsina]

Latest changes from the automatic branch.

Latest changes from the automatic branch.

[Roberto Alsina (ralsina)]

review: Approve

[lp:~ralsina/ubuntu-push/merge-automatic]

129. By Roberto Alsina on 2014-09-08

Latest changes from the automatic branch.
Approved by: Roberto Alsina

=== modified file 'PACKAGE_DEPS'
--- PACKAGE_DEPS	2014-08-21 20:26:36 +0000
+++ PACKAGE_DEPS	2014-09-08 16:59:38 +0000
@@ -11,3 +11,4 @@
 libubuntu-app-launch2-dev
 libclick-0.4-dev
 liburl-dispatcher1-dev
+libaccounts-glib-dev

=== added directory 'accounts'
=== added file 'accounts/accounts.go'
--- accounts/accounts.go	1970-01-01 00:00:00 +0000
+++ accounts/accounts.go	2014-09-08 16:59:38 +0000
@@ -0,0 +1,42 @@
+/*
+ Copyright 2014 Canonical Ltd.
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 3, as published
+ by the Free Software Foundation.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranties of
+ MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+// Package accounts wraps libaccounts
+package accounts
+
+/*
+#cgo pkg-config: libaccounts-glib
+
+void start();
+
+*/
+import "C"
+
+type Changed struct{}
+
+var ch chan Changed
+
+//export gocb
+func gocb() {
+	ch <- Changed{}
+}
+
+func Watch() <-chan Changed {
+	ch = make(chan Changed, 1)
+	C.start()
+
+	return ch
+}

=== added file 'accounts/caccounts.go'
--- accounts/caccounts.go	1970-01-01 00:00:00 +0000
+++ accounts/caccounts.go	2014-09-08 16:59:38 +0000
@@ -0,0 +1,28 @@
+package accounts
+
+/*
+#include <libaccounts-glib/accounts-glib.h>
+
+static void cb(AgManager *manager, AgAccountId account_id, gpointer p) {
+    AgAccount *account = ag_manager_get_account(manager, account_id);
+    if (!account) {
+        return;
+    }
+    GList *services = ag_account_list_services(account);
+    if (!services || !services->data) {
+        return;
+    }
+
+    gocb();
+}
+
+void start() {
+    AgManager *manager = ag_manager_new_for_service_type("ubuntuone");
+    g_signal_connect(manager, "account-created", G_CALLBACK(cb), NULL);
+    g_signal_connect(manager, "account-deleted", G_CALLBACK(cb), NULL);
+    g_signal_connect(manager, "account-updated", G_CALLBACK(cb), NULL);
+
+}
+
+*/
+import "C"

=== modified file 'bus/endpoint.go'
--- bus/endpoint.go	2014-07-04 23:00:42 +0000
+++ bus/endpoint.go	2014-09-08 16:59:38 +0000
@@ -19,6 +19,7 @@
 // Here we define the Endpoint, which represents the DBus connection itself.
 
 import (
+	"encoding/base64"
 	"errors"
 	"fmt"
 
@@ -268,7 +269,16 @@
 					reply = dbus.NewErrorMessage(msg, err_iface, err.Error())
 					endp.log.Errorf("WatchMethod: %s(%v, %#v, %#v) failure: %#v", msg.Member, msg.Path, args, extra, err)
 				} else {
-					endp.log.Debugf("WatchMethod: %s(%v, %#v, %#v) success: %#v", msg.Member, msg.Path, args, extra, rvals)
+					var san_rvals []string
+					for _, element := range rvals {
+						sane := fmt.Sprintf("%v", element)
+						_, err := base64.StdEncoding.DecodeString(sane)
+						if err == nil {
+							sane = "LooksLikeAToken=="
+						}
+						san_rvals = append(san_rvals, sane)
+					}
+					endp.log.Debugf("WatchMethod: %s(%v, %#v, %#v) success: %#v", msg.Member, msg.Path, args, extra, san_rvals)
 					reply = dbus.NewMethodReturnMessage(msg)
 					err = reply.AppendArgs(rvals...)
 					if err != nil {

=== modified file 'client/client.go'
--- client/client.go	2014-08-24 13:09:01 +0000
+++ client/client.go	2014-09-08 16:59:38 +0000
@@ -32,6 +32,7 @@
 	"os/exec"
 	"strings"
 
+	"launchpad.net/ubuntu-push/accounts"
 	"launchpad.net/ubuntu-push/bus"
 	"launchpad.net/ubuntu-push/bus/connectivity"
 	"launchpad.net/ubuntu-push/bus/networkmanager"
@@ -123,6 +124,7 @@
 	trackAddressees    map[string]*click.AppId
 	installedChecker   click.InstalledChecker
 	poller             poller.Poller
+	accountsCh         <-chan accounts.Changed
 }
 
 // Creates a new Ubuntu Push Notifications client-side daemon that will use
@@ -175,6 +177,7 @@
 
 	client.connCh = make(chan bool, 1)
 	client.sessionConnectedCh = make(chan uint32, 1)
+	client.accountsCh = accounts.Watch()
 
 	if client.config.CertPEMFile != "" {
 		client.pem, err = ioutil.ReadFile(client.config.CertPEMFile)
@@ -464,10 +467,19 @@
 	return nil
 }
 
+// handleAccountsChange deals with the user adding or removing (or
+// changing) the u1 account used to auth
+func (client *PushClient) handleAccountsChange() {
+	client.log.Infof("U1 account changed; restarting session")
+	client.session.Close()
+}
+
 // doLoop connects events with their handlers
-func (client *PushClient) doLoop(connhandler func(bool), bcasthandler func(*session.BroadcastNotification) error, ucasthandler func(session.AddressedNotification) error, errhandler func(error), unregisterhandler func(*click.AppId)) {
+func (client *PushClient) doLoop(connhandler func(bool), bcasthandler func(*session.BroadcastNotification) error, ucasthandler func(session.AddressedNotification) error, errhandler func(error), unregisterhandler func(*click.AppId), accountshandler func()) {
 	for {
 		select {
+		case <-client.accountsCh:
+			accountshandler()
 		case state := <-client.connCh:
 			connhandler(state)
 		case bcast := <-client.session.BroadcastCh:
@@ -501,7 +513,9 @@
 		client.handleBroadcastNotification,
 		client.handleUnicastNotification,
 		client.handleErr,
-		client.handleUnregister)
+		client.handleUnregister,
+		client.handleAccountsChange,
+	)
 }
 
 func (client *PushClient) setupPushService() error {

=== modified file 'client/client_test.go'
--- client/client_test.go	2014-08-24 13:09:01 +0000
+++ client/client_test.go	2014-09-08 16:59:38 +0000
@@ -32,6 +32,7 @@
 
 	. "launchpad.net/gocheck"
 
+	"launchpad.net/ubuntu-push/accounts"
 	"launchpad.net/ubuntu-push/bus"
 	"launchpad.net/ubuntu-push/bus/networkmanager"
 	"launchpad.net/ubuntu-push/bus/systemimage"
@@ -994,6 +995,7 @@
 var nopUcast = func(session.AddressedNotification) error { return nil }
 var nopError = func(error) {}
 var nopUnregister = func(*click.AppId) {}
+var nopAcct = func() {}
 
 func (cs *clientSuite) TestDoLoopConn(c *C) {
 	cli := NewPushClient(cs.configPath, cs.leveldbPath)
@@ -1004,7 +1006,7 @@
 	c.Assert(cli.initSessionAndPoller(), IsNil)
 
 	ch := make(chan bool, 1)
-	go cli.doLoop(func(bool) { ch <- true }, nopBcast, nopUcast, nopError, nopUnregister)
+	go cli.doLoop(func(bool) { ch <- true }, nopBcast, nopUcast, nopError, nopUnregister, nopAcct)
 	c.Check(takeNextBool(ch), Equals, true)
 }
 
@@ -1017,7 +1019,7 @@
 	cli.session.BroadcastCh <- &session.BroadcastNotification{}
 
 	ch := make(chan bool, 1)
-	go cli.doLoop(nopConn, func(_ *session.BroadcastNotification) error { ch <- true; return nil }, nopUcast, nopError, nopUnregister)
+	go cli.doLoop(nopConn, func(_ *session.BroadcastNotification) error { ch <- true; return nil }, nopUcast, nopError, nopUnregister, nopAcct)
 	c.Check(takeNextBool(ch), Equals, true)
 }
 
@@ -1030,7 +1032,7 @@
 	cli.session.NotificationsCh <- session.AddressedNotification{}
 
 	ch := make(chan bool, 1)
-	go cli.doLoop(nopConn, nopBcast, func(session.AddressedNotification) error { ch <- true; return nil }, nopError, nopUnregister)
+	go cli.doLoop(nopConn, nopBcast, func(session.AddressedNotification) error { ch <- true; return nil }, nopError, nopUnregister, nopAcct)
 	c.Check(takeNextBool(ch), Equals, true)
 }
 
@@ -1043,7 +1045,7 @@
 	cli.session.ErrCh <- nil
 
 	ch := make(chan bool, 1)
-	go cli.doLoop(nopConn, nopBcast, nopUcast, func(error) { ch <- true }, nopUnregister)
+	go cli.doLoop(nopConn, nopBcast, nopUcast, func(error) { ch <- true }, nopUnregister, nopAcct)
 	c.Check(takeNextBool(ch), Equals, true)
 }
 
@@ -1056,7 +1058,21 @@
 	cli.unregisterCh <- app1
 
 	ch := make(chan bool, 1)
-	go cli.doLoop(nopConn, nopBcast, nopUcast, nopError, func(app *click.AppId) { c.Check(app.Original(), Equals, appId1); ch <- true })
+	go cli.doLoop(nopConn, nopBcast, nopUcast, nopError, func(app *click.AppId) { c.Check(app.Original(), Equals, appId1); ch <- true }, nopAcct)
+	c.Check(takeNextBool(ch), Equals, true)
+}
+
+func (cs *clientSuite) TestDoLoopAcct(c *C) {
+	cli := NewPushClient(cs.configPath, cs.leveldbPath)
+	cli.log = cs.log
+	cli.systemImageInfo = siInfoRes
+	c.Assert(cli.initSessionAndPoller(), IsNil)
+	acctCh := make(chan accounts.Changed, 1)
+	acctCh <- accounts.Changed{}
+	cli.accountsCh = acctCh
+
+	ch := make(chan bool, 1)
+	go cli.doLoop(nopConn, nopBcast, nopUcast, nopError, nopUnregister, func() { ch <- true })
 	c.Check(takeNextBool(ch), Equals, true)
 }
 

=== modified file 'debian/changelog'
--- debian/changelog	2014-09-02 17:28:19 +0000
+++ debian/changelog	2014-09-08 16:59:38 +0000
@@ -1,3 +1,16 @@
+ubuntu-push (0.64) UNRELEASED; urgency=medium
+
+  [ Roberto Alsina ]
+  * Remove tokens from debug output
+  * Doc updates
+  * Included example code in docs directory
+
+  [ John R. Lenton]
+  * Use libaccounts to track changes to the u1 account used for auth; restart the session on change.
+  * Set the MEDIA_PROP env var to select the right media role for notification sounds
+
+ -- Roberto Alsina <ralsina@yoga>  Mon, 08 Sep 2014 13:25:33 -0300
+
 ubuntu-push (0.63.2+14.10.20140902.1-0ubuntu1) utopic; urgency=medium
 
   [ Roberto Alsina ]

=== modified file 'debian/control'
--- debian/control	2014-08-21 19:48:06 +0000
+++ debian/control	2014-09-08 16:59:38 +0000
@@ -21,6 +21,7 @@
                libnih-dbus-dev,
                libclick-0.4-dev,
                liburl-dispatcher1-dev,
+               libaccounts-glib-dev,
                cmake,
                python3,
 Standards-Version: 3.9.5

=== modified file 'debian/ubuntu-push-client.conf'
--- debian/ubuntu-push-client.conf	2014-08-06 14:08:29 +0000
+++ debian/ubuntu-push-client.conf	2014-09-08 16:59:38 +0000
@@ -3,6 +3,10 @@
 start on started unity8
 stop on stopping unity8
 
+# set the media role for sounds to notifications' role
+env PULSE_PROP="media.role=alert"
+export PULSE_PROP
+
 exec /usr/lib/ubuntu-push-client/ubuntu-push-client
 respawn
 

=== added file 'docs/_common.txt'
--- docs/_common.txt	1970-01-01 00:00:00 +0000
+++ docs/_common.txt	2014-09-08 16:59:38 +0000
@@ -0,0 +1,186 @@
+Application Helpers
+-------------------
+
+The payload delivered to push-client will be passed onto a helper program that can modify it as needed before passing it onto
+the postal service (see `Helper Output Format <#helper-output-format>`__).
+
+The helper receives two arguments ``infile`` and ``outfile``. The message is delivered via ``infile`` and the transformed
+version is placed in ``outfile``.
+
+This is the simplest possible useful helper, which simply passes the message through unchanged::
+
+    #!/usr/bin/python3
+
+    import sys
+    f1, f2 = sys.argv[1:3]
+    open(f2, "w").write(open(f1).read())
+
+Helpers need to be added to the click package manifest::
+
+    {
+        "name": "com.ubuntu.developer.ralsina.hello",
+        "description": "description of hello",
+        "framework": "ubuntu-sdk-14.10-qml-dev2",
+        "architecture": "all",
+        "title": "hello",
+        "hooks": {
+            "hello": {
+                "apparmor": "hello.json",
+                "desktop": "hello.desktop"
+            },
+            "helloHelper": {
+                "apparmor": "helloHelper-apparmor.json",
+                "push-helper": "helloHelper.json"
+            }
+        },
+        "version": "0.2",
+        "maintainer": "Roberto Alsina <[e-mail]>"
+    }
+
+Here, we created a helloHelper entry in hooks that has an apparmor profile and an additional JSON file for the push-helper hook.
+
+helloHelper-apparmor.json must contain **only** the push-notification-client policy group::
+
+    {
+        "policy_groups": [
+            "push-notification-client"
+        ],
+        "policy_version": 1.2
+    }
+
+And helloHelper.json must have at least a exec key with the path to the helper executable relative to the json, and optionally
+an app_id key containing the short id of one of the apps in the package (in the format packagename_appname without a version).
+If the app_id is not specified, the helper will be used for all apps in the package::
+
+    {
+        "exec": "helloHelper",
+        "app_id": "com.ubuntu.developer.ralsina.hello_hello"
+    }
+
+.. note:: For deb packages, helpers should be installed into /usr/lib/ubuntu-push-client/legacy-helpers/ as part of the package.
+
+Helper Output Format
+--------------------
+
+Helpers output has two parts, the postal message (in the "message" key) and a notification to be presented to the user (in the "notification" key).
+
+.. note:: This format **will** change with future versions of the SDK and it **may** be incompatible.
+
+Here's a simple example::
+
+    {
+        "message": "foobar",
+        "notification": {
+            "tag": "foo",
+            "card": {
+                "summary": "yes",
+                "body": "hello",
+                "popup": true,
+                "persist": true,
+                "timestamp": 1407160197
+            }
+            "sound": "buzz.mp3",
+            "vibrate": {
+                "pattern": [200, 100],
+                "repeat": 2
+            }
+            "emblem-counter": {
+                "count": 12,
+                "visible": true
+            }
+        }
+    }
+
+The notification can contain a **tag** field, which can later be used by the `persistent notification management API. <#persistent-notification-management>`__
+
+:message: (optional) A JSON object that is passed as-is to the application via PopAll.
+:notification: (optional) Describes the user-facing notifications triggered by this push message.
+
+The notification can contain a **card**. A card describes a specific notification to be given to the user,
+and has the following fields:
+
+:summary: (required) a title. The card will not be presented if this is missing.
+:body: longer text, defaults to empty.
+:actions: If empty (the default), a bubble notification is non-clickable.
+          If you add a URL, then bubble notifications are clickable and launch that URL. One use for this is using a URL like
+          ``appid://com.ubuntu.developer.ralsina.hello/hello/current-user-version`` which will switch to the app or launch
+          it if it's not running. See `URLDispatcher <https://wiki.ubuntu.com/URLDispatcher>`__ for more information.
+
+:icon: An icon relating to the event being notified. Defaults to empty (no icon);
+       a secondary icon relating to the application will be shown as well, regardless of this field.
+:timestamp: Seconds since the unix epoch, only used for persist (for now). If zero or unset, defaults to current timestamp.
+:persist: Whether to show in notification centre; defaults to false
+:popup: Whether to show in a bubble. Users can disable this, and can easily miss them, so don't rely on it exclusively. Defaults to false.
+
+.. note:: Keep in mind that the precise way in which each field is presented to the user depends on factors such as
+          whether it's shown as a bubble or in the notification centre, or even the version of Ubuntu Touch the user
+          has on their device.
+
+The notification can contain a **sound** field. This is either a boolean (play a predetermined sound) or the path to a sound file. The user can disable it, so don't rely on it exclusively.
+Defaults to empty (no sound). The path is relative, and will be looked up in (a) the application's .local/share/<pkgname>, and (b)
+standard xdg dirs.
+
+The notification can contain a **vibrate** field, causing haptic feedback, which can be either a boolean (if true, vibrate a predetermined way) or an object that has the following content:
+
+:pattern: a list of integers describing a vibration pattern (duration of alternating vibration/no vibration times, in milliseconds).
+:repeat: number of times the pattern has to be repeated (defaults to 1, 0 is the same as 1).
+
+The notification can contain a **emblem-counter** field, with the following content:
+
+:count: a number to be displayed over the application's icon in the launcher.
+:visible: set to true to show the counter, or false to hide it.
+
+.. note:: Unlike other notifications, emblem-counter needs to be cleaned by the app itself.
+          Please see `the persistent notification management section. <#persistent-notification-management>`__
+
+.. FIXME crosslink to hello example app on each method
+
+Security
+~~~~~~~~
+
+To use the push API, applications need to request permission in their security profile, using something like this::
+
+    {
+        "policy_groups": [
+            "networking",
+            "push-notification-client"
+        ],
+        "policy_version": 1.2
+    }
+
+
+Ubuntu Push Server API
+----------------------
+
+The Ubuntu Push server is located at https://push.ubuntu.com and has a single endpoint: ``/notify``.
+To notify a user, your application has to do a POST with ``Content-type: application/json``.
+
+.. note:: The contents of the data field are arbitrary. They should be enough for your helper to build
+          a notification using it, and decide whether it should be displayed or not. Keep in mind
+          that this will be processed by more than one version of the helper, because the user may be using
+          an older version of your app.
+
+Here is an example of the POST body using all the fields::
+
+    {
+        "appid": "com.ubuntu.music_music",
+        "expire_on": "2014-10-08T14:48:00.000Z",
+        "token": "LeA4tRQG9hhEkuhngdouoA==",
+        "clear_pending": true,
+        "replace_tag": "tagname",
+        "data": {
+            "id": 43578,
+            "timestamp": 1409583746,
+            "serial": 1254,
+            "sender": "Joe",
+            "snippet": "Hi there!"
+        }
+    }
+
+
+:appid: ID of the application that will receive the notification, as described in the client side documentation.
+:expire_on: Expiration date/time for this message, in `ISO8601 Extendend format <http://en.wikipedia.org/wiki/ISO_8601>`__
+:token: The token identifying the user+device to which the message is directed, as described in the client side documentation.
+:clear_pending: Discards all previous pending notifications. Usually in response to getting a "too-many-pending" error.
+:replace_tag: If there's a pending notification with the same tag, delete it before queuing this new one.
+:data: A JSON object.

=== added file 'docs/_description.txt'
--- docs/_description.txt	1970-01-01 00:00:00 +0000
+++ docs/_description.txt	2014-09-08 16:59:38 +0000
@@ -0,0 +1,46 @@
+Let's describe the push system by way of an example.
+
+Alice has written a chat application called Chatter. Using it, Bob can send messages to Carol and viceversa. Alice has a
+web application for it, so the way it works now is that Bob connects to the service, posts a message, and when Carol
+connects, she gets it. If Carol leaves the browser window open, it beeps when messages arrive.
+
+Now Alice wants to create an Ubuntu Touch app for Chatter, so she implements the same architecture using a client that
+does the same thing as the web browser. Sadly, since applications on Ubuntu Touch don't run continuously, messages are
+only delivered when Carol opens the app, and the user experience suffers.
+
+Using the Ubuntu Push Server, this problem is alleviated: the Chatter server will deliver the messages to the Ubuntu
+Push Server, which in turn will send it in an efficient manner to the Ubuntu Push Client running in Bob and Carol's
+devices. The user sees a notification (all without starting the app) and then can launch it if he's interested in
+reading messages at that point.
+
+Since the app is not started and messages are delivered oportunistically, this is both battery and bandwidth-efficient.
+
+.. figure:: push.svg
+
+The Ubuntu Push system provides:
+
+* A push server which receives **push messages** from the app servers, queues them and delivers them efficiently
+  to the devices.
+* A push client which receives those messages, queues messages to the app and displays notifications to the user
+
+The full lifecycle of a push message is:
+
+* Created in a application-specific server
+* Sent to the Ubuntu Push server, targeted at a user or user+device pair
+* Delivered to one or more Ubuntu devices
+* Passed through the application helper for processing
+* Notification displayed to the user (via different mechanisms)
+* Application Message queued for the app's use
+
+If the user interacts with the notification, the application is launched and should check its queue for messages
+it has to process.
+
+For the app developer, there are several components needed:
+
+* A server that sends the **push messages** to the Ubuntu Push server
+* Support in the client app for registering with the Ubuntu Push client
+* Support in the client app to react to **notifications** displayed to the user and process **application messages**
+* A helper program with application-specific knowledge that transforms **push messages** as needed.
+
+In the following sections, we'll see how to implement all the client side parts. For the application server, see the
+`Ubuntu Push Server API section <#ubuntu-push-server-api>`__

=== added directory 'docs/example-client'
=== added file 'docs/example-client/.excludes'
=== added file 'docs/example-client/Makefile'
--- docs/example-client/Makefile	1970-01-01 00:00:00 +0000
+++ docs/example-client/Makefile	2014-09-08 16:59:38 +0000
@@ -0,0 +1,22 @@
+# More information: https://wiki.ubuntu.com/Touch/Testing
+#
+# Notes for autopilot tests:
+# -----------------------------------------------------------
+# In order to run autopilot tests:
+# sudo apt-add-repository ppa:autopilot/ppa
+# sudo apt-get update
+# sudo apt-get install python-autopilot autopilot-qt
+#############################################################
+
+all:
+
+autopilot:
+	chmod +x tests/autopilot/run
+	tests/autopilot/run
+
+check:
+	qmltestrunner -input tests/unit
+
+run:
+	/usr/bin/qmlscene $@ push-example.qml
+

=== added file 'docs/example-client/README'
--- docs/example-client/README	1970-01-01 00:00:00 +0000
+++ docs/example-client/README	2014-09-08 16:59:38 +0000
@@ -0,0 +1,28 @@
+Example App for the QML notifications API. This is an example application
+showing how to use push notifications in Ubuntu Touch devices.
+
+= Running on Ubuntu Touch =
+
+Since push is currently only meant for Ubuntu Touch devices, this is meant
+to be used in the emulator or on a real device.
+
+* Open the example project in Ubuntu-SDK
+* Build a click file
+* Run in the emulator or device
+
+= Running on the desktop =
+
+This is more complicated but may be convenient while experimenting:
+
+* Install qtdeclarative5-ubuntu-push-notifications-plugin
+* Install ubuntu-push-client
+* Run ubuntu-push-client in trivial helper mode:
+
+	UBUNTU_PUSH_USE_TRIVIAL_HELPER=1 ./ubuntu-push-client
+
+* Build click package
+* Install in your desktop:
+
+	sudo click install --all-users com.ubuntu.developer.push.ubuntu-push-example_0.1_all.click
+
+* Run example app from the SDK using the "Desktop" kit

=== added directory 'docs/example-client/components'
=== added file 'docs/example-client/components/ChatClient.qml'
--- docs/example-client/components/ChatClient.qml	1970-01-01 00:00:00 +0000
+++ docs/example-client/components/ChatClient.qml	2014-09-08 16:59:38 +0000
@@ -0,0 +1,99 @@
+import QtQuick 2.0
+import Ubuntu.Components 0.1
+
+Item {
+    property string nick
+    property string token
+    property bool registered: false
+    signal error (string msg)
+    onNickChanged: {
+        if (nick) {
+            register()
+        } else {
+            registered = false
+        }
+    }
+    onTokenChanged: {register()}
+    function register() {
+        console.log("registering ", nick, token);
+        if (nick && token) {
+            var req = new XMLHttpRequest();
+            req.open("post", "http://direct.ralsina.me:8001/register", true);
+            req.setRequestHeader("Content-type", "application/json");
+            req.onreadystatechange = function() {//Call a function when the state changes.
+                if(req.readyState == 4) {
+                    if (req.status == 200) {
+                        registered = true;
+                    } else {
+                        error(JSON.parse(req.responseText)["error"]);
+                    }
+                }
+            }
+            req.send(JSON.stringify({
+                "nick" : nick.toLowerCase(),
+                "token": token
+            }))
+        }
+    }
+
+    /* options is of the form:
+      {
+          enabled: false,
+          persist: false,
+          popup: false,
+          sound: "buzz.mp3",
+          vibrate: false,
+          counter: 5
+      }
+    */
+    function sendMessage(message, options) {
+        var to_nick = message["to"]
+        var data = {
+            "from_nick": nick.toLowerCase(),
+            "from_token": token,
+            "nick": to_nick.toLowerCase(),
+            "data": {
+                "message": message,
+                "notification": {}
+            }
+        }
+        if (options["enabled"]) {
+            data["data"]["notification"] = {
+                "card": {
+                    "summary": nick + " says: " + message["message"],
+                    "body": "",
+                    "popup": options["popup"],
+                    "persist": options["persist"],
+                    "actions": ["appid://com.ubuntu.developer.ralsina.hello/hello/current-user-version"]
+                }
+            }
+            if (options["sound"]) {
+                data["data"]["notification"]["sound"] = options["sound"]
+            }
+            if (options["vibrate"]) {
+                data["data"]["notification"]["vibrate"] = {
+                    "duration": 200
+                }
+            }
+            if (options["counter"]) {
+                data["data"]["notification"]["emblem-counter"] = {
+                    "count": Math.floor(options["counter"]),
+                    "visible": true
+                }
+            }
+        }
+        var req = new XMLHttpRequest();
+        req.open("post", "http://direct.ralsina.me:8001/message", true);
+        req.setRequestHeader("Content-type", "application/json");
+        req.onreadystatechange = function() {//Call a function when the state changes.
+            if(req.readyState == 4) {
+                if (req.status == 200) {
+                    registered = true;
+                } else {
+                    error(JSON.parse(req.responseText)["error"]);
+                }
+            }
+        }
+        req.send(JSON.stringify(data))
+    }
+}

=== added file 'docs/example-client/hello.desktop'
--- docs/example-client/hello.desktop	1970-01-01 00:00:00 +0000
+++ docs/example-client/hello.desktop	2014-09-08 16:59:38 +0000
@@ -0,0 +1,8 @@
+[Desktop Entry]
+Name=hello
+Exec=qmlscene $@ main.qml
+Icon=push-example.png
+Terminal=false
+Type=Application
+X-Ubuntu-Touch=true
+

=== added file 'docs/example-client/hello.json'
--- docs/example-client/hello.json	1970-01-01 00:00:00 +0000
+++ docs/example-client/hello.json	2014-09-08 16:59:38 +0000
@@ -0,0 +1,7 @@
+{
+    "policy_groups": [
+        "networking",
+        "push-notification-client"
+    ],
+    "policy_version": 1.2
+}
\ No newline at end of file

=== added file 'docs/example-client/helloHelper'
--- docs/example-client/helloHelper	1970-01-01 00:00:00 +0000
+++ docs/example-client/helloHelper	2014-09-08 16:59:38 +0000
@@ -0,0 +1,7 @@
+#!/usr/bin/python3
+
+import sys
+
+f1, f2 = sys.argv[1:3]
+
+open(f2, "w").write(open(f1).read())

=== added file 'docs/example-client/helloHelper-apparmor.json'
--- docs/example-client/helloHelper-apparmor.json	1970-01-01 00:00:00 +0000
+++ docs/example-client/helloHelper-apparmor.json	2014-09-08 16:59:38 +0000
@@ -0,0 +1,6 @@
+{
+    "policy_groups": [
+        "push-notification-client"
+    ],
+    "policy_version": 1.2
+}

=== added file 'docs/example-client/helloHelper.json'
--- docs/example-client/helloHelper.json	1970-01-01 00:00:00 +0000
+++ docs/example-client/helloHelper.json	2014-09-08 16:59:38 +0000
@@ -0,0 +1,3 @@
+{
+    "exec": "helloHelper"
+}

=== added file 'docs/example-client/main.qml'
--- docs/example-client/main.qml	1970-01-01 00:00:00 +0000
+++ docs/example-client/main.qml	2014-09-08 16:59:38 +0000
@@ -0,0 +1,266 @@
+import QtQuick 2.0
+import Qt.labs.settings 1.0
+import Ubuntu.Components 0.1
+import Ubuntu.Components.ListItems 0.1 as ListItem
+import Ubuntu.PushNotifications 0.1
+import "components"
+
+MainView {
+    id: "mainView"
+    // objectName for functional testing purposes (autopilot-qt5)
+    objectName: "mainView"
+
+    // Note! applicationName needs to match the "name" field of the click manifest
+    applicationName: "com.ubuntu.developer.ralsina.hello"
+
+    automaticOrientation: true
+    useDeprecatedToolbar: false
+
+    width: units.gu(100)
+    height: units.gu(75)
+
+    Settings {
+        property alias nick: chatClient.nick
+        property alias nickText: nickEdit.text
+        property alias nickPlaceholder: nickEdit.placeholderText
+        property alias nickEnabled: nickEdit.enabled
+    }
+
+    ChatClient {
+        id: chatClient
+        onRegisteredChanged: {nickEdit.registered()}
+        onError: {messageList.handle_error(msg)}
+        token: pushClient.token
+    }
+
+    PushClient {
+        id: pushClient
+        Component.onCompleted: {
+            notificationsChanged.connect(messageList.handle_notifications)
+            error.connect(messageList.handle_error)
+        }
+        appId: "com.ubuntu.developer.ralsina.hello_hello"
+    }
+
+    TextField {
+        id: nickEdit
+        focus: true
+        placeholderText: "Your nickname"
+        anchors.left: parent.left
+        anchors.right: loginButton.left
+        anchors.top: parent.top
+        anchors.leftMargin: units.gu(.5)
+        anchors.rightMargin: units.gu(1)
+        anchors.topMargin: units.gu(.5)
+        function registered() {
+            readOnly = true
+            text = "Your nick is " + chatClient.nick
+            messageEdit.focus = true
+            messageEdit.enabled = true
+            loginButton.text = "Logout"
+        }
+        onAccepted: { loginButton.clicked() }
+    }
+
+    Button {
+        id: loginButton
+        text: chatClient.rgistered? "Logout": "Login"
+        anchors.top: nickEdit.top
+        anchors.right: parent.right
+        anchors.rightMargin: units.gu(.5)
+        onClicked: {
+            if (chatClient.nick) { // logout
+                chatClient.nick = ""
+                text = "Login"
+                nickEdit.enabled = true
+                nickEdit.readOnly = false
+                nickEdit.text = ""
+                nickEdit.focus = true
+                messageEdit.enabled = false
+            } else { // login
+                chatClient.nick = nickEdit.text
+            }
+        }
+    }
+
+    TextField {
+        id: messageEdit
+        anchors.right: parent.right
+        anchors.left: parent.left
+        anchors.top: nickEdit.bottom
+        anchors.topMargin: units.gu(1)
+        anchors.rightMargin: units.gu(.5)
+        anchors.leftMargin: units.gu(.5)
+        placeholderText: "Your message"
+        enabled: false
+        onAccepted: {
+            console.log("sending " + text)
+            var idx = text.indexOf(":")
+            var nick_to = text.substring(0, idx).trim()
+            var msg = text.substring(idx+1, 9999).trim()
+            var i = {
+                "from" :  chatClient.nick,
+                "to" :  nick_to,
+                "message" : msg
+            }
+            var o = {
+                enabled: annoyingSwitch.checked,
+                persist: persistSwitch.checked,
+                popup: popupSwitch.checked,
+                sound: soundSwitch.checked,
+                vibrate: vibrateSwitch.checked,
+                counter: counterSlider.value
+            }
+            chatClient.sendMessage(i, o)
+            i["type"] = "sent"
+            messagesModel.insert(0, i)
+            text = ""
+        }
+    }
+    ListModel {
+        id: messagesModel
+        ListElement {
+            from: ""
+            to: ""
+            type: "info"
+            message: "Register by typing your nick and clicking Login."
+        }
+        ListElement {
+            from: ""
+            to: ""
+            type: "info"
+            message: "Send messages in the form \"destination: hello\""
+        }
+        ListElement {
+            from: ""
+            to: ""
+            type: "info"
+            message: "Slide from the bottom to control notification behaviour."
+        }
+    }
+
+    UbuntuShape {
+        anchors.left: parent.left
+        anchors.right: parent.right
+        anchors.bottom: notificationSettings.bottom
+        anchors.top: messageEdit.bottom
+        anchors.topMargin: units.gu(1)
+        ListView {
+            id: messageList
+            model: messagesModel
+            anchors.fill: parent
+            delegate: Rectangle {
+                MouseArea {
+                    anchors.fill: parent
+                    onClicked: {
+                        if (from != "") {
+                            messageEdit.text = from + ": "
+                            messageEdit.focus = true
+                        }
+                    }
+                }
+                height: label.height + units.gu(2)
+                width: parent.width
+                Rectangle {
+                    color: {
+                        "info": "#B5EBB9",
+                        "received" : "#A2CFA5",
+                        "sent" : "#FFF9C8",
+                        "error" : "#FF4867"}[type]
+                    height: label.height + units.gu(1)
+                    anchors.fill: parent
+                    radius: 5
+                    anchors.margins: units.gu(.5)
+                    Text {
+                        id: label
+                        text: "<b>" + ((type=="sent")?to:from) + ":</b> " + message
+                        wrapMode: Text.Wrap
+                        width: parent.width - units.gu(1)
+                        x: units.gu(.5)
+                        y: units.gu(.5)
+                        horizontalAlignment: (type=="sent")?Text.AlignRight:Text.AlignLeft
+                    }
+                }
+            }
+
+            function handle_error(error) {
+                messagesModel.insert(0, {
+                     "from" :  "",
+                     "to" :  "",
+                     "type" :  "error",
+                     "message" : "<b>ERROR: " + error + "</b>"
+                })
+            }
+
+            function handle_notifications(list) {
+                list.forEach(function(notification) {
+                    var item = JSON.parse(notification)
+                    item["type"] = "received"
+                    messagesModel.insert(0, item)
+                })
+            }
+        }
+    }
+    Panel {
+        id: notificationSettings
+        anchors {
+            left: parent.left
+            right: parent.right
+            bottom: parent.bottom
+        }
+        height: item1.height * 7
+        UbuntuShape {
+            anchors.fill: parent
+            color: Theme.palette.normal.overlay
+            Column {
+                id: settingsColumn
+                anchors.fill: parent
+                ListItem.Header {
+                    text: "<b>Notification Settings</b>"
+                }
+                ListItem.Standard {
+                    id: item1
+                    text: "Enable Notifications"
+                    control: Switch {
+                        id: annoyingSwitch
+                    }
+                }
+                ListItem.Standard {
+                    text: "Enable Popup"
+                    enabled: annoyingSwitch.checked
+                    control: Switch {
+                        id: popupSwitch
+                    }
+                }
+                ListItem.Standard {
+                    text: "Persistent"
+                    enabled: annoyingSwitch.checked
+                    control: Switch {
+                        id: persistSwitch
+                    }
+                }
+                ListItem.Standard {
+                    text: "Make Sound"
+                    enabled: annoyingSwitch.checked
+                    control: Switch {
+                        id: soundSwitch
+                    }
+                }
+                ListItem.Standard {
+                    text: "Vibrate"
+                    enabled: annoyingSwitch.checked
+                    control: Switch {
+                        id: vibrateSwitch
+                    }
+                }
+                ListItem.Standard {
+                    text: "Counter Value"
+                    enabled: annoyingSwitch.checked
+                    control: Slider {
+                        id: counterSlider
+                    }
+                }
+            }
+        }
+    }
+}

=== added file 'docs/example-client/manifest.json'
--- docs/example-client/manifest.json	1970-01-01 00:00:00 +0000
+++ docs/example-client/manifest.json	2014-09-08 16:59:38 +0000
@@ -0,0 +1,19 @@
+{
+    "architecture": "all",
+    "description": "Example app for Ubuntu push notifications.",
+    "framework": "ubuntu-sdk-14.10-dev2",
+    "hooks": {
+        "hello": {
+            "apparmor": "hello.json",
+            "desktop": "hello.desktop"
+        },
+        "helloHelper": {
+            "apparmor": "helloHelper-apparmor.json",
+            "push-helper": "helloHelper.json"
+        }
+    },
+    "maintainer": "Roberto Alsina <[e-mail]>",
+    "name": "com.ubuntu.developer.ralsina.hello",
+    "title": "ubuntu-push-example",
+    "version": "0.4"
+}

=== added file 'docs/example-client/push-example.png'
Binary files docs/example-client/push-example.png	1970-01-01 00:00:00 +0000 and docs/example-client/push-example.png	2014-09-08 16:59:38 +0000 differ
=== added file 'docs/example-client/push-example.qmlproject'
--- docs/example-client/push-example.qmlproject	1970-01-01 00:00:00 +0000
+++ docs/example-client/push-example.qmlproject	2014-09-08 16:59:38 +0000
@@ -0,0 +1,52 @@
+import QmlProject 1.1
+
+Project {
+    mainFile: "main.qml"
+
+    /* Include .qml, .js, and image files from current directory and subdirectories */
+    QmlFiles {
+        directory: "."
+    }
+    JavaScriptFiles {
+        directory: "."
+    }
+    ImageFiles {
+        directory: "."
+    }
+    Files {
+        filter: "*.desktop"
+    }
+    Files {
+        filter: "www/*.html"
+    }
+    Files {
+        filter: "Makefile"
+    }
+    Files {
+        directory: "www"
+        filter: "*"
+    }
+    Files {
+        directory: "www/img/"
+        filter: "*"
+    }
+    Files {
+        directory: "www/css/"
+        filter: "*"
+    }
+    Files {
+        directory: "www/js/"
+        filter: "*"
+    }
+    Files {
+        directory: "tests/"
+        filter: "*"
+    }
+    Files {
+        directory: "debian"
+        filter: "*"
+    }
+    /* List of plugin directories passed to QML runtime */
+    importPaths: [ "." ,"/usr/bin","/usr/lib/x86_64-linux-gnu/qt5/qml" ]
+}
+

=== added directory 'docs/example-client/tests'
=== added directory 'docs/example-client/tests/autopilot'
=== added directory 'docs/example-client/tests/autopilot/push-example'
=== added file 'docs/example-client/tests/autopilot/push-example/__init__.py'
--- docs/example-client/tests/autopilot/push-example/__init__.py	1970-01-01 00:00:00 +0000
+++ docs/example-client/tests/autopilot/push-example/__init__.py	2014-09-08 16:59:38 +0000
@@ -0,0 +1,72 @@
+# -*- Mode: Python; coding: utf-8; indent-tabs-mode: nil; tab-width: 4 -*-
+
+"""Ubuntu Touch App autopilot tests."""
+
+import os
+import subprocess
+
+from autopilot import input, platform
+from autopilot.matchers import Eventually
+from testtools.matchers import Equals
+from ubuntuuitoolkit import base, emulators
+
+
+def _get_module_include_path():
+    return os.path.join(get_path_to_source_root(), 'modules')
+
+
+def get_path_to_source_root():
+    return os.path.abspath(
+        os.path.join(
+            os.path.dirname(__file__), '..', '..', '..', '..'))
+
+
+class ClickAppTestCase(base.UbuntuUIToolkitAppTestCase):
+    """Common test case that provides several useful methods for the tests."""
+
+    package_id = ''  # TODO
+    app_name = 'push-example'
+
+    def setUp(self):
+        super(ClickAppTestCase, self).setUp()
+        self.pointing_device = input.Pointer(self.input_device_class.create())
+        self.launch_application()
+
+        self.assertThat(self.main_view.visible, Eventually(Equals(True)))
+
+    def launch_application(self):
+        if platform.model() == 'Desktop':
+            self._launch_application_from_desktop()
+        else:
+            self._launch_application_from_phablet()
+
+    def _launch_application_from_desktop(self):
+        app_qml_source_location = self._get_app_qml_source_path()
+        if os.path.exists(app_qml_source_location):
+            self.app = self.launch_test_application(
+                base.get_qmlscene_launch_command(),
+                '-I' + _get_module_include_path(),
+                app_qml_source_location,
+                app_type='qt',
+                emulator_base=emulators.UbuntuUIToolkitEmulatorBase)
+        else:
+            raise NotImplementedError(
+                "On desktop we can't install click packages yet, so we can "
+                "only run from source.")
+
+    def _get_app_qml_source_path(self):
+        qml_file_name = '{0}.qml'.format(self.app_name)
+        return os.path.join(self._get_path_to_app_source(), qml_file_name)
+
+    def _get_path_to_app_source(self):
+        return os.path.join(get_path_to_source_root(), self.app_name)
+
+    def _launch_application_from_phablet(self):
+        # On phablet, we only run the tests against the installed click
+        # package.
+        self.app = self.launch_click_package(self.pacakge_id, self.app_name)
+
+    @property
+    def main_view(self):
+        return self.app.select_single(emulators.MainView)
+

=== added file 'docs/example-client/tests/autopilot/push-example/test_main.py'
--- docs/example-client/tests/autopilot/push-example/test_main.py	1970-01-01 00:00:00 +0000
+++ docs/example-client/tests/autopilot/push-example/test_main.py	2014-09-08 16:59:38 +0000
@@ -0,0 +1,25 @@
+# -*- Mode: Python; coding: utf-8; indent-tabs-mode: nil; tab-width: 4 -*-
+
+"""Tests for the Hello World"""
+
+import os
+
+from autopilot.matchers import Eventually
+from testtools.matchers import Equals
+
+import push-example
+
+
+class MainViewTestCase(push-example.ClickAppTestCase):
+    """Generic tests for the Hello World"""
+
+    def test_initial_label(self):
+        label = self.main_view.select_single(objectName='label')
+        self.assertThat(label.text, Equals('Hello..'))
+
+    def test_click_button_should_update_label(self):
+        button = self.main_view.select_single(objectName='button')
+        self.pointing_device.click_object(button)
+        label = self.main_view.select_single(objectName='label')
+        self.assertThat(label.text, Eventually(Equals('..world!')))
+

=== added file 'docs/example-client/tests/autopilot/run'
--- docs/example-client/tests/autopilot/run	1970-01-01 00:00:00 +0000
+++ docs/example-client/tests/autopilot/run	2014-09-08 16:59:38 +0000
@@ -0,0 +1,12 @@
+#!/bin/bash
+
+if [[ -z `which autopilot` ]]; then
+  echo "Autopilot is not installed. Skip"
+  exit
+fi
+
+SCRIPTPATH=`dirname $0`
+pushd ${SCRIPTPATH}
+autopilot run push-example
+popd
+

=== added directory 'docs/example-client/tests/unit'
=== added file 'docs/example-client/tests/unit/tst_hellocomponent.qml'
--- docs/example-client/tests/unit/tst_hellocomponent.qml	1970-01-01 00:00:00 +0000
+++ docs/example-client/tests/unit/tst_hellocomponent.qml	2014-09-08 16:59:38 +0000
@@ -0,0 +1,50 @@
+import QtQuick 2.0
+import QtTest 1.0
+import Ubuntu.Components 0.1
+import "../../components"
+
+// See more details @ http://qt-project.org/doc/qt-5.0/qtquick/qml-testcase.html
+
+// Execute tests with:
+//   qmltestrunner
+
+Item {
+    // The objects
+    HelloComponent {
+        id: objectUnderTest
+    }
+
+    TestCase {
+        name: "HelloComponent"
+
+        function init() {
+            console.debug(">> init");
+            compare("",objectUnderTest.text,"text was not empty on init");
+            console.debug("<< init");
+        }
+
+        function cleanup() {
+            console.debug(">> cleanup");
+            console.debug("<< cleanup");
+        }
+
+        function initTestCase() {
+            console.debug(">> initTestCase");
+            console.debug("<< initTestCase");
+        }
+
+        function cleanupTestCase() {
+            console.debug(">> cleanupTestCase");
+            console.debug("<< cleanupTestCase");
+        }
+
+        function test_canReadAndWriteText() {
+            var expected = "Hello World";
+
+            objectUnderTest.text = expected;
+
+            compare(expected,objectUnderTest.text,"expected did not equal result");
+        }
+    }
+}
+

=== added directory 'docs/example-server'
=== added file 'docs/example-server/.bzrignore'
--- docs/example-server/.bzrignore	1970-01-01 00:00:00 +0000
+++ docs/example-server/.bzrignore	2014-09-08 16:59:38 +0000
@@ -0,0 +1,1 @@
+.git

=== added file 'docs/example-server/.gitignore'
--- docs/example-server/.gitignore	1970-01-01 00:00:00 +0000
+++ docs/example-server/.gitignore	2014-09-08 16:59:38 +0000
@@ -0,0 +1,3 @@
+.bzr
+.bzrignore
+node_modules

=== added file 'docs/example-server/app.js'
--- docs/example-server/app.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/app.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,212 @@
+var express = require('express')
+  , bodyParser = require('body-parser')
+
+var Registry = require('./lib/registry')
+  , Inbox = require('./lib/inbox')
+  , Notifier = require('./lib/notifier')
+
+function wire(db, cfg) {
+    var reg, inbox, notifier, app
+
+    // control whether not to have persistent inboxes
+    var no_inbox = cfg.no_inbox
+
+    app = express()
+
+    reg = new Registry(db)
+    if (!no_inbox) {
+        inbox = new Inbox(db)
+    } else {
+        inbox = null
+    }
+    var push_url = process.env.PUSH_URL || cfg.push_url
+    notifier = new Notifier(push_url, cfg)
+    notifier.on('unknownToken', function(nick, token) {
+        reg.removeToken(nick, token, function() {},
+                        function(err) {
+                            app.emit('mongoError', err)
+                        })
+    })
+    notifier.on('pushError', function(err, resp, body) {
+        app.emit('pushError', err, resp, body)
+    })
+
+    function unavailable(resp, err) {
+        app.emit('mongoError', err)
+        var ctype = resp.get('Content-Type')
+        if (ctype&&ctype.substr(0,10) == 'text/plain') {
+            resp.send(503, "db is hopefully only momentarily :(\n")
+        } else {
+            resp.json(503, {error: "unavailable"})
+        }
+    }
+
+    app.get("/_check", function(req, resp) {
+        db.command({ping: 1}, function(err, res) {
+            if(!err) {
+                resp.json({ok: true})
+            } else {
+                unavailable(resp, err)
+            }
+        })
+    })
+
+    app.use(bodyParser.json())
+    app.use('/play-notify-form', bodyParser.urlencoded({extended: false}))
+    app.use(function(err, req, resp, next) {
+        resp.json(err.status, {error: "invalid", message: err.message})
+    })
+
+    app.get("/", function(req, resp) {
+        if (!cfg.play_notify_form) {
+            resp.sendfile(__dirname + '/index.html')
+        } else {
+            resp.sendfile(__dirname + '/notify-form.html')
+        }
+    })
+
+    // NB: simplified, minimal identity and auth piggybacking on push tokens
+
+    /*
+      POST /register let's register a pair nick, token taking a JSON obj:
+      { "nick": string, "token": token-string }
+    */
+    app.post("/register", function(req, resp) {
+        if(typeof(req.body.token) != "string" ||
+           typeof(req.body.nick) != "string" ||
+           req.body.token == "" || req.body.nick == "") {
+            resp.json(400, {"error": "invalid"})
+            return
+        }
+        reg.insertToken(req.body.nick, req.body.token, function() {
+            resp.json({ok: true})
+        }, function() {
+            resp.json(400, {"error": "dup"})
+        }, function(err) {
+            unavailable(resp, err)
+        })
+    })
+
+    function checkToken(nick, token, okCb, resp) {
+        function bad() {
+            resp.json(401, {error: "unauthorized"})
+        }
+        reg.findToken(nick, function(nickToken) {
+            if (nickToken == token) {
+                okCb()
+                return
+            }
+            bad()
+        }, bad, function(err) {
+            unavailable(resp, err)
+        })
+    }
+
+    /* doNotify
+
+       ephemeral is true: message not put in the inbox, _ephemeral flag added
+
+       ephemeral is false: message put in inbox, with added unix _timestamp and
+       increasing _serial
+
+     */
+    function doNotify(ephemeral, nick, data, okCb, unknownNickCb, resp) {
+        function notify(token, data) {
+            notifier.notify(nick, token, data)
+            okCb()
+        }
+        reg.findToken(nick, function(token) {
+            if (ephemeral||no_inbox) {
+                data._ephemeral = Date.now()
+                notify(token, data)
+            } else {
+                inbox.pushMessage(token, data, function(msg) {
+                    notify(token, msg)
+                }, function(err) {
+                    unavailable(resp, err)
+                })
+            }
+        }, function() { // not found
+            unknownNickCb()
+        }, function(err) {
+            unavailable(resp, err)
+        })
+    }
+
+    /*
+      POST /message let's send a message to nick taking a JSON obj:
+      { "nick": string, "data": data,  "from_nick": string, "from_token": string}
+    */
+    app.post("/message", function(req, resp) {
+        if (!req.body.data||!req.body.nick||!req.body.from_token||!req.body.from_nick) {
+            resp.json(400, {"error": "invalid"})
+            return
+        }
+        checkToken(req.body.from_nick, req.body.from_token, function() {
+            var data = req.body.data
+            data._from = req.body.from_nick
+            doNotify(false, req.body.nick, data, function() {
+                resp.json({ok: true})
+            }, function() { // not found
+                resp.json(400, {"error": "unknown-nick"})
+            }, resp)
+        }, resp)
+    })
+
+    if (!no_inbox) { // /drain supported only if no_inbox false
+        /*
+          POST /drain let's get pending messages for nick+token:
+          it removes messages older than timestamp and return newer ones
+          { "nick": string, "token": string, "timestamp": unix-timestamp }
+        */
+        app.post("/drain", function(req, resp) {
+            if(!req.body.token||!req.body.nick||
+               typeof(req.body.timestamp) != "number") {
+                resp.json(400, {"error": "invalid"})
+                return
+            }
+            checkToken(req.body.nick, req.body.token, function() {
+                inbox.drain(req.body.token, req.body.timestamp, function(msgs) {
+                    resp.json(200, {ok: true, msgs: msgs})
+                }, function(err) {
+                    unavailable(resp, err)
+                })
+            }, resp)
+        })
+    }
+
+    /*
+      Form /play-notify-form
+      messages sent through the form are ephemeral, just transmitted through PN,
+      without being pushed into the inbox
+    */
+    if (cfg.play_notify_form) {
+        app.post("/play-notify-form", function(req, resp) {
+            resp.type('text/plain')
+            if (!req.body.data||!req.body.nick) {
+                resp.send(400, "invalid/empty fields\n")
+                return
+            }
+            var data
+            try {
+                data = JSON.parse(req.body.data)
+            } catch(e) {
+                resp.send(400, "data is not JSON\n")
+                return
+            }
+            doNotify(true, req.body.nick, data, function() {
+                resp.send(200, 'OK\n')
+            }, function() { // not found
+                resp.send(400, "unknown nick\n")
+            }, resp)
+        })
+    }
+
+    // for testing
+    app.set('_reg', reg)
+    app.set('_inbox', inbox)
+    app.set('_notifier', notifier)
+    return app
+}
+
+exports.wire = wire

=== added directory 'docs/example-server/config'
=== added file 'docs/example-server/config/config.js'
--- docs/example-server/config/config.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/config/config.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,15 @@
+module.exports = config = {
+    "name" : "pushAppServer"
+    ,"app_id" : "appEx"
+    ,"listen_port" : 8000
+    ,"mongo_host" : "localhost"
+    ,"mongo_port" : 27017
+    ,"mongo_opts" : {}
+    ,"push_url": "https://push.ubuntu.com"
+    ,"retry_batch": 5
+    ,"retry_secs" : 30
+    ,"happy_retry_secs": 5
+    ,"expire_mins": 120
+    ,"no_inbox": true
+    ,"play_notify_form": false
+}

=== added file 'docs/example-server/index.html'
--- docs/example-server/index.html	1970-01-01 00:00:00 +0000
+++ docs/example-server/index.html	2014-09-08 16:59:38 +0000
@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+<head>
+<title>pushAppServer</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+</head>
+<body>
+<h1>Push Notifications Application Server Example</h1>
+</html>

=== added directory 'docs/example-server/lib'
=== added file 'docs/example-server/lib/inbox.js'
--- docs/example-server/lib/inbox.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/lib/inbox.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,47 @@
+/* token -> token inbox */
+
+function Inbox(db) {
+    this.db = db
+}
+
+Inbox.prototype.pushMessage = function(token, msg, doneCb, errCb) {
+    if (!msg._timestamp) {
+        var now = Date.now()
+        msg._timestamp = now
+    }
+    this.db.collection('inbox').findAndModify({_id: token}, null, {
+        $push: {msgs: msg},
+        $inc: {serial: 1},
+    }, {upsert: true, new: true, fields: {serial: 1}}, function(err, doc) {
+        if (err) {
+            errCb(err)
+            return
+        }
+        msg._serial = doc.serial
+        doneCb(msg)
+    })
+}
+
+Inbox.prototype.drain = function(token, timestamp, doneCb, errCb) {
+    this.db.collection('inbox').findAndModify({_id: token}, null, {
+        $pull: {msgs: {_timestamp: {$lt: timestamp}}}
+    }, {new: true}, function(err, doc) {
+        if (err) {
+            errCb(err)
+            return
+        }
+        if (!doc) {
+            doneCb([])
+            return
+        }
+        var serial = doc.serial
+        var msgs = doc.msgs
+        for (var i = msgs.length-1; i >= 0; i--) {
+            msgs[i].serial = serial
+            serial--
+        }
+        doneCb(msgs)
+    })
+}
+
+module.exports = Inbox

=== added file 'docs/example-server/lib/notifier.js'
--- docs/example-server/lib/notifier.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/lib/notifier.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,89 @@
+/* Notifier sends notifications, with some retry support */
+
+var request = require('request')
+  , url = require('url')
+  , EventEmitter = require('events').EventEmitter
+  , util = require('util')
+
+
+function Notifier(baseURL, cfg) {
+    this.baseURL = baseURL
+    this.cfg = cfg
+    this._retrier = null
+    this._retryInterval = 0
+    this._q = []
+}
+
+util.inherits(Notifier, EventEmitter)
+
+Notifier.prototype._retry = function(nick, token, data, cb, expireOn) {
+    var self = this
+    self._q.push([nick, token, data, cb, expireOn])
+    if (!self._retrier || self._retryInterval == self.cfg.happy_retry_secs) {
+        clearTimeout(self._retrier)
+        self._retryInterval = self.cfg.retry_secs
+        self._retrier = setTimeout(function() { self._doRetry() }, 1000*self._retryInterval)
+    }
+}
+
+Notifier.prototype._doRetry = function() {
+    var self = this
+    self._retryInterval = 0
+    self._retrier = null
+    var i = 0
+    while (self._q.length > 0) {
+        var toRetry = self._q.shift()
+        if (new Date() > toRetry[4]) { // expired
+            continue
+        }
+        self.notify(toRetry[0], toRetry[1], toRetry[2], toRetry[3], toRetry[4])
+        i++
+        if (i >= self.cfg.retry_batch) {
+            break
+        }
+    }
+    if (self._q.length) {
+        self._retryInterval = self.cfg.happy_retry_secs
+        self._retrier = setTimeout(function() { self._doRetry() }, 1000*self._retryInterval)
+    }
+}
+
+Notifier.prototype.unknownToken = function(nick, token) {
+    this.emit('unknownToken', nick, token)
+}
+
+
+Notifier.prototype.pushError = function(err, resp, body) {
+    this.emit('pushError', err, resp, body)
+}
+
+Notifier.prototype.notify = function(nick, token, data, cb, expireOn) {
+    var self = this
+    if (!expireOn) {
+        expireOn = new Date
+        expireOn.setUTCMinutes(expireOn.getUTCMinutes() + self.cfg.expire_mins)
+    }
+    var unicast = {
+        'appid': self.cfg.app_id,
+        'expire_on': expireOn.toISOString(),
+        'token': token,
+        'data': data
+    }
+    request.post(url.resolve(self.baseURL, 'notify'), {json: unicast}, function(error, resp, body) {
+        if (!error) {
+            if (resp.statusCode == 200) {
+                if (cb) cb()
+                return
+            } else if (resp.statusCode > 500) {
+                self._retry(nick, token, data, cb, expireOn)
+                return
+            } else if (resp.statusCode == 400 && body.error == "unknown-token") {
+                self.unknownToken(nick, token)
+                return
+            }
+        }
+        self.pushError(error, resp, body)
+    })
+}
+
+module.exports = Notifier

=== added file 'docs/example-server/lib/registry.js'
--- docs/example-server/lib/registry.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/lib/registry.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,62 @@
+/* nick -> token registry */
+
+function Registry(db) {
+    this.db = db
+}
+
+Registry.prototype.findToken = function(nick, foundCb, notFoundCb, errCb) {
+    var self = this
+    self.db.collection('registry').findOne({_id: nick}, function(err, doc) {
+        if (err) {
+            errCb(err)
+            return
+        }
+        if (doc == null) {
+            notFoundCb()
+            return
+        }
+        foundCb(doc.token)
+    })
+}
+
+Registry.prototype.insertToken = function(nick, token, doneCb, dupCb, errCb) {
+    var self = this
+    doc = {_id: nick, token: token}
+    self.db.collection('registry').insert(doc, function(err) {
+        if (!err) {
+            doneCb()
+        } else {
+            if (err.code == 11000) { // dup
+                self.findToken(nick, function(token2) {
+                    if (token == token2) {
+                        // same, idempotent
+                        doneCb()
+                        return
+                    }
+                    dupCb()
+                }, function() {
+                    // not found, try again
+                    self.insertToken(nick, token, doneCb, dupCb, errCb)
+                }, function(err) {
+                    errCb(err)
+                })
+                return
+            }
+            errCb(err)
+        }
+    })
+}
+
+Registry.prototype.removeToken = function(nick, token, doneCb, errCb) {
+    var self = this
+    doc = {_id: nick, token: token}
+    self.db.collection('registry').remove(doc, function(err) {
+        if (err) {
+            errCb(err)
+            return
+        }
+        doneCb()
+    })
+}
+
+module.exports = Registry

=== added file 'docs/example-server/notify-form.html'
--- docs/example-server/notify-form.html	1970-01-01 00:00:00 +0000
+++ docs/example-server/notify-form.html	2014-09-08 16:59:38 +0000
@@ -0,0 +1,14 @@
+<!doctype html>
+<html>
+<head>
+<title>notify</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+</head>
+<body>
+<form method="POST" action="/play-notify-form" >
+<label for="nick">Nick:</label><br><input id="nick" name="nick" type="text" autofocus><br>
+<label for="data">Message (JSON):</label><br><textarea id="data" name="data" cols="64" rows="8"></textarea><br>
+<input type="submit" value="notify">
+</form>
+</body>
+</html>

=== added file 'docs/example-server/package.json'
--- docs/example-server/package.json	1970-01-01 00:00:00 +0000
+++ docs/example-server/package.json	2014-09-08 16:59:38 +0000
@@ -0,0 +1,25 @@
+{
+  "name": "pushAppServer",
+  "version": "0.0.2",
+  "description": "Push Notifications App Server Example",
+  "main": "server.js",
+  "dependencies": {
+    "body-parser": "~1.4.3",
+    "express": "~4.4.5",
+    "mongodb": "~1.4.7",
+    "request": "~2.36.0"
+  },
+  "scripts": {
+    "test": "mocha --ui tdd",
+    "start": "PUSH_URL=http://localhost:8080 node server.js"
+  },
+  "author": "Canonical",
+  "license": "LGPL",
+  "directories": {
+    "test": "test"
+  },
+  "devDependencies": {
+    "mocha": "~1.20.1",
+    "supertest": "~0.13.0"
+  }
+}

=== added file 'docs/example-server/server.js'
--- docs/example-server/server.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/server.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,29 @@
+/*
+  Push Notifications App Server Example
+*/
+
+var wire = require('./app').wire
+
+var cfg = require('./config/config')
+var mongoURL = 'mongodb://' + cfg.mongo_host + ':' + cfg.mongo_port + '/pushApp'
+
+var MongoClient = require('mongodb').MongoClient
+
+MongoClient.connect(mongoURL, cfg.mongo_opts, function(err, database) {
+    if(err) throw err
+
+    // wire appplication
+    var app = wire(database, cfg)
+
+    // log errors
+    app.on('pushError', function(err, resp, body) {
+        console.error('pushError', err, resp, body)
+    })
+    app.on('mongoError', function(err) {
+        console.error('mongoError', err)
+    })
+
+    // connection ready => start app
+    app.listen(cfg.listen_port)
+    console.info("Listening on:", cfg.listen_port)
+})

=== added directory 'docs/example-server/test'
=== added file 'docs/example-server/test/app_test.js'
--- docs/example-server/test/app_test.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/test/app_test.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,551 @@
+var assert = require('assert')
+  ,  http = require('http')
+  ,  request = require('supertest')
+
+var app = require('../app')
+
+var cfg = {
+    'app_id': 'app1',
+    'push_url': 'http://push',
+    'expire_mins': 10,
+    'retry_secs': 0.05,
+    'retry_batch': 1,
+    'happy_retry_secs': 0.02,
+}
+
+function cloneCfg() {
+    return JSON.parse(JSON.stringify(cfg))
+}
+
+var PLAY_NOTIFY_FORM = '/play-notify-form'
+
+suite('app', function() {
+    setup(function() {
+        this.db = {}
+        this.app = app.wire(this.db, cloneCfg())
+        this.reg = this.app.get('_reg')
+        this.inbox = this.app.get('_inbox')
+        this.notifier = this.app.get('_notifier')
+    })
+
+    test('wire', function() {
+        assert.ok(this.reg)
+        assert.ok(this.notifier)
+        assert.equal(this.notifier.baseURL, 'http://push')
+        var emitted
+        this.app.on('pushError', function(err, resp, body) {
+            emitted = [err, resp, body]
+        })
+        this.notifier.pushError('err', 'resp', 'body')
+        assert.deepEqual(emitted, ["err", "resp", "body"])
+    })
+
+    test('wire-unknownToken', function() {
+        var got
+        this.reg.removeToken = function(nick, token, doneCb, errCb) {
+            got = [nick, token]
+            doneCb()
+        }
+        this.notifier.emit('unknownToken', "N", "T")
+        assert.deepEqual(got, ["N", "T"])
+    })
+
+    test('wire-unknownToken-mongoError', function() {
+        var emitted
+        this.app.on('mongoError', function(err) {
+            emitted = err
+        })
+        this.reg.removeToken = function(nick, token, doneCb, errCb) {
+            errCb({})
+        }
+        this.notifier.emit('unknownToken', "N", "T")
+        assert.ok(emitted)
+    })
+
+    test('_check', function(done) {
+        var pingCmd
+        this.db.command = function(cmd, cb) {
+            pingCmd = cmd
+            cb(null)
+        }
+        request(this.app)
+            .get('/_check')
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({ok: true})
+            .expect(200, function(err) {
+                assert.deepEqual(pingCmd, {ping: 1})
+                done(err)
+            })
+    })
+
+    test('_check-unavailable', function(done) {
+        var pingCmd
+        this.db.command = function(cmd, cb) {
+            pingCmd = cmd
+            cb({})
+        }
+        request(this.app)
+            .get('/_check')
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: "unavailable"})
+            .expect(503, function(err) {
+                done(err)
+            })
+    })
+
+    test('any-broken', function(done) {
+        request(this.app)
+            .post('/register')
+            .set('Content-Type', 'application/json')
+            .send("")
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'invalid', message: 'invalid json, empty body'})
+            .expect(400, done)
+    })
+
+    test('register', function(done) {
+        var got
+        this.reg.insertToken = function(nick, token, doneCb, dupCb, errCb) {
+            got = [nick, token]
+            doneCb()
+        }
+        request(this.app)
+            .post('/register')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N", token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({ok: true})
+            .expect(200, function(err) {
+                assert.deepEqual(got, ["N", "T"])
+                done(err)
+            })
+    })
+
+    test('register-invalid', function(done) {
+        request(this.app)
+            .post('/register')
+            .set('Content-Type', 'application/json')
+            .send({token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'invalid'})
+            .expect(400, done)
+    })
+
+    test('register-dup', function(done) {
+        this.reg.insertToken = function(nick, token, doneCb, dupCb, errCb) {
+            dupCb()
+        }
+        request(this.app)
+            .post('/register')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N", token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'dup'})
+            .expect(400, done)
+    })
+
+    test('register-unavailable', function(done) {
+        this.reg.insertToken = function(nick, token, doneCb, dupCb, errCb) {
+            errCb({})
+        }
+        request(this.app)
+            .post('/register')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N", token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'unavailable'})
+            .expect(503, done)
+    })
+
+    test('message', function(done) {
+        var lookup = []
+        var pushed
+        var notify
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            lookup.push(nick)
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                foundCb("T2")
+            }
+        }
+        this.inbox.pushMessage = function(token, msg, doneCb, errCb) {
+            pushed = [token]
+            msg._serial = 10
+            doneCb(msg)
+        }
+        this.notifier.notify = function(nick, token, data) {
+            notify = [nick, token, data]
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({ok: true})
+            .expect(200, function(err) {
+                assert.deepEqual(lookup, ["N", "N2"])
+                assert.deepEqual(pushed, ["T2"])
+                assert.deepEqual(notify, ["N2", "T2", {m: 1,_from: "N",_serial: 10}])
+                done(err)
+            })
+    })
+
+    test('message-unauthorized', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                notFoundCb()
+            }
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "Z"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: "unauthorized"})
+            .expect(401, done)
+    })
+
+    test('message-unknown-nick', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                notFoundCb()
+            }
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: "unknown-nick"})
+            .expect(400, done)
+    })
+
+    test('message-invalid', function(done) {
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N"}) // missing data
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'invalid'})
+            .expect(400, done)
+    })
+
+    test('message-check-token-unavailable', function(done) {
+        var emitted
+        this.app.on('mongoError', function(err) {
+            emitted = err
+        })
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (nick == "N") {
+                errCb({})
+            } else {
+                foundCb("T2")
+            }
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'unavailable'})
+            .expect(503, function(err) {
+                assert.ok(emitted)
+                done(err)
+            })
+    })
+
+    test('message-inbox-unavailable', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                foundCb("T2")
+            }
+        }
+        this.inbox.pushMessage = function(token, msg, doneCb, errCb) {
+            errCb({})
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'unavailable'})
+            .expect(503, done)
+    })
+
+    test('message-notify-unavailable', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                errCb({})
+            }
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'unavailable'})
+            .expect(503, function(err) {
+                done(err)
+            })
+    })
+
+    test('index', function(done) {
+        request(this.app)
+            .get('/')
+            .expect(new RegExp('<title>pushAppServer'))
+            .expect('Content-Type', 'text/html; charset=UTF-8')
+            .expect(200, done)
+    })
+
+    test('play-notify-form-absent', function(done) {
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .type('form')
+            .send({nick: "N", data: '{"m": 1}'})
+            .expect(404, done)
+    })
+
+    test('drain', function(done) {
+        var lookup
+        var got
+        var msgs = [{'m': 42, _timestamp: 4000, _serial: 20}]
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            lookup = [nick]
+            foundCb("T")
+        }
+        this.inbox.drain = function(token, timestamp, doneCb, errCb) {
+            got = [token, timestamp]
+            doneCb(msgs)
+        }
+        request(this.app)
+            .post('/drain')
+            .set('Content-Type', 'application/json')
+             .send({nick: "N", token: "T", timestamp: 4000})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({ok: true, msgs: msgs})
+            .expect(200, function(err) {
+                assert.deepEqual(lookup, ["N"])
+                assert.deepEqual(got, ["T", 4000])
+                done(err)
+            })
+    })
+
+    test('drain-unavailable', function(done) {
+        var msgs = [{'m': 42, _timestamp: 4000, _serial: 20}]
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            foundCb("T")
+        }
+        this.inbox.drain = function(token, timestamp, doneCb, errCb) {
+            errCb()
+        }
+        request(this.app)
+            .post('/drain')
+            .set('Content-Type', 'application/json')
+             .send({nick: "N", token: "T", timestamp: 4000})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'unavailable'})
+            .expect(503, function(err) {
+                done(err)
+            })
+    })
+
+    test('drain-invalid', function(done) {
+        request(this.app)
+            .post('/drain')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N"}) // missing data
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'invalid'})
+            .expect(400, done)
+    })
+
+    test('drain-invalid-timestamp', function(done) {
+        request(this.app)
+            .post('/drain')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N", token: "T", timestamp: "foo"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({error: 'invalid'})
+            .expect(400, done)
+    })
+
+})
+
+suite('app-with-play-notify', function() {
+    setup(function() {
+        this.db = {}
+        var cfg = cloneCfg()
+        cfg.play_notify_form = true
+        this.app = app.wire(this.db, cfg)
+        this.reg = this.app.get('_reg')
+        this.notifier = this.app.get('_notifier')
+    })
+
+    test('root-form', function(done) {
+        request(this.app)
+            .get('/')
+            .expect(new RegExp('<form.*action="' + PLAY_NOTIFY_FORM + '"(.|\n)*<input id="nick" name="nick"'))
+            .expect('Content-Type', 'text/html; charset=UTF-8')
+            .expect(200, done)
+    })
+
+    test('play-notify-form', function(done) {
+        var notify
+          , start = Date.now()
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            foundCb("T")
+        }
+        this.notifier.notify = function(nick, token, data) {
+            notify = [nick, token, data]
+        }
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .type('form')
+            .send({nick: "N", data: '{"m": 1}'})
+            .expect('Content-Type', 'text/plain; charset=utf-8')
+            .expect("OK\n")
+            .expect(200, function(err) {
+                assert.deepEqual(notify.slice(0, 2), ["N", "T"])
+                var data = notify[2]
+                assert.equal(typeof(data._ephemeral), "number")
+                assert.ok(data._ephemeral >= start)
+                delete data._ephemeral
+                assert.deepEqual(data, {"m": 1})
+                done(err)
+            })
+    })
+
+    test('play-notify-form-not-json', function(done) {
+        var notify
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            foundCb("T")
+        }
+        this.notifier.notify = function(nick, token, data) {
+            notify = [nick, token, data]
+        }
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .type('form')
+            .send({nick: "N", data: '{X'})
+            .expect('Content-Type', 'text/plain; charset=utf-8')
+            .expect("data is not JSON\n")
+            .expect(400, done)
+    })
+
+    test('play-notify-form-unknown-nick', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            notFoundCb()
+        }
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .set('Content-Type', 'application/json')
+            .send({nick: "N", data: '{"m": 1}'})
+            .expect('Content-Type', 'text/plain; charset=utf-8')
+            .expect("unknown nick\n")
+            .expect(400, done)
+    })
+
+    test('play-notify-form-unavailable', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            errCb({})
+        }
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .type('form')
+            .send({nick: "N", data: '{"m": 1}'})
+            .expect('Content-Type', 'text/plain; charset=utf-8')
+            .expect('db is hopefully only momentarily :(\n')
+            .expect(503, function(err) {
+                done(err)
+            })
+    })
+
+    test('play-notify-form-invalid', function(done) {
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            notFoundCb()
+        }
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .set('Content-Type', 'application/json')
+            .send({nick: "", data: '{"m": 1}'})
+            .expect('Content-Type', 'text/plain; charset=utf-8')
+            .expect("invalid/empty fields\n")
+            .expect(400, done)
+    })
+
+    test('play-notify-form-broken', function(done) {
+        request(this.app)
+            .post(PLAY_NOTIFY_FORM)
+            .type('form')
+            .send("=")
+            .expect(400, done)
+    })
+
+})
+
+suite('app-with-no-inbox', function() {
+    setup(function() {
+        this.db = {}
+        var cfg = cloneCfg()
+        cfg.no_inbox = true
+        this.app = app.wire(this.db, cfg)
+        this.reg = this.app.get('_reg')
+        this.inbox = this.app.get('_inbox')
+        this.notifier = this.app.get('_notifier')
+    })
+
+    test('no-inbox', function() {
+        assert.equal(this.inbox, null)
+    })
+
+    test('message-no-inbox', function(done) {
+        var lookup = []
+        var notify
+          , start = Date.now()
+        this.reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            lookup.push(nick)
+            if (nick == "N") {
+                foundCb("T")
+            } else {
+                foundCb("T2")
+            }
+        }
+        this.notifier.notify = function(nick, token, data) {
+            notify = [nick, token, data]
+        }
+        request(this.app)
+            .post('/message')
+            .set('Content-Type', 'application/json')
+            .send({nick: "N2", data: {"m": 1}, from_nick: "N", from_token: "T"})
+            .expect('Content-Type', 'application/json; charset=utf-8')
+            .expect({ok: true})
+            .expect(200, function(err) {
+                assert.deepEqual(lookup, ["N", "N2"])
+                assert.deepEqual(notify.slice(0, 2), ["N2", "T2"])
+                var data = notify[2]
+                assert.equal(typeof(data._ephemeral), "number")
+                assert.ok(data._ephemeral >= start)
+                delete data._ephemeral
+                assert.deepEqual(data, {"m": 1, _from:"N"})
+                done(err)
+            })
+    })
+
+    test('drain-not-there', function(done) {
+        request(this.app)
+            .post('/drain')
+            .set('Content-Type', 'application/json')
+             .send({nick: "N", token: "T", timestamp: 4000})
+            .expect(404, done)
+    })
+
+})

=== added file 'docs/example-server/test/inbox_test.js'
--- docs/example-server/test/inbox_test.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/test/inbox_test.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,79 @@
+var assert = require('assert')
+
+var MongoClient = require('mongodb').MongoClient
+
+function unexpected(msg) {
+    assert.ok(false, "unexpected: "+msg)
+}
+
+var Inbox = require('../lib/inbox')
+
+suite('Inbox', function(){
+    setup(function(done) {
+        var self = this
+        MongoClient.connect("mongodb://localhost:27017/pushAppTestDb", function(err, database) {
+            if(err) throw err
+            self.db = database
+            // cleanup
+            self.db.collection('inbox').drop(function(err) {
+                if(err && err.errmsg != 'ns not found') throw err
+                done()
+            })
+        })
+    })
+
+    test('push-1', function(done) {
+        var inbox = new Inbox(this.db)
+        inbox.pushMessage('foo', {m: 42}, function(msg) {
+            assert.ok(msg._timestamp)
+            assert.equal(msg._serial, 1)
+            done()
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('push-2', function(done) {
+        var inbox = new Inbox(this.db)
+        inbox.pushMessage('foo', {m: 42}, function(msg) {
+            assert.equal(msg._serial, 1)
+            inbox.pushMessage('foo', {m: 45}, function(msg) {
+                assert.equal(msg._serial, 2)
+                done()
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('push-3-drain', function(done) {
+        var inbox = new Inbox(this.db)
+        inbox.pushMessage('foo', {m: 42, _timestamp: 2000}, function(msg) {
+            inbox.pushMessage('foo', {m: 45, _timestamp: 3000}, function(msg) {
+                inbox.pushMessage('foo', {m: 47, _timestamp: 4000}, function(msg) {
+                    inbox.drain('foo', 3000, function(msgs) {
+                        assert.deepEqual(msgs, [
+                            {m: 45, _timestamp: 3000, serial: 2},
+                            {m: 47, _timestamp: 4000, serial: 3}
+                        ])
+                        inbox.drain('foo', 0, function(msgs) {
+                            assert.equal(msgs.length, 2)
+                            done()
+                        }, done)
+                    }, done)
+                }, done)
+            }, done)
+        }, done)
+    })
+
+    test('drain-nop', function(done) {
+        var inbox = new Inbox(this.db)
+        inbox.drain('foo', 3000, function(msgs) {
+            assert.deepEqual(msgs, [])
+            done()
+        }, done)
+    })
+
+})
\ No newline at end of file

=== added file 'docs/example-server/test/notifier_test.js'
--- docs/example-server/test/notifier_test.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/test/notifier_test.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,192 @@
+var assert = require('assert')
+  ,  http = require('http')
+
+
+var Notifier = require('../lib/notifier')
+
+var cfg = {
+    'app_id': 'app1',
+    'expire_mins': 10,
+    'retry_secs': 0.05,
+    'retry_batch': 1,
+    'happy_retry_secs': 0.02
+}
+  , cfg_batch2 = {
+    'app_id': 'app1',
+    'expire_mins': 10,
+    'retry_secs': 0.05,
+    'retry_batch': 2,
+    'happy_retry_secs': 0.02
+}
+
+suite('Notifier', function() {
+    setup(function(done) {
+        var self = this
+        self.s = http.createServer(function(req, resp) {
+            self.s.emit(req.method, req, resp)
+        })
+        self.s.listen(0, 'localhost', function() {
+            self.url = 'http://localhost:' + self.s.address().port
+            done()
+        })
+    })
+
+    teardown(function() {
+        this.s.close()
+    })
+
+    test('happy-notify', function(done) {
+        var b = ""
+        this.s.on('POST', function(req, resp) {
+            req.on('data', function(chunk) {
+                b += chunk
+            })
+            req.on('end', function() {
+                resp.writeHead(200, {"Content-Type": "application/json"})
+                resp.end('{}')
+            })
+        })
+        var n = new Notifier(this.url, cfg)
+        var approxExpire = new Date
+        approxExpire.setUTCMinutes(approxExpire.getUTCMinutes()+10)
+        n.notify("N", "T", {m: 42}, function() {
+            var reqObj = JSON.parse(b)
+            var expireOn = Date.parse(reqObj.expire_on)
+            delete reqObj.expire_on
+            assert.ok(expireOn >= approxExpire)
+            assert.deepEqual(reqObj, {
+                "token": "T",
+                "appid": "app1",
+                "data": {"m": 42}
+            })
+            done()
+        })
+    })
+
+    test('retry-notify', function(done) {
+        var b = ""
+        var fail = 1
+        this.s.on('POST', function(req, resp) {
+            if (fail) {
+                fail--
+                resp.writeHead(503, {"Content-Type": "application/json"})
+                resp.end('')
+                return
+            }
+            req.on('data', function(chunk) {
+                b += chunk
+            })
+            req.on('end', function() {
+                resp.writeHead(200, {"Content-Type": "application/json"})
+                resp.end('{}')
+            })
+        })
+        var n = new Notifier(this.url, cfg)
+        var approxExpire = new Date
+        approxExpire.setUTCMinutes(approxExpire.getUTCMinutes()+10)
+        n.notify("N", "T", {m: 42}, function() {
+            var reqObj = JSON.parse(b)
+            var expireOn = Date.parse(reqObj.expire_on)
+            delete reqObj.expire_on
+            assert.ok(expireOn >= approxExpire)
+            assert.deepEqual(reqObj, {
+                "token": "T",
+                "appid": "app1",
+                "data": {"m": 42}
+            })
+            done()
+        })
+    })
+
+    function flakyPOST(s, fail, tokens) {
+        s.on('POST', function(req, resp) {
+            var b = ""
+            req.on('data', function(chunk) {
+                b += chunk
+            })
+            req.on('end', function() {
+                var reqObj = JSON.parse(b)
+                if (fail) {
+                    fail--
+                    resp.writeHead(503, {"Content-Type": "application/json"})
+                    resp.end('')
+                    return
+                }
+                tokens[reqObj.token] = 1
+                resp.writeHead(200, {"Content-Type": "application/json"})
+                resp.end('{}')
+            })
+        })
+    }
+
+    test('retry-notify-2-retries', function(done) {
+        var tokens = {}
+        flakyPOST(this.s, 2, tokens)
+        var n = new Notifier(this.url, cfg)
+        function yay() {
+            assert.deepEqual(tokens, {"T1": 1})
+            done()
+        }
+        n.notify("N1", "T1", {m: 42}, yay)
+    })
+
+    test('retry-notify-2-batches', function(done) {
+        var tokens = {}
+        flakyPOST(this.s, 2, tokens)
+        var n = new Notifier(this.url, cfg)
+        var waiting = 2
+        function yay() {
+            waiting--
+            if (waiting == 0) {
+                assert.deepEqual(tokens, {"T1": 1, "T2": 1})
+                done()
+            }
+        }
+        n.notify("N1", "T1", {m: 42}, yay)
+        n.notify("N2", "T2", {m: 42}, yay)
+    })
+
+    test('retry-notify-expired', function(done) {
+        var tokens = {}
+        flakyPOST(this.s, 2, tokens)
+        var n = new Notifier(this.url, cfg_batch2)
+        var waiting = 1
+        function yay() {
+            waiting--
+            if (waiting == 0) {
+                assert.deepEqual(tokens, {"T2": 1})
+                done()
+            }
+        }
+        n.notify("N1", "T1", {m: 42}, yay, new Date)
+        n.notify("N2", "T2", {m: 42}, yay)
+    })
+
+    test('unknown-token-notify', function(done) {
+        this.s.on('POST', function(req, resp) {
+            resp.writeHead(400, {"Content-Type": "application/json"})
+            resp.end('{"error": "unknown-token"}')
+        })
+        var n = new Notifier(this.url, cfg)
+        n.on('unknownToken', function(nick, token) {
+            assert.equal(nick, "N")
+            assert.equal(token, "T")
+            done()
+        })
+        n.notify("N", "T", {m: 42})
+    })
+
+    test('error-notify', function(done) {
+        this.s.on('POST', function(req, resp) {
+            resp.writeHead(500)
+            resp.end('')
+        })
+        var n = new Notifier(this.url, cfg)
+        n.on('pushError', function(err, resp, body) {
+            assert.equal(resp.statusCode, 500)
+            done()
+        })
+        n.notify("N", "T", {m: 42})
+    })
+
+})

=== added file 'docs/example-server/test/registry_test.js'
--- docs/example-server/test/registry_test.js	1970-01-01 00:00:00 +0000
+++ docs/example-server/test/registry_test.js	2014-09-08 16:59:38 +0000
@@ -0,0 +1,179 @@
+var assert = require('assert')
+
+var MongoClient = require('mongodb').MongoClient
+
+function unexpected(msg) {
+    assert.ok(false, "unexpected: "+msg)
+}
+
+var Registry = require('../lib/registry')
+
+suite('Registry', function(){
+    setup(function(done) {
+        var self = this
+        MongoClient.connect("mongodb://localhost:27017/pushAppTestDb", function(err, database) {
+            if(err) throw err
+            self.db = database
+            // cleanup
+            self.db.collection('registry').drop(function(err) {
+                if(err && err.errmsg != 'ns not found') throw err
+                done()
+            })
+        })
+    })
+
+    test('insert-and-find', function(done) {
+        var reg = new Registry(this.db)
+        reg.insertToken("N", "T", function() {
+            reg.findToken("N", function(token) {
+                assert.equal(token, "T")
+                done()
+            }, function() {
+                unexpected("not-found")
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('find-not-found', function(done) {
+        var reg = new Registry(this.db)
+        reg.findToken("N", function() {
+            unexpected("found")
+        }, function() {
+            done()
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('insert-identical-dup', function(done) {
+        var reg = new Registry(this.db)
+        reg.insertToken("N", "T", function() {
+            reg.insertToken("N", "T", function() {
+                done()
+            }, function() {
+                unexpected("dup")
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('insert-dup', function(done) {
+        var reg = new Registry(this.db)
+        reg.insertToken("N", "T1", function() {
+            reg.insertToken("N", "T2", function() {
+                unexpected("success")
+            }, function() {
+                done()
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('insert-temp-dup', function(done) {
+        var reg = new Registry(this.db)
+        var findToken = reg.findToken
+          , insertToken = reg.insertToken
+        var notFoundOnce = 0
+        var insertInvocations = 0
+        reg.findToken = function(nick, foundCb, notFoundCb, errCb) {
+            if (notFoundOnce == 0) {
+                notFoundOnce++
+                notFoundCb()
+                return
+            }
+            findToken.call(reg, nick, foundCb, notFoundCb, errCb)
+        }
+        reg.insertToken = function(nick, token, doneCb, dupCb, errCb) {
+            insertInvocations++
+            insertToken.call(reg, nick, token, doneCb, dupCb, errCb)
+        }
+        reg.insertToken("N", "T1", function() {
+            reg.insertToken("N", "T2", function() {
+                unexpected("success")
+            }, function() {
+                assert.equal(insertInvocations, 3)
+                done()
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('remove', function(done) {
+        var reg = new Registry(this.db)
+        reg.insertToken("N", "T", function() {
+            reg.removeToken("N", "T", function() {
+                reg.findToken("N", function(token) {
+                    unexpected("found")
+                }, function() {
+                    done()
+                }, function(err) {
+                    unexpected(err)
+                })
+            }, function(err) {
+                unexpected(err)
+            })
+        },  function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('remove-exact', function(done) {
+        var reg = new Registry(this.db)
+        reg.insertToken("N", "T1", function() {
+            reg.removeToken("N", "T2", function() {
+                reg.findToken("N", function(token) {
+                    assert.equal(token, "T1")
+                    done()
+                }, function() {
+                    unexpected("no-found")
+                }, function(err) {
+                    unexpected(err)
+                })
+            }, function(err) {
+                unexpected(err)
+            })
+        },  function() {
+            unexpected("dup")
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+
+    test('remove-nop', function(done) {
+        var reg = new Registry(this.db)
+        reg.removeToken("N1", "T1", function() {
+            reg.findToken("N1", function(token) {
+                unexpected("found")
+            }, function() {
+                done()
+            }, function(err) {
+                unexpected(err)
+            })
+        }, function(err) {
+            unexpected(err)
+        })
+    })
+})

=== modified file 'docs/highlevel.txt'
--- docs/highlevel.txt	2014-08-08 09:09:39 +0000
+++ docs/highlevel.txt	2014-09-08 16:59:38 +0000
@@ -1,8 +1,10 @@
-Ubuntu Push Client Developer Guide
-==================================
+Ubuntu Push Client High Level Developer Guide
+============================================
 
 :Version: 0.50+
 
+.. contents::
+
 Introduction
 ------------
 
@@ -11,52 +13,7 @@
 
 ---------
 
-Let's describe the push system by way of an example.
-
-Alice has written a chat application called Chatter. Using it, Bob can send messages to Carol and viceversa. Alice has a
-web application for it, so the way it works now is that Bob connects to the service, posts a message, and when Carol
-connects, she gets it. If Carol leaves the browser window open, it beeps when messages arrive.
-
-Now Alice wants to create an Ubuntu Touch app for Chatter, so she implements the same architecture using a client that
-does the same thing as the web browser. Sadly, since applications on Ubuntu Touch don't run continuously, messages are
-only delivered when Carol opens the app, and the user experience suffers.
-
-Using the Ubuntu Push Server, this problem is alleviated: the Chatter server will deliver the messages to the Ubuntu
-Push Server, which in turn will send it in an efficient manner to the Ubuntu Push Client running in Bob and Carol's
-devices. The user sees a notification (all without starting the app) and then can launch it if he's interested in
-reading messages at that point.
-
-Since the app is not started and messages are delivered oportunistically, this is both battery and bandwidth-efficient.
-
-.. figure:: push.svg
-
-The Ubuntu Push system provides:
-
-* A push server which receives **push messages** from the app servers, queues them and delivers them efficiently
-  to the devices.
-* A push client which receives those messages, queues messages to the app and displays notifications to the user
-
-The full lifecycle of a push message is:
-
-* Created in a application-specific server
-* Sent to the Ubuntu Push server, targeted at a user or user+device pair
-* Delivered to one or more Ubuntu devices
-* Passed through the application helper for processing
-* Notification displayed to the user (via different mechanisms)
-* Application Message queued for the app's use
-
-If the user interacts with the notification, the application is launched and should check its queue for messages
-it has to process.
-
-For the app developer, there are several components needed:
-
-* A server that sends the **push messages** to the Ubuntu Push server
-* Support in the client app for registering with the Ubuntu Push client
-* Support in the client app to react to **notifications** displayed to the user and process **application messages**
-* A helper program with application-specific knowledge that transforms **push messages** as needed.
-
-In the following sections, we'll see how to implement all the client side parts. For the application server, see the
-`Ubuntu Push Server API section <#ubuntu-push-server-api>`__
+.. include:: _description.txt
 
 The PushClient Component
 ------------------------
@@ -68,7 +25,7 @@
     PushClient {
         id: pushClient
         Component.onCompleted: {
-            newNotifications.connect(messageList.handle_notifications)
+            notificationsChanged.connect(messageList.handle_notifications)
             error.connect(messageList.handle_error)
         }
         appId: "com.ubuntu.developer.push.hello_hello"
@@ -95,13 +52,13 @@
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 When a notification is received by the Push Client, it will be delivered to your application's push helper, and then
-placed in your application's mailbox. At that point, the PushClient will emit the ``newNotifications(QStringList)`` signal
+placed in your application's mailbox. At that point, the PushClient will emit the ``notificationsChanged(QStringList)`` signal
 containing your messages. You should probably connect to that signal and handle those messages.
 
 Because of the application's lifecycle, there is no guarantee that it will be running when the signal is emitted. For that
 reason, apps should check for pending notifications whenever they are activated or started. To do that, use the
 ``getNotifications()`` slot. Triggering that slot will fetch notifications and trigger the
-``newNotifications(QStringList)`` signal.
+``notificationsChanged(QStringList)`` signal.
 
 Error Handling
 ~~~~~~~~~~~~~~
@@ -111,8 +68,8 @@
 Persistent Notification Management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some notifications are persistent, meaning they don't disappear automatically. For those notifications, there is an API that
-allows the app to manage them without having to know the underlying details of the platform.
+Some notifications are persistent, meaning that, after they are presented, they don't disappear automatically.
+This API allows the app to manage that type of notifications.
 
 On each notification there's an optional ``tag`` field, used for this purpose.
 
@@ -125,201 +82,4 @@
 
 The ``count`` property sets the counter in the application's icon to the given value.
 
-
-Application Helpers
--------------------
-
-The payload delivered to push-client will be passed onto a helper program that can modify it as needed before passing it onto
-the postal service (see `Helper Output Format <#helper-output-format>`__).
-
-The helper receives two arguments ``infile`` and ``outfile``. The message is delivered via ``infile`` and the transformed
-version is placed in ``outfile``.
-
-This is the simplest possible useful helper, which simply passes the message through unchanged::
-
-	#!/usr/bin/python3
-
-	import sys
-	f1, f2 = sys.argv[1:3]
-	open(f2, "w").write(open(f1).read())
-
-Helpers need to be added to the click package manifest::
-
-	{
-		"name": "com.ubuntu.developer.ralsina.hello",
-		"description": "description of hello",
-		"framework": "ubuntu-sdk-14.10-qml-dev2",
-		"architecture": "all",
-		"title": "hello",
-		"hooks": {
-			"hello": {
-				"apparmor": "hello.json",
-				"desktop": "hello.desktop"
-			},
-			"helloHelper": {
-				"apparmor": "helloHelper-apparmor.json",
-				"push-helper": "helloHelper.json"
-			}
-		},
-		"version": "0.2",
-		"maintainer": "Roberto Alsina <[e-mail]>"
-	}
-
-Here, we created a helloHelper entry in hooks that has an apparmor profile and an additional JSON file for the push-helper hook.
-
-helloHelper-apparmor.json must contain **only** the push-notification-client policy group::
-
-	{
-		"policy_groups": [
-			"push-notification-client"
-		],
-		"policy_version": 1.2
-	}
-
-And helloHelper.json must have at least a exec key with the path to the helper executable relative to the json, and optionally
-an app_id key containing the short id of one of the apps in the package (in the format packagename_appname without a version).
-If the app_id is not specified, the helper will be used for all apps in the package::
-
-	{
-		"exec": "helloHelper",
-		"app_id": "com.ubuntu.developer.ralsina.hello_hello"
-	}
-
-.. note:: For deb packages, helpers should be installed into /usr/lib/ubuntu-push-client/legacy-helpers/ as part of the package.
-
-Helper Output Format
---------------------
-
-Helpers output has two parts, the postal message (in the "message" key) and a notification to be presented to the user (in the "notification" key).
-
-Here's a simple example::
-
-	{
-		"message": "foobar",
-		"notification": {
-			"tag": "foo",
-			"card": {
-				"summary": "yes",
-				"body": "hello",
-				"popup": true,
-				"persist": true,
-				"timestamp": 1407160197
-			}
-			"sound": "buzz.mp3",
-			"vibrate": {
-				"pattern": [200, 100],
-				"repeat": 2
-			}
-			"emblem-counter": {
-				"count": 12,
-				"visible": true
-			}
-		}
-	}
-
-The notification can contain a **tag** field, which can later be used by the `persistent notification management API. <#persistent-notification-management>`__
-
-:message: (optional) A JSON object that is passed as-is to the application via PopAll.
-:notification: (optional) Describes the user-facing notifications triggered by this push message.
-
-The notification can contain a **card**. A card describes a specific notification to be given to the user,
-and has the following fields:
-
-:summary: (required) a title. The card will not be presented if this is missing.
-:body: longer text, defaults to empty.
-:actions: If empty (the default), a bubble notification is non-clickable.
-          If you add a URL, then bubble notifications are clickable and launch that URL. One use for this is using a URL like
-          ``appid://com.ubuntu.developer.ralsina.hello/hello/current-user-version`` which will switch to the app or launch
-          it if it's not running. See `URLDispatcher <https://wiki.ubuntu.com/URLDispatcher>`__ for more information.
-
-:icon: An icon relating to the event being notified. Defaults to empty (no icon);
-       a secondary icon relating to the application will be shown as well, regardless of this field.
-:timestamp: Seconds since the unix epoch, only used for persist (for now). If zero or unset, defaults to current timestamp.
-:persist: Whether to show in notification centre; defaults to false
-:popup: Whether to show in a bubble. Users can disable this, and can easily miss them, so don't rely on it exclusively. Defaults to false.
-
-.. note:: Keep in mind that the precise way in which each field is presented to the user depends on factors such as
-          whether it's shown as a bubble or in the notification centre, or even the version of Ubuntu Touch the user
-          has on their device.
-
-The notification can contain a **sound** field. This is either a boolean (play a predetermined sound) or the path to a sound file. The user can disable it, so don't rely on it exclusively.
-Defaults to empty (no sound). The path is relative, and will be looked up in (a) the application's .local/share/<pkgname>, and (b)
-standard xdg dirs.
-
-The notification can contain a **vibrate** field, causing haptic feedback, which can be either a boolean (if true, vibrate a predetermined way) or an object that has the following content:
-
-:pattern: a list of integers describing a vibration pattern (duration of alternating vibration/no vibration times, in milliseconds).
-:repeat: number of times the pattern has to be repeated (defaults to 1, 0 is the same as 1).
-
-The notification can contain a **emblem-counter** field, with the following content:
-
-:count: a number to be displayed over the application's icon in the launcher.
-:visible: set to true to show the counter, or false to hide it.
-
-.. note:: Unlike other notifications, emblem-counter needs to be cleaned by the app itself.
-          Please see `the persistent notification management section. <#persistent-notification-management>`__
-
-.. FIXME crosslink to hello example app on each method
-
-Security
-~~~~~~~~
-
-To use the push API, applications need to request permission in their security profile, using something like this::
-
-	{
-		"policy_groups": [
-			"networking",
-			"push-notification-client"
-		],
-		"policy_version": 1.2
-	}
-
-
-Ubuntu Push Server API
-----------------------
-
-The Ubuntu Push server is located at https://push.ubuntu.com and has a single endpoint: ``/notify``.
-To notify a user, your application has to do a POST with ``Content-type: application/json``.
-
-Here is an example of the POST body using all the fields::
-
-	{
-		"appid": "com.ubuntu.music_music",
-		"expire_on": "2014-10-08T14:48:00.000Z",
-		"token": "LeA4tRQG9hhEkuhngdouoA==",
-		"clear_pending": true,
-		"replace_tag": "tagname",
-		"data": {
-			"message": "foobar",
-			"notification": {
-				"card": {
-					"summary": "yes",
-					"body": "hello",
-					"popup": true,
-					"persist": true,
-					"timestamp": 1407160197
-				}
-				"sound": "buzz.mp3",
-				"tag": "foo",
-				"vibrate": {
-					"pattern": [200, 100],
-					"repeat": 2
-				}
-				"emblem-counter": {
-					"count": 12,
-					"visible": true
-				}
-			}
-		}
-	}
-
-
-:appid: ID of the application that will receive the notification, as described in the client side documentation.
-:expire_on: Expiration date/time for this message, in `ISO8601 Extendend format <http://en.wikipedia.org/wiki/ISO_8601>`__
-:token: The token identifying the user+device to which the message is directed, as described in the client side documentation.
-:clear_pending: Discards all previous pending notifications. Usually in response to getting a "too-many-pending" error.
-:replace_tag: If there's a pending notification with the same tag, delete it before queuing this new one.
-:data: A JSON object.
-
-In this example, data is `what a helper would output <#helper-output-format>`__ but that's not necessarily the case.
-The content of the data field will be passed to the helper application which **has** to produce output in that format.
+.. include:: _common.txt
\ No newline at end of file

=== modified file 'docs/lowlevel.txt'
--- docs/lowlevel.txt	2014-08-08 09:09:39 +0000
+++ docs/lowlevel.txt	2014-09-08 16:59:38 +0000
@@ -1,8 +1,10 @@
-Ubuntu Push Client Developer Guide
-==================================
+Ubuntu Push Client Low Level Developer Guide
+============================================
 
 :Version: 0.50+
 
+.. contents::
+
 Introduction
 ------------
 
@@ -14,52 +16,8 @@
 
 ---------
 
-Let's describe the push system by way of an example.
-
-Alice has written a chat application called Chatter. Using it, Bob can send messages to Carol and viceversa. Alice has a
-web application for it, so the way it works now is that Bob connects to the service, posts a message, and when Carol
-connects, she gets it. If Carol leaves the browser window open, it beeps when messages arrive.
-
-Now Alice wants to create an Ubuntu Touch app for Chatter, so she implements the same architecture using a client that
-does the same thing as the web browser. Sadly, since applications on Ubuntu Touch don't run continuously, messages are
-only delivered when Carol opens the app, and the user experience suffers.
-
-Using the Ubuntu Push Server, this problem is alleviated: the Chatter server will deliver the messages to the Ubuntu
-Push Server, which in turn will send it in an efficient manner to the Ubuntu Push Client running in Bob and Carol's
-devices. The user sees a notification (all without starting the app) and then can launch it if he's interested in
-reading messages at that point.
-
-Since the app is not started and messages are delivered oportunistically, this is both battery and bandwidth-efficient.
-
-.. figure:: push.svg
-
-The Ubuntu Push system provides:
-
-* A push server which receives **push messages** from the app servers, queues them and delivers them efficiently
-  to the devices.
-* A push client which receives those messages, queues messages to the app and displays notifications to the user
-
-The full lifecycle of a push message is:
-
-* Created in a application-specific server
-* Sent to the Ubuntu Push server, targeted at a user or user+device pair
-* Delivered to one or more Ubuntu devices
-* Passed through the application helper for processing
-* Notification displayed to the user (via different mechanisms)
-* Application Message queued for the app's use
-
-If the user interacts with the notification, the application is launched and should check its queue for messages
-it has to process.
-
-For the app developer, there are several components needed:
-
-* A server that sends the **push messages** to the Ubuntu Push server
-* Support in the client app for registering with the Ubuntu Push client
-* Support in the client app to react to **notifications** displayed to the user and process **application messages**
-* A helper program with application-specific knowledge that transforms **push messages** as needed.
-
-In the following sections, we'll see how to implement all the client side parts. For the application server, see the
-`Ubuntu Push Server API section <#ubuntu-push-server-api>`__
+.. include:: _description.txt
+
 
 The PushNotifications Service
 -----------------------------
@@ -202,8 +160,8 @@
 Persistent Notification Management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some notifications are persistent, meaning they don't disappear automatically. For those notifications, there is an API that
-allows the app to manage them without having to know the underlying details of the platform.
+Some notifications are persistent, meaning that, after they are presented, they don't disappear automatically.
+This API allows the app to manage that type of notifications.
 
 On each notification there's an optional ``tag`` field, used for this purpose.
 
@@ -220,200 +178,4 @@
 Set the counter to the given values.
 
 
-Application Helpers
--------------------
-
-The payload delivered to push-client will be passed onto a helper program that can modify it as needed before passing it onto
-the postal service (see `Helper Output Format <#helper-output-format>`__).
-
-The helper receives two arguments ``infile`` and ``outfile``. The message is delivered via ``infile`` and the transformed
-version is placed in ``outfile``.
-
-This is the simplest possible useful helper, which simply passes the message through unchanged::
-
-	#!/usr/bin/python3
-
-	import sys
-	f1, f2 = sys.argv[1:3]
-	open(f2, "w").write(open(f1).read())
-
-Helpers need to be added to the click package manifest::
-
-	{
-		"name": "com.ubuntu.developer.ralsina.hello",
-		"description": "description of hello",
-		"framework": "ubuntu-sdk-14.10-qml-dev2",
-		"architecture": "all",
-		"title": "hello",
-		"hooks": {
-			"hello": {
-				"apparmor": "hello.json",
-				"desktop": "hello.desktop"
-			},
-			"helloHelper": {
-				"apparmor": "helloHelper-apparmor.json",
-				"push-helper": "helloHelper.json"
-			}
-		},
-		"version": "0.2",
-		"maintainer": "Roberto Alsina <[e-mail]>"
-	}
-
-Here, we created a helloHelper entry in hooks that has an apparmor profile and an additional JSON file for the push-helper hook.
-
-helloHelper-apparmor.json must contain **only** the push-notification-client policy group::
-
-	{
-		"policy_groups": [
-			"push-notification-client"
-		],
-		"policy_version": 1.2
-	}
-
-And helloHelper.json must have at least a exec key with the path to the helper executable relative to the json, and optionally
-an app_id key containing the short id of one of the apps in the package (in the format packagename_appname without a version).
-If the app_id is not specified, the helper will be used for all apps in the package::
-
-	{
-		"exec": "helloHelper",
-		"app_id": "com.ubuntu.developer.ralsina.hello_hello"
-	}
-
-.. note:: For deb packages, helpers should be installed into /usr/lib/ubuntu-push-client/legacy-helpers/ as part of the package.
-
-Helper Output Format
---------------------
-
-Helpers output has two parts, the postal message (in the "message" key) and a notification to be presented to the user (in the "notification" key).
-
-Here's a simple example::
-
-	{
-		"message": "foobar",
-		"notification": {
-			"tag": "foo",
-			"card": {
-				"summary": "yes",
-				"body": "hello",
-				"popup": true,
-				"persist": true,
-				"timestamp": 1407160197
-			}
-			"sound": "buzz.mp3",
-			"vibrate": {
-				"pattern": [200, 100],
-				"repeat": 2
-			}
-			"emblem-counter": {
-				"count": 12,
-				"visible": true
-			}
-		}
-	}
-
-The notification can contain a **tag** field, which can later be used by the `persistent notification management API. <#persistent-notification-management>`__
-
-:message: (optional) A JSON object that is passed as-is to the application via PopAll.
-:notification: (optional) Describes the user-facing notifications triggered by this push message.
-
-The notification can contain a **card**. A card describes a specific notification to be given to the user,
-and has the following fields:
-
-:summary: (required) a title. The card will not be presented if this is missing.
-:body: longer text, defaults to empty.
-:actions: If empty (the default), a bubble notification is non-clickable.
-          If you add a URL, then bubble notifications are clickable and launch that URL. One use for this is using a URL like
-          ``appid://com.ubuntu.developer.ralsina.hello/hello/current-user-version`` which will switch to the app or launch
-          it if it's not running. See `URLDispatcher <https://wiki.ubuntu.com/URLDispatcher>`__ for more information.
-
-:icon: An icon relating to the event being notified. Defaults to empty (no icon);
-       a secondary icon relating to the application will be shown as well, regardless of this field.
-:timestamp: Seconds since the unix epoch, only used for persist (for now). If zero or unset, defaults to current timestamp.
-:persist: Whether to show in notification centre; defaults to false
-:popup: Whether to show in a bubble. Users can disable this, and can easily miss them, so don't rely on it exclusively. Defaults to false.
-
-.. note:: Keep in mind that the precise way in which each field is presented to the user depends on factors such as
-          whether it's shown as a bubble or in the notification centre, or even the version of Ubuntu Touch the user
-          has on their device.
-
-The notification can contain a **sound** field. This is either a boolean (play a predetermined sound) or the path to a sound file. The user can disable it, so don't rely on it exclusively.
-Defaults to empty (no sound). The path is relative, and will be looked up in (a) the application's .local/share/<pkgname>, and (b)
-standard xdg dirs.
-
-The notification can contain a **vibrate** field, causing haptic feedback, which can be either a boolean (if true, vibrate a predetermined way) or an object that has the following content:
-
-:pattern: a list of integers describing a vibration pattern (duration of alternating vibration/no vibration times, in milliseconds).
-:repeat: number of times the pattern has to be repeated (defaults to 1, 0 is the same as 1).
-
-The notification can contain a **emblem-counter** field, with the following content:
-
-:count: a number to be displayed over the application's icon in the launcher.
-:visible: set to true to show the counter, or false to hide it.
-
-.. note:: Unlike other notifications, emblem-counter needs to be cleaned by the app itself.
-          Please see `the persistent notification management section. <#persistent-notification-management>`__
-
-.. FIXME crosslink to hello example app on each method
-
-Security
-~~~~~~~~
-
-To use the push API, applications need to request permission in their security profile, using something like this::
-
-	{
-		"policy_groups": [
-			"networking",
-			"push-notification-client"
-		],
-		"policy_version": 1.2
-	}
-
-
-Ubuntu Push Server API
-----------------------
-
-The Ubuntu Push server is located at https://push.ubuntu.com and has a single endpoint: ``/notify``.
-To notify a user, your application has to do a POST with ``Content-type: application/json``.
-
-Here is an example of the POST body using all the fields::
-
-	{
-		"appid": "com.ubuntu.music_music",
-		"expire_on": "2014-10-08T14:48:00.000Z",
-		"token": "LeA4tRQG9hhEkuhngdouoA==",
-		"clear_pending": true,
-		"replace_tag": "tagname",
-		"data": {
-			"message": "foobar",
-			"notification": {
-				"card": {
-					"summary": "yes",
-					"body": "hello",
-					"popup": true,
-					"persist": true,
-					"timestamp": 1407160197
-				}
-				"sound": "buzz.mp3",
-				"tag": "foo",
-				"vibrate": {
-					"pattern": [200, 100],
-					"repeat": 2
-				}
-				"emblem-counter": {
-					"count": 12,
-					"visible": true
-				}
-			}
-		}
-	}
-
-
-:appid: ID of the application that will receive the notification, as described in the client side documentation.
-:expire_on: Expiration date/time for this message, in `ISO8601 Extendend format <http://en.wikipedia.org/wiki/ISO_8601>`__
-:token: The token identifying the user+device to which the message is directed, as described in the client side documentation.
-:clear_pending: Discards all previous pending notifications. Usually in response to getting a "too-many-pending" error.
-:replace_tag: If there's a pending notification with the same tag, delete it before queuing this new one.
-:data: A JSON object.
-
-In this example, data is `what a helper would output <#helper-output-format>`__ but that's not necessarily the case.
-The content of the data field will be passed to the helper application which **has** to produce output in that format.
+.. include:: _common.txt
\ No newline at end of file