Throw exception if no jid or invalid jid. (#354)

converse.js

@@ -5484,7 +5484,15 @@
                 return _.map(jids, _transform);
             },
             'add': function (jid, name) {
-                if (jid.indexOf('@') < 0) return false;
+                if (typeof jid === "undefined") {
+                    throw new Error("Error: you must supply a jid");
+                }
+                if (typeof jid !== "string") {
+                    throw new Error('Error: wrong attribute (jid) type. Must be string.');
+                }
+                if (jid.indexOf('@') < 0) {
+                    throw new Error('Error: invalid jid ');
+                }
                 name = _.isEmpty(name)? jid: name;
                 converse.connection.roster.add(jid, name, [], function (iq) {
                     converse.connection.roster.subscribe(jid, null, converse.xmppstatus.get('fullname'));

docs/source/development.rst

@@ -272,6 +272,19 @@ The returned roster contact objects have these attributes:
 | vcard_updated  | When last the buddy's VCard was updated.                                                                                             |
 +----------------+--------------------------------------------------------------------------------------------------------------------------------------+
 
+add
+~~~
+
+Add a contact.
+
+Provide the JID of the contact you want to add::
+
+    converse.chats.add('buddy@example.com')
+    
+You may also provide the fullname. If not present, we use the jid as fullname.
+
+    converse.chats.add('buddy@example.com', 'Buddy')
+
 "chats" grouping
 ----------------