@zohodesk/i18n 1.0.0-beta.34 → 1.0.0-beta.35-murphy

package/docs/murphy/05-MURPHY_DESK_CLIENT_USAGE.md

@@ -0,0 +1,467 @@
+# Murphy Usage in Desk Client App
+
+## Overview
+
+The desk client application provides utility wrappers around Murphy to standardize error tracking and logging across the codebase.
+
+---
+
+## Utility Wrappers
+
+```
++-------------------------------------------------------------------+
+|  MURPHY UTILITY WRAPPERS                                           |
+|  Path: src/library/murphy/Utils.js                                 |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Error Tracking                                                    |
+|  +---------------------------------------------------------------+ |
+|  | deskCustomError(ErrorDetails, Message, envData)               | |
+|  | +-- Wraps murphy.error()                                      | |
+|  | +-- Adds custom tracking with murphy.addCustomTracking()      | |
+|  | +-- Supports Error objects or plain objects                   | |
+|  | +-- Handles error details formatting                          | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Application Logging                                               |
+|  +---------------------------------------------------------------+ |
+|  | deskLogger(info, details)                                     | |
+|  | +-- Wraps murphy.appLog()                                     | |
+|  | +-- Supports INFO, WARN, SEVERE levels                        | |
+|  | +-- Adds custom tags with _c_ prefix                          | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Performance Tracking                                              |
+|  +---------------------------------------------------------------+ |
+|  | endInitialLoadForMurphyPerformanceLogs()                      | |
+|  | startSoftNavigationMurphyPerformanceLogs({ fromUrl, toUrl })  | |
+|  | endSoftNavigationMurphyPerformanceLogs()                      | |
+|  | setClientMetricTags(value)                                    | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Presence Checks                                                   |
+|  +---------------------------------------------------------------+ |
+|  | isMurphyPresent()            -> Check if murphy exists        | |
+|  | isMurphyClientMetricsPresent() -> Check client metrics        | |
+|  | isMurphyClientMetricsInstalled() -> Check if installed        | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## 1. Presence Checks
+
+Before using Murphy, always check if it's available:
+
+```javascript
+// Path: src/library/murphy/Utils.js
+
+/**
+ * Check if Murphy SDK is loaded
+ */
+export function isMurphyPresent() {
+  return typeof murphy !== 'undefined';
+}
+
+/**
+ * Check if Murphy client metrics and telemetry are available
+ */
+export function isMurphyClientMetricsPresent() {
+  return (
+    isMurphyPresent() &&
+    typeof murphy.clientmetrics !== 'undefined' &&
+    typeof murphy.telemetry !== 'undefined'
+  );
+}
+
+/**
+ * Check if client metrics are installed
+ */
+export function isMurphyClientMetricsInstalled() {
+  return murphy.clientmetrics.isClientMetricsInstalled();
+}
+```
+
+---
+
+## 2. Error Tracking (deskCustomError)
+
+The primary function for reporting errors:
+
+```javascript
+/**
+ * Report custom error to Murphy
+ *
+ * @param {Object|Error} ErrorDetails - Error details or Error object
+ * @param {string} ErrorDisplayMessage - Human-readable error message
+ * @param {Object} envData - Additional environment/context data
+ */
+export function deskCustomError(ErrorDetails, ErrorDisplayMessage, envData) {
+  try {
+    if (isMurphyPresent()) {
+      let error;
+
+      // Handle Error objects
+      if (ErrorDetails instanceof Error) {
+        error = ErrorDetails;
+        error.message = ErrorDisplayMessage
+          ? `${ErrorDisplayMessage} - ${error.message}`
+          : error.message || 'An error occurred';
+      } else {
+        // Create new Error from message
+        error = new Error(ErrorDisplayMessage || 'An error occurred');
+      }
+
+      // Add tracking data
+      murphy && murphy.addCustomTracking(ErrorDetails);
+
+      // Build custom tags
+      let customErrorDataObj;
+      if (envData && typeof envData === 'object') {
+        const { errorType, ...errorData } = envData;
+        customErrorDataObj = {
+          customTags: {
+            errordetail: errorData,
+            errortype: errorType
+          },
+          preventClientGrouping: true
+        };
+      }
+
+      // Report to Murphy
+      murphy && murphy.error(error, undefined, customErrorDataObj);
+    }
+  } catch (error) {
+    console.error('error in desk custom error', error);
+  }
+}
+
+// Also exposed globally for error handling
+window._windowDeskCustomError = deskCustomError;
+```
+
+### Usage Examples
+
+```javascript
+// Basic error reporting
+deskCustomError(
+  { type: 'api_error', endpoint: '/tickets' },
+  'Failed to load tickets'
+);
+
+// With Error object
+try {
+  await saveTicket(data);
+} catch (err) {
+  deskCustomError(err, 'Ticket save failed', {
+    errorType: 'save_error',
+    ticketId: data.id
+  });
+}
+
+// HTTP error tracking (resource load failure)
+deskCustomError(
+  {
+    type: 'http',
+    category: 'xhr',
+    data: {
+      method: 'script',
+      url: loadFile,
+      status_code: 404
+    }
+  },
+  `Resource entry failed - ${JSON.stringify(loadFile)}`
+);
+```
+
+---
+
+## 3. Application Logging (deskLogger)
+
+Structured logging to Murphy:
+
+```javascript
+import { LOG_LEVEL } from './Constants';
+
+/**
+ * Send application logs to Murphy
+ *
+ * @param {string|Object} info - Log level/message or {type, message}
+ * @param {Object} details - Additional log details
+ */
+export function deskLogger(info, details) {
+  if (isMurphyPresent()) {
+    let type;
+    let message;
+
+    // Handle object input
+    if (info && typeof info === 'object') {
+      ({ type = LOG_LEVEL.INFO, message } = info);
+    } else {
+      type = LOG_LEVEL.INFO;
+      message = info;
+    }
+
+    // Build custom tags with _c_ prefix
+    let customTagObj = {};
+    if (details && typeof details === 'object') {
+      Object.keys(details).forEach((key) => {
+        customTagObj[`_c_${key}`] = details[key];
+      });
+    }
+
+    // Send to Murphy
+    message && murphy.appLog(type, message, customTagObj);
+  }
+}
+```
+
+### Log Levels
+
+```
++-----------------------------------+
+|  LOG_LEVEL Constants              |
++-----------------------------------+
+|  INFO   -> Informational logs    |
+|  WARN   -> Warning conditions    |
+|  SEVERE -> Critical errors       |
++-----------------------------------+
+```
+
+### Usage Examples
+
+```javascript
+// Simple info log
+deskLogger('User opened ticket detail view');
+
+// With details
+deskLogger('Ticket updated', {
+  ticketId: '12345',
+  field: 'status',
+  oldValue: 'Open',
+  newValue: 'Closed'
+});
+
+// With log level
+deskLogger(
+  { type: LOG_LEVEL.WARN, message: 'Slow API response detected' },
+  { endpoint: '/tickets', duration: 5000 }
+);
+```
+
+---
+
+## 4. Performance Tracking
+
+### Time to Interactive
+
+```javascript
+/**
+ * Mark end of initial load
+ */
+export function endInitialLoadForMurphyPerformanceLogs({
+  isCancelled = false,
+  ...value
+} = {}) {
+  if (!isMurphyClientMetricsPresent()) {
+    return;
+  }
+
+  const modeOfOperation = isCancelled
+    ? 'Cancelled_route_navigation'
+    : 'Success_route_navigation';
+
+  setClientMetricTags({
+    routerState: modeOfOperation,
+    ...value
+  });
+
+  murphy.clientmetrics.setTimeToInteractive();
+}
+```
+
+### Soft Navigation Tracking
+
+```javascript
+/**
+ * Start tracking route change
+ */
+export function startSoftNavigationMurphyPerformanceLogs({ fromUrl, toUrl }) {
+  if (!isMurphyClientMetricsPresent()) {
+    return;
+  }
+
+  murphy.clientmetrics.startSoftNavigation({
+    from_url: fromUrl,
+    to_url: toUrl,
+    from_normalised_url: fromUrl,
+    to_normalised_url: toUrl
+  });
+}
+
+/**
+ * End tracking route change
+ */
+export function endSoftNavigationMurphyPerformanceLogs(isCancelled = false) {
+  if (!isMurphyClientMetricsPresent()) {
+    return;
+  }
+
+  const modeOfOperation = isCancelled
+    ? 'Cancelled_route_navigation'
+    : 'Success_route_navigation';
+
+  setClientMetricTags({
+    routerState: modeOfOperation
+  });
+
+  murphy.clientmetrics.endSoftNavigation();
+}
+```
+
+### Usage in Router
+
+```javascript
+// In route change handler
+const handleRouteChange = (fromUrl, toUrl) => {
+  // Start tracking
+  startSoftNavigationMurphyPerformanceLogs({ fromUrl, toUrl });
+
+  // ... perform navigation ...
+
+  // End tracking when component mounts
+  endSoftNavigationMurphyPerformanceLogs();
+};
+```
+
+---
+
+## 5. Failed Resource Tracking
+
+Automatically tracks failed resource loads:
+
+```javascript
+/**
+ * Monkey-patches document.createElement to track failed resources
+ */
+export function failedResourcesEntry() {
+  if (isMurphyPresent()) {
+    document.createElement = (function (create) {
+      return function () {
+        var ret = create.apply(this, arguments);
+
+        if (
+          ret.tagName.toLowerCase() === 'script' ||
+          ret.tagName.toLowerCase() === 'link'
+        ) {
+          // Track load start time
+          ret.setAttribute('X-MURPHY-LOAD-START', Date.now());
+
+          // Handle successful load
+          ret.addEventListener('load', function () {
+            var loadFile = getLoadFile(this);
+            setCors(loadFile, ret);
+          });
+
+          // Handle failed load
+          ret.addEventListener('error', function () {
+            var loadFile = getLoadFile(this);
+
+            deskCustomError(
+              {
+                type: 'http',
+                category: 'xhr',
+                data: {
+                  method: this.tagName.toLowerCase(),
+                  url: loadFile,
+                  startimestamp: this.getAttribute('X-MURPHY-LOAD-START'),
+                  timeTaken: Date.now() - this.getAttribute('X-MURPHY-LOAD-START'),
+                  status_code: 404
+                }
+              },
+              `Resource entry failed - ${JSON.stringify(loadFile)}`
+            );
+          });
+        }
+
+        return ret;
+      };
+    })(document.createElement);
+  }
+}
+```
+
+---
+
+## Integration Pattern
+
+```
++-------------------------------------------------------------------+
+|  TYPICAL MURPHY INTEGRATION IN DESK CLIENT                         |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Component/Module Code                                             |
+|  +---------------------------------------------------------------+ |
+|  |  import {                                                     | |
+|  |    deskCustomError,                                           | |
+|  |    deskLogger                                                 | |
+|  |  } from 'library/murphy/Utils';                               | |
+|  |                                                                | |
+|  |  async function saveTicket(data) {                            | |
+|  |    try {                                                      | |
+|  |      deskLogger('Saving ticket', { ticketId: data.id });      | |
+|  |      await api.save(data);                                    | |
+|  |      deskLogger('Ticket saved successfully');                 | |
+|  |    } catch (error) {                                          | |
+|  |      deskCustomError(error, 'Failed to save ticket', {        | |
+|  |        errorType: 'api_error',                                | |
+|  |        ticketId: data.id                                      | |
+|  |      });                                                       | |
+|  |      throw error;                                             | |
+|  |    }                                                          | |
+|  |  }                                                            | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Summary
+
+```
++-------------------------------------------------------------------+
+|  DESK CLIENT MURPHY USAGE SUMMARY                                  |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Error Tracking:                                                   |
+|  +-- deskCustomError()  -> Standardized error reporting           |
+|  +-- Supports Error objects and plain objects                     |
+|  +-- Adds custom tags and tracking data                           |
+|                                                                    |
+|  Logging:                                                          |
+|  +-- deskLogger()       -> Structured application logs            |
+|  +-- Supports INFO, WARN, SEVERE levels                           |
+|  +-- Auto-prefixes custom tags with _c_                           |
+|                                                                    |
+|  Performance:                                                      |
+|  +-- Initial load tracking                                        |
+|  +-- Soft navigation tracking                                     |
+|  +-- Resource load failure detection                              |
+|                                                                    |
+|  Safety:                                                           |
+|  +-- All functions check isMurphyPresent() first                  |
+|  +-- Graceful degradation if Murphy unavailable                   |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Related Documents
+
+- [04-MURPHY_FRONTEND_INIT.md](./04-MURPHY_FRONTEND_INIT.md) - Frontend initialization
+- [06-MURPHY_I18N_INTEGRATION.md](./06-MURPHY_I18N_INTEGRATION.md) - i18n library integration
+- [07-MURPHY_WHY_I18N_APPROACH.md](./07-MURPHY_WHY_I18N_APPROACH.md) - Why i18n approach