@wxcc-desktop/sdk 1.2.11 → 1.2.13-dev

package/README.md

@@ -1,36 +1,412 @@
-# WXCC Desktop JavaScript SDK
+# WxCC Agent Desktop JS-API
+WxCC Agent Desktop JS API modules set
 
-WXCC Desktop JavaScript SDK is an npm package that allows you to request up-to-date information from the WXCC Desktop. Using the SDK, you can request information such as agent details, assigned tasks, particular task details, current browser locale, and authentication token for Single Sign-On (SSO) integration.
+## Root module (`Desktop`) includes:
+- Config module
+- I18N module
+- Actions module
+- Logger service module
+- ShortcutKey service module
+- AQM/Notifs **agent-contact** service layer API module for WxCC Agent Desktop.
+- AQM/Notifs **agent-state** service layer API module for WxCC Agent Desktop.
+- AQM/Notifs **dialer** service layer API module for WxCC Agent Desktop.
+- AQM/Notifs **screenpop** service layer API module for WxCC Agent Desktop.
 
-The SDK package allows you to
+### `Desktop` module
+Desktop module contains sub-modules:
 
-* request data to be passed to your widgets through properties and attributes
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
 
-* perform more complex operations by consuming and manipulating the system data inside your widget
+const {
+  config,
+  actions,
+  logger,
+  shortcutKey,
+  i18n,
 
-* subscribe to data arriving asynchronously
+  // AQM/Notifs modules
+  agentContact,
+  agentStateInfo,
+  dialer,
+  screenpop
+} = Desktop;
+```
+
+### `Desktop.logger` sub-module
+`Desktop.logger` sub-module is intended to create & maintain client-side logger's instances for third-party widgets.   
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+const logerOne = Desktop.logger.createLogger("for-service-one");
+const logerTwo = Desktop.logger.createLogger("for-service-two");
+    
+logerOne.info("Info test"); // console.log => "for-service-one: Info:test"
+logerTwo.warn("Warn test"); // console.log => "for-service-two: Warn:test"
+logerOne.error("Error test"); // console.log => "for-service-one: Error:test"
+
+// Start browser doanload logs as JSON for "for-service-one" prefix:
+Desktop.logger.browserDownloadLogsJson("for-service-one");
+
+// Start browser doanload logs as Test for "for-service-one" prefix:
+Desktop.logger.browserDownloadLogsText("for-service-one");
+
+// Get logs as Object's collection for "for-service-one" prefix:
+Desktop.logger.getLogsCollection("for-service-one");
+
+// Get logs as base64 encoded url ready to put into link href to initiate browser download as JSON for "for-service-one" prefix:
+Desktop.logger.getLogsJsonUrl("for-service-one");
+
+// Get logs as base64 encoded url ready to put into link href to initiate browser download as Text for "for-service-one" prefix:
+Desktop.logger.getLogsTextUrl("for-service-one");
+
+// Cleanup logs from LS for "for-service-one" prefix:
+Desktop.logger.cleanupPrefixedLogs("for-service-one");
+
+//...
+```
+
+### `Desktop.i18n` sub-module
+`Desktop.i18n` sub-module is intended to create & maintain client-side i18n & lit-element i18nMixin instances for third-party widgets.   
+
+Desktop.i18n instantinating object is described in:  https://www.i18next.com/overview/api#instance-creation
+
+i18n instance backend configuration described in: https://github.com/i18next/i18next-http-backend
+
+i18n instance languageDetector configuration described in: https://github.com/i18next/i18next-browser-languageDetector
+
+i18n instance init options are described in: https://www.i18next.com/overview/configuration-options
+
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+import { customElement, LitElement } from "lit-element";
+import { html } from "lit-html";
+
+
+//...
+
+/* 
+  Desktop.i18n service MAY NOT NEED to wait for Desktop.config.init({...}) was called for proper work
+*/
+
+// All CreateOotions for i18n are optional
+type CreateOptions = {
+  logger?: 
+      |  {
+           log(...args: any[]): void;
+           warn(...args: any[]): void;
+           error(...args: any[]): void;
+         }
+      |  ReturnType<typof Desktop.createLogger>;
+
+  backend?: Backend // import Backend from "i18next-http-backend";
+  languageDetector?: LanguageDetector // import LanguageDetector from "i18next-browser-languagedetector";
+};
+
+const i18n = Desktop.i18n.createInstance(createOptions?: CreateOptions) // returns instance described in https://www.i18next.com/overview/api#instance-creation
+const i18nMixin = Desktop.i18n.createMixin({ i18n /*Injecting i18n service instance into lit-element mixin */ })
+
+console.log(Desktop.i18n.DEFAULT_INIT_OPTIONS); // => i18n.init options that are using by AgentX by default
+
+// Init i18n with options to be able call "t" function translations
+if (!i18n.isInitialized) {
+  const initOptions = Desktop.i18n.getMergedInitOptions(Desktop.i18n.DEFAULT_INIT_OPTIONS || {}, {
+    defaultNS: "my-ns",
+    ns: ["my-ns"],
+    fallbackLng: "en",
+    backend: {
+      loadPath: "/.../path-to-locales/.../{{lng}}/{{ns}}.json"
+    }
+  });
+
+  i18n.init(initOptions).catch(err => console.log(err));
+}
+
+@customElement("my-awesome-component")
+export class MyAwesomeComponent extends i18nMixin(LitElement) {
+  render() {
+     return html`
+       <!-- i18nMixin will subscribe component tree updates on languages load & language change -->
+       <p>${i18n.t("my-ns:key1")}</p>
+       <!-- Component wrapped by i18nMixin can access t funcation via this.t(...) -->
+       <p>${this.t("my-ns:key2")}</p>`
+  }
+}
+
+```
+
+### `Desktop.actions` sub-module
+`Desktop.actions` sub-module is intended to make a calls into and/or get data from AgentX store.
+
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+
+// AgentX General Notifications:
+Desktop.actions.fireGeneralSilentNotification({...}) // => Fires silent notification in AgentX. One way
+
+// Unlike silent notification, autodismiss and acknowledge can have controlled responses, that may reflect in status, e.g.: 
+const [ status, reason, mode ]: [ Notifications.ItemMeta.Status, Notifications.ItemMeta.StatusChangeEventReason, Notifications.ItemMeta.Mode ] = await Desktop.actions.fireGeneralAutoDismissNotification({...}) // => Fires autudismiss notification in AgentX. Returns notification resolved status, reason, mode. NOTE: if AgentX notifications disabled - it will be converted into silent and reflected in "mode"  
+const [ status, reason, mode ]: [ Notifications.ItemMeta.Status, Notifications.ItemMeta.StatusChangeEventReason, Notifications.ItemMeta.Mode ] = await Desktop.actions.fireGeneralAcknowledgeNotification({...}) // => Fires acknowledge notification in AgentX. Returns notification resolved status, reason, mode. NOTE: if AgentX notifications disabled - it will be converted into silent and reflected in "mode"
+
+
+// AgentX Tasks:
+Desktop.actions.addCustomTask({...}) // => Add custom task object in AgentX store
+
+
+// AgentX Task Map:
+const currentTaskMap = await Desktop.actions.getTaskMap() // => Get current task map from AgentX store
+
+// AgentX Media Type Queues:
+const queue = await Desktop.actions.getMediaTypeQueue("telephony" | "social" | "email" | "chat") // => Get current media queue from AgentX store
+
+// AgentX AccessToken:
+const accessToken = await Desktop.actions.getToken() // => Get current accessToken from AgentX store
+
+// AgentX idleCodes:
+const idelCodes = await Desktop.actions.getIdleCodes() // => Get current idleCodes from AgentX store
+
+// AgentX wrapUpCodes:
+const wrapUpCodes = await Desktop.actions.getWrapUpCodes() // => Get current idleCodes from AgentX store
 
-Some events in the WXCC Desktop happen asynchronously. To subscribe to the asynchronous events and access data within the payload, you can add a listener. A few examples for asynchronous events are:
+// AgentX Maximize/Restore Dynamic Widget.
+const toggle = Desktop.actions.toggleMiximizeRestore(e: Event) // => maximize/restore widgets with toggle-maximize-restore.
 
-* New task offered
+```
+
+### `Desktop.shortcutKey` sub-module
+`Desktop.shortcutKey` sub-module is intended to register and call shortcut keys actions from widgets.   
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+console.log(Desktop.shortcutKey.DEFAULT_SHORTCUT_KEYS); //=> logs default shortcut keys
+
+console.log(Desktop.shortcutKey.MODIFIERS); //=> logs keys modifiers
+
+console.log(Desktop.shortcutKey.REGISTERED_KEYS); //=> logs registered keys
+
+console.log(Desktop.shortcutKey.getRegisteredKeys()); //=> logs service registered keys
+
+Desktop.shortcutKey.listenKeyPress((event) => {...}); //=> listen shortcuts key press
+
+Desktop.shortcutKey.listenKeyConflict((event) => {...}); //=> listen shortcuts key conflict
+
+Desktop.shortcutKey.listenConflictResolved(() => {}); //=> listen to shortcut key conflict resolved status
+
+Desktop.shortcutKey.register([ {...}, {...}, ... ]); //=> registering shortcut keys actions
+
+Desktop.shortcutKey.unregisterKeys('widget-one-example'); //=> used to unregister on unmount, widgetElement used for register should be provided
+
+//...
+```
+
+### `Desktop.agentContact` sub-module
+`Desktop.agentContact` sub-module is intended to make aqm requests and listen to notifs events related to agent-contact entity.
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+// List of available agent-contact aqm reqs:
+await Desktop.agentContact.accept({ ... });
+await Desktop.agentContact.consultAccept({ ... });
+await Desktop.agentContact.buddyAgents({ ... });
+await Desktop.agentContact.end({ ... });
+await Desktop.agentContact.consultEnd({ ... });
+await Desktop.agentContact.cancelCtq({ ... });
+await Desktop.agentContact.wrapup({ ... });
+await Desktop.agentContact.vteamTransfer({ ... });
+await Desktop.agentContact.blindTransfer({ ... });
+await Desktop.agentContact.hold({ ... });
+await Desktop.agentContact.unHold({ ... });
+await Desktop.agentContact.consult({ ... });
+await Desktop.agentContact.decline({ ... });
+await Desktop.agentContact.consultTransfer({ ... });
+await Desktop.agentContact.vteamList({ ... });
+await Desktop.agentContact.pauseRecording({ ... });
+await Desktop.agentContact.resumeRecording({ ... });
+
+// List of available agent-contact aqm notifs events:
+Desktop.agentContact.addEventListener("eAgentContact", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentContactAssigned", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentContactEnded", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentContactWrappedUp", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentOfferContact", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentOfferContactRona", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentOfferConsult", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentWrapup", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentContactHeld", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentContactUnHeld", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eCallRecordingStarted", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultCreated", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultConferenced", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultEnded", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentCtqCancelled", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsulting", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultFailed", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultEndFailed", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentCtqFailed", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentCtqCancelFailed", msg => console.log(msg));
+Desktop.agentContact.addEventListener("eAgentConsultConferenceEndFailed", msg => console.log(msg));
+
+// Module supports removing added listeners like:
+const listener = msg => console.log(msg);
+Desktop.agentContact.addEventListener("eAgentContact", listener);
+Desktop.agentContact.removeEventListener("eAgentContact", listener);
+
+// Module supports one-time added listeners like:
+Desktop.agentContact.addOnceEventListener("eAgentContact", listener);
+Desktop.agentContact.removeOnceEventListener("eAgentContact", listener);
+
+// Module supports removing all listeners like:
+Desktop.agentContact.removeAllEventListeners();
 
-* New task assigned
+```
+
+### `Desktop.agentStateInfo` sub-module
+`Desktop.agentStateInfo` sub-module is intended to listen for latest data updates for data:
+```Javascript
+type LatestInfoData = {
+  teamId?: string;
+  teamName?: string;
+  dn?: string;
+  status?: string;
+  subStatus?: string;
+  idleCodes?: Service.Aqm.Configs.Entity[];
+  wrapupCodes?: Service.Aqm.Configs.Entity[];
+  outDialRegex?: string;
+  isOutboundEnabledForTenant?: boolean;
+  isOutboundEnabledForAgent?: boolean;
+};
+```
 
-* Consult request created
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
 
-* Consult ended
+//...
 
-* Screen pop arrived and more
+/* 
+  Supposing Desktop.config.init() was called
+*/
 
-## Get Started
+// latestData inludes latest data fields 
+const latestData: LatestInfoData = Desktop.agentStateInfo.latestData;
 
-Run the following command in your project folder or using yarn:
+//...
+// Cumulative update event supported
+Desktop.agentStateInfo.addEventListener("updated", updatedList =>
+  console.log(updatedList) 
+ /* will log (in case of "dn", "status", "subStatus" fields were updated 
+  [
+    {
+      "name": "dn",
+      "value": "+12580258011",
+      "oldValue": ""
+    },
+    {
+      "name": "status",
+      "value": "LoggedIn",
+      "oldValue": "DefaultState"
+    },
+    {
+      "name": "subStatus",
+      "value": "Available",
+      "oldValue": ""
+    }
+  ] 
+*/
+);
+
+
+// List of available agent-state aqm reqs:
+await Desktop.agentStateInfo.stateChange({ ... });
+await Desktop.agentStateInfo.fetchAddressBooks({ ... });
 
 ```
-npm install @wxcc-desktop/sdk --save
-yarn add @wxcc-desktop/sdk
+
+### `Desktop.dialer` sub-module
+`Desktop.dialer` sub-module is intended to make aqm requests and listen to notifs events related to dialer entity.
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+// List of available agent-contact aqm reqs:
+await Desktop.dialer.startOutdial({ ... });
+
+// List of available agent-contact aqm notifs events:
+Desktop.dialer.addEventListener("eOutdialFailed", msg => console.log(msg));
+
+// Module supports removing added listeners like:
+const listener = msg => console.log(msg);
+Desktop.dialer.addEventListener("eOutdialFailed", listener);
+Desktop.dialer.removeEventListener("eOutdialFailed", listener);
+
+// Module supports one-time added listeners like:
+Desktop.dialer.addOnceEventListener("eOutdialFailed", listener);
+Desktop.dialer.removeOnceEventListener("eOutdialFailed", listener);
+
+// Module supports removing all listeners like:
+Desktop.dialer.removeAllEventListeners();
+
+```
+
+### `Desktop.screenpop` sub-module
+`Desktop.screenpop` sub-module is intended to make aqm requests and listen to notifs events related to screenpop entity.
+```Javascript
+import { Desktop } from "@wxcc-desktop/sdk";
+
+//...
+
+/* 
+  Supposing Desktop.config.init() was called
+*/
+
+// List of available agent-contact aqm notifs events:
+Desktop.screenpop.addEventListener("eScreenPop", msg => console.log(msg));
+
+// Module supports removing added listeners like:
+const listener = msg => console.log(msg);
+Desktop.screenpop.addEventListener("eScreenPop", listener);
+Desktop.screenpop.removeEventListener("eScreenPop", listener);
+
+// Module supports one-time added listeners like:
+Desktop.screenpop.addOnceEventListener("eScreenPop", listener);
+Desktop.screenpop.removeOnceEventListener("eScreenPop", listener);
+
+// Module supports removing all listeners like:
+Desktop.screenpop.removeAllEventListeners();
+
 ```
 
-## For detailed Info refer the below Link
+### Publishing the wxcc-desktop/js-api	
+For publishing internally to Internal Cisco Repository: `yarn npm:publish:internal`	
+For publishing to both Internal and public Repo : `yarn publish:external`	
 
-### [Webex Contact Center Desktop Docs](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cust_contact/contact_center/webexcc/developer_20/webexcc_b_20-desktop-developer-guide-/webexcc_m_30-javascript-sdk.html)
+`publish:all` responsible for publishing in both first internal repository and then to the external public repository npmjs