@adobe/acc-js-sdk 1.1.2 → 1.1.5

package/src/client.js

@@ -105,16 +105,49 @@ const xtkObjectHandler = {
  * @private
  * @memberof Campaign
  */
-const clientHandler = (representation) => {
+const clientHandler = (representation, headers, pushDownOptions) => {
     return {
         get: function(client, namespace) {
+
             // Force XML or JSON representation (NLWS.xml or NLWS.json)
-            if (namespace == "xml") return new Proxy(client, clientHandler("xml"));
-            if (namespace == "json") return new Proxy(client, clientHandler("SimpleJson"));
+            if (namespace == "xml") return new Proxy(client, clientHandler("xml", headers, pushDownOptions));
+            if (namespace == "json") return new Proxy(client, clientHandler("SimpleJson", headers, pushDownOptions));
+
+            // Override HTTP headers (NLWS.headers({...}))
+            // Unlike NLWS.xml or NLWS.json, NLWS.headers returns a function. This function takes key/value
+            // pairs of headers, and, when called, returns a proxy object which will remember the headers
+            // and be able to pass them to subsequent SOAP call context
+            if (namespace == "headers") return (methodHeaders) => {
+                // Build of copy of the http headers and append new headers in order to accomodate
+                // chained calls, such as NLWS.headers(...).headers(...)
+                const newHeaders = {};
+                if (headers) for (let h in headers) newHeaders[h] = headers[h];
+                if (methodHeaders) for (let h in methodHeaders) newHeaders[h] = methodHeaders[h];
+                return new Proxy(client, clientHandler(representation, newHeaders, pushDownOptions));
+            };
+
+            // Pushes down addition options to the SOAP and transport layers
+            if (namespace == "pushDown") return (methodPushDownOptions) => {
+                // Build of copy of the pushDownOptions in order to accomodate
+                // chained calls, such as NLWS.pushDown(...).pushDown(...)
+                const newPushDownOptions = {};
+                if (pushDownOptions) for (let h in pushDownOptions) newPushDownOptions[h] = pushDownOptions[h];
+                if (methodPushDownOptions) for (let h in methodPushDownOptions) newPushDownOptions[h] = methodPushDownOptions[h];
+                return new Proxy(client, clientHandler(representation, headers, newPushDownOptions));
+            };
 
             return new Proxy({ client:client, namespace:namespace}, {
                 get: function(callContext, methodName) {
                     callContext.representation = representation;
+                    callContext.headers = callContext.headers || client._connectionParameters._options.extraHttpHeaders;
+                    callContext.pushDownOptions = {};
+                    if (headers) {
+                        for (let h in headers) callContext.headers[h] = headers[h];
+                    }
+                    if (pushDownOptions) {
+                        for (let h in pushDownOptions) callContext.pushDownOptions[h] = pushDownOptions[h];
+                    }
+
                     if (methodName == ".") return callContext;
 
                     // get Schema id from namespace (find first upper case letter)
@@ -248,6 +281,11 @@ class Credentials {
     * @property {Storage} storage - Overrides the storage interface (i.e. LocalStorage)
     * @property {function} refreshClient - An async callback function with the SDK client as parameter, which will be called when the ACC session is expired
     * @property {string} charset - The charset encoding used for http requests. Defaults to UTF-8 since SDK version 1.1.1
+    * @property {{ name:string, value:string}} extraHttpHeaders - optional key/value pair of HTTP header (will override any other headers)
+    * @property {string} clientApp - optional name/version of the application client of the SDK. This will be passed in HTTP headers for troubleshooting
+    * @property {boolean} noSDKHeaders - set to disable "ACC-SDK" HTTP headers
+    * @property {boolean} noMethodInURL - Can be set to true to remove the method name from the URL
+    * @property {number} timeout - Can be set to change the HTTP call timeout. Value is passed in ms.
     * @memberOf Campaign
  */
  
@@ -269,7 +307,7 @@ class ConnectionParameters {
     constructor(endpoint, credentials, options) {
         // this._options will be populated with the data from "options" and with
         // default values. But the "options" parameter will not be modified
-        this._options = {};
+        this._options = Object.assign({}, options);
 
         // Default value
         if (options === undefined || options === null)
@@ -312,6 +350,13 @@ class ConnectionParameters {
         this._options._storage = storage;
         this._options.refreshClient = options.refreshClient;
         this._options.charset = options.charset === undefined ? "UTF-8": options.charset;
+        this._options.extraHttpHeaders = {};
+        if (options.extraHttpHeaders) {
+            for (let h in options.extraHttpHeaders) this._options.extraHttpHeaders[h] = options.extraHttpHeaders[h];
+        }
+        this._options.clientApp = options.clientApp;
+        this._options.noSDKHeaders = !!options.noSDKHeaders;
+        this._options.noMethodInURL = !!options.noMethodInURL;
     }
 
     /**
@@ -684,13 +729,16 @@ class Client {
      * @private
      * @param {string} urn is the API name space, usually the schema. For instance xtk:session
      * @param {string} method is the method to call, for instance Logon
+     * @param {boolean} internal is a boolean indicating whether the SOAP call is performed by the SDK (internal = true) or on behalf of a user
      * @return {SOAP.SoapMethodCall} a SoapMethodCall which have been initialized with security tokens... and to which the method
      * parameters should be set
      */
-    _prepareSoapCall(urn, method, internal) {
+    _prepareSoapCall(urn, method, internal, extraHttpHeaders, pushDownOptions) {
         const soapCall = new SoapMethodCall(this._transport, urn, method, 
                                             this._sessionToken, this._securityToken, 
-                                            this._getUserAgentString(), this._connectionParameters._options.charset);
+                                            this._getUserAgentString(),
+                                            Object.assign({}, this._connectionParameters._options, pushDownOptions),
+                                            extraHttpHeaders);
         soapCall.internal = !!internal;
         return soapCall;
     }
@@ -704,6 +752,7 @@ class Client {
      */
     async _retrySoapCall(soapCall) {
         soapCall.retry = false;
+        soapCall._retryCount = soapCall._retryCount + 1;
         var newClient = await this._refreshClient(this); 
         soapCall.finalize(newClient._soapEndPoint(), newClient);
         if (this._traceAPICalls) {
@@ -778,6 +827,18 @@ class Client {
         this._securityToken = "";
         const credentials = this._connectionParameters._credentials;
 
+        const sdkVersion = this.sdk.getSDKVersion();
+        const version = `${sdkVersion.name} ${sdkVersion.version}`;
+        const clientApp = this._connectionParameters._options.clientApp;
+        if (!this._connectionParameters._options.noSDKHeaders) {
+            this._connectionParameters._options.extraHttpHeaders["ACC-SDK-Version"] = version;
+            this._connectionParameters._options.extraHttpHeaders["ACC-SDK-Auth"] = `${credentials._type}`;
+            if (clientApp)
+                this._connectionParameters._options.extraHttpHeaders["ACC-SDK-Client-App"] = clientApp;
+        }
+        // See NEO-35259
+        this._connectionParameters._options.extraHttpHeaders['X-Query-Source'] = `${version}${clientApp? "," + clientApp : ""}`;
+
         // Clear session token cookie to ensure we're not inheriting an expired cookie. See NEO-26589
         if (credentials._type != "SecurityToken" && typeof document != "undefined") {
             document.cookie = '__sessiontoken=;path=/;';
@@ -790,8 +851,8 @@ class Client {
             that.application = new Application(that);
             return Promise.resolve();
         }
-        else if (credentials._type == "SecurityToken") { 
-           that._sessionInfo = undefined;
+        else if (credentials._type == "SecurityToken") {
+            that._sessionInfo = undefined;
             that._installedPackages = {};
             that._sessionToken = "";
             that._securityToken = credentials._securityToken;
@@ -799,12 +860,14 @@ class Client {
             return Promise.resolve();
         }
         else if (credentials._type == "UserPassword" || credentials._type == "BearerToken") {
-            const soapCall = that._prepareSoapCall("xtk:session", credentials._type === "UserPassword" ? "Logon" : "BearerTokenLogon");
+            const soapCall = that._prepareSoapCall("xtk:session", credentials._type === "UserPassword" ? "Logon" : "BearerTokenLogon", false, this._connectionParameters._options.extraHttpHeaders);
             // No retry for logon SOAP methods
             soapCall.retry = false;
             if (credentials._type == "UserPassword") {
                 const user = credentials._getUser();
                 const password = credentials._getPassword();
+                if (!this._connectionParameters._options.noSDKHeaders)
+                    this._connectionParameters._options.extraHttpHeaders["ACC-SDK-Auth"] = `${credentials._type} ${user}`;
                 soapCall.writeString("login", user);
                 soapCall.writeString("password", password);
                 var parameters = null;
@@ -872,7 +935,7 @@ class Client {
         if (!that.isLogged()) return;
         const credentials = this._connectionParameters._credentials;
         if (credentials._type != "SessionToken" && credentials._type != "AnonymousUser") {
-            var soapCall = that._prepareSoapCall("xtk:session", "Logoff");
+            var soapCall = that._prepareSoapCall("xtk:session", "Logoff", false, this._connectionParameters._options.extraHttpHeaders);
                 return this._makeSoapCall(soapCall).then(function() {
                 that._sessionToken = "";
                 that._securityToken = "";
@@ -977,7 +1040,7 @@ class Client {
      * @returns {boolean} a boolean indicating if the package is installed or not
      */
     hasPackage(packageId, optionalName) {
-    if (optionalName === undefined)
+    if (optionalName !== undefined)
         packageId = `${packageId}:${optionalName}`;
     if (!this.isLogged())
         throw CampaignException.NOT_LOGGED_IN(undefined, `Cannot call hasPackage: session not connected`);
@@ -991,7 +1054,7 @@ class Client {
      * @private
      * @deprecated since version 1.0.0
      */
-    async _getSecretKeyCipher() {
+     async _getSecretKeyCipher() {
         var that = this;
         if (this._secretKeyCipher) return this._secretKeyCipher;
         return that.getOption("XtkSecretKey").then(function(secretKey) {
@@ -1014,7 +1077,7 @@ class Client {
      */
      async getEntityIfMoreRecent(entityType, fullName, representation, internal) {
         const that = this;
-        const soapCall = this._prepareSoapCall("xtk:persist", "GetEntityIfMoreRecent", internal);
+        const soapCall = this._prepareSoapCall("xtk:persist", "GetEntityIfMoreRecent", internal, this._connectionParameters._options.extraHttpHeaders);
         soapCall.writeString("pk", entityType + "|" + fullName);
         soapCall.writeString("md5", "");
         soapCall.writeBoolean("mustExist", false);
@@ -1117,7 +1180,7 @@ class Client {
         // console.log(method.toXMLString());
 
         var urn = that._methodCache.getSoapUrn(schemaId, methodName);
-        var soapCall = that._prepareSoapCall(urn, methodName);
+        var soapCall = that._prepareSoapCall(urn, methodName, false, callContext.headers, callContext.pushDownOptions);
 
         // If method is called with one parameter which is a function, then we assume it's a hook: the function will return
         // the actual list of parameters
@@ -1158,6 +1221,8 @@ class Client {
                         soapCall.writeByte(paramName, XtkCaster.asByte(paramValue));
                     else if (type == "short")
                         soapCall.writeShort(paramName, XtkCaster.asShort(paramValue));
+                    else if (type == "int")
+                        soapCall.writeLong(paramName, XtkCaster.asLong(paramValue));
                     else if (type == "long")
                         soapCall.writeLong(paramName, XtkCaster.asLong(paramValue));
                     else if (type == "int64")
@@ -1182,11 +1247,12 @@ class Client {
                             const index = xtkschema.indexOf(":");
                             docName = xtkschema.substr(index+1);
                         }
+                        if (!docName) docName = paramName; // Use te parameter name as the XML root element
                         var xmlValue = that._fromRepresentation(docName, paramValue, callContext.representation);
                         if (type == "DOMDocument")
                             soapCall.writeDocument(paramName, xmlValue);
                         else
-                            soapCall.writeElement(paramName, xmlValue.documentElement);
+                            soapCall.writeElement(paramName, xmlValue);
                     }
                     else
                         throw CampaignException.BAD_SOAP_PARAMETER(soapCall, paramName, paramValue, `Unsupported parameter type '${type}' for parameter '${paramName}' of method '${methodName}' of schema '${schemaId}`);
@@ -1321,8 +1387,11 @@ class Client {
      */
     async test() {
         const request = {
-            url: `${this._connectionParameters._endpoint}/r/test`
+            url: `${this._connectionParameters._endpoint}/r/test`,
+            headers: {}
         };
+        for (let h in this._connectionParameters._options.extraHttpHeaders)
+            request.headers[h] = this._connectionParameters._options.extraHttpHeaders[h];
         const body = await this._makeHttpCall(request);
         const xml = DomUtil.parse(body);
         const result = this._toRepresentation(xml);
@@ -1342,6 +1411,8 @@ class Client {
                 'Cookie': '__sessiontoken=' + this._sessionToken
             }
         };
+        for (let h in this._connectionParameters._options.extraHttpHeaders)
+            request.headers[h] = this._connectionParameters._options.extraHttpHeaders[h];
         const body = await this._makeHttpCall(request);
         const lines = body.split('\n');
         const doc = DomUtil.newDocument("ping");
@@ -1371,6 +1442,8 @@ class Client {
                 'Cookie': '__sessiontoken=' + this._sessionToken
             }
         };
+        for (let h in this._connectionParameters._options.extraHttpHeaders)
+            request.headers[h] = this._connectionParameters._options.extraHttpHeaders[h];
         const body = await this._makeHttpCall(request);
         const lines = body.split('\n');
         const doc = DomUtil.newDocument("ping");

package/src/index.js

@@ -23,7 +23,8 @@ const DomUtil = require('./domUtil.js').DomUtil;
 const XtkCaster = require('./xtkCaster.js').XtkCaster;
 const { Client, Credentials, ConnectionParameters } = require('./client.js');
 const request = require('./transport.js').request;
-const { TestUtil } = require('./testUtil');
+const { TestUtil } = require('./testUtil.js');
+const { HttpError } = require('./transport.js');
 
 /**
  * Get/Set the transport function (defaults to Axios). This function is used for testing / mocking the transport layer.
@@ -210,6 +211,7 @@ sdk.XtkCaster = XtkCaster;
 sdk.Credentials = Credentials;
 sdk.DomUtil = DomUtil;
 sdk.ConnectionParameters = ConnectionParameters;
+sdk.HttpError = HttpError;
 
 // Public exports
 module.exports = sdk;

package/src/soap.js

@@ -78,13 +78,15 @@ const NS_XSD = "http://www.w3.org/2001/XMLSchema";
  * @param {string} sessionToken Campaign session token
  * @param {string} securityToken  Campaign security token
  * @param {string} userAgentString The user agent string to use for HTTP requests
- * @param {string} charset The charset encoding used for http requests, usually UTF-8
+ * @param {string} pushDownOptions Options to push down to the request (comes from connectionParameters._options)
+ * @param {{ name:string, value:string}} extraHttpHeaders key/value pair of HTTP header (will override any other headers)
  * @memberof SOAP
  */
 class SoapMethodCall {
     
-    constructor(transport, urn, methodName, sessionToken, securityToken, userAgentString, charset) {
+    constructor(transport, urn, methodName, sessionToken, securityToken, userAgentString, pushDownOptions, extraHttpHeaders) {
         this.request = undefined;       // The HTTP request (object litteral passed to the transport layer)
+        this.requestOptions = undefined;
         this.response = undefined;      // The HTTP response object (in case of success)
 
         // Current URN and method (for error reporting)
@@ -96,11 +98,14 @@ class SoapMethodCall {
         this.internal = false;
         // Enable soap retry
         this.retry = true;
+        this._retryCount = 0;
 
         this._sessionToken = sessionToken || "";
         this._securityToken = securityToken || "";
         this._userAgentString = userAgentString;
-        this._charset = charset || "";
+        this._pushDownOptions = pushDownOptions || {};
+        this._charset = this._pushDownOptions.charset || '';
+        this._extraHttpHeaders = extraHttpHeaders || {};
 
         // THe SOAP call being built
         this._doc = undefined;           // XML document for SOAP call
@@ -213,7 +218,7 @@ class SoapMethodCall {
      * @param {string} tag the parameter name
      * @param {*} value the parameter value, which will be casted to a int32 according to xtk rules
      */
-    writeLong(tag, value) {
+     writeLong(tag, value) {
         value = XtkCaster.asLong(value);
         this._addNode(tag, "xsd:int", XtkCaster.asString(value), SOAP_ENCODING_NATIVE);
     }
@@ -286,6 +291,7 @@ class SoapMethodCall {
     writeElement(tag, element) {
         const node = this._addNode(tag, "ns:Element", null, SOAP_ENCODING_XML);
         if (element !== null && element !== undefined) {
+            if (element.nodeType === 9) element = element.documentElement;
             const child = this._doc.importNode(element, true);
             node.appendChild(child);
         }
@@ -299,7 +305,8 @@ class SoapMethodCall {
     writeDocument(tag, document) {
         const node = this._addNode(tag, "", null, SOAP_ENCODING_XML);
         if (document !== null && document !== undefined) {
-            const child = this._doc.importNode(document.documentElement, true);
+            const element = document.nodeType === 1 ? document : document.documentElement;
+            const child = this._doc.importNode(element, true);
             node.appendChild(child);
         }
     }
@@ -513,23 +520,40 @@ class SoapMethodCall {
      * @param {string} url is the Campaign SOAP endpoint (soaprouter.jsp)
      * @returns {Object} an options object describing the HTTP request, with cookies, headers and body
      */
-    _createHTTPRequest(url) {
+    _createHTTPRequest(url, requestOptions) {
+
+        const headers = {
+            'Content-type': `application/soap+xml${this._charset ? ";charset=" + this._charset : ""}`,
+            'SoapAction': `${this.urn}#${this.methodName}`,
+            'X-Security-Token': this._securityToken
+        };
+
+        // Add HTTP headers specific to the SOAP call for better tracing/troubleshooting
+        if (this._extraHttpHeaders && this._extraHttpHeaders['ACC-SDK-Version']) {
+            // "this.retry" means that the call can be retried, not that it is being retried. The HTTP header howerver, indicates that this
+            // is actually a retry of a previously failed call (expired token)
+            if (this._retryCount > 0) headers["ACC-SDK-Call-RetryCount"] = `${this._retryCount}`;
+            if (this.internal) headers["ACC-SDK-Call-Internal"] = "1";
+        }
 
-        const options = {
+        const request = {
             url: url,
             method: 'POST',
-            headers: {
-                'Content-type': `application/soap+xml${this._charset ? ";charset=" + this._charset : ""}`,
-                'SoapAction': `${this.urn}#${this.methodName}`,
-                'X-Security-Token': this._securityToken
-            },
+            headers: headers,
             data: DomUtil.toXMLString(this._doc)
         };
         if (this._sessionToken)
-            options.headers.Cookie = '__sessiontoken=' + this._sessionToken;
+            request.headers.Cookie = '__sessiontoken=' + this._sessionToken;
         if (this._userAgentString)
-            options.headers['User-Agent'] = this._userAgentString;
-        return options;
+            request.headers['User-Agent'] = this._userAgentString;
+
+        // Override http headers with custom headers
+        for (let h in this._extraHttpHeaders) {
+            request.headers[h] = this._extraHttpHeaders[h];
+        }
+
+        const extraOptions = Object.assign({}, this._pushDownOptions, requestOptions);
+        return [ request, extraOptions ];
     }
     
     /**
@@ -575,9 +599,11 @@ class SoapMethodCall {
             sessionTokenElem.textContent = this._sessionToken;
             this._method.prepend(sessionTokenElem);
         }
-        const options = this._createHTTPRequest(url);
+        const noMethodInURL = !!this._pushDownOptions.noMethodInURL;
+        const actualUrl = noMethodInURL ? url : `${url}?${this.urn}:${this.methodName}`;
+
         // Prepare request and empty response objects
-        this.request = options;
+        [this.request, this.requestOptions] = this._createHTTPRequest(actualUrl);
         this.response = undefined;
     }
 
@@ -590,7 +616,7 @@ class SoapMethodCall {
      */
     async execute() {
         const that = this;
-        const promise = this._transport(this.request);
+        const promise = this._transport(this.request, this.requestOptions);
         return promise.then(function(body) {
             if (body.indexOf(`XSV-350008`) != -1)
                 throw CampaignException.SESSION_EXPIRED();

package/src/testUtil.js

@@ -1,4 +1,4 @@
-const { DomUtil } = require("./domUtil");
+const { DomUtil } = require("./domUtil.js");
 
 /*
 Copyright 2022 Adobe. All rights reserved.
@@ -14,7 +14,7 @@ governing permissions and limitations under the License.
 (function() {
 "use strict";    
   
-const { newSchema } = require("./application");
+const { newSchema } = require("./application.js");
 
 /**********************************************************************************
  * 

package/src/transport.js

@@ -14,13 +14,27 @@ governing permissions and limitations under the License.
 
 const { Util } = require('./util.js');
 
+/**
+ * @memberof Utils
+ * @class
+ * @constructor
+ */
 class HttpError {
+  /* Encapsulates an error from an HTTP call
+    * @param {string|number} statusCode - The Http status code
+    * @param {string?} statusText - The Http status text corresponding to the error code
+    * @param {any?} data - The payload of the HTTP response, which usually contains details about the error
+  */
   constructor(statusCode, statusText, data) {
       this.statusCode = statusCode;
       this.statusText = statusText || "";
       this.data = data;
   }
 
+  /**
+   * Returns a short description of the error
+   * @returns {string} a short descrption of the error
+   */
   toString() {
     return `${this.statusCode}${this.statusText ? " " + this.statusText : ""}`;
   }
@@ -52,13 +66,14 @@ if (!Util.isBrowser()) {
    * - request
    */
 
-  const request = (options) => {
+   const request = (options, requestOptions) => {
+    requestOptions = requestOptions || {};
     const request = {
       method: options.method || "GET",
       url: options.url,
       headers: options.headers,
       data: options.data,
-      timeout: 5000,
+      timeout: requestOptions.timeout || 5000,
     };
     return axios(request)
     .then((response) => {

package/test/application.test.js

@@ -2108,6 +2108,7 @@ describe('Application', () => {
             const application = client.application;
             expect(application).not.toBeNull();
             expect(application.buildNumber).toBeUndefined();
+            expect(application.version).toBeUndefined();
             expect(application.instanceName).toBeUndefined();
             expect(application.operator).toBeUndefined();
             expect(application.package).toBeUndefined();
@@ -2145,4 +2146,14 @@ describe('Application', () => {
             expect(schema2).toBeNull();
         });
     });
+
+    describe("Version", () => {
+        it("Should get proper version information", async () => {
+            const client = await Mock.makeClient();
+            client._transport.mockReturnValueOnce(Mock.LOGON_RESPONSE);
+            await client.NLWS.xtkSession.logon();
+            expect(client.application.buildNumber).toBe('9219');
+            expect(client.application.version).toBe('6.7.0');
+        })
+    })
 });

package/test/client.hasPackage.test.js

@@ -56,12 +56,12 @@ describe('ACC Client (has package)', () => {
     client._transport.mockReturnValueOnce(LOGON_RESPONSE);
     await client.NLWS.xtkSession.logon();
 
-    expect(client.hasPackage("nms:campaign"));
-    expect(client.hasPackage("nms", "campaign"));
-    expect(!client.hasPackage("nms:mrm"));
-    expect(!client.hasPackage("nms", "mrm"));
-    expect(client.hasPackage("nms:core"));
-    expect(client.hasPackage("nms", "core"));
+    expect(client.hasPackage("nms:campaign")).toBeTruthy();
+    expect(client.hasPackage("nms", "campaign")).toBeTruthy();
+    expect(client.hasPackage("nms:mrm")).toBeFalsy();
+    expect(client.hasPackage("nms", "mrm")).toBeFalsy();
+    expect(client.hasPackage("nms:core")).toBeTruthy();
+    expect(client.hasPackage("nms", "core")).toBeTruthy();
   });
 
   it('should fail when unlogged', async () => {