Merge branch 'release/0.2.x'

praekeltfoundation · Mar 18, 2015 · 14d51c0 · 14d51c0
2 parents 1931d86 + 8a4f2d8
commit 14d51c0
Show file tree

Hide file tree

Showing 11 changed files with 95 additions and 11 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -61,7 +61,7 @@
 # The short X.Y version.
 version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.12'
+release = '0.2.13'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/user.rst b/docs/user.rst
@@ -1,4 +1,7 @@
 User
 ====
 
+:class:`User` is used for short-term information about a user interacting with
+your application. Most of this information relates to the current interaction session with the user, and includes the user's current state, user's answers to previous states and language preference. While :class:`User` is used for short-term information about a user, a :class:`Contact` holds long-term information.
+
 .. autojs:: ../lib/user.js
diff --git a/lib/http/dummy.js b/lib/http/dummy.js
@@ -242,17 +242,24 @@ var HttpFixtures = Extendable.extend(function(self, opts) {
         :param object data:
             The properties of the fixture to be added.
             See :class:`HttpFixture`.
+
+        :returns:
+            The :class:`HttpFixture` that was created.
         */
         /**HttpFixtures.add(fixture)
         Adds an already initialised fixture to the fixture set.
 
         :param HttpFixture fixture:
-            The fixture to be added
+            The fixture to be added.
+
+        :returns:
+            The :class:`HttpFixture` that was passed in.
         */
         if (!(obj instanceof HttpFixture)) {
             obj = self.create(obj);
         }
         self.fixtures.push(obj);
+        return obj;
     };
 
     self.create = function(data) {

diff --git a/lib/interaction_machine.js b/lib/interaction_machine.js
@@ -122,7 +122,8 @@ var UnknownCommandEvent = IMEvent.extend(function(self, im, cmd) {
 });
 
 
-var ReplyEvent = IMEvent.extend(function(self, im, content, continue_session) {
+var ReplyEvent = IMEvent.extend(
+function(self, im, content, continue_session, helper_metadata) {
     /**class:ReplyEvent(im)
 
     Emitted after the interaction machine sends a reply to a message sent in by
@@ -142,6 +143,7 @@ var ReplyEvent = IMEvent.extend(function(self, im, content, continue_session) {
     IMEvent.call(self, 'reply', im);
     self.content = content;
     self.continue_session = continue_session;
+    self.helper_metadata = helper_metadata;
 });
 
 
@@ -670,6 +672,10 @@ var InteractionMachine = Eventable.extend(function(self, api, app) {
                 return self.state.continue_session();
             })
             .then(function(continue_session) {
+                return [continue_session, self.state.helper_metadata()];
+            })
+            .spread(function(continue_session, helper_metadata) {
+                opts.helper_metadata = helper_metadata;
                 opts.continue_session = continue_session;
                 self.user.in_session = continue_session;
 
@@ -697,11 +703,15 @@ var InteractionMachine = Eventable.extend(function(self, api, app) {
                 return self.api_request("outbound.reply_to", {
                     content: content,
                     in_reply_to: msg.message_id,
+                    helper_metadata: opts.helper_metadata,
                     continue_session: opts.continue_session
                 })
                 .then(function() {
                     return self.emit(new ReplyEvent(
-                        self, content, opts.continue_session));
+                        self,
+                        content,
+                        opts.continue_session,
+                        opts.helper_metadata));
                 });
             });
     };

diff --git a/lib/outbound/dummy.js b/lib/outbound/dummy.js
@@ -59,6 +59,10 @@ var DummyOutboundResource = DummyResource.extend(function(self, name, config) {
             msg.group = true;
         }
 
+        if (cmd.helper_metadata) {
+            msg.helper_metadata = cmd.helper_metadata;
+        }
+
         self.store.push(msg);
     };
 

diff --git a/lib/states/state.js b/lib/states/state.js
@@ -192,6 +192,11 @@ var State = Eventable.extend(function(self, name, opts) {
     :param boolean opts.continue_session:
         whether or not this is the last state in a session. Default is ``true``.
         May also be a function, which may return its result via a promise.
+    :param object opts.helper_metadata:
+        additional helper metadata to set on the reply sent to the user.
+        Primarily useful for setting voice metadata for messages destined to
+        be sent as voice calls. Default is `null`. May also be a function,
+        which may return its result via a promise.
     :param function opts.check:
         a function ``func(input)`` for validating a user's response, where
         ``input`` is the user's input. If a string or :class:`LazyText` is
@@ -216,6 +221,7 @@ var State = Eventable.extend(function(self, name, opts) {
     opts = _.defaults(opts || {}, {
         send_reply: true,
         continue_session: true,
+        helper_metadata: null,
         check: utils.functor(),
         events: {}
     });
@@ -225,6 +231,7 @@ var State = Eventable.extend(function(self, name, opts) {
     self.name = name;
     self.send_reply = utils.functor(opts.send_reply);
     self.continue_session = utils.functor(opts.continue_session);
+    self.helper_metadata = utils.functor(opts.helper_metadata);
     self.check = opts.check;
     self.events = opts.events;
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vumigo_v02",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Javascript toolkit and examples for Vumi's Javascript sandbox",
   "main": "lib/index.js",
   "scripts": {

diff --git a/test/test_http/test_dummy.js b/test/test_http/test_dummy.js
@@ -180,7 +180,7 @@ describe("http.dummy", function() {
             it("should support adding a fixture from data", function() {
                 var fixtures = new HttpFixtures();
 
-                fixtures.add({
+                var created_fixture = fixtures.add({
                     request: {url: 'http://example.com'},
                     response: {code: 201}
                 });
@@ -191,6 +191,7 @@ describe("http.dummy", function() {
                 assert(fixture instanceof HttpFixture);
                 assert.equal(fixture.request.url, 'http://example.com/');
                 assert.equal(fixture.responses[0].code, 201);
+                assert.strictEqual(created_fixture, fixture);
             });
 
             it("should support adding an already initialised fixture",
@@ -200,10 +201,11 @@ describe("http.dummy", function() {
                     request: {url: 'http://example.com'},
                     response: {code: 201}
                 });
-                fixtures.add(fixture);
+                var added_fixture = fixtures.add(fixture);
 
                 var request = new HttpRequest('get','http://example.com');
                 assert.equal(fixtures.filter(request)[0], fixture);
+                assert.strictEqual(added_fixture, fixture);
             });
         });
 

diff --git a/test/test_interaction_machine.js b/test/test_interaction_machine.js
@@ -43,6 +43,12 @@ describe("interaction_machine", function() {
             });
             app.states.add(end_state);
 
+            helper_meta_state = new EndState('helper_meta', {
+                text: test_utils.$('goodbye'),
+                helper_metadata: {'grass': 'green'},
+            });
+            app.states.add(helper_meta_state);
+
             return test_utils.make_im({
                 app: app,
                 msg: msg
@@ -600,12 +606,23 @@ describe("interaction_machine", function() {
                 });
             });
 
+            it("should use the state's helper metadata in the reply",
+            function() {
+                im.next_state.reset('helper_meta');
+                return im.reply(msg).then(function() {
+                    var reply = api.outbound.store[0];
+                    assert.deepEqual(reply.helper_metadata, {grass: 'green'});
+                });
+            });
+
             it("should emit an event after sending the reply", function() {
+                im.next_state.reset('helper_meta');
                 var p = im.once.resolved('reply').then(function(e) {
                     assert(api.outbound.store.length);
                     assert(e instanceof ReplyEvent);
-                    assert(!e.continue_session);
                     assert.equal(e.content, 'goodbye');
+                    assert(!e.continue_session);
+                    assert.deepEqual(e.helper_metadata, {grass: 'green'});
                 });
 
                 im.reply(msg);
@@ -882,7 +899,7 @@ describe("interaction_machine", function() {
                         assert.deepEqual(api.outbound.store, [{
                             content: 'goodbye',
                             in_reply_to: '2',
-                            continue_session: false
+                            continue_session: false,
                         }]);
                     });
                 });

diff --git a/test/test_outbound/test_dummy.js b/test/test_outbound/test_dummy.js
@@ -21,7 +21,8 @@ describe("outbound.dummy", function() {
                     return request('outbound.reply_to', {
                         content: 'foo',
                         in_reply_to: '123',
-                        continue_session: false
+                        continue_session: false,
+                        helper_metadata: {foo: 'bar'}
                     }).then(function(result) {
                         assert(result.success);
                         assert.equal(api.outbound.store.length, 1);
@@ -30,7 +31,8 @@ describe("outbound.dummy", function() {
                         assert.deepEqual(message, {
                             content: 'foo',
                             in_reply_to: '123',
-                            continue_session: false
+                            continue_session: false,
+                            helper_metadata: {foo: 'bar'}
                         });
                     });
                 });

diff --git a/test/test_states/test_state.js b/test/test_states/test_state.js
@@ -230,6 +230,38 @@ describe("states.state", function() {
             });
         });
 
+        describe(".helper_metadata", function() {
+            it("should be null by default", function() {
+                var state = new State('luke_the_state', {});
+
+                assert.strictEqual(state.helper_metadata(), null);
+            });
+
+            it("should be allowed to be a function", function() {
+                var state = new State('luke_the_state', {
+                    helper_metadata: function() {
+                        return {green: 'grows the holly'};
+                    }
+                });
+
+                assert.deepEqual(state.helper_metadata(), {
+                    green: 'grows the holly',
+                });
+            });
+
+            it("should be allowed to be a non-function", function() {
+                var state = new State('luke_the_state', {
+                    helper_metadata: {
+                        good: 'donkey',
+                    }
+                });
+
+                assert.deepEqual(state.helper_metadata(), {
+                    good: 'donkey',
+                });
+            });
+        });
+
         describe(".set_next_state", function() {
             it("should not change state undefined is given", function() {
                 assert(!im.next_state.exists());