@hellotext/hellotext 2.4.52 → 2.5.0

package/src/core/configuration/whatsapp.js

@@ -0,0 +1,143 @@
+/**
+ * @typedef {'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'} Placement
+ * @description Valid placements for the WhatsApp widget.
+ */
+
+/**
+ * @enum {Placement}
+ */
+const placements = {
+  TOP_LEFT: 'top-left',
+  TOP_RIGHT: 'top-right',
+  BOTTOM_LEFT: 'bottom-left',
+  BOTTOM_RIGHT: 'bottom-right'
+}
+
+/**
+ * @typedef {Object} WhatsAppWidgetAppearance
+ * @property {Object} [launcher] - Launcher appearance overrides.
+ * @property {string} [launcher.iconUrl] - Image URL used for the launcher icon.
+ */
+
+/**
+ * @class WhatsApp
+ * @classdesc Configuration for the standalone WhatsApp widget.
+ * @property {String} id - The id of the WhatsApp widget.
+ * @property {String} container - The container to append the widget to, defaults to 'body'.
+ * @property {Placement} placement - The placement of the widget, defaults to 'bottom-right'.
+ * @property {String} number - WhatsApp number used by the widget link.
+ * @property {String} body - Prefilled WhatsApp compose text.
+ * @property {WhatsAppWidgetAppearance} appearance - Appearance overrides.
+ */
+class WhatsApp {
+  static _id
+  static _container = 'body'
+  static _placement = 'bottom-right'
+  static _appearance = {}
+  static _number = null
+  static _body = null
+
+  static set id(value) {
+    this._id = value
+  }
+
+  static get id() {
+    return this._id
+  }
+
+  static set container(value) {
+    this._container = value
+  }
+
+  static get container() {
+    return this._container
+  }
+
+  static set placement(value) {
+    if (!Object.values(placements).includes(value)) {
+      throw new Error(`Invalid placement value: ${value}`)
+    }
+
+    this._placement = value
+  }
+
+  static get placement() {
+    return this._placement
+  }
+
+  static get appearance() {
+    return this._appearance
+  }
+
+  static set appearance(value) {
+    if (!this.isPlainObject(value)) {
+      throw new Error('Appearance must be an object')
+    }
+
+    Object.entries(value).forEach(([key, nestedValue]) => {
+      if (key !== 'launcher') {
+        throw new Error(`Invalid appearance property: ${key}`)
+      }
+
+      if (!this.isPlainObject(nestedValue)) {
+        throw new Error(`Appearance ${key} must be an object`)
+      }
+
+      Object.entries(nestedValue).forEach(([nestedKey, propertyValue]) => {
+        if (nestedKey !== 'iconUrl') {
+          throw new Error(`Invalid appearance launcher property: ${nestedKey}`)
+        }
+
+        if (propertyValue == null) {
+          return
+        }
+
+        if (typeof propertyValue !== 'string') {
+          throw new Error(`Invalid appearance ${key}.${nestedKey} value: ${propertyValue}`)
+        }
+      })
+    })
+
+    this._appearance = value
+  }
+
+  static get number() {
+    return this._number
+  }
+
+  static set number(value) {
+    if (value != null && typeof value !== 'string') {
+      throw new Error(`Invalid number value: ${value}`)
+    }
+
+    this._number = value
+  }
+
+  static get body() {
+    return this._body
+  }
+
+  static set body(value) {
+    if (value != null && typeof value !== 'string') {
+      throw new Error(`Invalid body value: ${value}`)
+    }
+
+    this._body = value
+  }
+
+  static assign(props) {
+    if (props) {
+      Object.entries(props).forEach(([key, value]) => {
+        this[key] = value
+      })
+    }
+
+    return this
+  }
+
+  static isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+  }
+}
+
+export { WhatsApp }

package/src/core/configuration.js

@@ -1,6 +1,7 @@
 import { Forms } from './configuration/forms'
 import { Locale } from './configuration/locale'
 import { Webchat } from './configuration/webchat'
+import { WhatsApp } from './configuration/whatsapp'
 
 /**
  * @class Configuration
@@ -10,6 +11,7 @@ import { Webchat } from './configuration/webchat'
  * @property {String} [session] - session id
  * @property {Forms} [forms] - form configuration
  * @property {Webchat} [webchat] - webchat configuration
+ * @property {WhatsApp} [whatsappWidget] - WhatsApp widget configuration
  * @property {Locale} [locale] - locale configuration
  */
 class Configuration {
@@ -21,6 +23,7 @@ class Configuration {
 
   static forms = Forms
   static webchat = Webchat
+  static whatsapp = WhatsApp
 
   /**
    *
@@ -42,6 +45,8 @@ class Configuration {
           this.forms = Forms.assign(value)
         } else if (key === 'webchat') {
           this.webchat = Webchat.assign(value)
+        } else if (key === 'whatsappWidget') {
+          this.whatsapp = WhatsApp.assign(value)
         } else {
           this[key] = value
         }

package/src/core/index.js

@@ -1,4 +1,5 @@
 export { Configuration } from './configuration'
 export { Locale } from './configuration/locale'
 export { Webchat } from './configuration/webchat'
+export { WhatsApp } from './configuration/whatsapp'
 export { default as Event } from './event'

package/src/hellotext.js

@@ -1,7 +1,17 @@
 import { Configuration, Event } from './core'
 
 import API, { Response, keepaliveFor } from './api'
-import { Business, Fingerprint, FormCollection, Page, Query, Session, User, Webchat } from './models'
+import {
+  Business,
+  Fingerprint,
+  FormCollection,
+  Page,
+  Query,
+  Session,
+  User,
+  Webchat,
+  WhatsAppWidget,
+} from './models'
 
 import { NotInitializedError } from './errors'
 
@@ -10,6 +20,7 @@ class Hellotext {
   static forms
   static business
   static webchat
+  static whatsapp
 
   /**
    * initialize the module.
@@ -18,25 +29,35 @@ class Hellotext {
    */
   static async initialize(business, config = {}) {
     this.business = new Business(business)
+    this.page = new Page()
 
     Configuration.assign(config)
-    Session.initialize()
+    Session.initialize(this.page)
 
-    this.page = new Page()
     this.forms = new FormCollection()
 
     this.query = new Query()
 
     const businessData = await this.business.hydrate()
-    const webchatConfig = config.webchat === false ?
-      false :
-      this.mergeWebchatConfig((businessData && businessData.webchat) || {}, config.webchat || {})
-
-    const hasExplicitBehaviourOverride = (
+    const webchatConfig =
+      config.webchat === false
+        ? false
+        : this.mergeWebchatConfig(
+            (businessData && businessData.webchat) || {},
+            config.webchat || {},
+          )
+    const whatsappConfig =
+      config.whatsappWidget === false
+        ? false
+        : this.mergeWhatsAppConfig(
+            (businessData && businessData.whatsapp) || {},
+            config.whatsappWidget || {},
+          )
+
+    const hasExplicitBehaviourOverride =
       config.webchat &&
       config.webchat !== false &&
       Object.prototype.hasOwnProperty.call(config.webchat, 'behaviour')
-    )
     Configuration.webchat.behaviourOverride = hasExplicitBehaviourOverride
 
     if (webchatConfig && webchatConfig.id) {
@@ -44,6 +65,11 @@ class Hellotext {
       this.webchat = await Webchat.load(webchatConfig.id)
     }
 
+    if (whatsappConfig && whatsappConfig.id) {
+      Configuration.whatsapp.assign(whatsappConfig)
+      this.whatsapp = await WhatsAppWidget.load(whatsappConfig.id)
+    }
+
     if (typeof MutationObserver !== 'undefined') {
       this.forms.collectExistingFormsOnPage()
     }
@@ -53,6 +79,10 @@ class Hellotext {
     return this.deepMergePlainObjects(dashboardConfig, localConfig)
   }
 
+  static mergeWhatsAppConfig(dashboardConfig, localConfig) {
+    return this.deepMergePlainObjects(dashboardConfig, localConfig)
+  }
+
   static deepMergePlainObjects(base, override) {
     const result = { ...base }
 
@@ -147,11 +177,7 @@ class Hellotext {
     })
 
     if (response.succeeded) {
-      User.remember(
-        externalId,
-        options.source,
-        fingerprint,
-      )
+      User.remember(externalId, options.source, fingerprint)
     }
 
     return response

package/src/models/index.js

@@ -9,3 +9,4 @@ export { Session } from './session'
 export { User } from './user'
 export { UTM } from './utm'
 export { Webchat } from './webchat'
+export { WhatsAppWidget } from './whatsapp_widget'

package/src/models/session.js

@@ -1,16 +1,24 @@
 import { Configuration } from '../core'
 import { Cookies } from './cookies'
+import { Page } from './page'
 import { Query } from './query'
 import API from '../api'
 
 class Session {
   static #session
   static #query
+  static #page
 
   static get session() {
     return this.#session
   }
 
+  static get ackPayload() {
+    return {
+      utm_params: this.#page?.utmParams || {},
+    }
+  }
+
   static set session(value) {
     const oldSession = Cookies.get('hello_session')
 
@@ -22,14 +30,15 @@ class Session {
     }
 
     if (!Cookies.get('hello_session_ack_at')) {
-      API.acks.send()
+      API.acks.send(this.ackPayload)
       Cookies.set('hello_session_ack_at', new Date().toISOString())
     }
 
     return this.#session
   }
 
-  static initialize() {
+  static initialize(page = new Page()) {
+    this.#page = page
     this.#query = new Query()
 
     this.session = this.#query.session || Configuration.session || Cookies.get('hello_session')

package/src/models/webchat.js

@@ -30,6 +30,7 @@ class Webchat {
     }
 
     this.containerToAppendTo.appendChild(this.data.html)
+    this.markCoexistingWidgets()
     this.mounted = true
 
     return true
@@ -69,6 +70,16 @@ class Webchat {
   get stylesheetLoaded() {
     return Business.waitForStylesheet(Business.latestStylesheet)
   }
+
+  markCoexistingWidgets() {
+    const webchat = this.data.html
+    const whatsapp = document.querySelector('.hellotext--whatsapp-widget')
+
+    if (!webchat || !whatsapp) return
+
+    webchat.classList.add('hellotext--with-whatsapp-widget')
+    whatsapp.classList.add('hellotext--with-webchat')
+  }
 }
 
 export { Webchat }

package/src/models/whatsapp_widget.js

@@ -0,0 +1,68 @@
+import { Configuration } from '../core'
+
+import API from '../api'
+import { Business } from './business'
+
+class WhatsAppWidget {
+  static async load(id) {
+    const widget = new WhatsAppWidget({
+      id,
+      html: await API.whatsappWidgets.get(id)
+    })
+
+    widget.rendered = widget.render()
+
+    return widget
+  }
+
+  constructor(data) {
+    this.data = data
+    this.mounted = false
+    this.rendered = Promise.resolve(false)
+  }
+
+  async render() {
+    if (!this.data.html) return false
+
+    const container = this.containerToAppendTo
+    if (!container) {
+      console.warn(`Hellotext WhatsApp widget was not mounted because the container ${Configuration.whatsapp.container} was not found.`)
+      return false
+    }
+
+    if (!await this.stylesheetLoaded) {
+      console.warn('Hellotext WhatsApp widget was not mounted because its stylesheet failed to load.')
+      return false
+    }
+
+    container.appendChild(this.data.html)
+    this.markCoexistingWidgets()
+    this.mounted = true
+
+    return true
+  }
+
+  get containerToAppendTo() {
+    try {
+      return document.querySelector(Configuration.whatsapp.container)
+    } catch (_) {
+      return null
+    }
+  }
+
+  get stylesheetLoaded() {
+    return Business.waitForStylesheet(Business.latestStylesheet)
+  }
+
+  markCoexistingWidgets() {
+    const webchat = document.querySelector('.hellotext--webchat:not(.hellotext--whatsapp-widget)')
+    const whatsapp = this.data.html
+
+    if (!webchat || !whatsapp) return
+
+    webchat.classList.add('hellotext--with-whatsapp-widget')
+    whatsapp.classList.add('hellotext--with-webchat')
+  }
+}
+
+export { WhatsAppWidget }