Document `_converse.ChatBox.prototype.sendMessage` as an API method

Until now, we've only been explicitly documenting the `_converse.api`
namespace and only considered the methods under it as forming the API
contract (which determines how we do semver releases).

It appears as if we've reached a point where trying to keep everything
under the `_converse.api` namespace no longer makes sense. Certain
methods are applicable to particular models and trying to shoehorn them
into the `_converse.api` namespace seems clunky and non-intuitive.

I've therefore decided to slightly refactor `sendMessage` to let it take
two simple parameters and to document it with JSDoc so that it's
presented as an API method, albeit only available on a chat model.

updates #1496
updates #1504

CHANGES.md

@@ -11,6 +11,7 @@
 - New config setting [locked_muc_domain](https://conversejs.org/docs/html/configuration.html#locked-muc-domain)
 - New config setting [show_client_info](https://conversejs.org/docs/html/configuration.html#show-client-info)
 - Render inline images served over HTTP if Converse itself was loaded on an unsecured (HTTP) page.
+- Document new API method [sendMessage](https://conversejs.org/docs/html/api/-_converse.ChatBox.html#sendMessage)
 - #1149: With `xhr_user_search_url`, contact requests are not being sent out
 - #1213: Switch roster filter input and icons
 - #1327: fix False mentions positives in URLs and Email addresses
@@ -24,7 +25,6 @@
 - #1501: Don't prompt for a reason if [auto_join_on_invite](https://conversejs.org/docs/html/configuration.html#auto-join-on-invite) is `true`
 
 
-
 ## 4.1.2 (2019-02-22)
 
 - Updated translations: af, cz, de, es, he, it, nl, nl_BE, pt_BR, zh_CN

dist/converse.js

@@ -50312,7 +50312,7 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins
         _converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].addClass('disabled', textarea);
         textarea.setAttribute('disabled', 'disabled');
 
-        if (this.parseMessageForCommands(message) || (await this.model.sendMessage(this.model.getOutgoingMessageAttributes(message, spoiler_hint)))) {
+        if (this.parseMessageForCommands(message) || (await this.model.sendMessage(message, spoiler_hint))) {
           hint_el.value = '';
           textarea.value = '';
           _converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].removeClass('correcting', textarea);
@@ -51598,6 +51598,8 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins
         /**
          * Retrieves the controlbox view.
          *
+         * @method _converse.api.controlbox.get
+         *
          * @example
          * const view = _converse.api.controlbox.get();
          *
@@ -56723,11 +56725,10 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_0__["default"].plugins
         }
       },
 
-      async sendMessage(attrs) {
-        const _converse = this.__super__._converse,
-              __ = _converse.__;
-
-        if (this.get('omemo_active') && attrs.message) {
+      async sendMessage(text, spoiler_hint) {
+        if (this.get('omemo_active') && text) {
+          const _converse = this.__super__._converse;
+          const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
           attrs['is_encrypted'] = true;
           attrs['plaintext'] = attrs.message;
 
@@ -62134,6 +62135,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
       model: _converse.Message,
       comparator: 'time'
     });
+    /**
+     * The "_converse.ChatBox" namespace
+     *
+     * @namespace _converse.ChatBox
+     * @memberOf _converse
+     */
+
     _converse.ChatBox = Backbone.Model.extend({
       defaults() {
         return {
@@ -62489,12 +62497,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
         });
       },
 
-      sendMessage(attrs) {
-        /* Responsible for sending off a text message.
-         *
-         *  Parameters:
-         *    (Message) message - The chat message
-         */
+      /**
+       * Responsible for sending off a text message inside an ongoing
+       * chat conversation.
+       *
+       * @method _converse.ChatBox#sendMessage
+       * @memberOf _converse.ChatBox
+       *
+       * @param {String} text - The chat message text
+       * @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
+       *
+       * @example
+       * const chat = _converse.api.chats.get('buddy1@example.com');
+       * chat.sendMessage('hello world');
+       */
+      sendMessage(text, spoiler_hint) {
+        const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
         let message = this.messages.findWhere('correcting');
 
         if (message) {
@@ -63130,7 +63148,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
          *
          * @method _converse.api.chats.get
          * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
-         * @returns {Backbone.Model}
+         * @returns {_converse.ChatBox}
          *
          * @example
          * // To return a single chat, provide the JID of the contact you're chatting with in that chat:

spec/messages.js

@@ -2495,23 +2495,12 @@
             await test_utils.openAndEnterChatRoom(_converse, 'room', 'muc.example.com', 'dummy');
             const view = _converse.chatboxviews.get('room@muc.example.com');
 
-            const attrs = {
-                'id': _converse.connection.getUniqueId(),
-                'origin_id': _converse.connection.getUniqueId(),
-                'fullname': 'dummy',
-                'references': [],
-                'from': _converse.connection.jid,
-                'sender': 'me',
-                'time': moment().format(),
-                'message': 'Hello world',
-                'is_spoiler': false,
-                'type': 'groupchat' 
-            }
-            view.model.sendMessage(attrs);
+            view.model.sendMessage('hello world');
             await test_utils.waitUntil(() => _converse.api.chats.get().length);
             await test_utils.waitUntil(() => view.model.messages.length === 1);
-            expect(view.model.messages.at(0).get('stanza_id')).toBeUndefined();
-            expect(view.model.messages.at(0).get('origin_id')).toBe(attrs.origin_id);
+            const msg = view.model.messages.at(0);
+            expect(msg.get('stanza_id')).toBeUndefined();
+            expect(msg.get('origin_id')).toBe(msg.get('origin_id'));
 
             const stanza = u.toStanza(`
                 <message xmlns="jabber:client"
@@ -2522,14 +2511,14 @@
                     <stanza-id xmlns="urn:xmpp:sid:0"
                                id="5f3dbc5e-e1d3-4077-a492-693f3769c7ad"
                                by="room@muc.example.com"/>
-                    <origin-id xmlns="urn:xmpp:sid:0" id="${attrs.origin_id}"/>
+                    <origin-id xmlns="urn:xmpp:sid:0" id="${msg.get('origin_id')}"/>
                 </message>`);
             spyOn(view.model, 'updateMessage').and.callThrough();
             _converse.connection._dataRecv(test_utils.createRequest(stanza));
             await test_utils.waitUntil(() => view.model.updateMessage.calls.count() === 1);
             expect(view.model.messages.length).toBe(1);
             expect(view.model.messages.at(0).get('stanza_id room@muc.example.com')).toBe("5f3dbc5e-e1d3-4077-a492-693f3769c7ad");
-            expect(view.model.messages.at(0).get('origin_id')).toBe(attrs.origin_id);
+            expect(view.model.messages.at(0).get('origin_id')).toBe(msg.get('origin_id'));
             done();
         }));
 

src/converse-chatview.js

@@ -872,7 +872,7 @@ converse.plugins.add('converse-chatview', {
                 u.addClass('disabled', textarea);
                 textarea.setAttribute('disabled', 'disabled');
                 if (this.parseMessageForCommands(message) ||
-                    await this.model.sendMessage(this.model.getOutgoingMessageAttributes(message, spoiler_hint))) {
+                    await this.model.sendMessage(message, spoiler_hint)) {
 
                     hint_el.value = '';
                     textarea.value = '';

src/converse-controlbox.js

@@ -664,6 +664,8 @@ converse.plugins.add('converse-controlbox', {
                 /**
                  * Retrieves the controlbox view.
                  *
+                 * @method _converse.api.controlbox.get
+                 *
                  * @example
                  * const view = _converse.api.controlbox.get();
                  *

src/converse-omemo.js

@@ -343,11 +343,10 @@ converse.plugins.add('converse-omemo', {
                 }
             },
 
-            async sendMessage (attrs) {
-                const { _converse } = this.__super__,
-                      { __ } = _converse;
-
-                if (this.get('omemo_active') && attrs.message) {
+            async sendMessage (text, spoiler_hint) {
+                if (this.get('omemo_active') && text) {
+                    const { _converse } = this.__super__;
+                    const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
                     attrs['is_encrypted'] = true;
                     attrs['plaintext'] = attrs.message;
                     try {

src/headless/converse-chatboxes.js

@@ -219,6 +219,12 @@ converse.plugins.add('converse-chatboxes', {
         });
 
 
+        /**
+         * The "_converse.ChatBox" namespace
+         *
+         * @namespace _converse.ChatBox
+         * @memberOf _converse
+         */
         _converse.ChatBox = Backbone.Model.extend({
             defaults () {
                 return {
@@ -506,12 +512,22 @@ converse.plugins.add('converse-chatboxes', {
                 });
             },
 
-            sendMessage (attrs) {
-                /* Responsible for sending off a text message.
-                 *
-                 *  Parameters:
-                 *    (Message) message - The chat message
-                 */
+            /**
+             * Responsible for sending off a text message inside an ongoing
+             * chat conversation.
+             *
+             * @method _converse.ChatBox#sendMessage
+             * @memberOf _converse.ChatBox
+             *
+             * @param {String} text - The chat message text
+             * @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
+             *
+             * @example
+             * const chat = _converse.api.chats.get('buddy1@example.com');
+             * chat.sendMessage('hello world');
+             */
+            sendMessage (text, spoiler_hint) {
+                const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
                 let message = this.messages.findWhere('correcting')
                 if (message) {
                     const older_versions = message.get('older_versions') || [];
@@ -1097,7 +1113,7 @@ converse.plugins.add('converse-chatboxes', {
                  *
                  * @method _converse.api.chats.get
                  * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
-                 * @returns {Backbone.Model}
+                 * @returns {_converse.ChatBox}
                  *
                  * @example
                  * // To return a single chat, provide the JID of the contact you're chatting with in that chat:

src/headless/dist/converse-headless.js

@@ -40407,6 +40407,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
       model: _converse.Message,
       comparator: 'time'
     });
+    /**
+     * The "_converse.ChatBox" namespace
+     *
+     * @namespace _converse.ChatBox
+     * @memberOf _converse
+     */
+
     _converse.ChatBox = Backbone.Model.extend({
       defaults() {
         return {
@@ -40762,12 +40769,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
         });
       },
 
-      sendMessage(attrs) {
-        /* Responsible for sending off a text message.
-         *
-         *  Parameters:
-         *    (Message) message - The chat message
-         */
+      /**
+       * Responsible for sending off a text message inside an ongoing
+       * chat conversation.
+       *
+       * @method _converse.ChatBox#sendMessage
+       * @memberOf _converse.ChatBox
+       *
+       * @param {String} text - The chat message text
+       * @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
+       *
+       * @example
+       * const chat = _converse.api.chats.get('buddy1@example.com');
+       * chat.sendMessage('hello world');
+       */
+      sendMessage(text, spoiler_hint) {
+        const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
         let message = this.messages.findWhere('correcting');
 
         if (message) {
@@ -41403,7 +41420,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
          *
          * @method _converse.api.chats.get
          * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
-         * @returns {Backbone.Model}
+         * @returns {_converse.ChatBox}
          *
          * @example
          * // To return a single chat, provide the JID of the contact you're chatting with in that chat: