helpdesk-app-framework-sdk 1.0.0

package/lib/client.js

@@ -0,0 +1,422 @@
+/**
+ * BoldDesk App Framework - Client SDK
+ * Core client for cross-frame communication and data access
+ */
+
+import { queryParameters, when, isObject, isString, isArray, isFunction, debounce, deepClone } from './utils'
+import ContextAPI from './apis/context'
+import MetadataAPI from './apis/metadata'
+import { InstanceAPI } from './apis/instance'
+import RequestAPI from './apis/request'
+import NativePromise from 'native-promise-only'
+
+const Promise = window.Promise || NativePromise
+
+// Constants
+const IFRAME_SESSION_TIMEOUT = 5 * 60 * 1000
+const PROMISE_TIMEOUT = 10000
+const PROMISE_TIMEOUT_LONG = 5 * 60 * 1000
+
+class Client {
+  constructor (options = {}) {
+    this.origin = options.origin
+    this.appGuid = options.appGuid
+
+    // Initialize state
+    this._isReady = false
+    this._messageQueue = []
+    this._pendingRequests = {}
+    this._eventListeners = {}
+    this._requestId = 0
+    this._currentInstanceId = null
+
+    // Initialize APIs
+    this.context = new ContextAPI()
+    this.metadata = new MetadataAPI()
+    this.instance = new InstanceAPI(this)
+    this.request = new RequestAPI(this)
+
+    // Bind message handler
+    this._handleMessage = this._handleMessage.bind(this)
+    window.addEventListener('message', this._handleMessage)
+
+    // Register with host
+    this._registerWithHost()
+  }
+
+  /**
+   * Register app with BoldDesk host
+   * @private
+   */
+  _registerWithHost () {
+    this.postMessage('app.register', {
+      appGuid: this.appGuid,
+      version: '1.0.0'
+    })
+  }
+
+  /**
+   * Post message to host frame
+   * @param {string} action - Action name
+   * @param {*} data - Data payload
+   * @param {Function} callback - Optional callback
+   * @private
+   */
+  postMessage (action, data, callback) {
+    const requestId = ++this._requestId
+
+    if (callback && isFunction(callback)) {
+      this._pendingRequests[requestId] = callback
+    }
+
+    const message = {
+      type: 'baf.request',
+      action,
+      data,
+      requestId,
+      appGuid: this.appGuid,
+      timestamp: Date.now()
+    }
+
+    if (this._isReady) {
+      window.parent.postMessage(message, this.origin)
+    } else {
+      this._messageQueue.push(message)
+    }
+  }
+
+  /**
+   * Handle incoming messages from host
+   * @private
+   */
+  _handleMessage (event) {
+    if (event.origin !== this.origin) return
+
+    const message = event.data
+    if (!message || message.type !== 'baf.response') return
+
+    // Handle app registration
+    if (message.action === 'app.registered') {
+      this._isReady = true
+      this._processMessageQueue()
+      this._handleAppRegistered(message.data)
+      return
+    }
+
+    // Handle pending request responses
+    if (message.requestId && this._pendingRequests[message.requestId]) {
+      const callback = this._pendingRequests[message.requestId]
+      delete this._pendingRequests[message.requestId]
+      callback(message.data)
+      return
+    }
+
+    // Handle events
+    if (message.action === 'event') {
+      this._handleEvent(message.eventName, message.data)
+      return
+    }
+
+    // Handle instance messages
+    if (message.action === 'instance.message') {
+      this.instance._triggerMessage(message.channel, message.payload)
+      return
+    }
+
+    // Handle instance registration
+    if (message.action === 'instance.registered') {
+      this.instance._registerInstance(message.data)
+      return
+    }
+  }
+
+  /**
+   * Handle app registration from host
+   * @private
+   */
+  _handleAppRegistered (data) {
+    if (data.context) {
+      this.context._updateData(data.context)
+    }
+
+    if (data.metadata) {
+      this.metadata._updateData(data.metadata)
+    }
+
+    if (data.instanceId) {
+      this._currentInstanceId = data.instanceId
+    }
+
+    // Emit app.registered event
+    this._emitEvent('app.registered', {
+      context: this.context.getAll(),
+      metadata: this.metadata.getAll()
+    })
+  }
+
+  /**
+   * Process queued messages
+   * @private
+   */
+  _processMessageQueue () {
+    while (this._messageQueue.length > 0) {
+      const message = this._messageQueue.shift()
+      window.parent.postMessage(message, this.origin)
+    }
+  }
+
+  /**
+   * Get data from platform context
+   * Retrieves data like ticket info, user info, etc.
+   *
+   * @param {string|Array} path - Data path or array of paths
+   * @returns {Promise} Resolves with requested data
+   *
+   * @example
+   * // Get single value
+   * sdk.get('ticket.subject').then(data => {
+   *   console.log(data['ticket.subject']);
+   * });
+   *
+   * @example
+   * // Get multiple values
+   * sdk.get(['ticket.subject', 'ticket.requester.email']).then(data => {
+   *   console.log(data['ticket.subject']);
+   *   console.log(data['ticket.requester.email']);
+   * });
+   */
+  get (path) {
+    return new Promise((resolve, reject) => {
+      if (!path) {
+        return reject(new Error('Path is required for get() method'))
+      }
+
+      try {
+        const paths = isArray(path) ? path : [path]
+        this.postMessage('data.get', { paths }, (response) => {
+          if (response.error) {
+            reject(new Error(response.error))
+          } else {
+            resolve(response.data || {})
+          }
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Set data in platform context
+   * Updates or stores data like ticket properties, custom fields, etc.
+   *
+   * @param {string} path - Data path to update
+   * @param {*} value - Value to set
+   * @returns {Promise} Resolves when data is set
+   *
+   * @example
+   * sdk.set('ticket.subject', 'Issue Resolved').then(() => {
+   *   console.log('Subject updated');
+   * });
+   */
+  set (path, value) {
+    return new Promise((resolve, reject) => {
+      if (!path) {
+        return reject(new Error('Path is required for set() method'))
+      }
+
+      try {
+        this.postMessage('data.set', { path, value }, (response) => {
+          if (response.error) {
+            reject(new Error(response.error))
+          } else {
+            resolve()
+          }
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Register event listener
+   * Listen for platform events like data changes, UI events, etc.
+   *
+   * @param {string} eventName - Event name to listen for
+   * @param {Function} callback - Handler function
+   * @returns {void}
+   *
+   * @example
+   * sdk.on('ticket.updated', (ticket) => {
+   *   console.log('Ticket updated:', ticket);
+   * });
+   */
+  on (eventName, callback) {
+    if (!isString(eventName) || !isFunction(callback)) {
+      throw new Error('on() requires eventName (string) and callback (function)')
+    }
+
+    if (!this._eventListeners[eventName]) {
+      this._eventListeners[eventName] = []
+      this.postMessage('event.register', { eventName })
+    }
+
+    this._eventListeners[eventName].push(callback)
+  }
+
+  /**
+   * Unregister event listener
+   * Stop listening for platform events
+   *
+   * @param {string} eventName - Event name
+   * @param {Function} callback - Optional specific handler to remove
+   * @returns {void}
+   *
+   * @example
+   * sdk.off('ticket.updated');
+   */
+  off (eventName, callback) {
+    if (!this._eventListeners[eventName]) return
+
+    if (callback && isFunction(callback)) {
+      const index = this._eventListeners[eventName].indexOf(callback)
+      if (index > -1) {
+        this._eventListeners[eventName].splice(index, 1)
+      }
+    } else {
+      this._eventListeners[eventName] = []
+    }
+
+    // Unregister from host if no more listeners
+    if (this._eventListeners[eventName].length === 0) {
+      this.postMessage('event.unregister', { eventName })
+    }
+  }
+
+  /**
+   * Invoke a platform action or method
+   * Execute platform-exposed methods like opening modals, etc.
+   *
+   * @param {string} methodName - Method name to invoke
+   * @param {*} payload - Optional data for the method
+   * @returns {Promise} Resolves with method result
+   *
+   * @example
+   * sdk.invoke('modal.open', {
+   *   title: 'Contact Details',
+   *   content: 'View full contact information'
+   * });
+   */
+  invoke (methodName, payload) {
+    return new Promise((resolve, reject) => {
+      if (!isString(methodName)) {
+        return reject(new Error('Method name is required'))
+      }
+
+      try {
+        this.postMessage('action.invoke', { methodName, payload }, (response) => {
+          if (response.error) {
+            reject(new Error(response.error))
+          } else {
+            resolve(response.result)
+          }
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Trigger a custom event
+   * Emit custom events to the platform or other app components
+   *
+   * @param {string} eventName - Event name
+   * @param {*} data - Event data
+   * @returns {void}
+   *
+   * @example
+   * sdk.trigger('custom.notification', {
+   *   message: 'Data saved successfully'
+   * });
+   */
+  trigger (eventName, data) {
+    if (!isString(eventName)) {
+      throw new Error('Event name must be a string')
+    }
+
+    this.postMessage('event.trigger', { eventName, data })
+
+    // Also emit locally
+    this._emitEvent(eventName, data)
+  }
+
+  /**
+   * Check if capability or value exists
+   * Verify availability of features or data paths
+   *
+   * @param {string} name - Capability or value name
+   * @returns {Promise} Resolves with boolean
+   *
+   * @example
+   * sdk.has('ticket.custom_field_123').then(exists => {
+   *   if (exists) {
+   *     console.log('Custom field is available');
+   *   }
+   * });
+   */
+  has (name) {
+    return new Promise((resolve, reject) => {
+      if (!isString(name)) {
+        return reject(new Error('Name must be a string'))
+      }
+
+      try {
+        this.postMessage('capability.check', { name }, (response) => {
+          resolve(response.exists === true)
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Internal: Emit event to local listeners
+   * @private
+   */
+  _emitEvent (eventName, data) {
+    if (this._eventListeners[eventName]) {
+      this._eventListeners[eventName].forEach(callback => {
+        try {
+          callback(data)
+        } catch (error) {
+          console.error(`Error in event listener for ${eventName}:`, error)
+        }
+      })
+    }
+  }
+
+  /**
+   * Internal: Handle incoming event from host
+   * @private
+   */
+  _handleEvent (eventName, data) {
+    this._emitEvent(eventName, data)
+  }
+
+  /**
+   * Destroy client and clean up
+   * @returns {void}
+   */
+  destroy () {
+    window.removeEventListener('message', this._handleMessage)
+    this._eventListeners = {}
+    this._pendingRequests = {}
+    this._messageQueue = []
+    this._isReady = false
+  }
+}
+
+export default Client

package/lib/index.js

@@ -0,0 +1,99 @@
+/**
+ * BoldDesk App Framework SDK
+ * Main entry point for the BAF SDK library
+ */
+
+import Client from './client'
+import { queryParameters } from './utils'
+
+/**
+ * BAFClient - BoldDesk App Framework Client
+ *
+ * Main API for initializing and using the BoldDesk App Framework SDK
+ * in embedded app iframes.
+ *
+ * @example
+ * // Initialize the client
+ * const client = BAFClient.init((context) => {
+ *   console.log('App initialized');
+ *   console.log('Current module:', context.module);
+ *   console.log('User:', context.user.name);
+ * });
+ *
+ * // Use the client APIs
+ * client.get('ticket.subject').then(data => {
+ *   console.log(data['ticket.subject']);
+ * });
+ */
+
+const BAFClient = {
+  /**
+   * Initialize BAFClient and establish connection with BoldDesk host
+   *
+   * Call this function in your app's HTML to initialize the SDK.
+   * The client will automatically detect the app instance and establish
+   * two-way communication with the BoldDesk platform.
+   *
+   * @param {Function} callback - Optional callback function called when app is registered
+   *                             Receives context object with app information
+   * @param {Object} loc - Optional window location object (for testing)
+   * @returns {Client|boolean} Client instance or false if not in iframe
+   *
+   * @example
+   * // Basic usage
+   * const client = BAFClient.init();
+   *
+   * @example
+   * // With callback
+   * const client = BAFClient.init((context) => {
+   *   const currentUser = context.user;
+   *   console.log('Hello ' + currentUser.name);
+   * });
+   */
+  init: function (callback, loc) {
+    loc = loc || window.location
+
+    // Parse query/hash parameters
+    const queryParams = queryParameters(loc.search)
+    const hashParams = queryParameters(loc.hash)
+
+    // Required parameters for iframe app
+    const origin = queryParams.origin || hashParams.origin
+    const appGuid = queryParams.app_guid || hashParams.app_guid
+
+    // Validate required parameters
+    if (!origin || !appGuid) {
+      console.error(
+        'BAFClient.init(): Missing required parameters. ' +
+        'App must be loaded with "origin" and "app_guid" parameters.'
+      )
+      return false
+    }
+
+    // Create client instance
+    const client = new Client({ origin, appGuid })
+
+    // Register callback for app registration event
+    if (typeof callback === 'function') {
+      client.on('app.registered', function (context) {
+        callback.call(client, context)
+      })
+    }
+
+    return client
+  }
+}
+
+export default BAFClient
+
+// Also export Client for advanced usage
+export { default as Client } from './client'
+
+// Export utility functions
+export * from './utils'
+
+// Export APIs for direct access
+export { default as ContextAPI } from './apis/context'
+export { default as MetadataAPI } from './apis/metadata'
+export { InstanceAPI } from './apis/instance'
+export { default as RequestAPI } from './apis/request'

package/lib/utils.js

@@ -0,0 +1,202 @@
+/**
+ * BoldDesk App Framework - Utility Functions
+ * Provides helper functions for common operations
+ */
+
+/**
+ * Query string parser
+ * @param {string} queryString - Query string to parse (with or without ?)
+ * @returns {Object} Parsed parameters
+ */
+export function queryParameters (queryString) {
+  const params = {}
+  if (!queryString) return params
+
+  const cleaned = queryString.replace(/^\?|^#/, '')
+  if (!cleaned) return params
+
+  cleaned.split('&').forEach((pair) => {
+    const [key, value] = pair.split('=')
+    if (key) {
+      params[decodeURIComponent(key)] = value ? decodeURIComponent(value) : true
+    }
+  })
+
+  return params
+}
+
+/**
+ * Promise utility - when all conditions are met
+ * @param {Array} promises - Array of promises to wait for
+ * @returns {Promise}
+ */
+export function when (promises) {
+  return Promise.all(promises)
+}
+
+/**
+ * Type checking utilities
+ */
+export const isObject = (obj) => Object.prototype.toString.call(obj) === '[object Object]'
+export const isString = (str) => typeof str === 'string'
+export const isArray = (arr) => Array.isArray(arr)
+export const isFunction = (fn) => typeof fn === 'function'
+export const isUndefined = (val) => typeof val === 'undefined'
+export const isNull = (val) => val === null
+
+/**
+ * Debounce function - delays execution
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+export function debounce (fn, delay) {
+  let timeoutId
+  return function (...args) {
+    clearTimeout(timeoutId)
+    timeoutId = setTimeout(() => fn.apply(this, args), delay)
+  }
+}
+
+/**
+ * Throttle function - rate limits execution
+ * @param {Function} fn - Function to throttle
+ * @param {number} limit - Time limit in milliseconds
+ * @returns {Function} Throttled function
+ */
+export function throttle (fn, limit) {
+  let inThrottle
+  return function (...args) {
+    if (!inThrottle) {
+      fn.apply(this, args)
+      inThrottle = true
+      setTimeout(() => (inThrottle = false), limit)
+    }
+  }
+}
+
+/**
+ * Deep clone an object
+ * @param {*} obj - Object to clone
+ * @returns {*} Cloned object
+ */
+export function deepClone (obj) {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (obj instanceof Date) return new Date(obj.getTime())
+  if (obj instanceof Array) return obj.map(item => deepClone(item))
+  if (obj instanceof Object) {
+    const cloned = {}
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        cloned[key] = deepClone(obj[key])
+      }
+    }
+    return cloned
+  }
+}
+
+/**
+ * Merge objects deeply
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object
+ * @returns {Object} Merged object
+ */
+export function deepMerge (target, source) {
+  const result = { ...target }
+  for (const key in source) {
+    if (source.hasOwnProperty(key)) {
+      if (isObject(source[key]) && isObject(result[key])) {
+        result[key] = deepMerge(result[key], source[key])
+      } else {
+        result[key] = deepClone(source[key])
+      }
+    }
+  }
+  return result
+}
+
+/**
+ * UUID v4 generator
+ * @returns {string} Generated UUID
+ */
+export function generateUUID () {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+    const r = (Math.random() * 16) | 0
+    const v = c === 'x' ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}
+
+/**
+ * Validate manifest fields
+ * @param {Object} manifest - Manifest object to validate
+ * @returns {Object} Validation result { valid: boolean, errors: Array }
+ */
+export function validateManifest (manifest) {
+  const errors = []
+
+  if (!manifest.name) errors.push('Manifest field "name" is required')
+  if (!manifest.version) errors.push('Manifest field "version" is required')
+  if (!manifest.frameworkVersion) errors.push('Manifest field "frameworkVersion" is required')
+  if (!manifest.product) errors.push('Manifest field "product" is required')
+
+  if (manifest.developer) {
+    const dev = manifest.developer
+    if (!dev.name) errors.push('Developer field "name" is required')
+    if (!dev.contactEmail) errors.push('Developer field "contactEmail" is required')
+    if (!dev.supportEmail) errors.push('Developer field "supportEmail" is required')
+  } else {
+    errors.push('Manifest field "developer" is required')
+  }
+
+  if (!Array.isArray(manifest.trustedDomains)) {
+    errors.push('Manifest field "trustedDomains" must be an array')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  }
+}
+
+/**
+ * Parse widget locations to ensure valid format
+ * @param {Array} locations - Widget locations from manifest
+ * @returns {Array} Parsed locations
+ */
+export function parseWidgetLocations (locations) {
+  const validLocations = [
+    'desk.menu.left',
+    'desk.ticket.view.rightpanel',
+    'desk.contact.view.rightpanel',
+    'desk.contactgroup.view.rightpanel',
+    'desk.chat.view.rightpanel',
+    'desk.cti.widget'
+  ]
+
+  return locations.filter(loc => validLocations.includes(loc))
+}
+
+/**
+ * Validate URL format
+ * @param {string} url - URL to validate
+ * @returns {boolean} Is valid URL
+ */
+export function isValidUrl (url) {
+  try {
+    new URL(url)
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * Format error message for logging
+ * @param {string} context - Context of error
+ * @param {Error} error - Error object
+ * @returns {string} Formatted error message
+ */
+export function formatError (context, error) {
+  return `[${context}] ${error.message || error}`
+}