helpdesk-app-framework-sdk 1.0.0

package/lib/apis/metadata.js

@@ -0,0 +1,156 @@
+/**
+ * BoldDesk App Framework - Metadata API
+ * Provides app and installation metadata information
+ */
+
+class MetadataAPI {
+  constructor (data = {}) {
+    this._data = {
+      appId: data.appId || null,
+      installationId: data.installationId || null,
+      appName: data.appName || null,
+      version: data.version || null,
+      locations: data.locations || [],
+      hasAllBrandAccess: data.hasAllBrandAccess || false,
+      hasReadAccess: data.hasReadAccess || false,
+      hasWriteAccess: data.hasWriteAccess || false,
+      isActive: data.isActive || false,
+      isEnabled: data.isEnabled || false,
+      frameworkVersion: data.frameworkVersion || null,
+      installDate: data.installDate || null,
+      developer: data.developer || null
+    }
+  }
+
+  /**
+   * Get app ID
+   * @returns {string} App ID
+   */
+  getAppId () {
+    return this._data.appId
+  }
+
+  /**
+   * Get installation ID (unique per installation)
+   * @returns {string} Installation ID
+   */
+  getInstallationId () {
+    return this._data.installationId
+  }
+
+  /**
+   * Get app name
+   * @returns {string} App name
+   */
+  getAppName () {
+    return this._data.appName
+  }
+
+  /**
+   * Get app version
+   * @returns {string} Version (semantic versioning)
+   */
+  getVersion () {
+    return this._data.version
+  }
+
+  /**
+   * Get widget locations where app is available
+   * @returns {Array} Array of location strings
+   */
+  getLocations () {
+    return Array.from(this._data.locations)
+  }
+
+  /**
+   * Check if app has all brand access
+   * @returns {boolean}
+   */
+  hasAllBrandAccess () {
+    return this._data.hasAllBrandAccess === true
+  }
+
+  /**
+   * Check if app has read permissions
+   * @returns {boolean}
+   */
+  hasReadAccess () {
+    return this._data.hasReadAccess === true
+  }
+
+  /**
+   * Check if app has write permissions
+   * @returns {boolean}
+   */
+  hasWriteAccess () {
+    return this._data.hasWriteAccess === true
+  }
+
+  /**
+   * Check if app is active
+   * @returns {boolean}
+   */
+  isActive () {
+    return this._data.isActive === true
+  }
+
+  /**
+   * Check if app is enabled
+   * @returns {boolean}
+   */
+  isEnabled () {
+    return this._data.isEnabled === true
+  }
+
+  /**
+   * Get framework version
+   * @returns {string} Framework version
+   */
+  getFrameworkVersion () {
+    return this._data.frameworkVersion
+  }
+
+  /**
+   * Get installation date
+   * @returns {string} ISO date string
+   */
+  getInstallDate () {
+    return this._data.installDate
+  }
+
+  /**
+   * Get developer information
+   * @returns {Object} Developer object
+   */
+  getDeveloper () {
+    return this._data.developer ? JSON.parse(JSON.stringify(this._data.developer)) : null
+  }
+
+  /**
+   * Check if location is supported
+   * @param {string} location - Location to check
+   * @returns {boolean}
+   */
+  isLocationSupported (location) {
+    return this._data.locations.includes(location)
+  }
+
+  /**
+   * Get all metadata
+   * @returns {Object} Full metadata object
+   */
+  getAll () {
+    return JSON.parse(JSON.stringify(this._data))
+  }
+
+  /**
+   * Update metadata (internal use)
+   * @param {Object} data - New data to merge
+   * @internal
+   */
+  _updateData (data) {
+    Object.assign(this._data, data)
+  }
+}
+
+export default MetadataAPI

package/lib/apis/request.js

@@ -0,0 +1,196 @@
+/**
+ * BoldDesk App Framework - Request API (Proxy)
+ * Provides secure HTTP request capability through server-side proxy
+ */
+
+import { isObject, isString, isValidUrl } from '../utils'
+
+class RequestAPI {
+  constructor (client) {
+    this._client = client
+  }
+
+  /**
+   * Make an HTTP request through BoldDesk proxy
+   * Prevents exposing sensitive data and handles CORS automatically
+   *
+   * @param {Object} options - Request options
+   * @param {string} options.url - Full URL of the API endpoint (required)
+   * @param {string} options.method - HTTP method (GET, POST, PUT, DELETE, PATCH) (required)
+   * @param {Object} options.headers - HTTP headers (optional)
+   * @param {Object} options.params - Query parameters (optional)
+   * @param {Object|string} options.body - Request payload (optional, for POST/PUT/PATCH)
+   * @param {number} options.timeout - Request timeout in ms (optional, default: 15000, max: 30000)
+   * @param {boolean} options.autoRetry - Auto-retry on 429/5xx (optional, default: true)
+   * @param {number} options.maxRetry - Max retry attempts (optional, default: 3)
+   * @param {number} options.retryDelay - Delay between retries in ms (optional, default: 1000)
+   *
+   * @returns {Promise} Resolves with response object { status, statusText, headers, data, body }
+   *
+   * @example
+   * // Simple GET request
+   * sdk.request({
+   *   url: 'https://api.example.com/users',
+   *   method: 'GET'
+   * }).then(response => console.log(response.data))
+   *
+   * @example
+   * // POST with data
+   * sdk.request({
+   *   url: 'https://api.example.com/tickets',
+   *   method: 'POST',
+   *   headers: { 'Content-Type': 'application/json' },
+   *   body: JSON.stringify({ subject: 'Help needed', priority: 'high' })
+   * })
+   *
+   * @example
+   * // Using secure settings placeholders
+   * sdk.request({
+   *   url: 'https://api.example.com/secure-endpoint',
+   *   method: 'GET',
+   *   headers: { 'Authorization': 'Bearer {{setting.api_key}}' }
+   * })
+   */
+  request (options = {}) {
+    return new Promise((resolve, reject) => {
+      try {
+        // Validate required options
+        if (!options.url) {
+          throw new Error('Request URL is required')
+        }
+
+        if (!options.method) {
+          throw new Error('Request method is required')
+        }
+
+        // Validate URL format
+        if (!isValidUrl(options.url)) {
+          throw new Error('Invalid URL format: ' + options.url)
+        }
+
+        // Validate method
+        const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
+        const method = (options.method || 'GET').toUpperCase()
+        if (!validMethods.includes(method)) {
+          throw new Error('Invalid HTTP method: ' + method)
+        }
+
+        // Build request object
+        const requestObj = {
+          url: options.url,
+          method,
+          headers: options.headers || {},
+          timeout: Math.min(options.timeout || 15000, 30000),
+          autoRetry: options.autoRetry !== false,
+          maxRetry: options.maxRetry || 3,
+          retryDelay: options.retryDelay || 1000
+        }
+
+        // Add query parameters if provided
+        if (options.params && isObject(options.params)) {
+          const params = new URLSearchParams(options.params)
+          const separator = options.url.includes('?') ? '&' : '?'
+          requestObj.url += separator + params.toString()
+        }
+
+        // Add body for POST/PUT/PATCH
+        if (['POST', 'PUT', 'PATCH'].includes(method)) {
+          if (options.body) {
+            requestObj.body = isObject(options.body)
+              ? JSON.stringify(options.body)
+              : options.body
+          }
+        }
+
+        // Send request through BoldDesk proxy
+        this._client.postMessage('request.send', requestObj, (response) => {
+          if (response.error) {
+            reject(new Error(response.error))
+          } else {
+            resolve(response)
+          }
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Make a GET request
+   * @param {string} url - URL endpoint
+   * @param {Object} options - Additional options
+   * @returns {Promise}
+   */
+  get (url, options = {}) {
+    return this.request({
+      ...options,
+      url,
+      method: 'GET'
+    })
+  }
+
+  /**
+   * Make a POST request
+   * @param {string} url - URL endpoint
+   * @param {*} body - Request body
+   * @param {Object} options - Additional options
+   * @returns {Promise}
+   */
+  post (url, body, options = {}) {
+    return this.request({
+      ...options,
+      url,
+      method: 'POST',
+      body
+    })
+  }
+
+  /**
+   * Make a PUT request
+   * @param {string} url - URL endpoint
+   * @param {*} body - Request body
+   * @param {Object} options - Additional options
+   * @returns {Promise}
+   */
+  put (url, body, options = {}) {
+    return this.request({
+      ...options,
+      url,
+      method: 'PUT',
+      body
+    })
+  }
+
+  /**
+   * Make a PATCH request
+   * @param {string} url - URL endpoint
+   * @param {*} body - Request body
+   * @param {Object} options - Additional options
+   * @returns {Promise}
+   */
+  patch (url, body, options = {}) {
+    return this.request({
+      ...options,
+      url,
+      method: 'PATCH',
+      body
+    })
+  }
+
+  /**
+   * Make a DELETE request
+   * @param {string} url - URL endpoint
+   * @param {Object} options - Additional options
+   * @returns {Promise}
+   */
+  delete (url, options = {}) {
+    return this.request({
+      ...options,
+      url,
+      method: 'DELETE'
+    })
+  }
+}
+
+export default RequestAPI