Merge pull request #354 from pzia/master

contacts.add API to register contacts

converse.js

@@ -5482,6 +5482,22 @@
                     return _transform(jids);
                 }
                 return _.map(jids, _transform);
+            },
+            'add': function (jid, name) {
+                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'));
+                });
+                return true;
             }
         },
         'chats': {

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
 ----------------