@adobe/acc-js-sdk 1.1.6 → 1.1.7

package/.eslintrc.js

@@ -12,5 +12,6 @@ module.exports = {
         "ecmaVersion": 12
     },
     "rules": {
+        "indent": ["error", 2],
     }
 };

package/CHANGELOG.md

@@ -5,6 +5,13 @@ This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like
 
 # Changelog 
 
+## Version 1.1.7
+_2022_08_30_
+
+* New listener interface to be notified of internal events from the SDK. Can be used to integrate with observability frameworks. See the "Observers" section of the README file.
+* Experimental file upload feature. Will require server-side changes to work, and is currently limited to be used with browsers only.
+
+
 ## Version 1.1.6
 _2022_08_19_
 

package/README.md

@@ -1111,6 +1111,34 @@ The `soapCall` parameter is a `SoapMethodCall` object which describes the SOAP c
 * `response` is a string containing the XML result of the SOAP call if the call was successful. It may be undefined if the call was not executed yet or if the call failed
 
 
+In version 1.1.7, the observer interface is extended to listen for internal events of the SDK. The `event` function of the observer, if it exist will be call for each SDK event with 2 parameters: the event itself, and for some events, a parent event. For instance a SOAP response event will have the SOAP request for a parent event.
+```js
+client.registerObserver({
+    event: (event, parentEvent) => { ... },
+});
+```
+
+The following events are available
+
+| event name | comment / description |
+|----|----|
+| SDK//logon | A client logs on |
+| SDK//logoff | A client logs off |
+| CACHE//stats | Regularly sends stats about internal caches |
+| SOAP//request | The SDK executes a SOAP request |
+| SOAP//response | The SDK processes the successful response of a SOAP request |
+| SOAP//failure | A SOAP request failed |
+| HTTP//request | The SDK executes an HTTP request |
+| HTTP//response | The SDK processes the successful response of an HTTP request |
+| HTTP//failure | An HTTP request failed |
+| CACHE_REFRESHER//start | A cache auto-refresher starts |
+| CACHE_REFRESHER//stop | A cache auto-refresher stops |
+| CACHE_REFRESHER//tick | A cache auto-refresh occurs |
+| CACHE_REFRESHER//loggedOff | The cache auto-refresh was triggered whereas the client was logged off |
+| CACHE_REFRESHER//error | The cache auto-refresh failed. Auto-refresh will continue. |
+| CACHE_REFRESHER//abort | The cache auto-refresh failed because the server does not support it. Auto-refresh will stop. |
+| CACHE_REFRESHER//response | The server responded to an auto-refresh request |
+
 # Configuration
 
 ## Tracking all SOAP calls
@@ -1528,8 +1556,6 @@ var event = await query.executeQuery();
 console.log(`>> Event: ${JSON.stringify(event)}`);
 ```
 
-
-
 # Application
 
 The `application` object can be obtained from a client, and will mimmic the Campaing `application` object (https://docs.adobe.com/content/help/en/campaign-classic/technicalresources/api/c-Application.html)

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@adobe/acc-js-sdk",
-      "version": "1.1.6",
+      "version": "1.1.7",
       "license": "ISC",
       "dependencies": {
         "axios": "^0.25.0",
@@ -4809,9 +4809,10 @@
     },
     "node_modules/uuid": {
       "version": "8.3.2",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+      "resolved": "https://artifactory.corp.adobe.com/artifactory/api/npm/npm-adobe-release/uuid/-/uuid-8.3.2.tgz",
       "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
       "dev": true,
+      "license": "MIT",
       "bin": {
         "uuid": "dist/bin/uuid"
       }
@@ -8751,7 +8752,7 @@
     },
     "uuid": {
       "version": "8.3.2",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+      "resolved": "https://artifactory.corp.adobe.com/artifactory/api/npm/npm-adobe-release/uuid/-/uuid-8.3.2.tgz",
       "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
       "dev": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "ACC Javascript SDK",
   "main": "src/index.js",
   "homepage": "https://github.com/adobe/acc-js-sdk#readme",

package/src/cache.js

@@ -179,6 +179,16 @@ class Cache {
       this._cache = {};
       // timestamp at which the cache was last cleared
       this._lastCleared = this._loadLastCleared();
+      this._stats = {
+        reads: 0,
+        writes: 0,
+        removals: 0,
+        clears: 0,
+        memoryHits: 0,
+        storageHits: 0,
+        loads: 0,
+        saves: 0,
+      };
   }
 
   // Load timestamp at which the cache was last cleared
@@ -195,6 +205,7 @@ class Cache {
 
   // Load from local storage
   _load(key) {
+    this._stats.loads = this._stats.loads + 1;
     const json = this._storage.getItem(key);
     if (!json || !json.cachedAt || json.cachedAt <= this._lastCleared) {
       this._storage.removeItem(key);
@@ -205,6 +216,7 @@ class Cache {
 
   // Save to local storage
   _save(key, cached) {
+    this._stats.saves = this._stats.saves + 1;
     this._storage.setItem(key, cached);
   }
 
@@ -216,6 +228,7 @@ class Cache {
   _getIfActive(key) {
     // In memory cache?
     var cached = this._cache[key];
+    var memoryHit = !!cached;
     // Local storage ?
     if (!cached) {
       cached = this._load(key);
@@ -228,6 +241,8 @@ class Cache {
       this._remove(key);
       return undefined;
     }
+    this._stats.memoryHits = this._stats.memoryHits + 1;
+    if (!memoryHit) this._stats.storageHits = this._stats.storageHits + 1;
     return cached.value;
   }
 
@@ -237,6 +252,7 @@ class Cache {
    * @returns {*} the cached value, or undefined if not found
    */
   get() {
+      this._stats.reads = this._stats.reads + 1;
       const key = this._makeKeyFn.apply(this, arguments);
       const cached = this._getIfActive(key);
       return cached;
@@ -249,6 +265,7 @@ class Cache {
    * @returns {CachedObject} a cached object containing the cached value
    */
    put() {
+      this._stats.writes = this._stats.writes + 1;
       const value = arguments[arguments.length -1];
       const key = this._makeKeyFn.apply(this, arguments);
       const now = Date.now();
@@ -264,6 +281,7 @@ class Cache {
    * as cleared so that subsequent get operation will not actually return any data cached in persistent storage
    */
   clear() {
+      this._stats.clears = this._stats.clears + 1;
       this._cache = {};
       this._saveLastCleared();
   }
@@ -273,6 +291,7 @@ class Cache {
    * @param {string} key the key to remove
    */
   remove(key) {
+      this._stats.removals = this._stats.removals + 1;
       delete this._cache[key];
       this._remove(key);
   }

package/src/cacheRefresher.js

@@ -63,18 +63,21 @@ governing permissions and limitations under the License.
         }
     }
 
+    /**
+    * A class to refresh regulary a Cache every n seconds, by sending a query to get the last modified entities.
+    * The refresh mechanism can be activated by calling client.startRefreshCaches().
+    * This mechanism depends on the xtk:session:GetModifiedEntities API which is introduced in ACC 8.4 and above.
+    *
+    * @class
+    * @constructor
+    * @memberof Campaign
+    * @param {Cache} cache is the cache to refresh
+    * @param {Client} client is the ACC API Client.
+    * @param {string} cacheSchemaId is the id of the schema present in the cache to be refreshed every 10 seconds
+    * @param {string} rootKey is used as the root key of cache items in the refresher state cache
+    */
     class CacheRefresher {
 
-        /**
-        * A class to refresh regulary a Cache every n seconds, by sending a query to get the last modified entities.
-        * The refresh mechanism can be activated by calling client.startRefreshCaches().
-        * This mechanism depends on the xtk:session:GetModifiedEntities API which is introduced in ACC 8.4 and above.
-        *
-        * @param {Cache} cache is the cache to refresh
-        * @param {Client} client is the ACC API Client.
-        * @param {string} cacheSchemaId is the id of the schema present in the cache to be refreshed every 10 seconds
-        * @param {string} rootKey is used as the root key of cache items in the refresher state cache
-        */
         constructor(cache, client, cacheSchemaId, rootKey) {
             const connectionParameters = client._connectionParameters;
             this._cache = cache;
@@ -96,6 +99,10 @@ governing permissions and limitations under the License.
          * @param {integer} refreshFrequency frequency of the refresh in ms (default value is 10,000 ms)
          */
         startAutoRefresh(refreshFrequency) {
+            this._client._trackEvent('CACHE_REFRESHER//start', undefined, {
+                cacheSchemaId: this._cacheSchemaId,
+                refreshFrequency: refreshFrequency
+            });
             if (this._intervalId != null) {
                 clearInterval(this._intervalId);
             }
@@ -109,6 +116,9 @@ governing permissions and limitations under the License.
             if (this._running) {
                 // This call is already running and maybe taking a long time to complete. Do not make things
                 // harder and just skip this run
+                this._client._trackEvent('CACHE_REFRESHER//skip', undefined, {
+                    cacheSchemaId: this._cacheSchemaId,
+                });
                 return;
             }
             this._running = true;
@@ -117,9 +127,16 @@ governing permissions and limitations under the License.
             } catch(ex) {
                 if (ex.errorCode === "SDK-000010") {
                     // client is not logged, this is not an error.
+                    this._client._trackEvent('CACHE_REFRESHER//loggedOff', undefined, {
+                        cacheSchemaId: this._cacheSchemaId,
+                    });
                     return;
                 }
-                console.warn(`Failed to refresh cache for ${this._cacheSchemaId}`, ex);
+                this._client._trackEvent('CACHE_REFRESHER//error', undefined, {
+                    cacheSchemaId: this._cacheSchemaId,
+                    error: ex,
+                });
+            console.warn(`Failed to refresh cache for ${this._cacheSchemaId}`, ex);
             }
               finally {
                 this._running = false;
@@ -166,6 +183,12 @@ governing permissions and limitations under the License.
             if (!this._client.isLogged())
               throw CampaignException.NOT_LOGGED_IN(soapCall, `Cannot call GetModifiedEntities: session not connected`);
 
+            const event = this._client._trackEvent('CACHE_REFRESHER//tick', undefined, {
+                cacheSchemaId: this._cacheSchemaId,
+                lastTime: this._lastTime,
+                buildNumber: this._buildNumber
+            });
+
             // Do a soap call GetModifiedEntities instead of xtksession.GetModifiedEnties because we don't want to go through methodCache 
             // which might not contain the method GetModifiedEntities just after a build updgrade from a old version of acc 
             return this._client._makeSoapCall(soapCall)
@@ -175,13 +198,17 @@ governing permissions and limitations under the License.
                     doc = that._client._toRepresentation(doc, 'xml');
                     that._lastTime = DomUtil.getAttributeAsString(doc, "time"); // save time to be able to send it as an attribute in the next soap call
                     that._buildNumber = DomUtil.getAttributeAsString(doc, "buildNumber");
-                    that._refresh(doc);
+                    that._refresh(doc, event);
                     that._refresherStateCache.put("time", that._lastTime);
                     that._refresherStateCache.put("buildNumber", that._buildNumber);
                 })
                 .catch((ex) => {
                     // if the method GetModifiedEntities is not found in this acc version we disable the autoresfresh of the cache
                     if (soapCall.methodName == "GetModifiedEntities" && ex.errorCode == "SOP-330006") {
+                        this._client._trackEvent('CACHE_REFRESHER//abort', undefined, {
+                            cacheSchemaId: this._cacheSchemaId,
+                            error: ex,
+                        });
                         this.stopAutoRefresh();
                     } else {
                         throw ex;
@@ -190,8 +217,9 @@ governing permissions and limitations under the License.
         }
 
         // Refresh Cache : remove entities modified recently listed in xmlDoc
-        _refresh(xmlDoc) {
+        _refresh(xmlDoc, event) {
             const clearCache = XtkCaster.asBoolean(DomUtil.getAttributeAsString(xmlDoc, "emptyCache"));
+            const evicted = [];
             if (clearCache == true) {
                 this._cache.clear();
             } else {
@@ -200,6 +228,7 @@ governing permissions and limitations under the License.
                     const pkSchemaId = DomUtil.getAttributeAsString(child, "pk");
                     const schemaId = DomUtil.getAttributeAsString(child, "schema");
                     if (schemaId === this._cacheSchemaId) {
+                        evicted.push(schemaId);
                         this._cache.remove(pkSchemaId);
                         // Notify listeners to refresh in SchemaCache
                         if (schemaId === "xtk:schema") {
@@ -210,12 +239,23 @@ governing permissions and limitations under the License.
                     child = DomUtil.getNextSiblingElement(child);
                 }
             }
+
+            this._client._trackEvent('CACHE_REFRESHER//response', event, {
+                cacheSchemaId: this._cacheSchemaId,
+                clearCache: clearCache,
+                evicted: evicted
+            });
         }
 
         /**
          * Stop auto refreshing the cache
          */
         stopAutoRefresh() {
+            if (this._intervalId) {
+                this._client._trackEvent('CACHE_REFRESHER//stop', undefined, {
+                    cacheSchemaId: this._cacheSchemaId,
+                });
+            }
             clearInterval(this._intervalId);
             this._intervalId = null;
         }

package/src/campaign.js

@@ -10,10 +10,10 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 (function() {
-"use strict";    
+"use strict";
 
 const { Util } = require("./util.js");
-   
+
 /**
  * @namespace Campaign
  */
@@ -38,7 +38,8 @@ const { Util } = require("./util.js");
   static NOT_LOGGED_IN(call, details)                     { return new CampaignException(     call, 400, 16384, `SDK-000010 Cannot call API because client is not logged in`, details); }
   static DECRYPT_ERROR(details)                           { return new CampaignException(undefined, 400, 16384, `SDK-000011 "Cannot decrypt password: password marker is missing`, details); }
   static SESSION_EXPIRED()                                { return new CampaignException(undefined, 401, 16384, `SDK-000012 "Session has expired or is invalid. Please reconnect.`); }
-  
+  static FILE_UPLOAD_FAILED(name, details)                { return new CampaignException(undefined, 500, 16384, `SDK-000013 "Failed to upload file ${name}`, details); }
+
 
   /**
    * Returns a short description of the exception
@@ -49,18 +50,18 @@ const { Util } = require("./util.js");
   }
 
   /**
-   * Represents a Campaign exception, i.e. any kind of error that can happen when calling Campaign APIs, 
+   * Represents a Campaign exception, i.e. any kind of error that can happen when calling Campaign APIs,
    * ranging from HTTP errors, XML serialization errors, SOAP errors, authentication errors, etc.
-   * 
+   *
    * Members of this object are trimmed, and all session tokens, security tokens, passwords, etc. are replaced by "***"
-   * 
+   *
    * @param {SoapMethodCall|request} call the call that triggered the error. It can be a SoapMethodCall object, a HTTP request object, or even be undefined if the exception is generated outside of the context of a call
    * @param {number} statusCode the HTTP status code (200, 500, etc.)
    * @param {string} faultCode the fault code, i.e. an error code
    * @param {string} faultString a short description of the error
    * @param {string} detail a more detailed description of the error
    * @param {Error|string} cause an optional error object representing the cause of the exception
-   */  
+   */
   constructor(call, statusCode, faultCode, faultString, detail, cause) {
 
       // Provides a shorter and more friendly description of the call and method name
@@ -80,7 +81,7 @@ const { Util } = require("./util.js");
               };
               methodName = `${call.urn}#${call.methodName}`;  // Example: "xtk:session#Logon"
           }
-          else { 
+          else {
               // HTTP call
               // Extract the path of the request URL if there's one
               // If it's a relative URL, use the URL itself
@@ -140,48 +141,48 @@ const { Util } = require("./util.js");
           faultString = faultString.trim();
       }
 
-      /** 
+      /**
        * The type of exception, always "CampaignException"
        * @type {string}
        */
       this.name = "CampaignException";
-      /** 
+      /**
        * A human friendly message describing the error
        * @type {string}
        */
       this.message = message;
-      /** 
-       * The HTTP status code corresponding to the error 
+      /**
+       * The HTTP status code corresponding to the error
        * @type {number}
        */
       this.statusCode = statusCode;
-      /** 
-       * An object describing the call (SOAP or HTTP) which caused the exception. Can be null 
+      /**
+       * An object describing the call (SOAP or HTTP) which caused the exception. Can be null
        * @type {string}
        */
       this.methodCall = methodCall;
-      /** 
-       * A Campaign-specific error code, such as XSV-350013. May not be set if the exception did not come from a SOAP call 
+      /**
+       * A Campaign-specific error code, such as XSV-350013. May not be set if the exception did not come from a SOAP call
        * @type {string}
        */
       this.errorCode = errorCode;
-      /** 
-       * An error code 
+      /**
+       * An error code
        * @type {string}
        */
       this.faultCode = faultCode;
-      /** 
-       * A short description of the error 
+      /**
+       * A short description of the error
        * @type {string}
        */
       this.faultString = faultString;
-      /** 
-       * A detailed description of the error 
+      /**
+       * A detailed description of the error
        * @type {string}
        */
       this.detail = detail;
-      /** 
-       * The cause of the error, such as the root cause exception 
+      /**
+       * The cause of the error, such as the root cause exception
        */
       this.cause = cause;
 
@@ -199,7 +200,7 @@ const { Util } = require("./util.js");
 
 /**
  * Creates a CampaignException for a SOAP call and from a root exception
- * 
+ *
  * @private
  * @param {SoapMethodCall} call the SOAP call
  * @param {*} err the exception causing the SOAP call.
@@ -210,7 +211,7 @@ function makeCampaignException(call, err) {
   // It's already a CampaignException
   if (err instanceof CampaignException)
       return err;
-  
+
   // Wraps DOM exceptions which can occur when dealing with malformed XML
   const ctor = Object.getPrototypeOf(err).constructor;
   if (ctor && ctor.name == "DOMException") {
@@ -244,9 +245,9 @@ exports.CampaignException = CampaignException;
 exports.makeCampaignException = makeCampaignException;
 
 /**********************************************************************************
- * 
+ *
  * Business constants and helpers
- * 
+ *
  *********************************************************************************/
 
 // Ignore constant definitions from coverage