🎹 Add new button types for Generic template

Author: stojanovic

docs/FB_TEMPLATE_MESSAGE_BUILDER.md

@@ -114,7 +114,12 @@ _Arguments_:
 | addBubble     | Yes      | title (string, required), subtitle (string) | `this` for chaining | Each Generic template can have 1 to 10 elements/bubbles, before you add anything to it. It requires element's title, but it can also accept element's subtitle |
 | addUrl        | No       | A valid URL                              | `this` for chaining | Adds an url to a current element, requires a valid URL, also requires `addBubble` to be added first |
 | addImage      | No       | A valid absolute URL                     | `this` for chaining | Adds an image to a current element, requires a valid URL, also requires `addBubble` to be added first |
-| addButton     | Yes      | title (string, required), value (required, string or a valid URL) | `this` for chaining | Adds a button to a current element, each button requires a title and a value, where value can be any string if you want `postback` type or a valid URL if you want it's type to be `web_url`, at least one button is required, and maximum 3 of them is allowed. It also requires `addBubble` to be added first |
+| addButton     | Yes, at least one of the button types | title (string, required), value (required, string or a valid URL) | `this` for chaining | Adds a button to a current element, each button requires a title and a value, where value can be any string if you want `postback` type or a valid URL if you want it's type to be `web_url`, at least one button is required, and maximum 3 of them is allowed. It also requires `addBubble` to be added first |
+| addCallButton | Yes, at least one of the button types | title (string, required), phoneNumber (required, string in '+1234...' format) | `this` for chaining | Adds a call button, check [official docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/call-button) for more info |
+| addShareButton | Yes, at least one of the button types | No args. | `this` for chaining | Adds a share button, check [official docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/share-button) for more info |
+| addBuyButton | Yes, at least one of the button types | title (string, required), value (required, string), paymentSummary (required, object, check [official docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buy-button) for more info) | `this` for chaining | Adds a share button, check [official docs](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buy-button) for more info |
+| addLoginButton | Yes, at least one of the button types | url (required, a valid URL) | `this` for chaining | Adds a login button, check [official docs](https://developers.facebook.com/docs/messenger-platform/account-linking/link-account) for more info |
+| addLogoutButton | Yes, at least one of the button types | No args. | `this` for chaining | Adds a logout button, check [official docs](https://developers.facebook.com/docs/messenger-platform/account-linking/unlink-account) for more info |
 | addQuickReply | No       | title (string, required, up to 20 characters), payload (string, required), up to 1000 characters | `this` for chaining | Facebook allows us to send up to 10 quick replies that will appear above the keyboard |
 | setNotificationType | No       | type (string, one of `REGULAR`, `SILENT_PUSH` or `NO_PUSH`) | `this` for chaining               | REGULAR will emit a sound/vibration and a phone notification; SILENT_PUSH will just emit a phone notification, NO_PUSH will not emit either
 | get           | Yes      | No args.                                 | Formatted JSON      | Get method is required and it returns a formatted JSON that is ready to be passed as a response to Facebook Messenger |

lib/facebook/format-message.js

@@ -253,7 +253,10 @@ class Generic extends FacebookTemplate {
     return this;
   }
 
-  addButton(title, value, type) {
+  addButtonByType(title, value, type, options) {
+    if (!title)
+      throw new Error('Button title cannot be empty');
+
     const bubble = this.getLastBubble();
 
     bubble.buttons = bubble.buttons || [];
@@ -264,44 +267,80 @@ class Generic extends FacebookTemplate {
     if (!title)
       throw new Error('Button title cannot be empty');
 
-    if (!value)
-      throw new Error('Button value is required');
-
     const button = {
-      title: title
+      title: title,
+      type: type || 'postback'
     };
 
-    if (isUrl(value)) {
-      button.type = 'web_url';
+    if (type === 'web_url') {
+      button.url = value;
+    } else if (type === 'account_link') {
+      delete button.title;
       button.url = value;
+    } else if (type === 'phone_number') {
+      button.payload = value;
+    } else if (type === 'payment') {
+      button.payload = value;
+      button.payment_summary = options.paymentSummary;
+    } else if (type === 'element_share' || type === 'account_unlink') {
+      delete button.title;
     } else {
       button.type = 'postback';
       button.payload = value;
     }
 
-    if (type) {
-      button.type = type;
-    }
-
     bubble.buttons.push(button);
 
     return this;
   }
 
+  addButton(title, value) {
+    // Keeping this to prevent breaking change
+    if (!title)
+      throw new Error('Button title cannot be empty');
+
+    if (!value)
+      throw new Error('Button value is required');
+
+    if (isUrl(value)) {
+      return this.addButtonByType(title, value, 'web_url');
+    } else {
+      return this.addButtonByType(title, value, 'postback');
+    }
+  }
+
+  addCallButton(title, phoneNumber) {
+    if (!/^\+[0-9]{4,20}$/.test(phoneNumber))
+      throw new Error('Call button value needs to be a valid phone number in following format: +1234567...');
+
+    return this.addButtonByType(title, phoneNumber, 'phone_number');
+  }
+
   addShareButton() {
-    const bubble = this.getLastBubble();
+    return this.addButtonByType('Share', null, 'element_share');
+  }
 
-    bubble.buttons = bubble.buttons || [];
+  addBuyButton(title, value, paymentSummary) {
+    if (!value)
+      throw new Error('Button value is required');
 
-    if (bubble.buttons.length === 3)
-      throw new Error('3 buttons are already added and that\'s the maximum');
-    const button = {
-      type: 'element_share'
-    };
+    if (typeof paymentSummary !== 'object')
+      throw new Error('Payment summary is required for buy button');
 
-    bubble.buttons.push(button);
+    return this.addButtonByType(title, value, 'payment', {
+      paymentSummary: paymentSummary
+    });
+  }
 
-    return this;
+  addLoginButton(url) {
+    if (!isUrl(url))
+      throw new Error('Valid URL is required for Login button');
+
+    return this.addButtonByType('Login', url, 'account_link');
+  }
+
+  addLogoutButton() {
+    return this.addButtonByType('Logout', null, 'account_unlink');
   }
 
   get() {

spec/facebook/facebook-format-message-spec.js

@@ -311,14 +311,84 @@ describe('Facebook format message', () => {
       expect(generic.bubbles[0].buttons[2].payload).toBe('v3');
     });
 
-    it('should override type when a type parameter is passed', () => {
-      generic
-        .addBubble('Test')
-        .addButton('b1', '+123456789', 'phone_number');
+    it('should throw an error if call button is added with wrong phone format', () => {
+      generic.addBubble('Test');
+      expect(() => generic.addCallButton('Title')).toThrowError('Call button value needs to be a valid phone number in following format: +1234567...');
+      expect(() => generic.addCallButton('Title', 123)).toThrowError('Call button value needs to be a valid phone number in following format: +1234567...');
+      expect(() => generic.addCallButton('Title', 'abc')).toThrowError('Call button value needs to be a valid phone number in following format: +1234567...');
+      expect(() => generic.addCallButton('Title', '+123')).toThrowError('Call button value needs to be a valid phone number in following format: +1234567...');
+    });
 
+    it('should add a call button', () => {
+      generic.addBubble('Test')
+        .addCallButton('Button 1', '+123456789');
+
+      expect(generic.bubbles[0].buttons.length).toBe(1);
+      expect(generic.bubbles[0].buttons[0].title).toBe('Button 1');
+      expect(generic.bubbles[0].buttons[0].payload).toBe('+123456789');
       expect(generic.bubbles[0].buttons[0].type).toBe('phone_number');
     });
 
+    it('should add a share button', () => {
+      generic.addBubble('Test')
+        .addShareButton();
+
+      expect(generic.bubbles[0].buttons.length).toBe(1);
+      expect(generic.bubbles[0].buttons[0].title).toBeUndefined();
+      expect(generic.bubbles[0].buttons[0].type).toBe('element_share');
+    });
+
+    it('should throw an error if all arguments are not provided for buy button', () => {
+      generic.addBubble('Test');
+
+      expect(() => generic.addBuyButton()).toThrowError('Button value is required');
+      expect(() => generic.addBuyButton('Title')).toThrowError('Button value is required');
+      expect(() => generic.addBuyButton('Title', 'PAYLOAD')).toThrowError('Payment summary is required for buy button');
+      expect(() => generic.addBuyButton('Title', 'PAYLOAD', 123)).toThrowError('Payment summary is required for buy button');
+      expect(() => generic.addBuyButton('Title', 'PAYLOAD', 'abc')).toThrowError('Payment summary is required for buy button');
+    });
+
+    it('should add a buy button', () => {
+      generic.addBubble('Test')
+        .addBuyButton('Buy', 'BUY_PAYLOAD', {
+          additionalOptions: true
+        });
+
+      expect(generic.bubbles[0].buttons.length).toBe(1);
+      expect(generic.bubbles[0].buttons[0].title).toBe('Buy');
+      expect(generic.bubbles[0].buttons[0].type).toBe('payment');
+      expect(generic.bubbles[0].buttons[0].payload).toBe('BUY_PAYLOAD');
+      expect(generic.bubbles[0].buttons[0].payment_summary).toEqual({
+        additionalOptions: true
+      });
+    });
+
+    it('should throw an error if url provided for login button is not valid', () => {
+      generic.addBubble('Test');
+
+      expect(() => generic.addLoginButton()).toThrowError('Valid URL is required for Login button');
+      expect(() => generic.addLoginButton('123')).toThrowError('Valid URL is required for Login button');
+    });
+
+    it('should add a login button', () => {
+      generic.addBubble('Test')
+        .addLoginButton('https://example.com');
+
+      expect(generic.bubbles[0].buttons.length).toBe(1);
+      expect(generic.bubbles[0].buttons[0].title).toBeUndefined();
+      expect(generic.bubbles[0].buttons[0].type).toBe('account_link');
+      expect(generic.bubbles[0].buttons[0].url).toBe('https://example.com');
+    });
+
+    it('should add a logout button', () => {
+      generic.addBubble('Test')
+        .addLogoutButton();
+
+      expect(generic.bubbles[0].buttons.length).toBe(1);
+      expect(generic.bubbles[0].buttons[0].title).toBeUndefined();
+      expect(generic.bubbles[0].buttons[0].type).toBe('account_unlink');
+    });
+
     it('should throw an error if you add more than 3 buttons', () => {
       generic
         .addBubble('Test');