@hellotext/hellotext 2.5.6 → 2.5.8

package/src/api/push/identities.js

@@ -0,0 +1,42 @@
+import Hellotext from '../../hellotext'
+
+import { Configuration } from '../../core'
+import { Response } from '../response'
+
+class PushIdentitiesAPI {
+  static get endpoint() {
+    return Configuration.endpoint('public/push/identities')
+  }
+
+  static async create(data = {}) {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      keepalive: true,
+      headers: Hellotext.headers,
+      body: JSON.stringify({
+        ...data,
+        session: Hellotext.session,
+        origin: window.location.origin,
+      }),
+    })
+
+    return new Response(response.ok, response)
+  }
+
+  static async destroy(data = {}) {
+    const response = await fetch(this.endpoint, {
+      method: 'DELETE',
+      keepalive: true,
+      headers: Hellotext.headers,
+      body: JSON.stringify({
+        ...data,
+        session: Hellotext.session,
+        origin: window.location.origin,
+      }),
+    })
+
+    return new Response(response.ok, response)
+  }
+}
+
+export default PushIdentitiesAPI

package/src/core/configuration/push.js

@@ -0,0 +1,12 @@
+class Push {
+  static serviceWorkerUrl = null
+  static channelId = null
+
+  static assign(props) {
+    this.serviceWorkerUrl = props?.serviceWorkerUrl || null
+    this.channelId = props?.channelId || null
+    return this
+  }
+}
+
+export { Push }

package/src/core/configuration.js

@@ -2,6 +2,7 @@ import { Forms } from './configuration/forms'
 import { Locale } from './configuration/locale'
 import { Webchat } from './configuration/webchat'
 import { WhatsApp } from './configuration/whatsapp'
+import { Push } from './configuration/push'
 
 /**
  * @class Configuration
@@ -12,6 +13,7 @@ import { WhatsApp } from './configuration/whatsapp'
  * @property {Forms} [forms] - form configuration
  * @property {Webchat} [webchat] - webchat configuration
  * @property {WhatsApp} [whatsappWidget] - WhatsApp widget configuration
+ * @property {Push} [push] - push subscription configuration
  * @property {Locale} [locale] - locale configuration
  */
 class Configuration {
@@ -24,6 +26,7 @@ class Configuration {
   static forms = Forms
   static webchat = Webchat
   static whatsapp = WhatsApp
+  static push = Push
 
   /**
    *
@@ -47,6 +50,8 @@ class Configuration {
           this.webchat = Webchat.assign(value)
         } else if (key === 'whatsappWidget') {
           this.whatsapp = WhatsApp.assign(value)
+        } else if (key === 'push') {
+          this.push = Push.assign(value)
         } else {
           this[key] = value
         }

package/src/hellotext.js

@@ -6,6 +6,7 @@ import {
   Fingerprint,
   FormCollection,
   Page,
+  Push,
   Query,
   Session,
   User,
@@ -21,6 +22,7 @@ class Hellotext {
   static business
   static webchat
   static whatsapp
+  static push
 
   /**
    * initialize the module.
@@ -28,10 +30,13 @@ class Hellotext {
    * @param { Configuration } config
    */
   static async initialize(business, config = {}) {
+    this.push?.dispose()
+    this.push = null
+
     this.business = new Business(business)
     this.page = new Page()
 
-    Configuration.assign(config)
+    Configuration.assign({ push: {}, ...config })
     Session.initialize(this.page)
 
     this.forms = new FormCollection()
@@ -39,6 +44,15 @@ class Hellotext {
     this.query = new Query()
 
     const businessData = await this.business.hydrate()
+
+    if (config.push !== false && businessData?.push?.public_key && Push.supported) {
+      this.push = new Push(businessData.push)
+
+      this.push.initialize().catch(error => {
+        console.warn('Hellotext Push initialization failed:', error)
+      })
+    }
+
     const webchatConfig =
       config.webchat === false
         ? false

package/src/index.bundle.js

@@ -1,4 +1,3 @@
-import '../styles/index.css'
 import './index.js'
 
 import Hellotext from './index.js'

package/src/models/business.js

@@ -27,6 +27,7 @@ const stylesheetLoadTimeout = 10000
  * @property {String} [locale] - Default dashboard locale for the business.
  * @property {String} [style_url] - Stylesheet URL to inject for dashboard-managed surfaces.
  * @property {BusinessWebchat|null} [webchat] - Dashboard webchat defaults.
+ * @property {{public_key: String}|null} [push] - Public VAPID key for push subscriptions.
  * @property {String|Array<String>} [whitelist] - Domain whitelist configuration.
  * @property {String} [subscription] - Current business subscription tier.
  */

package/src/models/index.js

@@ -4,6 +4,7 @@ export { Fingerprint } from './fingerprint'
 export { Form } from './form'
 export { FormCollection } from './form_collection'
 export { Page } from './page'
+export { Push } from './push'
 export { Query } from './query'
 export { Session } from './session'
 export { User } from './user'

package/src/models/push.js

@@ -0,0 +1,397 @@
+import API from '../api'
+import { Configuration } from '../core'
+
+/**
+ * Manages browser Push subscriptions for Hellotext.
+ *
+ * @property {Promise<void>|null} ready - Initialization promise, available after initialize().
+ */
+class Push {
+  /**
+   * @param {Object} data - Push configuration from the business response.
+   * @param {String} data.public_key - Base64url-encoded VAPID public key.
+   */
+  constructor(data) {
+    this.publicKey = data.public_key
+    this.serviceWorkerUrl = Configuration.push.serviceWorkerUrl
+
+    this.channelId = Configuration.push.channelId
+    this.ready = null
+
+    this.registrationPromise = null
+
+    this.subscribePromise = null
+    this.unsubscribePromise = null
+
+    this.syncPromise = null
+
+    this.subscription = null
+
+    this.retryTimeout = null
+    this.retryAttempts = 0
+    this.disposed = false
+  }
+
+  /**
+   * Prepares the service worker and restores an existing subscription.
+   *
+   * @returns {Promise<void>}
+   */
+  initialize() {
+    this.ready = this.restoreSubscription()
+    return this.ready
+  }
+
+  /**
+   * Registers an existing Hellotext subscription with the server without prompting.
+   *
+   * @private
+   * @returns {Promise<void>}
+   */
+  async restoreSubscription() {
+    const registration = await this.getRegistration()
+    const subscription = await registration.pushManager.getSubscription()
+
+    if (this.disposed || this.unsubscribePromise || !subscription || !this.owns(subscription)) {
+      return
+    }
+
+    this.subscription = subscription
+    await this.sync()
+  }
+
+  /**
+   * Creates or reuses a Push subscription. Call from a user click handler.
+   * Concurrent calls share the same pending request.
+   *
+   * @returns {Promise<import('../api/response').Response|void>} Server registration response,
+   *   or no value when disposed.
+   *   Rejects when permission is denied or a browser or network operation fails.
+   */
+  subscribe() {
+    if (this.disposed) return Promise.resolve()
+    if (this.unsubscribePromise) return Promise.reject(new Error('Push unsubscribe is in progress'))
+    if (this.subscribePromise) return this.subscribePromise
+
+    // Request permission before awaiting worker readiness to retain the click's user activation.
+    const permission =
+      Notification.permission === 'default'
+        ? Notification.requestPermission()
+        : Promise.resolve(Notification.permission)
+
+    this.subscribePromise = this.createSubscription(permission).finally(() => {
+      this.subscribePromise = null
+    })
+
+    return this.subscribePromise
+  }
+
+  /**
+   * Waits for permission and worker readiness, then subscribes and registers with Hellotext.
+   *
+   * @private
+   * @param {Promise<NotificationPermission>} permission - Pending notification permission result.
+   * @returns {Promise<import('../api/response').Response|void>}
+   */
+  async createSubscription(permission) {
+    if ((await permission) !== 'granted') throw new Error('Push permission was not granted')
+
+    const registration = await this.getRegistration()
+    if (this.disposed) return
+
+    let subscription = await registration.pushManager.getSubscription()
+    if (this.disposed) return
+    if (subscription && !this.owns(subscription)) {
+      throw new Error('The existing Push subscription belongs to a different application')
+    }
+
+    subscription ||= await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: this.applicationServerKey,
+    })
+
+    if (this.disposed) return
+    this.subscription = subscription
+    return this.sync()
+  }
+
+  /**
+   * Disables the server identity and removes the browser subscription.
+   * Keeps the subscription when the server request fails so the caller can retry.
+   *
+   * @returns {Promise<import('../api/response').Response|null|void>} Server response, null when
+   *   no subscription exists, or no value when disposed. Rejects when a browser or network
+   *   operation fails.
+   */
+  unsubscribe() {
+    if (this.disposed) return Promise.resolve()
+    if (this.unsubscribePromise) return this.unsubscribePromise
+
+    this.clearRetryTimeout()
+    this.unsubscribePromise = this.removeSubscription().finally(() => {
+      this.unsubscribePromise = null
+    })
+
+    return this.unsubscribePromise
+  }
+
+  /**
+   * Finishes pending registration before disabling and removing the subscription.
+   *
+   * @private
+   * @returns {Promise<import('../api/response').Response|null|void>}
+   */
+  async removeSubscription() {
+    await this.ready?.catch(() => {})
+    await this.subscribePromise?.catch(() => {})
+    await this.syncPromise?.catch(() => {})
+
+    const registration = await this.getRegistration()
+    const subscription = (await registration.pushManager.getSubscription()) || this.subscription
+    if (this.disposed) return
+    if (!subscription) return null
+    if (!this.owns(subscription)) {
+      throw new Error('The existing Push subscription belongs to a different application')
+    }
+
+    this.subscription = subscription
+
+    const response = await API.pushIdentities.destroy({
+      subscription: subscription.toJSON(),
+    })
+    if (response.failed) return response
+    if (this.disposed) return
+
+    await subscription.unsubscribe()
+    this.subscription = null
+    this.clearRetryTimeout()
+
+    return response
+  }
+
+  /**
+   * Registers the current subscription, sharing any request already in progress.
+   *
+   * @private
+   * @returns {Promise<import('../api/response').Response|void>}
+   */
+  sync() {
+    if (this.disposed) return Promise.resolve()
+    if (this.syncPromise) return this.syncPromise
+
+    this.clearRetryTimeout()
+    this.syncPromise = this.registerIdentity().finally(() => {
+      this.syncPromise = null
+    })
+
+    return this.syncPromise
+  }
+
+  /**
+   * Sends the subscription to Hellotext and schedules a retry on failure.
+   *
+   * @private
+   * @returns {Promise<import('../api/response').Response>}
+   */
+  async registerIdentity() {
+    try {
+      const response = await API.pushIdentities.create({
+        subscription: this.subscription.toJSON(),
+        ...(this.channelId ? { channel_id: this.channelId } : {}),
+      })
+
+      if (response.succeeded) {
+        this.retryAttempts = 0
+      } else {
+        this.scheduleRetry()
+      }
+
+      return response
+    } catch (error) {
+      this.scheduleRetry()
+      throw error
+    }
+  }
+
+  /**
+   * Schedules up to three registration retries with increasing delays.
+   *
+   * @private
+   * @returns {void}
+   */
+  scheduleRetry() {
+    if (this.disposed || this.unsubscribePromise || this.retryTimeout || this.retryAttempts >= 3)
+      return
+
+    this.retryTimeout = setTimeout(() => {
+      this.retryTimeout = null
+      this.sync().catch(() => {})
+    }, 1000 * 2 ** this.retryAttempts)
+    this.retryAttempts += 1
+  }
+
+  /**
+   * Cancels a pending registration retry.
+   *
+   * @private
+   * @returns {void}
+   */
+  clearRetryTimeout() {
+    clearTimeout(this.retryTimeout)
+    this.retryTimeout = null
+  }
+
+  /**
+   * Stops registration retries and prevents further use of this instance.
+   *
+   * @returns {void}
+   */
+  dispose() {
+    this.disposed = true
+    this.clearRetryTimeout()
+  }
+
+  /**
+   * Whether this instance has a browser subscription, regardless of server registration.
+   *
+   * @returns {Boolean}
+   */
+  get subscribed() {
+    return !!this.subscription
+  }
+
+  /**
+   * Decodes the public key into the bytes expected by PushManager.subscribe().
+   *
+   * @private
+   * @returns {Uint8Array}
+   */
+  get applicationServerKey() {
+    const base64 = this.publicKey.replace(/-/g, '+').replace(/_/g, '/')
+    return Uint8Array.from(atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')), char =>
+      char.charCodeAt(0),
+    )
+  }
+
+  /**
+   * Checks whether a subscription uses this instance's public key.
+   *
+   * @private
+   * @param {PushSubscription} subscription - Browser subscription to check.
+   * @returns {Boolean}
+   */
+  owns(subscription) {
+    const key = subscription.options?.applicationServerKey
+    if (!key) return false
+
+    const actual = new Uint8Array(key)
+    const expected = this.applicationServerKey
+    return (
+      actual.length === expected.length && actual.every((value, index) => value === expected[index])
+    )
+  }
+
+  /**
+   * Gets the worker registration, sharing any pending lookup.
+   * Failed lookups can be retried by a later call.
+   *
+   * @private
+   * @returns {Promise<ServiceWorkerRegistration>}
+   */
+  getRegistration() {
+    if (!this.registrationPromise) {
+      this.registrationPromise = this.loadRegistration().catch(error => {
+        this.registrationPromise = null
+        throw error
+      })
+    }
+
+    return this.registrationPromise
+  }
+
+  /**
+   * Registers the configured worker or waits for the page's existing registration.
+   *
+   * @private
+   * @returns {Promise<ServiceWorkerRegistration>} An active registration.
+   *   Rejects if registration fails or the worker readiness wait times out.
+   */
+  async loadRegistration() {
+    if (this.serviceWorkerUrl) {
+      const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl)
+
+      if (registration.active && !registration.installing && !registration.waiting) {
+        // A returning visitor may have an older worker that does not include our Push handlers.
+        // Calling register() with the same URL can return that existing registration without
+        // checking whether the script served at that URL has changed since their last visit.
+        //
+        // If no replacement is already installing or waiting, explicitly check for an update
+        // before treating the active worker as ready. Awaiting update() completes the update
+        // check, but does not wait for a replacement worker to activate. The code below selects
+        // that replacement, if one was found, and waits for its activation before subscribing.
+        await registration.update()
+      }
+
+      const worker = registration.installing || registration.waiting || registration.active
+      if (worker?.state === 'activated') return registration
+
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(
+          () => finish(new Error('Push service worker did not become active')),
+          10000,
+        )
+
+        const finish = error => {
+          clearTimeout(timeout)
+          worker?.removeEventListener('statechange', changed)
+          error ? reject(error) : resolve(registration)
+        }
+
+        const changed = () => {
+          if (worker?.state === 'activated') finish()
+          if (worker?.state === 'redundant')
+            finish(new Error('Push service worker installation failed'))
+        }
+
+        worker?.addEventListener('statechange', changed)
+        changed()
+      })
+    }
+
+    // Reuse the service worker already registered for this page.
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error('Push service worker is not available')),
+        10000,
+      )
+      navigator.serviceWorker.ready.then(
+        registration => {
+          clearTimeout(timeout)
+          resolve(registration)
+        },
+        error => {
+          clearTimeout(timeout)
+          reject(error)
+        },
+      )
+    })
+  }
+
+  /**
+   * Whether the current page provides the browser APIs required for Push.
+   *
+   * @returns {Boolean}
+   */
+  static get supported() {
+    return (
+      typeof window !== 'undefined' &&
+      window.isSecureContext === true &&
+      typeof navigator !== 'undefined' &&
+      'serviceWorker' in navigator &&
+      typeof PushManager !== 'undefined' &&
+      typeof Notification !== 'undefined'
+    )
+  }
+}
+
+export { Push }

package/src/vanilla.js

@@ -1 +1,2 @@
-export default from './hellotext'
+import Hellotext from './hellotext'
+export default Hellotext

package/styles/index.css

@@ -1,30 +0,0 @@
-form[data-hello-form] {
-  position: relative;
-}
-
-form[data-hello-form] article [data-error-container] {
-  font-size: 0.875rem;
-  line-height: 1.25rem;
-  display: none;
-}
-
-form[data-hello-form] article:has(input:invalid) [data-error-container] {
-  display: block;
-}
-
-form[data-hello-form] [data-logo-container] {
-  display: flex;
-  justify-content: center;
-  align-items: flex-end;
-  position: absolute;
-  right: 1rem;
-  bottom: 1rem;
-}
-
-form[data-hello-form] [data-logo-container] small {
-  margin: 0 0.3rem;
-}
-
-form[data-hello-form] [data-logo-container] [data-hello-brand] {
-  width: 4rem;
-}